@rebasepro/client 0.8.0 → 0.9.1-canary.09aaf62

package/src/sdk_query_builder.ts

@@ -0,0 +1,141 @@
+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, " +
+                "and not when it was created with realtime: false."
+            );
+        }
+        return this.collection.listen(this.params, onUpdate, onError);
+    }
+}

package/src/storage.ts

@@ -1,4 +1,4 @@
-import { StorageSource, UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult, DownloadMetadata } from "@rebasepro/types";
+import { StorageSource, UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult, DownloadMetadata, PUBLIC_STORAGE_PREFIX, isPublicStoragePath } from "@rebasepro/types";
 import { Transport } from "./transport";
 
 /**
@@ -10,7 +10,7 @@ import { Transport } from "./transport";
  *                    `StorageController` is resolved from the registry.
  */
 export function createStorage(transport: Transport, storageId?: string): StorageSource {
-    const urlsCache = new Map<string, DownloadConfig>();
+    const urlsCache = new Map<string, { config: DownloadConfig; expiresAt?: number }>();
 
     /** Append ?storageId=... to a path when multi-backend routing is active. */
     const withStorageId = (path: string): string => {
@@ -23,12 +23,22 @@ export function createStorage(transport: Transport, storageId?: string): Storage
         file,
         key,
         metadata,
-        bucket
+        bucket,
+        public: isPublic
     }: UploadFileProps): Promise<UploadFileResult> {
         const formData = new FormData();
         formData.append("file", file);
 
-        if (key) formData.append("key", key);
+        // Public objects live under the public prefix so they can be served
+        // token-less via a stable, permanent URL. Normalize the key here so the
+        // stored path is self-describing (no server round-trip needed to know
+        // it's public).
+        let effectiveKey = key;
+        if (isPublic && effectiveKey && !isPublicStoragePath(effectiveKey)) {
+            effectiveKey = `${PUBLIC_STORAGE_PREFIX}${effectiveKey.replace(/^\/+/, "")}`;
+        }
+
+        if (effectiveKey) formData.append("key", effectiveKey);
         if (bucket) formData.append("bucket", bucket);
         if (storageId) formData.append("storageId", storageId);
 
@@ -57,8 +67,13 @@ export function createStorage(transport: Transport, storageId?: string): Storage
         bucket?: string
     ): Promise<DownloadConfig> {
         const cacheKey = bucket ? `${bucket}/${keyOrUrl}` : keyOrUrl;
-        const cached = urlsCache.get(cacheKey);
-        if (cached) return cached;
+        const cachedEntry = urlsCache.get(cacheKey);
+        if (cachedEntry) {
+            if (!cachedEntry.expiresAt || cachedEntry.expiresAt > Date.now()) {
+                return cachedEntry.config;
+            }
+            urlsCache.delete(cacheKey);
+        }
 
         let filePath = keyOrUrl;
 
@@ -71,30 +86,58 @@ export function createStorage(transport: Transport, storageId?: string): Storage
         }
 
         if (!filePath || filePath.trim() === "" || filePath === "/") {
-            return { url: null,
-fileNotFound: true };
+            return { url: null, fileNotFound: true };
+        }
+
+        // ── Public objects ────────────────────────────────────────────────
+        // A public file (under the public prefix) is served token-less via a
+        // stable, permanent, CDN-cacheable URL. No metadata round-trip and no
+        // token are needed — build the URL directly and cache it forever.
+        if (isPublicStoragePath(filePath)) {
+            const publicConfig: DownloadConfig = {
+                url: withStorageId(`${transport.baseUrl}${transport.apiPath}/storage/file/${filePath}`)
+            };
+            urlsCache.set(cacheKey, { config: publicConfig }); // no expiry
+            return publicConfig;
         }
 
         try {
             const result = await transport.request<{ data: DownloadMetadata }>(withStorageId(`/storage/metadata/${filePath}`));
 
-            const activeToken = await transport.resolveToken();
-            const tokenQuery = activeToken ? `?token=${activeToken}` : "";
+            // Public object (server-confirmed): token-less permanent URL.
+            if (result.data.public) {
+                const publicConfig: DownloadConfig = {
+                    url: withStorageId(`${transport.baseUrl}${transport.apiPath}/storage/file/${filePath}`),
+                    metadata: result.data
+                };
+                urlsCache.set(cacheKey, { config: publicConfig }); // no expiry
+                return publicConfig;
+            }
+
+            // Private object: use the short-lived, file-scoped download token
+            // minted by the server. We deliberately do NOT fall back to the
+            // caller's access token — a URL must never carry a full-privilege
+            // credential. If no scoped token is present the URL fails closed.
+            const scopedToken = result.data.token;
+            const tokenQuery = scopedToken ? `?token=${scopedToken}` : "";
 
             const downloadConfig: DownloadConfig = {
                 // `withStorageId` picks `?` or `&` based on whether the token
                 // query is already present, so the URL stays valid even when
-                // there is no auth token.
+                // there is no token.
                 url: withStorageId(`${transport.baseUrl}${transport.apiPath}/storage/file/${filePath}${tokenQuery}`),
                 metadata: result.data
             };
 
-            urlsCache.set(cacheKey, downloadConfig);
+            const expiresAt = result.data.tokenExpiresIn
+                ? Date.now() + (result.data.tokenExpiresIn - 10) * 1000 // subtract 10s buffer
+                : undefined;
+
+            urlsCache.set(cacheKey, { config: downloadConfig, expiresAt });
             return downloadConfig;
         } catch (e: unknown) {
             if (e instanceof Error && "status" in e && (e as { status: number }).status === 404) {
-                return { url: null,
-fileNotFound: true };
+                return { url: null, fileNotFound: true };
             }
             throw e;
         }
@@ -104,33 +147,22 @@ fileNotFound: true };
         key: string,
         bucket?: string
     ): Promise<File | null> {
-        let filePath = key;
-
-        if (filePath && (filePath.startsWith("local://") || filePath.startsWith("s3://") || filePath.startsWith("gs://"))) {
-            filePath = filePath.substring(filePath.indexOf("://") + 3);
-        }
-
-        if (bucket && filePath && !filePath.startsWith(bucket)) {
-            filePath = `${bucket}/${filePath}`;
-        }
-
-        if (!filePath || filePath.trim() === "" || filePath === "/") {
+        const downloadConfig = await getSignedUrl(key, bucket);
+        if (downloadConfig.fileNotFound || !downloadConfig.url) {
             return null;
         }
 
-        // We must use plain fetch because transport.request expects JSON response, but here we want a Blob.
-        const url = withStorageId(`${transport.baseUrl}${transport.apiPath}/storage/file/${filePath}`);
-
-        // This is a bit manual, but necessary for blob handling
-        const response = await transport.fetchFn(url, {
-            headers: transport.getHeaders ? transport.getHeaders() : {}
+        // Fetch using the signed URL directly. Since the scoped token is in the ?token= query param,
+        // we explicitly omit any Authorization headers to prevent passing full access tokens to file serving routes.
+        const response = await transport.fetchFn(downloadConfig.url, {
+            headers: {}
         });
 
         if (response.status === 404) return null;
         if (!response.ok) throw new Error("Failed to get file");
 
         const blob = await response.blob();
-        const fileName = filePath.split("/").pop() || "file";
+        const fileName = (bucket ? `${bucket}/${key}` : key).split("/").pop() || "file";
         return new File([blob], fileName, { type: blob.type });
     }
 

package/src/transport.ts

@@ -1,14 +1,54 @@
-import { FindParams as TypesFindParams, FindResponse as TypesFindResponse } from "@rebasepro/types";
-import { serializeFilter, serializeLogicalCondition } from "@rebasepro/common";
+import { FindParams as TypesFindParams, FindResponse as TypesFindResponse, RebaseApiError } from "@rebasepro/types";
+import { serializeFilter, serializeLogicalCondition, serializeOrderBy } from "@rebasepro/common";
 import { rebaseReviver } from "./reviver";
 
+// The canonical client error now lives in `@rebasepro/types` so every package
+// (client, auth, …) throws one type. Re-exported here to preserve the historical
+// `import { RebaseApiError } from ".../transport"` path used across the SDK.
+export { RebaseApiError } from "@rebasepro/types";
+export type { RebaseErrorInit } from "@rebasepro/types";
+
 export interface RebaseClientConfig {
+    /**
+     * Origin of the Rebase server — scheme, host and port **only**.
+     *
+     * {@link apiPath} is appended to this, so do not include it here:
+     * `"http://localhost:3001"` is correct, while `"http://localhost:3001/api"`
+     * silently builds `/api/api/…` and every request 404s. Omit entirely for
+     * same-origin requests from the browser.
+     */
     baseUrl?: string;
+    /**
+     * Bearer token sent as `Authorization` on every request.
+     *
+     * In the browser this is the signed-in user's access token, so row-level
+     * security applies. Server-side callers — scripts, cron jobs, ETL — pass the
+     * service key instead, which resolves to `{ uid: "service", roles: ["admin"] }`
+     * and **bypasses RLS**: there is no user to constrain those queries, so scope
+     * them explicitly.
+     */
     token?: string;
+    /**
+     * Path the API is mounted under, appended to {@link baseUrl}.
+     * Defaults to `"/api"`; override only if the server mounts it elsewhere.
+     */
     apiPath?: string;
     fetch?: typeof globalThis.fetch;
     onUnauthorized?: () => Promise<boolean>;
     websocketUrl?: string; // Optional real-time WebSocket connection
+    /**
+     * Open the realtime WebSocket. **Defaults to `true`.**
+     *
+     * The socket connects as soon as the client is constructed and keeps the
+     * Node event loop alive, so a one-shot script (CLI, cron job, ETL) will not
+     * exit on its own. Set this to `false` for any process that reads or writes
+     * and then terminates — `.listen()` and `.listenById()` then throw instead
+     * of silently doing nothing.
+     *
+     * Long-lived processes that do want realtime can instead call
+     * `client.close()` when shutting down.
+     */
+    realtime?: boolean;
 }
 
 /**
@@ -17,20 +57,6 @@ export interface RebaseClientConfig {
 export type FindParams = TypesFindParams;
 export type FindResponse<T> = TypesFindResponse<T extends Record<string, unknown> ? T : Record<string, unknown>>;
 
-export class RebaseApiError extends Error {
-    status: number;
-    code?: string;
-    details?: unknown;
-
-    constructor(status: number, message: string, code?: string, details?: unknown) {
-        super(message);
-        this.name = "RebaseApiError";
-        this.status = status;
-        this.code = code;
-        this.details = details;
-    }
-}
-
 export function buildQueryString(params?: FindParams): string {
     if (!params) return "";
     const parts: string[] = [];
@@ -40,7 +66,8 @@ export function buildQueryString(params?: FindParams): string {
     if (params.page != null) parts.push(`page=${params.page}`);
 
     if (params.orderBy) {
-        parts.push(`orderBy=${encodeURIComponent(params.orderBy)}`);
+        const wire = serializeOrderBy(params.orderBy);
+        if (wire) parts.push(`orderBy=${encodeURIComponent(wire)}`);
     }
 
     if (params.searchString) {
@@ -138,12 +165,15 @@ headers });
             }
         }
 
+        // The server always emits the canonical `{ error: { message, code, details? } }`
+        // envelope (formatted by the central errorHandler), so we read strictly
+        // from `body.error.*`.
         const getErrorField = (obj: Record<string, unknown>, field: string): unknown => {
             const err = obj?.error;
-            if (err && typeof err === "object" && err !== null && field in (err as Record<string, unknown>)) {
+            if (err && typeof err === "object" && err !== null) {
                 return (err as Record<string, unknown>)[field];
             }
-            return obj?.[field];
+            return undefined;
         };
 
         if (res.status === 401 && onUnauthorizedHandler) {
@@ -176,10 +206,12 @@ headers: retryHeaders });
                         fallbackMessage = `Endpoint not found (${method} ${path}). This usually means the collection is not registered on the backend, or the frontend API URL configuration (e.g. VITE_API_URL) is missing or pointing to the wrong host.`;
                     }
                     throw new RebaseApiError(
-                        retryRes.status,
                         String(getErrorField(retryBody, "message") || fallbackMessage || `Request failed with status ${retryRes.status}`),
-                        getErrorField(retryBody, "code") as string | undefined,
-                        getErrorField(retryBody, "details")
+                        {
+                            status: retryRes.status,
+                            code: getErrorField(retryBody, "code") as string | undefined,
+                            details: getErrorField(retryBody, "details")
+                        }
                     );
                 }
                 return retryBody as T;
@@ -193,10 +225,12 @@ headers: retryHeaders });
                 fallbackMessage = `Endpoint not found (${method} ${path}). This usually means the collection is not registered on the backend, or the frontend API URL configuration (e.g. VITE_API_URL) is missing or pointing to the wrong host.`;
             }
             throw new RebaseApiError(
-                res.status,
                 String(getErrorField(body, "message") || fallbackMessage || `Request failed with status ${res.status}`),
-                getErrorField(body, "code") as string | undefined,
-                getErrorField(body, "details")
+                {
+                    status: res.status,
+                    code: getErrorField(body, "code") as string | undefined,
+                    details: getErrorField(body, "details")
+                }
             );
         }