@aforoai/metering 1.0.0

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

@@ -0,0 +1,15 @@
+import { MiddlewareOptions } from '../types';
+/**
+ * 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 declare function expressMiddleware(options: MiddlewareOptions): (req: any, res: any, next: any) => void;
+export declare const middleware: typeof expressMiddleware;
+//# sourceMappingURL=express.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../../src/middleware/express.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAK7C;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,IAUlB,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,GAAG,UAgEtE;AAeD,eAAO,MAAM,UAAU,0BAAoB,CAAC"}

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

@@ -0,0 +1,13 @@
+import { MiddlewareOptions } from '../types';
+/**
+ * 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 declare function fastifyPlugin(fastify: any, options: MiddlewareOptions): Promise<void>;
+//# sourceMappingURL=fastify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.d.ts","sourceRoot":"","sources":["../../../src/middleware/fastify.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAK7C;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,iBAAiB,iBAwE3E"}

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

@@ -0,0 +1,13 @@
+import { MiddlewareOptions } from '../types';
+/**
+ * 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 declare function koaMiddleware(options: MiddlewareOptions): (ctx: any, next: any) => Promise<void>;
+//# sourceMappingURL=koa.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"koa.d.ts","sourceRoot":"","sources":["../../../src/middleware/koa.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAK7C;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,iBAAiB,IAUR,KAAK,GAAG,EAAE,MAAM,GAAG,mBAuDlE"}

package/dist/types/path-normalizer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+export declare function normalizePath(actualPath: string, routeTemplate?: string): string;
+//# sourceMappingURL=path-normalizer.d.ts.map

package/dist/types/path-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-normalizer.d.ts","sourceRoot":"","sources":["../../src/path-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CAuBR"}

package/dist/types/transport.d.ts

@@ -0,0 +1,39 @@
+import { ResolvedEvent, FlushResult } from './types';
+export interface TransportOptions {
+    baseUrl: string;
+    apiKey: string;
+    timeout: number;
+    maxRetries: number;
+    retryBaseMs: number;
+}
+/**
+ * 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 declare class Transport {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly retryBaseMs;
+    constructor(options: TransportOptions);
+    /** Send a batch of events. Returns the number sent and failed. */
+    send(events: ResolvedEvent[]): Promise<FlushResult>;
+    /**
+     * 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.
+     */
+    sendSingleBestEffort(event: ResolvedEvent): Promise<boolean>;
+    private sleep;
+}
+//# sourceMappingURL=transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAgB,WAAW,EAAE,MAAM,SAAS,CAAC;AAEnE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,OAAO,EAAE,gBAAgB;IAQrC,kEAAkE;IAC5D,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAmEzD;;;;;;;;OAQG;IACG,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBlE,OAAO,CAAC,KAAK;CAGd"}

package/dist/types/types.d.ts

@@ -0,0 +1,128 @@
+/** Options for creating an AforoClient instance. */
+export interface AforoOptions {
+    /** Aforo API key for authentication. */
+    apiKey: string;
+    /** Base URL for the Aforo ingestor service. Defaults to https://api.aforo.ai */
+    baseUrl?: string;
+    /**
+     * Default product type stamped on every event (top-level `productType`).
+     * Required by the Aforo ingestor in production. One of API, AGENTIC_API,
+     * AI_AGENT, MCP_SERVER, GRPC_API, GRAPHQL_API, WEBSOCKET_API, MQTT_BROKER.
+     * Values are trimmed, uppercased and passed through. Default: "API".
+     * A per-event `productType` on `track()` overrides this.
+     */
+    productType?: string;
+    /** Maximum events to buffer before flushing (capped at 1000, the ingestor's batch limit). Default: 50 */
+    flushCount?: number;
+    /** Flush interval in milliseconds. Default: 5000 (5 seconds) */
+    flushInterval?: number;
+    /** Maximum events in the ring buffer. Oldest dropped on overflow. Default: 10000 */
+    maxQueueSize?: number;
+    /** Maximum retries on 5xx/timeout. Default: 3 */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff. Default: 1000 */
+    retryBaseMs?: number;
+    /** Request timeout in milliseconds. Default: 10000 */
+    timeout?: number;
+    /** Graceful shutdown timeout in milliseconds. Default: 5000 */
+    shutdownTimeoutMs?: number;
+}
+/** A usage event to track. */
+export interface TrackEvent {
+    /** Customer identifier (who is being billed). */
+    customerId: string;
+    /** Metric name (e.g., "api_calls", "ai_tokens", "GET /users"). */
+    metricName: string;
+    /** Quantity of usage. Must be > 0 (the ingestor rejects 0). Default: 1 */
+    quantity?: number;
+    /**
+     * Product type for this event. Overrides the client-level `productType`
+     * default. Trimmed, uppercased and sent as top-level `productType`.
+     */
+    productType?: string;
+    /** Optional override for idempotency key. Auto-generated if omitted. */
+    idempotencyKey?: string;
+    /** When the event occurred. Defaults to now. ISO 8601 string or epoch ms. */
+    occurredAt?: string | number;
+    /** Arbitrary key-value metadata attached to the event. */
+    metadata?: Record<string, string | number | boolean>;
+    /** Optional HTTP context, sent as top-level fields. */
+    endpointPath?: string;
+    httpMethod?: string;
+    statusCode?: number;
+    responseTimeMs?: number;
+}
+/** Internal event with all fields resolved (the exact wire shape). */
+export interface ResolvedEvent {
+    customerId: string;
+    metricName: string;
+    quantity: number;
+    idempotencyKey: string;
+    occurredAt: string;
+    productType: string;
+    metadata?: Record<string, string | number | boolean>;
+    endpointPath?: string;
+    httpMethod?: string;
+    statusCode?: number;
+    responseTimeMs?: number;
+    sessionId?: string;
+    sessionBoundary?: 'HEARTBEAT' | 'SESSION_END';
+}
+/** Batch request body sent to POST /v1/ingest/batch. */
+export interface BatchRequest {
+    events: ResolvedEvent[];
+}
+/** Response from the ingestor batch endpoint. */
+export interface BatchResponse {
+    accepted: number;
+    duplicates: number;
+    failed: number;
+    errors: Array<{
+        index: number;
+        message: string;
+    }>;
+    killedSessionIds?: string[];
+}
+/** Options for Express/Koa/Fastify middleware. */
+export interface MiddlewareOptions {
+    /** Aforo API key. */
+    apiKey: string;
+    /** Base URL for the ingestor. */
+    baseUrl?: string;
+    /**
+     * Product type stamped on every metered request (top-level `productType`).
+     * Default: the client default ("API", or `clientOptions.productType`).
+     */
+    productType?: string;
+    /**
+     * Metric to record for each request: a fixed name, or a function of the
+     * request/response. Default: `"api_calls"` (DEFAULT_METRIC_NAME).
+     *
+     * Must name a metric that exists in your Aforo catalog. The ingestor rejects
+     * unknown metrics, and one rejected event fails the whole batch it is in.
+     */
+    metricName?: string | ((req: any, res: any) => string);
+    /** Static quantity or function to derive from request/response. Requests with quantity <= 0 are not metered. */
+    quantity?: number | ((req: any, res: any) => number);
+    /**
+     * Aforo customer id: a fixed value, or a function of the request.
+     * Default: the authenticated user's id (`req.user.id` / `.sub`), then the
+     * `X-Customer-Id` header. Requests with no customer are not metered. The
+     * caller's `X-Api-Key` header is never used -- it is a secret, not an id.
+     */
+    customerId?: string | ((req: any) => string | null);
+    /** Paths to exclude from metering. Default: ["/health", "/ready", "/metrics", "/favicon.ico"] */
+    excludePaths?: string[];
+    /** Status codes to exclude. Default: none */
+    excludeStatusCodes?: number[];
+    /** Function to extract metadata from request/response. */
+    metadata?: (req: any, res: any) => Record<string, string | number | boolean>;
+    /** AforoClient options (flushCount, flushInterval, etc.) */
+    clientOptions?: Omit<AforoOptions, 'apiKey' | 'baseUrl'>;
+}
+/** Flush result for internal tracking. */
+export interface FlushResult {
+    sent: number;
+    failed: number;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@aforoai/metering",
+  "version": "1.0.0",
+  "description": "Aforo usage metering SDK — track API usage events with batching, retry, and framework middleware",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./middleware/express": {
+      "import": "./dist/esm/middleware/express.js",
+      "require": "./dist/cjs/middleware/express.js",
+      "types": "./dist/types/middleware/express.d.ts"
+    },
+    "./middleware/fastify": {
+      "import": "./dist/esm/middleware/fastify.js",
+      "require": "./dist/cjs/middleware/fastify.js",
+      "types": "./dist/types/middleware/fastify.d.ts"
+    },
+    "./middleware/koa": {
+      "import": "./dist/esm/middleware/koa.js",
+      "require": "./dist/cjs/middleware/koa.js",
+      "types": "./dist/types/middleware/koa.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "npm run build:cjs && npm run build:esm && npm run build:types",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "test": "jest --coverage",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.4.0"
+  },
+  "peerDependencies": {
+    "@types/express": ">=4.0.0",
+    "@types/koa": ">=2.0.0",
+    "fastify": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/express": { "optional": true },
+    "@types/koa": { "optional": true },
+    "fastify": { "optional": true }
+  },
+  "keywords": ["aforo", "metering", "usage", "billing", "api", "middleware", "express", "fastify", "koa"],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aforoai/SDKs.git",
+    "directory": "aforo-metering-sdks/node"
+  },
+  "homepage": "https://github.com/aforoai/SDKs/tree/main/aforo-metering-sdks/node#readme",
+  "bugs": {
+    "url": "https://github.com/aforoai/SDKs/issues"
+  }
+}