tf-checkout-react-native 2.0.0-beta.0 → 2.0.0-beta.11

package/README.md

@@ -4,26 +4,40 @@ The TicketFairy checkout for React Native. Drop in one component and you have
 ticket selection, add-ons, buyer details, payment, ID verification, and the
 receipt — or compose the sections yourself.
 
-Same API as [`tf-checkout-react`](../tf-checkout-react/README.md); the flow,
+Same API as [`tf-checkout-react`](https://github.com/theticketfairy/tf-shared-libraries/blob/main/packages/tf-checkout-react/README.md); the flow,
 validation, and gating rules are literally the same code.
 
+The 2.x source is maintained in [`tf-shared-libraries/packages/tf-checkout-react-native`](https://github.com/theticketfairy/tf-shared-libraries/tree/main/packages/tf-checkout-react-native).
+The core is private and bundled into both platform packages. Use React 18+ and
+React Query 5 on web; the native requirements below reflect its supported build.
+Never put a confidential OAuth client secret in browser or mobile code. Public
+checkout integrations use registered SDK client IDs and owned buyer sessions.
+
 ## Install
 
+The 2.0 line is currently a prerelease. Install `@beta` explicitly; the unqualified
+npm package still resolves to stable 1.x until the 2.0 release gates pass. Pin the
+verified exact version in a production app. The current matching pair is
+`2.0.0-beta.9`; see its [registry acceptance record](https://github.com/theticketfairy/tf-shared-libraries/blob/main/docs/releases/2.0.0-beta.9.registry.json).
+The [app integration contract](https://github.com/theticketfairy/tf-shared-libraries/blob/main/docs/integration/app-sdk.md)
+records the shared APIs and remaining deployment/provider acceptance gates.
+
 ```bash
-npx expo install tf-checkout-react-native \
+npx expo install tf-checkout-react-native@beta \
   @tanstack/react-query \
   @stripe/stripe-react-native \
-  react-native-mmkv \
-  @react-native-clipboard/clipboard
+  react-native-mmkv@3 \
+  @react-native-clipboard/clipboard \
+  react-native-webview
 ```
 
 Bare React Native:
 
 ```bash
-npm install tf-checkout-react-native @tanstack/react-query @stripe/stripe-react-native react-native-mmkv @react-native-clipboard/clipboard
+npm install tf-checkout-react-native@beta @tanstack/react-query @stripe/stripe-react-native react-native-mmkv@3 @react-native-clipboard/clipboard react-native-webview
 ```
 
-Those four are **peer dependencies** on purpose. React contexts and native
+These are **peer dependencies** on purpose. React contexts and native
 modules must exist exactly once in an app — a second copy of react-query means
 your `<QueryClientProvider>` is invisible to our hooks, and a second Stripe
 means a duplicate pod. As peers there is one copy and no Metro aliasing is ever
@@ -35,7 +49,7 @@ Everything else — the SDK core, the flow, the UI — ships inside the package.
 
 - React Native `0.81+` with the New Architecture enabled (required by
   `react-native-mmkv` 3.x)
-- React `19.1+`, Node `20.18.3+`
+- React `19.1+`, Node `20.19.4+`
 - iOS 15.1+ · Android API 24+ (Stripe SDK minimums)
 - A development build. **Expo Go will not work** — this package uses native
   modules.
@@ -62,7 +76,7 @@ npx expo run:ios
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { configureCheckout, EmbeddedCheckout } from 'tf-checkout-react-native'
 
-configureCheckout({ env: 'PROD', clientId: '…', clientSecret: '…' })
+configureCheckout({ env: 'PROD', clientId: 'PUBLIC_SDK_CLIENT_ID', clientSecret: '', cookieAuth: true })
 
 const queryClient = new QueryClient()
 
@@ -75,24 +89,23 @@ export default function App() {
 }
 ```
 
-`configureCheckout` runs once at app start. It persists tokens to MMKV, so a
-signed-in buyer survives a relaunch.
-
-### Why native defaults to cookie auth
+`configureCheckout` runs once at app start and defaults SDK-owned storage to
+MMKV. Storage survives a relaunch; the backend still validates the restored
+session.
 
-`configureCheckout` turns on `cookieAuth` by default. This is not cosmetic: the
-cart lives in the backend session, and a bearer request without a guest header
-gets moved onto a synthetic empty session — so a buyer who reserves tickets and
-then signs in mid-checkout would lose the cart to "The cart is expired". On the
-cookie flow no bearer is minted, the session holding the cart stays put, and the
-rotating `X-TF-ECOMMERCE` ticket is persisted to MMKV.
+### Checkout sessions and account scope
 
-Pass `cookieAuth: false` to opt into the bearer chain.
+The native wrapper defaults `cookieAuth` to true and disables ambient native
+cookie handling. Owned credentials use the SDK's header-backed session storage.
+Public checkout sign-in preserves the event-bound guest carrier and keeps its
+buyer credential server-side; it does not return a full-account ticket or grant
+private account access. First-party full-account flows explicitly use
+`accountAuth: true`; see the shared identity contract below.
 
 ### Environments
 
 ```ts
-configureCheckout({ env: 'STAG', clientId, clientSecret })
+configureCheckout({ env: 'STAG', clientId: 'PUBLIC_SDK_CLIENT_ID', clientSecret: '', cookieAuth: true })
 ```
 
 `PROD` → `www.ticketfairy.com`, `STAG` → `test.ticketfairy.com`, `DEV` →
@@ -190,13 +203,81 @@ const order = await checkout.placeOrder('card')
 `placeOrder` is retry-safe: one order, one charge, however many times the button
 is pressed.
 
+### Starting a new checkout
+
+`reset()` discards the cart. It returns nothing, so
+`useEffect(() => checkout.reset(), [eventId])` works as it always has. Before
+any money moves it resets at once. While a payment is going through, it waits
+for the payment to finish, so the payment never lands in a new cart. An order
+that is not confirmed yet is kept when it is charged, or when a payment step
+failed without an answer that nothing was charged (a network error, a
+timeout, or a Stripe error that is not a decline or a cancel). A Razorpay or
+redirect payment page the buyer closes is kept only when a check of the order
+fails or finds a payment; otherwise it is a cancel. Pressing Pay again then
+finishes the order, or pays as usual when nothing was paid. A server refusal
+of the order, such as an expired reservation, releases it.
+
+To know which happened, await `resetWhenSettled()` instead. It resolves `true`
+once the checkout is reset, or `false` when it kept the order. In that case,
+show the buyer `PAID_ORDER_PENDING_MESSAGE`. While it waits for a payment
+(`status === 'placing'`), tell the buyer, for example "Finishing your
+payment…":
+
+```tsx
+if (checkout.status === 'placing') setNotice('Finishing your payment…')
+if (!(await checkout.resetWhenSettled())) setNotice(PAID_ORDER_PENDING_MESSAGE)
+```
+
+A custom `providerPage` must resolve `'dismiss'` when it closes or unmounts, and
+any other custom port must settle then too, or `resetWhenSettled()` waits for it.
+
+A custom confirmer marks a decline or cancel by rejecting with
+`paymentProviderError(message, 'declined' | 'cancelled')`. Any other rejection
+counts as a payment that may have gone through, so the order is kept.
+
 The full SDK is re-exported from this package — `ttf`, `api`, `hooks`, `dtos`,
-`logic`, and the engine. See the [SDK reference](../tf-checkout-shared/README.md).
+`logic`, and the engine. See the [SDK reference](https://github.com/theticketfairy/tf-shared-libraries/blob/main/packages/tf-checkout-shared/README.md).
+
+## Rewards
+
+The native analogue of the web Rewards section: standing, the referral tree,
+the prize ladder, packs, the share card, and one share button.
+
+```tsx
+import { Confirmation, Rewards } from 'tf-checkout-react-native'
+;<Confirmation>
+  <Rewards orderHash={orderHash} />
+</Confirmation>
+```
+
+When `<EmbeddedCheckout/>` renders the receipt itself, pass the block through
+`confirmationChildren`:
+
+```tsx
+<EmbeddedCheckout eventId={eventId} confirmationChildren={<MyRewards />} />
+```
+
+Native adaptations, and why:
+
+- **No SVG.** The tree is positioned `View`s, from the same shared layout the
+  web SVG uses. Adding `react-native-svg` would be a new native peer for every
+  customer app; a dot-and-line picture does not need one.
+- **One share button.** Per-channel buttons collapse into `Share.share()` — the
+  OS sheet already lists every installed app, which is what the web's share
+  sheet channel reaches for through the browser.
+- **Copy comes in as props**, this package's idiom. `translate`, or `locale` and
+  `messages` for the built-in `rewards.*` catalogue.
+
+## Seat maps
+
+`SeatMap` uses the existing WebView peer to render internal charts or the event's
+Seats.io chart, with the shared core owning selection, holds and reservations.
+It requires the matching backend seating/session contracts. Provider-backed hold
+and deployed-cart acceptance remain separate checks; see the
+[seating contract and evidence](https://github.com/theticketfairy/tf-shared-libraries/blob/main/docs/integration/app-sdk.md#seat-chart-and-ticket-refund-checkpoint--25-october-2026).
 
 ## Known gaps vs web
 
-- **Seat maps** — the seat-picker view is a placeholder until the native picker
-  (WebView + seats.io) lands. Non-seated events are unaffected.
 - **Smooth scroll** — no `scrollIntoView` equivalent, so `autoScroll` has no
   native counterpart.
 
@@ -226,4 +307,14 @@ nothing of the sort.
 
 ---
 
-Part of the [TicketFairy checkout monorepo](../../README.md).
+Part of the [TicketFairy checkout monorepo](https://github.com/theticketfairy/tf-shared-libraries/blob/main/README.md).
+
+
+Public checkout sign-in uses event-scoped server-only buyer binding, without a bundled
+client secret. The checkout's auth modal supplies the event automatically; standalone
+`AuthModal` callers pass `checkoutEventId` and can receive the narrow
+`onCheckoutAuthenticated(CheckoutBuyerProfile)` callback. Password/signup/email/phone
+proofs still complete required two-factor verification. These credentials cannot read
+private account preferences or tickets. See the [shared identity contract](https://github.com/theticketfairy/tf-shared-libraries/blob/main/packages/tf-checkout-shared/README.md) for
+scope, retry, logout and configuration ownership. Existing confidential OAuth clients
+are trusted-server integrations; never distribute their secrets in browser/native code.