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

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

@@ -1,298 +0,0 @@
-import type { HttpClient } from '../http.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;
-    constructor(http: HttpClient, storeId: string, environment: Environment);
-    /**
-     * 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>;
-    /**
-     * Process an Apple Pay payment.
-     * Tokenizes the Apple Pay token and processes payment in one call.
-     */
-    processApplePay(opts: {
-        checkoutSessionId: string;
-        applePayToken: unknown;
-        paymentFlowId?: string;
-        processorId?: string;
-    }): Promise<PayResult>;
-    /**
-     * Process a Google Pay payment.
-     * Tokenizes the Google Pay token and processes payment in one call.
-     */
-    processGooglePay(opts: {
-        checkoutSessionId: string;
-        googlePayToken: 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

@@ -1 +0,0 @@
-{"version":3,"file":"payment.d.ts","sourceRoot":"","sources":["../../../src/core/modules/payment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAElB,cAAc,EACd,WAAW,EACX,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAFX,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,WAAW;IAO3C;;;;;;;;;OASG;IACG,eAAe,CACnB,iBAAiB,EAAE,MAAM,EACzB,IAAI,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;KAAE,GACjD,OAAO,CAAC,kBAAkB,CAAC;IAuB9B;;;OAGG;IACG,iBAAiB,CACrB,iBAAiB,EAAE,MAAM,EACzB,IAAI,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;KAAE,GACjD,OAAO,CAAC,cAAc,CAAC;IAuE1B;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAQ5C;;OAEG;IACG,iBAAiB,CACrB,iBAAiB,EAAE,MAAM,EACzB,IAAI,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;KAAE,GACjD,OAAO,CAAC,MAAM,EAAE,CAAC;IAWpB;;;;;;;;;;;;;OAaG;IACG,YAAY,CAAC,IAAI,EAAE;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAiCvE;;;OAGG;IACG,gBAAgB,CACpB,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC;QAAE,iBAAiB,EAAE,iBAAiB,CAAA;KAAE,CAAC;IAUpD;;;OAGG;IACG,gBAAgB,CAAC,IAAI,EAAE;QAC3B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,WAAW,EAAE;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAC;QACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,cAAc,CAAC;IAa3B;;;;;OAKG;IACG,GAAG,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IA2B/C;;;OAGG;IACG,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC;IAa3D;;;OAGG;IACG,eAAe,CAAC,IAAI,EAAE;QAC1B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,OAAO,CAAC;QACvB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,SAAS,CAAC;IAgBtB;;;OAGG;IACG,gBAAgB,CAAC,IAAI,EAAE;QAC3B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,SAAS,CAAC;IAgBtB;;;OAGG;IACG,UAAU,CAAC,IAAI,EAAE;QACrB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,SAAS,CAAC;IAStB;;;;;;;;;OASG;IACG,oBAAoB,CAAC,IAAI,EAAE;QAC/B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,OAAO,CAAC,SAAS,CAAC;IAatB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAQhF;;;;;;;;;;;;OAYG;IACG,QAAQ,CACZ,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC,oBAAoB,CAAC;IAwBhC;;;;;OAKG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,kBAAkB,CAAC,IAAI,CAAC,EAAE;QAC9B;;;;WAIG;QACH,GAAG,CAAC,EAAE,MAAM,CAAC;QACb;;;WAGG;QACH,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAoDxC,uCAAuC;IACjC,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAIjE;;;OAGG;IACG,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GACjD,OAAO,CAAC,aAAa,CAAC;IAgBzB,0DAA0D;IACpD,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAMjE,sEAAsE;IAChE,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3D;;;;OAIG;YACW,mBAAmB;IAkCjC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAwBvB;;;OAGG;YACW,iBAAiB;IA2D/B;;;OAGG;YACW,aAAa;IAyD3B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;YAahB,UAAU;CASzB"}