@rebasepro/types 0.8.0 → 0.9.0

package/src/controllers/navigation.ts

@@ -1,6 +1,6 @@
 import React from "react";
 import type { EntityReference } from "../types/entities";
-import type { EntityCollection } from "../types/collections";
+import type { CollectionConfig } from "../types/collections";
 
 
 /**
@@ -248,7 +248,7 @@ export interface NavigationEntry {
     name: string;
     slug: string;
     type: "collection" | "view" | "admin";
-    collection?: EntityCollection;
+    collection?: CollectionConfig;
     view?: AppView;
     description?: string;
     group: string;

package/src/controllers/registry.ts

@@ -1,6 +1,6 @@
 import { ReactNode } from "react";
-import type { EntityCollection } from "../types/collections";
-import type { EntityCollectionsBuilder, AppViewsBuilder } from "../types/builders";
+import type { CollectionConfig } from "../types/collections";
+import type { CollectionConfigsBuilder, AppViewsBuilder } from "../types/builders";
 import type { EntityCustomView } from "../types/entity_views";
 import type { EntityAction } from "../types/entity_actions";
 import type { AppView, NavigationGroupMapping } from "./navigation";
@@ -21,8 +21,8 @@ export interface CollectionEditorOptions {
     pathSuggestions?: string[];
 }
 
-export interface RebaseCMSConfig<EC extends EntityCollection = EntityCollection> {
-    collections?: EC[] | EntityCollectionsBuilder<EC>;
+export interface RebaseCMSConfig<EC extends CollectionConfig = CollectionConfig> {
+    collections?: EC[] | CollectionConfigsBuilder<EC>;
 
     /**
      * Custom top-level views added to the main navigation.
@@ -51,6 +51,20 @@ export interface RebaseCMSConfig<EC extends EntityCollection = EntityCollection>
      * are all auto-wired — no plugin or manual view injection needed.
      */
     collectionEditor?: boolean | CollectionEditorOptions;
+
+    /**
+     * URL path prefix the admin is mounted under, when it does not live at the
+     * site root. Set this when the admin is rendered inside a path-prefixed
+     * route (e.g. `<Route path="/admin/*">`) so URL⇄collection resolution
+     * accounts for the prefix — otherwise the current path won't be recognized
+     * as a collection path and views hang on a spinner with no data fetch.
+     *
+     * Do NOT set this when mounting via a react-router `basename` — react-router
+     * already strips the prefix from the location, so the default (`/`) is correct.
+     *
+     * @default "/"
+     */
+    basePath?: string;
 }
 
 export interface RebaseStudioConfig {

package/src/controllers/{side_entity_controller.tsx → side_panel_controller.tsx}

@@ -1,11 +1,11 @@
 import type { Entity } from "../types/entities";
-import type { EntityCollection } from "../types/collections";
+import type { CollectionConfig } from "../types/collections";
 
 /**
  * Props used to open a side dialog
  * @group Hooks and utilities
  */
-export interface EntitySidePanelProps<M extends Record<string, unknown> = Record<string, unknown>> {
+export interface SidePanelBindingProps<M extends Record<string, unknown> = Record<string, unknown>> {
 
     /**
      * Absolute path of the entity
@@ -38,7 +38,7 @@ export interface EntitySidePanelProps<M extends Record<string, unknown> = Record
      * Collection representing the entities of this view.
      * If you leave it blank it will be induced by your navigation
      */
-    collection?: EntityCollection<M>;
+    collection?: CollectionConfig<M>;
 
     /**
      * Should update the URL when opening the dialog.
@@ -87,7 +87,7 @@ export interface EntitySidePanelProps<M extends Record<string, unknown> = Record
  * Controller to open the side dialog displaying entity forms
  * @group Hooks and utilities
  */
-export interface SideEntityController {
+export interface SidePanelController {
     /**
      * Close the last panel
      */
@@ -98,15 +98,15 @@ export interface SideEntityController {
      * of the view is fetched from the collections you have specified in the
      * navigation.
      * At least you need to pass the path of the entity you would like
-     * to edit. You can set an entityId if you would like to edit and existing one
+     * to edit. You can set a entityId if you would like to edit and existing one
      * (or a new one with that id).
      * @param props
      */
-    open: <M extends Record<string, unknown> = Record<string, unknown>>(props: EntitySidePanelProps<M>) => void;
+    open: <M extends Record<string, unknown> = Record<string, unknown>>(props: SidePanelBindingProps<M>) => void;
 
     /**
      * Replace the last open entity panel with the given one.
      * @param props
      */
-    replace: <M extends Record<string, unknown> = Record<string, unknown>>(props: EntitySidePanelProps<M>) => void;
+    replace: <M extends Record<string, unknown> = Record<string, unknown>>(props: SidePanelBindingProps<M>) => void;
 }

package/src/controllers/storage.ts

@@ -1,3 +1,40 @@
+/**
+ * Path prefix that marks an object as **public**. Files stored under this
+ * prefix are served without any auth token via a stable, permanent,
+ * CDN-cacheable URL (see {@link StorageSource.getSignedUrl}). Shared by the
+ * client SDK and the backend so both agree on which objects are public.
+ *
+ * @group Models
+ */
+export const PUBLIC_STORAGE_PREFIX = "public/";
+
+/**
+ * True when a storage key/path points at a public object (lives under
+ * {@link PUBLIC_STORAGE_PREFIX}). The check is applied to the key *within the
+ * bucket* — strip any `bucket/` and `scheme://` prefixes first.
+ *
+ * @group Models
+ */
+export function isPublicStoragePath(path: string | null | undefined): boolean {
+    if (!path) return false;
+    let p = path;
+    const scheme = p.indexOf("://");
+    if (scheme !== -1) p = p.substring(scheme + 3);
+    p = p.replace(/^\/+/, "");
+
+    // Defense-in-depth: a path containing traversal segments is never public,
+    // so an attacker can't reach a private object via `public/../secret`.
+    if (p.split("/").some((seg) => seg === "..")) return false;
+
+    // Public iff the object **key** starts with the public prefix. A single
+    // leading `default/` bucket segment is tolerated (the default bucket).
+    // A substring match is deliberately NOT used — a private object under a
+    // folder literally named `public` (e.g. `reports/public/q3.pdf`) must stay
+    // private. Named buckets: pass the key (not `bucket/key`) so the prefix is
+    // anchored; otherwise it falls back to a private, token-scoped URL (safe).
+    return p.startsWith(PUBLIC_STORAGE_PREFIX) || p.startsWith(`default/${PUBLIC_STORAGE_PREFIX}`);
+}
+
 /**
  * @group Models
  */
@@ -5,7 +42,14 @@ export interface UploadFileProps {
     file: File,
     key: string,
     metadata?: Record<string, unknown>,
-    bucket?: string
+    bucket?: string,
+    /**
+     * Store this object as **public**: it is placed under
+     * {@link PUBLIC_STORAGE_PREFIX} and served via a stable, token-less,
+     * permanent URL (safe to persist in a database and cache on a CDN).
+     * Defaults to `false` (private, short-lived signed URLs).
+     */
+    public?: boolean
 }
 
 /**
@@ -74,6 +118,21 @@ export declare interface DownloadMetadata {
     contentType: string;
 
     customMetadata: Record<string, unknown>;
+    /**
+     * Optional short-lived download token (for local/server-mediated storage).
+     * Absent for public objects, which need no token.
+     */
+    token?: string;
+    /**
+     * Optional remaining lifetime of the token, in seconds.
+     */
+    tokenExpiresIn?: number;
+    /**
+     * True when this object is public: it is served without a token via a
+     * stable, permanent, CDN-cacheable URL. When set, the client builds a
+     * token-less URL and caches it indefinitely.
+     */
+    public?: boolean;
 }
 
 /**

package/src/errors.ts

@@ -0,0 +1,80 @@
+/**
+ * Structured initializer for {@link RebaseApiError}.
+ *
+ * @group Errors
+ */
+export interface RebaseErrorInit {
+    /**
+     * HTTP status code, when the error originated from an HTTP response.
+     * Left `undefined` for realtime/WebSocket, network, and client-side
+     * logic errors that have no HTTP status.
+     */
+    status?: number;
+    /** Stable, machine-readable error code (e.g. `"NOT_FOUND"`, `"BAD_REQUEST"`). */
+    code?: string;
+    /** Structured error payload returned by the server, when present. */
+    details?: unknown;
+    /** The underlying error this one wraps, if any. */
+    cause?: unknown;
+}
+
+/**
+ * The single error type thrown across the entire Rebase client surface —
+ * HTTP data/control-plane calls, realtime/WebSocket operations, and
+ * client-side logic errors (e.g. an unknown collection accessor). A `catch`
+ * block only ever needs to check for this one class:
+ *
+ * ```ts
+ * import { RebaseApiError } from "@rebasepro/client"; // re-exported
+ *
+ * try {
+ *   await client.data.products.update(id, { price: 9 });
+ * } catch (e) {
+ *   if (e instanceof RebaseApiError) {
+ *     if (e.status === 404) { ... }   // HTTP failures carry a status
+ *     console.error(e.code, e.details);
+ *   }
+ * }
+ * ```
+ *
+ * `status` is present for HTTP failures and `undefined` otherwise, so its
+ * presence distinguishes transport-level errors from realtime/logic errors.
+ *
+ * @group Errors
+ */
+export class RebaseApiError extends Error {
+    /** HTTP status code, or `undefined` for non-HTTP errors. */
+    readonly status?: number;
+    /** Stable machine-readable error code, when the server supplied one. */
+    readonly code?: string;
+    /** Structured error payload from the server, when present. */
+    readonly details?: unknown;
+
+    constructor(message: string, init: RebaseErrorInit = {}) {
+        super(message);
+        this.name = "RebaseApiError";
+        this.status = init.status;
+        this.code = init.code;
+        this.details = init.details;
+        if (init.cause !== undefined) {
+            // `cause` is standard on Error but not always in the lib target's type.
+            (this as { cause?: unknown }).cause = init.cause;
+        }
+    }
+}
+
+/**
+ * Client-side logic error — raised before any request is made (e.g. accessing
+ * an unknown collection accessor when a typed dictionary is configured).
+ *
+ * A subclass of {@link RebaseApiError} (with no `status`), so a single
+ * `catch (e) { if (e instanceof RebaseApiError) ... }` handles it too.
+ *
+ * @group Errors
+ */
+export class RebaseClientError extends RebaseApiError {
+    constructor(message: string) {
+        super(message);
+        this.name = "RebaseClientError";
+    }
+}

package/src/index.ts

@@ -1,3 +1,4 @@
+export * from "./errors";
 export * from "./rebase_context";
 export * from "./types";
 export * from "./controllers";

package/src/rebase_context.tsx

@@ -5,7 +5,7 @@ import type { UserConfigurationPersistence } from "./controllers/local_config_pe
 import type { DatabaseAdmin } from "./types/backend";
 import type { RebaseClient } from "./controllers/client";
 
-import type { RebaseData } from "./controllers/data";
+import type { RebaseSdkData } from "./controllers/data";
 import type { User } from "./users";
 
 
@@ -36,8 +36,12 @@ 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`).
      */
-    data: RebaseData;
+    data: RebaseSdkData;
 
     /**
      * Used storage implementation
@@ -77,9 +81,9 @@ export type RebaseContext<USER extends User = User, AuthControllerType extends A
     sideDialogsController?: import("./controllers/side_dialogs_controller").SideDialogsController;
 
     /**
-     * Controller to open the side dialog displaying entity forms
+     * Controller to open the side panel displaying entity forms
      */
-    sideEntityController?: import("./controllers/side_entity_controller").SideEntityController;
+    sidePanelController?: import("./controllers/side_panel_controller").SidePanelController;
 
     /**
      * Controller resolving URLs in the CMS

package/src/types/auth_adapter.ts

@@ -237,6 +237,9 @@ export interface AuthResponsePayload {
         email: string;
         displayName: string | null;
         photoURL: string | null;
+        providerId?: string;
+        isAnonymous?: boolean;
+        emailVerified?: boolean;
         roles: string[];
         metadata: Record<string, unknown>;
     };
@@ -393,7 +396,7 @@ export interface AuthAdapter {
      *
      * @param values - Raw request body from the client.
      * @param collectionAuth - The parsed `AuthCollectionConfig` from the collection (if `auth` is an object).
-     * @returns Processed values ready for `driver.saveEntity()`, plus metadata for the post-save step.
+     * @returns Processed values ready for `driver.save()`, plus metadata for the post-save step.
      */
     prepareUserCreation?(
         values: Record<string, unknown>,

package/src/types/backend.ts

@@ -1,6 +1,6 @@
-import type { Entity } from "./entities";
-import type { EntityCollection, FilterValues, WhereFilterOp } from "./collections";
+import type { CollectionConfig, FilterValues, WhereFilterOp } from "./collections";
 import type { AuthAdapter } from "./auth_adapter";
+import type { HistoryConfig } from "../controllers/client";
 
 // =============================================================================
 // DATABASE CONNECTION INTERFACES
@@ -52,7 +52,7 @@ export interface FetchCollectionOptions<M extends Record<string, unknown> = Reco
     startAfter?: unknown;
     searchString?: string;
     databaseId?: string;
-    collection?: EntityCollection;
+    collection?: CollectionConfig;
 }
 
 /**
@@ -64,7 +64,7 @@ export interface SearchOptions<M extends Record<string, unknown> = Record<string
     order?: "desc" | "asc";
     limit?: number;
     databaseId?: string;
-    collection?: EntityCollection;
+    collection?: CollectionConfig;
 }
 
 /**
@@ -150,15 +150,15 @@ export type ConditionBuilderStatic<T = unknown> = {
  * - Relation resolution
  * - ID generation and conversion
  */
-export interface EntityRepository {
+export interface DataRepository {
     /**
      * Fetch a single entity by ID
      */
-    fetchEntity<M extends Record<string, unknown>>(
+    fetchOne<M extends Record<string, unknown>>(
         collectionPath: string,
-        entityId: string | number,
+        id: string | number,
         databaseId?: string
-    ): Promise<Entity<M> | undefined>;
+    ): Promise<Record<string, unknown> | undefined>;
 
     /**
      * Fetch a collection of entities with optional filtering, ordering, and pagination
@@ -166,41 +166,41 @@ export interface EntityRepository {
     fetchCollection<M extends Record<string, unknown>>(
         collectionPath: string,
         options?: FetchCollectionOptions<M>
-    ): Promise<Entity<M>[]>;
+    ): Promise<Record<string, unknown>[]>;
 
     /**
      * Search entities by text
      */
-    searchEntities<M extends Record<string, unknown>>(
+    searchRows<M extends Record<string, unknown>>(
         collectionPath: string,
         searchString: string,
         options?: SearchOptions<M>
-    ): Promise<Entity<M>[]>;
+    ): Promise<Record<string, unknown>[]>;
 
     /**
      * Count entities in a collection
      */
-    countEntities<M extends Record<string, unknown>>(
+    count<M extends Record<string, unknown>>(
         collectionPath: string,
         options?: CountOptions<M>
     ): Promise<number>;
 
     /**
-     * Save an entity (create or update)
+     * Save a entity (create or update)
      */
-    saveEntity<M extends Record<string, unknown>>(
+    save<M extends Record<string, unknown>>(
         collectionPath: string,
         values: Partial<M>,
-        entityId?: string | number,
+        id?: string | number,
         databaseId?: string
-    ): Promise<Entity<M>>;
+    ): Promise<Record<string, unknown>>;
 
     /**
-     * Delete an entity by ID
+     * Delete a entity by ID
      */
-    deleteEntity(
+    delete(
         collectionPath: string,
-        entityId: string | number,
+        id: string | number,
         databaseId?: string
     ): Promise<void>;
 
@@ -239,10 +239,10 @@ export interface CollectionSubscriptionConfig {
 /**
  * Configuration for subscribing to a single entity
  */
-export interface EntitySubscriptionConfig {
+export interface SingleSubscriptionConfig {
     clientId: string;
     path: string;
-    entityId: string | number;
+    id: string | number;
 }
 
 /**
@@ -256,16 +256,16 @@ export interface RealtimeProvider {
     subscribeToCollection(
         subscriptionId: string,
         config: CollectionSubscriptionConfig,
-        callback?: (entities: Entity[]) => void
+        callback?: (rows: Record<string, unknown>[]) => void
     ): void;
 
     /**
      * Subscribe to single entity changes
      */
-    subscribeToEntity(
+    subscribeToOne(
         subscriptionId: string,
-        config: EntitySubscriptionConfig,
-        callback?: (entity: Entity | null) => void
+        config: SingleSubscriptionConfig,
+        callback?: (row: Record<string, unknown> | null) => void
     ): void;
 
     /**
@@ -274,12 +274,12 @@ export interface RealtimeProvider {
     unsubscribe(subscriptionId: string): void;
 
     /**
-     * Notify all relevant subscribers of an entity update
+     * Notify all relevant subscribers of a entity update
      */
-    notifyEntityUpdate(
+    notifyUpdate(
         path: string,
-        entityId: string,
-        entity: Entity | null,
+        id: string,
+        row: Record<string, unknown> | null,
         databaseId?: string
     ): Promise<void>;
 
@@ -314,17 +314,17 @@ export interface CollectionRegistryInterface {
     /**
      * Register a collection
      */
-    register(collection: EntityCollection): void;
+    register(collection: CollectionConfig): void;
 
     /**
      * Get a collection by its path
      */
-    getCollectionByPath(path: string): EntityCollection | undefined;
+    getCollectionByPath(path: string): CollectionConfig | undefined;
 
     /**
      * Get all registered collections
      */
-    getCollections(): EntityCollection[];
+    getCollections(): CollectionConfig[];
 
     /**
      * Get the currently registered global callbacks, if any.
@@ -346,7 +346,7 @@ export interface DataTransformer {
      */
     serializeToDatabase<M extends Record<string, unknown>>(
         entity: M,
-        collection: EntityCollection
+        collection: CollectionConfig
     ): Record<string, unknown>;
 
     /**
@@ -354,7 +354,7 @@ export interface DataTransformer {
      */
     deserializeFromDatabase<M extends Record<string, unknown>>(
         data: Record<string, unknown>,
-        collection: EntityCollection
+        collection: CollectionConfig
     ): Promise<M>;
 }
 
@@ -589,7 +589,7 @@ export interface BackendInstance extends BackendLifecycle {
     /**
      * Entity repository for CRUD operations
      */
-    entityRepository: EntityRepository;
+    entityRepository: DataRepository;
 
     /**
      * Realtime provider for subscriptions
@@ -697,7 +697,7 @@ export interface BackendBootstrapper {
      * Initialize history tables / services if this driver supports them.
      * Return undefined if history is not supported by this backend.
      */
-    initializeHistory?(config: unknown, driverResult: InitializedDriver): Promise<{ historyService: unknown } | undefined>;
+    initializeHistory?(config: HistoryConfig, driverResult: InitializedDriver): Promise<{ historyService: unknown } | undefined>;
 
     /**
      * Create a realtime provider for this driver.

package/src/types/builders.ts

@@ -1,10 +1,10 @@
 import type { AuthController } from "../controllers/auth";
 import type { RebaseData } from "../controllers/data";
 import type { User } from "../users";
-import type { EntityCollection } from "./collections";
+import type { CollectionConfig } from "./collections";
 import type { AppView } from "../controllers/navigation";
 
-export type EntityCollectionsBuilder<EC extends EntityCollection = EntityCollection> = (params: {
+export type CollectionConfigsBuilder<EC extends CollectionConfig = CollectionConfig> = (params: {
     user: User | null,
     authController: AuthController,
     data: RebaseData