@aforoai/mqtt-metering 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# @aforoai/mqtt-metering
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Meter MQTT traffic into Aforo two ways: hook an Aedes broker you operate to meter every PUBLISH/SUBSCRIBE/CONNECT/DISCONNECT, or wrap an `mqtt.js` client to meter what it publishes and receives against a third-party broker (AWS IoT, HiveMQ Cloud, EMQ X Cloud).
+
+**Version:** 1.0.0 · Apache-2.0 · [Changelog](CHANGELOG.md) · [User guide](USER_GUIDE.md)
+
+| Mode | When to use | Entry point |
+|---|---|---|
+| **Broker hook** | You run the broker (Aedes) and want to meter every client's events | `wrapAedesBroker(broker, options)` |
+| **Client proxy** | You consume a third-party broker and want client-side billing | `wrapMqttClient(client, options)` |
+
+## Install
+
+Intended public install (once published):
+
+```bash
+npm i @aforoai/mqtt-metering aedes   # broker mode
+# or
+npm i @aforoai/mqtt-metering mqtt    # client mode
+```
+
+> **Not yet on the public npm registry — install from source for now.** `aedes` and `mqtt` are **optional** peer dependencies — install only the one your mode needs.
+
+```bash
+# from the SDKs repo root
+cd SDKs/aforo-metering-sdks/node-mqtt
+npm install
+npm run build          # tsc → dist/
+
+# then, from YOUR app
+npm install /absolute/path/to/aforo-metering-sdks/node-mqtt
+npm install aedes      # broker mode, OR:
+npm install mqtt       # client mode
+```
+
+## Quickstart
+
+**Broker mode (Aedes):**
+
+```ts
+import aedes from 'aedes';
+import { createServer } from 'net';
+import { AforoMqttBilling } from '@aforoai/mqtt-metering';
+
+const billing = new AforoMqttBilling({
+  tenantId: 'tenant_acme',
+  productId: 'prod_mqtt_001',
+  apiKey: process.env.AFORO_API_KEY!,
+  ingestorUrl: 'https://api.aforo.ai', // SDK appends /v1/ingest/batch
+});
+
+const broker = aedes();
+billing.wrapAedesBroker(broker, {
+  resolveCustomerId: async (clientId, username) => customerStore.byClientId(clientId),
+  resolveMetadata: (clientId) => ({ deviceClass: deviceRegistry.classOf(clientId) }),
+});
+
+createServer(broker.handle).listen(1883);
+process.on('SIGTERM', async () => { await billing.shutdown(); });
+```
+
+**Client mode (`mqtt.js`):**
+
+```ts
+import mqtt from 'mqtt';
+import { AforoMqttBilling } from '@aforoai/mqtt-metering';
+
+const billing = new AforoMqttBilling({ tenantId: 'tenant_acme', productId: 'prod_mqtt_001', apiKey: process.env.AFORO_API_KEY!, ingestorUrl: 'https://api.aforo.ai' });
+const client = mqtt.connect('mqtts://broker.example.com', { clientId: `device-${deviceId}` });
+
+billing.wrapMqttClient(client, { customerId: 'cust_acme_001' });
+```
+
+Each event uses `metricName: "mqtt_broker.<event>"` (`mqtt_broker.publish`, `mqtt_broker.subscribe`, …) with `quantity: 1`, and carries `mqttTopic`, `mqttQos`, `mqttRetained`, `mqttClientId`, and `dataBytes`. Events ship to `POST https://api.aforo.ai/v1/ingest/batch` with `X-API-Key: <api_key>` and `X-Tenant-Id: <tenant_id>`.
+
+> **`DELIVER` (fan-out) events are dropped unless `emitDeliverEvents: true`.** This gate applies in **both** modes — client-mode inbound `message` deliveries and any broker delivery path are skipped by default because fan-out is high-volume. `PUBLISH`, `SUBSCRIBE`, `UNSUBSCRIBE`, `CONNECT`, and `DISCONNECT` are always metered.
+
+## Configuration
+
+`new AforoMqttBilling(config)` — `tenantId`, `productId`, `apiKey`, and `ingestorUrl` are required.
+
+| Option | Type | Default | What it does |
+|---|---|---|---|
+| `tenantId` | `string` | — (required) | Aforo tenant. Sent as `X-Tenant-Id`. Never read from a client header. |
+| `productId` | `string` | — (required) | Aforo product id; into each event's `metadata.productId`. |
+| `apiKey` | `string` | — (required) | Sent as `X-API-Key: <apiKey>`. |
+| `ingestorUrl` | `string` | — (required) | Ingestion base URL. SDK appends `/v1/ingest/batch`. Use `https://api.aforo.ai`. |
+| `productType` | `string` | `'MQTT_BROKER'` | Aforo product type sent as top-level `productType` on every event (trimmed + uppercased; unknown values pass through). Override via `wrapAedesBroker(broker, { productType })` or `wrapMqttClient(client, { customerId, productType })`. |
+| `emitDeliverEvents` | `boolean` | `false` | Emit a `DELIVER` event per fan-out delivery. Off → `DELIVER` events are dropped (both modes). |
+| `flushCount` | `number` | `200` | Buffered events that trigger an immediate flush. Highest default of the SDKs — MQTT is very high-volume. |
+| `flushIntervalMs` | `number` | `2000` | Max ms before a partial batch is flushed. |
+| `onError` | `(error: Error) => void` | logs to `console.error` | Called when a batch is dropped: after 3 attempts on network errors / 408 / 429 (honouring `Retry-After`) / 5xx, immediately on any other 4xx (not retried), and when a 202 reports per-event failures (`errors[].message`). |
+
+Mode-specific options:
+
+| Option | Mode | Type | What it does |
+|---|---|---|---|
+| `resolveCustomerId` | broker | `(clientId, username?) => string \| undefined \| Promise<…>` | Required. Map an MQTT client id to a customer. `undefined` → that client's events are not metered. |
+| `resolveMetadata` | broker | `(clientId) => Record<string, unknown> \| undefined` | Optional per-client tags. |
+| `customerId` | client | `string` | Customer to attribute all traffic on this client to. |
+| `clientId` | client | `string` | Fixed client id (defaults to `client.options.clientId`, then `'mqtt-client'`). |
+| `productType` | both | `string` | Product type for this broker's / client's events. Default: the client-level `productType`. |
+
+Every event carries `mqttQos` (0/1/2) and `mqttRetained` — use them in Aforo rate-plan filter conditions to price QoS ≥ 1 or retained messages separately.
+
+Exported symbols: `AforoMqttBilling` (with `wrapAedesBroker` / `wrapMqttClient` / `shutdown`) and the `AforoMqttConfig` / `AedesBrokerOptions` / `MqttClientOptions` types.
+
+## Walk me through it
+
+Step-by-step from install to a verified event in Aforo: [USER_GUIDE.md](USER_GUIDE.md).
+
+## What this doesn't cover
+
+- **Fan-out billing is opt-in.** `DELIVER` events are dropped unless `emitDeliverEvents: true`. Default metering counts the PUBLISH, not the per-subscriber fan-out.
+- **CONNECT/DISCONNECT have no MQTT topic.** Because the ingestor requires `mqttTopic`, they are sent with `$SYS/clients/<clientId>/connected` and `$SYS/clients/<clientId>/disconnected`. `$SYS/` is reserved for brokers, so these topics can't collide with a real one.
+- **Client-mode CONNECT/DISCONNECT use socket lifecycle.** `wrapMqttClient` maps `connect`/`close`; a client that reconnects emits a CONNECT each time.
+- **No persistent buffer.** Events are in memory until flushed; a hard crash before flush drops the buffered batch. `shutdown()` covers graceful exit only.
+- **The SDK does not enforce or read pricing.** It emits usage; rating/billing happens in Aforo.

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @aforoai/mqtt-metering — Aforo MQTT Metering SDK
+ *
+ * Two integration modes:
+ *
+ *   1. **Broker hook** (preferred) — wrapAedesBroker() attaches to every PUBLISH,
+ *      SUBSCRIBE, UNSUBSCRIBE, CONNECT, DISCONNECT event flowing through an
+ *      Aedes broker instance. Use this when you operate the broker yourself.
+ *
+ *   2. **Client proxy** — wrapMqttClient() wraps an mqtt.js client to meter
+ *      outbound publishes + inbound deliveries from the client's perspective.
+ *      Use this when you consume a third-party broker (AWS IoT, HiveMQ Cloud,
+ *      EMQ X Cloud) and need client-side billing.
+ *
+ * Usage (Aedes broker):
+ *   import aedes from 'aedes';
+ *   import { AforoMqttBilling } from '@aforoai/mqtt-metering';
+ *
+ *   const billing = new AforoMqttBilling({
+ *     tenantId: 'tenant_acme',
+ *     productId: 'prod_mqtt_telemetry',
+ *     apiKey: process.env.AFORO_API_KEY!,
+ *     ingestorUrl: 'https://api.aforo.ai',
+ *     // productType defaults to 'MQTT_BROKER'
+ *   });
+ *
+ *   const broker = aedes();
+ *   billing.wrapAedesBroker(broker, {
+ *     resolveCustomerId: (clientId) => customerIdLookup(clientId),
+ *   });
+ */
+export interface AforoMqttConfig {
+    tenantId: string;
+    productId: string;
+    apiKey: string;
+    ingestorUrl: string;
+    /**
+     * Aforo product type sent as top-level `productType` on every event (trimmed + uppercased).
+     * Default: `MQTT_BROKER`. Override per integration via `wrapAedesBroker(broker, { productType })` / `wrapMqttClient(client, { productType })`.
+     */
+    productType?: string;
+    /** How many events to buffer before flushing (default 200 — MQTT is very high-volume). */
+    flushCount?: number;
+    /** Max interval in ms before a partial batch is flushed (default 2000). */
+    flushIntervalMs?: number;
+    /** Emit one event per fanout delivery in addition to the publish (default false — costly). */
+    emitDeliverEvents?: boolean;
+    /** Callback for terminal flush failures. */
+    onError?: (error: Error) => void;
+}
+export interface AedesBrokerOptions {
+    /** Map an MQTT client ID to an Aforo customer ID. Required. */
+    resolveCustomerId: (clientId: string, username?: string) => string | undefined | Promise<string | undefined>;
+    /** Optional per-client metadata (tags, device type). */
+    resolveMetadata?: (clientId: string) => Record<string, unknown> | undefined;
+    /** Product type for events from this broker. Default: the client-level `productType`. */
+    productType?: string;
+}
+export interface MqttClientOptions {
+    /** Customer ID to attribute all traffic on this client to. */
+    customerId: string;
+    /** Fixed client identifier (defaults to mqtt.js connection options.clientId). */
+    clientId?: string;
+    /** Product type for events from this client. Default: the client-level `productType`. */
+    productType?: string;
+}
+/** Default top-level `productType` for this SDK. */
+export declare const DEFAULT_PRODUCT_TYPE = "MQTT_BROKER";
+/**
+ * mqttTopic is required on every MQTT_BROKER event, but CONNECT / DISCONNECT
+ * have no topic. These per-client `$SYS/clients/<id>/connected|disconnected`
+ * topics stand in for them (`$SYS/` is reserved for the broker by the MQTT
+ * spec, so they can never collide with a client topic). Same topics as the
+ * Python, Go and Java SDKs.
+ */
+export declare const mqttConnectTopic: (clientId: string) => string;
+export declare const mqttDisconnectTopic: (clientId: string) => string;
+/** Minimal Aedes broker surface — matches the `aedes` package. */
+interface MinimalAedes {
+    on(event: 'publish', fn: (packet: any, client: any) => void): void;
+    on(event: 'subscribe', fn: (subs: any[] | any, client: any) => void): void;
+    on(event: 'unsubscribe', fn: (unsubs: any[] | any, client: any) => void): void;
+    on(event: 'client', fn: (client: any) => void): void;
+    on(event: 'clientDisconnect', fn: (client: any) => void): void;
+}
+/** Minimal mqtt.js client surface. */
+interface MinimalMqttClient {
+    on(event: 'message', fn: (topic: string, payload: Buffer, packet: any) => void): void;
+    on(event: 'connect', fn: () => void): void;
+    on(event: 'close', fn: () => void): void;
+    publish: (topic: string, message: any, opts?: any, cb?: any) => any;
+    options?: {
+        clientId?: string;
+    };
+}
+export declare class AforoMqttBilling {
+    private readonly config;
+    private readonly productType;
+    private readonly flushCount;
+    private readonly flushIntervalMs;
+    private readonly emitDeliverEvents;
+    private readonly onError;
+    private buffer;
+    private flushTimer;
+    constructor(config: AforoMqttConfig);
+    wrapAedesBroker(broker: MinimalAedes, options: AedesBrokerOptions): void;
+    wrapMqttClient(client: MinimalMqttClient, options: MqttClientOptions): void;
+    private push;
+    private flush;
+    private send;
+    /** A 202 can still carry per-event rejections: `{accepted, duplicates, failed, errors:[{index, message}]}`. */
+    private reportPartialFailures;
+    private startTimer;
+    shutdown(): Promise<void>;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,402 @@
+"use strict";
+/**
+ * @aforoai/mqtt-metering — Aforo MQTT Metering SDK
+ *
+ * Two integration modes:
+ *
+ *   1. **Broker hook** (preferred) — wrapAedesBroker() attaches to every PUBLISH,
+ *      SUBSCRIBE, UNSUBSCRIBE, CONNECT, DISCONNECT event flowing through an
+ *      Aedes broker instance. Use this when you operate the broker yourself.
+ *
+ *   2. **Client proxy** — wrapMqttClient() wraps an mqtt.js client to meter
+ *      outbound publishes + inbound deliveries from the client's perspective.
+ *      Use this when you consume a third-party broker (AWS IoT, HiveMQ Cloud,
+ *      EMQ X Cloud) and need client-side billing.
+ *
+ * Usage (Aedes broker):
+ *   import aedes from 'aedes';
+ *   import { AforoMqttBilling } from '@aforoai/mqtt-metering';
+ *
+ *   const billing = new AforoMqttBilling({
+ *     tenantId: 'tenant_acme',
+ *     productId: 'prod_mqtt_telemetry',
+ *     apiKey: process.env.AFORO_API_KEY!,
+ *     ingestorUrl: 'https://api.aforo.ai',
+ *     // productType defaults to 'MQTT_BROKER'
+ *   });
+ *
+ *   const broker = aedes();
+ *   billing.wrapAedesBroker(broker, {
+ *     resolveCustomerId: (clientId) => customerIdLookup(clientId),
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AforoMqttBilling = exports.mqttDisconnectTopic = exports.mqttConnectTopic = exports.DEFAULT_PRODUCT_TYPE = void 0;
+const SDK_VERSION = '1.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`
+ * topics stand in for them (`$SYS/` is reserved for the broker by the MQTT
+ * spec, so they can never collide with a client topic). Same topics as the
+ * Python, Go and Java SDKs.
+ */
+const mqttConnectTopic = (clientId) => `$SYS/clients/${clientId || 'unknown'}/connected`;
+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;
+class AforoMqttBilling {
+    config;
+    productType;
+    flushCount;
+    flushIntervalMs;
+    emitDeliverEvents;
+    onError;
+    buffer = [];
+    flushTimer = null;
+    constructor(config) {
+        this.config = {
+            tenantId: config.tenantId,
+            productId: config.productId,
+            apiKey: config.apiKey,
+            ingestorUrl: config.ingestorUrl,
+        };
+        this.productType = normalizeProductType(config.productType) ?? exports.DEFAULT_PRODUCT_TYPE;
+        this.flushCount = config.flushCount ?? 200;
+        this.flushIntervalMs = config.flushIntervalMs ?? 2000;
+        this.emitDeliverEvents = config.emitDeliverEvents ?? false;
+        this.onError = config.onError ?? ((err) => console.error('[aforo-mqtt]', err.message));
+        this.startTimer();
+    }
+    // ── Broker-side integration (Aedes) ─────────────────────────────
+    wrapAedesBroker(broker, options) {
+        const resolveCustomer = async (clientId, username) => Promise.resolve(options.resolveCustomerId(clientId, username));
+        broker.on('publish', async (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),
+            });
+        });
+        broker.on('subscribe', async (subs, client) => {
+            const clientId = client?.id;
+            if (!clientId)
+                return;
+            const customerId = await resolveCustomer(clientId, client.username);
+            if (!customerId)
+                return;
+            const arr = Array.isArray(subs) ? subs : [subs];
+            for (const s of arr) {
+                this.push({
+                    customerId,
+                    mqttTopic: s.topic,
+                    mqttQos: s.qos ?? 0,
+                    mqttRetained: false,
+                    mqttEventType: 'SUBSCRIBE',
+                    mqttClientId: clientId,
+                    productType: options.productType,
+                    dataBytes: 0,
+                    metadata: options.resolveMetadata?.(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) {
+                this.push({
+                    customerId,
+                    mqttTopic: typeof topic === 'string' ? topic : topic?.topic ?? '',
+                    mqttQos: 0,
+                    mqttRetained: false,
+                    mqttEventType: 'UNSUBSCRIBE',
+                    mqttClientId: 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),
+            });
+        });
+        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),
+            });
+        });
+    }
+    // ── Client-side integration (mqtt.js) ───────────────────────────
+    wrapMqttClient(client, options) {
+        const clientId = options.clientId ?? client.options?.clientId ?? 'mqtt-client';
+        client.on('connect', () => {
+            this.push({
+                customerId: options.customerId,
+                mqttTopic: (0, exports.mqttConnectTopic)(clientId),
+                mqttQos: 0,
+                mqttRetained: false,
+                mqttEventType: 'CONNECT',
+                mqttClientId: clientId,
+                productType: options.productType,
+                dataBytes: 0,
+            });
+        });
+        client.on('close', () => {
+            this.push({
+                customerId: options.customerId,
+                mqttTopic: (0, exports.mqttDisconnectTopic)(clientId),
+                mqttQos: 0,
+                mqttRetained: false,
+                mqttEventType: 'DISCONNECT',
+                mqttClientId: clientId,
+                productType: options.productType,
+                dataBytes: 0,
+            });
+        });
+        client.on('message', (topic, payload, packet) => {
+            this.push({
+                customerId: options.customerId,
+                mqttTopic: topic,
+                mqttQos: packet?.qos ?? 0,
+                mqttRetained: !!packet?.retain,
+                mqttEventType: 'DELIVER',
+                mqttClientId: clientId,
+                productType: options.productType,
+                dataBytes: estimateBytes(payload),
+            });
+        });
+        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);
+        };
+    }
+    // ── Event pipeline ──────────────────────────────────────────────
+    push(partial) {
+        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 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),
+            productType: normalizeProductType(partial.productType) ?? this.productType,
+            metadata: {
+                ...(partial.metadata ?? {}),
+                sdkVersion: SDK_VERSION,
+                productId: this.config.productId,
+            },
+        };
+        this.buffer.push(event);
+        if (this.buffer.length >= this.flushCount) {
+            void this.flush();
+        }
+    }
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        const pending = this.buffer.splice(0, this.buffer.length);
+        // The ingestor accepts at most MAX_BATCH_EVENTS events per request.
+        for (let i = 0; i < pending.length; i += MAX_BATCH_EVENTS) {
+            await this.send(pending.slice(i, i + MAX_BATCH_EVENTS));
+        }
+    }
+    async send(batch) {
+        // Serialized once, so every retry re-sends the same idempotencyKeys.
+        const body = JSON.stringify({ events: batch });
+        const maxRetries = 3;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            let delayMs = Math.pow(2, attempt - 1) * 1000;
+            try {
+                const res = await fetch(this.config.ingestorUrl.replace(/\/$/, '') + '/v1/ingest/batch', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-API-Key': this.config.apiKey,
+                        'X-Tenant-Id': this.config.tenantId,
+                    },
+                    body,
+                });
+                if (res.ok) {
+                    await this.reportPartialFailures(res);
+                    return;
+                }
+                if (!isRetryableStatus(res.status)) {
+                    const { details } = await readErrorMessages(res);
+                    this.onError(new Error(`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)`));
+    }
+    /** A 202 can still carry per-event rejections: `{accepted, duplicates, failed, errors:[{index, message}]}`. */
+    async reportPartialFailures(res) {
+        const { failed, details } = await readErrorMessages(res);
+        if (failed && failed > 0) {
+            this.onError(new Error(`Aforo ingestor rejected ${failed} event(s)${details ? ` — ${details}` : ''}`));
+        }
+    }
+    startTimer() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setInterval(() => { void this.flush(); }, this.flushIntervalMs);
+        // Unref so the background timer never blocks host-process exit (final flush still needs shutdown()).
+        if (this.flushTimer && typeof this.flushTimer === 'object' && 'unref' in this.flushTimer) {
+            this.flushTimer.unref();
+        }
+        if (typeof this.flushTimer.unref === 'function')
+            this.flushTimer.unref();
+    }
+    async shutdown() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flush();
+    }
+}
+exports.AforoMqttBilling = AforoMqttBilling;
+function estimateBytes(data) {
+    if (data == null)
+        return 0;
+    if (typeof data === 'string')
+        return Buffer.byteLength(data, 'utf8');
+    if (Buffer.isBuffer?.(data))
+        return data.length;
+    if (data?.byteLength != null)
+        return data.byteLength;
+    return 0;
+}
+/** Trim + uppercase a product type; blank/non-string → undefined (unknown values pass through). */
+function normalizeProductType(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed.toUpperCase() : undefined;
+}
+/** Network errors, 408, 429 and 5xx are transient; every other 4xx (400/401/403/422...) is not. */
+function isRetryableStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+/** Retry-After (delta-seconds or HTTP date) in ms, capped at MAX_RETRY_AFTER_MS. */
+function parseRetryAfter(res) {
+    const raw = res?.headers?.get?.('retry-after');
+    if (!raw)
+        return undefined;
+    const secs = Number(raw);
+    if (Number.isFinite(secs) && secs >= 0)
+        return Math.min(secs * 1000, MAX_RETRY_AFTER_MS);
+    const date = Date.parse(raw);
+    if (!Number.isNaN(date))
+        return Math.min(Math.max(date - Date.now(), 0), MAX_RETRY_AFTER_MS);
+    return undefined;
+}
+/** Reads the ingestor's `errors[].message` entries (first 5) from a response body, if any. */
+async function readErrorMessages(res) {
+    if (typeof res?.json !== 'function')
+        return { details: '' };
+    try {
+        const body = await res.json();
+        const details = Array.isArray(body?.errors)
+            ? body.errors.slice(0, 5).map((e) => `#${e?.index}: ${e?.message}`).join('; ')
+            : typeof body?.message === 'string' ? body.message : '';
+        return { failed: typeof body?.failed === 'number' ? body.failed : undefined, details };
+    }
+    catch {
+        return { details: '' }; // Non-JSON or empty body — nothing to report.
+    }
+}
+function randomSuffix() {
+    return Math.random().toString(36).slice(2, 10);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@aforoai/mqtt-metering",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Aforo MQTT Metering SDK — aedes broker hooks + mqtt.js client wrapper that meters PUBLISH/DELIVER/SUBSCRIBE/CONNECT/DISCONNECT events to Aforo.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --testEnvironment=node",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "aforo",
+    "billing",
+    "mqtt",
+    "aedes",
+    "iot",
+    "metering",
+    "pub-sub"
+  ],
+  "author": "Aforo, Inc.",
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "mqtt": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "aedes": {
+      "optional": true
+    },
+    "mqtt": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "aedes": "^0.51.3",
+    "jest": "^29.7.0",
+    "mqtt": "^5.15.1",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aforoai/SDKs.git",
+    "directory": "aforo-metering-sdks/node-mqtt"
+  },
+  "homepage": "https://github.com/aforoai/SDKs/tree/main/aforo-metering-sdks/node-mqtt#readme",
+  "bugs": {
+    "url": "https://github.com/aforoai/SDKs/issues"
+  }
+}