@usethrottle/checkout-react 1.0.1 → 1.2.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { CSSProperties, RefObject } from 'react';
+import { Cart, AddLineItemInput, UpdateLineItemInput, SelectShippingInput, CheckoutHandoffInput, CheckoutHandoff, SelectedShipping } from '@usethrottle/cart';
 
 /**
  * Envelope every Throttle iframe message carries. Lets parents
@@ -177,4 +178,156 @@ interface UseThrottleEventsOptions {
  */
 declare function useThrottleEvents({ iframeRef, expectedOrigin, onMessage }: UseThrottleEventsOptions): void;
 
-export { CheckoutEmbed, type CheckoutEmbedExtraProps, PaymentEmbed, type RecurringIntent, CheckoutEmbed as ThrottleCheckout, type ThrottleEmbedProps, type ThrottleEnvelope, type ThrottleEvent, type ThrottleMessage, type ThrottleParentCommand, type ThrottleParentEnvelope, type ThrottleParentMessage, useThrottleEvents };
+interface UseCartSessionOptions {
+    /** Application UUID. */
+    applicationId: string;
+    /** Workspace environment UUID the publishable token was minted for. */
+    environmentId: string;
+    /** Publishable storefront quote token (`pk_…`). */
+    quoteToken: string;
+    baseUrl?: string;
+    /**
+     * localStorage key for persisting the session id across page loads. Default
+     * `'throttle.cartSessionId'`. Pass `null` to disable persistence (in-memory
+     * only).
+     */
+    storageKey?: string | null;
+}
+interface UseCartSessionResult {
+    /** Current cart snapshot, or null before the first item / resume. */
+    cart: Cart | null;
+    /** Current opaque session id, or null before the first item. */
+    cartSessionId: string | null;
+    /** True while a request is in flight. */
+    loading: boolean;
+    /** Last error, or null. */
+    error: Error | null;
+    addItem: (input: AddLineItemInput) => Promise<void>;
+    updateItem: (itemId: string, input: UpdateLineItemInput) => Promise<void>;
+    removeItem: (itemId: string) => Promise<void>;
+    selectShipping: (input: SelectShippingInput) => Promise<void>;
+    clearShipping: () => Promise<void>;
+    applyDiscount: (code: string) => Promise<void>;
+    removeDiscount: () => Promise<void>;
+    /** Hand off to checkout. Returns the hand-off (redirect the buyer to `checkoutUrl`). */
+    checkout: (input: CheckoutHandoffInput) => Promise<CheckoutHandoff>;
+    /** Re-fetch the current cart. */
+    refresh: () => Promise<void>;
+    /** Forget the current session (a new cart is created on the next item). */
+    reset: () => void;
+}
+/**
+ * React hook for backend-less cart ownership. Wraps {@link CartSessionClient}:
+ * creates the Throttle cart lazily on the first `addItem` (so empty carts
+ * aren't created on every page load), persists the session id to localStorage,
+ * and resumes it on the next visit. Mutations update reactive `cart` state.
+ *
+ * ```tsx
+ * const cart = useCartSession({ applicationId, environmentId, quoteToken });
+ * <button onClick={() => cart.addItem({ name: 'Widget', unitPrice: 2999, quantity: 1 })}>Add</button>
+ * <button onClick={async () => {
+ *   const { checkoutUrl } = await cart.checkout({ returnUrl, cancelUrl });
+ *   window.location.href = checkoutUrl;
+ * }}>Checkout</button>
+ * ```
+ */
+declare function useCartSession(options: UseCartSessionOptions): UseCartSessionResult;
+
+/**
+ * Lifecycle status for the checkout orchestration.
+ * - `idle`       — no work in flight, no cart yet
+ * - `loading`    — a request is in flight
+ * - `recovering` — the cart went stale (converted/abandoned); rebuilding from the
+ *                  last-known line items into a fresh session
+ * - `ready`      — a cart is present and no request is in flight
+ * - `error`      — the last operation failed (see `error`)
+ */
+type ThrottleCheckoutStatus = 'idle' | 'loading' | 'recovering' | 'ready' | 'error';
+interface CheckoutTotals {
+    currency: string;
+    subtotal: number;
+    discountTotal: number;
+    shippingTotal: number;
+    taxTotal: number;
+    total: number;
+}
+interface UseThrottleCheckoutOptions {
+    /** Application UUID. */
+    applicationId: string;
+    /** Workspace environment UUID the publishable token was minted for. */
+    environmentId: string;
+    /** Publishable storefront quote token (`pk_…`). */
+    quoteToken: string;
+    baseUrl?: string;
+    /**
+     * localStorage key for persisting the cart session id across page loads.
+     * Default `'throttle.cartSessionId'`. Pass `null` to disable persistence.
+     */
+    storageKey?: string | null;
+    /**
+     * Auto-recover from a stale cart. When a mutation fails with
+     * {@link CartNotOpenError} (the cart was converted by a completed order, or
+     * abandoned), the hook starts a fresh session, re-adds the last-known line
+     * items and re-selects the shipping method, then retries the operation once.
+     * Default `true`. Set `false` to surface {@link CartNotOpenError} instead.
+     */
+    autoRecover?: boolean;
+}
+interface UseThrottleCheckoutResult {
+    /** Current cart snapshot, or null before the first item / resume. */
+    cart: Cart | null;
+    /** Current cart session id, or null before the first item. */
+    cartSessionId: string | null;
+    /** Coarse lifecycle status — drive your UI off this rather than `cart === null`. */
+    status: ThrottleCheckoutStatus;
+    /** Last error, or null. */
+    error: Error | null;
+    /** The selected shipping method, bound to the cart (never a shadow copy). */
+    selectedMethod: SelectedShipping | null;
+    /** Live totals, bound to the cart. Null before a cart exists. */
+    totals: CheckoutTotals | null;
+    addItem: (input: AddLineItemInput) => Promise<void>;
+    updateItem: (itemId: string, input: UpdateLineItemInput) => Promise<void>;
+    removeItem: (itemId: string) => Promise<void>;
+    /** Lock a shipping method. One call — the returned cart carries recomputed totals. */
+    selectMethod: (input: SelectShippingInput) => Promise<void>;
+    clearShipping: () => Promise<void>;
+    applyDiscount: (code: string) => Promise<void>;
+    removeDiscount: () => Promise<void>;
+    /**
+     * Hand off to checkout. Returns the hand-off — use `checkoutSessionId` with
+     * `<PaymentEmbed sessionId={…}>` (or redirect the buyer to `checkoutUrl`).
+     */
+    createSession: (input: CheckoutHandoffInput) => Promise<CheckoutHandoff>;
+    /** Re-fetch the current cart. */
+    refresh: () => Promise<void>;
+    /** Forget the current session (a new cart is created on the next item). */
+    reset: () => void;
+}
+/**
+ * Orchestrates a backend-less storefront checkout on top of
+ * {@link CartSessionClient}, bundling the pieces every storefront otherwise
+ * re-implements:
+ *
+ * - **Cart as source of truth** — `selectedMethod` and `totals` are read straight
+ *   off the cart; there is no shadow copy to drift.
+ * - **One-call shipping select** — `selectMethod` locks the method and returns the
+ *   cart with recomputed totals in a single round trip.
+ * - **Stale-cart recovery** — a {@link CartNotOpenError} (cart converted by a
+ *   completed order, or abandoned) transparently rebuilds a fresh session from
+ *   the last-known line items + shipping and retries (`status === 'recovering'`).
+ * - **Session handoff** — `createSession` returns the `checkoutSessionId` for
+ *   `<PaymentEmbed>`.
+ *
+ * Address collection is handled inside the checkout embed (the hosted/full
+ * checkout collects shipping/billing), so this hook intentionally does not write
+ * addresses to the cart.
+ *
+ * ```tsx
+ * const { addItem, selectMethod, totals, createSession, status } =
+ *   useThrottleCheckout({ applicationId, environmentId, quoteToken });
+ * ```
+ */
+declare function useThrottleCheckout(options: UseThrottleCheckoutOptions): UseThrottleCheckoutResult;
+
+export { CheckoutEmbed, type CheckoutEmbedExtraProps, type CheckoutTotals, PaymentEmbed, type RecurringIntent, CheckoutEmbed as ThrottleCheckout, type ThrottleCheckoutStatus, type ThrottleEmbedProps, type ThrottleEnvelope, type ThrottleEvent, type ThrottleMessage, type ThrottleParentCommand, type ThrottleParentEnvelope, type ThrottleParentMessage, type UseCartSessionOptions, type UseCartSessionResult, type UseThrottleCheckoutOptions, type UseThrottleCheckoutResult, useCartSession, useThrottleCheckout, useThrottleEvents };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { CSSProperties, RefObject } from 'react';
+import { Cart, AddLineItemInput, UpdateLineItemInput, SelectShippingInput, CheckoutHandoffInput, CheckoutHandoff, SelectedShipping } from '@usethrottle/cart';
 
 /**
  * Envelope every Throttle iframe message carries. Lets parents
@@ -177,4 +178,156 @@ interface UseThrottleEventsOptions {
  */
 declare function useThrottleEvents({ iframeRef, expectedOrigin, onMessage }: UseThrottleEventsOptions): void;
 
-export { CheckoutEmbed, type CheckoutEmbedExtraProps, PaymentEmbed, type RecurringIntent, CheckoutEmbed as ThrottleCheckout, type ThrottleEmbedProps, type ThrottleEnvelope, type ThrottleEvent, type ThrottleMessage, type ThrottleParentCommand, type ThrottleParentEnvelope, type ThrottleParentMessage, useThrottleEvents };
+interface UseCartSessionOptions {
+    /** Application UUID. */
+    applicationId: string;
+    /** Workspace environment UUID the publishable token was minted for. */
+    environmentId: string;
+    /** Publishable storefront quote token (`pk_…`). */
+    quoteToken: string;
+    baseUrl?: string;
+    /**
+     * localStorage key for persisting the session id across page loads. Default
+     * `'throttle.cartSessionId'`. Pass `null` to disable persistence (in-memory
+     * only).
+     */
+    storageKey?: string | null;
+}
+interface UseCartSessionResult {
+    /** Current cart snapshot, or null before the first item / resume. */
+    cart: Cart | null;
+    /** Current opaque session id, or null before the first item. */
+    cartSessionId: string | null;
+    /** True while a request is in flight. */
+    loading: boolean;
+    /** Last error, or null. */
+    error: Error | null;
+    addItem: (input: AddLineItemInput) => Promise<void>;
+    updateItem: (itemId: string, input: UpdateLineItemInput) => Promise<void>;
+    removeItem: (itemId: string) => Promise<void>;
+    selectShipping: (input: SelectShippingInput) => Promise<void>;
+    clearShipping: () => Promise<void>;
+    applyDiscount: (code: string) => Promise<void>;
+    removeDiscount: () => Promise<void>;
+    /** Hand off to checkout. Returns the hand-off (redirect the buyer to `checkoutUrl`). */
+    checkout: (input: CheckoutHandoffInput) => Promise<CheckoutHandoff>;
+    /** Re-fetch the current cart. */
+    refresh: () => Promise<void>;
+    /** Forget the current session (a new cart is created on the next item). */
+    reset: () => void;
+}
+/**
+ * React hook for backend-less cart ownership. Wraps {@link CartSessionClient}:
+ * creates the Throttle cart lazily on the first `addItem` (so empty carts
+ * aren't created on every page load), persists the session id to localStorage,
+ * and resumes it on the next visit. Mutations update reactive `cart` state.
+ *
+ * ```tsx
+ * const cart = useCartSession({ applicationId, environmentId, quoteToken });
+ * <button onClick={() => cart.addItem({ name: 'Widget', unitPrice: 2999, quantity: 1 })}>Add</button>
+ * <button onClick={async () => {
+ *   const { checkoutUrl } = await cart.checkout({ returnUrl, cancelUrl });
+ *   window.location.href = checkoutUrl;
+ * }}>Checkout</button>
+ * ```
+ */
+declare function useCartSession(options: UseCartSessionOptions): UseCartSessionResult;
+
+/**
+ * Lifecycle status for the checkout orchestration.
+ * - `idle`       — no work in flight, no cart yet
+ * - `loading`    — a request is in flight
+ * - `recovering` — the cart went stale (converted/abandoned); rebuilding from the
+ *                  last-known line items into a fresh session
+ * - `ready`      — a cart is present and no request is in flight
+ * - `error`      — the last operation failed (see `error`)
+ */
+type ThrottleCheckoutStatus = 'idle' | 'loading' | 'recovering' | 'ready' | 'error';
+interface CheckoutTotals {
+    currency: string;
+    subtotal: number;
+    discountTotal: number;
+    shippingTotal: number;
+    taxTotal: number;
+    total: number;
+}
+interface UseThrottleCheckoutOptions {
+    /** Application UUID. */
+    applicationId: string;
+    /** Workspace environment UUID the publishable token was minted for. */
+    environmentId: string;
+    /** Publishable storefront quote token (`pk_…`). */
+    quoteToken: string;
+    baseUrl?: string;
+    /**
+     * localStorage key for persisting the cart session id across page loads.
+     * Default `'throttle.cartSessionId'`. Pass `null` to disable persistence.
+     */
+    storageKey?: string | null;
+    /**
+     * Auto-recover from a stale cart. When a mutation fails with
+     * {@link CartNotOpenError} (the cart was converted by a completed order, or
+     * abandoned), the hook starts a fresh session, re-adds the last-known line
+     * items and re-selects the shipping method, then retries the operation once.
+     * Default `true`. Set `false` to surface {@link CartNotOpenError} instead.
+     */
+    autoRecover?: boolean;
+}
+interface UseThrottleCheckoutResult {
+    /** Current cart snapshot, or null before the first item / resume. */
+    cart: Cart | null;
+    /** Current cart session id, or null before the first item. */
+    cartSessionId: string | null;
+    /** Coarse lifecycle status — drive your UI off this rather than `cart === null`. */
+    status: ThrottleCheckoutStatus;
+    /** Last error, or null. */
+    error: Error | null;
+    /** The selected shipping method, bound to the cart (never a shadow copy). */
+    selectedMethod: SelectedShipping | null;
+    /** Live totals, bound to the cart. Null before a cart exists. */
+    totals: CheckoutTotals | null;
+    addItem: (input: AddLineItemInput) => Promise<void>;
+    updateItem: (itemId: string, input: UpdateLineItemInput) => Promise<void>;
+    removeItem: (itemId: string) => Promise<void>;
+    /** Lock a shipping method. One call — the returned cart carries recomputed totals. */
+    selectMethod: (input: SelectShippingInput) => Promise<void>;
+    clearShipping: () => Promise<void>;
+    applyDiscount: (code: string) => Promise<void>;
+    removeDiscount: () => Promise<void>;
+    /**
+     * Hand off to checkout. Returns the hand-off — use `checkoutSessionId` with
+     * `<PaymentEmbed sessionId={…}>` (or redirect the buyer to `checkoutUrl`).
+     */
+    createSession: (input: CheckoutHandoffInput) => Promise<CheckoutHandoff>;
+    /** Re-fetch the current cart. */
+    refresh: () => Promise<void>;
+    /** Forget the current session (a new cart is created on the next item). */
+    reset: () => void;
+}
+/**
+ * Orchestrates a backend-less storefront checkout on top of
+ * {@link CartSessionClient}, bundling the pieces every storefront otherwise
+ * re-implements:
+ *
+ * - **Cart as source of truth** — `selectedMethod` and `totals` are read straight
+ *   off the cart; there is no shadow copy to drift.
+ * - **One-call shipping select** — `selectMethod` locks the method and returns the
+ *   cart with recomputed totals in a single round trip.
+ * - **Stale-cart recovery** — a {@link CartNotOpenError} (cart converted by a
+ *   completed order, or abandoned) transparently rebuilds a fresh session from
+ *   the last-known line items + shipping and retries (`status === 'recovering'`).
+ * - **Session handoff** — `createSession` returns the `checkoutSessionId` for
+ *   `<PaymentEmbed>`.
+ *
+ * Address collection is handled inside the checkout embed (the hosted/full
+ * checkout collects shipping/billing), so this hook intentionally does not write
+ * addresses to the cart.
+ *
+ * ```tsx
+ * const { addItem, selectMethod, totals, createSession, status } =
+ *   useThrottleCheckout({ applicationId, environmentId, quoteToken });
+ * ```
+ */
+declare function useThrottleCheckout(options: UseThrottleCheckoutOptions): UseThrottleCheckoutResult;
+
+export { CheckoutEmbed, type CheckoutEmbedExtraProps, type CheckoutTotals, PaymentEmbed, type RecurringIntent, CheckoutEmbed as ThrottleCheckout, type ThrottleCheckoutStatus, type ThrottleEmbedProps, type ThrottleEnvelope, type ThrottleEvent, type ThrottleMessage, type ThrottleParentCommand, type ThrottleParentEnvelope, type ThrottleParentMessage, type UseCartSessionOptions, type UseCartSessionResult, type UseThrottleCheckoutOptions, type UseThrottleCheckoutResult, useCartSession, useThrottleCheckout, useThrottleEvents };