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

package/dist/core/modules/payment.d.ts

@@ -0,0 +1,353 @@
+import type { HttpClient } from '../http.js';
+import { type ApplePayContact, type GooglePayContact } from '../helpers/walletContact.js';
+import type { CheckoutModule } from './checkout.js';
+import type { Environment, PaymentSetupConfig, ExpressMethods, StoreConfig, PayResult, PayOptions, PayDirectOptions, CreateInstrumentOptions, PaymentInstrument, ThreedsSession, PaymentStatus, ProcessPaymentOptions, ProcessPaymentResult } from '../types.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 declare class PaymentModule {
+    private readonly http;
+    private readonly storeId;
+    private readonly environment;
+    /** Used to persist wallet contacts onto the session before charging. */
+    private readonly checkout?;
+    constructor(http: HttpClient, storeId: string, environment: Environment, 
+    /** Used to persist wallet contacts onto the session before charging. */
+    checkout?: CheckoutModule | undefined);
+    /**
+     * 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`)
+     */
+    getPaymentSetup(checkoutSessionId: string, opts?: {
+        paymentSetupConfig?: PaymentSetupConfig;
+    }): Promise<PaymentSetupConfig>;
+    /**
+     * Get express payment methods (Apple Pay, Google Pay, PayPal, etc.)
+     * filtered to only those available in the current browser.
+     */
+    getExpressMethods(checkoutSessionId: string, opts?: {
+        paymentSetupConfig?: PaymentSetupConfig;
+    }): Promise<ExpressMethods>;
+    /**
+     * Get store-level payment config (3DS flags, default flow ID, etc.).
+     */
+    getStoreConfig(): Promise<StoreConfig>;
+    /**
+     * Convenience: return only enabled payment method keys.
+     */
+    getEnabledMethods(checkoutSessionId: string, opts?: {
+        paymentSetupConfig?: PaymentSetupConfig;
+    }): Promise<string[]>;
+    /**
+     * 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.
+     */
+    tokenizeCard(card: {
+        cardNumber: string;
+        expiryDate: string;
+        cvc: string;
+        cardholderName?: string;
+    }): Promise<{
+        tagadaToken: string;
+        rawToken: Record<string, unknown>;
+    }>;
+    /**
+     * Create a reusable payment instrument from a TagadaToken.
+     * Session-authenticated (uses the checkout session JWT).
+     */
+    createInstrument(opts: CreateInstrumentOptions): Promise<{
+        paymentInstrument: PaymentInstrument;
+    }>;
+    /**
+     * Create a 3DS session on the TagadaPay backend.
+     * This persists the session so the processor can use it during payment.
+     */
+    create3dsSession(opts: {
+        paymentInstrumentId: string;
+        sessionData: {
+            sessionId: string;
+            metadata?: Record<string, unknown>;
+        };
+        provider?: string;
+    }): Promise<ThreedsSession>;
+    /**
+     * 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.
+     */
+    pay(opts: PayOptions): Promise<PayResult>;
+    /**
+     * Low-level pay: process payment with an existing instrument or for APM/express flows
+     * where no instrument is needed (redirect-based methods).
+     */
+    payDirect(opts: PayDirectOptions): Promise<PayResult>;
+    /**
+     * 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.
+     */
+    private syncWalletContact;
+    /**
+     * 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,
+     *   });
+     * };
+     */
+    processApplePay(opts: {
+        checkoutSessionId: string;
+        applePayToken: unknown;
+        billingContact?: ApplePayContact | null;
+        shippingContact?: ApplePayContact | null;
+        paymentFlowId?: string;
+        processorId?: string;
+    }): Promise<PayResult>;
+    /**
+     * 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`.
+     */
+    processGooglePay(opts: {
+        checkoutSessionId: string;
+        googlePayToken: string;
+        billingAddress?: GooglePayContact | null;
+        shippingAddress?: GooglePayContact | null;
+        email?: string;
+        paymentFlowId?: string;
+        processorId?: string;
+    }): Promise<PayResult>;
+    /**
+     * Process an APM payment (Klarna, iDEAL, etc.) via redirect.
+     * These typically don't require a payment instrument -- the processor handles the redirect.
+     */
+    processApm(opts: {
+        checkoutSessionId: string;
+        paymentMethod: string;
+        processorId: string;
+        paymentFlowId?: string;
+    }): Promise<PayResult>;
+    /**
+     * 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.
+     */
+    processStripeExpress(opts: {
+        checkoutSessionId: string;
+        processorId: string;
+        paymentMethod: string;
+    }): Promise<PayResult>;
+    /**
+     * 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;
+     * }
+     * ```
+     */
+    processPayment(opts: ProcessPaymentOptions): Promise<ProcessPaymentResult>;
+    /**
+     * 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.
+     */
+    finalize(input: PayResult, opts?: {
+        returnUrl?: string;
+    }): Promise<ProcessPaymentResult>;
+    /**
+     * 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.
+     */
+    resumeAfterRedirect(paymentId: string): Promise<ProcessPaymentResult>;
+    /**
+     * 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.
+     * ```
+     */
+    maybeResumeFromUrl(opts?: {
+        /**
+         * URL to inspect (defaults to `window.location.href`). Pass an explicit
+         * URL when running outside the browser or when integrating with a
+         * router that hasn't navigated yet.
+         */
+        url?: string;
+        /**
+         * Whether to clean the redirect query params from the address bar
+         * once the payment has been resolved. Defaults to `true`.
+         */
+        cleanUrl?: boolean;
+    }): Promise<ProcessPaymentResult | null>;
+    /** Get current status of a payment. */
+    getPaymentStatus(paymentId: string): Promise<PaymentStatus>;
+    /**
+     * Poll a payment until it reaches a terminal status.
+     * Returns the final status or throws on timeout.
+     */
+    pollPaymentStatus(paymentId: string, opts?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<PaymentStatus>;
+    /** Finalize a payment after a 3DS challenge completes. */
+    completeAfter3ds(paymentId: string): Promise<PaymentStatus>;
+    /** Tell the server this action has been seen / is being processed. */
+    markActionProcessed(paymentId: string): Promise<void>;
+    /**
+     * Route a payment action to the appropriate handler.
+     * Returns `requires_redirect` for browser-level redirects,
+     * or attempts 3DS inline and polls to completion.
+     */
+    private handlePaymentAction;
+    /**
+     * Extract redirect info from actionData.
+     * Works for processor_auth (GET or POST), redirect, and any unknown type with a URL.
+     */
+    private extractRedirect;
+    /**
+     * Run a 3DS challenge using @tagadapay/core-js.
+     * If core-js is not installed, falls back to redirect.
+     */
+    private handleThreedsAuth;
+    /**
+     * Poll until the payment reaches a terminal status, then return a ProcessPaymentResult.
+     * Also handles new requireAction that may appear during polling.
+     */
+    private pollUntilDone;
+    /**
+     * Read paymentSetupConfig from the Tagada routing injection.
+     * Only available when running on Tagada infra (not on external hosting like Vercel).
+     */
+    private readInjectedStepConfig;
+    private loadCoreJs;
+}
+//# sourceMappingURL=payment.d.ts.map

package/dist/core/modules/payment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.d.ts","sourceRoot":"","sources":["../../../src/core/modules/payment.ts"],"names":[],"mappings":"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"}