apiforgejs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 APIForge Organisation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# apiforgejs
+
+API observability & intelligence SDK for Express.js — local-first, privacy-first.
+
+> Track latency, error rates, and behavioral trends of your APIs. Everything stays on your machine.
+
+## Install
+
+```bash
+npm install apiforgejs
+```
+
+## Quick start
+
+```javascript
+const express = require('express');
+const { apiforge } = require('apiforgejs');
+
+const app = express();
+
+// Add the middleware — one line, zero config required
+app.use(apiforge({ mode: 'local' }));
+
+app.get('/users/:id', (req, res) => res.json({ id: req.params.id }));
+
+app.listen(3000, () => {
+  console.log('App running on :3000');
+  // Dashboard auto-starts at http://localhost:4242
+});
+```
+
+## Dashboard
+
+Open **http://localhost:4242** after starting your app. The dashboard shows:
+
+- **Health Score** (0–100) — global API health at a glance
+- **Latency percentiles** — P50 / P90 / P99 per route
+- **Error rates** — 4xx and 5xx breakdown
+- **Automatic insights** — latency anomalies, dead endpoints, release regressions
+- **Time series chart** — click any route to see its latency over time
+
+Data is collected locally in `.apiforge.db` (SQLite). Nothing leaves your machine.
+
+## Configuration
+
+```javascript
+app.use(apiforge({
+  mode:          'local',                 // only supported mode in v0.x
+  dbPath:        '.apiforge.db',          // SQLite file location
+  dashboardPort: 4242,                    // set to 0 to disable dashboard
+  flushInterval: 60_000,                  // flush to SQLite every 60s (ms)
+  env:           process.env.NODE_ENV,    // 'production' | 'staging' | 'development'
+  release:       process.env.APP_VERSION, // enables release regression detection
+  service:       'my-api',               // label for multi-service setups
+  sampling:      1.0,                     // 0.0–1.0 sample rate
+  ignorePaths:   ['/health', '/ping'],    // paths to skip
+}));
+```
+
+## Release tracking
+
+Pass your release version to enable before/after deployment comparison:
+
+```javascript
+app.use(apiforge({
+  mode: 'local',
+  release: process.env.npm_package_version, // or 'v1.4.0', git SHA, etc.
+}));
+```
+
+When a new release is detected, APIForge automatically compares P90 latency before vs. after and surfaces regressions as insights.
+
+## Graceful shutdown
+
+```javascript
+const forge = apiforge({ mode: 'local' });
+app.use(forge);
+
+process.on('SIGTERM', () => {
+  forge.shutdown(); // flush remaining buffer to SQLite
+  process.exit(0);
+});
+```
+
+## Privacy by design
+
+The SDK **never** collects:
+- Request or response bodies
+- HTTP headers (Authorization, Cookie, etc.)
+- Query string values
+- Route parameter values (`/users/12345` → only `/users/:id` is stored)
+- IP addresses or User-Agent strings
+
+Collected fields: route pattern, HTTP method, status code, latency (ms), timestamp, and optional env/release/service labels.
+
+## Data collected
+
+```json
+{
+  "route":       "GET /users/:id",
+  "method":      "GET",
+  "status":      200,
+  "duration_ms": 134.7,
+  "timestamp":   "2026-05-13T10:00:00.000Z",
+  "env":         "production",
+  "release":     "v1.4.0"
+}
+```
+
+## Requirements
+
+- Node.js >= 18
+- Express >= 4
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "apiforgejs",
+  "version": "0.1.0",
+  "description": "API observability & intelligence SDK for Express.js — local-first, privacy-first",
+  "main": "src/index.js",
+  "keywords": [
+    "api", "observability", "monitoring", "express", "metrics",
+    "performance", "analytics", "middleware", "latency", "local-first"
+  ],
+  "author": "APIForge",
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "test:smoke": "node --test test/smoke.test.js"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "dependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "files": [
+    "src/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/APIForge-Organisation/sdk-nodejs"
+  }
+}

package/src/aggregator.js

@@ -0,0 +1,91 @@
+'use strict';
+
+class Aggregator {
+  constructor(transport, flushIntervalMs = 60_000) {
+    this.transport = transport;
+    this.flushIntervalMs = flushIntervalMs;
+    this.buffer = new Map();
+    this.timer = null;
+  }
+
+  start() {
+    this.timer = setInterval(() => this._flush(), this.flushIntervalMs);
+    // Don't prevent the process from exiting if nothing else is running
+    if (this.timer.unref) this.timer.unref();
+  }
+
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this._flush();
+  }
+
+  record(event) {
+    const key = `${event.method}|${event.route}|${event.env}|${event.release || ''}`;
+    let bucket = this.buffer.get(key);
+
+    if (!bucket) {
+      bucket = {
+        method: event.method,
+        route: event.route,
+        env: event.env,
+        release: event.release,
+        durations: [],
+        status_2xx: 0,
+        status_4xx: 0,
+        status_5xx: 0,
+      };
+      this.buffer.set(key, bucket);
+    }
+
+    bucket.durations.push(event.duration_ms);
+
+    const s = event.status;
+    if (s >= 200 && s < 300) bucket.status_2xx++;
+    else if (s >= 400 && s < 500) bucket.status_4xx++;
+    else if (s >= 500) bucket.status_5xx++;
+  }
+
+  _flush() {
+    if (this.buffer.size === 0) return;
+
+    // Round down to the current minute as the bucket timestamp
+    const bucketTs = Math.floor(Date.now() / 60_000) * 60;
+    const rows = [];
+
+    for (const bucket of this.buffer.values()) {
+      const sorted = bucket.durations.slice().sort((a, b) => a - b);
+      const n = sorted.length;
+
+      rows.push({
+        bucket_ts: bucketTs,
+        route: bucket.route,
+        method: bucket.method,
+        env: bucket.env,
+        release_tag: bucket.release,
+        status_2xx: bucket.status_2xx,
+        status_4xx: bucket.status_4xx,
+        status_5xx: bucket.status_5xx,
+        total_calls: n,
+        lat_p50: percentile(sorted, 0.50),
+        lat_p90: percentile(sorted, 0.90),
+        lat_p99: percentile(sorted, 0.99),
+        lat_min: sorted[0] ?? 0,
+        lat_max: sorted[n - 1] ?? 0,
+      });
+    }
+
+    this.buffer.clear();
+    this.transport.write(rows);
+  }
+}
+
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(Math.ceil(p * sorted.length) - 1, sorted.length - 1);
+  return sorted[Math.max(0, idx)];
+}
+
+module.exports = { Aggregator };

package/src/dashboard.js

@@ -0,0 +1,186 @@
+'use strict';
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { getInsights, computeHealthScore } = require('./insights');
+
+const UI_HTML = path.join(__dirname, 'ui.html');
+
+// Resolve React / ReactDOM UMD bundles from node_modules.
+// These are added as direct dependencies of apiforgejs so they are always present.
+function resolveAsset(pkg, file) {
+  try {
+    const main = require.resolve(pkg);
+    const pkgDir = path.dirname(main);
+    const candidate = path.join(pkgDir, 'umd', file);
+    if (fs.existsSync(candidate)) return candidate;
+    const alt = path.join(pkgDir, file);
+    if (fs.existsSync(alt)) return alt;
+  } catch (_) {}
+  return null;
+}
+
+const REACT_PATH     = resolveAsset('react', 'react.production.min.js');
+const REACT_DOM_PATH = resolveAsset('react-dom', 'react-dom.production.min.js');
+
+function startDashboard(db, port) {
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, `http://localhost:${port}`);
+    try {
+      route(req, res, url, db);
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+  });
+
+  server.listen(port, '127.0.0.1', () => {
+    console.log(`[apiforgejs] Dashboard → http://localhost:${port}`);
+  });
+
+  server.on('error', (err) => {
+    if (err.code === 'EADDRINUSE') {
+      console.warn(`[apiforgejs] Port ${port} already in use — dashboard not started.`);
+    }
+  });
+
+  return server;
+}
+
+function route(req, res, url, db) {
+  const pathname = url.pathname;
+
+  // ── HTML shell ────────────────────────────────────────────────────────────
+  if (req.method === 'GET' && pathname === '/') {
+    serveFile(res, UI_HTML, 'text/html; charset=utf-8');
+    return;
+  }
+
+  // ── Static assets (React UMD) ─────────────────────────────────────────────
+  if (req.method === 'GET' && pathname === '/assets/react.js') {
+    if (REACT_PATH) {
+      serveFile(res, REACT_PATH, 'application/javascript');
+    } else {
+      res.writeHead(404);
+      res.end('// react not found — run npm install inside apiforgejs');
+    }
+    return;
+  }
+
+  if (req.method === 'GET' && pathname === '/assets/react-dom.js') {
+    if (REACT_DOM_PATH) {
+      serveFile(res, REACT_DOM_PATH, 'application/javascript');
+    } else {
+      res.writeHead(404);
+      res.end('// react-dom not found — run npm install inside apiforgejs');
+    }
+    return;
+  }
+
+  // ── API: summary ──────────────────────────────────────────────────────────
+  if (req.method === 'GET' && pathname === '/api/summary') {
+    const data = db.getSummary();
+    const healthScore = computeHealthScore(db);
+    const insights = getInsights(db);
+
+    const total  = data.recent?.calls_total || 0;
+    const errors = (data.recent?.calls_4xx || 0) + (data.recent?.calls_5xx || 0);
+    const errorRate = total > 0 ? (errors / total) * 100 : 0;
+
+    sendJson(res, {
+      health_score:    healthScore,
+      calls_24h:       total,
+      error_rate_24h:  parseFloat(errorRate.toFixed(2)),
+      avg_p90_24h:     round(data.recent?.avg_p90),
+      avg_p99_24h:     round(data.recent?.avg_p99),
+      active_routes:   data.activeRoutes,
+      total_routes:    data.totalRoutes,
+      insights_count:  insights.length,
+      insights,
+    });
+    return;
+  }
+
+  // ── API: routes ───────────────────────────────────────────────────────────
+  if (req.method === 'GET' && pathname === '/api/routes') {
+    const hours = parseInt(url.searchParams.get('hours') || '24', 10);
+    const routes = db.getRoutes(hours);
+
+    const untracked = db.getUntrackedRoutes().map(r => ({
+      route:      r.route,
+      method:     r.method,
+      calls:      0,
+      calls_2xx:  0,
+      calls_4xx:  0,
+      calls_5xx:  0,
+      p50:        null,
+      p90:        null,
+      p99:        null,
+      lat_max:    null,
+      untracked:  true,
+    }));
+
+    sendJson(res, [...routes, ...untracked]);
+    return;
+  }
+
+  // ── API: timeseries (per route) ───────────────────────────────────────────
+  if (req.method === 'GET' && pathname === '/api/timeseries') {
+    const r     = url.searchParams.get('route');
+    const m     = url.searchParams.get('method');
+    const hours = parseInt(url.searchParams.get('hours') || '24', 10);
+
+    if (!r || !m) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'route and method are required' }));
+      return;
+    }
+
+    sendJson(res, db.getTimeSeries(r, m, hours));
+    return;
+  }
+
+  // ── API: global timeseries (all routes aggregated) ────────────────────────
+  if (req.method === 'GET' && pathname === '/api/global-timeseries') {
+    const hours = parseInt(url.searchParams.get('hours') || '24', 10);
+    sendJson(res, db.getGlobalTimeSeries(hours));
+    return;
+  }
+
+  // ── API: releases ─────────────────────────────────────────────────────────
+  if (req.method === 'GET' && pathname === '/api/releases') {
+    sendJson(res, db.getReleases());
+    return;
+  }
+
+  res.writeHead(404);
+  res.end('Not found');
+}
+
+function serveFile(res, filePath, contentType) {
+  fs.readFile(filePath, (err, data) => {
+    if (err) {
+      res.writeHead(404);
+      res.end('File not found');
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': contentType, 'Cache-Control': 'no-cache' });
+    res.end(data);
+  });
+}
+
+function sendJson(res, data) {
+  const body = JSON.stringify(data);
+  res.writeHead(200, {
+    'Content-Type': 'application/json',
+    'Access-Control-Allow-Origin': '*',
+  });
+  res.end(body);
+}
+
+function round(v) {
+  return v != null ? parseFloat(v.toFixed(2)) : null;
+}
+
+module.exports = { startDashboard };