@rebasepro/types 0.13.0 → 0.13.1-canary.g06dbe5b

package/dist/types/search.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Opt-in full-text search configuration.
+ *
+ * ## Why this is opt-in
+ *
+ * Without a `search` block, `.search()` behaves exactly as it always has: an
+ * `ILIKE '%term%'` OR-ed across the collection's top-level, non-enum `string`
+ * properties. That default is unchanged and will stay unchanged — declaring
+ * this block is the only way to get anything else.
+ *
+ * The default has three limits that no amount of tuning inside it can fix:
+ * it cannot reach inside `map` (JSONB) or `array` properties, it has no notion
+ * of relevance, and a leading `%` means it can never use an index. Collections
+ * that outgrow those limits declare what they want searched; collections that
+ * have not are left completely alone.
+ *
+ * ## What declaring it does
+ *
+ * One `tsvector` column, `GENERATED ALWAYS AS … STORED`, plus one GIN index on
+ * it. Postgres recomputes the column on every write of a source field, so it
+ * cannot drift from the row, and refuses any attempt to write it directly.
+ * `.search()` then compiles to `@@ websearch_to_tsquery(…)` against that
+ * column, which stems, drops stopwords, AND-es the terms, and ranks.
+ *
+ * These are stated consequences, not hidden ones: the column and the index
+ * appear in generated DDL, in `schema.generated.ts`, and in `rebase db push`
+ * output like any other declared object.
+ *
+ * @example
+ * ```ts
+ * const talents: PostgresCollectionConfig = {
+ *     slug: "talents",
+ *     table: "talents",
+ *     properties: { … },
+ *     search: {
+ *         language: "spanish",
+ *         unaccent: true,
+ *         fields: [
+ *             { path: "full_name", weight: "A" },
+ *             "location",
+ *             "questionnaire.certifications"   // into the JSONB
+ *         ]
+ *     }
+ * };
+ * ```
+ *
+ * @group Search
+ */
+export interface SearchConfig {
+    /**
+     * The fields to index, in the author's own words. Nothing is inferred: a
+     * field is searched if and only if it is named here.
+     *
+     * A bare string is shorthand for `{ path, weight: "B" }`.
+     *
+     * A path may address:
+     * - a top-level `string` property — `"full_name"`
+     * - a `string[]` property — `"tags"` (every element is indexed)
+     * - a path into a `map` property — `"questionnaire.certifications"`,
+     *   which indexes every string found at or below that point, including
+     *   nested objects and arrays of strings. JSON *keys* are never indexed,
+     *   only values.
+     *
+     * A path that does not resolve to one of those is a boot-time error, not
+     * a silent omission — a search field you believe is live and is not is the
+     * failure this whole block exists to prevent.
+     */
+    fields: readonly (string | SearchField)[];
+    /**
+     * The Postgres text search configuration, which decides stemming and
+     * stopwords. `"spanish"` stems `auditores` to `auditor` and drops `de`;
+     * `"simple"` does neither.
+     *
+     * Defaults to `"simple"`, which is the only choice that is never wrong:
+     * a stemmer applied to the wrong language silently mangles lexemes. Set it
+     * to your content's language to get stemming.
+     *
+     * @default "simple"
+     */
+    language?: string;
+    /**
+     * Fold accents before indexing, so `auditoria` matches `auditoría`.
+     *
+     * This is not cosmetic in accented languages. Postgres stems the two
+     * spellings to *different* lexemes — `to_tsvector('spanish', 'auditoría')`
+     * yields `auditor` while `'auditoria'` yields `auditori` — so without this
+     * a query typed without accents misses the rows that carry them, which is
+     * most queries most users type.
+     *
+     * Requires the `unaccent` extension. Boot fails with an explicit message if
+     * it is not installed and cannot be created, rather than quietly indexing
+     * accented text as-is.
+     *
+     * @default false
+     */
+    unaccent?: boolean;
+    /**
+     * Name of the generated column holding the `tsvector`.
+     *
+     * Only change this if `search_vector` collides with a column you already
+     * have. It is part of your schema once created: renaming it later is a
+     * column drop and recreate, which rewrites the table.
+     *
+     * @default "search_vector"
+     */
+    column?: string;
+    /**
+     * Also match on trigram similarity, so near-misses and typos still rank —
+     * `iso14000` reaching `ISO 14001`, which no amount of stemming will do
+     * because they are simply different lexemes.
+     *
+     * Adds a second generated `text` column and a GIN trigram index alongside
+     * the `tsvector`, and requires the `pg_trgm` extension. Costs write time
+     * and disk; buys the single most common class of failed search.
+     *
+     * Also changes what `_score` means: the trigram similarity is added to
+     * `ts_rank`. It has to be. A typo matches nothing on the exact path, so
+     * every row this finds has a `ts_rank` of zero — ranking by that alone
+     * would order the results arbitrarily, which is the failure `fuzzy` exists
+     * to fix.
+     *
+     * @default false
+     */
+    fuzzy?: boolean;
+    /**
+     * Similarity floor for {@link SearchConfig.fuzzy}, between 0 and 1. A row
+     * whose trigram similarity to the query falls below this never matches on
+     * the fuzzy path (it can still match on the exact one).
+     *
+     * Lower admits more typos and more noise. Ignored unless `fuzzy` is set.
+     *
+     * @default 0.3
+     */
+    fuzzyThreshold?: number;
+}
+/**
+ * One indexed field, with the weight it carries in the ranking.
+ *
+ * @group Search
+ */
+export interface SearchField {
+    /**
+     * Property name, or dotted path into a `map` property.
+     * @see SearchConfig.fields
+     */
+    path: string;
+    /**
+     * Postgres weight class. `ts_rank` scores an `A` hit far above a `D` hit,
+     * which is how a name outranks a passing mention in a long description.
+     *
+     * The four classes are Postgres's own and there are exactly four.
+     *
+     * @default "B"
+     */
+    weight?: SearchWeight;
+}
+/**
+ * Postgres tsvector weight classes, strongest to weakest.
+ *
+ * @group Search
+ */
+export type SearchWeight = "A" | "B" | "C" | "D";
+/** The column name used when {@link SearchConfig.column} is not given. */
+export declare const DEFAULT_SEARCH_COLUMN = "search_vector";
+/** The text search configuration used when {@link SearchConfig.language} is not given. */
+export declare const DEFAULT_SEARCH_LANGUAGE = "simple";
+/** The weight a field carries when it does not name one. */
+export declare const DEFAULT_SEARCH_WEIGHT: SearchWeight;
+/** The similarity floor used when {@link SearchConfig.fuzzyThreshold} is not given. */
+export declare const DEFAULT_FUZZY_THRESHOLD = 0.3;
+/**
+ * Sort keys a query computes rather than reads from a column.
+ *
+ * `orderBy` is otherwise typed against the row — `keyof M` — which is exactly
+ * right for a column and exactly wrong for relevance: `_score` is produced by
+ * the query, so it appears in no generated row type and a project with a
+ * generated SDK could not name it. The runtime accepted it, the docs told
+ * people to use it, and the types rejected it.
+ *
+ * Kept as a named union rather than a loose `string` so the other half of the
+ * guarantee survives: a typo'd column is still a compile error, and remains a
+ * 400 at runtime rather than a silently unsorted list.
+ *
+ * `_distance` is deliberately not here. A vector search orders by distance on
+ * its own and overrides `orderBy` outright, so naming it would imply a choice
+ * the caller does not have.
+ *
+ * @group Search
+ */
+export type ComputedSortField = typeof RELEVANCE_SORT_FIELD;
+/**
+ * The relevance sort key. Valid only on a collection that declares a
+ * {@link SearchConfig} *and* on a query that carries a search string; anywhere
+ * else it is an unknown field and the request is refused.
+ */
+export declare const RELEVANCE_SORT_FIELD = "_score";
+/**
+ * One field that matched, and the text around the hit.
+ *
+ * Returned per row as `_matches` when a query asks for it — see the `explain`
+ * option on `.search()`. Answers the question a ranked list otherwise leaves
+ * open: *why is this row here?* A candidate surfacing for "iso 14001" because
+ * of a certification is a different result from one surfacing because the
+ * string appears in a paragraph about something else, and the score alone
+ * cannot tell them apart.
+ *
+ * @group Search
+ */
+export interface SearchMatch {
+    /**
+     * The declared field path that matched, exactly as written in
+     * {@link SearchConfig.fields} — e.g. `"questionnaire.certifications"`.
+     * Map it to a label for display; the path is stable, a label is yours.
+     */
+    field: string;
+    /**
+     * The matching text, with each hit wrapped in `<mark>…</mark>`.
+     *
+     * Built by Postgres's `ts_headline` over the same normalized text that was
+     * indexed. With {@link SearchConfig.unaccent} on that means the snippet
+     * reads with accents folded — `Auditoria` rather than `Auditoría`. That is
+     * deliberate: `ts_headline` over the *original* text cannot find a hit the
+     * unaccented query produced, so it returns the text with nothing marked at
+     * all. A readable snippet that highlights beats a prettier one that
+     * silently does not.
+     *
+     * Contains markup by construction. Render it as HTML or strip the tags —
+     * do not display it raw, and do not trust it as plain text.
+     */
+    snippet: string;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.13.0",
+  "version": "0.13.1-canary.g06dbe5b",
   "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,16 @@ 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 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:
@@ -38,12 +48,66 @@ 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 **`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()` (`auth.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
      */

package/src/controllers/client.ts

@@ -267,18 +267,31 @@ export interface RebaseClient<DB = unknown> {
     data: RebaseSdkData<DB>;
 
     /**
-     * Admin-scoped, **RLS-bypassing** data accessor.
+     * Admin-scoped data accessor — **not** an RLS bypass.
      *
      * Present on the **server** singleton only (see {@link RebaseServerClient}).
-     * It runs with `{ uid: "service", roles: ["admin"] }` — every read and write
-     * bypasses row-level-security policies. This is the correct tool for trusted
-     * background work (cron jobs, migrations, service-to-service tasks).
+     * It runs as the service identity `{ uid: "service", roles: ["admin"] }`,
+     * and the driver is scoped with `withAuth()` at boot, so every read and
+     * write runs in a transaction that has switched to the restricted
+     * `rebase_user` role with `app.uid = 'service'`: policies are evaluated,
+     * against that identity. This is the correct tool for trusted background
+     * work (cron jobs, migrations, service-to-service tasks).
+     *
+     * Two consequences the name does not suggest:
+     *
+     * - `policy.serverContext()` compiles to `auth.uid() IS NULL` and is
+     *   therefore **false** here. A collection with `disableDefaultPolicies:
+     *   true` whose only rule is `serverContext()` refuses these writes
+     *   (`42501`) and returns zero rows — HTTP 200, empty — for these reads.
+     * - Its reach equals an `admin`-roled application user's reach. It is not a
+     *   private channel. The true bypass is {@link sql}, which runs on the
+     *   owner connection and never goes through `withAuth`.
      *
      * ⚠️ **Do NOT use it to serve user-facing data.** Inside a request handler,
      * user-scoped queries must go through the request-scoped driver
-     * (`c.var.driver`), which carries the caller's identity so RLS applies.
-     * Reaching for `dataAsAdmin` (or its alias {@link data}) in a request handler
-     * silently exposes every row to every caller.
+     * (`c.var.driver`), which carries the caller's identity. Reaching for
+     * `dataAsAdmin` (or its alias {@link data}) in a request handler serves
+     * every caller whatever an admin may see.
      *
      * Undefined in the browser SDK.
      */
@@ -362,7 +375,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>;
 
     /**
@@ -382,17 +410,20 @@ export interface RebaseClient<DB = unknown> {
  * the admin-scoped {@link dataAsAdmin} accessor, raw {@link sql}, and the
  * {@link email} service are all present (non-optional).
  *
- * **Trust levels.** {@link dataAsAdmin} is the admin-scoped, **RLS-bypassing**
- * driver, and it is the only name for it here — the `data` alias that used to
- * sit beside it is deliberately `Omit`ted from {@link RebaseClient} so the
- * privilege has to be spelled out at every call site. For user-scoped queries
- * inside a request handler use the request-scoped driver (`c.var.driver`)
- * instead — never `dataAsAdmin`.
+ * **Trust levels.** {@link dataAsAdmin} is the admin-scoped driver — scoped as
+ * `{ uid: "service", roles: ["admin"] }`, so policies are still evaluated
+ * against that identity rather than skipped — and it is the only name for it
+ * here: the `data` alias that used to sit beside it is deliberately `Omit`ted
+ * from {@link RebaseClient} so the privilege has to be spelled out at every
+ * call site. {@link sql} is the unconditional bypass: raw SQL on the owner
+ * connection, no policies. For user-scoped queries inside a request handler use
+ * the request-scoped driver (`c.var.driver`) instead — never `dataAsAdmin`.
  */
 export interface RebaseServerClient<DB = unknown> extends Omit<RebaseClient<DB>, "data"> {
     /**
-     * Admin-scoped, **RLS-bypassing** data accessor. Always present server-side.
-     * See {@link RebaseClient.dataAsAdmin} for the full safety contract.
+     * Admin-scoped data accessor (RLS is evaluated as the service identity, not
+     * skipped). Always present server-side. See {@link RebaseClient.dataAsAdmin}
+     * for the full safety contract.
      */
     dataAsAdmin: RebaseSdkData<DB>;
 
@@ -410,85 +441,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.
  *