@rebasepro/types 0.13.0 → 0.13.1-canary.g394d868

package/dist/types/admin_block.d.ts

@@ -29,7 +29,7 @@
  *
  * @group Models
  */
-export declare const ADMIN_COLLECTION_KEYS: readonly ["Actions", "additionalFields", "alwaysApplyDefaultValues", "components", "defaultEntityAction", "defaultFilter", "defaultSelectedView", "defaultSize", "defaultViewMode", "disableDefaultActions", "enabledViews", "entityActions", "entityViews", "exportable", "filterPresets", "fixedFilter", "form", "formAutoSave", "formView", "group", "hideFromNavigation", "hideIdFromCollection", "hideIdFromForm", "icon", "includeJsonView", "inlineEditing", "kanban", "listProperties", "localChangesBackup", "openEntityMode", "orderProperty", "pagination", "previewProperties", "propertiesOrder", "selectionController", "selectionEnabled", "sideDialogWidth", "sort", "titleProperty"];
+export declare const ADMIN_COLLECTION_KEYS: readonly ["Actions", "additionalFields", "alwaysApplyDefaultValues", "components", "defaultEntityAction", "defaultFilter", "defaultSelectedView", "defaultSize", "defaultViewMode", "disableDefaultActions", "display", "enabledViews", "entityActions", "entityViews", "exportable", "filterPresets", "fixedFilter", "form", "formAutoSave", "formView", "group", "hideFromNavigation", "hideIdFromCollection", "hideIdFromForm", "icon", "includeJsonView", "inlineEditing", "kanban", "listProperties", "localChangesBackup", "openEntityMode", "orderProperty", "pagination", "previewProperties", "propertiesOrder", "selectionController", "selectionEnabled", "sideDialogWidth", "sort", "titleProperty"];
 /** A key of a collection's `admin` block. @group Models */
 export type AdminCollectionKey = typeof ADMIN_COLLECTION_KEYS[number];
 /**

package/dist/types/collections.d.ts

@@ -13,9 +13,27 @@ import type { SecurityRule } from "./security_rules";
  */
 export interface BaseCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> {
     /**
-     * You can set an alias that will be used internally instead of the collection name.
-     * The `slug` value will be used to determine the URL of the collection.
-     * Note that you can use this value in reference properties too.
+     * The collection's identity. Required, and the value nearly everything else
+     * keys on:
+     *
+     * - the REST path — `/api/data/<slug>`
+     * - the SDK accessor — `client.data.<slug>` / `client.data.collection("<slug>")`
+     * - the admin panel's URL
+     * - the target of a `reference` or `relation` property
+     *
+     * Conventionally kebab-case and plural (`blog-posts`). It is independent of
+     * {@link table}: the slug is what callers say, the table is where the rows
+     * live, and renaming one does not rename the other.
+     *
+     * Treat it as frozen once anything has shipped against it — changing a slug
+     * changes every URL and every generated accessor at once.
+     *
+     * @example
+     * defineCollection({
+     *     slug: "blog-posts",   // /api/data/blog-posts, client.data.blogPosts
+     *     table: "posts",
+     *     properties: { … }
+     * })
      */
     slug: string;
     /**

package/dist/types/cron.d.ts

@@ -1,4 +1,5 @@
-import type { RebaseClient } from "../controllers/client";
+import type { RebaseServerClient } from "../controllers/client";
+import type { RebaseSdkData } from "../controllers/data";
 /**
  * Cron Job type definitions for Rebase.
  *
@@ -75,16 +76,56 @@ export interface CronJobContext {
     /** A simple logger scoped to this job run. */
     log: (...args: unknown[]) => void;
     /**
-     * The server-side {@link RebaseClient}. This is the **same singleton**
-     * exposed as `rebase` (imported from `@rebasepro/server`) and as
-     * `context` in collection callbacks — it is only named `client` here.
+     * The server-side Rebase singleton — the **same object** `import { rebase }
+     * from "@rebasepro/server"` returns, and the same one `defineFunction`
+     * hands its callback. Spelled the same way here so that one thing has one
+     * name across every server-side authoring surface.
      *
-     * Its data plane (`client.data`) runs with **admin privileges and bypasses
-     * RLS** (`{ uid: "service", roles: ["admin"] }`). There is no per-request
-     * user in a cron, so treat every query as fully trusted and scope your own
-     * filters explicitly.
+     * Its data plane is {@link RebaseServerClient.dataAsAdmin}, which runs with
+     * **admin privileges and bypasses RLS** (`{ uid: "service", roles:
+     * ["admin"] }`). A cron has no per-request user, so there is no user-scoped
+     * alternative here and no policy to fall back on: scope every query's
+     * filters yourself.
+     *
+     * @example
+     * export default defineCron({
+     *     name: "Nightly cleanup",
+     *     schedule: "0 3 * * *",
+     *     async handler({ rebase, log }) {
+     *         const expired = await rebase.dataAsAdmin.sessions.findAll({
+     *             where: { expired: ["==", true] }
+     *         });
+     *         for (const session of expired) {
+     *             await rebase.dataAsAdmin.sessions.delete(session.id as string);
+     *         }
+     *         log(`Deleted ${expired.length} expired sessions`);
+     *     }
+     * });
+     */
+    rebase: RebaseServerClient;
+    /**
+     * The same object as {@link rebase}, under the name this context used
+     * before.
+     *
+     * @deprecated Use `rebase` instead. Two things made the old name a problem,
+     * and neither was cosmetic. It contradicted every other server surface,
+     * where the singleton is `rebase` — the previous docstring had to end with
+     * *"it is only named `client` here"*. And typing it as `RebaseClient`
+     * re-exposed `client.data`, the alias that {@link RebaseServerClient}
+     * deliberately `Omit`s so the RLS-bypassing plane has exactly one name and
+     * the privilege is visible at the call site. A reader who learned
+     * `client.data` here carried it to a collection callback, where
+     * `context.data` is the *user-scoped* plane — same spelling, opposite
+     * privilege.
+     *
+     * Still the full server client at runtime, and `data` still resolves, so
+     * existing cron files keep working and keep compiling. It will be removed
+     * in the next major.
      */
-    client: RebaseClient;
+    client: RebaseServerClient & {
+        /** @deprecated Use `rebase.dataAsAdmin` — the name states the privilege. */
+        data: RebaseSdkData;
+    };
 }
 export type CronJobRunState = "idle" | "running" | "success" | "error" | "disabled";
 /**

package/dist/types/entity_callbacks.d.ts

@@ -7,7 +7,8 @@ import type { RebaseCallContext } from "../call_context";
  *
  * Register per-collection on the collection's `callbacks` field, or globally
  * via `initializeRebaseBackend({ callbacks })`. Fires on **every** data path — REST API,
- * WebSocket / realtime subscriptions, and server-side `rebase.data`.
+ * WebSocket / realtime subscriptions, and server-side writes through
+ * `rebase.dataAsAdmin`.
  *
  * When both global and per-collection callbacks are registered, execution
  * order is: **global → collection → property callbacks**.

package/dist/types/properties.d.ts

@@ -166,7 +166,7 @@ export interface BaseProperty<CustomProps = unknown> {
      * 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
+     * This is a server-side guarantee, unlike `admin.hideFromCollection`, which
      * only stops the admin panel from *rendering* a field and leaves it in the
      * JSON payload.
      */
@@ -904,6 +904,17 @@ export interface ImageResize {
  * @group Entity properties
  */
 export type JsonLogicRule = Record<string, any>;
+/**
+ * A condition that is either a JSON Logic rule or a literal answer.
+ *
+ * The unconditional case is the common one — "this field is never editable",
+ * "this field is never shown" — and with only a rule accepted it had to be
+ * spelled `{ "==": [1, 1] }`, which reads as a puzzle at the call site. A plain
+ * `true` says the same thing.
+ *
+ * @group Entity properties
+ */
+export type ConditionRule = JsonLogicRule | boolean;
 /**
  * Conditions for individual enum values within a property.
  * @group Entity properties
@@ -945,8 +956,10 @@ export interface PropertyConditions {
      * \`\`\`json
      * { "==": [{ "var": "values.status" }, "archived"] }
      * \`\`\`
+     *
+     * A literal `true` disables it unconditionally.
      */
-    disabled?: JsonLogicRule;
+    disabled?: ConditionRule;
     /**
      * Message to display when the field is disabled by a condition.
      */
@@ -959,13 +972,18 @@ export interface PropertyConditions {
     /**
      * Hide the field completely when this condition evaluates to true.
      * The field is removed from the form (not just visually hidden).
+     *
+     * A literal `true` hides it unconditionally. This is the way to keep a
+     * property out of the form without keeping it out of the collection.
      */
-    hidden?: JsonLogicRule;
+    hidden?: ConditionRule;
     /**
      * Make the field read-only when this condition evaluates to true.
      * Renders as a preview instead of an input.
+     *
+     * A literal `true` makes it read-only unconditionally.
      */
-    readOnly?: JsonLogicRule;
+    readOnly?: ConditionRule;
     /**
      * Make the field required when this condition evaluates to true.
      * Overrides the static `validation.required` setting.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.13.0",
+  "version": "0.13.1-canary.g394d868",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -42,7 +42,7 @@
     "@types/node": "^26.1.2",
     "@types/object-hash": "^3.0.6",
     "@types/react-measure": "^2.0.12",
-    "hono": "^4.12.27",
+    "hono": "^4.13.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.12",
     "typescript": "^6.0.3",

package/src/call_context.ts

@@ -1,3 +1,4 @@
+import type { DataDriver } from "./controllers/data_driver";
 import type { StorageSource } from "./controllers/storage";
 import type { RebaseClient } from "./controllers/client";
 import type { RebaseSdkData } from "./controllers/data";
@@ -21,7 +22,14 @@ export type RebaseCallContext<USER extends User = User> = {
      * The Rebase client instance.
      * Available in all entity callbacks (beforeSave, afterSave, afterRead,
      * beforeDelete, afterDelete) and in CollectionActionsProps via context.
-     * Use it to call backend functions, access data, storage, etc.
+     * Use it to call backend functions, access storage, send email, etc.
+     *
+     * ⚠️ **Not the same trust level as {@link data}.** Server-side this is the
+     * app singleton, so `client.dataAsAdmin` is **always** the RLS-bypassing
+     * plane — while {@link data}, one property over, follows whoever triggered
+     * the callback. On a user request, reaching for `context.client.dataAsAdmin`
+     * silently escalates a user-scoped operation to admin. For queries in a
+     * callback use {@link data}; come here for functions, storage and email.
      *
      * @example
      * // In a beforeSave callback:
@@ -38,12 +46,59 @@ export type RebaseCallContext<USER extends User = User> = {
      * Unified data access — `context.data.products.create(...)`.
      * Access any collection as a dynamic property.
      *
-     * Returns flat rows (`{ id, ...columns }`), identical to the frontend SDK
-     * client — so `context.data` in a backend callback and `client.data` in the
-     * frontend behave the same way (`row.title`, never `row.values.title`).
+     * **Inherits the privilege of whatever triggered the callback.** This is not
+     * a fixed trust level, and it is the one thing to know about this accessor:
+     *
+     * - Triggered by a **user request** (REST, realtime, an admin-panel edit):
+     *   user-scoped. The callback runs on the RLS-bound transaction opened for
+     *   that request, so policies apply to reads *and* writes — a callback
+     *   cannot see a row its caller could not.
+     * - Triggered by **server-context work** (`rebase.dataAsAdmin`, a cron):
+     *   unscoped, on the owner connection, bypassing RLS.
+     *
+     * So a callback that reads a sibling row will find it when an admin task
+     * saves and may find nothing when an end user saves — without an error,
+     * because RLS filters rather than raises. Write callbacks that tolerate
+     * that, or reach for {@link client}`.dataAsAdmin` deliberately when the
+     * callback genuinely has to see past its caller.
+     *
+     * Verified end-to-end against Postgres rather than asserted — see
+     * `"scopes context.data to the caller when a callback runs on a user
+     * request"` in `server-postgres`' `rls-enforcement` e2e suite. The
+     * documentation previously claimed the opposite (that callbacks always have
+     * full access), which is the unsafe direction to be wrong in.
+     *
+     * Returns flat rows (`{ id, ...columns }`), identical in *shape* to the
+     * frontend SDK client — so `context.data` in a backend callback and
+     * `client.data` in the frontend are accessed the same way (`row.title`,
+     * never `row.values.title`). Shape only: privilege differs as above.
      */
     data: RebaseSdkData;
 
+    /**
+     * The driver executing the operation this callback is attached to.
+     *
+     * Present server-side only. Declared here because it is already public in
+     * practice — the backend has always passed it, and the callbacks guide
+     * documented `context.driver.withAuth(user)` in all six locales. The
+     * contract simply did not name it, so `buildCallContext` was cast through
+     * `as unknown as RebaseCallContext` and nothing about the object was
+     * type-checked at all.
+     *
+     * The guide no longer recommends `withAuth` — {@link data} is already
+     * user-scoped on a user request, so the manual re-scoping it described was
+     * answering a problem that did not exist. The field stays declared rather
+     * than removed: it is on the runtime object, dropping it would break anyone
+     * who found it, and a named optional is better than a silent extra.
+     *
+     * `withAuth` is not on {@link DataDriver} because not every engine supports
+     * RLS scoping; it is narrowed here, and left optional so a driver without it
+     * is a compile-time absence rather than a runtime surprise.
+     */
+    driver?: DataDriver & {
+        withAuth?(user: { uid: string; roles?: string[] }): Promise<DataDriver>;
+    };
+
     /**
      * Used storage implementation
      */

package/src/controllers/client.ts

@@ -362,7 +362,22 @@ export interface RebaseClient<DB = unknown> {
     /** Resolve the current auth token */
     resolveToken?(): Promise<string | null>;
 
-    /** Make a raw HTTP call to the backend */
+    /**
+     * POST to an arbitrary path on the backend — the escape hatch, not the way
+     * to call a function.
+     *
+     * For a custom function use {@link functions}`.invoke(name, payload)`: it
+     * targets `/functions/<name>`, takes a method and sub-path, and returns the
+     * response body as sent. This posts wherever you point it and **unwraps**:
+     * it returns `res.data` when the response has a `data` property and the
+     * whole envelope otherwise — so an endpoint that legitimately answers
+     * `{ data: null }` hands back the envelope rather than `null`. Two ways to
+     * reach a function with two different response contracts is a trap; this is
+     * the one that exists for paths `invoke` cannot express.
+     *
+     * @internal Prefer `functions.invoke()`. Kept public because a backend can
+     * mount routes outside `/functions`, and nothing else reaches those.
+     */
     call?<T = unknown>(endpoint: string, payload?: unknown): Promise<T>;
 
     /**
@@ -410,85 +425,6 @@ export interface RebaseServerClient<DB = unknown> extends Omit<RebaseClient<DB>,
     sql(query: string, options?: { database?: string; role?: string; params?: unknown[] }): Promise<Record<string, unknown>[]>;
 }
 
-// ─── RebaseBrowserClient ─────────────────────────────────────────────────────
-
-/**
- * The browser-side Rebase surface — the shape produced by
- * `createRebaseClient()` in `@rebasepro/client`.
- *
- * Its {@link data} accessor is **user-scoped**: every call carries the signed-in
- * user's token, so backend RLS policies apply. It deliberately omits the
- * server-only members — there is no `sql`, no `email`, and no
- * `dataAsAdmin`, so the RLS-bypassing accessor can never be reached from
- * browser code.
- */
-export interface RebaseBrowserClient<DB = unknown> {
-    /** User-scoped data access layer (carries the signed-in user's token). */
-    data: RebaseSdkData<DB>;
-
-    /** Unified Authentication layer */
-    auth: AuthClient;
-
-    /** Unified Storage layer (default storage source, backward-compatible) */
-    storage?: StorageSource;
-
-    /** Registry of all named storage sources for multi-backend support */
-    storageRegistry?: StorageSourceRegistry;
-
-    /** Build a server-backed {@link StorageSource} for a named storage source. */
-    createStorageSource?(storageId: string): StorageSource;
-
-    /** Discover the storage sources declared on the backend. */
-    fetchStorageSources?(): Promise<StorageSourceDefinition[]>;
-
-    /** Admin API for user management */
-    admin?: AdminAPI;
-
-    /** Cron job management API */
-    cron?: CronAPI;
-
-    /** Database backup management API */
-    backups?: BackupsAPI;
-
-    /** Custom backend functions API */
-    functions?: FunctionsAPI;
-
-    /** Service API keys management API */
-    apiKeys?: ApiKeysAPI;
-
-    /** Base HTTP URL of the backend server */
-    baseUrl?: string;
-
-    /**
-     * The path every API route is mounted under, appended to {@link baseUrl}.
-     *
-     * `"/api"` unless the backend was configured with a different `basePath`
-     * and the client told to match. Exposed because code that builds a URL by
-     * hand — rather than going through the client's own methods — otherwise has
-     * to guess, and guessing `/api` is wrong for exactly the projects that set
-     * the option.
-     */
-    apiPath?: string;
-
-    /** WebSocket client for realtime subscriptions */
-    ws?: RebaseWebSocket;
-
-    /** Set the auth token for subsequent requests */
-    setToken?(token: string | null): void;
-
-    /** Set a function that lazily resolves the auth token */
-    setAuthTokenGetter?(getter: () => Promise<string | null>): void;
-
-    /** Set handler called when a request returns 401 */
-    setOnUnauthorized?(handler: () => Promise<boolean>): void;
-
-    /** Resolve the current auth token */
-    resolveToken?(): Promise<string | null>;
-
-    /** Make a raw HTTP call to the backend */
-    call?<T = unknown>(endpoint: string, payload?: unknown): Promise<T>;
-}
-
 /**
  * Client-side registry for managing multiple storage sources.
  *