bytex-sdk 5.3.0 → 5.5.0

package/index.js

@@ -405,3 +405,526 @@ export class BytexAI {
     return data.candidates[0].content.parts[0].text;
   }
 }
+
+// ════════════════════════════════════════════════════════════════
+// 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 and broadcast events.
+ *
+ * ⚠️  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(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 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: options.schema || 'public',
+        table,
+        ...(options.filter && { filter: options.filter })
+      }, (payload) => callback(payload))
+      .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 — 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(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 the room and clean up. */
+      leave: () => this.off(`bytex-room-${roomName}`)
+    };
+  }
+
+  /**
+   * Polling fallback — polls a URL and calls callback when response changes.
+   * Used when no Supabase is configured.
+   * @private
+   */
+  _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;
+  }
+
+  /**
+   * 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.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
+// Free tier: 3 Cron Triggers per Cloudflare account (FREE)
+// ════════════════════════════════════════════════════════════════
+/**
+ * BytexCron — Create and manage Cloudflare Workers Cron Triggers.
+ *
+ * Requires BYOC (user's Cloudflare account):
+ *   const cron = new BytexCron({ cfToken: '...', cfAccountId: '...', workerName: 'my-worker' });
+ */
+export class BytexCron {
+  constructor({ cfToken, cfAccountId, workerName } = {}) {
+    if (!cfToken || !cfAccountId || !workerName)
+      throw new Error('[BytexCron] Required: { cfToken, cfAccountId, workerName } — Use BYOC config from bytex dashboard.');
+    this.token = cfToken;
+    this.accountId = cfAccountId;
+    this.workerName = workerName;
+    this.base = `https://api.cloudflare.com/client/v4/accounts/${cfAccountId}`;
+  }
+
+  /** List all existing cron triggers for the worker. */
+  async list() {
+    const res = await fetch(`${this.base}/workers/scripts/${this.workerName}/schedules`, {
+      headers: { 'Authorization': `Bearer ${this.token}` }
+    });
+    const data = await res.json();
+    if (!data.success) throw new Error(`[BytexCron] ${JSON.stringify(data.errors)}`);
+    return data.result?.schedules || [];
+  }
+
+  /**
+   * Add a new cron trigger (max 3 in free tier).
+   * @param {string} cron - Cron expression (e.g. '0 0 * * *' = daily at midnight)
+   */
+  async add(cron) {
+    const existing = await this.list();
+    const schedules = [...existing.map(s => ({ cron: s.cron })), { cron }];
+    const res = await fetch(`${this.base}/workers/scripts/${this.workerName}/schedules`, {
+      method: 'PUT',
+      headers: { 'Authorization': `Bearer ${this.token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(schedules)
+    });
+    const data = await res.json();
+    if (!data.success) throw new Error(`[BytexCron] ${JSON.stringify(data.errors)}`);
+    return data.result;
+  }
+
+  /**
+   * Remove a cron trigger.
+   * @param {string} cron - The exact cron string to remove
+   */
+  async remove(cron) {
+    const existing = await this.list();
+    const schedules = existing.filter(s => s.cron !== cron).map(s => ({ cron: s.cron }));
+    const res = await fetch(`${this.base}/workers/scripts/${this.workerName}/schedules`, {
+      method: 'PUT',
+      headers: { 'Authorization': `Bearer ${this.token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(schedules)
+    });
+    const data = await res.json();
+    if (!data.success) throw new Error(`[BytexCron] ${JSON.stringify(data.errors)}`);
+    return data.result;
+  }
+}
+
+// ════════════════════════════════════════════════════════════════
+// ByteX QUEUE — Message Queue via Cloudflare Queues
+// Strategy: BYOC — user provides their Cloudflare API token
+// Free tier: 1,000,000 messages/month per account (FREE)
+// ════════════════════════════════════════════════════════════════
+/**
+ * BytexQueue — Create and publish to Cloudflare Queues.
+ *
+ * Requires BYOC (user's Cloudflare account):
+ *   const queue = new BytexQueue({ cfToken: '...', cfAccountId: '...' });
+ */
+export class BytexQueue {
+  constructor({ cfToken, cfAccountId } = {}) {
+    if (!cfToken || !cfAccountId)
+      throw new Error('[BytexQueue] Required: { cfToken, cfAccountId } — Use BYOC config from bytex dashboard.');
+    this.token = cfToken;
+    this.accountId = cfAccountId;
+    this.base = `https://api.cloudflare.com/client/v4/accounts/${cfAccountId}/queues`;
+  }
+
+  /** List all existing queues. */
+  async list() {
+    const res = await fetch(this.base, { headers: { 'Authorization': `Bearer ${this.token}` } });
+    const data = await res.json();
+    if (!data.success) throw new Error(`[BytexQueue] ${JSON.stringify(data.errors)}`);
+    return data.result || [];
+  }
+
+  /**
+   * Create a new queue.
+   * @param {string} name - Queue name (lowercase, hyphens only)
+   */
+  async create(name) {
+    const res = await fetch(this.base, {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${this.token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ queue_name: name })
+    });
+    const data = await res.json();
+    if (!data.success) throw new Error(`[BytexQueue] ${JSON.stringify(data.errors)}`);
+    return data.result;
+  }
+
+  /**
+   * Delete a queue.
+   * @param {string} name - Queue name
+   */
+  async delete(name) {
+    const res = await fetch(`${this.base}/${name}`, {
+      method: 'DELETE',
+      headers: { 'Authorization': `Bearer ${this.token}` }
+    });
+    const data = await res.json();
+    if (!data.success) throw new Error(`[BytexQueue] ${JSON.stringify(data.errors)}`);
+    return true;
+  }
+
+  /**
+   * Publish a message to a queue.
+   * @param {string} queueName - Target queue
+   * @param {object|string} body - Message content
+   * @param {object} options - { delaySeconds? }
+   */
+  async publish(queueName, body, options = {}) {
+    const message = { body: typeof body === 'string' ? body : JSON.stringify(body) };
+    if (options.delaySeconds) message.delay_seconds = options.delaySeconds;
+    const res = await fetch(`${this.base}/${queueName}/messages`, {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${this.token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ messages: [message] })
+    });
+    const data = await res.json();
+    if (!data.success) throw new Error(`[BytexQueue] ${JSON.stringify(data.errors)}`);
+    return data.result;
+  }
+
+  /**
+   * Publish multiple messages in a single batch (max 100).
+   * @param {string} queueName - Target queue
+   * @param {Array<object|string>} items - Array of message bodies
+   */
+  async publishBatch(queueName, items) {
+    const messages = items.map(body => ({ body: typeof body === 'string' ? body : JSON.stringify(body) }));
+    const res = await fetch(`${this.base}/${queueName}/messages`, {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${this.token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ messages })
+    });
+    const data = await res.json();
+    if (!data.success) throw new Error(`[BytexQueue] ${JSON.stringify(data.errors)}`);
+    return data.result;
+  }
+}
+
+// ════════════════════════════════════════════════════════════════
+// ByteX PROXY — Reverse Proxy via Cloudflare Workers
+// Strategy: Uses ByteX's Cloudflare (no BYOC needed for basic use)
+// Free tier: 100,000 requests/day (FREE)
+// ════════════════════════════════════════════════════════════════
+/**
+ * BytexProxy — Deploy and manage Cloudflare Worker reverse proxies.
+ *
+ * Usage:
+ *   // Use ByteX's proxy endpoint (no config needed):
+ *   const url = BytexProxy.buildUrl('https://api.target.com/endpoint', { headers: {...} });
+ *
+ *   // Or deploy your own proxy Worker (BYOC):
+ *   const proxy = new BytexProxy({ cfToken: '...', cfAccountId: '...' });
+ *   await proxy.deploy('my-proxy', 'https://api.target.com');
+ */
+export class BytexProxy {
+  constructor({ cfToken, cfAccountId } = {}) {
+    this.token = cfToken;
+    this.accountId = cfAccountId;
+  }
+
+  /**
+   * Build a proxied URL via ByteX's own proxy layer.
+   * Useful for CORS bypass and header injection.
+   * @param {string} targetUrl - The destination URL to proxy
+   * @param {{ headers?: object }} options
+   */
+  static buildUrl(targetUrl, options = {}) {
+    const encoded = encodeURIComponent(targetUrl);
+    const base = 'https://api.bytex.work/?action=proxy&target=';
+    return `${base}${encoded}`;
+  }
+
+  /**
+   * Deploy a Cloudflare Worker that proxies to a target origin (BYOC).
+   * @param {string} workerName - Unique name for this proxy worker
+   * @param {string} targetOrigin - Base URL of the backend (e.g. 'https://my-api.com')
+   * @param {{ injectHeaders?: object, stripHeaders?: string[] }} options
+   */
+  async deploy(workerName, targetOrigin, options = {}) {
+    if (!this.token || !this.accountId)
+      throw new Error('[BytexProxy] BYOC required for deploy. Pass { cfToken, cfAccountId }.');
+
+    const injectHeaders = options.injectHeaders
+      ? Object.entries(options.injectHeaders).map(([k, v]) => `req.headers.set('${k}', '${v}');`).join('\n      ')
+      : '';
+    const stripHeaders = (options.stripHeaders || [])
+      .map(h => `req.headers.delete('${h}');`).join('\n      ');
+
+    const workerScript = `
+export default {
+  async fetch(request) {
+    const url = new URL(request.url);
+    const target = new URL('${targetOrigin}' + url.pathname + url.search);
+    const req = new Request(target, request);
+    ${injectHeaders}
+    ${stripHeaders}
+    const response = await fetch(req);
+    const res = new Response(response.body, response);
+    res.headers.set('Access-Control-Allow-Origin', '*');
+    return res;
+  }
+}`;
+
+    const fd = new FormData();
+    fd.append('metadata', JSON.stringify({ main_module: 'worker.js', compatibility_date: '2024-01-01' }));
+    fd.append('worker.js', new Blob([workerScript], { type: 'application/javascript+module' }), 'worker.js');
+
+    const res = await fetch(`https://api.cloudflare.com/client/v4/accounts/${this.accountId}/workers/scripts/${workerName}`, {
+      method: 'PUT',
+      headers: { 'Authorization': `Bearer ${this.token}` },
+      body: fd
+    });
+    const data = await res.json();
+    if (!data.success) throw new Error(`[BytexProxy] ${JSON.stringify(data.errors)}`);
+    return { workerName, url: `https://${workerName}.workers.dev`, target: targetOrigin };
+  }
+}
+
+// ════════════════════════════════════════════════════════════════
+// ByteX MQTT — IoT Messaging via user's MQTT Broker
+// Strategy: BYOC — user provides their broker (HiveMQ/EMQX/any)
+// Free tier: HiveMQ Cloud free (10 devices), EMQX Serverless (1M msg/mo)
+// ════════════════════════════════════════════════════════════════
+/**
+ * BytexMQTT — Lightweight MQTT client wrapper (BYOC).
+ *
+ * Requires the 'mqtt' package: npm install mqtt
+ * Requires user's own MQTT broker (HiveMQ, EMQX, Mosquitto, etc.)
+ *
+ * Usage:
+ *   const mq = new BytexMQTT({
+ *     brokerUrl: 'mqtts://your-cluster.hivemq.cloud:8883',
+ *     username: 'user', password: 'pass'
+ *   });
+ *   await mq.connect();
+ *   mq.subscribe('bytex/files/#', (topic, msg) => console.log(topic, msg));
+ *   mq.publish('bytex/files/new', { name: 'photo.jpg' });
+ */
+export class BytexMQTT {
+  constructor({ brokerUrl, username, password, clientId } = {}) {
+    if (!brokerUrl)
+      throw new Error('[BytexMQTT] Required: { brokerUrl } — Get free broker at hivemq.com or emqx.com (BYOC).');
+    this.brokerUrl = brokerUrl;
+    this.options = {
+      username, password,
+      clientId: clientId || `bytex-${Math.random().toString(36).substring(2, 9)}`,
+      clean: true,
+      reconnectPeriod: 3000,
+      connectTimeout: 10000,
+    };
+    this.client = null;
+    this._handlers = new Map();
+  }
+
+  /**
+   * Connect to the MQTT broker.
+   * @returns {Promise<void>}
+   */
+  async connect() {
+    let mqtt;
+    try { mqtt = (await import('mqtt')).default; }
+    catch { throw new Error('[BytexMQTT] Install the mqtt package first: npm install mqtt'); }
+
+    return new Promise((resolve, reject) => {
+      this.client = mqtt.connect(this.brokerUrl, this.options);
+      this.client.on('connect', () => resolve());
+      this.client.on('error', (err) => reject(new Error(`[BytexMQTT] Connection failed: ${err.message}`)));
+      this.client.on('message', (topic, buf) => {
+        const msg = buf.toString();
+        let parsed; try { parsed = JSON.parse(msg); } catch { parsed = msg; }
+        this._handlers.forEach((fn, pattern) => {
+          if (this._topicMatch(pattern, topic)) fn(topic, parsed);
+        });
+      });
+    });
+  }
+
+  /**
+   * Publish a message to a topic.
+   * @param {string} topic
+   * @param {object|string} payload
+   * @param {{ qos?: 0|1|2, retain?: boolean }} options
+   */
+  publish(topic, payload, options = {}) {
+    if (!this.client) throw new Error('[BytexMQTT] Not connected. Call connect() first.');
+    const msg = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    this.client.publish(topic, msg, { qos: options.qos ?? 1, retain: options.retain ?? false });
+  }
+
+  /**
+   * Subscribe to a topic or wildcard pattern.
+   * @param {string} topic - Supports MQTT wildcards: '#' (multi-level), '+' (single-level)
+   * @param {function} callback - (topic, parsedPayload) => void
+   * @param {{ qos?: 0|1|2 }} options
+   */
+  subscribe(topic, callback, options = {}) {
+    if (!this.client) throw new Error('[BytexMQTT] Not connected. Call connect() first.');
+    this.client.subscribe(topic, { qos: options.qos ?? 1 });
+    this._handlers.set(topic, callback);
+  }
+
+  /** Unsubscribe from a topic. */
+  unsubscribe(topic) {
+    if (this.client) this.client.unsubscribe(topic);
+    this._handlers.delete(topic);
+  }
+
+  /** Gracefully disconnect from the broker. */
+  disconnect() {
+    if (this.client) { this.client.end(); this.client = null; }
+  }
+
+  _topicMatch(pattern, topic) {
+    const p = pattern.replace(/\+/g, '[^/]+').replace(/#$/, '.*');
+    return new RegExp(`^${p}$`).test(topic);
+  }
+}
+

package/package.json

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