@aforoai/ws-metering 1.0.0 → 2.0.0

package/dist/index.js

@@ -3,9 +3,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
@@ -25,22 +28,29 @@
  *
  *   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); });
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WS_CLOSE_REASONS = exports.AforoWsBilling = exports.DEFAULT_PRODUCT_TYPE = void 0;
+exports.WS_CLOSE_REASONS = exports.AforoWsBilling = exports.DEFAULT_PRODUCT_TYPE = exports.DEFAULT_CONNECTION_IDLE_TIMEOUT_MS = exports.CoreTransportError = void 0;
 const node_crypto_1 = require("node:crypto");
-const SDK_VERSION = '1.0.0';
+const core_1 = require("./transport-core/core");
+/** What onError receives for delivery problems: branch on `kind`, read `events`. */
+var core_2 = require("./transport-core/core");
+Object.defineProperty(exports, "CoreTransportError", { enumerable: true, get: function () { return core_2.CoreTransportError; } });
+const SDK_VERSION = '2.0.0';
+/** Default for AforoWsConfig.connectionIdleTimeoutMs: one hour. */
+exports.DEFAULT_CONNECTION_IDLE_TIMEOUT_MS = 60 * 60 * 1000;
 /** 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;
+const MAX_PRODUCT_TYPE = 20;
 // Close reason code → descriptor enum label
 const CLOSE_REASONS = {
     1000: 'NORMAL_CLOSURE',
@@ -59,64 +69,179 @@ const CLOSE_REASONS = {
 class AforoWsBilling {
     config;
     productType;
-    flushCount;
-    flushIntervalMs;
     perFrameEvents;
     onError;
-    buffer = [];
-    flushTimer = null;
+    core;
+    idleTimeoutMs;
+    connections = new Map();
+    sweepTimer;
+    shutdownPromise = null;
     constructor(config) {
+        const idle = config.connectionIdleTimeoutMs;
+        if (idle !== undefined && (typeof idle !== 'number' || !Number.isFinite(idle) || idle < 0)) {
+            throw new Error(`[aforo-ws] connectionIdleTimeoutMs must be a positive number of milliseconds (got ${String(idle)}); ` +
+                'without it connections that die without a close event are never released.');
+        }
+        this.idleTimeoutMs = idle ? idle : exports.DEFAULT_CONNECTION_IDLE_TIMEOUT_MS;
         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();
+        const onDrop = config.onDrop;
+        // The core is the only holder of the API key.
+        this.core = new core_1.TransportCore({
+            baseUrl: config.ingestorUrl,
+            apiKey: config.apiKey,
+            allowInsecureHttp: config.allowInsecureHttp,
+            headers: { 'X-Tenant-Id': config.tenantId },
+            userAgent: `aforo-ws-metering/${SDK_VERSION}`,
+            flushCount: config.flushCount,
+            flushIntervalMs: config.flushIntervalMs,
+            maxQueueSize: config.maxQueueSize,
+            maxRetries: config.maxRetries,
+            timeoutMs: config.timeoutMs,
+            shutdownTimeoutMs: config.shutdownTimeoutMs,
+            flushOnExit: config.flushOnExit,
+            logPrefix: '[aforo-ws]',
+            onError: (err) => this.reportError(err),
+            onDrop: onDrop ? (events, reason) => onDrop(events, reason) : undefined,
+        });
+        const every = Math.min(60_000, Math.max(1_000, Math.floor(this.idleTimeoutMs / 4)));
+        this.sweepTimer = setInterval(() => this.sweepIdleConnections(), every);
+        this.sweepTimer.unref?.();
+    }
+    /** Connections being tracked: opened and not yet closed by the socket, the idle sweep or shutdown(). */
+    get openConnections() {
+        return this.connections.size;
+    }
+    /**
+     * 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 = Date.now()) {
+        const cutoff = now - this.idleTimeoutMs;
+        let closed = 0;
+        for (const conn of Array.from(this.connections.values())) {
+            if (conn.lastActivity <= cutoff && conn.close(1006, 'sdk_idle_timeout'))
+                closed++;
+        }
+        return closed;
     }
-    /** Wrap a `ws` WebSocketServer (or any object emitting 'connection' events). */
+    /**
+     * Wrap a `ws` WebSocketServer (or any object emitting 'connection' events).
+     * Throws when neither `customerResolver` nor `trustCustomerHeader: true` is given.
+     */
     wrapServer(wss, options) {
+        const resolver = options?.customerResolver ?? options?.extractCustomerId;
+        const trustHeader = options?.trustCustomerHeader === true;
+        if (typeof resolver !== 'function' && !trustHeader) {
+            throw new Error('[aforo-ws] wrapServer needs a customerResolver: (req) => the Aforo customer id from identity your app ' +
+                'verified on the upgrade request. To bill the x-customer-id header instead — only safe behind a proxy ' +
+                'that sets it — pass trustCustomerHeader: true.');
+        }
         wss.on('connection', (ws, req) => {
-            const customerId = options.extractCustomerId(req);
-            if (!customerId || !customerId.trim())
-                return; // no customer resolved → skip metering
+            let customerId;
+            try {
+                customerId = textOrUndefined(typeof resolver === 'function' ? resolver(req) : undefined);
+                if (!customerId && trustHeader)
+                    customerId = textOrUndefined(headerValue(req?.headers?.['x-customer-id']));
+            }
+            catch (err) {
+                this.reportError(new Error(`[aforo-ws] customerResolver threw: ${err?.message ?? err}`));
+            }
             const metadata = options.extractMetadata?.(req);
-            this.trackConnection(ws, { customerId, metadata, productType: options.productType });
+            const status = options.executionStatus;
+            this.trackConnection(ws, {
+                customerId: 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`));
-            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({
+        if (typeof opts.customerId !== 'string' || !opts.customerId.trim()) {
+            // No customer: the connection is not metered. Counted as one 'invalid' drop.
+            this.core.reportDrop([this.buildEvent({
+                    customerId: typeof opts.customerId === 'string' ? opts.customerId : '',
+                    wsConnectionId: connectionId,
+                    productType,
+                    wsDirection: 'SERVER_TO_CLIENT',
+                    wsFrameType: 'OPEN',
+                    messageCount: 0,
+                    dataBytes: 0,
+                    executionDurationMs: 0,
+                    metadata: { ...(opts.metadata ?? {}), event: 'CONNECTION_OPENED' },
+                })], 'invalid', 'customer resolver returned no customer; the connection is not metered');
+            return () => { };
+        }
+        const openEvent = {
             customerId: opts.customerId,
             wsConnectionId: connectionId,
             productType,
             wsDirection: 'SERVER_TO_CLIENT',
-            wsFrameType: 'PING', // "handshake complete" marker; not an actual frame
+            wsFrameType: 'OPEN', // handshake complete; not a frame on the wire
             messageCount: 0,
             dataBytes: 0,
             executionDurationMs: 0,
             metadata: { ...(opts.metadata ?? {}), event: 'CONNECTION_OPENED' },
-        });
+        };
+        if (this.shutdownPromise) {
+            // Shutting down: a connection opened now could never get its CONNECTION_CLOSED.
+            this.core.reportDrop([this.buildEvent(openEvent)], 'closed', 'connection opened after shutdown(); not metered');
+            return () => { };
+        }
+        const start = Date.now();
+        let sentCount = 0;
+        let recvCount = 0;
+        let sentBytes = 0;
+        let recvBytes = 0;
+        let closed = false;
+        const conn = {
+            lastActivity: start,
+            close: (code, closedBy) => {
+                if (closed)
+                    return false;
+                closed = true;
+                this.connections.delete(connectionId);
+                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,
+                        ...(closedBy ? { closedBy } : {}),
+                    },
+                }, opts.executionStatus);
+                return true;
+            },
+        };
+        this.connections.set(connectionId, conn);
+        // Emit CONNECTION_OPENED immediately
+        this.push(openEvent);
         ws.on('message', (data, isBinary) => {
+            if (closed)
+                return;
+            conn.lastActivity = Date.now();
             recvCount++;
             const bytes = estimateBytes(data);
             recvBytes += bytes;
@@ -134,51 +259,56 @@ class AforoWsBilling {
                 });
             }
         });
-        // Wrap send() to count outbound frames
+        // Wrap send() to count outbound frames. A frame is billed only once the
+        // socket has accepted it (ws calls the send callback without an error), so a
+        // send to a closing or broken socket is never billed. The caller's own
+        // callback, if any, still runs with the same error.
         const origSend = ws.send.bind(ws);
-        ws.send = (data, cb) => {
-            sentCount++;
+        ws.send = (data, ...rest) => {
+            if (closed)
+                return origSend(data, ...rest);
+            conn.lastActivity = Date.now();
+            const callerCb = typeof rest[rest.length - 1] === 'function' ? rest.pop() : undefined;
             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);
+            const frameType = typeof data === 'string' ? 'TEXT' : 'BINARY';
+            const onSent = (err) => {
+                // A frame accepted after the connection was reported closed is not
+                // billed: the CONNECTION_CLOSED totals have already gone out.
+                if (!err && !closed) {
+                    sentCount++;
+                    sentBytes += bytes;
+                    if (this.perFrameEvents) {
+                        this.push({
+                            customerId: opts.customerId,
+                            wsConnectionId: connectionId,
+                            productType,
+                            wsDirection: 'SERVER_TO_CLIENT',
+                            wsFrameType: frameType,
+                            messageCount: 1,
+                            dataBytes: bytes,
+                            executionDurationMs: Date.now() - start,
+                            metadata: opts.metadata,
+                        });
+                    }
+                }
+                if (callerCb)
+                    callerCb(err);
+            };
+            return origSend(data, ...rest, onSent);
         };
+        // 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.
+        // 'error' is normally followed by 'close': bill the connection once,
+        // with whichever of the two arrives first (or the idle sweep / shutdown).
         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,
-                },
-            });
+            // CONNECTION_CLOSED with aggregated counters — this is the billing anchor.
+            conn.close(code);
         });
         ws.on('error', (err) => {
+            if (closed)
+                return;
+            closed = true;
+            this.connections.delete(connectionId);
             this.push({
                 customerId: opts.customerId,
                 wsConnectionId: connectionId,
@@ -189,23 +319,27 @@ class AforoWsBilling {
                 messageCount: sentCount + recvCount,
                 dataBytes: sentBytes + recvBytes,
                 executionDurationMs: Date.now() - start,
-                metadata: { ...(opts.metadata ?? {}), event: 'CONNECTION_ERROR', error: err.message },
-            });
+                metadata: { ...(opts.metadata ?? {}), event: 'CONNECTION_ERROR', error: String(err?.message ?? err).slice(0, 200) },
+            }, opts.executionStatus);
         });
         return () => {
-            // Tracking lifetime is managed by the close handler — no manual cleanup needed.
+            // Tracking lifetime is managed by the close handler, the idle sweep and shutdown().
         };
     }
-    push(partial) {
+    /** Fill in the fields every event carries. */
+    buildEvent(partial) {
         const now = new Date();
-        const event = {
+        return {
             ...partial,
             metricName: partial.wsFrameType === 'CLOSE'
                 ? 'websocket_api.connection_closed'
-                : 'websocket_api.message',
+                : partial.wsFrameType === 'OPEN'
+                    ? 'websocket_api.connection_opened'
+                    : '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,82 +347,72 @@ class AforoWsBilling {
                 productId: this.config.productId,
             },
         };
-        this.buffer.push(event);
-        if (this.buffer.length >= this.flushCount) {
-            void this.flush();
-        }
     }
-    async flush() {
-        if (this.buffer.length === 0)
+    push(partial, executionStatus) {
+        const event = this.buildEvent(partial);
+        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.core.reportDrop([event], 'invalid', invalid.problem);
             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));
         }
+        // Queue only; the core's single background sender does the HTTP.
+        this.core.enqueue(event);
     }
-    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);
+    /** Invoke onError; a hook bug must never break metering or flushing. */
+    reportError(err) {
+        try {
+            this.onError(err);
         }
-        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}` : ''}`));
+        catch (hookErr) {
+            console.debug('[aforo-ws] onError hook threw', hookErr);
         }
     }
-    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();
+    /** Number of events permanently dropped since this instance was created (every DropReason). */
+    get droppedCount() {
+        return this.core.droppedCount;
     }
-    async shutdown() {
-        if (this.flushTimer) {
-            clearInterval(this.flushTimer);
-            this.flushTimer = null;
+    /** Number of events waiting to be sent. */
+    get queuedCount() {
+        return this.core.queued;
+    }
+    /** Send what is queued now and wait for it (one request at a time; never concurrent). */
+    async flush() {
+        return this.core.flush();
+    }
+    /**
+     * 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() {
+        if (!this.shutdownPromise) {
+            this.shutdownPromise = (async () => {
+                clearInterval(this.sweepTimer);
+                for (const conn of Array.from(this.connections.values()))
+                    conn.close(1001, 'sdk_shutdown');
+                await this.core.shutdown();
+            })();
         }
-        await this.flush();
+        return this.shutdownPromise;
+    }
+    toJSON() {
+        return { tenantId: this.config.tenantId, productId: this.config.productId, queued: this.queuedCount, dropped: this.droppedCount };
+    }
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return `AforoWsBilling { tenantId: '${this.config.tenantId}', productId: '${this.config.productId}', queued: ${this.queuedCount}, dropped: ${this.droppedCount} }`;
     }
 }
 exports.AforoWsBilling = AforoWsBilling;
@@ -306,6 +430,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,42 +482,27 @@ function normalizeProductType(value) {
     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;
+/** 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);
 }
-/** 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)
+/** 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;
-    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;
+    return { field, problem: `${field} is ${value.length} chars, limit ${max}: ${preview(value)}` };
 }
-/** 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 textOrUndefined(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = String(value).trim();
+    return text ? text : undefined;
+}
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
 }
 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;