@rebasepro/client 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/offline.d.ts

@@ -1,3 +1,4 @@
+import { RebaseApiError } from "./transport.js";
 import { SDKCollectionClient } from "@rebasepro/types";
 import { CollectionClient } from "./collection.js";
 import { OfflineStore, PendingMutation } from "./offline-store.js";
@@ -81,7 +82,76 @@ export interface OfflineConfig {
      * Network failures are not errors: those mutations stay queued.
      */
     onSyncError?: (error: Error, mutation: PendingMutation) => void;
+    /**
+     * Detect conflicts when a queued edit replays: an `update` made offline
+     * is sent with `If-Match`, the version of the row it was made against,
+     * and if someone changed the row on the server since, this decides what
+     * happens to the edit:
+     *
+     * - `"overwrite"`: send it again without the precondition. Last writer
+     *   wins, as without this option.
+     * - `"discard"`: drop it. The row goes back to what it was before the
+     *   edit, as for a rejection, but it is not reported to `onSyncError`
+     *   (writes queued on top of it are, as `DEPENDENCY_REJECTED`), and the
+     *   row is read again from the server.
+     *
+     * The edit's version is the one the row's last read reported: a
+     * `findById`, a `listenById` frame, or the answer to an earlier `update`.
+     * A row last seen in a `find()` or `listen()` list has no version, and an
+     * edit made on top of another queued write to the same row has none
+     * either; those replay without a precondition. A caller's own `ifMatch` is
+     * kept on a queued edit too.
+     *
+     * The queue waits while this runs, so a prompt can ask the user. Without
+     * it — the default — replay sends no precondition and the last writer
+     * wins, per field.
+     */
+    onConflict?: (error: RebaseApiError, mutation: PendingMutation) => ConflictResolution | Promise<ConflictResolution>;
+    /**
+     * Remember, on this device, the last user who signed in, and open their
+     * local database when a reload cannot reach the server to restore the
+     * session. Off by default.
+     *
+     * This matters in cookie mode, where nothing about the session is stored
+     * on the device: without it, an offline reload has no user, so it shows
+     * the signed-out local database and queues the user's writes as the
+     * signed-out user's. With it, the reload shows the last user's rows, and
+     * writes made meanwhile go into their queue. That queue is not replayed
+     * until the session is confirmed — by a refresh once the connection is
+     * back, or a sign-in. If the server then refuses the session, or someone
+     * else signs in, the device switches users and the queue waits, kept, for
+     * its author.
+     *
+     * The trade-off is the reason it is opt-in: on a shared device, the
+     * previous user's cached rows can be read offline without a session.
+     * Turn it on for installs that belong to one person. The id is forgotten
+     * at sign-out, and when the server refuses the session; it is never used
+     * when the server answered that there is no session.
+     *
+     * {@link OfflineStatus.unverifiedUser} is `true` while the device shows a
+     * user whose session it has not confirmed.
+     */
+    keepLastUser?: boolean;
+    /**
+     * How many queued creates replay as one request. Defaults to `1`: every
+     * queued write is its own request, in order. Raise it (up to 1 000) and a
+     * run of consecutive offline creates in one collection drains as one
+     * `createMany` — 500 rows typed offline go back in a handful of requests
+     * instead of 500 round trips.
+     *
+     * Only creates whose ids the SDK minted as strings are folded, and never
+     * one that references another row of the same run: those are the writes a
+     * lost answer cannot duplicate (the server refuses the id the second time,
+     * and the create is recognised as its own) and whose values need nothing
+     * from the server first. Anything else — and any run the server refuses or
+     * defers for any reason but a lost connection — replays one write at a
+     * time exactly as with the default, so each write still stands or falls
+     * on its own.
+     */
+    replayBatchSize?: number;
 }
+/** What {@link OfflineConfig.onConflict} does with an edit the row has moved past. */
+export type ConflictResolution = "overwrite" | "discard";
 /** A snapshot of the engine's state, for a status indicator. */
 export interface OfflineStatus {
     /** False once a request has failed to reach the server, until one does. */
@@ -94,8 +164,23 @@ export interface OfflineStatus {
     lastSyncedAt?: number;
     /** The last replay rejection, if any. */
     lastError?: string;
+    /**
+     * Whether the browser agreed to keep the offline database through storage
+     * pressure (`navigator.storage.persist()`), asked when the first write is
+     * queued. `false` means it may be evicted — on Safari, after seven days
+     * without a visit — and unsent writes with it; a UI can warn. Unset until
+     * asked, and where there is nothing to ask.
+     */
+    persisted?: boolean;
+    /**
+     * `true` while the local data shown is the last signed-in user's, opened
+     * without a confirmed session ({@link OfflineConfig.keepLastUser}): their
+     * writes queue, and none replays until the session is confirmed. Unset
+     * otherwise.
+     */
+    unverifiedUser?: boolean;
 }
-export type { LiveResult, ObserveOptions, RowSnapshotMeta } from "./collection.js";
+export type { LiveResult, ObserveByIdOptions, ObserveOptions, RowSnapshotMeta } from "./collection.js";
 /** Which queue {@link OfflineApi.pending} and {@link OfflineApi.clear} act on. */
 export interface OfflineQueueOptions {
     /**
@@ -145,15 +230,7 @@ export interface OfflineApi {
     /** Subscribe to queue-size changes (for a "pending changes" badge). */
     onQueueChange(listener: (count: number) => void): () => void;
 }
-/**
- * True when a read failed because there was neither network nor local data.
- *
- * The code is `OFFLINE`. It was `"offline"`, the one lowercase code in a
- * surface whose every other code is `SCREAMING_SNAKE_CASE` — including the
- * `NETWORK_ERROR` it sits next to — so `e.code === "OFFLINE"`, which is what
- * anyone writes, never matched.
- */
-export declare function isOfflineError(error: unknown): boolean;
+export { isOfflineError } from "./offline-errors.js";
 type AnyRow = Record<string, unknown>;
 type InnerFactory = (slug: string) => SDKCollectionClient<AnyRow>;
 export declare class OfflineManager {
@@ -162,10 +239,20 @@ export declare class OfflineManager {
     private readonly maxCachedRows;
     private readonly maxRetries;
     private readonly onSyncError?;
+    private readonly onConflict?;
     private readonly createInner;
     private readonly inners;
     private readonly connectivity;
+    private readonly keepLastUser;
+    private readonly replayBatchSize;
     private scope;
+    /**
+     * The scope is the last signed-in user's, taken without a confirmed
+     * session ({@link resumeLastUser}). Nothing replays while it is set: the
+     * queue is sent under the credentials of whoever is signed in, and nobody
+     * is yet.
+     */
+    private unverified;
     /**
      * Set while the manager does not know whose data it holds: from
      * {@link holdScope} until the next {@link setScope}. `scope` is not
@@ -189,9 +276,21 @@ export declare class OfflineManager {
     /** The local database: normalized rows and query snapshots per collection. */
     private collections;
     /** In-memory mirror of the current scope's queue, in replay order. */
-    private queue;
+    private queueEntries;
+    private get queue();
+    private set queue(value);
     /**
-     * The mutation currently on the wire, if any.
+     * Per collection, the row ids the queue writes to and the ones it creates
+     * — {@link hasPending} and {@link isLocallyCreated}, which answering a
+     * page asks once or twice per row. Each used to scan the whole queue: a
+     * 500-row page against 200 queued writes read 80,000 queue entries, on
+     * every emit. Built on first use after the queue changes; whatever changes
+     * it in place calls {@link queueChangedInPlace}.
+     */
+    private pendingIndex?;
+    /**
+     * The mutations currently on the wire: one, or the members of a folded
+     * run (`replayBatchSize`).
      *
      * `flush` awaits `replay(op)` with `op` still at the head of `queue`, so for
      * the whole duration of that request the in-flight op is also the queue's
@@ -205,10 +304,10 @@ export declare class OfflineManager {
      *   create. It is seeing it right now, so the row would be created and the
      *   delete never queued — an orphan row nothing will ever remove.
      *
-     * Guarding on the id rather than on a boolean keeps this correct if the
-     * flush loop ever sends more than one op at a time.
+     * Guarding on ids rather than on a boolean is what keeps this correct
+     * when a folded run sends several at once, its last member the tail.
      */
-    private inFlightId;
+    private readonly inFlight;
     private queueLoad?;
     /** Serializes enqueues so concurrent writes keep the order the app made them. */
     private enqueueChain;
@@ -219,6 +318,8 @@ export declare class OfflineManager {
     private refreshPending;
     private revCounter;
     private disposed;
+    /** Whether {@link requestPersistence} has asked. */
+    private persistenceRequested;
     private currentStatus;
     private readonly channel?;
     private readonly tabId;
@@ -230,7 +331,27 @@ export declare class OfflineManager {
      * replay under the credentials that made them — so neither may ever leak
      * across a sign-out/sign-in on a shared browser.
      */
-    setScope(uid: string | undefined): void;
+    setScope(uid: string | undefined, options?: {
+        unverified?: boolean;
+    }): void;
+    /** Whether the manager was created with {@link OfflineConfig.keepLastUser}. */
+    get keepsLastUser(): boolean;
+    /**
+     * Take the scope of the last user who signed in on this device, without a
+     * session — for a load whose session restore could not reach the server.
+     * See {@link OfflineConfig.keepLastUser}. With no user remembered (or the
+     * option off) this is the signed-out scope, as it would have been anyway.
+     *
+     * Only while the scope is still held: an auth event that settled it while
+     * the id was being read is newer news.
+     */
+    resumeLastUser(): Promise<void>;
+    /**
+     * Keep the signed-in user's id for {@link resumeLastUser}, or forget it at
+     * sign-out. Forgetting does not depend on the option, so turning it off
+     * does not leave the last id behind for good.
+     */
+    private rememberUser;
     /**
      * Forget whose data this is until the next {@link setScope}.
      *
@@ -273,6 +394,21 @@ export declare class OfflineManager {
     /** Release listeners, timers and the cross-tab channel (client.close()). */
     dispose(): void;
     wrap<M extends AnyRow>(slug: string, inner: CollectionClient<M>): CollectionClient<M>;
+    /**
+     * `client.data.<slug>.trash` on an offline client: every call goes to the
+     * server, and none is cached or queued.
+     *
+     * The local database holds live rows only — a trashed row read into it
+     * would show up in every live query that matches it — so it cannot answer
+     * a trash read, and a restore or a purge queued offline would act on a row
+     * this device has never seen. Each of them rejects with `OFFLINE` instead.
+     *
+     * What the server answers does reach the local database: a restored row
+     * is live again and joins it, and a purged row leaves it. A row with a
+     * write still queued is synced first, so a purge never overtakes the
+     * queued delete it follows; if the queue cannot drain, the call is refused.
+     */
+    private wrapTrash;
     private observe;
     private observeById;
     private observersFor;
@@ -325,6 +461,13 @@ export declare class OfflineManager {
      * the difference. Reading one row first is enough to fix it.
      */
     private mintOfflineId;
+    /**
+     * Keep the version a server row came with, or forget the one held when it
+     * came with none: a row from a list carries no version, and may be newer
+     * than the one held. Only with `onConflict`, the one reader of it.
+     */
+    private noteETag;
+    private etagFor;
     private rawLocalRow;
     private localRow;
     private setLocalRow;
@@ -372,9 +515,35 @@ export declare class OfflineManager {
      */
     private scheduleRefresh;
     private evictRows;
+    /**
+     * Tombstones are tiny but unbounded — every row the app ever asked for and
+     * did not find leaves one. Capped against the row budget, oldest first,
+     * whenever one is added: the cap used to sit behind the row cache's own
+     * early return, so it only applied once the rows were over theirs, and
+     * looking up missing ids grew the set without limit.
+     */
+    private capTombstones;
     private evictSnapshots;
     private ensureQueueLoaded;
     private enqueue;
+    /**
+     * Ask the browser to keep the offline database, once, when there is first
+     * something in it worth keeping. Without it IndexedDB is best-effort
+     * storage, evicted under pressure (and by Safari after seven days without
+     * a visit) with the unsent writes in it.
+     */
+    private requestPersistence;
+    /** The queue's row ids for one collection — see {@link pendingIndex}. */
+    private pendingIds;
+    /**
+     * Did the queued writes to this row bring it into the query's filter? The
+     * row as it was before the first of them is that write's rollback; one
+     * that did not match then is in no server page of the query, so only
+     * this side can put it on screen.
+     */
+    private movedIntoFilter;
+    /** The queue's entries were changed without replacing the array. */
+    private queueChangedInPlace;
     private hasPending;
     /** Is this row one the server has never been told about? */
     private isLocallyCreated;
@@ -385,6 +554,38 @@ export declare class OfflineManager {
         remaining: number;
     }>;
     private flush;
+    /**
+     * The creates at the head of the queue that may replay as one request —
+     * see {@link OfflineConfig.replayBatchSize}. Fewer than two means the head
+     * replays on its own.
+     *
+     * Consecutive, so the queue's order holds; one collection, since a bulk
+     * write is one collection's. Each is a create never sent (so its request
+     * is still its own to choose) with an id the SDK minted as a string — a
+     * lost answer then cannot duplicate it, because the server refuses that
+     * id the second time and the single replay recognises the row as its
+     * own. A create whose values name another member's minted id waits: the
+     * server may give that row a different id, which only a replay one at a
+     * time can carry over.
+     */
+    private foldableRun;
+    /**
+     * Replay a {@link foldableRun} as one `createMany`.
+     *
+     * - `"done"`: every member is acknowledged, adopted and dropped.
+     * - `"offline"`: the connection failed; the members stay queued, as one
+     *   write would.
+     * - `"unbatch"`: anything else — a refusal, a busy server. Nothing was
+     *   written (a bulk write is one transaction), and the caller replays the
+     *   members one at a time, where each refusal, retry budget and recovery
+     *   applies to its own write.
+     *
+     * The key names the run by its first and last member and its length,
+     * which fixes its composition: a run re-sent after a lost answer is the
+     * same request under the same key, and is answered from the server's
+     * record of it.
+     */
+    private replayRun;
     private replay;
     /**
      * Send a queued write under its key.
@@ -428,6 +629,13 @@ export declare class OfflineManager {
      * silently lose writes the server would have accepted.
      */
     private rejectMutation;
+    /**
+     * An edit replayed with `If-Match` and refused with a 412: ask
+     * {@link OfflineConfig.onConflict}, and do what it says. A callback that
+     * throws, or none, is "overwrite" — what replay did before it knew of
+     * conflicts.
+     */
+    private resolveConflict;
     /**
      * 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
@@ -455,6 +663,10 @@ export declare class OfflineManager {
     private rowKey;
     private absentKey;
     private queueKey;
+    /** Queue a write in the store, its rows encoded as the cache's are. */
+    private persistMutation;
+    /** The store's queue under `prefix`, its rows revived. */
+    private readQueue;
     private readCache;
     private writeCache;
     private deleteCache;

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

@@ -23,7 +23,7 @@
  * generated SDK — where `M` is a concrete row type — the documented call was a
  * compile error. Nothing in this repo noticed; a downstream application did.
  */
-import type { FindParams, FindResult, SDKQueryBuilderInterface, WhereFilterOp } from "@rebasepro/types";
+import type { AggregateParams, FindParams, FindResult, LogicalCondition, SDKCollectionClient, SDKQueryBuilderInterface, UpdateValues, WhereFilterOp } from "@rebasepro/types";
 /**
  * A row shaped the way a **generated** SDK shapes one: a type alias with a
  * finite key set.
@@ -46,6 +46,10 @@ type ContractRow = {
     tags: string[];
     age: number;
     deleted_at: string | null;
+    /** A `vector` property. */
+    embedding: number[];
+    /** An `enum` property, which codegen emits as a union of literals. */
+    status: "draft" | "published";
 };
 /** A to-many relation, which codegen emits as `Array<TargetRow>`. */
 type TagRow = {
@@ -118,6 +122,21 @@ export declare const fluentRange: (qb: SDKQueryBuilderInterface<ContractRow>) =>
 export declare const paramsArrayContains: FindParams<ContractRow>;
 /** …and the array-of-tuples form the builder produces from two `.where()` calls. */
 export declare const paramsRange: FindParams<ContractRow>;
+/**
+ * `cond` cannot know the row on its own; the place the group is used can.
+ * `logical` and `.where(group)` check every condition in the tree against `M`,
+ * as the object-form `where` does, so a typo'd column is a compile error, not
+ * the server's 400.
+ */
+export declare const logicalOk: FindParams<ContractRow>;
+export declare const logicalTypo: FindParams<ContractRow>;
+export declare const logicalWrongValue: FindParams<ContractRow>;
+export declare const logicalEnumTypo: FindParams<ContractRow>;
+export declare const logicalArrayContainsList: FindParams<ContractRow>;
+export declare const fluentLogicalTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
+export declare const fluentLogicalOk: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
+/** A group built at runtime keeps working where the row is untyped. */
+export declare const untypedLogical: (qb: SDKQueryBuilderInterface, group: LogicalCondition) => SDKQueryBuilderInterface<Record<string, unknown>, import("@rebasepro/types").IncludeSpec>;
 /**
  * Sorting by relevance and then being unable to read it was the other half of
  * the same bug — the e2e cast around it, which should have been the tell.
@@ -171,4 +190,37 @@ export declare const fluentAggregateSortTypo: (qb: SDKQueryBuilderInterface<Post
 export declare const paramsRelationPath: FindParams<PostRow>;
 export declare const paramsJsonPath: FindParams<ContractRow>;
 export declare const paramsRelationAggregateSort: FindParams<PostRow>;
+/**
+ * `FilterValues` typed the key and left the value `unknown`, so the shape the
+ * fluent form was fixed to refuse compiled in `find({ where })` — the form
+ * `listen`, `observe`, `count` and `iterate` all take.
+ */
+export declare const paramsArrayContainsWholeArray: FindParams<ContractRow>;
+export declare const paramsWrongValueType: FindParams<ContractRow>;
+/** A path that is not a column has nothing to check against, and stays open. */
+export declare const paramsRelationPathTyped: FindParams<ContractRow>;
+/** An untyped row keeps the object form exactly as permissive as it was. */
+export declare const paramsUntyped: FindParams;
+/** `fields` is a projection of columns; a typo was `UNKNOWN_FIELD` at runtime. */
+export declare const fieldsColumn: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
+export declare const fieldsTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
+/** `vectorSearch` names a column. */
+export declare const vectorTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow, import("@rebasepro/types").IncludeSpec>;
+/** `sum` and `avg` add numbers up; `min`/`max` order anything. */
+export declare const aggregateSum: AggregateParams<ContractRow>;
+export declare const aggregateSumText: AggregateParams<ContractRow>;
+/** A field operation fits its column: `$inc` a number, `$push` an array. */
+export declare const updateOps: UpdateValues<Partial<ContractRow>>;
+export declare const updateIncText: UpdateValues<Partial<ContractRow>>;
+/** An untyped row keeps every operation on every key. */
+export declare const updateUntyped: UpdateValues<Partial<Record<string, unknown>>>;
+/**
+ * A typed client is still a client: a helper written against the wide
+ * `SDKCollectionClient` (an export, a paginator, a seeder) takes
+ * `rebase.data.posts`. The column checks above must narrow what a typed
+ * client's methods accept without making the typed client a different kind
+ * of thing — `NumericKeyOf` as a conditional over `keyof M` made tsc measure
+ * `AggregateParams` invariant, and this line stopped compiling.
+ */
+export declare const typedClientWidens: (posts: SDKCollectionClient<ContractRow>) => SDKCollectionClient;
 export {};

package/dist/realtime-channel.d.ts

@@ -103,6 +103,14 @@ export interface ChannelTransport {
      * transport need not implement it.
      */
     onConnectionLost?(handler: (error: RebaseApiError) => void): () => void;
+    /**
+     * Whether the server agreed, for the current socket, to `name` (see the
+     * socket's `hello`). A transport without it is one whose server agreed to
+     * nothing.
+     */
+    hasServerOptIn?(name: string): boolean;
+    /** The current socket's id on the server: the `senderId` of what it broadcasts. */
+    readonly socketClientId?: string;
 }
 export declare class RebaseRealtimeChannel {
     readonly name: string;
@@ -303,6 +311,23 @@ export declare class RebaseRealtimeChannel {
     private stopHeartbeat;
     /** Fold an incoming frame into the roster and fan it out. */
     private handle;
+    /**
+     * Whether a jump in the sequence means a missed message: only when the
+     * server numbers this client's own broadcasts for it (`channel_seq`), so
+     * its own messages leave no hole. Against a server that does not, a hole
+     * is as likely to be the client's own message, and the old behaviour —
+     * deliver, advance — stands.
+     */
+    private watchesForGaps;
+    /**
+     * Hold `event` back and fetch what lies between it and {@link lastSeq},
+     * when it is past a hole. A frame can go missing between instances — a
+     * dropped bus connection, a bus that does not order — and the watermark
+     * would otherwise step over it for good.
+     *
+     * @returns Whether it was held back.
+     */
+    private fillsGap;
     /** Tell the app that retention dropped messages it never received. */
     private reportHistoryGap;
     private emitError;

package/dist/reviver.d.ts

@@ -1 +1,19 @@
 export declare function rebaseReviver(_key: string, value: unknown): unknown;
+/**
+ * `JSON.parse(text, rebaseReviver)`, without the reviver's cost where it has
+ * nothing to do.
+ *
+ * Handing `JSON.parse` a reviver takes V8 off its fast path and calls back for
+ * every key and every value, primitives included: about 7× a plain parse on a
+ * 1,000-row page, 10 ms of main thread per 600 KB. The reviver only ever
+ * changes objects carrying `__type`, and a REST page of flat rows has none. So
+ * this parses plainly and walks the result only when the text can hold one —
+ * and the walk visits objects, never primitives.
+ *
+ * Same result, instance for instance: the same values revived, bottom-up, as
+ * own data properties, and nothing deleted (the reviver never answers
+ * `undefined`).
+ *
+ * @throws SyntaxError exactly where `JSON.parse` does.
+ */
+export declare function parseRebaseJson<T = unknown>(text: string): T;

package/dist/storage-resumable-VO-cMpse.js

@@ -0,0 +1,2 @@
+import { uploadResumable } from "@rebasepro/common";
+export { uploadResumable };

package/dist/storage-resumable.d.ts

@@ -0,0 +1 @@
+export { uploadResumable } from "@rebasepro/common";

package/dist/transport.d.ts

@@ -19,6 +19,11 @@ export interface RebaseClientConfig {
      * service key instead, which resolves to `{ uid: "service", roles: ["admin"] }`
      * and **bypasses RLS**: there is no user to constrain those queries, so scope
      * them explicitly.
+     *
+     * Read each time a request or the realtime socket needs a token, until
+     * `setToken()` or a sign-in replaces it — so it may be declared as a getter.
+     * A token getter installed with `setAuthTokenGetter()` comes first; this is
+     * what is sent when it answers nothing.
      */
     token?: string;
     /**
@@ -156,7 +161,25 @@ export type FindResponse<T> = TypesFindResponse<T extends Record<string, unknown
  * 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;
+/**
+ * `?deleted=` — which soft-deleted rows a read covers: `"only"` the trashed
+ * ones, `"include"` live and trashed together. Absent, the server hides them.
+ *
+ * Not a {@link FindParams} field: `FindParams` is also what `listen()` and the
+ * offline cache take, and neither can answer for a trashed row — a
+ * subscription has no `withDeleted`, and the local database never holds one.
+ * Only the trash accessor (`client.data.<slug>.trash`) passes it.
+ */
+export type SoftDeletedRows = "include" | "only";
+export declare function buildQueryString(params?: FindParams, deleted?: SoftDeletedRows): string;
+/**
+ * The body of `POST /data/<collection>/query`: the parameters
+ * {@link buildQueryString} puts in the URL, spelled as the URL spells them —
+ * each value a string, and a parameter the URL repeats (a filter with two
+ * conditions on one field) a list of them. The server reads it back into the
+ * same parameters and runs the same listing.
+ */
+export declare function buildQueryBody(params?: FindParams, deleted?: SoftDeletedRows): Record<string, string | string[]>;
 /**
  * The query string for `GET /<collection>/aggregate`.
  *
@@ -166,11 +189,12 @@ export declare function buildQueryString(params?: FindParams): string;
  * by exactly the same code a `find()` uses, so "revenue by status, this month"
  * narrows the same rows whichever call is asking.
  *
- * `orderBy`, `include` and the page are deliberately not here: an aggregate has
- * no rows to sort, no relations to load and no page to continue. `limit` is,
- * and bounds the number of *groups*.
+ * `include` and a cursor are deliberately not here: an aggregate has no
+ * relations to load and no row to continue after. `limit`, `offset` and
+ * `orderBy` are, and page and sort the *groups* — `orderBy` by a group column or
+ * an aggregate's alias, in the spelling a `find()` sends.
  */
-export declare function buildAggregateQueryString(params: AggregateParams): string;
+export declare function buildAggregateQueryString<M extends Record<string, unknown>>(params: AggregateParams<M>): string;
 /**
  * Response metadata a caller can ask for, filled in by `request`.
  *
@@ -191,12 +215,40 @@ export interface ResponseMeta {
     etag?: string;
     /** The HTTP status, for a caller that has to tell 200 from 204. */
     status?: number;
+    /**
+     * The response's headers, for a protocol that answers in them — a
+     * resumable upload's `Location` and `Upload-Offset`.
+     */
+    headers?: {
+        get(name: string): string | null;
+    };
 }
+/** See {@link Transport.setTokenRefresher}. */
+export type TokenRefresher = () => Promise<string | undefined> | undefined;
 export interface Transport {
     request: <T = unknown>(path: string, init?: RequestInit, meta?: ResponseMeta) => Promise<T>;
+    /**
+     * Like `request`, but the body of a success is left unread: the response
+     * comes back as it arrived, for a caller that wants text, a Blob or a
+     * stream. Auth, the refresh-and-resend and the error envelope are the same.
+     * Optional so a hand-written transport need not have it.
+     */
+    requestRaw?: (path: string, init?: RequestInit, meta?: ResponseMeta) => Promise<Response>;
     setToken: (newToken: string | null) => void;
     setAuthTokenGetter: (getter: () => Promise<string | null>) => void;
     setOnUnauthorized: (handler: () => Promise<boolean>) => void;
+    /**
+     * Install the hook asked, before each request that carries this
+     * transport's own token, whether that token is known to be spent. It
+     * answers `undefined` to send the token as held, or a promise for the one
+     * to send instead — the auth module's refresh, so a request made while a
+     * session is being restored, or after its token expired unnoticed, goes
+     * out once with a good token rather than with none or a dead one.
+     *
+     * Not consulted when an auth token getter is installed: the getter owns
+     * the token then. Optional so a hand-written transport need not have it.
+     */
+    setTokenRefresher?: (refresher: TokenRefresher | null) => void;
     readonly baseUrl: string;
     readonly apiPath: string;
     /** See {@link RebaseClientConfig.storageUrlOrigin}. Undefined = use `baseUrl`. */
@@ -205,4 +257,32 @@ export interface Transport {
     getHeaders: (init?: RequestInit) => Record<string, string>;
     resolveToken: () => Promise<string | null>;
 }
+/**
+ * The base every request and every caller-built URL resolves against.
+ *
+ * `baseUrl` is optional because the common production shape is a Rebase
+ * backend serving its own SPA, where the API is simply the page's origin.
+ * Leaving it unset is therefore the *correct* configuration there — and the
+ * one that keeps working when a second hostname (a custom domain) points at
+ * the same app.
+ *
+ * When unset in a browser this resolves to the page origin rather than "".
+ * Requests behave identically either way, but the empty string is a trap for
+ * anything that builds a URL from `client.baseUrl`: `new URL("" + path)`
+ * throws, so apps "fixed" it by baking an absolute host into their bundle —
+ * which is exactly what breaks the day a custom domain is added, and which no
+ * amount of CORS configuration repairs, because a SameSite=Lax auth cookie is
+ * not sent cross-site either.
+ */
+/**
+ * The code an error carries when the response did not name one: a proxy's 413,
+ * a load balancer's 502, a crash page's 500 — anything without the server's
+ * envelope. Without it `e.code` was `undefined` and the documented
+ * `switch (e.code)` fell through to `default` on exactly the failures that are
+ * not Rebase's own. Only codes the backend itself answers with, so a switch
+ * written against the error reference catches both.
+ *
+ * @internal
+ */
+export declare function defaultCodeForStatus(status: number): string | undefined;
 export declare function createTransport(config: RebaseClientConfig, environment?: TransportEnvironment): Transport;