@rebasepro/client 0.23.0 → 0.24.0

package/dist/offline-connectivity.d.ts

@@ -90,6 +90,12 @@ export declare class ConnectivityMonitor {
     private readonly clearTimer;
     /** Called when the backoff window expires, to drive an automatic retry. */
     onRetryDue?: () => void;
+    /**
+     * Called when the browser says the connection is back. Its own hook rather
+     * than {@link onRetryDue}: a client with automatic retries off sets no retry
+     * callback, and the `online` event has to wake it all the same.
+     */
+    onOnline?: () => void;
     private readonly handleOnline;
     private readonly handleOffline;
     constructor(options?: ConnectivityOptions);

package/dist/offline-store.d.ts

@@ -67,6 +67,14 @@ export interface PendingMutation {
     generatedId?: boolean;
     /** The payload: a row for create/update, an array of rows for createMany. */
     data?: Record<string, unknown> | Record<string, unknown>[];
+    /**
+     * For an `update` that consecutive edits were coalesced into: each edit,
+     * in the order the app made them. `data` is their merge, and is what is
+     * sent. Kept so a refusal of the merge over one field can be told apart
+     * from a refusal of the rest: the merge is split back into these and each
+     * replayed on its own, so only the edit the server refuses is undone.
+     */
+    parts?: Record<string, unknown>[];
     upsert?: boolean;
     /**
      * The request as it was already sent once, for a write tried online

package/dist/offline.d.ts

@@ -96,6 +96,24 @@ export interface OfflineStatus {
     lastError?: string;
 }
 export type { LiveResult, ObserveOptions, RowSnapshotMeta } from "./collection.js";
+/** Which queue {@link OfflineApi.pending} and {@link OfflineApi.clear} act on. */
+export interface OfflineQueueOptions {
+    /**
+     * The writes queued while nobody was signed in, instead of the current
+     * user's.
+     *
+     * While someone is signed in these are held back: they were not made by
+     * that user, so they are never replayed under their credentials, and never
+     * moved into their queue. `pending({ orphaned: true })` lists them so the
+     * app can decide — re-issue them as the signed-in user, or discard them
+     * with `clear({ orphaned: true })`. Left alone, they replay the next time
+     * nobody is signed in.
+     *
+     * With nobody signed in they are the current queue, and are not orphaned:
+     * `pending({ orphaned: true })` lists nothing.
+     */
+    orphaned?: boolean;
+}
 /** What `client.offline` exposes to the app. */
 export interface OfflineApi {
     /** Replay the queue now. Resolves with what was flushed and what remains. */
@@ -103,8 +121,12 @@ export interface OfflineApi {
         flushed: number;
         remaining: number;
     }>;
-    /** The queued mutations for the current user, oldest first. */
-    pending(): Promise<PendingMutation[]>;
+    /**
+     * The queued mutations for the current user, oldest first — or, with
+     * `{ orphaned: true }`, the ones queued while nobody was signed in (see
+     * {@link OfflineQueueOptions.orphaned}).
+     */
+    pending(options?: OfflineQueueOptions): Promise<PendingMutation[]>;
     /** The current engine state — connectivity, queue depth, last sync. */
     status(): OfflineStatus;
     /** Subscribe to {@link OfflineStatus} changes (for a sync indicator). */
@@ -114,8 +136,12 @@ export interface OfflineApi {
      * Destructive: queued writes are lost, not replayed. For "discard my
      * offline changes" flows, not for sign-out (scoping already isolates
      * users).
+     *
+     * With `{ orphaned: true }`, drop the writes queued while nobody was
+     * signed in, and the local rows they were applied to, instead — the
+     * current user's are left alone.
      */
-    clear(): Promise<void>;
+    clear(options?: OfflineQueueOptions): Promise<void>;
     /** Subscribe to queue-size changes (for a "pending changes" badge). */
     onQueueChange(listener: (count: number) => void): () => void;
 }
@@ -140,6 +166,26 @@ export declare class OfflineManager {
     private readonly inners;
     private readonly connectivity;
     private scope;
+    /**
+     * Set while the manager does not know whose data it holds: from
+     * {@link holdScope} until the next {@link setScope}. `scope` is not
+     * consulted meanwhile — no operation gets a {@link ScopeTicket}, and
+     * nothing reads or writes the store.
+     */
+    private scopeHold?;
+    /**
+     * Bumped by every change of user, and by `clear()`.
+     *
+     * The load paths always re-checked the scope after their awaits; the write
+     * paths did not. A `find` sent for user A that answered after B had signed
+     * in wrote A's RLS-filtered rows into B's local database, under B's keys,
+     * and showed them to B's observers; a replay acknowledged after the switch
+     * dequeued a key under B's scope that did not exist, so A's write stayed
+     * queued and was sent again when A came back. Every write now carries the
+     * {@link ScopeTicket} its operation started under, and one that is stale
+     * touches nothing that belongs to the new user.
+     */
+    private scopeEpoch;
     /** The local database: normalized rows and query snapshots per collection. */
     private collections;
     /** In-memory mirror of the current scope's queue, in replay order. */
@@ -185,6 +231,35 @@ export declare class OfflineManager {
      * across a sign-out/sign-in on a shared browser.
      */
     setScope(uid: string | undefined): void;
+    /**
+     * Forget whose data this is until the next {@link setScope}.
+     *
+     * For the time before the client knows who is signed in — a session being
+     * restored on load. Taking that time for "signed out" would put the user's
+     * own writes in the signed-out queue, which no sign-in replays, and show
+     * them the signed-out local database instead of theirs.
+     *
+     * Meanwhile the manager has no scope at all. Every operation — a read, a
+     * write, a replay, `pending()`, `clear()` — waits for one and then runs
+     * for whoever it turns out to be, and nothing reads or writes the store.
+     * A realtime frame arriving in between is handed on as the server sent it
+     * and kept nowhere.
+     */
+    holdScope(): void;
+    /** Let go of the current user's rows and queue: in memory, and on screen. */
+    private leaveScope;
+    /** Settles once the manager knows whose data it holds — see {@link holdScope}. */
+    private scopeKnown;
+    /**
+     * The user an operation is running for — see {@link scopeEpoch} — or
+     * nothing while that is not known ({@link holdScope}). An operation takes
+     * it as `this.ticket() ?? await this.nextTicket()`, before its first await.
+     */
+    private ticket;
+    /** The ticket of whoever the held scope turns out to be. */
+    private nextTicket;
+    /** Whether an operation's user is still the signed-in one. */
+    private isCurrent;
     /**
      * Throw away every local row, for a scope change or an explicit clear.
      *
@@ -353,6 +428,15 @@ export declare class OfflineManager {
      * silently lose writes the server would have accepted.
      */
     private rejectMutation;
+    /**
+     * Put the separate edits a coalesced `update` was made of back in the
+     * queue, in its place and in their order, each with the row as it stood
+     * before it as its rollback — so a refusal undoes that edit alone.
+     *
+     * Their ids extend the merged op's, which sorts them after it and before
+     * whatever was queued next, so the queue's order survives a reload.
+     */
+    private splitCoalesced;
     /** Every row id a mutation writes to. */
     private idsOf;
     private drop;

package/dist/query-contract.types.d.ts

@@ -67,11 +67,11 @@ export declare const orderByColumn: FindParams<ContractRow>;
  * turning every typo into an unsorted 200 in production.
  */
 export declare const orderByTypo: FindParams<ContractRow>;
-export declare const fluentScore: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
-export declare const fluentColumn: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
-export declare const fluentTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentScore: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
+export declare const fluentColumn: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
+export declare const fluentTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
 /** Vector search must be reachable from the builder, and chain. */
-export declare const fluentVector: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentVector: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
 /**
  * `array-contains` takes an **element** of the column, not the column.
  *
@@ -82,38 +82,38 @@ export declare const fluentVector: (qb: SDKQueryBuilderInterface<ContractRow>) =
  * did compile, `["featured"]`, builds `@> ARRAY[$1]` with the whole array bound
  * as the single element and matches nothing, forever, with no error anywhere.
  */
-export declare const fluentArrayContains: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
-export declare const fluentArrayContainsWrapped: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentArrayContains: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
+export declare const fluentArrayContainsWrapped: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
 /**
  * Same defect, and the case the relation compiler was specifically built for:
  * a to-many relation is emitted as `Array<TargetRow>`, and the compiler answers
  * `array-contains` on it by comparing **ids**. So the id must be accepted even
  * though it is not the element type.
  */
-export declare const fluentRelationContains: (qb: SDKQueryBuilderInterface<PostRow>, tagId: string) => SDKQueryBuilderInterface<PostRow>;
-export declare const fluentRelationIn: (qb: SDKQueryBuilderInterface<PostRow>, tagIds: string[]) => SDKQueryBuilderInterface<PostRow>;
-export declare const fluentRelationTypo: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow>;
+export declare const fluentRelationContains: (qb: SDKQueryBuilderInterface<PostRow>, tagId: string) => SDKQueryBuilderInterface<PostRow, import("@rebasepro/types").IncludeSpec>;
+export declare const fluentRelationIn: (qb: SDKQueryBuilderInterface<PostRow>, tagIds: string[]) => SDKQueryBuilderInterface<PostRow, import("@rebasepro/types").IncludeSpec>;
+export declare const fluentRelationTypo: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow, import("@rebasepro/types").IncludeSpec>;
 /** The list operators take a list of elements — or one, read as a one-element list. */
-export declare const fluentInList: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
-export declare const fluentInScalar: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
-export declare const fluentInNested: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentInList: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
+export declare const fluentInScalar: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
+export declare const fluentInNested: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
 /** A comparison takes one value. `eq(column, ["a","b"])` is not a query anyone meant. */
-export declare const fluentEqArray: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentEqArray: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
 /**
  * A pattern is a string on every column type. The driver casts, so refusing
  * `"%3%"` on a numeric column was the type being stricter than the runtime.
  */
-export declare const fluentLikeOnNumber: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentLikeOnNumber: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
 /** The null operators ignore their value; `null` is the conventional spelling. */
-export declare const fluentIsNull: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentIsNull: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
 /**
  * A caller holding an unnarrowed operator — a dynamic filter UI — must keep
  * compiling. `WhereValueFor` distributes over the operator, so this is the
  * union of every branch rather than a `never`.
  */
-export declare const fluentDynamicOp: (qb: SDKQueryBuilderInterface<ContractRow>, op: WhereFilterOp) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentDynamicOp: (qb: SDKQueryBuilderInterface<ContractRow>, op: WhereFilterOp) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
 /** Two conditions on one column: the shape the Mongo compiler used to drop. */
-export declare const fluentRange: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentRange: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
 /** The object form must accept exactly what the fluent form accepts. */
 export declare const paramsArrayContains: FindParams<ContractRow>;
 /** …and the array-of-tuples form the builder produces from two `.where()` calls. */
@@ -150,11 +150,11 @@ export declare const rowStaysIndexable: (result: FindResult<ContractRow>) => Rec
  * which is to say: on every project that took the trouble to be typed.
  */
 /** 1. A relation path. `find({ where: { "author.name": … } })` always compiled. */
-export declare const fluentRelationPath: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow>;
+export declare const fluentRelationPath: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow, import("@rebasepro/types").IncludeSpec>;
 /** 2. A JSON path into a `jsonb` column — `?metadata->>tier=eq.gold` on the wire. */
-export declare const fluentJsonPath: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentJsonPath: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
 /** 3. An aggregate over a to-many relation, which `FindParams.orderBy` takes. */
-export declare const fluentRelationAggregateSort: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow>;
+export declare const fluentRelationAggregateSort: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow, import("@rebasepro/types").IncludeSpec>;
 /** 4. Paging past the `limit` ceiling, which the client can do and the builder could not. */
 export declare const fluentIterate: (qb: SDKQueryBuilderInterface<ContractRow>) => AsyncIterableIterator<ContractRow>;
 export declare const fluentFindAll: (qb: SDKQueryBuilderInterface<ContractRow>) => Promise<ContractRow[]>;
@@ -164,9 +164,9 @@ export declare const fluentFindAll: (qb: SDKQueryBuilderInterface<ContractRow>)
  * `unknown` — turning every one of the assertions above into a silent pass.
  * These are the same refusals as before.
  */
-export declare const fluentPathTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
-export declare const fluentPathDoesNotLoosenValues: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
-export declare const fluentAggregateSortTypo: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow>;
+export declare const fluentPathTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
+export declare const fluentPathDoesNotLoosenValues: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
+export declare const fluentAggregateSortTypo: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow, import("@rebasepro/types").IncludeSpec>;
 /** And the object form still takes all four, unchanged. */
 export declare const paramsRelationPath: FindParams<PostRow>;
 export declare const paramsJsonPath: FindParams<ContractRow>;

package/dist/realtime-channel.d.ts

@@ -98,6 +98,11 @@ export interface ChannelTransport {
     sendMessage(message: Record<string, unknown>): Promise<unknown>;
     onChannelMessage(channel: string, handler: (message: ChannelMessage) => void): () => void;
     onReconnect(handler: () => void): () => void;
+    /**
+     * Notified once per outage that outlasted a blip. Optional so a test
+     * transport need not implement it.
+     */
+    onConnectionLost?(handler: (error: RebaseApiError) => void): () => void;
 }
 export declare class RebaseRealtimeChannel {
     readonly name: string;

package/dist/sdk_query_builder.d.ts

@@ -1,4 +1,4 @@
-import { FindResult, LogicalCondition, PageWalkOptions, RelationAggregateSort, SDKCollectionClient, SDKQueryBuilderInterface, WhereFilterOp, WhereValueFor, type AggregateParams, type AggregateRow, type ComputedSortField, type FieldPath, type IncludeSpec, type NonColumnFieldPath, type NullsPlacement } from "@rebasepro/types";
+import { FindResult, LogicalCondition, PageWalkOptions, RelationAggregateSort, SDKCollectionClient, SDKQueryBuilderInterface, WhereFilterOp, WhereValueFor, type AggregateParams, type AggregateResult, type ComputedSortField, type FieldPath, type IncludeSpec, type NonColumnFieldPath, type NullsPlacement } from "@rebasepro/types";
 /**
  * SDK Query Builder — returns flat rows (`FindResult<M>`) instead of
  * Entity-wrapped results (`FindResponse<M>`).
@@ -173,7 +173,7 @@ export declare class SDKQueryBuilder<M extends Record<string, unknown> = Record<
      * // [{ status: "paid", sum_total: 41822.5 }, …]
      * ```
      */
-    aggregate(params: Omit<AggregateParams<M>, "where" | "logical" | "searchString">): Promise<AggregateRow[]>;
+    aggregate(params: Omit<AggregateParams<M>, "where" | "logical" | "searchString">): Promise<AggregateResult>;
     /**
      * Page through everything this query matches, one row at a time.
      *

package/dist/sql-script.d.ts

@@ -0,0 +1,10 @@
+import type { SqlScriptResult } from "@rebasepro/types";
+/**
+ * Read an `EXECUTE_SQL_SUCCESS` payload for a script run as a
+ * {@link SqlScriptResult}, checking every field rather than trusting the frame.
+ *
+ * A server from before scripts existed answers `{ result }` alone, with parsed
+ * values. Its rows are kept, as text, and no column is said to come from
+ * anywhere — the console edits no cell of a result it cannot trace.
+ */
+export declare function readSqlScriptResult(payload: unknown): SqlScriptResult;

package/dist/transport.d.ts

@@ -1,4 +1,4 @@
-import { AggregateParams, FindParams as TypesFindParams, FindResponse as TypesFindResponse } from "@rebasepro/types";
+import { AggregateParams, FindParams as TypesFindParams, FindResponse as TypesFindResponse, type IncludeSpec } from "@rebasepro/types";
 export { RebaseApiError } from "@rebasepro/types";
 export type { RebaseErrorInit } from "@rebasepro/types";
 export interface RebaseClientConfig {
@@ -95,6 +95,19 @@ export interface RebaseClientConfig {
      * is not settable here; it always comes from the token.
      */
     headers?: Record<string, string>;
+    /**
+     * Run every request as this user, named by uid: sent as
+     * `x-rebase-impersonate` on each HTTP request, and with the realtime
+     * socket's sign-in.
+     *
+     * For checking what one user can see and do against the real row-level
+     * security, as Studio's API explorer and JS editor do. Only an
+     * administrator's own session may — the server refuses it for anyone
+     * else, and always for an API key or the service key. The data API,
+     * custom functions and realtime run as the named user; every other route
+     * refuses the request rather than answer as the administrator.
+     */
+    impersonate?: string;
 }
 /**
  * Facts about the surrounding client that the transport cannot read off its own
@@ -124,7 +137,7 @@ export declare const ANONYMOUS_SERVER_CLIENT_WARNING: string;
  * `orderBy` went back to accepting any column name — the alias, not the
  * definition, was where the typing was lost.
  */
-export type FindParams<M extends Record<string, unknown> = Record<string, unknown>> = TypesFindParams<M>;
+export type FindParams<M extends Record<string, unknown> = Record<string, unknown>, Inc = IncludeSpec> = TypesFindParams<M, Inc>;
 export type FindResponse<T> = TypesFindResponse<T extends Record<string, unknown> ? T : Record<string, unknown>>;
 /**
  * Refuse a filter whose *value* is missing.

package/dist/websocket.d.ts

@@ -1,4 +1,5 @@
-import { DeleteProps, CollectionConfig, FetchCollectionProps, ListenCollectionProps, FetchOneProps, SaveProps, CollectionUpdateMeta, ChannelMessage, TableMetadata, BranchInfo } from "@rebasepro/types";
+import { DeleteProps, CollectionConfig, FetchCollectionProps, ListenCollectionProps, FetchOneProps, SaveProps, CollectionUpdateMeta, ChannelMessage, TableMetadata, BranchInfo, RebaseApiError, type RealtimeConnectionState } from "@rebasepro/types";
+import type { SqlScriptResult } from "@rebasepro/types";
 export interface RebaseWebSocketConfig {
     websocketUrl: string;
     /** Optional auth token getter for WebSocket authentication */
@@ -7,6 +8,11 @@ export interface RebaseWebSocketConfig {
     WebSocket?: typeof WebSocket;
     /** Callback to handle unauthorized requests or token expiration (refreshes auth session) */
     onUnauthorized?: () => Promise<boolean>;
+    /**
+     * Sign in as this user rather than as the token's own — the socket half of
+     * `RebaseClientConfig.impersonate`. Sent with every `AUTHENTICATE`.
+     */
+    impersonate?: string;
 }
 export declare class RebaseWebSocketClient {
     private websocketUrl;
@@ -18,16 +24,41 @@ export declare class RebaseWebSocketClient {
     /** Set by `close()`. Blocks any later operation from silently redialling. */
     private closedByCaller;
     /**
-     * Set when the backoff budget ran out, cleared by anything that earns a
-     * fresh one.
+     * Set when the backoff budget ran out with nothing registered, cleared by
+     * anything that earns a fresh one.
      *
-     * Unlike {@link closedByCaller} this is not final — nobody *asked* for the
-     * socket to stay down. Five attempts with exponential backoff is about a
-     * minute, which a laptop lid, a wifi handover or a backend rollout all
-     * exceed routinely; treating that as permanent meant realtime silently
-     * stopped for the rest of the page's life, with a reload the only cure.
+     * Only reachable with nothing registered: while a subscription or a joined
+     * channel exists the client never stops retrying (see `attemptReconnect`).
+     * And it is not final like {@link closedByCaller} — nobody *asked* for the
+     * socket to stay down, so the next subscribe dials again.
      */
     private gaveUp;
+    /** See {@link state}. */
+    private connectionState;
+    private stateListeners;
+    /**
+     * Whether the current outage has been reported to the registrations as
+     * `CONNECTION_LOST`. Once per outage: cleared when a socket opens.
+     */
+    private outageReported;
+    /**
+     * Where the connection is.
+     *
+     * - `idle` — no socket, and none wanted yet (the connection is lazy), or
+     *   the last one was dropped by a sign-out.
+     * - `connecting` — dialling, with no outage in progress.
+     * - `connected` — the socket is open.
+     * - `reconnecting` — the socket dropped and the client is redialling. A
+     *   blip, so far: nothing has been reported.
+     * - `disconnected` — the outage has outlasted the blip budget. Every
+     *   subscription and joined channel has been told `CONNECTION_LOST` once;
+     *   the client keeps redialling (every 30 s at most) while any exists.
+     * - `closed` — `client.close()`. Final.
+     */
+    get state(): RealtimeConnectionState;
+    /** Called on every change of {@link state}. Returns the unsubscribe. */
+    onStateChange(listener: (state: RealtimeConnectionState) => void): () => void;
+    private setState;
     /**
      * Whether a socket exists at all (open or still opening).
      *
@@ -41,6 +72,13 @@ export declare class RebaseWebSocketClient {
     onChannelMessage(channel: string, handler: (message: ChannelMessage) => void): () => void;
     /** Notified after the socket comes back, so channels can re-join. */
     onReconnect(handler: () => void): () => void;
+    /**
+     * Notified once per outage that outlasted a blip, with the
+     * `CONNECTION_LOST` error — so a joined channel can tell its `onError`
+     * handlers, as subscriptions are told through theirs.
+     */
+    onConnectionLost(handler: (error: RebaseApiError) => void): () => void;
+    private connectionLostHandlers;
     on(event: "connect" | "disconnect" | "reconnect" | "error", cb: (...args: unknown[]) => void): () => boolean;
     private emit;
     private collectionSubscriptions;
@@ -49,7 +87,18 @@ export declare class RebaseWebSocketClient {
     private backendToEntityKey;
     private pendingRequests;
     private reconnectAttempts;
+    /**
+     * With nothing registered, how many failed redials before the client stops
+     * trying until something asks for the connection. With a registration it
+     * never stops.
+     */
     private maxReconnectAttempts;
+    /**
+     * How many failed redials make a blip an outage: the point at which every
+     * registration is told `CONNECTION_LOST` and {@link state} reads
+     * `disconnected`. Three is 2 + 4 + 8 s of backoff, about 14 s down.
+     */
+    private lostAfterAttempts;
     /**
      * Whether a socket of this client has ever opened — what makes the next
      * open a *reconnect*, whose server has forgotten every subscription and
@@ -71,6 +120,7 @@ export declare class RebaseWebSocketClient {
     private WebSocketConstructor;
     onUnauthorized?: () => Promise<boolean>;
     private refreshInProgress;
+    private readonly impersonate?;
     constructor(config: RebaseWebSocketConfig);
     /**
      * Open the socket if it is not open (or opening) already.
@@ -81,12 +131,20 @@ export declare class RebaseWebSocketClient {
      */
     ensureConnected(): void;
     /**
-     * The browser says the network is back — the usual reason the budget ran
-     * out in the first place. Registered lazily so a Node client, or a page
-     * that never subscribes, adds no listener.
+     * Dial now rather than at the next backoff step — the browser says the
+     * network is back, or the tab is in front of the user again. Both are the
+     * usual end of an outage; neither fires for a server restart, which the
+     * backoff covers.
+     */
+    private retryNow;
+    /**
+     * `online` and `visibilitychange`. Registered lazily so a Node client, or a
+     * page that never subscribes, adds no listener.
      */
-    private installOnlineListener;
+    private installNetworkListeners;
+    private removeNetworkListeners;
     private onlineListener;
+    private visibilityListener;
     /**
      * Authenticate the WebSocket connection
      */
@@ -122,6 +180,27 @@ export declare class RebaseWebSocketClient {
      */
     private shouldSendQueued;
     private attemptReconnect;
+    /**
+     * Whether anything depends on the socket coming back: a subscription, a
+     * joined channel, or a request whose caller is still waiting for a socket.
+     */
+    private hasRegistrations;
+    /**
+     * Tell every subscription and joined channel, once per outage, that the
+     * connection is down and their data is not updating.
+     *
+     * Registrations are kept — that is the difference from a subscribe that
+     * failed. When the socket is back they are re-subscribed, and the fresh
+     * `onUpdate` is the recovery.
+     */
+    private reportConnectionLost;
+    private notifyError;
+    /**
+     * A listener attaching while an outage is being reported is told at once:
+     * its subscribe waits for a socket that may be minutes away, and nothing
+     * else would say so.
+     */
+    private reportOutageTo;
     private isAuthError;
     private handleAuthFailure;
     /**
@@ -138,6 +217,15 @@ export declare class RebaseWebSocketClient {
      * Not part of the stable surface — prefer `client.realtime.channel(name)`.
      */
     sendMessage(message: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Frames whose caller has already been answered — timed out, or rejected
+     * by a close. One can still be on its way to the socket (awaiting
+     * authentication), and must not be written after its caller was told it
+     * failed.
+     */
+    private abandonedFrames;
+    /** Whether the server answers this frame with a response envelope. */
+    private expectsResponse;
     private doSendMessage;
     fetchCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;
     fetchOne<M extends Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;
@@ -147,6 +235,16 @@ export declare class RebaseWebSocketClient {
         database?: string;
         role?: string;
     }): Promise<Record<string, unknown>[]>;
+    /**
+     * Run a script a person wrote — the Studio console — and get back what its
+     * last statement returned, every value as the database's text, with the
+     * table column each result column was read from. See
+     * `SQLAdmin.runSqlScript`.
+     */
+    runSqlScript(sql: string, options?: {
+        database?: string;
+        role?: string;
+    }): Promise<SqlScriptResult>;
     fetchAvailableDatabases(): Promise<string[]>;
     fetchAvailableRoles(): Promise<string[]>;
     fetchApplicationRoles(): Promise<string[]>;
@@ -233,11 +331,6 @@ export declare class RebaseWebSocketClient {
     private armPendingSubscribeWatchdogs;
     private sendCollectionSubscribeWatchdog;
     private sendEntitySubscribeWatchdog;
-    /**
-     * Fail every subscription that never received data. Called when reconnection
-     * is given up on, so views surface an error instead of spinning forever.
-     */
-    private failAllPendingSubscriptions;
     /**
      * Re-send all active subscriptions to the backend after a reconnect.
      * The server wipes subscription state when a client disconnects, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/client",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "HTTP SDK client for the Rebase custom backend",
   "keywords": [
     "rebase",
@@ -41,9 +41,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/common": "0.23.0",
-    "@rebasepro/utils": "0.23.0",
-    "@rebasepro/types": "0.23.0"
+    "@rebasepro/common": "0.24.0",
+    "@rebasepro/utils": "0.24.0",
+    "@rebasepro/types": "0.24.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",