@seatlayer/js 0.67.14 → 0.67.15

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';
@@ -39,6 +77,52 @@ const hold = await chart.hold();          // null on a 409 conflict
 chart.destroy();
 ```
 
+## 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 +135,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
@@ -304,17 +409,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