@rebasepro/types 0.9.0 → 0.9.1-canary.0fce67c

package/dist/types/auth_adapter.d.ts

@@ -17,7 +17,7 @@
  *
  * @example Custom auth
  * ```ts
- * import { createCustomAuthAdapter } from "@rebasepro/server-core";
+ * import { createCustomAuthAdapter } from "@rebasepro/server";
  *
  * initializeRebaseBackend({
  *   auth: createCustomAuthAdapter({
@@ -77,8 +77,25 @@ export interface AuthAdapterCapabilities {
     emailPasswordLogin: boolean;
     /** Supports new user registration. */
     registration: boolean;
-    /** Supports password reset flow. */
+    /**
+     * Supports the end-user password reset flow (emailing a reset link).
+     *
+     * This is about *self-service* reset, so it is typically tied to whether an
+     * email service is configured. It says nothing about whether an admin can
+     * reset someone else's password — see `adminPasswordReset`.
+     */
     passwordReset: boolean;
+    /**
+     * Whether the adapter exposes `POST /admin/users/:userId/reset-password`,
+     * letting an admin reset another user's password.
+     *
+     * Independent of `passwordReset`: the built-in adapter supports this even
+     * with no email service configured (it returns a one-time temporary
+     * password instead of sending a link). Adapters that mount their own admin
+     * routes must set this to `true` only once that route actually exists —
+     * the admin UI hides the "Reset Password" action when it is `false`.
+     */
+    adminPasswordReset: boolean;
     /** Supports session listing/revocation. */
     sessionManagement: boolean;
     /** Supports profile updates (display name, photo). */
@@ -196,6 +213,11 @@ export interface UserCreationFinalizeResult {
     temporaryPassword?: string;
     /** Whether an invitation email was sent. */
     invitationSent: boolean;
+    /**
+     * Whether an email service was configured but delivery failed, causing the
+     * fallback to `temporaryPassword`. Absent when no email service is configured.
+     */
+    emailDeliveryFailed?: boolean;
 }
 /**
  * The auth response payload shape that flows through `transformAuthResponse`.
@@ -266,7 +288,7 @@ export interface AuthAdapter {
     /**
      * Verify an incoming request and extract the authenticated user.
      *
-     * This replaces the hardcoded JWT verification in server-core's middleware.
+     * This replaces the hardcoded JWT verification in server's middleware.
      * Each adapter implements its own token verification strategy:
      * - Built-in: verify Rebase JWT
      * - Clerk: call Clerk's `verifyToken()`

package/dist/types/backend.d.ts

@@ -551,6 +551,13 @@ export interface InitializedDriver {
     realtimeProvider?: RealtimeProvider;
     /** A collection registry to register schema / tables into. */
     collectionRegistry?: CollectionRegistryInterface;
+    /**
+     * Collections the driver derived from the live database schema.
+     *
+     * Set by drivers that introspect in `baas` mode; the server serves these
+     * instead of collections loaded from config files.
+     */
+    collections?: import("./collections").CollectionConfig[];
     /** The underlying database connection (for lifecycle management). */
     connection?: DatabaseConnection;
     /**

package/dist/types/backup.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Backup type definitions shared across server, client, and studio.
+ */
+/** Where a backup lives — a local path or an object-storage bucket. */
+export type BackupDestinationKind = "local" | "s3" | "gcs";
+/**
+ * A single backup as surfaced by the admin API / Studio Backups panel.
+ */
+export interface BackupInfo {
+    /** Storage key (object storage) or absolute file path (local). */
+    key: string;
+    /** Display name — the file's basename. */
+    name: string;
+    /** Size in bytes, when known. */
+    sizeBytes?: number;
+    /** ISO timestamp the backup was created, when recoverable. */
+    createdAt?: string;
+    /** The kind of destination this backup was read from. */
+    destinationKind: BackupDestinationKind;
+}

package/dist/types/collections.d.ts

@@ -154,24 +154,23 @@ export interface BaseCollectionConfig<M extends Record<string, unknown> = Record
      */
     auth?: boolean | AuthCollectionConfig;
     /**
-     * Opt out of the framework's default Row Level Security policies for
-     * authentication collections.
+     * Opt out of the framework's default Row Level Security policies.
      *
-     * When a collection has `auth` enabled, the schema generator automatically
-     * injects an admin-only write policy (INSERT/UPDATE/DELETE require the
-     * `admin` role, or the trusted server context) for any write operation that
-     * the collection does not already cover with an explicit `securityRules`
-     * entry. This makes privileged columns such as `roles` safe by default — a
-     * non-admin cannot modify the user row through the data API regardless of
-     * which code path issues the write.
+     * The schema generator automatically injects, for every collection, a
+     * baseline SELECT policy granting the trusted server context and the
+     * `admin` role read access (reads run under a restricted role, so RLS
+     * default-denies without it). For auth collections it additionally injects
+     * a self-read policy (`id = auth.uid()`) and an admin-only write gate
+     * (INSERT/UPDATE/DELETE require the `admin` role or the trusted server
+     * context), making privileged columns such as `roles` safe by default.
      *
-     * Defining your own write rule for an operation overrides the default for
-     * that operation. Set this flag to `true` to remove the default policies
+     * Author-defined `securityRules` are permissive and broaden access on top
+     * of these defaults. Set this flag to `true` to remove the defaults
      * entirely and take full responsibility for the collection's RLS.
      *
      * @default false
      */
-    disableDefaultAuthPolicies?: boolean;
+    disableDefaultPolicies?: boolean;
     /**
      * Order in which the properties are displayed.
      * If you are specifying your collection as code, the order is the same as the
@@ -331,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.

package/dist/types/cron.d.ts

@@ -3,7 +3,7 @@ import type { RebaseClient } from "../controllers/client";
  * Cron Job type definitions for Rebase.
  *
  * These types define the shape of cron job definitions, their runtime
- * status, and execution log entries — used across server-core, client,
+ * status, and execution log entries — used across server, client,
  * and studio packages.
  */
 /**
@@ -45,7 +45,7 @@ export interface CronJobContext {
     log: (...args: unknown[]) => void;
     /**
      * The server-side {@link RebaseClient}. This is the **same singleton**
-     * exposed as `rebase` (imported from `@rebasepro/server-core`) and as
+     * exposed as `rebase` (imported from `@rebasepro/server`) and as
      * `context` in collection callbacks — it is only named `client` here.
      *
      * Its data plane (`client.data`) runs with **admin privileges and bypasses

package/dist/types/database_adapter.d.ts

@@ -9,7 +9,7 @@
  *
  * @example
  * ```ts
- * import { createPostgresAdapter } from "@rebasepro/server-postgresql";
+ * import { createPostgresAdapter } from "@rebasepro/server-postgres";
  *
  * initializeRebaseBackend({
  *   database: createPostgresAdapter({ connection: db, schema }),
@@ -92,4 +92,20 @@ export interface DatabaseAdapterInitConfig {
     collections: CollectionConfig[];
     /** The shared collection registry to register into. */
     collectionRegistry: CollectionRegistryInterface;
+    /**
+     * How the server is being run — see `RebaseBackendConfig.mode`.
+     *
+     * In `"baas"` mode `collections` is empty by design: a driver that can
+     * describe its own schema should introspect the database and report the
+     * collections it found back on `InitializedDriver.collections`. Drivers
+     * that cannot introspect may ignore this.
+     */
+    mode?: "cms" | "baas";
+    /**
+     * `baas`-mode options — see `RebaseBackendConfig.baas`. Drivers that
+     * introspect should honour `unprotectedTables`.
+     */
+    baas?: {
+        unprotectedTables?: "exclude" | "serve";
+    };
 }

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/index.d.ts

@@ -24,6 +24,7 @@ export * from "./entity_views";
 export * from "./data_source";
 export * from "./storage_source";
 export * from "./cron";
+export * from "./backup";
 export * from "./component_ref";
 export * from "./auth_adapter";
 export * from "./database_adapter";

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.user_id`: 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/translations.d.ts

@@ -6,7 +6,7 @@ export type DeepPartial<T> = T extends object ? {
     [K in keyof T]?: DeepPartial<T[K]>;
 } : T;
 /**
- * All user-visible strings used internally by @rebasepro/core.
+ * All user-visible strings used internally by @rebasepro/app.
  * Pass a `DeepPartial<RebaseTranslations>` via the `translations` prop
  * on your Rebase entry-point component to override any key, or to add
  * a new locale.
@@ -487,6 +487,7 @@ export interface RebaseTranslations {
     invitation_sent_title?: string;
     temporary_password?: string;
     temporary_password_description?: string;
+    temporary_password_email_failed_description?: string;
     copy_password?: string;
     password_copied?: string;
     /** UsersView — pagination & search */
@@ -497,6 +498,9 @@ export interface RebaseTranslations {
     reset_password?: string;
     reset_password_success?: string;
     reset_password_confirmation?: string;
+    reset_password_send_email?: string;
+    reset_password_set_manually?: string;
+    reset_password_set_manually_description?: string;
     error_resetting_password?: string;
     /** Permission-denied empty states */
     no_permission_to_view_users?: string;

package/dist/types/user_management_delegate.d.ts

@@ -9,8 +9,14 @@ export interface UserCreationResult<USER extends User = User> {
     /** Whether an invitation email was sent to the user */
     invitationSent: boolean;
     /**
-     * Temporary password (only present when email service is not configured).
-     * This is returned one-time and should be shown to the admin to share manually.
+     * Temporary password, present when no invitation email could be delivered —
+     * either because no email service is configured, or because delivery failed
+     * (see `emailDeliveryFailed`). Returned one-time, to be shared manually.
      */
     temporaryPassword?: string;
+    /**
+     * Whether an email service was configured but delivery failed, causing the
+     * fallback to `temporaryPassword`. Absent when no email service is configured.
+     */
+    emailDeliveryFailed?: boolean;
 }

package/dist/types/websockets.d.ts

@@ -15,10 +15,34 @@ export interface WebSocketMessage {
     row?: Record<string, unknown> | null;
     error?: 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 +58,12 @@ 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;
 }
 /**
  * Column metadata returned by table introspection.

package/dist/users/user.d.ts

@@ -2,7 +2,7 @@
  * The canonical representation of an authenticated user in the Rebase ecosystem.
  *
  * Used by {@link AuthController}, collections, callbacks, and both the
- * `@rebasepro/client` and `@rebasepro/auth` packages. All other user types
+ * `@rebasepro/client` and `@rebasepro/app` packages. All other user types
  * (`RebaseUser`, `UserInfo`) are deprecated aliases of this type.
  *
  * **Backend-managed fields** (`uid`, `email`, `roles`, `metadata`, `createdAt`)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.9.0",
+  "version": "0.9.1-canary.0fce67c",
   "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/auth.tsx

@@ -10,7 +10,13 @@ export interface AuthCapabilities {
     emailPasswordLogin?: boolean;
     googleLogin?: boolean;
     registration?: boolean;
+    /** Self-service password reset (emailing a reset link) is available. */
     passwordReset?: boolean;
+    /**
+     * An admin can reset another user's password. Gates the "Reset Password"
+     * entity action in the admin UI. See `AuthAdapterCapabilities`.
+     */
+    adminPasswordReset?: boolean;
     sessionManagement?: boolean;
     profileUpdate?: boolean;
     emailVerification?: boolean;

package/src/controllers/client.ts

@@ -3,6 +3,7 @@ import type { RebaseSdkData } from "./data";
 import type { EmailService } from "./email";
 import type { StorageSource } from "./storage";
 import type { CronJobStatus, CronJobLogEntry } from "../types/cron";
+import type { BackupInfo, BackupDestinationKind } from "../types/backup";
 import type { ApiKeysAPI } from "../types/api_keys";
 import type { StorageSourceDefinition } from "../types/storage_source";
 
@@ -142,7 +143,7 @@ export interface AdminAPI {
     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 }>;
+    resetPassword(userId: 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[] } }>;
 }
@@ -161,6 +162,19 @@ export interface CronAPI {
     toggleJob(jobId: string, enabled: boolean): Promise<{ job: CronJobStatus }>;
 }
 
+// ─── Backups API ─────────────────────────────────────────────────────────────
+
+/**
+ * Client-side database-backup management interface.
+ * @group Backups
+ */
+export interface BackupsAPI {
+    /** List available backups at the configured destination, newest first. */
+    list(): Promise<{ backups: BackupInfo[]; destinationKind: BackupDestinationKind; configured: boolean }>;
+    /** Fetch a backup's bytes for download (authenticated). */
+    download(key: string): Promise<Blob>;
+}
+
 // ─── Functions API ───────────────────────────────────────────────────────────
 
 /**
@@ -294,6 +308,9 @@ export interface RebaseClient<DB = unknown> {
     /** Cron job management API */
     cron?: CronAPI;
 
+    /** Database backup management API */
+    backups?: BackupsAPI;
+
     /** Custom backend functions API */
     functions?: FunctionsAPI;
 
@@ -333,7 +350,7 @@ export interface RebaseClient<DB = unknown> {
 
 /**
  * The server-side Rebase surface — the shape of the `rebase` singleton exported
- * from `@rebasepro/server-core`.
+ * from `@rebasepro/server`.
  *
  * Narrows {@link RebaseClient} to the guarantees that always hold on the server:
  * the admin-scoped {@link dataAsAdmin} accessor, raw {@link sql}, and the
@@ -409,6 +426,9 @@ export interface RebaseBrowserClient<DB = unknown> {
     /** Cron job management API */
     cron?: CronAPI;
 
+    /** Database backup management API */
+    backups?: BackupsAPI;
+
     /** Custom backend functions API */
     functions?: FunctionsAPI;
 

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.
  *