@aforoai/metering 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# @aforoai/metering
+
+Track API usage from your Node service and send it to Aforo for billing. A buffered, batched, retrying client plus drop-in Express / Fastify / Koa middleware — `track()` returns immediately and events flush in the background, so metering never sits in your request path.
+
+**Version:** 1.0.0 · Apache-2.0 · [Changelog](CHANGELOG.md) · [User guide](USER_GUIDE.md)
+
+## Install
+
+```bash
+npm i @aforoai/metering
+```
+
+> **Not yet on the public npm registry.** Until it's published, install from source:
+> ```bash
+> git clone https://github.com/aforoai/SDKs.git
+> cd SDKs/aforo-metering-sdks/node
+> npm install && npm run build
+> npm pack        # produces aforo-metering-1.0.0.tgz to install in your app
+> # then in your app: npm i /path/to/aforo-metering-1.0.0.tgz
+> ```
+
+Requires Node >= 18 (uses the built-in `fetch`).
+
+## Quickstart
+
+Meter a single event:
+
+```ts
+import { AforoClient } from '@aforoai/metering';
+
+const aforo = new AforoClient({ apiKey: process.env.AFORO_API_KEY!, productType: 'API' });
+
+await aforo.track({ customerId: 'cust_123', metricName: 'api_calls', quantity: 1 });
+
+// Flush remaining events before the process exits:
+await aforo.shutdown();
+```
+
+Or meter every HTTP request with middleware — no per-route code:
+
+```ts
+import { expressMiddleware } from '@aforoai/metering/middleware/express';
+
+app.use(expressMiddleware({
+  apiKey: process.env.AFORO_API_KEY!,
+  customerId: (req) => req.user?.id ?? null,   // return null to skip metering this request
+  metricName: 'api_calls',                      // or (req, res) => string; must exist in your Aforo catalog
+  productType: 'API',                           // default: the client default ("API")
+}));
+```
+
+The middleware hooks `res.on('finish')`, so it runs after the response is sent — zero added latency.
+
+- **Metric:** `metricName` is a fixed name or a `(req, res) => string` resolver; the default is `"api_calls"` (exported as `DEFAULT_METRIC_NAME`). The metric must exist in your tenant's Aforo catalog: the ingestor rejects an unknown `metricName`, and because it validates a batch as a whole, one rejected event fails every event in that batch.
+- **Customer:** `customerId` is a fixed id or a `(req) => string | null` resolver; the default is `req.user.id` / `req.user.sub`, then the `X-Customer-Id` header. The caller's `X-Api-Key` header is never used — it is the end user's secret, not a customer id. Requests with no customer are not metered.
+- **CORS preflights** (`OPTIONS`) are never metered, nor are requests whose quantity is `<= 0`.
+- **HTTP context:** each event carries top-level `endpointPath` (path without query string, max 512 chars), `httpMethod`, `statusCode` and `responseTimeMs`, plus `productType`.
+
+## Configuration
+
+`new AforoClient(options)` — `options: AforoOptions`:
+
+| Option | Type | Default | What it does |
+|---|---|---|---|
+| `apiKey` | `string` | — (required) | Aforo API key, sent as `X-API-Key`. |
+| `baseUrl` | `string` | `https://api.aforo.ai` | Ingestor base URL. Events POST to `<baseUrl>/v1/ingest/batch`. |
+| `productType` | `string` | `"API"` | Top-level `productType` stamped on every event (required by the ingestor). One of `API`, `AGENTIC_API`, `AI_AGENT`, `MCP_SERVER`, `GRPC_API`, `GRAPHQL_API`, `WEBSOCKET_API`, `MQTT_BROKER`; trimmed and uppercased. |
+| `flushCount` | `number` | `50` | Buffered events that trigger a flush (and events per request; capped at 1000). |
+| `flushInterval` | `number` (ms) | `5000` | Background flush cadence. |
+| `maxQueueSize` | `number` | `10000` | Ring-buffer cap; oldest events drop on overflow. |
+| `maxRetries` | `number` | `3` | Retries on 5xx/timeout (exponential backoff). |
+| `retryBaseMs` | `number` (ms) | `1000` | Base backoff delay. |
+| `timeout` | `number` (ms) | `10000` | Per-request timeout. |
+| `shutdownTimeoutMs` | `number` (ms) | `5000` | Max time `shutdown()` waits for a final flush. |
+
+`track(event)` — `event: TrackEvent`: `customerId` (required, non-blank), `metricName` (required, non-blank), `quantity` (default 1, must be > 0 — otherwise `track()` throws), `productType` (overrides the client default for this event), `idempotencyKey` (a fresh random UUID v4 per event if omitted — pass your own key if you want the ingestor to deduplicate retries), `occurredAt` (ISO string or epoch ms; defaults to now), `metadata` (string/number/boolean map).
+
+### Sessions
+
+`startSession(sessionId, productType = 'AI_AGENT')` sends a `system.session.heartbeat` event immediately and every 30s; `endSession()` sends a final `SESSION_END` heartbeat and flushes buffered usage. Heartbeats carry quantity 1, top-level `sessionId`/`productType`/`sessionBoundary`, and customer `system`; the ingestor intercepts them before billing. Each one goes in its own request, never inside a usage batch, and is best-effort (no retries; failures never affect usage delivery). The timer does not keep the process alive and stops on `endSession()`/`shutdown()`.
+
+## Walk me through it
+
+Step-by-step from install to a verified event in Aforo: see the **[User guide](USER_GUIDE.md)**.
+
+## What this doesn't cover
+
+This SDK only *emits* usage. Pricing, rate plans, and which `metricName`s are billable are configured in the Aforo console — this package does not create or validate them. A `metricName` that isn't defined in your tenant is **rejected** by the ingestor — and fails the whole batch it travels in — so define the metric before sending it.

package/dist/cjs/buffer.d.ts

@@ -0,0 +1,27 @@
+import { ResolvedEvent } from './types';
+/**
+ * Bounded ring buffer for usage events.
+ * Thread-safe for Node.js single-threaded event loop.
+ * When full, the oldest event is dropped (FIFO overflow).
+ */
+export declare class RingBuffer {
+    private readonly items;
+    private readonly capacity;
+    private head;
+    private tail;
+    private count;
+    constructor(capacity?: number);
+    /** Add an event to the buffer. Returns true if added, false if overflow (oldest dropped). */
+    push(event: ResolvedEvent): boolean;
+    /** Drain all events from the buffer. Returns a new array and clears the buffer. */
+    drain(): ResolvedEvent[];
+    /** Drain up to `max` events from the front of the buffer. */
+    drainUpTo(max: number): ResolvedEvent[];
+    /** Current number of events in the buffer. */
+    get size(): number;
+    /** Whether the buffer is empty. */
+    get isEmpty(): boolean;
+    /** Whether the buffer is at capacity. */
+    get isFull(): boolean;
+}
+//# sourceMappingURL=buffer.d.ts.map

package/dist/cjs/buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../src/buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExC;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,KAAK,CAAK;gBAEN,QAAQ,GAAE,MAAe;IAMrC,6FAA6F;IAC7F,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO;IAiBnC,mFAAmF;IACnF,KAAK,IAAI,aAAa,EAAE;IAgBxB,6DAA6D;IAC7D,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,EAAE;IAgBvC,8CAA8C;IAC9C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mCAAmC;IACnC,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,yCAAyC;IACzC,IAAI,MAAM,IAAI,OAAO,CAEpB;CACF"}

package/dist/cjs/buffer.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RingBuffer = void 0;
+/**
+ * Bounded ring buffer for usage events.
+ * Thread-safe for Node.js single-threaded event loop.
+ * When full, the oldest event is dropped (FIFO overflow).
+ */
+class RingBuffer {
+    constructor(capacity = 10000) {
+        this.head = 0;
+        this.tail = 0;
+        this.count = 0;
+        if (capacity < 1)
+            throw new Error('Buffer capacity must be >= 1');
+        this.capacity = capacity;
+        this.items = new Array(capacity);
+    }
+    /** Add an event to the buffer. Returns true if added, false if overflow (oldest dropped). */
+    push(event) {
+        let overflow = false;
+        if (this.count === this.capacity) {
+            // Buffer full — drop oldest (advance head)
+            this.head = (this.head + 1) % this.capacity;
+            this.count--;
+            overflow = true;
+        }
+        this.items[this.tail] = event;
+        this.tail = (this.tail + 1) % this.capacity;
+        this.count++;
+        return !overflow;
+    }
+    /** Drain all events from the buffer. Returns a new array and clears the buffer. */
+    drain() {
+        if (this.count === 0)
+            return [];
+        const result = [];
+        for (let i = 0; i < this.count; i++) {
+            const idx = (this.head + i) % this.capacity;
+            result.push(this.items[idx]);
+        }
+        this.head = 0;
+        this.tail = 0;
+        this.count = 0;
+        return result;
+    }
+    /** Drain up to `max` events from the front of the buffer. */
+    drainUpTo(max) {
+        if (this.count === 0 || max <= 0)
+            return [];
+        const take = Math.min(max, this.count);
+        const result = [];
+        for (let i = 0; i < take; i++) {
+            const idx = (this.head + i) % this.capacity;
+            result.push(this.items[idx]);
+        }
+        this.head = (this.head + take) % this.capacity;
+        this.count -= take;
+        return result;
+    }
+    /** Current number of events in the buffer. */
+    get size() {
+        return this.count;
+    }
+    /** Whether the buffer is empty. */
+    get isEmpty() {
+        return this.count === 0;
+    }
+    /** Whether the buffer is at capacity. */
+    get isFull() {
+        return this.count === this.capacity;
+    }
+}
+exports.RingBuffer = RingBuffer;
+//# sourceMappingURL=buffer.js.map

package/dist/cjs/buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.js","sourceRoot":"","sources":["../../src/buffer.ts"],"names":[],"mappings":"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"}

package/dist/cjs/client.d.ts

@@ -0,0 +1,86 @@
+import { AforoOptions, TrackEvent, FlushResult } from './types';
+/**
+ * Aforo metering client.
+ *
+ * Enqueues usage events into a ring buffer, flushes them in batches
+ * to the Aforo ingestor service via HTTP. Non-blocking — `track()`
+ * returns immediately, flushing happens in the background.
+ *
+ * ```typescript
+ * const client = new AforoClient({ apiKey: 'your-key', productType: 'API' });
+ * await client.track({ customerId: 'cust_1', metricName: 'api_calls', quantity: 1 });
+ * // On shutdown:
+ * await client.shutdown();
+ * ```
+ */
+export declare class AforoClient {
+    private readonly buffer;
+    private readonly transport;
+    private readonly flushCount;
+    private readonly flushInterval;
+    private readonly shutdownTimeoutMs;
+    private readonly productType;
+    private flushTimer;
+    private flushing;
+    private closed;
+    private pendingFlush;
+    private heartbeatTimer;
+    private activeSessionId;
+    private sessionStartedAt;
+    private sessionProductType;
+    constructor(options: AforoOptions);
+    /**
+     * Start a session and emit `system.session.heartbeat` events: one now, then
+     * every 30s until `endSession()` / `shutdown()`.
+     *
+     * Each heartbeat is POSTed in its own request (`{"events":[heartbeat]}`),
+     * never mixed into a usage batch, so it always takes the ingestor's
+     * synchronous path, where it is intercepted before billing. Heartbeats are
+     * best-effort: sent once, failures ignored, never affecting usage delivery.
+     * The timer is unref'd so it never keeps the process alive.
+     *
+     * @param sessionId - Unique session identifier
+     * @param productType - Product type for the session (default AI_AGENT)
+     */
+    startSession(sessionId: string, productType?: string): void;
+    /**
+     * End the current session: stop heartbeats, send a final SESSION_END
+     * heartbeat (in its own request, best-effort) and flush buffered usage.
+     */
+    endSession(): Promise<void>;
+    private stopHeartbeatTimer;
+    private emitSessionHeartbeat;
+    /**
+     * Enqueue a usage event for batched delivery.
+     * Returns immediately — does not await HTTP.
+     * Triggers a flush if the buffer reaches flushCount.
+     *
+     * Throws if the event breaks any constraint the ingestor enforces — a blank
+     * or over-long `customerId` / `metricName` / `idempotencyKey`, a `quantity`
+     * that is not positive or carries more than 14 integer digits / 6 decimal
+     * places, an `occurredAt` that is not an ISO-8601 instant, or any other
+     * capped field that is too long. Limits the server makes configurable (event
+     * age, clock skew, metadata size) are left to the server, so the SDK can
+     * never refuse usage a given deployment would accept. Such an event is rejected by the ingestor and never billed,
+     * and because flushing happens in the background nobody would see that
+     * rejection — so it is reported here instead, and never enters the buffer.
+     * See `limits.ts` for the limits and where each one comes from.
+     */
+    track(event: TrackEvent): Promise<void>;
+    /**
+     * Force-flush all buffered events to the ingestor.
+     * Safe to call concurrently — only one flush runs at a time.
+     */
+    flush(): Promise<FlushResult>;
+    private doFlush;
+    /**
+     * Flush remaining events and stop the client.
+     * After shutdown, track() will throw.
+     */
+    shutdown(): Promise<void>;
+    /** Number of events currently buffered. */
+    get bufferedCount(): number;
+    /** Whether the client has been shut down. */
+    get isShutdown(): boolean;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/cjs/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAiB,WAAW,EAAE,MAAM,SAAS,CAAC;AAuB/E;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAqC;IAGzD,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,kBAAkB,CAAwC;gBAEtD,OAAO,EAAE,YAAY;IAsCjC;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,GAAE,MAAqC,GAAG,IAAI;IAezF;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,oBAAoB;IAgC5B;;;;;;;;;;;;;;;OAeG;IACG,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA+D7C;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;YAgBrB,OAAO;IAgBrB;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB/B,2CAA2C;IAC3C,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,6CAA6C;IAC7C,IAAI,UAAU,IAAI,OAAO,CAExB;CACF"}

package/dist/cjs/client.js

@@ -0,0 +1,301 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AforoClient = void 0;
+const buffer_1 = require("./buffer");
+const transport_1 = require("./transport");
+const idempotency_1 = require("./idempotency");
+const limits_1 = require("./limits");
+const DEFAULT_BASE_URL = 'https://api.aforo.ai';
+const DEFAULT_PRODUCT_TYPE = 'API';
+const DEFAULT_SESSION_PRODUCT_TYPE = 'AI_AGENT';
+/** Ingestor hard limit on events per batch request (IngestBatchRequest @Size(max = 1000)). */
+const MAX_BATCH_SIZE = 1000;
+const HEARTBEAT_INTERVAL_MS = 30000;
+const HEARTBEAT_METRIC = 'system.session.heartbeat';
+/** Heartbeats carry no billable customer; the ingestor intercepts them before billing. */
+const HEARTBEAT_CUSTOMER_ID = 'system';
+const DEFAULT_FLUSH_COUNT = 50;
+const DEFAULT_FLUSH_INTERVAL = 5000;
+const DEFAULT_MAX_QUEUE_SIZE = 10000;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_RETRY_BASE_MS = 1000;
+const DEFAULT_TIMEOUT = 10000;
+const DEFAULT_SHUTDOWN_TIMEOUT = 5000;
+/**
+ * Aforo metering client.
+ *
+ * Enqueues usage events into a ring buffer, flushes them in batches
+ * to the Aforo ingestor service via HTTP. Non-blocking — `track()`
+ * returns immediately, flushing happens in the background.
+ *
+ * ```typescript
+ * const client = new AforoClient({ apiKey: 'your-key', productType: 'API' });
+ * await client.track({ customerId: 'cust_1', metricName: 'api_calls', quantity: 1 });
+ * // On shutdown:
+ * await client.shutdown();
+ * ```
+ */
+class AforoClient {
+    constructor(options) {
+        this.flushTimer = null;
+        this.flushing = false;
+        this.closed = false;
+        this.pendingFlush = null;
+        // Session heartbeat state
+        this.heartbeatTimer = null;
+        this.activeSessionId = null;
+        this.sessionStartedAt = null;
+        this.sessionProductType = DEFAULT_SESSION_PRODUCT_TYPE;
+        if (!options.apiKey)
+            throw new Error('apiKey is required');
+        this.flushCount = Math.max(1, Math.min(options.flushCount ?? DEFAULT_FLUSH_COUNT, MAX_BATCH_SIZE));
+        this.productType = normalizeProductType(options.productType) ?? DEFAULT_PRODUCT_TYPE;
+        this.flushInterval = options.flushInterval ?? DEFAULT_FLUSH_INTERVAL;
+        this.shutdownTimeoutMs = options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT;
+        this.buffer = new buffer_1.RingBuffer(options.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE);
+        this.transport = new transport_1.Transport({
+            baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+            apiKey: options.apiKey,
+            timeout: options.timeout ?? DEFAULT_TIMEOUT,
+            maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+            retryBaseMs: options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS,
+        });
+        // Start periodic flush timer
+        this.flushTimer = setInterval(() => {
+            this.flush().catch(() => { });
+        }, this.flushInterval);
+        // Unref the timer so it doesn't prevent Node from exiting
+        if (this.flushTimer && typeof this.flushTimer === 'object' && 'unref' in this.flushTimer) {
+            this.flushTimer.unref();
+        }
+        // Register graceful shutdown handlers
+        const shutdownHandler = () => {
+            this.shutdown().catch(() => { });
+        };
+        process.once('SIGTERM', shutdownHandler);
+        process.once('SIGINT', shutdownHandler);
+    }
+    // ─── Session lifecycle with heartbeat ─────────────────────────────
+    /**
+     * Start a session and emit `system.session.heartbeat` events: one now, then
+     * every 30s until `endSession()` / `shutdown()`.
+     *
+     * Each heartbeat is POSTed in its own request (`{"events":[heartbeat]}`),
+     * never mixed into a usage batch, so it always takes the ingestor's
+     * synchronous path, where it is intercepted before billing. Heartbeats are
+     * best-effort: sent once, failures ignored, never affecting usage delivery.
+     * The timer is unref'd so it never keeps the process alive.
+     *
+     * @param sessionId - Unique session identifier
+     * @param productType - Product type for the session (default AI_AGENT)
+     */
+    startSession(sessionId, productType = DEFAULT_SESSION_PRODUCT_TYPE) {
+        if (this.closed || !sessionId || !String(sessionId).trim())
+            return;
+        this.stopHeartbeatTimer();
+        this.activeSessionId = String(sessionId);
+        this.sessionStartedAt = Date.now();
+        this.sessionProductType = normalizeProductType(productType) ?? DEFAULT_SESSION_PRODUCT_TYPE;
+        this.emitSessionHeartbeat('HEARTBEAT');
+        this.heartbeatTimer = setInterval(() => this.emitSessionHeartbeat('HEARTBEAT'), HEARTBEAT_INTERVAL_MS);
+        if (this.heartbeatTimer && typeof this.heartbeatTimer === 'object' && 'unref' in this.heartbeatTimer) {
+            this.heartbeatTimer.unref();
+        }
+    }
+    /**
+     * End the current session: stop heartbeats, send a final SESSION_END
+     * heartbeat (in its own request, best-effort) and flush buffered usage.
+     */
+    async endSession() {
+        this.stopHeartbeatTimer();
+        const end = this.activeSessionId ? this.emitSessionHeartbeat('SESSION_END') : Promise.resolve();
+        this.activeSessionId = null;
+        this.sessionStartedAt = null;
+        await Promise.all([end, this.flush()]);
+    }
+    stopHeartbeatTimer() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    emitSessionHeartbeat(boundary) {
+        const sessionId = this.activeSessionId;
+        if (!sessionId || (this.closed && boundary === 'HEARTBEAT'))
+            return Promise.resolve();
+        const now = Date.now();
+        const occurredAt = new Date(now).toISOString();
+        const heartbeat = {
+            customerId: HEARTBEAT_CUSTOMER_ID,
+            metricName: HEARTBEAT_METRIC,
+            // quantity must be > 0 to pass the ingestor's bean validation; the
+            // heartbeat is intercepted before billing and never counted as usage.
+            quantity: 1,
+            idempotencyKey: `hb:${boundary === 'SESSION_END' ? 'end:' : ''}${sessionId}:${now}:${randomSuffix()}`.slice(0, 255),
+            occurredAt,
+            productType: this.sessionProductType,
+            sessionId,
+            sessionBoundary: boundary,
+            metadata: {
+                sessionId,
+                sessionBoundary: boundary,
+                productType: this.sessionProductType,
+                heartbeatType: boundary === 'SESSION_END' ? 'SESSION_END' : 'PERIODIC',
+                uptimeMs: now - (this.sessionStartedAt ?? now),
+                sdkLanguage: 'node',
+            },
+        };
+        return this.transport.sendSingleBestEffort(heartbeat).then(() => undefined, () => undefined);
+    }
+    // ─── Event tracking ──────────────────────────────────────────────
+    /**
+     * Enqueue a usage event for batched delivery.
+     * Returns immediately — does not await HTTP.
+     * Triggers a flush if the buffer reaches flushCount.
+     *
+     * Throws if the event breaks any constraint the ingestor enforces — a blank
+     * or over-long `customerId` / `metricName` / `idempotencyKey`, a `quantity`
+     * that is not positive or carries more than 14 integer digits / 6 decimal
+     * places, an `occurredAt` that is not an ISO-8601 instant, or any other
+     * capped field that is too long. Limits the server makes configurable (event
+     * age, clock skew, metadata size) are left to the server, so the SDK can
+     * never refuse usage a given deployment would accept. Such an event is rejected by the ingestor and never billed,
+     * and because flushing happens in the background nobody would see that
+     * rejection — so it is reported here instead, and never enters the buffer.
+     * See `limits.ts` for the limits and where each one comes from.
+     */
+    async track(event) {
+        if (this.closed) {
+            throw new Error('AforoClient is shut down — cannot track new events');
+        }
+        if (event.customerId === undefined || event.customerId === null || !String(event.customerId).trim()) {
+            throw new Error('customerId is required');
+        }
+        if (event.metricName === undefined || event.metricName === null || !String(event.metricName).trim()) {
+            throw new Error('metricName is required');
+        }
+        const occurredAt = resolveOccurredAt(event.occurredAt);
+        const quantity = event.quantity ?? 1;
+        if (typeof quantity !== 'number' || !Number.isFinite(quantity) || quantity <= 0) {
+            throw new Error('quantity must be a positive number (> 0)');
+        }
+        const productType = normalizeProductType(event.productType) ?? this.productType;
+        // Minted once, here, when the event is enqueued — never at flush/retry
+        // time, so a retried batch carries the same keys and the ingestor
+        // deduplicates it. A caller-supplied key is passed through verbatim;
+        // otherwise each event gets its own random UUID. A deterministic hash of
+        // the event fields would make two genuinely distinct events in the same
+        // millisecond collide, and the ingestor would silently drop the second.
+        // Minted before the limit check so an over-long caller-supplied key is
+        // reported here rather than silently dropped by the server later.
+        const idempotencyKey = event.idempotencyKey ?? (0, idempotency_1.generateRandomKey)();
+        const violation = (0, limits_1.describeLimitViolation)({
+            customerId: event.customerId,
+            metricName: event.metricName,
+            quantity,
+            idempotencyKey,
+            occurredAt,
+            productType,
+            endpointPath: event.endpointPath,
+            httpMethod: event.httpMethod,
+        });
+        if (violation)
+            throw new Error(violation);
+        const resolved = {
+            customerId: event.customerId,
+            metricName: event.metricName,
+            quantity,
+            idempotencyKey,
+            occurredAt,
+            productType,
+            ...(event.metadata ? { metadata: event.metadata } : {}),
+            ...(event.endpointPath !== undefined ? { endpointPath: event.endpointPath } : {}),
+            ...(event.httpMethod !== undefined ? { httpMethod: event.httpMethod } : {}),
+            ...(event.statusCode !== undefined ? { statusCode: event.statusCode } : {}),
+            ...(event.responseTimeMs !== undefined ? { responseTimeMs: event.responseTimeMs } : {}),
+        };
+        this.buffer.push(resolved);
+        // Trigger flush if buffer threshold reached
+        if (this.buffer.size >= this.flushCount) {
+            this.flush().catch(() => { });
+        }
+    }
+    /**
+     * Force-flush all buffered events to the ingestor.
+     * Safe to call concurrently — only one flush runs at a time.
+     */
+    async flush() {
+        if (this.flushing && this.pendingFlush) {
+            return this.pendingFlush;
+        }
+        this.flushing = true;
+        this.pendingFlush = this.doFlush();
+        try {
+            return await this.pendingFlush;
+        }
+        finally {
+            this.flushing = false;
+            this.pendingFlush = null;
+        }
+    }
+    async doFlush() {
+        let totalSent = 0;
+        let totalFailed = 0;
+        while (!this.buffer.isEmpty) {
+            const batch = this.buffer.drainUpTo(this.flushCount);
+            if (batch.length === 0)
+                break;
+            const result = await this.transport.send(batch);
+            totalSent += result.sent;
+            totalFailed += result.failed;
+        }
+        return { sent: totalSent, failed: totalFailed };
+    }
+    /**
+     * Flush remaining events and stop the client.
+     * After shutdown, track() will throw.
+     */
+    async shutdown() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Stop session heartbeats
+        this.stopHeartbeatTimer();
+        // Clear periodic flush timer
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        // Flush with timeout
+        await Promise.race([
+            this.flush(),
+            new Promise((resolve) => setTimeout(resolve, this.shutdownTimeoutMs)),
+        ]);
+    }
+    /** Number of events currently buffered. */
+    get bufferedCount() {
+        return this.buffer.size;
+    }
+    /** Whether the client has been shut down. */
+    get isShutdown() {
+        return this.closed;
+    }
+}
+exports.AforoClient = AforoClient;
+function normalizeProductType(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const trimmed = String(value).trim();
+    return trimmed ? trimmed.toUpperCase() : undefined;
+}
+function randomSuffix() {
+    return Math.random().toString(36).slice(2, 10);
+}
+function resolveOccurredAt(value) {
+    if (!value)
+        return new Date().toISOString();
+    if (typeof value === 'number')
+        return new Date(value).toISOString();
+    return value;
+}
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/cjs/idempotency.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Generate a deterministic idempotency key from event fields.
+ * Uses SHA-256, truncated to 32 hex chars for compact storage.
+ *
+ * Formula: SHA256(customerId + metricName + quantity + occurredAt)
+ *
+ * NOT the client default any more. `occurredAt` only carries millisecond
+ * precision, so two genuinely distinct events for the same customer + metric
+ * + quantity inside one millisecond hash to the same key and the ingestor
+ * drops the second as a DUPLICATE — silent under-billing. Kept exported for
+ * callers who deliberately want content-addressed dedup (e.g. replaying a
+ * fixed batch) and pass the result to `track({ idempotencyKey })` themselves.
+ */
+export declare function generateIdempotencyKey(customerId: string, metricName: string, quantity: number, occurredAt: string): string;
+/**
+ * Generate a random UUID v4. This is the default key for an event whose caller
+ * supplied none: every event gets its own key, so no two distinct events can
+ * collide. Dedup stays opt-in via an explicit `idempotencyKey`.
+ */
+export declare function generateRandomKey(): string;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/cjs/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../src/idempotency.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,CAGR;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}