apiforgejs 1.0.2 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apiforgejs",
-  "version": "1.0.2",
+  "version": "2.0.0",
   "description": "API observability & intelligence SDK for Express.js — local-first, privacy-first",
   "main": "src/index.js",
   "keywords": [
@@ -18,16 +18,12 @@
   "author": "APIForge",
   "license": "MIT",
   "scripts": {
-    "test": "node --test test/**/*.test.js",
-    "test:smoke": "node --test test/smoke.test.js"
+    "tests": "node --test tests/**/*.test.js",
+    "test:smoke": "node --test tests/smoke.test.js"
   },
   "engines": {
     "node": ">=22.5.0"
   },
-  "dependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
-  },
   "peerDependencies": {
     "express": ">=4.0.0"
   },

package/src/aggregator.js

@@ -33,6 +33,7 @@ class Aggregator {
         env: event.env,
         release: event.release,
         durations: [],
+        response_sizes: [],
         status_2xx: 0,
         status_4xx: 0,
         status_5xx: 0,
@@ -41,6 +42,7 @@ class Aggregator {
     }
 
     bucket.durations.push(event.duration_ms);
+    if (event.response_size != null) bucket.response_sizes.push(event.response_size);
 
     const s = event.status;
     if (s >= 200 && s < 300) bucket.status_2xx++;
@@ -58,6 +60,14 @@ class Aggregator {
     for (const bucket of this.buffer.values()) {
       const sorted = bucket.durations.slice().sort((a, b) => a - b);
       const n = sorted.length;
+      const sizes = bucket.response_sizes;
+      const bytes_avg = sizes.length > 0
+        ? sizes.reduce((a, b) => a + b, 0) / sizes.length
+        : null;
+
+      const lat_avg = n > 0
+        ? bucket.durations.reduce((a, b) => a + b, 0) / n
+        : null;
 
       rows.push({
         bucket_ts: bucketTs,
@@ -72,8 +82,10 @@ class Aggregator {
         lat_p50: percentile(sorted, 0.50),
         lat_p90: percentile(sorted, 0.90),
         lat_p99: percentile(sorted, 0.99),
+        lat_avg,
         lat_min: sorted[0] ?? 0,
         lat_max: sorted[n - 1] ?? 0,
+        bytes_avg,
       });
     }
 

package/src/cloud-transport.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const CIRCUIT_OPEN_MS  = 60_000;
+const FAILURE_THRESHOLD = 5;
+
+class CloudTransport {
+  /**
+   * @param {string} cloudUrl  - Base URL of the SaaS API, e.g. 'https://api.apiforge.fr'
+   * @param {string} apiKey    - Project API key starting with 'af_'
+   * @param {string} service   - Service name passed to every metric row
+   */
+  constructor(cloudUrl, apiKey, service) {
+    this._url     = `${cloudUrl.replace(/\/$/, '')}/ingest`;
+    this._apiKey  = apiKey;
+    this._service = service;
+    this._failures  = 0;
+    this._openUntil = 0;
+  }
+
+  write(rows) {
+    if (rows.length === 0) return;
+    if (Date.now() < this._openUntil) return;
+
+    const metrics = rows.map(r => ({
+      route:       r.route,
+      method:      r.method,
+      service:     this._service,
+      env:         r.env,
+      release:     r.release_tag ?? null,
+      time:        new Date(r.bucket_ts * 1000).toISOString(),
+      calls_total: r.total_calls,
+      calls_2xx:   r.status_2xx,
+      calls_4xx:   r.status_4xx,
+      calls_5xx:   r.status_5xx,
+      lat_p50:     r.lat_p50 ?? null,
+      lat_p90:     r.lat_p90 ?? null,
+      lat_p99:     r.lat_p99 ?? null,
+      lat_avg:     r.lat_avg ?? null,
+      bytes_avg:   r.bytes_avg ?? null,
+    }));
+
+    fetch(this._url, {
+      method:  'POST',
+      headers: { 'Content-Type': 'application/json', 'X-API-Key': this._apiKey },
+      body:    JSON.stringify({ metrics }),
+    })
+      .then(res => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        this._failures = 0;
+      })
+      .catch(err => {
+        this._failures++;
+        if (this._failures >= FAILURE_THRESHOLD) {
+          this._openUntil = Date.now() + CIRCUIT_OPEN_MS;
+          this._failures  = 0;
+          console.warn(`[apiforgejs] Cloud flush failures — pausing for ${CIRCUIT_OPEN_MS / 1000}s. Error: ${err.message}`);
+        }
+      });
+  }
+}
+
+module.exports = { CloudTransport };

package/src/database.js

@@ -44,19 +44,23 @@ class ApiForgeDatabase {
         lat_p90     REAL,
         lat_p99     REAL,
         lat_min     REAL,
-        lat_max     REAL
+        lat_max     REAL,
+        bytes_avg   REAL
       );
       CREATE INDEX IF NOT EXISTS idx_route_ts  ON api_metrics (route, method, bucket_ts);
       CREATE INDEX IF NOT EXISTS idx_bucket_ts ON api_metrics (bucket_ts);
       CREATE INDEX IF NOT EXISTS idx_release   ON api_metrics (release_tag) WHERE release_tag IS NOT NULL;
     `);
 
+    // Migration for databases created before bytes_avg was introduced
+    try { this.db.exec('ALTER TABLE api_metrics ADD COLUMN bytes_avg REAL'); } catch (_) {}
+
     this._stmtInsert = this.db.prepare(`
       INSERT INTO api_metrics
         (bucket_ts, route, method, env, release_tag,
          status_2xx, status_4xx, status_5xx, total_calls,
-         lat_p50, lat_p90, lat_p99, lat_min, lat_max)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         lat_p50, lat_p90, lat_p99, lat_min, lat_max, bytes_avg)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
 
     this._begin    = this.db.prepare('BEGIN');
@@ -71,7 +75,7 @@ class ApiForgeDatabase {
         this._stmtInsert.run(
           r.bucket_ts, r.route, r.method, r.env, r.release_tag ?? null,
           r.status_2xx, r.status_4xx, r.status_5xx, r.total_calls,
-          r.lat_p50, r.lat_p90, r.lat_p99, r.lat_min, r.lat_max
+          r.lat_p50, r.lat_p90, r.lat_p99, r.lat_min, r.lat_max, r.bytes_avg ?? null
         );
       }
       this._commit.run();
@@ -131,7 +135,8 @@ class ApiForgeDatabase {
         AVG(lat_p50)     as p50,
         AVG(lat_p90)     as p90,
         AVG(lat_p99)     as p99,
-        MAX(lat_max)     as lat_max
+        MAX(lat_max)     as lat_max,
+        AVG(bytes_avg)   as bytes_avg
       FROM api_metrics
       WHERE bucket_ts >= ?
       GROUP BY route, method
@@ -286,6 +291,21 @@ class ApiForgeDatabase {
     `).all();
   }
 
+  // Returns one row per (route, method, day) for the last 30 days, used by drift detection
+  getDriftData() {
+    const since30d = nowSec() - 30 * 86_400;
+    return this.db.prepare(`
+      SELECT
+        route, method,
+        CAST(bucket_ts / 86400 AS INTEGER) as day_bucket,
+        AVG(lat_p90) as p90
+      FROM api_metrics
+      WHERE bucket_ts >= ? AND lat_p90 IS NOT NULL
+      GROUP BY route, method, day_bucket
+      ORDER BY route, method, day_bucket
+    `).all(since30d);
+  }
+
   getGlobalTimeSeries(hours = 24) {
     const since = nowSec() - hours * 3600;
     return this.db.prepare(`

package/src/index.js

@@ -1,49 +1,64 @@
 'use strict';
 
 const { createInterceptor } = require('./interceptor');
-const { Aggregator } = require('./aggregator');
-const { LocalTransport } = require('./transport');
-const { ApiForgeDatabase } = require('./database');
-const { startDashboard } = require('./dashboard');
+const { Aggregator }        = require('./aggregator');
+const { LocalTransport }    = require('./transport');
+const { CloudTransport }    = require('./cloud-transport');
+const { ApiForgeDatabase }  = require('./database');
+const { startDashboard }    = require('./dashboard');
 
 /**
  * APIForge Express middleware factory.
  *
- * @param {object} options
- * @param {'local'} options.mode          - Storage mode. Only 'local' (SQLite) in v0.x.
- * @param {string}  [options.dbPath]      - SQLite file path. Default: '.apiforge.db'
- * @param {number}  [options.dashboardPort] - Dashboard port. Default: 4242. Set to 0 to disable.
- * @param {number}  [options.flushInterval] - Aggregation flush interval in ms. Default: 60000.
- * @param {string}  [options.env]         - Environment label. Default: NODE_ENV or 'production'.
- * @param {string}  [options.release]     - Release/version tag for deployment correlation.
- * @param {string}  [options.service]     - Service name for multi-service setups.
- * @param {number}  [options.sampling]    - Sample rate 0.0–1.0. Default: 1.0.
- * @param {string[]}[options.ignorePaths] - Paths to skip. Default: ['/favicon.ico'].
+ * @param {object}   options
+ * @param {string}   [options.mode]          - 'local' (default) or 'cloud'.
+ * @param {string}   [options.cloudUrl]      - Cloud mode: SaaS API base URL.
+ * @param {string}   [options.apiKey]        - Cloud mode: project API key (af_…).
+ * @param {string}   [options.dbPath]        - Local mode: SQLite path. Default: '.apiforge.db'.
+ * @param {number}   [options.dashboardPort] - Local mode: dashboard port. Default: 4242. 0 = off.
+ * @param {number}   [options.flushInterval] - Flush interval in ms. Default: 60000.
+ * @param {string}   [options.env]           - Environment label. Default: NODE_ENV or 'production'.
+ * @param {string}   [options.release]       - Release/version tag.
+ * @param {string}   [options.service]       - Service name. Default: 'default'.
+ * @param {number}   [options.sampling]      - Sample rate 0.0–1.0. Default: 1.0.
+ * @param {string[]} [options.ignorePaths]   - Paths to skip. Default: ['/favicon.ico'].
  */
 function apiforge(options = {}) {
-  if (options.mode && options.mode !== 'local') {
-    throw new Error(`[apiforgejs] mode '${options.mode}' is not yet supported. Use 'local'.`);
+  const hasCloudUrl = Boolean(options.cloudUrl);
+  const hasApiKey   = Boolean(options.apiKey);
+  const isCloud     = options.mode === 'cloud' || (hasCloudUrl && hasApiKey);
+
+  if ((hasCloudUrl || hasApiKey) && !(hasCloudUrl && hasApiKey)) {
+    throw new Error('[apiforgejs] Cloud mode requires both cloudUrl and apiKey options.');
   }
 
   const config = {
-    mode: 'local',
-    dbPath: options.dbPath ?? '.apiforge.db',
-    dashboardPort: options.dashboardPort !== undefined ? options.dashboardPort : 4242,
+    mode:          isCloud ? 'cloud' : 'local',
+    cloudUrl:      options.cloudUrl ?? null,
+    apiKey:        options.apiKey   ?? null,
+    dbPath:        options.dbPath   ?? '.apiforge.db',
+    dashboardPort: isCloud ? 0 : (options.dashboardPort !== undefined ? options.dashboardPort : 4242),
     flushInterval: options.flushInterval ?? 60_000,
-    env: options.env ?? process.env.NODE_ENV ?? 'production',
-    release: options.release ?? process.env.APP_VERSION ?? null,
-    service: options.service ?? 'default',
-    sampling: options.sampling ?? 1.0,
-    ignorePaths: options.ignorePaths ?? ['/favicon.ico'],
+    env:           options.env ?? process.env.NODE_ENV ?? 'production',
+    release:       options.release ?? process.env.APP_VERSION ?? null,
+    service:       options.service ?? 'default',
+    sampling:      options.sampling ?? 1.0,
+    ignorePaths:   options.ignorePaths ?? ['/favicon.ico'],
   };
 
-  const db = new ApiForgeDatabase(config.dbPath);
-  const transport = new LocalTransport(db);
-  const aggregator = new Aggregator(transport, config.flushInterval);
+  let transport, db;
 
+  if (isCloud) {
+    transport = new CloudTransport(config.cloudUrl, config.apiKey, config.service);
+  } else {
+    db        = new ApiForgeDatabase(config.dbPath);
+    transport = new LocalTransport(db);
+  }
+
+  const aggregator = new Aggregator(transport, config.flushInterval);
   aggregator.start();
 
-  if (config.dashboardPort) {
+  if (!isCloud && config.dashboardPort) {
     startDashboard(db, config.dashboardPort);
   }
 
@@ -51,7 +66,7 @@ function apiforge(options = {}) {
 
   middleware.shutdown = () => {
     aggregator.stop();
-    db.close();
+    if (db) db.close();
   };
 
   return middleware;

package/src/insights.js

@@ -1,27 +1,19 @@
 'use strict';
 
-const DEAD_ENDPOINT_DAYS = 21;
-const REGRESSION_THRESHOLD = 0.20; // 20% worse P90 triggers regression insight
-const ANOMALY_Z_THRESHOLD = 2.5;   // Z-score threshold for latency anomaly
+const DEAD_ENDPOINT_DAYS    = 21;
+const REGRESSION_THRESHOLD  = 0.20;  // 20% worse P90 triggers regression insight
+const ANOMALY_Z_THRESHOLD   = 2.5;   // Z-score threshold for latency anomaly
+const DRIFT_SLOPE_THRESHOLD = 5;     // ms/day above which progressive drift is reported
+const DRIFT_MIN_DAYS        = 7;     // minimum number of daily data points required
 
 function getInsights(db) {
   const insights = [];
 
-  try {
-    insights.push(...detectLatencyAnomalies(db));
-  } catch (_) {}
-
-  try {
-    insights.push(...detectDeadEndpoints(db));
-  } catch (_) {}
-
-  try {
-    insights.push(...detectReleaseRegressions(db));
-  } catch (_) {}
-
-  try {
-    insights.push(...detectUntrackedRoutes(db));
-  } catch (_) {}
+  try { insights.push(...detectLatencyAnomalies(db));  } catch (_) {}
+  try { insights.push(...detectDeadEndpoints(db));      } catch (_) {}
+  try { insights.push(...detectReleaseRegressions(db)); } catch (_) {}
+  try { insights.push(...detectUntrackedRoutes(db));    } catch (_) {}
+  try { insights.push(...detectDrift(db));              } catch (_) {}
 
   return insights;
 }
@@ -33,7 +25,7 @@ function detectUntrackedRoutes(db) {
     severity: 'info',
     route: r.route,
     method: r.method,
-    message: `\`${r.method} ${r.route}\` est déclaré dans l'application mais n'a reçu aucune requête depuis le début du monitoring.`,
+    message: `\`${r.method} ${r.route}\` is declared but has received no requests since monitoring started.`,
     data: { first_seen_ts: r.first_seen },
   }));
 }
@@ -69,7 +61,7 @@ function detectLatencyAnomalies(db) {
         severity: 'warning',
         route: r.route,
         method: r.method,
-        message: `La latence P99 de \`${r.method} ${r.route}\` est anormalement élevée cette heure (${fmt(r.avg_p99)} vs moyenne ${fmt(mean)} — Z-score ${z.toFixed(1)}).`,
+        message: `\`${r.method} ${r.route}\` P99 latency is abnormally high this hour (${fmt(r.avg_p99)} vs baseline ${fmt(mean)} — Z-score ${z.toFixed(1)}).`,
         data: { current_p99: r.avg_p99, baseline_p99: mean, z_score: z },
       });
     }
@@ -87,7 +79,7 @@ function detectDeadEndpoints(db) {
       severity: 'info',
       route: row.route,
       method: row.method,
-      message: `\`${row.method} ${row.route}\` n'a reçu aucune requête depuis ${daysSince} jours. Candidat à la déprécation.`,
+      message: `\`${row.method} ${row.route}\` has received no requests in ${daysSince} days. Consider deprecating this endpoint.`,
       data: { last_seen_ts: row.last_seen, inactive_days: daysSince },
     };
   });
@@ -115,7 +107,7 @@ function detectReleaseRegressions(db) {
         severity: 'error',
         route: a.route,
         method: a.method,
-        message: `La latence P90 de \`${a.method} ${a.route}\` a augmenté de ${pct(delta)} depuis le déploiement ${release_tag}. Avant : ${fmt(b.avg_p90)} — Après : ${fmt(a.avg_p90)}.`,
+        message: `\`${a.method} ${a.route}\` P90 increased by ${pct(delta)} after ${release_tag}. Before: ${fmt(b.avg_p90)} — After: ${fmt(a.avg_p90)}.`,
         data: {
           release: release_tag,
           before_p90: b.avg_p90,
@@ -129,7 +121,7 @@ function detectReleaseRegressions(db) {
         severity: 'success',
         route: a.route,
         method: a.method,
-        message: `Le déploiement ${release_tag} a amélioré \`${a.method} ${a.route}\` de ${pct(-delta)}. Avant : ${fmt(b.avg_p90)} — Après : ${fmt(a.avg_p90)}.`,
+        message: `${release_tag} improved \`${a.method} ${a.route}\` by ${pct(-delta)}. Before: ${fmt(b.avg_p90)} — After: ${fmt(a.avg_p90)}.`,
         data: {
           release: release_tag,
           before_p90: b.avg_p90,
@@ -143,6 +135,53 @@ function detectReleaseRegressions(db) {
   return insights;
 }
 
+function detectDrift(db) {
+  const rows = db.getDriftData();
+  if (rows.length === 0) return [];
+
+  // Group daily P90 samples by endpoint
+  const byEndpoint = new Map();
+  for (const row of rows) {
+    const key = `${row.method}|${row.route}`;
+    if (!byEndpoint.has(key)) byEndpoint.set(key, { method: row.method, route: row.route, points: [] });
+    byEndpoint.get(key).points.push({ x: row.day_bucket, y: row.p90 });
+  }
+
+  const insights = [];
+  for (const { method, route, points } of byEndpoint.values()) {
+    if (points.length < DRIFT_MIN_DAYS) continue;
+
+    // Ordinary least squares on (day_index, p90) pairs
+    const x0  = points[0].x;
+    const xs   = points.map(p => p.x - x0);
+    const ys   = points.map(p => p.y);
+    const n    = xs.length;
+    const sumX  = xs.reduce((a, b) => a + b, 0);
+    const sumY  = ys.reduce((a, b) => a + b, 0);
+    const sumXY = xs.reduce((s, x, i) => s + x * ys[i], 0);
+    const sumX2 = xs.reduce((s, x) => s + x * x, 0);
+    const denom = n * sumX2 - sumX * sumX;
+    if (denom === 0) continue;
+
+    const slope = (n * sumXY - sumX * sumY) / denom;
+    if (slope < DRIFT_SLOPE_THRESHOLD) continue;
+
+    const observedDays  = xs[xs.length - 1];
+    const projection30  = Math.round(slope * 30);
+
+    insights.push({
+      type:     'DRIFT',
+      severity: 'warning',
+      route,
+      method,
+      message:  `\`${method} ${route}\` has been progressively degrading for ${observedDays} day${observedDays !== 1 ? 's' : ''}: +${slope.toFixed(1)}ms/day. 30-day projection: +${projection30}ms.`,
+      data: { slope_ms_per_day: slope, observed_days: observedDays, projection_30d_ms: projection30 },
+    });
+  }
+
+  return insights;
+}
+
 function computeHealthScore(db) {
   try {
     const { recent, baseline, activeRoutes, totalRoutes } = db.getSummary();

package/src/ui.html

@@ -1241,8 +1241,9 @@ function Insights({ setRoute, setParams }) {
 
   const types = [
     {id:'ALL',label:'All'},{id:'PERF',label:'Performance'},
-    {id:'ANOMALY',label:'Anomaly'},{id:'DEAD',label:'Dead'},
-    {id:'UNTRACKED',label:'Untracked'},{id:'OK',label:'OK'},
+    {id:'DRIFT',label:'Drift'},{id:'ANOMALY',label:'Anomaly'},
+    {id:'DEAD',label:'Dead'},{id:'UNTRACKED',label:'Untracked'},
+    {id:'OK',label:'OK'},
   ];
   const filtered = INSIGHTS.filter(i =>
     (typeFilter === 'ALL' || i.type === typeFilter) &&