@ticketlayer/backstage 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,148 @@
+# @ticketlayer/backstage
+
+TypeScript client for the Backstage API: every operation of the contract,
+generated from `backstage-api/openapi.json`, plus the `embed` subpath that
+mounts Backstage widgets in a partner's own page.
+
+## Install
+
+The package is published as `@ticketlayer/backstage`. Until the first
+release runs, the only version on npm is the old name
+`@ticketlayer/backstage-sdk` 0.1.1; our own apps use a `file:` link to this
+repository meanwhile. See the vault page `architecture/sdk-architecture.md`
+for what is on npm.
+
+```bash
+npm install @ticketlayer/backstage
+```
+
+## Client
+
+```ts
+import { BackstageClient } from '@ticketlayer/backstage';
+
+// Staff app (Next.js with Stagedoor OAuth): cookie mode, org from the subdomain
+const backstage = new BackstageClient({ baseUrl: 'https://api.staging.t9r.dev', authMode: 'cookie' });
+
+// Server or native app: bearer mode with a staff JWT, an organisation API key
+// (tlak_...), an embed session or a device token; the org must be named
+const server = new BackstageClient({
+  baseUrl: 'https://api.staging.t9r.dev',
+  authMode: 'bearer',
+  accessToken: () => currentToken,   // a resolver is read on every request
+  organisationSlug: 'rowbot',        // sent as X-Ticketlayer-Org
+});
+
+const events = await server.events.list();
+```
+
+Every request carries `TL-Version` (the dated API version the client was
+generated against) and JSend responses are unwrapped to their `data`. Errors
+are `BackstageAPIError` with `code` and `statusCode`.
+
+## Develop
+
+```bash
+npm ci
+npm run generate:client   # openapi.json -> src/generated/types.ts
+npm run build             # tsc -> dist/
+npm test                  # node --test against dist/
+```
+
+`src/client.ts` is generated by `backstage-sdk-tooling` (`tt sdk local`);
+do not edit it by hand. Releases are driven by changesets and
+`.github/workflows/release.yml`, which publishes to npm with provenance once
+`NPM_TOKEN` is set. `CLAUDE.md` is the working agreement.
+
+## Embedding Backstage widgets in your app
+
+`@ticketlayer/backstage/embed` mounts Backstage widgets (the events list, an
+event editor, the orders list, an order) in an iframe on your own page. Your
+users never log in to Backstage: your server mints an **embed session** for
+one account with your organisation API key, and the widget runs as that
+account with the scopes you chose. The subpath is framework-free and is not
+loaded by the main entry.
+
+The flow, as Rowbot uses it (one Ticketlayer organisation, one account per
+club):
+
+1. **Server: mint a session.** With the organisation API key, call
+   `POST /embed/sessions` for the club's account. Keep the API key on the
+   server; only the short-lived session token reaches the browser.
+
+   ```ts
+   import { BackstageClient } from '@ticketlayer/backstage';
+
+   const backstage = new BackstageClient({
+     baseUrl: 'https://api.staging.t9r.dev',
+     accessToken: process.env.TICKETLAYER_ORG_API_KEY,
+     organisationSlug: 'rowbot',
+   });
+
+   // e.g. GET /api/ticketing/session on your server
+   const { token, expiresAt } = await backstage.embed.createSession({
+     accountId: club.ticketlayerAccountId,
+     scopes: ['events.read', 'events.write', 'orders.read'],
+   });
+   ```
+
+2. **Page: mount a widget.** Hand the token to the loader; it builds
+   `${baseUrl}/embed/<widget>?session=...&parent_origin=<your origin>`, accepts
+   messages only from the Backstage origin, and sizes the frame to its content.
+
+   ```ts
+   import { createBackstageEmbed } from '@ticketlayer/backstage/embed';
+
+   const embed = createBackstageEmbed({
+     baseUrl: 'https://backstage.staging.t9r.dev',
+     session: token,
+     // Called when the widget reports the session expired: mint a new one.
+     sessionProvider: async () => (await fetch('/api/ticketing/session').then((r) => r.json())).token,
+     onNavigate: (widget, params) => history.replaceState(null, '', `/ticketing/${widget}/${params.id ?? ''}`),
+     onEvent: (name, payload) => console.log(name, payload), // event.created, order.refund_requested, ...
+     onError: (err) => console.warn(err.code, err.message),
+   });
+
+   embed.mount(document.getElementById('ticketing')!, { widget: 'events' });
+   // later: embed.navigate('order', { id: 'ord_123' }); embed.unmount();
+   ```
+
+3. **Refresh on expiry.** Sessions are short-lived. When the widget gets a 401
+   (or its token's `exp` passes) it posts `tl:session-expired`; the loader calls
+   your `sessionProvider`, posts the new token back as `tl:session`, and the
+   widget resumes where it was. Without a provider, `onSessionExpired` fires
+   and the widget shows its expired state.
+
+Widgets and params: `events` (`{ action?: 'new' }`), `event`
+(`{ id, tab?: 'details' | 'tickets' | 'occurrences' }`), `orders`, `order`
+(`{ id }`). Actions the session's scopes do not allow (for example editing
+with only `events.read`) are hidden in the widget.
+
+Messages from the widget (all carry `version: 1`): `tl:ready`, `tl:height`
+`{ height }`, `tl:navigate` `{ widget, params }`, `tl:event` `{ name, payload }`,
+`tl:session-expired`, `tl:error` `{ code, message }`. The only inbound message
+is `tl:session` `{ token }`. The Backstage deployment must list your origin in
+its `EMBED_FRAME_ANCESTORS` for the frame to load.
+
+React example (the loader owns the iframe; React owns the container):
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { createBackstageEmbed, type EmbedWidgetTarget } from '@ticketlayer/backstage/embed';
+
+export function BackstageWidget({ token, target }: { token: string; target: EmbedWidgetTarget }) {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!ref.current) return;
+    const embed = createBackstageEmbed({
+      baseUrl: 'https://backstage.staging.t9r.dev',
+      session: token,
+      sessionProvider: () => fetch('/api/ticketing/session').then((r) => r.json()).then((s) => s.token),
+    });
+    embed.mount(ref.current, target);
+    return () => embed.unmount();
+  }, [token, target]);
+  return <div ref={ref} />;
+}
+// <BackstageWidget token={token} target={{ widget: 'order', params: { id: 'ord_123' } }} />
+```