@rebasepro/client 0.7.0 → 0.8.0

package/dist/storage-registry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 type { Transport } from "./transport";
+/**
+ * Default implementation of the client-side `StorageSourceRegistry`.
+ */
+export declare class ClientStorageSourceRegistry implements StorageSourceRegistry {
+    private sources;
+    /**
+     * Register a storage source.
+     * @param key - Unique key matching a `StorageSourceDefinition.key`
+     * @param source - The `StorageSource` instance
+     */
+    register(key: string, source: StorageSource): void;
+    getDefault(): StorageSource;
+    get(key: string | undefined | null): StorageSource | undefined;
+    getOrDefault(key: string | undefined | null): StorageSource;
+    has(key: string): boolean;
+    list(): string[];
+    /**
+     * 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;
+}

package/dist/storage.d.ts

@@ -1,3 +1,11 @@
 import { StorageSource } from "@rebasepro/types";
 import { Transport } from "./transport";
-export declare function createStorage(transport: Transport): StorageSource;
+/**
+ * Create a StorageSource that talks to the Rebase backend REST API.
+ *
+ * @param transport - HTTP transport instance
+ * @param storageId - Optional storage-source key for multi-backend routing.
+ *                    When set, it is forwarded to the server so the correct
+ *                    `StorageController` is resolved from the registry.
+ */
+export declare function createStorage(transport: Transport, storageId?: string): StorageSource;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/client",
   "type": "module",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "HTTP SDK client for the Rebase custom backend",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -20,13 +20,6 @@
   "engines": {
     "node": ">=14"
   },
-  "scripts": {
-    "watch": "vite build --watch",
-    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
-    "test:lint": "eslint \"src/**\" --quiet",
-    "test": "jest --passWithNoTests --forceExit",
-    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -37,9 +30,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/common": "workspace:*",
-    "@rebasepro/types": "workspace:*",
-    "@rebasepro/utils": "workspace:*"
+    "@rebasepro/common": "0.8.0",
+    "@rebasepro/types": "0.8.0",
+    "@rebasepro/utils": "0.8.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
@@ -75,8 +68,16 @@
     ],
     "testEnvironment": "node",
     "moduleNameMapper": {
+      "^@rebasepro/common$": "<rootDir>/../common/src/index.ts",
       "^@rebasepro/types$": "<rootDir>/../types/src/index.ts",
       "^@rebasepro/utils$": "<rootDir>/../utils/src/index.ts"
     }
+  },
+  "scripts": {
+    "watch": "vite build --watch",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+    "test:lint": "eslint \"src/**\" --quiet",
+    "test": "jest --passWithNoTests --forceExit",
+    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f"
   }
-}
+}

package/src/api-keys.ts

@@ -15,6 +15,7 @@ export interface ApiKeyMasked {
     name: string;
     key_prefix: string;
     permissions: ApiKeyPermission[];
+    admin: boolean;
     rate_limit: number | null;
     created_by: string;
     created_at: string;

package/src/collection.test.ts

@@ -42,7 +42,7 @@ describe("createCollectionClient", () => {
 
             const client = createCollectionClient(transport, "products");
             const result = await client.count({
-                where: { status: "eq.published" }
+                where: { status: ["==", "published"] }
             });
 
             expect(transport.request).toHaveBeenCalledWith(
@@ -111,7 +111,7 @@ offset: 10 });
             const client = createCollectionClient(transport, "orders");
             await client.count({
                 where: {
-                    status: "eq.active",
+                    status: ["==", "active"],
                     total: [">=", 100]
                 }
             });

package/src/collection.ts

@@ -3,125 +3,15 @@ import { RebaseWebSocketClient } from "./websocket";
 import {
     CollectionAccessor,
     Entity,
-    FilterOperator,
     FilterValues,
     FindResponse,
-    WhereFieldValue,
-    WhereFilterOp,
     LogicalCondition,
+    WhereFilterOp,
     WhereValue
 } from "@rebasepro/types";
 
 import { QueryBuilder } from "./query_builder";
 
-function parseWhereFilter(where?: Record<string, WhereFieldValue>): FilterValues<string> | undefined {
-    if (!where) return undefined;
-    const filters: Record<string, any> = {};
-
-    const OP_TO_FILTER: Record<string, WhereFilterOp> = {
-        "eq": "==",
-        "neq": "!=",
-        "gt": ">",
-        "gte": ">=",
-        "lt": "<",
-        "lte": "<=",
-        "==": "==",
-        "!=": "!=",
-        ">": ">",
-        ">=": ">=",
-        "<": "<",
-        "<=": "<=",
-        "in": "in",
-        "nin": "not-in",
-        "not-in": "not-in",
-        "cs": "array-contains",
-        "csa": "array-contains-any",
-        "array-contains": "array-contains",
-        "array-contains-any": "array-contains-any"
-    };
-
-    const parseSingle = (rawValue: any, fieldKey: string): [WhereFilterOp, unknown] => {
-        if (rawValue === null) return ["==", null];
-        if (typeof rawValue === "boolean") return ["==", rawValue];
-        if (typeof rawValue === "number") return ["==", rawValue];
-
-        if (Array.isArray(rawValue) && rawValue.length === 2 && typeof rawValue[0] === "string") {
-            const [rawOp, val] = rawValue;
-            return [OP_TO_FILTER[rawOp] ?? "==", val];
-        }
-
-        const value = String(rawValue);
-        const dotIndex = value.indexOf(".");
-        if (dotIndex > 0) {
-            const opStr = value.substring(0, dotIndex);
-            const valStr = value.substring(dotIndex + 1);
-            let op: WhereFilterOp = "==";
-            let val: string | number | boolean | null | string[] = valStr;
-
-            switch (opStr) {
-                case "eq":
-                    op = "==";
-                    break;
-                case "neq":
-                    op = "!=";
-                    break;
-                case "gt":
-                    op = ">";
-                    break;
-                case "gte":
-                    op = ">=";
-                    break;
-                case "lt":
-                    op = "<";
-                    break;
-                case "lte":
-                    op = "<=";
-                    break;
-                case "in":
-                    op = "in";
-                    val = valStr.startsWith("(") && valStr.endsWith(")")
-                        ? valStr.slice(1, -1).split(",").map(v => v.trim())
-                        : valStr.split(",");
-                    break;
-                case "nin":
-                    op = "not-in";
-                    val = valStr.startsWith("(") && valStr.endsWith(")")
-                        ? valStr.slice(1, -1).split(",").map(v => v.trim())
-                        : valStr.split(",");
-                    break;
-                case "cs":
-                    op = "array-contains";
-                    break;
-                case "csa":
-                    op = "array-contains-any";
-                    val = valStr.startsWith("(") && valStr.endsWith(")")
-                        ? valStr.slice(1, -1).split(",").map(v => v.trim())
-                        : valStr.split(",");
-                    break;
-                default:
-                    op = "==";
-                    val = value;
-            }
-            if (val === "true") val = true;
-            else if (val === "false") val = false;
-            else if (val === "null") val = null;
-            else if (typeof val === "string" && /^[0-9]+(\.[0-9]+)?$/.test(val) && fieldKey !== "id" && !fieldKey.endsWith("_id")) val = Number(val);
-
-            return [op, val];
-        } else {
-            return ["==", value];
-        }
-    };
-
-    for (const [key, rawValue] of Object.entries(where)) {
-        if (Array.isArray(rawValue) && rawValue.length > 0 && Array.isArray(rawValue[0])) {
-            filters[key] = rawValue.map(r => parseSingle(r, key));
-        } else {
-            filters[key] = parseSingle(rawValue, key);
-        }
-    }
-    return filters;
-}
 
 /**
  * Wrap a flat row (returned by the REST API as `{ id, ...fields }`) into
@@ -144,10 +34,10 @@ function rowToEntity<M extends Record<string, unknown>>(row: Record<string, unkn
  * Additionally it exposes fluent query builder methods like `.where()`, `.orderBy()`.
  */
 export interface CollectionClient<M extends Record<string, unknown> = Record<string, unknown>> extends CollectionAccessor<M> {
-    where<K extends keyof M & string>(column: K, operator: FilterOperator, value: WhereValue<M[K]>): QueryBuilder<M>;
+    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): QueryBuilder<M>;
     where(logicalCondition: LogicalCondition): QueryBuilder<M>;
 
-    orderBy(column: keyof M & string, ascending?: "asc" | "desc"): QueryBuilder<M>;
+    orderBy(column: keyof M & string, direction?: "asc" | "desc"): QueryBuilder<M>;
 
     limit(count: number): QueryBuilder<M>;
 
@@ -227,15 +117,15 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
         },
 
         // Fluent builder instantiation
-        where(columnOrCondition: string | LogicalCondition, operator?: FilterOperator, value?: unknown) {
+        where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown) {
             const builder = new QueryBuilder<M>(client as unknown as CollectionAccessor<M>);
             if (typeof columnOrCondition === "object") {
                 return builder.where(columnOrCondition);
             }
             return builder.where(columnOrCondition as keyof M & string, operator!, value as WhereValue<M[keyof M & string]>);
         },
-        orderBy(column: keyof M & string, ascending?: "asc" | "desc") {
-            return new QueryBuilder<M>(client).orderBy(column, ascending);
+        orderBy(column: keyof M & string, direction?: "asc" | "desc") {
+            return new QueryBuilder<M>(client).orderBy(column, direction);
         },
         limit(count: number) {
             return new QueryBuilder<M>(client).limit(count);
@@ -253,10 +143,12 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
 
     if (ws) {
         client.listen = (params: FindParams | undefined, onUpdate: (response: FindResponse<M>) => void, onError?: (error: Error) => void) => {
-            return ws.listenCollection(
+            let active = true;
+            let lastUpdateId = 0;
+            const unsub = ws.listenCollection(
                 {
                     path: slug,
-                    filter: parseWhereFilter(params?.where),
+                    filter: params?.where,
                     limit: params?.limit,
                     startAfter: params?.offset ? String(params.offset) : undefined,
                     orderBy: params?.orderBy?.split(":")[0],
@@ -264,19 +156,49 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
                     searchString: params?.searchString
                 },
                 (entities: Entity[]) => {
+                    const currentUpdateId = ++lastUpdateId;
                     const requestedLimit = params?.limit || 20;
+                    const offset = params?.offset || 0;
+
+                    // Immediately fire update with heuristic metadata
                     onUpdate({
                         data: entities as Entity<M>[],
                         meta: {
                             total: entities.length,
                             limit: requestedLimit,
-                            offset: params?.offset || 0,
+                            offset,
                             hasMore: entities.length >= requestedLimit
                         }
                     });
+
+                    // Asynchronously fetch the actual count from the server to get accurate total/hasMore
+                    if (client.count) {
+                        client.count(params)
+                            .then((total) => {
+                                if (active && currentUpdateId === lastUpdateId) {
+                                    onUpdate({
+                                        data: entities as Entity<M>[],
+                                        meta: {
+                                            total,
+                                            limit: requestedLimit,
+                                            offset,
+                                            hasMore: offset + entities.length < total
+                                        }
+                                    });
+                                }
+                            })
+                            .catch(() => {
+                                // Silent fallback on count error
+                            });
+                    }
                 },
                 onError
             );
+
+            return () => {
+                active = false;
+                unsub();
+            };
         };
 
         client.listenById = (id: string | number, onUpdate: (data: Entity<M> | undefined) => void, onError?: (error: Error) => void) => {

package/src/index.ts

@@ -3,11 +3,19 @@ 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,
+    RebaseClient,
+    RebaseData,
+    StorageSource,
+    StorageSourceDefinition,
+    StorageSourceRegistry
+} from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 
 export * from "./transport";
@@ -19,6 +27,7 @@ export * from "./collection";
 export * from "./query_builder";
 export * from "./websocket";
 export * from "./storage";
+export * from "./storage-registry";
 export * from "./reviver";
 export * from "./functions";
 export type { Entity, FindResponse } from "@rebasepro/types";
@@ -28,6 +37,21 @@ export interface CreateRebaseClientOptions extends RebaseClientConfig {
     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 ────────────────────────────────────────────────────────
@@ -69,6 +93,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 +145,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;
@@ -190,6 +259,9 @@ 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") {
+                if (options.collections && prop in options.collections) {
+                    return collection(options.collections[prop]);
+                }
                 // Convert camelCase property names to snake_case slugs.
                 // e.g. `companyMembers` → `company_members`
                 const slug = toSnakeCase(prop);
@@ -206,6 +278,9 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         apiKeys,
         functions,
         storage,
+        storageRegistry,
+        createStorageSource,
+        fetchStorageSources,
         ws,
         setToken: transport.setToken,
         setAuthTokenGetter: transport.setAuthTokenGetter,

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;
+    }
+}