@rebasepro/client 0.7.0 → 0.9.0

package/src/storage.ts

@@ -1,25 +1,46 @@
-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";
 
-export function createStorage(transport: Transport): StorageSource {
-    const urlsCache = new Map<string, DownloadConfig>();
-
-    // We expect the transport to point to /api, and storage endpoints handle /api/storage internally if they are relative?
-    // Wait, useBackendStorageSource uses `${apiUrl}/api/storage` directly.
-    // Transport has `.request` which hits `${config.baseUrl}${config.apiPath}${path}`.
-    // Assuming `config.apiPath` is "/api", we just request(`/storage/upload`, ...).
+/**
+ * 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 function createStorage(transport: Transport, storageId?: string): StorageSource {
+    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 => {
+        if (!storageId) return path;
+        const sep = path.includes("?") ? "&" : "?";
+        return `${path}${sep}storageId=${encodeURIComponent(storageId)}`;
+    };
 
     async function putObject({
         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);
 
         if (metadata) {
             for (const [key, value] of Object.entries(metadata)) {
@@ -32,16 +53,10 @@ export function createStorage(transport: Transport): StorageSource {
             }
         }
 
-        // We use fetchFn directly if we need to do multipart boundary, but Transport.request might override Content-Type?
-        // Wait, transport.request defaults to application/json. We must remove Content-Type header or allow it to be evaluated by fetch when body is FormData!
-        const result = await transport.request<{ data: UploadFileResult }>("/storage/upload", {
+        const result = await transport.request<{ data: UploadFileResult }>(withStorageId("/storage/upload"), {
             method: "POST",
             body: formData,
-            headers: {
-                // transport.request merges headers, so to prevent it setting application/json we can delete it
-                // in transport if body is FormData, or we can explicitly set it to an empty string.
-                // Let's rely on standard behaviour for now and adjust transport if it fails.
-            }
+            headers: {}
         });
 
         return result.data;
@@ -52,12 +67,17 @@ export function createStorage(transport: Transport): StorageSource {
         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;
 
-        if (filePath && (filePath.startsWith("local://") || filePath.startsWith("s3://"))) {
+        if (filePath && (filePath.startsWith("local://") || filePath.startsWith("s3://") || filePath.startsWith("gs://"))) {
             filePath = filePath.substring(filePath.indexOf("://") + 3);
         }
 
@@ -66,27 +86,58 @@ export function createStorage(transport: Transport): StorageSource {
         }
 
         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 }>(`/storage/metadata/${filePath}`);
+            const result = await transport.request<{ data: DownloadMetadata }>(withStorageId(`/storage/metadata/${filePath}`));
+
+            // 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;
+            }
 
-            const activeToken = await transport.resolveToken();
-            const tokenQuery = activeToken ? `?token=${activeToken}` : "";
+            // 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 = {
-                url: `${transport.baseUrl}${transport.apiPath}/storage/file/${filePath}${tokenQuery}`,
+                // `withStorageId` picks `?` or `&` based on whether the token
+                // query is already present, so the URL stays valid even when
+                // 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;
         }
@@ -96,33 +147,22 @@ fileNotFound: true };
         key: string,
         bucket?: string
     ): Promise<File | null> {
-        let filePath = key;
-
-        if (filePath && (filePath.startsWith("local://") || filePath.startsWith("s3://"))) {
-            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 = `${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 });
     }
 
@@ -132,7 +172,7 @@ fileNotFound: true };
     ): Promise<void> {
         let filePath = key;
 
-        if (filePath && (filePath.startsWith("local://") || filePath.startsWith("s3://"))) {
+        if (filePath && (filePath.startsWith("local://") || filePath.startsWith("s3://") || filePath.startsWith("gs://"))) {
             filePath = filePath.substring(filePath.indexOf("://") + 3);
         }
 
@@ -145,7 +185,7 @@ fileNotFound: true };
         }
 
         try {
-            await transport.request(`/storage/file/${filePath}`, { method: "DELETE" });
+            await transport.request(withStorageId(`/storage/file/${filePath}`), { method: "DELETE" });
         } catch (e: unknown) {
             if (!(e instanceof Error && "status" in e && (e as { status: number }).status === 404)) throw e;
         }
@@ -167,6 +207,8 @@ fileNotFound: true };
         if (options?.maxResults) params.set("maxResults", String(options.maxResults));
         if (options?.pageToken) params.set("pageToken", options.pageToken);
 
+        if (storageId) params.set("storageId", storageId);
+
         const result = await transport.request<{ data: StorageListResult }>(`/storage/list?${params.toString()}`);
         return result.data;
     }

package/src/transport.ts

@@ -1,6 +1,13 @@
-import { FindParams as TypesFindParams, FindResponse as TypesFindResponse, WhereFieldValue, WhereFilterOpShort } from "@rebasepro/types";
+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 {
     baseUrl?: string;
     token?: string;
@@ -16,94 +23,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;
-    }
-}
-
-/**
- * Maps a short operator alias to the PostgREST-style short code.
- */
-const OP_MAP: Record<string, string> = {
-    "==": "eq",
-"!=": "neq",
-    ">": "gt",
-">=": "gte",
-    "<": "lt",
-"<=": "lte",
-    "not-in": "nin",
-    "array-contains": "cs",
-    "array-contains-any": "csa"
-};
-
-/**
- * Normalise a single `WhereFieldValue` into the PostgREST query-string
- * representation the backend expects.
- *
- * Supports:
- *  - `null`          → `"eq.null"`
- *  - `true`/`false`  → `"eq.true"` / `"eq.false"`
- *  - `42`            → `"42"` (plain equality)
- *  - `"active"`      → `"active"` (plain equality, backward-compat)
- *  - `"gte.18"`      → `"gte.18"` (pass-through PostgREST string)
- *  - `[">=", 18]`    → `"gte.18"` (tuple syntax)
- *  - `["in", [1,2]]` → `"in.(1,2)"` (tuple with array value)
- *  - `["!=", null]`  → `"neq.null"`
- */
-function normalizeWhereValue(value: WhereFieldValue): string {
-    // Null → eq.null
-    if (value === null) return "eq.null";
-
-    // Boolean → eq.true / eq.false
-    if (typeof value === "boolean") return `eq.${value}`;
-
-    // Number → plain equality
-    if (typeof value === "number") return String(value);
-
-    // Tuple: [operator, val]
-    if (Array.isArray(value)) {
-        const conditions: [WhereFilterOpShort, any][] = Array.isArray(value[0])
-            ? (value as [WhereFilterOpShort, any][])
-            : [value as [WhereFilterOpShort, any]];
-
-        const [rawOp, val] = conditions[0] || [];
-        if (rawOp) {
-            const op = OP_MAP[rawOp] ?? rawOp;
-            if (val === null) return `${op}.null`;
-            if (Array.isArray(val)) return `${op}.(${val.join(",")})`;
-            return `${op}.${val}`;
-        }
-    }
-
-    // String — pass through (either plain equality value or PostgREST syntax)
-    return String(value);
-}
-
-function serializeLogicalCondition(cond: any): string {
-    if ("type" in cond) {
-        const sub = (cond.conditions ?? []).map(serializeLogicalCondition).join(",");
-        return `${cond.type}(${sub})`;
-    } else {
-        const op = OP_MAP[cond.operator] ?? cond.operator;
-        let formattedValue = cond.value;
-        if (Array.isArray(cond.value)) {
-            formattedValue = `(${cond.value.join(",")})`;
-        } else if (cond.value === null) {
-            formattedValue = "null";
-        }
-        return `${cond.column}.${op}.${formattedValue}`;
-    }
-}
-
 export function buildQueryString(params?: FindParams): string {
     if (!params) return "";
     const parts: string[] = [];
@@ -113,7 +32,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) {
@@ -131,15 +51,14 @@ export function buildQueryString(params?: FindParams): string {
     }
 
     if (params.where) {
-        for (const [field, value] of Object.entries(params.where)) {
-            if (Array.isArray(value) && value.length > 0 && Array.isArray(value[0])) {
-                for (const subVal of value) {
-                    const normalized = normalizeWhereValue(subVal as WhereFieldValue);
-                    parts.push(`${encodeURIComponent(field)}=${encodeURIComponent(normalized)}`);
+        const serialized = serializeFilter(params.where);
+        for (const [field, value] of Object.entries(serialized)) {
+            if (Array.isArray(value)) {
+                for (const v of value) {
+                    parts.push(`${encodeURIComponent(field)}=${encodeURIComponent(v)}`);
                 }
             } else {
-                const normalized = normalizeWhereValue(value as WhereFieldValue);
-                parts.push(`${encodeURIComponent(field)}=${encodeURIComponent(normalized)}`);
+                parts.push(`${encodeURIComponent(field)}=${encodeURIComponent(value)}`);
             }
         }
     }
@@ -212,12 +131,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) {
@@ -250,10 +172,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;
@@ -267,10 +191,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")
+                }
             );
         }