@aforoai/metering 1.0.0 → 2.0.0

package/dist/cjs/middleware/fastify.js

@@ -1,25 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fastifyPlugin = fastifyPlugin;
-const client_1 = require("../client");
-const common_1 = require("./common");
+const common_js_1 = require("./common.js");
 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.
+ * Fastify plugin that records one usage event per request in the
+ * `onResponse` hook (after the response is sent).
  *
  * ```typescript
+ * import { AforoClient } from '@aforoai/metering';
  * import { fastifyPlugin } from '@aforoai/metering/middleware/fastify';
- * fastify.register(fastifyPlugin, { apiKey: process.env.AFORO_API_KEY, productType: 'API' });
+ * const aforo = new AforoClient({ apiKey: process.env.AFORO_API_KEY!, productType: 'API' });
+ * fastify.register(fastifyPlugin, { client: aforo, customerResolver: (request) => request.user?.aforoCustomerId });
  * ```
+ *
+ * When the plugin creates its own client (apiKey instead of client), it shuts
+ * that client down in Fastify's onClose hook. A client you pass in is yours to shut down.
  */
 async function fastifyPlugin(fastify, options) {
-    const client = new client_1.AforoClient({
-        apiKey: options.apiKey,
-        baseUrl: options.baseUrl,
-        ...options.clientOptions,
-    });
+    const lookupCustomer = (0, common_js_1.customerLookup)(options, (request) => request.headers?.['x-customer-id']);
+    const owned = !options.client;
+    const client = (0, common_js_1.middlewareClient)(options);
     const excludePaths = options.excludePaths ?? DEFAULT_EXCLUDE_PATHS;
     const excludeStatusCodes = options.excludeStatusCodes ?? [];
     fastify.addHook('onResponse', (request, reply, done) => {
@@ -27,62 +28,41 @@ async function fastifyPlugin(fastify, options) {
             const path = request.url || '/';
             const method = request.method || 'UNKNOWN';
             const statusCode = reply.statusCode || 0;
-            if ((0, common_1.isPreflight)(method))
+            if ((0, common_js_1.isPreflight)(method))
                 return done();
             if (excludePaths.some((p) => path.startsWith(p)))
                 return done();
             if (excludeStatusCodes.includes(statusCode))
                 return done();
-            const metricName = (0, common_1.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 = (0, common_1.firstNonEmpty)(request.user?.id, request.headers?.['x-customer-id']);
-            }
-            if (!customerId)
-                return done();
+            const quantity = typeof options.quantity === 'function' ? options.quantity(request, reply) : options.quantity ?? 1;
             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,
+                customerId: lookupCustomer(request) ?? '',
+                metricName: (0, common_js_1.resolveMetricName)(options, request, reply),
                 quantity,
-                metadata,
+                metadata: options.metadata ? options.metadata(request, reply) : undefined,
                 productType: options.productType,
-                endpointPath: (0, common_1.endpointPathOf)(path),
-                httpMethod: method,
+                endpointPath: (0, common_js_1.endpointPathFor)(options, path, request, request.routeOptions?.url ?? request.routerPath),
+                httpMethod: (0, common_js_1.httpMethodOf)(method),
                 statusCode,
                 ...(typeof elapsed === 'number' ? { responseTimeMs: Math.round(elapsed) } : {}),
-            }).catch(() => { });
+            }).catch((err) => console.debug(`[aforo] metering skipped: ${err?.message ?? err}`));
         }
-        catch {
-            // Never let metering affect the API
+        catch (err) {
+            // Never let metering affect the API.
+            console.debug(`[aforo] metering skipped: ${err?.message ?? err}`);
         }
         done();
     });
-    fastify.addHook('onClose', async () => {
-        await client.shutdown();
-    });
+    if (owned) {
+        fastify.addHook('onClose', async () => {
+            await client.shutdown();
+        });
+    }
 }
 // Mark as fastify plugin
 fastifyPlugin[Symbol.for('skip-override')] = true;

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

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

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

@@ -1,13 +1,18 @@
-import { MiddlewareOptions } from '../types';
+import { MiddlewareOptions } from '../types.js';
 /**
- * Koa middleware that automatically captures API usage events.
- *
- * Captures after `await next()` completes — runs after the response is generated.
+ * Koa middleware that records one usage event per request, after `await next()`.
+ * Metering never throws into the request.
  *
  * ```typescript
+ * import { AforoClient } from '@aforoai/metering';
  * import { koaMiddleware } from '@aforoai/metering/middleware/koa';
- * app.use(koaMiddleware({ apiKey: process.env.AFORO_API_KEY, productType: 'API' }));
+ * const aforo = new AforoClient({ apiKey: process.env.AFORO_API_KEY!, productType: 'API' });
+ * app.use(koaMiddleware({ client: aforo, customerResolver: (ctx) => ctx.state.user?.aforoCustomerId }));
  * ```
+ *
+ * `customerResolver` receives the Koa context.
  */
-export declare function koaMiddleware(options: MiddlewareOptions): (ctx: any, next: any) => Promise<void>;
+export declare function koaMiddleware(options: MiddlewareOptions): ((ctx: any, next: any) => Promise<void>) & {
+    client: import("../client.js").AforoClient;
+};
 //# sourceMappingURL=koa.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"koa.d.ts","sourceRoot":"","sources":["../../../src/middleware/koa.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAKhD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,iBAAiB,UAgBM,GAAG,QAAQ,GAAG;;EAkC3E"}

package/dist/cjs/middleware/koa.js

@@ -1,82 +1,64 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.koaMiddleware = koaMiddleware;
-const client_1 = require("../client");
-const common_1 = require("./common");
+const common_js_1 = require("./common.js");
 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.
+ * Koa middleware that records one usage event per request, after `await next()`.
+ * Metering never throws into the request.
  *
  * ```typescript
+ * import { AforoClient } from '@aforoai/metering';
  * import { koaMiddleware } from '@aforoai/metering/middleware/koa';
- * app.use(koaMiddleware({ apiKey: process.env.AFORO_API_KEY, productType: 'API' }));
+ * const aforo = new AforoClient({ apiKey: process.env.AFORO_API_KEY!, productType: 'API' });
+ * app.use(koaMiddleware({ client: aforo, customerResolver: (ctx) => ctx.state.user?.aforoCustomerId }));
  * ```
+ *
+ * `customerResolver` receives the Koa context.
  */
 function koaMiddleware(options) {
-    const client = new client_1.AforoClient({
-        apiKey: options.apiKey,
-        baseUrl: options.baseUrl,
-        ...options.clientOptions,
-    });
+    // customerResolver receives the Koa context; the deprecated customerId function kept receiving ctx.request.
+    const legacy = options.customerId;
+    const lookupCustomer = (0, common_js_1.customerLookup)({
+        ...options,
+        customerResolver: options.customerResolver ?? (typeof legacy === 'function' ? (ctx) => legacy(ctx?.request) : undefined),
+    }, (ctx) => ctx?.get?.('x-customer-id') || ctx?.request?.headers?.['x-customer-id']);
+    const client = (0, common_js_1.middlewareClient)(options);
     const excludePaths = options.excludePaths ?? DEFAULT_EXCLUDE_PATHS;
     const excludeStatusCodes = options.excludeStatusCodes ?? [];
-    return async function aforoMeteringMiddleware(ctx, next) {
+    const handler = 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 ((0, common_1.isPreflight)(method))
+            if ((0, common_js_1.isPreflight)(method))
                 return;
             if (excludePaths.some((p) => path.startsWith(p)))
                 return;
             if (excludeStatusCodes.includes(statusCode))
                 return;
-            const metricName = (0, common_1.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 = (0, common_1.firstNonEmpty)(ctx.state?.user?.id, ctx.get('x-customer-id'));
-            }
-            if (!customerId)
-                return;
+            const quantity = typeof options.quantity === 'function' ? options.quantity(ctx.request, ctx.response) : options.quantity ?? 1;
             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,
+                customerId: lookupCustomer(ctx) ?? '',
+                metricName: (0, common_js_1.resolveMetricName)(options, ctx.request, ctx.response),
                 quantity,
-                metadata,
+                metadata: options.metadata ? options.metadata(ctx.request, ctx.response) : undefined,
                 productType: options.productType,
-                endpointPath: (0, common_1.endpointPathOf)(path),
-                httpMethod: method,
+                endpointPath: (0, common_js_1.endpointPathFor)(options, path, ctx, ctx._matchedRoute ?? ctx.routerPath),
+                httpMethod: (0, common_js_1.httpMethodOf)(method),
                 statusCode,
                 responseTimeMs: Date.now() - startTime,
-            }).catch(() => { });
+            }).catch((err) => console.debug(`[aforo] metering skipped: ${err?.message ?? err}`));
         }
-        catch {
-            // Never let metering affect the API
+        catch (err) {
+            // Never let metering affect the API.
+            console.debug(`[aforo] metering skipped: ${err?.message ?? err}`);
         }
     };
+    return Object.assign(handler, { client });
 }
 //# sourceMappingURL=koa.js.map

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

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

package/dist/cjs/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