@rebasepro/types 0.17.3 → 0.18.1

package/dist/types/resources.d.ts

@@ -19,9 +19,9 @@
  * A declaration says a resource *exists* and what shape it has. It never says
  * how to reach it — that is a property of the environment, not of the project,
  * and it differs between a laptop, a self-hosted box and a tenant in the cloud.
- * Binding lives in `@rebasepro/server`'s boot path, reading environment
- * variables or an infrastructure config file, and it keys off the logical name
- * declared here.
+ * Binding lives in `@rebasepro/server`'s boot path, where each kind registers
+ * the resolver that reads its environment variables, keyed off the logical
+ * name declared here.
  *
  * This split is the whole point. Before it, storage topology was hand-written
  * into `rebase.json` while database topology lived in TypeScript, and the
@@ -54,6 +54,26 @@ export type ResourceTransport =
 export interface ResourceKindSpec {
     /** The kind's name, as it appears in a declaration and in the graph. */
     kind: string;
+    /**
+     * Which definition of this kind this is. Bump it whenever anything else in
+     * the spec changes.
+     *
+     * Two copies of this package can meet in one process — a published driver
+     * inlines it into its dist, and the runtime image ships its own — and the
+     * registry is shared between them on purpose. Without a revision the only
+     * thing the registry can do with two specs that differ is refuse, and a
+     * refusal at driver load is a pod that never boots: every bundle built with
+     * a driver older than the change dies on the first image that carries it.
+     * With one, the higher revision wins whichever copy loads first, and the
+     * older copy is told so. Missing means 0, which is what every copy shipped
+     * before revisions existed reports.
+     *
+     * Only copies that know about revisions honour them. A copy published
+     * BEFORE they existed still compares the whole literal and throws, so a
+     * kind that has shipped in such a copy cannot change its literal at all —
+     * not even to add this field. Correct those kinds with `amendResourceKind`.
+     */
+    revision?: number;
     /** Engines this kind ships with. `custom:<id>` is always additionally valid. */
     engines: readonly string[];
     /** Used when a declaration names none. */
@@ -100,6 +120,19 @@ export interface ResourceDeclaration {
     label?: string;
     /** Kind-specific options, validated against the kind's `optionKeys`. */
     options: Readonly<Record<string, unknown>>;
+    /**
+     * What in the project reaches this resource, as `<what>:<name>` — a
+     * `collection:posts` routed to a database, a `property:posts.cover` stored
+     * in a bucket, a `function:report` importing a handle.
+     *
+     * Recorded by the derive step, never by a constructor: a declaration says
+     * a resource exists, and only a reader that has evaluated the rest of the
+     * project can say who uses it. It is the map a host needs to split a
+     * monolith into units later, and the map a console needs to answer "what
+     * breaks if I remove this". Absent when nothing was recorded, which is
+     * different from an empty list.
+     */
+    usedBy?: readonly string[];
 }
 /**
  * The value a constructor returns.
@@ -115,9 +148,68 @@ export interface ResourceHandle extends ResourceDeclaration {
 }
 /** Whether a value is a resource handle rather than a plain string key. */
 export declare function isResourceHandle(value: unknown): value is ResourceHandle;
+/**
+ * A reference to a resource where a key is expected: the handle a constructor
+ * returned, or the key spelled as a string.
+ *
+ * The handle is the point. `dataSource: analytics` is the same name spelled
+ * once — rename the export and every use follows, jump-to-definition lands on
+ * the declaration, and the derive step can record who uses what. The string
+ * form stays because a key has to survive serialisation: the runtime and the
+ * admin UI read collections as plain data, where a handle cannot travel.
+ */
+export type ResourceRef = string | ResourceHandle;
 /** The key a resource reference names, whether it is a handle or already a key. */
-export declare function resourceKeyOf(ref: string | ResourceHandle): string;
-/** Register a resource kind. Idempotent for an identical spec; throws on a conflicting one. */
+export declare function resourceKeyOf(ref: ResourceRef): string;
+/**
+ * Replace every resource handle inside a value with its key, deeply.
+ *
+ * Applied where authored config becomes data: `defineCollection`, the
+ * collection loaders, the derive step. Past that point a collection is plain
+ * data that serialises, compares with `===` and reaches the admin UI over the
+ * wire, so a handle must not survive into it. Plain objects and arrays are
+ * walked; anything else — a function, a Date, a class instance — is a leaf and
+ * is returned as it is, which is what keeps callbacks and validators intact.
+ */
+export declare function resolveResourceRefs<T>(value: T): T;
+/**
+ * Corrections this copy applies on top of a registered kind.
+ *
+ * Deliberately a module local — per COPY of this package — where the registry
+ * above is deliberately shared. A published driver inlines this package into
+ * its dist, and the copy it carries compares the shared registry's entry for a
+ * kind against its own literal by `JSON.stringify` and throws if they differ
+ * (see `registerResourceKind` before revisions existed). That code is in the
+ * field and cannot be changed, so the registered literal of any kind that has
+ * ever shipped is frozen: change one enumerable key and every bundle built with
+ * an older driver dies at driver load on the next image. What a kind actually
+ * binds can still be corrected — here, read through `resourceKind()` and
+ * everything built on it, invisible to the older copy, which keeps binding the
+ * way it did when it was published.
+ */
+type KindAmendment = Partial<Pick<ResourceKindSpec, "envBases" | "envBasesByEngine" | "optionKeys">>;
+/**
+ * Correct a registered kind without touching its registered literal.
+ *
+ * Use this, never an edit to the literal, for a kind that has shipped in a
+ * published package. The amendment applies to reads through this copy only.
+ */
+export declare function amendResourceKind(kind: string, amendment: KindAmendment): void;
+/**
+ * Register a resource kind.
+ *
+ * Idempotent for an identical spec. When a spec for the same kind is already
+ * registered and differs, the `revision` decides: the higher one is kept and
+ * the other copy is warned about, in either load order. Two different specs at
+ * the SAME revision are a genuine conflict — two packages defining one kind, or
+ * a change that forgot to bump — and still throw.
+ *
+ * Both copies in that comparison are peers on `KINDS_KEY`, which is what makes
+ * the rule enforceable: a copy old enough not to know `revision` writes to the
+ * legacy map instead and never reaches this function's arithmetic. Registering
+ * a kind an older copy already put in the legacy map is therefore not a
+ * conflict — it is the ordinary case, and `visibleKinds` prefers this one.
+ */
 export declare function registerResourceKind(spec: ResourceKindSpec): void;
 /** Every registered kind, for validators and for `rebase doctor`. */
 export declare function resourceKinds(): ResourceKindSpec[];
@@ -185,8 +277,16 @@ export interface ResourceGraph {
 }
 /** The current graph format version. */
 export declare const RESOURCE_GRAPH_VERSION: 1;
-/** Build a graph from the current declarations, sorted for a stable diff. */
-export declare function buildResourceGraph(): ResourceGraph;
+/**
+ * Build a graph from the current declarations, sorted for a stable diff.
+ *
+ * `usedBy` maps a `kind:key` id to the things that reach it. The derive step
+ * supplies it after evaluating collections; a runtime building the graph at
+ * boot passes nothing and gets declarations alone, which is all it binds from.
+ */
+export declare function buildResourceGraph(usedBy?: ReadonlyMap<string, readonly string[]>): ResourceGraph;
+/** `kind:key`, the id `usedBy` maps are keyed by. Exported for the derive step. */
+export declare function resourceId(kind: string, key: string): string;
 /**
  * The environment variables worth writing for a resource, given its engine.
  *
@@ -195,3 +295,4 @@ export declare function buildResourceGraph(): ResourceGraph;
  * guessing narrow would silently omit the variable it actually needs.
  */
 export declare function envBasesForResource(declaration: ResourceDeclaration): readonly string[];
+export {};

package/dist/types/rls-functions.d.ts

@@ -56,6 +56,17 @@ export declare const REBASE_SCHEMA = "rebase";
 export declare const RLS_UID_SQL = "rebase.uid()";
 /** The request's roles as a comma-separated string, for `string_to_array`. */
 export declare const RLS_ROLES_SQL = "rebase.roles()";
+/**
+ * Whether the caller is a GUEST — signed in through anonymous sign-in rather
+ * than with an account.
+ *
+ * A different question from {@link ANONYMOUS_USER_ID}, and the two are easy to
+ * confuse: that sentinel means "no session at all", while this means "a session
+ * with nobody behind it". Anonymous sign-in mints a real user row with a real
+ * uid, so before this reached the database the two kinds of caller were one
+ * principal inside every policy.
+ */
+export declare const RLS_IS_ANONYMOUS_SQL = "rebase.is_anonymous()";
 /** The request's JWT claims as `jsonb`, or `{}`. */
 export declare const RLS_JWT_SQL = "rebase.jwt()";
 /**

package/dist/types/storage_source.d.ts

@@ -89,6 +89,18 @@ export interface StorageSourceDefinition {
      * upload/download traffic for this source.
      */
     transport: StorageSourceTransport;
+    /**
+     * Serve unqualified uploads — a storage property naming no `storageSource`
+     * — from this source.
+     *
+     * Declared, never inferred. A project with named buckets and no default
+     * used to have one chosen for it by declaration order, with a warning, and
+     * the choice differed between development and production because the
+     * synthesized local default is dropped in production and the promotion was
+     * not. Where the files land is the author's decision; boot now fails
+     * without one.
+     */
+    default?: boolean;
     /** Human-readable label for the UI (e.g. "Firebase Storage", "S3 Media"). */
     label?: string;
 }
@@ -145,26 +157,3 @@ export declare function findStorageSuffixCollision(keys: string[], defaultKey?:
     b: string;
     suffix: string;
 } | null;
-/** The `storage` block of `rebase.json`, structurally. */
-export type DeclaredStorageSources = Record<string, {
-    engine: string;
-    transport?: StorageSourceTransport;
-    label?: string;
-}>;
-/**
- * Merge the two places a project may declare storage sources into one list.
- *
- * `rebase.json` is authoritative for every field it states. Config code may add
- * sources it does not mention and fill in fields it left out, but may not
- * contradict it: the manifest is what a host reads to decide which buckets need
- * configuring, and a runtime that quietly disagreed with it would put the
- * console back to describing a topology the tenant does not have — the exact
- * failure this whole mechanism exists to end.
- *
- * Note what is *not* here: no default source is invented when both inputs are
- * empty. That decision belongs to the resolver, which knows whether declaring
- * nothing means "one plain bucket" (it does) or "no storage at all".
- *
- * @group Models
- */
-export declare function normalizeStorageSources(declared: DeclaredStorageSources | StorageSourceDefinition[] | undefined, exported: StorageSourceDefinition[] | undefined): StorageSourceDefinition[];

package/package.json

@@ -1,39 +1,43 @@
 {
   "name": "@rebasepro/types",
-  "type": "module",
-  "version": "0.17.3",
+  "version": "0.18.1",
   "description": "Rebase type definitions — shared interfaces and controller types",
-  "funding": {
-    "url": "https://github.com/sponsors/rebaseco"
+  "keywords": [
+    "rebase",
+    "cms",
+    "admin",
+    "typescript",
+    "headless",
+    "headless cms",
+    "content manager"
+  ],
+  "homepage": "https://rebase.pro",
+  "bugs": {
+    "url": "https://github.com/rebasepro/rebase/issues"
   },
-  "author": "Rebase",
-  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/rebasepro/rebase.git",
     "directory": "packages/types"
   },
+  "funding": {
+    "url": "https://github.com/sponsors/rebasepro"
+  },
+  "license": "MIT",
+  "author": "Rebase",
+  "type": "module",
   "main": "./dist/index.es.js",
   "module": "./dist/index.es.js",
   "types": "./dist/index.d.ts",
-  "source": "src/index.ts",
   "engines": {
-    "node": ">=20"
+    "node": ">=22.22.0"
   },
-  "keywords": [
-    "rebase",
-    "cms",
-    "admin",
-    "typescript",
-    "headless",
-    "headless cms",
-    "content manager"
-  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "development": "./dist/index.es.js",
-      "import": "./dist/index.es.js"
+      "import": "./dist/index.es.js",
+      "default": "./dist/index.es.js"
     },
     "./package.json": "./package.json"
   },
@@ -48,12 +52,8 @@
     "typescript": "^6.0.3",
     "vite": "^8.1.5"
   },
-  "peerDependencies": {
-    "hono": "^4.12.27"
-  },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "gitHead": "d935eefa5aa8d1009a2398cfac2c1e4ee9aeb6b6",
   "publishConfig": {
@@ -91,6 +91,7 @@
     "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json && node ../../tooling/scripts/add-dts-extensions.mjs dist && node ../../tooling/scripts/assert-build-output.mjs",
     "test:lint": "eslint \"src/**\" --quiet",
     "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
     "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f"
   }
 }

package/src/call_context.ts

@@ -1,120 +0,0 @@
-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";
-import type { User } from "./users";
-
-/**
- * Context that is provided to entity callbacks (hooks).
- * It contains only the dependencies that are available in both the frontend and the backend.
- *
- * This is the *whole* context a collection callback gets, and it lives apart from
- * {@link RebaseContext} on purpose. `RebaseContext` widens it with nine admin-panel
- * controllers — navigation, side dialogs, snackbars — none of which exist in a
- * backend process. Keeping them in one type meant every backend module that
- * touched a callback signature transitively named the admin UI.
- *
- * @group Hooks and utilities
- */
-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 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 admin-scoped
-     * plane — scoped as `{ uid: "service", roles: ["admin"] }`, so policies are
-     * evaluated against that identity rather than skipped — 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:
-     * const result = await context.client.functions.invoke('my-function', { ... });
-     *
-     * @example
-     * // In a CollectionAction component:
-     * const { client } = props.context;
-     * const result = await client.functions.invoke('extract-job', { url });
-     */
-    client: RebaseClient;
-
-    /**
-     * Unified data access — `context.data.products.create(...)`.
-     * Access any collection as a dynamic property.
-     *
-     * **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 **`rebase.dataAsAdmin` or a cron** (the same singleton):
-     *   admin-scoped, not unscoped. That driver is scoped as
-     *   `{ uid: "service", roles: ["admin"] }`, so the callback still runs on an
-     *   RLS-bound transaction — policies are evaluated against that identity.
-     * - Triggered by **the base driver** (auth flows, migrations): 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 what an admin may see. Note what that does
-     * *not* buy you: `policy.serverContext()` (`rebase.uid() IS NULL`) is false
-     * for the service identity, so a collection whose only rule is
-     * `serverContext()` stays closed to it.
-     *
-     * 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
-     */
-    storageSource: StorageSource;
-
-    /**
-     * Set by the backend when callbacks are executed on the server.
-     */
-    user?: USER;
-}

package/src/controllers/auth_state.ts

@@ -1,24 +0,0 @@
-import type { User } from "../users";
-
-/**
- * The read-only slice of authentication state that property resolution needs.
- *
- * `dynamicProps`, `conditions` and the JSON-Logic condition context all want the
- * same one thing: who is asking. They used to be handed the entire
- * {@link AuthController} — `signOut`, `googleLogin`, `authLoading`, thirty-odd
- * members of frontend machinery — which meant `properties.ts` named a frontend
- * controller, and so did `resolveProperty` in `@rebasepro/common`, which the
- * Postgres schema generator calls at build time. A backend generating DDL had to
- * satisfy a type with a login method in it.
- *
- * `User` already carries `roles` and `metadata`, so this is not a reduction in
- * what a dynamic property can decide on — only in what it has to be given.
- * An `AuthController` satisfies this structurally, so the frontend passes the
- * controller it already has.
- *
- * @group Hooks and utilities
- */
-export interface AuthState<USER extends User = User> {
-    /** The signed-in user, or `null` when nobody is. */
-    user: USER | null;
-}