@flopay/js 1.0.0 → 1.0.3

package/dist/index.d.cts

@@ -155,6 +155,73 @@ declare class StripeAdapter implements PaymentProviderAdapter {
     destroy(): void;
 }
 
+/**
+ * Client-side cache for display-only checkout fields the backend no longer
+ * persists (`overrideAmount`, `totalAmount`, `providerItemName`,
+ * `providerPlanName`, per-line `currency`).
+ *
+ * The cache lives in `sessionStorage` so it survives the navigation from the
+ * page that creates the session to the checkout page that fetches it, but
+ * dies on tab close. An in-memory fallback keeps the SDK working in Node /
+ * SSR contexts where `sessionStorage` is unavailable.
+ *
+ * Values from the server response always win — cached values fill in only
+ * where the server returned `null` or `undefined`.
+ */
+/** Display-only fields per item that can be cached and merged back later. */
+interface SessionDisplayItem {
+    /** Catalog code (preferred match key). */
+    code?: string;
+    /** @deprecated Match key fallback when `code` is not provided. */
+    providerItemId?: string;
+    /** Display-only name for the item. Takes priority over `providerItemName`. */
+    itemName?: string | null;
+    /** @deprecated Use `itemName`. */
+    providerItemName?: string | null;
+    totalAmount?: number;
+    overrideAmount?: number | null;
+    currency?: string;
+}
+/** Display-only fields per subscription that can be cached and merged back later. */
+interface SessionDisplaySubscription {
+    /** Catalog code (preferred match key). */
+    code?: string;
+    /** @deprecated Match key fallback when `code` is not provided. */
+    providerPlanId?: string;
+    /** Display-only name for the subscription plan. Takes priority over `providerPlanName`. */
+    subscriptionName?: string | null;
+    /** @deprecated Use `subscriptionName`. */
+    providerPlanName?: string | null;
+    totalAmount?: number;
+    overrideAmount?: number | null;
+    currency?: string;
+}
+/** Display-only payload that can be stashed for later merge into a session response. */
+interface SessionDisplayCacheData {
+    /** Session-level currency (falls into the response only when the server omits it). */
+    currency?: string;
+    items?: SessionDisplayItem[];
+    subscriptions?: SessionDisplaySubscription[];
+}
+/**
+ * Stash display-only data for a session. Called client-side right after the
+ * server returns a session ID, so the values survive the redirect to the
+ * checkout page.
+ */
+declare function cacheSessionDisplayData(sessionId: string, data: SessionDisplayCacheData, options?: {
+    ttlMs?: number;
+}): void;
+/**
+ * Read previously-cached display data for a session, or `null` if nothing
+ * is cached (or the TTL has elapsed).
+ */
+declare function getSessionDisplayData(sessionId: string): SessionDisplayCacheData | null;
+/**
+ * Drop any cached display data for a session. Call from the success page
+ * after the payment completes; otherwise the TTL handles cleanup.
+ */
+declare function clearSessionDisplayData(sessionId: string): void;
+
 /** Raw billing API response wrapper. */
 interface BillingResponse<T> {
     data: T;
@@ -167,30 +234,53 @@ interface RawCheckoutSession {
     status: 'pending' | 'completed' | 'expired';
     successUrl: string;
     cancelUrl: string;
+    /** Session-level currency. Takes precedence over per-item/per-subscription currency. */
+    currency?: string;
     createdAt?: string;
     checkoutUrl?: string;
     items: Array<{
         uuid: string;
         checkoutSessionId: string;
-        providerItemId: string;
-        providerItemName: string;
+        /** Preferred catalog code. Falls back to the deprecated `providerItemId`. */
+        code?: string;
+        /** @deprecated Use `code`. */
+        providerItemId?: string;
+        /** Display-only name. Preferred over `providerItemName`. */
+        itemName?: string | null;
+        /** @deprecated Use `itemName`. Mirrored for backward compatibility. */
+        providerItemName?: string | null;
+        /** Display-only description from the catalog. */
         providerItemDescription?: string | null;
         quantity: number;
-        totalAmount: number;
-        overrideAmount: number | null;
-        currency: string;
+        /** @deprecated Removed from the backend — resolved from the catalog. */
+        totalAmount?: number;
+        /** @deprecated Removed from the backend entirely. */
+        overrideAmount?: number | null;
+        /** @deprecated Use the session-level `currency`. */
+        currency?: string;
         metadata?: Record<string, unknown> | null;
     }>;
     subscriptions: Array<{
         uuid: string;
         checkoutSessionId: string;
-        providerPlanId: string;
-        providerPlanName: string;
+        /** Preferred catalog code. Falls back to the deprecated `providerPlanId`. */
+        code?: string;
+        /** @deprecated Use `code`. */
+        providerPlanId?: string;
+        /** Display-only name. Preferred over `providerPlanName`. */
+        subscriptionName?: string | null;
+        /** @deprecated Use `subscriptionName`. Mirrored for backward compatibility. */
+        providerPlanName?: string | null;
+        /** Display-only description from the catalog. */
         providerPlanDescription?: string | null;
         quantity: number;
-        totalAmount: number;
-        overrideAmount: number | null;
-        currency: string;
+        /** @deprecated Removed from the backend — resolved from the catalog. */
+        totalAmount?: number;
+        /** @deprecated Removed from the backend entirely. */
+        overrideAmount?: number | null;
+        /** @deprecated Use the session-level `currency`. */
+        currency?: string;
+        /** @deprecated Removed from the backend. Checkouts only create new subscriptions. */
         isUpdate?: boolean;
         metadata?: Record<string, unknown> | null;
     }>;
@@ -232,6 +322,33 @@ declare class PaymentAPI {
     constructor(billingApiUrl: string);
     /** Fetch a raw checkout session by ID. */
     getCheckoutSession(checkoutSessionId: string): Promise<BillingResponse<RawCheckoutSession>>;
+    /**
+     * Stash display-only data for a session so subsequent fetches can fill in
+     * fields the backend no longer persists (`overrideAmount`, `totalAmount`,
+     * `providerItemName`, `providerPlanName`).
+     *
+     * Backed by `sessionStorage` in the browser, with an in-memory fallback in
+     * Node/SSR contexts. Default TTL: 1 hour.
+     *
+     * Server-returned values always win — cached values fill in only where the
+     * server returned `null` / `undefined`.
+     *
+     * @example
+     * ```ts
+     * paymentAPI.cacheSessionDisplayData(sessionId, {
+     *   currency: 'USD',
+     *   items: [{ code: 'pro_plan', overrideAmount: 24.99, providerItemName: 'Pro' }],
+     * });
+     * ```
+     */
+    cacheSessionDisplayData(sessionId: string, data: SessionDisplayCacheData, options?: {
+        ttlMs?: number;
+    }): void;
+    /**
+     * Drop any cached display data for a session. Call after the payment
+     * completes; otherwise the TTL handles cleanup.
+     */
+    clearSessionDisplayData(sessionId: string): void;
     /**
      * Fetch and normalize a checkout session.
      *
@@ -301,6 +418,24 @@ declare class PaymentAPI {
     private resolveProcessResponse;
     private toCheckoutProcessingPending;
     private clampRetryAfterMs;
+    /**
+     * Stash the display-only fields the consumer passed into a create-session
+     * call. Runs after the backend assigns a UUID so a later GET on the same
+     * session (typically after a redirect) can fill in fields the backend no
+     * longer persists — `overrideAmount`, `totalAmount`, `itemName`, etc.
+     *
+     * No-op when no UUID is available.
+     */
+    private autoCacheDisplayData;
+    /**
+     * Merge cached display-only fields (set by {@link cacheSessionDisplayData})
+     * into a raw session response and mirror the new/legacy name aliases so
+     * readers using either field always get a value when one exists.
+     *
+     * Server values always win — cache fills in only where the server returned
+     * `null` / `undefined`.
+     */
+    private mergeCachedDisplayData;
 }
 
 /**
@@ -321,11 +456,11 @@ declare class PaymentAPI {
  *   billingApiUrl: 'https://billing.example.com',
  *   checkoutBaseUrl: 'https://checkout.example.com',
  *   clientId: 'client_123',
+ *   currency: 'USD',
  *   items: [{
- *     providerItemId: 'prod_abc',
- *     providerItemName: 'Pro Plan',
- *     totalAmount: 49.99,
- *     overrideAmount: 24.99,
+ *     code: 'initial_charge',
+ *     quantity: 1,
+ *     metadata: { source: 'web' },
  *   }],
  *   account: { userId: 'user_1', email: 'user@example.com' },
  *   successUrl: '/success',
@@ -344,4 +479,4 @@ declare function createCheckoutSessionWithRetries(options: CreateSessionParams &
     maxRetries?: number;
 }): Promise<CheckoutSessionResult>;
 
-export { FloPay, FloPayElements, PaymentAPI, StripeAdapter, createCheckoutSession, createCheckoutSessionWithRetries, loadFloPay };
+export { FloPay, FloPayElements, PaymentAPI, type SessionDisplayCacheData, type SessionDisplayItem, type SessionDisplaySubscription, StripeAdapter, cacheSessionDisplayData, clearSessionDisplayData, createCheckoutSession, createCheckoutSessionWithRetries, getSessionDisplayData, loadFloPay };

package/dist/index.d.ts

@@ -155,6 +155,73 @@ declare class StripeAdapter implements PaymentProviderAdapter {
     destroy(): void;
 }
 
+/**
+ * Client-side cache for display-only checkout fields the backend no longer
+ * persists (`overrideAmount`, `totalAmount`, `providerItemName`,
+ * `providerPlanName`, per-line `currency`).
+ *
+ * The cache lives in `sessionStorage` so it survives the navigation from the
+ * page that creates the session to the checkout page that fetches it, but
+ * dies on tab close. An in-memory fallback keeps the SDK working in Node /
+ * SSR contexts where `sessionStorage` is unavailable.
+ *
+ * Values from the server response always win — cached values fill in only
+ * where the server returned `null` or `undefined`.
+ */
+/** Display-only fields per item that can be cached and merged back later. */
+interface SessionDisplayItem {
+    /** Catalog code (preferred match key). */
+    code?: string;
+    /** @deprecated Match key fallback when `code` is not provided. */
+    providerItemId?: string;
+    /** Display-only name for the item. Takes priority over `providerItemName`. */
+    itemName?: string | null;
+    /** @deprecated Use `itemName`. */
+    providerItemName?: string | null;
+    totalAmount?: number;
+    overrideAmount?: number | null;
+    currency?: string;
+}
+/** Display-only fields per subscription that can be cached and merged back later. */
+interface SessionDisplaySubscription {
+    /** Catalog code (preferred match key). */
+    code?: string;
+    /** @deprecated Match key fallback when `code` is not provided. */
+    providerPlanId?: string;
+    /** Display-only name for the subscription plan. Takes priority over `providerPlanName`. */
+    subscriptionName?: string | null;
+    /** @deprecated Use `subscriptionName`. */
+    providerPlanName?: string | null;
+    totalAmount?: number;
+    overrideAmount?: number | null;
+    currency?: string;
+}
+/** Display-only payload that can be stashed for later merge into a session response. */
+interface SessionDisplayCacheData {
+    /** Session-level currency (falls into the response only when the server omits it). */
+    currency?: string;
+    items?: SessionDisplayItem[];
+    subscriptions?: SessionDisplaySubscription[];
+}
+/**
+ * Stash display-only data for a session. Called client-side right after the
+ * server returns a session ID, so the values survive the redirect to the
+ * checkout page.
+ */
+declare function cacheSessionDisplayData(sessionId: string, data: SessionDisplayCacheData, options?: {
+    ttlMs?: number;
+}): void;
+/**
+ * Read previously-cached display data for a session, or `null` if nothing
+ * is cached (or the TTL has elapsed).
+ */
+declare function getSessionDisplayData(sessionId: string): SessionDisplayCacheData | null;
+/**
+ * Drop any cached display data for a session. Call from the success page
+ * after the payment completes; otherwise the TTL handles cleanup.
+ */
+declare function clearSessionDisplayData(sessionId: string): void;
+
 /** Raw billing API response wrapper. */
 interface BillingResponse<T> {
     data: T;
@@ -167,30 +234,53 @@ interface RawCheckoutSession {
     status: 'pending' | 'completed' | 'expired';
     successUrl: string;
     cancelUrl: string;
+    /** Session-level currency. Takes precedence over per-item/per-subscription currency. */
+    currency?: string;
     createdAt?: string;
     checkoutUrl?: string;
     items: Array<{
         uuid: string;
         checkoutSessionId: string;
-        providerItemId: string;
-        providerItemName: string;
+        /** Preferred catalog code. Falls back to the deprecated `providerItemId`. */
+        code?: string;
+        /** @deprecated Use `code`. */
+        providerItemId?: string;
+        /** Display-only name. Preferred over `providerItemName`. */
+        itemName?: string | null;
+        /** @deprecated Use `itemName`. Mirrored for backward compatibility. */
+        providerItemName?: string | null;
+        /** Display-only description from the catalog. */
         providerItemDescription?: string | null;
         quantity: number;
-        totalAmount: number;
-        overrideAmount: number | null;
-        currency: string;
+        /** @deprecated Removed from the backend — resolved from the catalog. */
+        totalAmount?: number;
+        /** @deprecated Removed from the backend entirely. */
+        overrideAmount?: number | null;
+        /** @deprecated Use the session-level `currency`. */
+        currency?: string;
         metadata?: Record<string, unknown> | null;
     }>;
     subscriptions: Array<{
         uuid: string;
         checkoutSessionId: string;
-        providerPlanId: string;
-        providerPlanName: string;
+        /** Preferred catalog code. Falls back to the deprecated `providerPlanId`. */
+        code?: string;
+        /** @deprecated Use `code`. */
+        providerPlanId?: string;
+        /** Display-only name. Preferred over `providerPlanName`. */
+        subscriptionName?: string | null;
+        /** @deprecated Use `subscriptionName`. Mirrored for backward compatibility. */
+        providerPlanName?: string | null;
+        /** Display-only description from the catalog. */
         providerPlanDescription?: string | null;
         quantity: number;
-        totalAmount: number;
-        overrideAmount: number | null;
-        currency: string;
+        /** @deprecated Removed from the backend — resolved from the catalog. */
+        totalAmount?: number;
+        /** @deprecated Removed from the backend entirely. */
+        overrideAmount?: number | null;
+        /** @deprecated Use the session-level `currency`. */
+        currency?: string;
+        /** @deprecated Removed from the backend. Checkouts only create new subscriptions. */
         isUpdate?: boolean;
         metadata?: Record<string, unknown> | null;
     }>;
@@ -232,6 +322,33 @@ declare class PaymentAPI {
     constructor(billingApiUrl: string);
     /** Fetch a raw checkout session by ID. */
     getCheckoutSession(checkoutSessionId: string): Promise<BillingResponse<RawCheckoutSession>>;
+    /**
+     * Stash display-only data for a session so subsequent fetches can fill in
+     * fields the backend no longer persists (`overrideAmount`, `totalAmount`,
+     * `providerItemName`, `providerPlanName`).
+     *
+     * Backed by `sessionStorage` in the browser, with an in-memory fallback in
+     * Node/SSR contexts. Default TTL: 1 hour.
+     *
+     * Server-returned values always win — cached values fill in only where the
+     * server returned `null` / `undefined`.
+     *
+     * @example
+     * ```ts
+     * paymentAPI.cacheSessionDisplayData(sessionId, {
+     *   currency: 'USD',
+     *   items: [{ code: 'pro_plan', overrideAmount: 24.99, providerItemName: 'Pro' }],
+     * });
+     * ```
+     */
+    cacheSessionDisplayData(sessionId: string, data: SessionDisplayCacheData, options?: {
+        ttlMs?: number;
+    }): void;
+    /**
+     * Drop any cached display data for a session. Call after the payment
+     * completes; otherwise the TTL handles cleanup.
+     */
+    clearSessionDisplayData(sessionId: string): void;
     /**
      * Fetch and normalize a checkout session.
      *
@@ -301,6 +418,24 @@ declare class PaymentAPI {
     private resolveProcessResponse;
     private toCheckoutProcessingPending;
     private clampRetryAfterMs;
+    /**
+     * Stash the display-only fields the consumer passed into a create-session
+     * call. Runs after the backend assigns a UUID so a later GET on the same
+     * session (typically after a redirect) can fill in fields the backend no
+     * longer persists — `overrideAmount`, `totalAmount`, `itemName`, etc.
+     *
+     * No-op when no UUID is available.
+     */
+    private autoCacheDisplayData;
+    /**
+     * Merge cached display-only fields (set by {@link cacheSessionDisplayData})
+     * into a raw session response and mirror the new/legacy name aliases so
+     * readers using either field always get a value when one exists.
+     *
+     * Server values always win — cache fills in only where the server returned
+     * `null` / `undefined`.
+     */
+    private mergeCachedDisplayData;
 }
 
 /**
@@ -321,11 +456,11 @@ declare class PaymentAPI {
  *   billingApiUrl: 'https://billing.example.com',
  *   checkoutBaseUrl: 'https://checkout.example.com',
  *   clientId: 'client_123',
+ *   currency: 'USD',
  *   items: [{
- *     providerItemId: 'prod_abc',
- *     providerItemName: 'Pro Plan',
- *     totalAmount: 49.99,
- *     overrideAmount: 24.99,
+ *     code: 'initial_charge',
+ *     quantity: 1,
+ *     metadata: { source: 'web' },
  *   }],
  *   account: { userId: 'user_1', email: 'user@example.com' },
  *   successUrl: '/success',
@@ -344,4 +479,4 @@ declare function createCheckoutSessionWithRetries(options: CreateSessionParams &
     maxRetries?: number;
 }): Promise<CheckoutSessionResult>;
 
-export { FloPay, FloPayElements, PaymentAPI, StripeAdapter, createCheckoutSession, createCheckoutSessionWithRetries, loadFloPay };
+export { FloPay, FloPayElements, PaymentAPI, type SessionDisplayCacheData, type SessionDisplayItem, type SessionDisplaySubscription, StripeAdapter, cacheSessionDisplayData, clearSessionDisplayData, createCheckoutSession, createCheckoutSessionWithRetries, getSessionDisplayData, loadFloPay };