@rebasepro/types 0.7.0 → 0.9.0

package/src/controllers/data_driver.ts

@@ -1,26 +1,26 @@
 import type { CollectionRegistryController } from "./collection_registry";
-import type { Entity, EntityStatus, EntityValues } from "../types/entities";
-import type { EntityCollection, FilterValues } from "../types/collections";
+import type { EntityStatus, EntityValues } from "../types/entities";
+import type { CollectionConfig, FilterValues } from "../types/collections";
 import type { RebaseContext } from "../rebase_context";
 
 
 /**
  * @internal
  */
-export interface FetchEntityProps<M extends Record<string, unknown> = Record<string, unknown>> {
+export interface FetchOneProps<M extends Record<string, unknown> = Record<string, unknown>> {
     path: string;
-    entityId: string | number;
+    id: string | number;
     databaseId?: string;
-    collection?: EntityCollection<M>
+    collection?: CollectionConfig<M>
 }
 
 /**
  * @internal
  */
-export type ListenEntityProps<M extends Record<string, unknown> = Record<string, unknown>> =
-    FetchEntityProps<M>
+export type ListenOneProps<M extends Record<string, unknown> = Record<string, unknown>> =
+    FetchOneProps<M>
     & {
-        onUpdate: (entity: Entity<M> | null) => void,
+        onUpdate: (row: Record<string, unknown> | null) => void,
         onError?: (error: Error) => void,
     }
 
@@ -45,7 +45,7 @@ export interface VectorSearchParams {
  */
 export interface FetchCollectionProps<M extends Record<string, unknown> = Record<string, unknown>> {
     path: string;
-    collection?: EntityCollection<M>;
+    collection?: CollectionConfig<M>;
     filter?: FilterValues<Extract<keyof M, string>>,
     limit?: number;
     offset?: number;
@@ -63,42 +63,50 @@ export interface FetchCollectionProps<M extends Record<string, unknown> = Record
 export type ListenCollectionProps<M extends Record<string, unknown> = Record<string, unknown>> =
     FetchCollectionProps<M> &
     {
-        onUpdate: (entities: Entity<M>[]) => void;
+        onUpdate: (rows: Record<string, unknown>[]) => void;
         onError?: (error: Error) => void;
     };
 
 /**
  * @internal
  */
-export interface SaveEntityProps<M extends Record<string, unknown> = Record<string, unknown>> {
+export interface SaveProps<M extends Record<string, unknown> = Record<string, unknown>> {
     path: string;
     values: Partial<EntityValues<M>>;
-    entityId?: string | number; // can be empty for new entities
+    id?: string | number; // can be empty for new entities
     previousValues?: Partial<EntityValues<M>>;
-    collection?: EntityCollection<M>;
+    collection?: CollectionConfig<M>;
     status: EntityStatus;
 }
 
 /**
  * @internal
  */
-export interface DeleteEntityProps<M extends Record<string, unknown> = Record<string, unknown>> {
-    entity: Entity<M>;
-    collection?: EntityCollection<M>;
+export interface DeleteProps<M extends Record<string, unknown> = Record<string, unknown>> {
+    row: { id: string | number; path: string; values?: Partial<EntityValues<M>> };
+    collection?: CollectionConfig<M>;
 }
 
 export type FilterCombinationValidProps = {
     path: string;
     databaseId?: string;
-    collection: EntityCollection;
+    collection: CollectionConfig;
     filterValues: FilterValues<string>;
     sortBy?: [string, "asc" | "desc"];
 };
 
 /**
- * Internal driver interface for communicating with the data layer.
- * This is NOT the public API — use `RebaseData` / `context.data` instead.
- * @internal
+ * The integration SPI for plugging a data backend into Rebase.
+ *
+ * Implement this interface to connect a custom backend (or use a built-in
+ * driver such as the Firestore one) and register it on
+ * `<Rebase dataSources>`. Rebase wraps drivers via `buildRebaseData` and
+ * routes collections to them by their `dataSource` key.
+ *
+ * For *consuming* data in application code, use `RebaseData` /
+ * `context.data` instead — this interface is only for providing it.
+ *
+ * @group Datasource
  */
 export interface DataDriver {
 
@@ -115,9 +123,9 @@ export interface DataDriver {
     /**
      * Fetch data from a collection
      * @param props
-     * @return Promise of entities
+     * @return Promise of flat rows
      */
-    fetchCollection<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Entity<M>[]>;
+    fetchCollection<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;
 
     /**
      * Listen to a collection in a given path. If you don't implement this method
@@ -128,30 +136,30 @@ export interface DataDriver {
     listenCollection?<M extends Record<string, unknown> = Record<string, unknown>>(props: ListenCollectionProps<M>): () => void;
 
     /**
-     * Retrieve an entity given a path and a collection
+     * Retrieve a single row given a path and a collection
      * @param props
      */
-    fetchEntity<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchEntityProps<M>): Promise<Entity<M> | undefined>;
+    fetchOne<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;
 
     /**
-     * Get realtime updates on one entity.
+     * Get realtime updates on one row.
      * @param props
      * @return Function to cancel subscription
      */
-    listenEntity?<M extends Record<string, unknown> = Record<string, unknown>>(props: ListenEntityProps<M>): () => void;
+    listenOne?<M extends Record<string, unknown> = Record<string, unknown>>(props: ListenOneProps<M>): () => void;
 
     /**
-     * Save entity to the specified path
+     * Save a row to the specified path
      * @param props
      */
-    saveEntity<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveEntityProps<M>): Promise<Entity<M>>;
+    save<M extends Record<string, unknown> = Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>>;
 
     /**
-     * Delete an entity
+     * Delete a entity
      * @param props
      * @return was the whole deletion flow successful
      */
-    deleteEntity<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteEntityProps<M>): Promise<void>;
+    delete<M extends Record<string, unknown> = Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;
 
     /**
      * Delete all entities from a collection.
@@ -164,7 +172,7 @@ export interface DataDriver {
      * @param path Collection path
      * @param name of the property
      * @param value
-     * @param entityId
+     * @param id
      * @param collection
      * @return `true` if there are no other fields besides the given entity
      */
@@ -172,14 +180,14 @@ export interface DataDriver {
         path: string,
         name: string,
         value: unknown,
-        entityId?: string | number,
-        collection?: EntityCollection
+        id?: string | number,
+        collection?: CollectionConfig
     ): Promise<boolean>;
 
     /**
      * Count the number of entities in a collection
      */
-    countEntities?<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;
+    count?<M extends Record<string, unknown> = Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;
 
     /**
      * Check if the given filter combination is valid
@@ -202,7 +210,7 @@ export interface DataDriver {
         context: RebaseContext,
         path: string,
         databaseId?: string,
-        collection: EntityCollection,
+        collection: CollectionConfig,
         parentCollectionSlugs?: string[];
         parentEntityIds?: string[];
     }) => Promise<boolean>;
@@ -216,7 +224,7 @@ export interface DataDriver {
 
     /**
      * Optional REST-optimised fetch service. When present, the REST API
-     * generator uses these methods instead of the generic `fetchEntity` /
+     * generator uses these methods instead of the generic `fetchOne` /
      * `fetchCollection` pipeline, enabling include-aware eager-loading.
      */
     restFetchService?: RestFetchService;
@@ -244,8 +252,9 @@ export interface DataDriver {
  * REST-optimised fetch service exposed by drivers that support
  * eager-loading of relations via `include`.
  *
- * The methods return flattened rows (`{ id, ...columns }`) rather
- * than the `Entity<M>` wrapper used by the generic DataDriver API.
+ * The methods return flattened rows (`{ id, ...columns }`) with
+ * included relations inlined as plain nested rows — the shape served
+ * to app developers through the REST API / SDK client.
  *
  * @group DataDriver
  */
@@ -272,9 +281,9 @@ export interface RestFetchService {
     /**
      * Fetch a single flattened entity with optional relation includes.
      */
-    fetchEntityForRest(
+    fetchOneForRest(
         collectionPath: string,
-        entityId: string | number,
+        id: string | number,
         include?: string[],
         databaseId?: string
     ): Promise<Record<string, unknown> | null>;

package/src/controllers/index.ts

@@ -14,7 +14,7 @@ export * from "./storage";
 export * from "./email";
 export * from "./client";
 export * from "./customization_controller";
-export * from "./side_entity_controller";
+export * from "./side_panel_controller";
 export * from "./side_dialogs_controller";
 export * from "./dialogs_controller";
 export * from "./snackbar";

package/src/controllers/local_config_persistence.tsx

@@ -1,9 +1,9 @@
-import type { EntityCollection } from "../types/collections";
+import type { CollectionConfig } from "../types/collections";
 
 /**
  * @group Models
  */
-export type PartialEntityCollection<M extends Record<string, unknown> = Record<string, unknown>> = Partial<EntityCollection<M>>;
+export type PartialCollectionConfig<M extends Record<string, unknown> = Record<string, unknown>> = Partial<CollectionConfig<M>>;
 
 /**
  * This interface is in charge of defining the controller that persists
@@ -11,8 +11,8 @@ export type PartialEntityCollection<M extends Record<string, unknown> = Record<s
  * a data source, such as local storage or Firestore.
  */
 export interface UserConfigurationPersistence {
-    onCollectionModified: <M extends Record<string, unknown> = Record<string, unknown>>(path: string, partialCollection: PartialEntityCollection<M>) => void;
-    getCollectionConfig: <M extends Record<string, unknown> = Record<string, unknown>>(path: string) => PartialEntityCollection<M>;
+    onCollectionModified: <M extends Record<string, unknown> = Record<string, unknown>>(path: string, partialCollection: PartialCollectionConfig<M>) => void;
+    getCollectionConfig: <M extends Record<string, unknown> = Record<string, unknown>>(path: string) => PartialCollectionConfig<M>;
     recentlyVisitedPaths: string[];
     setRecentlyVisitedPaths: (paths: string[]) => void;
     favouritePaths: string[];

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,10 +1,9 @@
 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";
-import type { RebasePlugin } from "../types/plugins";
 
 /**
  * Options to enable the built-in collection editor.
@@ -22,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.
@@ -35,7 +34,6 @@ export interface RebaseCMSConfig<EC extends EntityCollection = EntityCollection>
     homePage?: ReactNode;
     entityViews?: EntityCustomView[];
     entityActions?: EntityAction[];
-    plugins?: RebasePlugin[];
 
     /**
      * Centralized configuration for how collections and views are grouped
@@ -53,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

@@ -4,8 +4,8 @@
  * Pluggable authentication abstraction for Rebase.
  *
  * An `AuthAdapter` decouples authentication from the database layer,
- * allowing users to bring their own auth system (Clerk, Auth0, Firebase Auth,
- * custom JWT, etc.) while keeping the Rebase admin frontend fully functional.
+ * allowing users to bring their own auth system (Clerk, Auth0, or other
+ * external providers) while keeping the Rebase admin frontend fully functional.
  *
  * @example Built-in auth (default — zero config change)
  * ```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>;
     };
@@ -277,7 +280,7 @@ export interface TransformAuthResponseContext {
  * 4. Advertise its capabilities so the frontend can adapt
  *
  * The built-in Rebase auth implements this interface internally.
- * External providers (Clerk, Auth0, Firebase Auth) provide their own adapters.
+ * External providers (Clerk, Auth0, or others) provide their own adapters.
  * Users with custom auth can use `createCustomAuthAdapter()` for a minimal setup.
  *
  * @group Auth
@@ -286,7 +289,7 @@ export interface AuthAdapter {
     /**
      * Unique identifier for this auth adapter.
      *
-     * @example "rebase-builtin", "clerk", "auth0", "firebase", "custom"
+     * @example "rebase-builtin", "clerk", "auth0", "external-provider", "custom"
      */
     readonly id: string;
 
@@ -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>,
@@ -435,7 +438,7 @@ export interface AuthAdapter {
      * response and returns a (potentially enriched) response.
      *
      * Use cases:
-     * - Inject tokens from external auth systems (Firebase Custom Tokens, etc.)
+     * - Inject tokens from external auth systems (custom provider tokens, etc.)
      * - Add project-specific metadata to the response
      * - Enrich the user object with data from external sources
      *