prepia 1.0.0

package/src/client/index.mjs

@@ -0,0 +1,483 @@
+/**
+ * Prepia Universal Client SDK
+ * Drop-in client for ANY AI agent to connect to Prepia
+ * Works with: OpenClaw, AutoGPT, CrewAI, LangChain, custom bots, anything
+ * 
+ * Usage:
+ *   import { PrepiClient } from 'prepia/client';
+ *   const prepi = new PrepiClient({ host: 'localhost', port: 4710 });
+ *   const result = await prepi.task('Research top 5 phones and make a table');
+ */
+
+import { EventEmitter } from 'events';
+import http from 'http';
+
+/**
+ * Simple WebSocket client using net.Socket
+ * No external dependencies — connects via raw TCP + WebSocket handshake
+ */
+class SimpleWebSocket extends EventEmitter {
+  constructor(url, options = {}) {
+    super();
+    this.url = url;
+    this.options = options;
+    this.socket = null;
+    this.connected = false;
+    this.buffer = Buffer.alloc(0);
+  }
+
+  connect() {
+    const { hostname, port, pathname } = this._parseUrl(this.url);
+    const net = require('net');
+    const crypto = require('crypto');
+
+    return new Promise((resolve, reject) => {
+      this.socket = net.createConnection(port, hostname, () => {
+        const key = crypto.randomBytes(16).toString('base64');
+        const headers = [
+          `GET ${pathname} HTTP/1.1`,
+          `Host: ${hostname}:${port}`,
+          'Upgrade: websocket',
+          'Connection: Upgrade',
+          `Sec-WebSocket-Key: ${key}`,
+          'Sec-WebSocket-Version: 13',
+          '',
+          '',
+        ].join('\r\n');
+        this.socket.write(headers);
+      });
+
+      let handshakeDone = false;
+      this.socket.on('data', (chunk) => {
+        if (!handshakeDone) {
+          const str = chunk.toString();
+          if (str.includes('101 Switching Protocols')) {
+            handshakeDone = true;
+            this.connected = true;
+            this.emit('open');
+            resolve();
+          }
+          return;
+        }
+        this._handleFrame(chunk);
+      });
+
+      this.socket.on('close', () => {
+        this.connected = false;
+        this.emit('close');
+      });
+
+      this.socket.on('error', (err) => {
+        this.emit('error', err);
+        if (!this.connected) reject(err);
+      });
+    });
+  }
+
+  send(data) {
+    if (!this.connected || !this.socket) return;
+    const payload = typeof data === 'object' ? JSON.stringify(data) : String(data);
+    const mask = require('crypto').randomBytes(4);
+    const payloadBuf = Buffer.from(payload);
+    let header;
+    if (payloadBuf.length < 126) {
+      header = Buffer.alloc(2);
+      header[0] = 0x81;
+      header[1] = 0x80 | payloadBuf.length;
+    } else {
+      header = Buffer.alloc(4);
+      header[0] = 0x81;
+      header[1] = 0x80 | 126;
+      header.writeUInt16BE(payloadBuf.length, 2);
+    }
+    const masked = Buffer.alloc(payloadBuf.length);
+    for (let i = 0; i < payloadBuf.length; i++) masked[i] = payloadBuf[i] ^ mask[i % 4];
+    this.socket.write(Buffer.concat([header, mask, masked]));
+  }
+
+  close() {
+    if (this.socket) this.socket.end();
+    this.connected = false;
+  }
+
+  _handleFrame(chunk) {
+    // Simplified frame parsing for client
+    if (chunk.length < 2) return;
+    const opcode = chunk[0] & 0x0f;
+    if (opcode === 0x08) { this.close(); return; }
+    if (opcode === 0x09) { /* ping → send pong */ return; }
+    let offset = 2;
+    let len = chunk[1] & 0x7f;
+    if (len === 126) { len = chunk.readUInt16BE(2); offset = 4; }
+    const payload = chunk.slice(offset, offset + len).toString();
+    try { this.emit('message', JSON.parse(payload)); } catch { this.emit('message', payload); }
+  }
+
+  _parseUrl(url) {
+    const u = new URL(url);
+    return { hostname: u.hostname, port: parseInt(u.port) || 80, pathname: u.pathname || '/' };
+  }
+}
+
+/**
+ * @typedef {Object} PrepiClientOptions
+ * @property {string} [host='localhost'] - Prepia server host
+ * @property {number} [port=4710] - Prepia server port
+ * @property {string} [apiKey] - API key for authentication
+ * @property {string} [protocol='http'] - 'http' or 'https'
+ * @property {number} [timeout=300000] - Default task timeout in ms
+ * @property {number} [retries=3] - Default retry count
+ * @property {boolean} [stream=false] - Enable streaming by default
+ * @property {string} [agentId] - Identifier for the connecting agent
+ * @property {string} [agentType='generic'] - Agent framework type
+ */
+
+export class PrepiClient extends EventEmitter {
+  /** @param {PrepiClientOptions} options */
+  constructor(options = {}) {
+    super();
+    this.host = options.host || 'localhost';
+    this.port = options.port || 4710;
+    this.apiKey = options.apiKey || null;
+    this.protocol = options.protocol || 'http';
+    this.timeout = options.timeout || 300000;
+    this.retries = options.retries || 3;
+    this.stream = options.stream || false;
+    this.agentId = options.agentId || `agent-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    this.agentType = options.agentType || 'generic';
+    this.baseUrl = `${this.protocol}://${this.host}:${this.port}`;
+    this.ws = null;
+    this.connected = false;
+    this._taskId = 0;
+  }
+
+  /**
+   * Get request headers
+   * @returns {Object}
+   */
+  _headers() {
+    const h = {
+      'Content-Type': 'application/json',
+      'X-Prepia-Agent-Id': this.agentId,
+      'X-Prepia-Agent-Type': this.agentType,
+    };
+    if (this.apiKey) h['Authorization'] = `Bearer ${this.apiKey}`;
+    return h;
+  }
+
+  /**
+   * Make an HTTP request to Prepia
+   * @param {string} method
+   * @param {string} path
+   * @param {Object} [body]
+   * @returns {Promise<Object>}
+   */
+  async _request(method, path, body = null) {
+    const url = `${this.baseUrl}${path}`;
+    const opts = {
+      method,
+      headers: this._headers(),
+      signal: AbortSignal.timeout(this.timeout),
+    };
+    if (body) opts.body = JSON.stringify(body);
+
+    let lastError;
+    for (let attempt = 1; attempt <= this.retries; attempt++) {
+      try {
+        const res = await fetch(url, opts);
+        const data = await res.json();
+        if (!res.ok) {
+          const err = new Error(data.error || `HTTP ${res.status}`);
+          err.status = res.status;
+          err.data = data;
+          throw err;
+        }
+        return data;
+      } catch (err) {
+        lastError = err;
+        if (attempt < this.retries && (err.code === 'ECONNREFUSED' || err.code === 'ETIMEDOUT' || err.status >= 500)) {
+          await new Promise(r => setTimeout(r, 1000 * attempt));
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw lastError;
+  }
+
+  /**
+   * Connect via WebSocket for real-time streaming
+   * @returns {Promise<void>}
+   */
+  async connect() {
+    if (this.connected) return;
+    return new Promise((resolve, reject) => {
+      const wsUrl = this.baseUrl.replace(/^http/, 'ws') + '/ws';
+      this.ws = new SimpleWebSocket(wsUrl, {
+        headers: this._headers(),
+      });
+
+      this.ws.on('open', () => {
+        this.connected = true;
+        this.emit('connected');
+        resolve();
+      });
+
+      this.ws.on('message', (data) => {
+        try {
+          const msg = JSON.parse(data.toString());
+          this.emit(msg.event, msg.data);
+          this.emit('message', msg);
+        } catch {
+          this.emit('raw', data);
+        }
+      });
+
+      this.ws.on('close', () => {
+        this.connected = false;
+        this.emit('disconnected');
+      });
+
+      this.ws.on('error', (err) => {
+        this.emit('error', err);
+        if (!this.connected) reject(err);
+      });
+    });
+  }
+
+  /**
+   * Disconnect WebSocket
+   */
+  disconnect() {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+      this.connected = false;
+    }
+  }
+
+  /**
+   * Submit a task to Prepia (the main method agents use)
+   * @param {string|Object} task - Task description or task object
+   * @param {Object} [options] - Task options
+   * @returns {Promise<Object>} Task result
+   * 
+   * @example
+   * // Simple string task
+   * const result = await prepi.task('What is the capital of France?');
+   * 
+   * @example
+   * // Detailed task with options
+   * const result = await prepi.task({
+   *   description: 'Research top phones and compare',
+   *   mode: 'shot',        // 'flash', 'shot', 'stream'
+   *   tools: ['web-search', 'calculator'],
+   *   cache: true,
+   *   maxTokens: 2000,
+   * });
+   */
+  async task(task, options = {}) {
+    const taskObj = typeof task === 'string' ? { description: task } : task;
+    const payload = {
+      ...taskObj,
+      agentId: this.agentId,
+      agentType: this.agentType,
+      ...options,
+    };
+
+    if (this.stream || payload.mode === 'stream') {
+      return this._streamTask(payload);
+    }
+
+    return this._request('POST', '/api/task', payload);
+  }
+
+  /**
+   * Submit task with streaming progress
+   * @param {Object} payload
+   * @returns {Promise<Object>}
+   */
+  async _streamTask(payload) {
+    if (!this.connected) await this.connect();
+
+    return new Promise((resolve, reject) => {
+      const taskId = `task-${++this._taskId}-${Date.now()}`;
+      const result = { phases: [], final: null };
+
+      const onMessage = (msg) => {
+        if (msg.taskId !== taskId) return;
+
+        switch (msg.event) {
+          case 'task:progress':
+            result.phases.push(msg.data);
+            this.emit('progress', msg.data);
+            break;
+          case 'task:complete':
+            result.final = msg.data;
+            cleanup();
+            resolve(result);
+            break;
+          case 'task:error':
+            cleanup();
+            reject(new Error(msg.data.error));
+            break;
+        }
+      };
+
+      const cleanup = () => {
+        this.removeListener('message', onMessage);
+      };
+
+      this.on('message', onMessage);
+
+      this.ws.send(JSON.stringify({
+        event: 'task:submit',
+        taskId,
+        data: payload,
+      }));
+
+      // Timeout safety
+      setTimeout(() => {
+        cleanup();
+        reject(new Error('Task timeout'));
+      }, this.timeout);
+    });
+  }
+
+  /**
+   * Quick query — instant answers (PrepiFlash mode)
+   * @param {string} query
+   * @returns {Promise<Object>}
+   * 
+   * @example
+   * const r = await prepi.quick('What is 2+2?');
+   * console.log(r.answer); // 4
+   */
+  async quick(query) {
+    return this._request('POST', '/api/task', {
+      description: query,
+      mode: 'flash',
+      agentId: this.agentId,
+      agentType: this.agentType,
+    });
+  }
+
+  /**
+   * Optimized single-LLM-call task (PrepiShot mode)
+   * @param {string} description
+   * @param {Object} [options]
+   * @returns {Promise<Object>}
+   */
+  async shot(description, options = {}) {
+    return this._request('POST', '/api/task', {
+      description,
+      mode: 'shot',
+      agentId: this.agentId,
+      agentType: this.agentType,
+      ...options,
+    });
+  }
+
+  /**
+   * Check Prepia server health
+   * @returns {Promise<Object>}
+   */
+  async health() {
+    return this._request('GET', '/api/health');
+  }
+
+  /**
+   * Get usage analytics
+   * @param {Object} [filters]
+   * @returns {Promise<Object>}
+   */
+  async analytics(filters = {}) {
+    const params = new URLSearchParams(filters).toString();
+    return this._request('GET', `/api/analytics${params ? '?' + params : ''}`);
+  }
+
+  /**
+   * Clear cache
+   * @param {string} [key] - Specific key, or all if omitted
+   * @returns {Promise<Object>}
+   */
+  async clearCache(key) {
+    const path = key ? `/api/cache/${encodeURIComponent(key)}` : '/api/cache';
+    return this._request('DELETE', path);
+  }
+
+  /**
+   * List installed plugins
+   * @returns {Promise<Object>}
+   */
+  async plugins() {
+    return this._request('GET', '/api/plugins');
+  }
+
+  /**
+   * Get/set configuration
+   * @param {Object} [config]
+   * @returns {Promise<Object>}
+   */
+  async config(config) {
+    if (config) return this._request('POST', '/api/config', config);
+    return this._request('GET', '/api/config');
+  }
+
+  /**
+   * Execute a PrepiScript
+   * @param {string} script
+   * @returns {Promise<Object>}
+   */
+  async script(script) {
+    return this._request('POST', '/api/script', { script });
+  }
+
+  /**
+   * Get knowledge base entries
+   * @param {string} [query]
+   * @returns {Promise<Object>}
+   */
+  async knowledge(query) {
+    const params = query ? `?q=${encodeURIComponent(query)}` : '';
+    return this._request('GET', `/api/knowledge${params}`);
+  }
+
+  /**
+   * Store something in the knowledge base
+   * @param {string} key
+   * @param {*} value
+   * @param {Object} [meta]
+   * @returns {Promise<Object>}
+   */
+  async store(key, value, meta = {}) {
+    return this._request('POST', '/api/knowledge', { key, value, ...meta });
+  }
+}
+
+/**
+ * Create a Prepia client with minimal config
+ * @param {string|Object} [config] - URL string or options object
+ * @returns {PrepiClient}
+ * 
+ * @example
+ * // From URL string
+ * const prepi = prepiConnect('http://localhost:4710');
+ * 
+ * @example
+ * // Simple options
+ * const prepi = prepiConnect({ port: 4710, apiKey: 'my-key' });
+ */
+export function prepiConnect(config = {}) {
+  if (typeof config === 'string') {
+    const url = new URL(config);
+    return new PrepiClient({
+      protocol: url.protocol.replace(':', ''),
+      host: url.hostname,
+      port: parseInt(url.port) || 4710,
+    });
+  }
+  return new PrepiClient(config);
+}
+
+export default PrepiClient;