prepia 1.0.0

package/src/analytics/dashboard.mjs

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Cost/efficiency reporting dashboard.
+ * @module analytics/dashboard
+ */
+
+/**
+ * Generate a formatted report from tracker metrics.
+ * @param {Object} metrics - From Tracker.getMetrics()
+ * @param {Object} [savings] - From Tracker.estimateSavings()
+ * @returns {string}
+ */
+export function generateReport(metrics, savings = {}) {
+  const uptimeStr = formatDuration(metrics.uptime || 0);
+  const efficiencyPct = ((metrics.efficiency || 0) * 100).toFixed(1);
+
+  return `
+╔══════════════════════════════════════════════════════════╗
+║                   PREPIA ANALYTICS                       ║
+╠══════════════════════════════════════════════════════════╣
+║                                                          ║
+║  Uptime:           ${uptimeStr.padEnd(38)}║
+║  Tasks Processed:  ${String(metrics.tasksProcessed).padEnd(38)}║
+║                                                          ║
+║  ── LLM Usage ────────────────────────────────────────── ║
+║  LLM Calls Made:   ${String(metrics.llmCallsMade).padEnd(38)}║
+║  LLM Calls Avoided:${String(metrics.llmCallsAvoided).padEnd(38)}║
+║  Efficiency:       ${(efficiencyPct + '%').padEnd(38)}║
+║                                                          ║
+║  ── Token Usage ──────────────────────────────────────── ║
+║  Tokens Used:      ${String(metrics.tokensUsed).padEnd(38)}║
+║  Tokens Saved:     ${String(metrics.tokensSaved).padEnd(38)}║
+║                                                          ║
+║  ── Cache ────────────────────────────────────────────── ║
+║  Cache Hits:       ${String(metrics.cacheHits).padEnd(38)}║
+║  Cache Misses:     ${String(metrics.cacheMisses).padEnd(38)}║
+║  Hit Rate:         ${formatHitRate(metrics.cacheHits, metrics.cacheMisses).padEnd(38)}║
+║                                                          ║
+║  ── Performance ──────────────────────────────────────── ║
+║  Avg Duration:     ${(metrics.avgDuration + 'ms').padEnd(38)}║
+║  Tasks/Minute:     ${String(metrics.tasksPerMinute).padEnd(38)}║
+║  Errors:           ${String(metrics.errors).padEnd(38)}║
+║                                                          ║${savings.estimatedDollarsSaved !== undefined ? `
+║  ── Cost Savings ─────────────────────────────────────── ║
+║  Est. Saved:       ${('$' + savings.estimatedDollarsSaved.toFixed(2)).padEnd(38)}║
+║  Est. Spent:       ${('$' + (savings.estimatedDollarsSpent || 0).toFixed(2)).padEnd(38)}║` : ''}
+║                                                          ║
+╚══════════════════════════════════════════════════════════╝`.trim();
+}
+
+/**
+ * Generate a compact summary line.
+ * @param {Object} metrics
+ * @returns {string}
+ */
+export function generateSummary(metrics) {
+  const eff = ((metrics.efficiency || 0) * 100).toFixed(0);
+  return `Prepia: ${metrics.tasksProcessed} tasks | ${eff}% LLM avoided | ${metrics.tokensSaved} tokens saved | ${metrics.errors} errors`;
+}
+
+/**
+ * Format duration in ms to human readable.
+ * @param {number} ms
+ * @returns {string}
+ */
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  if (ms < 3600000) return `${Math.floor(ms / 60000)}m ${Math.floor((ms % 60000) / 1000)}s`;
+  return `${Math.floor(ms / 3600000)}h ${Math.floor((ms % 3600000) / 60000)}m`;
+}
+
+/**
+ * Format cache hit rate.
+ * @param {number} hits
+ * @param {number} misses
+ * @returns {string}
+ */
+function formatHitRate(hits, misses) {
+  const total = hits + misses;
+  if (total === 0) return 'N/A';
+  return `${((hits / total) * 100).toFixed(1)}%`;
+}
+
+export default { generateReport, generateSummary };

package/src/analytics/tracker.mjs

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview Usage tracking and metrics.
+ * @module analytics/tracker
+ */
+
+import { EventEmitter } from 'node:events';
+
+export class Tracker extends EventEmitter {
+  constructor() {
+    super();
+    this._metrics = {
+      tasksProcessed: 0,
+      llmCallsMade: 0,
+      llmCallsAvoided: 0,
+      tokensUsed: 0,
+      tokensSaved: 0,
+      totalDuration: 0,
+      cacheHits: 0,
+      cacheMisses: 0,
+      errors: 0,
+    };
+    this._taskHistory = [];
+    this._maxHistory = 1000;
+    this._startTime = Date.now();
+  }
+
+  /**
+   * Record a completed task.
+   * @param {Object} task
+   * @param {string} task.id - Task ID
+   * @param {string} task.type - Task type
+   * @param {boolean} task.usedLLM - Whether LLM was called
+   * @param {number} [task.tokensUsed=0] - Tokens consumed
+   * @param {number} [task.tokensSaved=0] - Tokens saved by optimization
+   * @param {number} task.duration - Task duration in ms
+   * @param {boolean} [task.cached=false] - Whether result was cached
+   * @param {boolean} [task.success=true] - Whether task succeeded
+   */
+  record(task) {
+    this._metrics.tasksProcessed++;
+    if (task.usedLLM) {
+      this._metrics.llmCallsMade++;
+      this._metrics.tokensUsed += task.tokensUsed || 0;
+    } else {
+      this._metrics.llmCallsAvoided++;
+    }
+    this._metrics.tokensSaved += task.tokensSaved || 0;
+    this._metrics.totalDuration += task.duration || 0;
+    if (task.cached) this._metrics.cacheHits++;
+    else this._metrics.cacheMisses++;
+    if (!task.success) this._metrics.errors++;
+
+    this._taskHistory.push({
+      ...task,
+      timestamp: Date.now(),
+    });
+    if (this._taskHistory.length > this._maxHistory) {
+      this._taskHistory.shift();
+    }
+
+    this.emit('task:recorded', task);
+  }
+
+  /**
+   * Get current metrics.
+   * @returns {Object}
+   */
+  getMetrics() {
+    const uptime = Date.now() - this._startTime;
+    const efficiency = this._metrics.tasksProcessed > 0
+      ? this._metrics.llmCallsAvoided / this._metrics.tasksProcessed
+      : 0;
+    const avgDuration = this._metrics.tasksProcessed > 0
+      ? this._metrics.totalDuration / this._metrics.tasksProcessed
+      : 0;
+
+    return {
+      ...this._metrics,
+      efficiency: Math.round(efficiency * 100) / 100,
+      avgDuration: Math.round(avgDuration),
+      uptime,
+      tasksPerMinute: uptime > 0 ? (this._metrics.tasksProcessed / (uptime / 60000)).toFixed(2) : 0,
+    };
+  }
+
+  /**
+   * Get task history.
+   * @param {number} [limit=50]
+   * @returns {Object[]}
+   */
+  getHistory(limit = 50) {
+    return this._taskHistory.slice(-limit);
+  }
+
+  /**
+   * Estimate cost savings.
+   * @param {number} [costPerToken=0.00001] - Cost per token in dollars
+   * @returns {Object}
+   */
+  estimateSavings(costPerToken = 0.00001) {
+    const tokensSaved = this._metrics.tokensSaved;
+    const callsAvoided = this._metrics.llmCallsAvoided;
+    return {
+      tokensSaved,
+      callsAvoided,
+      estimatedDollarsSaved: Math.round(tokensSaved * costPerToken * 100) / 100,
+      estimatedDollarsSpent: Math.round(this._metrics.tokensUsed * costPerToken * 100) / 100,
+    };
+  }
+
+  /**
+   * Reset all metrics.
+   */
+  reset() {
+    this._metrics = {
+      tasksProcessed: 0,
+      llmCallsMade: 0,
+      llmCallsAvoided: 0,
+      tokensUsed: 0,
+      tokensSaved: 0,
+      totalDuration: 0,
+      cacheHits: 0,
+      cacheMisses: 0,
+      errors: 0,
+    };
+    this._taskHistory = [];
+    this._startTime = Date.now();
+  }
+}
+
+export default Tracker;

package/src/api/middleware.mjs

@@ -0,0 +1,219 @@
+/**
+ * @fileoverview API middleware - request parsing, error handling, rate limiting, auth.
+ * @module api/middleware
+ */
+
+import { SlidingWindow } from '../rate/limiter.mjs';
+
+/**
+ * Parse JSON request body.
+ * @param {import('node:http').IncomingMessage} req
+ * @returns {Promise<Object>}
+ */
+export function parseBody(req) {
+  return new Promise((resolve, reject) => {
+    if (req.method === 'GET' || req.method === 'HEAD') {
+      resolve(null);
+      return;
+    }
+
+    let body = '';
+    req.on('data', chunk => {
+      body += chunk;
+      if (body.length > 1024 * 1024) { // 1MB limit
+        reject(new Error('Request body too large'));
+        req.destroy();
+      }
+    });
+    req.on('end', () => {
+      if (!body) {
+        resolve(null);
+        return;
+      }
+      try {
+        resolve(JSON.parse(body));
+      } catch {
+        reject(new Error('Invalid JSON body'));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+/**
+ * CORS middleware.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {Object} [options]
+ */
+export function cors(req, res, options = {}) {
+  const origin = options.origin || '*';
+  res.setHeader('Access-Control-Allow-Origin', origin);
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-API-Key');
+  res.setHeader('Access-Control-Max-Age', '86400');
+
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204);
+    res.end();
+  }
+}
+
+/**
+ * Per-client rate limiting middleware.
+ */
+export class RateLimitMiddleware {
+  /**
+   * @param {Object} [options]
+   * @param {number} [options.maxRequests=100] - Max requests per window
+   * @param {number} [options.windowMs=60000] - Window duration
+   */
+  constructor(options = {}) {
+    this._maxRequests = options.maxRequests ?? 100;
+    this._windowMs = options.windowMs ?? 60000;
+    /** @type {Map<string, SlidingWindow>} */
+    this._clients = new Map();
+  }
+
+  /**
+   * Check rate limit for a client.
+   * @param {string} clientId - Client identifier (IP or API key)
+   * @returns {{ allowed: boolean, remaining: number, retryAfter: number }}
+   */
+  check(clientId) {
+    if (!this._clients.has(clientId)) {
+      this._clients.set(clientId, new SlidingWindow({
+        maxRequests: this._maxRequests,
+        windowMs: this._windowMs,
+      }));
+    }
+
+    const window = this._clients.get(clientId);
+    const allowed = window.consume();
+    return {
+      allowed,
+      remaining: window.remaining,
+      retryAfter: allowed ? 0 : window.waitFor(),
+    };
+  }
+
+  /**
+   * Clean up old client entries.
+   */
+  cleanup() {
+    for (const [id, window] of this._clients) {
+      if (window.remaining === this._maxRequests) {
+        this._clients.delete(id);
+      }
+    }
+  }
+}
+
+/**
+ * Authentication middleware.
+ */
+export class AuthMiddleware {
+  /**
+   * @param {Object} [options]
+   * @param {string[]} [options.apiKeys] - Valid API keys
+   * @param {boolean} [options.required=false] - Whether auth is required
+   */
+  constructor(options = {}) {
+    this._apiKeys = new Set(options.apiKeys || []);
+    this._required = options.required ?? false;
+  }
+
+  /**
+   * Authenticate a request.
+   * @param {import('node:http').IncomingMessage} req
+   * @returns {{ authenticated: boolean, clientId: string }}
+   */
+  authenticate(req) {
+    const apiKey = req.headers['x-api-key'] || this._extractBearerToken(req);
+
+    if (!apiKey) {
+      return { authenticated: !this._required, clientId: req.socket.remoteAddress || 'unknown' };
+    }
+
+    if (this._apiKeys.size === 0) {
+      return { authenticated: true, clientId: apiKey };
+    }
+
+    const valid = this._apiKeys.has(apiKey);
+    return {
+      authenticated: valid,
+      clientId: valid ? apiKey : req.socket.remoteAddress || 'unknown',
+    };
+  }
+
+  /**
+   * Add an API key.
+   * @param {string} key
+   */
+  addKey(key) {
+    this._apiKeys.add(key);
+  }
+
+  /**
+   * Remove an API key.
+   * @param {string} key
+   */
+  removeKey(key) {
+    this._apiKeys.delete(key);
+  }
+
+  /**
+   * Extract Bearer token from Authorization header.
+   * @param {import('node:http').IncomingMessage} req
+   * @returns {string|null}
+   * @private
+   */
+  _extractBearerToken(req) {
+    const auth = req.headers.authorization;
+    if (auth?.startsWith('Bearer ')) {
+      return auth.substring(7);
+    }
+    return null;
+  }
+}
+
+/**
+ * Error handler middleware.
+ * @param {Error} err
+ * @param {import('node:http').ServerResponse} res
+ */
+export function errorHandler(err, res) {
+  const status = err.statusCode || 500;
+  const message = err.message || 'Internal Server Error';
+
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({
+    error: {
+      message,
+      status,
+      timestamp: new Date().toISOString(),
+    },
+  }));
+}
+
+/**
+ * Request logger middleware.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @returns {Object} Logger with end() method
+ */
+export function requestLogger(req) {
+  const start = Date.now();
+  const method = req.method;
+  const url = req.url;
+
+  return {
+    end(res) {
+      const duration = Date.now() - start;
+      const status = res.statusCode;
+      console.log(`${method} ${url} ${status} ${duration}ms`);
+    },
+  };
+}
+
+export default { parseBody, cors, RateLimitMiddleware, AuthMiddleware, errorHandler, requestLogger };

package/src/api/routes.mjs

@@ -0,0 +1,142 @@
+/**
+ * @fileoverview API route handlers.
+ * @module api/routes
+ */
+
+/**
+ * Create route handlers for the API.
+ * @param {Object} engine - Prepia engine instance
+ * @returns {Object} Route handlers
+ */
+export function createRoutes(engine) {
+  /**
+   * POST /task - Submit a task
+   */
+  async function handleTask(req, res, body) {
+    if (!body || !body.query) {
+      return sendError(res, 400, 'Missing "query" in request body');
+    }
+
+    try {
+      const result = await engine.process(body.query, {
+        mode: body.mode || 'shot',
+        workflow: body.workflow,
+        ...body.options,
+      });
+      sendJSON(res, 200, result);
+    } catch (err) {
+      sendError(res, 500, err.message);
+    }
+  }
+
+  /**
+   * GET /status - Health check
+   */
+  function handleStatus(req, res) {
+    sendJSON(res, 200, {
+      status: 'ok',
+      version: '1.0.0',
+      uptime: process.uptime(),
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  /**
+   * GET /analytics - Usage stats
+   */
+  function handleAnalytics(req, res) {
+    try {
+      const metrics = engine.getAnalytics();
+      sendJSON(res, 200, metrics);
+    } catch (err) {
+      sendError(res, 500, err.message);
+    }
+  }
+
+  /**
+   * POST /cache/clear - Clear cache
+   */
+  async function handleCacheClear(req, res) {
+    try {
+      await engine.clearCache();
+      sendJSON(res, 200, { message: 'Cache cleared' });
+    } catch (err) {
+      sendError(res, 500, err.message);
+    }
+  }
+
+  /**
+   * GET /plugins - List plugins
+   */
+  function handlePlugins(req, res) {
+    try {
+      const plugins = engine.getPlugins();
+      sendJSON(res, 200, { plugins });
+    } catch (err) {
+      sendError(res, 500, err.message);
+    }
+  }
+
+  /**
+   * POST /config - Update configuration
+   */
+  function handleConfig(req, res, body) {
+    if (!body) {
+      return sendError(res, 400, 'Missing request body');
+    }
+    try {
+      engine.updateConfig(body);
+      sendJSON(res, 200, { message: 'Configuration updated' });
+    } catch (err) {
+      sendError(res, 500, err.message);
+    }
+  }
+
+  /**
+   * Route a request to the appropriate handler.
+   * @param {import('node:http').IncomingMessage} req
+   * @param {import('node:http').ServerResponse} res
+   * @param {Object|null} body - Parsed request body
+   */
+  async function route(req, res, body) {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const path = url.pathname;
+    const method = req.method;
+
+    // Match routes
+    if (path === '/task' && method === 'POST') return handleTask(req, res, body);
+    if (path === '/status' && method === 'GET') return handleStatus(req, res);
+    if (path === '/analytics' && method === 'GET') return handleAnalytics(req, res);
+    if (path === '/cache/clear' && method === 'POST') return handleCacheClear(req, res);
+    if (path === '/plugins' && method === 'GET') return handlePlugins(req, res);
+    if (path === '/config' && method === 'POST') return handleConfig(req, res);
+
+    // 404
+    sendError(res, 404, `Not found: ${method} ${path}`);
+  }
+
+  return { route, handleTask, handleStatus, handleAnalytics, handleCacheClear, handlePlugins, handleConfig };
+}
+
+/**
+ * Send a JSON response.
+ * @param {import('node:http').ServerResponse} res
+ * @param {number} status
+ * @param {*} data
+ */
+function sendJSON(res, status, data) {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(data, null, 2));
+}
+
+/**
+ * Send an error response.
+ * @param {import('node:http').ServerResponse} res
+ * @param {number} status
+ * @param {string} message
+ */
+function sendError(res, status, message) {
+  sendJSON(res, status, { error: { message, status } });
+}
+
+export default { createRoutes };