@rebasepro/types 0.23.0 → 0.24.0

package/dist/controllers/client.d.ts

@@ -3,9 +3,10 @@ import type { ResourceRef } from "../types/resources.js";
 import type { RebaseSdkData } from "./data.js";
 import type { EmailService } from "./email.js";
 import type { StorageSource } from "./storage.js";
-import type { CronJobStatus, CronJobLogEntry } from "../types/cron.js";
-import type { BackupInfo, BackupDestinationKind } from "../types/backup.js";
-import type { ApiKeysAPI } from "../types/api_keys.js";
+import type { CronJobStatus, CronJobLogEntry, CronJobListing } from "../types/cron.js";
+import type { BackupListing } from "../types/backup.js";
+import type { ApiKeysAPI, PersonalKeysAPI } from "../types/api_keys.js";
+import type { RoleSummary } from "../types/scopes.js";
 import type { StorageSourceDefinition } from "../types/storage_source.js";
 /**
  * Event type for authentication state changes
@@ -19,6 +20,10 @@ export type AuthChangeEvent = "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | "
  */
 export interface RebaseSession {
     accessToken: string;
+    /**
+     * `""` under `authFlowMode: "cookie"`: the refresh token is in an HttpOnly
+     * cookie that no script can read, so the session does not hold it.
+     */
     refreshToken: string;
     expiresAt: number;
     user: User;
@@ -134,6 +139,11 @@ export interface AdminUser {
      */
     providerId: string;
     roles: string[];
+    /**
+     * Switched off by an administrator (`PUT /admin/users/:uid { disabled }`):
+     * it signs in nowhere and the tokens it holds are refused.
+     */
+    disabled?: boolean;
     metadata?: Record<string, any>;
     createdAt: string;
     updatedAt: string;
@@ -191,11 +201,9 @@ export interface AdminAPI {
         invitationSent?: boolean;
         emailDeliveryFailed?: boolean;
     }>;
+    /** The built-in `admin` role and the app's declared roles, with the scopes each holds. */
     listRoles(): Promise<{
-        roles: Array<{
-            id: string;
-            name: string;
-        }>;
+        roles: RoleSummary[];
     }>;
     bootstrap(): Promise<{
         success: boolean;
@@ -211,9 +219,8 @@ export interface AdminAPI {
  * @group Cron
  */
 export interface CronAPI {
-    listJobs(): Promise<{
-        jobs: CronJobStatus[];
-    }>;
+    /** The registered jobs, and the cron files and jobs that did not become one. */
+    listJobs(): Promise<CronJobListing>;
     getJob(jobId: string): Promise<{
         job: CronJobStatus;
     }>;
@@ -235,12 +242,11 @@ export interface CronAPI {
  * @group Backups
  */
 export interface BackupsAPI {
-    /** List available backups at the configured destination, newest first. */
-    list(): Promise<{
-        backups: BackupInfo[];
-        destinationKind: BackupDestinationKind;
-        configured: boolean;
-    }>;
+    /**
+     * List available backups at the configured destination, newest first, and
+     * the scheduled backup job's last run.
+     */
+    list(): Promise<BackupListing>;
     /** Fetch a backup's bytes for download (authenticated). */
     download(key: string): Promise<Blob>;
 }
@@ -280,6 +286,25 @@ export interface FunctionsAPI {
 export type HistoryConfig = boolean | {
     retention?: number;
 };
+/**
+ * Where the realtime connection is.
+ *
+ * - `idle` — no socket, and none wanted yet (the connection is lazy), or the
+ *   last one was dropped by a sign-out.
+ * - `connecting` — dialling, with no outage in progress.
+ * - `connected` — the socket is open.
+ * - `reconnecting` — the socket dropped and the client is redialling. A blip,
+ *   so far: nothing has been reported.
+ * - `disconnected` — the outage has outlasted the blip budget (about 15 s).
+ *   Every live subscription and joined channel has been told
+ *   `CONNECTION_LOST` once, and the client keeps redialling — every 30 s at
+ *   most — for as long as any exists. When the socket is back each is
+ *   re-subscribed, and its next update carries what changed meanwhile.
+ * - `closed` — `client.close()`. Final.
+ *
+ * @group Realtime
+ */
+export type RealtimeConnectionState = "idle" | "connecting" | "connected" | "reconnecting" | "disconnected" | "closed";
 /**
  * Minimal WebSocket client contract exposed on {@link RebaseClient}.
  *
@@ -295,6 +320,10 @@ export interface RebaseWebSocket {
     setAuthTokenGetter(getter: () => Promise<string | null>): void;
     /** Listen for connection lifecycle events. */
     on(event: "connect" | "disconnect" | "reconnect" | "error", cb: (...args: unknown[]) => void): () => void;
+    /** Where the connection is. See {@link RealtimeConnectionState}. */
+    readonly state: RealtimeConnectionState;
+    /** Called on every change of {@link state}. Returns the unsubscribe. */
+    onStateChange(listener: (state: RealtimeConnectionState) => void): () => void;
 }
 /**
  * The single, canonical Rebase client interface.
@@ -390,8 +419,10 @@ export interface RebaseClient<DB = unknown> {
     backups?: BackupsAPI;
     /** Custom backend functions API */
     functions?: FunctionsAPI;
-    /** Service API keys management API */
+    /** The project's service keys. Requires `keys:read` / `keys:write`. */
     apiKeys?: ApiKeysAPI;
+    /** The signed-in person's own API keys, when the backend enables `auth.personalKeys`. */
+    personalKeys?: PersonalKeysAPI;
     /** Base HTTP URL of the backend server */
     baseUrl?: string;
     /**

package/dist/controllers/collection_registry.d.ts

@@ -31,6 +31,23 @@ export type CollectionRegistryController<DB = Record<string, unknown>, EC extend
      * This is strictly for the Visual Editor to manipulate AST code without persisting runtime state.
      */
     getRawCollection: (slugOrPath: string) => EC | undefined;
+    /**
+     * The path a collection's rows are stored under, for the path the admin
+     * addresses it by. A Firestore or MongoDB collection may declare a `path`
+     * other than its slug — `slug: "fs_diagnosis", path: "diagnosis"` — and
+     * `fs_diagnosis/abc/locales` is then stored at `diagnosis/abc/locales`.
+     * This is what a reference to one of its records stores. Unchanged for a
+     * collection stored under its slug.
+     */
+    resolveDataPath: (path: string) => string;
+    /**
+     * The path the admin addresses a collection by, for a path its rows are
+     * stored under: the inverse of {@link resolveDataPath}, for a reference
+     * read back. `diagnosis` may be both where a Firestore collection is stored
+     * and the slug of a Postgres one; `preferredDriver` — the reference's
+     * `driver`, or the data source of the record it was read from — decides.
+     */
+    resolveCollectionPath: (path: string, preferredDriver?: string) => string;
     /**
      * Retrieve all the related parent references for a given path
      * @param path

package/dist/controllers/data.d.ts

@@ -143,6 +143,47 @@ export interface IncludeOptions {
  * @group Data
  */
 export type IncludeSpec = string[] | Record<string, true | IncludeOptions>;
+/**
+ * An include checked against one generated collection's relations: `R` is its
+ * `Relations` map (relation name → the accessor it reaches) and `DB` the
+ * generated `Database`, so a nested `include` is checked against the *target's*
+ * relations in turn.
+ *
+ * A name, a dotted path starting with one, or `"*"`; or the tree, keyed by
+ * relation name. A name that is not a relation is a 400 `UNKNOWN_RELATION`
+ * from the server, and a compile error here.
+ *
+ * @group Data
+ */
+export type IncludeSpecFor<DB, R> = readonly (Extract<keyof R, string> | "*" | `${Extract<keyof R, string>}.${string}`)[] | {
+    [K in Extract<keyof R, string>]?: true | IncludeOptionsFor<DB, R[K]>;
+};
+/**
+ * {@link IncludeOptions} for a relation that reaches the generated collection
+ * `T`: its nested `include` is checked against `T`'s relations.
+ *
+ * @group Data
+ */
+export interface IncludeOptionsFor<DB, T> extends Omit<IncludeOptions, "include"> {
+    include?: T extends keyof DB ? IncludeOf<DB[T], DB> : IncludeSpec;
+}
+/**
+ * The include a generated `Database` entry takes — {@link IncludeSpecFor} over
+ * its `Relations` — or the unchecked {@link IncludeSpec} for anything that does
+ * not declare its relations (a hand-written row type, an older generated file).
+ *
+ * @group Data
+ */
+export type IncludeOf<Entry, DB> = Entry extends {
+    Relations: infer R;
+} ? IncludeSpecFor<DB, R> : IncludeSpec;
+/**
+ * One argument of the fluent `.include(...)`: an element of the include list, a
+ * whole list, or the tree.
+ *
+ * @group Data
+ */
+export type IncludeArgOf<Inc> = Inc extends readonly (infer E)[] ? E | Inc : Inc;
 /**
  * Hops an {@link IncludeSpec} may nest. `comments.author` is two.
  *
@@ -178,7 +219,7 @@ export declare const MAX_INCLUDE_DEPTH = 3;
  *
  * @group Data
  */
-export interface FindParams<M extends Record<string, unknown> = Record<string, unknown>> {
+export interface FindParams<M extends Record<string, unknown> = Record<string, unknown>, Inc = IncludeSpec> {
     /**
      * Maximum number of items to return.
      *
@@ -236,11 +277,14 @@ export interface FindParams<M extends Record<string, unknown> = Record<string, u
      * 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`.
+     * collection's actual relation keys, recursively — see
+     * {@link IncludeSpecFor}. The row a read returns still types each relation
+     * as optional; the generated `RowWith<A, I>` names the row with the
+     * included ones required.
      *
      * An unknown name is a 400 `UNKNOWN_RELATION`. It used to be ignored.
      */
-    include?: IncludeSpec;
+    include?: Inc;
     /**
      * Columns to return, instead of all of them.
      *
@@ -463,7 +507,7 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      * absent implementation in a stub that says so rather than returning a
      * number nothing counted.
      */
-    aggregate?(params: AggregateParams<M>): Promise<AggregateRow[]>;
+    aggregate?(params: AggregateParams<M>): Promise<AggregateResult>;
     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>;
@@ -605,14 +649,15 @@ 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.
+ * `limit` and `offset` page through the **groups**, as they page a listing's
+ * rows, because grouping by a high-cardinality column is a whole table's worth
+ * of rows in one response. Over HTTP a grouped aggregate with no `limit` gets
+ * the listing default (50 groups) — read {@link AggregateResult.meta} to know
+ * when there were more. Without `groupBy` there is one row: `limit` does nothing
+ * there and `offset` is refused.
  *
- * `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.
+ * `include`, `after` and the rest are absent on purpose: an aggregate has no
+ * relations to load and no row to continue after.
  *
  * @group Data
  */
@@ -627,8 +672,36 @@ export interface AggregateParams<M extends Record<string, unknown> = Record<stri
     logical?: LogicalCondition;
     /** Text search, AND-ed with the filters. */
     searchString?: string;
-    /** Most groups to return. Ignored without `groupBy`. */
+    /** Most groups to return. Grouped aggregates only. */
     limit?: number;
+    /** Groups to skip, to page past `limit`. Grouped aggregates only. */
+    offset?: number;
+}
+/**
+ * Where a grouped aggregate's page of groups sits: the `limit` it was cut at,
+ * the `offset` it started from, and whether more groups follow.
+ *
+ * @group Data
+ */
+export interface AggregateMeta {
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+}
+/**
+ * What {@link SDKCollectionClient.aggregate} resolves to: the rows, as an
+ * array, carrying the page they are as `meta`.
+ *
+ * `meta` is present on a grouped aggregate that was cut at a `limit` — which,
+ * over HTTP, is every grouped one, since the route applies the listing default
+ * when none is given. `hasMore: true` means the groups did not all fit: page on
+ * with `offset`, or raise `limit`. It is a non-enumerable property, so a spread,
+ * `JSON.stringify` or `Object.keys` of the result sees only the rows.
+ *
+ * @group Data
+ */
+export interface AggregateResult extends Array<AggregateRow> {
+    readonly meta?: AggregateMeta;
 }
 /**
  * Which column an iteration seeks on, for keyset ("seek") pagination.
@@ -693,7 +766,7 @@ export interface PageWalkOptions<M extends Record<string, unknown> = Record<stri
  *
  * @group Data
  */
-export type IterateParams<M extends Record<string, unknown> = Record<string, unknown>> = Omit<FindParams<M>, "limit" | "offset" | "page"> & PageWalkOptions<M>;
+export type IterateParams<M extends Record<string, unknown> = Record<string, unknown>, Inc = IncludeSpec> = Omit<FindParams<M, Inc>, "limit" | "offset" | "page"> & PageWalkOptions<M>;
 /**
  * Parameters accepted by {@link SDKCollectionClient.findAll}: the iteration
  * parameters plus the ceiling that keeps a whole collection from being pulled
@@ -701,7 +774,7 @@ export type IterateParams<M extends Record<string, unknown> = Record<string, unk
  *
  * @group Data
  */
-export type FindAllParams<M extends Record<string, unknown> = Record<string, unknown>> = IterateParams<M> & {
+export type FindAllParams<M extends Record<string, unknown> = Record<string, unknown>, Inc = IncludeSpec> = IterateParams<M, Inc> & {
     /**
      * Most rows to materialise. Defaults to 10 000. Exceeding it **throws**
      * — a truncated array returned as if it were the whole answer is the
@@ -716,7 +789,7 @@ export type FindAllParams<M extends Record<string, unknown> = Record<string, unk
  *
  * @group Data
  */
-export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>> {
+export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>, Inc = IncludeSpec> {
     where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
     /**
      * Filter on a relation path (`author.name`) or a JSON path
@@ -761,7 +834,7 @@ export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Re
      * Load relations — names, dotted paths (`"comments.author"`), or the
      * parametrised tree. Repeated calls merge rather than replace.
      */
-    include(...relations: (string | IncludeSpec)[]): this;
+    include(...relations: IncludeArgOf<Inc>[]): 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.
@@ -777,9 +850,10 @@ export interface SDKQueryBuilderInterface<M extends Record<string, unknown> = Re
      *
      * 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.
+     * ignored, exactly as they are on the REST route. Page the groups with the
+     * `limit`/`offset` passed here.
      */
-    aggregate(params: Omit<AggregateParams<M>, "where" | "logical" | "searchString">): Promise<AggregateRow[]>;
+    aggregate(params: Omit<AggregateParams<M>, "where" | "logical" | "searchString">): Promise<AggregateResult>;
     /**
      * Page through everything this query matches, one row at a time.
      *
@@ -944,22 +1018,40 @@ export interface BatchRef {
     /** `<ref name>.<field>`, e.g. `order.id`. */
     $ref: string;
 }
-/** One entry of a batch request. @group Data */
+/**
+ * A row's values in a batch: the collection's own columns, each of which may
+ * instead be a {@link BatchRef} to a value an earlier operation produces.
+ *
+ * Homomorphic over the row type, so a column the row type requires is required
+ * here too — a create in a batch is the same insert `create()` is. There used
+ * to be an `& Record<string, unknown>` on the end, which let a misspelt column
+ * compile and come back as a 400 `VALIDATION_UNKNOWN_FIELDS`.
+ */
+type BatchValues<T> = {
+    [F in keyof T]: T[F] | BatchRef;
+};
+/**
+ * One entry of a batch request.
+ *
+ * `collection` is the collection's **accessor** on a typed client — the name
+ * `client.data.<accessor>` takes, and the key of the generated `Database`
+ * (`orderItems`). The client resolves it to the slug the route knows
+ * (`order_items`) through its `collections` dictionary; a slug that is not an
+ * accessor is sent as written.
+ *
+ * @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>;
+        values: BatchValues<InsertOf<DB[K]>>;
         /** 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>;
+        values: BatchValues<InsertOf<DB[K]>>;
         /** See {@link UpsertOptions.onConflict}. Defaults to the primary key. */
         onConflict?: readonly string[];
         ref?: string;
@@ -969,7 +1061,7 @@ export type BatchOperation<DB = Record<string, unknown>> = {
         id: string | number | BatchRef;
         values: {
             [F in keyof UpdateOf<DB[K]>]?: UpdateOf<DB[K]>[F] | FieldOperation | BatchRef;
-        } & Record<string, unknown>;
+        };
         ref?: string;
     } | {
         op: "delete";
@@ -1021,6 +1113,10 @@ export interface WriteOptions {
      * 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.
+     *
+     * The in-process accessor (`context.data`, `rebase.data`) has no store to
+     * keep keys in, and refuses one with `UNSUPPORTED_OPTION` rather than
+     * writing as though it had been checked.
      */
     idempotencyKey?: string;
     /**
@@ -1035,7 +1131,9 @@ export interface WriteOptions {
      *
      * 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.
+     * use a row the server never sent — and `create`, `update` and `upsert`
+     * are typed `M | undefined` for a literal `returning: false`, so reading a
+     * field off the result is a compile error rather than a `TypeError`.
      */
     returning?: boolean;
     /**
@@ -1051,11 +1149,15 @@ export interface WriteOptions {
      *
      * `"*"` asserts only that the row exists.
      *
-     * Honoured on `update` and `delete`.
+     * Honoured on `update` and `delete` over HTTP. The in-process accessor
+     * (`context.data`, `rebase.data`) cannot check a precondition yet, and
+     * refuses one with `UNSUPPORTED_OPTION` rather than writing unconditionally.
      */
     ifMatch?: string;
 }
-export interface SDKCollectionClient<M extends Record<string, unknown> = Record<string, unknown>, I = Partial<M>, U = Partial<M>> {
+export interface SDKCollectionClient<M extends Record<string, unknown> = Record<string, unknown>, I = Partial<M>, U = Partial<M>, 
+/** The include this collection takes; {@link IncludeOf} for a generated `Database`. */
+Inc = IncludeSpec> {
     /**
      * Find multiple records with optional filtering, pagination, and sorting.
      *
@@ -1079,7 +1181,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * it is where the pagination metadata lives, and it is present exactly when
      * there is some.
      */
-    find(params?: FindParams<M>): Promise<FindResult<M>>;
+    find(params?: FindParams<M, Inc>): Promise<FindResult<M>>;
     /**
      * Walk every record matching a query, one row at a time, fetching pages as
      * the consumer consumes them.
@@ -1117,7 +1219,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      *     await handle(job);
      * }
      */
-    iterate(params?: IterateParams<M>): AsyncIterableIterator<M>;
+    iterate(params?: IterateParams<M, Inc>): AsyncIterableIterator<M>;
     /**
      * {@link iterate}, collected into an array.
      *
@@ -1138,7 +1240,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      *     cursor: "id"
      * });
      */
-    findAll(params?: FindAllParams<M>): Promise<M[]>;
+    findAll(params?: FindAllParams<M, Inc>): Promise<M[]>;
     /**
      * Find a single record by its ID.
      */
@@ -1183,8 +1285,11 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      *   on anything else (a `sku`, a composite key), there is no `id` column to
      *   receive it — put the key in `data` instead, where it belongs among the
      *   columns.
-     * @returns The created row
+     * @returns The created row — or nothing, with `returning: false`.
      */
+    create(data: I, id: string | number | undefined, options: WriteOptions & {
+        returning: false;
+    }): Promise<M | undefined>;
     create(data: I, id?: string | number, options?: WriteOptions): Promise<M>;
     /**
      * Write many records in a single request and a single transaction.
@@ -1236,6 +1341,9 @@ 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 | UpdateValues<U>, options: WriteOptions & {
+        returning: false;
+    }): Promise<M | undefined>;
     update(id: string | number, data: U | UpdateValues<U>, options?: WriteOptions): Promise<M>;
     /**
      * Insert the row, or replace the one already occupying its key.
@@ -1266,6 +1374,9 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * );
      * ```
      */
+    upsert(data: I, options: UpsertOptions & {
+        returning: false;
+    }): Promise<M | undefined>;
     upsert(data: I, options?: UpsertOptions): Promise<M>;
     /**
      * Update many records in a single request and a single transaction.
@@ -1367,7 +1478,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * `observe()` degrades to a single fetch instead of throwing, 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;
+    listen(params: FindParams<M, Inc> | 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;
     /**
@@ -1376,7 +1487,7 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * Always present; see {@link listen} for what a transport that cannot serve
      * it does instead.
      */
-    count(params?: FindParams<M>): Promise<number>;
+    count(params?: FindParams<M, Inc>): Promise<number>;
     /**
      * `count`/`sum`/`avg`/`min`/`max` over the matching rows, optionally
      * grouped — the SDK half of `GET /<collection>/aggregate`.
@@ -1401,17 +1512,17 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
      * 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>;
+    aggregate(params: AggregateParams<M>): Promise<AggregateResult>;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): SDKQueryBuilderInterface<M, Inc>;
     /** 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", nulls?: NullsPlacement): SDKQueryBuilderInterface<M>;
-    limit(count: number): SDKQueryBuilderInterface<M>;
-    offset(count: number): SDKQueryBuilderInterface<M>;
+    where(column: NonColumnFieldPath, operator: WhereFilterOp, value: unknown): SDKQueryBuilderInterface<M, Inc>;
+    where(logicalCondition: LogicalCondition): SDKQueryBuilderInterface<M, Inc>;
+    orderBy(column: FieldPath<M> | ComputedSortField | RelationAggregateSort, direction?: "asc" | "desc", nulls?: NullsPlacement): SDKQueryBuilderInterface<M, Inc>;
+    limit(count: number): SDKQueryBuilderInterface<M, Inc>;
+    offset(count: number): SDKQueryBuilderInterface<M, Inc>;
     search(searchString: string, options?: {
         explain?: boolean;
-    }): SDKQueryBuilderInterface<M>;
+    }): SDKQueryBuilderInterface<M, Inc>;
     /**
      * Order rows by nearest-neighbour distance to `vector`, closest first.
      * Postgres only, over a `type: "vector"` property. See
@@ -1420,14 +1531,14 @@ export interface SDKCollectionClient<M extends Record<string, unknown> = Record<
     vectorSearch(property: string, vector: number[], options?: {
         distance?: "cosine" | "l2" | "inner_product";
         threshold?: number;
-    }): SDKQueryBuilderInterface<M>;
-    include(...relations: (string | IncludeSpec)[]): SDKQueryBuilderInterface<M>;
+    }): SDKQueryBuilderInterface<M, Inc>;
+    include(...relations: IncludeArgOf<Inc>[]): SDKQueryBuilderInterface<M, Inc>;
     /** {@link SDKQueryBuilderInterface.fields} */
-    fields(...columns: (FieldPath<M> | string)[]): SDKQueryBuilderInterface<M>;
+    fields(...columns: (FieldPath<M> | string)[]): SDKQueryBuilderInterface<M, Inc>;
     /** {@link SDKQueryBuilderInterface.distinct} */
-    distinct(enabled?: boolean): SDKQueryBuilderInterface<M>;
+    distinct(enabled?: boolean): SDKQueryBuilderInterface<M, Inc>;
     /** {@link SDKQueryBuilderInterface.after} */
-    after(cursor: string): SDKQueryBuilderInterface<M>;
+    after(cursor: string): SDKQueryBuilderInterface<M, Inc>;
 }
 /**
  * The unified data access object for the **admin panel** (Entity-shaped).
@@ -1554,7 +1665,7 @@ export type RebaseSdkData<DB = unknown> = {
      */
     collection<M extends Record<string, unknown> = Record<string, unknown>>(slug: string): SDKCollectionClient<M>;
 } & (DB extends Record<string, unknown> ? {
-    [K in keyof DB]: SDKCollectionClient<RowOf<DB[K]>, InsertOf<DB[K]>, UpdateOf<DB[K]>>;
+    [K in keyof DB]: SDKCollectionClient<RowOf<DB[K]>, InsertOf<DB[K]>, UpdateOf<DB[K]>, IncludeOf<DB[K], DB>>;
 } : {
     /**
      * Dynamic flat collection accessor.
@@ -1565,3 +1676,4 @@ export type RebaseSdkData<DB = unknown> = {
      */
     [collectionSlug: string]: SDKCollectionClient;
 });
+export {};