@rebasepro/types 0.24.0 → 0.24.1-canary.g56af4a4

package/dist/types/auth_adapter.d.ts

@@ -303,6 +303,23 @@ export interface UserCreationPrepareResult {
     /** Whether an invitation was sent (only relevant when hookHandledEmail is true). */
     invitationSent: boolean;
 }
+/**
+ * What the door creating a user knows about its caller, for
+ * `AuthAdapter.prepareUserCreation()`.
+ *
+ * @group Auth
+ */
+export interface UserCreationOptions {
+    /**
+     * Whether the caller may waive the password policy with
+     * `skipPasswordPolicy: true` in the body. The doors set it for an
+     * administrator (the service key signs in as one) and for nobody else, so
+     * an adapter that reads the flag is taking an administrator at their word —
+     * an import of accounts whose passwords were set under another system's
+     * rules. Absent, the flag waives nothing.
+     */
+    mayWaivePasswordPolicy?: boolean;
+}
 /**
  * What a create body for an auth collection may name beyond the collection's
  * own declared fields — see `AuthAdapter.describeUserCreationContract()`.
@@ -322,6 +339,16 @@ export interface UserCreationWriteContract {
      * deletes it before the row is ever built.
      */
     extraFields: string[];
+    /**
+     * Each body's `prepareUserCreation` touches nothing but its own result —
+     * no hook, no email, no write — so a bulk create may prepare several at
+     * once. The built-in adapter's path with no `onCreateUser`, no
+     * `onAdminCreateUser` and the default `hashPassword` is: it hashes a
+     * password and normalizes an email, and a 1,000-row bulk spent half a
+     * minute hashing one password at a time. Leave it unset when a hook runs:
+     * preparations then run one at a time, in the order the rows were given.
+     */
+    independent?: boolean;
 }
 /**
  * Result of `AuthAdapter.finalizeUserCreation()`.
@@ -505,11 +532,15 @@ export interface AuthAdapter {
      *
      * If not implemented, the collection saves values as-is (no password hashing).
      *
+     * A chosen `password` is held to the password policy unless the body says
+     * `skipPasswordPolicy: true` and `options.mayWaivePasswordPolicy` is set.
+     *
      * @param values - Raw request body from the client.
      * @param collectionAuth - The parsed `AuthCollectionConfig` from the collection (if `auth` is an object).
+     * @param options - What the door knows about its caller.
      * @returns Processed values ready for `driver.save()`, plus metadata for the post-save step.
      */
-    prepareUserCreation?(values: Record<string, unknown>, collectionAuth?: unknown): Promise<UserCreationPrepareResult>;
+    prepareUserCreation?(values: Record<string, unknown>, collectionAuth?: unknown, options?: UserCreationOptions): Promise<UserCreationPrepareResult>;
     /**
      * Describe what a create body for this auth collection is allowed to name,
      * so unknown-field validation can run on it.

package/dist/types/backend.d.ts

@@ -252,6 +252,36 @@ export interface RealtimeChannelsConfig {
      * Defaults to 1000. `REALTIME_MAX_SUBSCRIPTIONS_PER_SOCKET` wins over it.
      */
     maxSubscriptionsPerSocket?: number;
+    /**
+     * How many sockets one user (one identity: a signed-in user, an API key's
+     * user, an impersonated user) may hold open on one server instance. The
+     * next one's `AUTHENTICATE` is refused with `TOO_MANY_SOCKETS` and the
+     * socket closed with 4002; the SDK keeps retrying with backoff, so it gets
+     * in once another closes. A positive whole number, checked at boot.
+     * Unset (the default) is no ceiling. `REALTIME_MAX_SOCKETS_PER_USER` wins
+     * over it.
+     */
+    maxSocketsPerUser?: number;
+    /**
+     * The longest a change waits for the refetch that delivers it, in ms. A
+     * refetch waits for 300 ms without a change, and at most this long under a
+     * steady stream of writes. Defaults to 1000. A positive whole number,
+     * checked at boot. `REALTIME_REFETCH_MAX_WAIT_MS` wins over it.
+     */
+    refetchMaxWaitMs?: number;
+    /**
+     * How long a big list subscription's total may be reused before it is
+     * counted again, in ms. Unset (the default), every frame counts. Frames
+     * that reuse it carry `meta.totalAsOf`. `REALTIME_RECOUNT_INTERVAL_MS`
+     * wins over it.
+     */
+    recountIntervalMs?: number;
+    /**
+     * The smallest last total at which {@link recountIntervalMs} applies;
+     * smaller lists are counted on every frame. Defaults to 100 000.
+     * `REALTIME_RECOUNT_MIN_ROWS` wins over it.
+     */
+    recountMinRows?: number;
 }
 /**
  * Abstract realtime provider interface.
@@ -445,8 +475,19 @@ export interface SqlScriptResult {
     tables: SqlScriptTable[];
     /** The last statement's command: `SELECT`, `UPDATE`, `CREATE TABLE` … */
     command?: string;
-    /** How many rows the last statement returned or changed, when its command reports a count. */
+    /**
+     * How many rows the last statement returned or changed, when its command
+     * reports a count — or, for a {@link truncated} result, how many it
+     * returned, of which {@link rows} holds the first.
+     */
     rowCount?: number;
+    /**
+     * The last statement returned more than a run keeps, and {@link rows}
+     * holds only its first rows. The Studio console's door keeps at most
+     * 10,000 rows, or 32 Mi characters of values, of one result: a run that
+     * held every row of a million-row table took the server down with it.
+     */
+    truncated?: boolean;
     /** What the database said while the script ran, in order. */
     notices: SqlScriptNotice[];
     /**
@@ -457,6 +498,22 @@ export interface SqlScriptResult {
      */
     effectiveRole?: string;
 }
+/**
+ * A query's result being read a batch at a time — see `SQLAdmin.openSqlCursor`.
+ *
+ * @group Admin
+ */
+export interface SqlCursor {
+    /** The result's column names, in order. */
+    readonly columns: string[];
+    /**
+     * The next rows, each value the text the database wrote for it and `null`
+     * for NULL — `null` once there are none left.
+     */
+    read(): Promise<(string | null)[][] | null>;
+    /** End the read and give the session back. Safe to call more than once. */
+    close(): Promise<void>;
+}
 /**
  * Administrative operations for SQL-based databases (PostgreSQL, MySQL, etc.).
  * Used by the SQL Editor, RLS Editor, and schema browser.
@@ -472,12 +529,19 @@ export interface SQLAdmin {
      * before it is reused. For SQL a person wrote (the Studio editor), which
      * may `SET ROLE` and must not leave that on a pooled connection the
      * server's own queries use next.
+     *
+     * `maxResultBytes` refuses a result whose rows take more than that many
+     * bytes, with an error whose `code` is `RESULT_TOO_LARGE`, rather than
+     * return it — never a part of it. On a session of its own the read stops
+     * there; elsewhere the rows are measured once read. The WebSocket
+     * `EXECUTE_SQL` door sets it for every caller.
      */
     executeSql(sql: string, options?: {
         database?: string;
         role?: string;
         params?: unknown[];
         isolateSession?: boolean;
+        maxResultBytes?: number;
     }): Promise<Record<string, unknown>[]>;
     /**
      * Run a script a person wrote — the Studio SQL console — and describe what
@@ -490,11 +554,35 @@ export interface SQLAdmin {
      * no other. A script that leaves a transaction open is refused, and the
      * transaction rolled back: nothing outlives the run to be committed or
      * rolled back by a later one.
+     *
+     * Aborting `signal` cancels the run: the statement in progress is stopped
+     * (`pg_cancel_backend` on a Postgres server; the in-process development
+     * database cannot be interrupted, and the run ends on its own), and the
+     * promise rejects.
      */
     runSqlScript?(sql: string, options?: {
         database?: string;
         role?: string;
+        signal?: AbortSignal;
     }): Promise<SqlScriptResult>;
+    /**
+     * Read the whole result of ONE query a person wrote, a batch at a time —
+     * the Studio SQL console's "Download full result as CSV", which the
+     * console's 10,000-row cap would otherwise leave no way to get.
+     *
+     * Through a server-side cursor, in a read-only transaction, on a session
+     * of its own, as `role`: a write is refused by the database, and a second
+     * statement by the protocol. Each batch is read when the previous one has
+     * been consumed, so memory holds one batch whatever the result's size;
+     * every read runs under the session's `statement_timeout`. The session is
+     * reset and returned when the cursor is closed — which the caller must do,
+     * on success, failure or a reader that went away.
+     */
+    openSqlCursor?(sql: string, options?: {
+        database?: string;
+        role?: string;
+        batchSize?: number;
+    }): Promise<SqlCursor>;
     /**
      * Fetch the available databases on the server.
      */
@@ -520,6 +608,21 @@ export interface SQLAdmin {
      * Fetch the current database name.
      */
     fetchCurrentDatabase?(): Promise<string | undefined>;
+    /**
+     * Hold a `LISTEN` on `channel`, on a connection of its own that stays open
+     * and comes back after a drop, and call `onNotify` with each payload — what
+     * wakes the job worker when another process enqueues, instead of a poll
+     * every two seconds.
+     *
+     * Resolves once listening, with the stop. Rejects when no such connection
+     * can be had — an in-process database, a first connect that fails — so the
+     * caller can fall back to polling. `onReconnect` is called each time a
+     * dropped connection is listening again: whatever was sent meanwhile is
+     * lost. `channel` must be a plain identifier.
+     */
+    listen?(channel: string, onNotify: (payload: string) => void, options?: {
+        onReconnect?: () => void;
+    }): Promise<() => Promise<void>>;
 }
 /**
  * Administrative operations for document-based databases (MongoDB, Firestore, etc.).
@@ -799,6 +902,17 @@ export interface RealtimeSocketOptions {
      * identity that has since signed out, been revoked, demoted or deleted.
      */
     identityRecheckIntervalMs?: number;
+    /**
+     * How often a socket that asked for heartbeats (`?rebase_caps=heartbeat`)
+     * is sent one, in ms (default 30 000). The SDK redials after two missed.
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * How many sockets one identity may hold open on this server; the next
+     * one's `AUTHENTICATE` is refused with `TOO_MANY_SOCKETS` and the socket
+     * closed (4002). Unset for no ceiling. See `realtime.maxSocketsPerUser`.
+     */
+    maxSocketsPerUser?: number;
 }
 /**
  * A `BackendBootstrapper` encapsulates all driver-specific initialization logic.

package/dist/types/backup.d.ts

@@ -87,6 +87,25 @@ export interface BackupScheduleStatus {
      */
     historyError?: string;
 }
+/**
+ * A short-lived link to one backup's bytes, from `POST /admin/backups/download-url`.
+ *
+ * The URL needs no `Authorization` header — the token in it stands in for one,
+ * for this backup only — so a browser can be sent to it and stream the dump to
+ * disk instead of holding it in the page.
+ */
+export interface BackupDownloadLink {
+    /**
+     * `…/admin/backups/download?key=…&token=…`. The server answers it as a
+     * path on itself; the SDK's `downloadUrl()` answers it absolute, on the
+     * client's own base URL.
+     */
+    url: string;
+    /** The token in {@link url}, on its own. */
+    token: string;
+    /** Seconds until the link stops working (60). */
+    expiresIn: number;
+}
 /** What the backup listing (`GET /admin/backups`) answers. */
 export interface BackupListing {
     /** Backups at the destination, newest first. */

package/dist/types/cron.d.ts

@@ -1,4 +1,5 @@
 import type { RebaseServerClient } from "../controllers/client.js";
+import type { RegisteredDatabase } from "./register.js";
 /**
  * Cron Job type definitions for Rebase.
  *
@@ -10,7 +11,7 @@ import type { RebaseServerClient } from "../controllers/client.js";
  * A cron job definition file exports this shape as its default export.
  * See the example cron files in `app/backend/crons/` for usage.
  */
-export interface CronJobDefinition {
+export interface CronJobDefinition<DB = RegisteredDatabase> {
     schedule: string;
     /**
      * IANA time zone the schedule is read in, e.g. `"Europe/Madrid"`.
@@ -84,20 +85,21 @@ export interface CronJobDefinition {
      * Receives a context object with the data driver and logger.
      * May return arbitrary JSON-serialisable data stored in the log.
      */
-    handler: (ctx: CronJobContext) => Promise<unknown> | unknown;
+    handler: (ctx: CronJobContext<DB>) => Promise<unknown> | unknown;
 }
 /**
  * Context passed to each cron handler invocation.
  */
-export interface CronJobContext {
+export interface CronJobContext<DB = RegisteredDatabase> {
     /** The job's unique ID (derived from filename). */
     jobId: string;
     /** The current scheduled tick timestamp. */
     scheduledAt: Date;
     /**
-     * A simple logger scoped to this job run. Each line is kept with the
-     * run's log entry and also written to the server log at `info`, with a
-     * `cron` field holding the job ID.
+     * A simple logger scoped to this job run. Each line is written to the
+     * server log at `info`, with a `cron` field holding the job ID, and kept
+     * with the run's log entry — the first 500 lines or 64 KB of them,
+     * whichever comes first, then one line saying how many more there were.
      */
     log: (...args: unknown[]) => void;
     /**
@@ -156,7 +158,7 @@ export interface CronJobContext {
      *     }
      * });
      */
-    rebase: RebaseServerClient;
+    rebase: RebaseServerClient<DB>;
 }
 export type CronJobRunState = "idle" | "running" | "success" | "error" | "disabled";
 /**
@@ -244,3 +246,16 @@ export interface CronJobLogEntry {
     /** Whether this was a manual trigger. */
     manual?: boolean;
 }
+/**
+ * The answer to a manual trigger made with `?async=1`
+ * (`client.cron.triggerJob(id, { async: true })`): the run has started and
+ * carries on after the answer. Its outcome is in the run history, as the entry
+ * with `manual: true` and this `startedAt`.
+ */
+export interface CronJobStarted {
+    accepted: true;
+    /** ISO timestamp the run started at — the `startedAt` of its log entry. */
+    startedAt: string;
+    /** The job's status as the run began. */
+    job: CronJobStatus;
+}

package/dist/types/entities.d.ts

@@ -32,6 +32,17 @@ export interface Entity<M extends Record<string, unknown> = Record<string, unkno
      * and a record fetched by id never has one.
      */
     searchMatches?: SearchMatch[];
+    /**
+     * The version of the row this entity was read at: the `ETag` the read
+     * reported, for a `findById`, a `PATCH` answer or a live row frame. A
+     * form saves with it as `If-Match`, so a write made against a version
+     * someone has since replaced is refused instead of reverting their change.
+     *
+     * Absent for a row from a list, from a cache, or from a server or data
+     * source that does not report versions — a save then is unconditional,
+     * as it always was.
+     */
+    etag?: string;
     /**
      * Which driver this entity belongs to (e.g., 'postgres', 'firestore').
      * If not specified, the default driver is assumed.

package/dist/types/history.d.ts

@@ -27,8 +27,20 @@ export interface EntityHistoryEntry {
     action: "create" | "update" | "delete";
     /** Which fields changed. `null` for creates and deletes. */
     changed_fields: string[] | null;
+    /** The row after the change; for a delete, the row that was deleted. */
     values: Record<string, unknown> | null;
+    /**
+     * On an update, what the changed fields held before it. `null` for creates
+     * and deletes. Which fields it holds depends on {@link format}.
+     */
     previous_values: Record<string, unknown> | null;
+    /**
+     * How the entry was stored. Absent or `1`: `previous_values` is the whole
+     * row before the change. `2`: it holds the `changed_fields` only — a field
+     * that is absent from it was absent before — and every other field is
+     * unchanged, so it is in `values`.
+     */
+    format?: 1 | 2;
     updated_by: string | null;
     /** ISO-8601. A driver storing a native date converts on read. */
     updated_at: string;
@@ -46,7 +58,9 @@ export interface RecordHistoryParams {
     updatedBy?: string | null;
 }
 /**
- * How much history to keep. Pruning runs per row after each write.
+ * How much history to keep. Both rules are applied to a row after each write
+ * to it; `ttlDays` is also applied to every row by an hourly sweep, so the
+ * history of a row nobody writes again (a deleted one) still ages out.
  * @group Backend
  */
 export interface HistoryRetentionConfig {

package/dist/types/index.d.ts

@@ -35,3 +35,4 @@ export * from "./project_manifest.js";
 export * from "./collection_contract.js";
 export * from "./schema_version.js";
 export * from "./storage_authorize.js";
+export * from "./register.js";

package/dist/types/project_manifest.d.ts

@@ -83,6 +83,14 @@ export interface RebaseBackendAppConfig {
      * its default export. Default `collections/users`.
      */
     usersCollection?: string;
+    /**
+     * Type server-side data from the generated `Database`. When `true`, every
+     * `rebase generate-sdk` — `rebase dev`'s included, and the first one on a
+     * fresh clone — writes the types and the `Register` declaration to
+     * `<config>/generated/`. `rebase generate-sdk --register` sets it.
+     * Default `false`.
+     */
+    registerDatabase?: boolean;
     /**
      * `runtime: "custom"` only. Dockerfile path relative to the repository root.
      * Default `Dockerfile`.

package/dist/types/properties.d.ts

@@ -5,6 +5,12 @@ import type { ColorKey, ColorScheme } from "./chips.js";
 import type { AuthState } from "../controllers/auth_state.js";
 import type { AfterReadProps, BeforeSaveProps } from "./entity_callbacks.js";
 import type { User } from "../users/index.js";
+/**
+ * A SQL expression, written in template form: ``"sql`gen_random_uuid()`"``.
+ * The `sql` and backticks are markup; the text between them is the SQL.
+ * @group Entity properties
+ */
+export type SqlExpression = `sql\`${string}\``;
 /**
  * Callbacks/Hooks for individual property fields
  * @group Entity properties
@@ -372,6 +378,25 @@ export interface BaseProperty<CustomProps = unknown> {
      * ```
      */
     access?: FieldAccess;
+    /**
+     * The database fills this column when a create leaves it empty: a
+     * `NOT NULL DEFAULT <expression>` column such as `gen_random_uuid()`,
+     * `nextval(…)` or `now()`, whose value no property can state.
+     *
+     * A `validation.required` field with it may be left out of a create, by
+     * the admin form and by the API alike, and a create that sends it as `null`
+     * leaves it to the database rather than storing `NULL`. It is still
+     * required when a stored record is edited. The generated SDK's `Insert`
+     * type makes the field optional. Defaults to `false`.
+     *
+     * Give the expression, in the template form `isId` takes
+     * (``databaseDefault: "sql`gen_random_uuid()`"``), and the schema planner
+     * writes it as the column's `DEFAULT`, so `rebase db push` keeps it. `true`
+     * declares a DEFAULT someone else wrote and the planner does not write
+     * one, so a push plans dropping it. "Import from table" and
+     * `rebase schema introspect` set the expression they read.
+     */
+    databaseDefault?: boolean | SqlExpression;
     /**
      * Use this to define dynamic properties that change based on certain conditions
      * or on the entity's values. For example, you can make a field read-only if
@@ -421,8 +446,9 @@ export interface StringProperty extends BaseProperty {
      */
     defaultValue?: string;
     /**
-     * Optional database column type. If not set, it defaults to `varchar` or `uuid` depending on `isId` configuration.
-     * Use `text` for strings with unbound length, `char` for fixed-length strings, or `varchar` for variable-length strings with a limit.
+     * Optional database column type. If not set, it is `text` — or `uuid` for an `isId: "uuid"` key.
+     * `validation.max` does not bound a `text` column; declare `varchar` (or `char`) to get a
+     * width, which is then taken from `validation.max` (255 when it states none).
      */
     columnType?: "varchar" | "text" | "char" | "uuid";
     /**

package/dist/types/register.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The project-wide registry of generated types, filled by module augmentation.
+ *
+ * Empty by default, and every server-side data surface is untyped while it is:
+ * `context.data`, `rebase.dataAsAdmin`, a cron's `ctx.rebase` and a function's
+ * `ctx.rebase` accept any collection by any name and hand back open records.
+ *
+ * A project that generated its types with `rebase generate-sdk` registers its
+ * `Database` once, in any file the TypeScript program includes:
+ *
+ * ```ts
+ * // src/rebase-env.d.ts — or the top of any module file
+ * import type { Database } from "./generated/database.types";
+ *
+ * declare module "@rebasepro/types" {
+ *     interface Register {
+ *         database: Database;
+ *     }
+ * }
+ * ```
+ *
+ * From then on every one of those surfaces is typed from it: rows, filters,
+ * sorts, `include`, and the inputs `create` and `update` accept. Nothing about
+ * the runtime changes; the registration is a declaration.
+ *
+ * A single function or cron can still name its own type instead —
+ * `defineFunction<Database>(…)`, `defineCron<Database>({…})` — which wins over
+ * the registration.
+ *
+ * @group Data
+ */
+export interface Register {
+}
+/**
+ * The `Database` a project registered on {@link Register}, or `unknown` when it
+ * registered none — which is what keeps an unregistered project's server-side
+ * data untyped, exactly as it was before the registry existed.
+ *
+ * @group Data
+ */
+export type RegisteredDatabase = Register extends {
+    database: infer DB;
+} ? DB : unknown;

package/dist/types/relations.d.ts

@@ -22,6 +22,23 @@ export type OnAction = "cascade" | "restrict" | "no action" | "set null" | "set
  * @group Models
  */
 export declare const JUNCTION_PIVOT_KEY = "_pivot";
+/**
+ * The key a row carries the totals of its counted relations under.
+ *
+ * An include that asks for a count — `include: { tags: { limit: 4, count: true } }`
+ * — serves, beside the (capped) `tags`, how many related rows there are in all:
+ * `{ id: 1, tags: [ …4 rows ], _count: { tags: 37 } }`. One object per row,
+ * keyed by relation name, so counting a second relation adds a key rather than
+ * a second top-level name.
+ *
+ * Leading underscore, like {@link JUNCTION_PIVOT_KEY} and `_matches`: it
+ * describes the read, not the record, and no column or form writes it. A
+ * collection with a property of this name cannot ask for a count — the read
+ * answers 400 rather than writing over the column.
+ *
+ * @group Models
+ */
+export declare const INCLUDE_COUNT_KEY = "_count";
 /**
  * What kind of link a relation is.
  *
@@ -108,6 +125,23 @@ export interface BelongsToRelation extends RelationBase {
      * Defaults to `<relationName>_id`.
      */
     localKey?: string;
+    /**
+     * Whether Rebase creates a btree index on {@link localKey}. Defaults to
+     * `true`.
+     *
+     * Postgres indexes the key a foreign key *points at* but never the column
+     * holding it, so without one every read from the other side seq-scans this
+     * table: a `hasMany`/`hasOne` include, a nested listing such as
+     * `/authors/5/posts`, and the `ON DELETE` check when a target row is
+     * deleted. The derived index is skipped on its own when the column already
+     * leads one — the primary key, a `validation.unique`, or an entry in
+     * `indexes:` — so it never duplicates an index you declared.
+     *
+     * Set `false` for a table so write-heavy that the index costs more than
+     * the lookups it serves, or when you keep an index of your own on the
+     * column outside Rebase's `indexes:` block.
+     */
+    index?: boolean;
 }
 /**
  * The target holds the foreign key, and at most one target row points back.
@@ -234,7 +268,7 @@ export interface ManyToManyRelation extends RelationBase {
          *     through: {
          *         table: "org_members",
          *         properties: {
-         *             role: { type: "string", enum: ["owner", "admin", "member"],
+         *             role: { type: "string", enum: { owner: "Owner", admin: "Admin", member: "Member" },
          *                     defaultValue: "member", validation: { required: true } },
          *             joinedAt: { type: "date", autoValue: "on_create" }
          *         }
@@ -364,6 +398,8 @@ export interface ResolvedBelongsTo extends ResolvedRelationBase {
     shared: false;
     /** Column on this collection's table. */
     localKey: string;
+    /** As authored, with the default filled in — see {@link BelongsToRelation.index}. */
+    index: boolean;
 }
 /** @group Models */
 export interface ResolvedHasOne extends ResolvedRelationBase {

package/dist/types/resource_kinds.d.ts

@@ -167,11 +167,13 @@ export interface TopicOptions extends DeclareOptions {
  *
  * `attempt` counts from 1. Worth branching on: the first delivery and the
  * fourth are the same call, but the fourth is where it is worth logging loudly.
+ * `signal` is aborted when the attempt runs past the job queue's `timeoutMs`.
  */
 export type TopicHandler<T> = (event: T, context: {
     attempt: number;
     topic: string;
     subscription: string;
+    signal: AbortSignal;
 }) => Promise<void> | void;
 /** A declared subscription, as recorded in the graph and wired at boot. */
 export interface TopicSubscription<T = unknown> {
@@ -279,11 +281,15 @@ export interface QueueOptions extends DeclareOptions {
     /** Attempts before a job is left failed. Default 5. */
     maxAttempts?: number;
 }
-/** What a queue's handler receives. `attempt` counts from 1. */
+/**
+ * What a queue's handler receives. `attempt` counts from 1; `signal` is
+ * aborted when the attempt runs past the job queue's `timeoutMs`.
+ */
 export type QueueHandler<T> = (payload: T, context: {
     attempt: number;
     queue: string;
     jobId: string;
+    signal: AbortSignal;
 }) => Promise<void> | void;
 /** Per-job options at enqueue time. */
 export interface QueueEnqueueOptions {

package/dist/types/storage_authorize.d.ts

@@ -18,6 +18,11 @@ export interface StorageAuthorizeUser {
 export interface StorageAuthorizeContext {
     /** Object key, bucket prefix stripped and traversal already sanitized. */
     key: string;
+    /**
+     * The bucket, by one name per bucket. On S3 and GCS, whose source serves a
+     * single bucket, this is always `"default"` — also when the request named
+     * the provider's bucket (`acme-media`), which reaches the same objects.
+     */
     bucket: string;
     operation: StorageOperation;
     /** Null when the route allows unauthenticated access. */

package/dist/types/websockets.d.ts

@@ -69,6 +69,13 @@ export interface CollectionUpdateMeta {
     hasMore: boolean;
     /** The opaque cursor continuing this listing — see `PaginationMeta.nextCursor`. */
     nextCursor?: string;
+    /**
+     * When `total` was counted, ISO-8601 — present only when it was not
+     * counted for this frame. A server with `REALTIME_RECOUNT_INTERVAL_MS` set
+     * reuses a big list's total for that long rather than counting it on every
+     * write; `hasMore` is then judged against the reused total.
+     */
+    totalAsOf?: string;
     /**
      * The count could not be taken, so `total` is missing and `hasMore` is a
      * floor rather than an answer.
@@ -97,6 +104,14 @@ export interface SingleUpdateMessage extends WebSocketMessage {
     type: "single_update";
     subscriptionId: string;
     row: Record<string, unknown> | null;
+    /**
+     * The row's version: the `ETag` a `GET /:id` of it answers, to send back
+     * as `If-Match` on a `PATCH` or `DELETE`. Sent only to a `subscribe_one`
+     * that asked with `etag: true`, and never beside a `null` row. A server
+     * that predates it ignores the ask and sends no tag; a client that does
+     * not ask gets frames without one.
+     */
+    etag?: string;
 }
 /**
  * Lightweight patch message sent to collection subscribers when a single
@@ -151,6 +166,22 @@ export interface BroadcastMessage extends WebSocketMessage {
      */
     seq?: number;
 }
+/**
+ * Server → client: the sequence number the sender's own broadcast took on a
+ * retained channel, sent to the sender in place of the message itself (which
+ * is never echoed back).
+ *
+ * Sent only to a socket that opted into `channel_seq` when it opened (see the
+ * socket's `hello`). With it, every member of a retained channel hears of
+ * every number, one way or the other, so a client that sees a hole in the
+ * sequence knows it missed a message and can ask for it — which is what the
+ * SDK does.
+ */
+export interface BroadcastAckMessage extends WebSocketMessage {
+    type: "broadcast_ack";
+    channel: string;
+    seq: number;
+}
 /**
  * Server → client: the whole roster of a channel.
  *
@@ -276,4 +307,4 @@ export interface ChannelHistoryMessage extends WebSocketMessage {
  * {@link WebSocketMessage}, whose `type` is a bare `string`, and a `string`
  * discriminates nothing.
  */
-export type ChannelMessage = BroadcastMessage | PresenceStateMessage | PresenceDiffMessage | ChannelHistoryMessage | ChannelErrorMessage;
+export type ChannelMessage = BroadcastMessage | BroadcastAckMessage | PresenceStateMessage | PresenceDiffMessage | ChannelHistoryMessage | ChannelErrorMessage;