@rebasepro/types 0.0.1-canary.eae7889 → 0.0.1-canary.eb08332

package/dist/controllers/client.d.ts

@@ -1,12 +1,20 @@
-import { User } from "../users";
-import { RebaseData } from "./data";
-import { EmailService } from "./email";
+import type { User } from "../users";
+import type { RebaseSdkData } from "./data";
+import type { EmailService } from "./email";
+import type { StorageSource } from "./storage";
+import type { CronJobStatus, CronJobLogEntry } from "../types/cron";
+import type { BackupInfo, BackupDestinationKind } from "../types/backup";
+import type { ApiKeysAPI } from "../types/api_keys";
+import type { StorageSourceDefinition } from "../types/storage_source";
 /**
  * Event type for authentication state changes
  */
 export type AuthChangeEvent = "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | "USER_UPDATED";
 /**
- * Standard session interface representing an authenticated state
+ * Standard session interface representing an authenticated state.
+ *
+ * There is exactly one canonical definition of this type (here in
+ * `@rebasepro/types`). The `@rebasepro/client` package re-exports it.
  */
 export interface RebaseSession {
     accessToken: string;
@@ -14,7 +22,36 @@ export interface RebaseSession {
     expiresAt: number;
     user: User;
 }
-import { StorageSource } from "./storage";
+/**
+ * Access and refresh token pair returned by authentication endpoints.
+ *
+ * Replaces the former `RebaseTokens` (client) and `AuthTokens` (auth) types,
+ * which had identical shapes.
+ *
+ * @group Auth
+ */
+export interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    /** Unix timestamp (ms) when the access token expires. */
+    accessTokenExpiresAt: number;
+}
+/**
+ * A device-level session entry as returned by `GET /auth/sessions`.
+ *
+ * Represents one refresh-token / device pair. Not to be confused with
+ * {@link RebaseSession}, which is the client-side representation of the
+ * *current* authenticated state (user + tokens).
+ *
+ * @group Auth
+ */
+export interface DeviceSession {
+    id: string;
+    userAgent?: string;
+    ipAddress?: string;
+    createdAt: string;
+    isCurrentSession?: boolean;
+}
 /**
  * Unified Authentication Client Interface
  * Pure functional SDK interface, decoupled from UI and React hooks
@@ -28,6 +65,12 @@ export interface AuthClient {
      * Get the currently active session
      */
     getSession(): RebaseSession | null;
+    /**
+     * Get the current user's active sessions
+     */
+    getSessions?: () => Promise<DeviceSession[]>;
+    revokeSession?: (sessionId: string) => Promise<void>;
+    revokeAllSessions?: () => Promise<void>;
     /**
      * Sign out the current user and clear local session
      */
@@ -42,7 +85,14 @@ export interface AuthClient {
     refreshSession(): Promise<RebaseSession>;
 }
 /**
- * User record as returned by the Admin API.
+ * User record as returned by the Admin API (`GET /admin/users`, etc.).
+ *
+ * This is a dedicated DTO for admin operations and differs from {@link User}:
+ * - `roles` is required (always an array), vs optional on `User`
+ * - Includes audit timestamps (`createdAt`, `updatedAt`) as ISO strings
+ * - `email` is non-nullable (admin users always have an email)
+ *
+ * @see User — the canonical client-facing user type
  * @group Admin
  */
 export interface AdminUser {
@@ -50,25 +100,19 @@ export interface AdminUser {
     email: string;
     displayName: string | null;
     photoURL: string | null;
-    provider: string;
+    /**
+     * The provider used to authenticate the user (e.g. `"password"`,
+     * `"google"`). Named to match the canonical {@link User.providerId}.
+     */
+    providerId: string;
     roles: string[];
+    metadata?: Record<string, any>;
     createdAt: string;
     updatedAt: string;
 }
-/**
- * Role record as returned by the Admin API.
- * @group Admin
- */
-export interface AdminRole {
-    id: string;
-    name: string;
-    isAdmin: boolean;
-    defaultPermissions: Record<string, unknown> | null;
-    config: Record<string, unknown> | null;
-}
 /**
  * Client-side Admin API interface.
- * Provides user and role management operations.
+ * Provides user management operations.
  * @group Admin
  */
 export interface AdminAPI {
@@ -95,6 +139,7 @@ export interface AdminAPI {
         displayName?: string;
         password?: string;
         roles?: string[];
+        metadata?: Record<string, any>;
     }): Promise<{
         user: AdminUser;
     }>;
@@ -103,37 +148,26 @@ export interface AdminAPI {
         displayName?: string;
         password?: string;
         roles?: string[];
+        metadata?: Record<string, any>;
     }): Promise<{
         user: AdminUser;
     }>;
     deleteUser(userId: string): Promise<{
         success: boolean;
     }>;
-    listRoles(): Promise<{
-        roles: AdminRole[];
-    }>;
-    getRole(roleId: string): Promise<{
-        role: AdminRole;
-    }>;
-    createRole(data: {
-        id: string;
-        name: string;
-        isAdmin?: boolean;
-        defaultPermissions?: Record<string, unknown>;
-        config?: Record<string, unknown>;
-    }): Promise<{
-        role: AdminRole;
-    }>;
-    updateRole(roleId: string, data: {
-        name?: string;
-        isAdmin?: boolean;
-        defaultPermissions?: Record<string, unknown>;
-        config?: Record<string, unknown>;
+    resetPassword(userId: string, options?: {
+        password?: string;
     }): Promise<{
-        role: AdminRole;
+        user: AdminUser;
+        temporaryPassword?: string;
+        invitationSent?: boolean;
+        emailDeliveryFailed?: boolean;
     }>;
-    deleteRole(roleId: string): Promise<{
-        success: boolean;
+    listRoles(): Promise<{
+        roles: Array<{
+            id: string;
+            name: string;
+        }>;
     }>;
     bootstrap(): Promise<{
         success: boolean;
@@ -145,26 +179,303 @@ export interface AdminAPI {
     }>;
 }
 /**
- * Overarching abstraction that unites Data, Auth, Storage, and Email.
- * Adapters for Supabase or Firebase simply need to implement this interface.
+ * Client-side Cron job management interface.
+ * @group Cron
+ */
+export interface CronAPI {
+    listJobs(): Promise<{
+        jobs: CronJobStatus[];
+    }>;
+    getJob(jobId: string): Promise<{
+        job: CronJobStatus;
+    }>;
+    triggerJob(jobId: string): Promise<{
+        log: CronJobLogEntry;
+        job: CronJobStatus;
+    }>;
+    getJobLogs(jobId: string, options?: {
+        limit?: number;
+    }): Promise<{
+        logs: CronJobLogEntry[];
+    }>;
+    toggleJob(jobId: string, enabled: boolean): Promise<{
+        job: CronJobStatus;
+    }>;
+}
+/**
+ * Client-side database-backup management interface.
+ * @group Backups
+ */
+export interface BackupsAPI {
+    /** List available backups at the configured destination, newest first. */
+    list(): Promise<{
+        backups: BackupInfo[];
+        destinationKind: BackupDestinationKind;
+        configured: boolean;
+    }>;
+    /** Fetch a backup's bytes for download (authenticated). */
+    download(key: string): Promise<Blob>;
+}
+/**
+ * Options for invoking a custom backend function.
+ * @group Functions
+ */
+export interface FunctionInvokeOptions {
+    /** HTTP method — defaults to `"POST"`. */
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Sub-path appended after the function name. */
+    path?: string;
+    /** Extra headers merged into the request. */
+    headers?: Record<string, string>;
+}
+/**
+ * Client interface for invoking custom backend functions.
+ * @group Functions
+ */
+export interface FunctionsAPI {
+    /**
+     * Invoke a custom backend function by name.
+     *
+     * @typeParam T - Expected shape of the response payload.
+     * @param name    - Function name (filename without extension, e.g. `"extract-job"`).
+     * @param payload - Optional JSON-serialisable body sent as POST.
+     * @param options - Optional overrides (method, sub-path, headers).
+     */
+    invoke<T = unknown>(name: string, payload?: unknown, options?: FunctionInvokeOptions): Promise<T>;
+}
+/**
+ * Configuration for entity history / audit-log tracking.
+ *
+ * - `true` — enable history with default settings
+ * - `{ retention?: number }` — enable with optional retention period in days
+ */
+export type HistoryConfig = boolean | {
+    retention?: number;
+};
+/**
+ * Minimal WebSocket client contract exposed on {@link RebaseClient}.
+ *
+ * The full implementation (`RebaseWebSocketClient` in `@rebasepro/client`)
+ * adds subscription helpers, CRUD-over-WS, SQL execution, etc.
+ */
+export interface RebaseWebSocket {
+    /** Disconnect the WebSocket and stop reconnecting. */
+    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. */
+    setAuthTokenGetter(getter: () => Promise<string | null>): void;
+    /** Listen for connection lifecycle events. */
+    on(event: "connect" | "disconnect" | "reconnect" | "error", cb: (...args: unknown[]) => void): () => void;
+}
+/**
+ * The single, canonical Rebase client interface.
+ *
+ * Used everywhere: the server-side `rebase` singleton, the SDK's
+ * `createRebaseClient()`, React context, cron job context, etc.
+ *
+ * Core fields (`data`, `auth`) are always present. Everything else
+ * is optional — which capabilities are populated depends on the
+ * runtime environment and adapter.
  */
 export interface RebaseClient<DB = unknown> {
     /** Unified Data access layer */
-    data: RebaseData;
+    data: RebaseSdkData<DB>;
+    /**
+     * Admin-scoped, **RLS-bypassing** data accessor.
+     *
+     * 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).
+     *
+     * ⚠️ **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.
+     *
+     * Undefined in the browser SDK.
+     */
+    dataAsAdmin?: RebaseSdkData<DB>;
     /** Unified Authentication layer */
     auth: AuthClient;
-    /** Unified Storage layer */
+    /** 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.
+     * The returned source forwards `storageId` to the backend so requests are
+     * routed to the matching `StorageController`. Used to lazily wire
+     * `transport: "server"` sources on the frontend.
+     */
+    createStorageSource?(storageId: string): StorageSource;
+    /**
+     * Discover the storage sources declared on the backend via
+     * `GET /api/storage/sources`. Server-transport sources are auto-registered
+     * into {@link storageRegistry}; `direct` sources are returned so the app
+     * can supply the live {@link StorageSource} instance. The result is cached
+     * (a failed call is retryable). This makes the backend the single source of
+     * truth for storage-source configuration.
+     */
+    fetchStorageSources?(): Promise<StorageSourceDefinition[]>;
     /**
      * Server-side email service.
-     *
-     * Available when SMTP (or a custom `sendEmail` function) is configured
-     * in the backend auth config. `undefined` when email is not configured.
-     *
-     * > **Note:** This is only available on the server-side `rebase` singleton.
-     * > The client-side SDK does not include an email service.
+     * Available when SMTP or a custom `sendEmail` function is configured.
      */
     email?: EmailService;
-    /** Admin API for user and role management */
+    /** 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;
+    /** 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>;
+    /**
+     * Execute raw SQL against the database.
+     * Only available server-side with a SQL database.
+     */
+    sql?(query: string, options?: {
+        database?: string;
+        role?: string;
+    }): Promise<Record<string, unknown>[]>;
+}
+/**
+ * The server-side Rebase surface — the shape of the `rebase` singleton exported
+ * from `@rebasepro/server`.
+ *
+ * Narrows {@link RebaseClient} to the guarantees that always hold on the server:
+ * the admin-scoped {@link dataAsAdmin} accessor, raw {@link sql}, and the
+ * {@link email} service are all present (non-optional).
+ *
+ * **Trust levels.** Both {@link dataAsAdmin} and the deprecated {@link data}
+ * alias point at the same admin-scoped, **RLS-bypassing** driver. Prefer
+ * `dataAsAdmin` so the privilege is explicit at every call site. For user-scoped
+ * queries inside a request handler use the request-scoped driver
+ * (`c.var.driver`) instead — never `dataAsAdmin`/`data`.
+ */
+export interface RebaseServerClient<DB = unknown> extends RebaseClient<DB> {
+    /**
+     * @deprecated On the server, prefer {@link dataAsAdmin} for admin scope or
+     * the request-scoped driver (`c.var.driver`) for user scope. This alias
+     * points at the same admin-scoped, RLS-bypassing accessor as `dataAsAdmin`.
+     */
+    data: RebaseSdkData<DB>;
+    /**
+     * Admin-scoped, **RLS-bypassing** data accessor. Always present server-side.
+     * See {@link RebaseClient.dataAsAdmin} for the full safety contract.
+     */
+    dataAsAdmin: RebaseSdkData<DB>;
+    /**
+     * Server-side email service. Always present server-side (a no-op sender is
+     * wired when SMTP is not configured).
+     */
+    email: EmailService;
+    /**
+     * Execute raw SQL against the database. Always present server-side for SQL
+     * engines.
+     */
+    sql(query: string, options?: {
+        database?: string;
+        role?: string;
+    }): Promise<Record<string, unknown>[]>;
+}
+/**
+ * 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;
+    /** 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.
+ *
+ * Mirrors the server-side `StorageRegistry` pattern. Allows collection
+ * properties to reference a named storage backend via
+ * `StorageConfig.storageSource`.
+ *
+ * @group Models
+ */
+export interface StorageSourceRegistry {
+    /**
+     * Get a storage source by key.
+     * @param key - Storage source key, or undefined/null for default
+     * @returns The StorageSource, or undefined if not found
+     */
+    get(key: string | undefined | null): StorageSource | undefined;
+    /**
+     * Get the default storage source (key = "(default)").
+     * @throws Error if no default storage is registered
+     */
+    getDefault(): StorageSource;
+    /**
+     * Get a storage source by key, with fallback to default.
+     * @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
+     */
+    getOrDefault(key: string | undefined | null): StorageSource;
+    /** Check if a storage source with the given key exists */
+    has(key: string): boolean;
+    /** List all registered storage source keys */
+    list(): string[];
 }

package/dist/controllers/collection_registry.d.ts

@@ -1,17 +1,17 @@
-import type { EntityCollection } from "../types/collections";
+import type { CollectionConfig } from "../types/collections";
 import type { EntityReference } from "../types/entities";
 /**
  * Controller that provides access to the registered entity collections.
  * @group Models
  */
-export type CollectionRegistryController<DB = Record<string, unknown>, EC extends EntityCollection = EntityCollection<any>> = {
+export type CollectionRegistryController<DB = Record<string, unknown>, EC extends CollectionConfig = CollectionConfig> = {
     /**
      * List of the mapped collections in the CMS.
      * Each entry relates to a collection in the root database.
      * Each of the navigation entries in this field
      * generates an entry in the main menu.
      */
-    collections?: EntityCollection[];
+    collections?: CollectionConfig[];
     /**
      * Is the registry ready to be used
      */
@@ -36,7 +36,8 @@ export type CollectionRegistryController<DB = Record<string, unknown>, EC extend
      * Retrieve all the related parent collection ids for a given path
      * @param path
      */
-    getParentCollectionIds: (path: string) => string[];
+    getParentCollectionSlugs: (path: string) => string[];
+    getParentEntityIds: (path: string) => string[];
     /**
      * Resolve paths from a list of ids
      * @param ids

package/dist/controllers/customization_controller.d.ts

@@ -1,4 +1,3 @@
-import React from "react";
 import type { EntityLinkBuilder } from "../types/entity_link_builder";
 import type { Locale } from "../types/locales";
 import type { EntityAction } from "../types/entity_actions";
@@ -6,6 +5,7 @@ import type { EntityCustomView } from "../types/entity_views";
 import type { RebasePlugin } from "../types/plugins";
 import type { PropertyConfig } from "../types/property_config";
 import type { SlotContribution } from "../types/slots";
+import type { ComponentOverrideMap } from "../types/component_overrides";
 export type CustomizationController = {
     /**
      * Builder for generating utility links for entities
@@ -24,7 +24,7 @@ export type CustomizationController = {
      * You can use the key to reference the custom view in
      * the `entityViews` prop of a collection.
      *
-     * You can also define an entity view from the UI.
+     * You can also define a entity view from the UI.
      */
     entityViews?: EntityCustomView[];
     /**
@@ -49,12 +49,13 @@ export type CustomizationController = {
      * the `propertyConfig` prop of a property in a collection.
      */
     propertyConfigs: Record<string, PropertyConfig>;
-    components?: {
-        /**
-         * Component to render when a reference is missing
-         */
-        missingReference?: React.ComponentType<{
-            path: string;
-        }>;
-    };
+    /**
+     * Global component overrides. Keys are component names from
+     * {@link OverridableComponentName}. Values replace the default
+     * implementation everywhere in the app.
+     *
+     * Collection-scoped overrides (set on individual collections)
+     * take precedence over global overrides.
+     */
+    components?: ComponentOverrideMap;
 };