@flopay/js 1.3.1 → 1.3.3

package/README.md

@@ -171,6 +171,45 @@ const result = await createCheckoutSession({
 
 Use `createCheckoutSessionWithRetries` for automatic retry with exponential backoff on timeout errors.
 
+#### Idempotent checkout creation
+
+When a secure RNG is available, every checkout-session create sends a stable
+`Idempotency-Key` header so a timeout or lost response cannot mint a second
+session. The behavior is fully additive — existing integrations need no changes:
+
+- **Automatic (default):** the SDK generates one cryptographically random,
+  high-entropy key per logical `createCheckoutSession` call and reuses it for
+  every transport retry of that same operation. Two independent calls get
+  different keys, even when their request bodies are identical. The generated
+  key is never derived from customer data and is never logged or returned.
+  Automatic generation requires a secure RNG (`crypto.randomUUID` /
+  `crypto.getRandomValues`); in an environment without one the SDK omits the
+  header rather than emit a weak key — supply a valid `idempotencyKey` yourself
+  to stay idempotent there.
+- **Merchant-supplied:** pass `idempotencyKey` to control the key yourself. It
+  is sent unchanged and reused across retries, so you can keep it stable across
+  React remounts, multiple SDK instances, or server retries you control. It
+  identifies **exactly one** logical checkout creation and must not be reused
+  for a new purchase. It must be non-empty and at most 255 characters (an
+  invalid value throws a `FloPayError('validation_error')` before any request).
+
+```ts
+// Merchant-controlled key — reused for this one logical checkout only.
+await createCheckoutSession({ /* … */ idempotencyKey: `checkout:${orderId}` });
+```
+
+`createCheckoutSessionWithRetries` resolves the key once, before its retry loop,
+so all attempts — timeouts, lost responses, and the backend's documented
+in-progress reply — replay the same key. A payload-conflict (`409`) is surfaced
+without retrying. The header is optional on the backend: older SDKs and direct
+API clients that omit it keep the legacy, unkeyed path. The same automatic and
+merchant-supplied behavior applies to inline session creation via
+`PaymentAPI.createAndFetchSession` (used by `@flopay/react`).
+
+`@flopay/shared` also exports the primitives directly if you build your own
+create flow: `generateIdempotencyKey()`, `resolveIdempotencyKey(supplied?)`,
+`IDEMPOTENCY_KEY_HEADER`, and `MAX_IDEMPOTENCY_KEY_LENGTH`.
+
 Coupon validation errors are surfaced as `FloPayError` with structured `code`:
 
 - `CouponLimitExceeded` — more than 5 coupon codes supplied (also enforced client-side before the request leaves the browser).

package/dist/index.cjs

@@ -632,6 +632,7 @@ var DEFAULT_PROCESSING_RETRY_AFTER_MS = 1e3;
 var MIN_PROCESSING_RETRY_AFTER_MS = 500;
 var DEFAULT_PROCESSING_TIMEOUT_MS = 15e3;
 var MAX_PROCESSING_RETRY_AFTER_MS = 3e3;
+var DEFAULT_ACCOUNT_SNAPSHOT_TIMEOUT_MS = 1e4;
 function isRecord(value) {
   return typeof value === "object" && value !== null;
 }
@@ -673,6 +674,7 @@ async function buildApiErrorFromResponse(response, fallbackMessage) {
   });
 }
 var NETWORK_RETRY_ATTEMPTS = 2;
+var IDEMPOTENCY_IN_PROGRESS_RETRY_ATTEMPTS = 2;
 async function fetchWithNetworkRetry(input, init, attempts = NETWORK_RETRY_ATTEMPTS) {
   let lastErr;
   for (let attempt = 0; ; attempt++) {
@@ -854,18 +856,33 @@ var PaymentAPI = class {
    * pre-pay PATCH would silently leave AVS unsent and cause an
    * AVS-protected charge to decline downstream.
    */
-  async patchAccountSnapshot(sessionId, nonce, body) {
-    const response = await fetchWithNetworkRetry(
-      `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(sessionId)}/account`,
-      {
-        method: "PATCH",
-        headers: {
-          "Content-Type": "application/json",
-          "x-checkout-session-token": nonce
-        },
-        body: JSON.stringify(body)
-      }
-    );
+  async patchAccountSnapshot(sessionId, nonce, body, options) {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_ACCOUNT_SNAPSHOT_TIMEOUT_MS;
+    const controller = new AbortController();
+    const onCallerAbort = () => controller.abort();
+    if (options?.signal) {
+      if (options.signal.aborted) controller.abort();
+      else options.signal.addEventListener("abort", onCallerAbort, { once: true });
+    }
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await fetchWithNetworkRetry(
+        `${this.baseUrl}/v1/checkouts/sessions/${encodeURIComponent(sessionId)}/account`,
+        {
+          method: "PATCH",
+          headers: {
+            "Content-Type": "application/json",
+            "x-checkout-session-token": nonce
+          },
+          body: JSON.stringify(body),
+          signal: controller.signal
+        }
+      );
+    } finally {
+      clearTimeout(timer);
+      options?.signal?.removeEventListener("abort", onCallerAbort);
+    }
     if (!response.ok) {
       throw await buildApiErrorFromResponse(response, "Failed to persist account snapshot");
     }
@@ -1004,29 +1021,41 @@ 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 fetchWithNetworkRetry(
-      `${this.baseUrl}/v1/checkouts/sessions?expand=true`,
-      {
-        method: "POST",
-        // Declare the SDK version so backends at TeamFloPay/backend#823 embed
-        // the hosted vault capture block (`body.vault`) in the response for
-        // SDKs ≥ 1.3.0. Older backends ignore the header.
-        headers: {
-          "Content-Type": "application/json",
-          [import_shared3.FLO_SDK_VERSION_HEADER]: import_shared3.SDK_VERSION
-        },
-        body: JSON.stringify(payload)
-      }
-    );
-    if (response.status === 204) {
-      throw new import_shared3.FloPayError(
-        "Session auto-completed \u2014 payment method already on file",
-        "api_error",
-        { code: "session_auto_completed" }
+    const headers = {
+      "Content-Type": "application/json",
+      // Declare the SDK version so backends at TeamFloPay/backend#823 embed
+      // the hosted vault capture block (`body.vault`) in the response for
+      // SDKs ≥ 1.3.0. Older backends ignore the header.
+      [import_shared3.FLO_SDK_VERSION_HEADER]: import_shared3.SDK_VERSION
+    };
+    const idempotencyKey = (0, import_shared3.resolveIdempotencyKey)(params.idempotencyKey);
+    if (idempotencyKey) {
+      headers[import_shared3.IDEMPOTENCY_KEY_HEADER] = idempotencyKey;
+    }
+    let response;
+    for (let attempt = 0; ; attempt++) {
+      response = await fetchWithNetworkRetry(
+        `${this.baseUrl}/v1/checkouts/sessions?expand=true`,
+        {
+          method: "POST",
+          headers,
+          body: JSON.stringify(payload)
+        }
       );
-    }
-    if (!response.ok) {
-      throw await buildApiErrorFromResponse(response, "Failed to create checkout session");
+      if (response.status === 204) {
+        throw new import_shared3.FloPayError(
+          "Session auto-completed \u2014 payment method already on file",
+          "api_error",
+          { code: "session_auto_completed" }
+        );
+      }
+      if (response.ok) break;
+      const error = await buildApiErrorFromResponse(response, "Failed to create checkout session");
+      if (error.code === import_shared3.IDEMPOTENCY_IN_PROGRESS_CODE && attempt < IDEMPOTENCY_IN_PROGRESS_RETRY_ATTEMPTS) {
+        await delay(150 * 2 ** attempt);
+        continue;
+      }
+      throw error;
     }
     const body = await response.json();
     if (body.data && "gateways" in body.data) {
@@ -1862,8 +1891,10 @@ async function createCheckoutSession(options) {
     timeoutMs = 12e3,
     clientId,
     currency,
-    utmMetadata
+    utmMetadata,
+    idempotencyKey
   } = options;
+  const resolvedIdempotencyKey = (0, import_shared7.resolveIdempotencyKey)(idempotencyKey);
   if (couponCodes.length > MAX_COUPON_CODES) {
     throw new import_shared7.FloPayError(
       `Too many coupon codes \u2014 a checkout session accepts at most ${MAX_COUPON_CODES}.`,
@@ -1912,12 +1943,16 @@ async function createCheckoutSession(options) {
   const url = `${billingApiUrl.replace(/\/+$/, "")}/v1/checkouts/sessions`;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const headers = { "Content-Type": "application/json" };
+  if (resolvedIdempotencyKey) {
+    headers[import_shared7.IDEMPOTENCY_KEY_HEADER] = resolvedIdempotencyKey;
+  }
   let status;
   let body;
   try {
     const response = await fetch(url, {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers,
       body: JSON.stringify(payload),
       signal: controller.signal
     });
@@ -1987,13 +2022,19 @@ async function createCheckoutSessionWithRetries(options) {
   if (!Number.isFinite(maxRetries) || !Number.isInteger(maxRetries) || maxRetries <= 0) {
     throw new Error("Number of retries must be greater than 0");
   }
+  const attemptOptions = {
+    ...sessionOptions,
+    idempotencyKey: (0, import_shared7.resolveIdempotencyKey)(sessionOptions.idempotencyKey)
+  };
   let lastErr;
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
-      return await createCheckoutSession(sessionOptions);
+      return await createCheckoutSession(attemptOptions);
     } catch (err) {
       lastErr = err;
-      if (err instanceof Error && err.name === "AbortError" && attempt < maxRetries) {
+      const isTransportAbort = err instanceof Error && err.name === "AbortError";
+      const isInProgressReplay = err instanceof import_shared7.FloPayError && err.code === import_shared7.IDEMPOTENCY_IN_PROGRESS_CODE;
+      if ((isTransportAbort || isInProgressReplay) && attempt < maxRetries) {
         await new Promise((r) => setTimeout(r, 100 * Math.pow(2, attempt)));
         continue;
       }