@flopay/js 0.5.19 → 1.0.2

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,15 @@ declare class PaymentAPI {
     private resolveProcessResponse;
     private toCheckoutProcessingPending;
     private clampRetryAfterMs;
+    /**
+     * 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 +447,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 +470,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.mjs

@@ -447,7 +447,80 @@ var FloPayElements = class {
 };
 
 // src/payment-api.ts
-import { FloPayError as FloPayError3 } from "@flopay/shared";
+import {
+  FloPayError as FloPayError3,
+  buildItemPayload,
+  buildSubscriptionPayload,
+  resolveSessionCurrency
+} from "@flopay/shared";
+
+// src/session-display-cache.ts
+var STORAGE_KEY_PREFIX = "flopay_session_display:";
+var DEFAULT_TTL_MS = 60 * 60 * 1e3;
+var memoryStore = /* @__PURE__ */ new Map();
+function storageKey(sessionId) {
+  return `${STORAGE_KEY_PREFIX}${sessionId}`;
+}
+function getSessionStorage() {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.sessionStorage;
+  } catch {
+    return null;
+  }
+}
+function cacheSessionDisplayData(sessionId, data, options) {
+  if (!sessionId) return;
+  const ttl = options?.ttlMs ?? DEFAULT_TTL_MS;
+  const entry = { data, expiresAt: Date.now() + ttl };
+  const storage = getSessionStorage();
+  if (storage) {
+    try {
+      storage.setItem(storageKey(sessionId), JSON.stringify(entry));
+      return;
+    } catch {
+    }
+  }
+  memoryStore.set(sessionId, entry);
+}
+function getSessionDisplayData(sessionId) {
+  if (!sessionId) return null;
+  const storage = getSessionStorage();
+  if (storage) {
+    try {
+      const raw = storage.getItem(storageKey(sessionId));
+      if (raw) {
+        const entry = JSON.parse(raw);
+        if (entry && typeof entry.expiresAt === "number" && entry.expiresAt > Date.now()) {
+          return entry.data;
+        }
+        storage.removeItem(storageKey(sessionId));
+      }
+    } catch {
+    }
+  }
+  const memEntry = memoryStore.get(sessionId);
+  if (memEntry) {
+    if (memEntry.expiresAt > Date.now()) {
+      return memEntry.data;
+    }
+    memoryStore.delete(sessionId);
+  }
+  return null;
+}
+function clearSessionDisplayData(sessionId) {
+  if (!sessionId) return;
+  memoryStore.delete(sessionId);
+  const storage = getSessionStorage();
+  if (storage) {
+    try {
+      storage.removeItem(storageKey(sessionId));
+    } catch {
+    }
+  }
+}
+
+// src/payment-api.ts
 var DEFAULT_PROCESSING_RETRY_AFTER_MS = 1e3;
 var MIN_PROCESSING_RETRY_AFTER_MS = 500;
 var DEFAULT_PROCESSING_TIMEOUT_MS = 15e3;
@@ -495,7 +568,37 @@ var PaymentAPI = class {
     if (!response.ok) {
       throw await buildApiErrorFromResponse(response, "Failed to get checkout session");
     }
-    return response.json();
+    const body = await response.json();
+    return { ...body, data: this.mergeCachedDisplayData(body.data) };
+  }
+  /**
+   * 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, data, options) {
+    cacheSessionDisplayData(sessionId, data, options);
+  }
+  /**
+   * Drop any cached display data for a session. Call after the payment
+   * completes; otherwise the TTL handles cleanup.
+   */
+  clearSessionDisplayData(sessionId) {
+    clearSessionDisplayData(sessionId);
   }
   /**
    * Fetch and normalize a checkout session.
@@ -599,27 +702,19 @@ var PaymentAPI = class {
    * Falls back to create + GET if the backend doesn't support `expand`.
    */
   async createAndFetchSession(params) {
+    const sessionCurrency = resolveSessionCurrency(
+      params.currency,
+      params.items,
+      params.subscriptions
+    );
     const payload = {
       clientId: params.clientId,
       successUrl: params.successUrl,
       cancelUrl: params.cancelUrl,
+      currency: sessionCurrency,
       checkoutMode: params.checkoutMode ?? "full",
-      items: (params.items ?? []).map((item) => ({
-        providerItemId: item.providerItemId,
-        providerItemName: item.providerItemName ?? null,
-        quantity: item.quantity ?? 1,
-        totalAmount: item.totalAmount,
-        overrideAmount: item.overrideAmount ?? null,
-        currency: item.currency ?? "USD"
-      })),
-      subscriptions: (params.subscriptions ?? []).map((sub) => ({
-        providerPlanId: sub.providerPlanId,
-        providerPlanName: sub.providerPlanName ?? null,
-        quantity: sub.quantity ?? 1,
-        totalAmount: sub.totalAmount,
-        overrideAmount: sub.overrideAmount ?? null,
-        currency: sub.currency ?? "USD"
-      })),
+      items: (params.items ?? []).map((item) => buildItemPayload(item, sessionCurrency)),
+      subscriptions: (params.subscriptions ?? []).map((sub) => buildSubscriptionPayload(sub, sessionCurrency)),
       accountData: {
         userId: params.account.userId,
         firstName: params.account.firstName ?? null,
@@ -662,8 +757,9 @@ var PaymentAPI = class {
     }
     const body = await response.json();
     if (body.data && "gateway" in body.data) {
+      const merged = this.mergeCachedDisplayData(body.data);
       return {
-        ...this.normalizeRawSession(body.data),
+        ...this.normalizeRawSession(merged),
         autoProcessingError: body.autoProcessingError,
         autoProcessingAttempted: body.autoProcessingAttempted,
         autoProcessingPending: body.autoProcessingPending
@@ -752,10 +848,11 @@ var PaymentAPI = class {
   /** Convert raw session to the SDK CheckoutSession shape. */
   toCheckoutSession(raw) {
     const totalAmount = [
-      ...raw.subscriptions.map((s) => s.overrideAmount || s.totalAmount),
-      ...raw.items.map((i) => i.overrideAmount || i.totalAmount)
+      ...raw.subscriptions.map((s) => s.overrideAmount ?? s.totalAmount ?? 0),
+      ...raw.items.map((i) => i.overrideAmount ?? i.totalAmount ?? 0)
     ].reduce((sum, val) => sum + val, 0);
     const amountInCents = Math.round(totalAmount * 100);
+    const currency = raw.currency ?? raw.subscriptions[0]?.currency ?? raw.items[0]?.currency ?? "USD";
     return {
       // Core fields (backward compat)
       id: raw.uuid,
@@ -763,7 +860,7 @@ var PaymentAPI = class {
       mode: raw.subscriptions.length > 0 ? "subscription" : "payment",
       status: this.toCheckoutSessionStatus(raw.status),
       amount: amountInCents,
-      currency: raw.subscriptions[0]?.currency ?? raw.items[0]?.currency ?? "USD",
+      currency,
       customer: {
         id: raw.accountData.userId,
         email: raw.accountData.email,
@@ -840,6 +937,57 @@ var PaymentAPI = class {
   clampRetryAfterMs(retryAfterMs) {
     return Math.max(0, Math.min(retryAfterMs, MAX_PROCESSING_RETRY_AFTER_MS));
   }
+  /**
+   * 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`.
+   */
+  mergeCachedDisplayData(raw) {
+    const cached = getSessionDisplayData(raw.uuid);
+    const cachedItems = /* @__PURE__ */ new Map();
+    for (const item of cached?.items ?? []) {
+      const key = item.code ?? item.providerItemId;
+      if (key) cachedItems.set(key, item);
+    }
+    const cachedSubs = /* @__PURE__ */ new Map();
+    for (const sub of cached?.subscriptions ?? []) {
+      const key = sub.code ?? sub.providerPlanId;
+      if (key) cachedSubs.set(key, sub);
+    }
+    return {
+      ...raw,
+      currency: raw.currency ?? cached?.currency,
+      items: raw.items.map((item) => {
+        const key = item.code ?? item.providerItemId;
+        const fallback = key ? cachedItems.get(key) : void 0;
+        const resolvedName = item.itemName ?? item.providerItemName ?? fallback?.itemName ?? fallback?.providerItemName;
+        return {
+          ...item,
+          itemName: resolvedName,
+          providerItemName: resolvedName,
+          totalAmount: item.totalAmount ?? fallback?.totalAmount,
+          overrideAmount: item.overrideAmount ?? fallback?.overrideAmount,
+          currency: item.currency ?? fallback?.currency
+        };
+      }),
+      subscriptions: raw.subscriptions.map((sub) => {
+        const key = sub.code ?? sub.providerPlanId;
+        const fallback = key ? cachedSubs.get(key) : void 0;
+        const resolvedName = sub.subscriptionName ?? sub.providerPlanName ?? fallback?.subscriptionName ?? fallback?.providerPlanName;
+        return {
+          ...sub,
+          subscriptionName: resolvedName,
+          providerPlanName: resolvedName,
+          totalAmount: sub.totalAmount ?? fallback?.totalAmount,
+          overrideAmount: sub.overrideAmount ?? fallback?.overrideAmount,
+          currency: sub.currency ?? fallback?.currency
+        };
+      })
+    };
+  }
 };
 
 // src/flopay.ts
@@ -973,6 +1121,11 @@ async function loadFloPay(publishableKey, options) {
 }
 
 // src/create-checkout-session.ts
+import {
+  buildItemPayload as buildItemPayload2,
+  buildSubscriptionPayload as buildSubscriptionPayload2,
+  resolveSessionCurrency as resolveSessionCurrency2
+} from "@flopay/shared";
 async function createCheckoutSession(options) {
   const {
     billingApiUrl,
@@ -989,29 +1142,18 @@ async function createCheckoutSession(options) {
     setCookie = true,
     timeoutMs = 12e3,
     clientId,
+    currency,
     utmMetadata
   } = options;
+  const sessionCurrency = resolveSessionCurrency2(currency, items, subscriptions);
   const payload = {
     clientId,
     successUrl,
     cancelUrl,
+    currency: sessionCurrency,
     checkoutMode,
-    items: items.map((item) => ({
-      providerItemId: item.providerItemId,
-      providerItemName: item.providerItemName ?? null,
-      quantity: item.quantity ?? 1,
-      totalAmount: item.totalAmount,
-      overrideAmount: item.overrideAmount ?? null,
-      currency: item.currency ?? "USD"
-    })),
-    subscriptions: subscriptions.map((sub) => ({
-      providerPlanId: sub.providerPlanId,
-      providerPlanName: sub.providerPlanName ?? null,
-      quantity: sub.quantity ?? 1,
-      totalAmount: sub.totalAmount,
-      overrideAmount: sub.overrideAmount ?? null,
-      currency: sub.currency ?? "USD"
-    })),
+    items: items.map((item) => buildItemPayload2(item, sessionCurrency)),
+    subscriptions: subscriptions.map((sub) => buildSubscriptionPayload2(sub, sessionCurrency)),
     accountData: {
       userId: account.userId,
       firstName: account.firstName ?? null,
@@ -1106,8 +1248,11 @@ export {
   FloPayElements,
   PaymentAPI,
   StripeAdapter,
+  cacheSessionDisplayData,
+  clearSessionDisplayData,
   createCheckoutSession,
   createCheckoutSessionWithRetries,
+  getSessionDisplayData,
   loadFloPay
 };
 //# sourceMappingURL=index.mjs.map