@aforoai/metering 1.0.0 → 1.1.2

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 drop-in 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 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.
 
-**Version:** 1.0.0 · Apache-2.0 · [Changelog](CHANGELOG.md) · [User guide](USER_GUIDE.md)
+**Version:** 1.1.2 · 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
 ```
 
-> **Not yet on the public npm registry.** Until it's published, install from source:
+> **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:
 > ```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.0.0.tgz to install in your app
-> # then in your app: npm i /path/to/aforo-metering-1.0.0.tgz
+> 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
 > ```
 
 Requires Node >= 18 (uses the built-in `fetch`).
@@ -51,7 +51,7 @@ app.use(expressMiddleware({
 
 The middleware hooks `res.on('finish')`, so it runs after the response is sent — zero added latency.
 
-- **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 unknown `metricName`, and because it validates a batch as a whole, one rejected event fails every event in that batch.
+- **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.
 - **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`.
@@ -68,12 +68,40 @@ The middleware hooks `res.on('finish')`, so it runs after the response is sent
 | `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. |
-| `maxRetries` | `number` | `3` | Retries on 5xx/timeout (exponential backoff). |
+| `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. |
 
-`track(event)` — `event: TrackEvent`: `customerId` (required, non-blank), `metricName` (required, non-blank), `quantity` (default 1, must be > 0 — otherwise `track()` throws), `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), `metadata` (string/number/boolean map).
+`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).
+
+### Execution status
+
+`executionStatus` feeds outcome-based pricing: an OUTCOME_BASED rate plan bills each event at the weight set for its status. Events without a status bill at full price.
+
+```ts
+await aforo.track({ customerId: 'cust_123', metricName: 'api_calls', executionStatus: 'TIMEOUT' });
+```
+
+The value is trimmed and upper-cased; blank is treated as absent. Accepted: `SUCCESS`, `PARTIAL`, `TIMEOUT`, `ERROR`, `VALIDATION_FAILED`, `FAILED`, `FAILURE`, `CANCELLED`, `PENDING`, `BLOCKED`, `HITL_REQUIRED`. Any other value (or one longer than 20 characters) is WARN-logged and left off the event; the event is still sent.
+
+### Dropped events
+
+Every event the SDK loses is counted in `client.droppedCount`, WARN-logged, and passed to the opt-in `onDrop(events, reason)` hook. Events keep their idempotency keys, so re-submitting them with `track()` is dedup-safe.
+
+| `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. |
+
+`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.
+
+When a 2xx response reports failures without saying which events, the count is added to `droppedCount` and logged, and `onDrop` is not called. A failed session heartbeat is not a drop.
 
 ### Sessions
 
@@ -85,4 +113,4 @@ Step-by-step from install to a verified event in Aforo: see the **[User guide](U
 
 ## What this doesn't cover
 
-This SDK only *emits* usage. Pricing, rate plans, and which `metricName`s are billable are configured in the Aforo console — this package does not create or validate them. A `metricName` that isn't defined in your tenant is **rejected** by the ingestor — and fails the whole batch it travels in — so define the metric before sending it.
+This SDK only *emits* usage. Pricing, rate plans, and which `metricName`s are billable are configured in the Aforo console — this package does not create or validate them. An event whose `metricName` isn't defined in your tenant is **rejected** by the ingestor, so define the metric before sending it.

package/dist/cjs/buffer.d.ts

@@ -1,4 +1,4 @@
-import { ResolvedEvent } from './types';
+import { ResolvedEvent } from './types.js';
 /**
  * Bounded ring buffer for usage events.
  * Thread-safe for Node.js single-threaded event loop.
@@ -13,6 +13,12 @@ export declare class RingBuffer {
     constructor(capacity?: number);
     /** Add an event to the buffer. Returns true if added, false if overflow (oldest dropped). */
     push(event: ResolvedEvent): boolean;
+    /**
+     * Add an event to the buffer. On overflow, returns the evicted OLDEST
+     * event so the caller can surface the drop; returns null when no
+     * eviction occurred.
+     */
+    pushEvict(event: ResolvedEvent): ResolvedEvent | null;
     /** Drain all events from the buffer. Returns a new array and clears the buffer. */
     drain(): ResolvedEvent[];
     /** Drain up to `max` events from the front of the buffer. */

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

@@ -1 +1 @@
-{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../src/buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,KAAK,CAAK;gBAEN,QAAQ,GAAE,MAAe;IAMrC,6FAA6F;IAC7F,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO;IAiBnC,mFAAmF;IACnF,KAAK,IAAI,aAAa,EAAE;IAgBxB,6DAA6D;IAC7D,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,EAAE;IAgBvC,8CAA8C;IAC9C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mCAAmC;IACnC,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,yCAAyC;IACzC,IAAI,MAAM,IAAI,OAAO,CAEpB;CACF"}
+{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../src/buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,KAAK,CAAK;gBAEN,QAAQ,GAAE,MAAe;IAMrC,6FAA6F;IAC7F,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO;IAInC;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,GAAG,IAAI;IAiBrD,mFAAmF;IACnF,KAAK,IAAI,aAAa,EAAE;IAgBxB,6DAA6D;IAC7D,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,EAAE;IAgBvC,8CAA8C;IAC9C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mCAAmC;IACnC,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,yCAAyC;IACzC,IAAI,MAAM,IAAI,OAAO,CAEpB;CACF"}

package/dist/cjs/buffer.js

@@ -18,17 +18,25 @@ class RingBuffer {
     }
     /** Add an event to the buffer. Returns true if added, false if overflow (oldest dropped). */
     push(event) {
-        let overflow = false;
+        return this.pushEvict(event) === null;
+    }
+    /**
+     * Add an event to the buffer. On overflow, returns the evicted OLDEST
+     * event so the caller can surface the drop; returns null when no
+     * eviction occurred.
+     */
+    pushEvict(event) {
+        let evicted = null;
         if (this.count === this.capacity) {
             // Buffer full — drop oldest (advance head)
+            evicted = this.items[this.head];
             this.head = (this.head + 1) % this.capacity;
             this.count--;
-            overflow = true;
         }
         this.items[this.tail] = event;
         this.tail = (this.tail + 1) % this.capacity;
         this.count++;
-        return !overflow;
+        return evicted;
     }
     /** Drain all events from the buffer. Returns a new array and clears the buffer. */
     drain() {

package/dist/cjs/buffer.js.map

@@ -1 +1 @@
-{"version":3,"file":"buffer.js","sourceRoot":"","sources":["../../src/buffer.ts"],"names":[],"mappings":";;;AAEA;;;;GAIG;AACH,MAAa,UAAU;IAOrB,YAAY,WAAmB,KAAM;QAJ7B,SAAI,GAAG,CAAC,CAAC;QACT,SAAI,GAAG,CAAC,CAAC;QACT,UAAK,GAAG,CAAC,CAAC;QAGhB,IAAI,QAAQ,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,6FAA6F;IAC7F,IAAI,CAAC,KAAoB;QACvB,IAAI,QAAQ,GAAG,KAAK,CAAC;QAErB,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;YACjC,2CAA2C;YAC3C,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;QAEb,OAAO,CAAC,QAAQ,CAAC;IACnB,CAAC;IAED,mFAAmF;IACnF,KAAK;QACH,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAEhC,MAAM,MAAM,GAAoB,EAAE,CAAC;QACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC5C,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/B,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QAEf,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,6DAA6D;IAC7D,SAAS,CAAC,GAAW;QACnB,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;YAAE,OAAO,EAAE,CAAC;QAE5C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,MAAM,GAAoB,EAAE,CAAC;QACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC5C,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/B,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/C,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC;QAEnB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,8CAA8C;IAC9C,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,mCAAmC;IACnC,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,yCAAyC;IACzC,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,QAAQ,CAAC;IACtC,CAAC;CACF;AA/ED,gCA+EC"}
+{"version":3,"file":"buffer.js","sourceRoot":"","sources":["../../src/buffer.ts"],"names":[],"mappings":"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"}

package/dist/cjs/client.d.ts

@@ -1,4 +1,4 @@
-import { AforoOptions, TrackEvent, FlushResult } from './types';
+import { AforoOptions, TrackEvent, FlushResult } from './types.js';
 /**
  * Aforo metering client.
  *
@@ -20,6 +20,10 @@ export declare class AforoClient {
     private readonly flushInterval;
     private readonly shutdownTimeoutMs;
     private readonly productType;
+    private readonly onDrop?;
+    private dropped;
+    private overflowDrops;
+    private invalidDrops;
     private flushTimer;
     private flushing;
     private closed;
@@ -28,6 +32,7 @@ export declare class AforoClient {
     private activeSessionId;
     private sessionStartedAt;
     private sessionProductType;
+    private readonly signalHandler;
     constructor(options: AforoOptions);
     /**
      * Start a session and emit `system.session.heartbeat` events: one now, then
@@ -55,18 +60,27 @@ export declare class AforoClient {
      * Returns immediately — does not await HTTP.
      * Triggers a flush if the buffer reaches flushCount.
      *
-     * Throws if the event breaks any constraint the ingestor enforces — 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. Limits the server makes configurable (event
-     * age, clock skew, metadata size) are left to the server, so the SDK can
-     * never refuse usage a given deployment would accept. Such an event is rejected by the ingestor and never billed,
-     * and because flushing happens in the background nobody would see that
-     * rejection — so it is reported here instead, and never enters the buffer.
-     * See `limits.ts` for the limits and where each one comes from.
+     * 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.
      */
     track(event: TrackEvent): Promise<void>;
+    /** Buffer an event; surface the evicted-oldest event if the push overflowed. */
+    private enqueue;
+    /**
+     * 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.
@@ -80,6 +94,8 @@ export declare class AforoClient {
     shutdown(): Promise<void>;
     /** Number of events currently buffered. */
     get bufferedCount(): number;
+    /** Total events permanently dropped (overflow, failed batches, server-rejected and invalid events) since creation. */
+    get droppedCount(): number;
     /** Whether the client has been shut down. */
     get isShutdown(): boolean;
 }

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,EAAE,MAAM,SAAS,CAAC;AAuB/E;;;;;;;;;;;;;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;IAErC,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;gBAEtD,OAAO,EAAE,YAAY;IAsCjC;;;;;;;;;;;;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;IAgC5B;;;;;;;;;;;;;;;OAeG;IACG,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA+D7C;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;YAgBrB,OAAO;IAgBrB;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB/B,2CAA2C;IAC3C,IAAI,aAAa,IAAI,MAAM,CAE1B;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,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"}

package/dist/cjs/client.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AforoClient = void 0;
-const buffer_1 = require("./buffer");
-const transport_1 = require("./transport");
-const idempotency_1 = require("./idempotency");
-const limits_1 = require("./limits");
+const buffer_js_1 = require("./buffer.js");
+const transport_js_1 = require("./transport.js");
+const idempotency_js_1 = require("./idempotency.js");
+const limits_js_1 = require("./limits.js");
 const DEFAULT_BASE_URL = 'https://api.aforo.ai';
 const DEFAULT_PRODUCT_TYPE = 'API';
 const DEFAULT_SESSION_PRODUCT_TYPE = 'AI_AGENT';
@@ -37,6 +37,11 @@ const DEFAULT_SHUTDOWN_TIMEOUT = 5000;
  */
 class AforoClient {
     constructor(options) {
+        // Drop accounting — events permanently lost (overflow eviction, failed
+        // batch, or an event that failed client-side validation)
+        this.dropped = 0;
+        this.overflowDrops = 0;
+        this.invalidDrops = 0;
         this.flushTimer = null;
         this.flushing = false;
         this.closed = false;
@@ -52,8 +57,9 @@ class AforoClient {
         this.productType = normalizeProductType(options.productType) ?? DEFAULT_PRODUCT_TYPE;
         this.flushInterval = options.flushInterval ?? DEFAULT_FLUSH_INTERVAL;
         this.shutdownTimeoutMs = options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT;
-        this.buffer = new buffer_1.RingBuffer(options.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE);
-        this.transport = new transport_1.Transport({
+        this.onDrop = options.onDrop;
+        this.buffer = new buffer_js_1.RingBuffer(options.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE);
+        this.transport = new transport_js_1.Transport({
             baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
             apiKey: options.apiKey,
             timeout: options.timeout ?? DEFAULT_TIMEOUT,
@@ -68,12 +74,12 @@ class AforoClient {
         if (this.flushTimer && typeof this.flushTimer === 'object' && 'unref' in this.flushTimer) {
             this.flushTimer.unref();
         }
-        // Register graceful shutdown handlers
-        const shutdownHandler = () => {
+        // Register graceful shutdown handlers (deregistered in shutdown())
+        this.signalHandler = () => {
             this.shutdown().catch(() => { });
         };
-        process.once('SIGTERM', shutdownHandler);
-        process.once('SIGINT', shutdownHandler);
+        process.once('SIGTERM', this.signalHandler);
+        process.once('SIGINT', this.signalHandler);
     }
     // ─── Session lifecycle with heartbeat ─────────────────────────────
     /**
@@ -145,6 +151,8 @@ class AforoClient {
                 sdkLanguage: 'node',
             },
         };
+        // Sent alone and outside the usage buffer; a failed heartbeat is not a
+        // usage drop, so it is never counted in droppedCount or handed to onDrop.
         return this.transport.sendSingleBestEffort(heartbeat).then(() => undefined, () => undefined);
     }
     // ─── Event tracking ──────────────────────────────────────────────
@@ -153,54 +161,35 @@ class AforoClient {
      * Returns immediately — does not await HTTP.
      * Triggers a flush if the buffer reaches flushCount.
      *
-     * Throws if the event breaks any constraint the ingestor enforces — 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. Limits the server makes configurable (event
-     * age, clock skew, metadata size) are left to the server, so the SDK can
-     * never refuse usage a given deployment would accept. Such an event is rejected by the ingestor and never billed,
-     * and because flushing happens in the background nobody would see that
-     * rejection — so it is reported here instead, and never enters the buffer.
-     * See `limits.ts` for the limits and where each one comes from.
+     * 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.
      */
     async track(event) {
         if (this.closed) {
             throw new Error('AforoClient is shut down — cannot track new events');
         }
-        if (event.customerId === undefined || event.customerId === null || !String(event.customerId).trim()) {
-            throw new Error('customerId is required');
-        }
-        if (event.metricName === undefined || event.metricName === null || !String(event.metricName).trim()) {
-            throw new Error('metricName is required');
-        }
+        // A missing event object is reported as an invalid event, not a TypeError.
+        event = (event ?? {});
         const occurredAt = resolveOccurredAt(event.occurredAt);
         const quantity = event.quantity ?? 1;
-        if (typeof quantity !== 'number' || !Number.isFinite(quantity) || quantity <= 0) {
-            throw new Error('quantity must be a positive number (> 0)');
-        }
         const productType = normalizeProductType(event.productType) ?? this.productType;
         // Minted once, here, when the event is enqueued — never at flush/retry
         // time, so a retried batch carries the same keys and the ingestor
         // deduplicates it. A caller-supplied key is passed through verbatim;
-        // otherwise each event gets its own random UUID. A deterministic hash of
-        // the event fields would make two genuinely distinct events in the same
-        // millisecond collide, and the ingestor would silently drop the second.
-        // Minted before the limit check so an over-long caller-supplied key is
-        // reported here rather than silently dropped by the server later.
-        const idempotencyKey = event.idempotencyKey ?? (0, idempotency_1.generateRandomKey)();
-        const violation = (0, limits_1.describeLimitViolation)({
-            customerId: event.customerId,
-            metricName: event.metricName,
-            quantity,
-            idempotencyKey,
-            occurredAt,
-            productType,
-            endpointPath: event.endpointPath,
-            httpMethod: event.httpMethod,
-        });
-        if (violation)
-            throw new Error(violation);
+        // otherwise each event gets its own random UUID (no caller key = dedup
+        // opt-out). A deterministic hash of the event fields would make two
+        // genuinely distinct events in the same millisecond collide, and the
+        // ingestor would silently drop the second. Minted before the validity
+        // check so a dropped event reaches onDrop with its key.
+        const idempotencyKey = event.idempotencyKey ?? (0, idempotency_js_1.generateRandomKey)();
         const resolved = {
             customerId: event.customerId,
             metricName: event.metricName,
@@ -214,12 +203,76 @@ class AforoClient {
             ...(event.statusCode !== undefined ? { statusCode: event.statusCode } : {}),
             ...(event.responseTimeMs !== undefined ? { responseTimeMs: event.responseTimeMs } : {}),
         };
-        this.buffer.push(resolved);
+        const executionStatus = normalizeExecutionStatus(event.executionStatus);
+        if (executionStatus) {
+            if (CANONICAL_EXECUTION_STATUSES.has(executionStatus)) {
+                resolved.executionStatus = executionStatus;
+            }
+            else {
+                // The ingestor rejects an event carrying an unknown status, so an
+                // unknown value is reported and the field omitted (the event still
+                // bills, at full weight) instead of losing the event.
+                warnUnknownExecutionStatus(executionStatus);
+            }
+        }
+        const violation = describeInvalidEvent(event, resolved);
+        if (violation) {
+            // Not buffered, not sent, never thrown: an un-awaited rejected track()
+            // would crash the process on the hot path. Same shape as every other drop.
+            this.recordDrop([resolved], 'invalid', violation);
+            return;
+        }
+        this.enqueue(resolved);
         // Trigger flush if buffer threshold reached
         if (this.buffer.size >= this.flushCount) {
             this.flush().catch(() => { });
         }
     }
+    /** Buffer an event; surface the evicted-oldest event if the push overflowed. */
+    enqueue(resolved) {
+        const evicted = this.buffer.pushEvict(resolved);
+        if (evicted) {
+            this.recordDrop([evicted], 'overflow');
+        }
+    }
+    /**
+     * 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).
+     */
+    recordDrop(events, reason, detail) {
+        if (events.length === 0)
+            return;
+        this.dropped += events.length;
+        if (reason === 'invalid') {
+            // Throttled like overflow: a tight loop of bad events can't storm the log.
+            this.invalidDrops += events.length;
+            if (this.invalidDrops === 1 || this.invalidDrops % 1000 === 0) {
+                console.warn(`[aforo] Invalid event dropped — ${detail ?? 'failed validation'} ` +
+                    `(${this.invalidDrops} invalid, ${this.dropped} total dropped). It was not sent.`);
+            }
+        }
+        else if (reason === 'overflow') {
+            this.overflowDrops += events.length;
+            if (this.overflowDrops === 1 || this.overflowDrops % 1000 === 0) {
+                console.warn(`[aforo] Buffer overflow: oldest event dropped (${this.dropped} total dropped). ` +
+                    `Consider raising maxQueueSize or checking ingest connectivity.`);
+            }
+        }
+        else {
+            console.warn(`[aforo] Dropped ${events.length} event(s) — ${reason}` +
+                `${detail ? `: ${detail}` : ''} (${this.dropped} total dropped).`);
+        }
+        if (this.onDrop) {
+            try {
+                this.onDrop(events, reason);
+            }
+            catch {
+                // A hook bug must never break tracking/flushing.
+            }
+        }
+    }
     /**
      * Force-flush all buffered events to the ingestor.
      * Safe to call concurrently — only one flush runs at a time.
@@ -248,6 +301,27 @@ class AforoClient {
             const result = await this.transport.send(batch);
             totalSent += result.sent;
             totalFailed += result.failed;
+            if (result.failed > 0) {
+                // The batch was already drained from the buffer — without this it
+                // vanishes silently. Surface it (counter + WARN + opt-in hook).
+                // A partially accepted batch drops only the events the server
+                // rejected: by index when the response names them; otherwise they are
+                // counted and logged but not handed to onDrop (which ones is unknown).
+                if (result.sent > 0 || result.rejected) {
+                    if (result.rejected) {
+                        const lost = result.rejected.map((r) => batch[r.index]).filter(Boolean);
+                        this.recordDrop(lost, 'rejected', result.message);
+                    }
+                    else {
+                        this.dropped += result.failed;
+                        console.warn(`[aforo] Ingestor rejected ${result.failed} of ${batch.length} event(s) in a batch` +
+                            `${result.message ? `: ${result.message}` : ''} (${this.dropped} total dropped).`);
+                    }
+                }
+                else {
+                    this.recordDrop(batch, result.reason ?? 'retry_exhausted', result.message);
+                }
+            }
         }
         return { sent: totalSent, failed: totalFailed };
     }
@@ -259,6 +333,10 @@ class AforoClient {
         if (this.closed)
             return;
         this.closed = true;
+        // Deregister signal handlers so repeated create/shutdown cycles don't
+        // accumulate process listeners (safe if already fired — once() removed it).
+        process.removeListener('SIGTERM', this.signalHandler);
+        process.removeListener('SIGINT', this.signalHandler);
         // Stop session heartbeats
         this.stopHeartbeatTimer();
         // Clear periodic flush timer
@@ -266,16 +344,32 @@ class AforoClient {
             clearInterval(this.flushTimer);
             this.flushTimer = null;
         }
-        // Flush with timeout
-        await Promise.race([
-            this.flush(),
-            new Promise((resolve) => setTimeout(resolve, this.shutdownTimeoutMs)),
-        ]);
+        // Flush with timeout. The escape-hatch timer MUST be cleared once the
+        // race settles — left dangling it holds the event loop open for up to
+        // shutdownTimeoutMs after a clean shutdown, delaying process exit in
+        // short-lived producers (CLIs, jobs, serverless handlers).
+        let escapeTimer;
+        try {
+            await Promise.race([
+                this.flush(),
+                new Promise((resolve) => {
+                    escapeTimer = setTimeout(resolve, this.shutdownTimeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (escapeTimer)
+                clearTimeout(escapeTimer);
+        }
     }
     /** Number of events currently buffered. */
     get bufferedCount() {
         return this.buffer.size;
     }
+    /** Total events permanently dropped (overflow, failed batches, server-rejected and invalid events) since creation. */
+    get droppedCount() {
+        return this.dropped;
+    }
     /** Whether the client has been shut down. */
     get isShutdown() {
         return this.closed;
@@ -288,14 +382,77 @@ function normalizeProductType(value) {
     const trimmed = String(value).trim();
     return trimmed ? trimmed.toUpperCase() : undefined;
 }
+/** Shorten an offending value for a log line. */
+function clip(value) {
+    return String(value).slice(0, 80);
+}
+/**
+ * First reason the ingestor would reject this event, or null when it is
+ * acceptable. Required fields and quantity sign first, then the size limits.
+ */
+function describeInvalidEvent(event, resolved) {
+    for (const field of ['customerId', 'metricName']) {
+        const value = event?.[field];
+        if (value === undefined || value === null || !String(value).trim()) {
+            return `${field} is required (got "${clip(value)}")`;
+        }
+    }
+    const quantity = resolved.quantity;
+    if (typeof quantity !== 'number' || !Number.isFinite(quantity) || quantity <= 0) {
+        return `quantity must be a positive number (> 0), got "${clip(quantity)}"`;
+    }
+    if (typeof resolved.occurredAt !== 'string') {
+        return `occurredAt must be an ISO-8601 string or epoch milliseconds, got "${clip(resolved.occurredAt)}"`;
+    }
+    return (0, limits_js_1.describeLimitViolation)({
+        customerId: resolved.customerId,
+        metricName: resolved.metricName,
+        quantity,
+        idempotencyKey: resolved.idempotencyKey,
+        occurredAt: resolved.occurredAt,
+        productType: resolved.productType,
+        endpointPath: resolved.endpointPath,
+        httpMethod: resolved.httpMethod,
+    });
+}
 function randomSuffix() {
     return Math.random().toString(36).slice(2, 10);
 }
 function resolveOccurredAt(value) {
     if (!value)
         return new Date().toISOString();
-    if (typeof value === 'number')
-        return new Date(value).toISOString();
+    if (typeof value === 'number') {
+        const date = new Date(value);
+        // An out-of-range epoch must not throw from track(); it is reported as invalid.
+        return Number.isNaN(date.getTime()) ? String(value) : date.toISOString();
+    }
     return value;
 }
+/**
+ * Statuses the ingestor accepts (contract/ingest-contract.json, max 20 chars).
+ * Anything else would make it reject the event.
+ */
+const CANONICAL_EXECUTION_STATUSES = new Set([
+    'SUCCESS', 'PARTIAL', 'TIMEOUT', 'ERROR', 'VALIDATION_FAILED', 'FAILED',
+    'FAILURE', 'CANCELLED', 'PENDING', 'BLOCKED', 'HITL_REQUIRED',
+]);
+// Warn once per distinct bad value (bounded) so a misconfigured static status
+// can't storm the log on every request.
+const MAX_WARNED_STATUSES = 100;
+const warnedStatuses = new Set();
+function warnUnknownExecutionStatus(value) {
+    if (warnedStatuses.has(value))
+        return;
+    if (warnedStatuses.size < MAX_WARNED_STATUSES)
+        warnedStatuses.add(value);
+    console.warn(`[aforo] Unknown executionStatus "${value.slice(0, 40)}" — field omitted from the event. ` +
+        `Expected one of: ${[...CANONICAL_EXECUTION_STATUSES].join(', ')}.`);
+}
+/** Trim + upper-case; blank/absent → undefined (key omitted from the wire body). */
+function normalizeExecutionStatus(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed.toUpperCase() : undefined;
+}
 //# sourceMappingURL=client.js.map