@seatlayer/js 0.80.3 → 0.82.0

package/README.md

@@ -129,6 +129,72 @@ Supply `initialOperationId` to restore a lost create response. Pending operation
 are polled through their retained operation URL; `partial_terminal` stays visible
 and must be reconciled rather than replaced with a blind new action.
 
+### Selling a Season from a page with no backend
+
+A Season the organizer has made public can be embedded without minting anything
+first. Omit `buyerAccessToken` and `buyerAccessTokenProvider` and the picker
+mints its own anonymous, origin-bound session against
+`POST /pub/seasons/:key/sessions`. That session is **Public sale only**: it can
+never reach a private channel or a renewal allocation, and an explicit
+`buyerAccessToken` / `buyerAccessTokenProvider` always takes precedence over it.
+
+`publicKey` is accepted for parity with `SeatPicker` so one snippet shape covers
+both surfaces. It is not sent and is not a credential — a public Season session
+is authorized by the Season key plus the browser's registered Origin.
+
+```js
+const picker = new SeasonPicker({
+  container: '#season',
+  season: 'sea_2027',
+  publicKey: 'pk_live_…',   // optional; never sent
+  checkout: 'hosted',
+  returnUrl: window.location.href,
+  onOrderConfirmed: (order) => showReceipt(order),
+});
+await picker.render();
+```
+
+Three refusals reach `onAccessUnavailable` with their own reasons, because they
+ask three different things of the organizer:
+
+| `reason` | Means | `retryable` |
+| --- | --- | --- |
+| `audience_not_public` | The Season is embed-only; a tokenless embed cannot sell it. | `false` |
+| `sales_not_open` | Public, but not on sale yet (or paused, or ended). | `true` |
+| `origin_not_allowed` | This page's Origin is not a declared embed domain. | `false` |
+
+The picker also says each one in plain language in its own status region, so a
+host that handles none of them still shows the buyer something true.
+
+### Package prices and hosted Season checkout
+
+`GET /pub/seasons/:key/prices` returns per-category package prices in minor
+units. When it does, **the server price wins**: the hero prices each category
+for the whole package ("Stalls · $480 for all 8 dates"), the confirm card totals
+the selection at those prices, and the host-authored display-only `offer` copy
+is not shown beside them. With no server prices, the existing "your ticketing
+platform confirms the price" wording stays exactly as it was.
+
+`checkout` chooses who takes the money:
+
+- `'handoff'` (default) — unchanged. `onContinue` fires with the opaque,
+  price-free handoff and your server prices, charges and books it. No payment
+  code is downloaded.
+- `'hosted'` — once the atomic hold is committed the primary action reads
+  *Continue to checkout*, and pressing it opens the same payment card the Event
+  picker uses. It collects an email, calls
+  `POST /pub/seasons/:key/checkout` with the hold's `operationId`, and follows
+  the gateway exactly as the Event path does — one order, one ticket per
+  performance. `onContinue` still fires, so a host that only observes the moment
+  keeps working.
+
+A Season the organizer prices on their own backend reports
+`checkoutMode: 'server'` on `GET /pub/seasons/:key`; asking for `'hosted'`
+there stays on `'handoff'` rather than starting a payment SeatLayer cannot
+complete. `returnUrl` follows the same rules as the Event picker's: the
+organizer's declared embed domains decide whether it is honoured, so supplying
+one cannot authorize it.
+
 The framework-agnostic JavaScript `SeasonPicker` is also wrapped by
 `@seatlayer/react`, `@seatlayer/vue`, and `@seatlayer/angular` `0.72.0` and
 newer. React Native, Flutter, iOS, and Android do not expose a Season bridge