@flopay/shared 1.0.3 → 1.1.3

package/README.md

@@ -79,9 +79,13 @@ throw validationError('Email is required', 'email');
 | `ButtonsLayoutStyles` | Style overrides for the `buttons` layout: `cardButton`, `cardButtonFontSize`, `cardFormContainer`, `cardInputBorder`, `cardInputColor`, `cardInputPlaceholderColor`, `cardInputFontSize`, `cardInputBackground`, `nameInput`, `backButton`, `backButtonFontSize`, `backButtonIcon`, `submitButton`, `submitButtonFontSize`, `title`, `titleFontSize`, `errorBanner` |
 | `ButtonsLayoutTheme` | Theme preset name: `'default'` / `'minimal'` / `'rounded'` / `'dark'` |
 | `CheckoutMode` | Checkout mode: `'full'` / `'auto'` / `'confirm'` |
-| `CheckoutSession` | Session object: `id`, `clientSecret`, `mode`, `status`, `amount`, `currency`, `customer?`, `checkoutMode?`, `items?`, `subscriptions?`, `successUrl?`, `cancelUrl?`, `coupons?`, `gateway?`, `gatewayData?` (includes `publishableKey?` + `paypalPublishableKey?` — null disables PayPal), `accountData?`, `tagsData?` |
-| `CheckoutSessionItem` | Session item from billing API: `uuid`, `providerItemId`, `providerItemName`, `quantity`, `totalAmount`, `overrideAmount`, `currency` |
-| `CheckoutSessionSubscription` | Session subscription from billing API: `uuid`, `providerPlanId`, `providerPlanName`, `quantity`, `totalAmount`, `overrideAmount`, `currency` |
+| `CheckoutSession` | Session object: `id`, `clientSecret`, `mode`, `status`, `amount`, `currency`, `customer?`, `checkoutMode?`, `products?` (unified `CheckoutSessionProduct[]`), `successUrl?`, `cancelUrl?`, `coupons?`, `subtotalAmount?` / `discountAmount?` / `totalAmount?` (cart-currency major units; populated by billing API ≥ v1.1.2), `gateways?` (map keyed by gateway code — `stripe`, `paypal`, …), `accountData?`, `tagsData?` |
+| `CheckoutSessionProduct` | Unified product from session response: `uuid`, `checkoutSessionId`, `type` (`'item'`/`'subscription'`), `code?`, `name?`, `description?`, `quantity`, `totalAmount?`, `overrideAmount?`, `currency?`, `metadata?` |
+| `CheckoutProductType` | `'item'` / `'subscription'` |
+| `CheckoutProduct` | Unified product input for session creation: `type`, `code?`, `name?`, `quantity?`, `totalAmount?`, `overrideAmount?`, `currency?`, `metadata?` |
+| `CheckoutGateway` | Per-gateway config: `publishableKey?`, `environment?` (`'sandbox'`/`'live'`), `stripeClientSecret?` (Stripe-only) |
+| `CheckoutGateways` | Map keyed by gateway code (e.g. `stripe`, `paypal`). A session can advertise multiple concurrent gateways. |
+| `GatewayEnvironment` | `'sandbox'` / `'live'` — drives the PayPal JS SDK script and any other environment-scoped behavior |
 | `PaymentResult` | Payment outcome: `status` (`'succeeded'`/`'processing'`/`'requires_action'`/`'failed'`), `paymentIntentId?`, `error?` |
 | `ConfirmPaymentParams` | `clientSecret`, `returnUrl?` |
 | `CreatePaymentMethodResult` | `paymentMethodId`, `error?` |
@@ -100,7 +104,7 @@ throw validationError('Email is required', 'email');
 | `TokenizedBody` | `id?`, `type?`, `threeDSecureActionResultTokenId?`, `originalPaymentMethodId?`, `isPaypal?` |
 | `NormalizedCheckoutSession` | Provider-agnostic session: `provider`, `mode`, `data`, `raw?` |
 | `CheckoutModeKind` | `'tokenize'` / `'redirect'` |
-| `CreateSessionParams` | Full session creation params: `billingApiUrl`, `checkoutBaseUrl`, `clientId`, `items?`, `subscriptions?`, `account`, `successUrl`, `cancelUrl`, `checkoutMode?`, `couponCodes?`, `tagsData?`, `redirectParams?`, `setCookie?`, `timeoutMs?`, `utmMetadata?` |
+| `CreateSessionParams` | Full session creation params: `billingApiUrl`, `checkoutBaseUrl`, `clientId`, `currency` (required — SDK throws `FloPayError({ type: 'validation_error', code: 'CurrencyRequired' })` before issuing the request when none can be resolved), `products?` (unified shape; takes precedence), `items?`, `subscriptions?` (legacy — folded into `products[]` before send), `account`, `successUrl`, `cancelUrl`, `checkoutMode?`, `couponCodes?`, `tagsData?`, `redirectParams?`, `setCookie?`, `timeoutMs?`, `utmMetadata?` |
 | `CheckoutSessionResult` | `{ status: 201; redirectUrl }` / `{ status: 204 }` / `{ status: number }` |
 | `CheckoutItem` | `providerItemId`, `providerItemName?`, `quantity?`, `totalAmount`, `overrideAmount?`, `currency?` |
 | `CheckoutSubscription` | `providerPlanId`, `providerPlanName?`, `quantity?`, `totalAmount`, `overrideAmount?`, `currency?` |

package/dist/index.cjs

@@ -45,8 +45,10 @@ __export(index_exports, {
   authenticationError: () => authenticationError,
   buildCheckoutDisplayData: () => buildCheckoutDisplayData,
   buildItemPayload: () => buildItemPayload,
+  buildProductPayload: () => buildProductPayload,
   buildSubscriptionPayload: () => buildSubscriptionPayload,
   configureFlopay: () => configureFlopay,
+  foldIntoProducts: () => foldIntoProducts,
   getConfiguredBillingApiUrl: () => getConfiguredBillingApiUrl,
   getCountryByCode: () => getCountryByCode,
   getCurrencyByCountry: () => getCurrencyByCountry,
@@ -60,6 +62,7 @@ __export(index_exports, {
   isValidPublishableKey: () => isValidPublishableKey,
   isValidSecretKey: () => isValidSecretKey,
   networkError: () => networkError,
+  normalizeGatewayEnvironment: () => normalizeGatewayEnvironment,
   rateLimitError: () => rateLimitError,
   resolveAVSConfig: () => resolveAVSConfig,
   resolveBillingApiUrl: () => resolveBillingApiUrl,
@@ -69,6 +72,24 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/types.ts
+function normalizeGatewayEnvironment(env) {
+  if (env == null) return void 0;
+  switch (env) {
+    case "sandbox":
+    case "stage":
+      return "sandbox";
+    case "live":
+    case "production":
+      return "live";
+    default:
+      console.warn(
+        `[FloPay] Unrecognized gateway environment "${env}". Expected one of: sandbox, live, stage, production. Falling back to undefined.`
+      );
+      return void 0;
+  }
+}
+
 // src/errors.ts
 var FloPayError = class extends Error {
   constructor(message, type, options) {
@@ -116,7 +137,7 @@ function getFloPayEnvironment() {
 }
 
 // src/constants.ts
-var SDK_VERSION = "1.0.3";
+var SDK_VERSION = "1.1.3";
 var BILLING_API_URL_STAGING = "https://api.stage.flopay.com";
 var BILLING_API_URL_PRODUCTION = "https://api.flopay.com";
 var DEFAULT_API_BASE_URL = BILLING_API_URL_STAGING;
@@ -775,7 +796,7 @@ function nonBlank(value) {
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : void 0;
 }
-function resolveSessionCurrency(sessionCurrency, items, subscriptions) {
+function resolveSessionCurrency(sessionCurrency, items, subscriptions, products) {
   const session = nonBlank(sessionCurrency);
   if (session) return session;
   for (const item of items ?? []) {
@@ -786,7 +807,67 @@ function resolveSessionCurrency(sessionCurrency, items, subscriptions) {
     const c = nonBlank(sub.currency);
     if (c) return c;
   }
-  return "USD";
+  for (const product of products ?? []) {
+    const c = nonBlank(product.currency);
+    if (c) return c;
+  }
+  return null;
+}
+function foldIntoProducts(items, subscriptions) {
+  const products = [];
+  for (const sub of subscriptions ?? []) {
+    products.push({
+      type: "subscription",
+      code: nonBlank(sub.code) ?? nonBlank(sub.providerPlanId),
+      providerPlanId: sub.providerPlanId,
+      name: nonBlank(sub.subscriptionName) ?? nonBlank(sub.providerPlanName) ?? null,
+      subscriptionName: sub.subscriptionName ?? null,
+      providerPlanName: sub.providerPlanName ?? null,
+      quantity: sub.quantity,
+      totalAmount: sub.totalAmount,
+      overrideAmount: sub.overrideAmount,
+      currency: sub.currency,
+      metadata: sub.metadata
+    });
+  }
+  for (const item of items ?? []) {
+    products.push({
+      type: "item",
+      code: nonBlank(item.code) ?? nonBlank(item.providerItemId),
+      providerItemId: item.providerItemId,
+      name: nonBlank(item.itemName) ?? nonBlank(item.providerItemName) ?? null,
+      itemName: item.itemName ?? null,
+      providerItemName: item.providerItemName ?? null,
+      quantity: item.quantity,
+      totalAmount: item.totalAmount,
+      overrideAmount: item.overrideAmount,
+      currency: item.currency,
+      metadata: item.metadata
+    });
+  }
+  return products;
+}
+function buildProductPayload(product, sessionCurrency) {
+  const code = nonBlank(product.code) ?? nonBlank(product.providerItemId) ?? nonBlank(product.providerPlanId);
+  if (!code) {
+    throw new Error(
+      "CheckoutProduct requires `code` (or the deprecated `providerItemId` / `providerPlanId`)."
+    );
+  }
+  const name = nonBlank(product.name) ?? nonBlank(product.itemName) ?? nonBlank(product.providerItemName) ?? nonBlank(product.subscriptionName) ?? nonBlank(product.providerPlanName) ?? null;
+  const payload = {
+    type: product.type,
+    code,
+    name,
+    quantity: product.quantity ?? 1,
+    totalAmount: product.totalAmount,
+    overrideAmount: product.overrideAmount ?? null,
+    currency: nonBlank(product.currency) ?? sessionCurrency
+  };
+  if (product.metadata) {
+    payload["metadata"] = product.metadata;
+  }
+  return payload;
 }
 function buildItemPayload(item, sessionCurrency) {
   const code = nonBlank(item.code) ?? nonBlank(item.providerItemId);
@@ -836,13 +917,15 @@ function buildSubscriptionPayload(subscription, sessionCurrency) {
 // src/display.ts
 function buildCheckoutDisplayData(session, options = {}) {
   const itemsList = [];
-  const subscriptions = session.subscriptions ?? [];
-  const items = session.items ?? [];
-  const currency = resolveSessionCurrency(session.currency, items, subscriptions).toUpperCase();
+  const products = session.products ?? [];
+  const subscriptions = products.filter((p) => p.type === "subscription");
+  const items = products.filter((p) => p.type === "item");
+  const resolvedCurrency = resolveSessionCurrency(session.currency, void 0, void 0, products);
+  const currency = (resolvedCurrency ?? "USD").toUpperCase();
   for (const sub of subscriptions) {
     const originalPrice = sub.totalAmount ?? 0;
     const discountedPrice = sub.overrideAmount ?? originalPrice;
-    let name = sub.subscriptionName || sub.providerPlanName || sub.code || "Subscription";
+    let name = sub.name || sub.code || "Subscription";
     if (name === "4-WEEK PLAN" && discountedPrice <= 1) {
       name = "7-DAY TRIAL: FULL ACCESS";
     }
@@ -859,7 +942,7 @@ function buildCheckoutDisplayData(session, options = {}) {
       const originalPrice = item.totalAmount ?? 0;
       const discountedPrice = item.overrideAmount ?? originalPrice;
       itemsList.push({
-        name: item.itemName || item.providerItemName || item.code || "Item",
+        name: item.name || item.code || "Item",
         quantity: item.quantity,
         price: discountedPrice,
         originalPrice
@@ -874,8 +957,13 @@ function buildCheckoutDisplayData(session, options = {}) {
       originalPrice: session.amount / 100
     });
   }
-  const originalTotal = itemsList.reduce((sum, i) => sum + i.originalPrice * i.quantity, 0);
-  const total = itemsList.reduce((sum, i) => sum + i.price * i.quantity, 0);
+  const lineOriginalTotal = itemsList.reduce((sum, i) => sum + i.originalPrice * i.quantity, 0);
+  const lineTotal = itemsList.reduce((sum, i) => sum + i.price * i.quantity, 0);
+  const hasBackendTotals = typeof session.totalAmount === "number" && Number.isFinite(session.totalAmount);
+  const hasBackendSubtotal = typeof session.subtotalAmount === "number" && Number.isFinite(session.subtotalAmount);
+  const hasBackendDiscount = typeof session.discountAmount === "number" && Number.isFinite(session.discountAmount);
+  const total = hasBackendTotals ? session.totalAmount : lineTotal;
+  const originalTotal = hasBackendSubtotal ? session.subtotalAmount : lineOriginalTotal;
   const totalSave = Math.max(0, originalTotal - total);
   const discountPercent = originalTotal > 0 ? Math.round(totalSave / originalTotal * 100) : 0;
   return {
@@ -884,7 +972,8 @@ function buildCheckoutDisplayData(session, options = {}) {
     total,
     originalTotal,
     totalSave,
-    discountPercent
+    discountPercent,
+    ...hasBackendDiscount ? { couponDiscount: session.discountAmount } : {}
   };
 }
 
@@ -925,8 +1014,10 @@ function isValidSecretKey(key) {
   authenticationError,
   buildCheckoutDisplayData,
   buildItemPayload,
+  buildProductPayload,
   buildSubscriptionPayload,
   configureFlopay,
+  foldIntoProducts,
   getConfiguredBillingApiUrl,
   getCountryByCode,
   getCurrencyByCountry,
@@ -940,6 +1031,7 @@ function isValidSecretKey(key) {
   isValidPublishableKey,
   isValidSecretKey,
   networkError,
+  normalizeGatewayEnvironment,
   rateLimitError,
   resolveAVSConfig,
   resolveBillingApiUrl,