@movmo_app/payments 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -37,6 +37,103 @@ 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;
+}
+
+/**
+ * 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
+ * editable field set grows — shared by the modal, the manager, and
+ * `useUpdatePaymentMethod` so the patch shape isn't restated in three places.
+ */
+declare type EditablePaymentMethodFields = Pick<UpdatePaymentMethodPatch, 'cardholderName' | 'zip'>;
+
 export declare const getPaymentsConfig: () => InternalPaymentsConfig;
 
 /* Excluded from this release type: InternalPaymentsConfig */
@@ -207,6 +304,22 @@ export declare interface PaymentMethodSummary {
     expMonth: number;
     expYear: number;
     isDefault: boolean;
+    /**
+     * Which vault the row lives in. monolith-api returns this on every row
+     * post-MOVMO-381. Only `'spreedly'` rows accept cardholder/zip metadata
+     * edits — Stripe rows are immutable on those fields and the backend rejects
+     * the patch (4xx). The Edit menu item in PaymentMethodsManager is gated on
+     * this value.
+     *
+     * Optional so the UI doesn't crash on pre-MOVMO-381 monolith deployments
+     * that haven't shipped the new field yet — those rows behave as if
+     * Edit isn't available.
+     */
+    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. */
+    zip?: string;
 }
 
 export declare interface PaymentsConfig {
@@ -230,6 +343,14 @@ export declare interface PaymentsConfig {
 
 export declare const setPaymentsConfig: (config: Partial<PaymentsConfig>) => void;
 
+export declare interface UpdatePaymentMethodPatch {
+    isDefault?: boolean;
+    /** MOVMO-381 — editable on Spreedly rows only; monolith-api rejects (4xx) Stripe rows. */
+    cardholderName?: string;
+    /** MOVMO-381 — editable on Spreedly rows only; monolith-api rejects (4xx) Stripe rows. */
+    zip?: string;
+}
+
 /**
  * Calls `DELETE /v1/users/:userId/payment-methods/:methodId`.
  *
@@ -318,6 +439,27 @@ export declare interface UseSetDefaultPaymentMethodResult {
 
 export declare type UseSetDefaultPaymentMethodStatus = 'idle' | 'pending' | 'error';
 
+/**
+ * Calls `PUT /v1/users/:userId/payment-methods/:methodId` with the
+ * cardholder-name + zip subset (MOVMO-381). The backend forwards to Spreedly
+ * for vault-backed rows and rejects the request (4xx) for Stripe-backed rows;
+ * the resulting `Error` carries the server's message so callers can surface it
+ * in the modal.
+ *
+ * Follows the same idle→pending→idle/error contract as
+ * `useSetDefaultPaymentMethod` (throws on failure so optimistic-update
+ * consumers can roll back), with a `(methodId, patch)` signature.
+ */
+export declare const useUpdatePaymentMethod: (userId: string) => UseUpdatePaymentMethodResult;
+
+export declare interface UseUpdatePaymentMethodResult {
+    updatePaymentMethod: (methodId: string, patch: EditablePaymentMethodFields) => Promise<void>;
+    status: UseUpdatePaymentMethodStatus;
+    error: string | null;
+}
+
+export declare type UseUpdatePaymentMethodStatus = 'idle' | 'pending' | 'error';
+
 /**
  * Fetches a user's saved payment methods from monolith-api.
  *