feat: prefer canonical awaiting-input contract

.changeset/canonical-awaiting-input.md

@@ -0,0 +1,5 @@
+---
+"@onkernel/managed-auth-react": minor
+---
+
+Prefer canonical managed-auth fields and choices when present, submit their stable IDs through `field_values` and `selected_choice_id`, and retain legacy rendering and submission fallbacks during the deprecation window.

.github/workflows/test.yaml

@@ -41,6 +41,9 @@ jobs:
       - name: Typecheck
         run: bun run typecheck
 
+      - name: Test
+        run: bun run test
+
       # Dry-run npm pack so we catch missing files / bad exports BEFORE a
       # tagged release tries to publish. Exits non-zero if e.g. dist/ is
       # missing from `files` or an export points at a non-existent path.

package.json

@@ -9,6 +9,7 @@
     "build": "bun run --filter '*' build",
     "dev": "bun run --filter '*' dev",
     "typecheck": "bun run --filter '*' typecheck",
+    "test": "bun test",
     "lint": "bun run --filter '*' lint",
     "format": "prettier --write \"**/*.{ts,tsx,js,json,md,css}\"",
     "format:check": "prettier --check \"**/*.{ts,tsx,js,json,md,css}\"",
@@ -18,6 +19,7 @@
   "devDependencies": {
     "@changesets/changelog-github": "0.7.0",
     "@changesets/cli": "^2.27.0",
+    "@types/bun": "1.2.21",
     "@types/node": "^20",
     "prettier": "^3.3.0",
     "typescript": "^5.6.0"

packages/managed-auth-react/src/components/ExternalActionWaiting.tsx

@@ -36,7 +36,7 @@ function getMFAIcon(type: MFAType) {
 interface ExternalActionWaitingProps {
   message?: string | null;
   mfaOptions?: MFAOption[];
-  onMFASelect?: (mfaType: MFAType) => void;
+  onMFASelect?: (mfaType: MFAType, choiceId?: string) => void;
   isLoading?: boolean;
 }
 
@@ -91,11 +91,11 @@ export function ExternalActionWaiting({
         <div className="kma-external-action__alternatives">
           {mfaOptions.map((option, idx) => (
             <Button
-              key={idx}
+              key={option.id ?? `${option.type}:${idx}`}
               variant="secondary"
               slotKey="mfaOption"
               className="kma-option"
-              onClick={() => onMFASelect(option.type)}
+              onClick={() => onMFASelect(option.type, option.id)}
               disabled={isLoading}
             >
               <span

packages/managed-auth-react/src/components/UnifiedAuthForm.tsx

@@ -38,7 +38,7 @@ interface UnifiedAuthFormProps {
   signInOptions?: SignInOption[];
   onSubmitFields: (credentials: Record<string, string>) => void;
   onSSOClick: (ssoButton: SSOButton) => void;
-  onMFASelect: (mfaType: MFAType) => void;
+  onMFASelect: (mfaType: MFAType, choiceId?: string) => void;
   onSignInOptionSelect: (optionId: string) => void;
   isLoading?: boolean;
   errorMessage?: string | null;
@@ -196,11 +196,11 @@ export function UnifiedAuthForm({
     <div className="kma-options">
       {sortedMFAOptions.map((option, idx) => (
         <Button
-          key={idx}
+          key={option.id ?? `${option.type}:${idx}`}
           variant="secondary"
           slotKey="mfaOption"
           className="kma-option"
-          onClick={() => onMFASelect(option.type)}
+          onClick={() => onMFASelect(option.type, option.id)}
           disabled={isLoading}
         >
           <span

packages/managed-auth-react/src/index.ts

@@ -43,6 +43,9 @@ export type {
   SignInOption,
   FlowStatus,
   FlowStep,
+  ManagedAuthChoice,
+  ManagedAuthChoiceType,
+  ManagedAuthField,
   ManagedAuthResponse,
   UIState,
 } from "./lib/types";

packages/managed-auth-react/src/lib/api.ts

@@ -91,17 +91,20 @@ export async function retrieveManagedAuth(
   return (await res.json()) as ManagedAuthResponse;
 }
 
-interface SubmitBody {
-  fields: Record<string, string>;
+export interface ManagedAuthSubmitBody {
+  field_values?: Record<string, string>;
+  selected_choice_id?: string;
+  fields?: Record<string, string>;
   sso_button_selector?: string;
+  sso_provider?: string;
   mfa_option_id?: MFAType;
   sign_in_option_id?: string;
 }
 
-async function submit(
+export async function submitManagedAuth(
   id: string,
   jwt: string,
-  body: SubmitBody,
+  body: ManagedAuthSubmitBody,
   options?: ApiClientOptions,
 ): Promise<void> {
   const f = getFetch(options);
@@ -119,52 +122,6 @@ async function submit(
   }
 }
 
-export function submitFieldValues(
-  id: string,
-  jwt: string,
-  fields: Record<string, string>,
-  options?: ApiClientOptions,
-): Promise<void> {
-  return submit(id, jwt, { fields }, options);
-}
-
-export function submitSSOButton(
-  id: string,
-  jwt: string,
-  selector: string,
-  options?: ApiClientOptions,
-): Promise<void> {
-  return submit(
-    id,
-    jwt,
-    { fields: {}, sso_button_selector: selector },
-    options,
-  );
-}
-
-export function submitMFASelection(
-  id: string,
-  jwt: string,
-  mfaType: MFAType,
-  options?: ApiClientOptions,
-): Promise<void> {
-  return submit(id, jwt, { fields: {}, mfa_option_id: mfaType }, options);
-}
-
-export function submitSignInOption(
-  id: string,
-  jwt: string,
-  signInOptionId: string,
-  options?: ApiClientOptions,
-): Promise<void> {
-  return submit(
-    id,
-    jwt,
-    { fields: {}, sign_in_option_id: signInOptionId },
-    options,
-  );
-}
-
 /** Callbacks for the SSE event stream. */
 export interface ManagedAuthStreamHandlers {
   onState: (data: ManagedAuthStateEventData) => void;

packages/managed-auth-react/src/lib/types.ts

@@ -28,6 +28,8 @@ export type MFAType =
   | "other";
 
 export interface DiscoveredField {
+  id?: string;
+  ref?: string;
   name: string;
   label: string;
   type: "text" | "email" | "password" | "tel" | "code" | "totp";
@@ -38,12 +40,14 @@ export interface DiscoveredField {
 }
 
 export interface SSOButton {
+  id?: string;
   provider: string;
   selector: string;
   label?: string;
 }
 
 export interface MFAOption {
+  id?: string;
   type: MFAType;
   label?: string;
   target?: string;
@@ -56,12 +60,46 @@ export interface SignInOption {
   description?: string | null;
 }
 
+export interface ManagedAuthField {
+  id: string;
+  ref: string;
+  type:
+    | "identifier"
+    | "password"
+    | "code"
+    | "totp_code"
+    | "totp_secret"
+    | "text";
+  label?: string;
+  required?: boolean;
+  observed_selector?: string | null;
+}
+
+export type ManagedAuthChoiceType =
+  | "mfa_method"
+  | "sso_provider"
+  | "sign_in_method"
+  | "auth_method"
+  | "identifier_method"
+  | "account"
+  | "other";
+
+export interface ManagedAuthChoice {
+  id: string;
+  type: ManagedAuthChoiceType;
+  label: string;
+  description?: string | null;
+  observed_selector?: string | null;
+}
+
 export interface ManagedAuthStateEventData {
   event: "managed_auth_state";
   timestamp: string;
   flow_status: FlowStatus;
   flow_step: FlowStep;
   flow_type?: "LOGIN" | "REAUTH";
+  fields?: ManagedAuthField[];
+  choices?: ManagedAuthChoice[];
   discovered_fields?: DiscoveredField[];
   mfa_options?: MFAOption[];
   sign_in_options?: SignInOption[];
@@ -82,6 +120,8 @@ export interface ManagedAuthResponse {
   flow_status: FlowStatus;
   flow_step: FlowStep;
   flow_type?: "LOGIN" | "REAUTH" | null;
+  fields?: ManagedAuthField[] | null;
+  choices?: ManagedAuthChoice[] | null;
   discovered_fields?: DiscoveredField[] | null;
   pending_sso_buttons?: SSOButton[] | null;
   mfa_options?: MFAOption[] | null;