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

package/README.md

@@ -7,22 +7,22 @@ components, plus the shared API and React Query hooks. Which paths a buyer can
 actually use depend on the event, the deployed API, the buyer's session and the
 payment provider.
 
-This reference describes **2.0.0-beta.27**. It is a prerelease with a different
+This reference describes **2.0.0-beta.28**. It is a prerelease with a different
 API from 1.x. Pin the version while evaluating it. npm's `latest` and `beta`
 tags can move independently and an unqualified install may select 1.x:
 
 ```bash
 npm view tf-checkout-react dist-tags
-npm install tf-checkout-react@2.0.0-beta.27 @tanstack/react-query react react-dom
+npm install tf-checkout-react@2.0.0-beta.28 @tanstack/react-query react react-dom
 ```
 
-The [API reference](https://unpkg.com/tf-checkout-react@2.0.0-beta.27/docs/API.html)
+The [API reference](https://unpkg.com/tf-checkout-react@2.0.0-beta.28/docs/API.html)
 is included as `docs/API.md` and `docs/API.html` in this package. A
-[standalone guide](https://unpkg.com/tf-checkout-react@2.0.0-beta.27/docs/GUIDE.html)
+[standalone guide](https://unpkg.com/tf-checkout-react@2.0.0-beta.28/docs/GUIDE.html)
 is also available.
 
 If the HTML has not reached the CDN yet, open the packaged `docs/API.md` in a
-Markdown viewer or read the [plain-text API Markdown](https://cdn.jsdelivr.net/npm/tf-checkout-react@2.0.0-beta.27/docs/API.md).
+Markdown viewer or read the [plain-text API Markdown](https://cdn.jsdelivr.net/npm/tf-checkout-react@2.0.0-beta.28/docs/API.md).
 The full guide is also shown on this npm page.
 
 ## Choose a checkout layout
@@ -41,6 +41,26 @@ version. The 1.x `*Container` components and named single-page/accordion
 examples are not drop-in 2.x exports. The [migration guide](#migrating-from-1x)
 shows how to reproduce those layouts with the current components.
 
+### Coming from a 1.x layout?
+
+The 1.x guide showed ways to arrange individual containers; those examples were
+not named, ready-made 2.x components. Choose the closest 2.x starting point:
+
+| 1.x integration | What to use in beta.28 | What your application owns |
+| --- | --- | --- |
+| Separate ticket, billing, payment and confirmation pages | [Step-by-step composition](#step-by-step-checkout) | Routes or step visibility, Back/Edit, and preserving one active checkout provider. |
+| A single page using the container components | [`EmbeddedCheckout`](#embeddedcheckout) for the stock flow, or [single-page composition](#single-page-checkout) to arrange the sections yourself | With composition, the page layout and navigation; with either approach, order-status reconciliation. |
+| The progressive enhancement example | [Step-by-step composition](#step-by-step-checkout) | The visible steps and the rules for moving between them. |
+| The accordion/collapsible example | [Accordion composition](#accordion-checkout) | Disclosure behavior and checkout navigation. |
+| A flow that already reserved a cart | [`ResumedCheckout`](#resume-a-server-cart) | Creating the cart in the same session and the order-status handoff. |
+
+The composition examples are starting points, not complete replacements for a
+multi-route checkout. In particular, implement Back/Edit, cart expiry and
+payment recovery before production. See [Compose sections](#compose-sections)
+for the full responsibilities. The 1.x props and callback payloads do not map
+automatically; [Migrating layout callbacks](#migrating-layout-callbacks) gives
+specific examples.
+
 [Requirements](#requirements) · [Quick start](#quick-start) ·
 [Configure sessions](#configuration-and-sessions) · [Ready-made checkout](#embeddedcheckout) ·
 [Custom layouts](#compose-sections) · [Payments](#payments) ·
@@ -683,7 +703,7 @@ error or closed provider page means the charge failed. A custom provider page mu
 settle with `{ event: 'dismiss' }` on close/unmount, and other custom payment
 ports must settle, or a waiting reset cannot finish.
 
-The beta.27 declaration comments for `reset` and `PAID_ORDER_PENDING_MESSAGE`
+The beta.28 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
@@ -740,7 +760,7 @@ holder's answers in `ticketDataCapture`, and add-on answers via
 the opaque catalog ID. Use backend country/state IDs for `countryId` and
 `stateId`; `countryCode` / `stateCode` are payment billing codes.
 
-In beta.27 conditional custom-field requiredness is left to the backend and
+In beta.28 conditional custom-field requiredness is left to the backend and
 not all hosted-checkout conditional visibility is reproduced. Verify the
 actual event against the deployed checkout, including blanks, images, holder
 scoping and validation errors; do not claim parity from the presence of a
@@ -761,7 +781,7 @@ unknown; `reloadCheckoutDetails()` can also retry the waiver read. A retained
 order with a possible payment follows separate recovery and needs reconciliation.
 `WaiverSigning` handles the SDK's signing flow.
 
-**Consent limitation in beta.27:** when `privacyPolicy` is supplied, the
+**Consent limitation in beta.28:** when `privacyPolicy` is supplied, the
 stock `BillingInfo` replaces the Ticket Fairy marketing checkbox with the
 required privacy checkbox, but both use `consent.ttfOptIn`; the order sends
 that value as `ttf_opt_in`. The privacy acknowledgement and Ticket Fairy
@@ -1014,6 +1034,52 @@ a full account user. Supply a host sign-in/route callback where applicable.
 | `PostReaction` | `postId: string \| number`, `onSignIn?`. `PostReactionControls` accepts `flow` and `onSignIn?`. |
 | `DiscoveryTravel` | `searchCities`, `searchEvents`, `storage?`, `locale?`. Host supplies search functions; see `DiscoveryTravelProps` for their signatures. |
 
+#### Example: ready-made account screens
+
+The following setup is for an authorized **first-party** full-account
+integration with the corresponding deployed account routes. In that host's initial
+[SDK configuration](#configuration-and-sessions), set `accountAuth: true` and
+`cookieAuth: true`, then complete the approved full-account sign-in and any
+required proof challenges before mounting them. The checkout-only quick start
+uses a sign-in path scoped to the event, which is not sufficient. Add the options
+to the one-time setup; do not reconfigure from this screen.
+
+The flags do not grant account access or enable backend routes. Third-party
+integrations need an explicitly approved, supported account journey; contact
+Ticket Fairy to find out whether one is available. The example assumes the
+existing `QueryClientProvider` is mounted and the backend supports these screens.
+The host supplies navigation callbacks. `ProfileSettings` and
+`NotificationPreferences` receive `signIn`; `AccountRewardsSection` has no
+sign-in callback and only displays a message while signed out. The host must
+detect session expiry and offer sign-in separately for rewards.
+
+```tsx
+import {
+  AccountRewardsSection, NotificationPreferences, ProfileSettings,
+} from 'tf-checkout-react'
+
+export function AccountScreen({ screen, goBack, signIn, browseEvents, viewTickets }: {
+  screen: 'visibility' | 'notifications' | 'rewards'
+  goBack: () => void
+  signIn: () => void
+  browseEvents: () => void
+  viewTickets: () => void
+}) {
+  if (screen === 'visibility') return (
+    <ProfileSettings mode="visibility" onBack={goBack} onSignIn={signIn} />
+  )
+  if (screen === 'notifications') return (
+    <NotificationPreferences onBack={goBack} onSignIn={signIn} />
+  )
+  return <AccountRewardsSection onBrowseEvents={browseEvents} onViewTickets={viewTickets} />
+}
+```
+
+Use `mode="links"` for profile links. These components do not replace an orders
+list or establish account authorization. Scope or clear account queries when the
+buyer signs out or changes, and handle loading, sign-in and navigation in the
+host as needed.
+
 For account orders and ticket lists use `hooks.useOrders`, `hooks.useOrder`,
 `ttf.orders.list`, `ttf.orders.get` or `ttf.orders.myTickets`. In this version
 `ttf.orders.get` / `useOrder` take a **numeric order ID string**, not a public
@@ -1248,7 +1314,7 @@ existing 1.x integration pinned until the new flow and backend are verified.
 There is no automatic translation of old URLs, component props, account
 sessions or persisted 1.x state.
 
-| 1.x integration | 2.0.0-beta.27 approach |
+| 1.x integration | 2.0.0-beta.28 approach |
 | --- | --- |
 | `setConfigs({ BASE_URL, ... })` | `configureCheckout({ env` or `baseUrl`, `clientId`, `clientSecret: ''`, ... `})`; public client registration and session setup are required. |
 | `TicketsContainer`, `SeatMapContainer`, `AddOnsContainer` | `EmbeddedCheckout` or `Tickets`, `SeatMap`, `AddOns` under `CheckoutProvider`. Adapt callbacks and navigation. |

package/docs/API.html

@@ -30,7 +30,7 @@
   <main id="main">
 <h1 id="react-checkout-api-reference">React checkout API reference</h1>
 <p>This reference describes the public surface of
-<code>tf-checkout-react</code> version <code>2.0.0-beta.27</code>. It
+<code>tf-checkout-react</code> version <code>2.0.0-beta.28</code>. It
 supplements the package's npm README with examples and an inventory of
 the shared facade and hooks. The package's installed
 <code>dist/index.d.ts</code> is the exact versioned source for complete
@@ -39,7 +39,7 @@ not establish that the matching backend feature, account permission or
 payment provider is enabled.</p>
 <p>For installation, a complete quick start, and examples of the
 ready-made, single-page and step-by-step layouts, start with the <a
-href="https://unpkg.com/tf-checkout-react@2.0.0-beta.27/docs/GUIDE.html#choose-a-checkout-layout">checkout
+href="https://unpkg.com/tf-checkout-react@2.0.0-beta.28/docs/GUIDE.html#choose-a-checkout-layout">checkout
 guide</a>. This file is the detailed component, engine and API
 reference.</p>
 <p>All examples assume <code>configureCheckout</code> has run, and React
@@ -450,7 +450,7 @@ confirmer errors should classify only proven no-charge outcomes as
 <code>UNSUPPORTED_GATEWAY</code> indicates the necessary platform
 capability is not available, not that every provider failure is safe to
 retry.</p>
-<p>The beta.27 declaration comments for <code>reset</code> and
+<p>The beta.28 declaration comments for <code>reset</code> and
 <code>PAID_ORDER_PENDING_MESSAGE</code> say pressing Pay again finishes
 an unconfirmed order; the <code>resetWhenSettled</code> comment omits
 retired checkouts as a reason for <code>false</code>. Those comments do

package/docs/API.md

@@ -1,14 +1,14 @@
 # React checkout API reference
 
 This reference describes the public surface of `tf-checkout-react` version
-`2.0.0-beta.27`. It supplements the package's npm README with examples and an
+`2.0.0-beta.28`. 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).
+single-page and step-by-step layouts, start with the [checkout guide](https://unpkg.com/tf-checkout-react@2.0.0-beta.28/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
@@ -398,7 +398,7 @@ 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`
+The beta.28 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.

package/docs/GUIDE.html

@@ -36,21 +36,21 @@ rewards, ticket-management and account components, plus the shared API
 and React Query hooks. Which paths a buyer can actually use depend on
 the event, the deployed API, the buyer's session and the payment
 provider.</p>
-<p>This reference describes <strong>2.0.0-beta.27</strong>. It is a
+<p>This reference describes <strong>2.0.0-beta.28</strong>. It is a
 prerelease with a different API from 1.x. Pin the version while
 evaluating it. npm's <code>latest</code> and <code>beta</code> tags can
 move independently and an unqualified install may select 1.x:</p>
 <pre class="bash"><code>npm view tf-checkout-react dist-tags
-npm install tf-checkout-react@2.0.0-beta.27 @tanstack/react-query react react-dom</code></pre>
+npm install tf-checkout-react@2.0.0-beta.28 @tanstack/react-query react react-dom</code></pre>
 <p>The <a
-href="https://unpkg.com/tf-checkout-react@2.0.0-beta.27/docs/API.html">API
+href="https://unpkg.com/tf-checkout-react@2.0.0-beta.28/docs/API.html">API
 reference</a> is included as <code>docs/API.md</code> and
 <code>docs/API.html</code> in this package. A <a
-href="https://unpkg.com/tf-checkout-react@2.0.0-beta.27/docs/GUIDE.html">standalone
+href="https://unpkg.com/tf-checkout-react@2.0.0-beta.28/docs/GUIDE.html">standalone
 guide</a> is also available.</p>
 <p>If the HTML has not reached the CDN yet, open the packaged
 <code>docs/API.md</code> in a Markdown viewer or read the <a
-href="https://cdn.jsdelivr.net/npm/tf-checkout-react@2.0.0-beta.27/docs/API.md">plain-text
+href="https://cdn.jsdelivr.net/npm/tf-checkout-react@2.0.0-beta.28/docs/API.md">plain-text
 API Markdown</a>. The full guide is also shown on this npm page.</p>
 <h2 id="choose-a-checkout-layout">Choose a checkout layout</h2>
 <table>
@@ -106,6 +106,59 @@ the ready-made flows in this version. The 1.x <code>*Container</code>
 components and named single-page/accordion examples are not drop-in 2.x
 exports. The <a href="#migrating-from-1x">migration guide</a> shows how
 to reproduce those layouts with the current components.</p>
+<h3 id="coming-from-a-1x-layout">Coming from a 1.x layout?</h3>
+<p>The 1.x guide showed ways to arrange individual containers; those
+examples were not named, ready-made 2.x components. Choose the closest
+2.x starting point:</p>
+<table>
+<thead>
+<tr>
+<th>1.x integration</th>
+<th>What to use in beta.28</th>
+<th>What your application owns</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Separate ticket, billing, payment and confirmation pages</td>
+<td><a href="#step-by-step-checkout">Step-by-step composition</a></td>
+<td>Routes or step visibility, Back/Edit, and preserving one active
+checkout provider.</td>
+</tr>
+<tr>
+<td>A single page using the container components</td>
+<td><a href="#embeddedcheckout"><code>EmbeddedCheckout</code></a> for
+the stock flow, or <a href="#single-page-checkout">single-page
+composition</a> to arrange the sections yourself</td>
+<td>With composition, the page layout and navigation; with either
+approach, order-status reconciliation.</td>
+</tr>
+<tr>
+<td>The progressive enhancement example</td>
+<td><a href="#step-by-step-checkout">Step-by-step composition</a></td>
+<td>The visible steps and the rules for moving between them.</td>
+</tr>
+<tr>
+<td>The accordion/collapsible example</td>
+<td><a href="#accordion-checkout">Accordion composition</a></td>
+<td>Disclosure behavior and checkout navigation.</td>
+</tr>
+<tr>
+<td>A flow that already reserved a cart</td>
+<td><a
+href="#resume-a-server-cart"><code>ResumedCheckout</code></a></td>
+<td>Creating the cart in the same session and the order-status
+handoff.</td>
+</tr>
+</tbody>
+</table>
+<p>The composition examples are starting points, not complete
+replacements for a multi-route checkout. In particular, implement
+Back/Edit, cart expiry and payment recovery before production. See <a
+href="#compose-sections">Compose sections</a> for the full
+responsibilities. The 1.x props and callback payloads do not map
+automatically; <a href="#migrating-layout-callbacks">Migrating layout
+callbacks</a> gives specific examples.</p>
 <p><a href="#requirements">Requirements</a> · <a
 href="#quick-start">Quick start</a> · <a
 href="#configuration-and-sessions">Configure sessions</a> · <a
@@ -919,7 +972,7 @@ not assume a timeout, network error or closed provider page means the
 charge failed. A custom provider page must settle with
 <code>{ event: 'dismiss' }</code> on close/unmount, and other custom
 payment ports must settle, or a waiting reset cannot finish.</p>
-<p>The beta.27 declaration comments for <code>reset</code> and
+<p>The beta.28 declaration comments for <code>reset</code> and
 <code>PAID_ORDER_PENDING_MESSAGE</code> say pressing Pay again finishes
 an unconfirmed order; the <code>resetWhenSettled</code> comment also
 omits retired checkouts as a reason for <code>false</code>. Those
@@ -986,7 +1039,7 @@ come from the priced cart, not the opaque catalog ID. Use backend
 country/state IDs for <code>countryId</code> and <code>stateId</code>;
 <code>countryCode</code> / <code>stateCode</code> are payment billing
 codes.</p>
-<p>In beta.27 conditional custom-field requiredness is left to the
+<p>In beta.28 conditional custom-field requiredness is left to the
 backend and not all hosted-checkout conditional visibility is
 reproduced. Verify the actual event against the deployed checkout,
 including blanks, images, holder scoping and validation errors; do not
@@ -1009,7 +1062,7 @@ unknown; <code>reloadCheckoutDetails()</code> can also retry the waiver
 read. A retained order with a possible payment follows separate recovery
 and needs reconciliation. <code>WaiverSigning</code> handles the SDK's
 signing flow.</p>
-<p><strong>Consent limitation in beta.27:</strong> when
+<p><strong>Consent limitation in beta.28:</strong> when
 <code>privacyPolicy</code> is supplied, the stock
 <code>BillingInfo</code> replaces the Ticket Fairy marketing checkbox
 with the required privacy checkbox, but both use
@@ -1489,6 +1542,50 @@ signatures.</td>
 </tr>
 </tbody>
 </table>
+<h4 id="example-ready-made-account-screens">Example: ready-made account
+screens</h4>
+<p>The following setup is for an authorized <strong>first-party</strong>
+full-account integration with the corresponding deployed account routes.
+In that host's initial <a href="#configuration-and-sessions">SDK
+configuration</a>, set <code>accountAuth: true</code> and
+<code>cookieAuth: true</code>, then complete the approved full-account
+sign-in and any required proof challenges before mounting them. The
+checkout-only quick start uses a sign-in path scoped to the event, which
+is not sufficient. Add the options to the one-time setup; do not
+reconfigure from this screen.</p>
+<p>The flags do not grant account access or enable backend routes.
+Third-party integrations need an explicitly approved, supported account
+journey; contact Ticket Fairy to find out whether one is available. The
+example assumes the existing <code>QueryClientProvider</code> is mounted
+and the backend supports these screens. The host supplies navigation
+callbacks. <code>ProfileSettings</code> and
+<code>NotificationPreferences</code> receive <code>signIn</code>;
+<code>AccountRewardsSection</code> has no sign-in callback and only
+displays a message while signed out. The host must detect session expiry
+and offer sign-in separately for rewards.</p>
+<pre class="tsx"><code>import {
+  AccountRewardsSection, NotificationPreferences, ProfileSettings,
+} from &#39;tf-checkout-react&#39;
+
+export function AccountScreen({ screen, goBack, signIn, browseEvents, viewTickets }: {
+  screen: &#39;visibility&#39; | &#39;notifications&#39; | &#39;rewards&#39;
+  goBack: () =&gt; void
+  signIn: () =&gt; void
+  browseEvents: () =&gt; void
+  viewTickets: () =&gt; void
+}) {
+  if (screen === &#39;visibility&#39;) return (
+    &lt;ProfileSettings mode=&quot;visibility&quot; onBack={goBack} onSignIn={signIn} /&gt;
+  )
+  if (screen === &#39;notifications&#39;) return (
+    &lt;NotificationPreferences onBack={goBack} onSignIn={signIn} /&gt;
+  )
+  return &lt;AccountRewardsSection onBrowseEvents={browseEvents} onViewTickets={viewTickets} /&gt;
+}</code></pre>
+<p>Use <code>mode="links"</code> for profile links. These components do
+not replace an orders list or establish account authorization. Scope or
+clear account queries when the buyer signs out or changes, and handle
+loading, sign-in and navigation in the host as needed.</p>
 <p>For account orders and ticket lists use <code>hooks.useOrders</code>,
 <code>hooks.useOrder</code>, <code>ttf.orders.list</code>,
 <code>ttf.orders.get</code> or <code>ttf.orders.myTickets</code>. In
@@ -1968,7 +2065,7 @@ props, account sessions or persisted 1.x state.</p>
 <thead>
 <tr>
 <th>1.x integration</th>
-<th>2.0.0-beta.27 approach</th>
+<th>2.0.0-beta.28 approach</th>
 </tr>
 </thead>
 <tbody>

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.0.0-beta.27",
+  "version": "2.0.0-beta.28",
   "license": "MIT",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",