@movmo_app/react-common 0.14.1 → 0.16.0

package/dist/index.d.ts

@@ -28,7 +28,11 @@ export declare class AuthError extends Error {
     code: AuthErrorCode | 'network' | 'unknown';
     retryAfter?: number | undefined;
     attemptsRemaining?: number | undefined;
-    constructor(status: number, code: AuthErrorCode | 'network' | 'unknown', retryAfter?: number | undefined, attemptsRemaining?: number | undefined);
+    /** RFC3339 end of the account-recovery cool-down (`recovery_cooldown` bodies). */
+    until?: string | undefined;
+    constructor(status: number, code: AuthErrorCode | 'network' | 'unknown', retryAfter?: number | undefined, attemptsRemaining?: number | undefined, 
+    /** RFC3339 end of the account-recovery cool-down (`recovery_cooldown` bodies). */
+    until?: string | undefined);
 }
 
 /** Autofill options live 5 min on the server; refresh at 4½. */
@@ -341,8 +345,25 @@ export declare interface ModalProps {
 
 /** Typed client for every Movmo sign-in and passkey-management call. */
 export declare interface MovmoAuthApi {
-    login(email: string): Promise<MovmoLoginResponse>;
+    /**
+     * `POST /v1/auth/login`. `deferCode` sends `defer_code: true`: an unenrolled
+     * email's flow is created without sending a code (`sendCode` releases the
+     * first send); used by the partner iframe.
+     */
+    login(email: string, opts?: {
+        deferCode?: boolean;
+    }): Promise<MovmoLoginResponse>;
     sendCode(flowId: string): Promise<MovmoCodeFlow>;
+    /**
+     * `POST /v1/auth/recovery {flow_id, time_zone?}`: starts account recovery for
+     * an enrolled email's unsent flow; the answer is a code flow (MOVMO-687).
+     */
+    startRecovery(flowId: string): Promise<MovmoCodeFlow>;
+    /**
+     * `POST /v1/auth/recovery/cancel {token}`. A token that isn't `rc1.` +
+     * base64url rejects with `invalid_request` before any request.
+     */
+    cancelRecovery(token: string): Promise<void>;
     passkeyOptions(): Promise<PasskeyOptionsResponse>;
     verifyCode(flowId: string, code: string): Promise<MovmoVerifyResponse>;
     verifyPasskey(flowId: string, credential: CredentialJSON): Promise<MovmoVerifyResponse>;
@@ -373,11 +394,29 @@ export declare interface MovmoSignIn {
     canUsePasskeyButton: boolean;
     /** Passkey step: the last ceremony failed; offer Try again (`retryPasskey`). */
     passkeyFailed: boolean;
+    /** False on re-auth (`lockedEmail`/`expectedUserId`): the passkey step offers no recovery entry. */
+    recoveryAvailable: boolean;
+    /** Recovery step: the server refused recovery (`recovery_blocked`); terminal, only Close remains. */
+    recoveryBlocked: boolean;
+    /**
+     * Framed passkeys: the browser won't run the passkey ceremony in this frame
+     * (`topOrigin_required`, or remembered). The passkey step offers `continueTopLevel`.
+     */
+    topLevelRequired: boolean;
+    /** Framed window with `framedPasskeys`: the passkey step always offers "Continue in a new window". */
+    framedPasskeys: boolean;
     liveMessage: string;
     submitEmail(): void;
     signInWithPasskey(): void;
     retryPasskey(): void;
-    useCodeInstead(): void;
+    /** Passkey step, `topLevelRequired`: calls `onContinueTopLevel` synchronously (inside the click). */
+    continueTopLevel(): void;
+    /** Passkey step: "I can't use my passkey" → the recovery step (aborts the ceremony). No-op on re-auth. */
+    cantUsePasskey(): void;
+    /** Recovery step: `POST /v1/auth/recovery`, then the code step. */
+    sendRecoveryCode(): void;
+    /** Recovery step: back to the passkey step (email step when passkeys can't be used here). */
+    back(): void;
     /** Passkey/code step: back to email with the email kept. */
     changeEmail(): void;
     submitCode(code: string): void;
@@ -571,6 +610,13 @@ export declare interface PasskeyListProps {
      * sign-in.
      */
     onAccountMismatch: () => void;
+    /**
+     * RFC3339 end of the account-recovery cool-down (the host's
+     * `security-preferences.recovery_until`). While it is in the future the card
+     * shows the in-progress status line and disables Add and Remove up front,
+     * without waiting for a `403 recovery_cooldown`.
+     */
+    recoveryUntil?: string | null;
 }
 
 export declare const PhoneInput: default_2.FC<PhoneInputProps>;
@@ -645,8 +691,8 @@ export declare function readPromptState(cookie?: string, now?: number): PromptSt
  *
  * The sign-in flow runs email-first only, with the account's email locked,
  * and continues at once (`autoContinue`): the login's `allowCredentials` limit
- * a passkey choice to this account, and **Use a code instead** stays
- * available. No autofill, no discoverable "Sign in with passkey", no
+ * a passkey choice to this account. The passkey step offers no recovery
+ * entry ("I can't use my passkey"): recovery starts from the sign-in page. No autofill, no discoverable "Sign in with passkey", no
  * enrollment prompt. The flow is single-use and is mounted only while open,
  * so every open starts fresh. In a framed window it only says "Manage
  * passkeys on the Movmo Security page." and makes no sign-in or WebAuthn call.
@@ -758,8 +804,15 @@ export declare const signInCopy: {
     readonly passkeyExists: "This passkey is already on your account.";
     readonly enrollExpired: "That took too long. Try again.";
     readonly invalidEmail: "Enter a valid email address.";
-    readonly passkeyUnavailable: "This browser couldn't use a passkey. Use a code instead.";
+    readonly passkeyUnavailable: "This browser couldn't use a passkey. Choose 'I can't use my passkey' to sign in with a code.";
     readonly discoverableNotRecognized: "That passkey isn't recognized. Continue with your email instead.";
+    readonly recoveryStarted: "Sign in without your passkey";
+    /** Framed passkeys (MOVMO-686): the browser won't run the passkey ceremony inside the frame. */
+    readonly topLevelRequired: "Your browser needs a separate window to use your passkey.";
+    readonly continueTopLevel: "Continue in a new window";
+    /** Framed passkeys: any browser-side failure; never points a framed user at account recovery first. */
+    readonly framedPasskeyFailed: "Your passkey didn't work here. Try again, or continue in a new window.";
+    readonly recoveryBlocked: "We can't recover this account right now";
 };
 
 export declare type SignInErrorCode = AuthErrorCode | 'network' | 'unknown' | WebAuthnFailure | 'account_mismatch';
@@ -786,7 +839,14 @@ export declare interface SignInFlowProps extends UseMovmoSignInOptions {
     onCancel?: () => void;
 }
 
-export declare type SignInMethod = 'otp' | 'passkey';
+/** What `onVerified`/`onSignedIn` receive. `recoveryUntil` (RFC3339) is set only for `method: 'recovery'`. */
+export declare interface SignInInfo {
+    method: SignInMethod;
+    newUser: boolean;
+    recoveryUntil?: string;
+}
+
+export declare type SignInMethod = 'otp' | 'passkey' | 'recovery';
 
 /**
  * "Sign in to Movmo": `SignInFlow` inside the focus-trapping `Modal`. Code or
@@ -816,14 +876,11 @@ export declare interface SignInModalProps extends Omit<UseMovmoSignInOptions, 'o
      * the prompt; `onAccountMismatch` (re-auth with `expectedUserId`) fires
      * after the package has ended the other account's session.
      */
-    onLoginSuccess: (user: User, info: {
-        method: SignInMethod;
-        newUser: boolean;
-    }) => void;
+    onLoginSuccess: (user: User, info: SignInInfo) => void;
 }
 
 /** `mismatch` is terminal: re-auth signed in a different account (see `onAccountMismatch`). */
-export declare type SignInStep = 'email' | 'passkey' | 'code' | 'enroll' | 'enrolled' | 'done' | 'mismatch';
+export declare type SignInStep = 'email' | 'passkey' | 'recovery' | 'code' | 'enroll' | 'enrolled' | 'done' | 'mismatch';
 
 export declare const Textarea: React_2.ForwardRefExoticComponent<TextareaProps & React_2.RefAttributes<HTMLTextAreaElement>>;
 
@@ -874,20 +931,14 @@ export declare interface UseMovmoSignInOptions {
     surface: 'top-level' | 'embedded';
     getCurrentUser: () => Promise<User>;
     /** The traveler is signed in: fires exactly once, after the enrollment prompt when one is shown. */
-    onSignedIn: (user: User, info: {
-        method: SignInMethod;
-        newUser: boolean;
-    }) => void;
+    onSignedIn: (user: User, info: SignInInfo) => void;
     /**
      * Fires once, right after a successful verify and `getCurrentUser()` (the
      * server session exists), BEFORE the enrollment prompt. Use it for work that
      * mustn't wait for the traveler to answer the prompt; `onSignedIn` keeps its
      * meaning.
      */
-    onVerified?: (user: User, info: {
-        method: SignInMethod;
-        newUser: boolean;
-    }) => void;
+    onVerified?: (user: User, info: SignInInfo) => void;
     /**
      * Re-auth only (`expectedUserId`): a different account signed in. The server
      * session has already been ended by the package (`api.logout()`) when this
@@ -908,6 +959,36 @@ export declare interface UseMovmoSignInOptions {
      */
     expectedUserId?: string;
     promptSurface?: 'modal' | 'connect';
+    /**
+     * A framed window may run the email-first passkey `get()` (the embedding SDK
+     * granted `publickey-credentials-get` on the iframe). Default false. Never
+     * enables autofill, the passkey button, enrollment or `create()`.
+     */
+    framedPasskeys?: boolean;
+    /**
+     * The `/v1/auth/login` response the app already obtained, expected from
+     * `api.login(email, { deferCode: true })`: adopted on mount instead of asking
+     * for an email. `next:"passkey"` runs the ceremony at once (the app must call
+     * within the click's transient activation, ~5 s); `next:"code"` sends the first
+     * code (`/v1/auth/code` on the deferred flow) and shows the code step. The
+     * email comes from `initialEmail` / `lockedEmail`. `api.login` is not called.
+     */
+    resumeLogin?: MovmoLoginResponse;
+    /**
+     * `continueTopLevel()` calls this synchronously (the app opens its popup
+     * inside the click; nothing may `await` before it) with the flow's current
+     * email, the one the ceremony ran for (it may differ from `initialEmail`
+     * after an email change).
+     */
+    onContinueTopLevel?: (email: string) => void;
+    /**
+     * With `resumeLogin`: the passkey/code step's "Change" calls this instead of showing the
+     * hook's own email step, and the host owns the email change. That step
+     * calls `api.login` without `deferCode`, which would send a code at once and
+     * sign a code user in inside the frame, bypassing the host's popup rule.
+     * Without `resumeLogin` or without this, behaviour is unchanged.
+     */
+    onChangeEmail?: () => void;
 }
 
 export declare const validateEmail: (email: string) => boolean;