openbase-js 0.1.7 → 0.1.9

package/README.md

@@ -0,0 +1,182 @@
+# OpenBase JS SDK
+
+The OpenBase JS SDK provides a lightweight, expressive interface for interacting with your OpenBase projects. It handles database queries (PostgreSQL), file storage (S3/MinIO), and realtime subscriptions via a simple, Supabase-like API.
+
+## 📦 Installation
+
+```bash
+npm install openbase-js
+# or
+yarn add openbase-js
+```
+
+> [!NOTE]  
+> If you are using Node.js for file uploads, you will also need `form-data`:  
+> `npm install form-data`
+
+## 🚀 Quick Start
+
+Initialize the client with your project URL, API key, and database name.
+
+```javascript
+const { createClient } = require('openbase-js');
+
+const openbase = createClient(
+  'http://localhost:3003', // The URL where your OpenBase backend is running
+  'your-anon-key',
+  'your-db-name'
+);
+
+// Fetch data
+async function getLeads() {
+  const { data, error } = await openbase
+    .from('leads')
+    .select('*')
+    .eq('status', 'active');
+  
+  if (error) console.error(error);
+  else console.log(data);
+}
+```
+
+---
+
+## 📊 Database Operations
+
+OpenBase uses a chainable query builder for database operations.
+
+### Basic CRUD
+
+#### Select
+```javascript
+const { data } = await openbase.from('users').select('id, username');
+```
+
+#### Insert
+```javascript
+const { data } = await openbase.from('users').insert({
+  username: 'jdoe',
+  email: 'john@example.com'
+});
+```
+
+#### Update
+```javascript
+const { data } = await openbase.from('users')
+  .update({ email: 'newemail@example.com' })
+  .eq('id', 1);
+```
+
+#### Delete
+```javascript
+const { data } = await openbase.from('users')
+  .delete()
+  .eq('id', 1);
+```
+
+### 🔍 Detailed Operator Guide
+
+Filtering is done using chainable operator methods.
+
+| Operator | Method | Description | Example |
+| :--- | :--- | :--- | :--- |
+| `==` | `.eq(col, val)` | Equal to | `.eq('name', 'Alice')` |
+| `>` | `.gt(col, val)` | Greater than | `.gt('age', 21)` |
+| `<` | `.lt(col, val)` | Less than | `.lt('score', 50)` |
+| `>=` | `.gte(col, val)` | Greater than or equal to | `.gte('price', 100)` |
+| `<=` | `.lte(col, val)` | Less than or equal to | `.lte('stock', 5)` |
+| `LIKE` | `.like(col, pattern)` | Case-sensitive pattern match | `.like('name', '%son%')` |
+| `ILIKE` | `.ilike(col, pattern)`| Case-insensitive pattern match | `.ilike('name', '%SON%')` |
+| `IN` | `.in(col, array)` | Contained in array | `.in('role', ['admin', 'mod'])` |
+| `IS` | `.is(col, value)` | Check for `null` or `boolean` | `.is('deleted_at', null)` |
+
+### 🛠️ Modifiers
+
+*   **`.order(column, { ascending: boolean })`**: Sort the results.
+*   **`.limit(count)`**: Limit the number of rows returned.
+*   **`.range(from, to)`**: Pagination (0-indexed, inclusive).
+*   **`.single()`**: Returns a single object instead of an array.
+
+```javascript
+const { data } = await openbase
+  .from('posts')
+  .select('*')
+  .gt('likes', 10)
+  .order('created_at', { ascending: false })
+  .range(0, 9) // First 10 items
+```
+
+---
+
+## 📁 Storage
+
+OpenBase provides built-in S3-compatible storage.
+
+### Uploading Files
+
+In the browser, you can pass a `File` or `Blob`. In Node.js, you can pass a file path, `Buffer`, or `ReadStream`.
+
+```javascript
+// Browser
+const file = event.target.files[0];
+const { data, error } = await openbase.storage.upload(file, 'profile.jpg');
+
+// Node.js (requires form-data)
+const { data, error } = await openbase.storage.upload('./local-image.png', 'remote-name.png');
+```
+
+### Listing & Managing Files
+
+```javascript
+// List all files in bucket
+const { data: files } = await openbase.storage.list();
+
+// Get a public presigned URL (valid for 7 days)
+const { data: { url } } = await openbase.storage.getUrl('profile.jpg');
+
+// Remove a file
+await openbase.storage.remove('profile.jpg');
+```
+
+---
+
+## 🔄 Realtime
+
+Subscribe to database changes using WebSockets.
+
+```javascript
+const subscription = openbase
+  .from('messages')
+  .on('INSERT', (payload) => {
+    console.log('New message:', payload.record);
+  })
+  .subscribe();
+
+// To stop listening
+// subscription.unsubscribe();
+```
+
+---
+
+## ⌨️ TypeScript Support
+
+The SDK is written with full TypeScript support. Types are automatically included.
+
+```typescript
+interface Lead {
+  id: number;
+  company_name: string;
+}
+
+const { data } = await openbase.from<Lead>('leads').select('*');
+// data is typed as Lead[] | null
+```
+
+---
+
+## 🧪 Testing
+
+To run the local tests:
+1. Ensure the OpenBase backend is running.
+2. Update the credentials in `test.js`.
+3. Run: `node test.js`

package/index.cjs

@@ -1,11 +1,13 @@
 // ─── Query Builder ────────────────────────────────────────────────────────────
 
 class QueryBuilder {
-  constructor(baseUrl, apiKey, dbName, table) {
+  constructor(baseUrl, apiKey, dbName, table, anonKey, sessionToken = null) {
     this._baseUrl = baseUrl;
     this._apiKey = apiKey;
     this._dbName = dbName;
     this._table = table;
+    this._anonKey = anonKey;
+    this._sessionToken = sessionToken;
     this._filters = [];
     this._columns = '*';
     this._limitVal = null;
@@ -27,7 +29,7 @@ class QueryBuilder {
   on(event, callback) {
     if (!this._realtimeSub) {
       this._realtimeSub = new RealtimeSubscription(
-        this._baseUrl, this._apiKey, this._dbName, this._table
+        this._baseUrl, this._apiKey, this._dbName, this._table, this._anonKey
       );
     }
     this._realtimeSub.on(event, callback);
@@ -37,7 +39,7 @@ class QueryBuilder {
   subscribe() {
     if (!this._realtimeSub) {
       this._realtimeSub = new RealtimeSubscription(
-        this._baseUrl, this._apiKey, this._dbName, this._table
+        this._baseUrl, this._apiKey, this._dbName, this._table, this._anonKey
       );
     }
     return this._realtimeSub.subscribe();
@@ -134,117 +136,154 @@ class QueryBuilder {
     return this;
   }
 
-  // ─── SQL Builder ───────────────────────────────────────────────────────────
-
-  _filterToSQL(f) {
-    const col = `"${f.col}"`;
-    switch (f.op) {
-      case 'eq': return typeof f.val === 'string' ? `${col} = '${f.val}'` : `${col} = ${f.val}`;
-      case 'gt': return `${col} > ${f.val}`;
-      case 'lt': return `${col} < ${f.val}`;
-      case 'gte': return `${col} >= ${f.val}`;
-      case 'lte': return `${col} <= ${f.val}`;
-      case 'like': return `${col} LIKE '${f.val}'`;
-      case 'ilike': return `${col} ILIKE '${f.val}'`;
-      case 'in': {
-        const list = f.val.map(v => typeof v === 'string' ? `'${v}'` : v).join(', ');
-        return `${col} IN (${list})`;
-      }
-      case 'is': {
-        if (f.val === null) return `${col} IS NULL`;
-        if (f.val === true) return `${col} IS TRUE`;
-        if (f.val === false) return `${col} IS FALSE`;
-        return `${col} IS NULL`;
-      }
-      default: return `${col} = '${f.val}'`;
-    }
+  upsert(data, onConflict = 'id') {
+    this._operation = 'upsert';
+    this._insertData = data;
+    this._upsertOnConflict = onConflict;
+    return this;
   }
 
-  _buildSQL() {
-    let sql = '';
+  // ─── Executor ──────────────────────────────────────────────────────────────
 
-    if (this._operation === 'select') {
-      sql = `SELECT ${this._columns} FROM "${this._table}"`;
-      if (this._filters.length) {
-        const where = this._filters.map(f => this._filterToSQL(f)).join(' AND ');
-        sql += ` WHERE ${where}`;
-      }
-      if (this._orderCol) {
-        sql += ` ORDER BY "${this._orderCol}" ${this._orderAsc ? 'ASC' : 'DESC'}`;
-      }
-      if (this._limitVal) sql += ` LIMIT ${this._limitVal}`;
-      if (this._offsetVal) sql += ` OFFSET ${this._offsetVal}`;
-
-    } else if (this._operation === 'insert') {
-      const cols = Object.keys(this._insertData).map(c => `"${c}"`).join(', ');
-      const vals = Object.values(this._insertData).map(v =>
-        typeof v === 'string' ? `'${v.replace(/'/g, "''")}'` : v
-      ).join(', ');
-      sql = `INSERT INTO "${this._table}" (${cols}) VALUES (${vals}) RETURNING *`;
-
-    } else if (this._operation === 'update') {
-      const setClauses = Object.entries(this._updateData).map(([col, val]) =>
-        typeof val === 'string' ? `"${col}" = '${val.replace(/'/g, "''")}'` : `"${col}" = ${val}`
-      ).join(', ');
-      sql = `UPDATE "${this._table}" SET ${setClauses}`;
-      if (this._filters.length) {
-        const where = this._filters.map(f => this._filterToSQL(f)).join(' AND ');
-        sql += ` WHERE ${where}`;
+  async _buildAndRun() {
+    try {
+      const headers = {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this._apiKey}`,
+        'X-Anon-Key': this._anonKey,
+      };
+
+      // If we have an active end-user session, use its token instead of the anon key
+      if (this._sessionToken) {
+        headers['Authorization'] = `Bearer ${this._sessionToken}`;
       }
-      sql += ` RETURNING *`;
 
-    } else if (this._operation === 'delete') {
-      sql = `DELETE FROM "${this._table}"`;
-      if (this._filters.length) {
-        const where = this._filters.map(f => this._filterToSQL(f)).join(' AND ');
-        sql += ` WHERE ${where}`;
-      }
-      sql += ` RETURNING *`;
+      const body = {
+        db_name: this._dbName,
+        table: this._table,
+        operation: this._operation,
+        columns: this._columns,
+        filters: this._filters,
+        limit: this._limitVal,
+        offset: this._offsetVal,
+        order_col: this._orderCol,
+        order_asc: this._orderAsc,
+        data: (this._operation === 'insert' || this._operation === 'upsert') ? this._insertData : this._updateData,
+        upsert_on_conflict: this._upsertOnConflict
+      };
+
+      const res = await fetch(`${this._baseUrl}/sdk/query`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+      });
+
+      const json = await res.json();
+      const { data, error } = json;
+      if (error) return { data: null, error };
+      if (this._single) return { data: data[0] || null, error: null };
+      return { data, error: null };
+    } catch (err) {
+      return { data: null, error: err.message };
     }
+  }
 
-    return sql;
+  then(resolve, reject) {
+    return this._buildAndRun().then(resolve, reject);
   }
+}
 
-  // ─── Executor ──────────────────────────────────────────────────────────────
+// ─── Auth Client ───────────────────────────────────────────────────────────────
 
-  async _buildAndRun() {
-    const sql = this._buildSQL();
+class AuthClient {
+  constructor(client) {
+    this._client = client;
+  }
+
+  async signUp(email, password) {
     try {
-      const res = await fetch(`${this._baseUrl}/query`, {
+      const res = await fetch(`${this._client._baseUrl}/sdk/auth/signup`, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
-          'Authorization': `Bearer ${this._apiKey}`,
+          'Authorization': `Bearer ${this._client._apiKey}`
         },
-        body: JSON.stringify({ sql, db_name: this._dbName }),
+        body: JSON.stringify({
+          db_name: this._client._dbName,
+          email,
+          password
+        }),
       });
+      const json = await res.json();
+      if (json.data && json.data.session) {
+        this._client._session = json.data.session;
+      }
+      return json;
+    } catch (err) {
+      return { data: null, error: err.message };
+    }
+  }
 
+  async signIn(email, password) {
+    try {
+      const res = await fetch(`${this._client._baseUrl}/sdk/auth/signin`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${this._client._apiKey}`
+        },
+        body: JSON.stringify({
+          db_name: this._client._dbName,
+          email,
+          password
+        }),
+      });
       const json = await res.json();
-      const { data, error } = json;
-      if (error) return { data: null, error };
-      if (this._single) return { data: data[0] || null, error: null };
-      return { data, error: null };
+      if (json.data && json.data.session) {
+        this._client._session = json.data.session;
+      }
+      return json;
     } catch (err) {
       return { data: null, error: err.message };
     }
   }
 
-  then(resolve, reject) {
-    return this._buildAndRun().then(resolve, reject);
+  async getSession() {
+    if (!this._client._session) return { data: null, error: null };
+    try {
+      const res = await fetch(`${this._client._baseUrl}/sdk/auth/session`, {
+        headers: {
+          'Authorization': `Bearer ${this._client._session.access_token}`
+        }
+      });
+      return await res.json();
+    } catch (err) {
+      return { data: null, error: err.message };
+    }
+  }
+
+  signOut() {
+    this._client._session = null;
+    return { data: { ok: true }, error: null };
   }
 }
 
 // ─── Storage Client ───────────────────────────────────────────────────────────
 
 class StorageClient {
-  constructor(baseUrl, apiKey, dbName) {
-    this._baseUrl = baseUrl;
-    this._apiKey = apiKey;
-    this._dbName = dbName;
+  constructor(client) {
+    this._client = client;
   }
 
   _headers() {
-    return { 'Authorization': `Bearer ${this._apiKey}` };
+    const headers = { 
+      'Authorization': `Bearer ${this._client._apiKey}`,
+      'X-Anon-Key': this._client._anonKey
+    };
+    if (this._client._session) {
+      headers['Authorization'] = `Bearer ${this._client._session.access_token}`;
+    }
+    return headers;
   }
 
   // Detect if we're running in Node.js
@@ -253,8 +292,6 @@ class StorageClient {
   }
 
   // Build a FormData object that works in both browser and Node.js
-  // In browser: file = File or Blob object
-  // In Node.js: file = file path string, Buffer, or ReadStream
   async _buildFormData(file, filename) {
     if (this._isNode()) {
       // Node.js — use form-data package
@@ -273,14 +310,11 @@ class StorageClient {
       const formData = new FormDataNode();
 
       if (typeof file === 'string') {
-        // file path string — read from disk
         const resolvedName = filename || path.basename(file);
         formData.append('file', fs.createReadStream(file), resolvedName);
       } else if (Buffer.isBuffer(file)) {
-        // Buffer
         formData.append('file', file, filename || 'file');
       } else {
-        // ReadStream or anything else
         formData.append('file', file, filename || 'file');
       }
 
@@ -294,14 +328,10 @@ class StorageClient {
     }
   }
 
-  // Upload a file
-  // Browser: pass a File or Blob (from <input type="file"> or drag-and-drop)
-  // Node.js: pass a file path string, Buffer, or ReadStream
   async upload(file, filename) {
     try {
       const formData = await this._buildFormData(file, filename);
 
-      // In Node.js, form-data needs its own headers (includes boundary)
       const headers = this._isNode()
         ? { ...this._headers(), ...formData.getHeaders() }
         : this._headers();
@@ -317,7 +347,6 @@ class StorageClient {
     }
   }
 
-  // List all files in this project's bucket
   async list() {
     try {
       const res = await fetch(`${this._baseUrl}/storage/${this._dbName}/list`, {
@@ -329,7 +358,6 @@ class StorageClient {
     }
   }
 
-  // Get a presigned URL valid for 7 days
   async getUrl(filename) {
     try {
       const res = await fetch(`${this._baseUrl}/storage/${this._dbName}/url/${encodeURIComponent(filename)}`, {
@@ -341,7 +369,6 @@ class StorageClient {
     }
   }
 
-  // Delete a file
   async remove(filename) {
     try {
       const res = await fetch(`${this._baseUrl}/storage/${this._dbName}/${encodeURIComponent(filename)}`, {
@@ -358,12 +385,13 @@ class StorageClient {
 // ─── Realtime Subscription ────────────────────────────────────────────────────
 
 class RealtimeSubscription {
-  constructor(baseUrl, apiKey, dbName, table) {
+  constructor(baseUrl, apiKey, dbName, table, anonKey) {
     this._baseUrl = baseUrl.replace('http://', 'ws://').replace('https://', 'wss://');
     this._apiKey = apiKey;
     this._dbName = dbName;
     this._table = table;
-    this._listeners = {}; // { INSERT: [fn], UPDATE: [fn], DELETE: [fn] }
+    this._anonKey = anonKey;
+    this._listeners = {}; 
     this._ws = null;
   }
 
@@ -374,7 +402,7 @@ class RealtimeSubscription {
   }
 
   subscribe() {
-    const url = `${this._baseUrl}/realtime/${this._dbName}/${this._table}?token=${this._apiKey}`;
+    const url = `${this._baseUrl}/realtime/${this._dbName}/${this._table}?token=${this._apiKey}&anon_key=${this._anonKey}`;
     this._ws = new WebSocket(url);
 
     this._ws.onmessage = (e) => {
@@ -404,25 +432,35 @@ class RealtimeSubscription {
 // ─── Client ───────────────────────────────────────────────────────────────────
 
 class OpenbaseClient {
-  constructor(baseUrl, apiKey, dbName) {
+  constructor(baseUrl, apiKey, dbName, options = {}) {
     this._baseUrl = baseUrl.replace(/\/$/, '');
     this._apiKey = apiKey;
     this._dbName = dbName;
-    this.storage = new StorageClient(this._baseUrl, this._apiKey, this._dbName);
+    this._anonKey = options.anonKey || apiKey; // Default to apiKey if anonKey not provided
+    this._session = null;
+    this.storage = new StorageClient(this);
+    this.auth = new AuthClient(this);
   }
 
   from(table) {
-    return new QueryBuilder(this._baseUrl, this._apiKey, this._dbName, table);
+    return new QueryBuilder(
+      this._baseUrl, 
+      this._apiKey, 
+      this._dbName, 
+      table, 
+      this._anonKey,
+      this._session ? this._session.access_token : null
+    );
   }
 }
 
 // ─── Factory ──────────────────────────────────────────────────────────────────
 
-function createClient(baseUrl, apiKey, dbName) {
-  if (!baseUrl) throw new Error('[openbase] Missing baseUrl. Pass your backend URL as the first argument.');
-  if (!apiKey) throw new Error('[openbase] Missing apiKey. Pass your anon or service key as the second argument.');
-  if (!dbName) throw new Error('[openbase] Missing dbName. Pass your database name as the third argument.');
-  return new OpenbaseClient(baseUrl, apiKey, dbName);
+function createClient(baseUrl, apiKey, dbName, options = {}) {
+  if (!baseUrl) throw new Error('[openbase] Missing baseUrl.');
+  if (!apiKey) throw new Error('[openbase] Missing apiKey.');
+  if (!dbName) throw new Error('[openbase] Missing dbName.');
+  return new OpenbaseClient(baseUrl, apiKey, dbName, options);
 }
 
 if (typeof module !== 'undefined') {
@@ -432,4 +470,3 @@ if (typeof module !== 'undefined') {
 if (typeof window !== 'undefined') {
   window.openbase = { createClient };
 }
-module.exports = { createClient };

package/index.d.ts

@@ -6,6 +6,31 @@ export interface OpenbaseResponse<T> {
   error: string | null;
 }
 
+export interface OpenbaseClientOptions {
+  /**
+   * The public Anon Key for your project. 
+   * If not provided, the 'apiKey' argument will be used as the project identifier.
+   */
+  anonKey?: string;
+}
+
+export interface User {
+  id: string;
+  email: string;
+  created_at: string;
+}
+
+export interface Session {
+  access_token: string;
+}
+
+export declare class AuthClient {
+  signUp(email: string, password: string): Promise<OpenbaseResponse<{ user: User, session: Session }>>;
+  signIn(email: string, password: string): Promise<OpenbaseResponse<{ user: User, session: Session }>>;
+  getSession(): Promise<OpenbaseResponse<{ user: User }>>;
+  signOut(): OpenbaseResponse<{ ok: boolean }>;
+}
+
 export declare class QueryBuilder<T = Record<string, unknown>> {
   // Column selection
   select(columns?: string): this;
@@ -31,6 +56,7 @@ export declare class QueryBuilder<T = Record<string, unknown>> {
   insert(data: Partial<T>): this;
   update(data: Partial<T>): this;
   delete(): this;
+  upsert(data: Partial<T>, onConflict?: string): this;
 
   then<R>(
     resolve: (value: OpenbaseResponse<T[]>) => R,
@@ -91,6 +117,9 @@ export declare class OpenbaseClient {
   /** Storage client for file upload, listing, URLs, and deletion */
   storage: StorageClient;
 
+  /** Auth client for user registration, login, and session management */
+  auth: AuthClient;
+
   /** Query builder for database operations */
   from<T = Record<string, unknown>>(table: string): QueryBuilder<T>;
 }
@@ -98,7 +127,8 @@ export declare class OpenbaseClient {
 export declare function createClient(
   baseUrl: string,
   apiKey: string,
-  dbName: string
+  dbName: string,
+  options?: OpenbaseClientOptions
 ): OpenbaseClient;
 
 export declare class RealtimeSubscription {