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

package/README.md

@@ -7,23 +7,34 @@ receipt — or compose the sections yourself.
 Same API as [`tf-checkout-react`](../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`](https://github.com/theticketfairy/tf-shared-libraries).
+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.
+
 ```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 +46,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 +73,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()
 
@@ -92,7 +103,7 @@ Pass `cookieAuth: false` to opt into the bearer chain.
 ### 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,9 +201,71 @@ 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).
 
+## 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.
+
 ## Known gaps vs web
 
 - **Seat maps** — the seat-picker view is a placeholder until the native picker
@@ -227,3 +300,14 @@ nothing of the sort.
 ---
 
 Part of the [TicketFairy checkout monorepo](../../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](
+../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.