@ticketlayer/live 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ticketlayer Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# @ticketlayer/live
+
+The buyer-facing Ticketlayer SDK. It runs in the browser (`@ticketlayer/live`),
+in React Native (`@ticketlayer/live/native`) and, from a separate entry, on
+the server (`@ticketlayer/live/server`).
+
+```bash
+npm install @ticketlayer/live
+```
+
+Not on npm yet: the package is built and versioned here but the first
+release waits on the `NPM_TOKEN` secret (see "Releasing"). Until then our
+apps use a `file:` link to this repository, and third-party pages load the
+CDN build. The vault page `architecture/sdk-architecture.md` lists what is
+on npm.
+
+## Browser
+
+```ts
+import { createLiveClient } from '@ticketlayer/live';
+
+const tl = await createLiveClient({
+  baseUrl: 'https://live.staging.t9r.dev',
+  publishableKey: 'tlpk_...',   // the channel's publishable key (embed); omit on a hosted storefront
+  checkout: { mode: 'modal', embedBaseUrl: 'https://hbo.staging.t9r.dev' },
+});
+```
+
+The CDN build (`dist/ticketlayer.js`, served at `/v1/ticketlayer.js`) boots
+itself from `data-*` attributes on its script tag; see `src/auto.ts` and
+`live-elements/cdn/README.md`. `CLAUDE.md` is the working agreement.
+
+## React Native
+
+`@ticketlayer/live/native` is the same stateful client (events, cart, auth,
+orders, presale, the event bus) built for an app instead of a page: nothing
+defaults from `window.location`, nothing is published on `window`, no theme
+is injected and no iframe modal is mounted. The Live session id travels in
+the `X-Live-Session` header (as the browser embed's does) and is kept in an
+async token storage you inject, so a cart or a magic-link sign-in survives
+an app restart. Card details never enter the app: the hosted checkout opens
+in a WebView.
+
+```ts
+import * as SecureStore from 'expo-secure-store';
+import { createNativeLiveClient, secureStoreStorage } from '@ticketlayer/live/native';
+
+const tl = await createNativeLiveClient({
+  apiUrl: 'https://live-api.ticketlayer.com',      // required: no page to default from
+  publishableKey: 'tlpk_...',
+  checkoutBaseUrl: 'https://checkout.ticketlayer.com', // the host serving /embed/checkout
+  tokenStorage: secureStoreStorage(SecureStore),   // or asyncStorageStorage(AsyncStorage)
+});
+
+const listings = await tl.events.list();
+await tl.cart.add({ eventOccurrenceId, categoryId, ticketTypeId, quantity: 1 });
+```
+
+Token storage is `{ get, set, remove }` (all async). Two adapters ship with
+the package, each taking the platform module as a parameter so the SDK
+depends on neither: `secureStoreStorage(SecureStore, { key?, options? })`
+for `expo-secure-store` (the keychain: preferred) and
+`asyncStorageStorage(AsyncStorage, { key? })` for
+`@react-native-async-storage/async-storage`. `memoryStorage()` is the
+default and forgets the session on restart. On start the client resumes a
+stored session (`GET /session`); a token the API rejects is removed and the
+client starts lazily, creating a session on the first cart mutation or
+sign-in, as the browser client does.
+
+Checkout, following `live-hostedboxoffice/docs/embed-checkout-contract.md`:
+
+```tsx
+import { WebView } from 'react-native-webview';
+import { Linking } from 'react-native';
+import { parseCheckoutMessage } from '@ticketlayer/live/native';
+
+const RETURN_URL = 'myapp://tickets/complete'; // on the checkout host's RETURN_URL_ALLOWLIST
+
+// 1. The URL hands the session (and so the cart) to the hosted checkout.
+const url = await tl.buildCheckoutUrl({ returnUrl: RETURN_URL });
+
+// 2. Success arrives as a tl:complete message ...
+<WebView
+  source={{ uri: url }}
+  onMessage={(e) => {
+    const m = parseCheckoutMessage(e.nativeEvent.data);
+    if (m?.type === 'tl:complete') tl.completeCheckout(m); // emits checkout:completed, drops the cart
+    if (m?.type === 'tl:close') close();
+  }}
+  onShouldStartLoadWithRequest={(req) => {
+    if (req.url.startsWith(RETURN_URL)) { Linking.openURL(req.url); return false; }
+    return req.url.startsWith('https://');
+  }}
+/>
+
+// 3. ... and as the return_url deep link (also on a cold start).
+Linking.addEventListener('url', ({ url }) => {
+  const done = tl.parseCheckoutReturn(url, { returnUrl: RETURN_URL });
+  if (done) tl.completeCheckout(done); // { orderId, orderReference }
+});
+```
+
+`tl.signOut()` ends the session, removes the stored token and clears the
+local cart; the next mutation mints a fresh session. The pure helpers
+(`buildCheckoutUrl`, `parseCheckoutReturn`, `parseCheckoutMessage`) are
+exported too for hosts that manage the session themselves.
+
+A complete illustrative app is in `examples/expo/` (type-checked against the
+built package with `npx tsc -p examples/expo/tsconfig.json`).
+
+## Server-side rendering
+
+`@ticketlayer/live/server` is a stateless catalogue client for Node and edge
+runtimes: plain `fetch`, no DOM, no window guards, no Elements. It reads the
+channel's listings, event detail and theme, keeps a small in-memory TTL cache
+(60s by default, `cache: false` to disable), and never pulls the browser client
+into your server bundle. Nothing from it is included in the browser build.
+
+```ts
+import { createServerClient } from '@ticketlayer/live/server';
+
+export const live = createServerClient({
+  apiUrl: process.env.LIVE_API_INTERNAL_URL!,
+  // One of: a channel publishable key, or the storefront domain (resolved
+  // once via GET /channel and cached).
+  publishableKey: process.env.LIVE_PUBLISHABLE_KEY,
+  // domain: 'tickets.example.com',
+  cache: { ttlMs: 60_000 }, // or false when the framework caches for you
+});
+```
+
+A Next.js server component:
+
+```tsx
+// app/events/[id]/page.tsx
+import { notFound } from 'next/navigation';
+import { createServerClient, LiveAPIError } from '@ticketlayer/live/server';
+
+const live = createServerClient({
+  apiUrl: process.env.LIVE_API_INTERNAL_URL!,
+  publishableKey: process.env.LIVE_PUBLISHABLE_KEY!,
+  // Let Next's fetch cache own revalidation instead of the SDK's TTL cache.
+  cache: false,
+});
+
+export default async function EventPage({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  try {
+    const [event, theme] = await Promise.all([
+      live.events.get(id, { fetchInit: { next: { revalidate: 300, tags: ['events', `event:${id}`] } } }),
+      live.theme.get({ fetchInit: { next: { revalidate: 300, tags: ['theme'] } } }),
+    ]);
+    return (
+      <main style={{ fontFamily: theme.typography?.fontFamily }}>
+        <h1>{event.name}</h1>
+      </main>
+    );
+  } catch (err) {
+    if (err instanceof LiveAPIError && err.status === 404) notFound();
+    throw err;
+  }
+}
+```
+
+Surface:
+
+| Call | Returns |
+|------|---------|
+| `events.list(opts?)` | `Listing[]` - the channel's active listings |
+| `events.get(eventId, opts?)` | `EventDetail` - throws `LiveAPIError` (404) when not listed |
+| `theme.get(opts?)` | `Theme` - throws `LiveAPIError` (404) when none is assigned |
+| `session.create()` | `{ sessionToken, channel, customer }` - a Live session id, e.g. to hand to a WebView checkout |
+| `get(path, opts?)` | Unwrapped JSend `data` for any other Live GET |
+| `clearCache()` | Drops cached reads and the domain-resolved key |
+
+`opts.fetchInit` is merged into that request (headers merge, everything else
+overrides), so framework-specific fetch options pass straight through.
+`opts.noCache` bypasses the in-memory cache for one call.
+
+## Scripts
+
+```bash
+npm run build      # tsc -> dist/ (index.js, server.js, native/, types)
+npm run build:cdn  # + esbuild IIFE -> dist/ticketlayer.js
+npm test           # builds, then node --test test/*.test.mjs
+npm run docs:gen   # typedoc -> docs-output/
+```
+
+## Releasing
+
+Versioning and publishing are driven by [changesets](.changeset/README.md):
+add a changeset with your change, and on merge to `main` the release workflow
+keeps a "Release @ticketlayer/live" pull request up to date; merging that
+publishes to npm with provenance. `src/client.ts` and `src/generated/` are
+generated by `backstage-sdk-tooling` (regeneration PRs arrive automatically
+when backstage-api publishes a contract) and are shipped exactly as committed.
+The `ticketlayer` block in `package.json` records the spec version, dated API
+version and generator each release was built from.

package/dist/auto.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Drop-in auto-init for the CDN/UMD build (`dist/ticketlayer.js`).
+ *
+ * This is the "one line of code" embed - what a Webflow/Framer/any site drops in:
+ *
+ *   <script src="https://cdn.ticketlayer.com/v1/ticketlayer.js"
+ *           data-publishable-key="tlpk_..."
+ *           data-api-url="https://live-api.ticketlayer.com"
+ *           data-checkout-base="https://checkout.ticketlayer.com"></script>
+ *
+ * On load it boots a Live client from the script tag's data-* attributes:
+ * publishes `window.Ticketlayer` (so `@ticketlayer/elements` bind), injects the
+ * Elements bundle, and installs the hosted iframe checkout modal. Plain HTML
+ * custom-element tags (`<tl-event-list>`, `<tl-buy-tickets-button event-id>`)
+ * then just work - no bundler, no framework.
+ *
+ * The IIFE also exposes the SDK on `window.TicketlayerLive` (createLiveClient,
+ * boot) for sites that want manual control instead of the data-attribute path.
+ *
+ * NOTE: index.ts (the npm/bundler entry) does NOT import this module, so only
+ * the CDN build auto-boots. Booting is idempotent and a no-op without a key.
+ */
+import { createLiveClient, TicketlayerLive } from './createLiveClient.js';
+/**
+ * Boot a Live client from the script tag's data-* attributes. Returns the
+ * client (or null when there's no publishable key / not in a browser). Safe to
+ * call once; subsequent calls no-op.
+ */
+export declare function boot(): Promise<TicketlayerLive | null>;
+export { createLiveClient, TicketlayerLive };
+//# sourceMappingURL=auto.d.ts.map

package/dist/auto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto.d.ts","sourceRoot":"","sources":["../src/auto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAkC1E;;;;GAIG;AACH,wBAAgB,IAAI,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CA0BtD;AAGD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC"}

package/dist/auto.js

@@ -0,0 +1,78 @@
+/**
+ * Drop-in auto-init for the CDN/UMD build (`dist/ticketlayer.js`).
+ *
+ * This is the "one line of code" embed - what a Webflow/Framer/any site drops in:
+ *
+ *   <script src="https://cdn.ticketlayer.com/v1/ticketlayer.js"
+ *           data-publishable-key="tlpk_..."
+ *           data-api-url="https://live-api.ticketlayer.com"
+ *           data-checkout-base="https://checkout.ticketlayer.com"></script>
+ *
+ * On load it boots a Live client from the script tag's data-* attributes:
+ * publishes `window.Ticketlayer` (so `@ticketlayer/elements` bind), injects the
+ * Elements bundle, and installs the hosted iframe checkout modal. Plain HTML
+ * custom-element tags (`<tl-event-list>`, `<tl-buy-tickets-button event-id>`)
+ * then just work - no bundler, no framework.
+ *
+ * The IIFE also exposes the SDK on `window.TicketlayerLive` (createLiveClient,
+ * boot) for sites that want manual control instead of the data-attribute path.
+ *
+ * NOTE: index.ts (the npm/bundler entry) does NOT import this module, so only
+ * the CDN build auto-boots. Booting is idempotent and a no-op without a key.
+ */
+import { createLiveClient, TicketlayerLive } from './createLiveClient.js';
+/** Read config off the embedding <script> tag's data-* attributes. */
+function readConfig() {
+    if (typeof document === 'undefined')
+        return null;
+    const el = document.currentScript ??
+        document.querySelector('script[data-publishable-key]');
+    if (!el)
+        return null;
+    const d = el.dataset;
+    return {
+        publishableKey: d.publishableKey,
+        apiUrl: d.apiUrl,
+        elementsUrl: d.elementsUrl,
+        checkoutBase: d.checkoutBase,
+        // Inject @ticketlayer/elements unless explicitly opted out (data-elements="false").
+        autoElements: d.elements !== 'false',
+    };
+}
+/**
+ * Boot a Live client from the script tag's data-* attributes. Returns the
+ * client (or null when there's no publishable key / not in a browser). Safe to
+ * call once; subsequent calls no-op.
+ */
+export function boot() {
+    if (typeof window === 'undefined')
+        return Promise.resolve(null);
+    const w = window;
+    if (w.__tlBooted)
+        return w.ticketlayer?.ready ?? Promise.resolve(null);
+    const cfg = readConfig();
+    if (!cfg?.publishableKey)
+        return Promise.resolve(null); // manual usage - nothing to boot
+    if (!cfg.apiUrl) {
+        console.error('[ticketlayer] Missing data-api-url on the embed script; cannot auto-init.');
+        return Promise.resolve(null);
+    }
+    w.__tlBooted = true;
+    const ready = createLiveClient({
+        baseUrl: cfg.apiUrl,
+        publishableKey: cfg.publishableKey,
+        elements: cfg.autoElements,
+        ...(cfg.elementsUrl ? { elementsUrl: cfg.elementsUrl } : {}),
+        checkout: { mode: 'modal', ...(cfg.checkoutBase ? { embedBaseUrl: cfg.checkoutBase } : {}) },
+    }).catch((err) => {
+        console.error('[ticketlayer] Failed to initialise:', err);
+        return null;
+    });
+    w.ticketlayer = { ready };
+    return ready;
+}
+// Manual-use surface on the global (the IIFE's globalName is TicketlayerLive).
+export { createLiveClient, TicketlayerLive };
+// Auto-boot on load.
+void boot();
+//# sourceMappingURL=auto.js.map

package/dist/auto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto.js","sourceRoot":"","sources":["../src/auto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAgB1E,sEAAsE;AACtE,SAAS,UAAU;IACjB,IAAI,OAAO,QAAQ,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,EAAE,GACL,QAAQ,CAAC,aAA0C;QACpD,QAAQ,CAAC,aAAa,CAAoB,8BAA8B,CAAC,CAAC;IAC5E,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IACrB,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC;IACrB,OAAO;QACL,cAAc,EAAE,CAAC,CAAC,cAAc;QAChC,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,YAAY,EAAE,CAAC,CAAC,YAAY;QAC5B,oFAAoF;QACpF,YAAY,EAAE,CAAC,CAAC,QAAQ,KAAK,OAAO;KACrC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI;IAClB,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,MAAM,CAAC,GAAG,MAA+B,CAAC;IAC1C,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,CAAC,CAAC,WAAW,EAAE,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,cAAc;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,iCAAiC;IACzF,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CAAC,2EAA2E,CAAC,CAAC;QAC3F,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,CAAC,CAAC,UAAU,GAAG,IAAI,CAAC;IACpB,MAAM,KAAK,GAAG,gBAAgB,CAAC;QAC7B,OAAO,EAAE,GAAG,CAAC,MAAM;QACnB,cAAc,EAAE,GAAG,CAAC,cAAc;QAClC,QAAQ,EAAE,GAAG,CAAC,YAAY;QAC1B,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;KAC7F,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACf,OAAO,CAAC,KAAK,CAAC,qCAAqC,EAAE,GAAG,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,CAAC,CAAC,WAAW,GAAG,EAAE,KAAK,EAAE,CAAC;IAC1B,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAC/E,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,CAAC;AAE7C,qBAAqB;AACrB,KAAK,IAAI,EAAE,CAAC"}