avo-inspector 3.2.0 → 3.2.3

package/README.md

@@ -269,10 +269,20 @@ inspector.setBatchFlushSeconds(10);
 
 You can control the network timeout for the SDK. Default is 2 seconds.
 
+In dev and staging, every send waits at least 10 seconds, or `networkTimeout` if it is longer (0, no timeout, is kept). That includes an event that has an event spec, which is validated and sent on its own, right away. Production sends use `networkTimeout`.
+
 ```javascript
 Inspector.AvoInspector.networkTimeout = 5000;
 ```
 
+# Maintainers: web GTM template support is internal
+
+The Avo web GTM tag template reaches features that are not part of this SDK's public API: the
+`/inspector/v2/track` transport and per-event gateway fields. They are reachable only through the
+script-tag build, when `window.inspector.__CLIENT__` is `"gtm-web"`. Everything else — npm full,
+npm lite and a regular script tag — sends to `/inspector/v1/track` exactly as 3.2.0 did. See
+`src/browser.js` and `src/AvoNetworkCallsHandler.cs.md`. Don't document these for SDK users.
+
 ## Author
 
 Avo (https://www.avo.app), friends@avo.app

package/dist/AvoBatcher.d.ts

@@ -1,8 +1,8 @@
-import { type AvoNetworkCallsHandler, type EventProperty } from "./AvoNetworkCallsHandler";
+import { type EventSchemaBody, type AvoNetworkCallsHandler, type EventProperty, type TrackOptions } from "./AvoNetworkCallsHandler";
 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/AvoInspector.d.ts

@@ -15,6 +15,7 @@ export declare class AvoInspector {
     private eventSpecCache?;
     private eventSpecFetcher?;
     private currentBranchId;
+    private readonly hasGatewayClient;
     static avoStorage: AvoStorage;
     private static _batchSize;
     static get batchSize(): number;
@@ -36,6 +37,7 @@ export declare class AvoInspector {
         publicEncryptionKey?: string;
     });
     trackSchemaFromEvent(eventName: string, eventProperties: Record<string, any>): Promise<EventProperty[]>;
+    private _trackSchemaFromEventWithOptions;
     private _avoFunctionTrackSchemaFromEvent;
     trackSchema(eventName: string, eventSchema: Array<{
         propertyName: string;
@@ -43,6 +45,7 @@ export declare class AvoInspector {
         encryptedPropertyValue?: string;
         children?: any;
     }>): Promise<void>;
+    private _trackSchemaWithOptions;
     private trackSchemaInternal;
     enableLogging(enable: boolean): void;
     extractSchema(eventProperties: Record<string, any>, shouldLogIfEnabled?: boolean): Promise<Array<{
@@ -53,6 +56,7 @@ export declare class AvoInspector {
     }>>;
     setBatchSize(newBatchSize: number): void;
     setBatchFlushSeconds(newBatchFlushSeconds: number): void;
+    private specCoordinates;
     /**
      * Handles branch change detection and cache storage for a fetched event spec.
      * This logic is shared between fetchEventSpecIfNeeded and fetchAndValidateEvent.

package/dist/AvoNetworkCallsHandler.d.ts

@@ -39,8 +39,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 */
@@ -50,6 +86,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 AvoNetworkCallsHandler {
     private readonly apiKey;
@@ -58,14 +98,42 @@ export declare class AvoNetworkCallsHandler {
     private readonly appVersion;
     private readonly libVersion;
     private readonly publicEncryptionKey?;
+    /**
+     * "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, publicEncryptionKey?: 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, publicEncryptionKey?: 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).
@@ -86,5 +154,12 @@ export declare class AvoNetworkCallsHandler {
      * 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 {};

package/dist/__tests__/UnboundPublicMethods_test.d.ts

@@ -0,0 +1 @@
+import "../__mocks__/xhr";

package/dist/__tests__/constants.d.ts

@@ -22,6 +22,7 @@ declare const requestMsg: {
     TIMEOUT: string;
 };
 declare const trackingEndpoint = "https://api.avo.app/inspector/v1/track";
+declare const trackingEndpointV2 = "https://api.avo.app/inspector/v2/track";
 declare const sessionTimeMs: number;
 declare const type: {
     STRING: string;
@@ -33,4 +34,4 @@ declare const type: {
     NULL: string;
     UNKNOWN: string;
 };
-export { defaultOptions, error, mockedReturns, networkCallType, requestMsg, sessionTimeMs, type, trackingEndpoint };
+export { defaultOptions, error, mockedReturns, networkCallType, requestMsg, sessionTimeMs, type, trackingEndpoint, trackingEndpointV2 };

package/dist/__tests__/helpers/internalGateway.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The internal web GTM tag template path, for tests.
+ *
+ * None of this is public API. In production only the script-tag bootstrap
+ * (src/browser.js) uses it: it passes `window.inspector.__CLIENT__` as the
+ * untyped `_client` constructor option, and routes a third `trackSchemaFromEvent`
+ * / `trackSchema` argument to the private `_…WithOptions` methods. These helpers
+ * do the same from TypeScript, so tests reach it without widening public types.
+ */
+export interface GatewayOptions {
+    outputReference?: unknown;
+    originHint?: unknown;
+    appVersion?: unknown;
+}
+/** Constructor options with the internal client set, as browser.js builds them. */
+export declare const withClient: <T extends object>(options: T, client: string | undefined) => T;
+/** Calls the internal `_trackSchemaFromEventWithOptions` on either build. */
+export declare const trackSchemaFromEventWithOptions: (inspector: object, eventName: string, eventProperties: Record<string, any>, options: GatewayOptions | undefined) => Promise<any[]>;
+/** Calls the internal `_trackSchemaWithOptions` on either build. */
+export declare const trackSchemaWithOptions: (inspector: object, eventName: string, eventSchema: Array<{
+    propertyName: string;
+    propertyType: string;
+}>, options: GatewayOptions | undefined) => Promise<void>;

package/dist/eventSpec/AvoEventSpecCache.d.ts

@@ -1,4 +1,4 @@
-import type { EventSpecResponse } from "./AvoEventSpecFetchTypes";
+import type { EventSpecResponse, EventSpecCoordinates } from "./AvoEventSpecFetchTypes";
 /**
  * EventSpecCache implements a dual-condition cache with LRU eviction.
  *
@@ -8,6 +8,9 @@ import type { EventSpecResponse } from "./AvoEventSpecFetchTypes";
  * - Each cache entry tracks: spec, timestamp, and hit count
  *
  * Cache Key Format: ${apiKey}:${streamId}:${eventName}
+ * With gateway coordinates (originHint / outputReference, web GTM tag template
+ * only) the key is JSON.stringify([apiKey, streamId, eventName, originHint, outputReference])
+ * instead, so specs for different checkpoints of the same event never share an entry.
  *
  * Note: Event count only increments on cache hits, not on every tracked event.
  * This ensures the cache evicts based on actual usage, not overall tracking volume.
@@ -33,7 +36,7 @@ export declare class EventSpecCache {
      * Returns true even for cached null specs (empty backend responses).
      * Use this to distinguish between "cache miss" and "cached empty response".
      */
-    contains(apiKey: string, streamId: string, eventName: string): boolean;
+    contains(apiKey: string, streamId: string, eventName: string, coordinates?: EventSpecCoordinates): boolean;
     /**
      * Retrieves an event spec response from the cache if it exists and is valid.
      * Returns null if the entry is missing, expired, has exceeded event count,
@@ -41,12 +44,12 @@ export declare class EventSpecCache {
      *
      * On cache hit, increments the hit count for this entry and the global counter.
      */
-    get(apiKey: string, streamId: string, eventName: string): EventSpecResponse | null;
+    get(apiKey: string, streamId: string, eventName: string, coordinates?: EventSpecCoordinates): EventSpecResponse | null;
     /**
      * Stores an event spec response in the cache.
      * Pass null to cache an empty response (event not found on backend).
      */
-    set(apiKey: string, streamId: string, eventName: string, spec: EventSpecResponse | null): void;
+    set(apiKey: string, streamId: string, eventName: string, spec: EventSpecResponse | null, coordinates?: EventSpecCoordinates): void;
     /**
      * Determines if a cache entry should be evicted based on:
      * - Age (older than 5 minutes)

package/dist/eventSpec/AvoEventSpecFetchTypes.d.ts

@@ -118,8 +118,19 @@ export interface EventSpecCacheEntry {
     /** Number of cache hits since this entry was cached */
     eventCount: number;
 }
+/**
+ * Gateway coordinates of the event a spec is fetched for (internal, web GTM tag
+ * template only). Both are already normalized by the caller: trimmed, and absent
+ * when blank. With neither set, the spec fetch is exactly the source-key fetch.
+ */
+export interface EventSpecCoordinates {
+    /** The source that produced the event, as the gateway names it */
+    originHint?: string;
+    /** The gateway output whose checkpoint observes the event */
+    outputReference?: string;
+}
 /** Parameters for fetching event specifications from the API. */
-export interface FetchEventSpecParams {
+export interface FetchEventSpecParams extends EventSpecCoordinates {
     /** The API key */
     apiKey: string;
     /** The stream ID */

package/dist/eventSpec/AvoEventSpecFetcher.d.ts

@@ -22,7 +22,12 @@ export declare class AvoEventSpecFetcher {
     /** Environment name */
     private readonly env;
     constructor(timeout: number | undefined, shouldLog: boolean | undefined, env: string, baseUrl?: string);
-    /** Generates a unique key for tracking in-flight requests. */
+    /**
+     * Generates a unique key for tracking in-flight requests, matching the spec
+     * cache key. The API key tells gateways apart, and gateway coordinates are
+     * part of the key, so fetches for different gateways or checkpoints of the
+     * same event name are never deduplicated into one.
+     */
     private generateRequestKey;
     /**
      * Fetches an event specification from the API.