tf-checkout-react 2.0.0-beta.25 → 2.0.0-beta.27

package/docs/API.md

@@ -1,12 +1,16 @@
 # React checkout API reference
 
 This reference describes the public surface of `tf-checkout-react` version
-`2.0.0-beta.25`. It supplements the package's npm README with examples and an
+`2.0.0-beta.27`. It supplements the package's npm README with examples and an
 inventory of the shared facade and hooks. The package's installed
 `dist/index.d.ts` is the exact versioned source for complete signatures and
 DTO fields. A named export or a typed payment method does not establish that
 the matching backend feature, account permission or payment provider is enabled.
 
+For installation, a complete quick start, and examples of the ready-made,
+single-page and step-by-step layouts, start with the [checkout guide](https://unpkg.com/tf-checkout-react@2.0.0-beta.27/docs/GUIDE.html#choose-a-checkout-layout).
+This file is the detailed component, engine and API reference.
+
 All examples assume `configureCheckout` has run, and React Query examples are
 under a host `QueryClientProvider`. Use a registered public SDK client ID and
 an empty `clientSecret` in a browser. Never ship a confidential client secret.
@@ -61,8 +65,11 @@ appropriate authorized logout flow where a backend session must also end.
 
 `Tickets` and `SeatMap` report when a cart is ready; the host owns navigation
 when composing individual sections. This skeleton connects seated selection to
-its view. It is not a standalone app: configure and mount it under
-`QueryClientProvider`.
+its view. This wiring recipe is not a standalone app: configure and mount it
+under `QueryClientProvider`. Its seat Back changes views only; it does not itself
+release held seats or cancel an in-flight reservation or cart priming. Before
+allowing a conflicting selection, coordinate that work and hold expiry or
+release under your deployed backend contract.
 
 ```tsx
 import { useState } from 'react'
@@ -75,15 +82,18 @@ export function CheckoutLayout({ eventId }: { eventId: string }) {
   const [notice, setNotice] = useState('')
   return (
     <CheckoutProvider>
-      {view === 'tickets' && (
+      <div hidden={view !== 'tickets'}>
         <Tickets
           eventId={eventId}
           onSelectSeats={() => setView('seats')}
           onContinue={() => setView('checkout')}
         />
-      )}
+      </div>
       {view === 'seats' && (
-        <SeatMap eventId={eventId} onContinue={() => setView('checkout')} />
+        <>
+          <button type="button" onClick={() => setView('tickets')}>Back to tickets</button>
+          <SeatMap eventId={eventId} onContinue={() => setView('checkout')} />
+        </>
       )}
       {view === 'checkout' && (
         <>
@@ -101,10 +111,11 @@ export function CheckoutLayout({ eventId }: { eventId: string }) {
 }
 ```
 
-Real navigation must also handle expiry, payment in flight, retained orders and
-buyer/session changes. Do not unconditionally discard or replace a cart on
-Back during a payment. Use the embedded flow when its navigation fits; when
-building your own, preserve validation and server reservation behavior. The
+Real navigation must also implement checkout Edit/Back, preserve entered
+details, and handle expiry, payment in flight, retained orders and buyer/session
+changes. Do not unconditionally discard or replace a cart on Back during a
+payment. Use `EmbeddedCheckout` for its built-in Back and guarded Edit behavior;
+when building your own, preserve validation and server reservation behavior. The
 host can use `useCheckoutContext()` inside the provider to read the shared
 checkout and `useCheckoutValidation()` to coordinate section validation.
 
@@ -231,8 +242,18 @@ validate on the deployed server too. In this beta the backend owns conditional
 requiredness and hosted-checkout conditional visibility is not fully reproduced.
 Test the actual event's branches before release.
 
+During priming, failed custom-field, checkout-config, add-on or event-condition
+reads fall back to empty/default data and are not recorded in `unavailableDetails`.
+The engine and stock UI cannot gate requirements they did not load. Do not treat
+an empty list as proof that no requirement exists; verify failure behavior and
+implement tested host safeguards for mandatory fields and acknowledgments. Server
+answer validation is not proof that a condition was acknowledged.
+
 If `unavailableDetails` includes `'waiver'`, the read failed without establishing
-whether a waiver exists. `reloadCheckoutDetails()` retries it. For a custom
+whether a waiver exists. Before money may have moved, placement retries that
+read and blocks if it remains unknown; `reloadCheckoutDetails()` also retries it.
+A retained order with a possible payment follows separate recovery and needs
+reconciliation. For a custom
 waiver UI, `holdWaiverSigning(index)` returns a hold or `null`; complete or
 cancel the upload, attach via `setWaiverSignature(index, signature, hold)` only
 while the binding remains current, and release the hold. The standard
@@ -258,7 +279,34 @@ If status is unavailable, contact support. Do not retry payment for a free order
 `OrderConfirmation` does not check payment status before rendering its default
 confirmed/ticket-availability copy. Gate it on authoritative appropriate status;
 when the result is pending, show pending UI and any voucher instead. The
-in-flow `Confirmation` component reads the current result's pending state.
+in-flow `Confirmation` component reads the current result's pending state but
+shows confirmed copy when `pending` is absent or false, even for paid orders
+whose final settlement has not been independently verified. Use a host-owned
+status route with `confirmationMode="redirect"` or a custom composed
+confirmation gated on authoritative order and provider status. Redirect omits
+inline ID verification; arrange it when `needIdVerification` is true.
+For `EmbeddedCheckout` in redirect mode, provide `onComplete` to route the
+result. `ResumedCheckout` defaults to redirect and likewise needs that callback;
+otherwise its successful flow remains in the loading transition. Inline mode
+has the confirmation and verification-copy limitations described here.
+The stock `IDVerification` and routed `OrderIDVerification` verified messages
+say tickets are on their way but do not verify settlement or issuance. Use a
+host-owned neutral verification and status UI when appropriate. If `onComplete`
+navigates away or unmounts the checkout, inline verification will not appear;
+keep the provider mounted or handle verification at the destination.
+
+For custom verification, `runIdVerification(orderHash, options)` does not
+open a URL by itself. Supply `openUrl`, validate the provider URL and open it
+in the browser; handle a missing URL or blocked/failed opening. The engine
+swallows asynchronous `openUrl` rejections, so catch and record failures in
+that callback while showing neutral status. Handle `onPhase` and browser
+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.
 
 For a custom Stripe card step, the following demonstrates the boundary between
 host-collected data and SDK placement. Render it only after reserving a cart and
@@ -350,6 +398,15 @@ no-charge outcomes as `declined`, `cancelled` or `notStarted`, with `unknown`
 for uncertainty. `UNSUPPORTED_GATEWAY` indicates the necessary platform
 capability is not available, not that every provider failure is safe to retry.
 
+The beta.27 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; check the current session and reconcile first.
+Stock `Payment` can also 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.
+
 ## Auth component contracts
 
 `AuthModal` owns a complete modal flow. Supply `open`, `onClose` and, for
@@ -464,6 +521,10 @@ preflight, state and payment coordination. Raw functions are also exported in
 the `api` namespace. Calling a low-level endpoint directly does not grant a
 buyer permission or guarantee a safe payment retry.
 
+`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.
+
 | Namespace | Methods |
 | --- | --- |
 | `ttf.events` | `featured`, `details`, `tickets`, `ticketsWithMeta`, `bundles`, `startBundlePurchase`, `info`, `conditions`, `timeSlotTickets`, `customFields`, `requiredCustomFieldLabels`, `addons`, `filterAddonsForTickets`, `submitPromoCode`, `setCurrency`, `authenticate`, `track`, `updateOrderDataCapture`, `updateTicketDataCapture`. |