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

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

@@ -0,0 +1,162 @@
+import type { HttpClient } from '../http.js';
+/**
+ * Tagada Rx — storefront module.
+ *
+ * Drives the post-checkout clinical case flow from the browser:
+ *   1. Ask the API whether a product needs an Rx case.
+ *   2. After the order is paid, submit the intake (patient + answers)
+ *      with the `(orderId, checkoutToken)` ownership proof.
+ *   3. Poll the case status from the thank-you page.
+ *
+ * PHI handling: the `patient` and `intakeAnswers` payloads are sent
+ * straight to the Tagada API which forwards them to the clinical
+ * network (e.g. MDI). Tagada NEVER persists PHI in its database.
+ *
+ * Auth model: there is no API key. Each route authorizes per-resource
+ * (productId is public; case routes require the checkoutToken the
+ * storefront already received when it bootstrapped the checkout).
+ *
+ * @example
+ * ```ts
+ * const { required } = await tagada.rx.isRequiredForProduct(productId);
+ * if (required) {
+ *   const intake = await collectIntakeFromUser();
+ *   const res = await tagada.rx.submitCase({
+ *     orderId, checkoutToken, productId,
+ *     patient, intakeAnswers: intake,
+ *   });
+ *   router.push(`/thank-you?rxCase=${res.rxCaseId}`);
+ * }
+ * ```
+ */
+export type RxCaseStatus = 'requested' | 'submitted' | 'in_review' | 'approved' | 'shipped' | 'delivered' | 'declined' | 'cancelled' | 'error';
+export interface RxRequiredForProduct {
+    required: boolean;
+    clinicalNetworkId: string | null;
+    externalOfferingId: string | null;
+    requiresLabs: boolean;
+    requiresIdVerification: boolean;
+    isDeaControlled: boolean;
+}
+export interface RxStorefrontPatient {
+    firstName: string;
+    lastName: string;
+    email: string;
+    phone?: string | null;
+    /** ISO date YYYY-MM-DD. */
+    dateOfBirth: string;
+    sexAtBirth: 'male' | 'female' | 'unspecified';
+    address: {
+        line1: string;
+        line2?: string;
+        city: string;
+        state: string;
+        zip: string;
+        /** ISO 3166-1 alpha-2 country code. */
+        country: string;
+    };
+    /** Patient-level clinical fields (MDI Full API / Judd). */
+    weight?: number | string;
+    height?: number | string;
+    allergies?: string;
+    pregnancy?: boolean | string;
+    currentMedications?: string;
+    medicalConditions?: string;
+    specialNecessities?: string;
+    driverLicenseId?: string;
+    introVideoId?: string;
+}
+export interface RxIntakeAnswer {
+    questionId: string;
+    value: string | number | boolean | string[];
+    comment?: string;
+    /** Exact question text shown to the patient (MDI case_questions.question). */
+    question?: string;
+    /** MDI answer type: string | number | boolean. */
+    type?: string;
+    important?: boolean;
+    isCritical?: boolean;
+    displayInPdf?: boolean;
+    description?: string;
+    label?: string;
+    metadata?: string;
+    /** Options presented for MCQ questions. */
+    displayedOptions?: string[];
+}
+export interface RxClinicalQuestion {
+    externalQuestionId: string;
+    title: string;
+    description: string | null;
+    placeholder: string | null;
+    type: string;
+    required: boolean;
+    order: number;
+    options: {
+        value: string;
+        label: string;
+    }[];
+}
+export interface RxQuestionsForProduct {
+    required: boolean;
+    externalQuestionnaireId: string | null;
+    questions: RxClinicalQuestion[];
+}
+export interface RxSubmitCaseInput {
+    orderId: string;
+    checkoutToken: string;
+    productId: string;
+    patient: RxStorefrontPatient;
+    intakeAnswers: RxIntakeAnswer[];
+    preferredPharmacyId?: string;
+}
+export interface RxSubmitCaseResult {
+    rxCaseId: string;
+    externalCaseId: string;
+    status: 'submitted' | 'error';
+    accrualAmountMinor: number;
+    accrualCurrency: string;
+}
+export interface RxCaseSummary {
+    id: string;
+    status: RxCaseStatus;
+    externalCaseId: string | null;
+    lastShipmentShippedAt: string | null;
+    createdAt: string;
+}
+export declare class RxModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Check whether a product requires an Rx case. Storefronts call this
+     * before rendering the intake form so they only ask the patient
+     * questions when really necessary.
+     *
+     * Read-only / public — does not require any ownership proof.
+     */
+    isRequiredForProduct(productId: string, opts?: {
+        clinicalNetworkId?: string;
+    }): Promise<RxRequiredForProduct>;
+    /**
+     * Look up the Rx cases attached to an order. Storefronts poll this
+     * on the thank-you page to render "Your prescription is being
+     * reviewed" → "Shipped" transitions.
+     */
+    getCasesForOrder(input: {
+        orderId: string;
+        checkoutToken: string;
+    }): Promise<{
+        cases: RxCaseSummary[];
+    }>;
+    /**
+     * Submit a fresh clinical case for a freshly-paid order. PHI is
+     * forwarded to the clinical network and never persisted on
+     * Tagada-side rows.
+     */
+    submitCase(input: RxSubmitCaseInput): Promise<RxSubmitCaseResult>;
+    /**
+     * Fetch the network-authored intake questions for a product.
+     * Empty `questions` means the storefront should use its local quiz.
+     */
+    getQuestionsForProduct(productId: string): Promise<RxQuestionsForProduct>;
+}
+//# sourceMappingURL=rx.d.ts.map

package/dist/core/modules/rx.js

@@ -0,0 +1,46 @@
+export class RxModule {
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Check whether a product requires an Rx case. Storefronts call this
+     * before rendering the intake form so they only ask the patient
+     * questions when really necessary.
+     *
+     * Read-only / public — does not require any ownership proof.
+     */
+    async isRequiredForProduct(productId, opts) {
+        return this.http.get('/api/public/v1/rx/required-for-product', {
+            params: {
+                productId,
+                clinicalNetworkId: opts?.clinicalNetworkId,
+            },
+        });
+    }
+    /**
+     * Look up the Rx cases attached to an order. Storefronts poll this
+     * on the thank-you page to render "Your prescription is being
+     * reviewed" → "Shipped" transitions.
+     */
+    async getCasesForOrder(input) {
+        return this.http.post('/api/public/v1/rx/cases/lookup', input);
+    }
+    /**
+     * Submit a fresh clinical case for a freshly-paid order. PHI is
+     * forwarded to the clinical network and never persisted on
+     * Tagada-side rows.
+     */
+    async submitCase(input) {
+        return this.http.post('/api/public/v1/rx/cases/submit', input);
+    }
+    /**
+     * Fetch the network-authored intake questions for a product.
+     * Empty `questions` means the storefront should use its local quiz.
+     */
+    async getQuestionsForProduct(productId) {
+        return this.http.get('/api/public/v1/rx/questions-for-product', {
+            params: { productId },
+        });
+    }
+}
+//# sourceMappingURL=rx.js.map

package/dist/core/types.d.ts

@@ -0,0 +1,505 @@
+export type Environment = 'production' | 'development' | 'local';
+export interface HeadlessConfig {
+    /** Your TagadaPay store ID (e.g. "store_abc123"). */
+    storeId: string;
+    /**
+     * Your TagadaPay account ID (e.g. "acc_abc123"). Required for
+     * `funnel.navigate()` — the CMS session + funnel-init endpoints reject calls
+     * without it. Optional for pure checkout / payment flows.
+     */
+    accountId?: string;
+    /** Environment. Defaults to "production". */
+    environment?: Environment;
+    /** Public API key for authenticated requests. Optional -- many flows use checkout tokens instead. */
+    apiKey?: string;
+    /** Override the base API URL. Auto-resolved from environment if omitted. */
+    baseUrl?: string;
+    /** Request timeout in ms. Default 30000. */
+    timeout?: number;
+}
+export interface HttpRequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+    headers?: Record<string, string>;
+    params?: Record<string, string | number | boolean | undefined>;
+    /** Override the auth token for this single request. */
+    token?: string;
+    signal?: AbortSignal;
+}
+export interface LineItem {
+    variantId: string;
+    priceId?: string;
+    quantity: number;
+}
+export interface CheckoutSession {
+    id: string;
+    storeId: string;
+    checkoutToken: string;
+    currency: string;
+    items: CheckoutLineItem[];
+    totals: CheckoutTotals;
+    customer?: CheckoutCustomer;
+    shippingAddress?: Address;
+    billingAddress?: Address;
+    /**
+     * ID of the shipping rate currently selected on the session, if any.
+     * Set by `selectShippingRate()` and persisted on the server. Use this
+     * to pre-select the radio button in your shipping rate UI after a
+     * page refresh — without it the customer has to re-pick the rate
+     * every time the form remounts.
+     */
+    selectedShippingRateId?: string | null;
+    promotionCode?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface CheckoutLineItem {
+    id: string;
+    variantId: string;
+    priceId?: string;
+    productName: string;
+    variantName: string;
+    quantity: number;
+    unitAmount: number;
+    totalAmount: number;
+    currency: string;
+    imageUrl?: string;
+    recurring?: {
+        interval: string;
+        intervalCount: number;
+    };
+}
+export interface CheckoutTotals {
+    subtotal: number;
+    discount: number;
+    shipping: number;
+    tax: number;
+    total: number;
+    currency: string;
+}
+export interface CheckoutCustomer {
+    id?: string;
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+}
+export interface Address {
+    firstName?: string;
+    lastName?: string;
+    line1?: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+    phone?: string;
+}
+export interface ShippingRate {
+    id: string;
+    name: string;
+    description?: string;
+    amount: number;
+    currency: string;
+    estimatedDays?: number;
+}
+export interface PaymentMethodConfig {
+    enabled: boolean;
+    method: string;
+    provider?: string;
+    type?: string;
+    label?: string;
+    logoUrl?: string;
+    description?: string;
+    express?: boolean;
+    paymentFlowId?: string;
+    processorId?: string;
+    integrationId?: string;
+    publishableKey?: string;
+    /** Map of express method keys to their enabled state (e.g. apple_pay, google_pay). */
+    methods?: Record<string, {
+        enabled: boolean;
+    }>;
+    metadata?: Record<string, unknown>;
+}
+export type PaymentSetupConfig = Record<string, PaymentMethodConfig>;
+export interface ExpressMethod {
+    type: string;
+    available: boolean;
+    processorId?: string;
+    publishableKey?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ExpressMethods {
+    applePay?: ExpressMethod;
+    googlePay?: ExpressMethod;
+    paypal?: ExpressMethod;
+    klarna?: ExpressMethod;
+    link?: ExpressMethod;
+}
+/**
+ * Options for initializing the Stripe Express Checkout Element.
+ * Used by `StripeExpressCheckout` (vanilla) and `useStripeExpress` (React).
+ */
+export interface StripeExpressOptions {
+    /** Stripe publishable key (pk_xxx). Obtained from `getExpressMethods()`. */
+    publishableKey: string;
+    /** Processor ID for the Stripe express integration. */
+    processorId: string;
+    /** Which express methods to show: 'apple_pay', 'google_pay', 'paypal', 'link', 'klarna_express'. */
+    enabledMethods?: string[];
+    /** Button height in pixels. Default: 48. */
+    buttonHeight?: number;
+    /** Button type for Apple Pay / Google Pay. Default: 'buy'. */
+    buttonType?: 'buy' | 'plain' | 'book' | 'donate' | 'checkout';
+    /** Require email from the wallet. Default: true. */
+    emailRequired?: boolean;
+    /** Require billing address from the wallet. Default: true. */
+    billingAddressRequired?: boolean;
+}
+export interface StoreConfig {
+    threedsEnabled: boolean;
+    paymentFlowId?: string;
+    [key: string]: unknown;
+}
+export interface PayResult {
+    payment: {
+        id: string;
+        amount: number;
+        currency: string;
+        status: 'succeeded' | 'pending' | 'failed' | 'declined' | 'requires_action';
+        requireAction?: 'none' | 'threeds_auth' | 'redirect';
+        requireActionData?: {
+            type: string;
+            processed?: boolean;
+            redirectUrl?: string;
+            metadata?: {
+                type?: string;
+                redirect?: {
+                    redirectUrl: string;
+                    returnUrl: string;
+                    method?: string;
+                    data?: Record<string, string>;
+                };
+                threedsSession?: {
+                    externalSessionId: string;
+                    acsChallengeUrl: string;
+                    acsTransID: string;
+                    messageVersion: string;
+                };
+                [key: string]: unknown;
+            };
+            resumeToken?: string;
+            message?: string;
+            errorCode?: string;
+        };
+    };
+    order?: {
+        id: string;
+        checkoutSessionId?: string;
+    };
+    redirectUrl?: string;
+}
+/**
+ * Options for `processPayment()`. Same as `PayOptions` with an optional
+ * `returnUrl` that the processor will redirect back to after 3DS / auth.
+ * If omitted, the SDK uses `window.location.href` (browser) or throws (Node).
+ */
+export interface ProcessPaymentOptions extends PayOptions {
+    /**
+     * URL the bank / PSP redirects back to after 3DS or processor auth.
+     * The URL will receive query params: `paymentAction`, `paymentActionStatus`, `paymentId`.
+     * Default: current page URL (browser only).
+     */
+    returnUrl?: string;
+}
+/**
+ * Discriminated union returned by `processPayment()`.
+ *
+ * - `succeeded`  — payment is confirmed. Show a success screen.
+ * - `requires_redirect` — user must be redirected to a URL (3DS, processor auth, APM).
+ *   In React, `usePayment().processPayment()` handles this automatically.
+ * - `failed` — payment was declined or errored.
+ * - `pending` — payment is still processing (rare edge case if polling timed out).
+ */
+export type ProcessPaymentResult = {
+    status: 'succeeded';
+    payment: PayResult['payment'];
+    order?: PayResult['order'];
+} | {
+    status: 'requires_redirect';
+    redirectUrl: string;
+    method?: 'GET' | 'POST';
+    postData?: Record<string, string>;
+    paymentId: string;
+} | {
+    status: 'failed';
+    error: string;
+    payment?: PayResult['payment'];
+} | {
+    status: 'pending';
+    paymentId: string;
+};
+export interface PayOptions {
+    checkoutSessionId: string;
+    /** Base64-encoded TagadaToken from tokenizeCard(). Instrument is auto-created. */
+    tagadaToken?: string;
+    /** Existing payment instrument ID (skip instrument creation). */
+    paymentInstrumentId?: string;
+    paymentFlowId?: string;
+    threedsSessionId?: string;
+    processorId?: string;
+    paymentMethod?: string;
+    isExpress?: boolean;
+    metadata?: Record<string, unknown>;
+    /**
+     * URL the bank / PSP redirects back to after 3DS or processor auth.
+     * If omitted during `processPayment()`, defaults to `window.location.href`.
+     */
+    returnUrl?: string;
+}
+export interface PayDirectOptions {
+    checkoutSessionId: string;
+    paymentInstrumentId?: string;
+    paymentFlowId?: string;
+    processorId?: string;
+    paymentMethod?: string;
+    isExpress?: boolean;
+    threedsSessionId?: string;
+}
+export interface CreateInstrumentOptions {
+    tagadaToken: string;
+    storeId: string;
+    customerData?: {
+        email?: string;
+        firstName?: string;
+        lastName?: string;
+    };
+    customerId?: string;
+}
+export interface PaymentInstrument {
+    id: string;
+    type: string;
+    customerId: string;
+    card?: {
+        last4: string;
+        brand: string;
+        expMonth: number;
+        expYear: number;
+    };
+}
+export interface ThreedsSession {
+    id: string;
+    externalSessionId: string;
+    provider: string;
+    status: string;
+    paymentInstrumentId: string;
+}
+export interface PaymentStatus {
+    id: string;
+    amount: number;
+    currency: string;
+    status: 'succeeded' | 'pending' | 'failed' | 'declined';
+    subStatus?: string;
+    requireAction?: string;
+    requireActionData?: PayResult['payment']['requireActionData'];
+    order?: {
+        id: string;
+        checkoutSessionId?: string;
+    };
+}
+export interface Offer {
+    id: string;
+    type: 'upsell' | 'downsell' | 'orderbump';
+    title: string;
+    titleTrans?: Record<string, string>;
+    description?: string;
+    lineItems: OfferLineItem[];
+    pricing?: {
+        amount: number;
+        currency: string;
+        compareAtAmount?: number;
+    };
+    metadata?: Record<string, unknown>;
+}
+export interface OfferLineItem {
+    id: string;
+    priceId: string;
+    productId?: string;
+    variantId?: string;
+    quantity: number;
+    productName?: string;
+    variantName?: string;
+    imageUrl?: string;
+    unitAmount?: number;
+    currency?: string;
+}
+export interface OfferPreview {
+    items: OfferPreviewItem[];
+    totalAmount: number;
+    totalAdjustedAmount: number;
+    currency: string;
+}
+export interface OfferPreviewItem {
+    id: string;
+    productId: string;
+    productName: string;
+    variantId: string;
+    variantName: string;
+    imageUrl?: string;
+    quantity: number;
+    unitAmount: number;
+    currency: string;
+}
+/**
+ * Response shape from `POST /api/v1/offers/:offerId/pay-preview`.
+ *
+ * The server pipeline runs preview → transform-to-checkout → prepare-order →
+ * payOrder, then returns each intermediate object so the client can either:
+ *  - inspect `payment.status` to know if the upsell charge succeeded,
+ *  - read `order.id` to chain to a follow-up upsell, or
+ *  - read `payment.requireAction` to handle a 3DS challenge inline.
+ *
+ * Mirrors the structure of `PayResult` (`{ payment, order }`) plus the
+ * `preview` and `checkout` artifacts. Lifecycle helpers like
+ * `processPayment()` are NOT used internally by `pay-preview` — if the
+ * upsell card requires 3DS, callers should read `payment.requireActionData`
+ * and either redirect or fall back to a customer-present retry.
+ */
+export interface OfferPayResult {
+    /** Pricing breakdown that was previewed before charging. */
+    preview: OfferPreview;
+    /** Newly-created upsell checkout session (linked to `mainOrderId`). */
+    checkout: {
+        checkoutUrl: string;
+        customerId?: string;
+        checkoutSessionId?: string;
+        checkoutToken?: string;
+    };
+    /**
+     * Payment outcome from the upsell charge.
+     * Same shape as `PayResult['payment']` returned by `pay()`.
+     */
+    payment: PayResult['payment'];
+    /** Newly-created upsell order (`order.id` chains to the next upsell as `mainOrderId`). */
+    order?: {
+        id: string;
+        status?: string;
+        checkoutSessionId?: string;
+    };
+}
+export interface CatalogProduct {
+    id: string;
+    name: string;
+    description?: string;
+    active: boolean;
+    variants: CatalogVariant[];
+}
+export interface CatalogVariant {
+    id: string;
+    productId: string;
+    name: string;
+    description?: string;
+    sku?: string;
+    price?: number;
+    currency?: string;
+    compareAtPrice?: number;
+    imageUrl?: string;
+    active: boolean;
+    inStock: boolean;
+    prices: CatalogPrice[];
+}
+export interface CurrencyOption {
+    amount: number;
+    compareAtAmount?: number;
+}
+export interface CatalogPrice {
+    id: string;
+    variantId?: string;
+    default: boolean;
+    currencyOptions: Record<string, CurrencyOption>;
+    recurring: boolean;
+    interval?: string;
+    intervalCount?: number;
+}
+export interface Customer {
+    id: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    createdAt?: string;
+}
+export interface Order {
+    id: string;
+    storeId: string;
+    customerId: string;
+    amount: number;
+    currency: string;
+    status: string;
+    items: OrderItem[];
+    createdAt: string;
+}
+export interface OrderItem {
+    id: string;
+    productName: string;
+    variantName: string;
+    quantity: number;
+    unitAmount: number;
+    totalAmount: number;
+}
+export interface Subscription {
+    id: string;
+    customerId: string;
+    storeId: string;
+    status: 'trialing' | 'active' | 'past_due' | 'paused' | 'canceled';
+    priceId: string;
+    currency: string;
+    amount: number;
+    interval: string;
+    intervalCount: number;
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+}
+export interface FunnelNavigateInput {
+    /** Funnel ID to enter (e.g. "fnlv2_..."). */
+    funnelId: string;
+    /**
+     * Funnel step to land on. Used for both `entryStepId` and `funnelStepId`,
+     * matching the WooCommerce plugin behaviour.
+     */
+    stepId: string;
+    /** Where the funnel should send the shopper back to after checkout. */
+    returnUrl?: string;
+    /**
+     * Customer overrides. Defaults are sourced from the currently-loaded
+     * `CheckoutSession` (`session.customer.email`, `session.currency`).
+     */
+    customer?: {
+        email?: string;
+        currency?: string;
+        locale?: string;
+    };
+    /**
+     * Discount codes to apply. Defaults to the session's `promotionCode` if set.
+     */
+    discountCodes?: string[];
+    /** Arbitrary metadata forwarded to the funnel-navigate event. */
+    metadata?: Record<string, unknown>;
+    /**
+     * Override the page URL recorded by the funnel. Defaults to
+     * `globalThis.location?.href` when running in a browser.
+     */
+    currentUrl?: string;
+    /** Override `accountId` per-call. Falls back to `HeadlessConfig.accountId`. */
+    accountId?: string;
+}
+export interface FunnelNavigateResult {
+    /** Fully-qualified URL the caller should redirect the shopper to. */
+    url: string;
+    /** Funnel session id (`context.sessionId` from `/funnel/initialize`). */
+    funnelSessionId: string;
+}
+//# sourceMappingURL=types.d.ts.map