@flopay/shared 1.0.3 → 1.1.3

package/dist/index.d.ts

@@ -160,62 +160,84 @@ interface LineItem {
 }
 /** Checkout mode controlling the payment UI behavior. */
 type CheckoutMode = 'full' | 'auto' | 'confirm';
-/** A one-time item from a checkout session response. */
-interface CheckoutSessionItem {
+/**
+ * Discriminator describing whether a checkout product is a one-time item or a
+ * recurring subscription. Mirrors the backend's `ProductTypeEnum`.
+ */
+type CheckoutProductType = 'item' | 'subscription';
+/** Unified checkout product from a session response. */
+interface CheckoutSessionProduct {
     uuid: string;
     checkoutSessionId: string;
-    /** Preferred catalog code for the item. */
+    /** Whether this product is a one-time item or a recurring subscription. */
+    type: CheckoutProductType;
+    /** Preferred catalog code for the product. */
     code?: string;
-    /** @deprecated Use {@link CheckoutSessionItem.code}. Backend may stop returning this in a future major. */
-    providerItemId?: string;
     /**
-     * Display-only name for the item. Preferred over `providerItemName`.
-     * The backend no longer persists names; the SDK populates this from the
-     * client-side display cache when the server response omits it.
+     * Display-only name. Resolved from the catalog server-side; the SDK
+     * populates this from the client-side display cache when missing.
      */
-    itemName?: string | null;
-    /** @deprecated Use {@link CheckoutSessionItem.itemName}. Mirrored from `itemName` for backward compatibility. */
-    providerItemName?: string | null;
-    /** Display-only. Resolved from the catalog server-side; not part of the persisted session. */
-    providerItemDescription?: string | null;
+    name?: string | null;
+    /** Display-only description from the catalog. */
+    description?: string | null;
     quantity: number;
-    /** Display-only. Backend no longer persists this; the SDK populates it from the client-side cache (set via `paymentAPI.cacheSessionDisplayData`) when missing from the server response. */
+    /** Display-only. Populated from cache when the server omits it. */
     totalAmount?: number;
-    /** Display-only. Backend no longer persists this; the SDK populates it from the client-side cache (set via `paymentAPI.cacheSessionDisplayData`) when missing from the server response. */
+    /** Display-only. Populated from cache when the server omits it. */
     overrideAmount?: number | null;
-    /** @deprecated Prefer the session-level `currency` on {@link CheckoutSession}. Kept for backward compatibility and populated from cache when the server omits it. */
+    /** @deprecated Prefer the session-level `currency` on {@link CheckoutSession}. */
     currency?: string;
     metadata?: Record<string, unknown> | null;
 }
-/** A subscription plan from a checkout session response. */
-interface CheckoutSessionSubscription {
-    uuid: string;
-    checkoutSessionId: string;
-    /** Preferred catalog code for the subscription plan. */
-    code?: string;
-    /** @deprecated Use {@link CheckoutSessionSubscription.code}. Backend may stop returning this in a future major. */
-    providerPlanId?: string;
+/**
+ * Environment for an upstream gateway. Accepts both the gateway-native values
+ * (`'sandbox'` | `'live'`) and FloPay's internal aliases (`'stage'` |
+ * `'production'`) so the same string can flow from the billing API straight
+ * to gateway SDKs without translation at every call site. Use
+ * {@link normalizeGatewayEnvironment} to collapse to the canonical pair
+ * before handing the value to a gateway SDK.
+ */
+type GatewayEnvironment = 'sandbox' | 'live' | 'stage' | 'production';
+/** Canonical gateway-native form returned by {@link normalizeGatewayEnvironment}. */
+type NormalizedGatewayEnvironment = 'sandbox' | 'live';
+/**
+ * Map FloPay's environment aliases to the gateway-native `'sandbox'`/`'live'`
+ * pair. `'stage'` → `'sandbox'`, `'production'` → `'live'`. Returns `undefined`
+ * for `undefined` input and logs a console warning for unrecognized strings
+ * (so misconfiguration surfaces immediately instead of hanging later — most
+ * gateway SDKs silently fall back to live endpoints on an unknown env, which
+ * then fails opaquely against sandbox credentials).
+ */
+declare function normalizeGatewayEnvironment(env: GatewayEnvironment | string | undefined | null): NormalizedGatewayEnvironment | undefined;
+/** Per-gateway configuration returned by the billing API. */
+interface CheckoutGateway {
+    /** Public client identifier (e.g. Stripe publishable key, PayPal client id). */
+    publishableKey?: string | null;
+    /** Sandbox or live mode for the gateway credentials. */
+    environment?: GatewayEnvironment;
     /**
-     * Display-only name for the subscription plan. Preferred over
-     * `providerPlanName`. The backend no longer persists names; the SDK
-     * populates this from the client-side display cache when the server
-     * response omits it.
+     * Optional Stripe PaymentIntent client secret exposed by the billing API
+     * when additional authentication is required for a saved payment method.
+     * Stripe-specific.
      */
-    subscriptionName?: string | null;
-    /** @deprecated Use {@link CheckoutSessionSubscription.subscriptionName}. Mirrored from `subscriptionName` for backward compatibility. */
-    providerPlanName?: string | null;
-    /** Display-only. Resolved from the catalog server-side; not part of the persisted session. */
-    providerPlanDescription?: string | null;
-    quantity: number;
-    /** Display-only. Backend no longer persists this; the SDK populates it from the client-side cache (set via `paymentAPI.cacheSessionDisplayData`) when missing from the server response. */
-    totalAmount?: number;
-    /** Display-only. Backend no longer persists this; the SDK populates it from the client-side cache (set via `paymentAPI.cacheSessionDisplayData`) when missing from the server response. */
-    overrideAmount?: number | null;
-    /** @deprecated Prefer the session-level `currency` on {@link CheckoutSession}. Kept for backward compatibility and populated from cache when the server omits it. */
-    currency?: string;
-    /** @deprecated Removed from backend. Checkouts only create new subscriptions. */
-    isUpdate?: boolean;
-    metadata?: Record<string, unknown> | null;
+    stripeClientSecret?: string | null;
+    /**
+     * Optional publishable key for a dedicated Stripe sub-account that renders
+     * PayPal via Stripe Elements. Stripe-specific. Distinct from
+     * `gateways.paypal.publishableKey`, which is a PayPal client id used by the
+     * direct PayPal SDK.
+     */
+    paypalPublishableKey?: string | null;
+}
+/**
+ * Map of gateways attached to a session, keyed by gateway code. A session can
+ * advertise multiple gateways concurrently — e.g. `gateways.stripe` for card
+ * + wallets and `gateways.paypal` for direct PayPal rendering.
+ */
+interface CheckoutGateways {
+    stripe?: CheckoutGateway;
+    paypal?: CheckoutGateway;
+    [key: string]: CheckoutGateway | undefined;
 }
 /** Represents a FloPay checkout session. */
 interface CheckoutSession {
@@ -229,27 +251,35 @@ interface CheckoutSession {
     customer?: Customer;
     metadata?: Record<string, string>;
     checkoutMode?: CheckoutMode;
-    items?: CheckoutSessionItem[];
-    subscriptions?: CheckoutSessionSubscription[];
+    /** Unified products array as returned by post-#760 backends. */
+    products?: CheckoutSessionProduct[];
     successUrl?: string;
     cancelUrl?: string;
     coupons?: string[];
+    /**
+     * Pre-discount total in cart-currency major units (e.g. 24.95). Populated by
+     * billing API ≥ v1.1.2; `undefined` on older backends — readers must fall
+     * back to summing per-line `totalAmount`.
+     */
+    subtotalAmount?: number;
+    /**
+     * Total reduction from applied coupons in cart-currency major units.
+     * Populated by billing API ≥ v1.1.2; `undefined` on older backends.
+     */
+    discountAmount?: number;
+    /**
+     * Final charge amount in cart-currency major units (subtotal − discount,
+     * clamped ≥ 0). Populated by billing API ≥ v1.1.2; `undefined` on older
+     * backends — readers must fall back to summing per-line `overrideAmount`.
+     */
+    totalAmount?: number;
     createdAt?: string;
-    gateway?: BillingProvider;
-    gatewayData?: {
-        publishableKey?: string | null;
-        /**
-         * Optional Stripe PaymentIntent client secret exposed by the billing API
-         * when additional authentication is required for a saved payment method.
-         */
-        stripeClientSecret?: string | null;
-        /**
-         * Dedicated Stripe publishable key for PayPal. When set, PayPal uses a
-         * separate Stripe account from the primary `publishableKey`. When `null`
-         * or missing, PayPal is disabled — there is no fallback to `publishableKey`.
-         */
-        paypalPublishableKey?: string | null;
-    };
+    /**
+     * Per-gateway configuration. A session can advertise multiple concurrent
+     * gateways — read `gateways.stripe` for card/wallets, `gateways.paypal` for
+     * direct PayPal, and so on.
+     */
+    gateways?: CheckoutGateways;
     accountData?: {
         userId: string;
         email: string;
@@ -440,8 +470,8 @@ interface PaymentProviderAdapter {
     createPayPalElements(options: ElementOptions): unknown;
     destroy(): void;
 }
-/** Supported upstream billing providers. */
-type BillingProvider = 'recurly' | 'chargebee' | 'stripe';
+/** Supported upstream gateway codes. */
+type BillingProvider = 'stripe' | 'paypal';
 /** Token payload produced by client-side tokenization. */
 interface TokenizedBody {
     id?: string;
@@ -475,9 +505,13 @@ interface CheckoutProcessingPending {
 }
 /** Checkout mode: tokenize client-side or redirect to hosted page. */
 type CheckoutModeKind = 'tokenize' | 'redirect';
-/** Provider-agnostic normalized checkout session. */
+/**
+ * Provider-agnostic normalized checkout session. Backend may attach multiple
+ * gateways per session — read each from `data.<gatewayCode>`.
+ */
 interface NormalizedCheckoutSession {
-    provider: BillingProvider;
+    /** Gateway codes advertised by the backend for this session, for diagnostics. */
+    providers: BillingProvider[];
     mode: CheckoutModeKind;
     autoProcessingError?: CheckoutProcessError;
     autoProcessingAttempted?: boolean;
@@ -486,17 +520,25 @@ interface NormalizedCheckoutSession {
         hostedUrl?: string;
         clientToken?: string;
         session?: CheckoutSession;
-        chargebee?: {
-            site?: string;
-            publishableKey?: string;
-            dropInToken?: string;
-            sessionId?: string;
-        };
         stripe?: {
             clientSecret?: string;
             publishableKey?: string;
-            /** Dedicated PayPal publishable key. `undefined` means PayPal is disabled. */
+            /**
+             * Optional dedicated Stripe sub-account publishable key for rendering
+             * PayPal via Stripe Elements. When present and distinct, the saved-PM
+             * resume flow loads a separate FloPay instance for the PayPal PI.
+             */
             paypalPublishableKey?: string;
+            environment?: GatewayEnvironment;
+        };
+        /**
+         * Direct PayPal gateway configuration. Present only when the backend has
+         * configured a dedicated PayPal gateway for the consumer; absent means the
+         * Stripe-rendered PayPal fallback should be used (if Stripe is configured).
+         */
+        paypal?: {
+            publishableKey?: string;
+            environment?: GatewayEnvironment;
         };
     };
     raw?: unknown;
@@ -532,6 +574,42 @@ interface CheckoutItem {
     /** Arbitrary key/value metadata forwarded to the backend. */
     metadata?: Record<string, unknown> | null;
 }
+/**
+ * Unified product input for checkout session creation. Mirrors the backend's
+ * `CreateCheckoutProductBodyDto` introduced in #760 — the SDK accepts this
+ * shape on `CreateSessionParams.products`. Callers using the legacy
+ * {@link CheckoutItem} / {@link CheckoutSubscription} shapes do not need to
+ * migrate; the SDK folds them into this shape internally.
+ */
+interface CheckoutProduct {
+    /** Whether this product is a one-time item or a recurring subscription. */
+    type: CheckoutProductType;
+    /** Catalog code — preferred identifier. */
+    code?: string;
+    /** @deprecated Falls back to {@link CheckoutProduct.code} for back-compat. */
+    providerItemId?: string;
+    /** @deprecated Falls back to {@link CheckoutProduct.code} for back-compat. */
+    providerPlanId?: string;
+    /** Display-only name for the product. */
+    name?: string | null;
+    /** @deprecated Use {@link CheckoutProduct.name}. */
+    itemName?: string | null;
+    /** @deprecated Use {@link CheckoutProduct.name}. */
+    providerItemName?: string | null;
+    /** @deprecated Use {@link CheckoutProduct.name}. */
+    subscriptionName?: string | null;
+    /** @deprecated Use {@link CheckoutProduct.name}. */
+    providerPlanName?: string | null;
+    /** Defaults to 1. */
+    quantity?: number;
+    /** Display-only. Backend resolves prices from the catalog. */
+    totalAmount?: number;
+    /** Display-only discount override. Backend ignores this entirely. */
+    overrideAmount?: number | null;
+    /** @deprecated Prefer the session-level `currency`. */
+    currency?: string;
+    metadata?: Record<string, unknown> | null;
+}
 /** A recurring subscription plan for checkout session creation. */
 interface CheckoutSubscription {
     /**
@@ -597,14 +675,23 @@ interface CreateSessionParams {
     /** The client ID for the checkout session. */
     clientId: string;
     /**
-     * Session-level ISO 4217 currency code. Takes precedence over any
-     * per-item/per-subscription `currency` field. When omitted, the SDK
-     * falls back to `items[0].currency ?? subscriptions[0].currency`.
+     * Session-level ISO 4217 currency code. **Required** by post-#760
+     * backends (`@IsNotEmpty`). The SDK resolves it from this field first,
+     * then `items[0].currency`, then `subscriptions[0].currency`, then
+     * `products[0].currency`. When none resolve, the SDK throws
+     * `FloPayError('validation_error')` before issuing the HTTP request.
      */
     currency?: string;
-    /** One-time purchase items. */
+    /**
+     * Unified products array. When supplied, it is sent verbatim and
+     * {@link CreateSessionParams.items} / {@link CreateSessionParams.subscriptions}
+     * are ignored. Otherwise the SDK folds the legacy fields into this shape
+     * before POSTing to the backend.
+     */
+    products?: CheckoutProduct[];
+    /** One-time purchase items. Folded into `products[]` before send. */
     items?: CheckoutItem[];
-    /** Recurring subscription plans. */
+    /** Recurring subscription plans. Folded into `products[]` before send. */
     subscriptions?: CheckoutSubscription[];
     /** Buyer's account information. */
     account: CheckoutAccount;
@@ -641,14 +728,23 @@ interface InlineSessionParams {
     /** The client ID for the checkout session. */
     clientId: string;
     /**
-     * Session-level ISO 4217 currency code. Takes precedence over any
-     * per-item/per-subscription `currency` field. When omitted, the SDK
-     * falls back to `items[0].currency ?? subscriptions[0].currency`.
+     * Session-level ISO 4217 currency code. **Required** by post-#760
+     * backends (`@IsNotEmpty`). The SDK resolves it from this field first,
+     * then `items[0].currency`, then `subscriptions[0].currency`, then
+     * `products[0].currency`. When none resolve, the SDK throws
+     * `FloPayError('validation_error')` before issuing the HTTP request.
      */
     currency?: string;
-    /** One-time purchase items. */
+    /**
+     * Unified products array. When supplied, it is sent verbatim and
+     * {@link InlineSessionParams.items} / {@link InlineSessionParams.subscriptions}
+     * are ignored. Otherwise the SDK folds the legacy fields into this shape
+     * before POSTing to the backend.
+     */
+    products?: CheckoutProduct[];
+    /** One-time purchase items. Folded into `products[]` before send. */
     items?: CheckoutItem[];
-    /** Recurring subscription plans. */
+    /** Recurring subscription plans. Folded into `products[]` before send. */
     subscriptions?: CheckoutSubscription[];
     /** Buyer's account information. */
     account: CheckoutAccount;
@@ -817,7 +913,7 @@ declare function getConfiguredBillingApiUrl(): string;
 declare function getFloPayEnvironment(): FloPayEnvironment;
 
 /** Current SDK version. */
-declare const SDK_VERSION = "1.0.3";
+declare const SDK_VERSION = "1.1.3";
 /** Billing API URL for staging environment. */
 declare const BILLING_API_URL_STAGING = "https://api.stage.flopay.com";
 /** Billing API URL for production environment. */
@@ -951,6 +1047,13 @@ interface CheckoutDisplayData {
     totalSave: number;
     /** Discount percentage (0–100). */
     discountPercent: number;
+    /**
+     * Coupon discount reported by the backend (cart-currency major units),
+     * when available. Populated from `session.discountAmount` (billing
+     * API ≥ v1.1.2); `undefined` on older backends. Use this to render an
+     * explicit "coupon" line without recomputing per-item math.
+     */
+    couponDiscount?: number;
 }
 /** Options for {@link buildCheckoutDisplayData}. */
 interface BuildCheckoutDisplayDataOptions {
@@ -987,31 +1090,51 @@ declare function buildCheckoutDisplayData(session: CheckoutSession, options?: Bu
 
 /**
  * Resolve the session-level currency, honoring the documented fallback:
- * `session.currency ?? items[*].currency ?? subscriptions[*].currency`.
+ * `session.currency ?? items[*].currency ?? subscriptions[*].currency ?? products[*].currency`.
  *
- * Returns the first non-blank currency found, or 'USD' when nothing is set.
+ * Returns the first non-blank currency found, or `null` when nothing is set.
  * Empty and whitespace-only strings are treated as unset so they do not
  * bypass the fallback chain.
+ *
+ * Post-#760 backends reject session-create requests without a session-level
+ * currency (`@IsNotEmpty`); callers should throw a validation error when
+ * this returns `null` rather than silently defaulting.
  */
-declare function resolveSessionCurrency(sessionCurrency: string | undefined, items: ReadonlyArray<{
+declare function resolveSessionCurrency(sessionCurrency: string | undefined, items?: ReadonlyArray<{
+    currency?: string;
+}> | undefined, subscriptions?: ReadonlyArray<{
     currency?: string;
-}> | undefined, subscriptions: ReadonlyArray<{
+}> | undefined, products?: ReadonlyArray<{
     currency?: string;
-}> | undefined): string;
+}> | undefined): string | null;
+/**
+ * Fold legacy `items` + `subscriptions` arrays into the unified `products[]`
+ * shape introduced by backend #760. Items become `type: 'item'`,
+ * subscriptions become `type: 'subscription'`. The relative order is
+ * subscriptions-first then items, matching the order the previous payload
+ * builders emitted on the wire.
+ */
+declare function foldIntoProducts(items: readonly CheckoutItem[] | undefined, subscriptions: readonly CheckoutSubscription[] | undefined): CheckoutProduct[];
+/**
+ * Build the request payload for a single product in the unified shape
+ * introduced by backend #760. Emits `type`, `code`, `name`, `quantity`,
+ * `totalAmount`, `overrideAmount`, `currency`, and optional `metadata`.
+ */
+declare function buildProductPayload(product: CheckoutProduct, sessionCurrency: string): Record<string, unknown>;
 /**
  * Build the request payload for a single item.
  *
- * Sends the new `code` field alongside the deprecated `providerItemId`,
- * `providerItemName`, `totalAmount`, and `overrideAmount` fields so that
- * both new and old backend versions accept the same request body.
+ * @deprecated Use {@link buildProductPayload} with {@link foldIntoProducts}.
+ * Retained until the next major so external callers building the legacy
+ * `items[]` payload manually keep working.
  */
 declare function buildItemPayload(item: CheckoutItem, sessionCurrency: string): Record<string, unknown>;
 /**
  * Build the request payload for a single subscription.
  *
- * Sends the new `code` field alongside the deprecated `providerPlanId`,
- * `providerPlanName`, `totalAmount`, and `overrideAmount` fields for
- * backward compatibility.
+ * @deprecated Use {@link buildProductPayload} with {@link foldIntoProducts}.
+ * Retained until the next major so external callers building the legacy
+ * `subscriptions[]` payload manually keep working.
  */
 declare function buildSubscriptionPayload(subscription: CheckoutSubscription, sessionCurrency: string): Record<string, unknown>;
 
@@ -1025,4 +1148,4 @@ declare function isValidPublishableKey(key: string): boolean;
 /** Returns `true` if the string looks like a Stripe secret key. */
 declare function isValidSecretKey(key: string): boolean;
 
-export { type AVSFieldConfig, BILLING_API_URL, BILLING_API_URL_PRODUCTION, BILLING_API_URL_STAGING, BUTTONS_LAYOUT_DARK, BUTTONS_LAYOUT_DEFAULT, BUTTONS_LAYOUT_MINIMAL, BUTTONS_LAYOUT_ROUNDED, type BeforeButtonClickEvent, type BillingDetails, type BillingProvider, type BuildCheckoutDisplayDataOptions, type ButtonsLayoutStyles, type ButtonsLayoutTheme, CA_PROVINCES, COUNTRY_OPTIONS, CURRENCY_MAP, type CheckoutAccount, type CheckoutButtonMethod, type CheckoutDisplayData, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutProcessError, type CheckoutProcessingPending, type CheckoutSession, type CheckoutSessionItem, type CheckoutSessionResult, type CheckoutSessionSubscription, type CheckoutSubscription, type ConfirmCardPaymentParams, type ConfirmCardPaymentResult, type ConfirmPaymentParams, type CountryOption, type CreateCustomerParams, type CreatePaymentMethodResult, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DeclineEvent, type DisplayLineItem, ELEMENT_TYPES, type ElementChangeEvent, type ElementOptions, type ElementType, FLAT_APPEARANCE, type FloPayAppearance, type FloPayConfig, type FloPayEnvironment, FloPayError, type FloPayErrorType, type FloPayThemeVariables, type InlineSessionDraft, type InlineSessionParams, type InlineSessionPatch, type LineItem, type MountedElement, NIGHT_APPEARANCE, type NormalizedCheckoutSession, type PaymentProviderAdapter, type PaymentResult, type PriceData, type ProcessPaymentParams, type RecurringInterval, SDK_VERSION, SUPPORTED_CARD_BRANDS, type StateOption, type TagsData, type TokenizedBody, US_STATES, type UpdateCustomerParams, type WebhookEvent, apiError, authenticationError, buildCheckoutDisplayData, buildItemPayload, buildSubscriptionPayload, configureFlopay, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, isAVSEnabled, isAVSFieldVisible, isValidPublishableKey, isValidSecretKey, networkError, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, resolveSessionCurrency, validationError };
+export { type AVSFieldConfig, BILLING_API_URL, BILLING_API_URL_PRODUCTION, BILLING_API_URL_STAGING, BUTTONS_LAYOUT_DARK, BUTTONS_LAYOUT_DEFAULT, BUTTONS_LAYOUT_MINIMAL, BUTTONS_LAYOUT_ROUNDED, type BeforeButtonClickEvent, type BillingDetails, type BillingProvider, type BuildCheckoutDisplayDataOptions, type ButtonsLayoutStyles, type ButtonsLayoutTheme, CA_PROVINCES, COUNTRY_OPTIONS, CURRENCY_MAP, type CheckoutAccount, type CheckoutButtonMethod, type CheckoutDisplayData, type CheckoutGateway, type CheckoutGateways, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutProcessError, type CheckoutProcessingPending, type CheckoutProduct, type CheckoutProductType, type CheckoutSession, type CheckoutSessionProduct, type CheckoutSessionResult, type CheckoutSubscription, type ConfirmCardPaymentParams, type ConfirmCardPaymentResult, type ConfirmPaymentParams, type CountryOption, type CreateCustomerParams, type CreatePaymentMethodResult, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DeclineEvent, type DisplayLineItem, ELEMENT_TYPES, type ElementChangeEvent, type ElementOptions, type ElementType, FLAT_APPEARANCE, type FloPayAppearance, type FloPayConfig, type FloPayEnvironment, FloPayError, type FloPayErrorType, type FloPayThemeVariables, type GatewayEnvironment, type InlineSessionDraft, type InlineSessionParams, type InlineSessionPatch, type LineItem, type MountedElement, NIGHT_APPEARANCE, type NormalizedCheckoutSession, type NormalizedGatewayEnvironment, type PaymentProviderAdapter, type PaymentResult, type PriceData, type ProcessPaymentParams, type RecurringInterval, SDK_VERSION, SUPPORTED_CARD_BRANDS, type StateOption, type TagsData, type TokenizedBody, US_STATES, type UpdateCustomerParams, type WebhookEvent, apiError, authenticationError, buildCheckoutDisplayData, buildItemPayload, buildProductPayload, buildSubscriptionPayload, configureFlopay, foldIntoProducts, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, isAVSEnabled, isAVSFieldVisible, isValidPublishableKey, isValidSecretKey, networkError, normalizeGatewayEnvironment, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, resolveSessionCurrency, validationError };

package/dist/index.mjs

@@ -1,3 +1,21 @@
+// src/types.ts
+function normalizeGatewayEnvironment(env) {
+  if (env == null) return void 0;
+  switch (env) {
+    case "sandbox":
+    case "stage":
+      return "sandbox";
+    case "live":
+    case "production":
+      return "live";
+    default:
+      console.warn(
+        `[FloPay] Unrecognized gateway environment "${env}". Expected one of: sandbox, live, stage, production. Falling back to undefined.`
+      );
+      return void 0;
+  }
+}
+
 // src/errors.ts
 var FloPayError = class extends Error {
   constructor(message, type, options) {
@@ -45,7 +63,7 @@ function getFloPayEnvironment() {
 }
 
 // src/constants.ts
-var SDK_VERSION = "1.0.3";
+var SDK_VERSION = "1.1.3";
 var BILLING_API_URL_STAGING = "https://api.stage.flopay.com";
 var BILLING_API_URL_PRODUCTION = "https://api.flopay.com";
 var DEFAULT_API_BASE_URL = BILLING_API_URL_STAGING;
@@ -704,7 +722,7 @@ function nonBlank(value) {
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : void 0;
 }
-function resolveSessionCurrency(sessionCurrency, items, subscriptions) {
+function resolveSessionCurrency(sessionCurrency, items, subscriptions, products) {
   const session = nonBlank(sessionCurrency);
   if (session) return session;
   for (const item of items ?? []) {
@@ -715,7 +733,67 @@ function resolveSessionCurrency(sessionCurrency, items, subscriptions) {
     const c = nonBlank(sub.currency);
     if (c) return c;
   }
-  return "USD";
+  for (const product of products ?? []) {
+    const c = nonBlank(product.currency);
+    if (c) return c;
+  }
+  return null;
+}
+function foldIntoProducts(items, subscriptions) {
+  const products = [];
+  for (const sub of subscriptions ?? []) {
+    products.push({
+      type: "subscription",
+      code: nonBlank(sub.code) ?? nonBlank(sub.providerPlanId),
+      providerPlanId: sub.providerPlanId,
+      name: nonBlank(sub.subscriptionName) ?? nonBlank(sub.providerPlanName) ?? null,
+      subscriptionName: sub.subscriptionName ?? null,
+      providerPlanName: sub.providerPlanName ?? null,
+      quantity: sub.quantity,
+      totalAmount: sub.totalAmount,
+      overrideAmount: sub.overrideAmount,
+      currency: sub.currency,
+      metadata: sub.metadata
+    });
+  }
+  for (const item of items ?? []) {
+    products.push({
+      type: "item",
+      code: nonBlank(item.code) ?? nonBlank(item.providerItemId),
+      providerItemId: item.providerItemId,
+      name: nonBlank(item.itemName) ?? nonBlank(item.providerItemName) ?? null,
+      itemName: item.itemName ?? null,
+      providerItemName: item.providerItemName ?? null,
+      quantity: item.quantity,
+      totalAmount: item.totalAmount,
+      overrideAmount: item.overrideAmount,
+      currency: item.currency,
+      metadata: item.metadata
+    });
+  }
+  return products;
+}
+function buildProductPayload(product, sessionCurrency) {
+  const code = nonBlank(product.code) ?? nonBlank(product.providerItemId) ?? nonBlank(product.providerPlanId);
+  if (!code) {
+    throw new Error(
+      "CheckoutProduct requires `code` (or the deprecated `providerItemId` / `providerPlanId`)."
+    );
+  }
+  const name = nonBlank(product.name) ?? nonBlank(product.itemName) ?? nonBlank(product.providerItemName) ?? nonBlank(product.subscriptionName) ?? nonBlank(product.providerPlanName) ?? null;
+  const payload = {
+    type: product.type,
+    code,
+    name,
+    quantity: product.quantity ?? 1,
+    totalAmount: product.totalAmount,
+    overrideAmount: product.overrideAmount ?? null,
+    currency: nonBlank(product.currency) ?? sessionCurrency
+  };
+  if (product.metadata) {
+    payload["metadata"] = product.metadata;
+  }
+  return payload;
 }
 function buildItemPayload(item, sessionCurrency) {
   const code = nonBlank(item.code) ?? nonBlank(item.providerItemId);
@@ -765,13 +843,15 @@ function buildSubscriptionPayload(subscription, sessionCurrency) {
 // src/display.ts
 function buildCheckoutDisplayData(session, options = {}) {
   const itemsList = [];
-  const subscriptions = session.subscriptions ?? [];
-  const items = session.items ?? [];
-  const currency = resolveSessionCurrency(session.currency, items, subscriptions).toUpperCase();
+  const products = session.products ?? [];
+  const subscriptions = products.filter((p) => p.type === "subscription");
+  const items = products.filter((p) => p.type === "item");
+  const resolvedCurrency = resolveSessionCurrency(session.currency, void 0, void 0, products);
+  const currency = (resolvedCurrency ?? "USD").toUpperCase();
   for (const sub of subscriptions) {
     const originalPrice = sub.totalAmount ?? 0;
     const discountedPrice = sub.overrideAmount ?? originalPrice;
-    let name = sub.subscriptionName || sub.providerPlanName || sub.code || "Subscription";
+    let name = sub.name || sub.code || "Subscription";
     if (name === "4-WEEK PLAN" && discountedPrice <= 1) {
       name = "7-DAY TRIAL: FULL ACCESS";
     }
@@ -788,7 +868,7 @@ function buildCheckoutDisplayData(session, options = {}) {
       const originalPrice = item.totalAmount ?? 0;
       const discountedPrice = item.overrideAmount ?? originalPrice;
       itemsList.push({
-        name: item.itemName || item.providerItemName || item.code || "Item",
+        name: item.name || item.code || "Item",
         quantity: item.quantity,
         price: discountedPrice,
         originalPrice
@@ -803,8 +883,13 @@ function buildCheckoutDisplayData(session, options = {}) {
       originalPrice: session.amount / 100
     });
   }
-  const originalTotal = itemsList.reduce((sum, i) => sum + i.originalPrice * i.quantity, 0);
-  const total = itemsList.reduce((sum, i) => sum + i.price * i.quantity, 0);
+  const lineOriginalTotal = itemsList.reduce((sum, i) => sum + i.originalPrice * i.quantity, 0);
+  const lineTotal = itemsList.reduce((sum, i) => sum + i.price * i.quantity, 0);
+  const hasBackendTotals = typeof session.totalAmount === "number" && Number.isFinite(session.totalAmount);
+  const hasBackendSubtotal = typeof session.subtotalAmount === "number" && Number.isFinite(session.subtotalAmount);
+  const hasBackendDiscount = typeof session.discountAmount === "number" && Number.isFinite(session.discountAmount);
+  const total = hasBackendTotals ? session.totalAmount : lineTotal;
+  const originalTotal = hasBackendSubtotal ? session.subtotalAmount : lineOriginalTotal;
   const totalSave = Math.max(0, originalTotal - total);
   const discountPercent = originalTotal > 0 ? Math.round(totalSave / originalTotal * 100) : 0;
   return {
@@ -813,7 +898,8 @@ function buildCheckoutDisplayData(session, options = {}) {
     total,
     originalTotal,
     totalSave,
-    discountPercent
+    discountPercent,
+    ...hasBackendDiscount ? { couponDiscount: session.discountAmount } : {}
   };
 }
 
@@ -853,8 +939,10 @@ export {
   authenticationError,
   buildCheckoutDisplayData,
   buildItemPayload,
+  buildProductPayload,
   buildSubscriptionPayload,
   configureFlopay,
+  foldIntoProducts,
   getConfiguredBillingApiUrl,
   getCountryByCode,
   getCurrencyByCountry,
@@ -868,6 +956,7 @@ export {
   isValidPublishableKey,
   isValidSecretKey,
   networkError,
+  normalizeGatewayEnvironment,
   rateLimitError,
   resolveAVSConfig,
   resolveBillingApiUrl,