@rebasepro/client 0.24.0 → 0.24.1-canary.gcb918fc

package/README.md

@@ -34,22 +34,37 @@ of it resolves too: Node has supported `require(esm)` since 22.12.
 |---|---|
 | `createRebaseClient<DB>(options)` | Create a client instance. Generic `DB` parameter enables type-safe `client.data.*` access. |
 | `CreateRebaseClientResult<DB>` | The client type it returns (`RebaseClient<DB>` from `@rebasepro/types`, narrowed) — includes `auth`, `admin`, `cron`, `functions`, `storage`, `ws`, `data`, `call`, and token management methods. |
-| `CreateRebaseClientOptions` | Extends `RebaseClientConfig` with `auth`, `admin`, and `cron` sub-configs. |
+| `CreateRebaseClientOptions` | Extends `RebaseClientConfig` with the `auth`, `admin`, `cron`, `apiKeys` and `personalKeys` sub-configs, plus `storageSources`, `collections` and `offline`. |
 
 ### Config
 
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `baseUrl` | `string` | `""` | Backend URL (e.g. `http://localhost:3001`) |
-| `token` | `string` | — | Static auth token |
+| `token` | `string` | — | Auth token, read each time one is needed (so it may be declared as a getter) until `setToken()` or a sign-in replaces it |
 | `apiPath` | `string` | `"/api"` | API path prefix |
 | `fetch` | `typeof fetch` | `globalThis.fetch` | Custom fetch implementation |
-| `onUnauthorized` | `() => Promise<boolean>` | auto-refresh | Handler for 401 responses |
+| `onUnauthorized` | `() => Promise<boolean>` | auto-refresh | Handler for a refused token, over HTTP (401) and on the realtime socket |
 | `websocketUrl` | `string` | derived from `baseUrl` | WebSocket URL for realtime |
 | `realtime` | `boolean` | `true` | Open the WebSocket — `false` lets a one-shot script exit |
 | `collections` | `Record<string, string>` | — | Maps accessor names to collection slugs |
 | `offline` | `boolean \| OfflineConfig` | `false` | Local-first sync — see [the docs](https://rebase.pro/docs/sdk/offline) |
 
+### Tokens
+
+| Method | Description |
+|---|---|
+| `setAuthTokenGetter(getter)` | Ask `getter` for the token each time one is needed: every HTTP request and every time the realtime socket authenticates. This is how a host signing users in with its own provider (Clerk, Firebase Auth, its own session) authenticates the client. It comes before the client's own session and the `token` option |
+| `setToken(token)` | Send this token from now on, over HTTP and on the socket |
+| `setOnUnauthorized(handler)` | Answer a refused token, on HTTP and the socket; resolve `true` to retry |
+| `resolveToken()` | The token the next request would carry |
+
+Installing a getter or calling `setToken()` rebuilds an open socket so it authenticates as the new credential. `client.ws.setAuthTokenGetter()` is deprecated: it still works, warns once, and reaches only the socket.
+
+```ts
+client.setAuthTokenGetter(() => clerk.session?.getToken() ?? Promise.resolve(null));
+```
+
 ### Collection Client
 
 `client.data.collection("slug")` or `client.data.myCollection` returns a `CollectionClient<M>`:
@@ -62,11 +77,11 @@ of it resolves too: Node has supported `require(esm)` since 22.12.
 | `update(id, data)` | Update a row. Returns `M` |
 | `delete(id)` | Delete a row |
 | `count(params?)` | Count matching rows |
-| `where(col, op, val)` | Start a fluent query — returns `QueryBuilder` |
-| `orderBy(col, dir?)` | Order results — returns `QueryBuilder` |
-| `limit(n)` / `offset(n)` | Pagination — returns `QueryBuilder` |
-| `search(str)` | Full-text search — returns `QueryBuilder` |
-| `include(...rels)` | Include related rows — returns `QueryBuilder` |
+| `where(col, op, val)` | Start a fluent query — returns a query builder |
+| `orderBy(col, dir?)` | Order results — returns a query builder |
+| `limit(n)` / `offset(n)` | Pagination — returns a query builder |
+| `search(str)` | Text search: a case-insensitive substring match by default, ranked full-text where the collection opts in — returns a query builder |
+| `include(...rels)` | Include related rows — returns a query builder |
 | `listen(params, onUpdate, onError?)` | Realtime subscription (requires WebSocket) |
 | `listenById(id, onUpdate, onError?)` | Realtime single-row subscription |
 | `observe(params, onResult, onError?, options?)` | Live query — local-first when `offline` is on, otherwise fetch + `listen` |
@@ -107,7 +122,7 @@ of it resolves too: Node has supported `require(esm)` since 22.12.
 
 | Method | Description |
 |---|---|
-| `listUsers()` / `listUsersPaginated(options?)` | List all users |
+| `listUsers(options?)` / `listUsersPaginated(options?)` | One page of users (25 by default; `limit`, `offset`, `search`, `orderBy`, `orderDir`) with `total` |
 | `getUser(userId)` | Get a single user |
 | `createUser(data)` | Create a user |
 | `updateUser(userId, data)` | Update a user |
@@ -130,7 +145,7 @@ of it resolves too: Node has supported `require(esm)` since 22.12.
 | `MemoryOfflineStore` | Reference `OfflineStore`; the IndexedDB one is wired automatically |
 | `createCookieStorage(options?)` | Cookie-based auth storage adapter |
 | `createMemoryStorage()` | In-memory auth storage adapter |
-| `QueryBuilder` | Fluent query builder (also re-exported from `@rebasepro/common`) |
+| `or`, `and`, `not`, `cond` | Logical-condition helpers for `.where(…)` |
 | `FindResult`, `FindParams`, `User`, … | Re-exported from `@rebasepro/types` |
 
 ## Quick Start

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

@@ -0,0 +1,21 @@
+/**
+ * Compile-time assertions about the admin client's answers.
+ *
+ * A plain module under `src`, imported by nothing, for the reason
+ * `query-contract.types.ts` gives: a type assertion in a jest test is checked
+ * by nothing here, and `pnpm typecheck` reads `src`.
+ */
+import type { createAdmin } from "./admin.js";
+type Admin = ReturnType<typeof createAdmin>;
+/**
+ * `POST /admin/users` answers `{ user, invitationSent, temporaryPassword?,
+ * emailDeliveryFailed? }`, and the temporary password is returned exactly
+ * once. Typed `{ user }`, it was a compile error to read — while the sibling
+ * `resetPassword` typed the same three fields.
+ */
+export declare const createUserDelivery: (admin: Admin) => Promise<{
+    temporaryPassword: string | undefined;
+    invitationSent: boolean | undefined;
+    emailDeliveryFailed: boolean | undefined;
+}>;
+export {};

package/dist/admin.d.ts

@@ -33,8 +33,12 @@ export declare function createAdmin(transport: Transport, options?: CreateAdminO
         displayName?: string;
         password?: string;
         roles?: string[];
+        skipPasswordPolicy?: boolean;
     }) => Promise<{
         user: AdminUser;
+        temporaryPassword?: string;
+        invitationSent?: boolean;
+        emailDeliveryFailed?: boolean;
     }>;
     updateUser: (userId: string, data: {
         email?: string;

package/dist/auth.d.ts

@@ -197,10 +197,6 @@ export declare function createAuth(transport: Transport, options?: CreateAuthOpt
             verified: boolean;
             createdAt: string;
         }[]>;
-        /**
-         * Remove a factor. Requires an `aal2` session — one that has already
-         * answered a challenge — so a stolen `aal1` token cannot turn MFA off.
-         */
         /**
          * Replace the account's recovery codes with ten new ones, shown once.
          * Needs an `aal2` session. Adding a second factor keeps the codes the
@@ -209,6 +205,12 @@ export declare function createAuth(transport: Transport, options?: CreateAuthOpt
         regenerateRecoveryCodes(): Promise<{
             recoveryCodes: string[];
         }>;
+        /**
+         * Remove a factor. Once the account has a verified factor this
+         * requires an `aal2` session — one that has already answered a
+         * challenge — so a stolen `aal1` token cannot turn MFA off. An
+         * unfinished first enrolment can be removed from any session.
+         */
         unenroll(factorId: string): Promise<{
             success: boolean;
             message: string;
@@ -325,7 +327,27 @@ export declare function createAuth(transport: Transport, options?: CreateAuthOpt
     onAuthStateChange: (callback: (event: AuthChangeEvent, session: RebaseSession | null) => void) => () => boolean;
     canRestoreSession: () => boolean;
     isInitialized: () => Promise<void>;
+    /**
+     * How restoring the session on load ended — see
+     * {@link SessionRestoreOutcome}. `"unreachable"` with no session is
+     * the one case where "signed out" is not known to be true: the
+     * device could not ask.
+     */
+    restoreOutcome: () => SessionRestoreOutcome;
 };
+/**
+ * How restoring the session on load ended — `auth.restoreOutcome()`.
+ *
+ * - `"pending"`: still restoring (`isInitialized()` has not settled).
+ * - `"restored"`: a session was restored, from storage or from the server.
+ * - `"none"`: there was nothing to restore.
+ * - `"refused"`: there was a session to restore, and the server refused it.
+ * - `"unreachable"`: the server could not be reached (or answered 5xx), so the
+ *   session was neither confirmed nor refused. With a stored session the
+ *   client keeps it and retries; in cookie mode, where nothing is stored on the
+ *   device, it has no session until a later refresh or sign-in succeeds.
+ */
+export type SessionRestoreOutcome = "pending" | "restored" | "none" | "refused" | "unreachable";
 export interface CookieStorageOptions {
     path?: string;
     domain?: string;

package/dist/backups.d.ts

@@ -1,9 +1,20 @@
 import { Transport } from "./transport.js";
-import { type BackupListing } from "@rebasepro/types";
+import { type BackupDownloadLink, type BackupListing } from "@rebasepro/types";
 export interface CreateBackupsOptions {
     backupsPath?: string;
 }
+/** One backup's bytes, as {@link createBackups}' `stream()` answers them. */
+export interface BackupStream {
+    /** The dump, read from the server as it is consumed. */
+    stream: ReadableStream<Uint8Array>;
+    /** Its size in bytes, when the server said. */
+    size?: number;
+    /** Its file name: the key's last segment, as the server names the download. */
+    name: string;
+}
 export declare function createBackups(transport: Transport, options?: CreateBackupsOptions): {
     list: () => Promise<BackupListing>;
-    download: (key: string) => Promise<Blob>;
+    download: (key: string) => Promise<void>;
+    downloadUrl: (key: string) => Promise<BackupDownloadLink>;
+    stream: (key: string) => Promise<BackupStream>;
 };

package/dist/collection.d.ts

@@ -1,22 +1,14 @@
 import { FindParams, Transport } from "./transport.js";
 import { RebaseWebSocketClient } from "./websocket.js";
-import { FindResult, SDKCollectionClient, type IncludeSpec } from "@rebasepro/types";
+import { FindResult, SDKCollectionClient, type ByIdReadOptions, type IncludeSpec, type RestoreOptions, type TrashClient, RebaseClientError } from "@rebasepro/types";
+import { etagOf } from "@rebasepro/common";
 /**
- * The version of a row, when it came straight from a read that reported one.
- *
- * ```ts
- * const post = await client.data.posts.get(1);
- * await client.data.posts.update(1, { title: "New" }, { ifMatch: etagOf(post) });
- * ```
- *
- * `undefined` for a row from `find()` (a list response carries one ETag at
- * most, and it would not be this row's), from the offline cache, or from a
- * server that does not send them. Passing `undefined` as `ifMatch` sends no
- * precondition, so the call above degrades to an ordinary update rather than
- * failing — which is the right default, and the reason to read this at the call
- * site where the choice is visible.
+ * A bulk call given something other than an array. A `RebaseClientError` with
+ * the code the server uses for the same mistake in a request body, so one
+ * `case "INVALID_BULK_BODY"` covers both.
  */
-export declare function etagOf(row: unknown): string | undefined;
+export declare function invalidBulkBody(message: string): RebaseClientError;
+export { etagOf };
 /**
  * A live query result: a normal {@link FindResult} plus what an interface
  * needs to decide whether to show a "saving…" or "offline" affordance over it.
@@ -51,6 +43,25 @@ export interface ObserveOptions {
      */
     realtime?: boolean;
 }
+/**
+ * Options for `observeById`: {@link ObserveOptions}, plus the relations to load
+ * into the row. `include` reaches both of its reads — the one-shot
+ * `findById` and the `listenById` subscription — so every emission carries
+ * the same relations.
+ */
+export interface ObserveByIdOptions<Inc = IncludeSpec> extends ObserveOptions, ByIdReadOptions<Inc> {
+}
+/**
+ * {@link TrashClient} and {@link RestoreOptions} are the transport-agnostic
+ * contract in `@rebasepro/types`. On this client every call goes to the
+ * server. With `offline` enabled the trash is not cached and nothing in it is
+ * queued: the local database never holds a trashed row, so it cannot answer
+ * for one, and a restore or a purge made offline would act on a row this
+ * device cannot see. They reject with `OFFLINE` instead (see
+ * `isOfflineError`). A restored row joins the local database; a purged one
+ * leaves it.
+ */
+export type { RestoreOptions, TrashClient };
 /**
  * The concrete, HTTP-backed implementation of the public
  * {@link SDKCollectionClient} contract — flat rows (no Entity wrapper), plus
@@ -63,6 +74,11 @@ export interface ObserveOptions {
  */
 export interface CollectionClient<M extends Record<string, unknown> = Record<string, unknown>, I = Partial<M>, U = Partial<M>, Inc = IncludeSpec> extends SDKCollectionClient<M, I, U, Inc> {
     count(params?: FindParams<M, Inc>): Promise<number>;
+    /**
+     * The collection's trash: list, count, restore and purge the rows a soft
+     * delete stamped. See {@link TrashClient}.
+     */
+    trash: TrashClient<M, Inc>;
     /**
      * Subscribe to a query's results.
      *
@@ -80,6 +96,11 @@ export interface CollectionClient<M extends Record<string, unknown> = Record<str
      */
     observe(params: FindParams<M, Inc> | undefined, onResult: (result: LiveResult<M>) => void, onError?: (error: Error) => void, options?: ObserveOptions): () => void;
     /** {@link CollectionClient.observe} for a single row. */
-    observeById(id: string | number, onResult: (row: M | undefined, meta: RowSnapshotMeta) => void, onError?: (error: Error) => void, options?: ObserveOptions): () => void;
+    observeById(id: string | number, onResult: (row: M | undefined, meta: RowSnapshotMeta) => void, onError?: (error: Error) => void, options?: ObserveByIdOptions<Inc>): () => void;
 }
+/**
+ * The part of {@link ObserveByIdOptions} that is a read option: `include`, and
+ * nothing else, so `realtime` never travels as a query parameter.
+ */
+export declare function byIdRead<Inc>(options: ObserveByIdOptions<Inc> | undefined): ByIdReadOptions<Inc> | undefined;
 export declare function createCollectionClient<M extends Record<string, unknown> = Record<string, unknown>>(transport: Transport, slug: string, ws?: RebaseWebSocketClient): CollectionClient<M>;

package/dist/cron.d.ts

@@ -1,5 +1,5 @@
 import { Transport } from "./transport.js";
-import type { CronJobStatus, CronJobLogEntry, CronJobListing } from "@rebasepro/types";
+import type { CronJobStatus, CronJobLogEntry, CronJobListing, CronJobStarted } from "@rebasepro/types";
 export interface CreateCronOptions {
     cronPath?: string;
 }
@@ -8,10 +8,17 @@ export declare function createCron(transport: Transport, options?: CreateCronOpt
     getJob: (jobId: string) => Promise<{
         job: CronJobStatus;
     }>;
-    triggerJob: (jobId: string) => Promise<{
-        log: CronJobLogEntry;
-        job: CronJobStatus;
-    }>;
+    triggerJob: {
+        (jobId: string, options?: {
+            async?: false;
+        }): Promise<{
+            log: CronJobLogEntry;
+            job: CronJobStatus;
+        }>;
+        (jobId: string, options: {
+            async: true;
+        }): Promise<CronJobStarted>;
+    };
     getJobLogs: (jobId: string, options?: {
         limit?: number;
     }) => Promise<{

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

@@ -0,0 +1,39 @@
+/**
+ * Compile-time assertion that a consumer can name, from `@rebasepro/client`
+ * alone, the types its own calls are written in.
+ *
+ * A plain module under `src`, imported by nothing, for the reason
+ * `query-contract.types.ts` gives: `pnpm typecheck` reads `src`, and a type
+ * assertion in a jest test is checked by nothing. A browser app installs this
+ * package only, so an argument type missing from the barrel is one it has to
+ * spell out by hand or reach into a package it never installed.
+ */
+import type { AggregateMeta, AggregateParams, AggregateResult, AggregateRow, AggregateSelect, FieldPath, FilterCondition, FilterConditionFor, FilterValues, IncludeOptions, IncludeSpec, InsertOf, LogicalCondition, LogicalConditionFor, OrderBySpec, QueryComputedFields, RestoreOptions, RowOf, StorageSource, TrashClient, UpdateOf, WhereConditionFor, WhereFilterOp, WhereFor, WhereValueFor, WriteOptions } from "./index.js";
+export type ConsumerCanName = [
+    AggregateMeta,
+    AggregateParams,
+    AggregateResult,
+    AggregateRow,
+    AggregateSelect,
+    FieldPath,
+    FilterCondition,
+    FilterValues<string>,
+    IncludeOptions,
+    IncludeSpec,
+    InsertOf<Record<string, unknown>>,
+    LogicalCondition,
+    OrderBySpec,
+    FilterConditionFor<Record<string, unknown>>,
+    LogicalConditionFor<Record<string, unknown>>,
+    QueryComputedFields,
+    RowOf<Record<string, unknown>>,
+    StorageSource,
+    UpdateOf<Record<string, unknown>>,
+    WhereConditionFor<string>,
+    WhereFilterOp,
+    WhereFor<Record<string, unknown>>,
+    WhereValueFor<"==", string>,
+    WriteOptions,
+    RestoreOptions,
+    TrashClient
+];

package/dist/functions.d.ts

@@ -28,21 +28,11 @@ export interface FunctionsClient {
      *                  One path segment: a sub-path goes in `options.path`.
      * @param payload - Optional JSON-serialisable body. Dropped for `GET`.
      * @param options - Optional overrides (HTTP method, sub-path, extra headers).
-     * @returns The parsed JSON response from the function.
+     * @returns The parsed JSON response from the function, or — with
+     *          `options.responseType` — its text, a `Blob`, or the raw `Response`.
      */
     invoke<T = unknown>(name: string, payload?: unknown, options?: FunctionInvokeOptions): Promise<T>;
 }
 export type { FunctionInvokeOptions } from "@rebasepro/types";
 import type { FunctionInvokeOptions } from "@rebasepro/types";
-/**
- * Create a `FunctionsClient` backed by the given transport.
- *
- * The transport already handles:
- * - Base URL resolution
- * - JWT injection via `Authorization: Bearer`
- * - 401 retry / `onUnauthorized` flow
- * - Consistent error throwing via `RebaseApiError`
- *
- * @internal
- */
 export declare function createFunctionsClient(transport: Transport): FunctionsClient;

package/dist/index.d.ts

@@ -8,38 +8,38 @@ import { CollectionClient } from "./collection.js";
 import { createFunctionsClient } from "./functions.js";
 import { RebaseWebSocketClient } from "./websocket.js";
 import { RebaseRealtimeChannel, type ChannelOptions } from "./realtime-channel.js";
-import { type OfflineApi, type OfflineConfig } from "./offline.js";
+import type { OfflineApi, OfflineConfig } from "./offline.js";
 import { type BatchOperation, type BatchResult, type IncludeOf, InsertOf, RebaseClient, RebaseSdkData, RowOf, StorageSource, StorageSourceDefinition, StorageSourceRegistry, UpdateOf, type WriteOptions } from "@rebasepro/types";
 export { RebaseApiError } from "./transport.js";
 export { RebaseClientError } from "./errors.js";
 export type { RebaseErrorCode } from "@rebasepro/types";
 export type { RebaseClientConfig, FindParams, FindResponse } from "./transport.js";
-export type { CollectionClient } from "./collection.js";
+export type { CollectionClient, RestoreOptions, TrashClient } from "./collection.js";
 export type { FindResult, SDKCollectionClient, SDKQueryBuilderInterface, PaginationMeta } from "@rebasepro/types";
 export type { IterateParams, FindAllParams, PageWalkOptions, CursorSpec } from "@rebasepro/types";
 export { RebasePaginationError } from "@rebasepro/common";
 export type { PaginationErrorCode } from "@rebasepro/common";
-export { QueryBuilder, or, and, not, cond } from "@rebasepro/common";
-export { resolveStorageReferences, storageReference, parseStorageReference, isStorageReference, STORAGE_REFERENCE_SCHEME } from "@rebasepro/types";
+export { or, and, not, cond } from "@rebasepro/common";
+export { resolveStorageReferences, storageReference, parseStorageReference, isStorageReference, STORAGE_REFERENCE_SCHEME, storageTargetOfDownloadUrl, storageReferencesForDownloadUrls, storageTargetsInText } from "@rebasepro/types";
 export type { StorageReferenceTarget, StorageReferenceResolver } from "@rebasepro/types";
 export { createCookieStorage, createMemoryStorage } from "./auth.js";
-export type { AuthConfig, AuthStorage, CookieStorageOptions, CreateAuthOptions } from "./auth.js";
+export type { AuthConfig, AuthStorage, CookieStorageOptions, CreateAuthOptions, SessionRestoreOutcome } from "./auth.js";
 export type { User, RebaseSession, AuthTokens, AuthChangeEvent, DeviceSession } from "@rebasepro/types";
 export type { CreateAdminOptions, ListUsersOptions } from "./admin.js";
 export type { AdminUser } from "./admin.js";
 export type { CreateCronOptions } from "./cron.js";
-export { createBackups } from "./backups.js";
-export type { CreateBackupsOptions } from "./backups.js";
+export type { BackupStream } from "./backups.js";
 export type { ApiKeyKind, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, CreateApiKeysOptions, CreatePersonalKeyRequest, CreatePersonalKeysOptions, UpdateApiKeyRequest } from "./api-keys.js";
 export type { FunctionInvokeOptions, FunctionsClient } from "./functions.js";
 export { RebaseWebSocketClient } from "./websocket.js";
 export { RebaseRealtimeChannel } from "./realtime-channel.js";
 export type { PresenceState, PresenceDiff, BroadcastEvent, ChannelTransport, ChannelOptions, ChannelHistoryEntry, ChannelHistoryResult } from "./realtime-channel.js";
-export type { OfflineApi, OfflineConfig, OfflineQueueOptions, OfflineStatus } from "./offline.js";
-export { isOfflineError } from "./offline.js";
-export type { LiveResult, ObserveOptions, RowSnapshotMeta } from "./collection.js";
+export type { ConflictResolution, OfflineApi, OfflineConfig, OfflineQueueOptions, OfflineStatus } from "./offline.js";
+export { isOfflineError } from "./offline-errors.js";
+export type { LiveResult, ObserveByIdOptions, ObserveOptions, RowSnapshotMeta } from "./collection.js";
 export { etagOf } from "./collection.js";
 export type { BatchOperation, BatchRef, BatchResult, FieldOperation, UpdateValues, UpsertOptions } from "@rebasepro/types";
+export type { WriteOptions, WhereFilterOp, WhereFor, WhereConditionFor, WhereValueFor, FilterValues, FieldPath, OrderBySpec, LogicalCondition, LogicalConditionFor, FilterCondition, FilterConditionFor, AggregateParams, AggregateSelect, AggregateRow, AggregateResult, AggregateMeta, IncludeSpec, IncludeOptions, QueryComputedFields, RowOf, InsertOf, UpdateOf, StorageSource } from "@rebasepro/types";
 export type { OfflineStore, OfflineCacheEntry, OfflineCacheRecord, PendingMutation, MutationRollback } from "./offline-store.js";
 export { MemoryOfflineStore } from "./offline-store.js";
 export interface CreateRebaseClientOptions extends RebaseClientConfig {
@@ -102,9 +102,35 @@ type TypedDataLayer<DB> = {
  * typed collection accessors when a `DB` schema generic is supplied.
  */
 export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<RebaseClient<DB>, "data" | "email"> & {
+    /**
+     * Send this token from now on, over HTTP and on the realtime socket. An
+     * open socket is rebuilt to authenticate with it. A token getter, when one
+     * is installed, still comes first.
+     */
     setToken: (token: string | null) => void;
+    /**
+     * Ask `getter` for the token each time one is needed — every HTTP request
+     * and every time the realtime socket authenticates. This is how a host
+     * that signs users in with its own provider (Clerk, Firebase Auth, a
+     * session of its own) authenticates the client:
+     *
+     * ```ts
+     * client.setAuthTokenGetter(() => clerk.session?.getToken() ?? Promise.resolve(null));
+     * ```
+     *
+     * It comes before the client's own session and the `token` option, which
+     * are used when it answers `null` or throws. An open socket is rebuilt to
+     * authenticate through it.
+     */
     setAuthTokenGetter: (getter: () => Promise<string | null>) => void;
+    /**
+     * Answer a refused credential — a 401 over HTTP, an auth error on the
+     * socket — with `handler`; resolve `true` to have the request or
+     * subscription retried with the token resolved again. Replaces the
+     * client's own session refresh.
+     */
     setOnUnauthorized: (handler: () => Promise<boolean>) => void;
+    /** The token the next request would carry, resolved as it would be. */
     resolveToken: () => Promise<string | null>;
     auth: ReturnType<typeof createAuth>;
     admin: ReturnType<typeof createAdmin>;