@rebasepro/types 0.19.1 → 0.19.2-canary.g08eed46

package/dist/controllers/data.d.ts

@@ -1,7 +1,7 @@
 import type { VectorSearchParams } from "./data_driver.js";
 import type { ComputedSortField, SearchMatch } from "../types/search.js";
 import { Entity, EntityValues } from "../types/entities.js";
-import { WhereFilterOp, FieldPath, NonColumnFieldPath, FilterValues, OrderBySpec, RelationAggregateSort } from "../types/filter-operators.js";
+import { WhereFilterOp, FieldPath, NonColumnFieldPath, FilterValues, NullsPlacement, OrderBySpec, RelationAggregateSort } from "../types/filter-operators.js";
 /**
  * The element type of an array column, and the column's own type otherwise.
  *
@@ -54,8 +54,24 @@ export type WhereElementOf<T> = ElementOf<T> | IdOf<ElementOf<T>>;
  * permissive as it was.
  */
 export type WhereValueFor<Op extends WhereFilterOp, T> = Op extends "array-contains" ? WhereElementOf<T> : Op extends "in" | "not-in" | "array-contains-any" ? readonly WhereElementOf<T>[] | WhereElementOf<T> | null : Op extends "like" | "ilike" | "not-like" | "not-ilike" ? string : Op extends "is-null" | "is-not-null" ? null | undefined : T | null;
+/**
+ * A group of conditions combined with `and`, `or`, or negated with `not`.
+ *
+ * ## `not`
+ *
+ * `not` negates the **conjunction** of its `conditions`: `not(a)` is `NOT a`,
+ * and `not(a, b)` is `NOT (a AND b)`. One rule, stated here and applied
+ * identically by the wire codec (`or(...)`/`and(...)`/`not(...)` in
+ * `@rebasepro/common`), the REST `?not=` parameter and every driver compiler,
+ * so a negation means the same thing whichever end writes it.
+ *
+ * Negation is not expressible by inverting the operators inside the group: SQL
+ * three-valued logic makes `NOT (a AND b)` and `(NOT a) OR (NOT b)` differ the
+ * moment a NULL is involved, and only one of them is what the caller wrote. It
+ * compiles to a real `NOT (...)`.
+ */
 export interface LogicalCondition {
-    type: "and" | "or";
+    type: "and" | "or" | "not";
     conditions: (FilterCondition | LogicalCondition)[];
 }
 export interface FilterCondition {
@@ -63,6 +79,76 @@ export interface FilterCondition {
     operator: WhereFilterOp;
     value: unknown;
 }
+/**
+ * How one relation is loaded by {@link FindParams.include}.
+ *
+ * `true` loads the relation whole. The object form narrows it — the same four
+ * knobs a top-level query has, applied to the rows *inside* one relation — and
+ * `include` nests, so a query can ask for "each post's five newest published
+ * comments, each with its author" in one request.
+ *
+ * ```ts
+ * include: {
+ *   comments: {
+ *     limit: 5,
+ *     where: { published: ["==", true] },
+ *     orderBy: ["created_at", "desc"],
+ *     include: { author: true }
+ *   }
+ * }
+ * ```
+ *
+ * Nesting is bounded at {@link MAX_INCLUDE_DEPTH} hops. Each hop is another
+ * batched query, and the bound is what stops one request from walking a
+ * self-referencing relation forever.
+ *
+ * @group Data
+ */
+export interface IncludeOptions {
+    /** Rows to load per parent row. Applied per parent, not across the page. */
+    limit?: number;
+    /** Filter the related rows, in the same dialect as {@link FindParams.where}. */
+    where?: FilterValues<string>;
+    /** An `and`/`or`/`not` group over the related rows. */
+    logical?: LogicalCondition;
+    /**
+     * Sort the related rows — the tuple form, or the `field:direction[:nulls]`
+     * shorthand the REST `?orderBy=` parameter uses.
+     *
+     * The string is accepted because this whole object travels over a query
+     * string, where a tuple is three characters of JSON heavier for no gain.
+     */
+    orderBy?: OrderBySpec<string> | string;
+    /** Columns of the *related* row to return. `id` is always included. */
+    fields?: string[];
+    /** Relations of the related row to load in turn. */
+    include?: IncludeSpec;
+}
+/**
+ * The relations a read loads, as a list of (possibly dotted) names or as a
+ * tree.
+ *
+ * - `["author", "comments.author"]` — a dotted path is the same thing as the
+ *   nested object form, spelled flat. It is what the REST `?include=` parameter
+ *   carries, and the two forms compile to the same request.
+ * - `["*"]` — every relation, one hop deep. The admin panel's shape.
+ * - `{ comments: { limit: 5, include: { author: true } } }` — the parametrised
+ *   form.
+ *
+ * A name that is not a relation of the collection is a **400
+ * `UNKNOWN_RELATION`**, not a silent omission: a read that quietly drops an
+ * `include` answers 200 with the field missing, which is indistinguishable from
+ * a row that genuinely has no related row.
+ *
+ * @group Data
+ */
+export type IncludeSpec = string[] | Record<string, true | IncludeOptions>;
+/**
+ * Hops an {@link IncludeSpec} may nest. `comments.author` is two.
+ *
+ * @group Data
+ */
+export declare const MAX_INCLUDE_DEPTH = 3;
 /**
  * Parameters for querying a collection.
  *
@@ -145,13 +231,59 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
      */
     orderBy?: OrderBySpec<FieldPath<M> | ComputedSortField>;
     /**
-     * Relations to include in the response.
+     * Relations to load into the response — see {@link IncludeSpec}.
+     *
+     * Not checked against `M` here: a relation name comes from the collection's
+     * `relations`, not from its columns, so nothing in a *hand-written* row type
+     * can validate one. A **generated** `Database` narrows this to the
+     * collection's actual relation keys, recursively — see `rebase codegen`.
+     *
+     * An unknown name is a 400 `UNKNOWN_RELATION`. It used to be ignored.
+     */
+    include?: IncludeSpec;
+    /**
+     * Columns to return, instead of all of them.
+     *
+     * A real column projection: only these columns are read from the database,
+     * so a query that needs two fields of a wide row does not pay for the rest.
+     * `excludeFromApi` still applies — naming such a column here does not
+     * un-hide it — and the primary key is always returned, because a row that
+     * cannot be addressed cannot be updated, deleted or paged past.
+     *
+     * A relation named in {@link FindParams.include} is loaded regardless of
+     * whether it appears here; use {@link IncludeOptions.fields} to narrow the
+     * columns *within* an included relation.
+     */
+    fields?: string[];
+    /**
+     * Collapse rows that are identical over the columns being returned.
+     *
+     * `SELECT DISTINCT` over the projection — so it is only meaningful
+     * alongside {@link FindParams.fields}, and with the primary key in the
+     * projection (which it always is) every row is already distinct. Pair it
+     * with `fields` naming the columns you actually want the distinct values of.
      *
-     * Deliberately `string[]` and not checked against `M`: a relation name
-     * comes from the collection's `relations`, not from its columns, so nothing
-     * in a generated row type can validate one.
+     * `meta.total` counts distinct rows too, so a distinct listing's `hasMore`
+     * describes the set it is paging.
      */
-    include?: string[];
+    distinct?: boolean;
+    /**
+     * Continue from where a previous page ended — keyset ("seek") pagination.
+     *
+     * The value is the opaque `meta.nextCursor` of the previous response. It
+     * encodes the sort keys the query was ordered by and the last row's values
+     * for them, so a page picks up strictly after the last row served rather
+     * than at a row *count* that concurrent writes have already moved.
+     *
+     * It has to describe the same query: `after` alongside a different
+     * `orderBy` is a 400 `CURSOR_ORDER_MISMATCH` rather than a page of rows
+     * seeked in an order nobody asked for. Mutually exclusive with `offset` and
+     * `page` for the same reason.
+     *
+     * Multi-key sorts and nullable keys both work — the comparison is built
+     * over every key, in order, with the NULL placement the sort declared.
+     */
+    after?: string;
     /**
      * Text search string, AND-ed with `where`/`logical`. This is the value
      * behind the query builder's `.search()` method.
@@ -279,6 +411,7 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      */
     createMany?(data: Partial<EntityValues<M>>[], options?: {
         upsert?: boolean;
+        onConflict?: readonly string[];
     }): Promise<Entity<M>[]>;
     /**
      * Update an existing record by ID.
@@ -324,6 +457,13 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      * one place the two halves of this API are not interchangeable.
      */
     count?(params?: FindParams<M>): Promise<number>;
+    /**
+     * {@link SDKCollectionClient.aggregate}. Optional here for the same reason
+     * `count` is: not every data source can compute one, and the SDK wraps an
+     * absent implementation in a stub that says so rather than returning a
+     * number nothing counted.
+     */
+    aggregate?(params: AggregateParams<M>): Promise<AggregateRow[]>;
     where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): QueryBuilderInterface<M>;
     where(logicalCondition: LogicalCondition): QueryBuilderInterface<M>;
     orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): QueryBuilderInterface<M>;
@@ -356,6 +496,20 @@ export interface PaginationMeta {
     limit: number;
     offset: number;
     hasMore: boolean;
+    /**
+     * The opaque cursor that continues this listing — pass it back as
+     * {@link FindParams.after}.
+     *
+     * Present whenever there is a next page to describe (`hasMore` is true and
+     * the page returned at least one row). Absent on the last page, and absent
+     * on a query no cursor can describe (relevance ordering, whose scores are
+     * computed per query and are not comparable between two of them).
+     *
+     * Opaque on purpose: it encodes the sort keys *and* the last row's values
+     * for them, and a client that parsed it would be depending on an encoding
+     * that exists to be changed.
+     */
+    nextCursor?: string;
 }
 /**
  * Paginated response from a collection query (SDK-facing).
@@ -416,6 +570,66 @@ export type QueryComputedFields = {
      */
     _distance?: number;
 };
+/**
+ * One aggregate a query asks for.
+ *
+ * `count` alone counts rows; every other function names a column, and `count`
+ * with a column counts its non-NULL values.
+ *
+ * The result key is derived rather than chosen: `sum(total)` comes back as
+ * `sum_total` and a bare `count()` as `count`. Letting a caller name it would
+ * mean checking their name is not also a `groupBy` field — a rule nobody would
+ * guess, and a silently overwritten value if it went unchecked.
+ *
+ * @group Data
+ */
+export type AggregateSelect<M extends Record<string, unknown> = Record<string, unknown>> = {
+    fn: "count";
+    field?: Extract<keyof M, string>;
+} | {
+    fn: "sum" | "avg" | "min" | "max";
+    field: Extract<keyof M, string>;
+};
+/**
+ * One row of an aggregate result: the `groupBy` columns, plus one key per
+ * {@link AggregateSelect} under its derived alias.
+ *
+ * `count`, `sum` and `avg` arrive as numbers — Postgres returns bigint and
+ * numeric as strings, and they are parsed once at the driver rather than by
+ * every caller. `min`/`max` keep the column's own type.
+ *
+ * @group Data
+ */
+export type AggregateRow = Record<string, unknown>;
+/**
+ * What {@link SDKCollectionClient.aggregate} takes: the same narrowing a
+ * `find()` takes, minus the parts of it that describe a *page* of rows.
+ *
+ * `limit` survives and means what it means on the REST route — a bound on the
+ * number of **groups**, because grouping by a high-cardinality column is a whole
+ * table's worth of rows in one response. It is ignored when there is no
+ * `groupBy`, since an ungrouped aggregate is one row.
+ *
+ * `orderBy`, `include`, `after` and the rest are absent on purpose: an
+ * aggregate has no rows to sort, no relations to load and no page to continue.
+ * They were silently ignored on the REST route; here they do not typecheck.
+ *
+ * @group Data
+ */
+export interface AggregateParams<M extends Record<string, unknown> = Record<string, unknown>> {
+    /** The aggregates to compute. At least one. */
+    select: AggregateSelect<M>[];
+    /** Columns to group by. Omit for a single row over everything that matches. */
+    groupBy?: Extract<keyof M, string>[];
+    /** Filter conditions, as {@link FindParams.where}. */
+    where?: FilterValues<FieldPath<M>>;
+    /** An `and`/`or`/`not` group, AND-ed with `where`. */
+    logical?: LogicalCondition;
+    /** Text search, AND-ed with the filters. */
+    searchString?: string;
+    /** Most groups to return. Ignored without `groupBy`. */
+    limit?: number;
+}
 /**
  * Which column an iteration seeks on, for keyset ("seek") pagination.
  *
@@ -524,7 +738,7 @@ export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Re
      * Sort by a column, a relation or JSON path, `_score`, or an aggregate over
      * a to-many relation — the same key set {@link FindParams.orderBy} takes.
      */
-    orderBy(column: FieldPath<M> | ComputedSortField | RelationAggregateSort, direction?: "asc" | "desc"): this;
+    orderBy(column: FieldPath<M> | ComputedSortField | RelationAggregateSort, direction?: "asc" | "desc", nulls?: NullsPlacement): this;
     limit(count: number): this;
     offset(count: number): this;
     search(searchString: string, options?: {
@@ -543,8 +757,29 @@ export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Re
         distance?: "cosine" | "l2" | "inner_product";
         threshold?: number;
     }): this;
-    include(...relations: string[]): this;
+    /**
+     * Load relations — names, dotted paths (`"comments.author"`), or the
+     * parametrised tree. Repeated calls merge rather than replace.
+     */
+    include(...relations: (string | IncludeSpec)[]): this;
+    /**
+     * Return only these columns. A real projection: the columns are what is
+     * read from the database, not what survives a trim of the response.
+     */
+    fields(...columns: (FieldPath<M> | string)[]): this;
+    /** `SELECT DISTINCT` over the projection — see {@link FindParams.distinct}. */
+    distinct(enabled?: boolean): this;
+    /** Continue after a previous page's `meta.nextCursor`. */
+    after(cursor: string): this;
     find(): Promise<FindResult<M>>;
+    /**
+     * Aggregate the rows this query matches instead of returning them.
+     *
+     * The builder's `where`/`logical`/`search` narrow which rows are
+     * aggregated; its `orderBy`, `include` and window do not apply and are
+     * ignored, exactly as they are on the REST route.
+     */
+    aggregate(params: Omit<AggregateParams<M>, "where" | "logical" | "searchString">): Promise<AggregateRow[]>;
     /**
      * Page through everything this query matches, one row at a time.
      *
@@ -591,6 +826,173 @@ export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Re
  *
  * @group Data
  */
+/**
+ * A change expressed as an operation on the column's current value, rather than
+ * as the value to store.
+ *
+ * `{ views: 5 }` says what the number becomes; `{ views: { $inc: 1 } }` says
+ * what happens to it. The difference is the read the caller no longer has to
+ * make — and the race that read opens. Two requests that each read `4`, add one
+ * and write `5` lose an increment between them; `SET views = views + 1` cannot,
+ * because the arithmetic happens inside the statement holding the row lock.
+ *
+ * Exactly one operator per field. `{ views: { $inc: 1, $push: "x" } }` is
+ * refused rather than applied in an order the caller cannot see.
+ *
+ * @group Data
+ */
+/**
+ * The operator names, as a value.
+ *
+ * A runtime list beside the type because three layers have to *recognise* an
+ * operation, not just accept one: the REST validator, the driver that compiles
+ * it, and the offline queue that must refuse to apply one locally. Three copies
+ * of four strings is three chances for one of them to miss an operator added to
+ * the other two, and the failure is silent in the worst direction — an
+ * unrecognised marker is written to the column as a JSON document.
+ *
+ * @group Data
+ */
+export declare const FIELD_OPERATORS: readonly ["$inc", "$push", "$pull", "$merge"];
+/**
+ * The key of a {@link BatchRef}. Declared here, beside the field operators,
+ * because the two share one namespace: a `$`-prefixed key in a write payload is
+ * a marker, and every reader of that namespace has to know all of it.
+ *
+ * @group Data
+ */
+export declare const BATCH_REF_KEY = "$ref";
+/**
+ * Whether a value is *trying* to be a field operation — including a misspelled
+ * one, which is the case worth catching.
+ *
+ * Any `$`-prefixed key counts, because `{ $increment: 1 }` written to a number
+ * column as a JSON document is the failure this exists to prevent. No collection
+ * can declare a column whose value legitimately has a key beginning with `$`: a
+ * `map` property's sub-keys are declared, and `$` is not valid in the
+ * identifiers the DDL generators emit.
+ *
+ * The one exception is `{ $ref: … }`, the batch's backward reference. It stands
+ * where a *value* goes and is resolved to one before the row is written, so it
+ * is not an operation on a column — reading it as a misspelled operator refused
+ * every `$ref` in a batch with "unknown field operator '$ref'".
+ *
+ * @group Data
+ */
+export declare function isFieldOperation(value: unknown): boolean;
+/** True when any value in a write payload is (or is attempting to be) one. @group Data */
+export declare function hasFieldOperation(values: Record<string, unknown> | undefined): boolean;
+export type FieldOperation = 
+/** Add to a `number` column; negative to subtract. `SET col = col + n`. */
+{
+    $inc: number;
+}
+/** Append one value, or each of an array of values, to an `array` column. */
+ | {
+    $push: unknown;
+}
+/** Remove every occurrence of a value from an `array` column. */
+ | {
+    $pull: unknown;
+}
+/** Shallow-merge an object into a `map` column. `SET col = col || …::jsonb`. */
+ | {
+    $merge: Record<string, unknown>;
+};
+/**
+ * The payload {@link SDKCollectionClient.update} accepts: plain values, field
+ * operations, or both in one body.
+ *
+ * @group Data
+ */
+export type UpdateValues<U> = {
+    [K in keyof U]?: U[K] | FieldOperation;
+};
+/**
+ * Where an upsert looks for the row it might be replacing.
+ *
+ * The columns must carry a uniqueness guarantee the database can use as an
+ * `ON CONFLICT` target — the primary key, a property with
+ * `validation.unique`, or the columns of a declared `unique` index. Anything
+ * else is refused with a 400 rather than sent to Postgres, which would answer
+ * `there is no unique or exclusion constraint matching the ON CONFLICT
+ * specification` from inside a transaction that has already done work.
+ *
+ * @group Data
+ */
+export interface UpsertOptions extends WriteOptions {
+    /** Column names forming the conflict target. Defaults to the primary key. */
+    onConflict?: readonly string[];
+}
+/**
+ * A placeholder standing for a value only the server will know: the id of a row
+ * an earlier operation in the same batch creates.
+ *
+ * `{ "$ref": "order.id" }` reads the field `id` off the result of the operation
+ * that named itself `ref: "order"`. Without it a batch cannot express the one
+ * thing a cross-collection batch exists for — writing a parent and its children
+ * together — because the child's foreign key is not knowable until the parent
+ * has been inserted, and splitting the two into separate requests is exactly
+ * the non-atomic sequence the batch replaces.
+ *
+ * Only backward references resolve. `ref` names must be unique within a batch,
+ * and an operation may not reference itself or anything after it.
+ *
+ * @group Data
+ */
+export interface BatchRef {
+    /** `<ref name>.<field>`, e.g. `order.id`. */
+    $ref: string;
+}
+/** One entry of a batch request. @group Data */
+export type BatchOperation<DB = Record<string, unknown>> = {
+    [K in Extract<keyof DB, string>]: {
+        op: "create";
+        collection: K;
+        values: {
+            [F in keyof InsertOf<DB[K]>]?: InsertOf<DB[K]>[F] | BatchRef;
+        } & Record<string, unknown>;
+        /** Name this row so a later operation can reference its columns. */
+        ref?: string;
+    } | {
+        op: "upsert";
+        collection: K;
+        values: {
+            [F in keyof InsertOf<DB[K]>]?: InsertOf<DB[K]>[F] | BatchRef;
+        } & Record<string, unknown>;
+        /** See {@link UpsertOptions.onConflict}. Defaults to the primary key. */
+        onConflict?: readonly string[];
+        ref?: string;
+    } | {
+        op: "update";
+        collection: K;
+        id: string | number | BatchRef;
+        values: {
+            [F in keyof UpdateOf<DB[K]>]?: UpdateOf<DB[K]>[F] | FieldOperation | BatchRef;
+        } & Record<string, unknown>;
+        ref?: string;
+    } | {
+        op: "delete";
+        collection: K;
+        id: string | number | BatchRef;
+        ref?: string;
+    };
+}[Extract<keyof DB, string>];
+/**
+ * What `POST /api/data/_batch` answers with.
+ *
+ * `data` is aligned to `operations`: the written row for a create, upsert or
+ * update, and `null` for a delete — so an index into one is an index into the
+ * other, whatever the batch mixed.
+ *
+ * @group Data
+ */
+export interface BatchResult<R = Record<string, unknown>> {
+    data: (R | null)[];
+    meta: {
+        operations: number;
+    };
+}
 /**
  * Per-request options for a write.
  * @group Data
@@ -621,6 +1023,37 @@ export interface WriteOptions {
      * header rather than refusing the write.
      */
     idempotencyKey?: string;
+    /**
+     * Whether the server should send the written row back.
+     *
+     * `false` sends `Prefer: return=minimal`, and the write answers `204 No
+     * Content` — `200` carrying the ids only, for a batch. The row is the
+     * default because it carries what the server decided: a serial id, an
+     * `autoValue` timestamp, whatever `beforeSave` rewrote. A caller that
+     * needs none of that is paying for a full row serialisation and, on
+     * Postgres, a read-back per written row.
+     *
+     * Reach for it on imports and fire-and-forget writes. The method resolves
+     * to `undefined` (or `[]`) when it is set, so a caller cannot accidentally
+     * use a row the server never sent.
+     */
+    returning?: boolean;
+    /**
+     * The version of the row this write was made against, so it is refused if
+     * the row has moved on.
+     *
+     * The `ETag` from the read that produced the row — `etagOf(row)` on a row
+     * from `findById`, or the `ETag` response header. A mismatch answers `412`
+     * rather than writing, which is the difference between "update the row I
+     * read" and "overwrite whatever is there now". Without it a read, an edit
+     * and a write is last-writer-wins over everything the write did not send,
+     * and the loser is told nothing.
+     *
+     * `"*"` asserts only that the row exists.
+     *
+     * Honoured on `update` and `delete`.
+     */
+    ifMatch?: string;
 }
 export interface SDKCollectionClient<M extends Record<string, unknown> = Record<string, unknown>, I = Partial<M>, U = Partial<M>> {
     /**
@@ -787,6 +1220,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      */
     createMany(data: I[], options?: {
         upsert?: boolean;
+        onConflict?: readonly string[];
     } & WriteOptions): Promise<M[]>;
     /**
      * Update an existing record by ID.
@@ -802,7 +1236,37 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * that retry from a second deliberate edit — which on a `PATCH` that
      * increments or appends is a second edit applied.
      */
-    update(id: string | number, data: U, options?: WriteOptions): Promise<M>;
+    update(id: string | number, data: U | UpdateValues<U>, options?: WriteOptions): Promise<M>;
+    /**
+     * Insert the row, or replace the one already occupying its key.
+     *
+     * `INSERT ... ON CONFLICT DO UPDATE`, in one statement — so unlike a
+     * `findById` followed by `create`-or-`update` it cannot lose the race
+     * between the two, and unlike `create` it does not fail when the row is
+     * already there. That is what makes a re-runnable import idempotent
+     * without a key.
+     *
+     * The conflict target defaults to the primary key. Pass `onConflict` to
+     * upsert on a natural key instead — `["email"]`, `["tenant_id", "slug"]` —
+     * and the columns must carry a uniqueness guarantee the database can use:
+     * a property with `validation.unique`, or the columns of a declared
+     * `unique` index. Anything else is a 400 rather than a Postgres error
+     * raised half-way through a transaction.
+     *
+     * The `on_create` timestamp of a row that already existed is left alone: a
+     * conflict means the row's creation is a fact about the past, and a nightly
+     * re-import that reset `createdAt` on everything it touched would take
+     * every "new this week" query with it.
+     *
+     * @example
+     * ```ts
+     * await client.data.users.upsert(
+     *     { email: "a@b.c", name: "Ada" },
+     *     { onConflict: ["email"] }
+     * );
+     * ```
+     */
+    upsert(data: I, options?: UpsertOptions): Promise<M>;
     /**
      * Update many records in a single request and a single transaction.
      *
@@ -843,13 +1307,19 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      */
     updateMany(updates: {
         id: string | number;
-        data: U;
+        data: U | UpdateValues<U>;
     }[], options?: WriteOptions): Promise<M[]>;
     /**
      * Delete a record by ID.
      * @throws {RebaseApiError} with status 404 when the record does not exist.
+     *
+     * Takes {@link WriteOptions} like every other write. It did not, so the one
+     * mutation that cannot be made safe by repeating it — a delete replayed
+     * after the row is gone answers 404, which an offline queue reads as a
+     * permanent failure — was also the one that could not carry an
+     * `idempotencyKey`.
      */
-    delete(id: string | number): Promise<void>;
+    delete(id: string | number, options?: WriteOptions): Promise<void>;
     /**
      * Delete many records in a single request and a single transaction.
      *
@@ -907,11 +1377,36 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * it does instead.
      */
     count(params?: FindParams<M>): Promise<number>;
+    /**
+     * `count`/`sum`/`avg`/`min`/`max` over the matching rows, optionally
+     * grouped — the SDK half of `GET /<collection>/aggregate`.
+     *
+     * The whole point is not to fetch rows in order to reduce them: "revenue by
+     * status" over a million orders is one query and one row per status here,
+     * and a `findAll()` plus a loop everywhere else — which is wrong under a
+     * `limit` and unaffordable without one. It runs through the same
+     * request-scoped handle as every other read, so RLS applies to the rows
+     * being aggregated.
+     *
+     * ```ts
+     * const rows = await rebase.data.orders.aggregate({
+     *     select: [{ fn: "sum", field: "total" }, { fn: "count" }],
+     *     groupBy: ["status"],
+     *     where: { created_at: [">=", startOfMonth] }
+     * });
+     * // [{ status: "paid", sum_total: 41822.5, count: 317 }, …]
+     * ```
+     *
+     * Always present; a backend whose driver cannot aggregate answers 501
+     * naming the capability rather than an empty result set, which would read
+     * as "nothing matched".
+     */
+    aggregate(params: AggregateParams<M>): Promise<AggregateRow[]>;
     where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): SDKQueryBuilderInterface<M>;
     /** A relation path (`author.name`) or a JSON path (`metadata->>tier`). */
     where(column: NonColumnFieldPath, operator: WhereFilterOp, value: unknown): SDKQueryBuilderInterface<M>;
     where(logicalCondition: LogicalCondition): SDKQueryBuilderInterface<M>;
-    orderBy(column: FieldPath<M> | ComputedSortField | RelationAggregateSort, direction?: "asc" | "desc"): SDKQueryBuilderInterface<M>;
+    orderBy(column: FieldPath<M> | ComputedSortField | RelationAggregateSort, direction?: "asc" | "desc", nulls?: NullsPlacement): SDKQueryBuilderInterface<M>;
     limit(count: number): SDKQueryBuilderInterface<M>;
     offset(count: number): SDKQueryBuilderInterface<M>;
     search(searchString: string, options?: {
@@ -926,7 +1421,13 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
         distance?: "cosine" | "l2" | "inner_product";
         threshold?: number;
     }): SDKQueryBuilderInterface<M>;
-    include(...relations: string[]): SDKQueryBuilderInterface<M>;
+    include(...relations: (string | IncludeSpec)[]): SDKQueryBuilderInterface<M>;
+    /** {@link SDKQueryBuilderInterface.fields} */
+    fields(...columns: (FieldPath<M> | string)[]): SDKQueryBuilderInterface<M>;
+    /** {@link SDKQueryBuilderInterface.distinct} */
+    distinct(enabled?: boolean): SDKQueryBuilderInterface<M>;
+    /** {@link SDKQueryBuilderInterface.after} */
+    after(cursor: string): SDKQueryBuilderInterface<M>;
 }
 /**
  * The unified data access object for the **admin panel** (Entity-shaped).