@rebasepro/client 0.0.1-canary.09e5ec5

package/src/query_builder.ts

@@ -0,0 +1,125 @@
+import { FindParams, Entity, FindResponse } from "@rebasepro/types";
+import { CollectionClient } from "./collection";
+
+export type FilterOperator =
+    | "eq" | "neq" | "gt" | "gte" | "lt" | "lte"
+    | "in" | "nin" | "cs" | "csa"
+    | "==" | "!=" | ">" | ">=" | "<" | "<="
+    | "array-contains" | "array-contains-any"
+    | "not-in";
+
+/**
+ * Maps standard operators to Rebase backend's string-based operators
+ */
+function mapOperator(op: FilterOperator): string {
+    switch (op) {
+        case "==": return "eq";
+        case "!=": return "neq";
+        case ">": return "gt";
+        case ">=": return "gte";
+        case "<": return "lt";
+        case "<=": return "lte";
+        case "array-contains": return "cs";
+        case "array-contains-any": return "csa";
+        case "not-in": return "nin";
+        default: return op;
+    }
+}
+
+export class QueryBuilder<M extends Record<string, unknown> = Record<string, unknown>> {
+    private params: FindParams = { where: {} };
+
+    constructor(private collection: CollectionClient<M>) {}
+
+    /**
+     * Add a filter condition to your query.
+     * @example
+     * client.collection('users').where('age', '>=', 18).find()
+     */
+    where(column: keyof M & string, operator: FilterOperator, value: unknown): this {
+        if (!this.params.where) {
+            this.params.where = {};
+        }
+
+        const mappedOp = mapOperator(operator);
+        let formattedValue = value;
+
+        // Handle arrays for in, nin, cs, csa
+        if (Array.isArray(value) && ["in", "nin", "cs", "csa"].includes(mappedOp)) {
+            formattedValue = `(${value.join(",")})`;
+        } else if (value === null) {
+            formattedValue = "null";
+        }
+
+        this.params.where[column] = mappedOp === "eq" ? String(formattedValue) : `${mappedOp}.${formattedValue}`;
+        return this;
+    }
+
+    /**
+     * Order the results by a specific column.
+     * @example
+     * client.collection('users').orderBy('createdAt', 'desc').find()
+     */
+    orderBy(column: keyof M & string, ascending: "asc" | "desc" = "asc"): this {
+        this.params.orderBy = `${column}:${ascending}`;
+        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 entity data instead of just IDs.
+     *
+     * @param relations - Relation names to include, or "*" for all.
+     * @example
+     * // Include specific relations
+     * client.data.posts.include("tags", "author").find()
+     *
+     * // Include all relations
+     * client.data.posts.include("*").find()
+     */
+    include(...relations: string[]): this {
+        this.params.include = relations;
+        return this;
+    }
+
+    /**
+     * Execute the find query and return the results.
+     */
+    async find(): Promise<FindResponse<M>> {
+        return this.collection.find(this.params) as Promise<FindResponse<M>>;
+    }
+
+    /**
+     * Listen to realtime updates matching this query.
+     */
+    listen(onUpdate: (data: FindResponse<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/reviver.ts

@@ -0,0 +1,39 @@
+import { EntityReference, EntityRelation, GeoPoint, Vector, Entity } from "@rebasepro/types";
+
+export function rebaseReviver(_key: string, value: unknown): unknown {
+    if (value && typeof value === "object" && "__type" in value) {
+        const record = value as Record<string, unknown>;
+        switch (record.__type) {
+            case "date":
+            case "Date": {
+                if (typeof record.value !== "string") {
+                    return value;
+                }
+                const date = new Date(record.value);
+                return isNaN(date.getTime()) ? null : date;
+            }
+            case "reference":
+            case "EntityReference":
+                return new EntityReference({
+                    id: String(record.id),
+                    path: record.path as string,
+                    driver: record.driver as string | undefined,
+                    databaseId: record.databaseId as string | undefined
+                });
+            case "relation":
+            case "EntityRelation":
+                return new EntityRelation(
+                    record.id as string | number,
+                    record.path as string,
+                    record.data as Entity | undefined
+                );
+            case "GeoPoint":
+                return new GeoPoint(record.latitude as number, record.longitude as number);
+            case "Vector":
+                return new Vector(record.value as number[]);
+            default:
+                return value;
+        }
+    }
+    return value;
+}

package/src/storage.ts

@@ -0,0 +1,181 @@
+import { StorageSource, UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult, DownloadMetadata } 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`, ...).
+
+    async function putObject({
+        file,
+        key,
+        metadata,
+        bucket
+    }: UploadFileProps): Promise<UploadFileResult> {
+        const formData = new FormData();
+        formData.append("file", file);
+
+        if (key) formData.append("key", key);
+        if (bucket) formData.append("bucket", bucket);
+
+        if (metadata) {
+            for (const [key, value] of Object.entries(metadata)) {
+                if (value !== undefined && value !== null) {
+                    formData.append(
+                        `metadata_${key}`,
+                        typeof value === "string" ? value : JSON.stringify(value)
+                    );
+                }
+            }
+        }
+
+        // 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", {
+            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.
+            }
+        });
+
+        return result.data;
+    }
+
+    async function getSignedUrl(
+        keyOrUrl: string,
+        bucket?: string
+    ): Promise<DownloadConfig> {
+        const cacheKey = bucket ? `${bucket}/${keyOrUrl}` : keyOrUrl;
+        const cached = urlsCache.get(cacheKey);
+        if (cached) return cached;
+
+        let filePath = keyOrUrl;
+
+        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 === "/") {
+            return { url: null,
+fileNotFound: true };
+        }
+
+        try {
+            const result = await transport.request<{ data: DownloadMetadata }>(`/storage/metadata/${filePath}`);
+
+            const activeToken = await transport.resolveToken();
+            const tokenQuery = activeToken ? `?token=${activeToken}` : "";
+
+            const downloadConfig: DownloadConfig = {
+                url: `${transport.baseUrl}${transport.apiPath}/storage/file/${filePath}${tokenQuery}`,
+                metadata: result.data
+            };
+
+            urlsCache.set(cacheKey, downloadConfig);
+            return downloadConfig;
+        } catch (e: unknown) {
+            if (e instanceof Error && "status" in e && (e as { status: number }).status === 404) {
+                return { url: null,
+fileNotFound: true };
+            }
+            throw e;
+        }
+    }
+
+    async function getObject(
+        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 === "/") {
+            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() : {}
+        });
+
+        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";
+        return new File([blob], fileName, { type: blob.type });
+    }
+
+    async function deleteObject(
+        key: string,
+        bucket?: string
+    ): Promise<void> {
+        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 === "/") {
+            return;
+        }
+
+        try {
+            await transport.request(`/storage/file/${filePath}`, { method: "DELETE" });
+        } catch (e: unknown) {
+            if (!(e instanceof Error && "status" in e && (e as { status: number }).status === 404)) throw e;
+        }
+
+        urlsCache.delete(bucket ? `${bucket}/${key}` : key);
+    }
+
+    async function listObjects(
+        prefix: string,
+        options?: {
+            bucket?: string;
+            maxResults?: number;
+            pageToken?: string;
+        }
+    ): Promise<StorageListResult> {
+        const params = new URLSearchParams();
+        if (prefix) params.set("prefix", prefix);
+        if (options?.bucket) params.set("bucket", options.bucket);
+        if (options?.maxResults) params.set("maxResults", String(options.maxResults));
+        if (options?.pageToken) params.set("pageToken", options.pageToken);
+
+        const result = await transport.request<{ data: StorageListResult }>(`/storage/list?${params.toString()}`);
+        return result.data;
+    }
+
+    return {
+        putObject,
+        getSignedUrl,
+        getObject,
+        deleteObject,
+        listObjects
+    };
+}

package/src/transport.ts

@@ -0,0 +1,259 @@
+import { FindParams as TypesFindParams, FindResponse as TypesFindResponse, WhereFieldValue } from "@rebasepro/types";
+import { rebaseReviver } from "./reviver";
+
+export interface RebaseClientConfig {
+    baseUrl?: string;
+    token?: string;
+    apiPath?: string;
+    fetch?: typeof globalThis.fetch;
+    onUnauthorized?: () => Promise<boolean>;
+    websocketUrl?: string; // Optional real-time WebSocket connection
+}
+
+/**
+ * Re-export from `@rebasepro/types` for backward compatibility.
+ */
+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) && value.length === 2) {
+        const [rawOp, val] = value;
+        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);
+}
+
+export function buildQueryString(params?: FindParams): string {
+    if (!params) return "";
+    const parts: string[] = [];
+
+    if (params.limit != null) parts.push(`limit=${params.limit}`);
+    if (params.offset != null) parts.push(`offset=${params.offset}`);
+    if (params.page != null) parts.push(`page=${params.page}`);
+
+    if (params.orderBy) {
+        parts.push(`orderBy=${encodeURIComponent(params.orderBy)}`);
+    }
+
+    if (params.searchString) {
+        parts.push(`searchString=${encodeURIComponent(params.searchString)}`);
+    }
+
+    if (params.include && params.include.length > 0) {
+        parts.push(`include=${encodeURIComponent(params.include.join(","))}`);
+    }
+
+    if (params.where) {
+        for (const [field, value] of Object.entries(params.where)) {
+            const normalized = normalizeWhereValue(value as WhereFieldValue);
+            parts.push(`${encodeURIComponent(field)}=${encodeURIComponent(normalized)}`);
+        }
+    }
+
+    return parts.length > 0 ? "?" + parts.join("&") : "";
+}
+
+export interface Transport {
+    request: <T = unknown>(path: string, init?: RequestInit) => Promise<T>;
+    setToken: (newToken: string | null) => void;
+    setAuthTokenGetter: (getter: () => Promise<string | null>) => void;
+    setOnUnauthorized: (handler: () => Promise<boolean>) => void;
+    readonly baseUrl: string;
+    readonly apiPath: string;
+    readonly fetchFn: typeof globalThis.fetch;
+    getHeaders: (init?: RequestInit) => Record<string, string>;
+    resolveToken: () => Promise<string | null>;
+}
+
+export function createTransport(config: RebaseClientConfig): Transport {
+    const fetchFn = config.fetch || globalThis.fetch;
+    const apiPath = config.apiPath || "/api";
+    let token = config.token;
+    let tokenGetter: (() => Promise<string | null>) | undefined;
+    let onUnauthorizedHandler = config.onUnauthorized;
+
+    function getHeaders(activeToken: string | undefined, init?: RequestInit) {
+        return {
+            "Content-Type": "application/json",
+            ...(activeToken ? { Authorization: `Bearer ${activeToken}` } : {}),
+            ...((init?.headers as Record<string, string>) || {})
+        };
+    }
+
+    async function request<T = unknown>(path: string, init?: RequestInit): Promise<T> {
+        const base = config.baseUrl ? config.baseUrl.replace(/\/$/, "") : "";
+        const url = base + apiPath + path;
+
+        let activeToken = token;
+        if (tokenGetter) {
+            try {
+                const fetched = await tokenGetter();
+                if (fetched !== null && fetched !== undefined) {
+                    activeToken = fetched;
+                }
+            } catch (e) {
+                // Ignore error, fallback to static token if any
+            }
+        }
+
+        const headers = getHeaders(activeToken, init);
+
+        // If passing FormData, we MUST let fetch set the boundary, so remove Content-Type
+        if (init?.body instanceof FormData) {
+            delete (headers as Record<string, string>)["Content-Type"];
+        }
+
+        const res = await fetchFn(url, { ...init,
+headers });
+
+        if (res.status === 204) return undefined as unknown as T;
+
+        const text = await res.text().catch(() => "");
+        let body: any = {};
+        if (text) {
+            try {
+                body = JSON.parse(text, rebaseReviver);
+            } catch (e) {
+                // If not valid JSON, fallback
+            }
+        }
+
+        if (res.status === 401 && onUnauthorizedHandler) {
+            const retried = await onUnauthorizedHandler();
+            if (retried) {
+                let retryToken = token;
+                if (tokenGetter) {
+                    try {
+                        const fetched = await tokenGetter();
+                        if (fetched !== null && fetched !== undefined) {
+                            retryToken = fetched;
+                        }
+                    } catch (e) { /* ignore */ }
+                }
+                const retryHeaders = getHeaders(retryToken, init) as Record<string, string>;
+                const retryRes = await fetchFn(url, { ...init,
+headers: retryHeaders });
+                if (retryRes.status === 204) return undefined as unknown as T;
+                const retryText = await retryRes.text().catch(() => "");
+                let retryBody: any = {};
+                if (retryText) {
+                    try {
+                        retryBody = JSON.parse(retryText, rebaseReviver);
+                    } catch (e) { /* ignore */ }
+                }
+                if (!retryRes.ok) {
+                    let fallbackMessage = retryRes.statusText;
+                    if (retryRes.status === 404 && !fallbackMessage) {
+                        const method = init?.method || "GET";
+                        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,
+                        retryBody?.error?.message || retryBody?.message || fallbackMessage || `Request failed with status ${retryRes.status}`,
+                        retryBody?.error?.code || retryBody?.code,
+                        retryBody?.error?.details || retryBody?.details
+                    );
+                }
+                return retryBody as T;
+            }
+        }
+
+        if (!res.ok) {
+            let fallbackMessage = res.statusText;
+            if (res.status === 404 && !fallbackMessage) {
+                const method = init?.method || "GET";
+                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,
+                body?.error?.message || body?.message || fallbackMessage || `Request failed with status ${res.status}`,
+                body?.error?.code || body?.code,
+                body?.error?.details || body?.details
+            );
+        }
+
+        return body as T;
+    }
+
+    return {
+        request,
+        setToken(newToken: string | null) { token = newToken || undefined; },
+        setAuthTokenGetter(getter: () => Promise<string | null>) { tokenGetter = getter; },
+        setOnUnauthorized(handler: () => Promise<boolean>) { onUnauthorizedHandler = handler; },
+        get baseUrl() { return config.baseUrl ? config.baseUrl.replace(/\/$/, "") : ""; },
+        get apiPath() { return apiPath; },
+        get fetchFn() { return fetchFn; },
+        getHeaders: (init?: RequestInit) => getHeaders(token, init) as Record<string, string>,
+        resolveToken: async () => {
+            if (tokenGetter) {
+                try {
+                    const fetched = await tokenGetter();
+                    if (fetched !== null && fetched !== undefined) {
+                        return fetched;
+                    }
+                } catch (e) { /* ignore */ }
+            }
+            return token || null;
+        }
+    };
+}