feat: extendHold and cursor pagination

Tracks two new API capabilities.

extendHold keeps a server-side hold alive past the checkout window, for
invoiced and phone orders. Releasing and re-holding hands the seats to
whoever is racing for them in between, so this is the call you want.

list() now takes limit/cursor, and listAll() pages transparently as an
async iterator — deliberately not an array, since paginating exists to
stop holding an unbounded list in memory and returning one would hand
that problem straight back. listAll() over events also drops the
per-event availability fanout, which is exactly the cost pagination was
added to avoid.

35 tests.

Author: navin10sharma

CHANGELOG.md

@@ -4,6 +4,9 @@
 
 First release of the SeatLayer Node server SDK.
 
+- `inventory.extendHold` — keep a server-side hold alive past the checkout window.
+- `charts.list` / `events.list` take `limit` and `cursor`; `listAll()` pages transparently as an
+  async iterator and skips the per-event availability fanout.
 - `SeatLayer` client with secret-key auth, per-attempt timeouts, and a typed escape hatch.
 - Resources: `charts`, `events`, `inventory`, `sessions`, `webhooks`, `workspaces`.
 - Automatic `Idempotency-Key` on every mutation, reused across retries so a retried

README.md

@@ -71,6 +71,47 @@ await seatlayer.inventory.bookBestAvailable(eventKey, { qty: 2, bookingRef: 'pho
 await seatlayer.inventory.boxOfficeBook(eventKey, { labels: ['A-1', 'A-2'], bookingRef: 'comp-14' });
 ```
 
+## Listing and pagination
+
+`list()` returns one page plus a `nextCursor`. When you want everything, `listAll()` pages for you
+and yields as it goes — an async iterator rather than an array, because the point of paginating is
+to *not* hold an unbounded list in memory.
+
+```ts
+// One page, your own paging.
+const page = await seatlayer.events.list({ limit: 50 });
+page.events;      // EventMeta[]
+page.nextCursor;  // undefined once exhausted
+
+// Or let the SDK walk it.
+for await (const event of seatlayer.events.listAll()) {
+  await sync(event);
+}
+```
+
+Listing events includes live availability `counts` by default, which costs the server one
+round-trip **per event**. `listAll()` turns them off automatically — walking a whole catalogue is
+exactly when you don't want that — and you can control it explicitly:
+
+```ts
+await seatlayer.events.list({ limit: 50, counts: false });
+```
+
+## Keeping a hold alive
+
+When an order takes longer than the checkout window — an invoice, a phone sale — extend rather than
+release and re-hold. Releasing first hands the seats to whoever is racing for them in between.
+
+```ts
+try {
+  await seatlayer.inventory.extendHold(eventKey, { holdId, ttlMs: 10 * 60_000 });
+} catch (error) {
+  if (error instanceof SeatLayerConflictError) {
+    // Gone, expired, or at its renewal cap — the buyer has to re-pick.
+  }
+}
+```
+
 ## Embedding the control room
 
 Your secret key never reaches a browser. Mint a scoped token instead and hand that to the widget.
@@ -116,9 +157,9 @@ app.post('/webhooks/seatlayer', express.raw({ type: 'application/json' }), (req,
       secret: process.env.SEATLAYER_WEBHOOK_SECRET!,
     });
 
-    // Deliveries are signed over the body only — there is no timestamp header
-    // and no tolerance window, so a captured delivery stays valid. Deduplicate
-    // on occurrenceId; this is your replay protection.
+    // The signed body carries `at`, but nothing enforces a freshness window,
+    // so a captured delivery stays valid indefinitely. Deduplicate on
+    // occurrenceId — this is your replay protection, not an optimisation.
     if (await alreadyProcessed(event.occurrenceId)) return res.sendStatus(200);
 
     await handle(event);
@@ -191,9 +232,9 @@ await seatlayer.request('POST', '/v1/events/ev_1/some-new-route', { body: { …
 
 | Resource | Methods |
 | --- | --- |
-| `charts` | `list` `create` `retrieve` `update` `delete` `copy` `archive` `unarchive` `publish` |
-| `events` | `list` `create` `retrieve` `update` `delete` `updateChart` `close` `reopen` `archive` `retrieveHoldTtl` `updateHoldTtl` `retrieveReport` `retrieveLog` |
-| `inventory` | `hold` `holdBestAvailable` `bookBestAvailable` `retrieveHold` `release` `book` `boxOfficeBook` `unbook` `block` `unblock` `unblockAll` `retrieveAvailability` `updateAvailability` |
+| `charts` | `list` `listAll` `create` `retrieve` `update` `delete` `copy` `archive` `unarchive` `publish` |
+| `events` | `list` `listAll` `create` `retrieve` `update` `delete` `updateChart` `close` `reopen` `archive` `retrieveHoldTtl` `updateHoldTtl` `retrieveReport` `retrieveLog` |
+| `inventory` | `hold` `holdBestAvailable` `bookBestAvailable` `extendHold` `retrieveHold` `release` `book` `boxOfficeBook` `unbook` `block` `unblock` `unblockAll` `retrieveAvailability` `updateAvailability` |
 | `sessions` | `createManageSession` `revokeManageSession` `createDesignerSession` `revokeDesignerSession` |
 | `webhooks` | `list` `create` `update` `delete` `listDeliveries` |
 | `workspaces` | `list` `create` `retrieve` `update` |

src/resources/charts.ts

@@ -1,6 +1,21 @@
 import type { HttpClient } from '../http.js';
 import type { Chart, ChartMeta } from '../types.js';
 
+export interface ChartListOptions {
+  workspaceId?: string;
+  externalRef?: string;
+  archived?: boolean;
+  /** Page size. Clamped server-side; asking for more is not an error. */
+  limit?: number;
+  cursor?: string;
+}
+
+export interface ChartPage {
+  charts: ChartMeta[];
+  /** Absent once the list is exhausted. */
+  nextCursor?: string;
+}
+
 /**
  * Charts are the seat-map definitions events are created from.
  *
@@ -16,16 +31,40 @@ export class Charts {
     this.#http = http;
   }
 
-  list(options: { workspaceId?: string; externalRef?: string; archived?: boolean } = {}): Promise<{ charts: ChartMeta[] }> {
+  /**
+   * One page of charts. Pass `cursor` from the previous page's `nextCursor`;
+   * its absence means the list is exhausted.
+   */
+  list(options: ChartListOptions = {}): Promise<ChartPage> {
     return this.#http.get('/v1/charts', {
       query: {
         workspaceId: options.workspaceId,
         externalRef: options.externalRef,
+        limit: options.limit,
+        cursor: options.cursor,
         ...(options.archived ? { archived: '1' } : {}),
       },
     });
   }
 
+  /**
+   * Every chart, paging transparently.
+   *
+   * An async iterator rather than an array: the whole point of paginating was
+   * to stop loading an unbounded list into memory, and returning `ChartMeta[]`
+   * would hand that problem straight back to the caller.
+   *
+   *   for await (const chart of seatlayer.charts.listAll()) { … }
+   */
+  async *listAll(options: Omit<ChartListOptions, 'cursor'> = {}): AsyncGenerator<ChartMeta> {
+    let cursor: string | undefined;
+    do {
+      const page = await this.list({ ...options, cursor });
+      for (const chart of page.charts) yield chart;
+      cursor = page.nextCursor;
+    } while (cursor);
+  }
+
   create(params: {
     name: string;
     doc?: Record<string, unknown>;

src/resources/events.ts

@@ -1,19 +1,65 @@
 import type { HttpClient } from '../http.js';
 import type { EventMeta } from '../types.js';
 
+export interface EventListOptions {
+  workspaceId?: string;
+  externalRef?: string;
+  /** Page size. Clamped server-side; asking for more is not an error. */
+  limit?: number;
+  cursor?: string;
+  /** Include live availability counts. One server round-trip per event. */
+  counts?: boolean;
+}
+
+export interface EventPage {
+  events: EventMeta[];
+  /** Absent once the list is exhausted. */
+  nextCursor?: string;
+}
+
 export class Events {
   #http: HttpClient;
 
   constructor(http: HttpClient) {
     this.#http = http;
   }
 
-  list(options: { workspaceId?: string; externalRef?: string } = {}): Promise<{ events: EventMeta[] }> {
+  /**
+   * One page of events. Pass `cursor` from the previous page's `nextCursor`.
+   *
+   * Live availability `counts` cost one round-trip per event server-side. They
+   * are included by default because most callers want them; pass
+   * `counts: false` when paging a whole catalogue, where you almost certainly
+   * do not.
+   */
+  list(options: EventListOptions = {}): Promise<EventPage> {
     return this.#http.get('/v1/events', {
-      query: { workspaceId: options.workspaceId, externalRef: options.externalRef },
+      query: {
+        workspaceId: options.workspaceId,
+        externalRef: options.externalRef,
+        limit: options.limit,
+        cursor: options.cursor,
+        ...(options.counts === false ? { counts: '0' } : {}),
+      },
     });
   }
 
+  /**
+   * Every event, paging transparently. Defaults to `counts: false` — you are
+   * walking the whole list, so per-event availability is rarely what you want
+   * and always what it costs.
+   *
+   *   for await (const event of seatlayer.events.listAll()) { … }
+   */
+  async *listAll(options: Omit<EventListOptions, 'cursor'> = {}): AsyncGenerator<EventMeta> {
+    let cursor: string | undefined;
+    do {
+      const page = await this.list({ counts: false, ...options, cursor });
+      for (const event of page.events) yield event;
+      cursor = page.nextCursor;
+    } while (cursor);
+  }
+
   create(params: {
     chartId: string;
     name?: string;

src/resources/inventory.ts

@@ -74,6 +74,22 @@ export class Inventory {
     });
   }
 
+  /**
+   * Push an active hold's expiry out by a fresh window before it lapses.
+   *
+   * Use this rather than release-and-re-hold when an order is taking longer
+   * than the checkout window — invoiced sales, a phone order on hold. Releasing
+   * first hands the seats to whoever is racing for them in between. The server
+   * clamps the window and the DO caps how many times one hold can be renewed;
+   * a hold that is gone, expired, or at its cap answers 409 `cannot_extend`.
+   */
+  extendHold(eventKey: string, params: {
+    holdId: string;
+    ttlMs?: number;
+  }): Promise<HoldResult> {
+    return this.#http.post(this.#path(eventKey, '/extend'), { body: params });
+  }
+
   /** Authoritative items and prices for a hold. Charge from this, not the browser. */
   retrieveHold(eventKey: string, holdId: string): Promise<{ items: HoldLineItem[]; expiresAt: number; currency: string }> {
     return this.#http.get(this.#path(eventKey, `/holds/${encodeURIComponent(holdId)}`));

test/client.test.ts

@@ -205,3 +205,58 @@ describe('charts', () => {
     expect(JSON.parse(call(0).body).expectedUpdatedAt).toBe(1234);
   });
 });
+
+describe('pagination', () => {
+  it('walks every page with listAll and stops when the cursor runs out', async () => {
+    const { sdk, calls } = client([
+      { status: 200, body: { charts: [{ id: 'c_1' }, { id: 'c_2' }], nextCursor: 'cur_1' } },
+      { status: 200, body: { charts: [{ id: 'c_3' }] } },
+    ]);
+
+    const seen: string[] = [];
+    for await (const chart of sdk.charts.listAll({ limit: 2 })) seen.push(chart.id);
+
+    expect(seen).toEqual(['c_1', 'c_2', 'c_3']);
+    expect(calls).toHaveLength(2);
+    // Absent nextCursor terminates — a caller looping on it cannot spin forever.
+    expect(String(calls[1]!.url)).toContain('cursor=cur_1');
+  });
+
+  it('does not ask for per-event counts when walking the whole catalogue', async () => {
+    // Counts cost a server round-trip PER EVENT, which is exactly the cost
+    // pagination was added to avoid.
+    const { sdk, call } = client([{ status: 200, body: { events: [] } }]);
+    for await (const _ of sdk.events.listAll()) { /* drain */ }
+    expect(call(0).url).toContain('counts=0');
+  });
+
+  it('keeps counts on a single explicit page', async () => {
+    const { sdk, call } = client([{ status: 200, body: { events: [] } }]);
+    await sdk.events.list({ limit: 10 });
+    expect(call(0).url).not.toContain('counts=0');
+  });
+
+  it('passes limit and cursor through verbatim', async () => {
+    const { sdk, call } = client([{ status: 200, body: { charts: [] } }]);
+    await sdk.charts.list({ limit: 25, cursor: 'abc' });
+    expect(call(0).url).toContain('limit=25');
+    expect(call(0).url).toContain('cursor=abc');
+  });
+});
+
+describe('extendHold', () => {
+  it('posts the hold id to the extend route', async () => {
+    const { sdk, call } = client([{ status: 200, body: { ok: true, expiresAt: 123 } }]);
+    await sdk.inventory.extendHold('ev_1', { holdId: 'h_9', ttlMs: 600_000 });
+
+    expect(call(0).url).toBe('https://api.seatlayer.io/v1/events/ev_1/extend');
+    expect(JSON.parse(call(0).body)).toEqual({ holdId: 'h_9', ttlMs: 600_000 });
+  });
+
+  it('surfaces a spent hold as a conflict, not a generic failure', async () => {
+    const { sdk } = client([{ status: 409, body: { error: 'cannot_extend', reason: 'expired' } }]);
+    const error = await sdk.inventory.extendHold('ev_1', { holdId: 'h_9' }).catch((e) => e);
+    expect(error).toBeInstanceOf(SeatLayerConflictError);
+    expect(error.code).toBe('cannot_extend');
+  });
+});