@flopay/js 1.2.0 → 1.2.4

package/dist/index.d.ts

@@ -64,6 +64,12 @@ declare class FloPay {
         sessionId: string;
         email: string;
         returnUrl: string;
+        /**
+         * Session-bound checkout token. Forwarded as `x-checkout-session-token`
+         * on the internal `POST /v1/checkouts/payments/intents` call so post-#640
+         * backends don't reject the round-trip with a 401.
+         */
+        nonce?: string;
     }): Promise<ConfirmCardPaymentResult>;
     /** Resume a PayPal payment after redirect return. Returns null if no PayPal params in URL. */
     resumePayPalPayment(): Promise<ConfirmCardPaymentResult | null>;
@@ -148,6 +154,7 @@ declare class StripeAdapter implements PaymentProviderAdapter {
         sessionId: string;
         email: string;
         returnUrl: string;
+        nonce?: string;
     }): Promise<ConfirmCardPaymentResult>;
     resumePayPalPayment(): Promise<ConfirmCardPaymentResult | null>;
     getRawProvider(): unknown;
@@ -281,11 +288,9 @@ declare class PaymentAPI {
      *
      * `nonce` is the session-bound checkout token returned when the session
      * was created. When supplied it is sent as the `x-checkout-session-token`
-     * header — the same token the backend already validates on session-scoped
-     * mutations (e.g. the payment-intent-decline endpoint). Sending it on the
-     * GET is forward-compatible with TeamFloPay/backend#640, which tightens
-     * session reads so the UUID alone is no longer sufficient to fetch a
-     * session. Backends that don't yet enforce it ignore the extra header.
+     * header that post-#640 backends match against `checkout_session.nonce`
+     * before returning the row — the UUID alone is no longer sufficient.
+     * Backends that don't yet enforce it ignore the extra header.
      */
     getCheckoutSession(checkoutSessionId: string, nonce?: string): Promise<BillingResponse<RawCheckoutSession>>;
     /**
@@ -329,6 +334,12 @@ declare class PaymentAPI {
      * The backend will either succeed, return `type: '3ds_required'`
      * (with a `threeDSecureToken`), or return `type: 'paypal_redirect_required'`.
      *
+     * Hits the session-scoped route `POST /v1/checkouts/sessions/:id/process`
+     * and forwards `data.nonce` as `x-checkout-session-token`. Backend
+     * `TeamFloPay/backend#640` rejects callers without a matching nonce with a
+     * 401 — this method throws synchronously when `data.nonce` is missing so the
+     * problem surfaces before the network round trip.
+     *
      * @param userId Vestigial — backend's GatewayInterceptor routes via session,
      *   not headers, so this value is no longer sent on the wire. Kept in the
      *   signature for back-compat with existing callers; will be removed in a
@@ -342,16 +353,26 @@ declare class PaymentAPI {
      *
      * Used by the Stripe flow to create a server-side PaymentIntent
      * with the client's payment method attached.
+     *
+     * Forwards `options.nonce` as `x-checkout-session-token` when supplied — the
+     * session-bound checkout token returned by session creation. Post-#640
+     * backends reject this call with a 401 when the header is missing or does
+     * not match the session's stored nonce.
      */
     createPaymentIntent(sessionId: string, email: string, paymentMethodType: string, options?: {
         signal?: AbortSignal;
         isPaypal?: string;
+        nonce?: string;
     }): Promise<Response>;
     /**
      * Create a SetupIntent for saving payment methods.
+     *
+     * Forwards `options.nonce` as `x-checkout-session-token` when supplied —
+     * required by post-#640 backends, ignored by earlier versions.
      */
     createSetupIntent(sessionId: string, email: string, paymentMethodType: 'card' | 'google_pay' | 'apple_pay' | 'paypal_express_checkout', options?: {
         signal?: AbortSignal;
+        nonce?: string;
     }): Promise<Response>;
     /**
      * Fetch user's prior payments by email.
@@ -380,6 +401,11 @@ declare class PaymentAPI {
     waitForCheckoutSessionCompletion(checkoutSessionId: string, options?: {
         initialDelayMs?: number;
         timeoutMs?: number;
+        /**
+         * Session-bound checkout token; forwarded on the poll's
+         * `GET /v1/checkouts/sessions/:id`. Required by post-#640 backends.
+         */
+        nonce?: string;
     }): Promise<NormalizedCheckoutSession>;
     /** Normalize a raw session into a provider-agnostic shape. */
     private normalizeRawSession;

package/dist/index.mjs

@@ -318,9 +318,11 @@ var StripeAdapter = class {
         };
       }
     }
+    const intentHeaders = { "Content-Type": "application/json" };
+    if (params.nonce) intentHeaders["x-checkout-session-token"] = params.nonce;
     const intentResponse = await fetch(`${baseUrl}/v1/checkouts/payments/intents`, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: intentHeaders,
       body: JSON.stringify({
         sessionId: params.sessionId,
         email: params.email,
@@ -582,6 +584,20 @@ async function buildApiErrorFromResponse(response, fallbackMessage) {
     statusCode: response.status
   });
 }
+var NETWORK_RETRY_ATTEMPTS = 2;
+async function fetchWithNetworkRetry(input, init, attempts = NETWORK_RETRY_ATTEMPTS) {
+  let lastErr;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fetch(input, init);
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") throw err;
+      lastErr = err;
+      if (attempt >= attempts) throw lastErr;
+      await delay(150 * 2 ** attempt);
+    }
+  }
+}
 var PaymentAPI = class {
   constructor(billingApiUrl) {
     this.baseUrl = billingApiUrl.replace(/\/+$/, "");
@@ -591,15 +607,13 @@ var PaymentAPI = class {
    *
    * `nonce` is the session-bound checkout token returned when the session
    * was created. When supplied it is sent as the `x-checkout-session-token`
-   * header — the same token the backend already validates on session-scoped
-   * mutations (e.g. the payment-intent-decline endpoint). Sending it on the
-   * GET is forward-compatible with TeamFloPay/backend#640, which tightens
-   * session reads so the UUID alone is no longer sufficient to fetch a
-   * session. Backends that don't yet enforce it ignore the extra header.
+   * header that post-#640 backends match against `checkout_session.nonce`
+   * before returning the row — the UUID alone is no longer sufficient.
+   * Backends that don't yet enforce it ignore the extra header.
    */
   async getCheckoutSession(checkoutSessionId, nonce) {
-    const response = await fetch(
-      `${this.baseUrl}/v1/checkouts/sessions/${checkoutSessionId}`,
+    const response = await fetchWithNetworkRetry(
+      `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(checkoutSessionId)}`,
       nonce ? { headers: { "x-checkout-session-token": nonce } } : void 0
     );
     if (!response.ok) {
@@ -654,34 +668,58 @@ var PaymentAPI = class {
    * The backend will either succeed, return `type: '3ds_required'`
    * (with a `threeDSecureToken`), or return `type: 'paypal_redirect_required'`.
    *
+   * Hits the session-scoped route `POST /v1/checkouts/sessions/:id/process`
+   * and forwards `data.nonce` as `x-checkout-session-token`. Backend
+   * `TeamFloPay/backend#640` rejects callers without a matching nonce with a
+   * 401 — this method throws synchronously when `data.nonce` is missing so the
+   * problem surfaces before the network round trip.
+   *
    * @param userId Vestigial — backend's GatewayInterceptor routes via session,
    *   not headers, so this value is no longer sent on the wire. Kept in the
    *   signature for back-compat with existing callers; will be removed in a
    *   future major version.
    */
   async processPayment(_userId, data, options) {
+    if (!data.nonce) {
+      throw new FloPayError3(
+        "processPayment requires `nonce` \u2014 pass the value returned from session creation.",
+        "validation_error",
+        { code: "MissingCheckoutSessionToken", param: "nonce" }
+      );
+    }
+    const { nonce, ...processBody } = data;
     const response = await fetch(
-      `${this.baseUrl}/v1/checkouts/sessions/process`,
+      `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(data.sessionId)}/process`,
       {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(data)
+        headers: {
+          "Content-Type": "application/json",
+          "x-checkout-session-token": nonce
+        },
+        body: JSON.stringify(processBody)
       }
     );
-    return this.resolveProcessResponse(response, data.sessionId, options);
+    return this.resolveProcessResponse(response, data.sessionId, { ...options, nonce });
   }
   /**
    * Create a PaymentIntent on the backend.
    *
    * Used by the Stripe flow to create a server-side PaymentIntent
    * with the client's payment method attached.
+   *
+   * Forwards `options.nonce` as `x-checkout-session-token` when supplied — the
+   * session-bound checkout token returned by session creation. Post-#640
+   * backends reject this call with a 401 when the header is missing or does
+   * not match the session's stored nonce.
    */
   async createPaymentIntent(sessionId, email, paymentMethodType, options) {
+    const headers = { "Content-Type": "application/json" };
+    if (options?.nonce) headers["x-checkout-session-token"] = options.nonce;
     return fetch(
       `${this.baseUrl}/v1/checkouts/payments/intents`,
       {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
+        headers,
         body: JSON.stringify({
           sessionId,
           email,
@@ -694,13 +732,18 @@ var PaymentAPI = class {
   }
   /**
    * Create a SetupIntent for saving payment methods.
+   *
+   * Forwards `options.nonce` as `x-checkout-session-token` when supplied —
+   * required by post-#640 backends, ignored by earlier versions.
    */
   async createSetupIntent(sessionId, email, paymentMethodType, options) {
+    const headers = { "Content-Type": "application/json" };
+    if (options?.nonce) headers["x-checkout-session-token"] = options.nonce;
     return fetch(
       `${this.baseUrl}/v1/checkouts/payments/setup-intents`,
       {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
+        headers,
         body: JSON.stringify({ sessionId, email, paymentMethodType }),
         signal: options?.signal
       }
@@ -785,7 +828,7 @@ var PaymentAPI = class {
     if (params.checkoutType) payload["checkoutType"] = params.checkoutType;
     if (params.checkoutLayout) payload["checkoutLayout"] = params.checkoutLayout;
     if (params.avsConfig) payload["avsConfig"] = params.avsConfig;
-    const response = await fetch(
+    const response = await fetchWithNetworkRetry(
       `${this.baseUrl}/v1/checkouts/sessions?expand=true`,
       {
         method: "POST",
@@ -842,7 +885,7 @@ var PaymentAPI = class {
           throw createCheckoutProcessingTimeoutError();
         }
       }
-      const session = await this.getUnifiedCheckoutSession(checkoutSessionId);
+      const session = await this.getUnifiedCheckoutSession(checkoutSessionId, options?.nonce);
       const status = session.data.session?.status;
       if (status === "complete" || status === "expired") {
         return session;
@@ -963,7 +1006,8 @@ var PaymentAPI = class {
     const pending = this.toCheckoutProcessingPending(payload, response, checkoutSessionId);
     const session = await this.waitForCheckoutSessionCompletion(pending.sessionId, {
       initialDelayMs: pending.retryAfterMs,
-      timeoutMs: options?.pollTimeoutMs
+      timeoutMs: options?.pollTimeoutMs,
+      nonce: options?.nonce
     });
     if (session.data.session?.status === "complete") {
       return new Response(null, { status: 204, statusText: "No Content" });
@@ -1307,9 +1351,17 @@ async function createCheckoutSession(options) {
   }
   if (status === 201) {
     const uuid = body?.data?.uuid;
+    const nonce = body?.data?.nonce;
     if (!uuid) {
       throw new Error("Checkout session created but no UUID was returned by the billing API");
     }
+    if (!nonce) {
+      throw new FloPayError6(
+        "Checkout session created but no `nonce` was returned by the billing API. Upgrade the billing service to TeamFloPay/backend#640 or later.",
+        "api_error",
+        { code: "MissingCheckoutSessionToken" }
+      );
+    }
     if (wireProducts.length || sessionCurrency) {
       cacheSessionDisplayData(uuid, {
         currency: sessionCurrency,
@@ -1332,11 +1384,12 @@ async function createCheckoutSession(options) {
       const checkoutData = JSON.stringify({ origin_url: cancelUrl });
       const domain = window.location.hostname.split(".").slice(-2).join(".");
       document.cookie = `checkout_data=${encodeURIComponent(checkoutData)}; domain=.${domain}; path=/; max-age=3600; SameSite=Lax; Secure;`;
+      document.cookie = `flopay_checkout_token=${encodeURIComponent(nonce)}; domain=.${domain}; path=/; max-age=3600; SameSite=Lax; Secure;`;
     }
     if (typeof window !== "undefined") {
       window.location.href = redirectUrl.toString();
     }
-    return { status: 201, redirectUrl: redirectUrl.toString() };
+    return { status: 201, redirectUrl: redirectUrl.toString(), nonce };
   }
   if (status === 204) {
     if (typeof window !== "undefined") {