@funnelfox/billing 0.8.0-beta.3 → 0.8.0-ffb-395.4

package/README.md

@@ -11,6 +11,7 @@ A modern TypeScript SDK for subscription payments with Primer Headless Checkout
 - 🔧 **Robust**: Built-in error handling, retries, and validation
 - 📦 **Lightweight**: Minimal dependencies, browser-optimized
 - 🎨 **Headless Checkout**: Full control over checkout UI with Primer Headless Checkout
+- 💳 **Stripe Integration**: Native Stripe Elements card form and Apple Pay / Google Pay wallets
 
 ## Installation
 
@@ -711,6 +712,216 @@ const headlessCheckout = await Primer.createHeadless(session.clientToken, {
 await headlessCheckout.start();
 ```
 
+## Stripe Integration
+
+The `Billing.stripe` namespace provides a Stripe-native checkout experience — no Primer dependency required. It supports card payments via Stripe Elements and native wallet payments (Apple Pay / Google Pay) via the Payment Request API.
+
+> **Note:** `@primer-io/checkout-web` is **not** required for Stripe integration. Only `@funnelfox/billing` and a Stripe-enabled price in your Funnelfox account are needed.
+
+---
+
+### `Billing.stripe.createCardForm(element, params)`
+
+Mounts a Stripe Elements payment form into a DOM element. Returns a `{ submit() }` handle — you control when payment is triggered (e.g. on your own button click).
+
+```javascript
+const element = document.getElementById('card-form');
+
+const cardForm = await Billing.stripe.createCardForm(element, {
+  // Required
+  priceId: 'price_123',
+  externalId: 'user_456',
+
+  // Optional
+  orgId: 'your-org-id',
+  email: 'user@example.com',
+  countryCode: 'US',
+  showWallets: false, // show Apple Pay / Google Pay inside the form
+  appearance: {
+    // Stripe Elements appearance API
+    theme: 'stripe',
+  },
+
+  // Callbacks
+  onRenderSuccess: () => {
+    document.getElementById('pay-button').disabled = false;
+  },
+  onLoaderChange: loading => {
+    document.getElementById('pay-button').disabled = loading;
+  },
+  onPaymentSuccess: (paymentMethod, orderId) => {
+    window.location.href = '/success?order=' + orderId;
+  },
+  onPaymentFail: error => {
+    console.error('Payment failed:', error.message);
+  },
+});
+
+// Wire up your own submit button
+document.getElementById('pay-button').addEventListener('click', async () => {
+  await cardForm.submit();
+});
+```
+
+**Key parameters:**
+
+| Parameter        | Type     | Description                                                                       |
+| ---------------- | -------- | --------------------------------------------------------------------------------- |
+| `priceId`        | string   | Price identifier                                                                  |
+| `externalId`     | string   | Your user identifier                                                              |
+| `email`          | string?  | Customer email                                                                    |
+| `orgId`          | string?  | Org ID (if not globally configured)                                               |
+| `showWallets`    | boolean? | Show Apple Pay / Google Pay inside the Stripe form                                |
+| `appearance`     | object?  | [Stripe Elements Appearance API](https://stripe.com/docs/elements/appearance-api) |
+| `clientMetadata` | object?  | Custom metadata attached to the order                                             |
+
+**Returns:** `Promise<{ submit: () => Promise<void> }>`
+
+---
+
+### `Billing.stripe.getAvailableWallet(params)`
+
+Checks whether Apple Pay or Google Pay is available on the current device and browser. Use this to conditionally show a wallet button before attempting payment.
+
+```javascript
+const wallet = await Billing.stripe.getAvailableWallet({
+  priceId: 'price_123',
+  externalId: 'user_456',
+});
+
+if (wallet === 'APPLE_PAY') {
+  document.getElementById('apple-pay-btn').style.display = 'block';
+} else if (wallet === 'GOOGLE_PAY') {
+  document.getElementById('google-pay-btn').style.display = 'block';
+} else {
+  // No wallet available — show card form only
+}
+```
+
+**Returns:** `Promise<'APPLE_PAY' | 'GOOGLE_PAY' | null>`
+
+---
+
+### `Billing.stripe.purchaseWallet(params)`
+
+Triggers the native Apple Pay or Google Pay payment sheet. Call this on button click after confirming a wallet is available via `getAvailableWallet`.
+
+```javascript
+document.getElementById('wallet-btn').addEventListener('click', async () => {
+  await Billing.stripe.purchaseWallet({
+    priceId: 'price_123',
+    externalId: 'user_456',
+    totalLabel: 'Premium Plan', // Label shown in the payment sheet
+
+    onPaymentSuccess: (paymentMethod, orderId) => {
+      window.location.href = '/success?order=' + orderId;
+    },
+    onPaymentFail: error => {
+      console.error('Wallet payment failed:', error.message);
+    },
+    onPaymentCancel: () => {
+      console.log('User cancelled');
+    },
+    onLoaderChange: loading => {
+      document.getElementById('wallet-btn').disabled = loading;
+    },
+  });
+});
+```
+
+**Key parameters:**
+
+| Parameter        | Type    | Description                                         |
+| ---------------- | ------- | --------------------------------------------------- |
+| `priceId`        | string  | Price identifier                                    |
+| `externalId`     | string  | Your user identifier                                |
+| `totalLabel`     | string? | Label shown next to the amount in the payment sheet |
+| `email`          | string? | Customer email                                      |
+| `clientMetadata` | object? | Custom metadata attached to the order               |
+
+---
+
+### `Billing.stripe.getAvailablePaymentMethods(params)`
+
+Returns all Stripe payment methods available for the current device. Always includes `PAYMENT_CARD`; also includes a wallet method if one is detected.
+
+```javascript
+const methods = await Billing.stripe.getAvailablePaymentMethods({
+  priceId: 'price_123',
+  externalId: 'user_456',
+});
+
+// methods: ['PAYMENT_CARD', 'APPLE_PAY'] or ['PAYMENT_CARD'] etc.
+console.log('Available:', methods);
+```
+
+**Returns:** `Promise<PaymentMethod[]>` — always contains `PAYMENT_CARD`, optionally `APPLE_PAY` or `GOOGLE_PAY`
+
+---
+
+### Combined Example: Wallet Detection + Card Form Fallback
+
+The recommended pattern — show a wallet button when available, always show the card form as fallback:
+
+```javascript
+import { Billing } from '@funnelfox/billing';
+
+Billing.configure({ orgId: 'your-org-id' });
+
+const params = {
+  priceId: 'price_123',
+  externalId: 'user_456',
+  email: 'user@example.com',
+};
+
+async function initCheckout() {
+  // 1. Check for wallet availability
+  const wallet = await Billing.stripe.getAvailableWallet(params);
+
+  if (wallet) {
+    const walletBtn = document.getElementById('wallet-btn');
+    walletBtn.textContent =
+      wallet === 'APPLE_PAY' ? 'Pay with Apple Pay' : 'Pay with Google Pay';
+    walletBtn.style.display = 'block';
+
+    walletBtn.addEventListener('click', () => {
+      Billing.stripe.purchaseWallet({
+        ...params,
+        totalLabel: 'Premium Plan',
+        onPaymentSuccess: (_, orderId) => {
+          window.location.href = '/success?order=' + orderId;
+        },
+        onPaymentFail: err => alert(err.message),
+        onPaymentCancel: () => console.log('Cancelled'),
+      });
+    });
+  }
+
+  // 2. Always mount card form as fallback
+  const cardForm = await Billing.stripe.createCardForm(
+    document.getElementById('card-form'),
+    {
+      ...params,
+      onPaymentSuccess: (_, orderId) => {
+        window.location.href = '/success?order=' + orderId;
+      },
+      onPaymentFail: err => alert(err.message),
+      onLoaderChange: loading => {
+        document.getElementById('pay-btn').disabled = loading;
+      },
+    }
+  );
+
+  document.getElementById('pay-btn').addEventListener('click', () => {
+    cardForm.submit();
+  });
+}
+
+initCheckout();
+```
+
+---
+
 ## Browser Support
 
 - Chrome 60+

package/dist/chunk-index.cjs.js

@@ -491,7 +491,7 @@ exports.PaymentMethod = void 0;
 /**
  * @fileoverview Constants for Funnefox SDK
  */
-const SDK_VERSION = '0.8.0-beta.3';
+const SDK_VERSION = '0.9.0-beta.1';
 const DEFAULTS = {
     BASE_URL: 'https://billing.funnelfox.com',
     REGION: 'default',
@@ -530,6 +530,7 @@ const API_ENDPOINTS = {
     UPDATE_CLIENT_SESSION: '/v1/checkout/update_client_session',
     CREATE_PAYMENT: '/v1/checkout/create_payment',
     RESUME_PAYMENT: '/v1/checkout/resume_payment',
+    STRIPE_CREATE_PAYMENT: '/v1/stripe/create_payment',
     ONE_CLICK: '/v1/checkout/one_click',
     CREATE_SIMPLE_CLIENT_SESSION: '/v1/checkout/create_simple_client_session',
 };
@@ -1059,6 +1060,9 @@ class PrimerWrapper {
         }
         return element;
     }
+    refreshClientSession() {
+        return this.currentHeadless?.then(headless => headless.refreshClientSession());
+    }
 }
 PrimerWrapper.headlessManager = new HeadlessManager();
 
@@ -1125,7 +1129,7 @@ class APIClient {
     async createClientSession(params) {
         const payload = {
             region: params.region || 'default',
-            integration_type: 'primer',
+            integration_type: params.integration ?? 'primer',
             pp_ident: params.priceId,
             external_id: params.externalId,
             email_address: params.email,
@@ -1171,6 +1175,15 @@ class APIClient {
             body: JSON.stringify(payload),
         }));
     }
+    async createStripePayment(params) {
+        return (await this.request(API_ENDPOINTS.STRIPE_CREATE_PAYMENT, {
+            method: 'POST',
+            body: JSON.stringify({
+                order_id: params.orderId,
+                payment_method_id: params.paymentMethodId,
+            }),
+        }));
+    }
     async resumePayment(params) {
         const payload = {
             order_id: params.orderId,
@@ -1261,6 +1274,45 @@ class APIClient {
     }
 }
 
+class SessionService {
+    constructor() {
+        this.cache = new Map();
+    }
+    buildCacheKey(p) {
+        return [p.orgId, p.priceId, p.externalId, p.email, p.integration].join('-');
+    }
+    makeClient(orgId, baseUrl) {
+        return new APIClient({
+            baseUrl: baseUrl || DEFAULTS.BASE_URL,
+            orgId,
+            timeout: DEFAULTS.REQUEST_TIMEOUT,
+            retryAttempts: DEFAULTS.RETRY_ATTEMPTS,
+        });
+    }
+    createSession(p) {
+        const key = this.buildCacheKey(p);
+        const cached = this.cache.get(key);
+        if (cached)
+            return cached;
+        const client = this.makeClient(p.orgId, p.baseUrl);
+        const req = client.createClientSession({
+            priceId: p.priceId,
+            externalId: p.externalId,
+            email: p.email,
+            region: p.region || DEFAULTS.REGION,
+            clientMetadata: p.clientMetadata,
+            countryCode: p.countryCode,
+            integration: p.integration,
+        });
+        this.cache.set(key, req);
+        return req;
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+}
+var sessionService = new SessionService();
+
 var loaderHtml = "<div class=\"ff-sdk-loader-container\">\n  <div class=\"ff-sdk-loader\"></div>\n</div>\n";
 
 if(typeof document!=="undefined")document.head.appendChild(document.createElement("style")).textContent=".ff-sdk-loader-container {\n    position: absolute;\n    top: 0;\n    left: 0;\n    width: 100%;\n    height: 100%;\n    display: flex;\n    justify-content: center;\n    align-items: center;\n    background-color: rgba(255, 255, 255);\n    z-index: 2;\n}\n\n.ff-sdk-loader {\n    width: 24px;\n    height: 24px;\n    border: 4px solid #e32f41;\n    border-top: 4px solid transparent;\n    border-radius: 50%;\n    animation: spin 1s linear infinite;\n}\n\n@keyframes spin {\n    0% {\n      transform: rotate(0deg);\n    }\n    100% {\n      transform: rotate(360deg);\n    }\n  }";
@@ -1855,6 +1907,12 @@ class CheckoutInstance extends EventEmitter {
         this.cardEmailAddress = this.checkoutConfig.customer.email;
         this.shouldApplySessionCardholderNameConfig =
             this.checkoutConfig.card?.cardholderName?.required === undefined;
+        this.apiClient = new APIClient({
+            baseUrl: this.baseUrl || DEFAULTS.BASE_URL,
+            orgId: this.orgId,
+            timeout: DEFAULTS.REQUEST_TIMEOUT,
+            retryAttempts: DEFAULTS.RETRY_ATTEMPTS,
+        });
         this._setupCallbackBridges();
     }
     _setupCallbackBridges() {
@@ -1896,68 +1954,38 @@ class CheckoutInstance extends EventEmitter {
         }
     }
     async createSession() {
-        this.apiClient = new APIClient({
-            baseUrl: this.baseUrl || DEFAULTS.BASE_URL,
+        const response = await sessionService.createSession({
             orgId: this.orgId,
-            timeout: DEFAULTS.REQUEST_TIMEOUT,
-            retryAttempts: DEFAULTS.RETRY_ATTEMPTS,
-        });
-        const sessionParams = {
+            baseUrl: this.baseUrl,
             priceId: this.checkoutConfig.priceId,
             externalId: this.checkoutConfig.customer.externalId,
             email: this.checkoutConfig.customer.email,
-            region: this.region || DEFAULTS.REGION,
+            region: this.region,
             clientMetadata: this.checkoutConfig.clientMetadata,
             countryCode: this.checkoutConfig.customer.countryCode,
-        };
-        const cacheKey = [
-            this.orgId,
-            this.checkoutConfig.priceId,
-            this.checkoutConfig.customer.externalId,
-            this.checkoutConfig.customer.email,
-        ].join('-');
-        let sessionResponse;
-        // Return cached response if payload hasn't changed
-        const cachedResponse = CheckoutInstance.sessionCache.get(cacheKey);
-        if (cachedResponse) {
-            sessionResponse = await cachedResponse;
-        }
-        else {
-            const sessionRequest = this.apiClient
-                .createClientSession(sessionParams)
-                .then((response) => {
-                const cachedResponse = response;
-                if (response.data?.stripe_public_key) {
-                    const stripePublicKey = response.data.stripe_public_key;
-                    cachedResponse.radarSessionId = loadStripe(stripePublicKey)
-                        .then(stripe => stripe
-                        ? stripe
-                            .createRadarSession()
-                            .then(session => session?.radarSession?.id || '')
-                            .catch(() => '')
-                        : '')
-                        .catch(() => '');
-                }
-                // Initialize Airwallex device fingerprinting if enabled by backend
-                if (response.data?.airwallex_risk_enabled) {
-                    const isLivemode = response.data?.is_livemode;
-                    const deviceId = generateUUID();
-                    cachedResponse.airwallexDeviceId = loadAirwallexDeviceFingerprint(deviceId, isLivemode)
-                        .then(() => deviceId)
-                        .catch(() => {
-                        // Silently fail - return deviceId anyway
-                        return deviceId;
-                    });
-                }
-                return cachedResponse;
-            });
-            // Cache the successful response
-            CheckoutInstance.sessionCache.set(cacheKey, sessionRequest);
-            sessionResponse = await sessionRequest;
+            integration: 'primer',
+        });
+        const sessionResponse = response;
+        if (response.data?.stripe_public_key) {
+            const stripePublicKey = response.data.stripe_public_key;
+            sessionResponse.radarSessionId = loadStripe(stripePublicKey)
+                .then(stripe => stripe
+                ? stripe
+                    .createRadarSession()
+                    .then(session => session?.radarSession?.id || '')
+                    .catch(() => '')
+                : '')
+                .catch(() => '');
+        }
+        if (response.data?.airwallex_risk_enabled) {
+            const isLivemode = response.data?.is_livemode;
+            const deviceId = generateUUID();
+            sessionResponse.airwallexDeviceId = loadAirwallexDeviceFingerprint(deviceId, isLivemode)
+                .then(() => deviceId)
+                .catch(() => deviceId);
         }
         this.cachedSessionResponse = sessionResponse;
-        this.isTelemetryEnabled =
-            !!sessionResponse.data?.sdk_telemetry_enabled || true;
+        this.isTelemetryEnabled = !!sessionResponse.data?.sdk_telemetry_enabled;
         this.isCollectingApplePayEmail =
             !!sessionResponse.data?.collect_apple_pay_email;
         this.applySessionCardFieldConfig(sessionResponse);
@@ -2211,9 +2239,9 @@ class CheckoutInstance extends EventEmitter {
             throw new CheckoutError('Cannot update price while payment is processing');
         }
         try {
+            this.onLoaderChangeWithRace(true);
             this._setState('updating');
-            // Invalidate session cache
-            CheckoutInstance.sessionCache.clear();
+            sessionService.clearCache();
             await this.apiClient.updateClientSession({
                 orderId: this.orderId,
                 clientToken: this.clientToken,
@@ -2221,9 +2249,12 @@ class CheckoutInstance extends EventEmitter {
                 clientMetadata,
             });
             this.checkoutConfig.priceId = newPriceId;
+            await this.primerWrapper.refreshClientSession();
+            this.onLoaderChangeWithRace(false);
             this._setState('ready');
         }
         catch (error) {
+            this.onLoaderChangeWithRace(false);
             this._setState('error');
             this.emit(EVENTS.ERROR, error);
             throw error;
@@ -2243,7 +2274,7 @@ class CheckoutInstance extends EventEmitter {
             return;
         try {
             this.stopUnhandledTelemetry();
-            CheckoutInstance.sessionCache.clear();
+            sessionService.clearCache();
             await this.primerWrapper.destroy();
             this._setState('destroyed');
             this.orderId = null;
@@ -2439,8 +2470,12 @@ class CheckoutInstance extends EventEmitter {
             baseUrl: this.baseUrl,
             enabled: this.isTelemetryEnabled,
             getContext: () => ({
+                checkoutId: this.id,
                 orderId: this.orderId,
                 priceId: this.checkoutConfig.priceId,
+                state: this.state,
+                paymentMethod: this.telemetryPaymentMethod,
+                reqId: this.cachedSessionResponse?.req_id,
             }),
         });
     }
@@ -2450,7 +2485,6 @@ class CheckoutInstance extends EventEmitter {
         this.telemetryPaymentMethod = undefined;
     }
 }
-CheckoutInstance.sessionCache = new Map();
 
 /**
  * @fileoverview Public API with configuration and orchestration logic
@@ -2641,6 +2675,79 @@ async function getAvailablePaymentMethods(params) {
         throw error;
     }
 }
+async function createStripeCardForm(element, params) {
+    const config = resolveConfig(params, 'createStripeCardForm');
+    const [session, { mountStripeCardForm }] = await Promise.all([
+        sessionService.createSession({
+            orgId: config.orgId,
+            baseUrl: config.baseUrl,
+            region: config.region,
+            priceId: params.priceId,
+            externalId: params.externalId,
+            email: params.email,
+            clientMetadata: params.clientMetadata,
+            countryCode: params.countryCode,
+            integration: 'stripe',
+        }),
+        Promise.resolve().then(function () { return require('./chunk-stripe-card-form.cjs.js'); }),
+    ]);
+    const apiClient = new APIClient({
+        orgId: config.orgId,
+        baseUrl: config.baseUrl || DEFAULTS.BASE_URL,
+    });
+    return mountStripeCardForm(element, session, { ...params, apiClient });
+}
+async function purchaseStripeWallet(params) {
+    const config = resolveConfig(params, 'purchaseStripeWallet');
+    const [session, { purchaseWallet }] = await Promise.all([
+        sessionService.createSession({
+            orgId: config.orgId,
+            baseUrl: config.baseUrl,
+            region: config.region,
+            priceId: params.priceId,
+            externalId: params.externalId,
+            email: params.email,
+            clientMetadata: params.clientMetadata,
+            countryCode: params.countryCode,
+            integration: 'stripe',
+        }),
+        Promise.resolve().then(function () { return require('./chunk-stripe-wallet.cjs.js'); }),
+    ]);
+    const apiClient = new APIClient({
+        orgId: config.orgId,
+        baseUrl: config.baseUrl || DEFAULTS.BASE_URL,
+    });
+    return purchaseWallet(session, { ...params, apiClient });
+}
+async function getAvailableStripeWallet(params) {
+    const config = resolveConfig(params, 'getAvailableStripeWallet');
+    const [session, { getAvailableWallet }] = await Promise.all([
+        sessionService.createSession({
+            orgId: config.orgId,
+            baseUrl: config.baseUrl,
+            region: config.region,
+            priceId: params.priceId,
+            externalId: params.externalId,
+            email: params.email,
+            clientMetadata: params.clientMetadata,
+            countryCode: params.countryCode,
+            integration: 'stripe',
+        }),
+        Promise.resolve().then(function () { return require('./chunk-stripe-wallet.cjs.js'); }),
+    ]);
+    const result = await getAvailableWallet(session);
+    if (result === 'APPLE_PAY')
+        return exports.PaymentMethod.APPLE_PAY;
+    if (result === 'GOOGLE_PAY')
+        return exports.PaymentMethod.GOOGLE_PAY;
+    return null;
+}
+async function getAvailableStripePaymentMethods(params) {
+    const wallet = await getAvailableStripeWallet(params);
+    return wallet
+        ? [exports.PaymentMethod.PAYMENT_CARD, wallet]
+        : [exports.PaymentMethod.PAYMENT_CARD];
+}
 
 /**
  * @fileoverview Main entry point for @funnelfox/billing
@@ -2652,6 +2759,12 @@ const Billing = {
     initMethod: initMethod,
     silentPurchase: silentPurchase,
     getAvailablePaymentMethods: getAvailablePaymentMethods,
+    stripe: {
+        createCardForm: createStripeCardForm,
+        purchaseWallet: purchaseStripeWallet,
+        getAvailableWallet: getAvailableStripeWallet,
+        getAvailablePaymentMethods: getAvailableStripePaymentMethods,
+    },
 };
 if (typeof window !== 'undefined') {
     window.Billing = Billing;
@@ -2675,3 +2788,4 @@ exports.configure = configure;
 exports.createCheckout = createCheckout;
 exports.createClientSession = createClientSession;
 exports.getAvailablePaymentMethods = getAvailablePaymentMethods;
+exports.loadStripe = loadStripe;