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

package/README.md

@@ -5,21 +5,73 @@ tickets. Start with `EmbeddedCheckout`, compose individual sections, or own the
 presentation using `useCheckout` and the shared API. The package includes its
 private shared core; hosts do not install `tf-checkout-shared`.
 
-This reference is for **`tf-checkout-react-native@2.0.0-beta.24`**, a
+This reference is for **`tf-checkout-react-native@2.0.0-beta.26`**, a
 prerelease with a different API from 1.x (including its `CheckoutV2`). Pin the
 version: `latest` and `beta` tags can move; check `npm view tf-checkout-react-native dist-tags`.
-The [API reference](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.24/docs/API.md)
-covers components and hooks; the [declarations](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.24/dist/index.d.ts)
-contain all types. The [web package](https://www.npmjs.com/package/tf-checkout-react/v/2.0.0-beta.24)
+The [API reference](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.26/docs/API.md)
+covers components and hooks; the [declarations](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.26/dist/index.d.ts)
+contain all types. The [web package](https://www.npmjs.com/package/tf-checkout-react/v/2.0.0-beta.26)
 shares the engine but has different UI and ports. Availability depends on the
 backend, event, gateway, account and device; installation does not establish
 hosted-checkout parity or payment acceptance.
 
+## Choose a ready-made layout
+
+The SDK supplies native UI for the checkout steps. Start with the complete
+checkout unless your app needs to control the screens and navigation itself.
+
+| I want to… | Use | Where to start |
+| --- | --- | --- |
+| Add a complete checkout | `EmbeddedCheckout` | [Quick start](#requirements-and-installation) |
+| Show ticket selection, seats, buyer details and payment on my own screens | `CheckoutProvider` with the ready-made sections | [Compose sections](#compose-sections-and-navigation) |
+| Add sign-in, registration and recovery | `AuthModal` or individual forms | [Authentication sheet](#a-reusable-authentication-sheet) |
+| Let a buyer change, gift or request a refund for a ticket | `TicketChange`, `TicketGift`, `TicketRefund` | [Ticket management screens](#ticket-management-screens) |
+| Show passes, rewards or account settings | Ready-made account and post-purchase sections | [Screen directory](#ready-made-screens-and-flows) |
+
+For example, after you [restore storage and configure the SDK](#initialize-secure-storage-and-configure),
+this renders the complete checkout. Do not mount it until initialization has
+finished. `EmbeddedCheckout` creates its own `CheckoutProvider` and React Query
+client for the checkout; hooks used elsewhere need their own
+`QueryClientProvider`.
+
+```tsx
+import { EmbeddedCheckout, type PlaceOrderResult } from 'tf-checkout-react-native'
+
+export function CheckoutScreen({ eventId, onComplete }: {
+  eventId: string
+  onComplete: (order: PlaceOrderResult) => void
+}) {
+  return <EmbeddedCheckout eventId={eventId} confirmationMode="redirect"
+    onComplete={onComplete} />
+}
+```
+
+The host owns the order-status route and must reconcile payment before showing
+a paid receipt or fulfilling an order. Follow the setup below before mounting
+this component. The [migration guide](#migration-from-1x) maps the former
+native layouts to the available beta components and calls out missing screens.
+
+## Quick start at a glance
+
+1. [Install the SDK and native peers](#requirements-and-installation), then
+   build an Expo development client or a bare native app.
+2. [Restore credential storage and configure the SDK](#initialize-secure-storage-and-configure).
+   Create the two named files shown there, using a **staging** client ID.
+3. [Mount the complete checkout](#embed-a-checkout) with your test event ID.
+   The example waits for setup and handles the order result.
+4. Run the app on a supported device or simulator. The ticket list should load
+   for an available test event; if it does not, see [troubleshooting](#testing-and-troubleshooting).
+
+Ask your Ticket Fairy integration contact for a public SDK client ID, the test
+environment and an event configured for your integration. Never put a client
+secret or provider secret key in the app.
+
 ## Contents
 
 - [Requirements and installation](#requirements-and-installation)
 - [Initialize secure storage and configure](#initialize-secure-storage-and-configure)
 - [Embed a checkout](#embed-a-checkout)
+- [Ready-made screens and flows](#ready-made-screens-and-flows)
 - [Compose sections and navigation](#compose-sections-and-navigation)
 - [Checkout section reference](#checkout-section-reference)
 - [Tickets, seats, codes and attribution](#tickets-seats-codes-and-attribution)
@@ -34,6 +86,10 @@ hosted-checkout parity or payment acceptance.
 
 ## Requirements and installation
 
+Choose the installation command for your app below. Both paths require a
+native build; installing the JavaScript package alone does not add native
+modules to an existing binary.
+
 The package declares Node `>=20.19.4`, React `>=19.1`, React Native `>=0.81`,
 `@tanstack/react-query >=5`, `@stripe/stripe-react-native >=0.45.0`,
 `@react-native-clipboard/clipboard >=1.14.0`, `react-native-webview >=13.15.0`,
@@ -49,7 +105,7 @@ identify duplicates.
 For an Expo project with compatible React and RN versions:
 
 ```sh
-npx expo install tf-checkout-react-native@2.0.0-beta.24 \
+npx expo install tf-checkout-react-native@2.0.0-beta.26 \
   @tanstack/react-query @stripe/stripe-react-native \
   @react-native-clipboard/clipboard react-native-webview \
   react-native-render-html@6.3.4 expo-secure-store
@@ -76,13 +132,13 @@ using your normal process. For a bare React Native app, install the peers in
 the app (React and React Native are normally already present):
 
 ```sh
-npm install tf-checkout-react-native@2.0.0-beta.24 @tanstack/react-query \
+npm install tf-checkout-react-native@2.0.0-beta.26 @tanstack/react-query \
   @stripe/stripe-react-native @react-native-clipboard/clipboard \
   react-native-webview react-native-render-html@6.3.4
 ```
 
 Configure autolinking and Stripe's native setup, run `pod install` in the iOS
-directory, and rebuild both platforms. Provide a Keychain/Keystore-backed
+directory, and rebuild each platform you support. Provide a Keychain/Keystore-backed
 storage adapter using a native library appropriate to the host. Consult the
 [Stripe React Native setup](https://docs.stripe.com/payments/accept-a-payment?platform=react-native)
 and [Expo SecureStore documentation](https://docs.expo.dev/versions/latest/sdk/securestore/)
@@ -108,12 +164,17 @@ code. Obtain a public SDK client ID authorized for the integration and use an
 empty `clientSecret` for public checkout; do not substitute a confidential
 credential. Environment variables compiled into an app are visible to its users.
 
-The SDK reads storage synchronously. The following Expo example asynchronously
-restores one protected snapshot first, then makes each subsequent OS write
-synchronously *before* publishing the new in-memory snapshot. The methods are
+Create `credentialStorage.ts`. The SDK reads storage synchronously; this Expo
+example asynchronously restores one protected snapshot first, then makes each
+subsequent OS write synchronously *before* publishing the new in-memory snapshot. The methods are
 not `async` and a failed write throws instead of reporting success. Replace the
 namespace with an app-owned, environment-specific key.
 
+For a bare React Native app without Expo modules, implement the same
+`StorageAdapter` with your app's Keychain/Keystore-backed storage instead. Do
+not copy the Expo-specific example unless Expo SecureStore is installed and
+configured in that app.
+
 ```ts
 // credentialStorage.ts
 import * as SecureStore from 'expo-secure-store'
@@ -154,6 +215,9 @@ corrupt snapshot or unavailable OS store must be handled explicitly; do not
 silently report durable sign-in. Migrate old credentials securely or require
 sign-in again.
 
+Next create `checkoutSetup.ts`. This example uses staging; switch to a
+production public SDK client ID, event and storage namespace for production.
+
 ```ts
 // checkoutSetup.ts
 import { configureCheckout } from 'tf-checkout-react-native'
@@ -163,9 +227,9 @@ let initialization: Promise<void> | undefined
 export function prepareCheckout(): Promise<void> {
   if (!initialization) {
     initialization = (async () => {
-      const storage = await restoreCredentialStorage('my_app_checkout_prod')
+      const storage = await restoreCredentialStorage('my_app_checkout_staging')
       configureCheckout({
-        env: 'PROD',
+        env: 'STAG',
         clientId: 'YOUR_PUBLIC_SDK_CLIENT_ID',
         clientSecret: '',
         storage,
@@ -200,7 +264,9 @@ access. Do not infer full account authorization from checkout authentication.
 
 Mount only after `prepareCheckout` resolves. `EmbeddedCheckout` provides its own
 `CheckoutProvider` and React Query client. Any separate React Query hooks outside
-that subtree need a `QueryClientProvider` of their own.
+that subtree need a `QueryClientProvider` of their own. Put this component in
+`App.tsx` or your checkout screen, and replace `YOUR_EVENT_ID` with an event in
+the same environment as your client ID.
 
 ```tsx
 import React, { useEffect, useState } from 'react'
@@ -240,6 +306,12 @@ export default function EventCheckout() {
 }
 ```
 
+After launching the native app, the event's ticket-selection screen should
+appear. Select a test ticket to reach buyer details and payment. If the catalog
+does not load, check the event, client ID and environment before trying a real
+payment. The example returns the order reference to the host; it does not
+implement an order-status service.
+
 `onComplete` is an order result, not proof of settled payment. `pending: true`
 requires pending instructions, but `pending !== true` also does not prove
 capture or settlement. `confirmationMode="inline"` (default) shows the stock
@@ -247,8 +319,9 @@ receipt, which can say tickets are confirmed for a non-pending order before
 final capture/settlement. Hosts requiring verified paid status should use
 `"redirect"` or custom UI and reconcile with the authoritative backend and
 provider before presenting that status or fulfilling. Redirect mode delegates
-routing to `onComplete` and keeps checkout mounted during handoff; the host owns
-navigation. The example shows a local fallback, not a complete status screen:
+routing to `onComplete` and keeps checkout mounted during handoff; provide that
+callback to navigate, or no host status screen is reached. The example
+shows a local fallback, not a complete status screen:
 the host must implement reconciliation, retain the order reference and voucher
 across its navigation/restart, and arrange verification when required. Validate
 provider URLs against the host's policy before opening them.
@@ -284,6 +357,161 @@ base64 encoding and the image signature, the 2 MiB maximum and any supplied
 dimensions (at most 4096 pixels per side); the server validates decoded bytes.
 The host owns permission and picker UX. For the separate event discussion picker, see its props below.
 
+## Ready-made screens and flows
+
+The SDK has one complete checkout layout, `EmbeddedCheckout`. Its `initialView`
+chooses tickets or seats, and `confirmationMode` chooses an inline receipt or
+host-owned navigation. It also exposes the sections below so you can put them
+on your own screens. These are native React components, not HTML or WebViews
+except where the seat map or a payment provider needs one.
+
+| Screen or task | Ready-made components | Setup |
+| --- | --- | --- |
+| Ticket selection and seating | `Tickets`, `SeatMap`, `Bundles` | Put them under one `CheckoutProvider`; pass `eventId`. Connect the tickets callbacks to your navigation. |
+| Checkout details | `AddOns`, `Accommodation`, `BillingInfo`, `WaiverSigning`, `OrderSummary`, `Payment` | Use the same provider and reserved cart. Match billing and payment validation props. |
+| Verify or display a result | `IDVerification`, `Confirmation`, `Rewards` | Verification and confirmation read the active checkout; use an authoritative host status before showing confirmed copy. |
+| Sign in or recover a password | `AuthModal`, `LoginForm`, `RegisterForm`, `ForgotPasswordForm`, `ResetPasswordForm`, `TwoFactorForm`, `EmailCodeForm`, `PhoneAuthentication` | Configure the SDK first. Use the modal for a complete sheet or the forms with a host-owned flow. |
+| Change, gift or request a refund | `TicketChange`, `TicketGift`, `TicketRefund` | Provide a ticket hash and the required buyer/session authority. See the [example below](#ticket-management-screens). |
+| Passes and rewards | `Passes`, `Rewards`, `RewardsLadder`, `RewardsTree`, `AccountRewardsSection` | Use the appropriate signed-in account or order context; eligibility comes from the server. |
+| Account settings and order information | `ProfileSettings`, `NotificationPreferences`, `AccountDeletion`, `AccountInformationSection`, `AccountPaymentPlanSection`, `Streaming`, `Trips`, `AccountEmailEnrichment` | Configure account access and a query provider; the host owns navigation and any required handoff. |
+| Discussion and reactions | `EventDiscussionView`, `PostReaction`, `PostReactionControls`, `PostReactionFeedback` | Supply the required event/discussion or post/flow and authorized session. |
+
+`AccountDeletionView`, `ProfileSettingsView`, `NotificationPreferencesView` and
+`StreamingView` are controlled variants: use them when your host already owns
+the corresponding flow. The ordinary component creates that flow for you. See
+the [component API reference](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.26/docs/API.md#account-and-post-purchase-components)
+for required props and variants.
+
+There is no native `MyOrders`, `MyOrderDetails`, `ResaleTickets`, `CheckoutSP`,
+`CheckoutV2` or `ResumedCheckout` layout exported in this version. The
+[migration table](#migration-from-1x) explains what can be composed and what the
+host must build.
+
+### A reusable authentication sheet
+
+The complete `EmbeddedCheckout` already opens its built-in sign-in sheet. Use
+`AuthModal` separately when your app owns the sign-in button or wants to show
+the sheet elsewhere. Run `prepareCheckout()` from the quick start before
+mounting this example. Here `checkoutEventId` requests the event-scoped
+checkout sign-in; it is not a full account session.
+
+```tsx
+import React, { useState } from 'react'
+import { Button, Text, View } from 'react-native'
+import { AuthModal, CheckoutProvider } from 'tf-checkout-react-native'
+
+export function CheckoutSignIn({ eventId }: { eventId: string }) {
+  const [open, setOpen] = useState(false)
+  const [notice, setNotice] = useState('')
+  return (
+    <CheckoutProvider>
+      <View>
+        <Button title="Sign in for checkout" onPress={() => setOpen(true)} />
+        <Text>{notice}</Text>
+        <AuthModal open={open} onClose={() => setOpen(false)}
+          checkoutEventId={eventId}
+          onCheckoutAuthenticated={() => setNotice('Checkout sign-in complete.')} />
+      </View>
+    </CheckoutProvider>
+  )
+}
+```
+
+`open` and `onClose` control the sheet. `allowRegistration` and
+`allowPasswordReset` default to true; `initialEmail` and `logoUrl` customize it.
+For a separately authorized account flow, omit `checkoutEventId`, configure
+the supported account journey and use `onAuthenticated`. If the screen is
+already under your checkout's provider, render `AuthModal` inside that provider
+instead of adding another one.
+
+### Complete a password reset
+
+`AuthModal` starts password recovery. Your app handles the reset link and passes
+its token to `ResetPasswordForm`. Configure the SDK before mounting this route;
+the form submits the new password and can offer a way back to sign-in.
+
+```tsx
+import React from 'react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { CheckoutThemeProvider, ResetPasswordForm } from 'tf-checkout-react-native'
+
+const queryClient = new QueryClient()
+
+export function PasswordResetScreen({ token, openSignIn }: {
+  token: string
+  openSignIn: () => void
+}) {
+  return <QueryClientProvider client={queryClient}>
+    <CheckoutThemeProvider>
+      <ResetPasswordForm token={token} onBackToLogin={openSignIn} />
+    </CheckoutThemeProvider>
+  </QueryClientProvider>
+}
+```
+
+Use your existing query provider if one is already mounted. Handle expired or
+missing links in the host and do not log the reset token.
+
+### Ticket management screens
+
+After SDK setup and an authorized buyer session, the following component can
+render one ready-made change, gift, refund or pass screen on a host-owned route.
+Use a current ticket hash from an authorized order. The host owns navigation
+and must refresh its own ticket list after a change. A refund submission is a
+request, not proof the refund has completed.
+
+```tsx
+import React from 'react'
+import { ScrollView } from 'react-native'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+  CheckoutThemeProvider, Passes, TicketChange, TicketGift, TicketRefund,
+} from 'tf-checkout-react-native'
+
+const queryClient = new QueryClient()
+
+export function TicketTools({ ticketHash, orderHash, screen, onDone }: {
+  ticketHash: string
+  orderHash?: string
+  screen: 'change' | 'gift' | 'refund'
+  onDone: () => void
+}) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <CheckoutThemeProvider>
+        <ScrollView>
+          {screen === 'change' && <TicketChange ticketHash={ticketHash}
+            orderHash={orderHash} onChanged={onDone} />}
+          {screen === 'gift' && <TicketGift ticketHash={ticketHash}
+            onDone={onDone} />}
+          {screen === 'refund' && <TicketRefund ticketHash={ticketHash}
+            onDone={onDone} />}
+        </ScrollView>
+      </CheckoutThemeProvider>
+    </QueryClientProvider>
+  )
+}
+
+export function MyPasses() {
+  return <QueryClientProvider client={queryClient}>
+    <CheckoutThemeProvider><Passes /></CheckoutThemeProvider>
+  </QueryClientProvider>
+}
+```
+
+`TicketChange` accepts `orderHash` for a supported guest order link and can
+open a hosted page for a paid change. `TicketGift` and `TicketRefund` do not
+accept that prop; check their own authorization and server eligibility. In an
+existing app use its query client instead of creating another provider, and
+clear or scope private query data when the buyer signs out or changes. Coordinate
+host navigation with in-flight actions and check authoritative status on return;
+do not treat leaving a screen as proof that a request did or did not complete.
+In this example `onDone` is host navigation, not a success signal: the gift
+screen can offer its exit before a gift is sent. Use `TicketGift`'s
+`onTicketsChanged` and `TicketRefund`'s `onSubmitted` for their respective
+notifications. `TicketChange.onChanged` runs on Back after a completed
+no-payment change; reconcile a paid change after returning from its hosted page.
+
 ## Compose sections and navigation
 
 `CheckoutProvider` owns a native `useCheckout()` instance, a query provider,
@@ -292,12 +520,23 @@ it share the app checkout store. `useCheckoutContext()` reads this instance and
 throws outside the provider. The following intentionally uses one combined
 billing/payment form after reservation; callbacks route tickets and seats.
 
+This is a wiring recipe, not a complete navigation flow. It includes a return
+from the seat view and keeps `Tickets` mounted while switching views. The host
+still needs to implement Edit and Back from checkout, preserve entered details,
+handle seat holds and cart expiry, and guard event/session changes and in-flight
+or retained payments. Use `EmbeddedCheckout` for its built-in Back and guarded
+Edit behavior.
+The seat-view Back button only changes views: it does not itself release reserved
+seats or cancel an already-started reservation or cart priming. Coordinate any
+in-flight work and the hold's expiry or release under your deployed backend
+contract before permitting a conflicting selection.
+
 ```tsx
 import React, { useState } from 'react'
-import { ScrollView, Text, View } from 'react-native'
+import { Button, ScrollView, Text, View } from 'react-native'
 import {
   CheckoutProvider, Tickets, SeatMap, AddOns, BillingInfo, WaiverSigning,
-  OrderSummary, Payment, IDVerification, useCheckoutContext,
+  Payment, useCheckoutContext,
   type PlaceOrderResult,
 } from 'tf-checkout-react-native'
 
@@ -312,22 +551,24 @@ function Flow({ eventId, onComplete }: {
       <Text>Order submitted: {checkout.order.orderHash}. Check payment status.</Text>
       {checkout.order.pending && <Text>Payment pending.</Text>}
       {checkout.order.pendingVoucherUrl && <Text selectable>{checkout.order.pendingVoucherUrl}</Text>}
-      <IDVerification />
+      {checkout.order.needIdVerification && <Text>Identity verification is required.</Text>}
     </View>
   )
   return (
     <ScrollView keyboardShouldPersistTaps="handled">
-      {view === 'tickets' && <Tickets eventId={eventId}
-        onSelectSeats={() => setView('seats')}
-        onContinue={() => setView('checkout')} />}
-      {view === 'seats' && <SeatMap eventId={eventId}
-        onContinue={() => setView('checkout')} />}
+      <View style={view === 'tickets' ? undefined : { display: 'none' }}>
+        <Tickets eventId={eventId} onSelectSeats={() => setView('seats')}
+          onContinue={() => setView('checkout')} />
+      </View>
+      {view === 'seats' && <View>
+        <Button title="Back to tickets" onPress={() => setView('tickets')} />
+        <SeatMap eventId={eventId} onContinue={() => setView('checkout')} />
+      </View>}
       {view === 'checkout' && <>
         <AddOns eventId={eventId} />
         <BillingInfo eventId={eventId} requireEmailConfirmation
           collectTicketHolders collectHolderContact />
         <WaiverSigning eventId={eventId} />
-        <OrderSummary eventId={eventId} />
         <Payment requireEmailConfirmation collectTicketHolders requireHolderContact
           onComplete={onComplete} />
       </>}
@@ -348,10 +589,13 @@ navigation transition depend solely on its `onContinue` unless your host handles
 that case. With no `onContinue`, `AddOns` and `BillingInfo` use combined-form
 behavior. Match `BillingInfo`'s email/holder policy to `Payment`'s
 `requireEmailConfirmation`, `collectTicketHolders` and `requireHolderContact`.
-The composed example renders the verification control for a required order;
-the buyer must press Verify. Before changing event, leaving payment or starting
-another cart, handle in-flight and retained orders as described under
-[safe completion](#payments-and-safe-completion).
+The composed example only shows neutral verification-required text: your host
+must arrange the verification and status journey. If its parent `onComplete`
+navigates away or unmounts this component, even that inline status view will
+not appear. Keep the active provider mounted for an inline flow, or handle
+verification and authoritative order status at the destination. Before changing
+event, leaving payment or starting another cart, handle in-flight and retained
+orders as described under [safe completion](#payments-and-safe-completion).
 
 `CheckoutProvider` props: `children` (required), `theme`, `pickImage`,
 `options` (wallet/redirect `CheckoutOptions`), `paymentSheet`, `queryClient`,
@@ -429,12 +673,21 @@ required fields. All props are optional:
 
 | Component | Props and behavior |
 | --- | --- |
-| `OrderSummary` | `eventId?`, `locale?`, `messages?`, `translate?`. Displays server-priced cart totals and optional event name. |
+| `OrderSummary` | `eventId?`, `locale?`, `messages?`, `translate?`. Displays server-priced cart totals and optional event name. `Payment` already renders it; use it separately when you need a summary elsewhere. |
 | `WaiverSigning` | **`eventId`**; `locale?`, `messages?`, `translate?`. Renders only when the event has a waiver; supports the server-offered signing methods. |
 | `Payment` | `onComplete?(order)`, `eventId?` (currently unused by native payment), `requireEmailConfirmation?`, `collectTicketHolders?`, `requireHolderContact?`, `additionalConditions?`, `requirePrivacyPolicy?`, `onPrivacyRequired?`, `showTestCardHint?`, `locale?`, `messages?`, `translate?`. Standalone boolean defaults are false. It validates, renders eligible methods and submits. |
-| `IDVerification` | No props. When required, it shows a Verify button; the buyer must press it to open and poll the provider. A stall proves neither failure nor settlement. |
+| `IDVerification` | No props. When required, it shows a Verify button; the buyer must press it to open and poll the provider. Its verified text says tickets are on their way without checking settlement or issuance. |
 | `Confirmation` | `shareUrl?`, `shareMessage?`, `viewOrderUrl?`, `message?`, `children?`. Reads the current order. Its stock title and share copy do not independently verify payment settlement or referral eligibility; see below. |
 
+The stock `IDVerification` verified message says tickets are on their way, but
+verification alone does not establish payment settlement or ticket issuance.
+Use a host-owned verification/status UI around `runIdVerification(orderHash, options)`
+when neutral copy is required, and reconcile the authoritative order/provider
+status. If `onComplete` navigates away, handle verification at the destination;
+unmounting the checkout prevents its inline verification view from appearing.
+See [host-owned ID verification](#host-owned-id-verification) for URL opening,
+return handling and neutral error copy.
+
 `Payment` gates its rendered event conditions, host `additionalConditions` and
 requested privacy acknowledgment in its UI. Each `EventCondition` is
 `{ id: string, name: string, content: string, isRequired: boolean }`. These
@@ -540,7 +793,7 @@ and email-confirmation defaults; match it with the paired `Payment` props. The
 SDK's confirmation email value is a UI check; the order API uses the primary
 email. Recheck terms, privacy and marketing consent with your own policy.
 
-**Beta.23 consent limitation:** when `privacyPolicy` is supplied, the stock
+**Consent limitation:** when `privacyPolicy` is supplied, the stock
 privacy checkbox reads and writes `consent.ttfOptIn`, which the order sends as
 `ttf_opt_in`. It is not independent of the Ticket Fairy marketing flag. The
 brand opt-in uses a separate value. If both opt-in labels are explicitly empty,
@@ -554,8 +807,10 @@ is required, use a custom flow and a tested backend consent contract.
 During cart priming, failed custom-field, checkout-config, add-on or event
 condition reads fall back to empty/default data. The stock UI cannot show or
 gate requirements it did not load. Only a failed waiver read (except a 404) is
-recorded in `unavailableDetails` and retried/gated. Do not treat an empty list as
-proof that no requirement exists; verify deployment/failure behavior and add
+recorded in `unavailableDetails`. Before money may have moved, placement retries
+an unavailable waiver and blocks if it remains unknown; a retained order with a
+possible payment follows separate recovery and needs reconciliation. Do not treat
+an empty list as proof that no requirement exists; verify failure behavior and add
 tested host safeguards for mandatory fields and acknowledgments. Server
 validation of required answers is not proof that a condition was acknowledged.
 
@@ -588,9 +843,9 @@ redirect routing when your fulfillment policy requires verified payment.
 When `needIdVerification` is true, the host must arrange a separate verification
 journey. Inline `IDVerification` requires the buyer to press Verify; redirect
 mode does not render it. A composed host can render `IDVerification` under the
-active `CheckoutProvider`, or call `runIdVerification(orderHash)` from a custom
-flow. Handle navigation/returns; a failed or delayed verification proves neither
-payment failure nor settlement.
+active `CheckoutProvider`, or call `runIdVerification(orderHash, options)` from a custom
+flow with the host URL opener described below. Handle navigation/returns; a
+failed or delayed verification proves neither payment failure nor settlement.
 
 **Zero-total orders:** this SDK ignores the free-registration response body and
 reports `needIdVerification: false`. Verification or approval may still be
@@ -614,20 +869,37 @@ is not an exactly-once charging guarantee across every host/provider.
 `reset()` starts a reset and returns no completion signal. Prefer
 `await resetWhenSettled()` when navigating to a new checkout: it waits for an
 in-flight payment and returns `true` only if reset completed. `false` can mean
-the original order is retained or the checkout was retired. Show
-`PAID_ORDER_PENDING_MESSAGE` where appropriate and reconcile; do not clear the
-store, start a new order or promise a refund merely to bypass this guard. A
-custom `providerPage` must settle on close/unmount with `{ event: 'dismiss' }`;
-other custom async ports must settle too, or reset can wait indefinitely.
+the original order is retained or the checkout was retired; the result does not
+identify which. Show neutral guidance and check the current session and the
+authoritative order and provider status before choosing recovery.
+`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.
+Do not clear the store, start a new order or promise a refund merely to bypass
+this guard. A custom `providerPage` must settle on close/unmount with
+`{ event: 'dismiss' }`; other custom async ports must settle too, or reset can
+wait indefinitely.
+
+The beta.26 declaration comments for `reset` and `PAID_ORDER_PENDING_MESSAGE`
+say pressing Pay again finishes an unconfirmed order; the `resetWhenSettled`
+comment also omits retired checkouts as a reason for `false`. Those comments do
+not establish that a retry is safe. Use the session and reconciliation guidance
+above.
+
+Stock `Payment` can display an engine message telling the buyer to press Pay
+again when payment is unconfirmed. That wording does not establish that a retry
+is safe. If neutral buyer guidance is required for uncertain outcomes, use a
+custom payment flow with host-controlled error UI, retain the order and reconcile
+the current session and authoritative order/provider status before recovery.
 
 ```tsx
-import { PAID_ORDER_PENDING_MESSAGE, useCheckoutContext } from 'tf-checkout-react-native'
+import { useCheckoutContext } from 'tf-checkout-react-native'
 
 function useStartAgain(setNotice: (message: string) => void) {
   const checkout = useCheckoutContext()
   return async () => {
     if (checkout.status === 'placing') setNotice('Finishing your payment…')
-    if (!(await checkout.resetWhenSettled())) setNotice(PAID_ORDER_PENDING_MESSAGE)
+    const reset = await checkout.resetWhenSettled()
+    setNotice(reset ? 'Choose tickets to start again.' : 'Unable to start over. Check your order or contact support.')
   }
 }
 ```
@@ -643,6 +915,24 @@ A custom confirmer can reject with `paymentProviderError(message, outcome)`:
 three when the provider establishes that no charge occurred. Other rejections
 are treated as unknown. Preserve the original order and reconcile it.
 
+### Host-owned ID verification
+
+`runIdVerification(orderHash, options)` does not open the provider on its own.
+Supply `openUrl` to validate the URL against your provider and scheme policy
+and open it on the device; handle a missing URL or failed opening in your UI.
+The engine swallows asynchronous `openUrl` rejections, so catch and record
+opening failures inside the callback: polling can otherwise continue without a
+handoff. Use `onPhase` for polling state and handle app returns;
+`registerForegroundListener` can trigger a recheck on return and must return an
+unsubscribe function.
+
+Alternatively, `onRequired` receives the order hash and possibly null URL; if
+it returns `true`, the engine resolves `undefined` without opening or polling,
+and your host owns both steps. A timeout or poll error rejects with a message
+promising that payment is safe and tickets will be emailed. Replace that text
+with neutral status and reconcile authoritative payment, verification and
+issuance. Verification alone does not prove settlement or issuance.
+
 ### Stripe card and PaymentSheet
 
 By default, native `Payment` uses Stripe's native `CardInput` for an eligible
@@ -679,7 +969,7 @@ controlled provider must create its `value` with the same `paymentSheet` and
 supported. In headless UI, use `checkout.paymentSheet?.placeOrder()` when
 available; the normal `Payment` section chooses it for the eligible card row.
 
-In beta.24 the sheet is limited to eligible non-MXN Stripe PaymentIntents whose
+In beta.26 the sheet is limited to eligible non-MXN Stripe PaymentIntents whose
 original methods are card alone, or card plus Cash App Pay in USD. It does not
 admit delayed methods, create a new intent or add a Stripe Customer/saved-card
 contract. The SDK checks the original intent's identity, amount and currency
@@ -819,7 +1109,7 @@ example only primes the cart.
 | `holdWaiverSigning(index)`, `setWaiverSignature(index, signature, hold?)` | Bind a signature to its original cart/holder; release the returned hold after saving. |
 | `checkBuyerEmail(email)`, `reloadCheckoutDetails()` | Check for an existing account; retry an unavailable waiver read. |
 | `placeOrder(method?, options?)` | Place/pay via an eligible method; returns `Promise<PlaceOrderResult>`. Options include `autoRunIdVerification`, `idVerification`, `claimCard`. |
-| `runIdVerification(orderHash, options?)` | Open/poll verification as a separate post-order step. |
+| `runIdVerification(orderHash, options?)` | Run verification separately with a host URL opener or takeover; see [host-owned ID verification](#host-owned-id-verification). |
 | `syncCurrency(eventId, code?, options?)` | Seed/change currency; refetch catalog and re-prime as needed. |
 | `applyPromoCode(eventId, promo)`, `attributeReferrer(eventId, referrer)`, `joinWaitingList(eventId, entry)` | Event engagement helpers. |
 | `reset()`, `resetWhenSettled()` | Reset subject to payment safety; use the awaited form to know its outcome. |
@@ -879,7 +1169,7 @@ reads require an appropriately authorized account session; the checkout buyer
 scope does not grant it. Low-level APIs do not replace checkout preflight or
 payment reconciliation.
 
-The [API reference](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.24/docs/API.md)
+The [API reference](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.26/docs/API.md)
 includes the full component and hook catalog.
 
 ## Authentication and account components
@@ -900,7 +1190,7 @@ Additional exports include `TicketChange`, `TicketRefund`, `TicketGift`,
 `Streaming`, `PhoneAuthentication`, `AccountEmailEnrichment`,
 `EventDiscussionView` and post reactions. Their availability depends on the
 deployed backend, authorized account scope and host-owned navigation. See the
-[API reference](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.24/docs/API.md)
+[API reference](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.26/docs/API.md)
 for component variants and required props.
 
 Standalone account components that use query hooks need a `QueryClientProvider`;
@@ -950,16 +1240,44 @@ against the exact new version, backend and devices. The historical
 and [1.0.47 declarations](https://unpkg.com/tf-checkout-react-native@1.0.47/lib/typescript/src/index.d.ts)
 describe the old package; examples there are not 2.x instructions.
 
-| 1.x integration | 2.x beta.24 approach |
+| 1.x integration | 2.x beta.26 approach |
 | --- | --- |
 | `setConfig({ EVENT_ID, ENV, ... })` and event-bound global UI | Restore a secure adapter and call `configureCheckout({ env, clientId, clientSecret: '', storage })`; pass `eventId` to the checkout or section. |
+| `Login` and `ResetPassword` screens | Use `AuthModal` for the built-in sign-in, registration and recovery sheet. Use `ResetPasswordForm` for a token from the host's reset-link route. Adapt callbacks; checkout and full-account sessions have different scopes. |
 | `Tickets` callbacks such as `onAddToCartSuccess` / `onPressMyOrders` | `Tickets` uses `onContinue` / `onSelectSeats`; the host owns orders navigation. Rework the host flow, not just prop names. |
-| 1.x `Checkout`, `CheckoutV2`, `BillingInfo` and older core components | Use `EmbeddedCheckout` or compose the 2.x sections and `CheckoutProvider`. The 1.x `CheckoutV2` name does not mean this 2.x API. |
+| 1.x `Checkout`, `CheckoutSP`, `CheckoutV2`, `BillingInfo` and older core components | Use `EmbeddedCheckout` or compose the 2.x sections and `CheckoutProvider`. These 1.x checkout names are not drop-in 2.x exports; the old `CheckoutSP` README link also lacked a matching section. |
+| `PurchaseConfirmation` | `Confirmation` renders the active checkout result under `CheckoutProvider`, but does not take an order hash to reload a past receipt. Gate any confirmed copy on authoritative status; build a host status page for routed or later visits. |
+| `MyOrders`, `MyOrderDetails` and `ResaleTickets` | These layouts are not exported in this version. Use the supported order/resale hooks and APIs with an authorized account to build the needed list, detail, resale and PDF/navigation flows. `TicketChange`, `TicketGift`, `TicketRefund` and `Passes` are separate ready-made actions, not replacement order-list or resale screens. |
+| `SessionHandleType` component refs and `reloadData()` | Use the relevant query hook's `refetch` and the checkout actions for the current flow. Manage authentication and buyer changes in the host; a ref is not a 2.x session contract. |
 | 1.x `useCheckout()` mutation | Native `useCheckout()` is a stateful engine binding with `setTickets`, setters and `placeOrder`; query hooks are under `hooks`. |
 | Implicit old native storage and session behavior | Supply and restore an OS-protected synchronous adapter. Migrate credentials securely or ask the buyer to sign in again. Checkout-only and account scopes differ. |
 | Per-component style/text props from the old UI | Use theme tokens, available render callbacks and section props; rebuild custom presentation where required. |
 | Existing Stripe setup | Verify current peer/native builds, receiving account, provider URLs, return scheme, wallets and PaymentSheet separately. |
 
+For example, the old ticket screen could call the host after adding to cart:
+
+```text
+// 1.x only: these callback props are not the 2.x contract
+<Tickets onAddToCartSuccess={openBilling} onPressMyOrders={openOrders} />
+```
+
+In 2.x, render this screen inside the same `CheckoutProvider` as the rest of
+your checkout. The host supplies navigation, including its own orders button.
+`onContinue` signals that the ticket cart is ready; it does not return the old
+`onAddToCartSuccess` payload.
+
+```tsx
+import { Tickets } from 'tf-checkout-react-native'
+
+export function TicketSelection({ eventId, openCheckout, openSeats }: {
+  eventId: string
+  openCheckout: () => void
+  openSeats: () => void
+}) {
+  return <Tickets eventId={eventId} onContinue={openCheckout} onSelectSeats={openSeats} />
+}
+```
+
 Rebuild the native binary after replacing native dependencies and pods. The 1.x
 My Orders/order-detail screens, PDF handling and resale screen are not drop-in
 2.x equivalents: build the needed host UI, navigation and PDF handling around
@@ -985,6 +1303,7 @@ and password-protected event flows against the deployed service.
 | --- | --- |
 | `TS2304: Cannot find name 'Crypto'` in SDK declarations | A host without DOM and without a compatible ambient `Crypto` type may report this. Prefer compatible host type definitions. `skipLibCheck` skips declaration-file checks, and unresolved `Crypto` can degrade affected types to `any`, allowing invalid `newBundleIdempotencyKey` arguments. Neither option installs runtime crypto. |
 | Configuration/storage error | Hydrate first, then pass an object with synchronous `getItem`, `setItem`, `removeItem`; check native storage failures. |
+| No tickets appear on first launch | Confirm the public client ID, event ID and environment belong together, and that the event has tickets available to this session. Check the catalog request before changing UI code. |
 | `No QueryClient set` or provider context error | Wrap standalone query hooks in `QueryClientProvider`, and checkout sections in `CheckoutProvider`; check duplicate React Query copies. |
 | Blank chart or missing seat CTA | Confirm event seating support, pass `onSelectSeats`, rebuild WebView, and verify provider/chart/hold contracts. |
 | Missing Apple Pay / Google Pay / Link | Check backend eligibility, real receiving account, device support and host wallet configuration; a simulator or local configuration alone may not qualify. |

package/docs/API.md

@@ -1,10 +1,10 @@
 # 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)
+`tf-checkout-react-native@2.0.0-beta.26`. Read it alongside the
+[package README](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.26/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)
+limitations. The [published declarations](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.26/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,
@@ -15,7 +15,24 @@ 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
+## Find a ready-made screen
+
+For a working starting point, follow the README's
+[complete checkout](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.26/README.md#embed-a-checkout),
+[authentication sheet](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.26/README.md#a-reusable-authentication-sheet),
+[ticket management](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.26/README.md#ticket-management-screens),
+or [composed checkout](https://unpkg.com/tf-checkout-react-native@2.0.0-beta.26/README.md#compose-sections-and-navigation)
+examples. The lists below cover their props and the other exported screens.
+
+`EmbeddedCheckout` supplies its own checkout/query provider. Standalone
+checkout sections need a shared `CheckoutProvider`; account and post-purchase
+screens that use queries need a `QueryClientProvider` and the appropriate
+buyer authority. A component's presence does not mean the event or backend has
+enabled that feature. The old native `MyOrders`, `MyOrderDetails`,
+`ResaleTickets`, `CheckoutSP` and `CheckoutV2` layouts are not exports here;
+see the README's migration table for alternatives and gaps.
+
+**TypeScript troubleshooting:** beta.26 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
@@ -25,6 +42,7 @@ compile. Neither a type declaration nor `skipLibCheck` installs runtime crypto.
 
 ## Contents
 
+- [Find a ready-made screen](#find-a-ready-made-screen)
 - [Checkout components](#checkout-components)
 - [Account and post-purchase components](#account-and-post-purchase-components)
 - [Authentication forms](#authentication-forms)
@@ -50,7 +68,9 @@ 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
+must arrange it. Provide `onComplete` in redirect mode to navigate; without it
+the checkout remains mounted and no host status screen is reached. Preserve
+`orderHash` and any `pendingVoucherUrl` for the
 order-status journey, including navigation/restart.
 
 `CheckoutProvider` takes required `children`, plus `value?: NativeUseCheckout`,
@@ -127,7 +147,7 @@ rendered. Without `onContinue` it mirrors edits into the combined form. A
 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
+In beta.26 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
@@ -138,19 +158,34 @@ 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.
+`unavailableDetails`. Before money may have moved, placement retries an unavailable
+waiver and blocks if it remains unknown; a retained order with a possible payment
+follows separate recovery and needs reconciliation. 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`,
+it does not run automatically on mount. Its verified message says tickets are
+on their way without checking settlement or issuance. Use a host-owned neutral
+verification/status UI around `runIdVerification(orderHash, options)` when that copy is
+premature, and reconcile authoritative order/provider status. If `onComplete`
+navigates away or unmounts the checkout, its inline verification view will not
+appear; keep the provider mounted for inline verification or handle it at the
+destination. To run custom verification, supply `openUrl` to validate and open
+the provider URL on the device; handle a missing URL or a failed opening. The
+engine swallows asynchronous `openUrl` rejections, so catch and record failures
+in that callback while showing neutral status. Handle `onPhase` and app returns;
+`registerForegroundListener` can recheck on return and returns an unsubscribe
+function. Alternatively, return `true` from `onRequired` to take over: the
+engine resolves `undefined` and neither opens nor polls. A timeout or poll error
+rejects with copy promising payment is safe and tickets will be emailed; replace
+it with neutral status and reconcile authoritative payment, verification and
+issuance. Verification alone proves neither settlement nor issuance.
+`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
@@ -297,7 +332,7 @@ SDK primitive styles; `resolveTheme(partial)` resolves the light/dark tokens.
 
 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
+beta.26; 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
@@ -434,6 +469,10 @@ 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:
 
+`ttf.events.requiredCustomFieldLabels(eventId)` returns `[]` if its lookup
+fails as well as when no matching required order/ticket labels exist. An empty
+result is not proof that the event has no required custom fields.
+
 | Domain | Methods |
 | --- | --- |
 | `ttf.events` | `featured`, `details`, `tickets`, `ticketsWithMeta`, `bundles`, `startBundlePurchase`, `info`, `conditions`, `timeSlotTickets`, `customFields`, `requiredCustomFieldLabels`, `addons`, `filterAddonsForTickets`, `submitPromoCode`, `setCurrency`, `authenticate`, `track`, `updateOrderDataCapture`, `updateTicketDataCapture` |
@@ -514,6 +553,10 @@ reset()                                    // void
 resetWhenSettled()                         // Promise<boolean>
 ```
 
+`runIdVerification` requires the host URL opener or takeover and neutral error
+handling described in the `IDVerification` section above; calling it without
+an opener does not open the provider.
+
 `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
@@ -521,9 +564,18 @@ review the README's payment section before constructing a custom selector. The
 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.
+order. `resetWhenSettled` returns false for a retained or retired checkout; check
+the current session and reconcile the order and provider status before recovery.
+The beta.26 declaration comments for `reset` and `PAID_ORDER_PENDING_MESSAGE`
+say pressing Pay again finishes an unconfirmed order; the `resetWhenSettled`
+comment omits retired checkouts as a reason for `false`. Those comments do not
+establish that a retry is safe. A provider page, picker or other custom port must
+settle on all close/cancel/unmount paths.
+
+Stock `Payment` can display an engine message telling the buyer to press Pay
+again when payment is unconfirmed. That wording does not prove a retry is safe.
+If neutral guidance is required, use a custom payment flow with host-controlled
+error UI, retain the order and reconcile before recovery.
 
 For zero-total orders, this SDK ignores the free-registration response body and
 reports `needIdVerification: false`. Verification or approval may still be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tf-checkout-react-native",
-  "version": "2.0.0-beta.24",
+  "version": "2.0.0-beta.26",
   "description": "TheTicketFairy ReactNative Checkout library",
   "homepage": "https://github.com/theticketfairy/tf-shared-libraries#readme",
   "author": "The Ticket Fairy",