@rebasepro/types 0.9.1-canary.fd3754b → 0.10.0

package/src/types/auth_adapter.ts

@@ -94,7 +94,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
@@ -198,8 +198,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>;
 }
 
 // ─── User Creation Lifecycle ─────────────────────────────────────────────────
@@ -223,6 +223,27 @@ export interface UserCreationPrepareResult {
     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()`.
  *
@@ -281,7 +302,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.). */
@@ -425,6 +446,33 @@ export interface AuthAdapter {
         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/src/types/backend.ts

@@ -245,6 +245,42 @@ export interface SingleSubscriptionConfig {
     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.
@@ -380,10 +416,24 @@ 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/src/types/collections.ts

@@ -382,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.
@@ -1059,9 +1071,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:
@@ -1093,10 +1110,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.
@@ -1327,7 +1344,7 @@ export interface AuthCollectionConfig {
      * Override for custom reset flows.
      */
     onResetPassword?: (
-        userId: string,
+        uid: string,
         ctx: AuthCollectionContext
     ) => Promise<AuthCollectionResetResult>;
 

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/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.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 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/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,57 @@ 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;
 }
 
 /**