fivebit-client 0.1.0 → 0.2.0

package/dist/FivebitClient.d.ts

@@ -1,4 +1,6 @@
 import { AuthClient } from './AuthClient';
+import { RealtimeClient } from './RealtimeClient';
+import { StorageClient } from './StorageClient';
 export interface FivebitConfig {
     url: string;
     apiKey?: string;
@@ -16,8 +18,9 @@ export interface QueryResult<T> {
 export declare class FivebitClient {
     config: FivebitConfig;
     auth: AuthClient;
+    storage: StorageClient;
+    realtime: RealtimeClient;
     private _query;
-    private _rt;
     private _session;
     constructor(config: FivebitConfig);
     get session(): AuthSession | null;
@@ -28,8 +31,19 @@ export declare class FivebitClient {
         update(id: number, record: Partial<T>): Promise<QueryResult<T>>;
         delete(id: number): Promise<boolean>;
         query(field: string, value: string, limit?: number): Promise<T[]>;
+        count(filter?: string): Promise<number>;
+        sum(field: string, filter?: string): Promise<number>;
+        avg(field: string, filter?: string): Promise<number>;
+        min(field: string): Promise<number>;
+        max(field: string): Promise<number>;
+    };
+    onChanges(table: string, fn: (record: any) => void): () => void;
+    channel(name: string): {
+        on(fn: (payload: any) => void): void;
+        broadcast(payload: any): void;
+        presence(userId: number, userName: string): void;
+        readonly users: any[];
     };
-    onChanges(table: string, fn: (record: any) => void): void;
     close(): void;
 }
 export declare function createClient(config: FivebitConfig): FivebitClient;

package/dist/FivebitClient.js

@@ -5,23 +5,23 @@ exports.createClient = createClient;
 const AuthClient_1 = require("./AuthClient");
 const QueryClient_1 = require("./QueryClient");
 const RealtimeClient_1 = require("./RealtimeClient");
+const StorageClient_1 = require("./StorageClient");
 class FivebitClient {
     constructor(config) {
         this._session = null;
         this.config = config;
         this.auth = new AuthClient_1.AuthClient(config.url);
-        this._query = new QueryClient_1.QueryClient(config.url, () => this._session?.token || '');
-        this._rt = new RealtimeClient_1.RealtimeClient(config.url);
+        const getToken = () => this._session?.token || '';
+        this._query = new QueryClient_1.QueryClient(config.url, getToken);
+        this.storage = new StorageClient_1.StorageClient(config.url, getToken);
+        this.realtime = new RealtimeClient_1.RealtimeClient(config.url);
     }
     get session() { return this._session; }
     setSession(s) { this._session = s; }
-    from(table) {
-        return this._query.table(table);
-    }
-    onChanges(table, fn) {
-        this._rt.subscribe(table, fn);
-    }
-    close() { this._rt.close(); }
+    from(table) { return this._query.table(table); }
+    onChanges(table, fn) { return this.realtime.subscribe(table, fn); }
+    channel(name) { return this.realtime.channel(name); }
+    close() { this.realtime.close(); }
 }
 exports.FivebitClient = FivebitClient;
 function createClient(config) {

package/dist/QueryClient.d.ts

@@ -11,5 +11,10 @@ export declare class QueryClient {
         update(id: number, record: Partial<T>): Promise<QueryResult<T>>;
         delete(id: number): Promise<boolean>;
         query(field: string, value: string, limit?: number): Promise<T[]>;
+        count(filter?: string): Promise<number>;
+        sum(field: string, filter?: string): Promise<number>;
+        avg(field: string, filter?: string): Promise<number>;
+        min(field: string): Promise<number>;
+        max(field: string): Promise<number>;
     };
 }

package/dist/QueryClient.js

@@ -32,9 +32,7 @@ class QueryClient {
                 return { data, error: null, etag: newEtag };
             },
             async insert(record) {
-                const r = await fetch(`${self.baseUrl}/records`, {
-                    method: 'POST', headers: self.headers(), body: JSON.stringify(record),
-                });
+                const r = await fetch(`${self.baseUrl}/records`, { method: 'POST', headers: self.headers(), body: JSON.stringify(record) });
                 const data = await r.json();
                 return { data, error: r.ok ? null : data.error, etag: '' };
             },
@@ -43,28 +41,51 @@ class QueryClient {
                 const etag = self.etagCache.get(id);
                 if (etag)
                     h['If-Match'] = `"${etag}"`;
-                const r = await fetch(`${self.baseUrl}/records/${id}`, {
-                    method: 'PUT', headers: h, body: JSON.stringify(record),
-                });
+                const r = await fetch(`${self.baseUrl}/records/${id}`, { method: 'PUT', headers: h, body: JSON.stringify(record) });
                 if (r.status === 412)
-                    return { data: null, error: 'Conflict — record modified', etag: '' };
+                    return { data: null, error: 'Conflict', etag: '' };
                 const data = await r.json();
                 return { data, error: null, etag: '' };
             },
             async delete(id) {
-                const r = await fetch(`${self.baseUrl}/records/${id}`, {
-                    method: 'DELETE', headers: self.headers(),
-                });
+                const r = await fetch(`${self.baseUrl}/records/${id}`, { method: 'DELETE', headers: self.headers() });
                 self.etagCache.delete(id);
                 return r.ok;
             },
             async query(field, value, limit = 20) {
-                const r = await fetch(`${self.baseUrl}/records?field=${field}&value=${value}&limit=${limit}`, {
-                    headers: self.headers(),
-                });
+                const r = await fetch(`${self.baseUrl}/records?field=${field}&value=${value}&limit=${limit}`, { headers: self.headers() });
                 const data = await r.json();
                 return data.results || [];
             },
+            // Aggregates
+            async count(filter) {
+                const q = filter ? `filter=${filter}&aggregate=count` : 'aggregate=count';
+                const r = await fetch(`${self.baseUrl}/query?${q}`, { headers: self.headers() });
+                const d = await r.json();
+                return d.count || 0;
+            },
+            async sum(field, filter) {
+                const q = `aggregate=sum:${field}${filter ? '&filter=' + filter : ''}`;
+                const r = await fetch(`${self.baseUrl}/query?${q}`, { headers: self.headers() });
+                const d = await r.json();
+                return d[`sum_${field}`] || 0;
+            },
+            async avg(field, filter) {
+                const q = `aggregate=avg:${field}${filter ? '&filter=' + filter : ''}`;
+                const r = await fetch(`${self.baseUrl}/query?${q}`, { headers: self.headers() });
+                const d = await r.json();
+                return d[`avg_${field}`] || 0;
+            },
+            async min(field) {
+                const r = await fetch(`${self.baseUrl}/query?aggregate=min:${field}`, { headers: self.headers() });
+                const d = await r.json();
+                return d[`min_${field}`] || 0;
+            },
+            async max(field) {
+                const r = await fetch(`${self.baseUrl}/query?aggregate=max:${field}`, { headers: self.headers() });
+                const d = await r.json();
+                return d[`max_${field}`] || 0;
+            },
         };
     }
 }

package/dist/RealtimeClient.d.ts

@@ -1,12 +1,22 @@
 type ChangeHandler = (record: any) => void;
+type MessageHandler = (payload: any) => void;
 export declare class RealtimeClient {
     private baseUrl;
-    private sources;
-    private handlers;
+    private ws;
+    private tableHandlers;
+    private channelHandlers;
+    private presenceCache;
     private reconnectMs;
+    private wsUrl;
     constructor(baseUrl: string);
-    subscribe(table: string, fn: ChangeHandler): () => void;
     private _connect;
+    subscribe(table: string, fn: ChangeHandler): () => void;
+    channel(name: string): {
+        on(fn: MessageHandler): void;
+        broadcast(payload: any): void;
+        presence(userId: number, userName: string): void;
+        readonly users: any[];
+    };
     close(): void;
 }
 export {};

package/dist/RealtimeClient.js

@@ -3,40 +3,78 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RealtimeClient = void 0;
 class RealtimeClient {
     constructor(baseUrl) {
-        this.sources = new Map();
-        this.handlers = new Map();
+        this.ws = null;
+        this.tableHandlers = new Map();
+        this.channelHandlers = new Map();
+        this.presenceCache = [];
         this.reconnectMs = 3000;
         this.baseUrl = baseUrl;
+        this.wsUrl = baseUrl.replace('http', 'ws') + '/ws';
+        this._connect();
     }
-    subscribe(table, fn) {
-        if (!this.handlers.has(table)) {
-            this.handlers.set(table, new Set());
-            this._connect(table);
-        }
-        this.handlers.get(table).add(fn);
-        return () => this.handlers.get(table)?.delete(fn);
-    }
-    _connect(table) {
-        const url = `${this.baseUrl}/stream/${table}`;
-        const es = new EventSource(url);
-        es.onmessage = (e) => {
+    _connect() {
+        if (typeof WebSocket === 'undefined')
+            return;
+        this.ws = new WebSocket(this.wsUrl);
+        this.ws.onopen = () => {
+            // Re-subscribe to tables
+            for (const table of this.tableHandlers.keys()) {
+                this.ws.send(JSON.stringify({ type: 'subscribe', table }));
+            }
+        };
+        this.ws.onmessage = (e) => {
             try {
-                const record = JSON.parse(e.data);
-                this.handlers.get(table)?.forEach(fn => fn(record));
+                const msg = JSON.parse(e.data);
+                if (msg.type === 'change') {
+                    this.tableHandlers.get(msg.table)?.forEach(fn => fn(msg.event));
+                }
+                else if (msg.type === 'broadcast') {
+                    this.channelHandlers.get(msg.channel)?.forEach(fn => fn(msg.payload));
+                }
+                else if (msg.type === 'presence') {
+                    this.presenceCache = msg.users || [];
+                    this.channelHandlers.get(`__presence:${msg.channel || ''}`)?.forEach(fn => fn(msg));
+                }
             }
             catch { }
         };
-        es.onerror = () => {
-            es.close();
-            setTimeout(() => this._connect(table), this.reconnectMs);
-        };
-        this.sources.set(table, es);
+        this.ws.onclose = () => setTimeout(() => this._connect(), this.reconnectMs);
     }
-    close() {
-        for (const es of this.sources.values())
-            es.close();
-        this.sources.clear();
-        this.handlers.clear();
+    // Table changes (backward compat + new)
+    subscribe(table, fn) {
+        if (!this.tableHandlers.has(table))
+            this.tableHandlers.set(table, new Set());
+        this.tableHandlers.get(table).add(fn);
+        if (this.ws?.readyState === 1) {
+            this.ws.send(JSON.stringify({ type: 'subscribe', table }));
+        }
+        return () => this.tableHandlers.get(table)?.delete(fn);
+    }
+    // Channels (new)
+    channel(name) {
+        const self = this;
+        return {
+            on(fn) {
+                if (!self.channelHandlers.has(name))
+                    self.channelHandlers.set(name, new Set());
+                self.channelHandlers.get(name).add(fn);
+                if (self.ws?.readyState === 1) {
+                    self.ws.send(JSON.stringify({ type: 'channel', channel: name }));
+                }
+            },
+            broadcast(payload) {
+                if (self.ws?.readyState === 1) {
+                    self.ws.send(JSON.stringify({ type: 'broadcast', channel: name, payload }));
+                }
+            },
+            presence(userId, userName) {
+                if (self.ws?.readyState === 1) {
+                    self.ws.send(JSON.stringify({ type: 'presence', userId, name: userName, channel: name }));
+                }
+            },
+            get users() { return self.presenceCache; },
+        };
     }
+    close() { this.ws?.close(); }
 }
 exports.RealtimeClient = RealtimeClient;

package/dist/StorageClient.d.ts

@@ -0,0 +1,23 @@
+export declare class StorageClient {
+    private baseUrl;
+    private getToken;
+    constructor(baseUrl: string, getToken: () => string);
+    bucket(name: string): {
+        upload(path: string, data: Blob | Buffer | Uint8Array): Promise<{
+            path: string;
+            hash: string;
+            size: number;
+        }>;
+        download(path: string): Promise<Blob | null>;
+        list(opts?: {
+            prefix?: string;
+            limit?: number;
+        }): Promise<{
+            path: string;
+            size: number;
+            hash: string;
+        }[]>;
+        remove(path: string): Promise<boolean>;
+    };
+    private _auth;
+}

package/dist/StorageClient.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageClient = void 0;
+class StorageClient {
+    constructor(baseUrl, getToken) {
+        this.baseUrl = baseUrl;
+        this.getToken = getToken;
+    }
+    bucket(name) {
+        const self = this;
+        return {
+            async upload(path, data) {
+                const form = new FormData();
+                const blob = data instanceof Blob ? data : new Blob([data]);
+                form.append('file', blob, path);
+                const r = await fetch(`${self.baseUrl}/storage/${name}/${path}`, {
+                    method: 'POST', headers: self._auth(), body: form,
+                });
+                return r.json();
+            },
+            async download(path) {
+                const r = await fetch(`${self.baseUrl}/storage/${name}/${path}`, { headers: self._auth() });
+                return r.ok ? r.blob() : null;
+            },
+            async list(opts) {
+                const prefix = opts?.prefix || '';
+                const limit = opts?.limit || 100;
+                const r = await fetch(`${self.baseUrl}/storage/${name}?prefix=${prefix}&limit=${limit}`, { headers: self._auth() });
+                const d = await r.json();
+                return d.files || [];
+            },
+            async remove(path) {
+                const r = await fetch(`${self.baseUrl}/storage/${name}/${path}`, { method: 'DELETE', headers: self._auth() });
+                return r.ok;
+            },
+        };
+    }
+    _auth() {
+        const t = this.getToken();
+        return t ? { Authorization: `Bearer ${t}` } : {};
+    }
+}
+exports.StorageClient = StorageClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fivebit-client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "5bit client SDK — deterministic, content-addressed database",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/FivebitClient.ts

@@ -1,6 +1,7 @@
 import { AuthClient } from './AuthClient';
 import { QueryClient } from './QueryClient';
 import { RealtimeClient } from './RealtimeClient';
+import { StorageClient } from './StorageClient';
 
 export interface FivebitConfig { url: string; apiKey?: string; }
 export interface AuthSession { userId: number; token: string; expiresAt: number; }
@@ -9,30 +10,27 @@ export interface QueryResult<T> { data: T | null; error: string | null; etag: st
 export class FivebitClient {
   config: FivebitConfig;
   auth: AuthClient;
+  storage: StorageClient;
+  realtime: RealtimeClient;
   private _query: QueryClient;
-  private _rt: RealtimeClient;
   private _session: AuthSession | null = null;
 
   constructor(config: FivebitConfig) {
     this.config = config;
     this.auth = new AuthClient(config.url);
-    this._query = new QueryClient(config.url, () => this._session?.token || '');
-    this._rt = new RealtimeClient(config.url);
+    const getToken = () => this._session?.token || '';
+    this._query = new QueryClient(config.url, getToken);
+    this.storage = new StorageClient(config.url, getToken);
+    this.realtime = new RealtimeClient(config.url);
   }
 
   get session(): AuthSession | null { return this._session; }
-
   setSession(s: AuthSession | null) { this._session = s; }
 
-  from<T = any>(table: string) {
-    return this._query.table<T>(table);
-  }
-
-  onChanges(table: string, fn: (record: any) => void) {
-    this._rt.subscribe(table, fn);
-  }
-
-  close() { this._rt.close(); }
+  from<T = any>(table: string) { return this._query.table<T>(table); }
+  onChanges(table: string, fn: (record: any) => void) { return this.realtime.subscribe(table, fn); }
+  channel(name: string) { return this.realtime.channel(name); }
+  close() { this.realtime.close(); }
 }
 
 export function createClient(config: FivebitConfig): FivebitClient {

package/src/QueryClient.ts

@@ -11,8 +11,7 @@ export class QueryClient {
 
   private headers(): Record<string, string> {
     const h: Record<string, string> = { 'Content-Type': 'application/json' };
-    const t = this.getToken();
-    if (t) h['Authorization'] = `Bearer ${t}`;
+    const t = this.getToken(); if (t) h['Authorization'] = `Bearer ${t}`;
     return h;
   }
 
@@ -20,51 +19,56 @@ export class QueryClient {
     const self = this;
     return {
       async getById(id: number): Promise<QueryResult<T>> {
-        const h = self.headers();
-        const etag = self.etagCache.get(id);
+        const h = self.headers(); const etag = self.etagCache.get(id);
         if (etag) h['If-None-Match'] = `"${etag}"`;
         const r = await fetch(`${self.baseUrl}/records/${id}`, { headers: h });
         if (r.status === 304) return { data: null, error: null, etag: etag || '' };
-        const data = await r.json();
-        const newEtag = r.headers.get('ETag')?.replace(/"/g, '') || '';
+        const data = await r.json(); const newEtag = r.headers.get('ETag')?.replace(/"/g, '') || '';
         if (newEtag) self.etagCache.set(id, newEtag);
         return { data, error: null, etag: newEtag };
       },
-
       async insert(record: Omit<T, '_id' | '_hash'>): Promise<QueryResult<T>> {
-        const r = await fetch(`${self.baseUrl}/records`, {
-          method: 'POST', headers: self.headers(), body: JSON.stringify(record),
-        });
-        const data = await r.json();
-        return { data, error: r.ok ? null : data.error, etag: '' };
+        const r = await fetch(`${self.baseUrl}/records`, { method: 'POST', headers: self.headers(), body: JSON.stringify(record) });
+        const data = await r.json(); return { data, error: r.ok ? null : data.error, etag: '' };
       },
-
       async update(id: number, record: Partial<T>): Promise<QueryResult<T>> {
-        const h = self.headers();
-        const etag = self.etagCache.get(id);
+        const h = self.headers(); const etag = self.etagCache.get(id);
         if (etag) h['If-Match'] = `"${etag}"`;
-        const r = await fetch(`${self.baseUrl}/records/${id}`, {
-          method: 'PUT', headers: h, body: JSON.stringify(record),
-        });
-        if (r.status === 412) return { data: null, error: 'Conflict — record modified', etag: '' };
-        const data = await r.json();
-        return { data, error: null, etag: '' };
+        const r = await fetch(`${self.baseUrl}/records/${id}`, { method: 'PUT', headers: h, body: JSON.stringify(record) });
+        if (r.status === 412) return { data: null, error: 'Conflict', etag: '' };
+        const data = await r.json(); return { data, error: null, etag: '' };
       },
-
       async delete(id: number): Promise<boolean> {
-        const r = await fetch(`${self.baseUrl}/records/${id}`, {
-          method: 'DELETE', headers: self.headers(),
-        });
-        self.etagCache.delete(id);
-        return r.ok;
+        const r = await fetch(`${self.baseUrl}/records/${id}`, { method: 'DELETE', headers: self.headers() });
+        self.etagCache.delete(id); return r.ok;
       },
-
       async query(field: string, value: string, limit = 20): Promise<T[]> {
-        const r = await fetch(`${self.baseUrl}/records?field=${field}&value=${value}&limit=${limit}`, {
-          headers: self.headers(),
-        });
-        const data = await r.json();
-        return data.results || [];
+        const r = await fetch(`${self.baseUrl}/records?field=${field}&value=${value}&limit=${limit}`, { headers: self.headers() });
+        const data = await r.json(); return data.results || [];
+      },
+      // Aggregates
+      async count(filter?: string): Promise<number> {
+        const q = filter ? `filter=${filter}&aggregate=count` : 'aggregate=count';
+        const r = await fetch(`${self.baseUrl}/query?${q}`, { headers: self.headers() });
+        const d = await r.json(); return d.count || 0;
+      },
+      async sum(field: string, filter?: string): Promise<number> {
+        const q = `aggregate=sum:${field}${filter ? '&filter=' + filter : ''}`;
+        const r = await fetch(`${self.baseUrl}/query?${q}`, { headers: self.headers() });
+        const d = await r.json(); return d[`sum_${field}`] || 0;
+      },
+      async avg(field: string, filter?: string): Promise<number> {
+        const q = `aggregate=avg:${field}${filter ? '&filter=' + filter : ''}`;
+        const r = await fetch(`${self.baseUrl}/query?${q}`, { headers: self.headers() });
+        const d = await r.json(); return d[`avg_${field}`] || 0;
+      },
+      async min(field: string): Promise<number> {
+        const r = await fetch(`${self.baseUrl}/query?aggregate=min:${field}`, { headers: self.headers() });
+        const d = await r.json(); return d[`min_${field}`] || 0;
+      },
+      async max(field: string): Promise<number> {
+        const r = await fetch(`${self.baseUrl}/query?aggregate=max:${field}`, { headers: self.headers() });
+        const d = await r.json(); return d[`max_${field}`] || 0;
       },
     };
   }

package/src/RealtimeClient.ts

@@ -1,41 +1,80 @@
 type ChangeHandler = (record: any) => void;
+type MessageHandler = (payload: any) => void;
 
 export class RealtimeClient {
   private baseUrl: string;
-  private sources: Map<string, EventSource> = new Map();
-  private handlers: Map<string, Set<ChangeHandler>> = new Map();
+  private ws: WebSocket | null = null;
+  private tableHandlers: Map<string, Set<ChangeHandler>> = new Map();
+  private channelHandlers: Map<string, Set<MessageHandler>> = new Map();
+  private presenceCache: any[] = [];
   private reconnectMs = 3000;
+  private wsUrl: string;
 
-  constructor(baseUrl: string) { this.baseUrl = baseUrl; }
-
-  subscribe(table: string, fn: ChangeHandler): () => void {
-    if (!this.handlers.has(table)) {
-      this.handlers.set(table, new Set());
-      this._connect(table);
-    }
-    this.handlers.get(table)!.add(fn);
-    return () => this.handlers.get(table)?.delete(fn);
+  constructor(baseUrl: string) {
+    this.baseUrl = baseUrl;
+    this.wsUrl = baseUrl.replace('http', 'ws') + '/ws';
+    this._connect();
   }
 
-  private _connect(table: string): void {
-    const url = `${this.baseUrl}/stream/${table}`;
-    const es = new EventSource(url);
-    es.onmessage = (e) => {
+  private _connect(): void {
+    if (typeof WebSocket === 'undefined') return;
+    this.ws = new WebSocket(this.wsUrl);
+    this.ws.onopen = () => {
+      // Re-subscribe to tables
+      for (const table of this.tableHandlers.keys()) {
+        this.ws!.send(JSON.stringify({ type: 'subscribe', table }));
+      }
+    };
+    this.ws.onmessage = (e) => {
       try {
-        const record = JSON.parse(e.data);
-        this.handlers.get(table)?.forEach(fn => fn(record));
+        const msg = JSON.parse(e.data);
+        if (msg.type === 'change') {
+          this.tableHandlers.get(msg.table)?.forEach(fn => fn(msg.event));
+        } else if (msg.type === 'broadcast') {
+          this.channelHandlers.get(msg.channel)?.forEach(fn => fn(msg.payload));
+        } else if (msg.type === 'presence') {
+          this.presenceCache = msg.users || [];
+          this.channelHandlers.get(`__presence:${msg.channel || ''}`)?.forEach(fn => fn(msg));
+        }
       } catch {}
     };
-    es.onerror = () => {
-      es.close();
-      setTimeout(() => this._connect(table), this.reconnectMs);
-    };
-    this.sources.set(table, es);
+    this.ws.onclose = () => setTimeout(() => this._connect(), this.reconnectMs);
   }
 
-  close(): void {
-    for (const es of this.sources.values()) es.close();
-    this.sources.clear();
-    this.handlers.clear();
+  // Table changes (backward compat + new)
+  subscribe(table: string, fn: ChangeHandler): () => void {
+    if (!this.tableHandlers.has(table)) this.tableHandlers.set(table, new Set());
+    this.tableHandlers.get(table)!.add(fn);
+    if (this.ws?.readyState === 1) {
+      this.ws.send(JSON.stringify({ type: 'subscribe', table }));
+    }
+    return () => this.tableHandlers.get(table)?.delete(fn);
   }
+
+  // Channels (new)
+  channel(name: string) {
+    const self = this;
+    return {
+      on(fn: MessageHandler) {
+        if (!self.channelHandlers.has(name)) self.channelHandlers.set(name, new Set());
+        self.channelHandlers.get(name)!.add(fn);
+        if (self.ws?.readyState === 1) {
+          self.ws.send(JSON.stringify({ type: 'channel', channel: name }));
+        }
+      },
+      broadcast(payload: any) {
+        if (self.ws?.readyState === 1) {
+          self.ws.send(JSON.stringify({ type: 'broadcast', channel: name, payload }));
+        }
+      },
+      presence(userId: number, userName: string) {
+        if (self.ws?.readyState === 1) {
+          self.ws.send(JSON.stringify({ type: 'presence', userId, name: userName, channel: name }));
+        }
+      },
+      get users(): any[] { return self.presenceCache; },
+    };
+  }
+
+  close(): void { this.ws?.close(); }
 }

package/src/StorageClient.ts

@@ -0,0 +1,39 @@
+export class StorageClient {
+  private baseUrl: string; private getToken: () => string;
+
+  constructor(baseUrl: string, getToken: () => string) {
+    this.baseUrl = baseUrl; this.getToken = getToken;
+  }
+
+  bucket(name: string) {
+    const self = this;
+    return {
+      async upload(path: string, data: Blob | Buffer | Uint8Array): Promise<{ path: string; hash: string; size: number }> {
+        const form = new FormData();
+        const blob = data instanceof Blob ? data : new Blob([data as any]);
+        form.append('file', blob, path);
+        const r = await fetch(`${self.baseUrl}/storage/${name}/${path}`, {
+          method: 'POST', headers: self._auth(), body: form,
+        });
+        return r.json();
+      },
+      async download(path: string): Promise<Blob | null> {
+        const r = await fetch(`${self.baseUrl}/storage/${name}/${path}`, { headers: self._auth() });
+        return r.ok ? r.blob() : null;
+      },
+      async list(opts?: { prefix?: string; limit?: number }): Promise<{ path: string; size: number; hash: string }[]> {
+        const prefix = opts?.prefix || ''; const limit = opts?.limit || 100;
+        const r = await fetch(`${self.baseUrl}/storage/${name}?prefix=${prefix}&limit=${limit}`, { headers: self._auth() });
+        const d = await r.json(); return d.files || [];
+      },
+      async remove(path: string): Promise<boolean> {
+        const r = await fetch(`${self.baseUrl}/storage/${name}/${path}`, { method: 'DELETE', headers: self._auth() });
+        return r.ok;
+      },
+    };
+  }
+
+  private _auth(): Record<string, string> {
+    const t = this.getToken(); return t ? { Authorization: `Bearer ${t}` } : {};
+  }
+}