@aforoai/metering 1.1.2 → 2.0.0

package/README.md

@@ -1,8 +1,8 @@
 # @aforoai/metering
 
-Track API usage from your Node service and send it to Aforo for billing. A buffered, batched, retrying client plus Express / Fastify / Koa middleware — `track()` returns immediately and events flush in the background, so metering never sits in your request path.
+Track API usage from your Node service and send it to Aforo for billing. A queued, batched, retrying client plus Express / Fastify / Koa middleware — `track()` returns immediately and one background sender ships events, so metering never sits in your request path and an ingestor outage does not lose usage.
 
-**Version:** 1.1.2 · Apache-2.0 · [Changelog](CHANGELOG.md) · [User guide](USER_GUIDE.md)
+**Version:** 2.0.0 · Apache-2.0 · [Changelog](CHANGELOG.md) · [User guide](USER_GUIDE.md)
 
 ## Install
 
@@ -10,13 +10,13 @@ Track API usage from your Node service and send it to Aforo for billing. A buffe
 npm i @aforoai/metering
 ```
 
-> **Install `1.1.2` or later. `1.0.0` on npm was built from an older copy of this code and lacks the fixes listed in the changelog.** If `1.1.2` is not on npm yet, install from source:
+> **Install `2.0.0` or later. `1.0.0` on npm was built from an older copy of this code and lacks the fixes listed in the changelog.** If `2.0.0` is not on npm yet, install from source:
 > ```bash
 > git clone https://github.com/aforoai/SDKs.git
 > cd SDKs/aforo-metering-sdks/node
 > npm install && npm run build
-> npm pack        # produces aforo-metering-1.1.2.tgz to install in your app
-> # then in your app: npm i /path/to/aforo-metering-1.1.2.tgz
+> npm pack        # produces aforo-metering-2.0.0.tgz to install in your app
+> # then in your app: npm i /path/to/aforo-metering-2.0.0.tgz
 > ```
 
 Requires Node >= 18 (uses the built-in `fetch`).
@@ -32,29 +32,39 @@ const aforo = new AforoClient({ apiKey: process.env.AFORO_API_KEY!, productType:
 
 await aforo.track({ customerId: 'cust_123', metricName: 'api_calls', quantity: 1 });
 
-// Flush remaining events before the process exits:
-await aforo.shutdown();
+// The SDK installs no signal handlers. Flush from your own shutdown path:
+process.once('SIGTERM', async () => {
+  await aforo.shutdown(); // sends what is queued, for at most shutdownTimeoutMs
+  process.exit(0);
+});
 ```
 
 Or meter every HTTP request with middleware — no per-route code:
 
 ```ts
+import { AforoClient } from '@aforoai/metering';
 import { expressMiddleware } from '@aforoai/metering/middleware/express';
 
+const aforo = new AforoClient({ apiKey: process.env.AFORO_API_KEY!, productType: 'API' });
+
 app.use(expressMiddleware({
-  apiKey: process.env.AFORO_API_KEY!,
-  customerId: (req) => req.user?.id ?? null,   // return null to skip metering this request
-  metricName: 'api_calls',                      // or (req, res) => string; must exist in your Aforo catalog
-  productType: 'API',                           // default: the client default ("API")
+  client: aforo,                                          // your client: you flush and shut it down
+  customerResolver: (req) => req.user?.aforoCustomerId,   // from identity your app authenticated
+  metricName: 'api_calls',                                // or (req, res) => string; must exist in your Aforo catalog
 }));
 ```
 
 The middleware hooks `res.on('finish')`, so it runs after the response is sent — zero added latency.
 
+- **Customer (required):** `customerResolver: (req) => string | null | undefined` returns the Aforo customer id from identity your app verified — a session, a JWT subject, an API-key lookup. Without it, or the explicit opt-in below, the middleware throws when you create it. When the resolver returns nothing for a request, that event is dropped with reason `invalid` and counted in `droppedCount`; the request itself is never blocked.
+- **`trustCustomerHeader: true`** reads the `X-Customer-Id` request header instead (or when the resolver returns nothing). That header is set by whoever calls your API, so turn this on only when a proxy you control sets it and strips any client copy. The caller's `X-Api-Key` header is never used — it is the end user's secret, not a customer id.
+- **Client:** pass `client` (an `AforoClient` you own) so your code can `flush()`, read `droppedCount` and `shutdown()` it. With `apiKey` instead, the middleware creates a client and exposes it as `middleware.client` (Fastify shuts its own client down in `onClose`).
 - **Metric:** `metricName` is a fixed name or a `(req, res) => string` resolver; the default is `"api_calls"` (exported as `DEFAULT_METRIC_NAME`). The metric must exist in your tenant's Aforo catalog: the ingestor rejects an event with an unknown `metricName` (the other events in the batch are still ingested), and the SDK reports it as a drop with reason `rejected`.
-- **Customer:** `customerId` is a fixed id or a `(req) => string | null` resolver; the default is `req.user.id` / `req.user.sub`, then the `X-Customer-Id` header. The caller's `X-Api-Key` header is never used — it is the end user's secret, not a customer id. Requests with no customer are not metered.
+- **Path:** `endpointPath` is normalized by default — the framework's route template when there is one (`req.route.path`, Koa's matched route, Fastify's route URL), otherwise dynamic segments collapse (`/users/123` → `/users/:id`, UUIDs and Mongo ids too). That keeps one label per route instead of one per id. `normalizePath: false` sends the raw path; a function `(path, req) => string` normalizes it your way.
 - **CORS preflights** (`OPTIONS`) are never metered, nor are requests whose quantity is `<= 0`.
-- **HTTP context:** each event carries top-level `endpointPath` (path without query string, max 512 chars), `httpMethod`, `statusCode` and `responseTimeMs`, plus `productType`.
+- **HTTP context:** each event carries top-level `endpointPath` (no query string, max 512 chars), `httpMethod`, `statusCode` and `responseTimeMs`, plus `productType`.
+
+Koa: `koaMiddleware({ client, customerResolver: (ctx) => ctx.state.user?.aforoCustomerId })`. Fastify: `fastify.register(fastifyPlugin, { client, customerResolver: (request) => request.user?.aforoCustomerId })`.
 
 ## Configuration
 
@@ -62,21 +72,27 @@ The middleware hooks `res.on('finish')`, so it runs after the response is sent
 
 | Option | Type | Default | What it does |
 |---|---|---|---|
-| `apiKey` | `string` | — (required) | Aforo API key, sent as `X-API-Key`. |
-| `baseUrl` | `string` | `https://api.aforo.ai` | Ingestor base URL. Events POST to `<baseUrl>/v1/ingest/batch`. |
+| `apiKey` | `string` | — (required) | Aforo API key, sent only as `X-API-Key`. Never logged and never shown by `inspect()` / `JSON.stringify`. |
+| `baseUrl` | `string` | `https://api.aforo.ai` | Ingestor base URL. Events POST to `<baseUrl>/v1/ingest/batch`. Must be `https://`; plain `http://` is accepted only for `localhost`, `127.0.0.1` and `::1`. |
+| `allowInsecureHttp` | `boolean` | `false` | Accept a plain `http://` `baseUrl` on another host (a private network you trust). |
 | `productType` | `string` | `"API"` | Top-level `productType` stamped on every event (required by the ingestor). One of `API`, `AGENTIC_API`, `AI_AGENT`, `MCP_SERVER`, `GRPC_API`, `GRAPHQL_API`, `WEBSOCKET_API`, `MQTT_BROKER`; trimmed and uppercased. |
-| `flushCount` | `number` | `50` | Buffered events that trigger a flush (and events per request; capped at 1000). |
-| `flushInterval` | `number` (ms) | `5000` | Background flush cadence. |
-| `maxQueueSize` | `number` | `10000` | Ring-buffer cap; oldest events drop on overflow. |
-| `onDrop` | `(events, reason) => void` | none | Called with events the SDK is about to lose. See [Dropped events](#dropped-events). |
-| `maxRetries` | `number` | `3` | Retries on 5xx, 408, 429 and network errors (exponential backoff; `Retry-After` honoured on 429). Other 4xx are not retried. |
-| `retryBaseMs` | `number` (ms) | `1000` | Base backoff delay. |
-| `timeout` | `number` (ms) | `10000` | Per-request timeout. |
-| `shutdownTimeoutMs` | `number` (ms) | `5000` | Max time `shutdown()` waits for a final flush. |
+| `flushCount` | `number` | `500` | Events per request (capped at 1000). Reaching it wakes the background sender. |
+| `flushInterval` | `number` (ms) | `5000` | The background sender also runs this often. |
+| `maxQueueSize` | `number` | `10000` | Queue capacity; the oldest event is dropped on overflow. |
+| `onDrop` | `(events, reason) => void` | none | Called with events the SDK loses for good. See [Dropped events](#dropped-events). |
+| `maxRetries` | `number` | `3` | Retries on network errors, timeouts, 408, 429 and 5xx, with full-jitter backoff. `Retry-After` (seconds or an HTTP date) is honoured, capped at 60 s. |
+| `retryBaseMs` | `number` (ms) | `500` | Backoff base: attempt *n* waits a random time up to `min(30 s, retryBaseMs · 2ⁿ)`. |
+| `timeout` | `number` (ms) | `10000` | Total deadline per request. |
+| `shutdownTimeoutMs` | `number` (ms) | `5000` | How long `shutdown()` keeps sending. Events still queued then are dropped with reason `shutdown`. |
+| `flushOnExit` | `boolean` | `true` | Send queued events when the process is about to exit on its own (`beforeExit`), within `shutdownTimeoutMs`. |
+
+### Delivery
+
+One background sender per client sends one request at a time; `track()` only queues. If the ingestor is unreachable, keeps answering 408/429/5xx after the retries, or answers 401/403 (wrong or revoked key — logged as an error), the batch goes back to the front of the queue with its idempotency keys and sending pauses (5 s, doubling to 5 min, randomized). New events keep queueing up to `maxQueueSize`. The first successful request resumes normal sending; the ingestor deduplicates the re-sent keys. A 413 splits the batch in half. Other 4xx drop the batch with reason `rejected`. Request bodies are plain JSON (no gzip: the ingestor does not decode compressed bodies).
 
 `track(event)` — `event: TrackEvent`: `customerId` (required, non-blank), `metricName` (required, non-blank), `quantity` (default 1, must be > 0), `productType` (overrides the client default for this event), `idempotencyKey` (a fresh random UUID v4 per event if omitted — pass your own key if you want the ingestor to deduplicate retries), `occurredAt` (ISO string or epoch ms; defaults to now), `executionStatus` (optional, see below), `endpointPath` / `httpMethod` / `statusCode` / `responseTimeMs` (optional HTTP context), `metadata` (string/number/boolean map).
 
-`track()` throws only when the client is shut down. It never throws for the content of an event — see [Dropped events](#dropped-events).
+`track()` never throws. After `shutdown()` an event is counted and reported with reason `closed`; an event the ingestor would reject is reported with reason `invalid` — see [Dropped events](#dropped-events).
 
 ### Execution status
 
@@ -94,10 +110,12 @@ Every event the SDK loses is counted in `client.droppedCount`, WARN-logged, and
 
 | `reason` | When |
 |---|---|
-| `overflow` | The ring buffer was full; the oldest event was evicted. |
-| `retry_exhausted` | A batch failed after all retries. |
-| `rejected` | The ingestor refused the batch with a non-retryable 4xx, or refused these events individually inside a batch it otherwise accepted. |
-| `invalid` | The event failed a client-side check at `track()` and was never buffered or sent. |
+| `overflow` | The queue was full; the oldest event was evicted. |
+| `rejected` | The ingestor refused the batch with a non-retryable 4xx, refused these events individually inside a batch it otherwise accepted, or answered 413 to a single event. |
+| `invalid` | The event failed a client-side check at `track()`, or a middleware `customerResolver` returned no customer. It was never queued or sent. |
+| `shutdown` | Still queued when `shutdownTimeoutMs` ran out. |
+| `closed` | `track()` was called after `shutdown()`. |
+| `retry_exhausted` | Not produced by 2.x (kept in the type for compatibility): an outage requeues the batch instead of dropping it. |
 
 `invalid` covers what the ingestor would reject for any deployment: blank `customerId` / `metricName`, `quantity <= 0`, a `quantity` with more than 14 integer digits or 6 decimal places, a malformed `occurredAt`, and fields over the server's size limit (`customerId` 64, `metricName` 255, `idempotencyKey` 255, `productType` 20, `endpointPath` 512, `httpMethod` 16). Nothing you pass to `track()` or set in the middleware options is truncated or rounded. The one exception is what the middlewares read off the request: a path over 512 characters or a method over 16 is cut to the limit and the event is still sent (one WARN per label). The WARN names the field, the limit and the value; it is logged for the first invalid event and then every 1000th. Limits the server makes configurable (event age, clock skew, metadata size) are not checked client-side.
 

package/dist/cjs/client.d.ts

@@ -1,38 +1,28 @@
-import { AforoOptions, TrackEvent, FlushResult } from './types.js';
+import { AforoOptions, TrackEvent, ResolvedEvent, FlushResult } from './types.js';
+/** Package version, sent in User-Agent. Keep in step with package.json. */
+export declare const SDK_VERSION = "2.0.0";
 /**
  * Aforo metering client.
  *
- * Enqueues usage events into a ring buffer, flushes them in batches
- * to the Aforo ingestor service via HTTP. Non-blocking — `track()`
- * returns immediately, flushing happens in the background.
+ * `track()` validates the event and puts it on a bounded queue; one background
+ * flusher sends batches to the ingestor. If the ingestor is down, batches go
+ * back on the queue (same idempotency keys) and are sent when it recovers.
  *
  * ```typescript
- * const client = new AforoClient({ apiKey: 'your-key', productType: 'API' });
+ * const client = new AforoClient({ apiKey: process.env.AFORO_API_KEY!, productType: 'API' });
  * await client.track({ customerId: 'cust_1', metricName: 'api_calls', quantity: 1 });
- * // On shutdown:
- * await client.shutdown();
+ * // The SDK installs no signal handlers. Flush from your own:
+ * process.once('SIGTERM', async () => { await client.shutdown(); process.exit(0); });
  * ```
  */
 export declare class AforoClient {
-    private readonly buffer;
-    private readonly transport;
-    private readonly flushCount;
-    private readonly flushInterval;
-    private readonly shutdownTimeoutMs;
+    private readonly core;
+    private readonly sendHeartbeat;
     private readonly productType;
-    private readonly onDrop?;
-    private dropped;
-    private overflowDrops;
-    private invalidDrops;
-    private flushTimer;
-    private flushing;
-    private closed;
-    private pendingFlush;
     private heartbeatTimer;
     private activeSessionId;
     private sessionStartedAt;
     private sessionProductType;
-    private readonly signalHandler;
     constructor(options: AforoOptions);
     /**
      * Start a session and emit `system.session.heartbeat` events: one now, then
@@ -56,47 +46,39 @@ export declare class AforoClient {
     private stopHeartbeatTimer;
     private emitSessionHeartbeat;
     /**
-     * Enqueue a usage event for batched delivery.
-     * Returns immediately — does not await HTTP.
-     * Triggers a flush if the buffer reaches flushCount.
+     * Queue a usage event. Returns at once — it never waits on HTTP and never
+     * starts a request (the background flusher sends batches).
      *
-     * Throws only when the client is shut down. An event the ingestor would
-     * reject — a blank or over-long `customerId` / `metricName` /
-     * `idempotencyKey`, a `quantity` that is not positive or carries more than
-     * 14 integer digits / 6 decimal places, an `occurredAt` that is not an
-     * ISO-8601 instant, or any other capped field that is too long — is NOT
-     * buffered and NOT sent. It is counted in `droppedCount`, WARN-logged with
-     * the field, the limit and the offending value, and passed to the opt-in
-     * `onDrop` hook with reason `'invalid'`. Limits the server makes
-     * configurable (event age, clock skew, metadata size) are left to the
-     * server. See `limits.ts` for the limits and where each one comes from.
+     * Never throws. An event the ingestor would reject — a blank or over-long
+     * `customerId` / `metricName` / `idempotencyKey`, a `quantity` that is not
+     * positive or carries more than 14 integer digits / 6 decimal places, an
+     * `occurredAt` that is not an ISO-8601 instant, or any other capped field
+     * that is too long — is NOT queued and NOT sent. It is counted in
+     * `droppedCount`, WARN-logged with the field and the limit, and passed to
+     * the opt-in `onDrop` hook with reason `'invalid'`. After `shutdown()` the
+     * event is counted and reported with reason `'closed'`.
      */
     track(event: TrackEvent): Promise<void>;
-    /** Buffer an event; surface the evicted-oldest event if the push overflowed. */
-    private enqueue;
+    /** @internal Count and report an event a middleware could not build (reason 'invalid'). */
+    reportInvalid(event: ResolvedEvent, detail: string): void;
     /**
-     * Account for permanently lost events: bump the counter, WARN-log, and
-     * invoke the opt-in onDrop hook. Overflow logs are throttled (first, then
-     * every 1000th eviction) so sustained overflow can't storm the log;
-     * failed-batch drops log every time (bounded by flush cadence).
-     */
-    private recordDrop;
-    /**
-     * Force-flush all buffered events to the ingestor.
-     * Safe to call concurrently — only one flush runs at a time.
+     * Send everything queued now and wait for it. Runs on the single flusher —
+     * never a second concurrent request. While the ingestor is down this makes
+     * one attempt; unsent events stay queued.
      */
     flush(): Promise<FlushResult>;
-    private doFlush;
     /**
-     * Flush remaining events and stop the client.
-     * After shutdown, track() will throw.
+     * Stop accepting events and send what is queued, for at most
+     * `shutdownTimeoutMs`. Events still queued at the deadline are counted and
+     * reported through onDrop with reason 'shutdown'. Safe to call more than once.
      */
     shutdown(): Promise<void>;
-    /** Number of events currently buffered. */
+    /** Number of events currently queued. */
     get bufferedCount(): number;
-    /** Total events permanently dropped (overflow, failed batches, server-rejected and invalid events) since creation. */
+    /** Total events permanently dropped (every DropReason) since creation. */
     get droppedCount(): number;
     /** Whether the client has been shut down. */
     get isShutdown(): boolean;
+    toJSON(): Record<string, unknown>;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAiB,WAAW,EAAc,MAAM,YAAY,CAAC;AAuB9F;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAwD;IAIhF,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAAK;IAEzB,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAqC;IAGzD,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,kBAAkB,CAAwC;IAIlE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAa;gBAE/B,OAAO,EAAE,YAAY;IAuCjC;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,GAAE,MAAqC,GAAG,IAAI;IAezF;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,oBAAoB;IAkC5B;;;;;;;;;;;;;;;OAeG;IACG,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA8D7C,gFAAgF;IAChF,OAAO,CAAC,OAAO;IAOf;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAqClB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;YAgBrB,OAAO;IAsCrB;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAmC/B,2CAA2C;IAC3C,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,sHAAsH;IACtH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,6CAA6C;IAC7C,IAAI,UAAU,IAAI,OAAO,CAExB;CACF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAc,MAAM,YAAY,CAAC;AAK9F,2EAA2E;AAC3E,eAAO,MAAM,WAAW,UAAU,CAAC;AAsCnC;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA+B;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAGrC,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,kBAAkB,CAAwC;gBAEtD,OAAO,EAAE,YAAY;IAgCjC;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,GAAE,MAAqC,GAAG,IAAI;IAezF;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,oBAAoB;IAkC5B;;;;;;;;;;;;OAYG;IACG,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAoD7C,2FAA2F;IAC3F,aAAa,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAIzD;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;IAKnC;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B,yCAAyC;IACzC,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,0EAA0E;IAC1E,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,6CAA6C;IAC7C,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAOlC"}