@aforoai/metering 1.0.0

package/dist/esm/middleware/fastify.js

@@ -0,0 +1,87 @@
+import { AforoClient } from '../client';
+import { isPreflight, resolveMetricName, firstNonEmpty, endpointPathOf } from './common';
+const DEFAULT_EXCLUDE_PATHS = ['/health', '/ready', '/metrics', '/favicon.ico'];
+/**
+ * Fastify plugin that automatically captures API usage events.
+ *
+ * Uses the `onResponse` hook — runs AFTER the response is sent.
+ *
+ * ```typescript
+ * import { fastifyPlugin } from '@aforoai/metering/middleware/fastify';
+ * fastify.register(fastifyPlugin, { apiKey: process.env.AFORO_API_KEY, productType: 'API' });
+ * ```
+ */
+export async function fastifyPlugin(fastify, options) {
+    const client = new AforoClient({
+        apiKey: options.apiKey,
+        baseUrl: options.baseUrl,
+        ...options.clientOptions,
+    });
+    const excludePaths = options.excludePaths ?? DEFAULT_EXCLUDE_PATHS;
+    const excludeStatusCodes = options.excludeStatusCodes ?? [];
+    fastify.addHook('onResponse', (request, reply, done) => {
+        try {
+            const path = request.url || '/';
+            const method = request.method || 'UNKNOWN';
+            const statusCode = reply.statusCode || 0;
+            if (isPreflight(method))
+                return done();
+            if (excludePaths.some((p) => path.startsWith(p)))
+                return done();
+            if (excludeStatusCodes.includes(statusCode))
+                return done();
+            const metricName = resolveMetricName(options, request, reply);
+            let quantity;
+            if (typeof options.quantity === 'function') {
+                quantity = options.quantity(request, reply);
+            }
+            else {
+                quantity = options.quantity ?? 1;
+            }
+            let customerId;
+            if (typeof options.customerId === 'function') {
+                customerId = options.customerId(request);
+            }
+            else if (options.customerId) {
+                customerId = options.customerId;
+            }
+            else {
+                // Never the caller's X-Api-Key: that is a secret, not a customer id.
+                customerId = firstNonEmpty(request.user?.id, request.headers?.['x-customer-id']);
+            }
+            if (!customerId)
+                return done();
+            if (!(quantity > 0))
+                return done(); // The ingestor rejects quantity <= 0
+            let metadata;
+            if (options.metadata) {
+                metadata = options.metadata(request, reply);
+            }
+            const elapsed = typeof reply.elapsedTime === 'number'
+                ? reply.elapsedTime
+                : typeof reply.getResponseTime === 'function' ? reply.getResponseTime() : undefined;
+            client.track({
+                customerId,
+                metricName,
+                quantity,
+                metadata,
+                productType: options.productType,
+                endpointPath: endpointPathOf(path),
+                httpMethod: method,
+                statusCode,
+                ...(typeof elapsed === 'number' ? { responseTimeMs: Math.round(elapsed) } : {}),
+            }).catch(() => { });
+        }
+        catch {
+            // Never let metering affect the API
+        }
+        done();
+    });
+    fastify.addHook('onClose', async () => {
+        await client.shutdown();
+    });
+}
+// Mark as fastify plugin
+fastifyPlugin[Symbol.for('skip-override')] = true;
+fastifyPlugin[Symbol.for('fastify.display-name')] = 'aforo-metering';
+//# sourceMappingURL=fastify.js.map

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

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

package/dist/esm/middleware/koa.js

@@ -0,0 +1,79 @@
+import { AforoClient } from '../client';
+import { isPreflight, resolveMetricName, firstNonEmpty, endpointPathOf } from './common';
+const DEFAULT_EXCLUDE_PATHS = ['/health', '/ready', '/metrics', '/favicon.ico'];
+/**
+ * Koa middleware that automatically captures API usage events.
+ *
+ * Captures after `await next()` completes — runs after the response is generated.
+ *
+ * ```typescript
+ * import { koaMiddleware } from '@aforoai/metering/middleware/koa';
+ * app.use(koaMiddleware({ apiKey: process.env.AFORO_API_KEY, productType: 'API' }));
+ * ```
+ */
+export function koaMiddleware(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 async function aforoMeteringMiddleware(ctx, next) {
+        const startTime = Date.now();
+        await next();
+        try {
+            const path = ctx.path || ctx.url || '/';
+            const method = ctx.method || 'UNKNOWN';
+            const statusCode = ctx.status || 0;
+            if (isPreflight(method))
+                return;
+            if (excludePaths.some((p) => path.startsWith(p)))
+                return;
+            if (excludeStatusCodes.includes(statusCode))
+                return;
+            const metricName = resolveMetricName(options, ctx.request, ctx.response);
+            let quantity;
+            if (typeof options.quantity === 'function') {
+                quantity = options.quantity(ctx.request, ctx.response);
+            }
+            else {
+                quantity = options.quantity ?? 1;
+            }
+            let customerId;
+            if (typeof options.customerId === 'function') {
+                customerId = options.customerId(ctx.request);
+            }
+            else if (options.customerId) {
+                customerId = options.customerId;
+            }
+            else {
+                // Never the caller's X-Api-Key: that is a secret, not a customer id.
+                customerId = firstNonEmpty(ctx.state?.user?.id, ctx.get('x-customer-id'));
+            }
+            if (!customerId)
+                return;
+            if (!(quantity > 0))
+                return; // The ingestor rejects quantity <= 0
+            let metadata;
+            if (options.metadata) {
+                metadata = options.metadata(ctx.request, ctx.response);
+            }
+            client.track({
+                customerId,
+                metricName,
+                quantity,
+                metadata,
+                productType: options.productType,
+                endpointPath: endpointPathOf(path),
+                httpMethod: method,
+                statusCode,
+                responseTimeMs: Date.now() - startTime,
+            }).catch(() => { });
+        }
+        catch {
+            // Never let metering affect the API
+        }
+    };
+}
+//# sourceMappingURL=koa.js.map

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

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

package/dist/esm/path-normalizer.js

@@ -0,0 +1,46 @@
+/**
+ * Normalize a URL path by replacing dynamic segments with parameter placeholders.
+ *
+ * If a framework route template is available (e.g., Express `req.route?.path`),
+ * use that directly — it already has :param placeholders.
+ *
+ * Otherwise, apply heuristic normalization:
+ *   /users/123         → /users/:id
+ *   /orders/abc-def    → /orders/:id
+ *   /v1/items/42/reviews/7 → /v1/items/:id/reviews/:id
+ *
+ * UUIDs, numeric IDs, and alphanumeric slugs are detected and replaced.
+ */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const NUMERIC_RE = /^\d+$/;
+const MONGO_ID_RE = /^[0-9a-f]{24}$/i;
+// Version-like segments: v1, v2, v10, etc. — should NOT be normalized
+const VERSION_RE = /^v\d+$/i;
+export function normalizePath(actualPath, routeTemplate) {
+    // Prefer the framework's route template if available
+    if (routeTemplate) {
+        return routeTemplate;
+    }
+    // Heuristic: replace dynamic-looking segments
+    const segments = actualPath.split('/');
+    const normalized = segments.map((seg) => {
+        if (!seg)
+            return seg;
+        // Preserve version segments (v1, v2, v10)
+        if (VERSION_RE.test(seg))
+            return seg;
+        if (UUID_RE.test(seg))
+            return ':id';
+        if (NUMERIC_RE.test(seg))
+            return ':id';
+        if (MONGO_ID_RE.test(seg))
+            return ':id';
+        // Alphanumeric tokens > 4 chars that mix letters and digits look like IDs
+        if (seg.length > 4 && seg.length <= 12 && /^[a-zA-Z0-9_-]+$/.test(seg) && /\d/.test(seg) && /[a-zA-Z]/.test(seg)) {
+            return ':id';
+        }
+        return seg;
+    });
+    return normalized.join('/');
+}
+//# sourceMappingURL=path-normalizer.js.map

package/dist/esm/path-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-normalizer.js","sourceRoot":"","sources":["../../src/path-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,OAAO,GAAG,iEAAiE,CAAC;AAClF,MAAM,UAAU,GAAG,OAAO,CAAC;AAC3B,MAAM,WAAW,GAAG,iBAAiB,CAAC;AACtC,sEAAsE;AACtE,MAAM,UAAU,GAAG,SAAS,CAAC;AAE7B,MAAM,UAAU,aAAa,CAC3B,UAAkB,EAClB,aAAsB;IAEtB,qDAAqD;IACrD,IAAI,aAAa,EAAE,CAAC;QAClB,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,8CAA8C;IAC9C,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACtC,IAAI,CAAC,GAAG;YAAE,OAAO,GAAG,CAAC;QACrB,0CAA0C;QAC1C,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC;QACrC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACpC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACvC,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACxC,0EAA0E;QAC1E,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,IAAI,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACjH,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC,CAAC;IAEH,OAAO,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC"}

package/dist/esm/transport.js

@@ -0,0 +1,112 @@
+/**
+ * HTTP transport that sends batched usage events to the Aforo ingestor.
+ *
+ * - POST /v1/ingest/batch with X-API-Key: {apiKey} (never Authorization: Bearer -- the ingestor parses Bearer as a JWT and rejects the request 401)
+ * - Retry on 5xx, 408, 429 with exponential backoff
+ * - Respects Retry-After header on 429
+ * - No retry on 4xx (bad input)
+ * - AbortController timeout per request
+ */
+export class Transport {
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        this.timeout = options.timeout;
+        this.maxRetries = options.maxRetries;
+        this.retryBaseMs = options.retryBaseMs;
+    }
+    /** Send a batch of events. Returns the number sent and failed. */
+    async send(events) {
+        if (events.length === 0)
+            return { sent: 0, failed: 0 };
+        const url = `${this.baseUrl}/v1/ingest/batch`;
+        const body = { events };
+        const bodyStr = JSON.stringify(body);
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), this.timeout);
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-API-Key': this.apiKey,
+                    },
+                    body: bodyStr,
+                    signal: controller.signal,
+                });
+                clearTimeout(timer);
+                if (response.ok) {
+                    return { sent: events.length, failed: 0 };
+                }
+                // 4xx (except 408, 429) — bad input, don't retry
+                if (response.status >= 400 && response.status < 500
+                    && response.status !== 408 && response.status !== 429) {
+                    return { sent: 0, failed: events.length };
+                }
+                // 429 — respect Retry-After header
+                if (response.status === 429) {
+                    const retryAfter = response.headers.get('Retry-After');
+                    const delayMs = retryAfter
+                        ? (parseInt(retryAfter, 10) || 1) * 1000
+                        : this.retryBaseMs * Math.pow(2, attempt);
+                    if (attempt < this.maxRetries) {
+                        await this.sleep(delayMs);
+                        continue;
+                    }
+                }
+                // 5xx or 408 — retry with backoff
+                if (attempt < this.maxRetries) {
+                    await this.sleep(this.retryBaseMs * Math.pow(2, attempt));
+                    continue;
+                }
+                return { sent: 0, failed: events.length };
+            }
+            catch (err) {
+                // Network error or abort — retry
+                if (attempt < this.maxRetries) {
+                    await this.sleep(this.retryBaseMs * Math.pow(2, attempt));
+                    continue;
+                }
+                return { sent: 0, failed: events.length };
+            }
+        }
+        return { sent: 0, failed: events.length };
+    }
+    /**
+     * Send a single event in its own request, once, best-effort.
+     *
+     * Used for session heartbeats: a heartbeat must never share a batch with
+     * usage (a large batch takes the high-throughput path, which does not
+     * intercept heartbeats), and a lost heartbeat is simply superseded by the
+     * next one -- so there is no retry and every failure is swallowed.
+     * Resolves to true when the ingestor accepted the request.
+     */
+    async sendSingleBestEffort(event) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const body = { events: [event] };
+            const response = await fetch(`${this.baseUrl}/v1/ingest/batch`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-Key': this.apiKey,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/esm/transport.js.map

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

package/dist/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/dist/types/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/types/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/types/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/types/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/types/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/types/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"}

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+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';
+export type { AforoOptions, TrackEvent, MiddlewareOptions, FlushResult, BatchRequest, BatchResponse, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,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;AAElB,YAAY,EACV,YAAY,EACZ,UAAU,EACV,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,aAAa,GACd,MAAM,SAAS,CAAC"}

package/dist/types/limits.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 declare const MAX_LENGTHS: {
+    readonly customerId: 64;
+    readonly metricName: 255;
+    readonly idempotencyKey: 255;
+    readonly productType: 20;
+    readonly traceId: 128;
+    readonly spanId: 32;
+    readonly sessionId: 64;
+    readonly agentId: 36;
+    readonly toolName: 64;
+    readonly endpointPath: 512;
+    readonly httpMethod: 16;
+};
+/** `@Digits(integer = 14, fraction = 6)` — `usage_events.quantity` is NUMERIC(20,6). */
+export declare const MAX_QUANTITY_INTEGER_DIGITS = 14;
+export declare const MAX_QUANTITY_DECIMAL_PLACES = 6;
+/**
+ * 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 declare function quantityDigits(serialized: string): {
+    integerDigits: number;
+    decimalPlaces: number;
+};
+/** The already-resolved event fields the limits apply to. */
+export interface LimitCheckedEvent {
+    customerId?: unknown;
+    metricName?: unknown;
+    quantity: number;
+    idempotencyKey?: unknown;
+    occurredAt: string;
+    productType?: unknown;
+    endpointPath?: unknown;
+    httpMethod?: unknown;
+    traceId?: unknown;
+    spanId?: unknown;
+    sessionId?: unknown;
+    agentId?: unknown;
+    toolName?: unknown;
+}
+/**
+ * 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 declare function describeLimitViolation(event: LimitCheckedEvent): string | null;
+//# sourceMappingURL=limits.d.ts.map

package/dist/types/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qFAAqF;AACrF,eAAO,MAAM,WAAW;;;;;;;;;;;;CAYd,CAAC;AAEX,wFAAwF;AACxF,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAC9C,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAoC7C;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAYnG;AA+BD,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,CAe9E"}

package/dist/types/middleware/common.d.ts

@@ -0,0 +1,22 @@
+import { MiddlewareOptions } from '../types';
+/**
+ * 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 declare 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 declare function isPreflight(method: string | undefined): boolean;
+/** Resolve the metric: resolver function, then fixed name, then DEFAULT_METRIC_NAME. */
+export declare function resolveMetricName(options: MiddlewareOptions, req: any, res: any): string;
+/** Request path without its query string, capped to what the ingestor accepts. */
+export declare function endpointPathOf(url: string): string;
+/** First non-empty string among the candidates, or null. */
+export declare function firstNonEmpty(...values: unknown[]): string | null;
+//# sourceMappingURL=common.d.ts.map

package/dist/types/middleware/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/middleware/common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE/D;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,MAAM,CAKxF;AAKD,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,GAAG,IAAI,CAOjE"}