avo-inspector 3.2.0 → 3.2.3

package/dist/lite/AvoBatcherLite.d.ts

@@ -1,8 +1,8 @@
-import { type AvoNetworkCallsHandler, type EventProperty } from "./AvoNetworkCallsHandlerLite";
+import { type EventSchemaBody, type AvoNetworkCallsHandler, type EventProperty, type TrackOptions } from "./AvoNetworkCallsHandlerLite";
 import type { EventSpecMetadata } from "../eventSpec/AvoEventSpecFetchTypes";
 export interface AvoBatcherType {
     handleSessionStarted: () => void;
-    handleTrackSchema: (eventName: string, schema: EventProperty[], eventId: string | null, eventHash: string | null, eventSpecMetadata?: EventSpecMetadata) => void;
+    handleTrackSchema: (eventName: string, schema: EventProperty[], eventId: string | null, eventHash: string | null, eventSpecMetadata?: EventSpecMetadata, options?: TrackOptions) => void;
 }
 export declare class AvoBatcher implements AvoBatcherType {
     private events;
@@ -10,7 +10,13 @@ export declare class AvoBatcher implements AvoBatcherType {
     private readonly networkCallsHandler;
     constructor(networkCallsHandler: AvoNetworkCallsHandler);
     handleSessionStarted(): void;
-    handleTrackSchema(eventName: string, schema: EventProperty[], eventId: string | null, eventHash: string | null, eventSpecMetadata?: EventSpecMetadata): void;
+    handleTrackSchema(eventName: string, schema: EventProperty[], eventId: string | null, eventHash: string | null, eventSpecMetadata?: EventSpecMetadata, options?: TrackOptions): void;
+    /**
+     * Queues an event body as it is, keeping its messageId and createdAt. Used to
+     * retry a failed immediate send: the request may have reached the server, and
+     * a resend must stay the same event rather than become a new one.
+     */
+    handleEventBody(eventBody: EventSchemaBody): void;
     private checkIfBatchNeedsToBeSent;
     private saveEvents;
     static get cacheKey(): string;

package/dist/lite/AvoBatcherLite.js

@@ -22,18 +22,45 @@ var AvoBatcher = /** @class */ (function () {
         });
     }
     AvoBatcher.prototype.handleSessionStarted = function () {
+        if (this.networkCallsHandler.isQueueingDisabled()) {
+            return;
+        }
         this.events.push(this.networkCallsHandler.bodyForSessionStartedCall());
         this.saveEvents();
+        if (this.networkCallsHandler.isSendingDisabled()) {
+            return;
+        }
         this.checkIfBatchNeedsToBeSent();
     };
-    AvoBatcher.prototype.handleTrackSchema = function (eventName, schema, eventId, eventHash, eventSpecMetadata) {
-        this.events.push(this.networkCallsHandler.bodyForEventSchemaCall(eventName, schema, eventId, eventHash, eventSpecMetadata));
+    AvoBatcher.prototype.handleTrackSchema = function (eventName, schema, eventId, eventHash, eventSpecMetadata, options) {
+        // v2 only: when the events could never be sent under any configuration (an api
+        // key that cannot be a header), queueing would only grow the stored queue.
+        if (this.networkCallsHandler.isQueueingDisabled()) {
+            return;
+        }
+        this.handleEventBody(this.networkCallsHandler.bodyForEventSchemaCall(eventName, schema, eventId, eventHash, eventSpecMetadata, undefined, options));
+    };
+    /**
+     * Queues an event body as it is, keeping its messageId and createdAt. Used to
+     * retry a failed immediate send: the request may have reached the server, and
+     * a resend must stay the same event rather than become a new one.
+     */
+    AvoBatcher.prototype.handleEventBody = function (eventBody) {
+        if (this.networkCallsHandler.isQueueingDisabled()) {
+            return;
+        }
+        this.events.push(eventBody);
         this.saveEvents();
         if (AvoInspectorLite_1.AvoInspector.shouldLog) {
             console.log("Avo Inspector: saved event " +
-                eventName +
+                eventBody.eventName +
                 " with schema " +
-                JSON.stringify(schema));
+                JSON.stringify(eventBody.eventProperties));
+        }
+        // v2 only: sending has stopped for this page, but the queue is kept and saved,
+        // so a later page load can still deliver these events.
+        if (this.networkCallsHandler.isSendingDisabled()) {
+            return;
         }
         this.checkIfBatchNeedsToBeSent();
     };
@@ -41,18 +68,24 @@ var AvoBatcher = /** @class */ (function () {
         var batchSize = this.events.length;
         if (batchSize === 0)
             return;
+        // One batch at a time. The queue is checked again when the batch in flight
+        // completes, so waiting events do not depend on a later event to be sent.
+        if (this.networkCallsHandler.isBatchInFlight())
+            return;
         var now = Date.now();
         var timeSinceLastFlushAttempt = now - this.batchFlushAttemptTimestamp;
-        var sendBySize = batchSize % AvoInspectorLite_1.AvoInspector.batchSize == 0;
+        var sendBySize = batchSize % AvoInspectorLite_1.AvoInspector.batchSize === 0;
         var sendByTime = timeSinceLastFlushAttempt >= AvoInspectorLite_1.AvoInspector.batchFlushSeconds * 1000;
         var avoBatcher = this;
         if (sendBySize || sendByTime) {
             this.batchFlushAttemptTimestamp = now;
             var sendingEvents_1 = avoBatcher.events;
             avoBatcher.events = [];
-            this.networkCallsHandler.callInspectorWithBatchBody(sendingEvents_1, function (error) {
+            this.networkCallsHandler.callInspectorWithBatchBody(sendingEvents_1, function (error, retryEvents) {
                 if (error != null) {
-                    avoBatcher.events = avoBatcher.events.concat(sendingEvents_1);
+                    // v2 names the events worth retrying (it drops what can never pass);
+                    // otherwise the whole batch goes back.
+                    avoBatcher.events = avoBatcher.events.concat(retryEvents !== undefined ? retryEvents : sendingEvents_1);
                     if (AvoInspectorLite_1.AvoInspector.shouldLog) {
                         console.log("Avo Inspector: batch sending failed: " +
                             error.message +
@@ -65,6 +98,12 @@ var AvoBatcher = /** @class */ (function () {
                     }
                 }
                 avoBatcher.saveEvents();
+                // After a success, send what queued up meanwhile. After a failure the
+                // queue waits for the next event or flush, as before, rather than
+                // retrying in a loop against a failing network.
+                if (error == null && !avoBatcher.networkCallsHandler.isSendingDisabled()) {
+                    avoBatcher.checkIfBatchNeedsToBeSent();
+                }
             });
         }
     };

package/dist/lite/AvoInspectorLite.d.ts

@@ -28,6 +28,7 @@ export declare class AvoInspectorLite {
         suffix?: string;
     });
     trackSchemaFromEvent(eventName: string, eventProperties: Record<string, any>): Promise<EventProperty[]>;
+    private _trackSchemaFromEventWithOptions;
     private _avoFunctionTrackSchemaFromEvent;
     trackSchema(eventName: string, eventSchema: Array<{
         propertyName: string;
@@ -35,6 +36,7 @@ export declare class AvoInspectorLite {
         encryptedPropertyValue?: string;
         children?: any;
     }>): Promise<void>;
+    private _trackSchemaWithOptions;
     private trackSchemaInternal;
     enableLogging(enable: boolean): void;
     extractSchema(eventProperties: Record<string, any>, shouldLogIfEnabled?: boolean): Promise<Array<{

package/dist/lite/AvoInspectorLite.js

@@ -61,7 +61,27 @@ var AvoInspectorLite = /** @class */ (function () {
             throw new Error("[Avo Inspector] No API key provided. Inspector can't operate without API key.");
         }
         else {
-            this.apiKey = options.apiKey;
+            // Trimmed once, here, so only the trimmed value is ever stored — on both
+            // transports. A key pasted out of a config file or read from an env var
+            // keeps its trailing newline, which on v2 has to survive being a request
+            // header. (On v1 the body is the only copy; v1 does not trim it either, so
+            // the untrimmed 3.2.0 behaviour was a failed key lookup, not a working send.)
+            //
+            // This is deliberately not a duplicate of what the platform already does.
+            // XMLHttpRequest strips surrounding whitespace from a header value before
+            // validating it, so a trailing-newline key reaches the server trimmed with
+            // no error — verified against a real server, not read off the spec. But it
+            // does that to the header only. The same key also travels in the request
+            // body, which nothing trims, so leaning on the platform is what would
+            // CREATE a divergence rather than avoid one: the header would carry "key"
+            // while the body carried the raw value. v2 reads the header and ignores
+            // the body copy, but that copy exists precisely so one body shape also
+            // serves v1 — and v1 reads its api key from the body.
+            //
+            // Trimming at the single source keeps the two identical, for 3 bytes
+            // gzipped. It is not a substitute for the send path's try/catch: an
+            // embedded control character survives trim and is still caught there.
+            this.apiKey = options.apiKey.trim();
         }
         if ((0, utils_1.isValueEmpty)(options.version)) {
             throw new Error("[Avo Inspector] No version provided. Many features of Inspector rely on versioning. Please provide comparable string version, i.e. integer or semantic.");
@@ -79,7 +99,12 @@ var AvoInspectorLite = /** @class */ (function () {
             AvoInspectorLite._shouldLog = false;
         }
         AvoInspectorLite.avoStorage = new AvoStorage_1.AvoStorage(AvoInspectorLite._shouldLog, options.suffix != null ? options.suffix : "");
-        this.avoNetworkCallsHandler = new AvoNetworkCallsHandlerLite_1.AvoNetworkCallsHandlerLite(this.apiKey, this.environment.toString(), options.appName || "", this.version, libVersion);
+        this.avoNetworkCallsHandler = new AvoNetworkCallsHandlerLite_1.AvoNetworkCallsHandlerLite(this.apiKey, this.environment.toString(), options.appName || "", this.version, libVersion, 
+        // INTERNAL: the web GTM tag template's client, which selects the v2
+        // transport. Only the script-tag bootstrap sets it (src/browser.js, from
+        // window.inspector.__CLIENT__), so it is deliberately not in the options
+        // type. Without it the SDK stays on v1 exactly as 3.2.0.
+        options._client);
         this.avoBatcher = new AvoBatcherLite_1.AvoBatcher(this.avoNetworkCallsHandler);
     }
     Object.defineProperty(AvoInspectorLite, "batchSize", {
@@ -124,9 +149,37 @@ var AvoInspectorLite = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    // Not a thin delegation: 3.2.0's public methods were async with the whole body
+    // in a try/catch, so even a call without a receiver (a destructured method)
+    // logged and resolved rather than throwing, and still does.
     AvoInspectorLite.prototype.trackSchemaFromEvent = function (eventName, eventProperties) {
         return __awaiter(this, void 0, void 0, function () {
-            var eventSchema, e_1;
+            var e_1;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        _a.trys.push([0, 2, , 3]);
+                        return [4 /*yield*/, this._trackSchemaFromEventWithOptions(eventName, eventProperties, undefined)];
+                    case 1: return [2 /*return*/, _a.sent()];
+                    case 2:
+                        e_1 = _a.sent();
+                        console.error("Avo Inspector: something went wrong. Please report to support@avo.app.", e_1);
+                        return [2 /*return*/, []];
+                    case 3: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    // INTERNAL — not public API. `trackSchemaFromEvent` with the web GTM tag template's
+    // gateway options, mirroring the full build's internal method (the script-tag
+    // bootstrap uses the full build). Private and underscore-named like
+    // `_avoFunctionTrackSchemaFromEvent`, so it stays out of the typings (a line
+    // comment, not JSDoc, so none of this is emitted into the .d.ts either). The
+    // options have an effect only when the instance has a client (v2); without
+    // one they are ignored entirely.
+    AvoInspectorLite.prototype._trackSchemaFromEventWithOptions = function (eventName, eventProperties, options) {
+        return __awaiter(this, void 0, void 0, function () {
+            var eventSchema, e_2;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
@@ -140,11 +193,11 @@ var AvoInspectorLite = /** @class */ (function () {
                         return [4 /*yield*/, this.extractSchema(eventProperties, false)];
                     case 1:
                         eventSchema = _a.sent();
-                        this.trackSchemaInternal(eventName, eventSchema, null, null);
+                        this.trackSchemaInternal(eventName, eventSchema, null, null, options);
                         return [2 /*return*/, eventSchema];
                     case 2:
-                        e_1 = _a.sent();
-                        console.error("Avo Inspector: something went wrong. Please report to support@avo.app.", e_1);
+                        e_2 = _a.sent();
+                        console.error("Avo Inspector: something went wrong. Please report to support@avo.app.", e_2);
                         return [2 /*return*/, []];
                     case 3: return [2 /*return*/];
                 }
@@ -153,7 +206,7 @@ var AvoInspectorLite = /** @class */ (function () {
     };
     AvoInspectorLite.prototype._avoFunctionTrackSchemaFromEvent = function (eventName, eventProperties, eventId, eventHash) {
         return __awaiter(this, void 0, void 0, function () {
-            var eventSchema, e_2;
+            var eventSchema, e_3;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
@@ -170,8 +223,8 @@ var AvoInspectorLite = /** @class */ (function () {
                         this.trackSchemaInternal(eventName, eventSchema, eventId, eventHash);
                         return [2 /*return*/, eventSchema];
                     case 2:
-                        e_2 = _a.sent();
-                        console.error("Avo Inspector: something went wrong. Please report to support@avo.app.", e_2);
+                        e_3 = _a.sent();
+                        console.error("Avo Inspector: something went wrong. Please report to support@avo.app.", e_3);
                         return [2 /*return*/, []];
                     case 3: return [2 /*return*/];
                 }
@@ -179,6 +232,33 @@ var AvoInspectorLite = /** @class */ (function () {
         });
     };
     AvoInspectorLite.prototype.trackSchema = function (eventName, eventSchema) {
+        return __awaiter(this, void 0, void 0, function () {
+            var e_4;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        _a.trys.push([0, 2, , 3]);
+                        return [4 /*yield*/, this._trackSchemaWithOptions(eventName, eventSchema, undefined)];
+                    case 1:
+                        _a.sent();
+                        return [3 /*break*/, 3];
+                    case 2:
+                        e_4 = _a.sent();
+                        console.error("Avo Inspector: something went wrong. Please report to support@avo.app.", e_4);
+                        return [3 /*break*/, 3];
+                    case 3: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    // INTERNAL — not public API. `trackSchema` with the web GTM tag template's
+    // gateway options, mirroring the full build's internal method (the script-tag
+    // bootstrap uses the full build). Private and underscore-named like
+    // `_avoFunctionTrackSchemaFromEvent`, so it stays out of the typings (a line
+    // comment, not JSDoc, so none of this is emitted into the .d.ts either). The
+    // options have an effect only when the instance has a client (v2); without
+    // one they are ignored entirely.
+    AvoInspectorLite.prototype._trackSchemaWithOptions = function (eventName, eventSchema, options) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
                 try {
@@ -188,7 +268,7 @@ var AvoInspectorLite = /** @class */ (function () {
                             " with schema " +
                             JSON.stringify(eventSchema));
                     }
-                    this.trackSchemaInternal(eventName, eventSchema, null, null);
+                    this.trackSchemaInternal(eventName, eventSchema, null, null, options);
                 }
                 catch (e) {
                     console.error("Avo Inspector: something went wrong. Please report to support@avo.app.", e);
@@ -197,9 +277,9 @@ var AvoInspectorLite = /** @class */ (function () {
             });
         });
     };
-    AvoInspectorLite.prototype.trackSchemaInternal = function (eventName, eventSchema, eventId, eventHash) {
+    AvoInspectorLite.prototype.trackSchemaInternal = function (eventName, eventSchema, eventId, eventHash, options) {
         try {
-            this.avoBatcher.handleTrackSchema(eventName, eventSchema, eventId, eventHash);
+            this.avoBatcher.handleTrackSchema(eventName, eventSchema, eventId, eventHash, undefined, options);
         }
         catch (e) {
             console.error("Avo Inspector: something went wrong. Please report to support@avo.app.", e);
@@ -210,7 +290,7 @@ var AvoInspectorLite = /** @class */ (function () {
     };
     AvoInspectorLite.prototype.extractSchema = function (eventProperties_1) {
         return __awaiter(this, arguments, void 0, function (eventProperties, shouldLogIfEnabled) {
-            var e_3;
+            var e_5;
             if (shouldLogIfEnabled === void 0) { shouldLogIfEnabled = true; }
             return __generator(this, function (_a) {
                 switch (_a.label) {
@@ -223,8 +303,8 @@ var AvoInspectorLite = /** @class */ (function () {
                         return [4 /*yield*/, AvoSchemaParserLite_1.AvoSchemaParserLite.extractSchema(eventProperties)];
                     case 1: return [2 /*return*/, _a.sent()];
                     case 2:
-                        e_3 = _a.sent();
-                        console.error("Avo Inspector: something went wrong in extractSchema. Please report to support@avo.app.", e_3);
+                        e_5 = _a.sent();
+                        console.error("Avo Inspector: something went wrong in extractSchema. Please report to support@avo.app.", e_5);
                         return [2 /*return*/, []];
                     case 3: return [2 /*return*/];
                 }

package/dist/lite/AvoNetworkCallsHandlerLite.d.ts

@@ -37,8 +37,44 @@ export interface BaseBody {
 export interface SessionStartedBody extends BaseBody {
     type: "sessionStarted";
 }
-export interface EventSchemaBody extends BaseBody {
+/**
+ * INTERNAL — not part of the public API, and not exported from either entry
+ * point. Per-call gateway coordinates for the web GTM tag template, which passes
+ * them as a third argument to `window.inspector.trackSchemaFromEvent` in the
+ * script-tag build (see src/browser.js).
+ *
+ * They are sent as top-level siblings of `eventProperties` on the track body —
+ * never nested inside the schema, and never read from event data. Every value is
+ * trimmed; empty, whitespace-only and non-string values are treated as absent.
+ *
+ * They only apply on the v2 transport, i.e. when a client is configured.
+ * `POST /inspector/v2/track` decodes both hints and accepts a literal
+ * `appVersion: null` (stored as "unversioned"). Without a client the SDK is on
+ * `POST /inspector/v1/track` and the options are ignored entirely, `appVersion`
+ * included, so the body is exactly the one 3.2.0 built.
+ *
+ * Defined locally (not imported) in both AvoNetworkCallsHandler.ts and
+ * AvoNetworkCallsHandlerLite.ts to keep the lite-sync diff flat.
+ */
+export interface TrackOptions {
+    /** Reference of the gateway output this observation was bound for. Omit for a gateway-level observation. */
+    outputReference?: string;
+    /** Low-cardinality hint identifying the event's upstream source (e.g. "web", "ios"). Never a user identifier. */
+    originHint?: string;
+    /** App version of the source that produced the event. With originHint set, replaces the SDK's configured version (literal null when omitted); without originHint, overrides it only when provided. */
+    appVersion?: string;
+}
+/** Events of a failed send that are worth queueing again; undefined means all of them. */
+type RetryEvents = Array<SessionStartedBody | EventSchemaBody> | undefined;
+export interface EventSchemaBody extends Omit<BaseBody, "appVersion"> {
     type: "event";
+    /**
+     * Nullable only here, and only on v2: with an originHint set and no per-event
+     * appVersion the event is source-scoped, so a literal null is sent rather than
+     * the SDK's configured version. Session-started bodies, and every v1 body,
+     * always carry the string version.
+     */
+    appVersion: string | null;
     /** ID of the base event from spec (null if no spec available) */
     eventId: string | null;
     /** Name seen in code */
@@ -48,6 +84,10 @@ export interface EventSchemaBody extends BaseBody {
     eventHash: string | null;
     /** Branch ID from getEventSpec response when value validation was performed */
     validatedBranchId?: string;
+    /** Gateway output this observation was bound for; absent = gateway checkpoint. v2 only. */
+    outputReference?: string;
+    /** Low-cardinality hint identifying the event's upstream source. v2 only. */
+    originHint?: string;
 }
 export declare class AvoNetworkCallsHandlerLite {
     private readonly apiKey;
@@ -55,14 +95,42 @@ export declare class AvoNetworkCallsHandlerLite {
     private readonly appName;
     private readonly appVersion;
     private readonly libVersion;
+    /**
+     * "gtm-web" for the web GTM tag template, otherwise undefined. It is the
+     * transport switch, decided once in the constructor: undefined keeps the v1
+     * request byte for byte as 3.2.0 sent it; "gtm-web" selects v2 and is the
+     * X-Avo-Client value.
+     */
+    private readonly client;
+    private readonly trackingEndpoint;
     private samplingRate;
     private sending;
-    private static readonly trackingEndpoint;
-    constructor(apiKey: string, envName: string, appName: string, appVersion: string, libVersion: string);
-    callInspectorWithBatchBody(inEvents: Array<SessionStartedBody | EventSchemaBody>, onCompleted: (error: Error | null) => any): void;
+    /** v2 only: permanent failures in a row for this instance's own events. */
+    private permanentFailures;
+    /** v2 only: permanent failures in a row per other api key and env, keyed as the send groups are. */
+    private readonly foreignFailures;
+    /** v2 only: set at most once, when sending can no longer succeed on this page. */
+    private sendingDisabled;
+    /** v2 only: set when the events themselves can never be sent, so queueing them would only grow the stored queue. */
+    private queueingDisabled;
+    constructor(apiKey: string, envName: string, appName: string, appVersion: string, libVersion: string, client?: string);
+    /**
+     * v2 only: true once sending has stopped for this page (see
+     * maxConsecutivePermanentFailures). Always false on v1.
+     */
+    isSendingDisabled(): boolean;
+    /**
+     * v2 only: true when queueing events would only grow the stored queue, because
+     * they could never be sent under any configuration. Always false on v1.
+     */
+    isQueueingDisabled(): boolean;
+    private disableSending;
+    /** True while a batch sent through callInspectorWithBatchBody awaits its response. */
+    isBatchInFlight(): boolean;
+    callInspectorWithBatchBody(inEvents: Array<SessionStartedBody | EventSchemaBody>, onCompleted: (error: Error | null, retryEvents?: RetryEvents) => any): void;
     private fixStreamIds;
     bodyForSessionStartedCall(): SessionStartedBody;
-    bodyForEventSchemaCall(eventName: string, eventProperties: EventProperty[], eventId: string | null, eventHash: string | null, eventSpecMetadata?: EventSpecMetadata, validatedBranchId?: string): EventSchemaBody;
+    bodyForEventSchemaCall(eventName: string, eventProperties: EventProperty[], eventId: string | null, eventHash: string | null, eventSpecMetadata?: EventSpecMetadata, validatedBranchId?: string, options?: TrackOptions): EventSchemaBody;
     private createBaseCallBody;
     /**
      * Calls Inspector API immediately with a single event (bypasses batching).
@@ -83,6 +151,12 @@ export declare class AvoNetworkCallsHandlerLite {
      * synchronously in the unavailable case, so legacy timing is preserved.
      */
     private callInspectorApi;
+    private sendEvents;
+    /**
+     * Reports a failure as permanent (second argument true) when retrying the same
+     * request cannot succeed: the browser refused to build it, or the API answered
+     * a 4xx other than 408 and 429.
+     */
     private sendTrackingRequest;
 }
 export { AvoNetworkCallsHandlerLite as AvoNetworkCallsHandler };