@flopay/js 1.0.3 → 1.1.3

package/README.md

@@ -154,6 +154,27 @@ const result = await createCheckoutSession({
 
 Use `createCheckoutSessionWithRetries` for automatic retry with exponential backoff on timeout errors.
 
+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).
+- `CouponCurrencyUnsupported` — an amount-based coupon has no price for the cart currency.
+
+```ts
+import { FloPayError } from '@flopay/shared';
+
+try {
+  await createCheckoutSession({ /* … */ couponCodes });
+} catch (err) {
+  if (err instanceof FloPayError) {
+    if (err.code === 'CouponLimitExceeded') {
+      // show "Too many coupons" toast
+    } else if (err.code === 'CouponCurrencyUnsupported') {
+      // show "Coupon is not valid for this currency" toast
+    }
+  }
+}
+```
+
 ## API Reference
 
 ### Exports

package/dist/index.cjs

@@ -643,9 +643,9 @@ var PaymentAPI = class {
   /**
    * Fetch and normalize a checkout session.
    *
-   * Reads the backend's `gateway` field to determine the provider,
-   * then wraps the session in a `NormalizedCheckoutSession` for
-   * provider-agnostic consumption.
+   * Reads the backend's `gateways` map to enumerate provider-specific data,
+   * then wraps the session in a `NormalizedCheckoutSession` for provider-
+   * agnostic consumption.
    */
   async getUnifiedCheckoutSession(checkoutSessionId) {
     const res = await this.getCheckoutSession(checkoutSessionId);
@@ -656,16 +656,18 @@ var PaymentAPI = class {
    *
    * The backend will either succeed, return `type: '3ds_required'`
    * (with a `threeDSecureToken`), or return `type: 'paypal_redirect_required'`.
+   *
+   * @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) {
+  async processPayment(_userId, data, options) {
     const response = await fetch(
       `${this.baseUrl}/v1/checkouts/sessions/process`,
       {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "x-user-id": userId
-        },
+        headers: { "Content-Type": "application/json" },
         body: JSON.stringify(data)
       }
     );
@@ -742,19 +744,28 @@ var PaymentAPI = class {
    * Falls back to create + GET if the backend doesn't support `expand`.
    */
   async createAndFetchSession(params) {
+    const wireProducts = params.products ?? (0, import_shared3.foldIntoProducts)(params.items, params.subscriptions);
     const sessionCurrency = (0, import_shared3.resolveSessionCurrency)(
       params.currency,
       params.items,
-      params.subscriptions
+      params.subscriptions,
+      wireProducts
     );
+    if (!sessionCurrency) {
+      throw new import_shared3.FloPayError(
+        "currency is required: pass `currency` on the session, or include a `currency` on the first item/subscription/product.",
+        "validation_error",
+        { code: "CurrencyRequired", param: "currency" }
+      );
+    }
     const payload = {
       clientId: params.clientId,
+      checkoutVersion: import_shared3.SDK_VERSION,
       successUrl: params.successUrl,
       cancelUrl: params.cancelUrl,
       currency: sessionCurrency,
       checkoutMode: params.checkoutMode ?? "full",
-      items: (params.items ?? []).map((item) => (0, import_shared3.buildItemPayload)(item, sessionCurrency)),
-      subscriptions: (params.subscriptions ?? []).map((sub) => (0, import_shared3.buildSubscriptionPayload)(sub, sessionCurrency)),
+      products: wireProducts.map((product) => (0, import_shared3.buildProductPayload)(product, sessionCurrency)),
       accountData: {
         userId: params.account.userId,
         firstName: params.account.firstName ?? null,
@@ -796,7 +807,7 @@ var PaymentAPI = class {
       throw await buildApiErrorFromResponse(response, "Failed to create checkout session");
     }
     const body = await response.json();
-    if (body.data && "gateway" in body.data) {
+    if (body.data && "gateways" in body.data) {
       this.autoCacheDisplayData(body.data.uuid, params);
       const merged = this.mergeCachedDisplayData(body.data);
       return {
@@ -849,57 +860,57 @@ var PaymentAPI = class {
   }
   /** Normalize a raw session into a provider-agnostic shape. */
   normalizeRawSession(session) {
-    const gateway = session.gateway;
-    if (gateway === "chargebee") {
-      return {
-        provider: "chargebee",
-        mode: "tokenize",
-        data: { session: this.toCheckoutSession(session) },
-        raw: { data: session }
-      };
-    }
-    if (gateway === "stripe") {
+    const gateways = session.gateways ?? {};
+    const providers = [];
+    const data = {
+      session: this.toCheckoutSession(session)
+    };
+    const stripeGateway = gateways.stripe;
+    if (stripeGateway?.publishableKey) {
+      providers.push("stripe");
       const rawSession = session;
-      const gatewayDataRecord = session.gatewayData ?? {};
       const stripeClientSecret = [
         rawSession["stripeClientSecret"],
-        gatewayDataRecord["stripeClientSecret"],
-        gatewayDataRecord["clientSecret"]
+        stripeGateway.stripeClientSecret
       ].find((value) => typeof value === "string" && value.length > 0);
-      return {
-        provider: "stripe",
-        mode: "tokenize",
-        data: {
-          session: this.toCheckoutSession(session),
-          stripe: {
-            clientSecret: stripeClientSecret ?? "",
-            publishableKey: session.gatewayData?.publishableKey ?? void 0,
-            paypalPublishableKey: session.gatewayData?.paypalPublishableKey ?? void 0
-          }
-        },
-        raw: { data: session }
+      data.stripe = {
+        clientSecret: stripeClientSecret ?? "",
+        publishableKey: stripeGateway.publishableKey ?? void 0,
+        paypalPublishableKey: stripeGateway.paypalPublishableKey ?? void 0,
+        environment: stripeGateway.environment
+      };
+    }
+    const paypalGateway = gateways.paypal;
+    if (paypalGateway?.publishableKey) {
+      providers.push("paypal");
+      data.paypal = {
+        publishableKey: paypalGateway.publishableKey,
+        environment: paypalGateway.environment
       };
     }
     return {
-      provider: "recurly",
+      providers,
       mode: "tokenize",
-      data: { session: this.toCheckoutSession(session) },
+      data,
       raw: { data: session }
     };
   }
   /** Convert raw session to the SDK CheckoutSession shape. */
   toCheckoutSession(raw) {
-    const totalAmount = [
-      ...raw.subscriptions.map((s) => s.overrideAmount ?? s.totalAmount ?? 0),
-      ...raw.items.map((i) => i.overrideAmount ?? i.totalAmount ?? 0)
-    ].reduce((sum, val) => sum + val, 0);
+    const rawProducts = raw.products ?? [];
+    const hasBackendTotal = typeof raw.totalAmount === "number" && Number.isFinite(raw.totalAmount);
+    const computedTotal = rawProducts.reduce(
+      (sum, p) => sum + (p.overrideAmount ?? p.totalAmount ?? 0),
+      0
+    );
+    const totalAmount = hasBackendTotal ? raw.totalAmount : computedTotal;
     const amountInCents = Math.round(totalAmount * 100);
-    const currency = raw.currency ?? raw.subscriptions[0]?.currency ?? raw.items[0]?.currency ?? "USD";
+    const currency = raw.currency ?? rawProducts[0]?.currency ?? "USD";
+    const mode = rawProducts.some((p) => p.type === "subscription") ? "subscription" : "payment";
     return {
-      // Core fields (backward compat)
       id: raw.uuid,
       clientSecret: raw.nonce,
-      mode: raw.subscriptions.length > 0 ? "subscription" : "payment",
+      mode,
       status: this.toCheckoutSessionStatus(raw.status),
       amount: amountInCents,
       currency,
@@ -917,16 +928,22 @@ var PaymentAPI = class {
         line2: raw.accountData.addressLine2 ?? void 0
       },
       metadata: {},
-      // Full session data from billing API
       checkoutMode: raw.checkoutMode,
-      items: raw.items,
-      subscriptions: raw.subscriptions,
+      products: rawProducts.map((p) => ({
+        ...p,
+        totalAmount: typeof p.totalAmount === "number" ? p.totalAmount : void 0,
+        overrideAmount: typeof p.overrideAmount === "number" ? p.overrideAmount : null,
+        currency: typeof p.currency === "string" ? p.currency : void 0,
+        metadata: p.metadata ?? null
+      })),
       successUrl: raw.successUrl,
       cancelUrl: raw.cancelUrl,
       coupons: raw.coupons,
+      subtotalAmount: raw.subtotalAmount,
+      discountAmount: raw.discountAmount,
+      totalAmount: raw.totalAmount,
       createdAt: raw.createdAt,
-      gateway: raw.gateway,
-      gatewayData: raw.gatewayData,
+      gateways: raw.gateways,
       accountData: raw.accountData,
       tagsData: raw.tagsData
     };
@@ -983,70 +1000,63 @@ var PaymentAPI = class {
    * Stash the display-only fields the consumer passed into a create-session
    * call. Runs after the backend assigns a UUID so a later GET on the same
    * session (typically after a redirect) can fill in fields the backend no
-   * longer persists — `overrideAmount`, `totalAmount`, `itemName`, etc.
+   * longer persists — `overrideAmount`, `totalAmount`, `name`, etc.
    *
    * No-op when no UUID is available.
    */
   autoCacheDisplayData(sessionId, params) {
     if (!sessionId) return;
-    if (!params.items?.length && !params.subscriptions?.length && !params.currency) {
+    const products = params.products ?? (0, import_shared3.foldIntoProducts)(params.items, params.subscriptions);
+    if (products.length === 0 && !params.currency) {
       return;
     }
+    const usingUnifiedProducts = params.products !== void 0;
+    const sessionCurrency = (0, import_shared3.resolveSessionCurrency)(
+      params.currency,
+      usingUnifiedProducts ? void 0 : params.items,
+      usingUnifiedProducts ? void 0 : params.subscriptions,
+      products
+    );
     cacheSessionDisplayData(sessionId, {
-      currency: params.currency,
-      items: params.items,
-      subscriptions: params.subscriptions
+      currency: sessionCurrency ?? void 0,
+      products: products.map((p) => ({
+        code: p.code ?? p.providerItemId ?? p.providerPlanId,
+        type: p.type,
+        name: p.name ?? p.itemName ?? p.providerItemName ?? p.subscriptionName ?? p.providerPlanName ?? null,
+        totalAmount: p.totalAmount,
+        overrideAmount: p.overrideAmount,
+        currency: p.currency ?? sessionCurrency ?? void 0
+      }))
     });
   }
   /**
    * Merge cached display-only fields (set by {@link cacheSessionDisplayData})
-   * into a raw session response and mirror the new/legacy name aliases so
-   * readers using either field always get a value when one exists.
-   *
-   * Server values always win — cache fills in only where the server returned
-   * `null` / `undefined`.
+   * into a raw session response. Server values always win — cache fills in
+   * only where the server returned `null` / `undefined`.
    */
   mergeCachedDisplayData(raw) {
     const cached = getSessionDisplayData(raw.uuid);
-    const cachedItems = /* @__PURE__ */ new Map();
-    for (const item of cached?.items ?? []) {
-      const key = item.code ?? item.providerItemId;
-      if (key) cachedItems.set(key, item);
-    }
-    const cachedSubs = /* @__PURE__ */ new Map();
-    for (const sub of cached?.subscriptions ?? []) {
-      const key = sub.code ?? sub.providerPlanId;
-      if (key) cachedSubs.set(key, sub);
-    }
+    const cachedProducts = /* @__PURE__ */ new Map();
+    const productKey = (type, code) => code && type ? `${type}:${code}` : void 0;
+    for (const p of cached?.products ?? []) {
+      const key = productKey(p.type, p.code);
+      if (key) cachedProducts.set(key, p);
+    }
+    const mergedProducts = (raw.products ?? []).map((p) => {
+      const key = productKey(p.type, p.code);
+      const fallback = key ? cachedProducts.get(key) : void 0;
+      return {
+        ...p,
+        name: p.name ?? fallback?.name ?? null,
+        totalAmount: p.totalAmount ?? fallback?.totalAmount,
+        overrideAmount: p.overrideAmount ?? fallback?.overrideAmount,
+        currency: p.currency ?? fallback?.currency
+      };
+    });
     return {
       ...raw,
       currency: raw.currency ?? cached?.currency,
-      items: raw.items.map((item) => {
-        const key = item.code ?? item.providerItemId;
-        const fallback = key ? cachedItems.get(key) : void 0;
-        const resolvedName = item.itemName ?? item.providerItemName ?? fallback?.itemName ?? fallback?.providerItemName;
-        return {
-          ...item,
-          itemName: resolvedName,
-          providerItemName: resolvedName,
-          totalAmount: item.totalAmount ?? fallback?.totalAmount,
-          overrideAmount: item.overrideAmount ?? fallback?.overrideAmount,
-          currency: item.currency ?? fallback?.currency
-        };
-      }),
-      subscriptions: raw.subscriptions.map((sub) => {
-        const key = sub.code ?? sub.providerPlanId;
-        const fallback = key ? cachedSubs.get(key) : void 0;
-        const resolvedName = sub.subscriptionName ?? sub.providerPlanName ?? fallback?.subscriptionName ?? fallback?.providerPlanName;
-        return {
-          ...sub,
-          subscriptionName: resolvedName,
-          providerPlanName: resolvedName,
-          totalAmount: sub.totalAmount ?? fallback?.totalAmount,
-          overrideAmount: sub.overrideAmount ?? fallback?.overrideAmount,
-          currency: sub.currency ?? fallback?.currency
-        };
-      })
+      products: mergedProducts
     };
   }
 };
@@ -1183,12 +1193,33 @@ async function loadFloPay(publishableKey, options) {
 
 // src/create-checkout-session.ts
 var import_shared6 = require("@flopay/shared");
+var MAX_COUPON_CODES = 5;
+function readString2(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function buildCheckoutSessionError(status, payload) {
+  const nested = payload?.error;
+  const code = readString2(payload?.code) ?? readString2(nested?.code) ?? `http_${status}`;
+  const message = readString2(payload?.message) ?? readString2(nested?.message) ?? defaultMessageForCode(code, status);
+  return new import_shared6.FloPayError(message, "api_error", { code, statusCode: status });
+}
+function defaultMessageForCode(code, status) {
+  switch (code) {
+    case "CouponLimitExceeded":
+      return `Too many coupon codes \u2014 a checkout session accepts at most ${MAX_COUPON_CODES}.`;
+    case "CouponCurrencyUnsupported":
+      return "One of the applied coupons has no price configured for the cart currency.";
+    default:
+      return `Failed to create checkout session (HTTP ${status}).`;
+  }
+}
 async function createCheckoutSession(options) {
   const {
     billingApiUrl,
     checkoutBaseUrl,
     items = [],
     subscriptions = [],
+    products,
     account,
     successUrl,
     cancelUrl,
@@ -1202,15 +1233,30 @@ async function createCheckoutSession(options) {
     currency,
     utmMetadata
   } = options;
-  const sessionCurrency = (0, import_shared6.resolveSessionCurrency)(currency, items, subscriptions);
+  if (couponCodes.length > MAX_COUPON_CODES) {
+    throw new import_shared6.FloPayError(
+      `Too many coupon codes \u2014 a checkout session accepts at most ${MAX_COUPON_CODES}.`,
+      "validation_error",
+      { code: "CouponLimitExceeded", param: "couponCodes" }
+    );
+  }
+  const wireProducts = products ?? (0, import_shared6.foldIntoProducts)(items, subscriptions);
+  const sessionCurrency = (0, import_shared6.resolveSessionCurrency)(currency, items, subscriptions, wireProducts);
+  if (!sessionCurrency) {
+    throw new import_shared6.FloPayError(
+      "currency is required: pass `currency` on the session, or include a `currency` on the first item/subscription/product.",
+      "validation_error",
+      { code: "CurrencyRequired", param: "currency" }
+    );
+  }
   const payload = {
     clientId,
+    checkoutVersion: import_shared6.SDK_VERSION,
     successUrl,
     cancelUrl,
     currency: sessionCurrency,
     checkoutMode,
-    items: items.map((item) => (0, import_shared6.buildItemPayload)(item, sessionCurrency)),
-    subscriptions: subscriptions.map((sub) => (0, import_shared6.buildSubscriptionPayload)(sub, sessionCurrency)),
+    products: wireProducts.map((product) => (0, import_shared6.buildProductPayload)(product, sessionCurrency)),
     accountData: {
       userId: account.userId,
       firstName: account.firstName ?? null,
@@ -1252,16 +1298,25 @@ async function createCheckoutSession(options) {
   } finally {
     clearTimeout(timer);
   }
+  if (status >= 400) {
+    throw buildCheckoutSessionError(status, body);
+  }
   if (status === 201) {
     const uuid = body?.data?.uuid;
     if (!uuid) {
       throw new Error("Checkout session created but no UUID was returned by the billing API");
     }
-    if (items.length || subscriptions.length || currency) {
+    if (wireProducts.length || sessionCurrency) {
       cacheSessionDisplayData(uuid, {
-        currency,
-        items,
-        subscriptions
+        currency: sessionCurrency,
+        products: wireProducts.map((p) => ({
+          code: p.code ?? p.providerItemId ?? p.providerPlanId,
+          type: p.type,
+          name: p.name ?? p.itemName ?? p.providerItemName ?? p.subscriptionName ?? p.providerPlanName ?? null,
+          totalAmount: p.totalAmount,
+          overrideAmount: p.overrideAmount,
+          currency: p.currency ?? sessionCurrency
+        }))
       });
     }
     const redirectUrl = new URL(`${checkoutBaseUrl.replace(/\/+$/, "")}/secure`);