@flopay/js 1.2.1 → 1.2.4

package/README.md

@@ -103,21 +103,32 @@ import { PaymentAPI } from '@flopay/js';
 
 const api = new PaymentAPI('https://billing.example.com');
 
-// Fetch and normalize a checkout session
-const session = await api.getUnifiedCheckoutSession('session_uuid');
+// Fetch and normalize a checkout session. `nonce` is the session-bound
+// checkout token returned from session creation — required by post-#640
+// backends, which match it against `checkout_session.nonce` before returning
+// the row.
+const session = await api.getUnifiedCheckoutSession('session_uuid', sessionNonce);
 // session.provider === 'stripe' | 'chargebee' | 'recurly'
 // session.data.session contains the normalized CheckoutSession
+// session.data.session.clientSecret carries the same nonce so downstream
+// code can re-use it.
 
-// Create a PaymentIntent
+// Create a PaymentIntent — nonce becomes the `x-checkout-session-token`
+// header automatically.
 const intentResponse = await api.createPaymentIntent(
   'session_uuid',
   'user@example.com',
   'pm_xxx',
+  { nonce: sessionNonce },
 );
 
-// Process a tokenized payment
+// Process a tokenized payment. `nonce` is required: the SDK throws a
+// `FloPayError` with code `MissingCheckoutSessionToken` when it is missing,
+// and otherwise POSTs to `/v1/checkouts/sessions/<id>/process` with the
+// header set.
 const processResponse = await api.processPayment('user_id', {
   sessionId: 'session_uuid',
+  nonce: sessionNonce,
   tokenizedData: { id: 'pm_xxx', type: 'card' },
   accountData: { userId: 'user_id', email: 'user@example.com', firstName: 'John', lastName: 'Doe' },
 });
@@ -148,7 +159,13 @@ const result = await createCheckoutSession({
   cancelUrl: '/cancel',
   redirectParams: { email: 'user@example.com', bg: 'courses', mode: 'confirm' },
 });
-// On 201: browser redirects to checkout page
+// On 201: browser redirects to checkout page. The resolved
+// `CheckoutSessionResult` is `{ status: 201, redirectUrl, nonce }` — `nonce` is
+// the session-bound checkout token returned by the billing API. A matching
+// `flopay_checkout_token` cookie is written to the same parent domain as
+// `checkout_data`, so a hosted-checkout page can read the token from
+// `document.cookie` and forward it on continuation calls without having to
+// pull it from the URL (kept out of history/Referer).
 // On 204: browser redirects to successUrl (payment method on file)
 ```
 

package/dist/index.cjs

@@ -363,9 +363,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,
@@ -644,15 +646,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 fetchWithNetworkRetry(
-      `${this.baseUrl}/v1/checkouts/sessions/${checkoutSessionId}`,
+      `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(checkoutSessionId)}`,
       nonce ? { headers: { "x-checkout-session-token": nonce } } : void 0
     );
     if (!response.ok) {
@@ -707,34 +707,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 import_shared3.FloPayError(
+        "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,
@@ -747,13 +771,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
       }
@@ -895,7 +924,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;
@@ -1016,7 +1045,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" });
@@ -1354,9 +1384,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 import_shared6.FloPayError(
+        "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,
@@ -1379,11 +1417,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") {