@aforoai/ws-metering 1.0.0 → 2.0.0

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:** 2.0.0 · 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 `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 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
@@ -40,10 +40,15 @@ const billing = new AforoWsBilling({
 
 const wss = new WebSocketServer({ port: 8080 });
 billing.wrapServer(wss, {
-  extractCustomerId: (req) => req.headers['x-customer-id'] as string,
+  // Who is billed: from identity your app verified on the upgrade request.
+  customerResolver: (req) => sessions.customerIdFor(req),
 });
 
-process.on('SIGTERM', async () => { await billing.shutdown(); });
+// The SDK installs no signal handlers. Flush from your own:
+process.once('SIGTERM', async () => {
+  await billing.shutdown();
+  process.exit(0);
+});
 ```
 
 For frameworks that don't expose a `ws`-style server, track each socket directly:
@@ -52,7 +57,7 @@ For frameworks that don't expose a `ws`-style server, track each socket directly
 billing.trackConnection(socket, { customerId: 'cust_001', metadata: { feed: 'market' } });
 ```
 
-By default the SDK emits two events per connection — `CONNECTION_OPENED` on connect and `CONNECTION_CLOSED` on close (the billing anchor, carrying aggregated sent/recv counts + bytes + duration). The close event uses `metricName: "websocket_api.connection_closed"`; open and per-frame events use `websocket_api.message`. Events ship to `POST https://api.aforo.ai/v1/ingest/batch` with `X-API-Key: <api_key>` and `X-Tenant-Id: <tenant_id>`.
+By default the SDK emits two events per connection — `CONNECTION_OPENED` on connect and `CONNECTION_CLOSED` on close (the billing anchor, carrying aggregated sent/recv counts + bytes + duration). The open event uses `metricName: "websocket_api.connection_opened"` with `wsFrameType: "OPEN"`, the close event `websocket_api.connection_closed`, and per-frame events `websocket_api.message`. A connection still open at `shutdown()` is billed a `CONNECTION_CLOSED` (`GOING_AWAY`, `closedBy: "sdk_shutdown"`), and one with no frame for `connectionIdleTimeoutMs` (default 1 hour) is closed by a sweep (`ABNORMAL_CLOSURE`, `closedBy: "sdk_idle_timeout"`), so every billed open has a close. Events ship to `POST https://api.aforo.ai/v1/ingest/batch` with `X-API-Key: <api_key>` and `X-Tenant-Id: <tenant_id>`.
 
 > **Per-frame metering is off by default.** Set `perFrameEvents: true` to emit one event per inbound and outbound frame — high volume, so size your batching accordingly. With it off, individual frames are still counted and rolled into the `CONNECTION_CLOSED` event.
 
@@ -64,27 +69,81 @@ By default the SDK emits two events per connection — `CONNECTION_OPENED` on co
 |---|---|---|---|
 | `tenantId` | `string` | — (required) | Aforo tenant. Sent as `X-Tenant-Id`. Never read from a client header. |
 | `productId` | `string` | — (required) | Aforo product id; into each event's `metadata.productId`. |
-| `apiKey` | `string` | — (required) | Sent as `X-API-Key: <apiKey>`. |
-| `ingestorUrl` | `string` | — (required) | Ingestion base URL. SDK appends `/v1/ingest/batch`. Use `https://api.aforo.ai`. |
+| `apiKey` | `string` | — (required) | Sent only as `X-API-Key: <apiKey>`; never logged or shown by `inspect()` / `JSON.stringify`. |
+| `ingestorUrl` | `string` | — (required) | Ingestion base URL, `https://` (see `allowInsecureHttp`). SDK appends `/v1/ingest/batch`. Use `https://api.aforo.ai`. |
 | `productType` | `string` | `'WEBSOCKET_API'` | Aforo product type sent as top-level `productType` on every event (trimmed + uppercased; unknown values pass through). Override via `wrapServer(wss, { productType })` or `trackConnection(ws, { customerId, productType })`. |
 | `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`). |
-
-`wrapServer(wss, options)` / `trackConnection(ws, opts)` take the customer resolver:
+| `connectionIdleTimeoutMs` | `number` | `3600000` | Close (and bill `CONNECTION_CLOSED` for) a connection with no frame for this long, so a socket that died without a close event is not tracked forever. Must be positive. |
+| `allowInsecureHttp` | `boolean` | `false` | Accept a plain `http://` `ingestorUrl` on a non-local host. `https://` is required otherwise (plain http is fine for `localhost`, `127.0.0.1`, `::1`). |
+| `flushCount` | `number` | `500` | Events per request (max 1000). Reaching it wakes the background sender; recording an event never sends by itself. |
+| `flushIntervalMs` | `number` | `5000` | The background sender also runs this often. |
+| `maxQueueSize` | `number` | `10000` | Queue capacity. When it is full — usually during a long outage — the oldest event is dropped with reason `overflow`. |
+| `maxRetries` | `number` | `3` | Retries per batch on network errors, timeouts, 408, 429 and 5xx, with full-jitter backoff (`Retry-After` in seconds or as a date is honoured, capped at 60 s). |
+| `timeoutMs` | `number` | `10000` | Total deadline per request. |
+| `shutdownTimeoutMs` | `number` | `5000` | How long `shutdown()` keeps sending. Events still queued then are dropped with reason `shutdown`. |
+| `flushOnExit` | `boolean` | `true` | Send queued events on the process `beforeExit` event, within `shutdownTimeoutMs`. The SDK installs no signal handlers. |
+| `onError` | `(error: Error) => void` | logs to `console.error` | Called for delivery problems: a batch the ingestor refused (the message includes its `errors[].message`), an ingestor outage (once per outage), events lost at the shutdown deadline, and an unusable `executionStatus`. Exceptions it throws are caught. Delivery reports are a `CoreTransportError`: branch on `err.kind` (`outage`, `auth`, `rejected`, `shutdown`, `closed`) and read `err.events`, not the message. |
+| `onDrop` | `(events, reason) => void` | none | Receives events lost for good. See [Dropped events](#dropped-events). |
+
+`wrapServer(wss, options)` / `trackConnection(ws, opts)` take the customer:
 
 | Option | Where | Type | What it does |
 |---|---|---|---|
-| `extractCustomerId` | `wrapServer` | `(req) => string \| undefined` | Resolve the customer from the upgrade request. `undefined` → connection is not metered. |
+| `customerResolver` | `wrapServer` | `(req) => string \| undefined` | Required (or `trustCustomerHeader`). The Aforo customer id from identity your app verified on the upgrade request. Returning nothing: the connection is not metered and one `invalid` drop is counted; the connection itself is not affected. `extractCustomerId` is a deprecated alias. |
+| `trustCustomerHeader` | `wrapServer` | `boolean` | Bill the `x-customer-id` header of the upgrade request. Any client can send that header, so only turn this on behind a proxy you control that sets it. Default `false`; `wrapServer` throws when neither this nor `customerResolver` is given. |
 | `extractMetadata` | `wrapServer` | `(req) => Record<string, unknown> \| undefined` | Optional per-connection tags. |
 | `customerId` | `trackConnection` | `string` | Customer to attribute all traffic on this socket to. |
 | `metadata` | `trackConnection` | `Record<string, unknown>` | Optional per-connection tags. |
 | `productType` | both | `string` | Product type for this server's / socket's events. Default: the client-level `productType`. |
 
-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`.
+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`; the `close` that follows it is not billed again (one closing event per connection).
+
+Exported symbols: `AforoWsBilling` (with `wrapServer` / `trackConnection` / `flush` / `shutdown` / `droppedCount` / `queuedCount`), the `WS_CLOSE_REASONS` map, `DEFAULT_PRODUCT_TYPE`, and the `AforoWsConfig` / `WrapServerOptions` / `TrackConnectionOptions` / `WsUsageEvent` / `DropReason` types.
+
+## Delivery
+
+One background sender per client sends one request at a time; recording an event only queues it. If the ingestor is unreachable, keeps answering 408/429/5xx after the retries, or answers 401/403 (a 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 sending, and the ingestor deduplicates the re-sent keys. A 413 splits the batch. Request bodies are plain JSON (the ingestor does not decode gzip). `flush()` sends what is queued now; `shutdown()` sends for at most `shutdownTimeoutMs` — call it from your own SIGTERM handler.
+
+## 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, {
+  customerResolver: (req) => sessions.customerIdFor(req),
+  // (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 customer resolver returned nothing (one event per connection), or the event failed a client-side check and was never queued 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 invalid event 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. |
+| `overflow` | The queue (`maxQueueSize`) was full and the oldest event was evicted. |
+| `shutdown` | Still queued when `shutdownTimeoutMs` ran out (also reported through `onError`). |
+| `closed` | Recorded after `shutdown()`. |
+| `retry_exhausted` | Not produced by 2.x (kept in the type): an outage keeps events queued instead of dropping them. |
 
-Exported symbols: `AforoWsBilling` (with `wrapServer` / `trackConnection` / `shutdown`), the `WS_CLOSE_REASONS` map, and the `AforoWsConfig` / `WrapServerOptions` types.
+A connection with no resolvable customer is not metered and is counted as one `invalid` drop.
+
+```ts
+const billing = new AforoWsBilling({
+  // …
+  onDrop: (events, reason) => deadLetterQueue.push({ reason, events }),
+});
+```
 
 ## Walk me through it
 
@@ -93,6 +152,6 @@ Step-by-step from install to a verified event in Aforo: [USER_GUIDE.md](USER_GUI
 ## What this doesn't cover
 
 - **`send()` is wrapped by reference.** `trackConnection` reassigns `ws.send` to count outbound frames. If another layer wraps `send` afterward, ordering matters.
-- **No persistent buffer.** Events are in memory until flushed; a hard crash before flush drops the buffered batch. `shutdown()` covers graceful exit only.
+- **No persistent buffer.** Events are in memory until sent; a hard crash loses what is queued. `shutdown()` covers graceful exit only.
 - **Connection identity is per-process.** `wsConnectionId` is a fresh UUID per `trackConnection` call; it does not survive reconnects or correlate across processes.
 - **The SDK does not enforce or read pricing.** It emits usage; rating/billing happens in Aforo.

package/dist/index.d.ts

@@ -2,9 +2,12 @@
  * @aforoai/ws-metering — Aforo WebSocket Metering SDK
  *
  * Wraps WebSocket server connections to emit three classes of billing events:
- *   - CONNECTION_OPENED  — once on upgrade completion
+ *   - CONNECTION_OPENED  — once on upgrade completion (wsFrameType OPEN,
+ *                          metric websocket_api.connection_opened)
  *   - MESSAGE            — one event per frame (direction + bytes + type)
- *   - CONNECTION_CLOSED  — once on close, carrying aggregated counters + duration
+ *   - CONNECTION_CLOSED  — once per connection, carrying aggregated counters +
+ *                          duration: on close, on a socket error, when an idle
+ *                          connection is swept, or at shutdown
  *
  * Works with the `ws` library out of the box (wrap WebSocketServer), or use
  * trackConnection() directly for Fastify-WebSocket, Socket.io, Deno, Bun, or
@@ -24,9 +27,15 @@
  *
  *   const wss = new WebSocketServer({ port: 8080 });
  *   billing.wrapServer(wss, {
- *     extractCustomerId: (req) => req.headers['x-customer-id'] as string,
+ *     // Who is billed, from identity your app verified at upgrade time.
+ *     customerResolver: (req) => sessionStore.customerFor(req),
  *   });
+ *
+ *   // The SDK installs no signal handlers. Flush from your own:
+ *   process.once('SIGTERM', async () => { await billing.shutdown(); process.exit(0); });
  */
+/** What onError receives for delivery problems: branch on `kind`, read `events`. */
+export { CoreTransportError, type CoreErrorKind } from './transport-core/core';
 export interface AforoWsConfig {
     tenantId: string;
     productId: string;
@@ -37,62 +46,205 @@ export interface AforoWsConfig {
      * Default: `WEBSOCKET_API`. Override per integration via `wrapServer(wss, { productType })` / `trackConnection(ws, { productType })`.
      */
     productType?: string;
-    /** How many events to buffer before flushing (default 100 — WS is high-volume). */
+    /** Allow a plain http:// ingestorUrl on a non-local host. Default false (https required). */
+    allowInsecureHttp?: boolean;
+    /** Events per request (default 500, max 1000). Reaching it wakes the background sender. */
     flushCount?: number;
-    /** Max interval in ms before a partial batch is flushed (default 3000). */
+    /** The background sender also runs this often, in ms (default 5000). */
     flushIntervalMs?: number;
+    /** Queue capacity (default 10 000). The oldest event is dropped on overflow. */
+    maxQueueSize?: number;
+    /** Retries per batch before the breaker opens (default 3). */
+    maxRetries?: number;
+    /** Total deadline per request, in ms (default 10 000). */
+    timeoutMs?: number;
+    /** How long shutdown() keeps sending, in ms (default 5000). */
+    shutdownTimeoutMs?: number;
+    /** Send queued events on the process 'beforeExit' event (default true). */
+    flushOnExit?: boolean;
     /** If true, emit one MESSAGE event per frame. If false (default) only aggregate on close. */
     perFrameEvents?: boolean;
-    /** Callback for terminal flush failures. */
+    /**
+     * Close a tracked connection that saw no frame for this long, in ms
+     * (default 3 600 000 = 1 hour): it gets a CONNECTION_CLOSED with close
+     * reason ABNORMAL_CLOSURE and metadata `closedBy: "sdk_idle_timeout"`. This
+     * keeps the open-connection map bounded when a socket dies without a close
+     * event. Must be a positive number; 0 means the default.
+     */
+    connectionIdleTimeoutMs?: number;
+    /** Callback for delivery problems (rejected batches, ingestor outages) and bad executionStatus values. */
     onError?: (error: Error) => void;
+    /**
+     * Opt-in hook receiving events that were permanently dropped (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. `overflow`: the queue was full and the
+ * oldest event was evicted. `rejected`: the ingestor refused the batch
+ * (non-retryable 4xx) or individual events of an accepted batch. `invalid`:
+ * the event failed a client-side check, or the customer resolver returned no
+ * customer. `shutdown`: still queued when the shutdown deadline passed.
+ * `closed`: recorded after shutdown(). `retry_exhausted`: kept for
+ * compatibility, not produced by 2.x — an outage keeps events queued.
+ */
+export type DropReason = 'overflow' | 'retry_exhausted' | 'rejected' | 'invalid' | 'shutdown' | 'closed';
 export interface WrapServerOptions {
-    /** Extract Aforo customer ID from the upgrade request. */
-    extractCustomerId: (req: any) => string | undefined;
+    /**
+     * Who is billed for a connection, from identity your app verified on the
+     * upgrade request (session cookie, verified token). Required unless
+     * `trustCustomerHeader` is true. Returning nothing drops the connection's
+     * opening event as 'invalid' (counted); the connection is not affected.
+     */
+    customerResolver?: (req: any) => string | undefined | null;
+    /** @deprecated Use `customerResolver` (same signature). */
+    extractCustomerId?: (req: any) => string | undefined | null;
+    /**
+     * Bill the `x-customer-id` header of the upgrade request. Any client can
+     * set that header, so only turn this on behind a proxy you control that
+     * sets it. Default false.
+     */
+    trustCustomerHeader?: boolean;
     /** 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;
     on(event: 'close', fn: (code: number, reason: Buffer | string) => void): void;
     on(event: 'error', fn: (err: Error) => void): void;
-    send(data: any, cb?: (err?: Error) => void): void;
+    /** `ws` takes (data, cb) or (data, options, cb); every argument is passed through. */
+    send(data: any, ...rest: any[]): void;
     readyState?: number;
 }
 /** Minimal WebSocketServer surface — matches `ws` WebSocketServer. */
 interface MinimalWss {
     on(event: 'connection', fn: (ws: MinimalWs, req: any) => void): void;
 }
+/** Default for AforoWsConfig.connectionIdleTimeoutMs: one hour. */
+export declare const DEFAULT_CONNECTION_IDLE_TIMEOUT_MS: number;
 /** 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: 'OPEN' | '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;
-    private readonly flushCount;
-    private readonly flushIntervalMs;
     private readonly perFrameEvents;
     private readonly onError;
-    private buffer;
-    private flushTimer;
+    private readonly core;
+    private readonly idleTimeoutMs;
+    private readonly connections;
+    private readonly sweepTimer;
+    private shutdownPromise;
     constructor(config: AforoWsConfig);
-    /** Wrap a `ws` WebSocketServer (or any object emitting 'connection' events). */
+    /** Connections being tracked: opened and not yet closed by the socket, the idle sweep or shutdown(). */
+    get openConnections(): number;
+    /**
+     * Close every tracked connection idle longer than `connectionIdleTimeoutMs`
+     * at `now` (CONNECTION_CLOSED, ABNORMAL_CLOSURE, `closedBy: "sdk_idle_timeout"`).
+     * Runs on a timer; callable directly. Returns how many it closed.
+     */
+    sweepIdleConnections(now?: number): number;
+    /**
+     * Wrap a `ws` WebSocketServer (or any object emitting 'connection' events).
+     * Throws when neither `customerResolver` nor `trustCustomerHeader: true` is given.
+     */
     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;
+    /** Fill in the fields every event carries. */
+    private buildEvent;
     private push;
-    private flush;
-    private send;
-    /** A 202 can still carry per-event rejections: `{accepted, duplicates, failed, errors:[{index, message}]}`. */
-    private reportPartialFailures;
-    private startTimer;
+    /** Invoke onError; a hook bug must never break metering or flushing. */
+    private reportError;
+    /** Number of events permanently dropped since this instance was created (every DropReason). */
+    get droppedCount(): number;
+    /** Number of events waiting to be sent. */
+    get queuedCount(): number;
+    /** Send what is queued now and wait for it (one request at a time; never concurrent). */
+    flush(): Promise<{
+        sent: number;
+        failed: number;
+        requeued: number;
+        queued: number;
+    }>;
+    /**
+     * Bill every connection still open with a CONNECTION_CLOSED (close code
+     * 1001, GOING_AWAY, metadata `closedBy: "sdk_shutdown"`), stop accepting
+     * events and send what is queued, for at most `shutdownTimeoutMs`. Events
+     * still queued then are dropped with reason 'shutdown' (counted, passed to
+     * onDrop). A connection opened from now on is reported as 'closed' and not
+     * tracked. Calling it again returns the first call's promise. Call it from
+     * your SIGTERM handler.
+     */
     shutdown(): Promise<void>;
+    toJSON(): Record<string, unknown>;
 }
 export declare const WS_CLOSE_REASONS: Record<number, string>;
-export {};