@lumibase/sdk 0.14.0 → 0.15.0

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ACCESS_EXPORT_SCHEMA: () => ACCESS_EXPORT_SCHEMA,
+  AudienceClient: () => AudienceClient,
   LumiError: () => LumiError,
   RealtimeClient: () => RealtimeClient,
   checkCdcPipelineHealth: () => checkCdcPipelineHealth,
@@ -147,6 +148,165 @@ function createLumiClient(opts) {
 // src/types.ts
 var ACCESS_EXPORT_SCHEMA = "lumibase.access@v1";
 
+// src/realtime/audience.ts
+var WS_OPEN = 1;
+var AudienceClient = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.backoffMs = opts.initialBackoffMs ?? 1e3;
+    for (const c of opts.channels ?? []) this.channels.add(c);
+  }
+  opts;
+  ws = null;
+  channels = /* @__PURE__ */ new Set();
+  channelListeners = /* @__PURE__ */ new Set();
+  notificationListeners = /* @__PURE__ */ new Set();
+  statusListeners = /* @__PURE__ */ new Set();
+  reconnectTimer = null;
+  backoffMs;
+  stopped = false;
+  _status = "closed";
+  // ─── Public API ─────────────────────────────────────────────────────────────
+  get status() {
+    return this._status;
+  }
+  connect() {
+    this.stopped = false;
+    void this._connect();
+    return this;
+  }
+  disconnect() {
+    this.stopped = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      try {
+        this.ws.close(1e3, "client disconnect");
+      } catch {
+      }
+      this.ws = null;
+    }
+    this.setStatus("closed");
+  }
+  /** Join a channel. Remembered and re-joined across reconnects. */
+  join(channel) {
+    this.channels.add(channel);
+    this.sendIfOpen({ type: "join", channel });
+  }
+  /** Leave a channel and stop re-joining it. */
+  leave(channel) {
+    this.channels.delete(channel);
+    this.sendIfOpen({ type: "leave", channel });
+  }
+  onChannelEvent(cb) {
+    this.channelListeners.add(cb);
+    return () => this.channelListeners.delete(cb);
+  }
+  onNotification(cb) {
+    this.notificationListeners.add(cb);
+    return () => this.notificationListeners.delete(cb);
+  }
+  onStatus(cb) {
+    this.statusListeners.add(cb);
+    return () => this.statusListeners.delete(cb);
+  }
+  // ─── Internal ────────────────────────────────────────────────────────────────
+  async _connect() {
+    if (this.ws) return;
+    this.setStatus("connecting");
+    const doFetch = this.opts.fetchImpl ?? fetch;
+    let ticket;
+    try {
+      const res = await doFetch(`${this.opts.baseUrl}/api/v1/realtime/audience-ticket`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.opts.token}`,
+          "X-Lumi-Site": this.opts.siteId,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ channels: Array.from(this.channels) })
+      });
+      if (!res.ok) throw new Error(`audience-ticket failed: ${res.status}`);
+      const body = await res.json();
+      if (!body.data?.ticket) throw new Error("ticket missing");
+      ticket = body.data.ticket;
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+    if (this.stopped) return;
+    const wsBase = this.opts.baseUrl.replace(/^http/, "ws");
+    const url = `${wsBase}/api/v1/realtime?ticket=${encodeURIComponent(ticket)}`;
+    const factory = this.opts.webSocketFactory ?? ((u) => new WebSocket(u));
+    let ws;
+    try {
+      ws = factory(url);
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+    this.ws = ws;
+    ws.addEventListener("open", () => {
+      this.backoffMs = this.opts.initialBackoffMs ?? 1e3;
+      this.setStatus("open");
+      for (const channel of this.channels) this.sendRaw({ type: "join", channel });
+    });
+    ws.addEventListener("message", (ev) => {
+      let msg;
+      try {
+        msg = JSON.parse(ev.data);
+      } catch {
+        return;
+      }
+      this.handleMessage(msg);
+    });
+    ws.addEventListener("close", () => {
+      this.ws = null;
+      this.setStatus("closed");
+      if (!this.stopped) this.scheduleReconnect();
+    });
+    ws.addEventListener("error", () => {
+    });
+  }
+  handleMessage(msg) {
+    switch (msg.type) {
+      case "ping":
+        this.sendRaw({ type: "pong" });
+        break;
+      case "event":
+        for (const cb of this.channelListeners) cb(msg);
+        break;
+      case "notification":
+        for (const cb of this.notificationListeners) cb(msg);
+        break;
+    }
+  }
+  scheduleReconnect() {
+    if (this.stopped || this.reconnectTimer) return;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      void this._connect();
+      this.backoffMs = Math.min(this.backoffMs * 2, this.opts.maxBackoffMs ?? 3e4);
+    }, this.backoffMs);
+  }
+  setStatus(status) {
+    if (this._status === status) return;
+    this._status = status;
+    for (const cb of this.statusListeners) cb(status);
+  }
+  sendIfOpen(data) {
+    if (this.ws && this.ws.readyState === WS_OPEN) this.sendRaw(data);
+  }
+  sendRaw(data) {
+    try {
+      this.ws?.send(JSON.stringify(data));
+    } catch {
+    }
+  }
+};
+
 // src/realtime/index.ts
 var RealtimeClient = class {
   constructor(opts) {
@@ -1330,6 +1490,7 @@ function jsonLdScript(item) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACCESS_EXPORT_SCHEMA,
+  AudienceClient,
   LumiError,
   RealtimeClient,
   checkCdcPipelineHealth,

package/dist/index.d.cts

@@ -1293,6 +1293,90 @@ interface LumiClient<TSchema extends DefaultSchema = DefaultSchema> {
 }
 declare function createLumiClient<TSchema extends DefaultSchema = DefaultSchema>(opts: LumiClientOptions): LumiClient<TSchema>;
 
+/**
+ * AudienceClient — realtime client for FRONTEND end-users (the public plane).
+ *
+ * End-users are addressed by a `subjectId` (mapped server-side from e.g. a
+ * citizenID) and by channels they are granted at ticket time. This client:
+ *   - fetches a short-lived audience ticket from `/api/v1/realtime/audience-ticket`;
+ *   - opens the WebSocket and (re)joins channels;
+ *   - surfaces per-channel events and personal notifications;
+ *   - reconnects with exponential backoff and re-joins open channels.
+ *
+ * The Studio (admin) plane uses the separate `RealtimeClient` in `./index`.
+ */
+interface AudienceEvent {
+    type: 'event';
+    channel?: string;
+    collection?: string;
+    action?: 'create' | 'update' | 'delete';
+    itemId?: string;
+    payload: unknown;
+}
+interface AudienceNotification {
+    type: 'notification';
+    payload: Record<string, unknown>;
+}
+type ChannelEventCallback = (event: AudienceEvent) => void;
+type NotificationCallback = (notification: AudienceNotification) => void;
+type ConnectionStatus = 'connecting' | 'open' | 'closed';
+type StatusCallback = (status: ConnectionStatus) => void;
+/** Minimal structural WebSocket — lets tests inject a fake. */
+interface WebSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open' | 'message' | 'close' | 'error', handler: (ev: any) => void): void;
+}
+type WebSocketFactory = (url: string) => WebSocketLike;
+interface AudienceClientOptions {
+    /** Base HTTP URL of the CMS. `wss://` is derived automatically. */
+    baseUrl: string;
+    /**
+     * Bearer token for the authenticated FRONTEND end-user. Exchanged for a
+     * short-lived audience ticket; never sent over the socket.
+     */
+    token: string;
+    siteId: string;
+    /** Channels to request access to (subject to the server-side allowlist). */
+    channels?: string[];
+    initialBackoffMs?: number;
+    maxBackoffMs?: number;
+    /** Injectable WebSocket factory (defaults to the global `WebSocket`). */
+    webSocketFactory?: WebSocketFactory;
+    /** Injectable fetch (defaults to the global `fetch`). */
+    fetchImpl?: typeof fetch;
+}
+declare class AudienceClient {
+    private readonly opts;
+    private ws;
+    private readonly channels;
+    private readonly channelListeners;
+    private readonly notificationListeners;
+    private readonly statusListeners;
+    private reconnectTimer;
+    private backoffMs;
+    private stopped;
+    private _status;
+    constructor(opts: AudienceClientOptions);
+    get status(): ConnectionStatus;
+    connect(): this;
+    disconnect(): void;
+    /** Join a channel. Remembered and re-joined across reconnects. */
+    join(channel: string): void;
+    /** Leave a channel and stop re-joining it. */
+    leave(channel: string): void;
+    onChannelEvent(cb: ChannelEventCallback): () => void;
+    onNotification(cb: NotificationCallback): () => void;
+    onStatus(cb: StatusCallback): () => void;
+    private _connect;
+    private handleMessage;
+    private scheduleReconnect;
+    private setStatus;
+    private sendIfOpen;
+    private sendRaw;
+}
+
 /**
  * RealtimeClient — typed WebSocket client for the LumiBase realtime API.
  *
@@ -1311,6 +1395,7 @@ declare function createLumiClient<TSchema extends DefaultSchema = DefaultSchema>
  *   // ... later
  *   rt.disconnect();
  */
+
 interface RealtimeEvent {
     type: 'event';
     collection: string;
@@ -1861,4 +1946,4 @@ declare function toNextMetadata(item: unknown): Record<string, unknown>;
  */
 declare function jsonLdScript(item: unknown): string | undefined;
 
-export { ACCESS_EXPORT_SCHEMA, type AIApproval, type AIApprovalStatus, type AIChatResponse, type AIChatStatus, type AIContentAssistResult, type AIConversation, type AIFieldSuggestion, type AIMessage, type AccessConflict, type AccessConflictCheckInput, type AccessConflictReport, type AccessExportApiKey, type AccessExportBindings, type AccessExportManifest, type AccessExportPermission, type AccessExportPolicy, type AccessExportRole, type AccessImportApplyResult, type AccessImportDiff, type AccessImportDiffEntry, type AccessImportDiffSection, type AccessImportDryRunResult, type AccessImportIssue, type AccessImportMode, type AccessImportOptions, type AccessImportSummary, type ActivityResource, type AgentApprovalResource, type AgentArtifactCreateInput, type AgentArtifactResource, type AgentArtifactType, type AgentEvaluationResource, type AgentGenerateAppInput, type AgentGenerateAppResult, type AgentGoalCreateInput, type AgentGoalResource, type AgentMemoryContext, type AgentMemoryResource, type AgentMemoryWriteInput, type AgentRiskLevel, type AgentRunResource, type AgentToolResource, type ApiKeyCreateInput, type ApiKeyPolicyAttachment, type ApiKeyResource, type ApiKeyRoleAttachment, type ApiKeyRotateInput, type ApiKeySecretResult, type Brand, type CdcConnectorType, type CdcDeployInput, type CdcDeploymentResult, type CdcDeploymentStatus, type CdcDeploymentStep, type CdcDeploymentTarget, type CdcEnvValidationResult, type CdcHealthCheckResult, type CdcHealthMetricEntry, type CdcPipelineCreateInput, type CdcPipelineMetrics, type CdcPipelinePatchInput, type CdcPipelineResource, type CdcPipelineStatus, type CdcRollbackResult, type CdcValidateEnvInput, type CollectionInput, type CollectionResource, type CompiledPermission, type CreateSCIMTokenParams, type DefaultSchema, type DeliverySeo, type DeploymentResource, type DeploymentTargetResource, type ExtensionResource, type FieldDeleteOptions, type FieldInput, type FieldMutationOptions, type FieldRenameInput, type FieldResource, type FileResource, type FlowGraph, type FlowNode, type FlowResource, type FlowRun, type FlowRunResult, type FlowRunStatus, type FlowStatus, type FlowTriggerType, type FolderResource, type GenerateOptions, type GraphQLExtension, type ID, type ItemFilter, type ItemFilterOp, type ItemRow, type ListItemsParams, type ListItemsResponse, type ListMarketplaceExtensionsParams, type Locale, type LumiClient, type LumiClientOptions, LumiError, type LumiErrorBody, type LumiResponse, type MarketplaceExtension, type MarketplaceListResponse, type MaterializeDataResponse, type MaterializeProjection, type MaterializeRefreshResult, type MaterializeRefreshStrategy, type MaterializedCollection, type PermissionAction, type PermissionBundle, type PermissionCheckResult, type PermissionRow, type PolicyDetail, type PolicyResource, type PresenceCallback, type PresenceEntry, type PresetResource, type PrimaryKeyType, RealtimeClient, type RealtimeEvent, type RealtimeEventCallback, type RelationInput, type RelationResource, type RelationType, type RevisionRow, type RoleDetail, type RoleResource, type SCIMTokenCreated, type SCIMTokenMeta, type SCIMTokenRotated, type SchemaApplyInput, type SchemaApplyResult, type SchemaChangedEvent, type SchemaDiff, type SchemaDiffEntry, type SchemaDiffInput, type SchemaDiffRisk, type SchemaRuntimeImpact, type SearchHit, type SearchHitMeta, type SearchParams, type SearchResponse, type SettingResource, type ShareCreateInput, type ShareResource, type ShareSecretResult, type SiteConfigUpdate, type SiteResource, type StorageMode, type TeamMemberResource, type TeamResource, type TranslationResource, type TypegenCollection, type TypegenField, type TypegenManifest, type TypegenRelation, type TypegenSchemaFilters, type UserPreferencesPayload, type UserResource, type WebhookResource, checkCdcPipelineHealth, createAgentArtifact, createAgentGoal, createCdcPipeline, createLumiClient, decideAgentApproval, deleteCdcPipeline, deployCdc, dryRunAccessImport, evaluateAgentArtifact, exportAccessManifest, extractSeo, generateAgentApp, generateTypes, graphql, importAccessManifest, jsonLdScript, legacyRest, listAgentApprovals, listAgentArtifacts, listAgentGoals, listAgentRuns, listAgentTools, listCdcPipelines, publishAgentArtifact, readAgentMemoryContext, readCdcPipeline, readCdcPipelineMetricHistory, readCdcPipelineMetrics, readItem, readItems, retryAgentRun, rollbackAgentArtifact, rollbackCdcDeployment, search, startCdcPipeline, stopCdcPipeline, toNextMetadata, updateCdcPipeline, validateCdcDeploymentEnv, writeAgentMemory };
+export { ACCESS_EXPORT_SCHEMA, type AIApproval, type AIApprovalStatus, type AIChatResponse, type AIChatStatus, type AIContentAssistResult, type AIConversation, type AIFieldSuggestion, type AIMessage, type AccessConflict, type AccessConflictCheckInput, type AccessConflictReport, type AccessExportApiKey, type AccessExportBindings, type AccessExportManifest, type AccessExportPermission, type AccessExportPolicy, type AccessExportRole, type AccessImportApplyResult, type AccessImportDiff, type AccessImportDiffEntry, type AccessImportDiffSection, type AccessImportDryRunResult, type AccessImportIssue, type AccessImportMode, type AccessImportOptions, type AccessImportSummary, type ActivityResource, type AgentApprovalResource, type AgentArtifactCreateInput, type AgentArtifactResource, type AgentArtifactType, type AgentEvaluationResource, type AgentGenerateAppInput, type AgentGenerateAppResult, type AgentGoalCreateInput, type AgentGoalResource, type AgentMemoryContext, type AgentMemoryResource, type AgentMemoryWriteInput, type AgentRiskLevel, type AgentRunResource, type AgentToolResource, type ApiKeyCreateInput, type ApiKeyPolicyAttachment, type ApiKeyResource, type ApiKeyRoleAttachment, type ApiKeyRotateInput, type ApiKeySecretResult, AudienceClient, type AudienceClientOptions, type AudienceEvent, type AudienceNotification, type Brand, type CdcConnectorType, type CdcDeployInput, type CdcDeploymentResult, type CdcDeploymentStatus, type CdcDeploymentStep, type CdcDeploymentTarget, type CdcEnvValidationResult, type CdcHealthCheckResult, type CdcHealthMetricEntry, type CdcPipelineCreateInput, type CdcPipelineMetrics, type CdcPipelinePatchInput, type CdcPipelineResource, type CdcPipelineStatus, type CdcRollbackResult, type CdcValidateEnvInput, type ChannelEventCallback, type CollectionInput, type CollectionResource, type CompiledPermission, type ConnectionStatus, type CreateSCIMTokenParams, type DefaultSchema, type DeliverySeo, type DeploymentResource, type DeploymentTargetResource, type ExtensionResource, type FieldDeleteOptions, type FieldInput, type FieldMutationOptions, type FieldRenameInput, type FieldResource, type FileResource, type FlowGraph, type FlowNode, type FlowResource, type FlowRun, type FlowRunResult, type FlowRunStatus, type FlowStatus, type FlowTriggerType, type FolderResource, type GenerateOptions, type GraphQLExtension, type ID, type ItemFilter, type ItemFilterOp, type ItemRow, type ListItemsParams, type ListItemsResponse, type ListMarketplaceExtensionsParams, type Locale, type LumiClient, type LumiClientOptions, LumiError, type LumiErrorBody, type LumiResponse, type MarketplaceExtension, type MarketplaceListResponse, type MaterializeDataResponse, type MaterializeProjection, type MaterializeRefreshResult, type MaterializeRefreshStrategy, type MaterializedCollection, type NotificationCallback, type PermissionAction, type PermissionBundle, type PermissionCheckResult, type PermissionRow, type PolicyDetail, type PolicyResource, type PresenceCallback, type PresenceEntry, type PresetResource, type PrimaryKeyType, RealtimeClient, type RealtimeEvent, type RealtimeEventCallback, type RelationInput, type RelationResource, type RelationType, type RevisionRow, type RoleDetail, type RoleResource, type SCIMTokenCreated, type SCIMTokenMeta, type SCIMTokenRotated, type SchemaApplyInput, type SchemaApplyResult, type SchemaChangedEvent, type SchemaDiff, type SchemaDiffEntry, type SchemaDiffInput, type SchemaDiffRisk, type SchemaRuntimeImpact, type SearchHit, type SearchHitMeta, type SearchParams, type SearchResponse, type SettingResource, type ShareCreateInput, type ShareResource, type ShareSecretResult, type SiteConfigUpdate, type SiteResource, type StatusCallback, type StorageMode, type TeamMemberResource, type TeamResource, type TranslationResource, type TypegenCollection, type TypegenField, type TypegenManifest, type TypegenRelation, type TypegenSchemaFilters, type UserPreferencesPayload, type UserResource, type WebSocketFactory, type WebSocketLike, type WebhookResource, checkCdcPipelineHealth, createAgentArtifact, createAgentGoal, createCdcPipeline, createLumiClient, decideAgentApproval, deleteCdcPipeline, deployCdc, dryRunAccessImport, evaluateAgentArtifact, exportAccessManifest, extractSeo, generateAgentApp, generateTypes, graphql, importAccessManifest, jsonLdScript, legacyRest, listAgentApprovals, listAgentArtifacts, listAgentGoals, listAgentRuns, listAgentTools, listCdcPipelines, publishAgentArtifact, readAgentMemoryContext, readCdcPipeline, readCdcPipelineMetricHistory, readCdcPipelineMetrics, readItem, readItems, retryAgentRun, rollbackAgentArtifact, rollbackCdcDeployment, search, startCdcPipeline, stopCdcPipeline, toNextMetadata, updateCdcPipeline, validateCdcDeploymentEnv, writeAgentMemory };

package/dist/index.d.ts

@@ -1293,6 +1293,90 @@ interface LumiClient<TSchema extends DefaultSchema = DefaultSchema> {
 }
 declare function createLumiClient<TSchema extends DefaultSchema = DefaultSchema>(opts: LumiClientOptions): LumiClient<TSchema>;
 
+/**
+ * AudienceClient — realtime client for FRONTEND end-users (the public plane).
+ *
+ * End-users are addressed by a `subjectId` (mapped server-side from e.g. a
+ * citizenID) and by channels they are granted at ticket time. This client:
+ *   - fetches a short-lived audience ticket from `/api/v1/realtime/audience-ticket`;
+ *   - opens the WebSocket and (re)joins channels;
+ *   - surfaces per-channel events and personal notifications;
+ *   - reconnects with exponential backoff and re-joins open channels.
+ *
+ * The Studio (admin) plane uses the separate `RealtimeClient` in `./index`.
+ */
+interface AudienceEvent {
+    type: 'event';
+    channel?: string;
+    collection?: string;
+    action?: 'create' | 'update' | 'delete';
+    itemId?: string;
+    payload: unknown;
+}
+interface AudienceNotification {
+    type: 'notification';
+    payload: Record<string, unknown>;
+}
+type ChannelEventCallback = (event: AudienceEvent) => void;
+type NotificationCallback = (notification: AudienceNotification) => void;
+type ConnectionStatus = 'connecting' | 'open' | 'closed';
+type StatusCallback = (status: ConnectionStatus) => void;
+/** Minimal structural WebSocket — lets tests inject a fake. */
+interface WebSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open' | 'message' | 'close' | 'error', handler: (ev: any) => void): void;
+}
+type WebSocketFactory = (url: string) => WebSocketLike;
+interface AudienceClientOptions {
+    /** Base HTTP URL of the CMS. `wss://` is derived automatically. */
+    baseUrl: string;
+    /**
+     * Bearer token for the authenticated FRONTEND end-user. Exchanged for a
+     * short-lived audience ticket; never sent over the socket.
+     */
+    token: string;
+    siteId: string;
+    /** Channels to request access to (subject to the server-side allowlist). */
+    channels?: string[];
+    initialBackoffMs?: number;
+    maxBackoffMs?: number;
+    /** Injectable WebSocket factory (defaults to the global `WebSocket`). */
+    webSocketFactory?: WebSocketFactory;
+    /** Injectable fetch (defaults to the global `fetch`). */
+    fetchImpl?: typeof fetch;
+}
+declare class AudienceClient {
+    private readonly opts;
+    private ws;
+    private readonly channels;
+    private readonly channelListeners;
+    private readonly notificationListeners;
+    private readonly statusListeners;
+    private reconnectTimer;
+    private backoffMs;
+    private stopped;
+    private _status;
+    constructor(opts: AudienceClientOptions);
+    get status(): ConnectionStatus;
+    connect(): this;
+    disconnect(): void;
+    /** Join a channel. Remembered and re-joined across reconnects. */
+    join(channel: string): void;
+    /** Leave a channel and stop re-joining it. */
+    leave(channel: string): void;
+    onChannelEvent(cb: ChannelEventCallback): () => void;
+    onNotification(cb: NotificationCallback): () => void;
+    onStatus(cb: StatusCallback): () => void;
+    private _connect;
+    private handleMessage;
+    private scheduleReconnect;
+    private setStatus;
+    private sendIfOpen;
+    private sendRaw;
+}
+
 /**
  * RealtimeClient — typed WebSocket client for the LumiBase realtime API.
  *
@@ -1311,6 +1395,7 @@ declare function createLumiClient<TSchema extends DefaultSchema = DefaultSchema>
  *   // ... later
  *   rt.disconnect();
  */
+
 interface RealtimeEvent {
     type: 'event';
     collection: string;
@@ -1861,4 +1946,4 @@ declare function toNextMetadata(item: unknown): Record<string, unknown>;
  */
 declare function jsonLdScript(item: unknown): string | undefined;
 
-export { ACCESS_EXPORT_SCHEMA, type AIApproval, type AIApprovalStatus, type AIChatResponse, type AIChatStatus, type AIContentAssistResult, type AIConversation, type AIFieldSuggestion, type AIMessage, type AccessConflict, type AccessConflictCheckInput, type AccessConflictReport, type AccessExportApiKey, type AccessExportBindings, type AccessExportManifest, type AccessExportPermission, type AccessExportPolicy, type AccessExportRole, type AccessImportApplyResult, type AccessImportDiff, type AccessImportDiffEntry, type AccessImportDiffSection, type AccessImportDryRunResult, type AccessImportIssue, type AccessImportMode, type AccessImportOptions, type AccessImportSummary, type ActivityResource, type AgentApprovalResource, type AgentArtifactCreateInput, type AgentArtifactResource, type AgentArtifactType, type AgentEvaluationResource, type AgentGenerateAppInput, type AgentGenerateAppResult, type AgentGoalCreateInput, type AgentGoalResource, type AgentMemoryContext, type AgentMemoryResource, type AgentMemoryWriteInput, type AgentRiskLevel, type AgentRunResource, type AgentToolResource, type ApiKeyCreateInput, type ApiKeyPolicyAttachment, type ApiKeyResource, type ApiKeyRoleAttachment, type ApiKeyRotateInput, type ApiKeySecretResult, type Brand, type CdcConnectorType, type CdcDeployInput, type CdcDeploymentResult, type CdcDeploymentStatus, type CdcDeploymentStep, type CdcDeploymentTarget, type CdcEnvValidationResult, type CdcHealthCheckResult, type CdcHealthMetricEntry, type CdcPipelineCreateInput, type CdcPipelineMetrics, type CdcPipelinePatchInput, type CdcPipelineResource, type CdcPipelineStatus, type CdcRollbackResult, type CdcValidateEnvInput, type CollectionInput, type CollectionResource, type CompiledPermission, type CreateSCIMTokenParams, type DefaultSchema, type DeliverySeo, type DeploymentResource, type DeploymentTargetResource, type ExtensionResource, type FieldDeleteOptions, type FieldInput, type FieldMutationOptions, type FieldRenameInput, type FieldResource, type FileResource, type FlowGraph, type FlowNode, type FlowResource, type FlowRun, type FlowRunResult, type FlowRunStatus, type FlowStatus, type FlowTriggerType, type FolderResource, type GenerateOptions, type GraphQLExtension, type ID, type ItemFilter, type ItemFilterOp, type ItemRow, type ListItemsParams, type ListItemsResponse, type ListMarketplaceExtensionsParams, type Locale, type LumiClient, type LumiClientOptions, LumiError, type LumiErrorBody, type LumiResponse, type MarketplaceExtension, type MarketplaceListResponse, type MaterializeDataResponse, type MaterializeProjection, type MaterializeRefreshResult, type MaterializeRefreshStrategy, type MaterializedCollection, type PermissionAction, type PermissionBundle, type PermissionCheckResult, type PermissionRow, type PolicyDetail, type PolicyResource, type PresenceCallback, type PresenceEntry, type PresetResource, type PrimaryKeyType, RealtimeClient, type RealtimeEvent, type RealtimeEventCallback, type RelationInput, type RelationResource, type RelationType, type RevisionRow, type RoleDetail, type RoleResource, type SCIMTokenCreated, type SCIMTokenMeta, type SCIMTokenRotated, type SchemaApplyInput, type SchemaApplyResult, type SchemaChangedEvent, type SchemaDiff, type SchemaDiffEntry, type SchemaDiffInput, type SchemaDiffRisk, type SchemaRuntimeImpact, type SearchHit, type SearchHitMeta, type SearchParams, type SearchResponse, type SettingResource, type ShareCreateInput, type ShareResource, type ShareSecretResult, type SiteConfigUpdate, type SiteResource, type StorageMode, type TeamMemberResource, type TeamResource, type TranslationResource, type TypegenCollection, type TypegenField, type TypegenManifest, type TypegenRelation, type TypegenSchemaFilters, type UserPreferencesPayload, type UserResource, type WebhookResource, checkCdcPipelineHealth, createAgentArtifact, createAgentGoal, createCdcPipeline, createLumiClient, decideAgentApproval, deleteCdcPipeline, deployCdc, dryRunAccessImport, evaluateAgentArtifact, exportAccessManifest, extractSeo, generateAgentApp, generateTypes, graphql, importAccessManifest, jsonLdScript, legacyRest, listAgentApprovals, listAgentArtifacts, listAgentGoals, listAgentRuns, listAgentTools, listCdcPipelines, publishAgentArtifact, readAgentMemoryContext, readCdcPipeline, readCdcPipelineMetricHistory, readCdcPipelineMetrics, readItem, readItems, retryAgentRun, rollbackAgentArtifact, rollbackCdcDeployment, search, startCdcPipeline, stopCdcPipeline, toNextMetadata, updateCdcPipeline, validateCdcDeploymentEnv, writeAgentMemory };
+export { ACCESS_EXPORT_SCHEMA, type AIApproval, type AIApprovalStatus, type AIChatResponse, type AIChatStatus, type AIContentAssistResult, type AIConversation, type AIFieldSuggestion, type AIMessage, type AccessConflict, type AccessConflictCheckInput, type AccessConflictReport, type AccessExportApiKey, type AccessExportBindings, type AccessExportManifest, type AccessExportPermission, type AccessExportPolicy, type AccessExportRole, type AccessImportApplyResult, type AccessImportDiff, type AccessImportDiffEntry, type AccessImportDiffSection, type AccessImportDryRunResult, type AccessImportIssue, type AccessImportMode, type AccessImportOptions, type AccessImportSummary, type ActivityResource, type AgentApprovalResource, type AgentArtifactCreateInput, type AgentArtifactResource, type AgentArtifactType, type AgentEvaluationResource, type AgentGenerateAppInput, type AgentGenerateAppResult, type AgentGoalCreateInput, type AgentGoalResource, type AgentMemoryContext, type AgentMemoryResource, type AgentMemoryWriteInput, type AgentRiskLevel, type AgentRunResource, type AgentToolResource, type ApiKeyCreateInput, type ApiKeyPolicyAttachment, type ApiKeyResource, type ApiKeyRoleAttachment, type ApiKeyRotateInput, type ApiKeySecretResult, AudienceClient, type AudienceClientOptions, type AudienceEvent, type AudienceNotification, type Brand, type CdcConnectorType, type CdcDeployInput, type CdcDeploymentResult, type CdcDeploymentStatus, type CdcDeploymentStep, type CdcDeploymentTarget, type CdcEnvValidationResult, type CdcHealthCheckResult, type CdcHealthMetricEntry, type CdcPipelineCreateInput, type CdcPipelineMetrics, type CdcPipelinePatchInput, type CdcPipelineResource, type CdcPipelineStatus, type CdcRollbackResult, type CdcValidateEnvInput, type ChannelEventCallback, type CollectionInput, type CollectionResource, type CompiledPermission, type ConnectionStatus, type CreateSCIMTokenParams, type DefaultSchema, type DeliverySeo, type DeploymentResource, type DeploymentTargetResource, type ExtensionResource, type FieldDeleteOptions, type FieldInput, type FieldMutationOptions, type FieldRenameInput, type FieldResource, type FileResource, type FlowGraph, type FlowNode, type FlowResource, type FlowRun, type FlowRunResult, type FlowRunStatus, type FlowStatus, type FlowTriggerType, type FolderResource, type GenerateOptions, type GraphQLExtension, type ID, type ItemFilter, type ItemFilterOp, type ItemRow, type ListItemsParams, type ListItemsResponse, type ListMarketplaceExtensionsParams, type Locale, type LumiClient, type LumiClientOptions, LumiError, type LumiErrorBody, type LumiResponse, type MarketplaceExtension, type MarketplaceListResponse, type MaterializeDataResponse, type MaterializeProjection, type MaterializeRefreshResult, type MaterializeRefreshStrategy, type MaterializedCollection, type NotificationCallback, type PermissionAction, type PermissionBundle, type PermissionCheckResult, type PermissionRow, type PolicyDetail, type PolicyResource, type PresenceCallback, type PresenceEntry, type PresetResource, type PrimaryKeyType, RealtimeClient, type RealtimeEvent, type RealtimeEventCallback, type RelationInput, type RelationResource, type RelationType, type RevisionRow, type RoleDetail, type RoleResource, type SCIMTokenCreated, type SCIMTokenMeta, type SCIMTokenRotated, type SchemaApplyInput, type SchemaApplyResult, type SchemaChangedEvent, type SchemaDiff, type SchemaDiffEntry, type SchemaDiffInput, type SchemaDiffRisk, type SchemaRuntimeImpact, type SearchHit, type SearchHitMeta, type SearchParams, type SearchResponse, type SettingResource, type ShareCreateInput, type ShareResource, type ShareSecretResult, type SiteConfigUpdate, type SiteResource, type StatusCallback, type StorageMode, type TeamMemberResource, type TeamResource, type TranslationResource, type TypegenCollection, type TypegenField, type TypegenManifest, type TypegenRelation, type TypegenSchemaFilters, type UserPreferencesPayload, type UserResource, type WebSocketFactory, type WebSocketLike, type WebhookResource, checkCdcPipelineHealth, createAgentArtifact, createAgentGoal, createCdcPipeline, createLumiClient, decideAgentApproval, deleteCdcPipeline, deployCdc, dryRunAccessImport, evaluateAgentArtifact, exportAccessManifest, extractSeo, generateAgentApp, generateTypes, graphql, importAccessManifest, jsonLdScript, legacyRest, listAgentApprovals, listAgentArtifacts, listAgentGoals, listAgentRuns, listAgentTools, listCdcPipelines, publishAgentArtifact, readAgentMemoryContext, readCdcPipeline, readCdcPipelineMetricHistory, readCdcPipelineMetrics, readItem, readItems, retryAgentRun, rollbackAgentArtifact, rollbackCdcDeployment, search, startCdcPipeline, stopCdcPipeline, toNextMetadata, updateCdcPipeline, validateCdcDeploymentEnv, writeAgentMemory };

package/dist/index.js

@@ -78,6 +78,165 @@ function createLumiClient(opts) {
 // src/types.ts
 var ACCESS_EXPORT_SCHEMA = "lumibase.access@v1";
 
+// src/realtime/audience.ts
+var WS_OPEN = 1;
+var AudienceClient = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.backoffMs = opts.initialBackoffMs ?? 1e3;
+    for (const c of opts.channels ?? []) this.channels.add(c);
+  }
+  opts;
+  ws = null;
+  channels = /* @__PURE__ */ new Set();
+  channelListeners = /* @__PURE__ */ new Set();
+  notificationListeners = /* @__PURE__ */ new Set();
+  statusListeners = /* @__PURE__ */ new Set();
+  reconnectTimer = null;
+  backoffMs;
+  stopped = false;
+  _status = "closed";
+  // ─── Public API ─────────────────────────────────────────────────────────────
+  get status() {
+    return this._status;
+  }
+  connect() {
+    this.stopped = false;
+    void this._connect();
+    return this;
+  }
+  disconnect() {
+    this.stopped = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      try {
+        this.ws.close(1e3, "client disconnect");
+      } catch {
+      }
+      this.ws = null;
+    }
+    this.setStatus("closed");
+  }
+  /** Join a channel. Remembered and re-joined across reconnects. */
+  join(channel) {
+    this.channels.add(channel);
+    this.sendIfOpen({ type: "join", channel });
+  }
+  /** Leave a channel and stop re-joining it. */
+  leave(channel) {
+    this.channels.delete(channel);
+    this.sendIfOpen({ type: "leave", channel });
+  }
+  onChannelEvent(cb) {
+    this.channelListeners.add(cb);
+    return () => this.channelListeners.delete(cb);
+  }
+  onNotification(cb) {
+    this.notificationListeners.add(cb);
+    return () => this.notificationListeners.delete(cb);
+  }
+  onStatus(cb) {
+    this.statusListeners.add(cb);
+    return () => this.statusListeners.delete(cb);
+  }
+  // ─── Internal ────────────────────────────────────────────────────────────────
+  async _connect() {
+    if (this.ws) return;
+    this.setStatus("connecting");
+    const doFetch = this.opts.fetchImpl ?? fetch;
+    let ticket;
+    try {
+      const res = await doFetch(`${this.opts.baseUrl}/api/v1/realtime/audience-ticket`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.opts.token}`,
+          "X-Lumi-Site": this.opts.siteId,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ channels: Array.from(this.channels) })
+      });
+      if (!res.ok) throw new Error(`audience-ticket failed: ${res.status}`);
+      const body = await res.json();
+      if (!body.data?.ticket) throw new Error("ticket missing");
+      ticket = body.data.ticket;
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+    if (this.stopped) return;
+    const wsBase = this.opts.baseUrl.replace(/^http/, "ws");
+    const url = `${wsBase}/api/v1/realtime?ticket=${encodeURIComponent(ticket)}`;
+    const factory = this.opts.webSocketFactory ?? ((u) => new WebSocket(u));
+    let ws;
+    try {
+      ws = factory(url);
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+    this.ws = ws;
+    ws.addEventListener("open", () => {
+      this.backoffMs = this.opts.initialBackoffMs ?? 1e3;
+      this.setStatus("open");
+      for (const channel of this.channels) this.sendRaw({ type: "join", channel });
+    });
+    ws.addEventListener("message", (ev) => {
+      let msg;
+      try {
+        msg = JSON.parse(ev.data);
+      } catch {
+        return;
+      }
+      this.handleMessage(msg);
+    });
+    ws.addEventListener("close", () => {
+      this.ws = null;
+      this.setStatus("closed");
+      if (!this.stopped) this.scheduleReconnect();
+    });
+    ws.addEventListener("error", () => {
+    });
+  }
+  handleMessage(msg) {
+    switch (msg.type) {
+      case "ping":
+        this.sendRaw({ type: "pong" });
+        break;
+      case "event":
+        for (const cb of this.channelListeners) cb(msg);
+        break;
+      case "notification":
+        for (const cb of this.notificationListeners) cb(msg);
+        break;
+    }
+  }
+  scheduleReconnect() {
+    if (this.stopped || this.reconnectTimer) return;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      void this._connect();
+      this.backoffMs = Math.min(this.backoffMs * 2, this.opts.maxBackoffMs ?? 3e4);
+    }, this.backoffMs);
+  }
+  setStatus(status) {
+    if (this._status === status) return;
+    this._status = status;
+    for (const cb of this.statusListeners) cb(status);
+  }
+  sendIfOpen(data) {
+    if (this.ws && this.ws.readyState === WS_OPEN) this.sendRaw(data);
+  }
+  sendRaw(data) {
+    try {
+      this.ws?.send(JSON.stringify(data));
+    } catch {
+    }
+  }
+};
+
 // src/realtime/index.ts
 var RealtimeClient = class {
   constructor(opts) {
@@ -1260,6 +1419,7 @@ function jsonLdScript(item) {
 }
 export {
   ACCESS_EXPORT_SCHEMA,
+  AudienceClient,
   LumiError,
   RealtimeClient,
   checkCdcPipelineHealth,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumibase/sdk",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "LumiBase JS SDK (REST + WebSocket) + typegen core. Isomorphic ESM.",
   "type": "module",
   "repository": {