@aforoai/metering 1.0.0

package/dist/esm/client.js

@@ -0,0 +1,297 @@
+import { RingBuffer } from './buffer';
+import { Transport } from './transport';
+import { generateRandomKey } from './idempotency';
+import { describeLimitViolation } from './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();
+ * ```
+ */
+export 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 RingBuffer(options.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE);
+        this.transport = new 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 ?? generateRandomKey();
+        const violation = 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;
+    }
+}
+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/esm/client.js.map

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

package/dist/esm/idempotency.js

@@ -0,0 +1,27 @@
+import { createHash, randomUUID } from 'node:crypto';
+/**
+ * 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 function generateIdempotencyKey(customerId, metricName, quantity, occurredAt) {
+    const input = `${customerId}:${metricName}:${quantity}:${occurredAt}`;
+    return createHash('sha256').update(input).digest('hex').substring(0, 32);
+}
+/**
+ * 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 function generateRandomKey() {
+    return randomUUID();
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/esm/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../src/idempotency.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAkB,EAClB,UAAkB,EAClB,QAAgB,EAChB,UAAkB;IAElB,MAAM,KAAK,GAAG,GAAG,UAAU,IAAI,UAAU,IAAI,QAAQ,IAAI,UAAU,EAAE,CAAC;IACtE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,9 @@
+// Public API for @aforoai/metering
+export { AforoClient } from './client';
+export { expressMiddleware, middleware } from './middleware/express';
+export { fastifyPlugin } from './middleware/fastify';
+export { koaMiddleware } from './middleware/koa';
+export { normalizePath } from './path-normalizer';
+export { DEFAULT_METRIC_NAME } from './middleware/common';
+export { MAX_LENGTHS, MAX_QUANTITY_DECIMAL_PLACES, MAX_QUANTITY_INTEGER_DIGITS, describeLimitViolation, } from './limits';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EACL,WAAW,EACX,2BAA2B,EAC3B,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,UAAU,CAAC"}

package/dist/esm/limits.js

@@ -0,0 +1,138 @@
+/**
+ * Client-side mirror of the ingestor's per-event field constraints.
+ *
+ * An event that breaks one of these is rejected by the ingestor and never
+ * billed. The server reports it per event (`errors[]` in the batch response,
+ * indexed), so the rest of the batch survives — but the SDK sends in the
+ * background, so that report reaches nobody: the usage is simply gone. Checking
+ * the same limits at `track()` surfaces the problem to the caller, at the call
+ * site that produced it, while the event can still be corrected.
+ *
+ * Source: `dto/IngestUsageEventRequest` (aforo-nextgen-usage-ingestor-service) —
+ * the `@Size` and `@Digits` bean constraints, which are compiled into the
+ * server and therefore identical in every environment.
+ *
+ * Deliberately NOT mirrored here: the timestamp window (`max-age-days`,
+ * `future-tolerance-minutes`) and the metadata cap (`max-metadata-bytes`) in
+ * `validation/UsageEventValidator`. Each is a per-environment property — a
+ * tenant may raise `max-age-days` to 365 for backfills — so enforcing the
+ * default here would make the SDK refuse usage its own server would accept and
+ * bill. Refusing real usage is a worse failure than the rejection it prevents.
+ * Only `occurredAt`'s shape is checked, since a malformed timestamp is invalid
+ * under every configuration.
+ *
+ * Nothing here truncates or rounds — that would change what is billed. The
+ * offending event is rejected instead, naming the field, the limit, and the
+ * offending value.
+ */
+/** Maximum characters the ingestor accepts per string field (`@Size(max = ...)`). */
+export const MAX_LENGTHS = {
+    customerId: 64,
+    metricName: 255,
+    idempotencyKey: 255,
+    productType: 20,
+    traceId: 128,
+    spanId: 32,
+    sessionId: 64,
+    agentId: 36,
+    toolName: 64,
+    endpointPath: 512,
+    httpMethod: 16,
+};
+/** `@Digits(integer = 14, fraction = 6)` — `usage_events.quantity` is NUMERIC(20,6). */
+export const MAX_QUANTITY_INTEGER_DIGITS = 14;
+export const MAX_QUANTITY_DECIMAL_PLACES = 6;
+/**
+ * ISO-8601 date-time, the shape Jackson can read into an `Instant`. The zone
+ * designator is optional here: the ingestor's example values all carry `Z`, but
+ * an offset-less value is not provably rejected, and falsely rejecting one
+ * would drop a billable event.
+ */
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?([Zz]|[+-]\d{2}:?\d{2})?$/;
+/**
+ * Length as the ingestor counts it: `String.length()` in Java is UTF-16 code
+ * units, which is exactly what `String.prototype.length` returns.
+ */
+function lengthOf(value) {
+    return value.length;
+}
+function lengthError(field, value) {
+    if (value === undefined || value === null)
+        return null;
+    const text = String(value);
+    const max = MAX_LENGTHS[field];
+    const len = lengthOf(text);
+    if (len <= max)
+        return null;
+    return `${field} is ${len} characters, exceeding the ingestor's ${max}-character limit `
+        + `(value starts "${text.slice(0, 32)}"). Shorten it — the SDK will not truncate it, `
+        + 'because a truncated id bills the wrong thing.';
+}
+/**
+ * Integer and decimal digit counts as the ingestor's `@Digits` sees them, i.e.
+ * as `BigDecimal` reads the number the SDK puts on the wire:
+ * `integerDigits = precision - scale`, `decimalPlaces = max(scale, 0)`.
+ *
+ * Works from the serialized text so exponent notation (`1e+21`, which
+ * `JSON.stringify` emits for large numbers) is counted the same way the server
+ * will count it.
+ */
+export function quantityDigits(serialized) {
+    const match = /^[+-]?(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/.exec(serialized.trim());
+    if (!match)
+        return { integerDigits: 0, decimalPlaces: 0 };
+    const intPart = match[1] ?? '';
+    const fracPart = match[2] ?? '';
+    const exponent = match[3] ? parseInt(match[3], 10) : 0;
+    const digits = (intPart + fracPart).replace(/^0+/, '');
+    const precision = digits.length === 0 ? 1 : digits.length;
+    const scale = fracPart.length - exponent;
+    return { integerDigits: precision - scale, decimalPlaces: Math.max(scale, 0) };
+}
+function quantityError(quantity) {
+    // JSON.stringify is what the transport uses, so this is the exact text the
+    // ingestor will parse into the BigDecimal that @Digits inspects.
+    const serialized = JSON.stringify(quantity);
+    const { integerDigits, decimalPlaces } = quantityDigits(String(serialized));
+    if (integerDigits > MAX_QUANTITY_INTEGER_DIGITS) {
+        return `quantity ${serialized} has ${integerDigits} integer digits, exceeding the ingestor's `
+            + `limit of ${MAX_QUANTITY_INTEGER_DIGITS} (usage_events.quantity is NUMERIC(20,6)).`;
+    }
+    if (decimalPlaces > MAX_QUANTITY_DECIMAL_PLACES) {
+        return `quantity ${serialized} has ${decimalPlaces} decimal places, exceeding the ingestor's `
+            + `limit of ${MAX_QUANTITY_DECIMAL_PLACES}. Round it yourself before tracking — the SDK will `
+            + 'not round it, because that would change the quantity you are billed for.';
+    }
+    return null;
+}
+function occurredAtError(occurredAt) {
+    if (!ISO_DATE_TIME.test(occurredAt)) {
+        return `occurredAt "${occurredAt}" is not an ISO-8601 timestamp `
+            + '(expected e.g. "2026-03-01T14:30:00Z").';
+    }
+    if (Number.isNaN(Date.parse(occurredAt))) {
+        return `occurredAt "${occurredAt}" is not a valid date.`;
+    }
+    return null;
+}
+/**
+ * Describe the first ingestor constraint this event breaks, or `null` when it
+ * would be accepted. Callers that must not throw (the framework middlewares)
+ * can use this to skip an event instead.
+ */
+export function describeLimitViolation(event) {
+    if (event.idempotencyKey !== undefined && event.idempotencyKey !== null
+        && !String(event.idempotencyKey).trim()) {
+        return 'idempotencyKey must not be blank when provided.';
+    }
+    for (const field of Object.keys(MAX_LENGTHS)) {
+        const problem = lengthError(field, event[field]);
+        if (problem)
+            return problem;
+    }
+    const quantityProblem = quantityError(event.quantity);
+    if (quantityProblem)
+        return quantityProblem;
+    return occurredAtError(event.occurredAt);
+}
+//# sourceMappingURL=limits.js.map

package/dist/esm/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qFAAqF;AACrF,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,UAAU,EAAE,EAAE;IACd,UAAU,EAAE,GAAG;IACf,cAAc,EAAE,GAAG;IACnB,WAAW,EAAE,EAAE;IACf,OAAO,EAAE,GAAG;IACZ,MAAM,EAAE,EAAE;IACV,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,QAAQ,EAAE,EAAE;IACZ,YAAY,EAAE,GAAG;IACjB,UAAU,EAAE,EAAE;CACN,CAAC;AAEX,wFAAwF;AACxF,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAC9C,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAK7C;;;;;GAKG;AACH,MAAM,aAAa,GACjB,iFAAiF,CAAC;AAKpF;;;GAGG;AACH,SAAS,QAAQ,CAAC,KAAa;IAC7B,OAAO,KAAK,CAAC,MAAM,CAAC;AACtB,CAAC;AAED,SAAS,WAAW,CAAC,KAAyB,EAAE,KAAc;IAC5D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3B,MAAM,GAAG,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,GAAG,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO,GAAG,KAAK,OAAO,GAAG,yCAAyC,GAAG,mBAAmB;UACpF,kBAAkB,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,iDAAiD;UACpF,+CAA+C,CAAC;AACtD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,UAAkB;IAC/C,MAAM,KAAK,GAAG,6CAA6C,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IACpF,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;IAC1D,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/B,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEvD,MAAM,MAAM,GAAG,CAAC,OAAO,GAAG,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;IAC1D,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC;IAEzC,OAAO,EAAE,aAAa,EAAE,SAAS,GAAG,KAAK,EAAE,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC;AACjF,CAAC;AAED,SAAS,aAAa,CAAC,QAAgB;IACrC,2EAA2E;IAC3E,iEAAiE;IACjE,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,GAAG,cAAc,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAE5E,IAAI,aAAa,GAAG,2BAA2B,EAAE,CAAC;QAChD,OAAO,YAAY,UAAU,QAAQ,aAAa,4CAA4C;cAC1F,YAAY,2BAA2B,4CAA4C,CAAC;IAC1F,CAAC;IACD,IAAI,aAAa,GAAG,2BAA2B,EAAE,CAAC;QAChD,OAAO,YAAY,UAAU,QAAQ,aAAa,4CAA4C;cAC1F,YAAY,2BAA2B,qDAAqD;cAC5F,0EAA0E,CAAC;IACjF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,eAAe,CAAC,UAAkB;IACzC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,OAAO,eAAe,UAAU,iCAAiC;cAC7D,yCAAyC,CAAC;IAChD,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QACzC,OAAO,eAAe,UAAU,wBAAwB,CAAC;IAC3D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAmBD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAwB;IAC7D,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS,IAAI,KAAK,CAAC,cAAc,KAAK,IAAI;WAChE,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5C,OAAO,iDAAiD,CAAC;IAC3D,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAyB,EAAE,CAAC;QACrE,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,EAAG,KAA4C,CAAC,KAAK,CAAC,CAAC,CAAC;QACzF,IAAI,OAAO;YAAE,OAAO,OAAO,CAAC;IAC9B,CAAC;IAED,MAAM,eAAe,GAAG,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACtD,IAAI,eAAe;QAAE,OAAO,eAAe,CAAC;IAE5C,OAAO,eAAe,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;AAC3C,CAAC"}

package/dist/esm/middleware/common.js

@@ -0,0 +1,41 @@
+/**
+ * Metric recorded for each request when `metricName` is not configured.
+ *
+ * It must exist in the tenant's Aforo metric catalog: the ingestor rejects an
+ * unknown metric, and because it validates a batch as a whole, one such event
+ * fails the entire batch with 400. The previous default, `"METHOD /path"`, is a
+ * name no catalog contains, so every event failed out of the box.
+ */
+export const DEFAULT_METRIC_NAME = 'api_calls';
+/**
+ * CORS preflights are a browser protocol detail, not a billable call, and carry
+ * no credentials -- so they never have a customer. They are never metered.
+ */
+export function isPreflight(method) {
+    return (method || '').toUpperCase() === 'OPTIONS';
+}
+/** Resolve the metric: resolver function, then fixed name, then DEFAULT_METRIC_NAME. */
+export function resolveMetricName(options, req, res) {
+    if (typeof options.metricName === 'function') {
+        return options.metricName(req, res) || DEFAULT_METRIC_NAME;
+    }
+    return options.metricName || DEFAULT_METRIC_NAME;
+}
+/** Longest endpointPath the ingestor accepts. */
+const MAX_ENDPOINT_PATH = 512;
+/** Request path without its query string, capped to what the ingestor accepts. */
+export function endpointPathOf(url) {
+    return (url.split('?')[0] || '/').slice(0, MAX_ENDPOINT_PATH);
+}
+/** First non-empty string among the candidates, or null. */
+export function firstNonEmpty(...values) {
+    for (const v of values) {
+        if (v === undefined || v === null)
+            continue;
+        const s = String(Array.isArray(v) ? v[0] : v).trim();
+        if (s)
+            return s;
+    }
+    return null;
+}
+//# sourceMappingURL=common.js.map

package/dist/esm/middleware/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../../src/middleware/common.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,WAAW,CAAC;AAE/C;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAA0B;IACpD,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC;AACpD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,iBAAiB,CAAC,OAA0B,EAAE,GAAQ,EAAE,GAAQ;IAC9E,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QAC7C,OAAO,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,mBAAmB,CAAC;IAC7D,CAAC;IACD,OAAO,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;AACnD,CAAC;AAED,iDAAiD;AACjD,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;AAChE,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,aAAa,CAAC,GAAG,MAAiB;IAChD,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;YAAE,SAAS;QAC5C,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACrD,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/esm/middleware/express.js

@@ -0,0 +1,100 @@
+import { AforoClient } from '../client';
+import { isPreflight, resolveMetricName, firstNonEmpty, endpointPathOf } from './common';
+const DEFAULT_EXCLUDE_PATHS = ['/health', '/ready', '/metrics', '/favicon.ico'];
+/**
+ * Express middleware that automatically captures API usage events.
+ *
+ * Hooks into `res.on('finish')` — runs AFTER the response is sent to the client.
+ * Zero latency impact on the API call itself.
+ *
+ * ```typescript
+ * import { expressMiddleware } from '@aforoai/metering/middleware/express';
+ * app.use(expressMiddleware({ apiKey: process.env.AFORO_API_KEY, productType: 'API' }));
+ * ```
+ */
+export function expressMiddleware(options) {
+    const client = new AforoClient({
+        apiKey: options.apiKey,
+        baseUrl: options.baseUrl,
+        ...options.clientOptions,
+    });
+    const excludePaths = options.excludePaths ?? DEFAULT_EXCLUDE_PATHS;
+    const excludeStatusCodes = options.excludeStatusCodes ?? [];
+    return function aforoMeteringMiddleware(req, res, next) {
+        // Capture timing
+        const startTime = Date.now();
+        res.on('finish', () => {
+            try {
+                const path = req.originalUrl || req.url || '/';
+                const method = req.method || 'UNKNOWN';
+                const statusCode = res.statusCode || 0;
+                // Check exclusions
+                if (isPreflight(method))
+                    return;
+                if (excludePaths.some((p) => path.startsWith(p)))
+                    return;
+                if (excludeStatusCodes.includes(statusCode))
+                    return;
+                // Resolve metric name (must be a metric in the tenant's catalog)
+                const metricName = resolveMetricName(options, req, res);
+                // Resolve quantity
+                let quantity;
+                if (typeof options.quantity === 'function') {
+                    quantity = options.quantity(req, res);
+                }
+                else {
+                    quantity = options.quantity ?? 1;
+                }
+                // Resolve customer ID
+                let customerId;
+                if (typeof options.customerId === 'function') {
+                    customerId = options.customerId(req);
+                }
+                else if (options.customerId) {
+                    customerId = options.customerId;
+                }
+                else {
+                    customerId = extractCustomerId(req);
+                }
+                if (!customerId)
+                    return; // Can't meter without a customer
+                if (!(quantity > 0))
+                    return; // The ingestor rejects quantity <= 0
+                // Build metadata
+                let metadata;
+                if (options.metadata) {
+                    metadata = options.metadata(req, res);
+                }
+                client.track({
+                    customerId,
+                    metricName,
+                    quantity,
+                    metadata,
+                    productType: options.productType,
+                    endpointPath: endpointPathOf(path),
+                    httpMethod: method,
+                    statusCode,
+                    responseTimeMs: Date.now() - startTime,
+                }).catch(() => { }); // Fire-and-forget
+            }
+            catch {
+                // Never let metering errors affect the API
+            }
+        });
+        next();
+    };
+}
+/**
+ * Default customer resolution: authenticated user id, then X-Customer-Id.
+ *
+ * The caller's X-Api-Key header is deliberately NOT used: that is the end
+ * user's secret, and using it as customerId wrote credentials into billing data
+ * while never matching an Aforo customer. Configure `customerId` to map your
+ * callers to Aforo customer ids.
+ */
+function extractCustomerId(req) {
+    return firstNonEmpty(req.user?.id, req.user?.sub, req.headers?.['x-customer-id']);
+}
+// Also export as `middleware` for convenience
+export const middleware = expressMiddleware;
+//# sourceMappingURL=express.js.map

package/dist/esm/middleware/express.js.map

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