@rebasepro/types 0.19.1 → 0.19.2-canary.g09316f6

package/dist/types/schema_editing.d.ts

@@ -62,6 +62,12 @@ export interface SchemaCommitPaths {
     searchFile: string;
     /** Vector columns and ANN indexes — like search, applied by Rebase not Atlas. */
     vectorFile: string;
+    /**
+     * `autoValue: "on_update"` triggers and the function they share. Atlas's
+     * free tier will not parse a desired state containing a function, so this
+     * is applied by Rebase like search and vector.
+     */
+    triggersFile: string;
 }
 export declare const DEFAULT_COMMIT_PATHS: SchemaCommitPaths;
 /** One file the commit writes, as content rather than as a path on a disk. */

package/dist/types/tenancy.d.ts

@@ -0,0 +1,147 @@
+/**
+ * First-class multi-tenancy: one declaration, every layer.
+ *
+ * A tenant-scoped collection was expert work. It took four separate,
+ * hand-written pieces that nothing checked against each other — a column, an
+ * `existsIn` or raw RLS rule, a value stamped on every insert by a callback,
+ * and an index somebody had to remember. Miss the index and the table scans;
+ * miss the stamp and the row is invisible the moment it is written; miss the
+ * rule and every tenant reads every other tenant's rows, which is the failure
+ * nothing surfaces until it is a disclosure.
+ *
+ * {@link CollectionTenantConfig} is the one place that says "this collection
+ * belongs to a tenant", and the four pieces are derived from it:
+ *
+ *  - the column is `NOT NULL` and gets a btree index (`planSchema`);
+ *  - a **restrictive** RLS policy is injected for every operation, so it
+ *    composes with (rather than replaces) whatever `securityRules` the
+ *    collection declares — tenancy narrows, it never grants;
+ *  - the write path stamps the caller's tenant on create, refuses a write that
+ *    names another tenant, and refuses an update that moves a row between
+ *    tenants;
+ *  - the OpenAPI document marks the field so a generated client can see it.
+ *
+ * @see CollectionTenantConfig
+ * @group Models
+ */
+/**
+ * The caller's tenant comes from a claim on their session token.
+ *
+ * The single-tenant-per-user shape: an identity provider (or Rebase's own
+ * custom-claims hook) puts the organization on the token, and every request
+ * carries it. Compiles to a comparison against `rebase.jwt() ->> '<claim>'`,
+ * which is the same value a hand-written rule would read — so the generated
+ * policy and anything an author writes beside it agree by construction.
+ *
+ * @group Models
+ */
+export interface TenantClaimSource {
+    /**
+     * The claim's name on the access token, e.g. `"org_id"`.
+     *
+     * Custom claims survive verification and reach RLS as `rebase.jwt()`; the
+     * identity claims (`uid`, `roles`, `aal`, `isAnonymous`) are written after
+     * them when a token is minted and cannot be shadowed, so naming one of
+     * those here is refused rather than quietly reading the identity.
+     */
+    claim: string;
+}
+/**
+ * The caller's tenants come from rows of a membership collection.
+ *
+ * The many-tenants-per-user shape — a `memberships` table with a user column
+ * and a tenant column, which is how a person belongs to three organizations at
+ * once. Compiles to a correlated `EXISTS` over that table (`policy.existsIn`),
+ * so the database answers "is the caller a member of this row's tenant?" in the
+ * same query rather than in an N+1 of lookups.
+ *
+ * Nothing is put on the token, so nothing has to be re-minted when somebody
+ * joins or leaves a tenant — the next statement already sees the new row.
+ *
+ * @group Models
+ */
+export interface TenantMembershipSource {
+    membership: {
+        /** Slug of the collection holding the memberships. */
+        collection: string;
+        /** The property on it that holds the user id (compared to `rebase.uid()`). */
+        userField: string;
+        /** The property on it that holds the tenant id. */
+        tenantField: string;
+    };
+}
+/** Where the caller's tenant comes from. @group Models */
+export type TenantSource = TenantClaimSource | TenantMembershipSource;
+/** Narrow a {@link TenantSource} to its claim form. @group Models */
+export declare function isTenantClaimSource(source: TenantSource): source is TenantClaimSource;
+/** Narrow a {@link TenantSource} to its membership form. @group Models */
+export declare function isTenantMembershipSource(source: TenantSource): source is TenantMembershipSource;
+/**
+ * The roles tenancy does not apply to, when the collection names none.
+ *
+ * `admin`, mirroring the security baseline every collection already carries
+ * (`<table>_default_admin_read` / `_write`): the Studio, `dataAsAdmin` and a
+ * support operator all run with it, and a tenancy rule that locked them out
+ * would make the admin panel show an empty table on a collection full of rows.
+ *
+ * @group Models
+ */
+export declare const DEFAULT_TENANT_BYPASS_ROLES: readonly string[];
+/**
+ * Declare a collection tenant-scoped.
+ *
+ * ```ts
+ * export const posts = buildCollection({
+ *     slug: "posts",
+ *     properties: {
+ *         orgId: { type: "string", validation: { required: true } },
+ *         title: { type: "string" }
+ *     },
+ *     tenant: { field: "orgId", from: { claim: "org_id" } }
+ * });
+ * ```
+ *
+ * The property has to exist — this says what a column *means*, it does not
+ * conjure one into existence, exactly like `softDelete`. A config naming a
+ * property the collection does not declare is refused at boot rather than at
+ * the first read.
+ *
+ * ## What it composes with
+ *
+ * The injected policy is **restrictive**, so it is ANDed with every permissive
+ * policy on the table: `securityRules`, `ownerField`, the injected admin
+ * baseline. That is the only composition that is safe by construction — a
+ * permissive tenancy policy would OR with the author's rules and a single
+ * `access: "public"` rule would take the whole tenancy boundary off.
+ *
+ * Postgres-only. RLS is what enforces it, and an engine without row-level
+ * security cannot be given this guarantee by an application-layer filter that
+ * a raw query goes around.
+ *
+ * @group Models
+ */
+export interface CollectionTenantConfig<M extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * The property holding the tenant id.
+     *
+     * A `string` or `number` property, or a `reference` / `belongsTo` relation
+     * to the tenants collection — in which case the foreign key the relation
+     * already declares is the column, and no second one is created.
+     *
+     * The column is made `NOT NULL` and indexed: a nullable tenant column is a
+     * row that belongs to nobody and is therefore invisible to everybody, and
+     * an unindexed one turns every RLS-filtered read into a sequential scan.
+     */
+    field: Extract<keyof M, string> | string;
+    /** Where the caller's tenant comes from. */
+    from: TenantSource;
+    /**
+     * Roles that see and write across every tenant.
+     *
+     * Defaults to {@link DEFAULT_TENANT_BYPASS_ROLES}. An empty array means
+     * "nobody bypasses" — the trusted server context still does, because it is
+     * what runs migrations and the auth flows, and a policy that excluded it
+     * would break the boot rather than protect a tenant.
+     */
+    bypassRoles?: readonly string[];
+}

package/dist/types/websockets.d.ts

@@ -39,6 +39,41 @@ export type WirePrimaryKeys = {
     type: "string" | "number";
     isUUID?: boolean;
 }[];
+/**
+ * What a `collection_update` frame says about the page it carries.
+ *
+ * The same shape a REST list's `meta` has, and for the same reason: a
+ * subscriber renders the list it was handed, and rendering it needs to know how
+ * many rows there are in total and whether there is another page.
+ *
+ * It used not to be sent. The frame carried rows and primary keys and nothing
+ * else, so the SDK issued a `GET /<collection>/count` **on every push** to
+ * recover it — one extra round trip per write, per subscriber, and a window in
+ * which the count and the rows described different states of the collection.
+ * The refetch already knows the query, so it counts once, beside the rows,
+ * inside the same RLS-bound transaction that read them.
+ */
+export interface CollectionUpdateMeta {
+    /** Rows matching the subscription's query. Absent when the count failed. */
+    total?: number;
+    /** Page size the rows were read with. */
+    limit: number;
+    /** Rows skipped to reach them. */
+    offset: number;
+    /** Whether rows exist beyond this page. */
+    hasMore: boolean;
+    /** The opaque cursor continuing this listing — see `PaginationMeta.nextCursor`. */
+    nextCursor?: string;
+    /**
+     * The count could not be taken, so `total` is missing and `hasMore` is a
+     * floor rather than an answer.
+     *
+     * Flagged rather than guessed: a subscriber that knows the total is unknown
+     * can keep the last one it had, which is what the SDK does. Substituting
+     * `rows.length` would claim a page read at offset 10 held two rows.
+     */
+    partial?: boolean;
+}
 export interface CollectionUpdateMessage extends WebSocketMessage {
     type: "collection_update";
     subscriptionId: string;
@@ -50,6 +85,8 @@ export interface CollectionUpdateMessage extends WebSocketMessage {
      * unchanged rows' references needs an address to match them by.
      */
     pks?: WirePrimaryKeys;
+    /** See {@link CollectionUpdateMeta}. */
+    meta?: CollectionUpdateMeta;
 }
 export interface SingleUpdateMessage extends WebSocketMessage {
     type: "single_update";

package/dist/users/user.d.ts

@@ -58,5 +58,26 @@ export type User = {
      * Accessible by the frontend, but only writable by the backend.
      */
     readonly metadata?: Record<string, any>;
+    /**
+     * The **custom claims on this session's token**, as the server verified
+     * them — not the user row's {@link metadata}, which is a different fact
+     * with a different lifetime.
+     *
+     * The distinction matters for authorization. `metadata` is whatever the
+     * users table holds right now; `claims` is what the caller's token asserts,
+     * which is what the database sees: they reach RLS as `rebase.jwt()`, and
+     * `policy.authClaim("org_id")` reads one. Multi-tenancy's `claim` form is
+     * built on them.
+     *
+     * Identity claims are not here. `uid`, `roles`, `aal` and `isAnonymous` are
+     * written *after* the custom claims when a token is minted, precisely so a
+     * claims hook cannot assert them, and they have their own fields on this
+     * type. Keeping them out means a rule reading `claims` can never be reading
+     * something the session asserted about its own identity.
+     *
+     * Absent for a caller with no token — an API key, a service identity, an
+     * anonymous request.
+     */
+    readonly claims?: Record<string, unknown>;
     getIdToken?: (forceRefresh?: boolean) => Promise<string>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/types",
-  "version": "0.19.1",
+  "version": "0.19.2-canary.g09316f6",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "keywords": [
     "rebase",