@aforoai/ws-metering 1.0.0 → 1.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 Meter WebSocket connections into Aforo — open, close, bytes, frame counts, and duration — by wrapping a `ws` server, or by tracking any connection that exposes the standard WebSocket event surface (Fastify-WebSocket, Socket.io, Deno, Bun).
 
-**Version:** 1.0.0 · Apache-2.0 · [Changelog](CHANGELOG.md) · [User guide](USER_GUIDE.md)
+**Version:** 1.2.1 · Apache-2.0 · [Changelog](CHANGELOG.md) · [User guide](USER_GUIDE.md)
 
 ## Install
 
@@ -12,7 +12,7 @@ Intended public install (once published):
 npm i @aforoai/ws-metering ws
 ```
 
-> **Not yet on the public npm registry — install from source for now.** `ws` (`^8`) is an **optional** peer dependency — needed only if you use `wrapServer`. `trackConnection` works with any compatible socket.
+> **Install `1.2.1` 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.2.1` is not on npm yet, install from source with the steps below. `ws` (`^8`) is an **optional** peer dependency — needed only if you use `wrapServer`. `trackConnection` works with any compatible socket.
 
 ```bash
 # from the SDKs repo root
@@ -70,7 +70,8 @@ By default the SDK emits two events per connection — `CONNECTION_OPENED` on co
 | `perFrameEvents` | `boolean` | `false` | Emit one event per frame (each direction). Off → frames are aggregated into the close event only. |
 | `flushCount` | `number` | `100` | Buffered events that trigger an immediate flush. Higher default than the base SDK — WS is high-volume. |
 | `flushIntervalMs` | `number` | `3000` | Max ms before a partial batch is flushed. |
-| `onError` | `(error: Error) => void` | logs to `console.error` | Called when a batch is dropped: after 3 attempts on network errors / 408 / 429 (honouring `Retry-After`) / 5xx, immediately on any other 4xx (not retried), and when a 202 reports per-event failures (`errors[].message`). |
+| `onError` | `(error: Error) => void` | logs to `console.error` | Called once per delivery problem: a batch dropped after 3 attempts (network errors / 408 / 429 honouring `Retry-After` / 5xx), a batch refused with any other 4xx (not retried; the message includes the ingestor's `errors[].message`), per-event failures reported in a 2xx response, and an unusable `executionStatus`. Exceptions it throws are swallowed. |
+| `onDrop` | `(events, reason) => void` | none | Receives events that were permanently dropped, with reason `invalid`, `rejected` or `retry_exhausted`. See [Dropped events](#dropped-events). |
 
 `wrapServer(wss, options)` / `trackConnection(ws, opts)` take the customer resolver:
 
@@ -84,7 +85,45 @@ By default the SDK emits two events per connection — `CONNECTION_OPENED` on co
 
 Close codes map to labels via `WS_CLOSE_REASONS` — `1000 → NORMAL_CLOSURE`, `1006 → ABNORMAL_CLOSURE`, `1009 → MESSAGE_TOO_BIG`, `4000 → IDLE_TIMEOUT`, etc. A socket `error` emits a synthetic `CONNECTION_CLOSED` with `wsCloseReason: INTERNAL_ERROR` and `metadata.event: CONNECTION_ERROR`.
 
-Exported symbols: `AforoWsBilling` (with `wrapServer` / `trackConnection` / `shutdown`), the `WS_CLOSE_REASONS` map, and the `AforoWsConfig` / `WrapServerOptions` types.
+Exported symbols: `AforoWsBilling` (with `wrapServer` / `trackConnection` / `shutdown` / `droppedCount`), the `WS_CLOSE_REASONS` map, `DEFAULT_PRODUCT_TYPE`, and the `AforoWsConfig` / `WrapServerOptions` / `TrackConnectionOptions` / `WsUsageEvent` / `DropReason` types.
+
+## Execution status
+
+Outcome-based pricing bills each event at the weight set for its `executionStatus`; events without one bill at full price. The SDK trims and upper-cases the value and leaves the key out of the event when it is unset or blank. Accepted values: `SUCCESS`, `PARTIAL`, `TIMEOUT`, `ERROR`, `VALIDATION_FAILED`, `FAILED`, `FAILURE`, `CANCELLED`, `PENDING`, `BLOCKED`, `HITL_REQUIRED`. Any other value (or a Promise returned by an async resolver) is reported through `onError` and left off the event — the event itself is still sent — because the server would reject the event. Resolvers must be synchronous.
+
+`executionStatus` is the outcome of the **connection**: it is set on the closing event only — `CONNECTION_CLOSED`, and the synthetic close emitted on a socket error. `CONNECTION_OPENED` and per-frame `MESSAGE` events never carry it, so a status such as `ERROR` for an abnormal close doesn't make every frame bill at the `ERROR` weight. (This matches the Python SDK; Go and Java take a status per call.)
+
+WebSocket frames carry no success or failure signal, so the SDK never sets `executionStatus` on its own — not even for abnormal closes or socket errors. Pass it yourself, as a string or as a synchronous function called with the closing event:
+
+```typescript
+billing.wrapServer(wss, {
+  extractCustomerId: (req) => req.headers['x-customer-id'] as string,
+  // (event, req) => status | undefined
+  executionStatus: (event, req) =>
+    event.wsFrameType === 'CLOSE' && event.wsCloseReason !== 'NORMAL_CLOSURE' ? 'ERROR' : undefined,
+});
+
+billing.trackConnection(socket, { customerId: 'cust_42', executionStatus: 'SUCCESS' });
+```
+
+## Dropped events
+
+The SDK does not throw into your socket handlers for event content. An event that cannot be delivered is counted in `billing.droppedCount`, logged with `console.warn`, and passed to the optional `onDrop(events, reason)` hook. Events handed to the hook keep their `idempotencyKey`, so storing them and re-submitting later is dedup-safe. Exceptions thrown by the hook are swallowed.
+
+| Reason | When |
+|---|---|
+| `invalid` | The event failed a client-side check and was never buffered or sent: `customerId` longer than 64 characters or `productType` longer than 20 (every event of that connection is counted). Values are never truncated. The warning names the field, the limit and the value (first 80 characters); it is logged for the first occurrence per field and for every 1000th after that. |
+| `rejected` | The ingestor refused the batch with a 4xx other than 408 / 429 (not retried), or named individual events in the `errors[]` of a 2xx response — then only those events are dropped. When a 2xx reports `failed > 0` without a usable `index`, the count is added to `droppedCount` and `onDrop` is not called. |
+| `retry_exhausted` | Network errors, 408, 429 or 5xx persisted through 3 attempts (1s / 2s / 4s backoff; `Retry-After` honoured up to 30 s). |
+
+A call with no resolvable customer id is not billable; it is skipped and is not counted as a drop.
+
+```ts
+const billing = new AforoWsBilling({
+  // …
+  onDrop: (events, reason) => deadLetterQueue.push({ reason, events }),
+});
+```
 
 ## Walk me through it
 

package/dist/index.d.ts

@@ -45,15 +45,77 @@ export interface AforoWsConfig {
     perFrameEvents?: boolean;
     /** Callback for terminal flush failures. */
     onError?: (error: Error) => void;
+    /**
+     * Opt-in hook receiving events that were permanently dropped (retry
+     * exhaustion, a rejection by the ingestor, or a failed client-side check —
+     * see DropReason). Events keep their idempotency keys,
+     * so persisting and re-submitting them after recovery is dedup-safe.
+     * Exceptions thrown by the hook are swallowed. Default: none (drops are
+     * still counted in droppedCount and WARN-logged).
+     */
+    onDrop?: (events: WsUsageEvent[], reason: DropReason) => void;
 }
+/**
+ * Why events were permanently dropped. `retry_exhausted`: the ingestor stayed
+ * unreachable / kept answering 408, 429 or 5xx. `rejected`: the ingestor
+ * refused the batch (non-retryable 4xx) or individual events of an accepted
+ * batch. `invalid`: the event failed a client-side check and was never sent.
+ * The buffer is unbounded (drained at flush start), so unlike the core SDK
+ * there is no 'overflow' reason here.
+ */
+export type DropReason = 'retry_exhausted' | 'rejected' | 'invalid';
 export interface WrapServerOptions {
     /** Extract Aforo customer ID from the upgrade request. */
     extractCustomerId: (req: any) => string | undefined;
     /** Optional per-connection metadata (product-defined tags). */
     extractMetadata?: (req: any) => Record<string, unknown> | undefined;
+    /**
+     * Optional outcome of the request (used by OUTCOME_BASED pricing, which bills
+     * each event at the weight set for its status). Events without a status bill
+     * at full price. Trimmed and upper-cased by the SDK; blank is treated as absent.
+     * Accepted values: SUCCESS, PARTIAL, TIMEOUT, ERROR, VALIDATION_FAILED, FAILED,
+     * FAILURE, CANCELLED, PENDING, BLOCKED, HITL_REQUIRED (max 20 chars). Any other
+     * value — or a Promise from an async resolver — is reported through `onError`
+     * and left off the event (the event is still sent), because the server would
+     * reject the event.
+     *
+     * This is the outcome of the CONNECTION: it is set on the closing event only
+     * (CONNECTION_CLOSED, and the synthetic close emitted on a socket error).
+     * CONNECTION_OPENED and per-frame MESSAGE events never carry it, so a status
+     * meant for the connection (e.g. ERROR on an abnormal close) can't zero out
+     * every frame under OUTCOME_BASED pricing. WebSocket frames carry no
+     * success/failure signal, so the SDK never derives one: pass a fixed string,
+     * or a synchronous function called with the closing event (and the upgrade
+     * request) that returns the status or undefined.
+     */
+    executionStatus?: string | ((event: WsUsageEvent, req: any) => string | undefined);
     /** Product type for connections accepted by this server. Default: the client-level `productType`. */
     productType?: string;
 }
+/** Options for trackConnection(). */
+export interface TrackConnectionOptions {
+    customerId: string;
+    metadata?: Record<string, unknown>;
+    /**
+     * Optional outcome of the request (used by OUTCOME_BASED pricing, which bills
+     * each event at the weight set for its status). Events without a status bill
+     * at full price. Trimmed and upper-cased by the SDK; blank is treated as absent.
+     * Accepted values: SUCCESS, PARTIAL, TIMEOUT, ERROR, VALIDATION_FAILED, FAILED,
+     * FAILURE, CANCELLED, PENDING, BLOCKED, HITL_REQUIRED (max 20 chars). Any other
+     * value — or a Promise from an async resolver — is reported through `onError`
+     * and left off the event (the event is still sent), because the server would
+     * reject the event.
+     *
+     * The outcome of the connection, set on its closing event only
+     * (CONNECTION_CLOSED, or the synthetic close on a socket error) — never on
+     * CONNECTION_OPENED or per-frame events. Never derived by the SDK: pass a
+     * fixed string, or a synchronous function called with the closing event that
+     * returns the status or undefined.
+     */
+    executionStatus?: string | ((event: WsUsageEvent) => string | undefined);
+    /** Product type for this connection's events (trimmed + uppercased). Default: the client-level `productType`. */
+    productType?: string;
+}
 /** Minimal WebSocket surface — matches `ws` WebSocket, Fastify socket, Deno, Bun. */
 interface MinimalWs {
     on(event: 'message', fn: (data: any, isBinary?: boolean) => void): void;
@@ -68,6 +130,24 @@ interface MinimalWss {
 }
 /** Default top-level `productType` for this SDK. */
 export declare const DEFAULT_PRODUCT_TYPE = "WEBSOCKET_API";
+export interface WsUsageEvent {
+    customerId: string;
+    metricName: string;
+    quantity: number;
+    occurredAt: string;
+    idempotencyKey: string;
+    productType: string;
+    wsConnectionId: string;
+    wsDirection: 'CLIENT_TO_SERVER' | 'SERVER_TO_CLIENT';
+    wsFrameType: 'TEXT' | 'BINARY' | 'PING' | 'PONG' | 'CLOSE';
+    wsCloseReason?: string;
+    messageCount: number;
+    dataBytes: number;
+    executionDurationMs: number;
+    metadata?: Record<string, unknown>;
+    /** Normalized (trimmed, upper-cased) execution status; omitted when not set. */
+    executionStatus?: string;
+}
 export declare class AforoWsBilling {
     private readonly config;
     private readonly productType;
@@ -75,23 +155,46 @@ export declare class AforoWsBilling {
     private readonly flushIntervalMs;
     private readonly perFrameEvents;
     private readonly onError;
+    private readonly onDrop?;
     private buffer;
     private flushTimer;
+    private dropped;
+    /** Invalid-event count per field, for WARN throttling. */
+    private readonly invalidSeen;
     constructor(config: AforoWsConfig);
     /** Wrap a `ws` WebSocketServer (or any object emitting 'connection' events). */
     wrapServer(wss: MinimalWss, options: WrapServerOptions): void;
     /** Track a single WebSocket connection. Returns an unsubscribe function. */
-    trackConnection(ws: MinimalWs, opts: {
-        customerId: string;
-        metadata?: Record<string, unknown>;
-        productType?: string;
-    }): () => void;
+    trackConnection(ws: MinimalWs, opts: TrackConnectionOptions): () => void;
     private push;
     private flush;
     private send;
-    /** A 202 can still carry per-event rejections: `{accepted, duplicates, failed, errors:[{index, message}]}`. */
-    private reportPartialFailures;
+    /**
+     * A 2xx can still carry per-event rejections:
+     * `{accepted, duplicates, failed, errors:[{index, message}]}`. Events the
+     * response names by index are dropped with reason 'rejected'; a `failed`
+     * count the response does not attribute to an index is counted only.
+     */
+    private handlePartialFailures;
+    /** Invoke onError; a hook bug must never break metering or flushing. */
+    private reportError;
+    /** Number of events permanently dropped since this instance was created. */
+    get droppedCount(): number;
+    /**
+     * Account for permanently lost events: bump the counter, WARN-log, and
+     * invoke the opt-in onDrop hook. The buffer is drained at flush start, so
+     * drops here are bounded by flush cadence — no log throttle needed.
+     */
+    private recordDrop;
+    /**
+     * Account for an event that failed a client-side check: never buffered,
+     * never sent. Runs on the hot path, so the WARN is throttled per field
+     * (first occurrence, then every 1000th).
+     */
+    private recordInvalid;
+    private notifyDrop;
     private startTimer;
+    /** Flush any buffered events and stop the background timer. Call before process exit. */
     shutdown(): Promise<void>;
 }
 export declare const WS_CLOSE_REASONS: Record<number, string>;

package/dist/index.js

@@ -31,7 +31,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WS_CLOSE_REASONS = exports.AforoWsBilling = exports.DEFAULT_PRODUCT_TYPE = void 0;
 const node_crypto_1 = require("node:crypto");
-const SDK_VERSION = '1.0.0';
+const SDK_VERSION = '1.2.1';
 /** Default top-level `productType` for this SDK. */
 exports.DEFAULT_PRODUCT_TYPE = 'WEBSOCKET_API';
 /** Upper bound on a server-requested Retry-After wait. */
@@ -41,6 +41,7 @@ const MAX_BATCH_EVENTS = 1000;
 /** usage-ingestor limits (IngestUsageEventRequest). */
 const MAX_CUSTOMER_ID = 64;
 const MAX_IDEMPOTENCY_KEY = 255;
+const MAX_PRODUCT_TYPE = 20;
 // Close reason code → descriptor enum label
 const CLOSE_REASONS = {
     1000: 'NORMAL_CLOSURE',
@@ -63,8 +64,12 @@ class AforoWsBilling {
     flushIntervalMs;
     perFrameEvents;
     onError;
+    onDrop;
     buffer = [];
     flushTimer = null;
+    dropped = 0;
+    /** Invalid-event count per field, for WARN throttling. */
+    invalidSeen = new Map();
     constructor(config) {
         this.config = {
             tenantId: config.tenantId,
@@ -77,6 +82,7 @@ class AforoWsBilling {
         this.flushIntervalMs = config.flushIntervalMs ?? 3000;
         this.perFrameEvents = config.perFrameEvents ?? false;
         this.onError = config.onError ?? ((err) => console.error('[aforo-ws]', err.message));
+        this.onDrop = config.onDrop;
         this.startTimer();
     }
     /** Wrap a `ws` WebSocketServer (or any object emitting 'connection' events). */
@@ -86,17 +92,20 @@ class AforoWsBilling {
             if (!customerId || !customerId.trim())
                 return; // no customer resolved → skip metering
             const metadata = options.extractMetadata?.(req);
-            this.trackConnection(ws, { customerId, metadata, productType: options.productType });
+            const status = options.executionStatus;
+            this.trackConnection(ws, {
+                customerId,
+                metadata,
+                executionStatus: typeof status === 'function' ? (event) => status(event, req) : status,
+                productType: options.productType,
+            });
         });
     }
     /** Track a single WebSocket connection. Returns an unsubscribe function. */
     trackConnection(ws, opts) {
-        if (!opts.customerId || !opts.customerId.trim())
-            return () => { };
-        if (opts.customerId.length > MAX_CUSTOMER_ID) {
-            this.onError(new Error(`WebSocket metering: customerId longer than ${MAX_CUSTOMER_ID} chars; connection not metered`));
+        // No customer resolved — the connection is not billable, not a drop.
+        if (typeof opts.customerId !== 'string' || !opts.customerId.trim())
             return () => { };
-        }
         const connectionId = (0, node_crypto_1.randomUUID)();
         const productType = normalizeProductType(opts.productType) ?? this.productType;
         const start = Date.now();
@@ -155,6 +164,8 @@ class AforoWsBilling {
             }
             return origSend(data, cb);
         };
+        // opts.executionStatus is the connection's outcome: only the closing events
+        // below carry it (same as the Python SDK), never OPENED or per-frame events.
         ws.on('close', (code) => {
             // Emit CONNECTION_CLOSED with aggregated counters — this is the billing anchor.
             this.push({
@@ -176,7 +187,7 @@ class AforoWsBilling {
                     recvBytes,
                     closeCode: code,
                 },
-            });
+            }, opts.executionStatus);
         });
         ws.on('error', (err) => {
             this.push({
@@ -190,13 +201,13 @@ class AforoWsBilling {
                 dataBytes: sentBytes + recvBytes,
                 executionDurationMs: Date.now() - start,
                 metadata: { ...(opts.metadata ?? {}), event: 'CONNECTION_ERROR', error: err.message },
-            });
+            }, opts.executionStatus);
         });
         return () => {
             // Tracking lifetime is managed by the close handler — no manual cleanup needed.
         };
     }
-    push(partial) {
+    push(partial, executionStatus) {
         const now = new Date();
         const event = {
             ...partial,
@@ -205,7 +216,8 @@ class AforoWsBilling {
                 : 'websocket_api.message',
             quantity: 1,
             occurredAt: now.toISOString(),
-            // Tail-trimmed to the ingestor's limit, keeping the unique millis:random suffix.
+            // Minted once, here. SDK-generated; tail-trimmed to the ingestor's limit,
+            // keeping the unique millis:random suffix.
             idempotencyKey: `ws:${this.config.tenantId}:${partial.wsConnectionId}:${partial.wsFrameType}:${now.getTime()}:${randomSuffix()}`.slice(-MAX_IDEMPOTENCY_KEY),
             metadata: {
                 ...(partial.metadata ?? {}),
@@ -213,6 +225,20 @@ class AforoWsBilling {
                 productId: this.config.productId,
             },
         };
+        const checked = checkExecutionStatus(resolveExecutionStatus(executionStatus, event));
+        if (checked.problem)
+            this.reportError(new Error(`[aforo-ws] ${checked.problem}`));
+        if (checked.status)
+            event.executionStatus = checked.status;
+        // An event the ingestor would reject is not sent (one bad event fails its
+        // whole batch): it is dropped here with reason 'invalid', never thrown
+        // into the socket handlers.
+        const invalid = tooLong('customerId', event.customerId, MAX_CUSTOMER_ID) ??
+            tooLong('productType', event.productType, MAX_PRODUCT_TYPE);
+        if (invalid) {
+            this.recordInvalid(event, invalid);
+            return;
+        }
         this.buffer.push(event);
         if (this.buffer.length >= this.flushCount) {
             void this.flush();
@@ -232,9 +258,11 @@ class AforoWsBilling {
         const body = JSON.stringify({ events: batch });
         const maxRetries = 3;
         for (let attempt = 1; attempt <= maxRetries; attempt++) {
-            let delayMs = Math.pow(2, attempt - 1) * 1000;
+            let delayMs = Math.pow(2, attempt - 1) * 1000; // 1s, 2s, 4s
+            let res;
+            let networkError;
             try {
-                const res = await fetch(this.config.ingestorUrl.replace(/\/$/, '') + '/v1/ingest/batch', {
+                res = await fetch(this.config.ingestorUrl.replace(/\/$/, '') + '/v1/ingest/batch', {
                     method: 'POST',
                     headers: {
                         'Content-Type': 'application/json',
@@ -243,33 +271,101 @@ class AforoWsBilling {
                     },
                     body,
                 });
+            }
+            catch (err) {
+                networkError = err;
+            }
+            if (res) {
                 if (res.ok) {
-                    await this.reportPartialFailures(res);
+                    await this.handlePartialFailures(res, batch);
                     return;
                 }
                 if (!isRetryableStatus(res.status)) {
-                    const { details } = await readErrorMessages(res);
-                    this.onError(new Error(`WebSocket metering batch rejected with HTTP ${res.status}${details ? ` — ${details}` : ''} (dropped ${batch.length} events, not retried)`));
+                    // 4xx other than 408/429: the same body would be refused again.
+                    const { details } = await readBatchResult(res, batch.length);
+                    this.recordDrop(batch, 'rejected');
+                    this.reportError(new Error(`WebSocket metering batch rejected with HTTP ${res.status}${details ? ` — ${details}` : ''} (dropped ${batch.length} events, not retried)`));
                     return;
                 }
                 delayMs = parseRetryAfter(res) ?? delayMs;
             }
-            catch (err) {
-                if (attempt === maxRetries) {
-                    this.onError(err);
-                    return;
-                }
+            else if (attempt === maxRetries) {
+                this.recordDrop(batch, 'retry_exhausted');
+                this.reportError(networkError ?? new Error('WebSocket metering request failed'));
+                return;
             }
             if (attempt < maxRetries)
                 await sleep(delayMs);
         }
-        this.onError(new Error(`WebSocket metering flush failed after ${maxRetries} attempts (dropped ${batch.length} events)`));
+        // Not re-queued: dropping avoids unbounded memory growth.
+        this.recordDrop(batch, 'retry_exhausted');
+        this.reportError(new Error(`WebSocket metering flush failed after ${maxRetries} attempts (dropped ${batch.length} events)`));
     }
-    /** A 202 can still carry per-event rejections: `{accepted, duplicates, failed, errors:[{index, message}]}`. */
-    async reportPartialFailures(res) {
-        const { failed, details } = await readErrorMessages(res);
-        if (failed && failed > 0) {
-            this.onError(new Error(`Aforo ingestor rejected ${failed} event(s)${details ? ` — ${details}` : ''}`));
+    /**
+     * A 2xx can still carry per-event rejections:
+     * `{accepted, duplicates, failed, errors:[{index, message}]}`. Events the
+     * response names by index are dropped with reason 'rejected'; a `failed`
+     * count the response does not attribute to an index is counted only.
+     */
+    async handlePartialFailures(res, batch) {
+        const { failed, details, indexes } = await readBatchResult(res, batch.length);
+        if (failed <= 0)
+            return;
+        if (indexes.length > 0)
+            this.recordDrop(indexes.map((i) => batch[i]), 'rejected');
+        const unattributed = Math.min(failed, batch.length) - indexes.length;
+        if (unattributed > 0) {
+            this.dropped += unattributed;
+            console.warn(`[aforo-ws] Dropped ${unattributed} event(s) — rejected, not identified by the ingestor (${this.dropped} total dropped).`);
+        }
+        this.reportError(new Error(`Aforo ingestor rejected ${failed} event(s)${details ? ` — ${details}` : ''}`));
+    }
+    /** Invoke onError; a hook bug must never break metering or flushing. */
+    reportError(err) {
+        try {
+            this.onError(err);
+        }
+        catch {
+            // ignore
+        }
+    }
+    /** Number of events permanently dropped since this instance was created. */
+    get droppedCount() {
+        return this.dropped;
+    }
+    /**
+     * Account for permanently lost events: bump the counter, WARN-log, and
+     * invoke the opt-in onDrop hook. The buffer is drained at flush start, so
+     * drops here are bounded by flush cadence — no log throttle needed.
+     */
+    recordDrop(events, reason) {
+        this.dropped += events.length;
+        console.warn(`[aforo-ws] Dropped ${events.length} event(s) — ${reason} (${this.dropped} total dropped).`);
+        this.notifyDrop(events, reason);
+    }
+    /**
+     * Account for an event that failed a client-side check: never buffered,
+     * never sent. Runs on the hot path, so the WARN is throttled per field
+     * (first occurrence, then every 1000th).
+     */
+    recordInvalid(event, invalid) {
+        this.dropped += 1;
+        const seen = (this.invalidSeen.get(invalid.field) ?? 0) + 1;
+        this.invalidSeen.set(invalid.field, seen);
+        if (seen === 1 || seen % 1000 === 0) {
+            console.warn(`[aforo-ws] Dropped 1 event — invalid: ${invalid.problem} ` +
+                `(${seen} for ${invalid.field}, ${this.dropped} total dropped).`);
+        }
+        this.notifyDrop([event], 'invalid');
+    }
+    notifyDrop(events, reason) {
+        if (!this.onDrop)
+            return;
+        try {
+            this.onDrop(events, reason);
+        }
+        catch {
+            // A hook bug must never break metering or flushing.
         }
     }
     startTimer() {
@@ -277,12 +373,10 @@ class AforoWsBilling {
             return;
         this.flushTimer = setInterval(() => { void this.flush(); }, this.flushIntervalMs);
         // Unref so the background timer never blocks host-process exit (final flush still needs shutdown()).
-        if (this.flushTimer && typeof this.flushTimer === 'object' && 'unref' in this.flushTimer) {
-            this.flushTimer.unref();
-        }
         if (typeof this.flushTimer.unref === 'function')
             this.flushTimer.unref();
     }
+    /** Flush any buffered events and stop the background timer. Call before process exit. */
     async shutdown() {
         if (this.flushTimer) {
             clearInterval(this.flushTimer);
@@ -306,6 +400,51 @@ function estimateBytes(data) {
         return data.reduce((s, d) => s + estimateBytes(d), 0);
     return 0;
 }
+/** Statuses the Aforo ingestor accepts (contract/ingest-contract.json, max 20 chars). */
+const CANONICAL_EXECUTION_STATUSES = new Set([
+    'SUCCESS', 'PARTIAL', 'TIMEOUT', 'ERROR', 'VALIDATION_FAILED', 'FAILED',
+    'FAILURE', 'CANCELLED', 'PENDING', 'BLOCKED', 'HITL_REQUIRED',
+]);
+/**
+ * Check a caller-supplied status. `{ status }` when canonical; `{ problem }`
+ * when it has to be left off the event (an unknown value would make the
+ * ingestor reject the event; a Promise from an async resolver can't be
+ * awaited on this path); `{}` when blank or absent.
+ */
+function checkExecutionStatus(value) {
+    if (value !== null && typeof value === 'object' && typeof value.then === 'function') {
+        // Swallow a later rejection so it doesn't surface as an unhandled rejection.
+        value.then(undefined, () => { });
+        return { problem: 'executionStatus resolver returned a Promise — resolvers must be synchronous; field omitted' };
+    }
+    const status = normalizeExecutionStatus(value);
+    if (!status)
+        return {};
+    if (!CANONICAL_EXECUTION_STATUSES.has(status)) {
+        return {
+            problem: `unknown executionStatus "${status.slice(0, 40)}" — field omitted. ` +
+                `Expected one of: ${[...CANONICAL_EXECUTION_STATUSES].join(', ')}`,
+        };
+    }
+    return { status };
+}
+/** 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;
+}
+function resolveExecutionStatus(option, event) {
+    if (typeof option !== 'function')
+        return option;
+    try {
+        return option(event);
+    }
+    catch {
+        return undefined; // a resolver bug must never break metering
+    }
+}
 /** Trim + uppercase a product type; blank/non-string → undefined (unknown values pass through). */
 function normalizeProductType(value) {
     if (typeof value !== 'string')
@@ -313,6 +452,17 @@ function normalizeProductType(value) {
     const trimmed = value.trim();
     return trimmed ? trimmed.toUpperCase() : undefined;
 }
+/** The offending value for a WARN line, cut to 80 chars. */
+function preview(value) {
+    const text = typeof value === 'string' ? value : String(value);
+    return JSON.stringify(text.length > 80 ? `${text.slice(0, 80)}…` : text);
+}
+/** Limits mirror the ingestor's IngestUsageEventRequest; over-limit values are never truncated. */
+function tooLong(field, value, max) {
+    if (typeof value !== 'string' || value.length <= max)
+        return undefined;
+    return { field, problem: `${field} is ${value.length} chars, limit ${max}: ${preview(value)}` };
+}
 /** Network errors, 408, 429 and 5xx are transient; every other 4xx (400/401/403/422...) is not. */
 function isRetryableStatus(status) {
     return status === 408 || status === 429 || status >= 500;
@@ -330,19 +480,30 @@ function parseRetryAfter(res) {
         return Math.min(Math.max(date - Date.now(), 0), MAX_RETRY_AFTER_MS);
     return undefined;
 }
-/** Reads the ingestor's `errors[].message` entries (first 5) from a response body, if any. */
-async function readErrorMessages(res) {
+/**
+ * Reads the ingestor's batch response body, if any: the `failed` count, the
+ * first 5 `errors[].message` entries, and the batch indexes `errors[]` names.
+ */
+async function readBatchResult(res, batchSize) {
+    const none = { failed: 0, details: '', indexes: [] };
     if (typeof res?.json !== 'function')
-        return { details: '' };
+        return none;
     try {
-        const body = await res.json();
-        const details = Array.isArray(body?.errors)
-            ? body.errors.slice(0, 5).map((e) => `#${e?.index}: ${e?.message}`).join('; ')
+        const body = unwrapEnvelope(await res.json());
+        const errors = Array.isArray(body?.errors) ? body.errors : undefined;
+        const details = errors
+            ? errors.slice(0, 5).map((e) => `#${e?.index}: ${e?.message}`).join('; ')
             : typeof body?.message === 'string' ? body.message : '';
-        return { failed: typeof body?.failed === 'number' ? body.failed : undefined, details };
+        const indexes = [
+            ...new Set((errors ?? [])
+                .map((e) => e?.index)
+                .filter((i) => Number.isInteger(i) && i >= 0 && i < batchSize)),
+        ].sort((a, b) => a - b);
+        const failed = typeof body?.failed === 'number' && body.failed > 0 ? body.failed : 0;
+        return { failed, details, indexes };
     }
     catch {
-        return { details: '' }; // Non-JSON or empty body — nothing to report.
+        return none; // Non-JSON or empty body — nothing to report.
     }
 }
 function randomSuffix() {
@@ -352,3 +513,11 @@ function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
 exports.WS_CLOSE_REASONS = CLOSE_REASONS;
+/**
+ * The ingestor wraps every 2xx JSON body in `{success, data, meta}`. Returns
+ * the inner `data` object when present, else the body unchanged (bare shape).
+ */
+function unwrapEnvelope(body) {
+    const data = body && typeof body === 'object' && !Array.isArray(body) ? body.data : undefined;
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : body;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aforoai/ws-metering",
-  "version": "1.0.0",
+  "version": "1.2.1",
   "description": "Aforo WebSocket Metering SDK — wraps ws/Fastify-WebSocket/Socket.io connections to meter frames, bytes, and connection duration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",