@ragable/sdk 0.6.13 → 0.6.15

package/dist/index.d.mts

@@ -943,6 +943,90 @@ declare class RagableBrowserDatabaseClient<Database extends RagableDatabase = De
     private toUrl;
     query: <Row extends Record<string, unknown> = Record<string, unknown>>(params: BrowserSqlQueryParams) => Promise<PostgrestResult<BrowserSqlQueryResult<Row>>>;
     private baseHeaders;
+    /**
+     * Postgres `LISTEN` / `NOTIFY` realtime via server-proxied SSE.
+     * Channels must be lowercase identifiers: `[a-z_][a-z0-9_]*` (max 63 chars).
+     */
+    /**
+     * Postgres `LISTEN` / `NOTIFY` realtime via server-proxied SSE.
+     *
+     * Returns a `BrowserRealtimeSubscription` with:
+     * - `unsubscribe()` — permanently close the subscription (stops reconnects).
+     * - `status` — current connection state: `"connecting"` | `"connected"` | `"reconnecting"` | `"disconnected"`.
+     *
+     * The subscription automatically reconnects with exponential backoff when the
+     * stream drops. Server heartbeats (every 15 s) are monitored — if none arrive
+     * within `heartbeatTimeoutMs` (default 45 s), the connection is treated as dead
+     * and a reconnect is triggered. Auth errors (401/403/404) are non-retryable.
+     *
+     * Channel names must be lowercase identifiers: `[a-z_][a-z0-9_]*` (max 63 chars).
+     */
+    realtime: {
+        subscribe: (params: BrowserRealtimeSubscribeParams) => Promise<BrowserRealtimeSubscription>;
+    };
+}
+/**
+ * A single NOTIFY message received from a Postgres channel.
+ *
+ * - `channel` — the lowercase channel name that fired.
+ * - `payload` — the text payload (may be null if NOTIFY was sent without one).
+ * - `processId` — the PID of the Postgres backend that called NOTIFY.
+ */
+interface BrowserRealtimeNotification {
+    channel: string;
+    payload: string | null;
+    processId: number;
+}
+/**
+ * Connection status of a realtime subscription.
+ *
+ * - `"connecting"` — establishing or re-establishing the SSE stream.
+ * - `"connected"` — stream is open, heartbeats are arriving, NOTIFY events are flowing.
+ * - `"reconnecting"` — the stream dropped and the SDK is waiting before the next retry.
+ * - `"disconnected"` — permanently stopped (via `unsubscribe()`, `signal` abort, or max retries exceeded).
+ */
+type BrowserRealtimeStatus = "connecting" | "connected" | "reconnecting" | "disconnected";
+interface BrowserRealtimeSubscribeParams {
+    databaseInstanceId?: string;
+    /** Channel names (normalized to lowercase on the server). */
+    channels: string[];
+    /** When aborted, the subscription stops permanently (equivalent to calling `unsubscribe()`). */
+    signal?: AbortSignal;
+    /** Called each time a Postgres NOTIFY message arrives. */
+    onNotify?: (msg: BrowserRealtimeNotification) => void;
+    /** Called once per connection attempt when the server confirms LISTEN is active. */
+    onReady?: (channels: string[]) => void;
+    /** Called when the stream encounters a non-retryable error or the server sends an error event. */
+    onError?: (message: string) => void;
+    /** Called whenever the connection status changes (connecting → connected → reconnecting → …). */
+    onStatusChange?: (status: BrowserRealtimeStatus) => void;
+    /** Called when the stream drops and the SDK will attempt to reconnect. `attempt` is 1-indexed. */
+    onDisconnect?: (info: {
+        attempt: number;
+        retryInMs: number;
+    }) => void;
+    /** Called when a reconnect attempt succeeds (stream is open again). */
+    onReconnect?: (info: {
+        attempt: number;
+    }) => void;
+    /** Maximum number of reconnect attempts before giving up. Set `0` to disable reconnect. Default: **Infinity** (never stops). */
+    maxReconnectAttempts?: number;
+    /** Base delay for exponential backoff (ms). Default: **1000**. */
+    reconnectBaseDelayMs?: number;
+    /** Maximum delay between reconnect attempts (ms). Default: **30000**. */
+    reconnectMaxDelayMs?: number;
+    /** How long to wait without a heartbeat before considering the connection dead (ms). Default: **45000** (3× the server's 15 s heartbeat interval). */
+    heartbeatTimeoutMs?: number;
+}
+/**
+ * Handle returned by `database.realtime.subscribe()`.
+ *
+ * - Call `unsubscribe()` to permanently close the subscription (no more reconnects).
+ * - Read `status` to check the current connection state at any time.
+ */
+interface BrowserRealtimeSubscription {
+    unsubscribe: () => void;
+    readonly status: BrowserRealtimeStatus;
 }
 declare class RagableBrowserAgentsClient {
     private readonly options;
@@ -1044,4 +1128,4 @@ declare function createClient(options: RagableClientOptions): Ragable;
 declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends Record<string, unknown> = Record<string, unknown>>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
 declare function createRagableServerClient(options: RagableClientOptions): Ragable;
 
-export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type BrowserAuthSession, type BrowserAuthTokens, type BrowserDataAuthMode, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, effectiveDataAuth, extractErrorMessage, formatPostgrestError, formatRetrievalContext, formatSdkError, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type BrowserAuthSession, type BrowserAuthTokens, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, effectiveDataAuth, extractErrorMessage, formatPostgrestError, formatRetrievalContext, formatSdkError, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream };

package/dist/index.d.ts

@@ -943,6 +943,90 @@ declare class RagableBrowserDatabaseClient<Database extends RagableDatabase = De
     private toUrl;
     query: <Row extends Record<string, unknown> = Record<string, unknown>>(params: BrowserSqlQueryParams) => Promise<PostgrestResult<BrowserSqlQueryResult<Row>>>;
     private baseHeaders;
+    /**
+     * Postgres `LISTEN` / `NOTIFY` realtime via server-proxied SSE.
+     * Channels must be lowercase identifiers: `[a-z_][a-z0-9_]*` (max 63 chars).
+     */
+    /**
+     * Postgres `LISTEN` / `NOTIFY` realtime via server-proxied SSE.
+     *
+     * Returns a `BrowserRealtimeSubscription` with:
+     * - `unsubscribe()` — permanently close the subscription (stops reconnects).
+     * - `status` — current connection state: `"connecting"` | `"connected"` | `"reconnecting"` | `"disconnected"`.
+     *
+     * The subscription automatically reconnects with exponential backoff when the
+     * stream drops. Server heartbeats (every 15 s) are monitored — if none arrive
+     * within `heartbeatTimeoutMs` (default 45 s), the connection is treated as dead
+     * and a reconnect is triggered. Auth errors (401/403/404) are non-retryable.
+     *
+     * Channel names must be lowercase identifiers: `[a-z_][a-z0-9_]*` (max 63 chars).
+     */
+    realtime: {
+        subscribe: (params: BrowserRealtimeSubscribeParams) => Promise<BrowserRealtimeSubscription>;
+    };
+}
+/**
+ * A single NOTIFY message received from a Postgres channel.
+ *
+ * - `channel` — the lowercase channel name that fired.
+ * - `payload` — the text payload (may be null if NOTIFY was sent without one).
+ * - `processId` — the PID of the Postgres backend that called NOTIFY.
+ */
+interface BrowserRealtimeNotification {
+    channel: string;
+    payload: string | null;
+    processId: number;
+}
+/**
+ * Connection status of a realtime subscription.
+ *
+ * - `"connecting"` — establishing or re-establishing the SSE stream.
+ * - `"connected"` — stream is open, heartbeats are arriving, NOTIFY events are flowing.
+ * - `"reconnecting"` — the stream dropped and the SDK is waiting before the next retry.
+ * - `"disconnected"` — permanently stopped (via `unsubscribe()`, `signal` abort, or max retries exceeded).
+ */
+type BrowserRealtimeStatus = "connecting" | "connected" | "reconnecting" | "disconnected";
+interface BrowserRealtimeSubscribeParams {
+    databaseInstanceId?: string;
+    /** Channel names (normalized to lowercase on the server). */
+    channels: string[];
+    /** When aborted, the subscription stops permanently (equivalent to calling `unsubscribe()`). */
+    signal?: AbortSignal;
+    /** Called each time a Postgres NOTIFY message arrives. */
+    onNotify?: (msg: BrowserRealtimeNotification) => void;
+    /** Called once per connection attempt when the server confirms LISTEN is active. */
+    onReady?: (channels: string[]) => void;
+    /** Called when the stream encounters a non-retryable error or the server sends an error event. */
+    onError?: (message: string) => void;
+    /** Called whenever the connection status changes (connecting → connected → reconnecting → …). */
+    onStatusChange?: (status: BrowserRealtimeStatus) => void;
+    /** Called when the stream drops and the SDK will attempt to reconnect. `attempt` is 1-indexed. */
+    onDisconnect?: (info: {
+        attempt: number;
+        retryInMs: number;
+    }) => void;
+    /** Called when a reconnect attempt succeeds (stream is open again). */
+    onReconnect?: (info: {
+        attempt: number;
+    }) => void;
+    /** Maximum number of reconnect attempts before giving up. Set `0` to disable reconnect. Default: **Infinity** (never stops). */
+    maxReconnectAttempts?: number;
+    /** Base delay for exponential backoff (ms). Default: **1000**. */
+    reconnectBaseDelayMs?: number;
+    /** Maximum delay between reconnect attempts (ms). Default: **30000**. */
+    reconnectMaxDelayMs?: number;
+    /** How long to wait without a heartbeat before considering the connection dead (ms). Default: **45000** (3× the server's 15 s heartbeat interval). */
+    heartbeatTimeoutMs?: number;
+}
+/**
+ * Handle returned by `database.realtime.subscribe()`.
+ *
+ * - Call `unsubscribe()` to permanently close the subscription (no more reconnects).
+ * - Read `status` to check the current connection state at any time.
+ */
+interface BrowserRealtimeSubscription {
+    unsubscribe: () => void;
+    readonly status: BrowserRealtimeStatus;
 }
 declare class RagableBrowserAgentsClient {
     private readonly options;
@@ -1044,4 +1128,4 @@ declare function createClient(options: RagableClientOptions): Ragable;
 declare function createClient<Database extends RagableDatabase = DefaultRagableDatabase, AuthUser extends Record<string, unknown> = Record<string, unknown>>(options: RagableBrowserClientOptions): RagableBrowser<Database, AuthUser>;
 declare function createRagableServerClient(options: RagableClientOptions): Ragable;
 
-export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type BrowserAuthSession, type BrowserAuthTokens, type BrowserDataAuthMode, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, effectiveDataAuth, extractErrorMessage, formatPostgrestError, formatRetrievalContext, formatSdkError, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream };
+export { type AgentChatMessage, type AgentChatParams, type AgentChatResult, type AgentPublicChatParams, type AgentStreamEvent, type AgentSummary, AgentsClient, AuthBroadcastChannel, type AuthBroadcastMessage, type AuthChangeEvent, type AuthOptions, type AuthSession, type BrowserAuthSession, type BrowserAuthTokens, type BrowserDataAuthMode, type BrowserRealtimeNotification, type BrowserRealtimeStatus, type BrowserRealtimeSubscribeParams, type BrowserRealtimeSubscription, type BrowserSqlExecParams, type BrowserSqlExecResult, type BrowserSqlQueryParams, type BrowserSqlQueryResult, type ColumnName, type ColumnValue, CookieStorageAdapter, DEFAULT_RAGABLE_API_BASE, type DefaultRagableDatabase, type FormatContextOptions, type HttpMethod, type Json, LocalStorageAdapter, MemoryStorageAdapter, type PostgRESTFetch, type PostgRESTFetchParams, PostgrestDeleteReturningBuilder, PostgrestDeleteRootBuilder, PostgrestInsertReturningBuilder, PostgrestInsertRootBuilder, PostgrestInsertSdkErrorReturning, PostgrestInsertSdkErrorRoot, type PostgrestResult, PostgrestSelectBuilder, PostgrestTableApi, PostgrestUpdateReturningBuilder, PostgrestUpdateRootBuilder, type PostgrestUpsertOptions, PostgrestUpsertReturningBuilder, PostgrestUpsertRootBuilder, type RagClientForPipeline, type RagPipeline, type RagPipelineOptions, Ragable, RagableAbortError, RagableAuth, type RagableAuthConfig, RagableBrowser, RagableBrowserAgentsClient, RagableBrowserAuthClient, type RagableBrowserClientOptions, RagableBrowserDatabaseClient, type RagableClientOptions, type RagableDatabase, RagableError, RagableNetworkError, RagableRequestClient, RagableSdkError, type RagableTableDefinition, type RagableTableNames, RagableTimeoutError, type RequestOptions, type RetrieveParams, type RetryOptions, type RunQuery, type SessionStorage, SessionStorageAdapter, type ShiftAddDocumentParams, ShiftClient, type ShiftCreateIndexParams, type ShiftEntry, type ShiftIndex, type ShiftIngestResponse, type ShiftListEntriesParams, type ShiftListEntriesResponse, type ShiftSearchParams, type ShiftSearchResult, type ShiftUpdateIndexParams, type ShiftUploadFileParams, type ShiftUploadableFile, type SseJsonEvent, type SupabaseCompatSession, type TableInsertRow, type TableRow, type TableUpdatePatch, type Tables, type TablesInsert, type TablesUpdate, Transport, type TransportOptions, type TransportRequest, asPostgrestResponse, bindFetch, createBrowserClient, createClient, createRagPipeline, createRagableBrowserClient, createRagableServerClient, detectStorage, effectiveDataAuth, extractErrorMessage, formatPostgrestError, formatRetrievalContext, formatSdkError, generateIdempotencyKey, normalizeBrowserApiBase, parseSseDataLine, parseTransportResponse, readSseStream };

package/dist/index.js

@@ -2368,6 +2368,32 @@ var RagableBrowserDatabaseClient = class {
         return payload;
       });
     });
+    /**
+     * Postgres `LISTEN` / `NOTIFY` realtime via server-proxied SSE.
+     * Channels must be lowercase identifiers: `[a-z_][a-z0-9_]*` (max 63 chars).
+     */
+    /**
+     * Postgres `LISTEN` / `NOTIFY` realtime via server-proxied SSE.
+     *
+     * Returns a `BrowserRealtimeSubscription` with:
+     * - `unsubscribe()` — permanently close the subscription (stops reconnects).
+     * - `status` — current connection state: `"connecting"` | `"connected"` | `"reconnecting"` | `"disconnected"`.
+     *
+     * The subscription automatically reconnects with exponential backoff when the
+     * stream drops. Server heartbeats (every 15 s) are monitored — if none arrive
+     * within `heartbeatTimeoutMs` (default 45 s), the connection is treated as dead
+     * and a reconnect is triggered. Auth errors (401/403/404) are non-retryable.
+     *
+     * Channel names must be lowercase identifiers: `[a-z_][a-z0-9_]*` (max 63 chars).
+     */
+    __publicField(this, "realtime", {
+      subscribe: (params) => subscribeBrowserRealtime(
+        this.options,
+        this.ragableAuth,
+        this.fetchImpl,
+        params
+      )
+    });
     this.fetchImpl = bindFetch(options.fetch);
   }
   /** @internal Called by RagableBrowser to share the Transport instance. */
@@ -2381,6 +2407,190 @@ var RagableBrowserDatabaseClient = class {
     return new Headers(this.options.headers);
   }
 };
+function followAbortSignal(parent, child) {
+  if (!parent) return;
+  if (parent.aborted) {
+    child.abort();
+    return;
+  }
+  parent.addEventListener("abort", () => child.abort(), { once: true });
+}
+function backoffDelay(attempt, baseMs, maxMs) {
+  const exp = Math.min(baseMs * 2 ** (attempt - 1), maxMs);
+  const jitter = exp * (0.5 + Math.random() * 0.5);
+  return Math.round(jitter);
+}
+async function subscribeBrowserRealtime(options, ragableAuth, fetchImpl, params) {
+  const gid = requireAuthGroupId(options);
+  const databaseInstanceId = params.databaseInstanceId?.trim() || options.databaseInstanceId?.trim();
+  if (!databaseInstanceId) {
+    throw new RagableError(
+      "realtime.subscribe requires databaseInstanceId in params or on createBrowserClient({ databaseInstanceId })",
+      400,
+      { code: "SDK_MISSING_DATABASE_INSTANCE_ID" }
+    );
+  }
+  if (!Array.isArray(params.channels) || params.channels.length === 0) {
+    throw new RagableError(
+      "realtime.subscribe requires a non-empty channels array",
+      400,
+      { code: "SDK_REALTIME_CHANNELS_REQUIRED" }
+    );
+  }
+  const maxAttempts = params.maxReconnectAttempts ?? Infinity;
+  const baseDelay = params.reconnectBaseDelayMs ?? 1e3;
+  const maxDelay = params.reconnectMaxDelayMs ?? 3e4;
+  const heartbeatTimeout = params.heartbeatTimeoutMs ?? 45e3;
+  const lifecycleAc = new AbortController();
+  followAbortSignal(params.signal, lifecycleAc);
+  let currentStatus = "connecting";
+  const setStatus = (s) => {
+    if (s === currentStatus) return;
+    currentStatus = s;
+    params.onStatusChange?.(s);
+  };
+  const subscription = {
+    unsubscribe: () => lifecycleAc.abort(),
+    get status() {
+      return currentStatus;
+    }
+  };
+  setStatus("connecting");
+  async function connectOnce(signal) {
+    const token = await resolveDatabaseAuthBearer(options, ragableAuth);
+    const headers = new Headers(options.headers);
+    headers.set("Authorization", `Bearer ${token}`);
+    headers.set("Content-Type", "application/json");
+    const response = await fetchImpl(
+      `${normalizeBrowserApiBase()}/auth-groups/${gid}/data/realtime/stream`,
+      {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          databaseInstanceId,
+          channels: params.channels
+        }),
+        signal
+      }
+    );
+    if (!response.ok) {
+      const payload = await parseMaybeJsonBody(response);
+      const message = extractErrorMessage(payload, response.statusText);
+      throw new RagableError(message, response.status, payload);
+    }
+    const streamBody = response.body;
+    if (!streamBody) {
+      throw new RagableError("Realtime stream has no body", 502, {
+        code: "SDK_REALTIME_NO_BODY"
+      });
+    }
+    let heartbeatTimer = null;
+    const resetHeartbeatTimer = () => {
+      if (heartbeatTimer) clearTimeout(heartbeatTimer);
+      heartbeatTimer = setTimeout(() => {
+        streamReader?.cancel().catch(() => void 0);
+      }, heartbeatTimeout);
+    };
+    let streamReader = null;
+    try {
+      streamReader = streamBody.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      resetHeartbeatTimer();
+      const processEvent = (evt) => {
+        if (evt.type === "realtime:heartbeat") {
+          resetHeartbeatTimer();
+          return;
+        }
+        resetHeartbeatTimer();
+        if (evt.type === "realtime:ready") {
+          const ch = evt.channels;
+          setStatus("connected");
+          params.onReady?.(
+            Array.isArray(ch) ? ch.map((c) => String(c)) : []
+          );
+        } else if (evt.type === "notify") {
+          params.onNotify?.({
+            channel: String(evt.channel ?? ""),
+            payload: evt.payload === void 0 || evt.payload === null ? null : String(evt.payload),
+            processId: Number(evt.processId ?? 0)
+          });
+        } else if (evt.type === "realtime:error") {
+          params.onError?.(String(evt.message ?? "Realtime error"));
+        }
+      };
+      while (true) {
+        const { done, value } = await streamReader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let boundary = buffer.indexOf("\n\n");
+        while (boundary !== -1) {
+          const block = buffer.slice(0, boundary);
+          buffer = buffer.slice(boundary + 2);
+          for (const line of block.split("\n")) {
+            const dataPrefix = "data: ";
+            if (!line.startsWith(dataPrefix)) continue;
+            const json = line.slice(dataPrefix.length).trim();
+            if (!json || json === "[DONE]") continue;
+            try {
+              processEvent(JSON.parse(json));
+            } catch {
+            }
+          }
+          boundary = buffer.indexOf("\n\n");
+        }
+      }
+      return "stream_ended";
+    } finally {
+      if (heartbeatTimer) clearTimeout(heartbeatTimer);
+      streamReader?.releaseLock();
+    }
+  }
+  void (async () => {
+    let attempt = 0;
+    while (!lifecycleAc.signal.aborted) {
+      const iterAc = new AbortController();
+      followAbortSignal(lifecycleAc.signal, iterAc);
+      try {
+        const result = await connectOnce(iterAc.signal);
+        if (lifecycleAc.signal.aborted) break;
+        if (result === "stream_ended") {
+          attempt++;
+        }
+      } catch (e) {
+        if (lifecycleAc.signal.aborted) break;
+        if (e.name === "AbortError") break;
+        const status = e.status;
+        if (status === 400 || status === 401 || status === 403 || status === 404) {
+          params.onError?.(e.message);
+          break;
+        }
+        attempt++;
+      }
+      if (lifecycleAc.signal.aborted) break;
+      if (attempt > maxAttempts) {
+        params.onError?.(`Realtime: gave up after ${maxAttempts} reconnect attempts`);
+        break;
+      }
+      const delay = backoffDelay(attempt, baseDelay, maxDelay);
+      setStatus("reconnecting");
+      params.onDisconnect?.({ attempt, retryInMs: delay });
+      await new Promise((r) => {
+        const timer = setTimeout(r, delay);
+        const onAbort = () => {
+          clearTimeout(timer);
+          r();
+        };
+        lifecycleAc.signal.addEventListener("abort", onAbort, { once: true });
+      });
+      if (lifecycleAc.signal.aborted) break;
+      setStatus("connecting");
+      params.onReconnect?.({ attempt });
+    }
+    setStatus("disconnected");
+  })();
+  return subscription;
+}
 var RagableBrowserAgentsClient = class {
   constructor(options) {
     this.options = options;