@tickean/checkout-js 0.1.0 → 0.2.11

package/README.md

@@ -2,4 +2,13 @@
 
 Framework-agnostic TypeScript client for Tickean Headless Checkout.
 
-See repository root README and `docs/readme/` for guides.
+## APIs
+
+- `createTickean(options)` — low-level client (unchanged public method signatures)
+- `createCheckoutController(options)` — state machine with cart, quote debounce, OTP, purchase+payment, persistence, telemetry
+
+## Phases
+
+`initializing` → `browsing` → `quoting` → `verifying_buyer` → `ready_to_purchase` → `purchasing` → `requires_action` | `processing` → `completed` | `failed` | `expired`
+
+See repository root README for monorepo build/test commands.

package/dist/index.d.mts

@@ -7,7 +7,8 @@ declare class TickeanError extends Error {
     readonly code: string;
     readonly details?: Record<string, unknown>;
     readonly status?: number;
-    constructor(payload: TickeanErrorPayload, status?: number);
+    readonly requestId?: string;
+    constructor(payload: TickeanErrorPayload, status?: number, requestId?: string);
 }
 type CreateTickeanOptions = {
     publishableKey: string;
@@ -16,12 +17,72 @@ type CreateTickeanOptions = {
     demo?: boolean;
     fetchImpl?: typeof fetch;
 };
+type CheckoutPhase = "initializing" | "browsing" | "quoting" | "verifying_buyer" | "ready_to_purchase" | "purchasing" | "requires_action" | "processing" | "completed" | "failed" | "expired";
+type NextAction = {
+    type: "display_instructions";
+    paymentInstructions: unknown;
+} | {
+    type: "redirect";
+    url: string;
+} | {
+    type: "stripe_elements";
+    clientSecret: string;
+    publishableKey?: string;
+    paymentIntentId?: string;
+} | {
+    type: "airwallex_dropin";
+    intentId: string;
+    clientSecret: string;
+    currency?: string;
+    env?: string;
+    countryCode?: string;
+} | {
+    type: "dlocal_fields";
+    merchantCheckoutToken: string;
+    smartFieldsApiKey?: string;
+    paymentId?: string;
+    sdkUrl?: string;
+} | {
+    type: "fintoc_widget";
+    sessionToken?: string;
+    widgetToken?: string;
+    publicKey?: string;
+    holderType?: string;
+    product?: string;
+} | {
+    type: "none";
+};
 type CheckoutSession = {
     sessionId: string;
     sessionToken: string;
     expiresAt: string;
     event: PublicEvent;
     capabilities: Record<string, boolean>;
+    phase?: CheckoutPhase | string;
+    status?: string;
+    otpVerified?: boolean;
+    buyerId?: string | null;
+    purchaseId?: string | null;
+    shoppingCartReference?: string | null;
+    nextAction?: NextAction;
+    returnUrl?: string | null;
+};
+type PromotionNxM = {
+    enabled?: boolean;
+    buyQty?: number;
+    payQty?: number;
+    label?: string;
+    startsAt?: string;
+    endsAt?: string;
+};
+type QuantityDiscount = {
+    enabled?: boolean;
+    type?: "SECOND_UNIT_PERCENT" | "NTH_UNIT_PERCENT" | string;
+    targetUnit?: number;
+    percentOff?: number;
+    label?: string;
+    startsAt?: string;
+    endsAt?: string;
 };
 type PublicShowOption = {
     id: string;
@@ -30,15 +91,20 @@ type PublicShowOption = {
     price: number;
     currency?: string;
     stock?: number;
+    sold?: number;
+    reserved?: number;
+    availableStock?: number;
     maxPerPurchase?: number;
     optionType?: string;
     accessScope?: string;
     coveredShowIds?: string[];
     passIssuanceMode?: "PER_DAY" | "SINGLE_PASS";
     catalogVisibility?: "PUBLIC" | "PROMO_GATED";
-    promotionNxM?: unknown;
-    quantityDiscount?: unknown;
+    promotionNxM?: PromotionNxM | null;
+    quantityDiscount?: QuantityDiscount | null;
     status?: string;
+    /** Present on options returned via promo unlock. */
+    showId?: string;
 };
 type PublicShow = {
     id: string;
@@ -47,6 +113,32 @@ type PublicShow = {
     endDate?: string;
     showOptions: PublicShowOption[];
 };
+type RegistrationQuestion = {
+    id: string;
+    type?: string;
+    label?: string;
+    required?: boolean;
+    options?: string[];
+};
+type RegistrationSettings = {
+    maxAttendeesPerPurchase?: number;
+    requireAttendeeEmail?: boolean;
+    requireAttendeePhone?: boolean;
+    terms?: {
+        required?: boolean;
+        label?: string | null;
+        pdfUrl?: string | null;
+    } | null;
+    questions?: RegistrationQuestion[];
+};
+type PurchaseAttendee = {
+    showOptionId: string;
+    firstName?: string;
+    lastName?: string;
+    email?: string;
+    phone?: string;
+    termsAccepted?: boolean;
+};
 type PublicEvent = {
     id: string;
     slug: string;
@@ -55,6 +147,9 @@ type PublicEvent = {
     images?: unknown[];
     location?: unknown;
     availablePaymentMethods?: string[];
+    hasPromoGatedShowOptions?: boolean;
+    collectAttendeeData?: boolean;
+    registrationSettings?: RegistrationSettings | null;
     organization?: {
         id?: string;
         slug?: string;
@@ -72,6 +167,7 @@ type QuoteResult = {
     totalPrice: number;
     pricingBreakdown?: unknown;
     discountCode?: unknown;
+    message?: string;
     unlockedShowOptionIds?: string[];
     unlockedShowOptions?: PublicShowOption[];
 };
@@ -105,32 +201,94 @@ type PaymentResult = {
     fintocWidget?: unknown;
     dlocalGo?: unknown;
     airwallex?: unknown;
+    mercadoPago?: unknown;
+    nextAction?: NextAction;
+    requiresAction?: boolean;
 };
 type PaymentStatusResult = {
     status: string;
     purchase?: PurchaseResult["purchase"] | null;
+    payment?: PaymentResult | null;
+    nextAction?: NextAction;
+    requiresAction?: boolean;
+    phase?: CheckoutPhase | string;
+};
+type TelemetryEvent = {
+    name: string;
+    timestamp: number;
+    properties?: Record<string, unknown>;
 };
+interface TelemetryAdapter {
+    track(event: TelemetryEvent): void;
+}
+type PersistedCheckoutState = {
+    sessionToken?: string;
+    eventSlug?: string;
+    cart?: CartItem[];
+    discountCode?: string | null;
+    phase?: CheckoutPhase;
+    /** Non-PII buyer flags only */
+    buyerVerified?: boolean;
+    purchaseId?: string | null;
+};
+interface PersistenceAdapter {
+    get(key: string): PersistedCheckoutState | null;
+    set(key: string, value: PersistedCheckoutState): void;
+    remove(key: string): void;
+}
 interface CheckoutTransport {
     request<T>(path: string, init: {
         method?: string;
         body?: unknown;
         sessionToken?: string | null;
+        idempotencyKey?: string;
     }): Promise<T>;
 }
 
 type TickeanClient = ReturnType<typeof createTickean>;
 declare function createTickean(options: CreateTickeanOptions): {
-    readonly session: CheckoutSession | null;
+    session: CheckoutSession | null;
     createSession(params: {
         eventSlug: string;
         returnUrl?: string;
     }): Promise<CheckoutSession>;
+    exchangeRecovery(params: {
+        code: string;
+    }): Promise<{
+        sessionId: string;
+        sessionToken: string;
+        expiresAt: string;
+        suggestedStep?: string | number;
+        event: PublicEvent;
+        capabilities?: Record<string, boolean>;
+        cart: CartItem[];
+        discountCode?: string | null;
+        buyer?: Buyer | null;
+        buyerVerified?: boolean;
+        purchase?: PurchaseResult["purchase"] | null;
+        payment?: PaymentResult | null;
+        nextAction?: NextAction;
+        shoppingCartReference?: string | null;
+        phase?: string;
+    }>;
+    getSession(): Promise<CheckoutSession>;
     getCatalog(): Promise<PublicEvent>;
     quote(params: {
         items: CartItem[];
         discountCode?: string;
         showId?: string;
     }): Promise<QuoteResult>;
+    lookupBuyer(params: {
+        phone: string;
+    }): Promise<{
+        exists: boolean;
+        buyer?: {
+            id: string;
+            phone: string;
+            name?: string;
+            email?: string;
+        };
+    }>;
     sendOtp(params: {
         phone: string;
         channel?: string;
@@ -150,12 +308,20 @@ declare function createTickean(options: CreateTickeanOptions): {
         expectedTotal?: number;
         shoppingCartReference?: string;
         idempotencyKey?: string;
+        attendees?: PurchaseAttendee[];
     }): Promise<PurchaseResult>;
     createPayment(params: {
         orderId: string;
         paymentMethod: string;
         currency: string;
         amount: number;
+        idempotencyKey?: string;
+    }): Promise<PaymentResult>;
+    confirmPayment(params?: {
+        paymentId?: string;
+        confirmationToken?: string;
+        providerPayload?: string;
+        idempotencyKey?: string;
     }): Promise<PaymentResult>;
     getPaymentStatus(): Promise<PaymentStatusResult>;
     watchPayment(options?: {
@@ -165,4 +331,287 @@ declare function createTickean(options: CreateTickeanOptions): {
     }): Promise<PaymentStatusResult>;
 };
 
-export { type Buyer, type CartItem, type CheckoutSession, type CheckoutTransport, type CreateTickeanOptions, type PaymentResult, type PaymentStatusResult, type PublicEvent, type PublicShow, type PublicShowOption, type PurchaseResult, type QuoteResult, type TickeanClient, TickeanError, type TickeanErrorPayload, createTickean };
+type CheckoutState = {
+    phase: CheckoutPhase;
+    session: CheckoutSession | null;
+    event: PublicEvent | null;
+    cart: CartItem[];
+    discountCode: string | null;
+    quote: QuoteResult | null;
+    isQuoting: boolean;
+    buyer: Buyer | null;
+    buyerVerified: boolean;
+    otpSent: boolean;
+    purchase: PurchaseResult["purchase"] | null;
+    payment: PaymentResult | null;
+    nextAction: NextAction;
+    error: TickeanError | null;
+    loading: boolean;
+};
+type CheckoutAction = {
+    type: "INIT_START";
+} | {
+    type: "INIT_SUCCESS";
+    session: CheckoutSession;
+    event: PublicEvent;
+} | {
+    type: "INIT_FAILURE";
+    error: TickeanError;
+} | {
+    type: "SET_CART";
+    cart: CartItem[];
+} | {
+    type: "SET_DISCOUNT";
+    discountCode: string | null;
+} | {
+    type: "QUOTE_START";
+} | {
+    type: "QUOTE_SUCCESS";
+    quote: QuoteResult;
+} | {
+    type: "QUOTE_FAILURE";
+    error: TickeanError;
+} | {
+    type: "OTP_SENT";
+} | {
+    type: "OTP_VERIFIED";
+    buyer: Buyer;
+} | {
+    type: "SET_EVENT";
+    event: PublicEvent;
+} | {
+    type: "MERGE_UNLOCKED_OPTIONS";
+    options: PublicShowOption[];
+} | {
+    type: "PURCHASE_START";
+} | {
+    type: "PURCHASE_SUCCESS";
+    purchase: PurchaseResult["purchase"];
+    payment: PaymentResult;
+    nextAction: NextAction;
+} | {
+    type: "PURCHASE_FAILURE";
+    error: TickeanError;
+} | {
+    type: "SET_NEXT_ACTION";
+    nextAction: NextAction;
+    payment?: PaymentResult | null;
+} | {
+    type: "RESET_PAYMENT_FLOW";
+} | {
+    type: "PROCESSING";
+} | {
+    type: "COMPLETED";
+    purchase?: PurchaseResult["purchase"] | null;
+} | {
+    type: "FAILED";
+    error: TickeanError;
+} | {
+    type: "EXPIRED";
+} | {
+    type: "CLEAR_ERROR";
+} | {
+    type: "REHYDRATE";
+    partial: Partial<CheckoutState>;
+};
+declare function createInitialState(partial?: Partial<CheckoutState>): CheckoutState;
+declare function checkoutReducer(state: CheckoutState, action: CheckoutAction): CheckoutState;
+
+type CreateCheckoutControllerOptions = CreateTickeanOptions & {
+    eventSlug: string;
+    returnUrl?: string;
+    /** Abandonment recovery code from `?resume=` deep link. */
+    resumeCode?: string;
+    quoteDebounceMs?: number;
+    persistence?: PersistenceAdapter | false;
+    persistenceKey?: string;
+    telemetry?: TelemetryAdapter;
+};
+declare function createCheckoutController(options: CreateCheckoutControllerOptions): {
+    client: {
+        session: CheckoutSession | null;
+        createSession(params: {
+            eventSlug: string;
+            returnUrl?: string;
+        }): Promise<CheckoutSession>;
+        exchangeRecovery(params: {
+            code: string;
+        }): Promise<{
+            sessionId: string;
+            sessionToken: string;
+            expiresAt: string;
+            suggestedStep?: string | number;
+            event: PublicEvent;
+            capabilities?: Record<string, boolean>;
+            cart: CartItem[];
+            discountCode?: string | null;
+            buyer?: Buyer | null;
+            buyerVerified?: boolean;
+            purchase?: PurchaseResult["purchase"] | null;
+            payment?: PaymentResult | null;
+            nextAction?: NextAction;
+            shoppingCartReference?: string | null;
+            phase?: string;
+        }>;
+        getSession(): Promise<CheckoutSession>;
+        getCatalog(): Promise<PublicEvent>;
+        quote(params: {
+            items: CartItem[];
+            discountCode?: string;
+            showId?: string;
+        }): Promise<QuoteResult>;
+        lookupBuyer(params: {
+            phone: string;
+        }): Promise<{
+            exists: boolean;
+            buyer?: {
+                id: string;
+                phone: string;
+                name?: string;
+                email?: string;
+            };
+        }>;
+        sendOtp(params: {
+            phone: string;
+            channel?: string;
+        }): Promise<unknown>;
+        verifyOtp(params: {
+            phone: string;
+            code: string;
+            name?: string;
+            email?: string;
+        }): Promise<unknown>;
+        createPurchase(params: {
+            items: CartItem[];
+            paymentMethod: string;
+            currency: string;
+            showId?: string;
+            discountCode?: string;
+            expectedTotal?: number;
+            shoppingCartReference?: string;
+            idempotencyKey?: string;
+            attendees?: PurchaseAttendee[];
+        }): Promise<PurchaseResult>;
+        createPayment(params: {
+            orderId: string;
+            paymentMethod: string;
+            currency: string;
+            amount: number;
+            idempotencyKey?: string;
+        }): Promise<PaymentResult>;
+        confirmPayment(params?: {
+            paymentId?: string;
+            confirmationToken?: string;
+            providerPayload?: string;
+            idempotencyKey?: string;
+        }): Promise<PaymentResult>;
+        getPaymentStatus(): Promise<PaymentStatusResult>;
+        watchPayment(options?: {
+            intervalMs?: number;
+            timeoutMs?: number;
+            signal?: AbortSignal;
+        }): Promise<PaymentStatusResult>;
+    };
+    ready: Promise<void>;
+    getSnapshot: () => CheckoutState;
+    subscribe: (listener: (snapshot: CheckoutState) => void) => () => void;
+    setCartItem: (showOptionId: string, amount: number) => void;
+    setCart: (cart: CartItem[]) => void;
+    applyDiscountCode: (code: string) => Promise<QuoteResult>;
+    lookupBuyer: (phone: string) => Promise<{
+        exists: boolean;
+        buyer?: {
+            id: string;
+            phone: string;
+            name?: string;
+            email?: string;
+        };
+    }>;
+    sendOtp: (phone: string, channel?: string) => Promise<void>;
+    verifyOtp: (params: {
+        phone: string;
+        code: string;
+        name?: string;
+        email?: string;
+    }) => Promise<void>;
+    purchaseAndPay: (params: {
+        paymentMethod: string;
+        currency: string;
+        discountCode?: string;
+        showId?: string;
+        idempotencyKey?: string;
+        attendees?: PurchaseAttendee[];
+    }) => Promise<{
+        purchaseId: string;
+        payment: PaymentResult;
+        nextAction: NextAction;
+    }>;
+    changePaymentMethod: () => void;
+    confirmPayment: (params?: {
+        paymentId?: string;
+        confirmationToken?: string;
+        providerPayload?: string;
+        idempotencyKey?: string;
+    }) => Promise<PaymentResult>;
+    watchPayment: (watchOptions?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }) => Promise<PaymentStatusResult>;
+    refreshCatalog: () => Promise<PublicEvent>;
+    dispose: () => void;
+    /** @internal test helper */
+    _dispatch: (action: CheckoutAction) => void;
+};
+type CheckoutController = ReturnType<typeof createCheckoutController>;
+
+declare function createMemoryPersistence(): PersistenceAdapter;
+/** sessionStorage adapter — stores only non-PII checkout resume data. */
+declare function createSessionStoragePersistence(storage?: Storage): PersistenceAdapter;
+
+declare function createNoopTelemetry(): TelemetryAdapter;
+type TelemetryListener = (event: TelemetryEvent) => void;
+declare function createEventEmitterTelemetry(listeners?: TelemetryListener[]): TelemetryAdapter & {
+    subscribe(listener: TelemetryListener): () => void;
+};
+
+type PaymentSocketSnapshot = {
+    purchaseId?: string;
+    orderId?: string;
+    paymentId?: string;
+    status?: string;
+    amount?: number;
+    currency?: string;
+};
+type PaymentSocketWatchHandle = {
+    promise: Promise<PaymentSocketSnapshot>;
+    dispose: () => void;
+    get connected(): boolean;
+};
+/**
+ * Join the legacy cart payment room (same as ecommerce) and resolve when
+ * payment:confirmed arrives. HTTP polling remains the fallback.
+ */
+declare function watchPaymentSocket(params: {
+    apiBaseUrl: string;
+    shoppingCartReference: string;
+    purchaseId?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): PaymentSocketWatchHandle;
+
+/**
+ * Navigate the top-level browsing context (breaks out of iframes).
+ * Used for Mercado Pago hosted checkout so payment is not trapped in embeds.
+ */
+declare function navigateTopLevel(url: string): void;
+declare function resolveRedirectUrl(params: {
+    nextAction?: {
+        type: string;
+        url?: string;
+    } | null;
+    redirectUrl?: string | null;
+    initPoint?: string | null;
+}): string | null;
+
+export { type Buyer, type CartItem, type CheckoutAction, type CheckoutController, type CheckoutPhase, type CheckoutSession, type CheckoutState, type CheckoutTransport, type CreateCheckoutControllerOptions, type CreateTickeanOptions, type NextAction, type PaymentResult, type PaymentSocketSnapshot, type PaymentSocketWatchHandle, type PaymentStatusResult, type PersistedCheckoutState, type PersistenceAdapter, type PromotionNxM, type PublicEvent, type PublicShow, type PublicShowOption, type PurchaseAttendee, type PurchaseResult, type QuantityDiscount, type QuoteResult, type RegistrationQuestion, type RegistrationSettings, type TelemetryAdapter, type TelemetryEvent, type TelemetryListener, type TickeanClient, TickeanError, type TickeanErrorPayload, checkoutReducer, createCheckoutController, createEventEmitterTelemetry, createInitialState, createMemoryPersistence, createNoopTelemetry, createSessionStoragePersistence, createTickean, navigateTopLevel, resolveRedirectUrl, watchPaymentSocket };