@aforoai/ws-metering 1.0.0

package/README.md

@@ -0,0 +1,98 @@
+# @aforoai/ws-metering
+
+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)
+
+## Install
+
+Intended public install (once published):
+
+```bash
+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.
+
+```bash
+# from the SDKs repo root
+cd SDKs/aforo-metering-sdks/node-ws
+npm install
+npm run build          # tsc → dist/
+
+# then, from YOUR app
+npm install /absolute/path/to/aforo-metering-sdks/node-ws
+npm install ws         # only if you use wrapServer
+```
+
+## Quickstart
+
+```ts
+import { WebSocketServer } from 'ws';
+import { AforoWsBilling } from '@aforoai/ws-metering';
+
+const billing = new AforoWsBilling({
+  tenantId: 'tenant_acme',
+  productId: 'prod_ws_001',
+  apiKey: process.env.AFORO_API_KEY!,
+  ingestorUrl: 'https://api.aforo.ai', // SDK appends /v1/ingest/batch
+});
+
+const wss = new WebSocketServer({ port: 8080 });
+billing.wrapServer(wss, {
+  extractCustomerId: (req) => req.headers['x-customer-id'] as string,
+});
+
+process.on('SIGTERM', async () => { await billing.shutdown(); });
+```
+
+For frameworks that don't expose a `ws`-style server, track each socket directly:
+
+```ts
+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>`.
+
+> **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.
+
+## Configuration
+
+`new AforoWsBilling(config)` — `tenantId`, `productId`, `apiKey`, and `ingestorUrl` are required.
+
+| Option | Type | Default | What it does |
+|---|---|---|---|
+| `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`. |
+| `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:
+
+| Option | Where | Type | What it does |
+|---|---|---|---|
+| `extractCustomerId` | `wrapServer` | `(req) => string \| undefined` | Resolve the customer from the upgrade request. `undefined` → connection is not metered. |
+| `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`.
+
+Exported symbols: `AforoWsBilling` (with `wrapServer` / `trackConnection` / `shutdown`), the `WS_CLOSE_REASONS` map, and the `AforoWsConfig` / `WrapServerOptions` types.
+
+## Walk me through it
+
+Step-by-step from install to a verified event in Aforo: [USER_GUIDE.md](USER_GUIDE.md).
+
+## 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.
+- **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

@@ -0,0 +1,98 @@
+/**
+ * @aforoai/ws-metering — Aforo WebSocket Metering SDK
+ *
+ * Wraps WebSocket server connections to emit three classes of billing events:
+ *   - CONNECTION_OPENED  — once on upgrade completion
+ *   - MESSAGE            — one event per frame (direction + bytes + type)
+ *   - CONNECTION_CLOSED  — once on close, carrying aggregated counters + duration
+ *
+ * Works with the `ws` library out of the box (wrap WebSocketServer), or use
+ * trackConnection() directly for Fastify-WebSocket, Socket.io, Deno, Bun, or
+ * anything else that exposes the standard WebSocket event surface.
+ *
+ * Usage:
+ *   import { WebSocketServer } from 'ws';
+ *   import { AforoWsBilling } from '@aforoai/ws-metering';
+ *
+ *   const billing = new AforoWsBilling({
+ *     tenantId: 'tenant_acme',
+ *     productId: 'prod_ws_market_feed',
+ *     apiKey: process.env.AFORO_API_KEY!,
+ *     ingestorUrl: 'https://api.aforo.ai',
+ *     // productType defaults to 'WEBSOCKET_API'
+ *   });
+ *
+ *   const wss = new WebSocketServer({ port: 8080 });
+ *   billing.wrapServer(wss, {
+ *     extractCustomerId: (req) => req.headers['x-customer-id'] as string,
+ *   });
+ */
+export interface AforoWsConfig {
+    tenantId: string;
+    productId: string;
+    apiKey: string;
+    ingestorUrl: string;
+    /**
+     * Aforo product type sent as top-level `productType` on every event (trimmed + uppercased).
+     * 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). */
+    flushCount?: number;
+    /** Max interval in ms before a partial batch is flushed (default 3000). */
+    flushIntervalMs?: number;
+    /** If true, emit one MESSAGE event per frame. If false (default) only aggregate on close. */
+    perFrameEvents?: boolean;
+    /** Callback for terminal flush failures. */
+    onError?: (error: Error) => void;
+}
+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;
+    /** Product type for connections accepted by this server. 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;
+    readyState?: number;
+}
+/** Minimal WebSocketServer surface — matches `ws` WebSocketServer. */
+interface MinimalWss {
+    on(event: 'connection', fn: (ws: MinimalWs, req: any) => void): void;
+}
+/** Default top-level `productType` for this SDK. */
+export declare const DEFAULT_PRODUCT_TYPE = "WEBSOCKET_API";
+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;
+    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;
+    private push;
+    private flush;
+    private send;
+    /** A 202 can still carry per-event rejections: `{accepted, duplicates, failed, errors:[{index, message}]}`. */
+    private reportPartialFailures;
+    private startTimer;
+    shutdown(): Promise<void>;
+}
+export declare const WS_CLOSE_REASONS: Record<number, string>;
+export {};

package/dist/index.js

@@ -0,0 +1,354 @@
+"use strict";
+/**
+ * @aforoai/ws-metering — Aforo WebSocket Metering SDK
+ *
+ * Wraps WebSocket server connections to emit three classes of billing events:
+ *   - CONNECTION_OPENED  — once on upgrade completion
+ *   - MESSAGE            — one event per frame (direction + bytes + type)
+ *   - CONNECTION_CLOSED  — once on close, carrying aggregated counters + duration
+ *
+ * Works with the `ws` library out of the box (wrap WebSocketServer), or use
+ * trackConnection() directly for Fastify-WebSocket, Socket.io, Deno, Bun, or
+ * anything else that exposes the standard WebSocket event surface.
+ *
+ * Usage:
+ *   import { WebSocketServer } from 'ws';
+ *   import { AforoWsBilling } from '@aforoai/ws-metering';
+ *
+ *   const billing = new AforoWsBilling({
+ *     tenantId: 'tenant_acme',
+ *     productId: 'prod_ws_market_feed',
+ *     apiKey: process.env.AFORO_API_KEY!,
+ *     ingestorUrl: 'https://api.aforo.ai',
+ *     // productType defaults to 'WEBSOCKET_API'
+ *   });
+ *
+ *   const wss = new WebSocketServer({ port: 8080 });
+ *   billing.wrapServer(wss, {
+ *     extractCustomerId: (req) => req.headers['x-customer-id'] as string,
+ *   });
+ */
+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';
+/** Default top-level `productType` for this SDK. */
+exports.DEFAULT_PRODUCT_TYPE = 'WEBSOCKET_API';
+/** Upper bound on a server-requested Retry-After wait. */
+const MAX_RETRY_AFTER_MS = 30_000;
+/** The ingestor rejects batch requests with more than 1000 events. */
+const MAX_BATCH_EVENTS = 1000;
+/** usage-ingestor limits (IngestUsageEventRequest). */
+const MAX_CUSTOMER_ID = 64;
+const MAX_IDEMPOTENCY_KEY = 255;
+// Close reason code → descriptor enum label
+const CLOSE_REASONS = {
+    1000: 'NORMAL_CLOSURE',
+    1001: 'GOING_AWAY',
+    1002: 'PROTOCOL_ERROR',
+    1003: 'UNSUPPORTED_DATA',
+    1005: 'NORMAL_CLOSURE', // no status
+    1006: 'ABNORMAL_CLOSURE',
+    1007: 'PROTOCOL_ERROR',
+    1008: 'POLICY_VIOLATION',
+    1009: 'MESSAGE_TOO_BIG',
+    1011: 'INTERNAL_ERROR',
+    1012: 'GOING_AWAY',
+    4000: 'IDLE_TIMEOUT', // common app-level range
+};
+class AforoWsBilling {
+    config;
+    productType;
+    flushCount;
+    flushIntervalMs;
+    perFrameEvents;
+    onError;
+    buffer = [];
+    flushTimer = null;
+    constructor(config) {
+        this.config = {
+            tenantId: config.tenantId,
+            productId: config.productId,
+            apiKey: config.apiKey,
+            ingestorUrl: config.ingestorUrl,
+        };
+        this.productType = normalizeProductType(config.productType) ?? exports.DEFAULT_PRODUCT_TYPE;
+        this.flushCount = config.flushCount ?? 100;
+        this.flushIntervalMs = config.flushIntervalMs ?? 3000;
+        this.perFrameEvents = config.perFrameEvents ?? false;
+        this.onError = config.onError ?? ((err) => console.error('[aforo-ws]', err.message));
+        this.startTimer();
+    }
+    /** Wrap a `ws` WebSocketServer (or any object emitting 'connection' events). */
+    wrapServer(wss, options) {
+        wss.on('connection', (ws, req) => {
+            const customerId = options.extractCustomerId(req);
+            if (!customerId || !customerId.trim())
+                return; // no customer resolved → skip metering
+            const metadata = options.extractMetadata?.(req);
+            this.trackConnection(ws, { customerId, metadata, 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`));
+            return () => { };
+        }
+        const connectionId = (0, node_crypto_1.randomUUID)();
+        const productType = normalizeProductType(opts.productType) ?? this.productType;
+        const start = Date.now();
+        let sentCount = 0;
+        let recvCount = 0;
+        let sentBytes = 0;
+        let recvBytes = 0;
+        // Emit CONNECTION_OPENED immediately
+        this.push({
+            customerId: opts.customerId,
+            wsConnectionId: connectionId,
+            productType,
+            wsDirection: 'SERVER_TO_CLIENT',
+            wsFrameType: 'PING', // "handshake complete" marker; not an actual frame
+            messageCount: 0,
+            dataBytes: 0,
+            executionDurationMs: 0,
+            metadata: { ...(opts.metadata ?? {}), event: 'CONNECTION_OPENED' },
+        });
+        ws.on('message', (data, isBinary) => {
+            recvCount++;
+            const bytes = estimateBytes(data);
+            recvBytes += bytes;
+            if (this.perFrameEvents) {
+                this.push({
+                    customerId: opts.customerId,
+                    wsConnectionId: connectionId,
+                    productType,
+                    wsDirection: 'CLIENT_TO_SERVER',
+                    wsFrameType: isBinary ? 'BINARY' : 'TEXT',
+                    messageCount: 1,
+                    dataBytes: bytes,
+                    executionDurationMs: Date.now() - start,
+                    metadata: opts.metadata,
+                });
+            }
+        });
+        // Wrap send() to count outbound frames
+        const origSend = ws.send.bind(ws);
+        ws.send = (data, cb) => {
+            sentCount++;
+            const bytes = estimateBytes(data);
+            sentBytes += bytes;
+            if (this.perFrameEvents) {
+                this.push({
+                    customerId: opts.customerId,
+                    wsConnectionId: connectionId,
+                    productType,
+                    wsDirection: 'SERVER_TO_CLIENT',
+                    wsFrameType: typeof data === 'string' ? 'TEXT' : 'BINARY',
+                    messageCount: 1,
+                    dataBytes: bytes,
+                    executionDurationMs: Date.now() - start,
+                    metadata: opts.metadata,
+                });
+            }
+            return origSend(data, cb);
+        };
+        ws.on('close', (code) => {
+            // Emit CONNECTION_CLOSED with aggregated counters — this is the billing anchor.
+            this.push({
+                customerId: opts.customerId,
+                wsConnectionId: connectionId,
+                productType,
+                wsDirection: 'SERVER_TO_CLIENT',
+                wsFrameType: 'CLOSE',
+                wsCloseReason: CLOSE_REASONS[code] ?? 'NORMAL_CLOSURE',
+                messageCount: sentCount + recvCount,
+                dataBytes: sentBytes + recvBytes,
+                executionDurationMs: Date.now() - start,
+                metadata: {
+                    ...(opts.metadata ?? {}),
+                    event: 'CONNECTION_CLOSED',
+                    sentCount,
+                    recvCount,
+                    sentBytes,
+                    recvBytes,
+                    closeCode: code,
+                },
+            });
+        });
+        ws.on('error', (err) => {
+            this.push({
+                customerId: opts.customerId,
+                wsConnectionId: connectionId,
+                productType,
+                wsDirection: 'SERVER_TO_CLIENT',
+                wsFrameType: 'CLOSE',
+                wsCloseReason: 'INTERNAL_ERROR',
+                messageCount: sentCount + recvCount,
+                dataBytes: sentBytes + recvBytes,
+                executionDurationMs: Date.now() - start,
+                metadata: { ...(opts.metadata ?? {}), event: 'CONNECTION_ERROR', error: err.message },
+            });
+        });
+        return () => {
+            // Tracking lifetime is managed by the close handler — no manual cleanup needed.
+        };
+    }
+    push(partial) {
+        const now = new Date();
+        const event = {
+            ...partial,
+            metricName: partial.wsFrameType === 'CLOSE'
+                ? 'websocket_api.connection_closed'
+                : 'websocket_api.message',
+            quantity: 1,
+            occurredAt: now.toISOString(),
+            // 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 ?? {}),
+                sdkVersion: SDK_VERSION,
+                productId: this.config.productId,
+            },
+        };
+        this.buffer.push(event);
+        if (this.buffer.length >= this.flushCount) {
+            void this.flush();
+        }
+    }
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        const pending = this.buffer.splice(0, this.buffer.length);
+        // The ingestor accepts at most MAX_BATCH_EVENTS events per request.
+        for (let i = 0; i < pending.length; i += MAX_BATCH_EVENTS) {
+            await this.send(pending.slice(i, i + MAX_BATCH_EVENTS));
+        }
+    }
+    async send(batch) {
+        // Serialized once, so every retry re-sends the same idempotencyKeys.
+        const body = JSON.stringify({ events: batch });
+        const maxRetries = 3;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            let delayMs = Math.pow(2, attempt - 1) * 1000;
+            try {
+                const res = await fetch(this.config.ingestorUrl.replace(/\/$/, '') + '/v1/ingest/batch', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-API-Key': this.config.apiKey,
+                        'X-Tenant-Id': this.config.tenantId,
+                    },
+                    body,
+                });
+                if (res.ok) {
+                    await this.reportPartialFailures(res);
+                    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)`));
+                    return;
+                }
+                delayMs = parseRetryAfter(res) ?? delayMs;
+            }
+            catch (err) {
+                if (attempt === maxRetries) {
+                    this.onError(err);
+                    return;
+                }
+            }
+            if (attempt < maxRetries)
+                await sleep(delayMs);
+        }
+        this.onError(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}` : ''}`));
+        }
+    }
+    startTimer() {
+        if (this.flushTimer)
+            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();
+    }
+    async shutdown() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flush();
+    }
+}
+exports.AforoWsBilling = AforoWsBilling;
+// ── Helpers ──────────────────────────────────────────────────────
+function estimateBytes(data) {
+    if (data == null)
+        return 0;
+    if (typeof data === 'string')
+        return Buffer.byteLength(data, 'utf8');
+    if (Buffer.isBuffer?.(data))
+        return data.length;
+    if (data?.byteLength != null)
+        return data.byteLength;
+    if (Array.isArray(data))
+        return data.reduce((s, d) => s + estimateBytes(d), 0);
+    return 0;
+}
+/** Trim + uppercase a product type; blank/non-string → undefined (unknown values pass through). */
+function normalizeProductType(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed.toUpperCase() : undefined;
+}
+/** 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;
+}
+/** Retry-After (delta-seconds or HTTP date) in ms, capped at MAX_RETRY_AFTER_MS. */
+function parseRetryAfter(res) {
+    const raw = res?.headers?.get?.('retry-after');
+    if (!raw)
+        return undefined;
+    const secs = Number(raw);
+    if (Number.isFinite(secs) && secs >= 0)
+        return Math.min(secs * 1000, MAX_RETRY_AFTER_MS);
+    const date = Date.parse(raw);
+    if (!Number.isNaN(date))
+        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) {
+    if (typeof res?.json !== 'function')
+        return { details: '' };
+    try {
+        const body = await res.json();
+        const details = Array.isArray(body?.errors)
+            ? body.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 };
+    }
+    catch {
+        return { details: '' }; // Non-JSON or empty body — nothing to report.
+    }
+}
+function randomSuffix() {
+    return Math.random().toString(36).slice(2, 10);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+exports.WS_CLOSE_REASONS = CLOSE_REASONS;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@aforoai/ws-metering",
+  "version": "1.0.0",
+  "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",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --testEnvironment=node",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "aforo",
+    "billing",
+    "websocket",
+    "ws",
+    "metering",
+    "usage-based",
+    "streaming"
+  ],
+  "author": "Aforo, Inc.",
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "ws": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.18.1",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0",
+    "ws": "^8.20.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aforoai/SDKs.git",
+    "directory": "aforo-metering-sdks/node-ws"
+  },
+  "homepage": "https://github.com/aforoai/SDKs/tree/main/aforo-metering-sdks/node-ws#readme",
+  "bugs": {
+    "url": "https://github.com/aforoai/SDKs/issues"
+  }
+}