@movmo_app/payments 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -39,6 +39,8 @@ declare interface CardFieldValidity {
     cvv: boolean;
 }
 
+export declare type CardFormField = 'number' | 'expiry' | 'cvv' | 'zip' | 'name';
+
 export declare type CardFormStatus = 'idle' | 'loading' | 'ready' | 'tokenizing' | 'saving' | 'error';
 
 export declare interface CardholderTokenizeData {
@@ -52,6 +54,18 @@ export declare interface CardholderTokenizeData {
     zip?: string;
 }
 
+/**
+ * PII-free validation snapshot: field KEYS only, never values. Lets a parent
+ * (e.g. `PaymentMethodsManager`) turn touched-invalid streaks into a
+ * consumer-side friction signal without the SDK importing an analytics
+ * library or leaking anything the traveler typed.
+ */
+export declare interface CardValidationState {
+    valid: boolean;
+    missing: CardFormField[];
+    touchedInvalid: CardFormField[];
+}
+
 /**
  * Builds an auth-aware `fetch` that the payments package (or any other
  * consumer that registers it via `setPaymentsConfig({ fetch })`) can call.
@@ -59,41 +73,6 @@ export declare interface CardholderTokenizeData {
  */
 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
@@ -129,6 +108,11 @@ export declare interface CreateMovmoAuthFetchOptions {
      * infinite recursion when refresh returns 401. Defaults to `/v1/auth/`.
      */
     authPathFragment?: string;
+    /**
+     * 403 response `code`s that skip refresh + retry (the response is returned
+     * as-is). Defaults to {@link DEFAULT_NO_REFRESH_CODES}.
+     */
+    noRefreshCodes?: ReadonlySet<string>;
     /**
      * Underlying fetch impl. Defaults to `globalThis.fetch.bind(globalThis)`.
      * Override only for tests or non-browser environments.
@@ -141,6 +125,9 @@ export declare interface CreateMovmoAuthFetchOptions {
     readCookie?: (name: string) => string | null;
 }
 
+/** 403 error codes that mean "refreshing will not help"; the wrapper returns them untouched. */
+export declare const DEFAULT_NO_REFRESH_CODES: ReadonlySet<string>;
+
 /**
  * The cardholder/zip subset of {@link UpdatePaymentMethodPatch} that the Edit
  * flow (MOVMO-381) can mutate. Derived via `Pick` so it stays in sync if the
@@ -154,7 +141,7 @@ export declare const getPaymentsConfig: () => InternalPaymentsConfig;
 /* Excluded from this release type: InternalPaymentsConfig */
 
 export declare const MovmoCardForm: {
-    ({ userId, onSuccess, onError, onErrorDetail, isDefault, className, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, autoSave, formId, hideInternalSaveButton, onCanSubmitChange, onSavingChange, autoFocus, }: MovmoCardFormProps): JSX_2.Element;
+    ({ userId, onSuccess, onError, onErrorDetail, isDefault, className, defaultCardholderName, defaultCardholderFirstName, defaultCardholderLastName, autoSave, formId, hideInternalSaveButton, onCanSubmitChange, onSavingChange, autoFocus, onValidationChange, }: MovmoCardFormProps): JSX_2.Element;
     displayName: string;
 };
 
@@ -221,6 +208,14 @@ export declare interface MovmoCardFormProps {
      * accounts-ui add-card modal so the user can start typing immediately.
      */
     autoFocus?: 'number' | 'cvv';
+    /**
+     * Fires whenever the validation snapshot changes (missing fields or
+     * touched-invalid fields). PII-free by design — carries field KEYS only,
+     * never values — so a parent can turn a touched-invalid streak into an
+     * analytics-neutral friction event without the SDK importing an analytics
+     * library.
+     */
+    onValidationChange?: (state: CardValidationState) => void;
 }
 
 /**
@@ -254,6 +249,12 @@ export declare interface PaymentManagerError {
     source: PaymentErrorSource;
     message: string;
     cause?: unknown;
+    /** HTTP status when the failure was an API response. */
+    status?: number;
+    /** Server error code (e.g. `recovery_cooldown`) when present. */
+    code?: string;
+    /** RFC3339 UTC end of a `recovery_cooldown`, when the server sent it. */
+    until?: string;
 }
 
 /**
@@ -270,8 +271,15 @@ export declare interface PaymentManagerError {
  * - `edited`        — the cardholder/zip PUT succeeded.
  * - `deleted`       — the delete request succeeded.
  * - `set_default`   — the set-default PUT succeeded.
+ * - `validation_error` — a touched card-form field is invalid (fires once per
+ *                     invalid streak, not per keystroke). This is a friction
+ *                     signal, not a failure — it's the analytics-neutral
+ *                     counterpart to `onError`'s `card-tokenize` source, meant
+ *                     to surface which fields trip people up. Props are
+ *                     `field_count` and `fields` (touched-invalid field KEYS
+ *                     only, e.g. `'zip'` — never card values).
  */
-export declare type PaymentMethodEvent = 'autoselected' | 'selected' | 'added' | 'edited' | 'deleted' | 'set_default';
+export declare type PaymentMethodEvent = 'autoselected' | 'selected' | 'added' | 'edited' | 'deleted' | 'set_default' | 'validation_error';
 
 /**
  * Compact preview of a single saved card: brand icon + label. Used by
@@ -415,10 +423,26 @@ export declare interface PaymentMethodSummary {
     vault?: 'stripe' | 'spreedly';
     /** Current cardholder name (MOVMO-381). Empty/absent for legacy rows. */
     cardholderName?: string;
-    /** Current billing ZIP (MOVMO-381). Empty/absent for legacy rows. */
+    /** Current billing postal code (MOVMO-381). Empty/absent for legacy rows. */
     zip?: string;
 }
 
+/**
+ * Error thrown by every API helper on a non-2xx response. `code`/`until` come
+ * from the server's JSON error body (e.g. `recovery_cooldown`); `message` is
+ * user-facing (cool-down copy, the server `message`, or the helper's fallback).
+ */
+export declare class PaymentsApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly until?: string;
+    constructor(message: string, opts: {
+        status: number;
+        code?: string;
+        until?: string;
+    });
+}
+
 export declare interface PaymentsConfig {
     baseUrl: string;
     /**