@rebasepro/types 0.9.0 → 0.9.1-canary.09aaf62

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

package/src/controllers/email.ts

@@ -1,7 +1,7 @@
 /**
- * Email service types — portable interface shared by RebaseClient and server-core.
+ * Email service types — portable interface shared by RebaseClient and server.
  *
- * The concrete SMTP implementation lives in `@rebasepro/server-core/email`.
+ * The concrete SMTP implementation lives in `@rebasepro/server/email`.
  * This file provides only the consumer-facing contract so that it can be
  * referenced from `RebaseClient` without dragging in nodemailer.
  */

package/src/controllers/registry.ts

@@ -7,7 +7,7 @@ import type { AppView, NavigationGroupMapping } from "./navigation";
 
 /**
  * Options to enable the built-in collection editor.
- * When provided to `<RebaseCMS>`, the editor is auto-wired as a native feature.
+ * When provided to `<RebaseAdmin>`, the editor is auto-wired as a native feature.
  */
 export interface CollectionEditorOptions {
     /**
@@ -21,7 +21,7 @@ export interface CollectionEditorOptions {
     pathSuggestions?: string[];
 }
 
-export interface RebaseCMSConfig<EC extends CollectionConfig = CollectionConfig> {
+export interface RebaseAdminConfig<EC extends CollectionConfig = CollectionConfig> {
     collections?: EC[] | CollectionConfigsBuilder<EC>;
 
     /**
@@ -68,7 +68,7 @@ export interface RebaseCMSConfig<EC extends CollectionConfig = CollectionConfig>
 }
 
 export interface RebaseStudioConfig {
-    tools?: ("sql" | "js" | "rls" | "schema" | "storage" | "cron" | "schema-visualizer" | "branches" | "api" | "logs" | "api-keys")[];
+    tools?: ("sql" | "js" | "rls" | "schema" | "storage" | "cron" | "schema-visualizer" | "branches" | "backups" | "api" | "logs" | "api-keys")[];
     homePage?: ReactNode;
     devViews?: AppView[];
 }
@@ -79,12 +79,12 @@ export interface RebaseAuthConfig {
 
 export interface RebaseRegistryController {
     // Current state
-    cmsConfig: RebaseCMSConfig | null;
+    cmsConfig: RebaseAdminConfig | null;
     studioConfig: RebaseStudioConfig | null;
     authConfig: RebaseAuthConfig | null;
 
     // Registration functions
-    registerCMS: (config: RebaseCMSConfig) => void;
+    registerCMS: (config: RebaseAdminConfig) => void;
     unregisterCMS: () => void;
 
     registerStudio: (config: RebaseStudioConfig) => void;

package/src/types/auth_adapter.ts

@@ -17,7 +17,7 @@
  *
  * @example Custom auth
  * ```ts
- * import { createCustomAuthAdapter } from "@rebasepro/server-core";
+ * import { createCustomAuthAdapter } from "@rebasepro/server";
  *
  * initializeRebaseBackend({
  *   auth: createCustomAuthAdapter({
@@ -85,8 +85,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). */
@@ -218,6 +235,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;
 }
 
 // ─── Auth Response Transform ─────────────────────────────────────────────────
@@ -298,7 +320,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/src/types/backend.ts

@@ -736,6 +736,14 @@ export interface InitializedDriver {
     /** 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/src/types/backup.ts

@@ -0,0 +1,26 @@
+/**
+ * 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/src/types/collections.ts

@@ -179,24 +179,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;
 
 
     /**
@@ -383,6 +382,18 @@ export interface BaseCollectionConfig<M extends Record<string, unknown> = Record
      */
     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/src/types/cron.ts

@@ -4,7 +4,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.
  */
 
@@ -62,7 +62,7 @@ export interface CronJobContext {
 
     /**
      * 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/src/types/database_adapter.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 }),
@@ -118,4 +118,18 @@ 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/src/types/entity_callbacks.ts

@@ -91,7 +91,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>
 
@@ -185,7 +185,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>;
 
@@ -217,7 +217,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/src/types/index.ts

@@ -26,6 +26,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/src/types/policy.ts

@@ -27,9 +27,28 @@ export type PolicyExpression =
     | 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 const ANONYMOUS_USER_ID = "anonymous";
+
 /** Always allows. Compiles to `true`. @group Models */
 export interface TruePolicyExpression {
     kind: "true";
@@ -93,13 +112,42 @@ export interface RolesContainPolicyExpression {
 }
 
 /**
- * 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
@@ -218,6 +266,7 @@ export const policy = {
     rolesOverlap: (roles: readonly string[]): RolesOverlapPolicyExpression => ({ kind: "rolesOverlap", roles: roles as string[] }),
     rolesContain: (roles: readonly string[]): RolesContainPolicyExpression => ({ kind: "rolesContain", roles: roles as string[] }),
     authenticated: (): AuthenticatedPolicyExpression => ({ kind: "authenticated" }),
+    serverContext: (): ServerContextPolicyExpression => ({ kind: "serverContext" }),
     existsIn: (args: { collection: string; where: PolicyExpression }): ExistsInPolicyExpression =>
         ({ kind: "existsIn", collection: args.collection, where: args.where }),
     raw: (sql: string): RawPolicyExpression => ({ kind: "raw", sql }),

package/src/types/properties.ts

@@ -231,6 +231,20 @@ export interface BaseProperty<CustomProps = unknown> {
      */
     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;
+
     // NOTE: `defaultValue` is intentionally NOT on BaseProperty.
     // Each concrete property type (StringProperty, NumberProperty, etc.)
     // defines its own typed `defaultValue` for compile-time safety.

package/src/types/translations.ts

@@ -7,7 +7,7 @@ export type DeepPartial<T> = T extends object
     : 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.
@@ -549,6 +549,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;
 
@@ -560,6 +561,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 */

package/src/types/user_management_delegate.ts

@@ -10,8 +10,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/src/types/websockets.ts

@@ -12,12 +12,40 @@ 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 {
@@ -35,9 +63,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;
 }
 
 /**

package/src/users/user.ts

@@ -3,7 +3,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`)