@tagadapay/headless-sdk 1.8.0-rc.0 → 1.8.0

package/dist/stripe/StripeExpressCheckout.js

@@ -0,0 +1,198 @@
+const EXPRESS_METHOD_KEYS = ['apple_pay', 'google_pay', 'paypal', 'link', 'klarna_express'];
+/**
+ * Session-based Stripe Express Checkout integration.
+ *
+ * Mounts the Stripe `ExpressCheckoutElement` (Apple Pay, Google Pay, Link,
+ * PayPal, Klarna express) into any DOM container, wired to a Tagada
+ * checkout session. Drives the full flow:
+ * mount → wallet confirm → backend `payDirect` (`processStripeExpress`)
+ * → `stripe.confirmPayment` → poll payment status → emit `success`.
+ *
+ * **Session-free / partner S2S flow?** Use the lower-level primitive
+ * `startStripeExpressCheckout` exported from `@tagadapay/core-js`
+ * (also re-exported from `@tagadapay/headless-sdk/stripe`). It uses
+ * Stripe's older Payment Request API, stops at tokenization, and
+ * returns a `paymentMethodId` for partner-server-side processing.
+ *
+ * @example
+ * ```ts
+ * import { createHeadlessClient } from '@tagadapay/headless-sdk';
+ * import { StripeExpressCheckout } from '@tagadapay/headless-sdk/stripe';
+ *
+ * const client = createHeadlessClient({ storeId: 'store_xxx' });
+ * const session = await client.checkout.loadSession(checkoutToken);
+ * const express = await client.payment.getExpressMethods(session.id);
+ *
+ * const ece = new StripeExpressCheckout({
+ *   client,
+ *   publishableKey: express.applePay?.publishableKey!,
+ *   processorId: express.applePay?.processorId!,
+ * });
+ *
+ * ece.on('success', ({ payment }) => console.log('Paid!', payment.id));
+ * ece.on('error', (msg) => console.error(msg));
+ *
+ * await ece.mount(document.getElementById('express-container')!, {
+ *   checkoutSessionId: session.id,
+ *   amount: session.totals.total,
+ *   currency: session.totals.currency,
+ * });
+ * ```
+ */
+export class StripeExpressCheckout {
+    constructor(opts) {
+        this.stripe = null;
+        this.elements = null;
+        this.expressElement = null;
+        this.container = null;
+        this.isProcessing = false;
+        this.listeners = {};
+        this.client = opts.client;
+        this.publishableKey = opts.publishableKey;
+        this.processorId = opts.processorId;
+        this.enabledMethods = opts.enabledMethods ?? [...EXPRESS_METHOD_KEYS];
+        this.buttonHeight = opts.buttonHeight ?? 48;
+        this.buttonType = opts.buttonType ?? 'buy';
+        this.emailRequired = opts.emailRequired ?? true;
+        this.billingAddressRequired = opts.billingAddressRequired ?? true;
+    }
+    on(event, handler) {
+        if (!this.listeners[event]) {
+            this.listeners[event] = new Set();
+        }
+        this.listeners[event].add(handler);
+    }
+    off(event, handler) {
+        this.listeners[event]?.delete(handler);
+    }
+    /**
+     * Load Stripe.js, create Elements, and mount the ExpressCheckoutElement.
+     */
+    async mount(container, opts) {
+        this.container = container;
+        const { loadStripe } = await import('@stripe/stripe-js');
+        const stripe = await loadStripe(this.publishableKey);
+        if (!stripe) {
+            this.emit('error', 'Failed to load Stripe.js');
+            return;
+        }
+        this.stripe = stripe;
+        const amount = Math.max(Math.round(opts.amount), 1);
+        const currency = opts.currency.toLowerCase();
+        this.elements = stripe.elements({
+            mode: 'payment',
+            amount,
+            currency,
+        });
+        const methodEnabled = (key) => this.enabledMethods.includes(key);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe TS types don't expose expressCheckout overload
+        this.expressElement = this.elements.create('expressCheckout', {
+            buttonType: {
+                applePay: this.buttonType,
+                googlePay: this.buttonType,
+            },
+            buttonHeight: this.buttonHeight,
+            paymentMethods: {
+                applePay: methodEnabled('apple_pay') ? 'always' : 'never',
+                googlePay: methodEnabled('google_pay') ? 'always' : 'never',
+                link: methodEnabled('link') ? 'auto' : 'never',
+                paypal: methodEnabled('paypal') ? 'auto' : 'never',
+                klarna: methodEnabled('klarna_express') ? 'auto' : 'never',
+            },
+            emailRequired: this.emailRequired,
+            billingAddressRequired: this.billingAddressRequired,
+        });
+        this.expressElement.on('ready', ({ availablePaymentMethods }) => {
+            if (availablePaymentMethods) {
+                this.emit('ready', { availablePaymentMethods });
+            }
+        });
+        this.expressElement.on('cancel', () => {
+            this.isProcessing = false;
+            this.emit('cancel', undefined);
+        });
+        this.expressElement.on('confirm', async (event) => {
+            if (this.isProcessing)
+                return;
+            this.isProcessing = true;
+            try {
+                const { error: submitError } = await this.elements.submit();
+                if (submitError) {
+                    this.emit('error', submitError.message ?? 'Validation failed');
+                    this.isProcessing = false;
+                    return;
+                }
+                const payResult = await this.client.payment.processStripeExpress({
+                    checkoutSessionId: opts.checkoutSessionId,
+                    processorId: this.processorId,
+                    paymentMethod: event.expressPaymentType,
+                });
+                const clientSecret = this.extractClientSecret(payResult);
+                if (!clientSecret) {
+                    this.emit('error', 'Express checkout configuration missing — no client secret returned');
+                    this.isProcessing = false;
+                    return;
+                }
+                const { error: confirmError } = await this.stripe.confirmPayment({
+                    elements: this.elements,
+                    clientSecret,
+                    confirmParams: { return_url: window.location.href },
+                    redirect: 'if_required',
+                });
+                if (confirmError) {
+                    this.emit('error', confirmError.message ?? 'Payment confirmation failed');
+                    this.isProcessing = false;
+                    return;
+                }
+                const paymentId = payResult.payment.id;
+                const status = await this.client.payment.pollPaymentStatus(paymentId);
+                if (status.status === 'succeeded') {
+                    this.emit('success', { payment: status, order: status.order });
+                }
+                else {
+                    this.emit('error', `Payment ${status.status}`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : 'Express checkout failed';
+                this.emit('error', msg);
+            }
+            finally {
+                this.isProcessing = false;
+            }
+        });
+        this.expressElement.mount(container);
+    }
+    /**
+     * Update the payment amount (e.g. after a cart change).
+     */
+    updateAmount(amount, currency) {
+        if (!this.elements)
+            return;
+        const update = { amount: Math.max(Math.round(amount), 1) };
+        if (currency)
+            update.currency = currency.toLowerCase();
+        this.elements.update(update);
+    }
+    /**
+     * Clean up: unmount the element and release references.
+     */
+    unmount() {
+        this.expressElement?.unmount();
+        this.expressElement = null;
+        this.elements = null;
+        this.stripe = null;
+        this.container = null;
+        this.listeners = {};
+    }
+    emit(event, data) {
+        this.listeners[event]?.forEach((handler) => handler(data));
+    }
+    extractClientSecret(payResult) {
+        return payResult.payment?.requireActionData?.metadata?.stripeExpressCheckout
+            ? (payResult.payment.requireActionData.metadata
+                .stripeExpressCheckout.clientSecret)
+            : undefined;
+    }
+}
+//# sourceMappingURL=StripeExpressCheckout.js.map

package/dist/stripe/index.d.ts

@@ -0,0 +1,8 @@
+export { StripeExpressCheckout } from './StripeExpressCheckout.js';
+export { useStripeExpress } from './useStripeExpress.js';
+export type { UseStripeExpressOptions, UseStripeExpressReturn } from './useStripeExpress.js';
+export { StripeExpressButton } from './StripeExpressButton.js';
+export type { StripeExpressButtonProps } from './StripeExpressButton.js';
+export type { StripeExpressOptions } from '../core/types.js';
+export { startStripeExpressCheckout, isStripeExpressAvailable, type StripeExpressOptions as CoreStripeExpressOptions, type StripeExpressShippingAddress, type StripeExpressTokenResult, type StripeExpressCallbacks, } from '@tagadapay/core-js';
+//# sourceMappingURL=index.d.ts.map

package/dist/stripe/index.js

@@ -0,0 +1,15 @@
+// ─────────────────────────────────────────────────────────────────
+// Session-based Stripe Express Checkout — drives Stripe's Express
+// Checkout Element (drop-in widget) wired to a checkout session.
+// Used by sites built on `@tagadapay/headless-sdk`.
+// ─────────────────────────────────────────────────────────────────
+export { StripeExpressCheckout } from './StripeExpressCheckout.js';
+export { useStripeExpress } from './useStripeExpress.js';
+export { StripeExpressButton } from './StripeExpressButton.js';
+// ─────────────────────────────────────────────────────────────────
+// Session-free wallet tokenization — re-exported from `@tagadapay/core-js`
+// for partner / S2S flows that don't use a checkout session. Stops at
+// Stripe `paymentMethodId`; the partner forwards it to their server.
+// ─────────────────────────────────────────────────────────────────
+export { startStripeExpressCheckout, isStripeExpressAvailable, } from '@tagadapay/core-js';
+//# sourceMappingURL=index.js.map

package/dist/stripe/useStripeExpress.d.ts

@@ -0,0 +1,54 @@
+import type { ExpressMethods, PaymentStatus, PaymentSetupConfig } from '../core/types.js';
+export interface UseStripeExpressOptions {
+    checkoutSessionId: string;
+    amount: number;
+    currency: string;
+    onSuccess?: (result: {
+        payment: PaymentStatus;
+        order?: {
+            id: string;
+            checkoutSessionId?: string;
+        };
+    }) => void;
+    onError?: (error: string) => void;
+    onCancel?: () => void;
+    /** Override payment setup config (skips API discovery). */
+    paymentSetupConfig?: PaymentSetupConfig;
+}
+export interface UseStripeExpressReturn {
+    /** Attach this ref to a <div> — the express buttons will mount inside it. */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /** True once the Stripe element has rendered at least one wallet button. */
+    isReady: boolean;
+    /** True while a payment is being confirmed. */
+    isProcessing: boolean;
+    /** Discovered express methods (null while loading). */
+    expressMethods: ExpressMethods | null;
+    /** Update the displayed amount after cart changes. */
+    updateAmount: (amount: number, currency?: string) => void;
+}
+/**
+ * React hook that mounts the Stripe Express Checkout Element into a ref'd container.
+ *
+ * Handles the full lifecycle: discover config -> load Stripe -> mount ECE ->
+ * onConfirm -> processStripeExpress -> stripe.confirmPayment -> poll -> callbacks.
+ *
+ * @example
+ * ```tsx
+ * import { useStripeExpress } from '@tagadapay/headless-sdk/stripe';
+ *
+ * function ExpressSection({ sessionId, totals }) {
+ *   const { containerRef, isReady } = useStripeExpress({
+ *     checkoutSessionId: sessionId,
+ *     amount: totals.total,
+ *     currency: totals.currency,
+ *     onSuccess: () => router.push('/confirmation'),
+ *     onError: (msg) => toast.error(msg),
+ *   });
+ *
+ *   return <div ref={containerRef} style={{ display: isReady ? 'block' : 'none' }} />;
+ * }
+ * ```
+ */
+export declare function useStripeExpress(opts: UseStripeExpressOptions): UseStripeExpressReturn;
+//# sourceMappingURL=useStripeExpress.d.ts.map

package/dist/stripe/useStripeExpress.js

@@ -0,0 +1,126 @@
+import { useState, useRef, useEffect, useCallback } from 'react';
+import { useHeadlessClient } from '../react/provider.js';
+import { StripeExpressCheckout } from './StripeExpressCheckout.js';
+/**
+ * React hook that mounts the Stripe Express Checkout Element into a ref'd container.
+ *
+ * Handles the full lifecycle: discover config -> load Stripe -> mount ECE ->
+ * onConfirm -> processStripeExpress -> stripe.confirmPayment -> poll -> callbacks.
+ *
+ * @example
+ * ```tsx
+ * import { useStripeExpress } from '@tagadapay/headless-sdk/stripe';
+ *
+ * function ExpressSection({ sessionId, totals }) {
+ *   const { containerRef, isReady } = useStripeExpress({
+ *     checkoutSessionId: sessionId,
+ *     amount: totals.total,
+ *     currency: totals.currency,
+ *     onSuccess: () => router.push('/confirmation'),
+ *     onError: (msg) => toast.error(msg),
+ *   });
+ *
+ *   return <div ref={containerRef} style={{ display: isReady ? 'block' : 'none' }} />;
+ * }
+ * ```
+ */
+export function useStripeExpress(opts) {
+    const client = useHeadlessClient();
+    const containerRef = useRef(null);
+    const eceRef = useRef(null);
+    const [isReady, setIsReady] = useState(false);
+    const [isProcessing, setIsProcessing] = useState(false);
+    const [expressMethods, setExpressMethods] = useState(null);
+    const callbacksRef = useRef(opts);
+    callbacksRef.current = opts;
+    const { checkoutSessionId, amount, currency, paymentSetupConfig } = opts;
+    useEffect(() => {
+        if (!checkoutSessionId || !containerRef.current)
+            return;
+        let mounted = true;
+        let instance = null;
+        const init = async () => {
+            const express = await client.payment.getExpressMethods(checkoutSessionId, paymentSetupConfig ? { paymentSetupConfig } : undefined);
+            if (!mounted)
+                return;
+            setExpressMethods(express);
+            const stripeMethod = findStripeExpressMethod(express);
+            if (!stripeMethod?.publishableKey || !stripeMethod?.processorId)
+                return;
+            instance = new StripeExpressCheckout({
+                client,
+                publishableKey: stripeMethod.publishableKey,
+                processorId: stripeMethod.processorId,
+                enabledMethods: stripeMethod.enabledMethods,
+            });
+            instance.on('ready', () => {
+                if (mounted)
+                    setIsReady(true);
+            });
+            instance.on('success', (result) => {
+                if (mounted)
+                    setIsProcessing(false);
+                callbacksRef.current.onSuccess?.(result);
+            });
+            instance.on('error', (msg) => {
+                if (mounted)
+                    setIsProcessing(false);
+                callbacksRef.current.onError?.(msg);
+            });
+            instance.on('cancel', () => {
+                if (mounted)
+                    setIsProcessing(false);
+                callbacksRef.current.onCancel?.();
+            });
+            eceRef.current = instance;
+            if (containerRef.current) {
+                await instance.mount(containerRef.current, {
+                    checkoutSessionId,
+                    amount,
+                    currency,
+                });
+            }
+        };
+        void init();
+        return () => {
+            mounted = false;
+            instance?.unmount();
+            eceRef.current = null;
+            setIsReady(false);
+        };
+    }, [client, checkoutSessionId, paymentSetupConfig]); // eslint-disable-line react-hooks/exhaustive-deps
+    useEffect(() => {
+        eceRef.current?.updateAmount(amount, currency);
+    }, [amount, currency]);
+    const updateAmount = useCallback((newAmount, newCurrency) => {
+        eceRef.current?.updateAmount(newAmount, newCurrency);
+    }, []);
+    return { containerRef, isReady, isProcessing, expressMethods, updateAmount };
+}
+/**
+ * Find a Stripe ECE-capable method from the express methods map.
+ * Returns publishableKey, processorId, and list of enabled sub-methods.
+ */
+function findStripeExpressMethod(express) {
+    const allMethods = [
+        { key: 'apple_pay', entry: express.applePay },
+        { key: 'google_pay', entry: express.googlePay },
+        { key: 'paypal', entry: express.paypal },
+        { key: 'link', entry: express.link },
+        { key: 'klarna_express', entry: express.klarna },
+    ];
+    for (const { entry } of allMethods) {
+        if (entry?.publishableKey && entry.processorId) {
+            const enabledMethods = allMethods
+                .filter(({ entry: e }) => e?.available && e.publishableKey === entry.publishableKey)
+                .map(({ key }) => key);
+            return {
+                publishableKey: entry.publishableKey,
+                processorId: entry.processorId,
+                enabledMethods,
+            };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=useStripeExpress.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagadapay/headless-sdk",
-  "version": "1.8.0-rc.0",
+  "version": "1.8.0",
   "description": "Headless SDK for using TagadaPay as a checkout, offers, and CRM backend from any external website",
   "type": "module",
   "main": "dist/core/index.js",
@@ -58,8 +58,7 @@
     }
   },
   "files": [
-    "dist/index.js",
-    "dist/index.d.ts",
+    "dist/**/*",
     "README.md"
   ],
   "repository": {