@flopay/js 1.1.0 → 1.1.3

package/dist/index.d.ts

@@ -167,30 +167,14 @@ declare class StripeAdapter implements PaymentProviderAdapter {
  * Values from the server response always win — cached values fill in only
  * where the server returned `null` or `undefined`.
  */
-/** Display-only fields per item that can be cached and merged back later. */
-interface SessionDisplayItem {
-    /** Catalog code (preferred match key). */
+/** Display-only fields per product that can be cached and merged back later. */
+interface SessionDisplayProduct {
+    /** Catalog code (match key). */
     code?: string;
-    /** @deprecated Match key fallback when `code` is not provided. */
-    providerItemId?: string;
-    /** Display-only name for the item. Takes priority over `providerItemName`. */
-    itemName?: string | null;
-    /** @deprecated Use `itemName`. */
-    providerItemName?: string | null;
-    totalAmount?: number;
-    overrideAmount?: number | null;
-    currency?: string;
-}
-/** Display-only fields per subscription that can be cached and merged back later. */
-interface SessionDisplaySubscription {
-    /** Catalog code (preferred match key). */
-    code?: string;
-    /** @deprecated Match key fallback when `code` is not provided. */
-    providerPlanId?: string;
-    /** Display-only name for the subscription plan. Takes priority over `providerPlanName`. */
-    subscriptionName?: string | null;
-    /** @deprecated Use `subscriptionName`. */
-    providerPlanName?: string | null;
+    /** Whether this product is a one-time item or a recurring subscription. */
+    type?: 'item' | 'subscription';
+    /** Display-only name for the product. */
+    name?: string | null;
     totalAmount?: number;
     overrideAmount?: number | null;
     currency?: string;
@@ -199,8 +183,7 @@ interface SessionDisplaySubscription {
 interface SessionDisplayCacheData {
     /** Session-level currency (falls into the response only when the server omits it). */
     currency?: string;
-    items?: SessionDisplayItem[];
-    subscriptions?: SessionDisplaySubscription[];
+    products?: SessionDisplayProduct[];
 }
 /**
  * Stash display-only data for a session. Called client-side right after the
@@ -232,57 +215,35 @@ interface RawCheckoutSession {
     status: 'pending' | 'completed' | 'expired';
     successUrl: string;
     cancelUrl: string;
-    /** Session-level currency. Takes precedence over per-item/per-subscription currency. */
+    /** Session-level currency. */
     currency?: string;
     createdAt?: string;
     checkoutUrl?: string;
-    items: Array<{
-        uuid: string;
-        checkoutSessionId: string;
-        /** Preferred catalog code. Falls back to the deprecated `providerItemId`. */
-        code?: string;
-        /** @deprecated Use `code`. */
-        providerItemId?: string;
-        /** Display-only name. Preferred over `providerItemName`. */
-        itemName?: string | null;
-        /** @deprecated Use `itemName`. Mirrored for backward compatibility. */
-        providerItemName?: string | null;
-        /** Display-only description from the catalog. */
-        providerItemDescription?: string | null;
-        quantity: number;
-        /** @deprecated Removed from the backend — resolved from the catalog. */
-        totalAmount?: number;
-        /** @deprecated Removed from the backend entirely. */
-        overrideAmount?: number | null;
-        /** @deprecated Use the session-level `currency`. */
-        currency?: string;
-        metadata?: Record<string, unknown> | null;
-    }>;
-    subscriptions: Array<{
+    /** Unified products list returned by the billing API (post-#760). */
+    products?: Array<{
         uuid: string;
         checkoutSessionId: string;
-        /** Preferred catalog code. Falls back to the deprecated `providerPlanId`. */
+        /** 'item' or 'subscription'. */
+        type: 'item' | 'subscription';
         code?: string;
-        /** @deprecated Use `code`. */
-        providerPlanId?: string;
-        /** Display-only name. Preferred over `providerPlanName`. */
-        subscriptionName?: string | null;
-        /** @deprecated Use `subscriptionName`. Mirrored for backward compatibility. */
-        providerPlanName?: string | null;
-        /** Display-only description from the catalog. */
-        providerPlanDescription?: string | null;
+        name?: string | null;
+        description?: string | null;
         quantity: number;
-        /** @deprecated Removed from the backend — resolved from the catalog. */
         totalAmount?: number;
-        /** @deprecated Removed from the backend entirely. */
         overrideAmount?: number | null;
-        /** @deprecated Use the session-level `currency`. */
         currency?: string;
-        /** @deprecated Removed from the backend. Checkouts only create new subscriptions. */
-        isUpdate?: boolean;
         metadata?: Record<string, unknown> | null;
     }>;
     coupons?: string[];
+    /**
+     * Pre-discount total in cart-currency major units. Populated by billing
+     * API ≥ v1.1.2; absent on older backends.
+     */
+    subtotalAmount?: number;
+    /** Total reduction from applied coupons (cart-currency major units). */
+    discountAmount?: number;
+    /** Final charge amount after coupon discount (cart-currency major units). */
+    totalAmount?: number;
     checkoutMode?: 'full' | 'auto' | 'confirm';
     gateways?: CheckoutGateways;
     accountData: {
@@ -421,18 +382,15 @@ declare class PaymentAPI {
      * 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.
      */
     private autoCacheDisplayData;
     /**
      * 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`.
      */
     private mergeCachedDisplayData;
 }
@@ -478,4 +436,4 @@ declare function createCheckoutSessionWithRetries(options: CreateSessionParams &
     maxRetries?: number;
 }): Promise<CheckoutSessionResult>;
 
-export { FloPay, FloPayElements, PaymentAPI, type SessionDisplayCacheData, type SessionDisplayItem, type SessionDisplaySubscription, StripeAdapter, cacheSessionDisplayData, clearSessionDisplayData, createCheckoutSession, createCheckoutSessionWithRetries, getSessionDisplayData, loadFloPay };
+export { FloPay, FloPayElements, PaymentAPI, type SessionDisplayCacheData, type SessionDisplayProduct, StripeAdapter, cacheSessionDisplayData, clearSessionDisplayData, createCheckoutSession, createCheckoutSessionWithRetries, getSessionDisplayData, loadFloPay };

package/dist/index.mjs

@@ -449,8 +449,9 @@ var FloPayElements = class {
 // src/payment-api.ts
 import {
   FloPayError as FloPayError3,
-  buildItemPayload,
-  buildSubscriptionPayload,
+  SDK_VERSION,
+  buildProductPayload,
+  foldIntoProducts,
   resolveSessionCurrency
 } from "@flopay/shared";
 
@@ -704,19 +705,28 @@ var PaymentAPI = class {
    * Falls back to create + GET if the backend doesn't support `expand`.
    */
   async createAndFetchSession(params) {
+    const wireProducts = params.products ?? foldIntoProducts(params.items, params.subscriptions);
     const sessionCurrency = resolveSessionCurrency(
       params.currency,
       params.items,
-      params.subscriptions
+      params.subscriptions,
+      wireProducts
     );
+    if (!sessionCurrency) {
+      throw new FloPayError3(
+        "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: SDK_VERSION,
       successUrl: params.successUrl,
       cancelUrl: params.cancelUrl,
       currency: sessionCurrency,
       checkoutMode: params.checkoutMode ?? "full",
-      items: (params.items ?? []).map((item) => buildItemPayload(item, sessionCurrency)),
-      subscriptions: (params.subscriptions ?? []).map((sub) => buildSubscriptionPayload(sub, sessionCurrency)),
+      products: wireProducts.map((product) => buildProductPayload(product, sessionCurrency)),
       accountData: {
         userId: params.account.userId,
         firstName: params.account.firstName ?? null,
@@ -848,17 +858,20 @@ var PaymentAPI = class {
   }
   /** 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,
@@ -876,13 +889,20 @@ 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,
       gateways: raw.gateways,
       accountData: raw.accountData,
@@ -941,70 +961,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 ?? foldIntoProducts(params.items, params.subscriptions);
+    if (products.length === 0 && !params.currency) {
       return;
     }
+    const usingUnifiedProducts = params.products !== void 0;
+    const sessionCurrency = 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
     };
   }
 };
@@ -1141,16 +1154,39 @@ async function loadFloPay(publishableKey, options) {
 
 // src/create-checkout-session.ts
 import {
-  buildItemPayload as buildItemPayload2,
-  buildSubscriptionPayload as buildSubscriptionPayload2,
+  FloPayError as FloPayError6,
+  SDK_VERSION as SDK_VERSION2,
+  buildProductPayload as buildProductPayload2,
+  foldIntoProducts as foldIntoProducts2,
   resolveSessionCurrency as resolveSessionCurrency2
 } from "@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 FloPayError6(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,
@@ -1164,15 +1200,30 @@ async function createCheckoutSession(options) {
     currency,
     utmMetadata
   } = options;
-  const sessionCurrency = resolveSessionCurrency2(currency, items, subscriptions);
+  if (couponCodes.length > MAX_COUPON_CODES) {
+    throw new FloPayError6(
+      `Too many coupon codes \u2014 a checkout session accepts at most ${MAX_COUPON_CODES}.`,
+      "validation_error",
+      { code: "CouponLimitExceeded", param: "couponCodes" }
+    );
+  }
+  const wireProducts = products ?? foldIntoProducts2(items, subscriptions);
+  const sessionCurrency = resolveSessionCurrency2(currency, items, subscriptions, wireProducts);
+  if (!sessionCurrency) {
+    throw new FloPayError6(
+      "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: SDK_VERSION2,
     successUrl,
     cancelUrl,
     currency: sessionCurrency,
     checkoutMode,
-    items: items.map((item) => buildItemPayload2(item, sessionCurrency)),
-    subscriptions: subscriptions.map((sub) => buildSubscriptionPayload2(sub, sessionCurrency)),
+    products: wireProducts.map((product) => buildProductPayload2(product, sessionCurrency)),
     accountData: {
       userId: account.userId,
       firstName: account.firstName ?? null,
@@ -1214,16 +1265,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`);