@rebasepro/types 0.9.1-canary.ff338b5 → 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

@@ -909,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:
@@ -940,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.
@@ -1158,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/policy.d.ts

@@ -21,7 +21,7 @@ export type PolicyExpression = TruePolicyExpression | FalsePolicyExpression | An
 /**
  * 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
+ * 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

package/dist/types/websockets.d.ts

@@ -72,6 +72,49 @@ export interface CollectionPatchMessage extends WebSocketMessage {
     /** 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.ff338b5",
+  "version": "0.10.0",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"

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

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

package/src/types/policy.ts

@@ -34,7 +34,7 @@ export type PolicyExpression =
 /**
  * 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
+ * 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

package/src/types/websockets.ts

@@ -71,6 +71,51 @@ export interface CollectionPatchMessage extends WebSocketMessage {
     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.
  */