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

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

@@ -0,0 +1,268 @@
+import type { HttpClient } from '../http.js';
+import type { CheckoutSession, LineItem, ShippingRate, Address, CheckoutCustomer } from '../types.js';
+/**
+ * Result returned by `updateCart()`. Mirrors the
+ * `POST /checkout-sessions/:id/line-items` payload (mutation stats, NOT
+ * a refreshed session). Call `loadSession()` to get an updated session.
+ */
+export interface UpdateCartResult {
+    success: boolean;
+    /** Number of existing line items updated. */
+    updated: number;
+    /** Number of new line items created. */
+    created: number;
+    /** Total number of line items in the cart after the mutation. */
+    total: number;
+}
+/**
+ * Manages checkout sessions — load, update cart, apply promo codes, handle shipping.
+ *
+ * Works for both **shipped** and **digital** products:
+ *
+ * **Shipped products** (physical goods):
+ * ```
+ * updateCustomer(id, { email, firstName, lastName })
+ * updateAddress(id, { shippingAddress: { line1, city, ... } })
+ * getShippingRates(id)
+ * selectShippingRate(id, rateId)
+ * ```
+ *
+ * **Digital products** (no shipping needed):
+ * ```
+ * updateCustomer(id, { email, firstName, lastName })
+ * updateAddress(id, { billingAddress: { line1, city, country } })
+ * // Skip shipping rates — go straight to payment
+ * ```
+ */
+export declare class CheckoutModule {
+    private readonly http;
+    private readonly storeId;
+    private readonly onTokenChange?;
+    private sessionToken;
+    private customerEmail;
+    private customerFirstName;
+    private customerLastName;
+    private customerPhone;
+    /**
+     * Last session returned by `loadSession()`. Cached so sibling modules
+     * (e.g. `FunnelModule`) can read the cart without re-fetching. Cleared
+     * intentionally on no events — call `loadSession()` again to refresh.
+     */
+    private _currentSession;
+    constructor(http: HttpClient, storeId: string, onTokenChange?: ((token: string) => void) | undefined);
+    /**
+     * Returns the most recently loaded `CheckoutSession`, if any.
+     *
+     * Populated by `loadSession()`. Returns `undefined` if the SDK has not
+     * loaded a session yet. Used by `funnel.navigate()` to source the cart.
+     */
+    getCurrentSession(): CheckoutSession | undefined;
+    /**
+     * Load an existing checkout session by its checkout token.
+     *
+     * @param checkoutToken The checkout token (from URL param `checkoutToken`).
+     * @param sessionToken The JWT session token (from URL param `token`). Required for auth.
+     * @param opts.currency Optional presentment currency override (e.g. 'EUR').
+     *   Only applied when the session has no currency set yet (first load).
+     *   Once set, currency is locked to the session and this param is ignored.
+     *
+     * Both `checkoutToken` and `sessionToken` come from the redirect URL returned by `createSession()`.
+     * Example URL: `/checkout?checkoutToken=abc123&token=eyJ...`
+     */
+    loadSession(checkoutToken: string, sessionToken?: string, opts?: {
+        currency?: string;
+    }): Promise<CheckoutSession>;
+    /**
+     * Create a new checkout session.
+     *
+     * Returns a `checkoutToken` and `sessionToken` (JWT) needed for all subsequent calls.
+     * Also returns a `checkoutUrl` (the full Tagada-hosted checkout URL, for reference).
+     */
+    createSession(opts: {
+        items: LineItem[];
+        currency?: string;
+        returnUrl?: string;
+        customerEmail?: string;
+        customerFirstName?: string;
+        customerLastName?: string;
+    }): Promise<{
+        checkoutUrl: string;
+        checkoutToken: string;
+        sessionToken: string;
+        customerId: string;
+    }>;
+    /**
+     * Create a session and produce a self-hosted redirect URL.
+     *
+     * Convenience wrapper around `createSession()`. Builds a URL of the
+     * form `${origin}${checkoutPath}?checkoutToken=...&sessionToken=...`
+     * that you can navigate to from a Cart page. The receiving page reads
+     * the params via {@link CheckoutModule.parseTokensFromUrl} and calls
+     * {@link CheckoutModule.loadSession}.
+     *
+     * For Tagada-hosted checkouts use the `checkoutUrl` returned by
+     * `createSession()` directly — this helper is for **self-hosted**
+     * checkout pages.
+     *
+     * @example
+     * ```ts
+     * const { url } = await tagada.checkout.createSessionUrl({
+     *   items: [{ variantId, quantity: 1 }],
+     *   checkoutPath: '/checkout',
+     * });
+     * window.location.href = url;
+     * ```
+     */
+    createSessionUrl(opts: {
+        items: LineItem[];
+        currency?: string;
+        returnUrl?: string;
+        customerEmail?: string;
+        customerFirstName?: string;
+        customerLastName?: string;
+        /** Path on the current origin for the self-hosted checkout. Default: `/checkout`. */
+        checkoutPath?: string;
+        /** Origin to use. Defaults to `window.location.origin`. */
+        origin?: string;
+    }): Promise<{
+        url: string;
+        checkoutUrl: string;
+        checkoutToken: string;
+        sessionToken: string;
+        customerId: string;
+    }>;
+    /**
+     * Read `checkoutToken` and session token from a URL.
+     *
+     * Recognizes both the SDK convention (`?sessionToken=`) and the
+     * Tagada-hosted convention (`?token=`), so the same checkout page
+     * works whether the user came from `createSessionUrl()` or directly
+     * from a Tagada-hosted redirect.
+     *
+     * Returns `null` if `checkoutToken` is missing.
+     *
+     * @example
+     * ```ts
+     * const tokens = CheckoutModule.parseTokensFromUrl();
+     * if (!tokens) {
+     *   window.location.href = '/cart';
+     *   return;
+     * }
+     * const session = await tagada.checkout.loadSession(
+     *   tokens.checkoutToken,
+     *   tokens.sessionToken,
+     * );
+     * ```
+     */
+    static parseTokensFromUrl(url?: string): {
+        checkoutToken: string;
+        sessionToken: string;
+    } | null;
+    /**
+     * Add or update cart items on an existing session (upsert by product).
+     *
+     * Sends each item as `lineItems` to `POST /checkout-sessions/:id/line-items`.
+     * The endpoint UPSERTs by product: it adds new products and updates the
+     * variant/quantity of products already in the cart, but it does NOT remove
+     * products omitted from `items`, and an empty array is a no-op (it does not
+     * clear the cart). Each `quantity` must be >= 1 — removal is not supported by
+     * this endpoint.
+     *
+     * Returns a server-side mutation summary (counts of created/updated rows).
+     * It does NOT return the updated `CheckoutSession` — the underlying endpoint
+     * never has and the previous typing was a lie that quietly assigned
+     * `{ success, updated, ... }` into a `CheckoutSession` slot in `useCheckout`.
+     *
+     * Call `loadSession()` after this if you need the refreshed session
+     * (the React `useCheckout` hook does this for you).
+     */
+    updateCart(sessionId: string, items: LineItem[]): Promise<UpdateCartResult>;
+    /**
+     * Update customer identity (email, name, phone).
+     *
+     * Call this before `updateAddress()` — the SDK remembers the values and
+     * includes them automatically when addresses are submitted.
+     *
+     * If you prefer a single call, use `updateCustomerAndAddress()` instead.
+     */
+    updateCustomer(sessionId: string, customer: Partial<CheckoutCustomer>): Promise<void>;
+    /**
+     * Update shipping and/or billing address on the session.
+     *
+     * Automatically includes customer name/phone stored from `updateCustomer()`.
+     * Uses the same atomic API call as the production checkout, so email,
+     * customer name, and addresses are all persisted together.
+     *
+     * **Shipped products**: pass `shippingAddress`. If `billingAddress` is omitted,
+     * the shipping address is automatically used as billing.
+     *
+     * **Digital products**: pass only `billingAddress` (no shipping needed).
+     *
+     * @example
+     * // Shipped product — billing = shipping automatically
+     * await checkout.updateAddress(sessionId, {
+     *   shippingAddress: { line1: '10 Rue de la Paix', city: 'Paris', postalCode: '75002', country: 'FR' },
+     * });
+     *
+     * @example
+     * // Digital product — billing only
+     * await checkout.updateAddress(sessionId, {
+     *   billingAddress: { country: 'FR' },
+     * });
+     */
+    updateAddress(sessionId: string, addresses: {
+        shippingAddress?: Address;
+        billingAddress?: Address;
+    }): Promise<void>;
+    /**
+     * Set customer info + addresses in one call (mirrors production checkout).
+     *
+     * Equivalent to calling `updateCustomer()` then `updateAddress()`, but
+     * in a single network request.
+     */
+    updateCustomerAndAddress(sessionId: string, data: {
+        customer: Partial<CheckoutCustomer>;
+        shippingAddress?: Address;
+        billingAddress?: Address;
+    }): Promise<void>;
+    /** Map an SDK Address to the API shape, injecting stored customer fields. */
+    private mapAddress;
+    /** Apply a promotion code to the session. */
+    applyPromoCode(sessionId: string, code: string): Promise<void>;
+    /** Remove a promotion from the session by promotion ID. */
+    removePromoCode(sessionId: string, promotionId?: string): Promise<void>;
+    /**
+     * Fetch available shipping rates for the session's address.
+     * Only relevant for **shipped products** — digital products can skip this step.
+     *
+     * Requires a shipping address to be set first via `updateAddress()`.
+     * Returns an empty array if no rates are configured or address is missing.
+     */
+    getShippingRates(sessionId: string): Promise<ShippingRate[]>;
+    /**
+     * Normalize the v1 rates payload (`shippingRateName`, `estimatedDeliveryTime`)
+     * to the SDK's `ShippingRate` shape (`name`, `estimatedDays`). Without
+     * this the consumer's UI shows blank rate names — the demo's "Delivery"
+     * radios were rendering only the price, no label.
+     */
+    private normalizeShippingRate;
+    /**
+     * Select a shipping rate for the session.
+     * Only relevant for **shipped products** — digital products can skip this step.
+     */
+    selectShippingRate(sessionId: string, rateId: string): Promise<void>;
+    /**
+     * Normalize the raw v2 API response into a cleaner CheckoutSession shape.
+     * The raw response has nested `checkoutSession` + `summary` -- we flatten it.
+     */
+    private normalizeSession;
+    /**
+     * Map the raw API address shape (`address1`, `address2`, `postal`) onto
+     * the SDK's `Address` shape (`line1`, `line2`, `postalCode`). Without
+     * this, `session.shippingAddress.line1` is silently undefined after a
+     * reload — the type was lying about the actual key names — which is
+     * what makes the demo lose form state on refresh.
+     */
+    private normalizeAddress;
+}
+//# sourceMappingURL=checkout.d.ts.map

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

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