@rebasepro/types 0.23.0 → 0.24.1-canary.g19596ef

package/dist/call_context.d.ts

@@ -3,6 +3,7 @@ import type { StorageSource } from "./controllers/storage.js";
 import type { RebaseClient } from "./controllers/client.js";
 import type { RebaseSdkData } from "./controllers/data.js";
 import type { User } from "./users/index.js";
+import type { RegisteredDatabase } from "./types/register.js";
 /**
  * The client a collection callback is handed as `context.client`: the Rebase
  * client **without `data`**.
@@ -21,7 +22,7 @@ import type { User } from "./users/index.js";
  *
  * @group Hooks and utilities
  */
-export type RebaseCallbackClient<DB = unknown> = Omit<RebaseClient<DB>, "data">;
+export type RebaseCallbackClient<DB = RegisteredDatabase> = Omit<RebaseClient<DB>, "data">;
 /**
  * Context that is provided to entity callbacks (hooks).
  * It contains only the dependencies that are available in both the frontend and the backend.
@@ -54,7 +55,7 @@ export type RebaseCallbackClient<DB = unknown> = Omit<RebaseClient<DB>, "data">;
  *
  * @group Hooks and utilities
  */
-export type RebaseCallContext<USER extends User = User> = {
+export type RebaseCallContext<USER extends User = User, DB = RegisteredDatabase> = {
     /**
      * The Rebase client instance.
      * Available in all entity callbacks (beforeSave, afterSave, afterRead,
@@ -81,7 +82,7 @@ export type RebaseCallContext<USER extends User = User> = {
      * const { client } = props.context;
      * const result = await client.functions.invoke('extract-job', { url });
      */
-    client: RebaseCallbackClient;
+    client: RebaseCallbackClient<DB>;
     /**
      * Unified data access — `context.data.products.create(...)`.
      * Access any collection as a dynamic property.
@@ -119,8 +120,11 @@ export type RebaseCallContext<USER extends User = User> = {
      * 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.
+     *
+     * Untyped until the project registers its generated `Database` on
+     * {@link Register}; typed from it from then on.
      */
-    data: RebaseSdkData;
+    data: RebaseSdkData<DB>;
     /**
      * The driver executing the operation this callback is attached to.
      *

package/dist/controllers/client.d.ts

@@ -3,10 +3,12 @@ import type { ResourceRef } from "../types/resources.js";
 import type { RebaseSdkData } from "./data.js";
 import type { EmailService } from "./email.js";
 import type { StorageSource } from "./storage.js";
-import type { CronJobStatus, CronJobLogEntry } from "../types/cron.js";
-import type { BackupInfo, BackupDestinationKind } from "../types/backup.js";
-import type { ApiKeysAPI } from "../types/api_keys.js";
+import type { CronJobStatus, CronJobLogEntry, CronJobListing, CronJobStarted } from "../types/cron.js";
+import type { BackupDownloadLink, BackupListing } from "../types/backup.js";
+import type { ApiKeysAPI, PersonalKeysAPI } from "../types/api_keys.js";
+import type { RoleSummary } from "../types/scopes.js";
 import type { StorageSourceDefinition } from "../types/storage_source.js";
+import type { RegisteredDatabase } from "../types/register.js";
 /**
  * Event type for authentication state changes
  */
@@ -19,6 +21,10 @@ export type AuthChangeEvent = "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | "
  */
 export interface RebaseSession {
     accessToken: string;
+    /**
+     * `""` under `authFlowMode: "cookie"`: the refresh token is in an HttpOnly
+     * cookie that no script can read, so the session does not hold it.
+     */
     refreshToken: string;
     expiresAt: number;
     user: User;
@@ -134,10 +140,27 @@ export interface AdminUser {
      */
     providerId: string;
     roles: string[];
+    /**
+     * Switched off by an administrator (`PUT /admin/users/:uid { disabled }`):
+     * it signs in nowhere and the tokens it holds are refused.
+     */
+    disabled?: boolean;
     metadata?: Record<string, any>;
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * A user as the user picker sees one (`GET /admin/users/pick`): who the person
+ * is, and nothing about their account — no roles, no status, no timestamps.
+ *
+ * @group Admin
+ */
+export interface PickedUser {
+    uid: string;
+    email: string;
+    displayName: string | null;
+    photoURL: string | null;
+}
 /**
  * Client-side Admin API interface.
  * Provides user management operations.
@@ -170,6 +193,9 @@ export interface AdminAPI {
         metadata?: Record<string, any>;
     }): Promise<{
         user: AdminUser;
+        temporaryPassword?: string;
+        invitationSent?: boolean;
+        emailDeliveryFailed?: boolean;
     }>;
     updateUser(uid: string, data: {
         email?: string;
@@ -191,11 +217,9 @@ export interface AdminAPI {
         invitationSent?: boolean;
         emailDeliveryFailed?: boolean;
     }>;
+    /** The built-in `admin` role and the app's declared roles, with the scopes each holds. */
     listRoles(): Promise<{
-        roles: Array<{
-            id: string;
-            name: string;
-        }>;
+        roles: RoleSummary[];
     }>;
     bootstrap(): Promise<{
         success: boolean;
@@ -211,16 +235,30 @@ export interface AdminAPI {
  * @group Cron
  */
 export interface CronAPI {
-    listJobs(): Promise<{
-        jobs: CronJobStatus[];
-    }>;
+    /** The registered jobs, and the cron files and jobs that did not become one. */
+    listJobs(): Promise<CronJobListing>;
     getJob(jobId: string): Promise<{
         job: CronJobStatus;
     }>;
-    triggerJob(jobId: string): Promise<{
+    /**
+     * Run a job now and wait for it to finish. A proxy in front of the server
+     * may cut a long run's answer short while the run carries on; pass
+     * `{ async: true }` for those.
+     */
+    triggerJob(jobId: string, options?: {
+        async?: false;
+    }): Promise<{
         log: CronJobLogEntry;
         job: CronJobStatus;
     }>;
+    /**
+     * Start a job now and answer as soon as it has started. Read its outcome
+     * from {@link CronAPI.getJobLogs}: the entry with `manual: true` and the
+     * returned `startedAt`.
+     */
+    triggerJob(jobId: string, options: {
+        async: true;
+    }): Promise<CronJobStarted>;
     getJobLogs(jobId: string, options?: {
         limit?: number;
     }): Promise<{
@@ -235,14 +273,25 @@ export interface CronAPI {
  * @group Backups
  */
 export interface BackupsAPI {
-    /** List available backups at the configured destination, newest first. */
-    list(): Promise<{
-        backups: BackupInfo[];
-        destinationKind: BackupDestinationKind;
-        configured: boolean;
+    /**
+     * List available backups at the configured destination, newest first, and
+     * the scheduled backup job's last run.
+     */
+    list(): Promise<BackupListing>;
+    /**
+     * Save a backup in the browser: the browser is sent to a
+     * {@link downloadUrl} link and streams the dump to disk; the page never
+     * holds it. Browser only — elsewhere use {@link stream} or {@link downloadUrl}.
+     */
+    download(key: string): Promise<void>;
+    /** A link to one backup's bytes, good for 60 seconds, that needs no `Authorization` header. */
+    downloadUrl(key: string): Promise<BackupDownloadLink>;
+    /** A backup's bytes as a stream, read as consumed — to write one to a file outside a browser. */
+    stream(key: string): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        size?: number;
+        name: string;
     }>;
-    /** Fetch a backup's bytes for download (authenticated). */
-    download(key: string): Promise<Blob>;
 }
 /**
  * Options for invoking a custom backend function.
@@ -255,6 +304,15 @@ export interface FunctionInvokeOptions {
     path?: string;
     /** Extra headers merged into the request. */
     headers?: Record<string, string>;
+    /**
+     * How to read the function's answer — defaults to `"json"`.
+     *
+     * A function is a Hono route, so it may answer `c.text(csv)` or
+     * `c.body(pdf)`: ask for `"text"` (a string), `"blob"` (a `Blob`) or
+     * `"response"` (the `Response` itself, body unread, for streaming or
+     * headers). An error status is thrown as a `RebaseApiError` in every mode.
+     */
+    responseType?: "json" | "text" | "blob" | "response";
 }
 /**
  * Client interface for invoking custom backend functions.
@@ -280,6 +338,25 @@ export interface FunctionsAPI {
 export type HistoryConfig = boolean | {
     retention?: number;
 };
+/**
+ * Where the realtime connection is.
+ *
+ * - `idle` — no socket, and none wanted yet (the connection is lazy), or the
+ *   last one was dropped by a sign-out.
+ * - `connecting` — dialling, with no outage in progress.
+ * - `connected` — the socket is open.
+ * - `reconnecting` — the socket dropped and the client is redialling. A blip,
+ *   so far: nothing has been reported.
+ * - `disconnected` — the outage has outlasted the blip budget (about 15 s).
+ *   Every live subscription and joined channel has been told
+ *   `CONNECTION_LOST` once, and the client keeps redialling — every 30 s at
+ *   most — for as long as any exists. When the socket is back each is
+ *   re-subscribed, and its next update carries what changed meanwhile.
+ * - `closed` — `client.close()`. Final.
+ *
+ * @group Realtime
+ */
+export type RealtimeConnectionState = "idle" | "connecting" | "connected" | "reconnecting" | "disconnected" | "closed";
 /**
  * Minimal WebSocket client contract exposed on {@link RebaseClient}.
  *
@@ -291,10 +368,19 @@ export interface RebaseWebSocket {
     disconnect(): void;
     /** Send an authentication token to the server. */
     authenticate(token: string): Promise<void>;
-    /** Set a function that lazily resolves the auth token for auto-authentication. */
+    /**
+     * Set a function that lazily resolves the auth token for auto-authentication.
+     *
+     * @deprecated Use `client.setAuthTokenGetter()` instead, which authenticates
+     * HTTP requests and this socket together. Will be removed in a future release.
+     */
     setAuthTokenGetter(getter: () => Promise<string | null>): void;
     /** Listen for connection lifecycle events. */
     on(event: "connect" | "disconnect" | "reconnect" | "error", cb: (...args: unknown[]) => void): () => void;
+    /** Where the connection is. See {@link RealtimeConnectionState}. */
+    readonly state: RealtimeConnectionState;
+    /** Called on every change of {@link state}. Returns the unsubscribe. */
+    onStateChange(listener: (state: RealtimeConnectionState) => void): () => void;
 }
 /**
  * The single, canonical Rebase client interface.
@@ -390,8 +476,10 @@ export interface RebaseClient<DB = unknown> {
     backups?: BackupsAPI;
     /** Custom backend functions API */
     functions?: FunctionsAPI;
-    /** Service API keys management API */
+    /** The project's service keys. Requires `keys:read` / `keys:write`. */
     apiKeys?: ApiKeysAPI;
+    /** The signed-in person's own API keys, when the backend enables `auth.personalKeys`. */
+    personalKeys?: PersonalKeysAPI;
     /** Base HTTP URL of the backend server */
     baseUrl?: string;
     /**
@@ -457,7 +545,7 @@ export interface RebaseClient<DB = unknown> {
  * 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"> {
+export interface RebaseServerClient<DB = RegisteredDatabase> extends Omit<RebaseClient<DB>, "data"> {
     /**
      * Admin-scoped data accessor (RLS is evaluated as the service identity, not
      * skipped). Always present server-side. See {@link RebaseClient.dataAsAdmin}
@@ -530,10 +618,11 @@ export interface StorageSourceRegistry {
      */
     getDefault(): StorageSource;
     /**
-     * Get a storage source by key, with fallback to default.
+     * Get a storage source by key, or the default one for no key.
      * @param key - Storage source key, or undefined/null for default
-     * @returns The StorageSource (falls back to default if key not found)
-     * @throws Error if neither the specified nor default storage exists
+     * @returns The StorageSource registered under `key` (the default for no key)
+     * @throws Error if `key` names no registered source — never the default in
+     * its place — or no key is given and no default is registered
      */
     getOrDefault(key: string | undefined | null): StorageSource;
     /** Check if a storage source with the given key exists */

package/dist/controllers/collection_registry.d.ts

@@ -31,6 +31,23 @@ export type CollectionRegistryController<DB = Record<string, unknown>, EC extend
      * This is strictly for the Visual Editor to manipulate AST code without persisting runtime state.
      */
     getRawCollection: (slugOrPath: string) => EC | undefined;
+    /**
+     * The path a collection's rows are stored under, for the path the admin
+     * addresses it by. A Firestore or MongoDB collection may declare a `path`
+     * other than its slug — `slug: "fs_diagnosis", path: "diagnosis"` — and
+     * `fs_diagnosis/abc/locales` is then stored at `diagnosis/abc/locales`.
+     * This is what a reference to one of its records stores. Unchanged for a
+     * collection stored under its slug.
+     */
+    resolveDataPath: (path: string) => string;
+    /**
+     * The path the admin addresses a collection by, for a path its rows are
+     * stored under: the inverse of {@link resolveDataPath}, for a reference
+     * read back. `diagnosis` may be both where a Firestore collection is stored
+     * and the slug of a Postgres one; `preferredDriver` — the reference's
+     * `driver`, or the data source of the record it was read from — decides.
+     */
+    resolveCollectionPath: (path: string, preferredDriver?: string) => string;
     /**
      * Retrieve all the related parent references for a given path
      * @param path