@rebasepro/client 0.22.0 → 0.24.0

package/dist/offline-connectivity.d.ts

@@ -30,6 +30,14 @@ export declare function isNetworkError(error: unknown): boolean;
  * server's own message says, and exactly what this SDK used not to do.
  */
 export declare function isIdempotencyInProgressError(error: unknown): boolean;
+/**
+ * Is this key held for a different request than the one just sent with it?
+ *
+ * For a create the queue already sent once, that is an answer rather than a
+ * failure: the key is live only because the first attempt got through and
+ * committed, and only its response went missing.
+ */
+export declare function isIdempotencyKeyReusedError(error: unknown): boolean;
 /** Is this failure worth another attempt later? */
 export declare function isRetryableError(error: unknown): boolean;
 /**
@@ -82,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-query.d.ts

@@ -15,7 +15,11 @@ export { DEFAULT_LIST_LIMIT as DEFAULT_PAGE_SIZE } from "@rebasepro/types";
  * which is how NULL propagates through a comparison.
  */
 export declare function compareValues(a: unknown, b: unknown): number | undefined;
-/** Equality with the wire's type erasure allowed for, but never across NULL. */
+/**
+ * Equality with a string filter value allowed to name a number, a boolean or
+ * an instant, but never across NULL. Two strings are equal only when they are
+ * the same string, as text is in Postgres.
+ */
 export declare function looseEquals(a: unknown, b: unknown): boolean;
 /** Evaluate one canonical operator against one row value. */
 export declare function matchesOperator(rowValue: unknown, op: WhereFilterOp, filterValue: unknown): boolean;
@@ -72,14 +76,14 @@ export declare function isExactlyEvaluable(params?: FindParams): boolean;
  *
  * Asked of the rows rather than of the query, because unlike a filter this one
  * *is* decidable from the data in hand: {@link compareValues} reaches the
- * collator only when it cannot read both operands as numbers, and `toComparable`
- * has already turned dates and relations into numbers and ids by then. If every
+ * collator only when neither operand is a number, and `toComparable` has
+ * already turned dates and relations into numbers and ids by then. If every
  * value on the sort column normalises to a number, the collator is unreachable
  * and the local order is the server's order.
  *
  * A text column is therefore refused — see {@link isExactlyEvaluable} for why
- * the two cannot be made to agree — and so is a column this page happens to see
- * only as strings, which is the same thing from here.
+ * the two cannot be made to agree — including one holding only digits, which
+ * Postgres orders as text ("10", "100", "9").
  *
  * Nulls are fine either way: they are ordered by an explicit rule (last
  * ascending, first descending) that matches Postgres and never reaches the

package/dist/offline-store.d.ts

@@ -67,7 +67,37 @@ 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
+     * that failed on the network before it was queued. Nothing says whether
+     * it reached the server — only the answer may have been lost — so replay
+     * keeps its key. For a create, sent with the rows as queued (their minted
+     * ids, which later offline writes may reference), the server either takes
+     * them, or, having committed the first attempt, refuses the key as held
+     * for a different request, and this request is sent again for its stored
+     * answer. Replaying under a fresh key wrote the rows a second time.
+     *
+     * An `update` or `delete` carries only the key: its queued request is the
+     * one it sent, since nothing is merged into an op that has `sent`.
+     */
+    sent?: {
+        idempotencyKey: string;
+        /** `create`: the row it was called with; `createMany`: the rows. */
+        data?: Record<string, unknown> | Record<string, unknown>[];
+        /** `create`: the `id` argument it was called with. */
+        id?: string | number;
+        /** `createMany`: the conflict target the batch was sent with. */
+        onConflict?: readonly string[];
+    };
     queuedAt: number;
     /** How many times replay has been attempted (diagnostics for a stuck queue). */
     attempts?: number;

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.
      *
@@ -221,6 +296,19 @@ export declare class OfflineManager {
      * query the server has never answered here.
      */
     private answer;
+    /**
+     * Answer a projected query (`fields`, `distinct`) from the server's own
+     * answer to it.
+     *
+     * The server's rows are the answer. The local database contributes only
+     * what it knows better: a row with unsynced writes shows them, narrowed to
+     * the columns the server sent, or drops out if it was deleted here or
+     * edited out of a filter this side can evaluate; and rows created here
+     * join the first page when there is somewhere to put them. A distinct
+     * query, or an order on a column the projection does not carry, leaves
+     * them out, and the result says it is partial.
+     */
+    private projectedAnswer;
     private localFind;
     /**
      * A temporary id of the type this collection's ids actually have.
@@ -256,6 +344,12 @@ export declare class OfflineManager {
      * Rows that came back unchanged keep their identity and revision, so a
      * refetch that changed nothing does not re-render every live query that
      * touches them — or rewrite them all to disk.
+     *
+     * A `projection` (see {@link isProjection}) only refreshes the columns it
+     * carries on rows already held, and never creates one. It is not a row:
+     * stored as one, it replaced the full row every other query reads and
+     * wrote the narrowed copy to disk, so a list lost its columns because a
+     * dropdown elsewhere asked for titles.
      */
     private ingest;
     /**
@@ -292,6 +386,17 @@ export declare class OfflineManager {
     }>;
     private flush;
     private replay;
+    /**
+     * Send a queued write under its key.
+     *
+     * A write the queue sent once already, before it was queued, carries that
+     * attempt's key and is sent under it again, as queued. If the server holds
+     * the key for a different request, the difference is the ids minted here
+     * — so the first attempt committed and only its answer was lost, and
+     * sending that request again returns the stored answer instead of a
+     * second copy of the rows.
+     */
+    private sendQueuedWrite;
     /**
      * Take the server's version of a row the client created offline.
      *
@@ -323,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;
@@ -133,6 +138,27 @@ export declare class RebaseRealtimeChannel {
      */
     private pendingLive;
     private catchUpInFlight;
+    /**
+     * Whether {@link lastSeq} is a position this client reached, rather than
+     * the zero of a handle that has not caught up yet.
+     *
+     * A client joining for the first time asks for whatever is retained, so
+     * history pruned before it ever joined is not something it missed. Only a
+     * client with a position can have a hole in what it saw.
+     */
+    private positioned;
+    /** The page size the catch-up in flight asked for, reused for its later pages. */
+    private catchUpLimit;
+    /**
+     * `latestSeq` of an empty page that left this client behind, while a
+     * second request confirms it.
+     *
+     * The server reads the retained messages and then the cursor, so a message
+     * committed between the two shows up in `latestSeq` and not in the page.
+     * The second request returns it if it exists; only a second empty page
+     * means the messages up to this seq are gone.
+     */
+    private emptyTailSeq;
     /**
      * Deadline for a catch-up response.
      *
@@ -234,6 +260,12 @@ export declare class RebaseRealtimeChannel {
      * retention cannot be served; `CHANNEL_BUS_PAYLOAD_TOO_LARGE` when a
      * broadcast on an ephemeral channel is too big to cross the bus.
      *
+     * `CHANNEL_HISTORY_GAP` is raised by the client: a catch-up found that the
+     * server no longer retains messages this client never received, so its
+     * state has a hole a replay cannot fill. `details` is `{ from, to }`, the
+     * inclusive range of sequence numbers missed. Resync the channel's state
+     * from its source of truth.
+     *
      * These used to be dropped on the floor — there is no promise to reject on
      * a fire-and-forget frame, so a forbidden broadcast looked exactly like a
      * delivered one. With no handler attached they are logged as a warning,
@@ -271,6 +303,9 @@ export declare class RebaseRealtimeChannel {
     private stopHeartbeat;
     /** Fold an incoming frame into the roster and fan it out. */
     private handle;
+    /** Tell the app that retention dropped messages it never received. */
+    private reportHistoryGap;
+    private emitError;
     /** Deliver everything held back during a catch-up, in sequence order. */
     private flushPendingLive;
     private deliver;

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,8 +137,25 @@ 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.
+ *
+ * `where: { status: ["==", undefined] }` used to serialize to the literal
+ * string, so `status=eq.undefined` went out on the wire and the server dutifully
+ * looked for rows whose status is the four-letter word "undefined". The caller
+ * saw an empty page, not an error — the classic shape of a variable that was
+ * never set.
+ *
+ * Dropping the condition instead would be worse than sending it: the query
+ * would come back *unfiltered*, which for an ownership or tenant filter means
+ * returning rows the caller never asked to see. So this is a hard error, and
+ * both correct spellings are named in the message: omit the key to skip the
+ * filter, or use `["is-null", null]` to match SQL NULL (which still
+ * serializes — `null` is a value, `undefined` is the absence of one).
+ */
+export declare function assertNoUndefinedFilterValues(where: Record<string, unknown>): void;
 export declare function buildQueryString(params?: FindParams): string;
 /**
  * The query string for `GET /<collection>/aggregate`.