corebase-js 0.1.1 → 0.2.3

package/README.md

@@ -6,6 +6,9 @@ A robust JavaScript/TypeScript client for communicating with your CoreBase backe
 
 ```bash
 npm install corebase-js
+
+# If using React/React Native hooks (Optioanal peer dependency)
+npm install --save-dev react @types/react
 ```
 
 ## Initialization
@@ -171,6 +174,67 @@ const { data, error } = await corebase
   .eq('id', 123);
 ```
 
+## File Storage
+
+Upload files to your project buckets.
+
+### Upload File
+
+Upload a file directly from the browser (e.g., from an `<input type="file" />`).
+
+```typescript
+// Assuming you have an input element: <input type="file" id="fileInput" />
+const fileInput = document.getElementById('fileInput') as HTMLInputElement;
+const file = fileInput.files?.[0];
+
+if (file) {
+  const { data, error } = await corebase.storage.upload(file);
+
+  if (error) {
+    console.error('Upload failed:', error);
+  } else {
+    console.log('File uploaded successfully!');
+    console.log('File Key:', data.key);
+    console.log('Upload URL:', data.url);
+  }
+}
+```
+
+## Realtime Data (React / React Native)
+
+Subscribe to live data changes using the `useQuery` hook.
+
+```typescript
+import { useQuery } from 'corebase-js/react';
+
+// Define your query
+const query = {
+  from: 'posts',
+  select: ['id', 'title', 'likes'],
+  where: { 
+    status: 'published' 
+  }
+};
+
+const MyComponent = () => {
+  // Subscribe to realtime updates
+  const { data, loading, error } = useQuery(corebase, query);
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <ul>
+      {data.map(post => (
+        <li key={post.id}>
+          {post.title} ({post.likes} likes)
+        </li>
+      ))}
+    </ul>
+  );
+};
+```
+
 ## TypeScript Support
 
 This library is written in TypeScript and exports types for all responses.

package/dist/client.d.ts

@@ -1,8 +1,12 @@
 import { AuthClient } from './auth';
 import { QueryBuilder } from './query';
+import { StorageClient } from './storage';
+import { RealtimeClient } from './realtime';
 import { ClientConfig } from './types';
 export declare class CoreBaseClient {
     auth: AuthClient;
+    storage: StorageClient;
+    realtime: RealtimeClient;
     private config;
     constructor(config: ClientConfig);
     from<T = any>(table: string): QueryBuilder<T>;

package/dist/client.js

@@ -4,6 +4,8 @@ exports.CoreBaseClient = void 0;
 exports.createClient = createClient;
 const auth_1 = require("./auth");
 const query_1 = require("./query");
+const storage_1 = require("./storage");
+const realtime_1 = require("./realtime");
 class CoreBaseClient {
     constructor(config) {
         if (!config.apiKey) {
@@ -14,6 +16,8 @@ class CoreBaseClient {
         }
         this.config = config;
         this.auth = new auth_1.AuthClient(config);
+        this.storage = new storage_1.StorageClient(this.auth);
+        this.realtime = new realtime_1.RealtimeClient(config, this.auth);
     }
     from(table) {
         return new query_1.QueryBuilder((path, options) => this.auth.request(path, options), table);

package/dist/index.d.ts

@@ -2,3 +2,5 @@ export * from './types';
 export * from './client';
 export * from './auth';
 export * from './query';
+export * from './storage';
+export * from './realtime';

package/dist/index.js

@@ -18,3 +18,5 @@ __exportStar(require("./types"), exports);
 __exportStar(require("./client"), exports);
 __exportStar(require("./auth"), exports);
 __exportStar(require("./query"), exports);
+__exportStar(require("./storage"), exports);
+__exportStar(require("./realtime"), exports);

package/dist/react.d.ts

@@ -0,0 +1,21 @@
+import { CoreBaseClient } from './client';
+export interface UseQueryOptions {
+    enabled?: boolean;
+    onData?: (data: any) => void;
+    onError?: (error: any) => void;
+}
+export interface UseQueryResult<T> {
+    data: T | null;
+    loading: boolean;
+    error: any;
+}
+/**
+ * Hook to subscribe to realtime data queries.
+ * Compatible with React and React Native.
+ *
+ * @param client - The CoreBaseClient instance
+ * @param query - The query object definition
+ * @param options - Options for the hook
+ * @returns The current data, loading state, and error
+ */
+export declare function useQuery<T = any>(client: CoreBaseClient, query: any, options?: UseQueryOptions): UseQueryResult<T>;

package/dist/react.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useQuery = useQuery;
+const react_1 = require("react");
+/**
+ * Hook to subscribe to realtime data queries.
+ * Compatible with React and React Native.
+ *
+ * @param client - The CoreBaseClient instance
+ * @param query - The query object definition
+ * @param options - Options for the hook
+ * @returns The current data, loading state, and error
+ */
+function useQuery(client, query, options = {}) {
+    const [data, setData] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    const { enabled = true, onData, onError } = options;
+    // Use stringified query to detect changes deeply
+    const queryJson = JSON.stringify(query);
+    (0, react_1.useEffect)(() => {
+        if (!enabled) {
+            setLoading(false);
+            return;
+        }
+        let subId;
+        const subscribe = () => {
+            setLoading(true);
+            setError(null);
+            try {
+                if (!client.realtime) {
+                    throw new Error("RealtimeClient is not initialized on the CoreBaseClient instance.");
+                }
+                subId = client.realtime.subscribe(query, (newData) => {
+                    setData(newData);
+                    setLoading(false);
+                    if (onData)
+                        onData(newData);
+                });
+            }
+            catch (err) {
+                console.error("CoreBase useQuery error:", err);
+                setError(err);
+                setLoading(false);
+                if (onError)
+                    onError(err);
+            }
+        };
+        subscribe();
+        return () => {
+            if (subId && client.realtime) {
+                client.realtime.unsubscribe(subId);
+            }
+        };
+    }, [client, queryJson, enabled]); // Re-run if client, query or enabled status changes
+    return { data, loading, error };
+}

package/dist/realtime.d.ts

@@ -0,0 +1,28 @@
+import { AuthClient } from './auth';
+import { ClientConfig } from './types';
+export interface RealtimeMessage {
+    type: 'subscribe' | 'unsubscribe' | 'data' | 'error';
+    id?: string;
+    query?: any;
+    data?: any;
+    error?: any;
+}
+export type RealtimeCallback = (data: any) => void;
+export declare class RealtimeClient {
+    private ws;
+    private subscriptions;
+    private reconnectTimer;
+    private config;
+    private auth;
+    private isConnected;
+    constructor(config: ClientConfig, auth: AuthClient);
+    private getUrl;
+    connect(): void;
+    disconnect(): void;
+    subscribe(query: any, callback: RealtimeCallback): string;
+    unsubscribe(id: string): void;
+    private send;
+    private handleMessage;
+    private resubscribeAll;
+    private scheduleReconnect;
+}

package/dist/realtime.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeClient = void 0;
+class RealtimeClient {
+    constructor(config, auth) {
+        this.ws = null;
+        this.subscriptions = new Map();
+        this.reconnectTimer = null;
+        this.isConnected = false;
+        this.config = config;
+        this.auth = auth;
+    }
+    getUrl() {
+        var _a;
+        const baseUrl = this.config.baseUrl || 'http://localhost:3000';
+        let url = baseUrl.replace(/^http/, 'ws') + '/v1/realtime';
+        // Append Auth params for standard browser support (which doesn't support headers)
+        const params = new URLSearchParams();
+        if (this.config.apiKey) {
+            params.append('x-api-key', this.config.apiKey);
+        }
+        const token = (_a = this.auth.getSession()) === null || _a === void 0 ? void 0 : _a.access_token;
+        if (token) {
+            params.append('token', token);
+        }
+        const queryString = params.toString();
+        if (queryString) {
+            url += `?${queryString}`;
+        }
+        return url;
+    }
+    connect() {
+        var _a;
+        if (this.ws && (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING))
+            return;
+        const url = this.getUrl();
+        const headers = {
+            'x-api-key': this.config.apiKey
+        };
+        const token = (_a = this.auth.getSession()) === null || _a === void 0 ? void 0 : _a.access_token;
+        if (token) {
+            headers['Authorization'] = `Bearer ${token}`;
+        }
+        try {
+            // Try to pass headers (Node.js / React Native)
+            // @ts-ignore
+            this.ws = new WebSocket(url, undefined, { headers });
+        }
+        catch (e) {
+            // Fallback for standard browsers
+            this.ws = new WebSocket(url);
+        }
+        if (!this.ws)
+            return;
+        this.ws.onopen = () => {
+            this.isConnected = true;
+            this.resubscribeAll();
+        };
+        this.ws.onmessage = (event) => {
+            try {
+                const msg = JSON.parse(event.data);
+                this.handleMessage(msg);
+            }
+            catch (e) {
+                console.error('CoreBase Realtime parse error', e);
+            }
+        };
+        this.ws.onclose = () => {
+            this.isConnected = false;
+            this.scheduleReconnect();
+        };
+        this.ws.onerror = (e) => {
+            console.error('CoreBase Realtime error', e);
+        };
+    }
+    disconnect() {
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.isConnected = false;
+    }
+    subscribe(query, callback) {
+        const id = Math.random().toString(36).substring(7);
+        this.subscriptions.set(id, { query, callback });
+        if (this.isConnected) {
+            this.send({ type: 'subscribe', id, query });
+        }
+        else {
+            this.connect();
+        }
+        return id;
+    }
+    unsubscribe(id) {
+        if (this.subscriptions.has(id)) {
+            this.subscriptions.delete(id);
+            if (this.isConnected) {
+                this.send({ type: 'unsubscribe', id });
+            }
+        }
+    }
+    send(msg) {
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+    handleMessage(msg) {
+        if (msg.type === 'data' && msg.id && msg.data) {
+            const sub = this.subscriptions.get(msg.id);
+            if (sub) {
+                sub.callback(msg.data);
+            }
+        }
+        else if (msg.type === 'error') {
+            console.error('CoreBase Realtime message error:', msg.error);
+        }
+    }
+    resubscribeAll() {
+        this.subscriptions.forEach((sub, id) => {
+            this.send({ type: 'subscribe', id, query: sub.query });
+        });
+    }
+    scheduleReconnect() {
+        if (!this.reconnectTimer) {
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = null;
+                this.connect();
+            }, 3000);
+        }
+    }
+}
+exports.RealtimeClient = RealtimeClient;

package/dist/storage.d.ts

@@ -0,0 +1,20 @@
+import { AuthClient } from './auth';
+import { ClientResponse } from './types';
+export declare class StorageClient {
+    private auth;
+    constructor(auth: AuthClient);
+    /**
+     * Uploads a file to the storage bucket.
+     * This involves two steps:
+     * 1. Getting a signed upload URL from the API.
+     * 2. Uploading the file content directly to the cloud storage provider via the signed URL.
+     *
+     * @param file The File object to upload.
+     * @param bucketName The name of the bucket to upload the file to.
+     * @returns The key of the uploaded file.
+     */
+    upload(file: File, bucketName: string): Promise<ClientResponse<{
+        key: string;
+        url: string;
+    }>>;
+}

package/dist/storage.js

@@ -0,0 +1,79 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageClient = void 0;
+class StorageClient {
+    constructor(auth) {
+        this.auth = auth;
+    }
+    /**
+     * Uploads a file to the storage bucket.
+     * This involves two steps:
+     * 1. Getting a signed upload URL from the API.
+     * 2. Uploading the file content directly to the cloud storage provider via the signed URL.
+     *
+     * @param file The File object to upload.
+     * @param bucketName The name of the bucket to upload the file to.
+     * @returns The key of the uploaded file.
+     */
+    upload(file, bucketName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 1. Get Signed URL
+            const { data: signData, error: signError } = yield this.auth.request('/storage/upload/sign', {
+                method: 'POST',
+                body: JSON.stringify({
+                    filename: file.name,
+                    contentType: file.type,
+                    size: file.size,
+                    bucketName
+                }),
+            });
+            if (signError) {
+                return { data: null, error: signError };
+            }
+            if (!signData) {
+                return { data: null, error: { message: 'Failed to retrieve signed upload URL.' } };
+            }
+            try {
+                // 2. Upload File to Signed URL
+                const uploadResponse = yield fetch(signData.uploadUrl, {
+                    method: 'PUT',
+                    headers: {
+                        'Content-Type': file.type,
+                    },
+                    body: file,
+                });
+                if (!uploadResponse.ok) {
+                    return {
+                        data: null,
+                        error: {
+                            message: `File upload failed with status ${uploadResponse.status}: ${uploadResponse.statusText}`
+                        }
+                    };
+                }
+                // Return success with the key. 
+                // The URL returned by sign is the upload URL (often with SAS/Signature params).
+                // Users typically store the 'key' to reference the file later.
+                return {
+                    data: {
+                        key: signData.key,
+                        url: signData.uploadUrl // Returning the upload URL might be useful for immediate access if it's still valid/public-read
+                    },
+                    error: null
+                };
+            }
+            catch (err) {
+                return { data: null, error: { message: err.message || 'Network error during file upload.' } };
+            }
+        });
+    }
+}
+exports.StorageClient = StorageClient;

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "corebase-js",
-  "version": "0.1.1",
+  "version": "0.2.3",
   "description": "JavaScript client for CoreBase",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./react": "./dist/react.js"
+  },
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build"
@@ -20,6 +24,16 @@
   "license": "ISC",
   "type": "commonjs",
   "devDependencies": {
+    "@types/react": "^19.2.10",
+    "react": "^19.2.4",
     "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   }
 }