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

package/dist/core/modules/funnel.js

@@ -0,0 +1,138 @@
+import { TagadaError } from '../errors.js';
+/**
+ * Initialize a funnel session from the SDK's current cart and produce a
+ * redirect URL into a funnel step.
+ *
+ * Mirrors the WooCommerce checkout plugin
+ * (`public/assets/php/woocommerce/tagada-checkout-plugin.php`):
+ *
+ *  1. `POST /api/v1/cms/session/anonymous` — public, returns a CMS token.
+ *  2. `POST /api/v1/cms/session/v2/init`   — uses the token, returns a CMS customer id.
+ *  3. `POST /api/v1/funnel/initialize`     — creates the funnel session.
+ *  4. `POST /api/v1/funnel/navigate`       — fires an `INIT_CHECKOUT` event and returns `{ url }`.
+ *
+ * Steps 1–3 are cached on the module instance, so repeat `navigate()` calls in
+ * the same page only fire step 4.
+ *
+ * **Prerequisite**: the SDK must have a loaded `CheckoutSession`
+ * (`sdk.checkout.loadSession(...)`). The cart is sourced from `session.items`,
+ * the currency from `session.currency`, the customer email from
+ * `session.customer.email`, and the promotion code from `session.promotionCode`.
+ */
+export class FunnelModule {
+    constructor(http, storeId, checkout, accountId) {
+        this.http = http;
+        this.storeId = storeId;
+        this.checkout = checkout;
+        this.accountId = accountId;
+    }
+    async navigate(input) {
+        const session = this.checkout.getCurrentSession();
+        if (!session) {
+            throw new TagadaError('No checkout session loaded. Call sdk.checkout.loadSession(...) before sdk.funnel.navigate(...).', 'no_cart_loaded');
+        }
+        const accountId = input.accountId ?? this.accountId;
+        if (!accountId) {
+            throw new TagadaError('accountId is required for funnel.navigate(). Set it on createHeadlessClient({ accountId }) or pass it per call.', 'missing_account_id');
+        }
+        const currentUrl = input.currentUrl ?? (typeof globalThis !== 'undefined' ? globalThis.location?.href : undefined);
+        await this.ensureCmsSession(session, accountId, input);
+        const funnelSessionId = await this.initializeFunnel({
+            funnelId: input.funnelId,
+            stepId: input.stepId,
+            accountId,
+            currentUrl,
+        });
+        const url = await this.runNavigate({
+            funnelSessionId,
+            stepId: input.stepId,
+            session,
+            input,
+            currentUrl,
+        });
+        return { url, funnelSessionId };
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    async ensureCmsSession(session, accountId, input) {
+        if (this._cmsToken && this._cmsSessionId && this._cmsCustomerId)
+            return;
+        const anon = await this.http.post('/api/v1/cms/session/anonymous', { storeId: this.storeId, role: 'anonymous', draft: false });
+        this._cmsToken = anon.token;
+        this._cmsSessionId = anon.sessionId;
+        const init = await this.http.post('/api/v1/cms/session/v2/init', {
+            storeId: this.storeId,
+            accountId,
+            customerId: 'anon_placeholder',
+            browserLocale: input.customer?.locale ?? defaultLocale(),
+            userAgent: defaultUserAgent(),
+            queryCurrency: input.customer?.currency ?? session.currency,
+            queryLocale: input.customer?.locale,
+        }, { token: this._cmsToken });
+        this._cmsCustomerId = init.customer.id;
+    }
+    async initializeFunnel(args) {
+        const res = await this.http.post('/api/v1/funnel/initialize', {
+            cmsSession: {
+                customerId: this._cmsCustomerId,
+                sessionId: this._cmsSessionId,
+                storeId: this.storeId,
+                accountId: args.accountId,
+            },
+            funnelId: args.funnelId,
+            entryStepId: args.stepId,
+            funnelStepId: args.stepId,
+            currentUrl: args.currentUrl,
+            draft: false,
+        }, { token: this._cmsToken });
+        return res.context.sessionId;
+    }
+    async runNavigate(args) {
+        const { funnelSessionId, stepId, session, input, currentUrl } = args;
+        const lineItems = session.items.map((i) => ({
+            variantId: i.variantId,
+            priceId: i.priceId,
+            quantity: i.quantity,
+        }));
+        const discountCodes = input.discountCodes ??
+            (session.promotionCode ? [session.promotionCode] : undefined);
+        const customer = {
+            email: input.customer?.email ?? session.customer?.email,
+            currency: input.customer?.currency ?? session.currency,
+            locale: input.customer?.locale,
+        };
+        const res = await this.http.post('/api/v1/funnel/navigate', {
+            sessionId: funnelSessionId,
+            currentUrl,
+            funnelStepId: stepId,
+            fireAndForget: false,
+            event: {
+                type: 'INIT_CHECKOUT',
+                data: {
+                    checkoutInit: {
+                        cartToken: session.id,
+                        lineItems,
+                        customer,
+                        returnUrl: input.returnUrl,
+                        storeId: this.storeId,
+                        metadata: input.metadata,
+                        discountCodes,
+                    },
+                },
+            },
+        }, { token: this._cmsToken });
+        return res.result.url;
+    }
+}
+function defaultLocale() {
+    if (typeof navigator !== 'undefined' && navigator.language)
+        return navigator.language;
+    return 'en-US';
+}
+function defaultUserAgent() {
+    if (typeof navigator !== 'undefined' && navigator.userAgent)
+        return navigator.userAgent;
+    return 'tagadapay-headless-sdk';
+}
+//# sourceMappingURL=funnel.js.map

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

@@ -0,0 +1,137 @@
+import type { HttpClient } from '../http.js';
+import type { Offer, OfferPreview, OfferPayResult, ProcessPaymentResult } from '../types.js';
+import type { PaymentModule } from './payment.js';
+/**
+ * Offers — upsells, downsells, order bumps, and post-purchase offers.
+ *
+ * Endpoints align with the plugin-sdk patterns:
+ *   GET  /api/v1/offers/:id                             — single offer
+ *   GET  /api/v1/stores/:storeId/offers                 — list store offers
+ *   POST /api/v1/offers/:offerId/preview                — preview pricing
+ *   POST /api/v1/offers/:offerId/pay-preview            — pay a previewed offer (one-click)
+ *   POST /api/v1/checkout-sessions/:id/toggle-order-bump — toggle order bump
+ *   GET  /api/v1/post-purchase/:orderId/offers          — post-purchase offers for an order
+ *   POST /api/v1/orders/:orderId/post-purchase-offers/:offerId/accept  — accept
+ *   POST /api/v1/orders/:orderId/post-purchase-offers/:offerId/decline — decline
+ */
+export declare class OffersModule {
+    private readonly http;
+    private readonly storeId;
+    private readonly payment?;
+    constructor(http: HttpClient, storeId: string, payment?: PaymentModule | undefined);
+    /** Get a single offer by ID. */
+    getOffer(offerId: string): Promise<Offer>;
+    /** List offers for the current store. Optionally filter by type or a set of IDs. */
+    listOffers(opts?: {
+        type?: 'upsell' | 'orderbump';
+        ids?: string[];
+    }): Promise<Offer[]>;
+    /** Preview offer pricing. Returns line items with amounts and totals. */
+    previewOffer(opts: {
+        offerId: string;
+        currency?: string;
+        lineItems?: Array<{
+            lineItemId?: string;
+            productId?: string;
+            variantId: string;
+            quantity: number;
+        }>;
+    }): Promise<OfferPreview>;
+    /**
+     * Pay a previously previewed offer (one-click charge).
+     * Used after a main order so the stored payment instrument is reused.
+     *
+     * **Low-level API.** Returns the raw `OfferPayResult` — `requireAction`,
+     * polling, and 3DS redirects are NOT handled. For most cases, use
+     * {@link processOfferPayment} which orchestrates the full lifecycle.
+     */
+    payPreviewedOffer(opts: {
+        offerId: string;
+        mainOrderId: string;
+        currency?: string;
+        lineItems?: Array<{
+            lineItemId?: string;
+            productId?: string;
+            variantId: string;
+            quantity: number;
+        }>;
+        returnUrl?: string;
+        paymentInstrumentId?: string;
+    }): Promise<OfferPayResult>;
+    /**
+     * One-click upsell with full lifecycle handling.
+     *
+     * Like `payment.processPayment()` but for previewed offers: charges the
+     * stored instrument from `mainOrderId`, runs any 3DS challenge or bank
+     * redirect, polls until terminal, and returns a typed
+     * `ProcessPaymentResult` (`succeeded` / `requires_redirect` /
+     * `failed` / `pending`).
+     *
+     * Use this instead of the lower-level `payPreviewedOffer()` whenever you
+     * don't need to inspect the raw `OfferPayResult` shape — which is most
+     * of the time.
+     *
+     * @example
+     * ```ts
+     * const result = await tagada.offers.processOfferPayment({
+     *   offerId: 'offer_xxx',
+     *   mainOrderId: order.id,
+     *   returnUrl: window.location.href,
+     * });
+     *
+     * switch (result.status) {
+     *   case 'succeeded':
+     *     window.location.href = '/upsell-2';
+     *     break;
+     *   case 'requires_redirect':
+     *     window.location.href = result.redirectUrl;
+     *     break;
+     *   case 'failed':
+     *     showError(result.error);
+     *     break;
+     * }
+     * ```
+     */
+    processOfferPayment(opts: {
+        offerId: string;
+        mainOrderId: string;
+        currency?: string;
+        lineItems?: Array<{
+            lineItemId?: string;
+            productId?: string;
+            variantId: string;
+            quantity: number;
+        }>;
+        returnUrl?: string;
+        paymentInstrumentId?: string;
+    }): Promise<ProcessPaymentResult>;
+    /** Toggle an order bump on/off within a checkout session. */
+    toggleOrderBump(opts: {
+        checkoutSessionId: string;
+        orderBumpOfferId: string;
+        selected: boolean;
+    }): Promise<unknown>;
+    /** List post-purchase offers for an order. */
+    listPostPurchaseOffers(orderId: string): Promise<Offer[]>;
+    /** Accept a post-purchase offer. */
+    acceptPostPurchaseOffer(opts: {
+        orderId: string;
+        offerId: string;
+        items?: Array<{
+            variantId: string;
+            quantity: number;
+        }>;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Decline a post-purchase offer. */
+    declinePostPurchaseOffer(opts: {
+        orderId: string;
+        offerId: string;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+//# sourceMappingURL=offers.d.ts.map

package/dist/core/modules/offers.js

@@ -0,0 +1,141 @@
+/**
+ * Offers — upsells, downsells, order bumps, and post-purchase offers.
+ *
+ * Endpoints align with the plugin-sdk patterns:
+ *   GET  /api/v1/offers/:id                             — single offer
+ *   GET  /api/v1/stores/:storeId/offers                 — list store offers
+ *   POST /api/v1/offers/:offerId/preview                — preview pricing
+ *   POST /api/v1/offers/:offerId/pay-preview            — pay a previewed offer (one-click)
+ *   POST /api/v1/checkout-sessions/:id/toggle-order-bump — toggle order bump
+ *   GET  /api/v1/post-purchase/:orderId/offers          — post-purchase offers for an order
+ *   POST /api/v1/orders/:orderId/post-purchase-offers/:offerId/accept  — accept
+ *   POST /api/v1/orders/:orderId/post-purchase-offers/:offerId/decline — decline
+ */
+export class OffersModule {
+    constructor(http, storeId, payment) {
+        this.http = http;
+        this.storeId = storeId;
+        this.payment = payment;
+    }
+    // ---------------------------------------------------------------------------
+    // Offer loading
+    // ---------------------------------------------------------------------------
+    /** Get a single offer by ID. */
+    async getOffer(offerId) {
+        return this.http.get(`/api/v1/offers/${offerId}`);
+    }
+    /** List offers for the current store. Optionally filter by type or a set of IDs. */
+    async listOffers(opts) {
+        let url = `/api/v1/stores/${this.storeId}/offers`;
+        const queryParts = [];
+        if (opts?.type)
+            queryParts.push(`type=${encodeURIComponent(opts.type)}`);
+        if (opts?.ids?.length) {
+            for (const id of opts.ids)
+                queryParts.push(`ids=${encodeURIComponent(id)}`);
+        }
+        if (queryParts.length)
+            url += `?${queryParts.join('&')}`;
+        const res = await this.http.get(url);
+        return res.offers ?? [];
+    }
+    // ---------------------------------------------------------------------------
+    // Preview & pay (one-click upsell flow from plugin-sdk)
+    // ---------------------------------------------------------------------------
+    /** Preview offer pricing. Returns line items with amounts and totals. */
+    async previewOffer(opts) {
+        return this.http.post(`/api/v1/offers/${opts.offerId}/preview`, {
+            offerId: opts.offerId,
+            currency: opts.currency ?? '',
+            lineItems: opts.lineItems,
+        });
+    }
+    /**
+     * Pay a previously previewed offer (one-click charge).
+     * Used after a main order so the stored payment instrument is reused.
+     *
+     * **Low-level API.** Returns the raw `OfferPayResult` — `requireAction`,
+     * polling, and 3DS redirects are NOT handled. For most cases, use
+     * {@link processOfferPayment} which orchestrates the full lifecycle.
+     */
+    async payPreviewedOffer(opts) {
+        return this.http.post(`/api/v1/offers/${opts.offerId}/pay-preview`, {
+            offerId: opts.offerId,
+            currency: opts.currency ?? '',
+            lineItems: opts.lineItems,
+            returnUrl: opts.returnUrl ?? (typeof window !== 'undefined' ? window.location.href : ''),
+            mainOrderId: opts.mainOrderId,
+            paymentInstrumentId: opts.paymentInstrumentId,
+        });
+    }
+    /**
+     * One-click upsell with full lifecycle handling.
+     *
+     * Like `payment.processPayment()` but for previewed offers: charges the
+     * stored instrument from `mainOrderId`, runs any 3DS challenge or bank
+     * redirect, polls until terminal, and returns a typed
+     * `ProcessPaymentResult` (`succeeded` / `requires_redirect` /
+     * `failed` / `pending`).
+     *
+     * Use this instead of the lower-level `payPreviewedOffer()` whenever you
+     * don't need to inspect the raw `OfferPayResult` shape — which is most
+     * of the time.
+     *
+     * @example
+     * ```ts
+     * const result = await tagada.offers.processOfferPayment({
+     *   offerId: 'offer_xxx',
+     *   mainOrderId: order.id,
+     *   returnUrl: window.location.href,
+     * });
+     *
+     * switch (result.status) {
+     *   case 'succeeded':
+     *     window.location.href = '/upsell-2';
+     *     break;
+     *   case 'requires_redirect':
+     *     window.location.href = result.redirectUrl;
+     *     break;
+     *   case 'failed':
+     *     showError(result.error);
+     *     break;
+     * }
+     * ```
+     */
+    async processOfferPayment(opts) {
+        if (!this.payment) {
+            throw new Error('OffersModule: no PaymentModule injected. ' +
+                'Use createHeadlessClient() instead of constructing OffersModule directly.');
+        }
+        const returnUrl = opts.returnUrl ?? (typeof window !== 'undefined' ? window.location.href : undefined);
+        const payResult = await this.payPreviewedOffer({ ...opts, returnUrl });
+        return this.payment.finalize({ payment: payResult.payment, order: payResult.order }, { returnUrl });
+    }
+    // ---------------------------------------------------------------------------
+    // Order bumps (checkout-session scoped)
+    // ---------------------------------------------------------------------------
+    /** Toggle an order bump on/off within a checkout session. */
+    async toggleOrderBump(opts) {
+        return this.http.post(`/api/v1/checkout-sessions/${opts.checkoutSessionId}/toggle-order-bump`, {
+            orderBumpOfferId: opts.orderBumpOfferId,
+            selected: opts.selected,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Post-purchase offers (order-scoped)
+    // ---------------------------------------------------------------------------
+    /** List post-purchase offers for an order. */
+    async listPostPurchaseOffers(orderId) {
+        const res = await this.http.get(`/api/v1/post-purchase/${orderId}/offers`);
+        return Array.isArray(res) ? res : [];
+    }
+    /** Accept a post-purchase offer. */
+    async acceptPostPurchaseOffer(opts) {
+        return this.http.post(`/api/v1/orders/${opts.orderId}/post-purchase-offers/${opts.offerId}/accept`, { items: opts.items ?? [] });
+    }
+    /** Decline a post-purchase offer. */
+    async declinePostPurchaseOffer(opts) {
+        return this.http.post(`/api/v1/orders/${opts.orderId}/post-purchase-offers/${opts.offerId}/decline`);
+    }
+}
+//# sourceMappingURL=offers.js.map