@aforoai/mqtt-metering 1.0.0 → 2.0.0

package/dist/index.js

@@ -27,16 +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;
-const SDK_VERSION = '1.0.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 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`
@@ -48,216 +66,382 @@ 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;
+const MAX_PRODUCT_TYPE = 20;
+const MAX_MQTT_TOPIC = 500;
+const MAX_MQTT_CLIENT_ID = 128;
 class AforoMqttBilling {
     config;
     productType;
-    flushCount;
-    flushIntervalMs;
     emitDeliverEvents;
     onError;
-    buffer = [];
-    flushTimer = null;
+    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.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));
-        broker.on('publish', async (packet, client) => {
+        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;
+        /**
+         * 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: packet.topic,
-                mqttQos: packet.qos ?? 0,
-                mqttRetained: !!packet.retain,
-                mqttEventType: 'PUBLISH',
-                mqttClientId: clientId,
-                productType: options.productType,
-                dataBytes: bytes,
-                metadata: options.resolveMetadata?.(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: 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',
-                    mqttClientId: clientId,
+                    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: typeof topic === 'string' ? topic : topic?.topic ?? '',
+                    mqttTopic: (0, exports.mqttDisconnectTopic)(this.clientIdLabel(clientId)),
                     mqttQos: 0,
                     mqttRetained: false,
-                    mqttEventType: 'UNSUBSCRIBE',
-                    mqttClientId: clientId,
+                    mqttEventType: 'DISCONNECT',
+                    mqttClientId: this.clientIdLabel(clientId),
                     productType: options.productType,
                     dataBytes: 0,
                     metadata: options.resolveMetadata?.(clientId),
-                });
-            }
-        });
-        broker.on('client', async (client) => {
-            const clientId = client.id;
-            const customerId = await resolveCustomer(clientId, client.username);
-            if (!customerId)
-                return;
-            this.push({
-                customerId,
-                mqttTopic: (0, exports.mqttConnectTopic)(clientId), // CONNECT has no topic; mqttTopic is required
-                mqttQos: 0,
-                mqttRetained: false,
-                mqttEventType: 'CONNECT',
-                mqttClientId: clientId,
-                productType: options.productType,
-                dataBytes: 0,
-                metadata: options.resolveMetadata?.(clientId),
+                }, brokerStatus(clientId), clientId, at);
             });
-        });
-        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)(clientId),
-                mqttQos: 0,
-                mqttRetained: false,
-                mqttEventType: 'DISCONNECT',
-                mqttClientId: clientId,
-                productType: options.productType,
-                dataBytes: 0,
-                metadata: options.resolveMetadata?.(clientId),
+            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();
+            }
+            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)(clientId),
+                mqttTopic: (0, exports.mqttConnectTopic)(this.clientIdLabel(clientId)),
                 mqttQos: 0,
                 mqttRetained: false,
                 mqttEventType: 'CONNECT',
-                mqttClientId: clientId,
+                mqttClientId: this.clientIdLabel(clientId),
                 productType: options.productType,
                 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)(clientId),
+                mqttTopic: (0, exports.mqttDisconnectTopic)(this.clientIdLabel(clientId)),
                 mqttQos: 0,
                 mqttRetained: false,
                 mqttEventType: 'DISCONNECT',
-                mqttClientId: clientId,
+                mqttClientId: this.clientIdLabel(clientId),
                 productType: options.productType,
                 dataBytes: 0,
+            }, 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({
                 customerId: options.customerId,
-                mqttTopic: topic,
+                mqttTopic: this.topicLabel(topic),
                 mqttQos: packet?.qos ?? 0,
                 mqttRetained: !!packet?.retain,
                 mqttEventType: 'DELIVER',
-                mqttClientId: clientId,
+                mqttClientId: this.clientIdLabel(clientId),
                 productType: options.productType,
                 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: topic,
-                mqttQos: opts?.qos ?? 0,
-                mqttRetained: !!opts?.retain,
-                mqttEventType: 'PUBLISH',
-                mqttClientId: clientId,
-                productType: options.productType,
-                dataBytes: estimateBytes(message),
-            });
-            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 ──────────────────────────────────────────────
-    push(partial) {
+    /**
+     * Bound an MQTT label (topic, client id) to the ingestor's limit. The event
+     * is still sent; one WARN per label name per client. Identity fields
+     * (customerId, productType) never go through here — an over-long one drops
+     * the event as 'invalid'.
+     */
+    requestLabel(field, value, max) {
+        if (typeof value !== 'string' || value.length <= max)
+            return value;
+        if (!this.truncationWarned.has(field)) {
+            this.truncationWarned.add(field);
+            console.warn(`[aforo-mqtt] ${field} was longer than the ingestor's limit and was ` +
+                `truncated to ${max} characters; the event is still sent. Logged once per label.`);
+        }
+        return truncateToLimit(value, max);
+    }
+    /** Topic off an incoming packet, bound to the ingestor's mqttTopic limit. */
+    topicLabel(topic) {
+        return typeof topic === 'string' ? this.requestLabel('mqttTopic', topic, MAX_MQTT_TOPIC) : topic;
+    }
+    /** Client id a connecting client chose, bound to the ingestor's mqttClientId limit. */
+    clientIdLabel(clientId) {
+        return typeof clientId === 'string' ? this.requestLabel('mqttClientId', clientId, MAX_MQTT_CLIENT_ID) : clientId;
+    }
+    push(partial, executionStatus, 
+    /** Untruncated client id for the idempotency key, when `partial.mqttClientId` was cut to the limit. */
+    keyClientId, 
+    /** When it happened, if not now (a debounced DISCONNECT, a confirmed PUBLISH). */
+    at) {
         if (!this.emitDeliverEvents && partial.mqttEventType === 'DELIVER')
             return;
-        if (!partial.customerId || !partial.customerId.trim())
-            return;
-        if (partial.customerId.length > MAX_CUSTOMER_ID) {
-            this.onError(new Error(`MQTT metering: customerId longer than ${MAX_CUSTOMER_ID} chars; event dropped`));
-            return;
-        }
-        const mqttTopic = partial.mqttTopic;
-        if (!mqttTopic || !mqttTopic.trim())
-            return; // mqttTopic is required on every MQTT_BROKER event
-        const now = new Date();
-        const mqttClientId = partial.mqttClientId.slice(0, 128);
+        const now = at ?? new Date();
+        const mqttClientId = typeof partial.mqttClientId === 'string' ? partial.mqttClientId : String(partial.mqttClientId ?? '');
         const event = {
             ...partial,
-            mqttTopic: mqttTopic.slice(0, 500),
             mqttQos: partial.mqttQos === 1 || partial.mqttQos === 2 ? partial.mqttQos : 0,
             mqttClientId,
             metricName: `mqtt_broker.${partial.mqttEventType.toLowerCase()}`,
             quantity: 1,
             occurredAt: now.toISOString(),
-            // Topic left out (it can be 500 chars); tail-trimmed to keep the unique millis:random suffix.
-            idempotencyKey: `mqtt:${this.config.tenantId}:${mqttClientId}:${partial.mqttEventType}:${now.getTime()}:${randomSuffix()}`.slice(-MAX_IDEMPOTENCY_KEY),
+            // Minted once, here, from the untruncated client id; the topic is left
+            // out. When the client id makes the key longer than the ingestor allows,
+            // it is replaced by its SHA-256 digest; the key itself is never cut.
+            idempotencyKey: boundedIdempotencyKey(`mqtt:${this.config.tenantId}:`, typeof keyClientId === 'string' ? keyClientId : mqttClientId, `:${partial.mqttEventType}:${now.getTime()}:${randomSuffix()}`),
             productType: normalizeProductType(partial.productType) ?? this.productType,
             metadata: {
                 ...(partial.metadata ?? {}),
@@ -265,82 +449,94 @@ class AforoMqttBilling {
                 productId: this.config.productId,
             },
         };
-        this.buffer.push(event);
-        if (this.buffer.length >= this.flushCount) {
-            void this.flush();
-        }
-    }
-    async flush() {
-        if (this.buffer.length === 0)
+        const checked = checkExecutionStatus(resolveExecutionStatus(executionStatus, event));
+        if (checked.problem)
+            this.reportError(new Error(`[aforo-mqtt] ${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 broker / client handlers. mqttTopic is required on every
+        // MQTT_BROKER event.
+        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.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(`MQTT 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(`MQTT metering flush failed after ${maxRetries} attempts (dropped ${batch.length} events)`));
+    /** 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;
     }
-    /** 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}` : ''}`));
+    /** Invoke onError; a hook bug must never break metering or flushing. */
+    reportError(err) {
+        try {
+            this.onError(err);
         }
-    }
-    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();
+        catch (hookErr) {
+            console.debug('[aforo-mqtt] onError hook threw', hookErr);
         }
-        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;
+    }
+    /** 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();
+    }
+    /**
+     * 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.
+     */
     async shutdown() {
-        if (this.flushTimer) {
-            clearInterval(this.flushTimer);
-            this.flushTimer = null;
-        }
-        await this.flush();
+        // 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();
+    }
+    toJSON() {
+        return { tenantId: this.config.tenantId, productId: this.config.productId, queued: this.queuedCount, dropped: this.droppedCount };
+    }
+    [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;
@@ -355,6 +551,51 @@ function estimateBytes(data) {
         return data.byteLength;
     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')
@@ -362,41 +603,63 @@ 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; identity 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 requiredText(field, value) {
+    if (typeof value === 'string' && value.trim())
+        return undefined;
+    return { field, problem: `${field} is required and must not be blank: ${preview(value)}` };
+}
+/**
+ * Cut `value` to at most `max` UTF-16 code units — how the ingestor counts
+ * (`String.length()` in Java) — without leaving half a surrogate pair.
+ */
+function truncateToLimit(value, max) {
+    if (value.length <= max)
+        return value;
+    let end = Math.max(0, max);
+    const last = end > 0 ? value.charCodeAt(end - 1) : 0;
+    // A high surrogate at the cut means its low half was cut off: drop it too.
+    if (last >= 0xd800 && last <= 0xdbff)
+        end -= 1;
+    return value.slice(0, end);
+}
+/**
+ * Build `head + component + tail`, where `component` is text taken from the
+ * incoming request and may be any length. Returned unchanged when it fits the
+ * ingestor's idempotencyKey limit; otherwise the component is replaced by the
+ * SHA-256 hex digest of its full, untruncated value (and, if the fixed parts
+ * alone are too long, `head + component` is). The key is never cut, so the
+ * unique tail always survives and two different components never share a key
+ * prefix by accident.
+ */
+function boundedIdempotencyKey(head, component, tail) {
+    const key = `${head}${component}${tail}`;
+    if (key.length <= MAX_IDEMPOTENCY_KEY)
+        return key;
+    const hashed = `${head}${sha256Hex(component)}${tail}`;
+    if (hashed.length <= MAX_IDEMPOTENCY_KEY)
+        return hashed;
+    return `${sha256Hex(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));
-}