tf-checkout-react 2.0.0-beta.23 → 2.0.0-beta.24

package/docs/API.md

@@ -0,0 +1,540 @@
+# React checkout API reference
+
+This reference describes the public surface of `tf-checkout-react` version
+`2.0.0-beta.24`. It supplements the package's npm README with examples and an
+inventory of the shared facade and hooks. The package's installed
+`dist/index.d.ts` is the exact versioned source for complete signatures and
+DTO fields. A named export or a typed payment method does not establish that
+the matching backend feature, account permission or payment provider is enabled.
+
+All examples assume `configureCheckout` has run, and React Query examples are
+under a host `QueryClientProvider`. Use a registered public SDK client ID and
+an empty `clientSecret` in a browser. Never ship a confidential client secret.
+
+## Configure and persist sessions
+
+The following adapter keeps values in memory for the life of this JavaScript
+module. Use it for a test or a deliberately non-persistent browser session;
+refresh loses the session. Production persistence and security are the host's
+choice. For an async backing store, the required synchronous methods operate on
+a loaded mirror and optional `flush()` waits for pending writes; initialize the
+mirror before configuring and await relevant writes before claiming success.
+
+```ts
+import { configureCheckout, type StorageAdapter } from 'tf-checkout-react'
+
+const values = new Map<string, string>()
+const storage: StorageAdapter = {
+  getItem(key) { return values.get(key) ?? null },
+  setItem(key, value) { values.set(key, value) },
+  removeItem(key) { values.delete(key) },
+}
+
+configureCheckout({
+  env: 'STAG',
+  clientId: 'PUBLIC_SDK_CLIENT_ID',
+  clientSecret: '',
+  cookieAuth: true,
+  storage,
+})
+```
+
+The default web adapter uses `localStorage`. `createMemoryStorage()` supplies a
+ready-made in-memory adapter. `getConfig()` reads the active resolved config,
+and `isConfigured()` reports whether configuration has occurred. Do not expose
+credentials by logging that config. `configureCheckout` is global and should
+run before mounting; a second configuration replaces the first. In an SSR app,
+initialize the SDK in a client entry, and never share a module-level buyer
+session between server requests. `auth` is a per-request header function whose
+result normally merges after SDK headers. Protected requests enforce session
+isolation: guest bootstrap strips sensitive buyer/session headers after the
+merge. Do not attach privileged server credentials in browser code.
+
+A checkout buyer identity has event-scoped authority. `hooks.useAuthSession()`
+observes session state, but a UI flag, local token or checkout buyer profile does
+not itself authorize private account data. Coordinate logout, buyer changes,
+query-cache use and cart ownership with the host. `clearSession()` and
+`clearCheckoutGuestSession()` are lower-level session operations; use the
+appropriate authorized logout flow where a backend session must also end.
+
+## Compose navigation
+
+`Tickets` and `SeatMap` report when a cart is ready; the host owns navigation
+when composing individual sections. This skeleton connects seated selection to
+its view. It is not a standalone app: configure and mount it under
+`QueryClientProvider`.
+
+```tsx
+import { useState } from 'react'
+import {
+  AddOns, BillingInfo, CheckoutProvider, Payment, SeatMap, Tickets, WaiverSigning,
+} from 'tf-checkout-react'
+
+export function CheckoutLayout({ eventId }: { eventId: string }) {
+  const [view, setView] = useState<'tickets' | 'seats' | 'checkout'>('tickets')
+  const [notice, setNotice] = useState('')
+  return (
+    <CheckoutProvider>
+      {view === 'tickets' && (
+        <Tickets
+          eventId={eventId}
+          onSelectSeats={() => setView('seats')}
+          onContinue={() => setView('checkout')}
+        />
+      )}
+      {view === 'seats' && (
+        <SeatMap eventId={eventId} onContinue={() => setView('checkout')} />
+      )}
+      {view === 'checkout' && (
+        <>
+          <AddOns eventId={eventId} />
+          <BillingInfo eventId={eventId} />
+          <WaiverSigning eventId={eventId} />
+          <Payment eventId={eventId} onComplete={(order) => {
+            setNotice(order.pending ? 'Payment pending' : 'Order submitted')
+          }} />
+          <p role="status">{notice}</p>
+        </>
+      )}
+    </CheckoutProvider>
+  )
+}
+```
+
+Real navigation must also handle expiry, payment in flight, retained orders and
+buyer/session changes. Do not unconditionally discard or replace a cart on
+Back during a payment. Use the embedded flow when its navigation fits; when
+building your own, preserve validation and server reservation behavior. The
+host can use `useCheckoutContext()` inside the provider to read the shared
+checkout and `useCheckoutValidation()` to coordinate section validation.
+
+The provider's `value?: UseCheckout` accepts a checkout created by the host's
+`useCheckout`; pass the same instance to all sections of that flow. Omit it to
+let the provider create one and wire the default installment picker. Checkout
+state is app-wide by default; two hook calls do not create isolated carts.
+`useCheckout` takes `{ ports?, options? }` once at first render. A custom
+`ports` object is merged over browser defaults and may provide `providerPage`,
+`openUrl`, `onInstallmentOffers` or other payment capabilities, but its type
+omits `confirmer` and cannot replace the web hook's `webConfirmer`. Use the
+lower-level `createEngine` configuration for a custom confirmer. `options` includes
+`stripePublishableKey`, `merchantIdentifier`, `merchantCountryCode`,
+`merchantName`, `googlePayTestEnv`, `redirectReturnUrl` and `urlScheme`.
+Only set options appropriate to your host and payment provider.
+
+## Data and action contracts
+
+### Catalog and reservation
+
+`hooks.useTicketsWithMeta(eventId)` loads current ticket types along with promo,
+waiting-list and bundle metadata. `useTicketCatalog` manages the catalog and
+selection state used by the standard ticket picker. The following renders a
+read-only status; use the actual catalog row to construct `TicketSelection` and
+reserve with `setTickets` after the buyer chooses a quantity.
+
+```tsx
+import { hooks } from 'tf-checkout-react'
+
+export function EventAvailability({ eventId }: { eventId: string }) {
+  const query = hooks.useTicketsWithMeta(eventId)
+  if (query.isPending) return <p role="status">Loading availability…</p>
+  if (query.isError) return <button onClick={() => void query.refetch()}>Retry</button>
+  const { tickets, waitingList } = query.data
+  return <p>{tickets.length} ticket types; waiting list: {waitingList?.state ?? 'unavailable'}</p>
+}
+```
+
+`TicketSelection = { id, name, optionName, price, quantity, currency }`. `id`
+is the current opaque encrypted ID from the catalog. A stable optional API
+`selectionKey` can preserve the buyer's selected quantity across ID rotation;
+the latest encrypted ID is still used on cart requests. For time-slot events,
+pass the actual available date to `useTimeSlotTickets(eventId, date)` and
+respect the backend's dated context. `useEventAddons(eventId)` loads add-ons;
+`ttf.events.filterAddonsForTickets(list, checkout.ticketTypeIds)` filters for
+the primed ticket types. Call `setAddons({ [addonId]: quantity })` to reprice.
+
+`setSeats(eventId, SeatLine[])` uses reserved seat IDs and the corresponding
+tier/ticket relation, option and price. The seat-map reservation has a server
+expiry. `setSeatsIo(eventId, SeatsIoSelection)` is the separate seats.io path.
+Neither method makes stale availability authoritative. Use `resumeCart(eventId,
+{ isFromResale? })` only after the preceding flow has created the server cart
+in the matching session.
+
+### Billing and captures
+
+The following code illustrates the setter shapes; the inputs must come from
+actual buyer entry and the event's current configuration. It does not attempt
+payment or assert that these fields alone satisfy a particular event.
+
+```tsx
+import { useCheckout, type CheckoutBilling, type CheckoutHolder } from 'tf-checkout-react'
+
+export function SaveBuyer({ billing, holders }: {
+  billing: CheckoutBilling
+  holders: CheckoutHolder[]
+}) {
+  const checkout = useCheckout()
+  function save() {
+    checkout.setBilling(billing)
+    checkout.setHolders(holders)
+  }
+  return <button disabled={checkout.orderFixed} onClick={save}>Save details</button>
+}
+```
+
+`CheckoutBilling` requires `firstName`, `lastName` and `email`, with optional
+`confirmEmail`, `phone`, `phoneVerificationToken`, `phoneFirstUseKnownEmail`,
+`streetAddress`, `city`, `zip`, `countryId`, `stateId`, `countryCode`,
+`stateCode`, `stateRequired`, `dobDay`, `dobMonth`, `dobYear`, `nationality`,
+`gender`, `instagramHandle` and `dataCapture`. Backend country/state IDs are
+not ISO codes; use `ttf.geo.countries()` and `ttf.geo.states(...)` or their
+hooks. `confirmEmail` is a UI check and is not sent as an independent buyer
+email. A phone verification token must be the server-issued proof for the
+matching event and phone.
+
+`CheckoutHolder` requires `firstName`, `lastName`, `email`, and optionally has
+`phone`, numeric backend `ticketTypeId` expressed as a string, and
+`ticketDataCapture`. Holder requirements can be stricter than the type's
+optional fields. `CheckoutConsent` has `ttfOptIn` and `brandOptIn` booleans;
+`EventCondition` acceptance is recorded separately. In stock `BillingInfo`,
+however, supplying `privacyPolicy` replaces the Ticket Fairy marketing control
+with a required privacy checkbox that writes the **same** `consent.ttfOptIn`
+value, submitted as `ttf_opt_in`. This path does not independently capture
+privacy and Ticket Fairy marketing choices. `brandOptIn` is separate. Hosts
+requiring independent choices need an alternative whose UI, payload and backend
+behavior have been verified; do not rely on the stock `privacyPolicy` prop for
+that requirement.
+
+For a host condition provide `{ id, name, content, isRequired }` and record
+acceptance with `acceptCondition(id, true)` or `setAcceptedConditions(map)`.
+These are client gates, not a replacement for server validation. `Payment`
+renders `content` (or `name` as a fallback) as HTML; supply trusted or sanitized
+content and verify how server-provided conditions are handled as well.
+
+Do not combine required stock `privacyPolicy` with
+`skipBillingWhenProfileComplete` / `skipWhenProfileComplete`: an eligible skip
+can hide the privacy and marketing controls while `Payment` still requires
+the privacy value. Keep billing visible and test both guest and signed-in flows.
+
+`checkBuyerEmail(email)` starts a request; it does not debounce it. The stock
+`BillingInfo` delays calls, but headless hosts should debounce and coordinate
+in-flight checks. A late response for an older email in the same cart can
+overwrite the snapshot. Compare `existingAccountEmail` to the current trimmed
+input before showing a match and recheck the current value if needed.
+
+`customFields` is an array of `EventCustomFieldGroup` with order, ticket or
+add-on scope; `CustomFieldValues` maps field names to strings or string arrays.
+Order answers belong in `billing.dataCapture`, ticket answers in each holder's
+`ticketDataCapture`, and add-on answers in `setAddonDataCapture` keyed by
+add-on ID. Apply ticket-scoped questions only to matching ticket types. Image
+capture has format and size constraints and needs the SDK's image handling;
+validate on the deployed server too. In this beta the backend owns conditional
+requiredness and hosted-checkout conditional visibility is not fully reproduced.
+Test the actual event's branches before release.
+
+If `unavailableDetails` includes `'waiver'`, the read failed without establishing
+whether a waiver exists. `reloadCheckoutDetails()` retries it. For a custom
+waiver UI, `holdWaiverSigning(index)` returns a hold or `null`; complete or
+cancel the upload, attach via `setWaiverSignature(index, signature, hold)` only
+while the binding remains current, and release the hold. The standard
+`WaiverSigning` component performs this coordination. Edits made when
+`orderFixed` is true are not a way to amend an already placed order.
+
+### Placement and recovery
+
+`placeOrder(method?, options?)` returns `Promise<PlaceOrderResult>`; options
+include `autoRunIdVerification`, `idVerification` and `claimCard`. The default
+method is card. Supply the method appropriate to the event and the active
+payment field. Inspect `pending`, `pendingVoucherUrl` and
+`needIdVerification`; `orderHash` is an order reference, not a universal proof
+of settlement. Provider and server reconciliation controls fulfilment.
+For zero-total orders, this SDK ignores the free-registration response body and
+reports `needIdVerification: false`. Verification or approval may still be
+required; `free: true` is not proof of ticket issuance. The default inline
+`EmbeddedCheckout` can nevertheless show confirmed or ticket-available copy
+while approval or verification is still outstanding. Use
+`confirmationMode="redirect"` with host-owned authoritative order and
+verification status, or a custom composed confirmation gated on that status.
+If status is unavailable, contact support. Do not retry payment for a free order.
+`OrderConfirmation` does not check payment status before rendering its default
+confirmed/ticket-availability copy. Gate it on authoritative appropriate status;
+when the result is pending, show pending UI and any voucher instead. The
+in-flow `Confirmation` component reads the current result's pending state.
+
+For a custom Stripe card step, the following demonstrates the boundary between
+host-collected data and SDK placement. Render it only after reserving a cart and
+confirming that Stripe card is offered. `canSubmit` must reflect the actual
+event's required answers, add-ons, consent and waivers; it is not a substitute
+for server validation. This example stops further attempts after an error until
+the host has reconciled the outcome.
+
+```tsx
+import { useState } from 'react'
+import {
+  CardInput, useCheckout, type CheckoutBilling, type CheckoutConsent,
+  type CheckoutHolder,
+} from 'tf-checkout-react'
+
+export function StripeCardStep(props: {
+  billing: CheckoutBilling
+  holders: CheckoutHolder[]
+  consent: CheckoutConsent
+  acceptedConditions: Record<string, boolean>
+  canSubmit: boolean
+}) {
+  const checkout = useCheckout()
+  const [notice, setNotice] = useState('')
+  const [needsReview, setNeedsReview] = useState(false)
+  async function pay() {
+    checkout.setBilling(props.billing)
+    checkout.setHolders(props.holders)
+    checkout.setConsent(props.consent)
+    checkout.setAcceptedConditions(props.acceptedConditions)
+    try {
+      const order = await checkout.placeOrder('card')
+      setNotice(order.pending ? 'Payment pending' : `Order reference: ${order.orderHash}`)
+    } catch {
+      setNeedsReview(true)
+      setNotice('The payment outcome needs review. Please contact support.')
+    }
+  }
+  return <div>
+    <CardInput />
+    <button disabled={!props.canSubmit || checkout.isBusy || needsReview || checkout.status !== 'ready'}
+      onClick={() => void pay()}>Pay</button>
+    <p role="status">{notice}</p>
+  </div>
+}
+```
+
+The host should display `needIdVerification` and any pending voucher as
+appropriate, check the authoritative result, and provide a recovery path. A
+production UI also needs field labels, accessible errors and a way to recover
+after a confirmed decline; do not automatically repeat the charge in a catch.
+
+`Confirmation` defaults its share URL to `window.location.href` and shows
+generic referral copy for non-pending orders without checking organizer
+eligibility. That URL may contain unrelated query parameters or lack a
+buyer-specific referral. `EmbeddedCheckout` does not expose a `shareUrl` prop.
+In a composed flow pass a verified eligible buyer-specific `shareUrl`, or pass
+`shareUrl=""` to suppress sharing. Server-backed `OrderConfirmation` and
+`Rewards` can use response data where the backend supplies it; first gate
+`OrderConfirmation` on an authoritative appropriate payment status.
+
+```tsx
+import { useState } from 'react'
+import { useCheckout } from 'tf-checkout-react'
+
+export function StartOver() {
+  const checkout = useCheckout()
+  const [notice, setNotice] = useState('')
+  async function startOver() {
+    if (checkout.status === 'placing') setNotice('Finishing your payment…')
+    const reset = await checkout.resetWhenSettled()
+    setNotice(reset ? 'Choose tickets to start again.' : 'Unable to start over. Check your order or contact support.')
+  }
+  return <div>
+    <button onClick={() => void startOver()}>Start over</button>
+    <p role="status">{notice}</p>
+  </div>
+}
+```
+
+A retained order can represent an unknown payment outcome. Never infer a safe
+new charge from an error, closed window or network timeout. `resetWhenSettled`
+can also return `false` for a retired checkout, so check current session/context
+before choosing recovery. The exported `PAID_ORDER_PENDING_MESSAGE` tells the
+buyer to press Pay again; a `false` result alone is not enough to use that
+instruction or establish a safe retry. For custom provider ports, return a settled dismissal
+on closure/unmount; custom confirmer errors should classify only proven
+no-charge outcomes as `declined`, `cancelled` or `notStarted`, with `unknown`
+for uncertainty. `UNSUPPORTED_GATEWAY` indicates the necessary platform
+capability is not available, not that every provider failure is safe to retry.
+
+## Auth component contracts
+
+`AuthModal` owns a complete modal flow. Supply `open`, `onClose` and, for
+public checkout sign-in, `checkoutEventId`. Optional fields are `initialView`,
+`initialEmail`, `message`, `allowRegistration`, `allowPasswordReset`,
+`requireRegistrationAddress`, `registrationFields`, `logoUrl`, `className`,
+`onCheckoutAuthenticated` and `onAuthenticated`. The callbacks correspond to
+checkout-buyer and full-account profiles respectively; they are not
+interchangeable authority. The registered backend journey decides which path is
+available. The web checkout popup uses browser cryptography, a state value and
+PKCE, checks the message origin and window, and can be blocked, closed or time
+out. Never treat popup closure as successful authentication.
+
+The exported controlled forms can be combined with `hooks.useAuthFlow`; they
+are not an authentication backend on their own:
+
+| Form | Required props | Optional props |
+| --- | --- | --- |
+| `LoginForm` | `onSubmit(input)` | `initialEmail`, `errors`, `error`, `loading`, `allowPasswordReset`, `onForgotPassword(email)`, `onFieldChange(field)`. |
+| `RegisterForm` | `onSubmit(input, options)` | `initialEmail`, `errors`, `error`, `loading`, `requireAddress`, `requireTerms`, `completionRefresh`, `onFieldChange(field)`. `completionRefresh` supplies `retryAfter`, `onRequest()` and `onVerify(code)`. |
+| `ForgotPasswordForm` | `onSubmit(email)`, `onBackToLogin(email)` | `initialEmail`, `errors`, `error`, `successMessage`, `loading`, `onFieldChange`. |
+| `ResetPasswordForm` | `token` | `onSuccess`, `onBackToLogin`. |
+| `TwoFactorForm` | `loading`, `error`, `successMessage`, `smsAvailable`, `smsRetryAfter`, `onSubmit(code)`, `onSendSms()`, `onCancel()` | None. |
+| `EmailCodeForm` | `initialEmail`, `sent`, `target`, `retryAfter`, `loading`, `error`, `successMessage`, `onRequest(email)`, `onVerify(code)`, `onBack()` | None. |
+| `PhoneAuthView` | `flow: PhoneAuthenticationFlow` | `allowCreation`, `allowPasswordReset`, `termsUrl`, `privacyUrl`. |
+
+Use the exported `AuthLoginInput`, `AuthRegistrationInput`, `AuthFieldErrors`,
+`AuthFieldName`, `AuthFlowView` and form `*Props` types for exact values.
+Phone checkout requires `sdkCheckoutPhoneAuth` and a matching deployed journey;
+do not enable it just because the view exists. Complete any two-factor or
+email/phone challenge before treating a buyer as authenticated. The built-in
+modal's default `allowRegistration`, `allowPasswordReset` and
+`requireRegistrationAddress` are all `true`. Public checkout registration and
+account completion force address collection even when the option is `false`.
+
+## Payment input contracts
+
+`CardInput` accepts `className?`, Stripe card-element `style?`, `owner?`
+(default `'checkout'`) and `visible?` (default `true`). `StripePaymentElement`
+accepts `className?`, `elementsConfig?`, `wallets?` (`applePay?`, `googlePay?`),
+Stripe `options?` and `owner?`. `XenditCardInput` accepts `className?`,
+`inputClassName?`, and `onValidationChange?(message: string | null)`; the
+consumer renders that message. Standard `Payment` mounts the applicable field.
+
+A separate bundle and ticket checkout can compete for the same payment SDK.
+The web hook's default claim uses the `checkout` owner's registered Payment
+Element if present, otherwise its `CardInput`, and refuses if neither is
+available. For a custom owner, `claimCardField(owner)` claims only `CardInput`.
+For a `StripePaymentElement`, use `cardClaimStep('webPaymentElement', () =>
+webConfirmer.claimPaymentElement(owner))` as the `placeOrder` `claimCard` step;
+for `CardInput`, use a `webCard` claim step that calls
+`webConfirmer.releasePaymentElement()` before `claimCardField(owner)`. The
+standard `Payment` component handles the claims and key changes. Don't assume
+the most recently mounted field is the one belonging to an order. For a custom
+owner, these helpers produce the appropriate step to pass as
+`placeOrder('card', { claimCard })`:
+
+```ts
+import { cardClaimStep, claimCardField, webConfirmer, type CardClaimStep } from 'tf-checkout-react'
+
+export function claimCustomCard(owner: string): CardClaimStep {
+  return cardClaimStep('webCard', () => {
+    webConfirmer.releasePaymentElement()
+    return claimCardField(owner)
+  })
+}
+
+export function claimCustomPaymentElement(owner: string): CardClaimStep {
+  return cardClaimStep('webPaymentElement', () => webConfirmer.claimPaymentElement(owner))
+}
+```
+
+`webConfirmer`, `webPorts` and
+`webXenditTokenizer` are shared platform instances; factories are available for
+advanced platform work. The generic `createEngine({ ports, options?, store? })`
+requires a payment confirmer and applicable optional ports. A custom integration
+must preserve the same ownership, redirect, pending and error guarantees.
+
+## Hooks inventory
+
+Import these from the `hooks` namespace. Function signatures and returned flow
+state are in the declarations; React Query hooks require a query client. Many
+accept optional query/mutation options. Names being exported do not imply that
+every feature is deployed for your integration.
+
+| Domain | Hook names |
+| --- | --- |
+| Event/catalog | `useEvent`, `useTickets`, `useTicketsWithMeta`, `useTimeSlotTickets`, `useEventAddons`, `useEventBundles`, `useTicketCatalog`, `useFeaturedEvents`. |
+| Geo | `useCountries`, `useStates`. |
+| Checkout | `useCheckout` (shared lower-level binding), `useAppCheckoutSession`, `useCheckoutBuyerProfile`, `useCheckoutPhoneIdentity`, `useCheckoutImageField`, `useCheckoutPaymentMethods`, `useAddOnSelection`, `useSeatSelection`, `useSeatsIoSelection`, `useAccommodationSelection`, `useWaiverSigning`. Use the top-level web `useCheckout` for pre-wired web ports. |
+| Codes and engagement | `useWaitingListForm`, `useJoinWaitingList`, `useAttributeReferrer`, `useValidatePhone`, `useSendRsvp`. |
+| Auth/session | `useAuthSession`, `useSessionAction`, `useAuthFlow`, `useLogin`, `useRegister`, `useRegisterAccount`, `useRestorePassword`, `useRestorePasswordRn`, `useResetPassword`, `useLogout`, `useCheckEmailExists`, `useVerifyTwoFactor`, `useSendTwoFactorSms`, `useRequestAccountEmailCode`, `useVerifyAccountEmailCode`, `useCompleteAccount`, `usePhoneAuthentication`. |
+| Buyer/profile | `useProfile`, `useUpdateAccount`, `useUpdateProfile`, `useSavePhone`, `useSendPhoneCode`, `useVerifyPhoneCode`, `useProfileGender`, `useLinkedAccounts`, `useAccountEmailEnrichment`. |
+| Orders/tickets | `useOrders`, `useOrder`, `useTicketChangeOptions`, `useTicketChange`, `useTicketRefund`, `useTicketGift`, `useTicketResale`, `useCustomerPasses`, `useAccountInformation`, `useAccountPlanManagement`. |
+| Bundles/gateway | `useBundlePurchase`, `useBundleFlow`, `useConfirmerHolder`, `useTicketGatewayWait`, `useBundleStarting`, `useTicketCardForm`, `useTicketCardOwner`. |
+| Rewards | `useOrderRewards`, `useAccountRewards`, `useSubmitPrizeDetails`, `useCreatePack`, `useJoinPack`, `useLeavePack`, `useRegenerateShareCard`, `useAccountRewardsSummary`, `useReceiptRewards`. |
+| Account/community | `useAccountPreferences`, `useInterestSelection`, `useNotificationPreferences`, `useAccountDeletion`, `useFriends`, `useProfileSettings`, `useFriendProfile`, `useSavedEvents`, `useSavedEvent`, `useEventComments`, `useEventCommentImage`, `useEventDiscussion`, `useWordPostReaction`. |
+| Travel | `useTrips`, `useTrip`, `useDiscoveryTravel`. |
+| Coordination | `useLiveScope`, `useLockBusy`, `useHeldScopes`, `useScopedState`, `useOnOrderReleased`, `useOnEventChange`. These are lower-level lifecycle/ownership helpers. |
+
+For account order history, `useOrders(query?, options?)` takes pagination and
+filters; `useOrder(orderId, options?)` takes a numeric order ID string. A public
+order hash is used for `OrderConfirmation`, `OrderIDVerification`, and rewards,
+not as a numeric account order ID. Check the declarations for each shape and
+make the appropriate authorized request.
+
+## `ttf` facade inventory
+
+These functions are grouped under the configured `ttf` export. They are
+low-level calls; the engine and components perform additional sequencing,
+preflight, state and payment coordination. Raw functions are also exported in
+the `api` namespace. Calling a low-level endpoint directly does not grant a
+buyer permission or guarantee a safe payment retry.
+
+| Namespace | Methods |
+| --- | --- |
+| `ttf.events` | `featured`, `details`, `tickets`, `ticketsWithMeta`, `bundles`, `startBundlePurchase`, `info`, `conditions`, `timeSlotTickets`, `customFields`, `requiredCustomFieldLabels`, `addons`, `filterAddonsForTickets`, `submitPromoCode`, `setCurrency`, `authenticate`, `track`, `updateOrderDataCapture`, `updateTicketDataCapture`. |
+| `ttf.cart` | `add`, `addSeats`, `get`, `checkoutConfigs`, `price`, `priceBreakdown`, `paymentConfig`, `preOrderMethods`, `checkBuyerEmail`. |
+| `ttf.order` | `create`, `review`, `mapProfileToBilling`, `completeFreeRegistration`, `confirmSuccess`, `idVerificationStatus`, `verifyCustomer`. |
+| `ttf.payment` | `startAdyen`, `adyenPage`, `changeMethodType`, `confirmRedirect`, `prepareOxxo`, `xenditEWalletCharge`, `xenditCardCharge`, `installmentOffers`, `confirmInstallments`, `createPaymentPlan`, `chargeSavedCardPlan`, `changeMethod`, `paypalForm`. |
+| `ttf.seatmap` | `startSession`, `data`, `statuses`, `reserve`, `removeReserved`, `refreshReservation`. |
+| `ttf.engagement` | `attributeReferrer`, `joinWaitingList`, `sendRsvp`, `validatePhone`. |
+| `ttf.geo` | `countries`, `states`. |
+| `ttf.confirmation` | `get`. |
+| `ttf.orders` | `list`, `get`, `myTickets`, `updateOrderCustomFields`, `updateTicketHolderCustomFields`, `updateAddOnCustomFields`. |
+| `ttf.ticketChanges` | `options`, `change`, `joinWaitlist`, `leaveWaitlist`, `history`. |
+| `ttf.resale` | `sell`, `remove`, `process`, `decline`. |
+| `ttf.refunds` | `options`, `submit`. |
+| `ttf.gifts` | `options`, `send`, `cancel`. |
+| `ttf.passes` | `list`, `get`, `events`, `bookings`, `redeem`, `cancel`. |
+| `ttf.rewards` | `forOrder`, `forAccount`, `submitPrizeDetails`, `createPack`, `joinPack`, `leavePack`, `regenerateShareCard`. |
+| `ttf.waivers` | `forCheckout`, `uploadSignatureImage`. |
+| `ttf.extras` | `accommodation`, `quoteAccommodation`, `reserve`. |
+| `ttf.trips` | `list`, `get`. |
+| `ttf.profile` | `get`, `updateAccount`, `update`, `savePhone`, `sendPhoneCode`, `verifyPhoneCode`. |
+| `ttf.preferences` | `getNotifications`, `saveNotifications`, `get`, `save`, `connectAppleMusic`, `disconnectAppleMusic`, `connectSpotify`, `disconnectSpotify`. |
+| `ttf.friends` | `list`, `preview`, `command`, `saveSettings`, `saveProfileSettings`, `matchContacts`, `profile`. |
+| `ttf.savedEvents` | `list`, `status`, `save`. |
+| `ttf.comments` | `list`, `image`, `create`, `update`, `remove`, `react`, `report`, `block`, `moderate`. |
+| `ttf.word` | `getReaction`, `setReaction`. |
+| `ttf.preRegistration` | `confirm`, `influencers`, `confirmationPage`, `submitShareAction`. |
+| `ttf.delegation` | `checkCustomerExists`, `pageInfo`, `issueTicket`. |
+| `ttf.auth` | Checkout: `loginForCheckout`, `loginCheckoutWithVerifiedPhone`, `registerForCheckout`, `getCheckoutBuyerProfile`, `requestCheckoutEmailCode`, `verifyCheckoutEmailCode`, `verifyCheckoutTwoFactor`, `sendCheckoutTwoFactorSms`, `cancelCheckoutTwoFactor`, `logoutFromCheckout`, `signInWithCheckoutBrowser`. Account/session: `login`, `register`, `registerAccount`, `logout`, `verifyTwoFactor`, `cancelTwoFactor`, `sendTwoFactorSms`, `signInWithBrowser`, `beginBrowserSignIn`, `exchangeBrowserSignIn`, `checkEmailExists`. Recovery/proof: `restorePassword`, `restorePasswordRn`, `validateResetToken`, `resetPassword`, `requestAccountEmailCode`, `verifyAccountEmailCode`, `completeAccount`, `requestCheckoutPhoneCode`, `verifyCheckoutPhoneCode`, `loginWithVerifiedPhone`, `mintVerificationUrl`, `getVerificationInfo`, `updateVerificationStatus`. Account management: `getLinkedAccounts`, `linkAccount`, `disconnectAccount`, `getAccountDeletionStatus`, `sendAccountDeletionCode`, `deleteAccount`. |
+
+`ttf.events.track(eventId, { pageUrl?, page?, orderHash? })` is explicit event
+tracking. The host owns its trigger, consent and deduplication. Account and
+post-purchase methods can require a different authority from public checkout.
+Never log raw credentials, buyer answers or payment-provider payloads.
+
+## UI type reference
+
+In addition to the checkout/section prop tables in the npm README, these
+primitives expose the following contracts:
+
+- `Card` accepts HTML `div` attributes. `SectionHeader` requires `title` and
+  accepts `step`, `pills`, `className`. `Pill` takes `children` and `muted`.
+- `Button` accepts normal button attributes and `variant`, `block`, `loading`.
+  `Field` takes `children`, `label`, `error`, `invalid`, `className`;
+  `FieldRow` takes `children` and `className`.
+- `Input`, `Textarea`, `Select` accept the matching HTML attributes and
+  `invalid`; `Checkbox` accepts input attributes and `label`.
+- `CustomFieldInput` requires `field`, `value`, `onChange` and accepts `error`.
+  `CustomFieldGroupFields` requires `group`, `values`, `onChange(name, value)`
+  and accepts `ticketTypeId`. The UI's `customFieldsComplete` helper does not
+  replace server conditional-field validation.
+- `PaymentMethods` is controlled: `options`, `selected`, `onSelect`,
+  `extraValues`, `onExtraChange` are required. `showValidation`, `children`,
+  `inputSlotFor`, `className` are optional. `PaymentMethodOption` identifies
+  the label/value, method ID and optional extra input.
+- `Stepper` and `QuantitySelect` require `value` and `onChange`; both accept
+  `min`, `max`, `step`, `disabled`, `className`. `QuantitySelect` also accepts
+  an accessible `label`.
+- `PriceLine` requires `amount`, with `currency`, `original`, `note`,
+  `className`. `Timer` requires `seconds`, with `urgentAt`, `label`,
+  `className`; `TimerBanner` accepts optional `seconds`, `urgentAt`, `message`,
+  `className`. `Loader` accepts `className`.
+- `SignaturePad` requires `onChange(pngDataUrl, inkLength)`, `label` and
+  `clearLabel`; `disabled` is optional. `FrozenFields` takes `children` and an
+  optional `frozen`, using a disabled fieldset. `I18nProvider` takes optional
+  `locale`, `messages` and `children`; `useT()` reads its translator.
+
+`CheckoutTheme` supports `colorScheme`, `accent`, `accentHover`,
+`accentContrast`, `surface`, `surfaceMuted`, `text`, `muted`, `border`,
+`error`, `success`, `radiusCard`, `radiusControl`, `shadow`, `font`, `fontSize`
+and `maxWidth`. `themeToVars` returns corresponding CSS custom properties.
+`LocaleCode` accepts `en-GB`, `en-US`, `es-MX`, `fr`, `de`, `ru`, `id`;
+translations may fall back to English. Always verify event-specific copy,
+contrast, focus handling and third-party payment widgets in the host.

package/package.json

@@ -1,11 +1,12 @@
 {
-  "version": "2.0.0-beta.23",
+  "version": "2.0.0-beta.24",
   "license": "MIT",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs"
   ],
   "engines": {
     "node": ">=18"