@flopay/shared 1.1.0 → 1.1.4

package/dist/index.d.cts

@@ -160,61 +160,33 @@ 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 {
-    uuid: string;
-    checkoutSessionId: string;
-    /** Preferred catalog code for the item. */
-    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.
-     */
-    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;
-    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;
-    metadata?: Record<string, unknown> | null;
-}
-/** A subscription plan from a checkout session response. */
-interface CheckoutSessionSubscription {
+/**
+ * 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 subscription plan. */
+    /** 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 CheckoutSessionSubscription.code}. Backend may stop returning this in a future major. */
-    providerPlanId?: string;
     /**
-     * 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.
+     * Display-only name. Resolved from the catalog server-side; the SDK
+     * populates this from the client-side display cache when missing.
      */
-    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;
+    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;
-    /** @deprecated Removed from backend. Checkouts only create new subscriptions. */
-    isUpdate?: boolean;
     metadata?: Record<string, unknown> | null;
 }
 /**
@@ -279,11 +251,28 @@ 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;
     /**
      * Per-gateway configuration. A session can advertise multiple concurrent
@@ -585,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 {
     /**
@@ -650,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;
@@ -694,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;
@@ -870,7 +913,7 @@ declare function getConfiguredBillingApiUrl(): string;
 declare function getFloPayEnvironment(): FloPayEnvironment;
 
 /** Current SDK version. */
-declare const SDK_VERSION = "1.1.0";
+declare const SDK_VERSION = "1.1.4";
 /** Billing API URL for staging environment. */
 declare const BILLING_API_URL_STAGING = "https://api.stage.flopay.com";
 /** Billing API URL for production environment. */
@@ -1004,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 {
@@ -1040,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>;
 
@@ -1078,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 CheckoutGateway, type CheckoutGateways, 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 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, buildSubscriptionPayload, configureFlopay, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, isAVSEnabled, isAVSFieldVisible, isValidPublishableKey, isValidSecretKey, networkError, normalizeGatewayEnvironment, 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.d.ts

@@ -160,61 +160,33 @@ 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 {
-    uuid: string;
-    checkoutSessionId: string;
-    /** Preferred catalog code for the item. */
-    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.
-     */
-    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;
-    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;
-    metadata?: Record<string, unknown> | null;
-}
-/** A subscription plan from a checkout session response. */
-interface CheckoutSessionSubscription {
+/**
+ * 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 subscription plan. */
+    /** 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 CheckoutSessionSubscription.code}. Backend may stop returning this in a future major. */
-    providerPlanId?: string;
     /**
-     * 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.
+     * Display-only name. Resolved from the catalog server-side; the SDK
+     * populates this from the client-side display cache when missing.
      */
-    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;
+    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;
-    /** @deprecated Removed from backend. Checkouts only create new subscriptions. */
-    isUpdate?: boolean;
     metadata?: Record<string, unknown> | null;
 }
 /**
@@ -279,11 +251,28 @@ 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;
     /**
      * Per-gateway configuration. A session can advertise multiple concurrent
@@ -585,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 {
     /**
@@ -650,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;
@@ -694,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;
@@ -870,7 +913,7 @@ declare function getConfiguredBillingApiUrl(): string;
 declare function getFloPayEnvironment(): FloPayEnvironment;
 
 /** Current SDK version. */
-declare const SDK_VERSION = "1.1.0";
+declare const SDK_VERSION = "1.1.4";
 /** Billing API URL for staging environment. */
 declare const BILLING_API_URL_STAGING = "https://api.stage.flopay.com";
 /** Billing API URL for production environment. */
@@ -1004,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 {
@@ -1040,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>;
 
@@ -1078,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 CheckoutGateway, type CheckoutGateways, 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 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, buildSubscriptionPayload, configureFlopay, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, isAVSEnabled, isAVSFieldVisible, isValidPublishableKey, isValidSecretKey, networkError, normalizeGatewayEnvironment, 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 };