@aforoai/metering 1.1.2 → 2.0.0

package/dist/types/transport-core/core.d.ts

@@ -0,0 +1,355 @@
+/**
+ * Aforo Node transport core (wave 5, contract v2).
+ *
+ * THE ONE PLACE TO EDIT. This file lives in `node/src/transport-core/` and is
+ * copied, byte for byte, into every Node variant (`node-ws`, `node-mqtt`,
+ * `node-grpc`, `node-graphql`, `node-mcp`, `node-agent`, `mcp-proxy`) by
+ * `scripts/sync-transport.sh node`. Edit it here, then run the sync; CI fails
+ * when a copy differs. Normative behaviour: `contract/TRANSPORT-SPEC.md`.
+ *
+ * Self-contained on purpose: no imports (not even relative ones, so every
+ * module format and test runner that receives the copy can load it), only
+ * Node built-ins reached through globals (`fetch`, `AbortSignal`, `Buffer`,
+ * timers). Target ES2020.
+ *
+ * What it does, per client:
+ *   - one bounded FIFO queue (evict-oldest, reported as 'overflow');
+ *   - one long-lived flusher: `enqueue()` never sends, it only wakes the
+ *     flusher at `flushCount`; `flush()` hands work to the flusher and waits;
+ *     at most one ingest request is ever in flight;
+ *   - full-jitter retries, Retry-After in both forms (capped), a total
+ *     deadline per request that also covers reading the response body;
+ *   - redirects are never followed (the API key must not reach another
+ *     host): a 3xx keeps the batch queued and opens the breaker;
+ *   - each event is serialized once, at enqueue: an event JSON cannot
+ *     represent (BigInt, a cycle, NaN) is dropped there as 'invalid';
+ *   - 413 splits the batch, 2xx per-event `retryable` failures are requeued,
+ *     other 4xx are dropped as 'rejected';
+ *   - after the last retry (or on 401/403) the batch goes back to the front
+ *     of the queue with its keys and a breaker pauses the flusher;
+ *   - `shutdown()` drains until a deadline and reports leftovers as
+ *     'shutdown'; `enqueue()` after close reports 'closed';
+ *   - no signal handlers: a process `beforeExit` hook flushes within the
+ *     shutdown deadline. Apps call `shutdown()` from their own SIGTERM handler;
+ *   - `onAccepted(body, events)` sees the parsed 2xx body of every accepted
+ *     batch (for fields such as `killedSessionIds`); `onError` receives a
+ *     `CoreTransportError` whose `kind` says what happened.
+ */
+/** Why events were permanently dropped. See TRANSPORT-SPEC.md "Drop reasons". */
+export type CoreDropReason = 'overflow' | 'rejected' | 'invalid' | 'shutdown' | 'closed' | 'retry_exhausted';
+/**
+ * What an onError report is about. `outage` and `auth` keep the events queued
+ * (`willRetry` true); the others describe events that are gone.
+ *   - outage:   network errors, timeouts, 408/429/5xx after every retry, or
+ *               per-event `retryable` failures that never cleared
+ *   - auth:     HTTP 401/403, the API key is wrong or revoked
+ *   - rejected: the ingestor refused the events (other 4xx, 2xx per-event errors, a single event still 413)
+ *   - shutdown: still queued when the shutdown deadline passed
+ *   - closed:   tracked after shutdown (reported for the first, then every 1000th)
+ */
+export type CoreErrorKind = 'outage' | 'auth' | 'rejected' | 'shutdown' | 'closed';
+/**
+ * The error every onError report receives. `message` is for people; branch on
+ * `kind`. `events` are the events concerned: the queued ones for outage/auth,
+ * the dropped ones otherwise (empty when the ingestor did not name them).
+ */
+export declare class CoreTransportError<E = CoreEvent> extends Error {
+    readonly kind: CoreErrorKind;
+    readonly events: E[];
+    /** HTTP status of the answer that caused the report, when there was one. */
+    readonly status?: number;
+    /** True when the events are still queued and will be re-sent. */
+    readonly willRetry: boolean;
+    constructor(kind: CoreErrorKind, message: string, events: E[], options?: {
+        status?: number;
+    });
+}
+/** Every event the core sends carries the key the ingestor deduplicates on. */
+export interface CoreEvent {
+    idempotencyKey: string;
+}
+/** The subset of a fetch Response the core reads. */
+export interface CoreResponse {
+    status: number;
+    ok?: boolean;
+    headers: {
+        get(name: string): string | null;
+    };
+    text?(): Promise<string>;
+    json?(): Promise<unknown>;
+}
+/** The subset of fetch the core calls. Injectable for tests. */
+export type CoreFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+    redirect: 'manual';
+}) => Promise<CoreResponse>;
+/** Sleep that ends early (resolving) when `signal` aborts. Injectable for tests. */
+export type CoreSleep = (ms: number, signal?: AbortSignal) => Promise<void>;
+export interface CoreLogger {
+    debug(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+export interface TransportCoreOptions<E extends CoreEvent> {
+    /** Ingestor base URL. Must be https:// (plain http only for localhost, 127.0.0.1, ::1, or with allowInsecureHttp). */
+    baseUrl: string;
+    /** Tenant API key, sent only as X-API-Key. Never logged, never in an error or onDrop payload. */
+    apiKey: string;
+    /** Allow plain http:// to a non-local host. Default false. */
+    allowInsecureHttp?: boolean;
+    /** Path appended to baseUrl. Default '/v1/ingest/batch'. */
+    path?: string;
+    /** Sent as User-Agent, e.g. 'aforo-node/2.0.0'. */
+    userAgent?: string;
+    /** Extra request headers (e.g. X-Tenant-Id). Content-Type, X-API-Key and Content-Encoding cannot be overridden. */
+    headers?: Record<string, string>;
+    /** Events per request. Default 500, clamped to 1..1000. */
+    flushCount?: number;
+    /** Flush at least this often, in ms. Default 5000. */
+    flushIntervalMs?: number;
+    /** Queue capacity. Default 10 000. Overflow evicts the oldest event. */
+    maxQueueSize?: number;
+    /** Retries per batch before the breaker opens. Default 3. */
+    maxRetries?: number;
+    /** Backoff base in ms. Default 500. */
+    retryBaseMs?: number;
+    /** Backoff cap in ms. Default 30 000. */
+    retryMaxDelayMs?: number;
+    /** Retry-After cap in ms. Default 60 000. */
+    retryAfterMaxMs?: number;
+    /** First breaker cooldown in ms. Default 5000 (doubles, full jitter). */
+    breakerInitialMs?: number;
+    /** Breaker cooldown cap in ms. Default 300 000. */
+    breakerMaxMs?: number;
+    /** Total deadline per request in ms. Default 10 000. */
+    timeoutMs?: number;
+    /** shutdown() deadline in ms. Default 5000. */
+    shutdownTimeoutMs?: number;
+    /** Split a batch whose JSON body exceeds this many bytes. Default 4 MiB. */
+    targetRequestBodyBytes?: number;
+    /** Flush on the process 'beforeExit' event (within shutdownTimeoutMs). Default true. */
+    flushOnExit?: boolean;
+    /** Receives events that are lost for good. A throw is caught and logged. */
+    onDrop?: (events: E[], reason: CoreDropReason, detail?: string) => void;
+    /**
+     * Receives failures worth surfacing: breaker openings (`outage`, `auth`),
+     * rejections, shutdown leftovers and post-close tracking. Branch on
+     * `error.kind`, never on the message. A throw is caught and logged.
+     */
+    onError?: (error: CoreTransportError<E>) => void;
+    /**
+     * Called after every accepted (2xx) batch with the response body, the
+     * `{success, data}` envelope already unwrapped (`undefined` when the body was
+     * empty or not JSON), and the events of that batch. Use it to read fields
+     * such as `killedSessionIds`. A throw is caught and logged.
+     */
+    onAccepted?: (body: unknown, events: E[]) => void;
+    /** Log sink. Default: console with `logPrefix` (debug lines only when AFORO_DEBUG is set). */
+    logger?: CoreLogger;
+    /** Prefix for default log lines. Default '[aforo]'. */
+    logPrefix?: string;
+    /** Injectable for tests. Default: the global fetch, looked up on every request. */
+    fetch?: CoreFetch;
+    /** Injectable for tests. Default Date.now. */
+    clock?: () => number;
+    /** Injectable for tests. Default: an unref'd timer that ends when the signal aborts. */
+    sleep?: CoreSleep;
+    /** Injectable for tests. Default Math.random. */
+    random?: () => number;
+}
+/** What one flush cycle did. */
+export interface CoreFlushResult {
+    /** Events the ingestor accepted (including duplicates it already had). */
+    sent: number;
+    /** Events dropped for good in this cycle. */
+    failed: number;
+    /** Events put back on the queue (outage or per-event retryable). */
+    requeued: number;
+    /** Events still queued when the cycle ended. */
+    queued: number;
+}
+/** What shutdown() did. */
+export interface CoreShutdownResult extends CoreFlushResult {
+    /** Events still queued at the deadline, reported as 'shutdown'. */
+    leftover: number;
+    /** True when the deadline passed before the queue was empty. */
+    timedOut: boolean;
+}
+export declare const CORE_DEFAULTS: Readonly<{
+    path: "/v1/ingest/batch";
+    flushCount: 500;
+    maxBatchEvents: 1000;
+    flushIntervalMs: 5000;
+    maxQueueSize: 10000;
+    maxRetries: 3;
+    retryBaseMs: 500;
+    retryMaxDelayMs: 30000;
+    retryAfterMaxMs: 60000;
+    breakerInitialMs: 5000;
+    breakerMaxMs: 300000;
+    timeoutMs: 10000;
+    shutdownTimeoutMs: 5000;
+    targetRequestBodyBytes: number;
+}>;
+declare const INSPECT: unique symbol;
+/**
+ * Throws when `baseUrl` is not https:// (plain http only for a local host or
+ * with `allowInsecureHttp`). Returns the URL without trailing slashes.
+ */
+export declare function checkBaseUrl(baseUrl: string, allowInsecureHttp?: boolean): string;
+/** Full-jitter backoff: random(0, min(maxDelay, base * 2^attempt)). */
+export declare function fullJitter(attempt: number, baseMs: number, maxMs: number, random: () => number): number;
+/**
+ * Retry-After in ms: delta-seconds or an HTTP-date, capped at `maxMs`.
+ * Undefined when absent or unreadable (the caller then uses its own delay).
+ */
+export declare function parseRetryAfter(value: string | null | undefined, now: number, maxMs: number): number | undefined;
+/** Sleep on an unref'd timer; resolves early when `signal` aborts. */
+export declare const defaultSleep: CoreSleep;
+/**
+ * The Node transport core. One instance per SDK client.
+ *
+ * ```ts
+ * const core = new TransportCore<MyEvent>({ baseUrl, apiKey, onDrop });
+ * core.enqueue(event);          // never sends, never throws
+ * await core.flush();           // waits for the flusher to drain the queue
+ * await core.shutdown();        // drains until shutdownTimeoutMs, reports leftovers
+ * ```
+ */
+export declare class TransportCore<E extends CoreEvent> {
+    private readonly url;
+    private readonly headers;
+    private readonly flushCount;
+    private readonly flushIntervalMs;
+    private readonly maxRetries;
+    private readonly retryBaseMs;
+    private readonly retryMaxDelayMs;
+    private readonly retryAfterMaxMs;
+    private readonly breakerInitialMs;
+    private readonly breakerMaxMs;
+    private readonly timeoutMs;
+    private readonly shutdownTimeoutMs;
+    private readonly targetBytes;
+    private readonly fetchFn;
+    private readonly clock;
+    private readonly sleepFn;
+    private readonly random;
+    private readonly logger;
+    private readonly onDrop?;
+    private readonly onError?;
+    private readonly onAccepted?;
+    private readonly queue;
+    private dropped;
+    private overflowDrops;
+    private invalidDrops;
+    private closedDrops;
+    private sentTotal;
+    private inFlight;
+    private closedFlag;
+    private deadline;
+    private readonly stopController;
+    /** Aborted to wake the flusher from its idle wait (replaced after each wake). */
+    private idleWake;
+    /** Aborted to cut a breaker wait short (explicit flush / shutdown). */
+    private breakerWake;
+    private breakerOpens;
+    private breakerOpen;
+    /** ERROR line for this breaker opening (401/403 or a redirect) already written. */
+    private configErrorLogged;
+    private flushWaiters;
+    private readonly loop;
+    private shutdownPromise;
+    private readonly closingTotals;
+    private deadlineTimer;
+    /** Per-event retryable failures seen so far, keyed by event object. */
+    private readonly perEventRetries;
+    /** Highest per-event retry count in the last requeue, for the backoff before the resend. */
+    private perEventAttempt;
+    /** Each queued event's JSON, taken at enqueue. */
+    private readonly serialized;
+    /** Events taken off the queue that are being sent or waiting for a retry. */
+    private eventsInHand;
+    private shutdownSettled;
+    private exitKeepAlive;
+    constructor(options: TransportCoreOptions<E>);
+    /**
+     * Queue an event. Never sends and never throws. The event is serialized
+     * now, so later changes to the object are not sent; one JSON cannot
+     * represent is reported through onDrop(…, 'invalid'). After shutdown the
+     * event is reported through onDrop(…, 'closed'). Returns false in both cases.
+     */
+    enqueue(event: E): boolean;
+    /** Count and report events the caller rejected before queueing (reason 'invalid' or another). */
+    reportDrop(events: E[], reason: CoreDropReason, detail?: string): void;
+    /**
+     * Hand the queue to the flusher and wait for one drain cycle. Never runs a
+     * second concurrent send. While the breaker is open this makes one attempt
+     * now instead of waiting for the cooldown.
+     */
+    flush(): Promise<CoreFlushResult>;
+    /**
+     * Stop accepting events and drain until `shutdownTimeoutMs`. Each request
+     * in that window uses min(timeoutMs, time left). Events still queued at the
+     * deadline are reported through onDrop(…, 'shutdown'). Idempotent.
+     */
+    shutdown(): Promise<CoreShutdownResult>;
+    /** Events waiting in the queue. */
+    get queued(): number;
+    /** Events lost for good since creation (every reason, including unattributed per-event rejections). */
+    get droppedCount(): number;
+    /** Events the ingestor accepted since creation. */
+    get sentCount(): number;
+    /** True after shutdown() was called. */
+    get closed(): boolean;
+    /** True while the breaker pauses the flusher after an outage. */
+    get isBreakerOpen(): boolean;
+    /** Ingest requests in flight right now (0 or 1). */
+    get inFlightRequests(): number;
+    /** True while events are queued or a taken batch is being sent / retried. */
+    get busy(): boolean;
+    /**
+     * @internal Called from the process 'beforeExit' hook. When this core still
+     * holds events (or a shutdown is already running), it shuts down and holds
+     * the event loop open with one timer until the shutdown settles. Never
+     * longer than the shutdown deadline plus a second.
+     */
+    flushForExit(): void;
+    /** @internal Debug log, used by the exit hook. */
+    logDebug(message: string): void;
+    toJSON(): Record<string, unknown>;
+    [INSPECT](): string;
+    private wakeIdle;
+    private wakeBreaker;
+    private get pastDeadline();
+    private run;
+    private waitBackoff;
+    private waitIdle;
+    private waitBreaker;
+    /** Send everything queued, one request at a time. Stops on outage or deadline. */
+    private drainCycle;
+    /**
+     * Send one batch (splitting it when the body is too large or the ingestor
+     * answers 413). Returns true when the cycle must stop (outage or deadline);
+     * unsent events are already back at the front of the queue then.
+     */
+    private sendBatch;
+    /** Request body from the JSON taken at enqueue. */
+    private bodyFor;
+    private requeue;
+    /** `kept` are the events just put back on the queue (named in the onError report). */
+    private openBreaker;
+    private closeBreaker;
+    /** One chunk, with retries. Never throws. */
+    private sendWithRetry;
+    private post;
+    private handleAccepted;
+    private discardBody;
+    private readProblem;
+    private recordDrop;
+    private reportError;
+}
+export {};
+//# sourceMappingURL=core.d.ts.map

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

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

package/dist/types/types.d.ts

@@ -1,20 +1,32 @@
+import type { AforoClient } from './client.js';
 /**
- * Why a buffered event was permanently dropped by the SDK.
- * - 'overflow': the ring buffer was full — the OLDEST event was evicted to make room.
- * - 'retry_exhausted': a batch failed after all transport retries (ingest outage).
- * - 'rejected': the ingestor rejected the batch with a non-retryable 4xx, or
- *   rejected this event individually in a partially accepted batch.
+ * Why events were permanently lost. Every dropped event keeps its
+ * idempotency key, so re-tracking it after recovery is dedup-safe.
+ * - 'overflow': the queue was full — the OLDEST event was evicted to make room.
+ * - 'rejected': the ingestor refused the event (a non-retryable 4xx, a
+ *   per-event rejection inside an accepted batch, or 413 on a single event).
  * - 'invalid': the event failed a client-side check at track() (blank
  *   customerId/metricName, quantity <= 0, a field over the ingestor's size
- *   limit, a malformed occurredAt) and was never buffered or sent.
+ *   limit, a malformed occurredAt), or a middleware customer resolver
+ *   returned nothing. It was never queued or sent.
+ * - 'shutdown': still queued when the shutdown deadline passed.
+ * - 'closed': track() was called after shutdown().
+ * - 'retry_exhausted': kept for compatibility; not produced by 2.x (an outage
+ *   requeues the batch behind a breaker instead of dropping it).
  */
-export type DropReason = 'overflow' | 'retry_exhausted' | 'rejected' | 'invalid';
+export type DropReason = 'overflow' | 'retry_exhausted' | 'rejected' | 'invalid' | 'shutdown' | 'closed';
 /** Options for creating an AforoClient instance. */
 export interface AforoOptions {
-    /** Aforo API key for authentication. */
+    /** Aforo API key, sent as X-API-Key. Never logged or shown by inspect(). */
     apiKey: string;
-    /** Base URL for the Aforo ingestor service. Defaults to https://api.aforo.ai */
+    /**
+     * Base URL for the Aforo ingestor. Default https://api.aforo.ai.
+     * Must be https:// — plain http:// is accepted only for localhost,
+     * 127.0.0.1 and ::1, or with `allowInsecureHttp: true`.
+     */
     baseUrl?: string;
+    /** Allow a plain http:// baseUrl on a non-local host. Default false. */
+    allowInsecureHttp?: boolean;
     /**
      * Default product type stamped on every event (top-level `productType`).
      * Required by the Aforo ingestor in production. One of API, AGENTIC_API,
@@ -23,29 +35,34 @@ export interface AforoOptions {
      * 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 */
+    /** Events per request (capped at 1000, the ingestor's batch limit). Default: 500 */
     flushCount?: number;
-    /** Flush interval in milliseconds. Default: 5000 (5 seconds) */
+    /** Flush at least this often, in milliseconds. Default: 5000 */
     flushInterval?: number;
-    /** Maximum events in the ring buffer. Oldest dropped on overflow. Default: 10000 */
+    /** Queue capacity. The oldest event is dropped on overflow. Default: 10000 */
     maxQueueSize?: number;
-    /** Maximum retries on 5xx/timeout. Default: 3 */
+    /** Retries per batch on network errors, timeouts, 408, 429 and 5xx before the breaker opens. Default: 3 */
     maxRetries?: number;
-    /** Base delay in ms for exponential backoff. Default: 1000 */
+    /** Base delay in ms for full-jitter backoff. Default: 500 */
     retryBaseMs?: number;
-    /** Request timeout in milliseconds. Default: 10000 */
+    /** Total deadline per request, in milliseconds. Default: 10000 */
     timeout?: number;
-    /** Graceful shutdown timeout in milliseconds. Default: 5000 */
+    /** How long shutdown() keeps sending, in milliseconds. Default: 5000 */
     shutdownTimeoutMs?: number;
+    /**
+     * Flush queued events when the process is about to exit naturally
+     * (`beforeExit`), within shutdownTimeoutMs. Default true. The SDK installs
+     * no signal handlers: call `await client.shutdown()` from your own SIGTERM
+     * handler before exiting.
+     */
+    flushOnExit?: boolean;
     /**
      * OPT-IN hook invoked with events the SDK is about to lose permanently
-     * (buffer overflow, retry exhaustion, non-retryable rejection, or an event
-     * that failed client-side validation — reason 'invalid'), so the
-     * app can persist / alert / replay them. Dropped events keep their
-     * idempotency keys — re-submitting them via track() after recovery is
-     * dedup-safe. Default: none (drops are still counted in droppedCount and
-     * WARN-logged). Exceptions thrown by the hook are swallowed — a hook bug
-     * can never break flushing.
+     * (see DropReason), so the app can persist / alert / replay them. Dropped
+     * events keep their idempotency keys — re-submitting them via track() after
+     * recovery is dedup-safe. Default: none (drops are still counted in
+     * droppedCount and WARN-logged). An exception thrown by the hook is caught
+     * and logged; it never breaks flushing.
      */
     onDrop?: (events: ResolvedEvent[], reason: DropReason) => void;
 }
@@ -119,14 +136,22 @@ export interface BatchResponse {
     errors: Array<{
         index: number;
         message: string;
+        retryable?: boolean;
     }>;
     killedSessionIds?: string[];
 }
 /** Options for Express/Koa/Fastify middleware. */
 export interface MiddlewareOptions {
-    /** Aforo API key. */
-    apiKey: string;
-    /** Base URL for the ingestor. */
+    /**
+     * An AforoClient the app owns (recommended): the app can flush it, read
+     * droppedCount and call shutdown() from its SIGTERM handler. When omitted,
+     * the middleware creates one from apiKey/baseUrl/clientOptions and exposes
+     * it as `middleware.client`.
+     */
+    client?: AforoClient;
+    /** Aforo API key (only when `client` is not given). */
+    apiKey?: string;
+    /** Base URL for the ingestor (only when `client` is not given). */
     baseUrl?: string;
     /**
      * Product type stamped on every metered request (top-level `productType`).
@@ -138,43 +163,54 @@ export interface MiddlewareOptions {
      * 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.
+     * unknown metrics.
      */
     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.
+     * Who is billed for a request, from identity your app authenticated (the
+     * session, a verified JWT subject, an API-key lookup). Required unless
+     * `trustCustomerHeader` is true. Return null/undefined/'' when the request
+     * has no billable customer: the event is dropped as 'invalid' and counted;
+     * the request itself is never blocked.
+     */
+    customerResolver?: (req: any) => string | null | undefined;
+    /**
+     * @deprecated Use `customerResolver`. A function is used as the resolver; a
+     * fixed string bills every request to that customer.
      */
-    customerId?: string | ((req: any) => string | null);
+    customerId?: string | ((req: any) => string | null | undefined);
+    /**
+     * Read the customer from the `X-Customer-Id` request header. That header is
+     * set by whoever calls your API, so only turn this on when a trusted proxy
+     * in front of the app sets it and strips any client copy. Default false.
+     */
+    trustCustomerHeader?: boolean;
+    /**
+     * Collapse dynamic path segments before sending `endpointPath`
+     * (`/users/123` → `/users/:id`; the framework's route template wins when
+     * there is one). Default true, so per-id paths do not create unbounded
+     * label cardinality. Pass a function to normalize yourself, or false to send
+     * the raw path.
+     */
+    normalizePath?: boolean | ((path: string, req: any) => string);
     /** 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.) */
+    /** AforoClient options (flushCount, flushInterval, etc.) when the middleware creates the client. */
     clientOptions?: Omit<AforoOptions, 'apiKey' | 'baseUrl'>;
 }
 /** Flush result for internal tracking. */
 export interface FlushResult {
     sent: number;
     failed: number;
-    /** Why the batch failed, when failed > 0. Absent on success. */
-    reason?: DropReason;
-    /**
-     * Events the ingestor rejected individually inside a batch it otherwise
-     * accepted (per-event `errors[]` in the response). `index` is the position
-     * in the sent batch. Present only when the response identified them.
-     */
-    rejected?: Array<{
-        index: number;
-        message: string;
-    }>;
-    /** Server-provided explanation for a failed batch, when one was returned. */
-    message?: string;
+    /** Events put back on the queue (ingestor outage or a per-event retryable failure). */
+    requeued: number;
+    /** Events still queued after the flush. */
+    queued: number;
 }
 //# sourceMappingURL=types.d.ts.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aforoai/metering",
-  "version": "1.1.2",
+  "version": "2.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",

package/dist/cjs/buffer.d.ts

@@ -1,33 +0,0 @@
-import { ResolvedEvent } from './types.js';
-/**
- * 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;
-    /**
-     * Add an event to the buffer. On overflow, returns the evicted OLDEST
-     * event so the caller can surface the drop; returns null when no
-     * eviction occurred.
-     */
-    pushEvict(event: ResolvedEvent): ResolvedEvent | null;
-    /** 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

@@ -1 +0,0 @@
-{"version":3,"file":"buffer.d.ts","sourceRoot":"","sources":["../../src/buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;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;IAInC;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,GAAG,IAAI;IAiBrD,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"}