@dloizides/auth-web 1.4.0 → 1.5.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { ReactElement, ReactNode } from 'react';
-import { BffAuthClient, BffUser, BffLoginRequest, BffForgotPasswordRequest, BffResetPasswordRequest, BffOtpRequestResult, HttpClient } from '@dloizides/auth-client';
+import { BffAuthClient, BffUser, HttpClient, BffLoginRequest, BffForgotPasswordRequest, BffResetPasswordRequest, BffOtpRequestResult } from '@dloizides/auth-client';
 export { BffAuthClient, BffAuthClientOptions, BffForgotPasswordRequest, BffLoginRequest, BffOtpRequestRequest, BffOtpRequestResult, BffOtpVerifyRequest, BffPinLoginRequest, BffRegisterRequest, BffResetPasswordRequest, BffUser, HttpClient, HttpRequest, HttpResponse, createFetchHttpClient } from '@dloizides/auth-client';
 import { UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
 
@@ -232,6 +232,32 @@ interface PasskeySettingsLabels {
     /** Success line shown after returning from a registration. */
     registeredSuccess: string;
 }
+/** Strings rendered by `<PreferredMethodSettingsCard>` — the cross-device default-method picker. */
+interface PreferredMethodSettingsLabels {
+    title: string;
+    description: string;
+    /** The "no preference / ask me each time" option. */
+    noPreference: string;
+    /** Display name for the password method option. */
+    methodPassword: string;
+    /** Display name for the device-PIN method option. */
+    methodPin: string;
+    /** Display name for the passkey method option. */
+    methodPasskey: string;
+    /** Shown while a selection is being saved. */
+    saving: string;
+    /** Error shown when saving the preference fails. */
+    saveFailed: string;
+}
+/** Strings rendered by `<PreferredMethodHint>` — the login-screen "you usually sign in with…" line. */
+interface PreferredMethodHintLabels {
+    /** Full sentence shown when the cached preference is password. */
+    password: string;
+    /** Full sentence shown when the cached preference is device-PIN. */
+    pin: string;
+    /** Full sentence shown when the cached preference is passkey. */
+    passkey: string;
+}
 /** Strings rendered by `<ResetPasswordForm>`. */
 interface ResetPasswordFormLabels {
     title: string;
@@ -263,6 +289,8 @@ declare const DEFAULT_DEVICE_PIN_ENROLL_LABELS: DevicePinEnrollLabels;
 declare const DEFAULT_DEVICE_PIN_SETTINGS_LABELS: DevicePinSettingsLabels;
 declare const DEFAULT_PASSKEY_LOGIN_LABELS: PasskeyLoginLabels;
 declare const DEFAULT_PASSKEY_SETTINGS_LABELS: PasskeySettingsLabels;
+declare const DEFAULT_PREFERRED_METHOD_SETTINGS_LABELS: PreferredMethodSettingsLabels;
+declare const DEFAULT_PREFERRED_METHOD_HINT_LABELS: PreferredMethodHintLabels;
 declare const DEFAULT_RESET_PASSWORD_LABELS: ResetPasswordFormLabels;
 
 /**
@@ -984,6 +1012,129 @@ interface PasskeySettingsCardProps {
 /** Themeable authenticated passkey add card. */
 declare function PasskeySettingsCard({ returnUrl, theme: themeProp, labels: labelsProp, testIdPrefix, }: Readonly<PasskeySettingsCardProps>): ReactElement;
 
+/**
+ * Same-origin client for the user's cross-device login-method preference
+ * (unified-login D5). Unlike the device-PIN client (which targets the BFF's
+ * own `/bff/*` auth endpoints), the preference lives in TenantService and is
+ * reached THROUGH the BFF's YARP proxy:
+ *
+ *  - GET  `${baseUrl}/bff/api/{tenantsSegment}/api/v1/me/preferences`
+ *         → `{ ..., preferredLoginMethod }`
+ *  - PUT  `${baseUrl}/bff/api/{tenantsSegment}/api/v1/me/login-method-preference`
+ *         body `{ method }`
+ *
+ * The BFF attaches the session's Bearer token to the proxied request, so both
+ * calls require an authenticated session (the cookie travels via
+ * `credentials: 'include'`). The PUT carries the `X-BFF-Csrf` header the BFF
+ * anti-forgery middleware requires.
+ *
+ * react-query-FREE: plain `HttpClient` calls with `.then/.catch`. Portable
+ * across every consumer (Expo RN-web apps AND the kefi/poueni surfaces).
+ */
+
+interface PreferencesClientOptions {
+    /** Runtime-agnostic HTTP transport (wrap native `fetch` with `createFetchHttpClient`). */
+    http: HttpClient;
+    /**
+     * BFF origin. Defaults to `''` (same-origin) — the production wiring. An
+     * explicit origin is only useful for tests or a non-same-origin BFF.
+     */
+    baseUrl?: string;
+    /**
+     * The BFF YARP downstream segment that routes to TenantService. Defaults to
+     * `'tenants'` — the segment every product BFF (katalogos / erevna / kefi)
+     * uses for `tenant-api`.
+     */
+    tenantsSegment?: string;
+}
+/**
+ * The narrow client the preferred-method UI depends on. Both methods NEVER
+ * reject — they resolve a benign value on any failure so the settings card and
+ * the post-login cache sync degrade gracefully rather than throwing.
+ */
+interface PreferredMethodClient {
+    /**
+     * `GET /me/preferences` → the stored preferred login method, or `null` when
+     * the user never picked one (or on any failure).
+     */
+    getPreferredLoginMethod(): Promise<string | null>;
+    /**
+     * `PUT /me/login-method-preference` — set (or clear, with `null`) the stored
+     * preference. Resolves `true` on a 2xx, `false` on anything else.
+     */
+    setPreferredLoginMethod(method: string | null): Promise<boolean>;
+}
+/**
+ * Build a same-origin {@link PreferredMethodClient}. With no `baseUrl` this is
+ * the production wiring: same-origin, the session cookie travels automatically.
+ */
+declare function createPreferencesClient(options: PreferencesClientOptions): PreferredMethodClient;
+
+/**
+ * The authenticated "Preferred sign-in method" settings card (unified-login D5).
+ *
+ * Mount on an authenticated settings/account surface alongside the device-PIN
+ * and passkey cards. It lets the user pick which of their enabled login methods
+ * they want emphasised on the login screen — stored SERVER-SIDE so the choice
+ * follows them across devices. The login screen reads the device-local mirror
+ * of this value (see `readCachedPreferredMethod` / `<PreferredMethodHint>`).
+ *
+ * `availableMethods` should be the BFF's advertised methods (from
+ * `GET /bff/config` → `useBffLoginConfig().methods`) so the card only offers
+ * methods this product actually supports. A "No preference" option always
+ * appears. react-query-free: the persistence lives in `usePreferredMethodSetting`.
+ */
+
+interface PreferredMethodSettingsCardProps {
+    /** The client exposing `getPreferredLoginMethod` + `setPreferredLoginMethod`. */
+    client: PreferredMethodClient;
+    /**
+     * The login methods this BFF advertises (lowercase, e.g.
+     * `['password', 'pin', 'passkey']`). Only these are offered, plus the
+     * always-present "No preference" option.
+     */
+    availableMethods: readonly string[];
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<PreferredMethodSettingsLabels>;
+    /** Prefix applied to every `testID`. */
+    testIdPrefix?: string;
+    /** Called whenever a save succeeds (`null` = no preference). */
+    onChanged?: (method: string | null) => void;
+}
+/** Themeable authenticated preferred-method picker. */
+declare function PreferredMethodSettingsCard({ client, availableMethods, theme: themeProp, labels: labelsProp, testIdPrefix, onChanged, }: Readonly<PreferredMethodSettingsCardProps>): ReactElement;
+
+/**
+ * The login-screen "you usually sign in with…" hint (unified-login D5).
+ *
+ * Mount at the top of the login surface. Given the device-local cached
+ * preferred method (`readCachedPreferredMethod()`), it renders a single
+ * reassurance line naming that method. Renders NOTHING for an unknown / absent
+ * method so the login screen stays clean for first-time visitors.
+ *
+ * No network, no state — pure presentation driven by the cached value the host
+ * passes in. (The cache is seeded post-login by `syncPreferredMethodFromServer`.)
+ */
+
+interface PreferredMethodHintProps {
+    /**
+     * The cached preferred method (`'password'` | `'pin'` | `'passkey'`), or
+     * `null`. Typically `readCachedPreferredMethod()`. An unknown / `null` value
+     * renders nothing.
+     */
+    method: string | null;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<PreferredMethodHintLabels>;
+    /** Prefix applied to the `testID`. */
+    testIdPrefix?: string;
+}
+/** Themeable login-screen preferred-method hint. Renders `null` when there is nothing to say. */
+declare function PreferredMethodHint({ method, theme: themeProp, labels: labelsProp, testIdPrefix, }: Readonly<PreferredMethodHintProps>): ReactElement | null;
+
 /**
  * React context for the `AuthTheme`.
  *
@@ -1084,6 +1235,10 @@ declare const AuthTestIds: {
     readonly passkeySettings: "auth-passkey-settings";
     readonly passkeySettingsAdd: "auth-passkey-settings-add";
     readonly passkeySettingsSuccess: "auth-passkey-settings-success";
+    readonly preferredMethodSettings: "auth-preferred-method-settings";
+    readonly preferredMethodSettingsOption: "auth-preferred-method-settings-option";
+    readonly preferredMethodSettingsError: "auth-preferred-method-settings-error";
+    readonly preferredMethodHint: "auth-preferred-method-hint";
 };
 /** Apply an optional prefix to a base test ID. */
 declare function withTestIdPrefix(baseId: string, prefix?: string): string;
@@ -1480,6 +1635,60 @@ declare function readPasskeyError(): PasskeyErrorCode | null;
  */
 declare function readPasskeyRegistered(): boolean;
 
+/**
+ * Device-local cache of the user's preferred login method (unified-login D5).
+ *
+ * The preference is owned server-side (TenantService UserPreference), but the
+ * LOGIN screen needs it BEFORE the user is authenticated — when no server call
+ * is possible. So we cache it in `localStorage`, seeded after every successful
+ * login (see {@link syncPreferredMethodFromServer}). A user who sets "passkey"
+ * on device A will, after their first login on device B, see device B's login
+ * screen prefer passkey too — cross-device sync with one-login lag.
+ *
+ * SSR-safe: every function no-ops / returns `null` when `localStorage` is
+ * unavailable (server render, native, privacy modes that throw on access).
+ */
+/**
+ * Read the cached preferred login method, or `null` when none is cached / the
+ * store is unavailable. Cheap + synchronous so the login screen can call it on
+ * render.
+ */
+declare function readCachedPreferredMethod(): string | null;
+/**
+ * Write (or, with `null`, clear) the cached preferred login method. No-op when
+ * the store is unavailable. Never throws.
+ */
+declare function cachePreferredMethod(method: string | null): void;
+/** Clear the cached preferred login method (e.g. on logout). Never throws. */
+declare function clearCachedPreferredMethod(): void;
+
+/**
+ * Fetch the server-stored preferred login method and mirror it into the
+ * device-local cache. Resolves to the value written (or `null`). Safe to
+ * `void` — it swallows all errors.
+ */
+declare function syncPreferredMethodFromServer(client: PreferredMethodClient): Promise<string | null>;
+
+interface UsePreferredMethodSettingArgs {
+    /** The client exposing `getPreferredLoginMethod` + `setPreferredLoginMethod`. */
+    client: PreferredMethodClient;
+    /** Called whenever a save succeeds (the new value, `null` = no preference). */
+    onChanged?: (method: string | null) => void;
+}
+interface UsePreferredMethodSettingResult {
+    /** `true` until the initial server load resolves. */
+    loading: boolean;
+    /** `true` while a selection is being persisted. */
+    saving: boolean;
+    /** `true` when the last save failed (cleared on the next `select`). */
+    failed: boolean;
+    /** The currently-selected method, or `null` for "no preference". */
+    selected: string | null;
+    /** Optimistically select a method (`null` clears the preference) and persist it. */
+    select: (method: string | null) => void;
+}
+declare function usePreferredMethodSetting({ client, onChanged, }: UsePreferredMethodSettingArgs): UsePreferredMethodSettingResult;
+
 /**
  * `createBffAuthClient` — the one-line wiring of a same-origin `BffAuthClient`.
  *
@@ -1615,4 +1824,4 @@ declare function validatePasswordPolicy(password: string): PasswordPolicyError[]
 /** `true` when the password satisfies every policy rule. */
 declare function isPasswordValid(password: string): boolean;
 
-export { AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type CreateBffAuthClientOptions, DEFAULT_DEVICE_PIN_ENROLL_LABELS, DEFAULT_DEVICE_PIN_SETTINGS_LABELS, DEFAULT_DEVICE_PIN_UNLOCK_LABELS, DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PASSKEY_LOGIN_LABELS, DEFAULT_PASSKEY_SETTINGS_LABELS, DEFAULT_PIN_LABELS, DEFAULT_RESET_PASSWORD_LABELS, DEVICE_PIN_ALLOWED_DIGITS, DEVICE_PIN_DEFAULT_DIGITS, type DevicePinCapableClient, type DevicePinDisableCapableClient, type DevicePinEnrollCapableClient, DevicePinEnrollErrorKey, DevicePinEnrollForm, type DevicePinEnrollFormProps, type DevicePinEnrollLabels, type DevicePinEnrollResult, DevicePinErrorKey, DevicePinInput, type DevicePinInputProps, DevicePinLengthPicker, type DevicePinLengthPickerProps, DevicePinOffer, type DevicePinOfferProps, DevicePinSettingsCard, type DevicePinSettingsCardProps, type DevicePinSettingsLabels, type DevicePinUnlockCapableClient, type DevicePinUnlockLabels, type DevicePinUnlockResult, DevicePinUnlockScreen, type DevicePinUnlockScreenProps, type DevicePinUnlockedUser, ForgotPasswordFields, type ForgotPasswordFieldsLabels, type ForgotPasswordFieldsProps, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, type LoginConfigCapableClient, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, PinForm, type PinFormLabels, type PinFormProps, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffLoginConfigResult, type UseBffResetPasswordOptions, type UseDevicePinDisableArgs, type UseDevicePinDisableResult, type UseDevicePinEnrollArgs, type UseDevicePinEnrollResult, type UseDevicePinUnlockArgs, type UseDevicePinUnlockResult, type UseForgotPasswordSubmitArgs, type UseForgotPasswordSubmitResult, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePinLoginOptions, type UsePinLoginResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, collectUserRoles, createBffAuthClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, readPasskeyError, readPasskeyRegistered, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePinLogin, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };
+export { AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type CreateBffAuthClientOptions, DEFAULT_DEVICE_PIN_ENROLL_LABELS, DEFAULT_DEVICE_PIN_SETTINGS_LABELS, DEFAULT_DEVICE_PIN_UNLOCK_LABELS, DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PASSKEY_LOGIN_LABELS, DEFAULT_PASSKEY_SETTINGS_LABELS, DEFAULT_PIN_LABELS, DEFAULT_PREFERRED_METHOD_HINT_LABELS, DEFAULT_PREFERRED_METHOD_SETTINGS_LABELS, DEFAULT_RESET_PASSWORD_LABELS, DEVICE_PIN_ALLOWED_DIGITS, DEVICE_PIN_DEFAULT_DIGITS, type DevicePinCapableClient, type DevicePinDisableCapableClient, type DevicePinEnrollCapableClient, DevicePinEnrollErrorKey, DevicePinEnrollForm, type DevicePinEnrollFormProps, type DevicePinEnrollLabels, type DevicePinEnrollResult, DevicePinErrorKey, DevicePinInput, type DevicePinInputProps, DevicePinLengthPicker, type DevicePinLengthPickerProps, DevicePinOffer, type DevicePinOfferProps, DevicePinSettingsCard, type DevicePinSettingsCardProps, type DevicePinSettingsLabels, type DevicePinUnlockCapableClient, type DevicePinUnlockLabels, type DevicePinUnlockResult, DevicePinUnlockScreen, type DevicePinUnlockScreenProps, type DevicePinUnlockedUser, ForgotPasswordFields, type ForgotPasswordFieldsLabels, type ForgotPasswordFieldsProps, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, type LoginConfigCapableClient, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, PinForm, type PinFormLabels, type PinFormProps, type PreferencesClientOptions, type PreferredMethodClient, PreferredMethodHint, type PreferredMethodHintLabels, type PreferredMethodHintProps, PreferredMethodSettingsCard, type PreferredMethodSettingsCardProps, type PreferredMethodSettingsLabels, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffLoginConfigResult, type UseBffResetPasswordOptions, type UseDevicePinDisableArgs, type UseDevicePinDisableResult, type UseDevicePinEnrollArgs, type UseDevicePinEnrollResult, type UseDevicePinUnlockArgs, type UseDevicePinUnlockResult, type UseForgotPasswordSubmitArgs, type UseForgotPasswordSubmitResult, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePinLoginOptions, type UsePinLoginResult, type UsePreferredMethodSettingArgs, type UsePreferredMethodSettingResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, cachePreferredMethod, clearCachedPreferredMethod, collectUserRoles, createBffAuthClient, createPreferencesClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, readCachedPreferredMethod, readPasskeyError, readPasskeyRegistered, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, syncPreferredMethodFromServer, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePinLogin, usePreferredMethodSetting, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ReactElement, ReactNode } from 'react';
-import { BffAuthClient, BffUser, BffLoginRequest, BffForgotPasswordRequest, BffResetPasswordRequest, BffOtpRequestResult, HttpClient } from '@dloizides/auth-client';
+import { BffAuthClient, BffUser, HttpClient, BffLoginRequest, BffForgotPasswordRequest, BffResetPasswordRequest, BffOtpRequestResult } from '@dloizides/auth-client';
 export { BffAuthClient, BffAuthClientOptions, BffForgotPasswordRequest, BffLoginRequest, BffOtpRequestRequest, BffOtpRequestResult, BffOtpVerifyRequest, BffPinLoginRequest, BffRegisterRequest, BffResetPasswordRequest, BffUser, HttpClient, HttpRequest, HttpResponse, createFetchHttpClient } from '@dloizides/auth-client';
 import { UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
 
@@ -232,6 +232,32 @@ interface PasskeySettingsLabels {
     /** Success line shown after returning from a registration. */
     registeredSuccess: string;
 }
+/** Strings rendered by `<PreferredMethodSettingsCard>` — the cross-device default-method picker. */
+interface PreferredMethodSettingsLabels {
+    title: string;
+    description: string;
+    /** The "no preference / ask me each time" option. */
+    noPreference: string;
+    /** Display name for the password method option. */
+    methodPassword: string;
+    /** Display name for the device-PIN method option. */
+    methodPin: string;
+    /** Display name for the passkey method option. */
+    methodPasskey: string;
+    /** Shown while a selection is being saved. */
+    saving: string;
+    /** Error shown when saving the preference fails. */
+    saveFailed: string;
+}
+/** Strings rendered by `<PreferredMethodHint>` — the login-screen "you usually sign in with…" line. */
+interface PreferredMethodHintLabels {
+    /** Full sentence shown when the cached preference is password. */
+    password: string;
+    /** Full sentence shown when the cached preference is device-PIN. */
+    pin: string;
+    /** Full sentence shown when the cached preference is passkey. */
+    passkey: string;
+}
 /** Strings rendered by `<ResetPasswordForm>`. */
 interface ResetPasswordFormLabels {
     title: string;
@@ -263,6 +289,8 @@ declare const DEFAULT_DEVICE_PIN_ENROLL_LABELS: DevicePinEnrollLabels;
 declare const DEFAULT_DEVICE_PIN_SETTINGS_LABELS: DevicePinSettingsLabels;
 declare const DEFAULT_PASSKEY_LOGIN_LABELS: PasskeyLoginLabels;
 declare const DEFAULT_PASSKEY_SETTINGS_LABELS: PasskeySettingsLabels;
+declare const DEFAULT_PREFERRED_METHOD_SETTINGS_LABELS: PreferredMethodSettingsLabels;
+declare const DEFAULT_PREFERRED_METHOD_HINT_LABELS: PreferredMethodHintLabels;
 declare const DEFAULT_RESET_PASSWORD_LABELS: ResetPasswordFormLabels;
 
 /**
@@ -984,6 +1012,129 @@ interface PasskeySettingsCardProps {
 /** Themeable authenticated passkey add card. */
 declare function PasskeySettingsCard({ returnUrl, theme: themeProp, labels: labelsProp, testIdPrefix, }: Readonly<PasskeySettingsCardProps>): ReactElement;
 
+/**
+ * Same-origin client for the user's cross-device login-method preference
+ * (unified-login D5). Unlike the device-PIN client (which targets the BFF's
+ * own `/bff/*` auth endpoints), the preference lives in TenantService and is
+ * reached THROUGH the BFF's YARP proxy:
+ *
+ *  - GET  `${baseUrl}/bff/api/{tenantsSegment}/api/v1/me/preferences`
+ *         → `{ ..., preferredLoginMethod }`
+ *  - PUT  `${baseUrl}/bff/api/{tenantsSegment}/api/v1/me/login-method-preference`
+ *         body `{ method }`
+ *
+ * The BFF attaches the session's Bearer token to the proxied request, so both
+ * calls require an authenticated session (the cookie travels via
+ * `credentials: 'include'`). The PUT carries the `X-BFF-Csrf` header the BFF
+ * anti-forgery middleware requires.
+ *
+ * react-query-FREE: plain `HttpClient` calls with `.then/.catch`. Portable
+ * across every consumer (Expo RN-web apps AND the kefi/poueni surfaces).
+ */
+
+interface PreferencesClientOptions {
+    /** Runtime-agnostic HTTP transport (wrap native `fetch` with `createFetchHttpClient`). */
+    http: HttpClient;
+    /**
+     * BFF origin. Defaults to `''` (same-origin) — the production wiring. An
+     * explicit origin is only useful for tests or a non-same-origin BFF.
+     */
+    baseUrl?: string;
+    /**
+     * The BFF YARP downstream segment that routes to TenantService. Defaults to
+     * `'tenants'` — the segment every product BFF (katalogos / erevna / kefi)
+     * uses for `tenant-api`.
+     */
+    tenantsSegment?: string;
+}
+/**
+ * The narrow client the preferred-method UI depends on. Both methods NEVER
+ * reject — they resolve a benign value on any failure so the settings card and
+ * the post-login cache sync degrade gracefully rather than throwing.
+ */
+interface PreferredMethodClient {
+    /**
+     * `GET /me/preferences` → the stored preferred login method, or `null` when
+     * the user never picked one (or on any failure).
+     */
+    getPreferredLoginMethod(): Promise<string | null>;
+    /**
+     * `PUT /me/login-method-preference` — set (or clear, with `null`) the stored
+     * preference. Resolves `true` on a 2xx, `false` on anything else.
+     */
+    setPreferredLoginMethod(method: string | null): Promise<boolean>;
+}
+/**
+ * Build a same-origin {@link PreferredMethodClient}. With no `baseUrl` this is
+ * the production wiring: same-origin, the session cookie travels automatically.
+ */
+declare function createPreferencesClient(options: PreferencesClientOptions): PreferredMethodClient;
+
+/**
+ * The authenticated "Preferred sign-in method" settings card (unified-login D5).
+ *
+ * Mount on an authenticated settings/account surface alongside the device-PIN
+ * and passkey cards. It lets the user pick which of their enabled login methods
+ * they want emphasised on the login screen — stored SERVER-SIDE so the choice
+ * follows them across devices. The login screen reads the device-local mirror
+ * of this value (see `readCachedPreferredMethod` / `<PreferredMethodHint>`).
+ *
+ * `availableMethods` should be the BFF's advertised methods (from
+ * `GET /bff/config` → `useBffLoginConfig().methods`) so the card only offers
+ * methods this product actually supports. A "No preference" option always
+ * appears. react-query-free: the persistence lives in `usePreferredMethodSetting`.
+ */
+
+interface PreferredMethodSettingsCardProps {
+    /** The client exposing `getPreferredLoginMethod` + `setPreferredLoginMethod`. */
+    client: PreferredMethodClient;
+    /**
+     * The login methods this BFF advertises (lowercase, e.g.
+     * `['password', 'pin', 'passkey']`). Only these are offered, plus the
+     * always-present "No preference" option.
+     */
+    availableMethods: readonly string[];
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<PreferredMethodSettingsLabels>;
+    /** Prefix applied to every `testID`. */
+    testIdPrefix?: string;
+    /** Called whenever a save succeeds (`null` = no preference). */
+    onChanged?: (method: string | null) => void;
+}
+/** Themeable authenticated preferred-method picker. */
+declare function PreferredMethodSettingsCard({ client, availableMethods, theme: themeProp, labels: labelsProp, testIdPrefix, onChanged, }: Readonly<PreferredMethodSettingsCardProps>): ReactElement;
+
+/**
+ * The login-screen "you usually sign in with…" hint (unified-login D5).
+ *
+ * Mount at the top of the login surface. Given the device-local cached
+ * preferred method (`readCachedPreferredMethod()`), it renders a single
+ * reassurance line naming that method. Renders NOTHING for an unknown / absent
+ * method so the login screen stays clean for first-time visitors.
+ *
+ * No network, no state — pure presentation driven by the cached value the host
+ * passes in. (The cache is seeded post-login by `syncPreferredMethodFromServer`.)
+ */
+
+interface PreferredMethodHintProps {
+    /**
+     * The cached preferred method (`'password'` | `'pin'` | `'passkey'`), or
+     * `null`. Typically `readCachedPreferredMethod()`. An unknown / `null` value
+     * renders nothing.
+     */
+    method: string | null;
+    /** Explicit theme; overrides any `<AuthThemeProvider>`. */
+    theme?: AuthTheme;
+    /** Localised copy. Partial — unspecified keys fall back to English defaults. */
+    labels?: Partial<PreferredMethodHintLabels>;
+    /** Prefix applied to the `testID`. */
+    testIdPrefix?: string;
+}
+/** Themeable login-screen preferred-method hint. Renders `null` when there is nothing to say. */
+declare function PreferredMethodHint({ method, theme: themeProp, labels: labelsProp, testIdPrefix, }: Readonly<PreferredMethodHintProps>): ReactElement | null;
+
 /**
  * React context for the `AuthTheme`.
  *
@@ -1084,6 +1235,10 @@ declare const AuthTestIds: {
     readonly passkeySettings: "auth-passkey-settings";
     readonly passkeySettingsAdd: "auth-passkey-settings-add";
     readonly passkeySettingsSuccess: "auth-passkey-settings-success";
+    readonly preferredMethodSettings: "auth-preferred-method-settings";
+    readonly preferredMethodSettingsOption: "auth-preferred-method-settings-option";
+    readonly preferredMethodSettingsError: "auth-preferred-method-settings-error";
+    readonly preferredMethodHint: "auth-preferred-method-hint";
 };
 /** Apply an optional prefix to a base test ID. */
 declare function withTestIdPrefix(baseId: string, prefix?: string): string;
@@ -1480,6 +1635,60 @@ declare function readPasskeyError(): PasskeyErrorCode | null;
  */
 declare function readPasskeyRegistered(): boolean;
 
+/**
+ * Device-local cache of the user's preferred login method (unified-login D5).
+ *
+ * The preference is owned server-side (TenantService UserPreference), but the
+ * LOGIN screen needs it BEFORE the user is authenticated — when no server call
+ * is possible. So we cache it in `localStorage`, seeded after every successful
+ * login (see {@link syncPreferredMethodFromServer}). A user who sets "passkey"
+ * on device A will, after their first login on device B, see device B's login
+ * screen prefer passkey too — cross-device sync with one-login lag.
+ *
+ * SSR-safe: every function no-ops / returns `null` when `localStorage` is
+ * unavailable (server render, native, privacy modes that throw on access).
+ */
+/**
+ * Read the cached preferred login method, or `null` when none is cached / the
+ * store is unavailable. Cheap + synchronous so the login screen can call it on
+ * render.
+ */
+declare function readCachedPreferredMethod(): string | null;
+/**
+ * Write (or, with `null`, clear) the cached preferred login method. No-op when
+ * the store is unavailable. Never throws.
+ */
+declare function cachePreferredMethod(method: string | null): void;
+/** Clear the cached preferred login method (e.g. on logout). Never throws. */
+declare function clearCachedPreferredMethod(): void;
+
+/**
+ * Fetch the server-stored preferred login method and mirror it into the
+ * device-local cache. Resolves to the value written (or `null`). Safe to
+ * `void` — it swallows all errors.
+ */
+declare function syncPreferredMethodFromServer(client: PreferredMethodClient): Promise<string | null>;
+
+interface UsePreferredMethodSettingArgs {
+    /** The client exposing `getPreferredLoginMethod` + `setPreferredLoginMethod`. */
+    client: PreferredMethodClient;
+    /** Called whenever a save succeeds (the new value, `null` = no preference). */
+    onChanged?: (method: string | null) => void;
+}
+interface UsePreferredMethodSettingResult {
+    /** `true` until the initial server load resolves. */
+    loading: boolean;
+    /** `true` while a selection is being persisted. */
+    saving: boolean;
+    /** `true` when the last save failed (cleared on the next `select`). */
+    failed: boolean;
+    /** The currently-selected method, or `null` for "no preference". */
+    selected: string | null;
+    /** Optimistically select a method (`null` clears the preference) and persist it. */
+    select: (method: string | null) => void;
+}
+declare function usePreferredMethodSetting({ client, onChanged, }: UsePreferredMethodSettingArgs): UsePreferredMethodSettingResult;
+
 /**
  * `createBffAuthClient` — the one-line wiring of a same-origin `BffAuthClient`.
  *
@@ -1615,4 +1824,4 @@ declare function validatePasswordPolicy(password: string): PasswordPolicyError[]
 /** `true` when the password satisfies every policy rule. */
 declare function isPasswordValid(password: string): boolean;
 
-export { AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type CreateBffAuthClientOptions, DEFAULT_DEVICE_PIN_ENROLL_LABELS, DEFAULT_DEVICE_PIN_SETTINGS_LABELS, DEFAULT_DEVICE_PIN_UNLOCK_LABELS, DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PASSKEY_LOGIN_LABELS, DEFAULT_PASSKEY_SETTINGS_LABELS, DEFAULT_PIN_LABELS, DEFAULT_RESET_PASSWORD_LABELS, DEVICE_PIN_ALLOWED_DIGITS, DEVICE_PIN_DEFAULT_DIGITS, type DevicePinCapableClient, type DevicePinDisableCapableClient, type DevicePinEnrollCapableClient, DevicePinEnrollErrorKey, DevicePinEnrollForm, type DevicePinEnrollFormProps, type DevicePinEnrollLabels, type DevicePinEnrollResult, DevicePinErrorKey, DevicePinInput, type DevicePinInputProps, DevicePinLengthPicker, type DevicePinLengthPickerProps, DevicePinOffer, type DevicePinOfferProps, DevicePinSettingsCard, type DevicePinSettingsCardProps, type DevicePinSettingsLabels, type DevicePinUnlockCapableClient, type DevicePinUnlockLabels, type DevicePinUnlockResult, DevicePinUnlockScreen, type DevicePinUnlockScreenProps, type DevicePinUnlockedUser, ForgotPasswordFields, type ForgotPasswordFieldsLabels, type ForgotPasswordFieldsProps, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, type LoginConfigCapableClient, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, PinForm, type PinFormLabels, type PinFormProps, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffLoginConfigResult, type UseBffResetPasswordOptions, type UseDevicePinDisableArgs, type UseDevicePinDisableResult, type UseDevicePinEnrollArgs, type UseDevicePinEnrollResult, type UseDevicePinUnlockArgs, type UseDevicePinUnlockResult, type UseForgotPasswordSubmitArgs, type UseForgotPasswordSubmitResult, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePinLoginOptions, type UsePinLoginResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, collectUserRoles, createBffAuthClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, readPasskeyError, readPasskeyRegistered, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePinLogin, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };
+export { AuthTestIds, type AuthTheme, type AuthThemeColors, AuthThemeProvider, type AuthThemeProviderProps, type AuthThemeRadii, type AuthThemeSpacing, type AuthThemeTypography, BffAuthStatus, type BffDeviceState, type BffLoginConfig, type CreateBffAuthClientOptions, DEFAULT_DEVICE_PIN_ENROLL_LABELS, DEFAULT_DEVICE_PIN_SETTINGS_LABELS, DEFAULT_DEVICE_PIN_UNLOCK_LABELS, DEFAULT_FORGOT_PASSWORD_FIELDS_LABELS, DEFAULT_FORGOT_PASSWORD_LABELS, DEFAULT_LOGIN_LABELS, DEFAULT_OTP_LABELS, DEFAULT_PASSKEY_LOGIN_LABELS, DEFAULT_PASSKEY_SETTINGS_LABELS, DEFAULT_PIN_LABELS, DEFAULT_PREFERRED_METHOD_HINT_LABELS, DEFAULT_PREFERRED_METHOD_SETTINGS_LABELS, DEFAULT_RESET_PASSWORD_LABELS, DEVICE_PIN_ALLOWED_DIGITS, DEVICE_PIN_DEFAULT_DIGITS, type DevicePinCapableClient, type DevicePinDisableCapableClient, type DevicePinEnrollCapableClient, DevicePinEnrollErrorKey, DevicePinEnrollForm, type DevicePinEnrollFormProps, type DevicePinEnrollLabels, type DevicePinEnrollResult, DevicePinErrorKey, DevicePinInput, type DevicePinInputProps, DevicePinLengthPicker, type DevicePinLengthPickerProps, DevicePinOffer, type DevicePinOfferProps, DevicePinSettingsCard, type DevicePinSettingsCardProps, type DevicePinSettingsLabels, type DevicePinUnlockCapableClient, type DevicePinUnlockLabels, type DevicePinUnlockResult, DevicePinUnlockScreen, type DevicePinUnlockScreenProps, type DevicePinUnlockedUser, ForgotPasswordFields, type ForgotPasswordFieldsLabels, type ForgotPasswordFieldsProps, ForgotPasswordForm, type ForgotPasswordFormLabels, type ForgotPasswordFormProps, type LoginConfigCapableClient, LoginForm, type LoginFormLabels, type LoginFormProps, OtpForm, type OtpFormLabels, type OtpFormProps, OtpLoginStep, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, type PasskeyErrorCode, PasskeyLoginButton, type PasskeyLoginButtonProps, type PasskeyLoginLabels, PasskeySettingsCard, type PasskeySettingsCardProps, type PasskeySettingsLabels, PasswordPolicyError, PinForm, type PinFormLabels, type PinFormProps, type PreferencesClientOptions, type PreferredMethodClient, PreferredMethodHint, type PreferredMethodHintLabels, type PreferredMethodHintProps, PreferredMethodSettingsCard, type PreferredMethodSettingsCardProps, type PreferredMethodSettingsLabels, ResetPasswordError, ResetPasswordForm, type ResetPasswordFormLabels, type ResetPasswordFormProps, type RoleRoute, type RoleRouteTable, type UseBffAuthOptions, type UseBffAuthResult, type UseBffForgotPasswordOptions, type UseBffLoginConfigResult, type UseBffResetPasswordOptions, type UseDevicePinDisableArgs, type UseDevicePinDisableResult, type UseDevicePinEnrollArgs, type UseDevicePinEnrollResult, type UseDevicePinUnlockArgs, type UseDevicePinUnlockResult, type UseForgotPasswordSubmitArgs, type UseForgotPasswordSubmitResult, type UseOtpLoginOptions, type UseOtpLoginResult, type UsePinLoginOptions, type UsePinLoginResult, type UsePreferredMethodSettingArgs, type UsePreferredMethodSettingResult, type UseResetPasswordFormArgs, type UseResetPasswordFormResult, cachePreferredMethod, clearCachedPreferredMethod, collectUserRoles, createBffAuthClient, createPreferencesClient, defaultAuthTheme, isAllowedPinDigits, isPasswordValid, isValidForgotPasswordEmail, readCachedPreferredMethod, readPasskeyError, readPasskeyRegistered, resolvePostLoginRoute, startPasskeyLogin, startPasskeyRegistration, syncPreferredMethodFromServer, useAuthTheme, useBffAuth, useBffForgotPassword, useBffLoginConfig, useBffResetPassword, useDevicePinDisable, useDevicePinEnroll, useDevicePinUnlock, useForgotPasswordSubmit, useOtpLogin, usePinLogin, usePreferredMethodSetting, useResetPasswordForm, validatePasswordPolicy, withTestIdPrefix };