apiforgejs 1.0.3 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apiforgejs",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "description": "API observability & intelligence SDK for Express.js — local-first, privacy-first",
   "main": "src/index.js",
   "keywords": [

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

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;