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

package/dist/core/modules/payment.js

@@ -0,0 +1,784 @@
+import { applePayContactToAddress, googlePayContactToAddress, } from '../helpers/walletContact.js';
+/**
+ * Full payment lifecycle -- discover APMs, tokenize, create instruments,
+ * process payments, handle 3DS, and poll for status.
+ *
+ * Wraps the same REST endpoints that plugin-sdk uses internally.
+ *
+ * @remarks PCI DSS compliance notice
+ *
+ * This SDK collects card data (PAN, expiry, CVC) in the merchant's page
+ * context and sends it directly to Basis Theory for tokenization. Card data
+ * never reaches TagadaPay servers.
+ *
+ * Because card data transits through the merchant's JavaScript environment,
+ * merchants using this SDK are responsible for **PCI DSS SAQ-A-EP**
+ * compliance. This includes quarterly ASV scans, secure page delivery
+ * (TLS), and ensuring no unauthorized scripts can access cardholder data.
+ *
+ * TagadaPay is PCI DSS Level 1 certified. The merchant's PCI scope is
+ * determined by their integration method, not by TagadaPay's certification.
+ *
+ * See: https://docs.tagada.io/developer-tools/headless-sdk/pci-compliance
+ */
+export class PaymentModule {
+    constructor(http, storeId, environment, 
+    /** Used to persist wallet contacts onto the session before charging. */
+    checkout) {
+        this.http = http;
+        this.storeId = storeId;
+        this.environment = environment;
+        this.checkout = checkout;
+    }
+    // ---------------------------------------------------------------------------
+    // Discovery: what payment methods are available?
+    // ---------------------------------------------------------------------------
+    /**
+     * Get the full payment setup config for a checkout session.
+     * Returns a map of payment methods with their configuration
+     * (card, apple_pay, google_pay, klarna, etc.).
+     *
+     * Priority chain:
+     * 1. Explicit `paymentSetupConfig` parameter (developer override)
+     * 2. `window.__TGD_STEP_CONFIG__` injection (Tagada routing infra)
+     * 3. API fallback (`GET /api/v1/payment-methods`)
+     */
+    async getPaymentSetup(checkoutSessionId, opts) {
+        if (opts?.paymentSetupConfig) {
+            return opts.paymentSetupConfig;
+        }
+        const injected = this.readInjectedStepConfig();
+        if (injected) {
+            return injected;
+        }
+        const methods = await this.http.get('/api/v1/payment-methods', { params: { checkoutSessionId } });
+        const config = {};
+        for (const m of methods.methods ?? []) {
+            const key = m.provider ? `${m.method}:${m.provider}` : m.method;
+            config[key] = m;
+        }
+        return config;
+    }
+    /**
+     * Get express payment methods (Apple Pay, Google Pay, PayPal, etc.)
+     * filtered to only those available in the current browser.
+     */
+    async getExpressMethods(checkoutSessionId, opts) {
+        const setup = await this.getPaymentSetup(checkoutSessionId, opts);
+        const result = {};
+        for (const [key, config] of Object.entries(setup)) {
+            if (!config.enabled)
+                continue;
+            // Handle express_checkout:processorId entries (from paymentSetupConfig injection)
+            // These have a `methods` map like { apple_pay: { enabled: true }, google_pay: { enabled: true } }
+            if (key.startsWith('express_checkout:') && config.methods) {
+                const base = {
+                    available: true,
+                    processorId: config.processorId,
+                    publishableKey: config.publishableKey,
+                    metadata: config.metadata,
+                };
+                if (config.methods.apple_pay?.enabled) {
+                    const hasApplePay = typeof window !== 'undefined' &&
+                        'ApplePaySession' in window &&
+                        window
+                            .ApplePaySession?.canMakePayments?.();
+                    result.applePay = { ...base, type: 'apple_pay', available: !!hasApplePay };
+                }
+                if (config.methods.google_pay?.enabled) {
+                    result.googlePay = { ...base, type: 'google_pay' };
+                }
+                if (config.methods.link?.enabled) {
+                    result.link = { ...base, type: 'link' };
+                }
+                if (config.methods.klarna_express?.enabled) {
+                    result.klarna = { ...base, type: 'klarna_express' };
+                }
+                continue;
+            }
+            if (!config.express)
+                continue;
+            const method = config.method;
+            const base = {
+                type: method,
+                available: true,
+                processorId: config.processorId,
+                publishableKey: config.publishableKey,
+                metadata: config.metadata,
+            };
+            if (method === 'apple_pay' || config.type === 'apple_pay') {
+                const hasApplePay = typeof window !== 'undefined' &&
+                    'ApplePaySession' in window &&
+                    window
+                        .ApplePaySession?.canMakePayments?.();
+                result.applePay = { ...base, available: !!hasApplePay };
+            }
+            else if (method === 'google_pay' || config.type === 'google_pay') {
+                result.googlePay = base;
+            }
+            else if (method === 'paypal') {
+                result.paypal = base;
+            }
+            else if (method === 'klarna' || method === 'klarna_express') {
+                result.klarna = base;
+            }
+            else if (method === 'link') {
+                result.link = base;
+            }
+        }
+        return result;
+    }
+    /**
+     * Get store-level payment config (3DS flags, default flow ID, etc.).
+     */
+    async getStoreConfig() {
+        const res = await this.http.get('/api/v1/checkout/config', { params: { storeId: this.storeId } });
+        return res.config ?? res;
+    }
+    /**
+     * Convenience: return only enabled payment method keys.
+     */
+    async getEnabledMethods(checkoutSessionId, opts) {
+        const setup = await this.getPaymentSetup(checkoutSessionId, opts);
+        return Object.entries(setup)
+            .filter(([, c]) => c.enabled)
+            .map(([key]) => key);
+    }
+    // ---------------------------------------------------------------------------
+    // Tokenization (delegates to @tagadapay/core-js if available)
+    // ---------------------------------------------------------------------------
+    /**
+     * Tokenize a card using @tagadapay/core-js.
+     * Requires `@tagadapay/core-js` to be installed as a peer dependency.
+     *
+     * Card data is sent directly to Basis Theory for tokenization and never
+     * reaches TagadaPay servers. The returned `tagadaToken` is safe to pass
+     * to the TagadaPay API.
+     *
+     * **PCI note:** Using this method means card data passes through your
+     * JavaScript environment. You are responsible for PCI DSS SAQ-A-EP
+     * compliance. See https://docs.tagada.io/developer-tools/headless-sdk/pci-compliance
+     *
+     * @returns tagadaToken (base64 string) and rawToken with SCA metadata.
+     */
+    async tokenizeCard(card) {
+        const coreJs = await this.loadCoreJs();
+        const tokenizer = new coreJs.Tokenizer({ environment: this.environment });
+        await tokenizer.initialize();
+        const sanitized = {
+            cardNumber: card.cardNumber,
+            expiryDate: card.expiryDate,
+            cvc: card.cvc,
+        };
+        if (card.cardholderName)
+            sanitized.cardholderName = card.cardholderName;
+        // Tokenize ONCE — both `tokenizer.tokenizeCard` and
+        // `tokenizer.tokenizeCardRaw` internally call BasisTheory's
+        // `POST /tokens`. Running them in `Promise.all` charged the
+        // customer's network with two identical tokenization requests
+        // (visible in the browser as duplicated `tokens/` calls). Get
+        // the raw response once, then derive the encoded TagadaToken
+        // locally via `createTagadaToken`.
+        const rawToken = await tokenizer.tokenizeCardRaw(sanitized);
+        const tagadaToken = coreJs.createTagadaToken(rawToken, tokenizer.getProvider().getProviderName());
+        return { tagadaToken, rawToken };
+    }
+    // ---------------------------------------------------------------------------
+    // Instrument creation
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a reusable payment instrument from a TagadaToken.
+     * Session-authenticated (uses the checkout session JWT).
+     */
+    async createInstrument(opts) {
+        return this.http.post('/api/v1/payment/create-instrument-from-token', {
+            tagadaToken: opts.tagadaToken,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // 3DS
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a 3DS session on the TagadaPay backend.
+     * This persists the session so the processor can use it during payment.
+     */
+    async create3dsSession(opts) {
+        return this.http.post('/api/public/v1/threeds/create-session', {
+            provider: opts.provider ?? 'basis_theory',
+            storeId: this.storeId,
+            paymentInstrumentId: opts.paymentInstrumentId,
+            sessionData: opts.sessionData,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Payment processing
+    // ---------------------------------------------------------------------------
+    /**
+     * High-level pay: single API call that decodes tagadaToken server-side,
+     * creates the payment instrument, and processes payment.
+     *
+     * Also accepts `paymentInstrumentId` directly for pre-created instruments.
+     */
+    async pay(opts) {
+        if (opts.tagadaToken && !opts.paymentInstrumentId) {
+            return this.http.post('/api/v1/payment/pay-with-token', {
+                tagadaToken: opts.tagadaToken,
+                checkoutSessionId: opts.checkoutSessionId,
+                returnUrl: opts.returnUrl,
+                paymentFlowId: opts.paymentFlowId,
+                processorId: opts.processorId,
+                paymentMethod: opts.paymentMethod,
+                isExpress: opts.isExpress,
+                metadata: opts.metadata,
+            });
+        }
+        return this.http.post('/api/public/v1/checkout/pay-v2', {
+            checkoutSessionId: opts.checkoutSessionId,
+            paymentInstrumentId: opts.paymentInstrumentId,
+            storeId: this.storeId,
+            paymentFlowId: opts.paymentFlowId,
+            threedsSessionId: opts.threedsSessionId,
+            processorId: opts.processorId,
+            paymentMethod: opts.paymentMethod,
+            isExpress: opts.isExpress,
+            metadata: opts.metadata,
+            returnUrl: opts.returnUrl,
+        });
+    }
+    /**
+     * Low-level pay: process payment with an existing instrument or for APM/express flows
+     * where no instrument is needed (redirect-based methods).
+     */
+    async payDirect(opts) {
+        return this.http.post('/api/public/v1/checkout/pay-v2', {
+            checkoutSessionId: opts.checkoutSessionId,
+            paymentInstrumentId: opts.paymentInstrumentId ?? '',
+            storeId: this.storeId,
+            paymentFlowId: opts.paymentFlowId,
+            processorId: opts.processorId,
+            paymentMethod: opts.paymentMethod,
+            isExpress: opts.isExpress,
+            threedsSessionId: opts.threedsSessionId,
+            returnUrl: opts.returnUrl,
+        });
+    }
+    /**
+     * Persist a wallet contact onto the session before the charge.
+     *
+     * Express wallets are the one checkout where the buyer never fills an address
+     * form: they approve one inside the sheet, and it comes back on the
+     * authorization event. Studio's `ExpressPaymentWidget` writes it to the
+     * session; the headless path used to drop it, which is how a year of orders
+     * reached merchants with NULL shipping, billing and customer addresses
+     * (#TAG-1989).
+     *
+     * Never invents data: a contact with no street line or no country maps to
+     * `undefined` and the session is left exactly as it was. Failures are NOT
+     * swallowed — if we hold an address and cannot store it, the charge must not
+     * proceed, or we are back to the bug this fixes.
+     */
+    async syncWalletContact(checkoutSessionId, contact) {
+        const { shippingAddress, billingAddress } = contact;
+        if (!shippingAddress && !billingAddress)
+            return;
+        if (!this.checkout) {
+            throw new Error('PaymentModule cannot persist the wallet contact: no CheckoutModule was provided. ' +
+                'Build the SDK through createTagadaClient() rather than constructing PaymentModule directly.');
+        }
+        const customer = {};
+        if (contact.email)
+            customer.email = contact.email;
+        if (contact.phone)
+            customer.phone = contact.phone;
+        if (contact.firstName)
+            customer.firstName = contact.firstName;
+        if (contact.lastName)
+            customer.lastName = contact.lastName;
+        await this.checkout.updateCustomerAndAddress(checkoutSessionId, {
+            customer,
+            shippingAddress,
+            billingAddress,
+        });
+    }
+    /**
+     * Process an Apple Pay payment.
+     * Tokenizes the Apple Pay token and processes payment in one call.
+     *
+     * Pass the contacts from `onpaymentauthorized` — `event.payment.billingContact`
+     * and `event.payment.shippingContact` — and they are written to the session
+     * before the charge, so the address the buyer approved in the wallet sheet
+     * lands on the order (#TAG-1989).
+     *
+     * Apple only returns them when the payment request asked for them, so the
+     * `ApplePaySession` request needs:
+     *
+     * ```js
+     * requiredBillingContactFields: ['postalAddress'],
+     * requiredShippingContactFields: ['name', 'phone', 'email', 'postalAddress'],
+     * ```
+     *
+     * @example
+     * session.onpaymentauthorized = async (event) => {
+     *   await tagada.payment.processApplePay({
+     *     checkoutSessionId,
+     *     applePayToken: event.payment.token,
+     *     billingContact: event.payment.billingContact,
+     *     shippingContact: event.payment.shippingContact,
+     *   });
+     * };
+     */
+    async processApplePay(opts) {
+        await this.syncWalletContact(opts.checkoutSessionId, {
+            shippingAddress: applePayContactToAddress(opts.shippingContact),
+            billingAddress: applePayContactToAddress(opts.billingContact),
+            email: opts.shippingContact?.emailAddress ?? opts.billingContact?.emailAddress,
+            phone: opts.shippingContact?.phoneNumber ?? opts.billingContact?.phoneNumber,
+            firstName: opts.shippingContact?.givenName ?? opts.billingContact?.givenName,
+            lastName: opts.shippingContact?.familyName ?? opts.billingContact?.familyName,
+        });
+        const coreJs = await this.loadCoreJs();
+        const tokenizer = new coreJs.Tokenizer({ environment: this.environment });
+        await tokenizer.initialize();
+        const { tagadaToken } = await tokenizer.tokenizeApplePay(opts.applePayToken);
+        return this.pay({
+            checkoutSessionId: opts.checkoutSessionId,
+            tagadaToken,
+            paymentFlowId: opts.paymentFlowId,
+            processorId: opts.processorId,
+            paymentMethod: 'apple_pay',
+            isExpress: true,
+        });
+    }
+    /**
+     * Process a Google Pay payment.
+     * Tokenizes the Google Pay token and processes payment in one call.
+     *
+     * Pass `paymentData.shippingAddress` / the billing address off
+     * `paymentMethodData.info.billingAddress` and they are persisted to the
+     * session before the charge (#TAG-1989). Google only returns them when the
+     * request sets `shippingAddressRequired` / `billingAddressRequired`.
+     */
+    async processGooglePay(opts) {
+        await this.syncWalletContact(opts.checkoutSessionId, {
+            shippingAddress: googlePayContactToAddress(opts.shippingAddress),
+            billingAddress: googlePayContactToAddress(opts.billingAddress),
+            email: opts.email ?? opts.shippingAddress?.emailAddress ?? opts.billingAddress?.emailAddress,
+            phone: opts.shippingAddress?.phoneNumber ?? opts.billingAddress?.phoneNumber,
+        });
+        const coreJs = await this.loadCoreJs();
+        const tokenizer = new coreJs.Tokenizer({ environment: this.environment });
+        await tokenizer.initialize();
+        const { tagadaToken } = await tokenizer.tokenizeGooglePay(opts.googlePayToken);
+        return this.pay({
+            checkoutSessionId: opts.checkoutSessionId,
+            tagadaToken,
+            paymentFlowId: opts.paymentFlowId,
+            processorId: opts.processorId,
+            paymentMethod: 'google_pay',
+            isExpress: true,
+        });
+    }
+    /**
+     * Process an APM payment (Klarna, iDEAL, etc.) via redirect.
+     * These typically don't require a payment instrument -- the processor handles the redirect.
+     */
+    async processApm(opts) {
+        return this.payDirect({
+            checkoutSessionId: opts.checkoutSessionId,
+            paymentMethod: opts.paymentMethod,
+            processorId: opts.processorId,
+            paymentFlowId: opts.paymentFlowId,
+        });
+    }
+    /**
+     * Initiate a Stripe Express Checkout payment (Apple Pay, Google Pay, Link, etc.).
+     *
+     * Calls `pay-v2` with `isExpress: true`, which returns a `clientSecret` in
+     * `payment.requireActionData.metadata.stripeExpressCheckout.clientSecret`.
+     * The caller must then call `stripe.confirmPayment()` with that secret.
+     *
+     * Used by the `StripeExpressCheckout` class and `useStripeExpress` hook.
+     * Not typically called directly — use the Stripe integration classes instead.
+     */
+    async processStripeExpress(opts) {
+        return this.payDirect({
+            checkoutSessionId: opts.checkoutSessionId,
+            processorId: opts.processorId,
+            paymentMethod: opts.paymentMethod,
+            isExpress: true,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // High-level orchestrator — the ONE function beginners should call
+    // ---------------------------------------------------------------------------
+    /**
+     * Process a payment end-to-end: pay, handle 3DS / redirects, poll until done.
+     *
+     * This is the **recommended** way to process payments. It wraps `pay()`, detects
+     * `requireAction`, runs 3DS challenges (if `@tagadapay/core-js` is installed),
+     * and polls until a terminal status.
+     *
+     * Returns a discriminated union so you can pattern-match on `result.status`:
+     *
+     * @example
+     * ```ts
+     * const result = await payment.processPayment({
+     *   checkoutSessionId: session.id,
+     *   tagadaToken,
+     * });
+     *
+     * switch (result.status) {
+     *   case 'succeeded':
+     *     console.log('Paid!', result.payment.id);
+     *     break;
+     *   case 'requires_redirect':
+     *     // In browser: window.location.href = result.redirectUrl
+     *     // The React hook handles this automatically.
+     *     break;
+     *   case 'failed':
+     *     console.error(result.error);
+     *     break;
+     * }
+     * ```
+     */
+    async processPayment(opts) {
+        if (!opts.returnUrl && typeof window !== 'undefined') {
+            opts = { ...opts, returnUrl: window.location.href };
+        }
+        const payResult = await this.pay(opts);
+        return this.finalize(payResult, { returnUrl: opts.returnUrl });
+    }
+    /**
+     * Resolve a raw `PayResult` (from any pay endpoint — `pay()`, `payDirect()`,
+     * `processApplePay()`, `offers.payPreviewedOffer()`, …) into a typed
+     * `ProcessPaymentResult` (`succeeded` / `requires_redirect` / `failed`
+     * / `pending`).
+     *
+     * Handles 3DS routing (modal challenge via core-js, or bank redirect)
+     * and async polling until the payment reaches a terminal status.
+     *
+     * This is the same logic `processPayment()` runs after `pay()` — exposed
+     * so callers (and the offers module) that already have a raw `PayResult`
+     * don't need to re-pay.
+     */
+    async finalize(input, opts) {
+        const payment = input.payment;
+        const returnUrl = opts?.returnUrl ?? (typeof window !== 'undefined' ? window.location.href : undefined);
+        if (payment.status === 'succeeded') {
+            return { status: 'succeeded', payment, order: input.order };
+        }
+        if (payment.status === 'failed' || payment.status === 'declined') {
+            const msg = payment.requireActionData?.message
+                || payment.requireActionData?.errorCode
+                || `Payment ${payment.status}`;
+            return { status: 'failed', error: msg, payment };
+        }
+        if (payment.requireAction && payment.requireAction !== 'none' && payment.requireActionData) {
+            return this.handlePaymentAction(payment, { returnUrl });
+        }
+        // 'pending' or 'requires_action' without explicit actionData — poll
+        return this.pollUntilDone(payment.id);
+    }
+    /**
+     * Resume a payment after the user returns from a redirect (3DS, processor auth, APM).
+     *
+     * Called automatically by `usePayment()` in React when it detects return-URL params.
+     * You can also call it manually in non-React apps.
+     */
+    async resumeAfterRedirect(paymentId) {
+        return this.pollUntilDone(paymentId);
+    }
+    /**
+     * Detect a return from a 3DS / processor redirect by inspecting the
+     * current page URL, then poll the payment to completion.
+     *
+     * The post-3DS URL convention used by Tagada-routed processors is
+     * `?paymentAction=requireAction&paymentActionStatus=completed&paymentId=pay_xxx`.
+     * If those params are present, this method polls the payment, cleans the
+     * URL (so a refresh doesn't re-trigger), and returns the resolved
+     * `ProcessPaymentResult`. Otherwise it returns `null`.
+     *
+     * Use this in vanilla apps as the first thing on page load. The React
+     * `usePayment` hook does the same automatically — don't call this when
+     * also using `usePayment`, you'll double-poll.
+     *
+     * @example
+     * ```ts
+     * const tagada = createHeadlessClient({ storeId, environment });
+     *
+     * const resumed = await tagada.payment.maybeResumeFromUrl();
+     * if (resumed?.status === 'succeeded') {
+     *   window.location.href = `/thank-you?orderId=${resumed.order?.id}`;
+     *   return;
+     * }
+     * if (resumed?.status === 'failed') {
+     *   showError(resumed.error);
+     *   return;
+     * }
+     * // No 3DS return — render the normal page.
+     * ```
+     */
+    async maybeResumeFromUrl(opts) {
+        if (typeof window === 'undefined' && !opts?.url)
+            return null;
+        const href = opts?.url ?? window.location.href;
+        let url;
+        try {
+            url = new URL(href);
+        }
+        catch {
+            return null;
+        }
+        const action = url.searchParams.get('paymentAction');
+        const actionStatus = url.searchParams.get('paymentActionStatus');
+        const paymentId = url.searchParams.get('paymentId');
+        if (action !== 'requireAction' || actionStatus !== 'completed' || !paymentId) {
+            return null;
+        }
+        const result = await this.resumeAfterRedirect(paymentId);
+        // Strip the redirect params so a refresh doesn't re-trigger.
+        if (opts?.cleanUrl !== false && typeof window !== 'undefined' && !opts?.url) {
+            const cleanParams = new URLSearchParams(window.location.search);
+            [
+                'paymentAction',
+                'paymentActionStatus',
+                'paymentId',
+                'payment_intent',
+                'payment_intent_client_secret',
+                'source_type',
+                'redirect_status',
+                'sessionId',
+            ].forEach((k) => cleanParams.delete(k));
+            const search = cleanParams.toString();
+            try {
+                window.history.replaceState({}, document.title, window.location.pathname + (search ? '?' + search : ''));
+            }
+            catch {
+                // Best-effort.
+            }
+        }
+        return result;
+    }
+    // ---------------------------------------------------------------------------
+    // Status polling
+    // ---------------------------------------------------------------------------
+    /** Get current status of a payment. */
+    async getPaymentStatus(paymentId) {
+        return this.http.get(`/api/v1/payments/${paymentId}`);
+    }
+    /**
+     * Poll a payment until it reaches a terminal status.
+     * Returns the final status or throws on timeout.
+     */
+    async pollPaymentStatus(paymentId, opts) {
+        const interval = opts?.intervalMs ?? 1500;
+        const timeout = opts?.timeoutMs ?? 60000;
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            const status = await this.getPaymentStatus(paymentId);
+            if (status.status === 'succeeded' || status.status === 'failed' || status.status === 'declined') {
+                return status;
+            }
+            await new Promise((r) => setTimeout(r, interval));
+        }
+        throw new Error(`Payment ${paymentId} did not reach terminal status within ${timeout}ms.`);
+    }
+    /** Finalize a payment after a 3DS challenge completes. */
+    async completeAfter3ds(paymentId) {
+        return this.http.post('/api/v1/payments/complete-after-3ds', {
+            paymentId,
+        });
+    }
+    /** Tell the server this action has been seen / is being processed. */
+    async markActionProcessed(paymentId) {
+        try {
+            await this.http.post('/api/v1/payments/require-action/processed', {
+                paymentId,
+            });
+        }
+        catch {
+            // Best-effort — don't block the payment flow if this fails
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Internal: action routing
+    // ---------------------------------------------------------------------------
+    /**
+     * Route a payment action to the appropriate handler.
+     * Returns `requires_redirect` for browser-level redirects,
+     * or attempts 3DS inline and polls to completion.
+     */
+    async handlePaymentAction(payment, opts) {
+        const actionData = payment.requireActionData;
+        await this.markActionProcessed(payment.id);
+        const actionType = actionData.type;
+        switch (actionType) {
+            case 'threeds_auth':
+                return this.handleThreedsAuth(payment, opts);
+            case 'processor_auth':
+            case 'redirect_to_payment':
+                return this.extractRedirect(payment, actionData);
+            case 'redirect':
+                return this.extractRedirect(payment, actionData);
+            case 'error':
+                return {
+                    status: 'failed',
+                    error: actionData.message || actionData.errorCode || 'Payment failed',
+                    payment,
+                };
+            default:
+                // Unknown action type — try to extract a redirect URL (forward-compatible)
+                return this.extractRedirect(payment, actionData);
+        }
+    }
+    /**
+     * Extract redirect info from actionData.
+     * Works for processor_auth (GET or POST), redirect, and any unknown type with a URL.
+     */
+    extractRedirect(payment, actionData) {
+        const redirect = actionData.metadata?.redirect;
+        const url = redirect?.redirectUrl || actionData.redirectUrl;
+        if (!url) {
+            return {
+                status: 'failed',
+                error: `Payment requires action (${actionData.type}) but no redirect URL was provided`,
+                payment,
+            };
+        }
+        return {
+            status: 'requires_redirect',
+            redirectUrl: url,
+            method: redirect?.method?.toUpperCase() || 'GET',
+            postData: redirect?.data,
+            paymentId: payment.id,
+        };
+    }
+    /**
+     * Run a 3DS challenge using @tagadapay/core-js.
+     * If core-js is not installed, falls back to redirect.
+     */
+    async handleThreedsAuth(payment, opts) {
+        const session = payment.requireActionData?.metadata?.threedsSession;
+        // If no 3DS session data, fall back to redirect (acsChallengeUrl)
+        if (!session?.externalSessionId) {
+            return this.extractRedirect(payment, payment.requireActionData);
+        }
+        // Try to run the challenge inline via core-js
+        let coreJs; // eslint-disable-line @typescript-eslint/no-explicit-any
+        try {
+            coreJs = await import('@tagadapay/core-js');
+        }
+        catch {
+            // core-js not installed — fall back to redirect if possible
+            if (session.acsChallengeUrl) {
+                return {
+                    status: 'requires_redirect',
+                    redirectUrl: session.acsChallengeUrl,
+                    paymentId: payment.id,
+                };
+            }
+            return this.extractRedirect(payment, payment.requireActionData);
+        }
+        // Run BasisTheory 3DS challenge in a modal iframe
+        try {
+            const manager = new coreJs.ThreedsManager({ provider: 'basis_theory' });
+            await manager.initialize({ apiKey: undefined });
+            await manager.startChallenge({
+                sessionId: session.externalSessionId,
+                acsChallengeUrl: session.acsChallengeUrl,
+                acsTransactionId: session.acsTransID,
+                threeDSVersion: session.messageVersion,
+            });
+            // Challenge done — tell backend and poll
+            await this.completeAfter3ds(payment.id);
+            return this.pollUntilDone(payment.id);
+        }
+        catch {
+            // 3DS challenge failed — fall back to redirect
+            if (session.acsChallengeUrl) {
+                return {
+                    status: 'requires_redirect',
+                    redirectUrl: session.acsChallengeUrl,
+                    paymentId: payment.id,
+                };
+            }
+            return {
+                status: 'failed',
+                error: '3D Secure authentication failed',
+                payment,
+            };
+        }
+    }
+    /**
+     * Poll until the payment reaches a terminal status, then return a ProcessPaymentResult.
+     * Also handles new requireAction that may appear during polling.
+     */
+    async pollUntilDone(paymentId, opts) {
+        const interval = opts?.intervalMs ?? 1500;
+        const timeout = opts?.timeoutMs ?? 60000;
+        const start = Date.now();
+        let consecutiveErrors = 0;
+        while (Date.now() - start < timeout) {
+            let status;
+            try {
+                status = await this.getPaymentStatus(paymentId);
+                consecutiveErrors = 0;
+            }
+            catch {
+                consecutiveErrors++;
+                if (consecutiveErrors >= 3) {
+                    return { status: 'failed', error: 'Payment verification failed due to network errors' };
+                }
+                await new Promise((r) => setTimeout(r, interval));
+                continue;
+            }
+            if (status.status === 'succeeded' ||
+                (status.status === 'pending' && status.subStatus === 'authorized')) {
+                return { status: 'succeeded', payment: status, order: status.order };
+            }
+            if (status.status === 'failed' || status.status === 'declined') {
+                return { status: 'failed', error: status.status, payment: status };
+            }
+            // New unprocessed action appeared during polling
+            if (status.requireAction &&
+                status.requireAction !== 'none' &&
+                status.requireActionData &&
+                !status.requireActionData.processed) {
+                return this.handlePaymentAction(status, {});
+            }
+            await new Promise((r) => setTimeout(r, interval));
+        }
+        return { status: 'pending', paymentId };
+    }
+    // ---------------------------------------------------------------------------
+    // Internal helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Read paymentSetupConfig from the Tagada routing injection.
+     * Only available when running on Tagada infra (not on external hosting like Vercel).
+     */
+    readInjectedStepConfig() {
+        if (typeof window === 'undefined')
+            return null;
+        const raw = window.__TGD_STEP_CONFIG__;
+        if (!raw)
+            return null;
+        try {
+            const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+            return parsed?.paymentSetupConfig ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async loadCoreJs() {
+        try {
+            return await import('@tagadapay/core-js');
+        }
+        catch {
+            throw new Error('This method requires @tagadapay/core-js. Install it: npm install @tagadapay/core-js');
+        }
+    }
+}
+//# sourceMappingURL=payment.js.map