@movmo_app/payments 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -7,6 +7,16 @@ export declare interface CardFieldError {
     message: string;
 }
 
+/**
+ * Focus state of each Spreedly-hosted iframe. The browser's `focus-within`
+ * CSS pseudo-class can't see across iframe boundaries, so the consumer needs
+ * an explicit signal to render the "active border" on the iframe shell.
+ */
+declare interface CardFieldFocus {
+    number: boolean;
+    cvv: boolean;
+}
+
 declare interface CardFieldValidity {
     /** True only when the card-number field has a complete, length-valid value. */
     number: boolean;
@@ -27,12 +37,101 @@ export declare interface CardholderTokenizeData {
     zip?: string;
 }
 
+/**
+ * Builds an auth-aware `fetch` that the payments package (or any other
+ * consumer that registers it via `setPaymentsConfig({ fetch })`) can call.
+ * See file header for the full contract.
+ */
+export declare const createMovmoAuthFetch: (options: CreateMovmoAuthFetchOptions) => typeof fetch;
+
+/**
+ * Auth-aware `fetch` wrapper for `@movmo_app/payments`. The package's API
+ * helpers call through `getPaymentsConfig().fetch`, bypassing whatever axios
+ * interceptor stack the consumer wires up. Without this wrapper:
+ *
+ *   - Session cookie expiry → silent 401/403 (no refresh, no logout).
+ *   - State-mutating endpoints → 403 because the CSRF cookie isn't echoed.
+ *   - Local-dev / multi-tenant flows → missing per-request headers like
+ *     `X-Movmo-Proxy-Auth` or `movmo-customer-id`.
+ *
+ * This factory replaces a ~95-line `paymentsFetch.ts` copy that was
+ * duplicated across consumer apps. The contract:
+ *
+ *   1. CSRF token from `csrfCookieName` is set on every request as
+ *      `X-CSRF-Token` (matching the axios interceptor's unconditional set).
+ *   2. `extraHeaders(input, init)` is invoked per-request to allow dynamic
+ *      headers (proxy-auth, customer id, etc.). Headers the caller already
+ *      set on `init.headers` win — `extraHeaders` only fills gaps.
+ *   3. `credentials: 'include'` is forced so the session cookie travels.
+ *   4. On a 401/403 from a non-auth endpoint, the wrapper calls
+ *      `refreshSession()` once (concurrent failures share one in-flight
+ *      promise) and retries the original request. If refresh ITSELF fails,
+ *      `onRefreshFailed(err)` fires so the consumer can drive a sign-out —
+ *      silently swallowing here would strand the user on a broken page.
+ *      Failures on the *retry* fetch are logged and the original response is
+ *      returned so the SDK still sees a Response to render an error from.
+ *   5. The original fetch's network errors (offline, CORS, DNS) propagate.
+ *      Only retry-path failures are caught; pre-refresh errors are left for
+ *      the consumer to surface.
+ *
+ * The duplicated copies that this replaces both silently swallowed refresh
+ * failure (see review issue #1 on both PR #47 + PR #180). Making
+ * `onRefreshFailed` *required* enforces at the type level that consumers
+ * wire up a logout path.
+ */
+export declare interface CreateMovmoAuthFetchOptions {
+    /**
+     * Refreshes the session cookie. Called once on the first 401/403; concurrent
+     * 401/403s share the same in-flight promise. Resolved value is ignored — the
+     * wrapper only cares about success vs. rejection. Must rotate the session
+     * cookie (and CSRF cookie, if applicable) such that a retry with the same
+     * request will succeed.
+     */
+    refreshSession: () => Promise<unknown>;
+    /**
+     * Fired when `refreshSession()` itself rejects. The consumer MUST treat this
+     * as a terminal auth failure and trigger a sign-out + redirect — otherwise
+     * the user is stranded on a broken page with `authState.isAuthenticated`
+     * still true.
+     *
+     * Receives the underlying rejection so the consumer can log it.
+     */
+    onRefreshFailed: (error: unknown) => void;
+    /**
+     * Cookie name carrying the CSRF token. Defaults to `movmo_csrf_token`.
+     */
+    csrfCookieName?: string;
+    /**
+     * Optional per-request header builder. Evaluated on every call (not cached)
+     * so dynamically-changing headers (e.g. `movmo-customer-id` driven by a
+     * route param) reflect the current value. Headers the caller already set
+     * on `init.headers` always win — `extraHeaders` only fills gaps.
+     */
+    extraHeaders?: (input: RequestInfo | URL, init?: RequestInit) => Record<string, string>;
+    /**
+     * Substring used to detect requests that must NOT trigger the refresh
+     * retry — typically the auth-refresh endpoint itself, to avoid an
+     * infinite recursion when refresh returns 401. Defaults to `/v1/auth/`.
+     */
+    authPathFragment?: string;
+    /**
+     * Underlying fetch impl. Defaults to `globalThis.fetch.bind(globalThis)`.
+     * Override only for tests or non-browser environments.
+     */
+    baseFetch?: typeof fetch;
+    /**
+     * Cookie reader. Defaults to reading `document.cookie`. Override only in
+     * non-browser test environments — the default works in jsdom.
+     */
+    readCookie?: (name: string) => string | null;
+}
+
 export declare const getPaymentsConfig: () => InternalPaymentsConfig;
 
 /* Excluded from this release type: InternalPaymentsConfig */
 
 export declare const MovmoCardForm: {
-    ({ userId, onSuccess, onError, isDefault, className, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, autoSave, formId, hideInternalSaveButton, onCanSubmitChange, }: MovmoCardFormProps): JSX_2.Element;
+    ({ userId, onSuccess, onError, isDefault, className, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, autoSave, formId, hideInternalSaveButton, onCanSubmitChange, onSavingChange, autoFocus, }: MovmoCardFormProps): JSX_2.Element;
     displayName: string;
 };
 
@@ -77,15 +176,32 @@ export declare interface MovmoCardFormProps {
      * not in flight). Use to enable / disable an external Save button.
      */
     onCanSubmitChange?: (canSubmit: boolean) => void;
+    /**
+     * Fires whenever the form transitions in / out of the "saving" state
+     * (tokenize call or save POST in flight). A parent rendering its own
+     * Save button (e.g. a modal footer) uses this to swap the button label
+     * for a spinner. The hook's loading state is internal and not surfaced
+     * directly — this callback is the single source of truth.
+     */
+    onSavingChange?: (isSaving: boolean) => void;
+    /**
+     * When set, the named Spreedly hosted-fields iframe receives keyboard
+     * focus the moment the field becomes ready. Use `"number"` for the
+     * accounts-ui add-card modal so the user can start typing immediately.
+     */
+    autoFocus?: 'number' | 'cvv';
 }
 
 /**
- * Compact preview of a single saved card: brand icon + "Brand last4".
- * Used by consumers (e.g. flights-ui's collapsed checkout drawer) to show
- * the currently-selected card outside the full `<PaymentMethodsManager />`
+ * Compact preview of a single saved card: brand icon + label. Used by
+ * consumers (e.g. flights-ui's collapsed checkout drawer) to show the
+ * currently-selected card outside the full `<PaymentMethodsManager />`
  * list view. Keeps the brand-icon styling consistent with the expanded list.
+ *
+ * Brand icon is sized to match flights-ui main's `w-[34px]` collapsed view.
+ * No vertical padding — the parent controls spacing.
  */
-export declare const PaymentMethodPreview: ({ method, trailing, onClick, className, }: PaymentMethodPreviewProps) => JSX_2.Element;
+export declare const PaymentMethodPreview: ({ method, trailing, onClick, cardLabelFormat, className, }: PaymentMethodPreviewProps) => JSX_2.Element;
 
 export declare interface PaymentMethodPreviewProps {
     /**
@@ -98,11 +214,17 @@ export declare interface PaymentMethodPreviewProps {
     trailing?: React.ReactNode;
     /** Whole-row click handler — typically toggles the drawer open. */
     onClick?: () => void;
+    /**
+     * Controls how the card label is rendered.
+     * - `'branded'` (default): "Visa 4242" — brand name + last4
+     * - `'masked'`: "•••• 4242" — masked bullets + last4 (flights-ui collapsed-drawer style)
+     */
+    cardLabelFormat?: 'masked' | 'branded';
     className?: string;
 }
 
 export declare const PaymentMethodsManager: {
-    ({ userId, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, selectedId, onSelect, onChange, paymentTypeSelector, autoSaveFirstCard, selectionSetsDefault, showDefaultBadge, className, }: PaymentMethodsManagerProps): JSX_2.Element;
+    ({ userId, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, selectedId, onSelect, onChange, paymentTypeSelector, autoSaveFirstCard, selectionSetsDefault, showDefaultBadge, collapsible, cardLabelFormat, className, }: PaymentMethodsManagerProps): JSX_2.Element;
     displayName: string;
 };
 
@@ -151,6 +273,19 @@ export declare interface PaymentMethodsManagerProps {
      * Defaults to `true`.
      */
     showDefaultBadge?: boolean;
+    /**
+     * When `true` AND the user has at least one saved card, the list collapses
+     * into a compact preview row with a chevron-down toggle. Expanding shows the
+     * full list + Add button. Defaults to `false` (accounts-ui behaviour).
+     * flights-ui passes `true`.
+     */
+    collapsible?: boolean;
+    /**
+     * Controls the card label format inside rows.
+     * - `'branded'` (default): "Visa 4242" — brand name + last4
+     * - `'masked'`: "•••• 4242" — masked bullets + last4 (flights-ui style)
+     */
+    cardLabelFormat?: 'masked' | 'branded';
     className?: string;
 }
 
@@ -171,6 +306,15 @@ export declare interface PaymentsConfig {
      * consumers should override at boot once a prod CDN is set up.
      */
     iconCdnBaseUrl?: string;
+    /**
+     * Custom `fetch` impl used by every API call in this package. Defaults to
+     * `globalThis.fetch`. Consumers that need auth-token refresh, CSRF-token
+     * injection, or any other request-shaping logic should provide their own
+     * wrapper here (e.g. one that retries on 401/403 after refreshing the
+     * session cookie). The package never adds business headers — that's the
+     * consumer's responsibility.
+     */
+    fetch?: typeof fetch;
 }
 
 export declare const setPaymentsConfig: (config: Partial<PaymentsConfig>) => void;
@@ -231,6 +375,12 @@ export declare interface UseMovmoCardFieldsResult {
     validity: CardFieldValidity;
     /** Latest detected brand (or null if unknown). */
     brand: string | null;
+    /**
+     * Live focus state for each iframe. True while the user is editing that
+     * field. Consumers use this to apply an "active" border on the iframe shell
+     * (the browser's `:focus-within` CSS doesn't propagate across iframes).
+     */
+    focused: CardFieldFocus;
     /**
      * Programmatically move keyboard focus into one of the Spreedly iframes.
      * No-op when the hook is not in the `'ready'` state. Used to auto-advance