@aforoai/mqtt-metering 1.2.2 → 2.0.0

package/dist/index.js

@@ -27,18 +27,34 @@
  *
  *   const broker = aedes();
  *   billing.wrapAedesBroker(broker, {
- *     resolveCustomerId: (clientId) => customerIdLookup(clientId),
+ *     // Who is billed: map the client your broker authenticated to an Aforo customer.
+ *     customerResolver: (clientId, username) => deviceRegistry.customerFor(clientId),
  *   });
+ *
+ *   // 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.AforoMqttBilling = exports.mqttDisconnectTopic = exports.mqttConnectTopic = exports.DEFAULT_PRODUCT_TYPE = void 0;
+exports.AforoMqttBilling = exports.mqttDisconnectTopic = exports.mqttConnectTopic = exports.DEFAULT_PRODUCT_TYPE = exports.DEFAULT_RECONNECT_DEBOUNCE_MS = exports.CoreTransportError = void 0;
 exports.truncateToLimit = truncateToLimit;
 const node_crypto_1 = require("node:crypto");
-const SDK_VERSION = '1.2.2';
+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; } });
+/** Default reconnect window, the same as python-mqtt's `reconnect_debounce_sec`. */
+exports.DEFAULT_RECONNECT_DEBOUNCE_MS = 30_000;
+function checkDebounce(value, fallback, where) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        throw new Error(`[aforo-mqtt] ${where}: reconnectDebounceMs must be a non-negative number of milliseconds (got ${String(value)})`);
+    }
+    return value;
+}
+const SDK_VERSION = '2.0.0';
 /** Default top-level `productType` for this SDK. */
 exports.DEFAULT_PRODUCT_TYPE = 'MQTT_BROKER';
-/** Upper bound on a server-requested Retry-After wait. */
-const MAX_RETRY_AFTER_MS = 30_000;
 /**
  * mqttTopic is required on every MQTT_BROKER event, but CONNECT / DISCONNECT
  * have no topic. These per-client `$SYS/clients/<id>/connected|disconnected`
@@ -50,8 +66,6 @@ const mqttConnectTopic = (clientId) => `$SYS/clients/${clientId || 'unknown'}/co
 exports.mqttConnectTopic = mqttConnectTopic;
 const mqttDisconnectTopic = (clientId) => `$SYS/clients/${clientId || 'unknown'}/disconnected`;
 exports.mqttDisconnectTopic = mqttDisconnectTopic;
-/** 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;
@@ -61,144 +75,238 @@ const MAX_MQTT_CLIENT_ID = 128;
 class AforoMqttBilling {
     config;
     productType;
-    flushCount;
-    flushIntervalMs;
     emitDeliverEvents;
     onError;
-    onDrop;
-    buffer = [];
-    flushTimer = null;
-    dropped = 0;
-    /** Invalid-event count per field, for WARN throttling. */
-    invalidSeen = new Map();
+    core;
     /** Request-derived labels already reported as truncated (one WARN per label). */
     truncationWarned = new Set();
+    reconnectDebounceMs;
+    /** DISCONNECTs inside their reconnect window; billed at shutdown at the latest. */
+    pendingDisconnects = new Set();
     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 ?? 200;
-        this.flushIntervalMs = config.flushIntervalMs ?? 2000;
         this.emitDeliverEvents = config.emitDeliverEvents ?? false;
+        this.reconnectDebounceMs = checkDebounce(config.reconnectDebounceMs, exports.DEFAULT_RECONNECT_DEBOUNCE_MS, 'AforoMqttBilling');
         this.onError = config.onError ?? ((err) => console.error('[aforo-mqtt]', err.message));
-        this.onDrop = config.onDrop;
-        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-mqtt-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-mqtt]',
+            onError: (err) => this.reportError(err),
+            onDrop: onDrop ? (events, reason) => onDrop(events, reason) : undefined,
+        });
     }
     // ── Broker-side integration (Aedes) ─────────────────────────────
+    /**
+     * Attach to an Aedes broker. Throws when neither `customerResolver` nor
+     * `trustCustomerHeader: true` is given. Every listener catches its own
+     * errors (a resolver rejection is reported through onError), so metering can
+     * never produce an unhandled rejection in the broker process.
+     */
     wrapAedesBroker(broker, options) {
-        const resolveCustomer = async (clientId, username) => Promise.resolve(options.resolveCustomerId(clientId, username));
+        const resolver = options?.customerResolver ?? options?.resolveCustomerId;
+        const trustUsername = options?.trustCustomerHeader === true;
+        if (typeof resolver !== 'function' && !trustUsername) {
+            throw new Error('[aforo-mqtt] wrapAedesBroker needs a customerResolver: (clientId, username) => the Aforo customer id ' +
+                'for the client your broker authenticated. To bill the MQTT username instead — only when your broker ' +
+                'authenticates it — pass trustCustomerHeader: true.');
+        }
+        const resolveCustomer = async (clientId, username) => {
+            const fromResolver = typeof resolver === 'function' ? textOrUndefined(await resolver(clientId, username)) : undefined;
+            if (fromResolver)
+                return fromResolver;
+            return trustUsername ? textOrUndefined(username) : undefined;
+        };
+        const debounceMs = checkDebounce(options.reconnectDebounceMs, this.reconnectDebounceMs, 'wrapAedesBroker');
+        /** Per client id: live connections and a DISCONNECT inside its reconnect window. */
+        const sessions = new Map();
         const status = options.executionStatus;
         const brokerStatus = (clientId) => typeof status === 'function' ? (event) => status(event, clientId) : status;
-        broker.on('publish', async (packet, client) => {
+        /**
+         * Run a listener body. The returned promise always resolves: a throw or
+         * rejection is reported through onError, never left unhandled.
+         */
+        const guarded = (hook, body) => body().catch((err) => {
+            this.reportError(new Error(`[aforo-mqtt] ${hook} metering failed: ${err?.message ?? err}`));
+        });
+        /** Resolve the customer; a resolver failure is reported and treated as "no customer". */
+        const customerFor = async (hook, clientId, username) => {
+            try {
+                return (await resolveCustomer(clientId, username)) ?? '';
+            }
+            catch (err) {
+                this.reportError(new Error(`[aforo-mqtt] customerResolver failed on ${hook}: ${err?.message ?? err}`));
+                return '';
+            }
+        };
+        broker.on('publish', (packet, client) => {
             if (!client)
                 return; // broker-originated publishes skip billing
-            const clientId = client.id;
-            const customerId = await resolveCustomer(clientId, client.username);
-            if (!customerId)
-                return;
-            const payload = packet.payload;
-            const bytes = estimateBytes(payload);
-            this.push({
-                customerId,
-                mqttTopic: this.topicLabel(packet.topic),
-                mqttQos: packet.qos ?? 0,
-                mqttRetained: !!packet.retain,
-                mqttEventType: 'PUBLISH',
-                mqttClientId: this.clientIdLabel(clientId),
-                productType: options.productType,
-                dataBytes: bytes,
-                metadata: options.resolveMetadata?.(clientId),
-            }, brokerStatus(clientId), clientId);
+            return guarded('publish', async () => {
+                const clientId = client.id;
+                const customerId = await customerFor('publish', clientId, client.username);
+                this.push({
+                    customerId,
+                    mqttTopic: this.topicLabel(packet?.topic),
+                    mqttQos: packet?.qos ?? 0,
+                    mqttRetained: !!packet?.retain,
+                    mqttEventType: 'PUBLISH',
+                    mqttClientId: this.clientIdLabel(clientId),
+                    productType: options.productType,
+                    dataBytes: estimateBytes(packet?.payload),
+                    metadata: options.resolveMetadata?.(clientId),
+                }, brokerStatus(clientId), clientId);
+            });
         });
-        broker.on('subscribe', async (subs, client) => {
+        broker.on('subscribe', (subs, client) => {
             const clientId = client?.id;
             if (!clientId)
                 return;
-            const customerId = await resolveCustomer(clientId, client.username);
-            if (!customerId)
+            return guarded('subscribe', async () => {
+                const customerId = await customerFor('subscribe', clientId, client.username);
+                const arr = Array.isArray(subs) ? subs : [subs];
+                for (const s of arr) {
+                    this.push({
+                        customerId,
+                        mqttTopic: this.topicLabel(s?.topic),
+                        mqttQos: s?.qos ?? 0,
+                        mqttRetained: false,
+                        mqttEventType: 'SUBSCRIBE',
+                        mqttClientId: this.clientIdLabel(clientId),
+                        productType: options.productType,
+                        dataBytes: 0,
+                        metadata: options.resolveMetadata?.(clientId),
+                    }, brokerStatus(clientId), clientId);
+                }
+            });
+        });
+        broker.on('unsubscribe', (unsubs, client) => {
+            const clientId = client?.id;
+            if (!clientId)
                 return;
-            const arr = Array.isArray(subs) ? subs : [subs];
-            for (const s of arr) {
+            return guarded('unsubscribe', async () => {
+                const customerId = await customerFor('unsubscribe', clientId, client.username);
+                const arr = Array.isArray(unsubs) ? unsubs : [unsubs];
+                for (const topic of arr) {
+                    this.push({
+                        customerId,
+                        mqttTopic: this.topicLabel(typeof topic === 'string' ? topic : topic?.topic ?? ''),
+                        mqttQos: 0,
+                        mqttRetained: false,
+                        mqttEventType: 'UNSUBSCRIBE',
+                        mqttClientId: this.clientIdLabel(clientId),
+                        productType: options.productType,
+                        dataBytes: 0,
+                        metadata: options.resolveMetadata?.(clientId),
+                    }, brokerStatus(clientId), clientId);
+                }
+            });
+        });
+        broker.on('client', (client) => {
+            if (debounceMs > 0) {
+                const key = String(client?.id ?? '');
+                let session = sessions.get(key);
+                if (!session) {
+                    session = { live: 0, pending: null };
+                    sessions.set(key, session);
+                }
+                // Back inside the window, or a takeover of its own live session: same session, no CONNECT.
+                const sameSession = session.pending !== null || session.live > 0;
+                session.pending?.cancel();
+                session.pending = null;
+                session.live += 1;
+                if (sameSession)
+                    return;
+            }
+            return guarded('client', async () => {
+                const clientId = client?.id;
+                const customerId = await customerFor('client', clientId, client?.username);
                 this.push({
                     customerId,
-                    mqttTopic: this.topicLabel(s.topic),
-                    mqttQos: s.qos ?? 0,
+                    // CONNECT has no topic; mqttTopic is required. Built from the bounded
+                    // client id so the stand-in topic keeps its `/connected` suffix.
+                    mqttTopic: (0, exports.mqttConnectTopic)(this.clientIdLabel(clientId)),
+                    mqttQos: 0,
                     mqttRetained: false,
-                    mqttEventType: 'SUBSCRIBE',
+                    mqttEventType: 'CONNECT',
                     mqttClientId: this.clientIdLabel(clientId),
                     productType: options.productType,
                     dataBytes: 0,
                     metadata: options.resolveMetadata?.(clientId),
                 }, brokerStatus(clientId), clientId);
-            }
+            });
         });
-        broker.on('unsubscribe', async (unsubs, client) => {
-            const clientId = client?.id;
-            if (!clientId)
-                return;
-            const customerId = await resolveCustomer(clientId, client.username);
-            if (!customerId)
-                return;
-            const arr = Array.isArray(unsubs) ? unsubs : [unsubs];
-            for (const topic of arr) {
+        broker.on('clientDisconnect', (client) => {
+            const at = new Date();
+            const emit = () => guarded('clientDisconnect', async () => {
+                const clientId = client?.id;
+                const customerId = await customerFor('clientDisconnect', clientId, client?.username);
                 this.push({
                     customerId,
-                    mqttTopic: this.topicLabel(typeof topic === 'string' ? topic : topic?.topic ?? ''),
+                    mqttTopic: (0, exports.mqttDisconnectTopic)(this.clientIdLabel(clientId)),
                     mqttQos: 0,
                     mqttRetained: false,
-                    mqttEventType: 'UNSUBSCRIBE',
+                    mqttEventType: 'DISCONNECT',
                     mqttClientId: this.clientIdLabel(clientId),
                     productType: options.productType,
                     dataBytes: 0,
                     metadata: options.resolveMetadata?.(clientId),
-                }, brokerStatus(clientId), clientId);
+                }, brokerStatus(clientId), clientId, at);
+            });
+            if (debounceMs === 0)
+                return emit();
+            const key = String(client?.id ?? '');
+            const session = sessions.get(key) ?? { live: 1, pending: null };
+            session.live = Math.max(0, session.live - 1);
+            if (session.live > 0)
+                return; // a takeover: the session lives on in the new connection
+            // aedes sets _disconnected only for a DISCONNECT packet: a clean disconnect is billed at once.
+            if (client?._disconnected === true) {
+                sessions.delete(key);
+                return emit();
             }
-        });
-        broker.on('client', async (client) => {
-            const clientId = client.id;
-            const customerId = await resolveCustomer(clientId, client.username);
-            if (!customerId)
-                return;
-            this.push({
-                customerId,
-                // CONNECT has no topic; mqttTopic is required. Built from the bounded
-                // client id so the stand-in topic keeps its `/connected` suffix.
-                mqttTopic: (0, exports.mqttConnectTopic)(this.clientIdLabel(clientId)),
-                mqttQos: 0,
-                mqttRetained: false,
-                mqttEventType: 'CONNECT',
-                mqttClientId: this.clientIdLabel(clientId),
-                productType: options.productType,
-                dataBytes: 0,
-                metadata: options.resolveMetadata?.(clientId),
-            }, brokerStatus(clientId), clientId);
-        });
-        broker.on('clientDisconnect', async (client) => {
-            const clientId = client.id;
-            const customerId = await resolveCustomer(clientId, client.username);
-            if (!customerId)
-                return;
-            this.push({
-                customerId,
-                mqttTopic: (0, exports.mqttDisconnectTopic)(this.clientIdLabel(clientId)),
-                mqttQos: 0,
-                mqttRetained: false,
-                mqttEventType: 'DISCONNECT',
-                mqttClientId: this.clientIdLabel(clientId),
-                productType: options.productType,
-                dataBytes: 0,
-                metadata: options.resolveMetadata?.(clientId),
-            }, brokerStatus(clientId), clientId);
+            sessions.set(key, session);
+            session.pending = this.scheduleDisconnect(debounceMs, () => {
+                session.pending = null;
+                if (session.live === 0)
+                    sessions.delete(key);
+                return emit();
+            });
         });
     }
     // ── Client-side integration (mqtt.js) ───────────────────────────
     wrapMqttClient(client, options) {
         const clientId = options.clientId ?? client.options?.clientId ?? 'mqtt-client';
+        const debounceMs = checkDebounce(options?.reconnectDebounceMs, this.reconnectDebounceMs, 'wrapMqttClient');
+        let connected = false;
+        let pendingDisconnect = null;
         client.on('connect', () => {
+            if (pendingDisconnect) {
+                // Reconnected inside the window: the same session, nothing new to bill.
+                pendingDisconnect.cancel();
+                pendingDisconnect = null;
+                connected = true;
+                return;
+            }
+            if (connected && debounceMs > 0)
+                return;
+            connected = true;
             this.push({
                 customerId: options.customerId,
                 mqttTopic: (0, exports.mqttConnectTopic)(this.clientIdLabel(clientId)),
@@ -210,8 +318,14 @@ class AforoMqttBilling {
                 dataBytes: 0,
             }, options.executionStatus, clientId);
         });
+        // mqtt.js emits 'close' for every lost connection and for every failed
+        // reconnect attempt; only the end of a live connection can be a DISCONNECT.
         client.on('close', () => {
-            this.push({
+            if (!connected)
+                return;
+            connected = false;
+            const at = new Date();
+            const emit = () => this.push({
                 customerId: options.customerId,
                 mqttTopic: (0, exports.mqttDisconnectTopic)(this.clientIdLabel(clientId)),
                 mqttQos: 0,
@@ -220,7 +334,22 @@ class AforoMqttBilling {
                 mqttClientId: this.clientIdLabel(clientId),
                 productType: options.productType,
                 dataBytes: 0,
-            }, options.executionStatus, clientId);
+            }, options.executionStatus, clientId, at);
+            if (debounceMs === 0 || client.disconnecting === true) {
+                emit(); // the caller ended it: a clean disconnect
+                return;
+            }
+            pendingDisconnect = this.scheduleDisconnect(debounceMs, () => {
+                pendingDisconnect = null;
+                emit();
+            });
+        });
+        // end() while waiting for a reconnect: the session is over now.
+        client.on('end', () => {
+            const pending = pendingDisconnect;
+            pendingDisconnect = null;
+            if (pending)
+                void pending.fire();
         });
         client.on('message', (topic, payload, packet) => {
             this.push({
@@ -234,19 +363,38 @@ class AforoMqttBilling {
                 dataBytes: estimateBytes(payload),
             }, options.executionStatus, clientId);
         });
+        // PUBLISH is billed when mqtt.js reports success: the broker's PUBACK /
+        // PUBCOMP for QoS 1 / 2, the socket write for QoS 0. A publish that
+        // throws or whose callback gets an error is not billed. publishAsync()
+        // goes through publish(), so it is covered too.
         const origPublish = client.publish.bind(client);
         client.publish = (topic, message, opts, cb) => {
-            this.push({
-                customerId: options.customerId,
-                mqttTopic: this.topicLabel(topic),
-                mqttQos: opts?.qos ?? 0,
-                mqttRetained: !!opts?.retain,
-                mqttEventType: 'PUBLISH',
-                mqttClientId: this.clientIdLabel(clientId),
-                productType: options.productType,
-                dataBytes: estimateBytes(message),
-            }, options.executionStatus, clientId);
-            return origPublish(topic, message, opts, cb);
+            const optsIsCallback = typeof opts === 'function';
+            const userCallback = optsIsCallback ? opts : cb;
+            const publishOpts = optsIsCallback ? undefined : opts;
+            const at = new Date();
+            const done = (err, ...rest) => {
+                if (!err) {
+                    try {
+                        this.push({
+                            customerId: options.customerId,
+                            mqttTopic: this.topicLabel(topic),
+                            mqttQos: publishOpts?.qos ?? 0,
+                            mqttRetained: !!publishOpts?.retain,
+                            mqttEventType: 'PUBLISH',
+                            mqttClientId: this.clientIdLabel(clientId),
+                            productType: options.productType,
+                            dataBytes: estimateBytes(message),
+                        }, options.executionStatus, clientId, at);
+                    }
+                    catch (meterErr) {
+                        this.reportError(new Error(`[aforo-mqtt] publish metering failed: ${meterErr?.message ?? meterErr}`));
+                    }
+                }
+                if (typeof userCallback === 'function')
+                    return userCallback(err, ...rest);
+            };
+            return optsIsCallback ? origPublish(topic, message, done) : origPublish(topic, message, opts, done);
         };
     }
     // ── Event pipeline ──────────────────────────────────────────────
@@ -276,13 +424,12 @@ class AforoMqttBilling {
     }
     push(partial, executionStatus, 
     /** Untruncated client id for the idempotency key, when `partial.mqttClientId` was cut to the limit. */
-    keyClientId) {
+    keyClientId, 
+    /** When it happened, if not now (a debounced DISCONNECT, a confirmed PUBLISH). */
+    at) {
         if (!this.emitDeliverEvents && partial.mqttEventType === 'DELIVER')
             return;
-        // No customer resolved — not billable, not a drop.
-        if (typeof partial.customerId !== 'string' || !partial.customerId.trim())
-            return;
-        const now = new Date();
+        const now = at ?? new Date();
         const mqttClientId = typeof partial.mqttClientId === 'string' ? partial.mqttClientId : String(partial.mqttClientId ?? '');
         const event = {
             ...partial,
@@ -311,159 +458,85 @@ class AforoMqttBilling {
         // whole batch): it is dropped here with reason 'invalid', never thrown
         // into the broker / client handlers. mqttTopic is required on every
         // MQTT_BROKER event.
-        const invalid = tooLong('customerId', event.customerId, MAX_CUSTOMER_ID) ??
+        const invalid = (typeof event.customerId !== 'string' || !event.customerId.trim()
+            ? { field: 'customerId', problem: 'no customer: the customer resolver returned nothing (or customerId is blank); the event is not metered' }
+            : undefined) ??
+            tooLong('customerId', event.customerId, MAX_CUSTOMER_ID) ??
             requiredText('mqttTopic', event.mqttTopic) ??
             tooLong('mqttTopic', event.mqttTopic, MAX_MQTT_TOPIC) ??
             tooLong('mqttClientId', event.mqttClientId, MAX_MQTT_CLIENT_ID) ??
             tooLong('productType', event.productType, MAX_PRODUCT_TYPE);
         if (invalid) {
-            this.recordInvalid(event, invalid);
-            return;
-        }
-        this.buffer.push(event);
-        if (this.buffer.length >= this.flushCount) {
-            void this.flush();
-        }
-    }
-    async flush() {
-        if (this.buffer.length === 0)
+            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; // 1s, 2s, 4s
-            let res;
-            let networkError;
-            try {
-                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,
-                });
-            }
-            catch (err) {
-                networkError = err;
-            }
-            if (res) {
-                if (res.ok) {
-                    await this.handlePartialFailures(res, batch);
-                    return;
-                }
-                if (!isRetryableStatus(res.status)) {
-                    // 4xx other than 408/429: the same body would be refused again.
-                    const { details } = await readBatchResult(res, batch.length);
-                    this.recordDrop(batch, 'rejected');
-                    this.reportError(new Error(`MQTT metering batch rejected with HTTP ${res.status}${details ? ` — ${details}` : ''} (dropped ${batch.length} events, not retried)`));
-                    return;
-                }
-                delayMs = parseRetryAfter(res) ?? delayMs;
-            }
-            else if (attempt === maxRetries) {
-                this.recordDrop(batch, 'retry_exhausted');
-                this.reportError(networkError ?? new Error('MQTT metering request failed'));
-                return;
-            }
-            if (attempt < maxRetries)
-                await sleep(delayMs);
-        }
-        // Not re-queued: dropping avoids unbounded memory growth.
-        this.recordDrop(batch, 'retry_exhausted');
-        this.reportError(new Error(`MQTT metering flush failed after ${maxRetries} attempts (dropped ${batch.length} events)`));
-    }
-    /**
-     * A 2xx can still carry per-event rejections:
-     * `{accepted, duplicates, failed, errors:[{index, message}]}`. Events the
-     * response names by index are dropped with reason 'rejected'; a `failed`
-     * count the response does not attribute to an index is counted only.
-     */
-    async handlePartialFailures(res, batch) {
-        const { failed, details, indexes } = await readBatchResult(res, batch.length);
-        if (failed <= 0)
-            return;
-        if (indexes.length > 0)
-            this.recordDrop(indexes.map((i) => batch[i]), 'rejected');
-        const unattributed = Math.min(failed, batch.length) - indexes.length;
-        if (unattributed > 0) {
-            this.dropped += unattributed;
-            console.warn(`[aforo-mqtt] Dropped ${unattributed} event(s) — rejected, not identified by the ingestor (${this.dropped} total dropped).`);
-        }
-        this.reportError(new Error(`Aforo ingestor rejected ${failed} event(s)${details ? ` — ${details}` : ''}`));
+    /** Hold a DISCONNECT for `ms`; it is billed when the window passes unless cancelled. */
+    scheduleDisconnect(ms, emit) {
+        let done = false;
+        let timer;
+        const pending = {
+            fire: () => {
+                if (done)
+                    return Promise.resolve();
+                done = true;
+                if (timer)
+                    clearTimeout(timer);
+                this.pendingDisconnects.delete(pending);
+                return Promise.resolve()
+                    .then(emit)
+                    .catch((err) => this.reportError(new Error(`[aforo-mqtt] DISCONNECT metering failed: ${err?.message ?? err}`)));
+            },
+            cancel: () => {
+                done = true;
+                if (timer)
+                    clearTimeout(timer);
+                this.pendingDisconnects.delete(pending);
+            },
+        };
+        timer = setTimeout(() => void pending.fire(), ms);
+        timer.unref?.();
+        this.pendingDisconnects.add(pending);
+        return pending;
     }
     /** Invoke onError; a hook bug must never break metering or flushing. */
     reportError(err) {
         try {
             this.onError(err);
         }
-        catch {
-            // ignore
+        catch (hookErr) {
+            console.debug('[aforo-mqtt] onError hook threw', hookErr);
         }
     }
-    /** Number of events permanently dropped since this instance was created. */
+    /** Number of events permanently dropped since this instance was created (every DropReason). */
     get droppedCount() {
-        return this.dropped;
+        return this.core.droppedCount;
     }
-    /**
-     * Account for permanently lost events: bump the counter, WARN-log, and
-     * invoke the opt-in onDrop hook. The buffer is drained at flush start, so
-     * drops here are bounded by flush cadence — no log throttle needed.
-     */
-    recordDrop(events, reason) {
-        this.dropped += events.length;
-        console.warn(`[aforo-mqtt] Dropped ${events.length} event(s) — ${reason} (${this.dropped} total dropped).`);
-        this.notifyDrop(events, reason);
+    /** 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();
     }
     /**
-     * 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).
+     * 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). Call it from your SIGTERM handler.
      */
-    recordInvalid(event, invalid) {
-        this.dropped += 1;
-        const seen = (this.invalidSeen.get(invalid.field) ?? 0) + 1;
-        this.invalidSeen.set(invalid.field, seen);
-        if (seen === 1 || seen % 1000 === 0) {
-            console.warn(`[aforo-mqtt] Dropped 1 event — invalid: ${invalid.problem} ` +
-                `(${seen} for ${invalid.field}, ${this.dropped} total dropped).`);
-        }
-        this.notifyDrop([event], 'invalid');
-    }
-    notifyDrop(events, reason) {
-        if (!this.onDrop)
-            return;
-        try {
-            this.onDrop(events, reason);
-        }
-        catch {
-            // A hook bug must never break metering or flushing.
-        }
+    async shutdown() {
+        // A DISCONNECT still inside its reconnect window is billed now, not lost.
+        await Promise.all(Array.from(this.pendingDisconnects, (p) => p.fire()));
+        await this.core.shutdown();
     }
-    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 (typeof this.flushTimer.unref === 'function')
-            this.flushTimer.unref();
+    toJSON() {
+        return { tenantId: this.config.tenantId, productId: this.config.productId, queued: this.queuedCount, dropped: this.droppedCount };
     }
-    /** Flush any buffered events and stop the background timer. Call before process exit. */
-    async shutdown() {
-        if (this.flushTimer) {
-            clearInterval(this.flushTimer);
-            this.flushTimer = null;
-        }
-        await this.flush();
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return `AforoMqttBilling { tenantId: '${this.config.tenantId}', productId: '${this.config.productId}', queued: ${this.queuedCount}, dropped: ${this.droppedCount} }`;
     }
 }
 exports.AforoMqttBilling = AforoMqttBilling;
@@ -546,49 +619,6 @@ function requiredText(field, value) {
         return undefined;
     return { field, problem: `${field} is required and must not be blank: ${preview(value)}` };
 }
-/** Network errors, 408, 429 and 5xx are transient; every other 4xx (400/401/403/422...) is not. */
-function isRetryableStatus(status) {
-    return status === 408 || status === 429 || status >= 500;
-}
-/** 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 batch response body, if any: the `failed` count, the
- * first 5 `errors[].message` entries, and the batch indexes `errors[]` names.
- */
-async function readBatchResult(res, batchSize) {
-    const none = { failed: 0, details: '', indexes: [] };
-    if (typeof res?.json !== 'function')
-        return none;
-    try {
-        const body = unwrapEnvelope(await res.json());
-        const errors = Array.isArray(body?.errors) ? body.errors : undefined;
-        const details = errors
-            ? errors.slice(0, 5).map((e) => `#${e?.index}: ${e?.message}`).join('; ')
-            : typeof body?.message === 'string' ? body.message : '';
-        const indexes = [
-            ...new Set((errors ?? [])
-                .map((e) => e?.index)
-                .filter((i) => Number.isInteger(i) && i >= 0 && i < batchSize)),
-        ].sort((a, b) => a - b);
-        const failed = typeof body?.failed === 'number' && body.failed > 0 ? body.failed : 0;
-        return { failed, details, indexes };
-    }
-    catch {
-        return none; // Non-JSON or empty body — nothing to report.
-    }
-}
 /**
  * Cut `value` to at most `max` UTF-16 code units — how the ingestor counts
  * (`String.length()` in Java) — without leaving half a surrogate pair.
@@ -624,17 +654,12 @@ function boundedIdempotencyKey(head, component, tail) {
 function sha256Hex(text) {
     return (0, node_crypto_1.createHash)('sha256').update(text, 'utf8').digest('hex');
 }
+function textOrUndefined(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const text = String(value).trim();
+    return text ? text : undefined;
+}
 function randomSuffix() {
     return Math.random().toString(36).slice(2, 10);
 }
-function sleep(ms) {
-    return new Promise((r) => setTimeout(r, ms));
-}
-/**
- * The ingestor wraps every 2xx JSON body in `{success, data, meta}`. Returns
- * the inner `data` object when present, else the body unchanged (bare shape).
- */
-function unwrapEnvelope(body) {
-    const data = body && typeof body === 'object' && !Array.isArray(body) ? body.data : undefined;
-    return data && typeof data === 'object' && !Array.isArray(data) ? data : body;
-}