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

package/dist/core/index.d.ts

@@ -0,0 +1,15 @@
+export { HeadlessClient, createHeadlessClient } from './client.js';
+export { CheckoutModule } from './modules/checkout.js';
+export { PaymentModule } from './modules/payment.js';
+export { OffersModule } from './modules/offers.js';
+export { CustomerModule } from './modules/customer.js';
+export { CatalogModule } from './modules/catalog.js';
+export { FunnelModule } from './modules/funnel.js';
+export { RxModule } from './modules/rx.js';
+export type { RxCaseStatus, RxRequiredForProduct, RxStorefrontPatient, RxIntakeAnswer, RxClinicalQuestion, RxQuestionsForProduct, RxSubmitCaseInput, RxSubmitCaseResult, RxCaseSummary, } from './modules/rx.js';
+export { HttpClient } from './http.js';
+export { TagadaError, TagadaAuthError, TagadaValidationError, TagadaNotFoundError, TagadaRateLimitError, TagadaPaymentError, TagadaNetworkError, } from './errors.js';
+export { GoogleAutocompleteCore, loadGoogleMapsScript, ISODataCore, AVAILABLE_LANGUAGES, CurrencyUtils, formatMoney, ensureGeoDataLoaded, getCountries, getStatesForCountry, isLanguageLoaded, } from './helpers/index.js';
+export type { GooglePrediction, GooglePlaceDetails, ExtractedAddress, FormattedAddress, SupportedLanguage, ISOCountry, ISORegion, Country, State, Currency, } from './helpers/index.js';
+export type { Environment, HeadlessConfig, HttpRequestOptions, LineItem, CheckoutSession, CheckoutLineItem, CheckoutTotals, CheckoutCustomer, Address, ShippingRate, PaymentMethodConfig, PaymentSetupConfig, ExpressMethod, ExpressMethods, StoreConfig, PayResult, PayOptions, PayDirectOptions, ProcessPaymentOptions, ProcessPaymentResult, CreateInstrumentOptions, PaymentInstrument, ThreedsSession, PaymentStatus, Offer, OfferLineItem, OfferPreview, OfferPreviewItem, OfferPayResult, Customer, Order, OrderItem, Subscription, CatalogProduct, CatalogVariant, CatalogPrice, CurrencyOption, FunnelNavigateInput, FunnelNavigateResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -0,0 +1,13 @@
+export { HeadlessClient, createHeadlessClient } from './client.js';
+export { CheckoutModule } from './modules/checkout.js';
+export { PaymentModule } from './modules/payment.js';
+export { OffersModule } from './modules/offers.js';
+export { CustomerModule } from './modules/customer.js';
+export { CatalogModule } from './modules/catalog.js';
+export { FunnelModule } from './modules/funnel.js';
+export { RxModule } from './modules/rx.js';
+export { HttpClient } from './http.js';
+export { TagadaError, TagadaAuthError, TagadaValidationError, TagadaNotFoundError, TagadaRateLimitError, TagadaPaymentError, TagadaNetworkError, } from './errors.js';
+// Helpers: Google Autocomplete, ISO countries/regions, currency formatting
+export { GoogleAutocompleteCore, loadGoogleMapsScript, ISODataCore, AVAILABLE_LANGUAGES, CurrencyUtils, formatMoney, ensureGeoDataLoaded, getCountries, getStatesForCountry, isLanguageLoaded, } from './helpers/index.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,27 @@
+import type { HttpClient } from '../http.js';
+import type { CatalogProduct } from '../types.js';
+/**
+ * Fetches the product catalog for a store.
+ *
+ * Uses the public `/api/v1/products` endpoint (no auth required).
+ */
+export declare class CatalogModule {
+    private readonly http;
+    private readonly storeId;
+    constructor(http: HttpClient, storeId: string);
+    /**
+     * List all active products for the store, including variants and prices.
+     *
+     * @param opts.productIds  Optional filter to specific product IDs.
+     * @param opts.variantIds  Optional filter to products containing these variant IDs.
+     */
+    getProducts(opts?: {
+        productIds?: string[];
+        variantIds?: string[];
+    }): Promise<CatalogProduct[]>;
+    /**
+     * Get a single product by ID.
+     */
+    getProduct(productId: string): Promise<CatalogProduct | null>;
+}
+//# sourceMappingURL=catalog.d.ts.map

package/dist/core/modules/catalog.js

@@ -0,0 +1,38 @@
+/**
+ * Fetches the product catalog for a store.
+ *
+ * Uses the public `/api/v1/products` endpoint (no auth required).
+ */
+export class CatalogModule {
+    constructor(http, storeId) {
+        this.http = http;
+        this.storeId = storeId;
+    }
+    /**
+     * List all active products for the store, including variants and prices.
+     *
+     * @param opts.productIds  Optional filter to specific product IDs.
+     * @param opts.variantIds  Optional filter to products containing these variant IDs.
+     */
+    async getProducts(opts) {
+        const body = {
+            storeId: this.storeId,
+            includeVariants: true,
+            includePrices: true,
+        };
+        if (opts?.productIds?.length)
+            body.productIds = opts.productIds;
+        if (opts?.variantIds?.length)
+            body.variantIds = opts.variantIds;
+        const res = await this.http.post('/api/v1/products', body);
+        return res.items ?? [];
+    }
+    /**
+     * Get a single product by ID.
+     */
+    async getProduct(productId) {
+        const items = await this.getProducts({ productIds: [productId] });
+        return items[0] ?? null;
+    }
+}
+//# sourceMappingURL=catalog.js.map

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