@seatlayer/js 0.67.14 → 0.68.0

package/README.md

@@ -1,20 +1,46 @@
-# @seatlayer/js
+# SeatLayer JavaScript Seat Map SDK for Reserved Seating
 
 [![npm](https://img.shields.io/npm/v/@seatlayer/js)](https://www.npmjs.com/package/@seatlayer/js)
 [![npm downloads](https://img.shields.io/npm/dm/@seatlayer/js)](https://www.npmjs.com/package/@seatlayer/js)
-
-The framework-agnostic SeatLayer embed SDK. Render the complete buyer picker or
-a headless interactive chart, let buyers select and **hold** inventory in the
-browser, then **book** it from your trusted server.
-
-[Package on npm](https://www.npmjs.com/package/@seatlayer/js) ·
-[Install guide](https://docs.seatlayer.io/buyer-sdk/install/) ·
-[Live demo](https://app.seatlayer.io/demo/play) ·
-[Website](https://seatlayer.io/developers/) ·
-[AI Toolkit](https://github.com/seatlayer/seatlayer-ai-toolkit)
-
-Works in plain HTML and any framework (React, Vue, Svelte, Angular…). For React,
-prefer the [`@seatlayer/react`](https://www.npmjs.com/package/@seatlayer/react) wrapper.
+[![TypeScript](https://img.shields.io/badge/TypeScript-types%20included-3178C6.svg)](https://www.typescriptlang.org/)
+
+The framework-agnostic SeatLayer seat map SDK for the browser. Render an
+interactive seating chart or a complete seat picker, show live seat
+availability, and let buyers take temporary holds on the inventory they choose.
+
+The browser **selects and holds**; your trusted server **books**. It works in
+plain HTML and in any framework.
+
+[SeatLayer JavaScript SDK on npm](https://www.npmjs.com/package/@seatlayer/js) ·
+[Buyer SDK installation guide](https://docs.seatlayer.io/buyer-sdk/install/) ·
+[SeatLayer reserved-seating platform](https://seatlayer.io/) ·
+[Buyer seat-map demo](https://app.seatlayer.io/demo/play/grand-theatre) ·
+[SeatLayer React seat map SDK](https://www.npmjs.com/package/@seatlayer/react) ·
+[SeatLayer Vue seat map SDK](https://www.npmjs.com/package/@seatlayer/vue) ·
+[SeatLayer Angular seat map SDK](https://www.npmjs.com/package/@seatlayer/angular) ·
+[SeatLayer AI Toolkit](https://github.com/seatlayer/seatlayer-ai-toolkit)
+
+For React, Vue, or Angular, prefer the first-party wrapper — it is this same
+runtime with the framework's own component, props, and lifecycle around it.
+
+## What is included
+
+- `SeatingChart` — the headless interactive chart, mounted into an element you
+  own.
+- `SeatPicker` — the complete buyer experience: map, legend, priced tray, hold
+  timer, and the checkout hand-off.
+- `EmbeddedDesigner` — a hosted chart Designer inside your own application.
+- `SeatManager` and `ManageApi`, from the `@seatlayer/js/manager` subpath — the
+  organizer control room and event-scoped inventory client.
+- `attachPickerFrame` — the host-side iframe helper for embedded pickers.
+- TypeScript declarations for ESM (`dist/index.d.ts`) and CommonJS
+  (`dist/index.d.cts`), for the root and the `./manager` subpath.
+
+## Requirements
+
+- A browser DOM. Give the container a definite height; the chart sizes itself
+  to its container, not to the viewport.
+- No framework, build step, or peer dependency is required.
 
 ## Install
 
@@ -22,7 +48,19 @@ prefer the [`@seatlayer/react`](https://www.npmjs.com/package/@seatlayer/react)
 npm install @seatlayer/js
 ```
 
-## Usage
+No build tool? Load the hosted bundle instead — it exposes a `seatlayer`
+global. Pin an exact version in production; the major alias always redirects to
+the newest release in that line.
+
+```html
+<div id="picker" style="width: 100%; height: 640px"></div>
+<script src="https://cdn.seatlayer.io/seatlayer-js@0/seatlayer.js"></script>
+<script>
+  new seatlayer.SeatPicker({ container: '#picker', event: 'ev_9f3a' }).render();
+</script>
+```
+
+## Quick start
 
 ```js
 import { SeatingChart } from '@seatlayer/js';
@@ -30,6 +68,7 @@ import { SeatingChart } from '@seatlayer/js';
 const chart = new SeatingChart({
   container: '#chart',
   event: 'ev_9f3a',
+  publicKey: 'pk_test_…',
   onHold: ({ holdId }) => bookOnYourServer(holdId),
 });
 
@@ -39,6 +78,61 @@ const hold = await chart.hold();          // null on a 409 conflict
 chart.destroy();
 ```
 
+For an ordinary Public sale on a Platform/SDK event, `publicKey` starts one
+direct bootstrap after SeatLayer validates the key, event mode, and browser's
+exact registered origin. The SDK keeps the returned Public-only bearer in
+memory, and the bootstrap carries the chart plus compact inventory status
+together. Login, presale, partner, and channel inventory instead use
+`buyerAccessTokenProvider` or `buyerAccessToken` from your authenticated
+backend; either explicit credential takes precedence over `publicKey`. Managed
+public/unlisted events retain anonymous event-key access and omit `publicKey`.
+
+## Fixed Renewable Season (private-beta candidate)
+
+The Season source is merged for development, but it is not included in the
+currently registered stable package. The validated out-of-band candidate is
+`0.67.0-season-s08.0`; the npm badge and install command above describe the
+stable registered package and do not prove this candidate is published.
+
+`SeasonPicker` is a distinct fixed-inclusion surface. Your server mints a
+short-lived `bss_` session for the browser's exact Origin; keep that token in
+memory. The picker returns an opaque, price-free handoff with the immutable Plan
+activation, stable operation/hold identities, expiry/policy, and per-occurrence
+outcomes. Inspect and book it from trusted server code.
+
+```js
+import { SeasonPicker } from '@seatlayer/js';
+
+const picker = new SeasonPicker({
+  container: '#season',
+  season: 'sea_2027',
+  buyerAccessToken: session.token,
+  onContinue: (handoff) => continueOnYourServer(handoff.operationId),
+});
+await picker.render();
+await picker.holdSameSeat(['A-1'], 'sop_checkout_1183');
+
+// Caller-stable and exact-replayable. Do not invent a new id after uncertainty.
+await picker.release('sra_checkout_1183');
+
+// Returning-holder journey: this records browser intent only. It never proves
+// price, payment, an order, or a renewed Contract; your trusted backend must
+// inspect and commit the exact offer with a caller-stable action ID.
+const intent = await picker.createRenewalIntent('sro_returning_holder_1183');
+sendIntentToYourBackend(intent);
+```
+
+Supply `initialOperationId` to restore a lost create response. Pending operations
+are polled through their retained operation URL; `partial_terminal` stays visible
+and must be reconciled rather than replaced with a blind new action. This is an
+unpublished private-beta candidate, not the currently registered npm package.
+
+The private-beta claim is this framework-agnostic JavaScript `SeasonPicker`
+only. `@seatlayer/react`, `@seatlayer/vue`, `@seatlayer/angular`, React Native,
+Flutter, iOS, and Android do not expose a verified Season wrapper and are
+explicitly unsupported for this candidate. A host may mount this plain-JS
+surface inside a framework, but that does not create a wrapper support claim.
+
 ## Use in any framework
 
 The SDK only needs a DOM element and mount/unmount hooks:
@@ -51,6 +145,27 @@ onUnmounted(() => chart?.destroy());
 
 Svelte → `onMount` / `onDestroy`. Angular → `ngAfterViewInit` / `ngOnDestroy`.
 
+First-party wrappers exist for the three largest frameworks and are built on
+this package: [`@seatlayer/react`](https://www.npmjs.com/package/@seatlayer/react),
+[`@seatlayer/vue`](https://www.npmjs.com/package/@seatlayer/vue), and
+[`@seatlayer/angular`](https://www.npmjs.com/package/@seatlayer/angular).
+
+## Security boundary
+
+The browser **selects and holds** inventory. Your trusted backend **inspects and
+books** the hold after payment or order validation.
+
+- Never expose a SeatLayer secret key in browser code or a bundled environment
+  variable.
+- Send only the `holdId` and your normal checkout context to your backend.
+- Calculate the charge from server-inspected hold items, not from browser input.
+- Reuse your stable order id as `bookingRef` so a retried booking is idempotent.
+- Organizer surfaces take a short-lived, event-scoped `mse_` browser grant held
+  in memory — never a tenant `sk_` secret, never a URL, storage, or log.
+
+Read [how the integration works](https://docs.seatlayer.io/start/how-it-works/)
+before connecting checkout.
+
 ## Embed the live control room
 
 `SeatManager` gives first-party dashboards and external platforms the same
@@ -118,13 +233,28 @@ callers must use an event-scoped `mse_` grant.
 
 ## Embed the chart Designer
 
-For organizer-facing venue design, use `EmbeddedDesigner`. Your backend mints the
-short-lived `designerUrl`; the browser receives no SeatLayer secret key. The wrapper
-creates the iframe, recreates it for a new session URL, and validates every
-`postMessage` by iframe source and exact Designer origin.
+For organizer-facing venue design, use `EmbeddedDesigner`. Your backend
+authenticates and authorizes the organizer, then requests a short-lived session
+from SeatLayer with `sk_…`; SeatLayer mints the `dse_…` token and returns
+`designerUrl`. Never expose the secret or call SeatLayer's Designer-session
+endpoint from browser code. The wrapper creates the iframe, recreates it for a
+new session URL, and validates every `postMessage` by iframe source and exact
+Designer origin.
+
+Start that required backend request on authenticated route intent or page load,
+not on the final **Open Designer** click. Keep the response no-store and the
+session in memory, and race its promise with the SDK import and editor shell.
+An authenticated server-rendered page may instead include `designerUrl` in a
+no-store bootstrap. The iframe still waits for the session; the win comes from
+overlapping the trusted request with SDK and shell loading.
 
 ```js
-import { EmbeddedDesigner } from '@seatlayer/js';
+const sdkPromise = import('@seatlayer/js');
+const sessionPromise = requestDesignerSession(); // authenticated + no-store
+const [{ EmbeddedDesigner }, session] = await Promise.all([
+  sdkPromise,
+  sessionPromise,
+]);
 
 const designer = new EmbeddedDesigner({
   container: '#venue-designer',
@@ -134,9 +264,9 @@ const designer = new EmbeddedDesigner({
   onPublished: ({ chartId }) => refreshVenue(chartId),
   onClose: () => closeVenueEditor(),
   onError: ({ code, message }) => showError(code ?? message),
-  // Mint a fresh session when the user retries an expired/failed editor:
+  // Request a fresh session through your backend on retry/expiry:
   onRequestRelaunch: async () => {
-    const next = await mintDesignerSession(session.chartId);
+    const next = await requestDesignerSession(session.chartId);
     designer.setDesignerUrl(next.designerUrl);
   },
 });
@@ -175,7 +305,7 @@ CSS files or external assets.
 | --- | --- | --- | --- |
 | `showLoadingState` | `boolean` | `true` | Render the built-in skeleton and error card. Set `false` when you draw your own chrome. |
 | `loadingTimeoutMs` | `number` | `20000` | If `ready` never arrives within this window, show the error card with a timeout message. |
-| `onRequestRelaunch` | `() => void` | — | Called by **"Try again"** _and_ by automatic renewal (below). Mint a fresh session and call `setDesignerUrl()`; the iframe recreates and returns to loading. When omitted, "Try again" reloads the current URL in place. |
+| `onRequestRelaunch` | `() => void` | — | Called by **"Try again"** _and_ by automatic renewal (below). Request a fresh session through your backend and call `setDesignerUrl()`; the iframe recreates and returns to loading. When omitted, "Try again" reloads the current URL in place. |
 | `autoRenewSession` | `boolean` | `true`¹ | Silently renew the session before it expires and auto-recover once if an expiry error slips through. ¹Defaults `true` only when `onRequestRelaunch` is provided; a no-op without it. Set `false` for fully manual "Try again". |
 
 `setDesignerUrl()` always returns the host to the loading state, so a relaunch
@@ -183,20 +313,21 @@ flow needs no extra bookkeeping.
 
 ### Session lifecycle
 
-Designer sessions are **short-lived by design**: your backend mints a `dse_`
-token (default 1 hour, up to 4 hours via `expiresInSeconds`) and bakes it into
-`designerUrl`. Pick a TTL that fits how long organizers actually edit — longer is
-not automatically better; the renewal below keeps even a multi-hour session alive.
+Designer sessions are **short-lived by design**: your backend authorizes and
+requests one, then SeatLayer mints a `dse_` token (default 1 hour, up to 4 hours
+via `expiresInSeconds`) into `designerUrl`. Pick a TTL that fits how long
+organizers actually edit — longer is not automatically better; the renewal
+below keeps even a multi-hour session alive.
 
-Provide `onRequestRelaunch` returning (or awaiting) a freshly minted session, and
-the SDK turns expiry into a non-event:
+Provide `onRequestRelaunch` returning (or awaiting) a freshly requested session,
+and the SDK turns expiry into a non-event:
 
 - **Silent proactive renewal.** From each `ready` message's `expiresAt` the SDK
   schedules an automatic relaunch shortly before the session lapses — ~3 minutes
   ahead, or, for a TTL under 15 minutes, after 80% of the remaining life (never
-  sooner than 30s after `ready`). Your `onRequestRelaunch` mints a fresh session
-  and swaps `designerUrl`, so editing continues with no expiry card. The timer
-  re-arms from every `ready`.
+  sooner than 30s after `ready`). Your `onRequestRelaunch` requests a fresh
+  session through your backend and swaps `designerUrl`, so editing continues
+  with no expiry card. The timer re-arms from every `ready`.
 - **Automatic expiry recovery.** If an expiry error still arrives (a laptop that
   slept past the renewal window, say), the SDK makes **one** automatic relaunch
   attempt before showing the "Try again" card, and only falls back to the card if
@@ -210,9 +341,9 @@ const designer = new EmbeddedDesigner({
   container: '#venue-designer',
   designerUrl: session.designerUrl,
   expectedChartId: session.chartId,
-  // Mint a fresh session on renewal, expiry recovery, or "Try again":
+  // Request a fresh session on renewal, expiry recovery, or "Try again":
   onRequestRelaunch: async () => {
-    const next = await mintDesignerSession(session.chartId); // your backend, up to 4h TTL
+    const next = await requestDesignerSession(session.chartId); // your backend, up to 4h TTL
     designer.setDesignerUrl(next.designerUrl);               // recreates the iframe
   },
   // autoRenewSession defaults to true because onRequestRelaunch is present.
@@ -223,7 +354,8 @@ designer.mount();
 ## API
 
 `new SeatingChart(options)` — options: `container` (selector or element, required),
-`event` (key, required), `apiBase?`, `maxSelection?` (default 10),
+`event` (key, required), `apiBase?`, `publicKey?`,
+`buyerAccessTokenProvider?`, `buyerAccessToken?`, `maxSelection?` (default 10),
 `selectedObjects?`, `selectableObjects?`, `numberOfPlacesToSelect?`,
 `selectionValidators?`,
 `onSelectionChange?`, `onSelectionValidityChange?`, `onHold?`,
@@ -304,17 +436,93 @@ Two limits worth knowing before switching it on:
   rather than back in your embed. In-page gateways never navigate away and
   confirm in place, as does an embed running on an allowed origin.
 
-## Related resources
-
-- [Buyer SDK documentation](https://docs.seatlayer.io/buyer-sdk/install/)
-- [SeatingChart reference](https://docs.seatlayer.io/buyer-sdk/seating-chart/)
-- [Holds and checkout](https://docs.seatlayer.io/buyer-sdk/holds-and-checkout/)
-- [Complete checkout example](https://docs.seatlayer.io/examples/complete-checkout/)
-- [`@seatlayer/react`](https://www.npmjs.com/package/@seatlayer/react)
-- [React Native SDK](https://github.com/seatlayer/seatlayer-react-native)
-- [iOS SDK](https://github.com/seatlayer/seatlayer-ios)
-- [Flutter package](https://pub.dev/packages/seatlayer)
-- [Agent-readable documentation](https://docs.seatlayer.io/llms.txt)
+## Frequently asked questions
+
+### What is the best JavaScript library for seat maps and seat booking?
+
+That depends on what you need to own. This package is a complete reserved-seating
+runtime: it draws the venue, shows live availability, enforces selection rules,
+and takes temporary holds that stop two buyers from taking the same seat. A
+generic drawing library is lighter if you only need pictures of seats; the live
+inventory, holds, and server-side booking are the parts SeatLayer provides, and
+the same event also renders through the React, Vue, Angular, and native mobile
+SDKs.
+
+### How do I add a seat map to a plain JavaScript page?
+
+Load the hosted bundle with a `<script>` tag or install `@seatlayer/js`, give a
+container a definite height, construct `SeatPicker` or `SeatingChart` with your
+event key, and call `render()`. The install snippet above is the whole
+integration; the
+[buyer SDK installation guide](https://docs.seatlayer.io/buyer-sdk/install/)
+covers options, events, and the framework variants.
+
+### Does it render in the page or in an iframe?
+
+`SeatPicker` and `SeatingChart` render directly into the element you give them,
+so your own styles and layout apply. Embedding in an iframe is supported too —
+`attachPickerFrame` wires the host side of the resize and fullscreen protocol,
+verifying the message origin. The organizer Designer is deliberately
+iframe-only, so no Designer credential ever reaches the host bundle.
+
+### How do temporary seat holds work?
+
+When a buyer commits to a selection, `hold()` reserves that inventory against
+concurrent buyers for a limited checkout window and returns an opaque `holdId`.
+The hold lapses on its own if checkout never completes, `resumeHold()` restores
+it after a same-tab checkout navigation or a reload, and `releaseLabels()` gives
+back part of it. This is what prevents double-selling without locking seats
+forever.
+
+### Can I use my own payment provider?
+
+Yes. By default no payment code is downloaded at all. The widget hands your code
+a `holdId` and a self-contained `CheckoutHandoff` with priced line items, your
+backend charges through whatever provider you already use, and it then books the
+hold through the
+[server-side checkout flow](https://docs.seatlayer.io/buyer-sdk/holds-and-checkout/).
+The opt-in `checkout: 'hosted'` mode documented above exists only for hosts with
+no backend.
+
+### Are TypeScript types included?
+
+Yes. The package ships its own declarations for ESM and CommonJS, for both the
+root entry and the `@seatlayer/js/manager` subpath — there is no `@types/*`
+package to add. Declarations are validated at release by `publint` and
+`arethetypeswrong`.
+
+## Continue your JavaScript integration
+
+- [Follow the buyer SDK installation guide](https://docs.seatlayer.io/buyer-sdk/install/)
+  for the hosted script, ESM, and framework variants.
+- [Read the SeatingChart reference](https://docs.seatlayer.io/buyer-sdk/seating-chart/)
+  for the complete chart API.
+- [Connect seat holds to secure server-side checkout](https://docs.seatlayer.io/buyer-sdk/holds-and-checkout/)
+  without putting booking credentials in the browser.
+- [Run the complete checkout example](https://docs.seatlayer.io/examples/complete-checkout/)
+  to connect a buyer hold id to payment and idempotent booking.
+- [Compare SeatLayer's mobile seat map SDKs](https://docs.seatlayer.io/buyer-sdk/mobile/)
+  when the same event also has to render in native apps.
+- [Read the embedded Designer guide](https://docs.seatlayer.io/platform/embedded-designer/)
+  to let organizers draw their own venues inside your product.
+- [Explore the 3D seating chart](https://seatlayer.io/3d-seat-map/) for the
+  interactive venue view buyers can switch to from the map.
+- [Point AI coding agents at the SeatLayer docs index](https://docs.seatlayer.io/llms.txt)
+  (`llms.txt`) for an agent-readable map of the documentation.
+
+## SeatLayer SDK ecosystem
+
+| Surface | Package or source |
+| --- | --- |
+| JavaScript | [`@seatlayer/js`](https://www.npmjs.com/package/@seatlayer/js) (this package) |
+| React | [`@seatlayer/react`](https://www.npmjs.com/package/@seatlayer/react) |
+| Vue | [`@seatlayer/vue`](https://www.npmjs.com/package/@seatlayer/vue) |
+| Angular | [`@seatlayer/angular`](https://www.npmjs.com/package/@seatlayer/angular) |
+| React Native | [`@seatlayer/react-native`](https://www.npmjs.com/package/@seatlayer/react-native) |
+| iOS | [`seatlayer-ios`](https://github.com/seatlayer/seatlayer-ios) |
+| Flutter | [`seatlayer`](https://pub.dev/packages/seatlayer) |
+| Android | [`seatlayer-android`](https://github.com/seatlayer/seatlayer-android) |
+| Server SDKs | [Node.js, Python, PHP, Ruby, .NET, Java, and Go](https://docs.seatlayer.io/server-sdk/install/) |
 
 ## License