@rebasepro/types 0.9.1-canary.fd3754b → 0.10.0

package/dist/types/auth_adapter.d.ts

@@ -86,7 +86,7 @@ export interface AuthAdapterCapabilities {
      */
     passwordReset: boolean;
     /**
-     * Whether the adapter exposes `POST /admin/users/:userId/reset-password`,
+     * Whether the adapter exposes `POST /admin/users/:uid/reset-password`,
      * letting an admin reset another user's password.
      *
      * Independent of `passwordReset`: the built-in adapter supports this even
@@ -180,8 +180,8 @@ export interface UserManagementAdapter {
     createUser(data: AuthCreateUserData): Promise<AuthUserData>;
     updateUser(id: string, data: Partial<AuthCreateUserData>): Promise<AuthUserData | null>;
     deleteUser(id: string): Promise<void>;
-    getUserRoles(userId: string): Promise<string[]>;
-    setUserRoles(userId: string, roleIds: string[]): Promise<void>;
+    getUserRoles(uid: string): Promise<string[]>;
+    setUserRoles(uid: string, roleIds: string[]): Promise<void>;
 }
 /**
  * Result of `AuthAdapter.prepareUserCreation()`.
@@ -201,6 +201,26 @@ export interface UserCreationPrepareResult {
     /** Whether an invitation was sent (only relevant when hookHandledEmail is true). */
     invitationSent: boolean;
 }
+/**
+ * What a create body for an auth collection may name beyond the collection's
+ * own declared fields — see `AuthAdapter.describeUserCreationContract()`.
+ *
+ * @group Auth
+ */
+export interface UserCreationWriteContract {
+    /**
+     * Whether to check the body for fields neither the collection nor
+     * {@link extraFields} declares. `false` skips the check entirely.
+     */
+    validate: boolean;
+    /**
+     * Credential and provider keys the adapter consumes itself, which the
+     * collection therefore does not declare as columns. `password` is the
+     * canonical one: `prepareUserCreation` hashes it into `passwordHash` and
+     * deletes it before the row is ever built.
+     */
+    extraFields: string[];
+}
 /**
  * Result of `AuthAdapter.finalizeUserCreation()`.
  *
@@ -255,7 +275,7 @@ export interface AuthResponsePayload {
  */
 export interface TransformAuthResponseContext {
     /** The authenticated user's ID. */
-    userId: string;
+    uid: string;
     /** The auth method that triggered this response. */
     method: "login" | "register" | "oauth" | "refresh" | "anonymous" | "magic-link" | "mfa";
     /** The raw HTTP request (for reading headers, IP, etc.). */
@@ -371,6 +391,30 @@ export interface AuthAdapter {
      * @returns Processed values ready for `driver.save()`, plus metadata for the post-save step.
      */
     prepareUserCreation?(values: Record<string, unknown>, collectionAuth?: unknown): Promise<UserCreationPrepareResult>;
+    /**
+     * Describe what a create body for this auth collection is allowed to name,
+     * so unknown-field validation can run on it.
+     *
+     * A signup body is not the collection's shape: it carries credential fields
+     * like `password` that the users table never declares as columns, and
+     * `prepareUserCreation` maps them onto real ones. Validating the raw body
+     * against the collection alone would reject every legitimate signup — which
+     * is why the check used to be skipped outright for auth collections. That
+     * skip was total, so an undeclared field was silently dropped and the write
+     * still returned 201, while the same typo on a normal collection was a 400.
+     *
+     * This narrows the exemption to the fields the adapter actually consumes.
+     *
+     * `validate: false` disables the check for this collection, and is the right
+     * answer when a custom `onCreateUser` hook is configured: the body is then
+     * the hook's contract, not the collection's, and this layer cannot know what
+     * the hook accepts.
+     *
+     * If not implemented, validation is skipped — the pre-existing behaviour.
+     *
+     * @param collectionAuth - The parsed `AuthCollectionConfig` from the collection (if `auth` is an object).
+     */
+    describeUserCreationContract?(collectionAuth?: unknown): UserCreationWriteContract;
     /**
      * Finalize a user creation after the entity has been persisted.
      *

package/dist/types/backend.d.ts

@@ -162,6 +162,40 @@ export interface SingleSubscriptionConfig {
     path: string;
     id: string | number;
 }
+/**
+ * Opt-in retention for one set of broadcast channels.
+ *
+ * Retention is configured on the server and nowhere else. A channel is created
+ * by whoever names it, so letting a client ask for its own history depth would
+ * let any visitor commit the backend to unbounded storage; and presence-only or
+ * notification-only channels — the overwhelming majority — must not pay for a
+ * feature they never use. With no rules configured nothing is written, no table
+ * is created, and broadcast behaves exactly as it did before history existed.
+ */
+export interface ChannelRetentionRule {
+    /**
+     * Channel name to match. Either exact (`"doc:42"`) or a trailing-`*` prefix
+     * (`"doc:*"`). Deliberately not a full glob or RegExp: this decides what
+     * gets written to disk, and a rule whose blast radius is not obvious at a
+     * glance is the wrong shape for that.
+     */
+    match: string;
+    /** Keep at most this many of the most recent messages per channel. */
+    limit?: number;
+    /**
+     * Keep messages for at most this long. Accepts a millisecond count or a
+     * short duration string (`"30s"`, `"15m"`, `"24h"`, `"7d"`).
+     */
+    ttl?: number | string;
+}
+/** Server-side realtime options. */
+export interface RealtimeChannelsConfig {
+    /**
+     * Retention rules, most specific first — the first match wins. Omitted or
+     * empty means no channel retains anything.
+     */
+    channels?: ChannelRetentionRule[];
+}
 /**
  * Abstract realtime provider interface.
  * Handles real-time subscriptions and notifications for entity changes.
@@ -258,9 +292,22 @@ export interface SQLAdmin {
      */
     fetchAvailableDatabases?(): Promise<string[]>;
     /**
-     * Fetch the available database roles.
+     * Fetch the available *native PostgreSQL* database roles (from `pg_roles`).
+     *
+     * These are connection-level roles — what the SQL editor can `SET ROLE` to,
+     * and what `SecurityRule.pgRoles` targets. They are NOT application roles;
+     * for those use {@link fetchApplicationRoles}.
      */
     fetchAvailableRoles?(): Promise<string[]>;
+    /**
+     * Fetch the *application-level* roles in use in this project.
+     *
+     * These are the strings stored on the users table's `roles` column and
+     * exposed to policies as `auth.roles()` — what `SecurityRule.roles`
+     * matches against. Distinct from {@link fetchAvailableRoles}; the two are
+     * not interchangeable.
+     */
+    fetchApplicationRoles?(): Promise<string[]>;
     /**
      * Fetch the current database name.
      */

package/dist/types/collections.d.ts

@@ -330,6 +330,17 @@ export interface BaseCollectionConfig<M extends Record<string, unknown> = Record
      * This prop has no effect if the history plugin is not enabled
      */
     history?: boolean;
+    /**
+     * Whether a write naming a field this collection does not declare is
+     * rejected with a 400. Defaults to `true`.
+     *
+     * Set to `false` to let unknown keys through to the database, which is what
+     * happened before this existed: a typo reached the INSERT and came back as
+     * a Postgres error about a column, or — where a column really does exist
+     * that the config never declared, populated by a trigger or a default —
+     * quietly worked. The second case is the reason for the escape hatch.
+     */
+    strictWrites?: boolean;
     /**
      * Should local changes be backed up in local storage, to prevent data loss on
      * accidental navigations.
@@ -898,9 +909,14 @@ export interface SecurityRuleBase {
      * **Shortcut.** Restrict this rule to users that have one of these
      * application-level roles.
      *
-     * **Important:** These are NOT native PostgreSQL database roles. They are
-     * application roles managed by Rebase, stored in the `rebase.user_roles`
-     * table, and injected into each transaction via `auth.roles()`.
+     * **Important:** These are NOT native PostgreSQL database roles — names
+     * like `public`, `anon` or `authenticated` belong to {@link pgRoles} and
+     * produce a condition no user can satisfy if used here. These are
+     * application roles managed by Rebase, stored as an inline `roles TEXT[]`
+     * column on the users table, and injected into each transaction as
+     * `app.user_roles` — which `auth.roles()` reads.
+     *
+     * There is no roles registry: a role exists once it is assigned to a user.
      *
      * Generates a safe array-overlap condition — the user passes if they hold
      * *any* of the listed roles:
@@ -929,10 +945,10 @@ export interface SecurityRuleBase {
      * every database connection). This is correct for most setups where
      * a single database role is used for all connections.
      *
-     * **Important:** These are NOT the same as the application-level `roles`
-     * (admin, editor, viewer, etc.) — those are enforced in the USING/WITH
-     * CHECK clauses via `auth.roles()`. This field controls the PostgreSQL
-     * `TO` clause in `CREATE POLICY ... TO role_name`.
+     * **Important:** These are NOT the same as the application-level
+     * {@link roles} (admin, editor, viewer, etc.) — those are enforced in the
+     * USING/WITH CHECK clauses via `auth.roles()`. This field controls the
+     * PostgreSQL `TO` clause in `CREATE POLICY ... TO role_name`.
      *
      * Use this if you have dedicated PostgreSQL roles (e.g. `app_read`,
      * `app_write`) and want policies to target specific ones.
@@ -1147,7 +1163,7 @@ export interface AuthCollectionConfig {
      * Default: generate reset token → send email (or generate + return temp password).
      * Override for custom reset flows.
      */
-    onResetPassword?: (userId: string, ctx: AuthCollectionContext) => Promise<AuthCollectionResetResult>;
+    onResetPassword?: (uid: string, ctx: AuthCollectionContext) => Promise<AuthCollectionResetResult>;
     /**
      * Control which auth-specific entity actions are auto-injected.
      *

package/dist/types/entity_callbacks.d.ts

@@ -74,7 +74,7 @@ export interface AfterReadProps<M extends Record<string, unknown> = Record<strin
      */
     path: string;
     /**
-     * Fetched row (flat — `{ id, ...columns }`)
+     * Fetched row (flat — the table's columns)
      */
     row: Record<string, unknown>;
     /**
@@ -149,7 +149,7 @@ export interface BeforeDeleteProps<M extends Record<string, unknown> = Record<st
      */
     id: string | number;
     /**
-     * Deleted row (flat — `{ id, ...columns }`)
+     * Deleted row (flat — the table's columns)
      */
     row: Record<string, unknown>;
     /**
@@ -175,7 +175,7 @@ export interface AfterDeleteProps<M extends Record<string, unknown> = Record<str
      */
     id: string | number;
     /**
-     * Deleted row (flat — `{ id, ...columns }`)
+     * Deleted row (flat — the table's columns)
      */
     row: Record<string, unknown>;
     /**

package/dist/types/policy.d.ts

@@ -17,7 +17,24 @@
  *
  * @group Models
  */
-export type PolicyExpression = TruePolicyExpression | FalsePolicyExpression | AndPolicyExpression | OrPolicyExpression | NotPolicyExpression | ComparePolicyExpression | RolesOverlapPolicyExpression | RolesContainPolicyExpression | AuthenticatedPolicyExpression | ExistsInPolicyExpression | RawPolicyExpression;
+export type PolicyExpression = TruePolicyExpression | FalsePolicyExpression | AndPolicyExpression | OrPolicyExpression | NotPolicyExpression | ComparePolicyExpression | RolesOverlapPolicyExpression | RolesContainPolicyExpression | AuthenticatedPolicyExpression | ServerContextPolicyExpression | ExistsInPolicyExpression | RawPolicyExpression;
+/**
+ * The id a request without a logged-in user reports as `auth.uid()`.
+ *
+ * A user-context request always sets `app.uid`: blank would read back as
+ * `NULL`, and `NULL` is how the trusted server context is recognised, so an
+ * anonymous visitor would be promoted to server privileges. The driver
+ * therefore substitutes this sentinel at the single chokepoint where the GUC
+ * is set.
+ *
+ * The consequence for policy authors is that **`auth.uid() IS NOT NULL` is a
+ * tautology on the user path** — it is true for anonymous visitors too. Use
+ * {@link policy.authenticated} (or `auth.uid() <> 'anonymous'`) to mean "signed
+ * in", and {@link policy.serverContext} to mean "the trusted server context".
+ *
+ * @group Models
+ */
+export declare const ANONYMOUS_USER_ID = "anonymous";
 /** Always allows. Compiles to `true`. @group Models */
 export interface TruePolicyExpression {
     kind: "true";
@@ -72,12 +89,40 @@ export interface RolesContainPolicyExpression {
     roles: readonly string[];
 }
 /**
- * True when there is an authenticated user (`auth.uid() IS NOT NULL`).
+ * True when a signed-in user is making the request. Compiles to
+ * `auth.uid() IS NOT NULL AND auth.uid() <> 'anonymous'`.
+ *
+ * Both halves are load-bearing. `IS NOT NULL` excludes the server context;
+ * the {@link ANONYMOUS_USER_ID} comparison excludes anonymous visitors, who
+ * *do* carry a non-null `auth.uid()`. Checking only `IS NOT NULL` grants to
+ * everyone — see {@link ANONYMOUS_USER_ID}.
+ *
+ * `policy.not(policy.authenticated())` therefore means "anonymous visitor or
+ * the server context". To single out the server context, use
+ * {@link ServerContextPolicyExpression}.
  * @group Models
  */
 export interface AuthenticatedPolicyExpression {
     kind: "authenticated";
 }
+/**
+ * True only in the trusted **server context** — the built-in flows that run
+ * without a user (signup, migrations, `dataAsAdmin`) set no user GUC, so
+ * `auth.uid()` is `NULL` for them and only for them. Compiles to
+ * `auth.uid() IS NULL`.
+ *
+ * This is what lets the owner connection satisfy a policy even under FORCE RLS.
+ * It is deliberately a primitive rather than `not(authenticated())`: the two
+ * meant the same thing while `authenticated` ignored {@link ANONYMOUS_USER_ID},
+ * and conflating them is what turns a server-only grant into an anonymous one.
+ *
+ * The JavaScript evaluator always returns `false` for this node — a client is
+ * never the server context.
+ * @group Models
+ */
+export interface ServerContextPolicyExpression {
+    kind: "serverContext";
+}
 /**
  * Membership / relational access: true when at least one row exists in another
  * collection (a join/membership table) matching `where`. This is what lets you
@@ -178,6 +223,7 @@ export declare const policy: {
     rolesOverlap: (roles: readonly string[]) => RolesOverlapPolicyExpression;
     rolesContain: (roles: readonly string[]) => RolesContainPolicyExpression;
     authenticated: () => AuthenticatedPolicyExpression;
+    serverContext: () => ServerContextPolicyExpression;
     existsIn: (args: {
         collection: string;
         where: PolicyExpression;

package/dist/types/properties.d.ts

@@ -175,6 +175,19 @@ export interface BaseProperty<CustomProps = unknown> {
      * Rules for validating this property
      */
     validation?: PropertyValidationSchema;
+    /**
+     * Never include this column in an API response.
+     *
+     * For secrets the server must store and read but no client should ever
+     * receive — password hashes, verification tokens. The value is still
+     * written and queryable server-side; it is stripped from every row the API
+     * serves, for every caller, including admins and service keys.
+     *
+     * This is a server-side guarantee, unlike `ui.hideFromCollection`, which
+     * only stops the admin panel from *rendering* a field and leaves it in the
+     * JSON payload.
+     */
+    excludeFromApi?: boolean;
     /**
      * 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

package/dist/types/websockets.d.ts

@@ -14,11 +14,42 @@ export interface WebSocketMessage {
     rows?: Record<string, unknown>[];
     row?: Record<string, unknown> | null;
     error?: string;
+    /**
+     * Channel name, on broadcast and presence frames.
+     *
+     * These are addressed by channel rather than by `requestId` or
+     * `subscriptionId`, so this is the only field that routes them.
+     */
+    channel?: string;
 }
+/**
+ * The key columns a collection's rows are addressed by.
+ *
+ * A row is exactly its columns and carries no address, so a subscriber that has
+ * to recognise one — to patch it, or to keep its reference across a refetch —
+ * derives the address from these. The SDK is usable with no collections
+ * declared at all, so the server is the only side that knows them.
+ *
+ * Undefined when the server cannot resolve them: a table with no primary key
+ * and no `id` column has no address, and rows of it cannot be recognised by
+ * anyone.
+ */
+export type WirePrimaryKeys = {
+    fieldName: string;
+    type: "string" | "number";
+    isUUID?: boolean;
+}[];
 export interface CollectionUpdateMessage extends WebSocketMessage {
     type: "collection_update";
     subscriptionId: string;
     rows: Record<string, unknown>[];
+    /**
+     * See {@link WirePrimaryKeys}. Sent with the rows themselves — and not only
+     * with a patch — because a CDC-originated change sends no patch at all: it
+     * invalidates and goes straight to a refetch, and the merge that preserves
+     * unchanged rows' references needs an address to match them by.
+     */
+    pks?: WirePrimaryKeys;
 }
 export interface SingleUpdateMessage extends WebSocketMessage {
     type: "single_update";
@@ -34,9 +65,55 @@ export interface SingleUpdateMessage extends WebSocketMessage {
 export interface CollectionPatchMessage extends WebSocketMessage {
     type: "collection_patch";
     subscriptionId: string;
+    /** The address of the row this patch refers to — derived, never read off it. */
     id: string;
     /** The updated row, or null if deleted */
     row: Record<string, unknown> | null;
+    /** See {@link WirePrimaryKeys}: how the subscriber finds {@link id} in its cache. */
+    pks?: WirePrimaryKeys;
+}
+/**
+ * One retained broadcast, as it travels on the wire.
+ *
+ * `seq` is per-channel, dense and monotonically increasing — it is the only
+ * thing a reconnecting client needs to say where it got to. See
+ * {@link ChannelHistoryMessage}.
+ */
+export interface ChannelHistoryEntry {
+    seq: number;
+    event: string;
+    payload: unknown;
+    /**
+     * The server-side client id of whoever sent it, for information only.
+     *
+     * Deliberately not used to filter a client's own messages out of a replay:
+     * a reconnect assigns a brand-new client id, so the very case replay exists
+     * for is the case where this would fail to match. Consumers that cannot
+     * tolerate re-applying their own operations must make them idempotent.
+     */
+    senderId?: string;
+    /** When the server accepted it, ISO-8601. */
+    at: string;
+}
+/**
+ * Server → client: the retained messages a client missed.
+ *
+ * `retained: false` means the channel has no retention rule configured, so
+ * there is no history to replay and there never will be — an explicit answer
+ * rather than an empty one, so a client can tell "nothing missed" apart from
+ * "this channel does not keep history".
+ */
+export interface ChannelHistoryMessage extends WebSocketMessage {
+    type: "channel_history";
+    channel: string;
+    messages: ChannelHistoryEntry[];
+    retained: boolean;
+    /**
+     * The highest seq the server holds for this channel, whether or not it was
+     * returned. Lets a client that capped its request with `limit` see that it
+     * is still behind, and decide to resync wholesale instead of paging.
+     */
+    latestSeq?: number;
 }
 /**
  * Column metadata returned by table introspection.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.9.1-canary.fd3754b",
+  "version": "0.10.0",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -13,12 +13,12 @@
     "url": "https://github.com/rebasepro/rebase.git",
     "directory": "packages/types"
   },
-  "main": "./dist/index.umd.js",
+  "main": "./dist/index.es.js",
   "module": "./dist/index.es.js",
   "types": "./dist/index.d.ts",
   "source": "src/index.ts",
   "engines": {
-    "node": ">=14"
+    "node": ">=20"
   },
   "keywords": [
     "rebase",
@@ -33,8 +33,7 @@
     ".": {
       "types": "./dist/index.d.ts",
       "development": "./dist/index.es.js",
-      "import": "./dist/index.es.js",
-      "require": "./dist/index.umd.js"
+      "import": "./dist/index.es.js"
     },
     "./package.json": "./package.json"
   },
@@ -92,7 +91,7 @@
   },
   "scripts": {
     "watch": "vite build --watch",
-    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json && node ../../scripts/assert-build-output.mjs",
     "test:lint": "eslint \"src/**\" --quiet",
     "test": "jest --passWithNoTests",
     "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f"

package/src/controllers/client.ts

@@ -139,11 +139,11 @@ export interface AdminAPI {
         orderBy?: string;
         orderDir?: "asc" | "desc";
     }): Promise<{ users: AdminUser[]; total: number; limit: number; offset: number }>;
-    getUser(userId: string): Promise<{ user: AdminUser }>;
+    getUser(uid: string): Promise<{ user: AdminUser }>;
     createUser(data: { email: string; displayName?: string; password?: string; roles?: string[]; metadata?: Record<string, any> }): Promise<{ user: AdminUser }>;
-    updateUser(userId: string, data: { email?: string; displayName?: string; password?: string; roles?: string[]; metadata?: Record<string, any> }): Promise<{ user: AdminUser }>;
-    deleteUser(userId: string): Promise<{ success: boolean }>;
-    resetPassword(userId: string, options?: { password?: string }): Promise<{ user: AdminUser; temporaryPassword?: string; invitationSent?: boolean; emailDeliveryFailed?: boolean }>;
+    updateUser(uid: string, data: { email?: string; displayName?: string; password?: string; roles?: string[]; metadata?: Record<string, any> }): Promise<{ user: AdminUser }>;
+    deleteUser(uid: string): Promise<{ success: boolean }>;
+    resetPassword(uid: string, options?: { password?: string }): Promise<{ user: AdminUser; temporaryPassword?: string; invitationSent?: boolean; emailDeliveryFailed?: boolean }>;
     listRoles(): Promise<{ roles: Array<{ id: string; name: string }> }>;
     bootstrap(): Promise<{ success: boolean; message: string; user: { uid: string; roles: string[] } }>;
 }

package/src/controllers/data.ts

@@ -161,6 +161,14 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      */
     create(data: Partial<EntityValues<M>>, id?: string | number): Promise<Entity<M>>;
 
+    /**
+     * Create many records in a single transaction.
+     *
+     * See {@link SDKCollectionClient.createMany}. Optional: not every driver can
+     * write in bulk, and callers should fall back to `create` per record.
+     */
+    createMany?(data: Partial<EntityValues<M>>[], options?: { upsert?: boolean }): Promise<Entity<M>[]>;
+
     /**
      * Update an existing record by ID.
      * @returns The updated entity
@@ -294,11 +302,43 @@ export interface SDKCollectionClient<
     /**
      * Create a new record.
      * @param data The record data to create (the collection's `Insert` shape).
-     * @param id Optional specific ID to use for the new record.
+     * @param id Optional specific id, sent as an `id` column. This is for tables
+     *   whose key *is* `id`: the value goes in as that column. For a table keyed
+     *   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
      */
     create(data: I, id?: string | number): Promise<M>;
 
+    /**
+     * Write many records in a single request and a single transaction.
+     *
+     * Built for imports and ETL, where 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: if any record is rejected, none of them land and the
+     * error names the offending index.
+     *
+     * A record carrying its primary key updates that row; one without inserts.
+     * With `{ upsert: true }` each record is written as INSERT ... ON CONFLICT
+     * DO UPDATE on the primary key instead, which is what makes a re-runnable
+     * import idempotent.
+     *
+     * Batches are capped server-side (1000 rows by default) because one batch
+     * holds its locks for the whole transaction — chunk larger jobs.
+     *
+     * @returns The written rows, in the order given.
+     *
+     * @example
+     * ```ts
+     * for (const chunk of chunks(rows, 1000)) {
+     *     await client.data.products.createMany(chunk, { upsert: true });
+     * }
+     * ```
+     */
+    createMany(data: I[], options?: { upsert?: boolean }): Promise<M[]>;
+
     /**
      * Update an existing record by ID.
      * @param data The fields to update (the collection's `Update` shape).
@@ -386,7 +426,7 @@ export type RebaseData<DB = unknown> = {
  * - The frontend SDK client (`client.data.products.find()`)
  * - Backend framework callbacks & scripts (`context.data.products.find()`)
  *
- * Every accessor returns flat rows (`{ id, ...columns }`) via
+ * Every accessor returns flat rows (the table's columns) via
  * {@link SDKCollectionClient} — access fields directly (`row.title`), never
  * `row.values.title`. The admin CMS uses {@link RebaseData} (Entity) instead.
  *

package/src/controllers/data_driver.ts

@@ -77,6 +77,31 @@ export interface SaveProps<M extends Record<string, unknown> = Record<string, un
     previousValues?: Partial<EntityValues<M>>;
     collection?: CollectionConfig<M>;
     status: EntityStatus;
+    /**
+     * Write the row with INSERT ... ON CONFLICT DO UPDATE on the primary key
+     * instead of choosing between insert and update up front.
+     *
+     * One statement, so it does not lose the race a read-then-write can, and it
+     * succeeds whether or not the row is already there — what a re-runnable
+     * import needs. Requires every primary key column to be present; without
+     * them there is no conflict target and the row is inserted normally.
+     */
+    upsert?: boolean;
+}
+
+/**
+ * @internal
+ */
+export interface SaveManyProps<M extends Record<string, unknown> = Record<string, unknown>> {
+    path: string;
+    /**
+     * The rows to write. A row carrying its primary key updates (or, with
+     * `upsert`, inserts-or-updates) that row; one without inserts.
+     */
+    rows: Partial<EntityValues<M>>[];
+    collection?: CollectionConfig<M>;
+    /** Apply every row as INSERT ... ON CONFLICT DO UPDATE. See {@link SaveProps.upsert}. */
+    upsert?: boolean;
 }
 
 /**
@@ -154,6 +179,20 @@ export interface DataDriver {
      */
     save<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>>;
 
+    /**
+     * Save many rows as one unit of work.
+     *
+     * Every row runs the same pipeline as {@link save} — callbacks, relations
+     * and row-level security all still apply — but they share a single
+     * transaction, so the batch either lands whole or not at all. That, and the
+     * single round trip, is what makes importing tens of thousands of rows
+     * viable without dropping to raw SQL.
+     *
+     * Optional: drivers that cannot do this leave it undefined and callers fall
+     * back to `save` per row.
+     */
+    saveMany?<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveManyProps<M>): Promise<Record<string, unknown>[]>;
+
     /**
      * Delete a entity
      * @param props
@@ -252,9 +291,14 @@ export interface DataDriver {
  * REST-optimised fetch service exposed by drivers that support
  * eager-loading of relations via `include`.
  *
- * The methods return flattened rows (`{ id, ...columns }`) with
- * included relations inlined as plain nested rows — the shape served
- * to app developers through the REST API / SDK client.
+ * The methods return flattened rows — exactly the table's columns, under their
+ * own names and with the types the database returned — and included relations
+ * inlined as plain nested rows. This is the shape served to app developers
+ * through the REST API / SDK client.
+ *
+ * No synthesized `id`: identity is a primary key, which may be named anything
+ * and span several columns, so an address is derived by whoever needs one (see
+ * `buildCompositeId`) rather than written into the row on top of the data.
  *
  * @group DataDriver
  */