@seatlayer/js 0.10.2 → 0.12.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { PickerSeat, SeatHoverDetails } from '@seatlayer/core';
-export { SeatHoverDetails } from '@seatlayer/core';
+import { PickerSeat, SeatHoverDetails, ChartDoc, ChartTheme, ExpandedSeat } from '@seatlayer/core';
+export { ExpandedSeat, SeatHoverDetails } from '@seatlayer/core';
 
 /**
  * Minimal client for the public embed surface of workers/api (the `/pub/*`
@@ -575,4 +575,450 @@ declare class SeatPicker {
     destroy(): void;
 }
 
-export { ApiError, type BestAvailableResult, type CheckoutHandoff, type CheckoutLineItem, EmbeddedDesigner, type EmbeddedDesignerEventType, type EmbeddedDesignerMessage, type EmbeddedDesignerOptions, type GAAreaAvailability, type HoldConflict, type HoldLineItem, type HoldResult, SeatPicker, type SeatPickerOptions, type SeatPickerTheme, SeatingChart, type SeatingChartOptions, type SelectedSeat };
+/**
+ * Organizer manage-surface client for workers/api (the `/v1/events/:key/*`
+ * inventory routes + the public realtime channel). Companion to api.ts (the
+ * buyer `/pub/*` client) — kept separate because the manage surface is
+ * token-authed (Bearer) and cross-origin from the CMS:
+ *
+ *   - Writes + reports send `Authorization: Bearer <token>` where the token is
+ *     a short-lived, event-scoped organizer manage token (`mse_…`, minted by
+ *     NestJS) OR a tenant secret key (`sk_…`). Both are accepted by the worker's
+ *     `eitherAuth` on block / unblock / unblock-all / unbook / hold-ttl / report
+ *     / log. The Authorization header also exempts the call from the worker's
+ *     cookie-CSRF gate, so no extra client header is needed.
+ *   - `credentials: 'omit'` — there is no session cookie; the CMS runs
+ *     cross-origin. The worker's credentialed CORS still echoes the CMS origin.
+ *   - Realtime read (`/pub/events/:key/subscribe`, `/objects`, `/chart`) is
+ *     PUBLIC (wildcard CORS, no token) — the live board subscribes with no auth.
+ *
+ * `box-book` is intentionally omitted for M1 (box office ships in M2, and the
+ * route is still session-only server-side).
+ */
+
+declare class ManageApiError extends Error {
+    status: number;
+    code?: string;
+    /** Present when a block/unbook 409s because seats were just taken. */
+    conflicts?: {
+        label: string;
+        reason?: string;
+    }[];
+    constructor(status: number, message: string, code?: string, conflicts?: {
+        label: string;
+        reason?: string;
+    }[]);
+}
+interface ReportByStatus {
+    free: number;
+    held: number;
+    booked: number;
+    not_for_sale: number;
+}
+interface ReportCategoryRow {
+    category: string;
+    total: number;
+    free: number;
+    held: number;
+    booked: number;
+    not_for_sale: number;
+    /** Exact sum of booked unit_price snapshots, in major currency units. */
+    bookedRevenue: number;
+}
+interface ReportCategoryMeta {
+    key: string;
+    label: string;
+    color: string;
+    price: number;
+}
+interface ReportResult {
+    report: {
+        byStatus: ReportByStatus;
+        byCategory: ReportCategoryRow[];
+        bySection?: ControlRoomSectionMetric[];
+    };
+    event: {
+        key: string;
+        name: string;
+        seatTotal: number;
+        currency?: string;
+    };
+    categories: ReportCategoryMeta[];
+}
+interface ControlRoomSectionMetric {
+    sectionId: string;
+    sectionLabel: string;
+    zoneId: string | null;
+    total: number;
+    free: number;
+    held: number;
+    booked: number;
+    not_for_sale: number;
+    bookedRevenue: number;
+}
+interface ControlRoomSnapshot {
+    version: number;
+    currency: string;
+    totals: {
+        free: number;
+        held: number;
+        booked: number;
+        blocked: number;
+    };
+    revenue: {
+        gross: number;
+        bySection: ControlRoomSectionMetric[];
+    };
+    velocity: {
+        windowMinutes: number;
+        bySection: Array<{
+            sectionId: string;
+            netBooked: number;
+            grossRevenue: number;
+            previousNetBooked: number;
+            trend: 'rising' | 'steady' | 'cooling';
+        }>;
+    };
+    presence: {
+        shoppingSessions: number;
+        activeHolds: number;
+    };
+    event: {
+        key: string;
+        name: string;
+        seatTotal: number;
+        currency?: string;
+    };
+}
+interface LogEntry {
+    id: number;
+    at: number;
+    action: string;
+    labels: string[];
+    ref: string | null;
+}
+interface LogPage {
+    entries: LogEntry[];
+    nextBefore: number | null;
+}
+interface PubObjectsResult {
+    /** Every non-free seat's status keyed by label (free seats omitted). */
+    seats: Record<string, string>;
+    hidden?: string[];
+    closed?: string[];
+    updatedAt: number;
+}
+interface PubChartResult {
+    event: {
+        key: string;
+        name: string;
+        status?: string;
+        venue?: string | null;
+        startsAt?: number | null;
+        currency?: string;
+        mode?: string;
+    };
+    doc: ChartDoc;
+}
+/**
+ * Bound to one apiBase + one event-scoped token. Rebuild (or `setToken`) when a
+ * token is re-minted on 401.
+ */
+declare class ManageApi {
+    private base;
+    private token;
+    constructor(apiBase: string, token: string);
+    /** Swap the Bearer token in place (SeatManager re-mints on 401). */
+    setToken(token: string): void;
+    private auth;
+    private pub;
+    chart(key: string): Promise<PubChartResult>;
+    objects(key: string): Promise<PubObjectsResult>;
+    socketUrl(key: string): string;
+    /** Take FREE seats off sale in one batched call. Optional `releaseAt` (epoch
+     *  ms, future) auto-returns them to sale; `reason` tags the block (M3 uses it).
+     *  Throws ManageApiError 409 (conflicts) if any seat was just taken. */
+    block(key: string, labels: string[], opts?: {
+        releaseAt?: number;
+        reason?: string;
+    }): Promise<{
+        ok: true;
+        blocked: string[];
+    }>;
+    /** Return specific blocked seats to sale (one batched call). */
+    unblock(key: string, labels: string[]): Promise<{
+        ok: true;
+        unblocked: string[];
+    }>;
+    /** Return every blocked seat to sale; resolves with the freed count. */
+    unblockAll(key: string): Promise<{
+        ok: true;
+        freed: number;
+    }>;
+    /** Cancel bookings — return BOOKED seats to free (credit not refunded).
+     *  Guarded by the original booking reference. */
+    unbook(key: string, labels: string[], bookingRef: string): Promise<{
+        ok: true;
+        unbooked: string[];
+    }>;
+    /** Set (ms, clamped 1–60 min server-side) or clear (null) the hold TTL. */
+    setHoldTtl(key: string, holdTtlMs: number | null): Promise<{
+        ok: true;
+        holdTtlMs: number | null;
+    }>;
+    report(key: string): Promise<ReportResult>;
+    controlRoom(key: string, windowMinutes?: number): Promise<ControlRoomSnapshot>;
+    log(key: string, opts?: {
+        limit?: number;
+        before?: number;
+    }): Promise<LogPage>;
+    /** CSV report as a Blob (Bearer auth can't ride a plain <a href>). Host builds
+     *  an object URL for download. */
+    reportCsv(key: string): Promise<Blob>;
+}
+
+/**
+ * SeatManager — the organizer manage surface, packaged for the SDK.
+ *
+ * Productizes the SeatLayer dashboard's ManageEventPage into a framework-
+ * agnostic class (mirrors how SeatPicker productized the buyer flow). It mounts
+ * the shared engine in `manageMode`, subscribes to the event's realtime channel
+ * and drives three control-room tools on one persistent canvas:
+ *
+ *   - **view**  — a live board: realtime seat repaint (flash on hold/book),
+ *                 live KPI tallies + gross revenue, and a streaming activity
+ *                 feed derived from the delta stream + audit log. Read-only.
+ *   - **inspect** — select one seat to read its live inventory context.
+ *   - **block** — bulk-first block/unblock: marquee-drag, ⌘A select-all,
+ *                 whole-category / whole-section select, single-seat fallback →
+ *                 one batched block/unblock (optimistic, reconciled by the WS),
+ *                 and timed auto-release.
+ *
+ * Auth: reads (chart/objects/WS) are public; writes/reports carry a Bearer
+ * event-scoped manage token (`mse_…`) or a tenant secret key (`sk_…`) via
+ * {@link ManageApi}. Box office + Sections + full Reports UI are M2/M3.
+ */
+
+type SeatManagerMode = 'view' | 'inspect' | 'block';
+/** DO seat status — 'blocked' has no engine analogue (→ 'not_for_sale'). */
+type DoStatus = 'free' | 'held' | 'booked' | 'blocked';
+/** Live KPI snapshot pushed to `onTallies` on every state change. */
+interface SeatManagerTallies {
+    free: number;
+    held: number;
+    booked: number;
+    blocked: number;
+    /** Total seats on the chart. */
+    total: number;
+    /** booked / total, 0–100. */
+    capacityPct: number;
+    /** booked / (total − blocked), 0–100 — sell-through of sellable inventory. */
+    sellThroughPct: number;
+    /** Exact Σ booked unit_price snapshots from the authenticated report. */
+    grossRevenue: number;
+    /** Revenue is never reconstructed from chart list price. */
+    revenueStatus: 'loading' | 'current' | 'stale';
+    /** ISO-4217 currency for grossRevenue. */
+    currency: string;
+}
+/** One streamed activity line for the live feed. */
+interface SeatManagerActivity {
+    id: string;
+    at: number;
+    label: string;
+    /** Full labels affected by this one backend/realtime operation. */
+    labels: string[];
+    count: number;
+    /** Human verb: held / booked / released / blocked / unblocked. */
+    verb: string;
+    status: DoStatus;
+}
+/** Fired after a successful organizer action, for host toasts/telemetry. */
+interface SeatManagerActionResult {
+    action: 'block' | 'unblock' | 'unblockAll' | 'cancelBooking' | 'setHoldTtl';
+    labels: string[];
+    count: number;
+}
+interface SeatManagerOptions {
+    /** CSS selector or element to mount into. */
+    container: string | HTMLElement;
+    /** API origin. Defaults to https://api.seatlayer.io. */
+    apiBase?: string;
+    /** Event key (e.g. `ev_xxx` / `west-end-p3`). */
+    eventKey: string;
+    /** Bearer manage token — event-scoped `mse_…` or a tenant secret `sk_…`. */
+    token: string;
+    /** Absolute token expiry (epoch ms). Enables proactive in-place rotation. */
+    tokenExpiresAt?: number;
+    /** Initial mode. Default 'view'. */
+    mode?: SeatManagerMode;
+    /** ISO-4217 fallback currency for revenue (chart/event currency wins). */
+    currency?: string;
+    /** Chart theme override for the chrome (rails/bar). Chart colors come from the doc. */
+    theme?: ChartTheme;
+    /**
+     * Keep the canvas painting even when the tab is hidden/backgrounded (a war-room
+     * board on a second monitor). Calls `forceDraw()` after each delta so Chrome's
+     * rAF throttling on occluded tabs never leaves the board stale. Default true.
+     */
+    keepLiveWhileHidden?: boolean;
+    /** Chart + first snapshot are loaded and the board is live. */
+    onReady?: () => void;
+    /** Live KPI tallies changed. */
+    onTallies?: (tallies: SeatManagerTallies) => void;
+    /** A grouped live/audit activity item arrived. */
+    onActivity?: (activity: SeatManagerActivity) => void;
+    /** Exact private control-room projection changed. */
+    onControlRoom?: (snapshot: ControlRoomSnapshot) => void;
+    /** Called before token expiry. The manager swaps the result without remounting. */
+    onTokenRefresh?: () => Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+    /** Tool/mode changed from inside the shared cockpit. */
+    onModeChange?: (mode: SeatManagerMode) => void;
+    /** Block-mode selection changed (marquee / ⌘A / category / section / tap). */
+    onSelectionChange?: (seats: ExpandedSeat[]) => void;
+    /** A block/unblock/cancel action completed successfully. */
+    onActionComplete?: (result: SeatManagerActionResult) => void;
+    onError?: (err: unknown) => void;
+}
+declare class SeatManager {
+    private readonly opts;
+    private readonly api;
+    private readonly key;
+    private readonly keepLive;
+    private host;
+    private root;
+    private mapHost;
+    private els;
+    private renderer;
+    private doc;
+    private mode;
+    private labelToId;
+    private labelToSeat;
+    private allIds;
+    private status;
+    private currency;
+    private authoritativeGrossRevenue;
+    private revenueStatus;
+    private revenueRequest;
+    private revenueRefreshTimer;
+    private controlRoomSnapshot;
+    private trendWindowMinutes;
+    private heatEnabled;
+    private ws;
+    private reconnectTimer;
+    private attempt;
+    private closed;
+    private ready;
+    private feed;
+    private feedTimer;
+    private toastTimer;
+    private releaseAt;
+    private layoutObserver;
+    private tokenExpiresAt;
+    private tokenRefreshTimer;
+    private tokenRefreshInFlight;
+    private sectionByObject;
+    private sectionLabelById;
+    private lastSyncedAt;
+    private readonly onFullscreenChange;
+    private readonly onKeyDown;
+    constructor(options: SeatManagerOptions);
+    /** Build the DOM, load the chart, subscribe to realtime, mount the board. */
+    render(): Promise<this>;
+    setMode(mode: SeatManagerMode): void;
+    /** Toggle the normalized sales-velocity outline overlay without changing seat colors. */
+    setHeatOverlay(enabled: boolean): void;
+    /** Change the current-vs-previous sales window and refresh the private projection. */
+    setTrendWindow(windowMinutes: number): Promise<ControlRoomSnapshot>;
+    enterFullscreen(): Promise<void>;
+    exitFullscreen(): Promise<void>;
+    isFullscreen(): boolean;
+    private toggleFullscreen;
+    /** Rotate the delegated credential without rebuilding DOM, canvas or socket. */
+    setToken(token: string, expiresAt?: number): void;
+    private scheduleTokenRefresh;
+    private rotateToken;
+    /** Bulk block the given labels (or the current selection when omitted). */
+    block(labels?: string[], opts?: {
+        releaseAt?: number;
+        reason?: string;
+    }): Promise<void>;
+    unblock(labels?: string[]): Promise<void>;
+    unblockAll(): Promise<void>;
+    /** Cancel bookings (BOOKED → free), guarded by the original booking ref. */
+    cancelBooking(labels: string[], bookingRef: string): Promise<void>;
+    selectAll(): ExpandedSeat[];
+    selectSection(sectionId: string): ExpandedSeat[];
+    selectByLabels(labels: string[]): ExpandedSeat[];
+    clearSelection(): void;
+    getSelection(): ExpandedSeat[];
+    getReport(): Promise<ReportResult>;
+    getControlRoomSnapshot(windowMinutes?: number): Promise<ControlRoomSnapshot>;
+    getLog(opts?: {
+        limit?: number;
+        before?: number;
+    }): Promise<{
+        entries: LogEntry[];
+        nextBefore: number | null;
+    }>;
+    setHoldTtl(ms: number | null): Promise<void>;
+    /** M2 — box-office booking from free seats. Stubbed (route is session-only today). */
+    boxBook(_labels: string[], _bookingRef: string): Promise<void>;
+    zoomToFit(): void;
+    destroy(): void;
+    private buildRenderer;
+    private updateRendererInteraction;
+    private handleSeatSelect;
+    private repaintAll;
+    private connect;
+    private scheduleReconnect;
+    private onMessage;
+    private resnapshot;
+    private applySnapshot;
+    /** Optimistic local write shared by delta stream + organizer actions. */
+    private setSeatLocal;
+    /** Keep the canvas painting on hidden/occluded tabs (war-room second monitor). */
+    private afterPaint;
+    private flash;
+    private applyReportRevenue;
+    private refreshControlRoom;
+    private scheduleRevenueRefresh;
+    private recomputeTallies;
+    private verbFor;
+    private pushActivity;
+    private seedFeed;
+    private startFeedClock;
+    private selectionLabels;
+    private syncSelection;
+    private buildChrome;
+    private updateContainerLayout;
+    private sectionOptions;
+    private buildSectionOptions;
+    private paintModeTabs;
+    private paintHeatButton;
+    private paintFullscreenButton;
+    private paintTrendWindow;
+    private setLive;
+    private updateZoomHint;
+    private paintKpis;
+    private paintRail;
+    private renderViewRail;
+    private paintMonitorInsights;
+    private applyHeatOverlay;
+    private renderInspectRail;
+    private paintLegend;
+    private paintFeed;
+    private renderBlockRail;
+    private selectCategory;
+    private paintSelBar;
+    private done;
+    private toastOk;
+    private toastErr;
+    private toast;
+    private fail;
+}
+
+export { ApiError, type BestAvailableResult, type CheckoutHandoff, type CheckoutLineItem, type ControlRoomSectionMetric, type ControlRoomSnapshot, EmbeddedDesigner, type EmbeddedDesignerEventType, type EmbeddedDesignerMessage, type EmbeddedDesignerOptions, type GAAreaAvailability, type HoldConflict, type HoldLineItem, type HoldResult, type LogEntry, type LogPage, ManageApi, ManageApiError, type ReportByStatus, type ReportCategoryMeta, type ReportCategoryRow, type ReportResult, SeatManager, type SeatManagerActionResult, type SeatManagerActivity, type SeatManagerMode, type SeatManagerOptions, type SeatManagerTallies, SeatPicker, type SeatPickerOptions, type SeatPickerTheme, SeatingChart, type SeatingChartOptions, type SelectedSeat };