@rebasepro/types 0.13.0 → 0.13.1-canary.g06dbe5b

package/src/controllers/data.ts

@@ -1,8 +1,80 @@
+import type { VectorSearchParams } from "./data_driver";
+import type { ComputedSortField, SearchMatch } from "../types/search";
 import { Entity, EntityValues } from "../types/entities";
 import { WhereFilterOp, FieldPath, FilterValues, OrderByTuple } from "../types/filter-operators";
 
+/**
+ * Operator-blind filter value: whatever the column holds, a list of it, or null.
+ *
+ * @deprecated Superseded by {@link WhereValueFor}, which correlates the value
+ * with the operator. Kept exported because it is public API and downstream code
+ * annotates with it; every `where()` overload in this file uses `WhereValueFor`.
+ */
 export type WhereValue<T> = T | T[] | null;
 
+/**
+ * The element type of an array column, and the column's own type otherwise.
+ *
+ * A generated SDK emits an `array` property as `Array<X>` and a to-many
+ * relation as `Array<TargetRow>`, so this is what `array-contains` compares
+ * against on either.
+ */
+export type ElementOf<T> = T extends readonly (infer E)[] ? E : T;
+
+/**
+ * The `id` of a row-shaped element, and `never` for anything else.
+ *
+ * A to-many relation is emitted as `Array<TargetRow>`, but the filter compilers
+ * compare a relation by **id** — `buildRelationFilterPredicate` in
+ * `@rebasepro/server-postgres` unwraps a relation value down to its id — so
+ * `where("tags", "array-contains", tagId)` is the call that works, and the
+ * element type alone would refuse it.
+ */
+export type IdOf<E> = E extends { id: infer I } ? I : never;
+
+/**
+ * One member of an array column: its element, or — when the element is a row —
+ * that row's id, which is what a relation filter is actually compared against.
+ */
+export type WhereElementOf<T> = ElementOf<T> | IdOf<ElementOf<T>>;
+
+/**
+ * The value a given operator takes on a column of type `T`.
+ *
+ * `WhereValue<T>` was one value type for all sixteen operators, which made
+ * `array-contains` uncallable from a generated SDK — it is the one operator
+ * whose value is an *element* of the column rather than the column's own type,
+ * so on `tags: string[]` it wanted a `string[]` and the documented
+ * `.where("tags", "array-contains", "featured")` was a compile error. The
+ * spelling that did compile, `["featured"]`, builds `@> ARRAY[$1]` with the
+ * whole array bound as the single element and matches nothing: the correct
+ * query rejected, the accepted query silently wrong.
+ *
+ * The branches mirror `buildSingleFilterCondition` in `@rebasepro/server-postgres`:
+ *
+ * - `array-contains` → one element of the column (or a related row's id).
+ * - `in` / `not-in` / `array-contains-any` → a list of elements; a bare element
+ *   is read as the one-element list, and `null` is a null check.
+ * - `like` / `ilike` / `not-like` / `not-ilike` → a SQL pattern. Always a
+ *   string, including on numeric and date columns, which the driver casts.
+ * - `is-null` / `is-not-null` → nothing; the value is ignored everywhere.
+ * - everything else → the column's own type, or `null` for a null comparison.
+ *
+ * Distributes over `Op`, so a caller holding an unnarrowed `WhereFilterOp`
+ * (a dynamic filter UI, say) gets the union of every branch and stays as
+ * 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;
+
 export interface LogicalCondition {
     type: "and" | "or";
     conditions: (FilterCondition | LogicalCondition)[];
@@ -38,13 +110,24 @@ export interface FilterCondition {
  *
  * `limit`/`offset` and `page` describe the same window two ways. If **both
  * `offset` and `page` are provided, `page` wins** — the backend computes
- * `offset = (page - 1) * (limit ?? 20)` and ignores the explicit `offset`.
- * Pick one style per query.
+ * `offset = (page - 1) * (limit ?? DEFAULT_LIST_LIMIT)` and ignores the
+ * explicit `offset`. Pick one style per query.
  *
  * @group Data
  */
 export interface FindParams<M extends Record<string, unknown> = Record<string, unknown>> {
-    /** Maximum number of items to return (default: 20). */
+    /**
+     * Maximum number of items to return.
+     *
+     * Omit it and the backend applies {@link DEFAULT_LIST_LIMIT}, so a read is
+     * never unbounded. Provide it and it must be a whole number between 1 and
+     * {@link MAX_LIST_LIMIT}: the backend **rejects** anything else with a 400
+     * rather than trimming it to fit, because a page quietly smaller than the
+     * one you asked for is indistinguishable from having reached the end of the
+     * collection. To read past the ceiling, page with `offset` — or let
+     * {@link SDKCollectionClient.iterate} / {@link SDKCollectionClient.findAll}
+     * do it for you.
+     */
     limit?: number;
     /**
      * Number of items to skip. Ignored when {@link FindParams.page} is also
@@ -53,7 +136,7 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
     offset?: number;
     /**
      * Page number (1-indexed), alternative to {@link FindParams.offset}.
-     * When set, overrides `offset` as `(page - 1) * (limit ?? 20)`.
+     * When set, overrides `offset` as `(page - 1) * (limit ?? DEFAULT_LIST_LIMIT)`.
      */
     page?: number;
     /**
@@ -80,7 +163,7 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
      * Sort order as a `[field, direction]` tuple.
      * @example orderBy: ["created_at", "desc"]
      */
-    orderBy?: OrderByTuple<FieldPath<M>>;
+    orderBy?: OrderByTuple<FieldPath<M> | ComputedSortField>;
     /**
      * Relations to include in the response.
      *
@@ -90,11 +173,47 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
      */
     include?: string[];
     /**
-     * Full-text search string. Matched (OR-ed) across the collection's
-     * searchable columns, then AND-ed with `where`/`logical`. This is the
-     * value behind the query builder's `.search()` method.
+     * Text search string, AND-ed with `where`/`logical`. This is the value
+     * behind the query builder's `.search()` method.
+     *
+     * What it compiles to depends on the collection. By default — matching
+     * every collection that has not said otherwise — it is a case-insensitive
+     * substring match OR-ed across the collection's top-level `string`
+     * properties: it does not reach inside `map` or `array` properties, it does
+     * not stem or rank, and it cannot use an index.
+     *
+     * A Postgres collection that declares a `search` block instead gets a
+     * ranked full-text match over exactly the fields it named, and rows come
+     * back with a {@link FindParams.orderBy}-able `_score`.
      */
     searchString?: string;
+
+    /**
+     * Nearest-neighbour search over a `vector` property.
+     *
+     * Postgres only, and only for a collection that declares a property of
+     * type `vector`. Rows come back ordered by distance, closest first, each
+     * carrying a `_distance`. Combines with `where` and `logical`, which are
+     * applied as filters before the ordering — so this is "the nearest rows
+     * that also match", not "the nearest rows, then filtered".
+     *
+     * Supplying the query vector is the caller's job: rebase stores and
+     * searches embeddings, it does not compute them.
+     */
+    vectorSearch?: VectorSearchParams;
+
+    /**
+     * Ask each returned row to explain itself: which declared search fields
+     * matched, with a highlighted snippet from each. Populates `_matches`.
+     *
+     * Off by default because it is not free — one `ts_headline` per declared
+     * field per returned row, and `ts_headline` re-parses the document rather
+     * than reading the index. Fine for a page of results, not for an export.
+     *
+     * Ignored unless the collection declares a `search` block and the query
+     * carries a `searchString`; there is nothing to explain otherwise.
+     */
+    searchExplain?: boolean;
 }
 
 /**
@@ -116,35 +235,50 @@ export interface FindResponse<M extends Record<string, unknown> = Record<string,
 
 
 /**
- * Fluent query builder for the **admin admin** — resolves to `FindResponse<M>`
+ * Fluent query builder for the **admin panel** — resolves to `FindResponse<M>`
  * (Snapshot-wrapped rows).
  *
  * @internal App developers should use {@link SDKQueryBuilderInterface}
  * (flat rows, returned by `client.data.*` / `context.data.*`). This
- * Snapshot-flavored variant backs the admin admin internals only.
+ * Snapshot-flavored variant backs the admin panel internals only.
  *
  * @group Data
  */
 export interface QueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>> {
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
-    orderBy(column: keyof M & string, direction?: "asc" | "desc"): this;
+    orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): this;
     limit(count: number): this;
     offset(count: number): this;
-    search(searchString: string): this;
+    search(searchString: string, options?: { explain?: boolean }): this;
+
+    /**
+     * Order rows by nearest-neighbour distance to `vector`, closest first.
+     *
+     * Postgres only, over a property declared as `type: "vector"`. Each row
+     * comes back with a `_distance`. Any `where` on the same query filters
+     * before the ordering; distance decides the order.
+     *
+     * The query embedding is the caller's to produce.
+     */
+    vectorSearch(
+        property: string,
+        vector: number[],
+        options?: { distance?: "cosine" | "l2" | "inner_product"; threshold?: number }
+    ): this;
     include(...relations: string[]): this;
     find(): Promise<FindResponse<M>>;
     listen(onUpdate: (data: FindResponse<M>) => void, onError?: (error: Error) => void): () => void;
 }
 
 /**
- * A single collection's CRUD accessor for the **admin admin** — every method
+ * A single collection's CRUD accessor for the **admin panel** — every method
  * resolves to `Snapshot`-wrapped rows (`FindResponse<M>` / `Snapshot<M>`).
  *
  * @internal App developers do **not** use this. The public, symmetric surface
  * is {@link SDKCollectionClient} (flat rows), exposed as `client.data.products`
  * in the SDK and `context.data.products` in framework callbacks. This
- * Snapshot-flavored accessor backs the admin admin view-model only.
+ * Snapshot-flavored accessor backs the admin panel view-model only.
  *
  * @group Data
  */
@@ -181,6 +315,20 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      */
     update(id: string | number, data: Partial<EntityValues<M>>): Promise<Entity<M>>;
 
+    /**
+     * Update many records in a single transaction.
+     *
+     * See {@link SDKCollectionClient.updateMany}. Optional, as `createMany` is.
+     */
+    updateMany?(updates: { id: string | number; data: Partial<EntityValues<M>> }[]): Promise<Entity<M>[]>;
+
+    /**
+     * Delete many records in a single transaction.
+     *
+     * See {@link SDKCollectionClient.deleteMany}. Optional, as `createMany` is.
+     */
+    deleteMany?(ids: (string | number)[]): Promise<void>;
+
     /**
      * Delete a record by ID.
      */
@@ -200,16 +348,37 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
 
     /**
      * Count the number of records matching the given filter.
+     *
+     * Optional on this contract because a data source need not support it, and
+     * required on `CollectionClient` — the HTTP implementation always has it.
+     * So `client.data.posts.count()` compiles in the browser while the same
+     * call through a `context.data` accessor needs `count?.()`, which is the
+     * one place the two halves of this API are not interchangeable.
      */
     count?(params?: FindParams<M>): Promise<number>;
 
     // Fluent Query Builder
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): QueryBuilderInterface<M>;
+    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, direction?: "asc" | "desc"): QueryBuilderInterface<M>;
+    orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): QueryBuilderInterface<M>;
     limit(count: number): QueryBuilderInterface<M>;
     offset(count: number): QueryBuilderInterface<M>;
-    search(searchString: string): QueryBuilderInterface<M>;
+    search(searchString: string, options?: { explain?: boolean }): QueryBuilderInterface<M>;
+
+    /**
+     * Order rows by nearest-neighbour distance to `vector`, closest first.
+     *
+     * Postgres only, over a property declared as `type: "vector"`. Each row
+     * comes back with a `_distance`. Any `where` on the same query filters
+     * before the ordering; distance decides the order.
+     *
+     * The query embedding is the caller's to produce.
+     */
+    vectorSearch(
+        property: string,
+        vector: number[],
+        options?: { distance?: "cosine" | "l2" | "inner_product"; threshold?: number }
+    ): QueryBuilderInterface<M>;
     include(...relations: string[]): QueryBuilderInterface<M>;
 }
 
@@ -240,12 +409,55 @@ export interface PaginationMeta {
  * @group Data
  */
 export interface FindResult<M extends Record<string, unknown> = Record<string, unknown>> {
-    /** Array of flat rows matching the query */
-    data: M[];
+    /**
+     * Flat rows matching the query, each carrying whatever the query computed
+     * for it — see {@link QueryComputedFields}.
+     */
+    data: (M & QueryComputedFields)[];
     /** Pagination metadata */
     meta: PaginationMeta;
 }
 
+/**
+ * Values a query attaches to a row that are not columns of it.
+ *
+ * Both are absent unless the query asked for the thing that produces them, so
+ * both are optional — and reading one on a query that did not ask returns
+ * `undefined` rather than a wrong number.
+ *
+ * They live here rather than on the row type because a generated row type
+ * describes a *table*, and neither of these is in one. Without this, a caller
+ * who sorted by relevance could not then read the relevance.
+ *
+ * A `type` alias, deliberately, not an `interface`. TypeScript grants an
+ * implicit index signature to a type alias and withholds it from an interface,
+ * so `Row & QueryComputedFields` stops being assignable to
+ * `Record<string, unknown>` the moment this becomes an interface. Seven casts
+ * in one downstream app broke on exactly that.
+ *
+ * @group Data
+ */
+export type QueryComputedFields = {
+    /**
+     * Relevance, when the collection declares a {@link SearchConfig} and the
+     * query carried a search string. Higher is better; the scale is not
+     * comparable between two different search strings.
+     */
+    _score?: number;
+    /**
+     * Which declared fields matched, and the text around each hit. Present only
+     * when the query asked for it — `.search(term, { explain: true })` — because
+     * it costs a `ts_headline` per field per row.
+     */
+    _matches?: SearchMatch[];
+    /**
+     * Distance to the query vector, when the query used
+     * {@link FindParams.vectorSearch}. Lower is closer, and the rows are
+     * already ordered by it.
+     */
+    _distance?: number;
+};
+
 /**
  * Which column an iteration seeks on, for keyset ("seek") pagination.
  *
@@ -338,12 +550,27 @@ export type FindAllParams<M extends Record<string, unknown> = Record<string, unk
  * @group Data
  */
 export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>> {
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
-    orderBy(column: keyof M & string, direction?: "asc" | "desc"): this;
+    orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): this;
     limit(count: number): this;
     offset(count: number): this;
-    search(searchString: string): this;
+    search(searchString: string, options?: { explain?: boolean }): this;
+
+    /**
+     * Order rows by nearest-neighbour distance to `vector`, closest first.
+     *
+     * Postgres only, over a property declared as `type: "vector"`. Each row
+     * comes back with a `_distance`. Any `where` on the same query filters
+     * before the ordering; distance decides the order.
+     *
+     * The query embedding is the caller's to produce.
+     */
+    vectorSearch(
+        property: string,
+        vector: number[],
+        options?: { distance?: "cosine" | "l2" | "inner_product"; threshold?: number }
+    ): this;
     include(...relations: string[]): this;
     find(): Promise<FindResult<M>>;
     count(): Promise<number>;
@@ -389,9 +616,20 @@ export interface WriteOptions {
      * it performs it again. On a table with a server-assigned id that is a
      * duplicate row, because the id the client chose was never used.
      *
+     * A key names **one** request, not a job. It records the method, the path
+     * and the body it was claimed for, so re-sending that exact request replays
+     * its answer, while the same key on a different one is refused with
+     * `IDEMPOTENCY_KEY_REUSED` (422) rather than silently answered with the
+     * first request's result. Pass a fresh key — a uuid — per call; a reusable
+     * business id shared by the create and the delete of one import means the
+     * second of them never runs.
+     *
      * Set by the offline queue on every replay. Honoured for 24 hours and scoped
-     * to the authenticated user; a server that cannot store keys ignores it
-     * rather than refusing the write.
+     * to the authenticated user — an unauthenticated caller has no principal to
+     * scope it to, so the key is ignored there. A retry sent while the first
+     * attempt is still being answered gets `IDEMPOTENCY_KEY_IN_PROGRESS` (409)
+     * and should be sent again. A server that cannot store keys ignores the
+     * header rather than refusing the write.
      */
     idempotencyKey?: string;
 }
@@ -501,6 +739,12 @@ export interface SDKCollectionClient<
      * Batches are capped server-side (1000 rows by default) because one batch
      * holds its locks for the whole transaction — chunk larger jobs.
      *
+     * Pass {@link WriteOptions.idempotencyKey} on anything that may be retried.
+     * A client that never sees the response cannot know whether the batch
+     * committed, and without a key the server cannot tell the retry from a
+     * second genuine import — so it performs it again, duplicating every row in
+     * the batch rather than just one.
+     *
      * @returns The written rows, in the order given.
      *
      * @example
@@ -510,7 +754,7 @@ export interface SDKCollectionClient<
      * }
      * ```
      */
-    createMany(data: I[], options?: { upsert?: boolean }): Promise<M[]>;
+    createMany(data: I[], options?: { upsert?: boolean } & WriteOptions): Promise<M[]>;
 
     /**
      * Update an existing record by ID.
@@ -520,6 +764,46 @@ export interface SDKCollectionClient<
      */
     update(id: string | number, data: U): Promise<M>;
 
+    /**
+     * Update many records in a single request and a single transaction.
+     *
+     * The counterpart to {@link createMany}, and the reason it exists is the
+     * same: one call per row means one HTTP round trip and one transaction per
+     * row. Every record still runs the normal pipeline — callbacks, relations,
+     * row-level security — and the batch is all-or-nothing, so a rejected
+     * record leaves none of them written and the error names the offending
+     * index.
+     *
+     * Each entry is `{ id, data }` rather than a flat row carrying its own key.
+     * That is deliberate: on a table keyed on something other than `id` — a
+     * `sku`, a composite key — a flat row cannot say whether a column is the
+     * address or a value to write. Naming the address separately mirrors
+     * single-row `update(id, data)` exactly and leaves nothing to infer.
+     *
+     * An id that matches no row fails the batch with a 404 rather than being
+     * skipped, for the same reason `update()` does: silently updating four of
+     * five rows is worse than updating none.
+     *
+     * Batches share `createMany`'s server-side cap (1000 rows by default),
+     * because one batch holds its locks for the whole transaction.
+     *
+     * Pass {@link WriteOptions.idempotencyKey} on anything that may be retried.
+     * An update replayed in full is naturally idempotent, but one interleaved
+     * with another writer's is not — the key is what stops a lost ACK from
+     * re-applying a stale batch over newer data.
+     *
+     * @returns The updated rows, in the order given.
+     *
+     * @example
+     * ```ts
+     * await client.data.orders.updateMany([
+     *     { id: "o-1", data: { status: "shipped" } },
+     *     { id: "o-2", data: { status: "shipped" } }
+     * ]);
+     * ```
+     */
+    updateMany(updates: { id: string | number; data: U }[], options?: WriteOptions): Promise<M[]>;
+
     /**
      * Delete a record by ID.
      * @throws {RebaseApiError} with status 404 when the record does not exist.
@@ -527,13 +811,48 @@ export interface SDKCollectionClient<
     delete(id: string | number): Promise<void>;
 
     /**
-     * Subscribe to a collection for real-time updates.
+     * Delete many records in a single request and a single transaction.
+     *
+     * Takes ids, not a filter. A filter-shaped bulk delete is a different and
+     * far more dangerous operation — the failure mode is an omitted or
+     * mistyped condition emptying a table, and it cannot be reviewed at the
+     * call site the way an explicit list can. Read first, then pass the ids you
+     * meant.
+     *
+     * `beforeDelete` and `afterDelete` fire per row, exactly as they do for
+     * single deletes, and returning `false` from `beforeDelete` fails the batch
+     * rather than quietly dropping one row from it. All-or-nothing, so an id
+     * that matches no row 404s the whole call.
+     *
+     * Shares `createMany`'s row cap.
+     *
+     * @example
+     * ```ts
+     * const stale = await client.data.sessions.findAll({
+     *     where: { expires_at: ["<", cutoff] }
+     * });
+     * await client.data.sessions.deleteMany(stale.map(s => s.id as string));
+     * ```
      */
-    listen?(params: FindParams<M> | undefined, onUpdate: (response: FindResult<M>) => void, onError?: (error: Error) => void): () => void;
+    deleteMany(ids: (string | number)[], options?: WriteOptions): Promise<void>;
 
     /**
-     * Subscribe to a single record for real-time updates.
+     * The low-level realtime subscription: raw server pushes, nothing else.
+     *
+     * **Prefer `observe()`** on a client from `@rebasepro/client`, which wraps
+     * this one and is what a UI actually wants — it emits from the local
+     * database first when offline is enabled, re-emits on local writes and
+     * rollbacks, and de-duplicates emissions so a refresh that changes nothing
+     * does not call back. `listen` does none of that; it forwards what the
+     * socket sends.
+     *
+     * Optional because it is only present when realtime is enabled. `observe()`
+     * is not — it degrades to a single fetch — which is the other reason to
+     * reach for it instead.
      */
+    listen?(params: FindParams<M> | undefined, onUpdate: (response: FindResult<M>) => void, onError?: (error: Error) => void): () => void;
+
+    /** {@link listen} for a single row. Prefer `observeById()`. */
     listenById?(id: string | number, onUpdate: (row: M | undefined) => void, onError?: (error: Error) => void): () => void;
 
     /**
@@ -542,17 +861,27 @@ export interface SDKCollectionClient<
     count?(params?: FindParams<M>): Promise<number>;
 
     // Fluent Query Builder
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): SDKQueryBuilderInterface<M>;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): SDKQueryBuilderInterface<M>;
     where(logicalCondition: LogicalCondition): SDKQueryBuilderInterface<M>;
-    orderBy(column: keyof M & string, direction?: "asc" | "desc"): SDKQueryBuilderInterface<M>;
+    orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): SDKQueryBuilderInterface<M>;
     limit(count: number): SDKQueryBuilderInterface<M>;
     offset(count: number): SDKQueryBuilderInterface<M>;
-    search(searchString: string): SDKQueryBuilderInterface<M>;
+    search(searchString: string, options?: { explain?: boolean }): SDKQueryBuilderInterface<M>;
+    /**
+     * Order rows by nearest-neighbour distance to `vector`, closest first.
+     * Postgres only, over a `type: "vector"` property. See
+     * {@link SDKQueryBuilderInterface.vectorSearch}.
+     */
+    vectorSearch(
+        property: string,
+        vector: number[],
+        options?: { distance?: "cosine" | "l2" | "inner_product"; threshold?: number }
+    ): SDKQueryBuilderInterface<M>;
     include(...relations: string[]): SDKQueryBuilderInterface<M>;
 }
 
 /**
- * The unified data access object for the **admin admin** (Entity-shaped).
+ * The unified data access object for the **admin panel** (Entity-shaped).
  *
  * Access collections as dynamic properties: `data.products.find(...)`. Each
  * accessor returns `Entity`-wrapped records (`{ id, path, values }`) — the
@@ -561,7 +890,7 @@ export interface SDKCollectionClient<
  *
  * @internal App developers do **not** use this — they use
  * {@link RebaseSdkData} (flat rows), which is what the SDK client and backend
- * `context.data` expose. This Entity-shaped map backs the admin admin only.
+ * `context.data` expose. This Entity-shaped map backs the admin panel only.
  *
  * @group Data
  */
@@ -584,10 +913,15 @@ export type RebaseData<DB = unknown> = {
              * Dynamic collection accessor.
              * Access any collection by its slug as a property.
              *
+             * The index signature is `CollectionAccessor` alone, for the reason
+             * spelled out on {@link RebaseSdkData}: unioning in the `collection`
+             * method's own signature is unnecessary across an intersection, and it
+             * costs `data.products.find()` — the access this `@example` documents.
+             *
              * @example
              * data.products.find({ where: { status: ["==", "published"] } })
              */
-            [collectionSlug: string]: CollectionAccessor | ((slug: string) => CollectionAccessor);
+            [collectionSlug: string]: CollectionAccessor;
         }
 );
 
@@ -639,6 +973,26 @@ export type InsertOf<T> = T extends { Insert: infer I extends Record<string, unk
  */
 export type UpdateOf<T> = T extends { Update: infer U extends Record<string, unknown> } ? U : Partial<RowOf<T>>;
 
+/**
+ * Note on the untyped branch below: its index signature is
+ * `SDKCollectionClient`, NOT `SDKCollectionClient | ((slug: string) => …)`.
+ *
+ * The union looks like it is needed so `collection` — a method on this same
+ * object — satisfies the index signature. It is not, because `collection` is
+ * declared in a *separate* member of the intersection, and TypeScript only
+ * requires named properties to be assignable to an index signature declared
+ * alongside them. Including the function arm cost the documented accessor:
+ *
+ *     rebase.dataAsAdmin.projects.find()
+ *     //                          ^ Property 'find' does not exist on type
+ *     //                            'SDKCollectionClient | ((slug: string) => …)'
+ *
+ * Every project without a generated `Database` type lands on this branch, so
+ * property-style access — the form used by the `@example` below, by the
+ * scaffolded function template, and by the 0.13 migration note — did not
+ * compile for any of them. Do not restore the arm; use `collection(slug)` if a
+ * caller genuinely needs the by-slug function.
+ */
 export type RebaseSdkData<DB = unknown> = {
     /**
      * Get a flat collection accessor by slug.
@@ -659,6 +1013,6 @@ export type RebaseSdkData<DB = unknown> = {
              * @example
              * data.products.find({ where: { status: ["==", "published"] } })
              */
-            [collectionSlug: string]: SDKCollectionClient | ((slug: string) => SDKCollectionClient);
+            [collectionSlug: string]: SDKCollectionClient;
         }
 );