bytex-sdk 5.4.0 → 5.5.0

package/index.js

@@ -407,77 +407,187 @@ export class BytexAI {
 }
 
 // ════════════════════════════════════════════════════════════════
-// ByteX REALTIME — Database Realtime via Supabase
-// Strategy: Uses ByteX's Supabase OR user's own (BYOC)
-// Free tier: 200 concurrent connections per Supabase project
+// ByteX REALTIME — Database Realtime (BYOC Model)
+// Strategy: ALWAYS uses user's own Supabase (BYOC)
+//           Falls back to HTTP polling if no Supabase configured
+// Free tier: 200 concurrent connections per USER's Supabase project
 // ════════════════════════════════════════════════════════════════
 /**
- * BytexRealtime — Subscribe to database changes in real-time.
+ * BytexRealtime — Subscribe to database changes and broadcast events.
  *
- * Usage:
- *   const rt = new BytexRealtime(bytex.supabase);
- *   rt.on('api_keys', (payload) => console.log(payload));
+ * ⚠️  IMPORTANT: Always use BYOC (user's own Supabase), NOT ByteX's central Supabase.
+ *     ByteX's Supabase has a limit of 200 concurrent connections total.
+ *     With BYOC, EACH USER gets their own 200 free concurrent connections.
+ *
+ * Usage (BYOC — Recommended):
+ *   const rt = new BytexRealtime({
+ *     supabaseUrl: 'https://your-project.supabase.co',
+ *     supabaseKey: 'your-anon-key'
+ *   });
+ *
+ * Usage (Polling fallback — no Supabase needed):
+ *   const rt = new BytexRealtime({ pollUrl: 'https://api.bytex.work/', pollInterval: 5000 });
  */
 export class BytexRealtime {
-  constructor(supabaseClient) {
-    if (!supabaseClient) throw new Error('[BytexRealtime] Pass a Supabase client. Use: new BytexRealtime(bytex.supabase)');
-    this.client = supabaseClient;
+  constructor(config = {}) {
     this._channels = new Map();
+    this._pollers = new Map();
+    this._mode = 'idle';
+
+    // Mode 1: BYOC Supabase client passed directly (legacy support)
+    if (config && typeof config.from === 'function') {
+      console.warn('[BytexRealtime] ⚠️  Passing ByteX\'s own Supabase client is not recommended for production. Use BYOC credentials to avoid shared connection limits.');
+      this.client = config;
+      this._mode = 'supabase';
+      return;
+    }
+
+    // Mode 2: BYOC — user provides their own Supabase credentials
+    if (config.supabaseUrl && config.supabaseKey) {
+      this.client = createClient(config.supabaseUrl, config.supabaseKey, {
+        realtime: { params: { eventsPerSecond: 10 } }
+      });
+      this._mode = 'supabase';
+      return;
+    }
+
+    // Mode 3: Polling fallback — no Supabase required
+    if (config.pollUrl) {
+      this._pollUrl = config.pollUrl;
+      this._pollInterval = config.pollInterval || 5000;
+      this._mode = 'polling';
+      return;
+    }
+
+    throw new Error(
+      '[BytexRealtime] Configuration required. Options:\n' +
+      '  1. BYOC (recommended): { supabaseUrl, supabaseKey } — user\'s own Supabase\n' +
+      '  2. Polling fallback:   { pollUrl, pollInterval? } — works without Supabase'
+    );
   }
 
   /**
-   * Subscribe to realtime changes on a table.
-   * @param {string} table - Table name (e.g. 'api_keys', 'files')
+   * Subscribe to realtime database changes on a table (Supabase mode only).
+   * @param {string} table - Table name (e.g. 'messages', 'orders')
    * @param {function} callback - Receives { event, new, old }
    * @param {{ event?: 'INSERT'|'UPDATE'|'DELETE'|'*', filter?: string }} options
    */
   on(table, callback, options = {}) {
+    if (this._mode === 'polling') {
+      return this._pollTable(table, callback, options);
+    }
+
+    if (this._mode !== 'supabase') throw new Error('[BytexRealtime] No Supabase client. Provide supabaseUrl + supabaseKey.');
+
     const event = options.event || '*';
     const channelName = `bytex-rt-${table}-${Date.now()}`;
     const channel = this.client
       .channel(channelName)
       .on('postgres_changes', {
         event,
-        schema: 'public',
+        schema: options.schema || 'public',
         table,
         ...(options.filter && { filter: options.filter })
       }, (payload) => callback(payload))
-      .subscribe();
+      .subscribe((status) => {
+        if (status === 'CHANNEL_ERROR') {
+          console.error(`[BytexRealtime] Channel error on table "${table}". Check your Supabase config.`);
+        }
+      });
+
     this._channels.set(channelName, channel);
     return channelName;
   }
 
   /**
-   * Subscribe to a broadcast channel (WebSocket replacement).
-   * @param {string} channelName - Unique room/channel name
+   * Subscribe to a broadcast channel — acts like a room/WebSocket.
+   * @param {string} roomName - Unique room identifier
    * @param {function} callback - Receives { event, payload }
+   * @returns {{ send, leave }} - Methods to send messages or leave the room
    */
-  join(channelName, callback) {
-    const channel = this.client.channel(channelName);
-    channel.on('broadcast', { event: '*' }, (msg) => callback(msg)).subscribe();
-    this._channels.set(channelName, channel);
+  join(roomName, callback) {
+    if (this._mode !== 'supabase') {
+      throw new Error('[BytexRealtime] Broadcast channels require Supabase. Provide supabaseUrl + supabaseKey.');
+    }
+
+    const channel = this.client.channel(`bytex-room-${roomName}`, {
+      config: { broadcast: { self: false } }
+    });
+
+    channel
+      .on('broadcast', { event: '*' }, (msg) => callback(msg))
+      .subscribe();
+
+    this._channels.set(`bytex-room-${roomName}`, channel);
+
     return {
+      /** Send a message to all members of this room. */
       send: (event, payload) => channel.send({ type: 'broadcast', event, payload }),
-      leave: () => this.off(channelName)
+      /** Leave the room and clean up. */
+      leave: () => this.off(`bytex-room-${roomName}`)
     };
   }
 
   /**
-   * Unsubscribe from a channel.
-   * @param {string} channelName
+   * Polling fallback — polls a URL and calls callback when response changes.
+   * Used when no Supabase is configured.
+   * @private
    */
-  off(channelName) {
-    const ch = this._channels.get(channelName);
-    if (ch) { this.client.removeChannel(ch); this._channels.delete(channelName); }
+  _pollTable(table, callback, options) {
+    let lastHash = null;
+    const pollerId = `poll-${table}-${Date.now()}`;
+
+    const poll = async () => {
+      try {
+        const url = `${this._pollUrl}?action=list&table=${table}`;
+        const res = await fetch(url);
+        const text = await res.text();
+        const hash = btoa(text.substring(0, 200));
+        if (lastHash !== null && hash !== lastHash) {
+          callback({ event: '*', source: 'poll', data: text });
+        }
+        lastHash = hash;
+      } catch (e) {
+        console.warn(`[BytexRealtime] Poll error: ${e.message}`);
+      }
+    };
+
+    poll();
+    const timer = setInterval(poll, this._pollInterval);
+    this._pollers.set(pollerId, timer);
+    return pollerId;
   }
 
-  /** Remove all active subscriptions. */
+  /**
+   * Check current realtime mode.
+   * @returns {'supabase'|'polling'|'idle'}
+   */
+  get mode() { return this._mode; }
+
+  /**
+   * Get current active connection count (Supabase mode only).
+   */
+  get connectionCount() { return this._channels.size; }
+
+  /** Unsubscribe from a specific channel or poller. */
+  off(channelId) {
+    const ch = this._channels.get(channelId);
+    if (ch) { this.client?.removeChannel(ch); this._channels.delete(channelId); return; }
+
+    const timer = this._pollers.get(channelId);
+    if (timer) { clearInterval(timer); this._pollers.delete(channelId); }
+  }
+
+  /** Disconnect all subscriptions and clean up. */
   destroy() {
-    this._channels.forEach((ch) => this.client.removeChannel(ch));
+    this._channels.forEach((ch) => this.client?.removeChannel(ch));
     this._channels.clear();
+    this._pollers.forEach((t) => clearInterval(t));
+    this._pollers.clear();
   }
 }
 
+
 // ════════════════════════════════════════════════════════════════
 // ByteX CRON — Scheduled Jobs via Cloudflare Workers Cron Triggers
 // Strategy: BYOC — user provides their Cloudflare API token

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bytex-sdk",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "Official ByteX Cloud SDK with AI (BYOM) support",
   "main": "index.js",
   "scripts": {