node-avo-inspector 2.0.0-beta.1 → 2.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 2.0.0
+## 2.0.0 (2026-10-22)
 
 Implements [avohq/spec-first-inspector-server-sdk](https://github.com/avohq/spec-first-inspector-server-sdk) v3.0.1: the `/inspector/v2/track` endpoint, batching with `flush()` and `destroy()`, gzip, and gateway fields. This is a breaking release; see [Upgrading from 1.x to 2.0](README.md#upgrading-from-1x-to-20) in the README.
 

package/README.md

@@ -318,6 +318,8 @@ To test against a local mock server, set the `AVO_INSPECTOR_MOCK_ENDPOINT` envir
 
 Update the `VERSION` constant in `src/AvoInspectorVersion.ts` and the `version` in `package.json` on every release. `VERSION` is sent to Avo as `libVersion`, and a unit test fails if the two differ.
 
+`npm pack` and `npm publish` run the `prepack` script, which deletes `dist/` and rebuilds it from `src/`, so a stale local `dist/` (it is git-ignored) is not packed. This needs npm lifecycle scripts enabled: with `ignore-scripts` set, `prepack` is skipped and whatever is in `dist/` is packed. Before publishing, run `npm pack --dry-run` and check that it prints the `prepack` build and lists the files you expect.
+
 ## Conformance suite
 
 `scripts/run-conformance.sh` builds the SDK and runs the spec's conformance suite (36 fixtures) against the harness in `conformance/avo-inspector-conformance.js` (runner contract 1.1.0). It fetches the spec at the pinned commit into `.spec-repo/`; set `SPEC_DIR` to use a local checkout instead.

package/dist/AvoBatchQueue.d.ts

@@ -0,0 +1,73 @@
+import { InspectorBody } from "./AvoNetworkCallsHandler";
+export declare const MAX_TIMER_MS = 2147483647;
+export declare const MAX_IN_FLIGHT_SENDS = 4;
+export declare const MAX_WAITING_EVENTS = 10000;
+export declare const BACKPRESSURE_WAITING_EVENTS = 1000;
+export declare const BACKPRESSURE_MAX_WAIT_MS = 10000;
+export interface AvoBatchOptions {
+    batchSize: number;
+    batchFlushSeconds: number;
+    maxQueueSize: number;
+    disableBatchTimer: boolean;
+}
+/**
+ * In-memory pending batch buffer. Node runs this on a single thread, so appending and
+ * the swap-and-clear in drain() are atomic without a lock; the send itself happens in
+ * the dispatch callback, after the buffer has been swapped out. At most
+ * MAX_IN_FLIGHT_SENDS dispatches run at once; later batches wait in order.
+ */
+export declare class AvoBatchQueue<T> {
+    private options;
+    private dispatch;
+    private dropped;
+    private track;
+    private buffer;
+    private waiting;
+    private waitingEvents;
+    private inFlight;
+    private inFlightEventCount;
+    private capacityWaiters;
+    private capacityTimer;
+    private flushTimer;
+    private bufferOutcome;
+    /**
+     * @param dispatch sends one batch; must not reject.
+     * @param dropped the outcome for a batch discarded before it was sent.
+     * @param track called with each batch's outcome promise as soon as it is swapped out.
+     */
+    constructor(options: AvoBatchOptions, dispatch: (batch: Array<InspectorBody>) => Promise<T>, dropped: T, track?: (outcome: Promise<T>) => Promise<T>);
+    /** Events in the unsent buffer (bounded by maxQueueSize). */
+    get length(): number;
+    /** Events in batches waiting for a send slot (bounded by MAX_WAITING_EVENTS). */
+    get waitingLength(): number;
+    /** Events in batches being sent. */
+    get inFlightEvents(): number;
+    /**
+     * Appends an event and evaluates the size trigger. Returns the send promise when
+     * this call dispatched a batch, otherwise null.
+     */
+    enqueue(event: InspectorBody): Promise<T> | null;
+    /**
+     * The outcome of the batch that will carry the events buffered now, whichever drain (size
+     * trigger, timer, flush) swaps them out. Null when the buffer is empty.
+     */
+    bufferedBatchOutcome(): Promise<T> | null;
+    /** Swaps out every buffered event and dispatches them as one batch. */
+    drain(): Promise<T> | null;
+    /**
+     * Resolves once fewer than BACKPRESSURE_WAITING_EVENTS events wait for a send slot (at
+     * once if they already do), when the backlog overflows, and at the latest after
+     * BACKPRESSURE_MAX_WAIT_MS. clear() resolves it too.
+     */
+    whenBelowBackpressure(): Promise<void>;
+    /** Tracks waiting on backpressure. */
+    get capacityWaiterCount(): number;
+    private releaseCapacityWaiters;
+    /** Discards every buffered or waiting event unsent and cancels the scheduled flush. */
+    clear(): void;
+    private startSends;
+    private dropOldestWaiting;
+    private scheduleFlush;
+    private clearTimer;
+    get hasScheduledFlush(): boolean;
+}

package/dist/AvoBatchQueue.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AvoBatchQueue = exports.BACKPRESSURE_MAX_WAIT_MS = exports.BACKPRESSURE_WAITING_EVENTS = exports.MAX_WAITING_EVENTS = exports.MAX_IN_FLIGHT_SENDS = exports.MAX_TIMER_MS = void 0;
+const AvoLog_1 = require("./AvoLog");
+// setTimeout fires almost at once for delays above this (2^31 - 1 ms, about 24.8 days).
+exports.MAX_TIMER_MS = 2147483647;
+// Batch sends in flight at once. Batches swapped out beyond this wait for a free slot, so
+// a fast producer or a slow endpoint cannot open an unbounded number of requests.
+exports.MAX_IN_FLIGHT_SENDS = 4;
+// Events that may wait for a send slot, across all waiting batches. Separate from
+// maxQueueSize, which bounds only the unsent buffer; past this the oldest waiting events
+// are dropped.
+exports.MAX_WAITING_EVENTS = 10000;
+// Backpressure: from this many events waiting for a send slot, an awaited track waits until
+// fewer wait (see whenBelowBackpressure), so awaited loops slow to the speed of the sends.
+exports.BACKPRESSURE_WAITING_EVENTS = 1000;
+// The longest a track waits on backpressure: one request timeout.
+exports.BACKPRESSURE_MAX_WAIT_MS = 10000;
+/**
+ * In-memory pending batch buffer. Node runs this on a single thread, so appending and
+ * the swap-and-clear in drain() are atomic without a lock; the send itself happens in
+ * the dispatch callback, after the buffer has been swapped out. At most
+ * MAX_IN_FLIGHT_SENDS dispatches run at once; later batches wait in order.
+ */
+class AvoBatchQueue {
+    /**
+     * @param dispatch sends one batch; must not reject.
+     * @param dropped the outcome for a batch discarded before it was sent.
+     * @param track called with each batch's outcome promise as soon as it is swapped out.
+     */
+    constructor(options, dispatch, dropped, track = (outcome) => outcome) {
+        this.options = options;
+        this.dispatch = dispatch;
+        this.dropped = dropped;
+        this.track = track;
+        this.buffer = [];
+        this.waiting = [];
+        this.waitingEvents = 0;
+        this.inFlight = 0;
+        this.inFlightEventCount = 0;
+        // Resolved once fewer than BACKPRESSURE_WAITING_EVENTS events wait, when the backlog
+        // overflows, when the wait timer fires, or by clear().
+        this.capacityWaiters = [];
+        // Ref'd while there are waiters: a stalled awaited loop is pending work, so "beforeExit"
+        // does not fire in the middle of it. Fires after BACKPRESSURE_MAX_WAIT_MS at the latest.
+        this.capacityTimer = null;
+        this.flushTimer = null;
+        // Settled with the outcome of the batch that takes the current buffer, whichever drain
+        // swaps it out (or `dropped` if clear() discards it). Created on demand.
+        this.bufferOutcome = null;
+    }
+    /** Events in the unsent buffer (bounded by maxQueueSize). */
+    get length() {
+        return this.buffer.length;
+    }
+    /** Events in batches waiting for a send slot (bounded by MAX_WAITING_EVENTS). */
+    get waitingLength() {
+        return this.waitingEvents;
+    }
+    /** Events in batches being sent. */
+    get inFlightEvents() {
+        return this.inFlightEventCount;
+    }
+    /**
+     * Appends an event and evaluates the size trigger. Returns the send promise when
+     * this call dispatched a batch, otherwise null.
+     */
+    enqueue(event) {
+        this.buffer.push(event);
+        const overflow = this.buffer.length - this.options.maxQueueSize;
+        if (overflow > 0) {
+            this.buffer.splice(0, overflow);
+            AvoLog_1.AvoLog.dropped(overflow, "queue full");
+        }
+        if (this.buffer.length >= this.options.batchSize) {
+            return this.drain();
+        }
+        this.scheduleFlush();
+        return null;
+    }
+    /**
+     * The outcome of the batch that will carry the events buffered now, whichever drain (size
+     * trigger, timer, flush) swaps them out. Null when the buffer is empty.
+     */
+    bufferedBatchOutcome() {
+        if (this.buffer.length === 0) {
+            return null;
+        }
+        if (this.bufferOutcome === null) {
+            let settle;
+            const promise = new Promise((resolve) => (settle = resolve));
+            this.bufferOutcome = { promise, settle };
+        }
+        return this.bufferOutcome.promise;
+    }
+    /** Swaps out every buffered event and dispatches them as one batch. */
+    drain() {
+        this.clearTimer();
+        if (this.buffer.length === 0) {
+            return null;
+        }
+        const batch = this.buffer;
+        this.buffer = [];
+        const outcome = new Promise((settle) => {
+            this.waiting.push({ events: batch, settle });
+        });
+        if (this.bufferOutcome !== null) {
+            this.bufferOutcome.settle(outcome);
+            this.bufferOutcome = null;
+        }
+        this.waitingEvents += batch.length;
+        this.startSends();
+        const excess = this.waitingEvents - exports.MAX_WAITING_EVENTS;
+        if (excess > 0) {
+            this.dropOldestWaiting(excess);
+            AvoLog_1.AvoLog.dropped(excess, "send backlog full");
+            // An awaited loop stalls near BACKPRESSURE_WAITING_EVENTS, so an overflow means the
+            // callers are not awaiting: release them all. Calls that are not awaited therefore
+            // hold at most the waiters registered since the last overflow (under one batch),
+            // while an awaited loop that reaches the cap is still throttled between overflows.
+            this.releaseCapacityWaiters(true);
+        }
+        return this.track(outcome);
+    }
+    /**
+     * Resolves once fewer than BACKPRESSURE_WAITING_EVENTS events wait for a send slot (at
+     * once if they already do), when the backlog overflows, and at the latest after
+     * BACKPRESSURE_MAX_WAIT_MS. clear() resolves it too.
+     */
+    whenBelowBackpressure() {
+        if (this.waitingEvents < exports.BACKPRESSURE_WAITING_EVENTS) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.capacityWaiters.push(resolve);
+            if (this.capacityTimer === null) {
+                this.capacityTimer = setTimeout(() => {
+                    this.capacityTimer = null;
+                    this.releaseCapacityWaiters(true);
+                }, exports.BACKPRESSURE_MAX_WAIT_MS);
+            }
+        });
+    }
+    /** Tracks waiting on backpressure. */
+    get capacityWaiterCount() {
+        return this.capacityWaiters.length;
+    }
+    releaseCapacityWaiters(all = false) {
+        if (!all && this.waitingEvents >= exports.BACKPRESSURE_WAITING_EVENTS) {
+            return;
+        }
+        if (this.capacityTimer !== null) {
+            clearTimeout(this.capacityTimer);
+            this.capacityTimer = null;
+        }
+        const waiters = this.capacityWaiters;
+        this.capacityWaiters = [];
+        waiters.forEach((resolve) => resolve());
+    }
+    /** Discards every buffered or waiting event unsent and cancels the scheduled flush. */
+    clear() {
+        this.clearTimer();
+        this.buffer = [];
+        if (this.bufferOutcome !== null) {
+            this.bufferOutcome.settle(this.dropped);
+            this.bufferOutcome = null;
+        }
+        const discarded = this.waiting;
+        this.waiting = [];
+        this.waitingEvents = 0;
+        discarded.forEach((batch) => batch.settle(this.dropped));
+        this.releaseCapacityWaiters(true);
+    }
+    startSends() {
+        while (this.inFlight < exports.MAX_IN_FLIGHT_SENDS && this.waiting.length > 0) {
+            const batch = this.waiting.shift();
+            this.waitingEvents -= batch.events.length;
+            this.inFlight++;
+            this.inFlightEventCount += batch.events.length;
+            const done = (outcome) => {
+                this.inFlight--;
+                this.inFlightEventCount -= batch.events.length;
+                batch.settle(outcome);
+                this.startSends();
+            };
+            // A dispatch that throws or rejects is an internal error: its events are lost, so both
+            // are reported. The slot is still freed and the batch still settles.
+            const failedInternally = (err) => {
+                AvoLog_1.AvoLog.internal(err);
+                AvoLog_1.AvoLog.dropped(batch.events.length, "internal error");
+                done(this.dropped);
+            };
+            let sent;
+            try {
+                sent = this.dispatch(batch.events);
+            }
+            catch (err) {
+                // Settled asynchronously, like any other dispatch outcome.
+                sent = Promise.reject(err);
+            }
+            sent.then(done, failedInternally);
+        }
+        this.releaseCapacityWaiters();
+    }
+    dropOldestWaiting(count) {
+        while (count > 0 && this.waiting.length > 0) {
+            const batch = this.waiting[0];
+            const removed = batch.events.splice(0, Math.min(count, batch.events.length)).length;
+            this.waitingEvents -= removed;
+            count -= removed;
+            if (batch.events.length === 0) {
+                this.waiting.shift();
+                batch.settle(this.dropped);
+            }
+        }
+    }
+    // Fires once the oldest buffered event is batchFlushSeconds old. Unref'd so it never
+    // holds the process open.
+    scheduleFlush() {
+        if (this.options.disableBatchTimer || this.flushTimer !== null) {
+            return;
+        }
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            this.drain();
+        }, Math.min(this.options.batchFlushSeconds * 1000, exports.MAX_TIMER_MS));
+        this.flushTimer.unref();
+    }
+    clearTimer() {
+        if (this.flushTimer !== null) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    get hasScheduledFlush() {
+        return this.flushTimer !== null;
+    }
+}
+exports.AvoBatchQueue = AvoBatchQueue;

package/dist/AvoDeduplicator.d.ts

@@ -1,11 +1,18 @@
+interface Registration {
+    time: number;
+    key: string;
+    generation: number;
+}
 export declare class AvoDeduplicator {
-    avoFunctionsEvents: {
-        [time: number]: string;
-    };
-    manualEvents: {
-        [time: number]: string;
-    };
+    avoFunctionsEvents: Array<Registration>;
+    manualEvents: Array<Registration>;
+    private avoFunctionsHead;
+    private manualHead;
     private msToConsiderOld;
+    private now;
+    private avoFunctionsLatest;
+    private manualLatest;
+    private nextGeneration;
     avoFunctionsEventsParams: {
         [key: string]: {
             [propName: string]: any;
@@ -27,5 +34,7 @@ export declare class AvoDeduplicator {
     }, checkInAvoFunctions: boolean): boolean;
     private lookForEventParamsIn;
     private clearOldEvents;
+    private expire;
     private _clearEvents;
 }
+export {};

package/dist/AvoDeduplicator.js

@@ -4,9 +4,21 @@ exports.AvoDeduplicator = void 0;
 const utils_1 = require("./utils");
 class AvoDeduplicator {
     constructor() {
-        this.avoFunctionsEvents = {};
-        this.manualEvents = {};
+        // Every registration, oldest first; `head` is the first one not yet expired. Cleanup pops
+        // from the front, so its cost is amortised O(1) per call.
+        this.avoFunctionsEvents = [];
+        this.manualEvents = [];
+        this.avoFunctionsHead = 0;
+        this.manualHead = 0;
         this.msToConsiderOld = 500;
+        // Milliseconds from a monotonic clock: the log must stay in time order, and a wall clock
+        // stepping back (NTP, manual change) would stall expiry. Replaceable in tests.
+        this.now = utils_1.monotonicNowMs;
+        // The generation of each key's latest registration. A key's params always belong to its
+        // latest registration, so only that registration's expiry may delete them.
+        this.avoFunctionsLatest = {};
+        this.manualLatest = {};
+        this.nextGeneration = 0;
         // Keyed by streamId\0eventName to prevent cross-stream suppression on server
         this.avoFunctionsEventsParams = {};
         this.manualEventsParams = {};
@@ -17,12 +29,15 @@ class AvoDeduplicator {
     shouldRegisterEvent(eventName, params, fromAvoFunction, streamId = "") {
         this.clearOldEvents();
         const key = AvoDeduplicator.dedupKey(eventName, streamId);
+        const registration = { time: this.now(), key, generation: this.nextGeneration++ };
         if (fromAvoFunction) {
-            this.avoFunctionsEvents[Date.now()] = key;
+            this.avoFunctionsEvents.push(registration);
+            this.avoFunctionsLatest[key] = registration.generation;
             this.avoFunctionsEventsParams[key] = params;
         }
         else {
-            this.manualEvents[Date.now()] = key;
+            this.manualEvents.push(registration);
+            this.manualLatest[key] = registration.generation;
             this.manualEventsParams[key] = params;
         }
         let checkInAvoFunctions = !fromAvoFunction;
@@ -81,34 +96,41 @@ class AvoDeduplicator {
         return false;
     }
     clearOldEvents() {
-        const now = Date.now();
-        for (const time in this.avoFunctionsEvents) {
-            if (this.avoFunctionsEvents.hasOwnProperty(time)) {
-                const timestamp = Number(time) || 0;
-                if (now - timestamp > this.msToConsiderOld) {
-                    const key = this.avoFunctionsEvents[time];
-                    delete this.avoFunctionsEvents[time];
-                    delete this.avoFunctionsEventsParams[key];
-                }
-            }
+        const now = this.now();
+        this.avoFunctionsHead = this.expire(this.avoFunctionsEvents, this.avoFunctionsHead, this.avoFunctionsEventsParams, this.avoFunctionsLatest, now);
+        this.manualHead = this.expire(this.manualEvents, this.manualHead, this.manualEventsParams, this.manualLatest, now);
+        if (this.avoFunctionsHead > 1024 && this.avoFunctionsHead * 2 > this.avoFunctionsEvents.length) {
+            this.avoFunctionsEvents = this.avoFunctionsEvents.slice(this.avoFunctionsHead);
+            this.avoFunctionsHead = 0;
         }
-        for (const time in this.manualEvents) {
-            if (this.manualEvents.hasOwnProperty(time)) {
-                const timestamp = Number(time) || 0;
-                if (now - timestamp > this.msToConsiderOld) {
-                    const key = this.manualEvents[time];
-                    delete this.manualEvents[time];
-                    delete this.manualEventsParams[key];
-                }
+        if (this.manualHead > 1024 && this.manualHead * 2 > this.manualEvents.length) {
+            this.manualEvents = this.manualEvents.slice(this.manualHead);
+            this.manualHead = 0;
+        }
+    }
+    // Pops every registration older than msToConsiderOld and deletes a key's params only when
+    // the popped registration is still that key's latest; returns the new head.
+    expire(registrations, head, paramsByKey, latestByKey, now) {
+        while (head < registrations.length && now - registrations[head].time > this.msToConsiderOld) {
+            const { key, generation } = registrations[head];
+            if (latestByKey[key] === generation) {
+                delete paramsByKey[key];
+                delete latestByKey[key];
             }
+            head++;
         }
+        return head;
     }
     // used in tests
     _clearEvents() {
-        this.avoFunctionsEvents = {};
-        this.manualEvents = {};
+        this.avoFunctionsEvents = [];
+        this.manualEvents = [];
+        this.avoFunctionsHead = 0;
+        this.manualHead = 0;
         this.avoFunctionsEventsParams = {};
         this.manualEventsParams = {};
+        this.avoFunctionsLatest = {};
+        this.manualLatest = {};
     }
 }
 exports.AvoDeduplicator = AvoDeduplicator;

package/dist/AvoInspector.d.ts

@@ -1,6 +1,41 @@
 import { AvoInspectorEnvValueType } from "./AvoInspectorEnv";
 import { AvoNetworkCallsHandler } from "./AvoNetworkCallsHandler";
 import { AvoDeduplicator } from "./AvoDeduplicator";
+/**
+ * One observed event, the single argument of `trackSchemaFromEvent`. The gateway fields
+ * are for a gateway-scoped Inspector API key; blank values are treated as absent.
+ */
+export interface InspectorEvent {
+    /** The event name. A missing, empty or whitespace-only name is sent as "Missing Event Name". */
+    eventName: string;
+    /** The event's properties. Absent or null: an event with no properties. */
+    eventProperties?: {
+        [propName: string]: any;
+    } | null;
+    /** Optional stream id to correlate events. */
+    streamId?: string;
+    /** Reference of the gateway output this observation was bound for. Absent = gateway checkpoint. */
+    outputReference?: string;
+    /** Low-cardinality label of the source the event came from (e.g. "web"). Never a user id. */
+    originHint?: string;
+    /** App version of the source that produced this event; overrides the instance version. */
+    originAppVersion?: string;
+}
+/**
+ * The gateway fields of a Codegen call (`_avoFunctionTrackSchemaFromEvent`), with the same
+ * meaning as on InspectorEvent. Not re-exported from the package root, but not marked internal:
+ * stripInternal would drop it from the declarations while that public method still uses it.
+ */
+export interface CodegenGatewayFields {
+    outputReference?: string;
+    originHint?: string;
+    originAppVersion?: string;
+}
+type SchemaEntry = {
+    propertyName: string;
+    propertyType: string;
+    children?: any;
+};
 export declare class AvoInspector {
     environment: AvoInspectorEnvValueType;
     avoNetworkCallsHandler: AvoNetworkCallsHandler;
@@ -12,45 +47,116 @@ export declare class AvoInspector {
     private eventSpecCache;
     private eventValidator;
     private generatedAnonymousId;
-    private pendingCount;
-    private keepAliveTimer;
+    private batchSize;
+    private batchQueue;
+    private destroyed;
+    private destroyWaiters;
+    private pending;
+    private validations;
+    private drainScheduled;
+    private drainThisTurn;
+    private untilDestroyed;
+    private untilGivenUp;
+    /** The exit drain ran out of time for validations: their events are sent unvalidated. */
+    private giveUpValidations;
+    private get pendingCount();
     private trackPending;
+    private static instancesWithWork;
+    private static exitDrainArmed;
+    private static exitReportArmed;
+    private static exitDeadline;
+    private static waitingValidations;
+    private releaseWaiting;
+    private validationOutcomes;
+    private giveUpWaiters;
+    private static lastTrackAt;
+    private static validationGraceUsedFor;
+    private static explicitFlushDeadlines;
+    private static drainOnExit;
+    private static reportOnExit;
+    private static armExitDrain;
+    private static disarmExitDrain;
+    private updateExitDrain;
     private static _shouldLog;
+    /** Whether the SDK writes its diagnostic log lines (shared by every instance). */
     static get shouldLog(): boolean;
     static set shouldLog(enable: boolean);
+    /**
+     * Creates an Inspector instance. A missing or unsupported `env` falls back to dev.
+     *
+     * @throws if `apiKey` or `version` is blank, or `apiKey` contains a character that
+     * cannot be sent in an HTTP header.
+     */
     constructor(options: {
         apiKey: string;
         env: AvoInspectorEnvValueType;
         version: string;
         appName?: string;
         publicEncryptionKey?: string;
+        /** Flush when this many events are buffered. Default 30; always 1 in dev. */
+        batchSize?: number;
+        /** Flush once the oldest buffered event is this many seconds old. Default 30. */
+        batchFlushSeconds?: number;
+        /** Maximum buffered events; the oldest are dropped first. Default 1000. */
+        maxQueueSize?: number;
+        /** Start no background flush timer (recommended for serverless). Default false. */
+        disableBatchTimer?: boolean;
     });
-    trackSchemaFromEvent(eventName: string, eventProperties: {
-        [propName: string]: any;
-    }, streamId?: string): Promise<Array<{
-        propertyName: string;
-        propertyType: string;
-        children?: any;
-    }>>;
+    private static resolveBatchOptions;
+    /**
+     * Resolves the gateway options for one event. outputReference / originHint are
+     * omitted when blank; appVersion is the per-event override, null for a
+     * source-scoped event without one, else the instance version.
+     */
+    private resolveGatewayFields;
+    private static warnUnknownEventKeys;
+    /**
+     * Extracts the event schema and queues it for the Inspector API.
+     *
+     * Resolves with the schema once the event is queued. In dev (batch size 1) the send
+     * happens within the call and a non-200 response resolves `[]`; with batching the
+     * batch's HTTP outcome is not observable here. Buffered events are only delivered
+     * by a later size or time trigger, or by `flush()` — call `flush()` before exit.
+     *
+     * Anything but an object (such as a 1.x call `trackSchemaFromEvent(name, properties)`)
+     * sends nothing, prints an always-on error naming the fix, and resolves `[]`.
+     */
+    trackSchemaFromEvent(event: InspectorEvent): Promise<Array<SchemaEntry>>;
+    /**
+     * Codegen entry point: like `trackSchemaFromEvent`, and additionally records the
+     * Avo function's `eventId` / `eventHash` so the event is sent with `avoFunction: true`.
+     */
     _avoFunctionTrackSchemaFromEvent(eventName: string, eventProperties: {
         [propName: string]: any;
-    }, eventId: string, eventHash: string, streamId?: string): Promise<Array<{
-        propertyName: string;
-        propertyType: string;
-        children?: any;
-    }>>;
+    }, eventId: string, eventHash: string, streamId?: string, options?: CodegenGatewayFields): Promise<Array<SchemaEntry>>;
+    private track;
     /**
-     * Try to fetch event spec and validate, then send a single event call.
-     * If validation succeeds, sends a validated event (with results merged in).
-     * If unavailable, sends a plain event.
-     *
-     * Uses trackPending() to keep the Node process alive until the work completes,
-     * so short-lived processes (CLIs) don't exit before the send finishes — even
-     * when the caller doesn't await the returned promise.
+     * Codegen/manual deduplication applies only to plain calls. A call carrying gateway
+     * options is a distinct observation per gateway output and is always sent.
+     */
+    private shouldRegisterEvent;
+    /**
+     * Samples the event, then queues it. When event spec validation is active the spec
+     * is fetched (or read from cache) first, so the event joins the queue once its
+     * validation results are merged in; flush() awaits that fetch before draining.
      */
-    private sendEventWithOptionalValidation;
-    private doSendEventWithOptionalValidation;
+    private sampleAndEnqueue;
+    private enqueue;
+    private sendBatch;
+    private isValidationActive;
+    /**
+     * Sends every buffered event, then waits until all in-flight sends (and spec fetches
+     * that will enqueue) have completed or `timeoutMs` (default 10000) has elapsed.
+     * Resolves `true` if, when it resolves, this instance has nothing buffered, waiting or in
+     * flight (always after destroy()), and `false` if the timeout won. Never rejects. Call it
+     * before process exit or before a serverless handler returns.
+     */
+    flush(timeoutMs?: number): Promise<boolean>;
+    private hasDrained;
+    private flushWithin;
+    /** Turns the SDK's diagnostic logging on or off for every instance. */
     enableLogging(enable: boolean): void;
+    /** Returns the schema of `eventProperties` without tracking or sending anything. */
     extractSchema(eventProperties: {
         [propName: string]: any;
     }, shouldLogIfEnabled?: boolean): Array<{
@@ -63,5 +169,12 @@ export declare class AvoInspector {
      * validation succeeds, or null if unavailable (prod, no spec, fetch error).
      */
     private fetchAndValidate;
+    /**
+     * Cancels and cleans up: discards the pending batch unsent, abandons in-flight
+     * requests and stops the flush timer. Does not flush. After destroy() the instance
+     * is terminated and trackSchemaFromEvent resolves [] without sending; a call still
+     * waiting on a spec fetch or on its immediate send also resolves [].
+     */
     destroy(): void;
 }
+export {};