@rebasepro/client 0.7.0 → 0.9.0

package/src/index.ts

@@ -1,33 +1,99 @@
 import { createTransport, RebaseClientConfig } from "./transport";
+import { RebaseClientError } from "./errors";
 import { createAuth, CreateAuthOptions } from "./auth";
 import { createAdmin, CreateAdminOptions } from "./admin";
 import { createCron, CreateCronOptions } from "./cron";
 import { createApiKeys, CreateApiKeysOptions } from "./api-keys";
-import { createCollectionClient, CollectionClient } from "./collection";
+import { CollectionClient, createCollectionClient } from "./collection";
 import { createFunctionsClient } from "./functions";
 import { createStorage } from "./storage";
+import { ClientStorageSourceRegistry } from "./storage-registry";
 import { RebaseWebSocketClient } from "./websocket";
-import { RebaseClient, RebaseData, StorageSource } from "@rebasepro/types";
+import {
+    DEFAULT_STORAGE_SOURCE_KEY,
+    InsertOf,
+    RebaseClient,
+    RebaseSdkData,
+    RowOf,
+    StorageSource,
+    StorageSourceDefinition,
+    StorageSourceRegistry,
+    UpdateOf
+} from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 
-export * from "./transport";
-export * from "./auth";
-export * from "./admin";
-export * from "./cron";
-export * from "./api-keys";
-export * from "./collection";
-export * from "./query_builder";
-export * from "./websocket";
-export * from "./storage";
-export * from "./reviver";
-export * from "./functions";
-export type { Entity, FindResponse } from "@rebasepro/types";
+// ─── Public API surface ──────────────────────────────────────────────────────
+//
+// This barrel is the public API of `@rebasepro/client`. It is an explicit,
+// curated list — NOT `export *` — so that adding an export to a module below
+// does not silently republish it to app developers. Internal factories
+// (`createTransport`, `createAuth`, `createCollectionClient`, …), the raw
+// `Transport`, the storage-source registry impl, the JSON reviver, and the
+// concrete `SDKQueryBuilder` class are intentionally NOT re-exported: they are
+// implementation details of `createRebaseClient()` and have no external
+// consumers. App developers reach them through the client instance, never by
+// importing the factory. To add something to the public surface, add it here
+// deliberately.
+
+// Errors — the single error type thrown by SDK HTTP calls, plus the
+// data-proxy's unknown-collection error.
+export { RebaseApiError } from "./transport";
+export { RebaseClientError } from "./errors";
+
+// Query + collection types (annotate SDK results; construct via the fluent API).
+export type { RebaseClientConfig, FindParams, FindResponse } from "./transport";
+export type { CollectionClient } from "./collection";
+export type { FindResult, SDKCollectionClient, SDKQueryBuilderInterface, PaginationMeta } from "@rebasepro/types";
+
+// Logical-condition helpers for `.where(or(...), and(...))`.
+export { QueryBuilder, or, and, cond } from "@rebasepro/common";
+
+// Auth: session/token types, config, and the pluggable storage strategies.
+export { createCookieStorage, createMemoryStorage } from "./auth";
+export type { AuthConfig, AuthStorage, CookieStorageOptions, CreateAuthOptions } from "./auth";
+export type { RebaseSession, AuthTokens, AuthChangeEvent, DeviceSession } from "@rebasepro/types";
+/** @deprecated Import `User` / `AuthTokens` from `@rebasepro/types` instead. */
+export type { RebaseUser, RebaseTokens } from "./auth";
+
+// Control-plane client option/DTO types (the client instance exposes the impls).
+export type { CreateAdminOptions } from "./admin";
+export type { AdminUser } from "./admin";
+export type { CreateCronOptions } from "./cron";
+export type {
+    ApiKeyMasked,
+    ApiKeyPermission,
+    ApiKeyWithSecret,
+    CreateApiKeyRequest,
+    CreateApiKeysOptions,
+    UpdateApiKeyRequest
+} from "./api-keys";
+export type { FunctionInvokeOptions, FunctionsClient } from "./functions";
+
+// Realtime: the WebSocket client class is internal to `createRebaseClient()`,
+// but re-exported (see @internal on the class) because the `client-postgresql`
+// driver constructs it directly. Not a stable app-facing API.
+export { RebaseWebSocketClient } from "./websocket";
 
 export interface CreateRebaseClientOptions extends RebaseClientConfig {
     auth?: CreateAuthOptions;
     admin?: CreateAdminOptions;
     cron?: CreateCronOptions;
     apiKeys?: CreateApiKeysOptions;
+    /**
+     * Declared storage sources for multi-backend support. Server-transport
+     * entries are auto-wired into `client.storageRegistry`; `direct` sources
+     * are registered app-side (e.g. via a Firebase Storage hook). The default
+     * source (`storage`) is always registered under
+     * {@link DEFAULT_STORAGE_SOURCE_KEY}.
+     */
+    storageSources?: StorageSourceDefinition[];
+    /**
+     * Maps camelCase property names / safe identifiers to the actual
+     * collection slugs on the server (e.g. `{ companyMembers: "company-members" }`).
+     * If provided, the data layer proxy will resolve property accessors to their
+     * correct slugs via this map before falling back to automatic snake_casing.
+     */
+    collections?: Record<string, string>;
 }
 
 // ─── Typed Data Proxy ────────────────────────────────────────────────────────
@@ -38,17 +104,21 @@ type KebabToCamelCase<S extends string> =
     ? `${T}${Capitalize<KebabToCamelCase<U>>}`
     : S;
 
+// Resolve a generated `Database` entry from a (kebab-case) slug literal,
+// or `unknown` when the slug isn't in the schema — the extractors below
+// then fall back to the open row / partial shapes.
+type DBEntry<DB, S extends string> =
+    KebabToCamelCase<S> extends keyof DB ? DB[KebabToCamelCase<S>] : unknown;
+
 type TypedDataLayer<DB> = {
     collection<S extends string>(slug: S): CollectionClient<
-        KebabToCamelCase<S> extends keyof DB
-            ? (DB[KebabToCamelCase<S>] extends { Row: infer R extends Record<string, unknown> } ? R : Record<string, unknown>)
-            : Record<string, unknown>
+        RowOf<DBEntry<DB, S>>,
+        InsertOf<DBEntry<DB, S>>,
+        UpdateOf<DBEntry<DB, S>>
     >;
 } & {
-    [K in keyof DB]: CollectionClient<
-        DB[K] extends { Row: infer R extends Record<string, unknown> } ? R : Record<string, unknown>
-    >;
-} & RebaseData;
+    [K in keyof DB]: CollectionClient<RowOf<DB[K]>, InsertOf<DB[K]>, UpdateOf<DB[K]>>;
+} & RebaseSdkData;
 
 /**
  * The return type of `createRebaseClient<DB>()`.
@@ -57,7 +127,7 @@ type TypedDataLayer<DB> = {
  * capabilities populated and the `data` layer narrowed to provide
  * typed collection accessors when a `DB` schema generic is supplied.
  */
-export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<RebaseClient, "data"> & {
+export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<RebaseClient<DB>, "data" | "email"> & {
     setToken: (token: string | null) => void;
     setAuthTokenGetter: (getter: () => Promise<string | null>) => void;
     setOnUnauthorized: (handler: () => Promise<boolean>) => void;
@@ -69,6 +139,9 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
     functions: ReturnType<typeof createFunctionsClient>;
     ws?: RebaseWebSocketClient;
     storage: StorageSource;
+    storageRegistry: StorageSourceRegistry;
+    createStorageSource: (storageId: string) => StorageSource;
+    fetchStorageSources: () => Promise<StorageSourceDefinition[]>;
     call: <T = unknown>(endpoint: string, payload?: unknown) => Promise<T>;
     data: TypedDataLayer<DB>;
 };
@@ -118,6 +191,48 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
     const storage = createStorage(transport);
     const functions = createFunctionsClient(transport);
 
+    // Build a server-backed StorageSource for a given storage-source key.
+    const createStorageSource = (storageId: string): StorageSource =>
+        storageId === DEFAULT_STORAGE_SOURCE_KEY ? storage : createStorage(transport, storageId);
+
+    // Storage registry: always holds the default source, plus any declared
+    // server-transport sources. `direct` sources are registered app-side.
+    const storageRegistry = new ClientStorageSourceRegistry();
+    storageRegistry.register(DEFAULT_STORAGE_SOURCE_KEY, storage);
+    for (const def of options.storageSources ?? []) {
+        if (def.transport === "server" && def.key !== DEFAULT_STORAGE_SOURCE_KEY) {
+            storageRegistry.register(def.key, createStorageSource(def.key));
+        }
+    }
+
+    // Discover storage sources from the backend, making the server the single
+    // source of truth. Server-transport sources are auto-wired into the
+    // registry; `direct` sources are returned for the app to register. The
+    // promise is cached on success and reset on failure so it can be retried
+    // (e.g. once the user authenticates).
+    let storageSourcesPromise: Promise<StorageSourceDefinition[]> | undefined;
+    const fetchStorageSources = (): Promise<StorageSourceDefinition[]> => {
+        if (storageSourcesPromise) return storageSourcesPromise;
+        storageSourcesPromise = transport
+            .request<{ data: StorageSourceDefinition[] }>("/storage/sources")
+            .then((res) => {
+                const defs = res.data ?? [];
+                for (const def of defs) {
+                    if (def.transport === "server"
+                        && def.key !== DEFAULT_STORAGE_SOURCE_KEY
+                        && !storageRegistry.has(def.key)) {
+                        storageRegistry.register(def.key, createStorageSource(def.key));
+                    }
+                }
+                return defs;
+            })
+            .catch((e) => {
+                storageSourcesPromise = undefined; // allow retry
+                throw e;
+            });
+        return storageSourcesPromise;
+    };
+
     const resolvedWsUrl = options.websocketUrl ?? deriveWebSocketUrl(options.baseUrl);
 
     let ws: RebaseWebSocketClient | undefined;
@@ -172,7 +287,62 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         });
     }
 
+    /**
+     * Suggest the closest known collection key for a mistyped accessor.
+     * Uses edit-distance-1 and prefix matching — no external dependency.
+     */
+    function suggestCollection(prop: string, knownKeys: string[]): string | undefined {
+        // Prefix match (e.g. "prod" → "products")
+        const prefixMatch = knownKeys.find(k => k.startsWith(prop) || prop.startsWith(k));
+        if (prefixMatch) return prefixMatch;
+
+        // Edit-distance-1: deletions, insertions, substitutions, transpositions
+        for (const key of knownKeys) {
+            if (Math.abs(key.length - prop.length) > 1) continue;
+            let diffs = 0;
+            const longer = key.length >= prop.length ? key : prop;
+            const shorter = key.length >= prop.length ? prop : key;
+            if (longer.length === shorter.length) {
+                // Same length: allow 1 substitution or 1 transposition
+                for (let i = 0; i < longer.length; i++) {
+                    if (longer[i] !== shorter[i]) {
+                        // Check for transposition
+                        if (
+                            i + 1 < longer.length &&
+                            longer[i] === shorter[i + 1] &&
+                            longer[i + 1] === shorter[i]
+                        ) {
+                            diffs++;
+                            i++; // skip next char (already accounted for)
+                            if (diffs > 1) break;
+                            continue;
+                        }
+                        diffs++;
+                    }
+                    if (diffs > 1) break;
+                }
+            } else {
+                // Length differs by 1: allow 1 insertion/deletion
+                let li = 0;
+                let si = 0;
+                while (li < longer.length) {
+                    if (si < shorter.length && longer[li] === shorter[si]) {
+                        si++;
+                    } else {
+                        diffs++;
+                    }
+                    li++;
+                    if (diffs > 1) break;
+                }
+            }
+            if (diffs <= 1) return key;
+        }
+
+        return undefined;
+    }
+
     const collectionClients = new Map<string, CollectionClient<Record<string, unknown>>>();
+    let untypedWarned = false;
 
     function collection(slug: string): CollectionClient<Record<string, unknown>> {
         if (!collectionClients.has(slug)) {
@@ -190,8 +360,30 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
             }
             if (typeof prop === "symbol") return undefined;
             if (typeof prop === "string" && prop !== "then" && prop !== "toJSON" && prop !== "$$typeof") {
-                // Convert camelCase property names to snake_case slugs.
+                if (options.collections) {
+                    if (prop in options.collections) {
+                        return collection(options.collections[prop]);
+                    }
+                    // Strict mode: the developer supplied a typed dictionary,
+                    // so we know the full set of valid accessors.
+                    const knownKeys = Object.keys(options.collections);
+                    const suggestion = suggestCollection(prop, knownKeys);
+                    const knownList = knownKeys.join(", ");
+                    let msg = `Unknown collection accessor "${prop}". Known collections: ${knownList}.`;
+                    if (suggestion) msg += ` Did you mean "${suggestion}"?`;
+                    msg += ` Use data.collection("<slug>") for dynamic slugs.`;
+                    throw new RebaseClientError(msg);
+                }
+                // Untyped fallback: convert camelCase property names to snake_case slugs.
                 // e.g. `companyMembers` → `company_members`
+                if (!untypedWarned) {
+                    untypedWarned = true;
+                    console.warn(
+                        `[Rebase] Untyped data access detected (client.data.${prop}). ` +
+                        `Collection names are resolved via snake_case conversion, which may cause silent 404s at request time. ` +
+                        `Pass a \`collections\` dictionary to createRebaseClient() or use the generated SDK for type-safe access.`
+                    );
+                }
                 const slug = toSnakeCase(prop);
                 return collection(slug);
             }
@@ -206,6 +398,9 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         apiKeys,
         functions,
         storage,
+        storageRegistry,
+        createStorageSource,
+        fetchStorageSources,
         ws,
         setToken: transport.setToken,
         setAuthTokenGetter: transport.setAuthTokenGetter,
@@ -222,7 +417,6 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
             return res.data ?? (res as T);
         },
         data: dataProxy,
-        email: undefined
     } as unknown as CreateRebaseClientResult<DB>;
 
     return target;

package/src/reviver.ts

@@ -1,4 +1,4 @@
-import { EntityReference, EntityRelation, GeoPoint, Vector, Entity } from "@rebasepro/types";
+import { EntityReference, EntityRelation, GeoPoint, Vector } from "@rebasepro/types";
 
 export function rebaseReviver(_key: string, value: unknown): unknown {
     if (value && typeof value === "object" && "__type" in value) {
@@ -25,7 +25,7 @@ export function rebaseReviver(_key: string, value: unknown): unknown {
                 return new EntityRelation(
                     record.id as string | number,
                     record.path as string,
-                    record.data as Entity | undefined
+                    record.data as Record<string, unknown> | undefined
                 );
             case "GeoPoint":
                 return new GeoPoint(record.latitude as number, record.longitude as number);

package/src/sdk_query_builder.ts

@@ -0,0 +1,138 @@
+import {
+    FindParams,
+    FindResult,
+    LogicalCondition,
+    SDKCollectionClient,
+    SDKQueryBuilderInterface,
+    WhereFilterOp,
+    WhereValue
+} from "@rebasepro/types";
+
+/**
+ * SDK Query Builder — returns flat rows (`FindResult<M>`) instead of
+ * Entity-wrapped results (`FindResponse<M>`).
+ *
+ * @example
+ * const { data } = await rebase.data.posts
+ *     .where("status", "==", "published")
+ *     .orderBy("created_at", "desc")
+ *     .limit(10)
+ *     .find();
+ *
+ * console.log(data[0].title); // flat access
+ */
+export class SDKQueryBuilder<M extends Record<string, unknown> = Record<string, unknown>> implements SDKQueryBuilderInterface<M> {
+    private params: FindParams = { where: {} };
+
+    constructor(private collection: SDKCollectionClient<M>) {}
+
+    /**
+     * Add a filter condition to your query.
+     * @example
+     * client.data.users.where('age', '>=', 18).find()
+     */
+    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where(logicalCondition: LogicalCondition): this;
+    where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown): this {
+        if (typeof columnOrCondition === "object" && columnOrCondition !== null && "type" in columnOrCondition) {
+            this.params.logical = columnOrCondition as LogicalCondition;
+            return this;
+        }
+
+        if (!this.params.where) {
+            this.params.where = {};
+        }
+
+        const column = columnOrCondition as string;
+        const condition: [WhereFilterOp, unknown] = [operator!, value];
+        const existing = this.params.where[column];
+
+        if (existing === undefined) {
+            this.params.where[column] = condition;
+        } else if (Array.isArray(existing) && existing.length > 0 && Array.isArray(existing[0])) {
+            (this.params.where[column] as [WhereFilterOp, unknown][]).push(condition);
+        } else {
+            let firstCondition: [WhereFilterOp, unknown];
+            if (Array.isArray(existing) && existing.length === 2 && typeof existing[0] === "string") {
+                firstCondition = existing as [WhereFilterOp, unknown];
+            } else {
+                firstCondition = ["==", existing];
+            }
+            this.params.where[column] = [firstCondition, condition];
+        }
+
+        return this;
+    }
+
+    /**
+     * Order the results by a specific column.
+     */
+    orderBy(column: keyof M & string, direction: "asc" | "desc" = "asc"): this {
+        this.params.orderBy = [column, direction];
+        return this;
+    }
+
+    /**
+     * Limit the number of results returned.
+     */
+    limit(count: number): this {
+        this.params.limit = count;
+        return this;
+    }
+
+    /**
+     * Skip the first N results.
+     */
+    offset(count: number): this {
+        this.params.offset = count;
+        return this;
+    }
+
+    /**
+     * Set a free-text search string if supported by the backend.
+     */
+    search(searchString: string): this {
+        this.params.searchString = searchString;
+        return this;
+    }
+
+    /**
+     * Include related entities in the response.
+     * Relations will be populated with full data instead of just IDs.
+     *
+     * @param relations - Relation names to include, or "*" for all.
+     * @example
+     * client.data.posts.include("tags", "author").find()
+     */
+    include(...relations: string[]): this {
+        this.params.include = relations;
+        return this;
+    }
+
+    /**
+     * Execute the find query and return the results as flat rows.
+     */
+    async find(): Promise<FindResult<M>> {
+        return this.collection.find(this.params);
+    }
+
+    /**
+     * Count the records matching this query.
+     */
+    async count(): Promise<number> {
+        if (!this.collection.count) {
+            throw new Error("count() is not supported by this collection client.");
+        }
+        return this.collection.count(this.params);
+    }
+
+    /**
+     * Listen to realtime updates matching this query.
+     */
+    listen(onUpdate: (data: FindResult<M>) => void, onError?: (error: Error) => void): () => void {
+        if (!this.collection.listen) {
+            throw new Error("Listen is only available when RebaseClient is configured with a websocketUrl.");
+        }
+        return this.collection.listen(this.params, onUpdate, onError);
+    }
+}

package/src/storage-registry.ts

@@ -0,0 +1,102 @@
+/**
+ * Client-side storage source registry.
+ *
+ * Manages multiple `StorageSource` instances keyed by
+ * `StorageSourceDefinition.key`. Collection properties reference
+ * a source by key via `StorageConfig.storageSource`.
+ *
+ * Typical bootstrap flow:
+ * 1. Fetch definitions from `GET /api/storage/sources`
+ * 2. Build server-backed sources automatically via `createStorage(transport, key)`
+ * 3. Register "direct" sources manually (e.g. Firebase Storage hook)
+ */
+
+import type { StorageSource, StorageSourceRegistry, StorageSourceDefinition } from "@rebasepro/types";
+import { DEFAULT_STORAGE_SOURCE_KEY } from "@rebasepro/types";
+import { createStorage } from "./storage";
+import type { Transport } from "./transport";
+
+/**
+ * Default implementation of the client-side `StorageSourceRegistry`.
+ */
+export class ClientStorageSourceRegistry implements StorageSourceRegistry {
+    private sources = new Map<string, StorageSource>();
+
+    /**
+     * Register a storage source.
+     * @param key - Unique key matching a `StorageSourceDefinition.key`
+     * @param source - The `StorageSource` instance
+     */
+    register(key: string, source: StorageSource): void {
+        this.sources.set(key, source);
+    }
+
+    getDefault(): StorageSource {
+        const source = this.sources.get(DEFAULT_STORAGE_SOURCE_KEY);
+        if (!source) {
+            throw new Error(
+                `[StorageSourceRegistry] No default storage source registered. ` +
+                `Register one with key "${DEFAULT_STORAGE_SOURCE_KEY}".`
+            );
+        }
+        return source;
+    }
+
+    get(key: string | undefined | null): StorageSource | undefined {
+        if (key === undefined || key === null) {
+            return this.sources.get(DEFAULT_STORAGE_SOURCE_KEY);
+        }
+        return this.sources.get(key);
+    }
+
+    getOrDefault(key: string | undefined | null): StorageSource {
+        if (key === undefined || key === null) {
+            return this.getDefault();
+        }
+        const source = this.sources.get(key);
+        if (source) return source;
+
+        // Fallback to default
+        console.warn(
+            `[StorageSourceRegistry] Storage source "${key}" not found, ` +
+            `falling back to "${DEFAULT_STORAGE_SOURCE_KEY}".`
+        );
+        return this.getDefault();
+    }
+
+    has(key: string): boolean {
+        return this.sources.has(key);
+    }
+
+    list(): string[] {
+        return Array.from(this.sources.keys());
+    }
+
+    /**
+     * Build a registry from `StorageSourceDefinition[]` and an HTTP transport.
+     *
+     * - Sources with `transport: "server"` are auto-wired via `createStorage(transport, key)`.
+     * - Sources with `transport: "direct"` are **not** auto-wired — they must
+     *   be registered manually after this call (e.g. via a Firebase hook).
+     *
+     * @param definitions - Array of storage source definitions
+     * @param transport - HTTP transport for server-backed sources
+     */
+    static fromDefinitions(
+        definitions: StorageSourceDefinition[],
+        transport: Transport
+    ): ClientStorageSourceRegistry {
+        const registry = new ClientStorageSourceRegistry();
+
+        for (const def of definitions) {
+            if (def.transport === "server") {
+                // Auto-create a server-backed StorageSource for this key
+                const source = createStorage(transport, def.key === DEFAULT_STORAGE_SOURCE_KEY ? undefined : def.key);
+                registry.register(def.key, source);
+            }
+            // "direct" sources must be registered manually
+        }
+
+        return registry;
+    }
+}