@funnelfox/billing 0.9.0-beta.7 → 0.9.0-ffb-467-adyen.15

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-adyen-card-form.cjs.js

@@ -0,0 +1,165 @@
+/**
+ * @funnelfox/billing v0.1.0
+ * JavaScript SDK for Funnelfox billing with Primer integration
+ * 
+ * @author Funnelfox
+ * @license MIT
+ */
+'use strict';
+
+var adyenLoader = require('./chunk-adyen-loader.cjs.js');
+require('./chunk-index.cjs.js');
+
+const TAX_RECALC_DEBOUNCE_MS = 600;
+async function mountAdyenCardForm(element, session, params) {
+    const { adyen_client_key, adyen_payment_methods, amount, amount_total, currency, is_livemode, order_id, client_token, detected_country_code, show_country_selector_field, show_postal_code_field, } = session.data;
+    const taxEnabled = session.data.tax_enabled ?? params.enableTax ?? false;
+    const currencyUpper = (currency || 'usd').toUpperCase();
+    const AdyenCheckout = await adyenLoader.getAdyenCheckout(!!is_livemode);
+    // Remounting (e.g. picking another price) must replace the form, not stack a second one.
+    element.replaceChildren();
+    let taxCalculationId;
+    let taxAddress = {};
+    let flushTaxRecalc = async () => { };
+    let resolvePayment;
+    let rejectPayment;
+    const runRecalc = async () => {
+        const country = taxAddress.country || detected_country_code;
+        // US tax needs the ZIP to resolve a jurisdiction; skip until it's entered.
+        if (!country || (country === 'US' && !taxAddress.postalCode))
+            return;
+        try {
+            const tax = await params.apiClient.recalculateTax({
+                orderId: order_id,
+                clientToken: client_token,
+                countryCode: country,
+                postalCode: taxAddress.postalCode,
+                subdivision: taxAddress.state,
+            });
+            taxCalculationId = tax.tax_calculation_id;
+            params.onTaxChange?.({
+                amountTotal: tax.amount_total,
+                taxAmount: tax.tax_amount,
+                currency: tax.currency,
+            });
+        }
+        catch {
+            // Best-effort: keep the current total if recalculation fails.
+        }
+    };
+    const finalize = async (raw, component) => {
+        const result = params.apiClient.processPaymentResponse(raw);
+        if (result.type === 'action_required') {
+            // Adyen packs the next action (3DS) JSON into action_required_token; the challenge result
+            // comes back through onAdditionalDetails, which resumes the payment.
+            component.handleAction(JSON.parse(result.clientToken));
+            return;
+        }
+        params.onPaymentSuccess?.(order_id);
+        resolvePayment?.();
+    };
+    const checkout = await AdyenCheckout({
+        environment: is_livemode ? 'live' : 'test',
+        clientKey: adyen_client_key,
+        paymentMethodsResponse: adyen_payment_methods,
+        amount: { value: amount_total ?? amount ?? 0, currency: currencyUpper },
+        locale: 'en-US',
+        onSubmit: (state, component) => {
+            void (async () => {
+                try {
+                    const address = state.data.billingAddress || {};
+                    const raw = await params.apiClient.createPayment({
+                        orderId: order_id,
+                        paymentMethodToken: JSON.stringify(state.data),
+                        email: params.email,
+                        countryCode: taxEnabled ? address.country : params.countryCode,
+                        postalCode: taxEnabled ? address.postalCode : undefined,
+                        subdivision: taxEnabled ? address.stateOrProvince : undefined,
+                        taxCalculationId: taxEnabled ? taxCalculationId : undefined,
+                        clientMetadata: params.clientMetadata,
+                    });
+                    await finalize(raw, component);
+                }
+                catch (err) {
+                    params.onPaymentFail?.(err);
+                    rejectPayment?.(err);
+                }
+            })();
+        },
+        onAdditionalDetails: (state, component) => {
+            void (async () => {
+                try {
+                    const raw = await params.apiClient.resumePayment({
+                        orderId: order_id,
+                        resumeToken: JSON.stringify(state.data),
+                    });
+                    await finalize(raw, component);
+                }
+                catch (err) {
+                    params.onPaymentFail?.(err);
+                    rejectPayment?.(err);
+                }
+            })();
+        },
+        onError: error => params.onPaymentFail?.(error),
+    });
+    const billingFields = [];
+    if (show_country_selector_field)
+        billingFields.push('country');
+    if (show_postal_code_field)
+        billingFields.push('postalCode');
+    let debounce;
+    const cardConfig = {
+        showPayButton: false,
+        billingAddressRequired: billingFields.length > 0,
+        billingAddressRequiredFields: billingFields,
+        onChange: (state) => {
+            if (!taxEnabled)
+                return;
+            const address = state.data.billingAddress;
+            if (!address)
+                return;
+            taxAddress = {
+                country: address.country,
+                postalCode: address.postalCode || undefined,
+                state: address.stateOrProvince || undefined,
+            };
+            if (debounce)
+                clearTimeout(debounce);
+            debounce = setTimeout(() => void runRecalc(), TAX_RECALC_DEBOUNCE_MS);
+        },
+    };
+    if (detected_country_code) {
+        cardConfig.data = { billingAddress: { country: detected_country_code } };
+    }
+    const card = checkout.create('card', cardConfig);
+    card.mount(element);
+    flushTaxRecalc = async () => {
+        if (debounce) {
+            clearTimeout(debounce);
+            debounce = undefined;
+        }
+        if (taxEnabled)
+            await runRecalc();
+    };
+    params.onRenderSuccess?.();
+    return {
+        submit: async () => {
+            params.onLoaderChange?.(true);
+            const done = new Promise((resolve, reject) => {
+                resolvePayment = resolve;
+                rejectPayment = reject;
+            });
+            try {
+                await flushTaxRecalc();
+                card.submit();
+                await done;
+            }
+            finally {
+                params.onLoaderChange?.(false);
+            }
+        },
+    };
+}
+
+exports.mountAdyenCardForm = mountAdyenCardForm;

package/dist/chunk-adyen-card-form.es.js

@@ -0,0 +1,163 @@
+/**
+ * @funnelfox/billing v0.1.0
+ * JavaScript SDK for Funnelfox billing with Primer integration
+ * 
+ * @author Funnelfox
+ * @license MIT
+ */
+import { g as getAdyenCheckout } from './chunk-adyen-loader.es.js';
+import './chunk-index.es.js';
+
+const TAX_RECALC_DEBOUNCE_MS = 600;
+async function mountAdyenCardForm(element, session, params) {
+    const { adyen_client_key, adyen_payment_methods, amount, amount_total, currency, is_livemode, order_id, client_token, detected_country_code, show_country_selector_field, show_postal_code_field, } = session.data;
+    const taxEnabled = session.data.tax_enabled ?? params.enableTax ?? false;
+    const currencyUpper = (currency || 'usd').toUpperCase();
+    const AdyenCheckout = await getAdyenCheckout(!!is_livemode);
+    // Remounting (e.g. picking another price) must replace the form, not stack a second one.
+    element.replaceChildren();
+    let taxCalculationId;
+    let taxAddress = {};
+    let flushTaxRecalc = async () => { };
+    let resolvePayment;
+    let rejectPayment;
+    const runRecalc = async () => {
+        const country = taxAddress.country || detected_country_code;
+        // US tax needs the ZIP to resolve a jurisdiction; skip until it's entered.
+        if (!country || (country === 'US' && !taxAddress.postalCode))
+            return;
+        try {
+            const tax = await params.apiClient.recalculateTax({
+                orderId: order_id,
+                clientToken: client_token,
+                countryCode: country,
+                postalCode: taxAddress.postalCode,
+                subdivision: taxAddress.state,
+            });
+            taxCalculationId = tax.tax_calculation_id;
+            params.onTaxChange?.({
+                amountTotal: tax.amount_total,
+                taxAmount: tax.tax_amount,
+                currency: tax.currency,
+            });
+        }
+        catch {
+            // Best-effort: keep the current total if recalculation fails.
+        }
+    };
+    const finalize = async (raw, component) => {
+        const result = params.apiClient.processPaymentResponse(raw);
+        if (result.type === 'action_required') {
+            // Adyen packs the next action (3DS) JSON into action_required_token; the challenge result
+            // comes back through onAdditionalDetails, which resumes the payment.
+            component.handleAction(JSON.parse(result.clientToken));
+            return;
+        }
+        params.onPaymentSuccess?.(order_id);
+        resolvePayment?.();
+    };
+    const checkout = await AdyenCheckout({
+        environment: is_livemode ? 'live' : 'test',
+        clientKey: adyen_client_key,
+        paymentMethodsResponse: adyen_payment_methods,
+        amount: { value: amount_total ?? amount ?? 0, currency: currencyUpper },
+        locale: 'en-US',
+        onSubmit: (state, component) => {
+            void (async () => {
+                try {
+                    const address = state.data.billingAddress || {};
+                    const raw = await params.apiClient.createPayment({
+                        orderId: order_id,
+                        paymentMethodToken: JSON.stringify(state.data),
+                        email: params.email,
+                        countryCode: taxEnabled ? address.country : params.countryCode,
+                        postalCode: taxEnabled ? address.postalCode : undefined,
+                        subdivision: taxEnabled ? address.stateOrProvince : undefined,
+                        taxCalculationId: taxEnabled ? taxCalculationId : undefined,
+                        clientMetadata: params.clientMetadata,
+                    });
+                    await finalize(raw, component);
+                }
+                catch (err) {
+                    params.onPaymentFail?.(err);
+                    rejectPayment?.(err);
+                }
+            })();
+        },
+        onAdditionalDetails: (state, component) => {
+            void (async () => {
+                try {
+                    const raw = await params.apiClient.resumePayment({
+                        orderId: order_id,
+                        resumeToken: JSON.stringify(state.data),
+                    });
+                    await finalize(raw, component);
+                }
+                catch (err) {
+                    params.onPaymentFail?.(err);
+                    rejectPayment?.(err);
+                }
+            })();
+        },
+        onError: error => params.onPaymentFail?.(error),
+    });
+    const billingFields = [];
+    if (show_country_selector_field)
+        billingFields.push('country');
+    if (show_postal_code_field)
+        billingFields.push('postalCode');
+    let debounce;
+    const cardConfig = {
+        showPayButton: false,
+        billingAddressRequired: billingFields.length > 0,
+        billingAddressRequiredFields: billingFields,
+        onChange: (state) => {
+            if (!taxEnabled)
+                return;
+            const address = state.data.billingAddress;
+            if (!address)
+                return;
+            taxAddress = {
+                country: address.country,
+                postalCode: address.postalCode || undefined,
+                state: address.stateOrProvince || undefined,
+            };
+            if (debounce)
+                clearTimeout(debounce);
+            debounce = setTimeout(() => void runRecalc(), TAX_RECALC_DEBOUNCE_MS);
+        },
+    };
+    if (detected_country_code) {
+        cardConfig.data = { billingAddress: { country: detected_country_code } };
+    }
+    const card = checkout.create('card', cardConfig);
+    card.mount(element);
+    flushTaxRecalc = async () => {
+        if (debounce) {
+            clearTimeout(debounce);
+            debounce = undefined;
+        }
+        if (taxEnabled)
+            await runRecalc();
+    };
+    params.onRenderSuccess?.();
+    return {
+        submit: async () => {
+            params.onLoaderChange?.(true);
+            const done = new Promise((resolve, reject) => {
+                resolvePayment = resolve;
+                rejectPayment = reject;
+            });
+            try {
+                await flushTaxRecalc();
+                card.submit();
+                await done;
+            }
+            finally {
+                params.onLoaderChange?.(false);
+            }
+        },
+    };
+}
+
+export { mountAdyenCardForm };

package/dist/chunk-adyen-loader.cjs.js

@@ -0,0 +1,38 @@
+/**
+ * @funnelfox/billing v0.1.0
+ * JavaScript SDK for Funnelfox billing with Primer integration
+ * 
+ * @author Funnelfox
+ * @license MIT
+ */
+'use strict';
+
+var index = require('./chunk-index.cjs.js');
+
+/**
+ * @fileoverview Adyen Web SDK (Drop-in/Components) CDN loader.
+ *
+ * Adyen Web is loaded from the checkoutshopper CDN (not npm), so we declare the minimal shapes we
+ * use rather than depend on @adyen/adyen-web types.
+ */
+const ADYEN_WEB_VERSION = '5.66.0';
+/**
+ * Loads Adyen Web (adyen.js + adyen.css) from the CDN and returns the AdyenCheckout factory.
+ * Host is livemode-aware; the loaders dedupe so repeated calls are cheap.
+ */
+async function getAdyenCheckout(isLivemode) {
+    const host = isLivemode
+        ? 'https://checkoutshopper-live.adyen.com'
+        : 'https://checkoutshopper-test.adyen.com';
+    const base = `${host}/checkoutshopper/sdk/${ADYEN_WEB_VERSION}`;
+    await Promise.all([
+        index.loadStylesheet({ href: `${base}/adyen.css` }),
+        index.loadScript({ id: 'adyen-web-sdk', src: `${base}/adyen.js`, async: true }),
+    ]);
+    const factory = window.AdyenCheckout;
+    if (!factory)
+        throw new Error('Failed to load Adyen Web SDK');
+    return factory;
+}
+
+exports.getAdyenCheckout = getAdyenCheckout;

package/dist/chunk-adyen-loader.es.js

@@ -0,0 +1,36 @@
+/**
+ * @funnelfox/billing v0.1.0
+ * JavaScript SDK for Funnelfox billing with Primer integration
+ * 
+ * @author Funnelfox
+ * @license MIT
+ */
+import { l as loadStylesheet, a as loadScript } from './chunk-index.es.js';
+
+/**
+ * @fileoverview Adyen Web SDK (Drop-in/Components) CDN loader.
+ *
+ * Adyen Web is loaded from the checkoutshopper CDN (not npm), so we declare the minimal shapes we
+ * use rather than depend on @adyen/adyen-web types.
+ */
+const ADYEN_WEB_VERSION = '5.66.0';
+/**
+ * Loads Adyen Web (adyen.js + adyen.css) from the CDN and returns the AdyenCheckout factory.
+ * Host is livemode-aware; the loaders dedupe so repeated calls are cheap.
+ */
+async function getAdyenCheckout(isLivemode) {
+    const host = isLivemode
+        ? 'https://checkoutshopper-live.adyen.com'
+        : 'https://checkoutshopper-test.adyen.com';
+    const base = `${host}/checkoutshopper/sdk/${ADYEN_WEB_VERSION}`;
+    await Promise.all([
+        loadStylesheet({ href: `${base}/adyen.css` }),
+        loadScript({ id: 'adyen-web-sdk', src: `${base}/adyen.js`, async: true }),
+    ]);
+    const factory = window.AdyenCheckout;
+    if (!factory)
+        throw new Error('Failed to load Adyen Web SDK');
+    return factory;
+}
+
+export { getAdyenCheckout as g };