@movmo_app/payments 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -37,6 +37,95 @@ 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 */