avo-inspector 3.2.0 → 3.2.3-alpha.1

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__/ApiKeyHeaderInjection_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/BrowserBootstrap_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/EnableLoggingLite_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/EnableLogging_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/EventSpecGatewayCoordinates_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/InFlightQueueGaps_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/InFlightQueue_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/NetworkCallsHandlerLite_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/PublicSurface_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/TrackOptionsIntegration_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/TrackOptionsTransport_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/TrackingHeaders_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/UnboundPublicMethods_test.d.ts

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

package/dist/__tests__/V1WireBaseline_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/V2QueuedAttribution_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/V2StopSending_test.d.ts

@@ -0,0 +1 @@
+export {};

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>;