node-avo-inspector 1.2.0 → 2.0.0-beta.2

package/dist/AvoInspectorVersion.d.ts

@@ -0,0 +1,3 @@
+export declare const VERSION = "2.0.0";
+export declare const SPEC_VERSION = "3.0.1";
+export declare const LIB_PLATFORM = "node";

package/dist/AvoInspectorVersion.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIB_PLATFORM = exports.SPEC_VERSION = exports.VERSION = void 0;
+// SDK library version, sent on the wire as `libVersion`. Plain SemVer, no suffix.
+// Update this constant (and package.json "version") on every release.
+exports.VERSION = "2.0.0";
+// Version of avohq/spec-first-inspector-server-sdk this SDK implements.
+exports.SPEC_VERSION = "3.0.1";
+// Sent as `libPlatform` on every event and as the `X-Avo-Client` request header.
+exports.LIB_PLATFORM = "node";

package/dist/AvoLog.d.ts

@@ -0,0 +1,52 @@
+/** The event name sent for a track call whose event name is missing. */
+export declare const MISSING_EVENT_NAME = "Missing Event Name";
+export type DropReason = "queue full" | "send backlog full" | "internal error" | "unsent at exit" | "unconfirmed at exit";
+export declare class AvoLog {
+    static now: () => number;
+    private static windows;
+    private static exitListenerArmed;
+    private static exiting;
+    /** Events dropped because the unsent buffer or the send backlog is full. */
+    static dropped(count: number, reason: DropReason): void;
+    /** A batch answered with an HTTP status other than 200. Only the status is logged. */
+    static rejected(status: number): void;
+    /** A batch that could not be sent (network error, timeout, header guard). */
+    static failed(error: unknown): void;
+    /**
+     * An internal error. Only its type is printed: the error may come from reading a property
+     * (a throwing getter or proxy), so its message or stack can carry a property value.
+     */
+    static internal(error: unknown): void;
+    private static readonly errorTypes;
+    /** A track call without a usable event name, sent as MISSING_EVENT_NAME. */
+    static missingEventName(): void;
+    /** A streamId containing ':' (warned on every call before; now once per window). */
+    static streamIdColon(): void;
+    /**
+     * A tracked InspectorEvent with keys the SDK does not know (a typo such as `outputRef` or
+     * `eventname`). Only the key names are printed, JSON-quoted, at most
+     * MAX_LOGGED_OPTION_KEYS of them, each cut to MAX_LOGGED_OPTION_KEY_LENGTH characters;
+     * never a value.
+     */
+    static unknownEventKeys(keys: string[], known: string[]): void;
+    /**
+     * trackSchemaFromEvent called with something other than an InspectorEvent object, such
+     * as a 1.x call with the event name first. Nothing about the argument is printed.
+     */
+    static notAnInspectorEvent(): void;
+    /**
+     * Prints every pending count and resets its key. With `onlyExpired` (flush()), only keys
+     * whose window has expired; destroy() and the exit drain print them all.
+     */
+    static flushPending: (onlyExpired?: boolean) => void;
+    private static names;
+    private static noteNames;
+    private static takeNames;
+    private static occur;
+    private static seconds;
+    private static suffix;
+    private static updateExitListener;
+    private static onBeforeExit;
+    private static onExit;
+    private static write;
+}

package/dist/AvoLog.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AvoLog = exports.MISSING_EVENT_NAME = exports.INTERNAL_ERROR_MESSAGE = void 0;
+const fs_1 = require("fs");
+const utils_1 = require("./utils");
+// Lines about lost data and failed sends, written to stderr whatever the logging flag. Each
+// kind (per drop reason, HTTP status or failure reason) prints at most one line per 10 s:
+// the first occurrence prints at once, and later ones in the window are counted. A count is
+// printed with the next occurrence after the window, by flush() once the window has expired,
+// or by destroy() and the exit drain at once. "in the last Ns" is the real whole seconds
+// since the window began (at least 1). There is no timer. While a count is pending, a
+// "beforeExit" listener prints the expired ones (beforeExit also fires at every idle point of
+// a script whose only pending work is the SDK's, so it is not treated as the exit), and an
+// "exit" listener prints the rest, synchronously, when the process really exits.
+const WINDOW_MS = 10000;
+// How many names (unknown InspectorEvent keys, error types) a line prints, and how much of each key.
+const MAX_LOGGED_OPTION_KEYS = 5;
+const MAX_LOGGED_OPTION_KEY_LENGTH = 64;
+// Imports only utils, which imports nothing: the jest setup loads this module before test
+// files install their mocks, so it must not pull in the rest of the SDK.
+/** @internal The track rejection reason and internal-error log text (SPEC §4.2 step 5). */
+exports.INTERNAL_ERROR_MESSAGE = "Avo Inspector: something went wrong. Please report to support@avo.app.";
+/** The event name sent for a track call whose event name is missing. */
+exports.MISSING_EVENT_NAME = "Missing Event Name";
+class AvoLog {
+    /** Events dropped because the unsent buffer or the send backlog is full. */
+    static dropped(count, reason) {
+        AvoLog.occur("dropped:" + reason, count, (total, _more, seconds) => {
+            AvoLog.write("warn", `Avo Inspector: dropped ${total} event(s) (${reason}) in the last ${seconds}s.`);
+        });
+    }
+    /** A batch answered with an HTTP status other than 200. Only the status is logged. */
+    static rejected(status) {
+        AvoLog.occur("non200:" + status, 1, (total, _more, seconds) => {
+            AvoLog.write("warn", `Avo Inspector: ${total} batch(es) rejected with HTTP ${status} in the last ${seconds}s.`);
+        });
+    }
+    /** A batch that could not be sent (network error, timeout, header guard). */
+    static failed(error) {
+        // The two fixed transport reasons print as is; anything else (an Error thrown while
+        // sending, any other value) prints only its type, so neither the line nor the limiter
+        // key ever depends on an error's message.
+        const reason = error === "Request failed" || error === "Request timed out"
+            ? error
+            : "Request failed (" + AvoLog.errorType(error) + ")";
+        AvoLog.occur("failed:" + reason, 1, (_total, more, seconds) => {
+            AvoLog.write("error", "Avo Inspector: schema sending failed: " + reason + "." + AvoLog.suffix(more, seconds));
+        });
+    }
+    /**
+     * An internal error. Only its type is printed: the error may come from reading a property
+     * (a throwing getter or proxy), so its message or stack can carry a property value.
+     */
+    static internal(error) {
+        AvoLog.noteNames("internal", [AvoLog.errorType(error)]);
+        AvoLog.occur("internal", 1, (_total, more, seconds) => {
+            const types = AvoLog.takeNames("internal", (type) => type);
+            AvoLog.write("error", exports.INTERNAL_ERROR_MESSAGE + AvoLog.suffix(more, seconds) + " (" + types + ")");
+        });
+    }
+    /**
+     * @internal A fixed label for what was thrown, for any log line that reports a caught
+     * error; it never reads a field of the value. A proxy whose traps throw yields "unknown".
+     */
+    static errorType(error) {
+        try {
+            for (const [type, label] of AvoLog.errorTypes) {
+                if (error instanceof type) {
+                    return label;
+                }
+            }
+            return typeof error;
+        }
+        catch (e) {
+            return "unknown";
+        }
+    }
+    /** A track call without a usable event name, sent as MISSING_EVENT_NAME. */
+    static missingEventName() {
+        AvoLog.occur("missing-event-name", 1, (total, _more, seconds) => {
+            AvoLog.write("warn", `Avo Inspector: ${total} event(s) tracked without an event name in the last ${seconds}s, sent as "${exports.MISSING_EVENT_NAME}".`);
+        });
+    }
+    /** A streamId containing ':' (warned on every call before; now once per window). */
+    static streamIdColon() {
+        AvoLog.occur("streamid-colon", 1, (_total, more, seconds) => {
+            AvoLog.write("warn", "[Avo Inspector] Warning: streamId contains ':' which is not supported" + AvoLog.suffix(more, seconds));
+        });
+    }
+    /**
+     * A tracked InspectorEvent with keys the SDK does not know (a typo such as `outputRef` or
+     * `eventname`). Only the key names are printed, JSON-quoted, at most
+     * MAX_LOGGED_OPTION_KEYS of them, each cut to MAX_LOGGED_OPTION_KEY_LENGTH characters;
+     * never a value.
+     */
+    static unknownEventKeys(keys, known) {
+        AvoLog.noteNames("unknown-event-keys", keys.map((key) => (key.length > MAX_LOGGED_OPTION_KEY_LENGTH ? key.slice(0, MAX_LOGGED_OPTION_KEY_LENGTH) + "…" : key)));
+        AvoLog.occur("unknown-event-keys", 1, (_total, more, seconds) => {
+            const names = AvoLog.takeNames("unknown-event-keys", (key) => JSON.stringify(key));
+            AvoLog.write("warn", "[Avo Inspector] Warning: unknown InspectorEvent key(s) " + names + " ignored; the known keys are " +
+                known.join(", ") + AvoLog.suffix(more, seconds));
+        });
+    }
+    /**
+     * trackSchemaFromEvent called with something other than an InspectorEvent object, such
+     * as a 1.x call with the event name first. Nothing about the argument is printed.
+     */
+    static notAnInspectorEvent() {
+        AvoLog.occur("not-an-inspector-event", 1, (_total, more, seconds) => {
+            AvoLog.write("error", "[Avo Inspector] Error: since 2.0.0, trackSchemaFromEvent takes one InspectorEvent object; nothing was sent. " +
+                "Replace trackSchemaFromEvent(eventName, eventProperties) with trackSchemaFromEvent({ eventName, eventProperties })." +
+                AvoLog.suffix(more, seconds));
+        });
+    }
+    static noteNames(kind, names) {
+        const seen = AvoLog.names.get(kind) || [];
+        for (const name of names) {
+            if (seen.length > MAX_LOGGED_OPTION_KEYS) {
+                break;
+            }
+            if (seen.indexOf(name) < 0) {
+                seen.push(name);
+            }
+        }
+        AvoLog.names.set(kind, seen);
+    }
+    // The names noted for `kind`, formatted, joined and capped (", …" past the cap), and forgets
+    // them: the next line names only what is seen after this one.
+    static takeNames(kind, format) {
+        const seen = AvoLog.names.get(kind) || [];
+        AvoLog.names.delete(kind);
+        return seen.slice(0, MAX_LOGGED_OPTION_KEYS).map(format).join(", ") +
+            (seen.length > MAX_LOGGED_OPTION_KEYS ? ", …" : "");
+    }
+    /** @internal Test-only: forget every window. */
+    static _resetForTesting() {
+        AvoLog.windows.clear();
+        AvoLog.names.clear();
+        AvoLog.updateExitListener();
+    }
+    // Counts `amount` for `key`, or prints a line when the key's window is over (or new). The
+    // line reports this occurrence plus what the previous window counted, over the real time
+    // since that window began; with nothing counted it covers just this occurrence (1 s).
+    static occur(key, amount, print) {
+        const now = AvoLog.now();
+        const window = AvoLog.windows.get(key);
+        if (window && now - window.start < WINDOW_MS) {
+            window.suppressed += amount;
+            AvoLog.updateExitListener();
+            return;
+        }
+        const previous = window ? window.suppressed : 0;
+        AvoLog.windows.set(key, { start: now, suppressed: 0, print });
+        print(amount + previous, previous, previous > 0 ? AvoLog.seconds(now - window.start) : 1);
+        AvoLog.updateExitListener();
+    }
+    static seconds(elapsedMs) {
+        return Math.max(1, Math.floor(elapsedMs / 1000));
+    }
+    static suffix(more, seconds) {
+        return more > 0 ? ` (${more} more in the last ${seconds}s)` : "";
+    }
+    // Armed only while some key has a pending count: it prints them at a natural exit. It
+    // schedules nothing, so it never keeps the process alive.
+    static updateExitListener() {
+        let pending = false;
+        AvoLog.windows.forEach((window) => {
+            pending = pending || window.suppressed > 0;
+        });
+        if (pending && !AvoLog.exitListenerArmed) {
+            process.on("beforeExit", AvoLog.onBeforeExit);
+            process.on("exit", AvoLog.onExit);
+            AvoLog.exitListenerArmed = true;
+        }
+        else if (!pending && AvoLog.exitListenerArmed) {
+            process.removeListener("beforeExit", AvoLog.onBeforeExit);
+            process.removeListener("exit", AvoLog.onExit);
+            AvoLog.exitListenerArmed = false;
+        }
+    }
+    /** @internal From now on lines are written synchronously: the process is exiting. */
+    static enterExit() {
+        AvoLog.exiting = true;
+    }
+    static write(level, line) {
+        if (!AvoLog.exiting) {
+            console[level](line);
+            return;
+        }
+        try {
+            (0, fs_1.writeSync)(2, line + "\n");
+        }
+        catch (e) {
+            // stderr is gone; nothing else to do as the process exits.
+        }
+    }
+}
+exports.AvoLog = AvoLog;
+// Milliseconds from a monotonic clock; overridable in tests.
+AvoLog.now = utils_1.monotonicNowMs;
+AvoLog.windows = new Map();
+AvoLog.exitListenerArmed = false;
+// Set by the "exit" listener: from then on lines are written synchronously, because
+// console writes to a pipe are asynchronous and would be lost as the process ends.
+AvoLog.exiting = false;
+// Built-in error classes, most specific first. Matched by prototype, never by reading the
+// error's own `name`, which is writable and may be a getter.
+AvoLog.errorTypes = [
+    [TypeError, "TypeError"],
+    [RangeError, "RangeError"],
+    [ReferenceError, "ReferenceError"],
+    [SyntaxError, "SyntaxError"],
+    [URIError, "URIError"],
+    [EvalError, "EvalError"],
+    [Error, "Error"],
+];
+/**
+ * Prints every pending count and resets its key. With `onlyExpired` (flush()), only keys
+ * whose window has expired; destroy() and the exit drain print them all.
+ */
+AvoLog.flushPending = (onlyExpired = false) => {
+    const now = AvoLog.now();
+    for (const [key, window] of Array.from(AvoLog.windows)) {
+        if (window.suppressed === 0 || (onlyExpired && now - window.start < WINDOW_MS)) {
+            continue;
+        }
+        AvoLog.windows.delete(key);
+        window.print(window.suppressed, window.suppressed, AvoLog.seconds(now - window.start));
+    }
+    AvoLog.updateExitListener();
+};
+// Distinct names (unknown keys, error types) a kind has seen since its last line, in order,
+// for the line that reports them: a count line covers every occurrence it counts, so it
+// names all of theirs, not only the first. At most MAX_LOGGED_OPTION_KEYS + 1 are kept, so
+// the line can tell that more were seen.
+AvoLog.names = new Map();
+// Not the exit: the SDK's exit drain may resume the process. Only expired counts print,
+// as in flush(), so idle points cannot break the rate limit.
+AvoLog.onBeforeExit = () => {
+    AvoLog.flushPending(true);
+};
+// The real exit (natural, or process.exit()): print everything still pending.
+AvoLog.onExit = () => {
+    AvoLog.enterExit();
+    AvoLog.flushPending();
+};

package/dist/AvoNetworkCallsHandler.d.ts

@@ -2,18 +2,28 @@ import { EventSpecMetadata, PropertyValidationResult } from "./eventSpec/AvoEven
 export interface BaseBody {
     apiKey: string;
     appName: string;
-    appVersion: string;
+    appVersion: string | null;
     libVersion: string;
     env: string;
     libPlatform: "node";
     messageId: string;
-    trackingId: string;
-    sessionId: string;
+    streamId: string;
     anonymousId: string;
     createdAt: string;
     samplingRate: number;
     publicEncryptionKey?: string;
 }
+export interface ResolvedGatewayFields {
+    appVersion: string | null;
+    outputReference?: string;
+    originHint?: string;
+    /** True when the caller supplied at least one non-blank gateway option. */
+    gatewayScoped: boolean;
+}
+export interface CallStamp {
+    createdAt: string;
+    samplingRate: number;
+}
 export interface EventPropertyEncrypted {
     propertyName: string;
     propertyType: string;
@@ -27,7 +37,6 @@ export interface EventPropertyPlain {
 }
 export interface EventPropertyValidation {
     failedEventIds?: string[];
-    passedEventIds?: string[];
 }
 export type EventProperty = (EventPropertyEncrypted | EventPropertyPlain) & EventPropertyValidation;
 export interface EventSchemaBody extends BaseBody {
@@ -37,7 +46,8 @@ export interface EventSchemaBody extends BaseBody {
     avoFunction: boolean;
     eventId: string | null;
     eventHash: string | null;
-    streamId?: string;
+    outputReference?: string;
+    originHint?: string;
     eventSpecMetadata?: EventSpecMetadata;
 }
 export type InspectorBody = EventSchemaBody;
@@ -49,16 +59,45 @@ export declare class AvoNetworkCallsHandler {
     private libVersion;
     private samplingRate;
     private publicEncryptionKey?;
+    private inFlightRequests;
+    private aborted;
+    /** The valid mock-endpoint override in effect for this instance, read once, or null. */
+    readonly mockEndpoint: string | null;
     private static trackingEndpoint;
+    private static mockEndpointEnvVar;
+    private static requestTimeoutMs;
+    private static gzipThresholdBytes;
     constructor(apiKey: string, envName: string, appName: string, appVersion: string, libVersion: string, publicEncryptionKey?: string);
-    callInspectorWithBatchBody(inEvents: Array<InspectorBody>): Promise<void>;
+    /**
+     * The test-only endpoint override. Fail-closed: a prod instance never honors it,
+     * whatever the surrounding process environment says. A value that is not an http(s)
+     * URL is ignored (with a one-time warning), so callers only ever see a valid URL.
+     */
+    static mockEndpointFor(envName: string): string | null;
+    private static warnRedirect;
+    private static warnedMockEndpoint;
+    private static warnOnce;
+    /** The sampling rate last returned by the Inspector API (1 until a response sets it). */
+    getSamplingRate(): number;
+    /** Aborts every request still in flight (used by AvoInspector.destroy). */
+    abortInFlight(): void;
+    /**
+     * POSTs one batch. Resolves with the HTTP status code (the batch is never retried);
+     * rejects with "Request failed" / "Request timed out" on transport failures, or when
+     * a header value cannot be transmitted safely.
+     */
+    callInspectorWithBatchBody(inEvents: Array<InspectorBody>): Promise<number | void>;
+    private static gzipAsync;
+    private post;
+    /** Builds the wire body for one event, encrypting property values when configured. */
     bodyForEventSchemaCall(anonymousId: string, eventName: string, eventProperties: Array<{
         propertyName: string;
         propertyType: string;
         children?: any;
     }>, eventId: string | null, eventHash: string | null, rawEventProperties?: {
         [propName: string]: any;
-    }): EventSchemaBody;
+    }, gatewayFields?: ResolvedGatewayFields, stamp?: CallStamp): EventSchemaBody;
+    /** Returns the event properties, with values encrypted when encryption applies. */
     buildEventProperties(eventProperties: Array<{
         propertyName: string;
         propertyType: string;
@@ -66,7 +105,15 @@ export declare class AvoNetworkCallsHandler {
     }>, rawEventProperties?: {
         [propName: string]: any;
     }): Array<EventProperty>;
-    bodyForValidatedEventSchemaCall(anonymousId: string, eventName: string, eventProperties: Array<EventProperty>, eventId: string | null, eventHash: string | null, eventSpecMetadata: EventSpecMetadata, propertyResults: PropertyValidationResult[]): EventSchemaBody;
+    /** Builds the wire body for one event, including its event-spec validation results. */
+    bodyForValidatedEventSchemaCall(anonymousId: string, eventName: string, eventProperties: Array<EventProperty>, eventId: string | null, eventHash: string | null, eventSpecMetadata: EventSpecMetadata, propertyResults: PropertyValidationResult[], gatewayFields?: ResolvedGatewayFields, stamp?: CallStamp): EventSchemaBody;
+    /**
+     * A property with its failed event IDs, and those of its object properties merged into its
+     * children. A list's children are its element schemas; each object element gets the
+     * results of the properties it has (a list of objects is validated across all its items).
+     */
+    private static withValidation;
+    private static applyAvoFunctionFields;
     private encryptProperties;
     private createBaseCallBody;
 }