@flopay/shared 1.0.0 → 1.0.3

package/dist/index.d.cts

@@ -164,26 +164,56 @@ type CheckoutMode = 'full' | 'auto' | 'confirm';
 interface CheckoutSessionItem {
     uuid: string;
     checkoutSessionId: string;
-    providerItemId: string;
-    providerItemName: 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;
-    totalAmount: number;
-    overrideAmount: number | null;
-    currency: string;
+    /** 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 {
     uuid: string;
     checkoutSessionId: string;
-    providerPlanId: string;
-    providerPlanName: 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;
+    /**
+     * 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.
+     */
+    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;
-    totalAmount: number;
-    overrideAmount: number | null;
-    currency: string;
+    /** 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;
 }
@@ -473,33 +503,65 @@ interface NormalizedCheckoutSession {
 }
 /** A one-time purchase item for checkout session creation. */
 interface CheckoutItem {
-    /** The provider's item/product ID (e.g. Stripe price ID, Recurly plan code). */
-    providerItemId: string;
-    /** Display name for the item. */
+    /**
+     * Catalog code for the item — the preferred identifier. When omitted, the
+     * deprecated `providerItemId` is used as a fallback.
+     */
+    code?: string;
+    /**
+     * @deprecated Use {@link CheckoutItem.code}. Still accepted as a fallback
+     * when `code` is not provided.
+     */
+    providerItemId?: string;
+    /**
+     * Display-only name for the item. Takes priority over the deprecated
+     * `providerItemName`. Backend resolves names from the catalog; pass this
+     * to seed the client-side display cache for the post-redirect fetch.
+     */
+    itemName?: string | null;
+    /** @deprecated Use {@link CheckoutItem.itemName}. Still accepted as a fallback when `itemName` is not provided. */
     providerItemName?: string | null;
     /** Defaults to 1. */
     quantity?: number;
-    /** The regular (full) price in the given currency. */
-    totalAmount: number;
-    /** A discounted price to charge instead of totalAmount. */
+    /** Display-only. Backend resolves prices from the catalog; pass this to seed the client-side display cache so the UI can render the regular price after redirect. */
+    totalAmount?: number;
+    /** Display-only. Backend ignores this entirely; pass this to seed the client-side display cache so the UI can render the discounted price after redirect. */
     overrideAmount?: number | null;
-    /** ISO 4217 currency code. Defaults to 'USD'. */
+    /** @deprecated Prefer the session-level `currency` on {@link CreateSessionParams}/{@link InlineSessionParams}. */
     currency?: string;
+    /** Arbitrary key/value metadata forwarded to the backend. */
+    metadata?: Record<string, unknown> | null;
 }
 /** A recurring subscription plan for checkout session creation. */
 interface CheckoutSubscription {
-    /** The provider's plan ID. */
-    providerPlanId: string;
-    /** Display name for the plan. */
+    /**
+     * Catalog code for the plan — the preferred identifier. When omitted, the
+     * deprecated `providerPlanId` is used as a fallback.
+     */
+    code?: string;
+    /**
+     * @deprecated Use {@link CheckoutSubscription.code}. Still accepted as a
+     * fallback when `code` is not provided.
+     */
+    providerPlanId?: string;
+    /**
+     * Display-only name for the subscription plan. Takes priority over the
+     * deprecated `providerPlanName`. Backend resolves names from the catalog;
+     * pass this to seed the client-side display cache for the post-redirect fetch.
+     */
+    subscriptionName?: string | null;
+    /** @deprecated Use {@link CheckoutSubscription.subscriptionName}. Still accepted as a fallback when `subscriptionName` is not provided. */
     providerPlanName?: string | null;
     /** Defaults to 1. */
     quantity?: number;
-    /** The regular (full) price in the given currency. */
-    totalAmount: number;
-    /** A discounted price to charge instead of totalAmount. */
+    /** Display-only. Backend resolves prices from the catalog; pass this to seed the client-side display cache so the UI can render the regular price after redirect. */
+    totalAmount?: number;
+    /** Display-only. Backend ignores this entirely; pass this to seed the client-side display cache so the UI can render the discounted price after redirect. */
     overrideAmount?: number | null;
-    /** ISO 4217 currency code. Defaults to 'USD'. */
+    /** @deprecated Prefer the session-level `currency` on {@link CreateSessionParams}/{@link InlineSessionParams}. */
     currency?: string;
+    /** Arbitrary key/value metadata forwarded to the backend. */
+    metadata?: Record<string, unknown> | null;
 }
 /** Buyer's account information for session creation. */
 interface CheckoutAccount {
@@ -534,6 +596,12 @@ interface CreateSessionParams {
     checkoutBaseUrl: string;
     /** 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`.
+     */
+    currency?: string;
     /** One-time purchase items. */
     items?: CheckoutItem[];
     /** Recurring subscription plans. */
@@ -572,6 +640,12 @@ interface CreateSessionParams {
 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`.
+     */
+    currency?: string;
     /** One-time purchase items. */
     items?: CheckoutItem[];
     /** Recurring subscription plans. */
@@ -743,7 +817,7 @@ declare function getConfiguredBillingApiUrl(): string;
 declare function getFloPayEnvironment(): FloPayEnvironment;
 
 /** Current SDK version. */
-declare const SDK_VERSION = "1.0.0";
+declare const SDK_VERSION = "1.0.3";
 /** Billing API URL for staging environment. */
 declare const BILLING_API_URL_STAGING = "https://api.stage.flopay.com";
 /** Billing API URL for production environment. */
@@ -878,12 +952,21 @@ interface CheckoutDisplayData {
     /** Discount percentage (0–100). */
     discountPercent: number;
 }
+/** Options for {@link buildCheckoutDisplayData}. */
+interface BuildCheckoutDisplayDataOptions {
+    /**
+     * When `true`, items are hidden from the order summary if the session also
+     * contains subscriptions (matches the legacy checkout/CheckoutModal
+     * behavior). Defaults to `false` — items are always shown.
+     */
+    hideBundledItems?: boolean;
+}
 /**
  * Builds display data from a `CheckoutSession` for rendering an order summary.
  *
- * Matches the display logic in checkout/CheckoutModal exactly:
  * - Subscriptions are always shown
- * - Items are hidden when the session has both subscriptions AND items
+ * - Items are shown by default; pass `{ hideBundledItems: true }` to suppress
+ *   them when the session also contains subscriptions (legacy behavior)
  * - `overrideAmount` (when not null/undefined) is the discounted price
  * - Plan name "4-WEEK PLAN" with price <= 1 is renamed to "7-DAY TRIAL: FULL ACCESS"
  * - Discount percentage and savings are computed from the difference
@@ -900,7 +983,37 @@ interface CheckoutDisplayData {
  * // display.currency → 'EUR'
  * ```
  */
-declare function buildCheckoutDisplayData(session: CheckoutSession): CheckoutDisplayData;
+declare function buildCheckoutDisplayData(session: CheckoutSession, options?: BuildCheckoutDisplayDataOptions): CheckoutDisplayData;
+
+/**
+ * Resolve the session-level currency, honoring the documented fallback:
+ * `session.currency ?? items[*].currency ?? subscriptions[*].currency`.
+ *
+ * Returns the first non-blank currency found, or 'USD' when nothing is set.
+ * Empty and whitespace-only strings are treated as unset so they do not
+ * bypass the fallback chain.
+ */
+declare function resolveSessionCurrency(sessionCurrency: string | undefined, items: ReadonlyArray<{
+    currency?: string;
+}> | undefined, subscriptions: ReadonlyArray<{
+    currency?: string;
+}> | undefined): string;
+/**
+ * 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.
+ */
+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.
+ */
+declare function buildSubscriptionPayload(subscription: CheckoutSubscription, sessionCurrency: string): Record<string, unknown>;
 
 /**
  * Look up currency information by ISO 3166-1 alpha-2 country code.
@@ -912,4 +1025,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 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, configureFlopay, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, isAVSEnabled, isAVSFieldVisible, isValidPublishableKey, isValidSecretKey, networkError, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, 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 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 };

package/dist/index.d.ts

@@ -164,26 +164,56 @@ type CheckoutMode = 'full' | 'auto' | 'confirm';
 interface CheckoutSessionItem {
     uuid: string;
     checkoutSessionId: string;
-    providerItemId: string;
-    providerItemName: 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;
-    totalAmount: number;
-    overrideAmount: number | null;
-    currency: string;
+    /** 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 {
     uuid: string;
     checkoutSessionId: string;
-    providerPlanId: string;
-    providerPlanName: 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;
+    /**
+     * 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.
+     */
+    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;
-    totalAmount: number;
-    overrideAmount: number | null;
-    currency: string;
+    /** 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;
 }
@@ -473,33 +503,65 @@ interface NormalizedCheckoutSession {
 }
 /** A one-time purchase item for checkout session creation. */
 interface CheckoutItem {
-    /** The provider's item/product ID (e.g. Stripe price ID, Recurly plan code). */
-    providerItemId: string;
-    /** Display name for the item. */
+    /**
+     * Catalog code for the item — the preferred identifier. When omitted, the
+     * deprecated `providerItemId` is used as a fallback.
+     */
+    code?: string;
+    /**
+     * @deprecated Use {@link CheckoutItem.code}. Still accepted as a fallback
+     * when `code` is not provided.
+     */
+    providerItemId?: string;
+    /**
+     * Display-only name for the item. Takes priority over the deprecated
+     * `providerItemName`. Backend resolves names from the catalog; pass this
+     * to seed the client-side display cache for the post-redirect fetch.
+     */
+    itemName?: string | null;
+    /** @deprecated Use {@link CheckoutItem.itemName}. Still accepted as a fallback when `itemName` is not provided. */
     providerItemName?: string | null;
     /** Defaults to 1. */
     quantity?: number;
-    /** The regular (full) price in the given currency. */
-    totalAmount: number;
-    /** A discounted price to charge instead of totalAmount. */
+    /** Display-only. Backend resolves prices from the catalog; pass this to seed the client-side display cache so the UI can render the regular price after redirect. */
+    totalAmount?: number;
+    /** Display-only. Backend ignores this entirely; pass this to seed the client-side display cache so the UI can render the discounted price after redirect. */
     overrideAmount?: number | null;
-    /** ISO 4217 currency code. Defaults to 'USD'. */
+    /** @deprecated Prefer the session-level `currency` on {@link CreateSessionParams}/{@link InlineSessionParams}. */
     currency?: string;
+    /** Arbitrary key/value metadata forwarded to the backend. */
+    metadata?: Record<string, unknown> | null;
 }
 /** A recurring subscription plan for checkout session creation. */
 interface CheckoutSubscription {
-    /** The provider's plan ID. */
-    providerPlanId: string;
-    /** Display name for the plan. */
+    /**
+     * Catalog code for the plan — the preferred identifier. When omitted, the
+     * deprecated `providerPlanId` is used as a fallback.
+     */
+    code?: string;
+    /**
+     * @deprecated Use {@link CheckoutSubscription.code}. Still accepted as a
+     * fallback when `code` is not provided.
+     */
+    providerPlanId?: string;
+    /**
+     * Display-only name for the subscription plan. Takes priority over the
+     * deprecated `providerPlanName`. Backend resolves names from the catalog;
+     * pass this to seed the client-side display cache for the post-redirect fetch.
+     */
+    subscriptionName?: string | null;
+    /** @deprecated Use {@link CheckoutSubscription.subscriptionName}. Still accepted as a fallback when `subscriptionName` is not provided. */
     providerPlanName?: string | null;
     /** Defaults to 1. */
     quantity?: number;
-    /** The regular (full) price in the given currency. */
-    totalAmount: number;
-    /** A discounted price to charge instead of totalAmount. */
+    /** Display-only. Backend resolves prices from the catalog; pass this to seed the client-side display cache so the UI can render the regular price after redirect. */
+    totalAmount?: number;
+    /** Display-only. Backend ignores this entirely; pass this to seed the client-side display cache so the UI can render the discounted price after redirect. */
     overrideAmount?: number | null;
-    /** ISO 4217 currency code. Defaults to 'USD'. */
+    /** @deprecated Prefer the session-level `currency` on {@link CreateSessionParams}/{@link InlineSessionParams}. */
     currency?: string;
+    /** Arbitrary key/value metadata forwarded to the backend. */
+    metadata?: Record<string, unknown> | null;
 }
 /** Buyer's account information for session creation. */
 interface CheckoutAccount {
@@ -534,6 +596,12 @@ interface CreateSessionParams {
     checkoutBaseUrl: string;
     /** 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`.
+     */
+    currency?: string;
     /** One-time purchase items. */
     items?: CheckoutItem[];
     /** Recurring subscription plans. */
@@ -572,6 +640,12 @@ interface CreateSessionParams {
 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`.
+     */
+    currency?: string;
     /** One-time purchase items. */
     items?: CheckoutItem[];
     /** Recurring subscription plans. */
@@ -743,7 +817,7 @@ declare function getConfiguredBillingApiUrl(): string;
 declare function getFloPayEnvironment(): FloPayEnvironment;
 
 /** Current SDK version. */
-declare const SDK_VERSION = "1.0.0";
+declare const SDK_VERSION = "1.0.3";
 /** Billing API URL for staging environment. */
 declare const BILLING_API_URL_STAGING = "https://api.stage.flopay.com";
 /** Billing API URL for production environment. */
@@ -878,12 +952,21 @@ interface CheckoutDisplayData {
     /** Discount percentage (0–100). */
     discountPercent: number;
 }
+/** Options for {@link buildCheckoutDisplayData}. */
+interface BuildCheckoutDisplayDataOptions {
+    /**
+     * When `true`, items are hidden from the order summary if the session also
+     * contains subscriptions (matches the legacy checkout/CheckoutModal
+     * behavior). Defaults to `false` — items are always shown.
+     */
+    hideBundledItems?: boolean;
+}
 /**
  * Builds display data from a `CheckoutSession` for rendering an order summary.
  *
- * Matches the display logic in checkout/CheckoutModal exactly:
  * - Subscriptions are always shown
- * - Items are hidden when the session has both subscriptions AND items
+ * - Items are shown by default; pass `{ hideBundledItems: true }` to suppress
+ *   them when the session also contains subscriptions (legacy behavior)
  * - `overrideAmount` (when not null/undefined) is the discounted price
  * - Plan name "4-WEEK PLAN" with price <= 1 is renamed to "7-DAY TRIAL: FULL ACCESS"
  * - Discount percentage and savings are computed from the difference
@@ -900,7 +983,37 @@ interface CheckoutDisplayData {
  * // display.currency → 'EUR'
  * ```
  */
-declare function buildCheckoutDisplayData(session: CheckoutSession): CheckoutDisplayData;
+declare function buildCheckoutDisplayData(session: CheckoutSession, options?: BuildCheckoutDisplayDataOptions): CheckoutDisplayData;
+
+/**
+ * Resolve the session-level currency, honoring the documented fallback:
+ * `session.currency ?? items[*].currency ?? subscriptions[*].currency`.
+ *
+ * Returns the first non-blank currency found, or 'USD' when nothing is set.
+ * Empty and whitespace-only strings are treated as unset so they do not
+ * bypass the fallback chain.
+ */
+declare function resolveSessionCurrency(sessionCurrency: string | undefined, items: ReadonlyArray<{
+    currency?: string;
+}> | undefined, subscriptions: ReadonlyArray<{
+    currency?: string;
+}> | undefined): string;
+/**
+ * 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.
+ */
+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.
+ */
+declare function buildSubscriptionPayload(subscription: CheckoutSubscription, sessionCurrency: string): Record<string, unknown>;
 
 /**
  * Look up currency information by ISO 3166-1 alpha-2 country code.
@@ -912,4 +1025,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 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, configureFlopay, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, isAVSEnabled, isAVSFieldVisible, isValidPublishableKey, isValidSecretKey, networkError, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, 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 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 };

package/dist/index.mjs

@@ -45,7 +45,7 @@ function getFloPayEnvironment() {
 }
 
 // src/constants.ts
-var SDK_VERSION = "1.0.0";
+var SDK_VERSION = "1.0.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;
@@ -698,16 +698,80 @@ function getStateFromPostalCode(country, postalCode) {
   }
 }
 
+// src/checkout-payload.ts
+function nonBlank(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function resolveSessionCurrency(sessionCurrency, items, subscriptions) {
+  const session = nonBlank(sessionCurrency);
+  if (session) return session;
+  for (const item of items ?? []) {
+    const c = nonBlank(item.currency);
+    if (c) return c;
+  }
+  for (const sub of subscriptions ?? []) {
+    const c = nonBlank(sub.currency);
+    if (c) return c;
+  }
+  return "USD";
+}
+function buildItemPayload(item, sessionCurrency) {
+  const code = nonBlank(item.code) ?? nonBlank(item.providerItemId);
+  if (!code) {
+    throw new Error("CheckoutItem requires either `code` or the deprecated `providerItemId`.");
+  }
+  const itemName = nonBlank(item.itemName) ?? nonBlank(item.providerItemName) ?? null;
+  const payload = {
+    code,
+    providerItemId: nonBlank(item.providerItemId) ?? code,
+    itemName,
+    providerItemName: nonBlank(item.providerItemName) ?? itemName,
+    quantity: item.quantity ?? 1,
+    totalAmount: item.totalAmount,
+    overrideAmount: item.overrideAmount ?? null,
+    currency: nonBlank(item.currency) ?? sessionCurrency
+  };
+  if (item.metadata) {
+    payload["metadata"] = item.metadata;
+  }
+  return payload;
+}
+function buildSubscriptionPayload(subscription, sessionCurrency) {
+  const code = nonBlank(subscription.code) ?? nonBlank(subscription.providerPlanId);
+  if (!code) {
+    throw new Error(
+      "CheckoutSubscription requires either `code` or the deprecated `providerPlanId`."
+    );
+  }
+  const subscriptionName = nonBlank(subscription.subscriptionName) ?? nonBlank(subscription.providerPlanName) ?? null;
+  const payload = {
+    code,
+    providerPlanId: nonBlank(subscription.providerPlanId) ?? code,
+    subscriptionName,
+    providerPlanName: nonBlank(subscription.providerPlanName) ?? subscriptionName,
+    quantity: subscription.quantity ?? 1,
+    totalAmount: subscription.totalAmount,
+    overrideAmount: subscription.overrideAmount ?? null,
+    currency: nonBlank(subscription.currency) ?? sessionCurrency
+  };
+  if (subscription.metadata) {
+    payload["metadata"] = subscription.metadata;
+  }
+  return payload;
+}
+
 // src/display.ts
-function buildCheckoutDisplayData(session) {
+function buildCheckoutDisplayData(session, options = {}) {
   const itemsList = [];
-  let currency = "USD";
   const subscriptions = session.subscriptions ?? [];
   const items = session.items ?? [];
+  const currency = resolveSessionCurrency(session.currency, items, subscriptions).toUpperCase();
   for (const sub of subscriptions) {
-    const originalPrice = sub.totalAmount;
+    const originalPrice = sub.totalAmount ?? 0;
     const discountedPrice = sub.overrideAmount ?? originalPrice;
-    let name = sub.providerPlanName || "Subscription";
+    let name = sub.subscriptionName || sub.providerPlanName || sub.code || "Subscription";
     if (name === "4-WEEK PLAN" && discountedPrice <= 1) {
       name = "7-DAY TRIAL: FULL ACCESS";
     }
@@ -717,20 +781,18 @@ function buildCheckoutDisplayData(session) {
       price: discountedPrice,
       originalPrice
     });
-    if (sub.currency) currency = sub.currency.toUpperCase();
   }
-  const hideItems = subscriptions.length > 0 && items.length > 0;
+  const hideItems = options.hideBundledItems === true && subscriptions.length > 0 && items.length > 0;
   if (!hideItems) {
     for (const item of items) {
-      const originalPrice = item.totalAmount;
+      const originalPrice = item.totalAmount ?? 0;
       const discountedPrice = item.overrideAmount ?? originalPrice;
       itemsList.push({
-        name: item.providerItemName || "Item",
+        name: item.itemName || item.providerItemName || item.code || "Item",
         quantity: item.quantity,
         price: discountedPrice,
         originalPrice
       });
-      if (item.currency) currency = item.currency.toUpperCase();
     }
   }
   if (itemsList.length === 0) {
@@ -740,7 +802,6 @@ function buildCheckoutDisplayData(session) {
       price: session.amount / 100,
       originalPrice: session.amount / 100
     });
-    currency = session.currency?.toUpperCase() ?? "USD";
   }
   const originalTotal = itemsList.reduce((sum, i) => sum + i.originalPrice * i.quantity, 0);
   const total = itemsList.reduce((sum, i) => sum + i.price * i.quantity, 0);
@@ -791,6 +852,8 @@ export {
   apiError,
   authenticationError,
   buildCheckoutDisplayData,
+  buildItemPayload,
+  buildSubscriptionPayload,
   configureFlopay,
   getConfiguredBillingApiUrl,
   getCountryByCode,
@@ -809,6 +872,7 @@ export {
   resolveAVSConfig,
   resolveBillingApiUrl,
   resolveButtonsLayoutTheme,
+  resolveSessionCurrency,
   validationError
 };
 //# sourceMappingURL=index.mjs.map