@seatlayer/server 0.1.0

package/dist/index.js

@@ -0,0 +1,657 @@
+// src/errors.ts
+var SeatLayerError = class extends Error {
+  status;
+  /** Machine-readable code: `body.code ?? body.error`. */
+  code;
+  body;
+  /** Correlation id from `X-Request-ID`. Quote it in support requests. */
+  requestId;
+  constructor(status, body, requestId) {
+    const code = body.code ?? body.error ?? "unknown_error";
+    super(body.message ?? `SeatLayer API error ${status} (${code})`);
+    this.name = "SeatLayerError";
+    this.status = status;
+    this.code = code;
+    this.body = body;
+    this.requestId = requestId;
+  }
+};
+var SeatLayerAuthError = class extends SeatLayerError {
+  constructor(status, body, requestId) {
+    super(status, body, requestId);
+    this.name = "SeatLayerAuthError";
+  }
+  /**
+   * True when the key's mode and the event's mode disagree — the most common
+   * cause of a "works locally, 403s in production" report.
+   */
+  get isModeMismatch() {
+    return this.code === "mode_mismatch";
+  }
+};
+var SeatLayerNotFoundError = class extends SeatLayerError {
+  constructor(status, body, requestId) {
+    super(status, body, requestId);
+    this.name = "SeatLayerNotFoundError";
+  }
+};
+var SeatLayerConflictError = class extends SeatLayerError {
+  /** Per-object conflicts, when the endpoint reports them. */
+  conflicts;
+  constructor(status, body, requestId) {
+    super(status, body, requestId);
+    this.name = "SeatLayerConflictError";
+    this.conflicts = Array.isArray(body.conflicts) ? body.conflicts : [];
+  }
+  /** True when best-available could not find enough free inventory. */
+  get isSoldOut() {
+    return this.body.reason === "sold_out" || this.body.reason === "not_enough_together";
+  }
+};
+var SeatLayerValidationError = class extends SeatLayerError {
+  constructor(status, body, requestId) {
+    super(status, body, requestId);
+    this.name = "SeatLayerValidationError";
+  }
+};
+var SeatLayerRateLimitError = class extends SeatLayerError {
+  retryAfterSeconds;
+  constructor(status, body, requestId, retryAfterSeconds) {
+    super(status, body, requestId);
+    this.name = "SeatLayerRateLimitError";
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+};
+var SeatLayerConnectionError = class extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "SeatLayerConnectionError";
+    this.cause = cause;
+  }
+};
+function errorFromResponse(status, body, requestId, retryAfterSeconds) {
+  if (status === 401 || status === 403) return new SeatLayerAuthError(status, body, requestId);
+  if (status === 404) return new SeatLayerNotFoundError(status, body, requestId);
+  if (status === 409) return new SeatLayerConflictError(status, body, requestId);
+  if (status === 422) return new SeatLayerValidationError(status, body, requestId);
+  if (status === 429) {
+    return new SeatLayerRateLimitError(status, body, requestId, retryAfterSeconds);
+  }
+  return new SeatLayerError(status, body, requestId);
+}
+
+// src/http.ts
+var DEFAULT_BASE_URL = "https://api.seatlayer.io";
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_TIMEOUT_MS = 3e4;
+var IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+function assertValidIdempotencyKey(key) {
+  if (!IDEMPOTENCY_KEY_PATTERN.test(key)) {
+    throw new TypeError(
+      `Invalid Idempotency-Key ${JSON.stringify(key)}: allowed characters are A-Z a-z 0-9 . _ : - and the length must be 1-128.`
+    );
+  }
+}
+function shouldSendIdempotencyKey(method) {
+  return method !== "GET" && method !== "HEAD";
+}
+function isRetryableStatus(status) {
+  return status === 429 || status === 408 || status >= 500 && status < 600;
+}
+function backoffMs(attempt, retryAfterSeconds) {
+  if (retryAfterSeconds !== null) return retryAfterSeconds * 1e3;
+  const ceiling = Math.min(8e3, 250 * 2 ** attempt);
+  return Math.random() * ceiling;
+}
+function parseRetryAfter(response, body) {
+  const header = response.headers.get("retry-after");
+  if (header) {
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0) return seconds;
+  }
+  const field = body.retryAfterSeconds;
+  if (typeof field === "number" && Number.isFinite(field)) return field;
+  return 1;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var HttpClient = class {
+  baseUrl;
+  /** Whether this client is pointed at test-mode or live-mode data. */
+  mode;
+  #secretKey;
+  #maxRetries;
+  #timeoutMs;
+  #fetch;
+  constructor(options) {
+    if (!options.secretKey) {
+      throw new TypeError("A SeatLayer secret key is required.");
+    }
+    if (options.secretKey.startsWith("pk_")) {
+      throw new TypeError(
+        "That is a publishable key. The server SDK needs a secret key (sk_live_\u2026 or sk_test_\u2026)."
+      );
+    }
+    if (!options.secretKey.startsWith("sk_")) {
+      throw new TypeError("A SeatLayer secret key starts with sk_live_ or sk_test_.");
+    }
+    this.#secretKey = options.secretKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.mode = options.secretKey.startsWith("sk_test_") ? "test" : options.secretKey.startsWith("sk_live_") ? "live" : "unknown";
+  }
+  async request(method, path, options = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    const headers = {
+      Authorization: `Bearer ${this.#secretKey}`,
+      Accept: "application/json",
+      "User-Agent": "@seatlayer/server"
+    };
+    if (options.body !== void 0) headers["Content-Type"] = "application/json";
+    if (shouldSendIdempotencyKey(method)) {
+      const key = options.idempotencyKey ?? crypto.randomUUID();
+      assertValidIdempotencyKey(key);
+      headers["Idempotency-Key"] = key;
+    }
+    let lastError;
+    for (let attempt = 0; attempt < this.#maxRetries; attempt++) {
+      const timeout = AbortSignal.timeout(this.#timeoutMs);
+      const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+      let response;
+      try {
+        response = await this.#fetch(url, {
+          method,
+          headers,
+          signal,
+          ...options.body !== void 0 ? { body: JSON.stringify(options.body) } : {}
+        });
+      } catch (cause) {
+        if (options.signal?.aborted) throw cause;
+        lastError = new SeatLayerConnectionError(
+          `Request to ${method} ${path} failed: ${cause?.message ?? "unknown error"}`,
+          cause
+        );
+        if (attempt < this.#maxRetries - 1) {
+          await sleep(backoffMs(attempt, null));
+          continue;
+        }
+        throw lastError;
+      }
+      const requestId = response.headers.get("x-request-id");
+      if (response.ok) {
+        if (response.status === 204) return void 0;
+        const text = await response.text();
+        return text ? JSON.parse(text) : void 0;
+      }
+      const body = await response.json().catch(() => ({}));
+      const retryAfter = parseRetryAfter(response, body);
+      if (isRetryableStatus(response.status) && attempt < this.#maxRetries - 1) {
+        await sleep(backoffMs(attempt, response.status === 429 ? retryAfter : null));
+        continue;
+      }
+      throw errorFromResponse(response.status, body, requestId, retryAfter);
+    }
+    throw lastError ?? new SeatLayerConnectionError("Request failed with no attempts made.", null);
+  }
+  get(path, options) {
+    return this.request("GET", path, options);
+  }
+  post(path, options) {
+    return this.request("POST", path, options);
+  }
+  put(path, options) {
+    return this.request("PUT", path, options);
+  }
+  patch(path, options) {
+    return this.request("PATCH", path, options);
+  }
+  delete(path, options) {
+    return this.request("DELETE", path, options);
+  }
+};
+
+// src/resources/charts.ts
+var Charts = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * One page of charts. Pass `cursor` from the previous page's `nextCursor`;
+   * its absence means the list is exhausted.
+   */
+  list(options = {}) {
+    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 = {}) {
+    let cursor;
+    do {
+      const page = await this.list({ ...options, cursor });
+      for (const chart of page.charts) yield chart;
+      cursor = page.nextCursor;
+    } while (cursor);
+  }
+  create(params, options = {}) {
+    return this.#http.post("/v1/charts", { body: params, idempotencyKey: options.idempotencyKey });
+  }
+  retrieve(chartId) {
+    return this.#http.get(`/v1/charts/${encodeURIComponent(chartId)}`);
+  }
+  /**
+   * Replace a chart document.
+   *
+   * `expectedUpdatedAt` is required by the API for optimistic concurrency and
+   * is not optional here either: without it two concurrent writers silently
+   * overwrite each other, and a seat map is exactly the kind of document where
+   * that loses work. Read it from `retrieve()` immediately before writing.
+   *
+   * The Designer is the authoring surface. Reach for this for bulk programmatic
+   * edits and migrations, not for drawing.
+   */
+  update(chartId, params) {
+    return this.#http.put(`/v1/charts/${encodeURIComponent(chartId)}`, { body: params });
+  }
+  delete(chartId) {
+    return this.#http.delete(`/v1/charts/${encodeURIComponent(chartId)}`);
+  }
+  /** Copy a chart — the usual way to provision a venue from a template. */
+  copy(chartId, options = {}) {
+    return this.#http.post(`/v1/charts/${encodeURIComponent(chartId)}/duplicate`, {
+      idempotencyKey: options.idempotencyKey
+    });
+  }
+  archive(chartId) {
+    return this.#http.post(`/v1/charts/${encodeURIComponent(chartId)}/archive`);
+  }
+  unarchive(chartId) {
+    return this.#http.post(`/v1/charts/${encodeURIComponent(chartId)}/unarchive`);
+  }
+  /** Publish the draft. An event can only be created from a published chart. */
+  publish(chartId) {
+    return this.#http.post(`/v1/charts/${encodeURIComponent(chartId)}/publish`);
+  }
+};
+
+// src/resources/events.ts
+var Events = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * 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 = {}) {
+    return this.#http.get("/v1/events", {
+      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 = {}) {
+    let cursor;
+    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, options = {}) {
+    return this.#http.post("/v1/events", { body: params, idempotencyKey: options.idempotencyKey });
+  }
+  retrieve(eventKey) {
+    return this.#http.get(`/v1/events/${encodeURIComponent(eventKey)}`);
+  }
+  update(eventKey, params) {
+    return this.#http.patch(`/v1/events/${encodeURIComponent(eventKey)}`, { body: params });
+  }
+  delete(eventKey) {
+    return this.#http.delete(`/v1/events/${encodeURIComponent(eventKey)}`);
+  }
+  /** Move a live event onto the latest published version of its chart. */
+  updateChart(eventKey) {
+    return this.#http.post(`/v1/events/${encodeURIComponent(eventKey)}/update-chart`);
+  }
+  /** Stop buyer sales. Existing holds keep their TTL. */
+  close(eventKey) {
+    return this.#http.post(`/v1/events/${encodeURIComponent(eventKey)}/close`);
+  }
+  reopen(eventKey) {
+    return this.#http.post(`/v1/events/${encodeURIComponent(eventKey)}/reopen`);
+  }
+  archive(eventKey) {
+    return this.#http.post(`/v1/events/${encodeURIComponent(eventKey)}/archive`);
+  }
+  /** Read the checkout window (ms) buyers get for this event. */
+  retrieveHoldTtl(eventKey) {
+    return this.#http.get(`/v1/events/${encodeURIComponent(eventKey)}/hold-ttl`);
+  }
+  updateHoldTtl(eventKey, holdTtlMs) {
+    return this.#http.post(`/v1/events/${encodeURIComponent(eventKey)}/hold-ttl`, {
+      body: { holdTtlMs }
+    });
+  }
+  retrieveReport(eventKey) {
+    return this.#http.get(`/v1/events/${encodeURIComponent(eventKey)}/report`);
+  }
+  retrieveLog(eventKey) {
+    return this.#http.get(`/v1/events/${encodeURIComponent(eventKey)}/log`);
+  }
+};
+
+// src/resources/inventory.ts
+var Inventory = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  #path(eventKey, suffix) {
+    return `/v1/events/${encodeURIComponent(eventKey)}${suffix}`;
+  }
+  hold(eventKey, params, options = {}) {
+    return this.#http.post(this.#path(eventKey, "/hold"), {
+      body: params,
+      idempotencyKey: options.idempotencyKey
+    });
+  }
+  /**
+   * Ask us to pick the best free objects and hold them.
+   *
+   * The picker is the same one the buyer widget uses, so a phone order and a
+   * web order get the same answer for the same inventory. `qty` above the
+   * server cap is clamped, not rejected.
+   */
+  holdBestAvailable(eventKey, params, options = {}) {
+    return this.#http.post(this.#path(eventKey, "/best-available"), {
+      body: params,
+      idempotencyKey: options.idempotencyKey
+    });
+  }
+  /**
+   * Pick and book in one call — the box-office shape, where payment is already
+   * taken and there is no buyer session to hold against.
+   *
+   * Prefer this over holdBestAvailable-then-book for that case: a failure
+   * between the two calls would strand inventory until the TTL expired.
+   */
+  bookBestAvailable(eventKey, params, options = {}) {
+    return this.#http.post(this.#path(eventKey, "/best-available-book"), {
+      body: params,
+      idempotencyKey: options.idempotencyKey
+    });
+  }
+  /**
+   * 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, params) {
+    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, holdId) {
+    return this.#http.get(this.#path(eventKey, `/holds/${encodeURIComponent(holdId)}`));
+  }
+  /** Free a hold early. Requires both the labels and the hold id. */
+  release(eventKey, params) {
+    return this.#http.post(this.#path(eventKey, "/release"), { body: params });
+  }
+  book(eventKey, params, options = {}) {
+    return this.#http.post(this.#path(eventKey, "/book"), {
+      body: params,
+      idempotencyKey: options.idempotencyKey
+    });
+  }
+  boxOfficeBook(eventKey, params, options = {}) {
+    return this.#http.post(this.#path(eventKey, "/box-book"), {
+      body: params,
+      idempotencyKey: options.idempotencyKey
+    });
+  }
+  /** Reverse a booking. Requires a key with cancel authority. */
+  unbook(eventKey, params) {
+    return this.#http.post(this.#path(eventKey, "/unbook"), { body: params });
+  }
+  /** Hold inventory back from sale (house seats, holds for production). */
+  block(eventKey, params) {
+    return this.#http.post(this.#path(eventKey, "/block"), { body: params });
+  }
+  unblock(eventKey, params) {
+    return this.#http.post(this.#path(eventKey, "/unblock"), { body: params });
+  }
+  unblockAll(eventKey) {
+    return this.#http.post(this.#path(eventKey, "/unblock-all"));
+  }
+  retrieveAvailability(eventKey) {
+    return this.#http.get(this.#path(eventKey, "/availability"));
+  }
+  updateAvailability(eventKey, params) {
+    return this.#http.post(this.#path(eventKey, "/availability"), { body: params });
+  }
+};
+
+// src/resources/sessions.ts
+var Sessions = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * Mint a manage-session token for the control room.
+   *
+   * `capabilities` is required here even though the API defaults it. That
+   * default grants all four — including `event:cancel`, which un-books paid
+   * inventory. Granting the ability to reverse sales by forgetting an argument
+   * is not a default worth inheriting, so this SDK makes you say it.
+   *
+   * `allowedOrigin` must be an https origin; the token is bound to it.
+   */
+  // `async` so the guard below rejects rather than throwing synchronously —
+  // a sync throw from a promise-returning method escapes `.catch()` and
+  // surfaces as an unhandled error in the caller's request handler.
+  async createManageSession(eventKey, params) {
+    if (!params.capabilities?.length) {
+      throw new TypeError(
+        'capabilities is required: pass the smallest set the page needs, e.g. ["event:view"]. Omitting it server-side grants event:cancel, which can reverse paid bookings.'
+      );
+    }
+    return this.#http.post(`/v1/events/${encodeURIComponent(eventKey)}/manage-sessions`, {
+      body: params
+    });
+  }
+  /** Revoke a manage token before it expires (staff logout, permission change). */
+  revokeManageSession(eventKey, sessionId) {
+    return this.#http.delete(
+      `/v1/events/${encodeURIComponent(eventKey)}/manage-sessions/${encodeURIComponent(sessionId)}`
+    );
+  }
+  /**
+   * Mint a designer-session token so an organiser can edit a chart inside your
+   * own UI. Requires a chartId that already exists — create or copy one first.
+   */
+  createDesignerSession(params) {
+    return this.#http.post("/v1/designer/sessions", { body: params });
+  }
+  revokeDesignerSession(sessionId) {
+    return this.#http.delete(`/v1/designer/sessions/${encodeURIComponent(sessionId)}`);
+  }
+};
+
+// src/resources/webhooks.ts
+var Webhooks = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  list() {
+    return this.#http.get("/v1/webhooks");
+  }
+  create(params) {
+    return this.#http.post("/v1/webhooks", { body: params });
+  }
+  update(webhookId, params) {
+    return this.#http.patch(`/v1/webhooks/${encodeURIComponent(webhookId)}`, { body: params });
+  }
+  delete(webhookId) {
+    return this.#http.delete(`/v1/webhooks/${encodeURIComponent(webhookId)}`);
+  }
+  listDeliveries(webhookId) {
+    return this.#http.get(`/v1/webhooks/${encodeURIComponent(webhookId)}/deliveries`);
+  }
+};
+
+// src/resources/workspaces.ts
+var Workspaces = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  list() {
+    return this.#http.get("/v1/workspaces");
+  }
+  create(params, options = {}) {
+    return this.#http.post("/v1/workspaces", { body: params, idempotencyKey: options.idempotencyKey });
+  }
+  retrieve(workspaceId) {
+    return this.#http.get(`/v1/workspaces/${encodeURIComponent(workspaceId)}`);
+  }
+  /**
+   * Rename, re-reference, or disable a workspace.
+   *
+   * The organisation's default workspace cannot be disabled — the API answers
+   * 409 `default_workspace_required`. Promote another one first.
+   */
+  update(workspaceId, params) {
+    return this.#http.patch(`/v1/workspaces/${encodeURIComponent(workspaceId)}`, { body: params });
+  }
+};
+
+// src/webhooks-verify.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var WebhookVerificationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WebhookVerificationError";
+  }
+};
+function verifyWebhook(options) {
+  const { payload, signature, secret } = options;
+  if (!secret) throw new WebhookVerificationError("A webhook signing secret is required.");
+  if (!signature) {
+    throw new WebhookVerificationError("Missing X-SeatLayer-Signature header.");
+  }
+  const [scheme, provided] = signature.split("=");
+  if (scheme !== "sha256" || !provided) {
+    throw new WebhookVerificationError(
+      `Unsupported signature format ${JSON.stringify(signature)}; expected "sha256=<hex>".`
+    );
+  }
+  const body = typeof payload === "string" ? Buffer.from(payload, "utf8") : Buffer.from(payload);
+  const expected = createHmac("sha256", secret).update(body).digest("hex");
+  const a = Buffer.from(expected, "hex");
+  const b = Buffer.from(provided, "hex");
+  if (a.length !== b.length || !timingSafeEqual(a, b)) {
+    throw new WebhookVerificationError("Webhook signature did not match.");
+  }
+  try {
+    return JSON.parse(body.toString("utf8"));
+  } catch (cause) {
+    throw new WebhookVerificationError(
+      `Signature verified but the body is not valid JSON: ${cause.message}`
+    );
+  }
+}
+
+// src/index.ts
+var SeatLayer = class {
+  charts;
+  events;
+  inventory;
+  sessions;
+  webhooks;
+  workspaces;
+  /** `test` or `live`, derived from the key prefix. */
+  mode;
+  #http;
+  constructor(options) {
+    const resolved = typeof options === "string" ? { secretKey: options } : options;
+    this.#http = new HttpClient(resolved);
+    this.mode = this.#http.mode;
+    this.charts = new Charts(this.#http);
+    this.events = new Events(this.#http);
+    this.inventory = new Inventory(this.#http);
+    this.sessions = new Sessions(this.#http);
+    this.webhooks = new Webhooks(this.#http);
+    this.workspaces = new Workspaces(this.#http);
+  }
+  /** Dependency-aware readiness probe. Unauthenticated upstream. */
+  ready() {
+    return this.#http.get("/health/ready");
+  }
+  /**
+   * Escape hatch for surface this SDK does not wrap yet. Carries the same auth,
+   * retry, idempotency and error mapping as everything else.
+   */
+  request(method, path, options) {
+    return this.#http.request(method, path, options);
+  }
+};
+var index_default = SeatLayer;
+export {
+  SeatLayer,
+  SeatLayerAuthError,
+  SeatLayerConflictError,
+  SeatLayerConnectionError,
+  SeatLayerError,
+  SeatLayerNotFoundError,
+  SeatLayerRateLimitError,
+  SeatLayerValidationError,
+  WebhookVerificationError,
+  index_default as default,
+  verifyWebhook
+};
+//# sourceMappingURL=index.js.map