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

package/docs/API.md

@@ -0,0 +1,602 @@
+# React Native API reference
+
+This reference describes the API and behavior shipped in
+`tf-checkout-react-native@2.0.0-beta.24`. Read it alongside the
+[package README](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.24/README.md)
+for installation, secure setup, complete examples, payment safety and
+limitations. The [published declarations](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.24/dist/index.d.ts)
+are authoritative for exact types and include the remaining DTO fields.
+The shared core is bundled; do not install its private workspace package.
+Availability of any operation depends on the deployed backend, event, account,
+provider and device.
+
+All examples assume `configureCheckout` has completed after the host restored
+its OS-protected synchronous storage adapter. Hooks using React Query need a
+`QueryClientProvider` (provided inside `CheckoutProvider`). Do not put
+confidential client secrets into the app.
+
+**TypeScript troubleshooting:** beta.24 declarations reference a global
+`Crypto` type. A host configuration excluding DOM and lacking a compatible
+ambient `Crypto` type may report TS2304 while checking SDK declarations. Supply
+compatible host type definitions where possible. `skipLibCheck` skips
+declaration-file checks; if `Crypto` remains unresolved, affected types can
+degrade to `any`, allowing invalid `newBundleIdempotencyKey` arguments to
+compile. Neither a type declaration nor `skipLibCheck` installs runtime crypto.
+
+## Contents
+
+- [Checkout components](#checkout-components)
+- [Account and post-purchase components](#account-and-post-purchase-components)
+- [Authentication forms](#authentication-forms)
+- [Primitives](#primitives)
+- [Hook catalog](#hook-catalog)
+- [API facade](#api-facade)
+- [Headless state, actions and ports](#headless-state-actions-and-ports)
+- [Types and errors](#types-and-errors)
+
+## Checkout components
+
+### Provider and embedded flow
+
+`EmbeddedCheckout` takes required `eventId`; optional `onComplete`,
+`confirmationMode`, `confirmationChildren`, `initialView`, `onViewChange`,
+`requireEmailConfirmation`, `collectTicketHolders`, `collectHolderContact`,
+`onLogin`, `auth`, `skipBillingWhenProfileComplete`, `ttfOptInLabel`,
+`brandOptInLabel`, `privacyPolicy`, `additionalConditions`, `initialPromoCode`,
+`referrer`, `readAttributionFromUrl`, `pickImage`, `showTestCardHint` and
+`theme`. Defaults and examples are in the README. Native URL attribution is a
+no-op; an order result may be pending, and a result without `pending` is not
+proof of settlement. The embedded component creates its own provider and does
+not expose `options`, `paymentSheet` or `shareUrl` props. Use redirect/custom
+routing and reconcile payment status when confirmed paid status is required.
+Redirect omits inline verification: when `needIdVerification` is true, the host
+must arrange it. Preserve `orderHash` and any `pendingVoucherUrl` for the
+order-status journey, including navigation/restart.
+
+`CheckoutProvider` takes required `children`, plus `value?: NativeUseCheckout`,
+`queryClient?: QueryClient`, `theme?: CheckoutTheme`,
+`pickImage?: CheckoutImagePicker`, `options?: CheckoutOptions` and
+`paymentSheet?: NativePaymentSheetOptions`. Omit `value` to use its native
+checkout hook, provider-page UI and installment picker. A controlled value must
+itself be created with the required ports/options. `CheckoutThemeProvider` takes
+`children` and optional `theme` and supplies only theme context.
+
+`useCheckoutContext()` returns `NativeUseCheckout` within a checkout provider.
+`useCheckoutValidation()` returns `{ attempt, requestValidation }`; composed
+controls can reveal errors after a submit attempt. `useTheme()` returns the
+resolved theme (light defaults outside a theme provider). The provider owns a
+shared query client by default; pass `queryClient` to use yours. Native
+`useCheckout()` and sections share one app checkout store; multiple hooks do not
+imply separate concurrent carts.
+
+### Catalog and cart
+
+Native `Tickets` has no password prompt or password prop. For a protected
+event, a host may collect the password, call `ttf.events.authenticate(eventId,
+password)`, handle wrong-password/session errors and refetch the event/catalog
+in the same buyer/event context. Do not log passwords; verify this session and
+unlock flow against the deployed backend rather than assuming API success is
+sufficient.
+
+`Tickets` requires `eventId` and accepts:
+
+- `title?: string | false` (default `false`), `buttonLabel?: string` (default
+  `Get tickets`), `onContinue?: () => void` and `onSelectSeats?: () => void`.
+  `onContinue` follows a successful cart prime; the seat CTA is hidden without
+  `onSelectSeats`.
+- `timeSlotDates?: string[]` for explicit ISO dates; without it event metadata
+  determines time-slot mode.
+- `initialPromoCode?: string`, `referrer?: string | number`,
+  `readAttributionFromUrl?: boolean`. The last is accepted but does nothing on
+  native; classify and supply attribution yourself.
+- `unstyled?: boolean`, `renderTicket?: (row) => ReactNode` and
+  `renderContinue?: (cta) => ReactNode`. The row has `ticket: TicketType`,
+  `quantity`, `range: { min, max, step }`, `unavailable`, `seated` and
+  `onQuantityChange(quantity)`. The CTA has `onPress`, `disabled`, `loading`
+  and `title`. Use those controls rather than bypassing cart rules.
+
+`SeatMap` requires `eventId` and accepts `onContinue`. It handles internal and
+Seats.io chart selection through WebView and the shared controller. Its use
+requires a compatible deployed event/session/hold/cart backend. A working chart
+is not by itself evidence that seats were reserved or sold.
+
+`AddOns` requires `eventId`; it accepts `onContinue`, `onSkip`, `buttonLabel`,
+`eyebrow` and `heading`. It can render nothing for no applicable or all sold-out
+items. With no `onContinue`, it participates in a combined form. Required
+add-ons prevent skipping and are checked before order placement.
+
+`Bundles` requires `eventId`; accepts `onPurchased(orderHash)`,
+`onComplete(order)`, `confirmationMode`, `visible`, `heading`, `locale`,
+`messages`, `translate`. It makes its own bundle order, separate from the
+normal ticket cart. Hide its native card field with `visible={false}` when the
+section is hidden. The default confirmation mode is `inline`.
+
+`Accommodation` takes `eventId`. Its shared flow owns stay drafts, server quotes
+and reservation; render it only for a configured event. Missing quotes are not
+zero-priced.
+
+### Buyer details and fulfillment
+
+`BillingInfo` accepts `eventId`, `onContinue`, `heading`, `buttonLabel`,
+`onLogin(email?)`, `skipWhenProfileComplete`, `requireEmailConfirmation`,
+`collectTicketHolders`, `collectHolderContact`, `ttfOptInLabel`,
+`brandOptInLabel`, `privacyPolicy`, `showPrivacyError` and `step`. Its
+standalone email/holder/skip flags default to false. `step` is accepted but not
+rendered. Without `onContinue` it mirrors edits into the combined form. A
+`CheckoutPrivacyPolicy` is `{ url, brandName, linkLabel? }`. `Payment` must use
+matching email/holder flags and `requirePrivacyPolicy` when the host requires
+that checkbox. `onPrivacyRequired` lets the host reveal the inline error.
+
+In beta.24 the stock `privacyPolicy` checkbox shares `consent.ttfOptIn`, sent
+as `ttf_opt_in`; it does not capture independent privacy and marketing choices.
+If both opt-in labels are explicitly empty, consent may not be committed and
+the privacy gate can remain blocked. `skipWhenProfileComplete` (or embedded
+`skipBillingWhenProfileComplete`) can hide the checkbox while Payment still
+requires it. Avoid those combinations without a verified host workaround. A
+host needing separate consent must use a custom flow and tested server contract.
+
+During priming, failed event custom-field, checkout-config, add-on and condition
+reads fall back to empty/default data. Neither stock UI nor engine can gate
+requirements that were not loaded. Only non-404 waiver failures are recorded in
+`unavailableDetails` and gated/retried. Verify failure behavior and implement
+tested host safeguards for mandatory fields and acknowledgments; server answer
+validation does not prove an acknowledgment was made.
+
+`OrderSummary` accepts `eventId`, `locale`, `messages`, `translate` and uses
+server-priced cart state. `WaiverSigning` requires `eventId` and accepts
+`locale`, `messages`, `translate`; it returns no section if there is no waiver.
+`IDVerification` takes no props and renders only when the current order requires
+verification. The buyer must press its Verify button to open/poll the provider;
+it does not run automatically on mount. A redirect/composed host must arrange
+this component under the active checkout provider or a custom
+`runIdVerification(orderHash)` flow. Verification is separate from payment
+settlement. `Confirmation` takes `shareUrl`,
+`shareMessage`, `viewOrderUrl`, `message`, `children`; it reads the current
+order. For every non-pending order, a supplied `shareUrl` triggers stock
+reward-promising copy without checking eligibility or generating a
+buyer-specific URL. Omit it unless the host has verified both. Its non-pending
+receipt can show confirmed copy before capture/settlement. It reads the original
+`checkout.order.pending` and does not refresh that flag after later settlement;
+use custom status UI backed by a fresh authoritative read for asynchronous
+orders. These components use checkout context.
+
+`Payment` accepts `onComplete`, `eventId`, `requireEmailConfirmation`,
+`collectTicketHolders`, `requireHolderContact`, `additionalConditions`,
+`requirePrivacyPolicy`, `onPrivacyRequired`, `showTestCardHint`, `locale`,
+`messages`, `translate`. `eventId` is currently unused by native payment. All
+its boolean props default false in standalone use. Its `onComplete` may receive
+a pending result. `pending !== true` does not establish settlement: Stripe
+`Processing` and `RequiresCapture` can return without that flag. It reads the
+selected cart, renders server/device-eligible methods and uses provider-owned
+card collection. Reconcile the authoritative backend/provider status before
+fulfillment; use custom/redirect UI when the stock confirmed copy is premature.
+`Payment` gates loaded event conditions, host `additionalConditions` and
+requested privacy in its UI. Conditions render through filtered native
+`RichText`, not full browser HTML, with HTTP(S)-only links. A headless
+`placeOrder` checks loaded event conditions but does not receive host
+`additionalConditions` or the privacy prop; the host must enforce its own
+required acknowledgments. These client-side acceptances are not sent as separate
+server fields.
+
+`Rewards` takes `orderHash?`, `data?: RewardsPayload | null`, `locale?`,
+`messages?`, `translate?`. Supply an order hash or data. It displays the
+order-scoped reward experience and native share sheet. It uses the server's
+`share_link` and renders nothing when `referrals_enabled` is explicitly false;
+verify eligibility and the buyer-specific link against your deployed contract.
+`RewardsLadder` requires `rows` and `translate`, and accepts async
+`onSubmitDetails(awardId, details)`.
+`RewardsTree` requires `tree` and accepts `size` (default 260). These can be
+composed within `Confirmation`. Account-level `AccountRewardsSection` is a
+separate read-only aggregate.
+
+## Account and post-purchase components
+
+These exports are independent features, not implied by a checkout purchase.
+They require matching backend support and appropriate account or order access.
+Host-owned links, callbacks and sign-in should preserve buyer/session ownership
+across asynchronous navigation. Many use React Query hooks and therefore need
+a query provider. The optional `locale`, `translate`, `theme`, `style`,
+`showHeader` and callbacks listed below customize each specific screen, not the
+entire SDK. Inspect the linked declarations for the exact `Translate`, data and
+flow types.
+
+| Component | Required props | Optional props / behavior |
+| --- | --- | --- |
+| `TicketChange` | `ticketHash` | `orderHash`, `onChanged`, `openUrl`, `onLogin`, `locale`, `messages`, `translate`. `orderHash` supports an order-link guest; a paid change hands off to the hosted payment page. |
+| `TicketRefund` | `ticketHash` | `onSubmitted`, `onDone`; the server supplies available refund options. |
+| `TicketGift` | `ticketHash` | `onTicketsChanged`, `onDone`, `locale`; displays server gift eligibility/status and confirmation. |
+| `Passes` | — | `onTicketsChanged`, `locale`; server-owned pass events, redemption and booking state. |
+| `Trips` | `onOpen(url)`, `onPage(query)` | `data`, `locale`, `loading`, `errorMessage`, `onRetry`; the host loads data and owns authenticated navigation. |
+| `AccountRewardsSection` | — | `locale`, `onBrowseEvents`, `onViewTickets`; read-only account aggregate, with no order-specific mutation. |
+| `AccountInformationSection` | `orderId` | `title`, `target`, `locale`, `active`, `onSaved`; edit supported order information. |
+| `AccountPaymentPlanSection` | `plan`, `orderHash`, `onOpen(url)` | `locale`, `onReturn`; host opens the server-provided plan URL. |
+| `AccountDeletion` | — | `showHeader`, `showExplanation`, `onSignIn`, `onDone`, `onOpenTeam`, `locale`, `translate`, `theme`, `style`; shared flow handles proof and blockers. |
+| `AccountDeletionView` | `deletion: AccountDeletionFlow` | Same remaining props as `AccountDeletion`; use when the host owns the flow. |
+| `ProfileSettings` | `mode: 'links' \| 'visibility'` | `showHeader`, `onBack`, `onSignIn`, `locale`, `translate`, `renderLinkIcon`, `renderSaveButton`, `theme`, `style`. |
+| `ProfileSettingsView` | `mode`, `settings: ReturnType<typeof hooks.useProfileSettings>` | Same remaining props as `ProfileSettings`. |
+| `NotificationPreferences` | — | `locale`, `translate`, `showHeader`, `onBack`, `onSignIn`, `onSaved`, `theme`, `style`, `renderSaveButton`. |
+| `NotificationPreferencesView` | `preferences: NotificationPreferencesFlow` | Same remaining props as `NotificationPreferences`. |
+| `Streaming` | `onOpenMusic(url, provider)` | `onSignIn`, `locale`, `translate`, `renderProviderIcon`, `showHeader`, `theme`, `style`. The callback must resolve when the browser handoff returns. |
+| `StreamingView` | `onOpenMusic`, `preferences: ReturnType<typeof hooks.useAccountPreferences>` | Same remaining props as `Streaming`. |
+| `PhoneAuthentication` | `flow: PhoneAuthenticationFlow` | `locale`, `showHeader`, `allowCreation`, `allowPasswordReset`, `countryOptions`, `onOpenTerms`, `onOpenPrivacy`, `style`. |
+| `AccountEmailEnrichment` | `flow: AccountEmailEnrichmentFlow` | `locale`, `showHeader`, `onDone`, `style`. |
+| `EventDiscussionView` | `eventId`, `discussion: EventDiscussion` | `onLogin`, `pickImage`, `pickImages(remaining)`, `previewKey`, `locale`, `renderReplyIcon`, `renderImageCloseIcon`, `onModerationFilter`, `renderReactionIcon`. Discussion pickers return base64 strings or `null`, unlike checkout's object picker. |
+| `PostReaction` | `postId: string \| number` | `onSignIn`, `renderIcon`, `translate`, `showFeedback`; creates its flow. |
+| `PostReactionControls` | `flow: WordPostReactionFlow` | `onSignIn`, `renderIcon`, `translate`, `showFeedback`. |
+| `PostReactionFeedback` | `flow` | `translate`. |
+
+Use `hooks.useTicketChange`, `useTicketRefund`, `useTicketGift`,
+`useCustomerPasses`, `useTrips`/`useTrip`, `useAccountDeletion`,
+`useProfileSettings`, `useNotificationPreferences`, `useAccountPreferences`,
+`usePhoneAuthentication`, `useAccountEmailEnrichment`, `useEventDiscussion`
+and `useWordPostReaction` for custom presentations. Consult their individual
+state/actions and server eligibility rather than assuming a mutation succeeded
+because a screen closed.
+
+## Authentication forms
+
+`AuthModal` requires `open: boolean` and `onClose: () => void`; optional props
+are `checkoutEventId`, `onCheckoutAuthenticated`, `allowRegistration`,
+`allowPasswordReset`, `requireRegistrationAddress`, `logoUrl`,
+`onAuthenticated`, `initialEmail` and `message`. Checkout scope and
+full-account scope are distinct. `EmbeddedCheckout` supplies its event ID to
+the built-in modal. A host `onLogin` callback replaces the modal and must
+preserve the guest cart and session owner itself.
+
+The smaller forms can be composed with `hooks.useAuthFlow` or an authorized host
+controller. Required callbacks are marked:
+
+| Form | Props |
+| --- | --- |
+| `LoginForm` | **`onSubmit(input)`**; `initialEmail`, `errors`, `error`, `loading`, `allowPasswordReset`, `onForgotPassword(email)`, `onFieldChange(field)`. |
+| `RegisterForm` | **`onSubmit(input, { requireState, termsAccepted? })`**; `initialEmail`, `locale`, `errors`, `error`, `loading`, `requireAddress`, `requireTerms`, `completionRefresh`, `onFieldChange`. `completionRefresh` supplies `retryAfter`, async `onRequest`, async `onVerify`. |
+| `ForgotPasswordForm` | **`onSubmit(email)`**, **`onBackToLogin(email)`**; `initialEmail`, `errors`, `error`, `successMessage`, `loading`, `onFieldChange`. |
+| `ResetPasswordForm` | **`token`** from the reset link; `onSuccess`, `onBackToLogin`. It drives its reset mutation. |
+| `TwoFactorForm` | **`loading`**, **`error`**, **`successMessage`**, **`smsAvailable`**, **`smsRetryAfter`**, **`onSubmit(code)`**, **`onSendSms()`**, **`onCancel()`**. The async callbacks retain the controller's pending challenge. |
+| `EmailCodeForm` | **`initialEmail`**, **`sent`**, **`target`**, **`retryAfter`**, **`loading`**, **`error`**, **`successMessage`**, **`onRequest(email)`**, **`onVerify(code)`**, **`onBack()`**. |
+| `PasswordInput` | Same props as `Input` except `secureTextEntry`; it owns visibility. |
+
+`AuthLoginInput` has `email` and `password`; `AuthRegistrationInput` includes
+names, email, password/confirmation and optional contact/address fields. Do not
+log passwords, verification codes, auth proofs, tokens or full profile data.
+The host must restore/flush its secure adapter as described in the README.
+
+## Primitives
+
+These native exports are theme-aware. Unless shown otherwise, fields below are
+optional. They are controlled presentation; the host owns their state and
+accessible context.
+
+| Export | Props / behavior |
+| --- | --- |
+| `Loader` | `size?: 'small' \| 'large'`, `color?`. |
+| `Card` | **`children`**, `style?: StyleProp<ViewStyle>`. |
+| `SectionHeader` | **`title`**, `subtitle?`. |
+| `Divider` | No props. |
+| `BodyText`, `MutedText` | **`children`**, optional text `style`. |
+| `ErrorText` | **`children`**. |
+| `Button` | **`onPress`**, **`children`**, `loading?`, `disabled?`, `variant?: 'primary' \| 'ghost'`. |
+| `FrozenFields` | **`children`**, `frozen?`; supported SDK controls stop input while frozen. `useFrozen()` reads the state. |
+| `Field` | **`children`**, `label?`, `error?`, `required?`. |
+| `Input` | **`value`**, **`onChangeText`**; `placeholder`, `keyboardType`, `autoCapitalize`, `secureTextEntry`, `editable`, `invalid`, `onBlur`, plus selected native `TextInputProps`: `textContentType`, `autoComplete`, `autoFocus`, `maxLength`, `onSubmitEditing`, `accessibilityLabel`, `multiline`. |
+| `Checkbox` | **`checked`**, **`onChange(checked)`**, **`label`**, `invalid?`. |
+| `Select<T>` | **`value: T \| null \| undefined`**, **`onChange(value)`**, **`options: { label: string; value: T }[]`**; `placeholder?`, `invalid?`, `disabled?`. |
+| `QuantitySelect` | **`value`**, **`onChange(value)`**, `min?`, `max?`, `step?`, `disabled?`, `label?`. Zero is allowed as no selection even if a purchase has a minimum. Supply an accessible label. |
+| `Timer` | **`seconds`**, `urgentAt?` (default 60), `label?`. |
+| `TimerBanner` | `seconds?`, `urgentAt?` (default 60), `message?`; dismissible and hidden without a positive live reservation. |
+| `PaymentMethods` | **`options: PaymentMethodOption[]`**, **`selected`**, **`onSelect(value)`**; `extraValues`, `onExtraChange`, `showValidation`, `inputSlotFor`, `children`. Renders options/extra fields, not payment submission. |
+| `RichText` | **`html`**, `textStyle`, `tagsStyles`, `onLinkPress(href)`, `selectable`. Requires `react-native-render-html`. |
+| `CardInput` | `onComplete(complete)`, `owner` (default `checkout`), `visible`. It is a provider card field, not an order result. `claimCardField(owner)` claims the matching field. |
+
+`useInstallmentPicker()` returns `{ onInstallmentOffers, picker }` for a custom
+provider: mount `picker` and pass its callback as the port. The self-provided
+`CheckoutProvider` already handles this. `useStyles(resolvedTheme)` returns the
+SDK primitive styles; `resolveTheme(partial)` resolves the light/dark tokens.
+
+## Hook catalog
+
+Import these as `hooks.use…`, except the **top-level native** `useCheckout()`
+and the context/theme hooks in the preceding sections. Parameters below describe
+beta.24; consult the declarations for exact returned state, types, generics and
+callbacks. Hook state is scoped to the active configuration/session. Avoid using
+an old async result to mutate a newly signed-in buyer's UI. Some hooks return
+React Query query/mutation results; flow hooks return their own state, commands
+and queries, not a universal mutation interface.
+
+### Catalog, geography and engagement
+
+| Hook | Parameters / role |
+| --- | --- |
+| `useEvent` | `(eventId, options?)`: event information. |
+| `useTickets` | `(eventId, options?)`: current ticket types. |
+| `useTicketsWithMeta` | `(eventId, options?)`: tickets plus catalog promo/access and waiting-list metadata. Refetch after applying a code. |
+| `useTimeSlotTickets` | `(eventId, date, options?)`: one date's slot tickets. |
+| `useEventAddons` | `(eventId, options?)`: event add-on catalog. |
+| `useEventBundles` | `(eventId)`: event bundles. |
+| `useTicketCatalog` | `(eventId, explicitDates?)`: ticket selection controller used by `Tickets`. |
+| `useFeaturedEvents` | `(query?, options?)`: featured events. |
+| `useCountries` | `(options?)`: country list. |
+| `useStates` | `(countryId, options?)`: states for a country; gated on ID. |
+| `useWaitingListForm` | `(eventId, definition, onJoin, prefill?)`: render a server-defined waiting list. |
+| `useJoinWaitingList` | `(eventId, options?)`: waiting-list mutation. |
+| `useAttributeReferrer` | `(eventId, options?)`: attribution mutation. Classify a link before calling. |
+| `useSendRsvp` | `(eventId, options?)`: RSVP mutation where supported. |
+| `useValidatePhone` | `(options?)`: phone validation mutation. |
+| `useDiscoveryTravel` | `(publicPreferenceStorage?)`: discovery travel state; any supplied adapter is distinct from assumed secure credential storage. |
+
+### Cart, payment and checkout state
+
+| Hook | Parameters / role |
+| --- | --- |
+| `useCheckout` | `(config: EngineConfig)`: **shared low-level hook** under `hooks`, requiring ports. Normally use the top-level native `useCheckout(options?)` instead. |
+| `useAppCheckoutSession` | `()`: active app checkout session/store. |
+| `useAddOnSelection` | `(eventId, checkout, { onContinue?, onSkip? })`: add-on drafts, capture and save. |
+| `useSeatSelection` | `(eventId, checkout, onContinue?)`: internal seating controller. |
+| `useSeatsIoSelection` | `(eventId, checkout, initial, onContinue?)`: Seats.io controller. |
+| `useAccommodationSelection` | `(eventId, checkout)`: stay draft, quote and reservation. |
+| `useCheckoutPaymentMethods` | `(store)`: pre-order method query for the store. |
+| `useCheckoutImageField` | `({ value, onChange, pick?, identity, disabled? })`: validates the checkout image selection. |
+| `useCheckoutPhoneIdentity` | `({ eventId?, whatsappAvailable?, currentPhone?, onVerified })`: checkout-scoped phone proof flow. |
+| `useCheckoutBuyerProfile` | `(eventId?)`: checkout buyer profile query. |
+| `useWaiverSigning` | `(eventId, waiver, attach, hold)`: signatures with cart/holder-bound holds. |
+| `useTicketCardOwner` | `()`: per-mount field owner. |
+| `useTicketCardForm` | `({ confirmer, store, owner, showsStripeField })`: coordinates the ticket card form. |
+| `useTicketGatewayWait` | `(store)`: reason a shared confirmer is held. |
+| `useConfirmerHolder` | `()`: current payment confirmer holder. |
+| `useBundleStarting` | `(store)`: bundle gateway state. |
+| `useBundlePurchase` | `(confirmer, scope?, onComplete?, checkoutStore?, visible?, section?)`: bundle purchase controller. |
+| `useBundleFlow` | `(confirmer, eventId, options)`: bundle form, payment and completion controller. |
+| `useOnEventChange` | `(eventId, onChange)`: notify a composed form of event change. |
+| `useOnOrderReleased` | `(orderFixed, onRelease)`: restore/edit a form when a non-charged placement releases it. |
+
+### Identity, profile and account
+
+| Hook | Parameters / role |
+| --- | --- |
+| `useAuthFlow` | `(options?)`: shared login/register/recovery/verification controller. |
+| `useAuthSession` | `()`: observable auth/session state. |
+| `useSessionAction` | `()`: capture a session assertion for async host actions. |
+| `useLogin` | `(options?)`: login mutation; variables include `email`, `password`. |
+| `useRegister` | `(options?)`: raw registration mutation. |
+| `useRegisterAccount` | `(options?, handoff?)`: typed account-registration mutation. |
+| `useLogout` | `(options?)`: logout mutation. |
+| `useCheckEmailExists` | `(options?)`: email check mutation. |
+| `useRestorePassword`, `useRestorePasswordRn` | `(options?)`: password recovery mutation. |
+| `useResetPassword` | `(options?)`: variables `{ token, password, passwordConfirmation? }`. |
+| `useVerifyTwoFactor` | `(options?)`: variables include `code`, `csrfToken`, `sessionEpoch`, optional expected customer ID. |
+| `useSendTwoFactorSms` | `(options?)`: variables include the pending `csrfToken` and `sessionEpoch`. |
+| `useRequestAccountEmailCode`, `useVerifyAccountEmailCode`, `useCompleteAccount` | Account email challenge/completion operations; preserve the original challenge and buyer. |
+| `usePhoneAuthentication` | `(options?)`: phone authentication flow. |
+| `useAccountEmailEnrichment` | `(options?)`: add/verify account email through its flow. |
+| `useProfile` | `(options?)`: account profile query. |
+| `useUpdateAccount`, `useUpdateProfile` | `(options?)`: account/profile mutations with `AccountUpdate` / `ProfileUpdate`. |
+| `useSavePhone`, `useSendPhoneCode`, `useVerifyPhoneCode` | `(options?)`: account phone operations. |
+| `useProfileGender` | `()`: profile gender state. |
+| `useLinkedAccounts` | `(email)`: linked accounts flow. |
+| `useAccountDeletion` | `()`: account deletion proof/blocker/submission flow. |
+| `useAccountInformation` | `(orderId, target?, enabled?)`: order information editing flow. |
+| `useAccountPlanManagement` | `(plan, orderHash, onOpen, onReturn?)`: hosted plan action flow. |
+| `useNotificationPreferences` | `()`: notification preference flow. |
+| `useAccountPreferences`, `useInterestSelection` | `(enabled?)` / `()`: account preferences and interests. |
+| `useProfileSettings` | `()`: profile link/visibility editor flow. |
+
+### Orders, rewards, social and post-purchase
+
+| Hook | Parameters / role |
+| --- | --- |
+| `useOrders` | `(query?, options?)`: account order list query. |
+| `useOrder` | `(orderId, options?)`: order detail query. |
+| `useTicketChangeOptions`, `useTicketChange` | `(access, options?)` / `(access, openUrl?, options?)`: server-offered changes, optional guest order link and handoff. |
+| `useTicketRefund` | `(ticketHash, onSubmitted?)`: refund review/submission flow. |
+| `useTicketGift` | `(ticketHash, onTicketsChanged?)`: gift flow. |
+| `useTicketResale` | `(ticket, onListed?)`: resale flow for a supplied ticket. |
+| `useCustomerPasses` | `(onTicketsChanged?)`: passes and redemptions. |
+| `useTrips`, `useTrip` | `(accountKey, query?, options?)` / `(accountKey, eventId, query?, options?)`: account trips. |
+| `useOrderRewards`, `useAccountRewards` | `(orderHash, options?)` / `(options?)`: order-specific and account aggregate queries. |
+| `useReceiptRewards` | `({ orderHash, data })`: order reward presentation/controller. |
+| `useSubmitPrizeDetails`, `useCreatePack`, `useJoinPack`, `useLeavePack`, `useRegenerateShareCard` | `(orderHash, options?)`: order-scoped reward mutations. |
+| `useAccountRewardsSummary` | `(translate)`: account rewards view/controller. |
+| `useEventComments`, `useEventDiscussion` | `(eventId, options?)`: comments and discussion flows. |
+| `useEventCommentImage` | `(eventId, comment, previewKey?, index?)`: comment image query. |
+| `useWordPostReaction` | `(postId, enabled?)`: post reaction flow. |
+| `useFriends` | `(section?)`: friends flow. |
+| `useFriendProfile` | `(id, section?, cursor?)`: profile. |
+| `useSavedEvents`, `useSavedEvent` | `(cursor?, enabled?)` / `(eventId, enabled?)`: saved-event state. |
+
+Advanced composition helpers are also in `hooks`: `useLiveScope(subject)`,
+`useScopedState(scope, initial)`, `useHeldScopes(lock, scopes)`,
+`useLockBusy(lock, scope)`, `ttfKeys`, `appCheckoutStore`,
+`rotateAppCheckoutSession`, `confirmerGateway`, `checkoutStartLock`,
+`whenConfirmerFree`, and other exported selection/gateway functions. Treat
+these as coordination tools with the declared contracts, not as permission to
+bypass a fixed order or an outstanding payment.
+
+## API facade
+
+`ttf` groups configured API calls and helpers. Network calls usually return
+promises; `ttf.events.filterAddonsForTickets` and
+`ttf.order.mapProfileToBilling` are synchronous. Import `ttf` from the native
+package after native setup. For example:
+
+```ts
+import { ttf } from 'tf-checkout-react-native'
+
+export async function loadCatalog(eventId: string) {
+  const [info, tickets] = await Promise.all([
+    ttf.events.info(eventId),
+    ttf.events.ticketsWithMeta(eventId),
+  ])
+  return { info, tickets }
+}
+```
+
+The facade is not a payment UI or a replacement for the engine's preflight,
+confirmation and uncertainty handling. Some calls change server state and
+require an authorized buyer, event, order or other proof. Its domain map:
+
+| Domain | 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.auth` | `loginForCheckout`, `loginCheckoutWithVerifiedPhone`, `registerForCheckout`, `getCheckoutBuyerProfile`, checkout email/2FA methods, `logoutFromCheckout`, account deletion/linking, browser sign-in, account email/phone verification, `login`, `register`, `registerAccount`, `logout`, password recovery/reset, email check and identity verification methods |
+| `ttf.profile` | `get`, `updateAccount`, `update`, `savePhone`, `sendPhoneCode`, `verifyPhoneCode` |
+| `ttf.geo` | `countries`, `states` |
+| `ttf.extras` | `accommodation`, `quoteAccommodation`, `reserve` |
+| `ttf.orders` | `list`, `get`, `myTickets`, `updateOrderCustomFields`, `updateTicketHolderCustomFields`, `updateAddOnCustomFields` |
+| `ttf.engagement` | `attributeReferrer`, `joinWaitingList`, `sendRsvp`, `validatePhone` |
+| `ttf.seatmap` | `startSession`, `data`, `statuses`, `reserve`, `removeReserved`, `refreshReservation` |
+| `ttf.ticketChanges` | `options`, `change`, `joinWaitlist`, `leaveWaitlist`, `history` |
+| `ttf.refunds` | `options`, `submit` |
+| `ttf.gifts` | `options`, `send`, `cancel` |
+| `ttf.passes` | `list`, `get`, `events`, `bookings`, `redeem`, `cancel` |
+| `ttf.trips` | `list`, `get` |
+| `ttf.resale` | `sell`, `remove`, `process`, `decline` |
+| `ttf.confirmation` | `get` |
+| `ttf.rewards` | `forOrder`, `forAccount`, `submitPrizeDetails`, `createPack`, `joinPack`, `leavePack`, `regenerateShareCard` |
+| `ttf.waivers` | `forCheckout`, `uploadSignatureImage` |
+| `ttf.comments` | `list`, `image`, `create`, `update`, `remove`, `react`, `report`, `block`, `moderate` |
+| `ttf.word` | `getReaction`, `setReaction` |
+| `ttf.friends` | `list`, `preview`, `command`, `saveSettings`, `saveProfileSettings`, `matchContacts`, `profile` |
+| `ttf.savedEvents` | `list`, `status`, `save` |
+| `ttf.preferences` | `getNotifications`, `saveNotifications`, `get`, `save`, `connectAppleMusic`, `disconnectAppleMusic`, `connectSpotify`, `disconnectSpotify` |
+| `ttf.preRegistration` | `confirm`, `influencers`, `confirmationPage`, `submitShareAction` |
+| `ttf.delegation` | `checkCustomerExists`, `pageInfo`, `issueTicket` |
+
+`api` exports raw API functions in a namespace; `ENDPOINTS` provides endpoint
+constants. Use declarations to choose the exact method signature and response
+envelope. Direct calls still require the right session and may not carry the
+state-management guarantees of the checkout engine. Never store the raw
+credentials or log authorization headers, payment secrets, buyer answers or
+full provider payloads.
+
+## Headless state, actions and ports
+
+`NativeUseCheckout` extends `UseCheckout` and `CheckoutSnapshot`. The top-level
+native `useCheckout({ ports?, options?, paymentSheet? })` merges optional ports
+over native defaults. `CheckoutProvider` creates it when `value` is omitted;
+when a host passes `value`, configure the hook itself. Its snapshot is also
+spread on the return value. Derived `isBusy`, `secondsLeft`,
+`missingRequiredAddonNames`, `buyerFields` and `isLoggedIn` are useful for
+custom UI. `isLoggedIn` can reflect an authenticated access/header-backed
+session or an event-bound in-memory checkout buyer. It does not establish full
+private-account scope.
+
+Important actions:
+
+```text
+// Signatures are descriptive; invoke these on a hook/engine, not at module scope.
+setTickets(eventId, selections)             // Promise<void>
+setSeats(eventId, seatLines)                // Promise<void>
+setSeatsIo(eventId, selection)             // Promise<void>
+resumeCart(eventId, { isFromResale? })      // Promise<void>
+setAddons({ [addOnId]: quantity })         // Promise<void>, reprices
+setExtraItems(items)                       // Promise<void>
+setExtraDraft(itemsOrUndefined)            // void
+setBilling(billing)                        // void
+setHolders(holders, { backfilled? })        // void
+setConsent({ ttfOptIn, brandOptIn })        // void
+setAcceptedConditions({ [id]: boolean })   // void
+acceptCondition(id, accepted)               // void
+setAddonDataCapture({ [addOnId]: values }) // void
+holdWaiverSigning(index)                   // hold | null; release when done
+setWaiverSignature(index, signatureOrNull, hold?) // boolean
+checkBuyerEmail(email)                     // Promise<void>
+reloadCheckoutDetails()                   // Promise<void>
+syncCurrency(eventId, code?, options?)     // Promise<CurrencySync>
+placeOrder(method?, options?)              // Promise<PlaceOrderResult>
+runIdVerification(orderHash, options?)      // Promise<IdVerificationStatus | undefined>
+applyPromoCode(eventId, promo)             // Promise<void>
+attributeReferrer(eventId, referrerOrNull) // Promise<void>
+joinWaitingList(eventId, entry)             // Promise<void>
+reset()                                    // void
+resetWhenSettled()                         // Promise<boolean>
+```
+
+`placeOrder` accepts a simple card/wallet method or a `PaymentRequest` union;
+review the README's payment section before constructing a custom selector. The
+`options` can include `autoRunIdVerification`, `idVerification`, and
+`claimCard`. After the order step returns, automatic ID-verification rejection
+is swallowed. A pending order can also request verification; failure of that
+separate step proves neither payment failure nor settlement. Present its status
+independently. When money may have moved, preserve and reconcile the original
+order. `resetWhenSettled`
+returns false for a retained or retired checkout. A provider page, picker or
+other custom port must settle on all close/cancel/unmount paths.
+
+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 say registration is complete and the buyer
+is registered 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.
+
+`CheckoutOptions` has `stripePublishableKey`, `merchantIdentifier`,
+`merchantCountryCode`, `merchantName`, `googlePayTestEnv`, `redirectReturnUrl`
+and `urlScheme`. The native `Payment` Google Pay support probe derives test
+mode from `env` (`STAG`/`DEV`), while confirmation uses `googlePayTestEnv`.
+Set them consistently and test both on device; `baseUrl` does not set `env`.
+The wallet merchant country comes from the order review.
+`NativePaymentSheetOptions` requires `merchantDisplayName` and
+`returnURL`; it is a limited opt-in and requires matching registered scheme,
+callback routing and provider eligibility. `CheckoutPorts` requires a
+`confirmer: PaymentConfirmer` and has optional `claimDefaultCardField`,
+`providerPage`, `openUrl`, `onInstallmentOffers`, `tokenizeXenditCard` and
+payment-specific `PaymentConfirmerExtras`. `createRnStripeConfirmer()` and
+`createRnPorts()` create native adapters; `rnConfirmer` and `rnPorts` are the
+package instances. `rnPorts` includes native Stripe rails and Linking but no
+provider-page presentation. `Payment` inside a self-providing
+`CheckoutProvider` includes the provider page and installment picker; a
+headless/controlled host supplies them.
+
+For advanced non-React use, `createEngine({ ports, options?, store? })` returns
+`store`, `getSnapshot`, `subscribe`, `prime`, `primeSeats`, `primeSeatsIo`,
+`resumeCart`, the setters, `placeOrder`, `syncCurrency`, `runIdVerification`,
+`reset`, `resetWhenSettled` and `expireCart`. `createCheckoutStore(initial?)`
+constructs a store. A separate custom store is an explicit ownership decision;
+do not run competing flows against the same buyer/cart or provider UI. The
+shared confirmer returns Stripe-style intent statuses; a custom confirmer must
+use accurate `paymentProviderError` outcome classifications and retain unknown
+outcomes. See the declarations for all method contracts and status types.
+
+## Types and errors
+
+Key shapes:
+
+- `TicketSelection`: `id`, `name`, `optionName`, `price`, `quantity`, `currency`.
+- `SeatLine`: `seatId`, `tierId`, `ticketTypeId`, `optionName`, `price`, optional
+  `guests`; only for a seat already reserved through the appropriate flow.
+- `CheckoutBilling`: required `firstName`, `lastName`, `email`; optional email
+  confirmation, phone, address, IDs/codes, DOB, event-gated fields and
+  `dataCapture`.
+- `CheckoutHolder`: required `firstName`, `lastName`, `email`; optional `phone`,
+  numeric ticket-type ID encoded as string, and `ticketDataCapture`.
+- `CheckoutConsent`: `ttfOptIn`, `brandOptIn` booleans. `EventCondition`:
+  `id`, `name`, `content`, `isRequired`.
+- `CheckoutImagePicker`: asynchronous picker returning raw base64 and optional
+  dimensions, or `null`. The SDK checks base64 encoding and image signature,
+  the 2 MiB maximum and supplied dimensions (at most 4096 pixels per side); the
+  server validates decoded bytes. The host owns OS permissions and storage.
+- `PlaceOrderResult`: `orderHash`, `free`, `needIdVerification`, with optional
+  `currency`, `paymentIntentId`, `alreadyPaid`, `pending`, `pendingVoucherUrl`.
+  `pending: true` is not a paid receipt; absence of that flag does not prove
+  settlement. Stripe `Processing` or `RequiresCapture` may omit it.
+- `CheckoutStatus`: `idle`, `priming`, `ready`, `repricing`, `placing`,
+  `succeeded`, `expired`, `error`. Consult the full snapshot for order/payment
+  ownership; a status alone is not a provider settlement statement.
+- `TtfError`: `message`, `status`, optional `code`, `data`, `retryAfter`.
+  `status === 0` indicates a transport/network error. `errorMessage` and
+  `isCartExpiredError` help present errors.
+
+Other useful exports include `CartChangedError`, `ConfirmerBusyError`,
+`CardClaimError`, `PAID_ORDER_PENDING_MESSAGE`, `CART_CHANGED_MESSAGE`,
+`paymentProviderError`, `createMemoryStorage`, `getConfig`, `isConfigured`,
+`clearSession`, `clearCheckoutGuestSession`, `isAuthenticated`,
+`captureSessionAction`, `createTranslator`, `resolveLocale` and
+`registerCatalogue`. Memory storage is for tests, not secure persistence;
+clearing session or resetting an order must respect any in-flight operation.
+Consult the versioned declarations for the complete named type, logic and helper
+surface.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tf-checkout-react-native",
-  "version": "2.0.0-beta.23",
+  "version": "2.0.0-beta.24",
   "description": "TheTicketFairy ReactNative Checkout library",
   "homepage": "https://github.com/theticketfairy/tf-shared-libraries#readme",
   "author": "The Ticket Fairy",
@@ -39,7 +39,8 @@
     "!scripts/verify-provider-uri.cjs",
     "!scripts/verify-native-textarea.cjs",
     "!scripts/verify-frozen-select.cjs",
-    "!scripts/verify-payment-sheet.cjs"
+    "!scripts/verify-payment-sheet.cjs",
+    "docs"
   ],
   "scripts": {
     "test": "node scripts/verify-discussion-support.cjs && node scripts/verify-wallet-context.cjs && node scripts/verify-provider-uri.cjs && node scripts/verify-native-textarea.cjs && node scripts/verify-frozen-select.cjs && node scripts/verify-payment-sheet.cjs && jest --passWithNoTests",