@aforoai/ws-metering 1.2.1 → 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.2.1 · 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
 ```
 
-> **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.
+> **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,28 +69,40 @@ 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 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:
+| `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
 
-Exported symbols: `AforoWsBilling` (with `wrapServer` / `trackConnection` / `shutdown` / `droppedCount`), the `WS_CLOSE_REASONS` map, `DEFAULT_PRODUCT_TYPE`, and the `AforoWsConfig` / `WrapServerOptions` / `TrackConnectionOptions` / `WsUsageEvent` / `DropReason` types.
+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
 
@@ -97,7 +114,7 @@ WebSocket frames carry no success or failure signal, so the SDK never sets `exec
 
 ```typescript
 billing.wrapServer(wss, {
-  extractCustomerId: (req) => req.headers['x-customer-id'] as string,
+  customerResolver: (req) => sessions.customerIdFor(req),
   // (event, req) => status | undefined
   executionStatus: (event, req) =>
     event.wsFrameType === 'CLOSE' && event.wsCloseReason !== 'NORMAL_CLOSURE' ? 'ERROR' : undefined,
@@ -112,11 +129,14 @@ The SDK does not throw into your socket handlers for event content. An event tha
 
 | 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. |
+| `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. |
-| `retry_exhausted` | Network errors, 408, 429 or 5xx persisted through 3 attempts (1s / 2s / 4s backoff; `Retry-After` honoured up to 30 s). |
+| `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. |
 
-A call with no resolvable customer id is not billable; it is skipped and is not counted as a drop.
+A connection with no resolvable customer is not metered and is counted as one `invalid` drop.
 
 ```ts
 const billing = new AforoWsBilling({
@@ -132,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,18 +46,37 @@ 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 (retry
-     * exhaustion, a rejection by the ingestor, or a failed client-side check —
-     * see DropReason). Events keep their idempotency keys,
+     * 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).
@@ -56,17 +84,31 @@ export interface AforoWsConfig {
     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.
+ * 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 = 'retry_exhausted' | 'rejected' | 'invalid';
+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;
     /**
@@ -121,13 +163,16 @@ 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 {
@@ -139,7 +184,7 @@ export interface WsUsageEvent {
     productType: string;
     wsConnectionId: string;
     wsDirection: 'CLIENT_TO_SERVER' | 'SERVER_TO_CLIENT';
-    wsFrameType: 'TEXT' | 'BINARY' | 'PING' | 'PONG' | 'CLOSE';
+    wsFrameType: 'OPEN' | 'TEXT' | 'BINARY' | 'PING' | 'PONG' | 'CLOSE';
     wsCloseReason?: string;
     messageCount: number;
     dataBytes: number;
@@ -151,51 +196,55 @@ export interface WsUsageEvent {
 export declare class AforoWsBilling {
     private readonly config;
     private readonly productType;
-    private readonly flushCount;
-    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;
+    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: TrackConnectionOptions): () => void;
+    /** Fill in the fields every event carries. */
+    private buildEvent;
     private push;
-    private flush;
-    private send;
-    /**
-     * 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. */
+    /** 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;
+    }>;
     /**
-     * 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).
+     * 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.
      */
-    private recordInvalid;
-    private notifyDrop;
-    private startTimer;
-    /** Flush any buffered events and stop the background timer. Call before process exit. */
     shutdown(): Promise<void>;
+    toJSON(): Record<string, unknown>;
 }
 export declare const WS_CLOSE_REASONS: Record<number, string>;
-export {};