avo-inspector 2.2.0 → 2.2.2-alpha.2

package/dist-browser/AvoInspector.d.ts

@@ -0,0 +1,78 @@
+import { type AvoInspectorEnvValueType } from "./AvoInspectorEnv";
+import { AvoBatcher } from "./AvoBatcher";
+import { AvoStorage } from "./AvoStorage";
+import { AvoDeduplicator } from "./AvoDeduplicator";
+export declare class AvoInspector {
+    environment: AvoInspectorEnvValueType;
+    avoBatcher: AvoBatcher;
+    avoDeduplicator: AvoDeduplicator;
+    apiKey: string;
+    version: string;
+    private avoNetworkCallsHandler;
+    private publicEncryptionKey?;
+    private streamId?;
+    private eventSpecCache?;
+    private eventSpecFetcher?;
+    static avoStorage: AvoStorage;
+    private static _batchSize;
+    static get batchSize(): number;
+    static set batchSize(newSize: number);
+    private static _batchFlushSeconds;
+    static get batchFlushSeconds(): number;
+    private static _shouldLog;
+    static get shouldLog(): boolean;
+    static set shouldLog(enable: boolean);
+    private static _networkTimeout;
+    static get networkTimeout(): number;
+    static set networkTimeout(timeout: number);
+    constructor(options: {
+        apiKey: string;
+        env: AvoInspectorEnvValueType;
+        version: string;
+        appName?: string;
+        suffix?: string;
+        publicEncryptionKey?: string;
+    });
+    trackSchemaFromEvent(eventName: string, eventProperties: Record<string, any>): Promise<Array<{
+        propertyName: string;
+        propertyType: string;
+        encryptedPropertyValue?: string;
+        children?: any;
+    }>>;
+    private _avoFunctionTrackSchemaFromEvent;
+    trackSchema(eventName: string, eventSchema: Array<{
+        propertyName: string;
+        propertyType: string;
+        encryptedPropertyValue?: string;
+        children?: any;
+    }>): Promise<void>;
+    private trackSchemaInternal;
+    enableLogging(enable: boolean): void;
+    extractSchema(eventProperties: Record<string, any>, shouldLogIfEnabled?: boolean): Array<{
+        propertyName: string;
+        propertyType: string;
+        encryptedPropertyValue?: string;
+        children?: any;
+    }>;
+    setBatchSize(newBatchSize: number): void;
+    setBatchFlushSeconds(newBatchFlushSeconds: number): void;
+    /**
+     * Fetches the event spec if spec fetching is enabled.
+     * Used by trackSchema when we don't have raw properties to validate.
+     *
+     * Note: EventSpec fetching only happens in dev/staging environments.
+     */
+    private fetchEventSpecIfNeeded;
+    /**
+     * Fetches event spec and validates the event against it.
+     * Returns ValidationResult if spec is available, null otherwise.
+     *
+     * Note: EventSpec fetching and validation only happens in dev/staging environments.
+     */
+    private fetchAndValidateEvent;
+    /**
+     * Sends an event immediately with validation data (bypasses batching).
+     * Logs validation errors if shouldLog is true.
+     */
+    private sendEventWithValidation;
+}

package/dist-browser/AvoInspectorEnv.d.ts

@@ -0,0 +1,7 @@
+export declare const AvoInspectorEnv: {
+    readonly Prod: "prod";
+    readonly Dev: "dev";
+    readonly Staging: "staging";
+};
+export type AvoInspectorEnvType = typeof AvoInspectorEnv;
+export type AvoInspectorEnvValueType = AvoInspectorEnvType[keyof AvoInspectorEnvType];

package/dist-browser/AvoNetworkCallsHandler.d.ts

@@ -0,0 +1,74 @@
+import type { EventSpecMetadata } from "./eventSpec/AvoEventSpecFetchTypes";
+import type { ValidationIssue } from "./eventSpec/EventValidator";
+export interface BaseBody {
+    apiKey: string;
+    appName: string;
+    appVersion: string;
+    libVersion: string;
+    env: string;
+    libPlatform: "web";
+    messageId: string;
+    trackingId: string;
+    createdAt: string;
+    sessionId: string;
+    anonymousId: string;
+    samplingRate: number;
+}
+export interface SessionStartedBody extends BaseBody {
+    type: "sessionStarted";
+}
+export interface EventSchemaBody extends BaseBody {
+    type: "event";
+    /** ID of the matched base event */
+    eventId: string | null;
+    /** ID of the matched variant (if any) */
+    variantId?: string | null;
+    /** Name seen in code */
+    eventName?: string;
+    /** Event spec metadata from EventSpecResponse */
+    eventSpecMetadata?: EventSpecMetadata;
+    /** Array of validation issues found during validation */
+    validationErrors?: ValidationIssue[];
+    eventProperties: Array<{
+        propertyName: string;
+        propertyType: string;
+        encryptedPropertyValue?: string;
+        children?: any;
+    }>;
+    avoFunction: boolean;
+    eventHash: string | null;
+}
+export declare class AvoNetworkCallsHandler {
+    private readonly apiKey;
+    private readonly envName;
+    private readonly appName;
+    private readonly appVersion;
+    private readonly libVersion;
+    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;
+    private fixAnonymousIds;
+    bodyForSessionStartedCall(): SessionStartedBody;
+    bodyForEventSchemaCall(eventName: string, eventProperties: Array<{
+        propertyName: string;
+        propertyType: string;
+        children?: any;
+    }>, eventId: string | null, eventHash: string | null, variantId?: string | null, eventSpecMetadata?: EventSpecMetadata, validationErrors?: ValidationIssue[]): EventSchemaBody;
+    private createBaseCallBody;
+    /**
+     * Calls Inspector API immediately with a single event (bypasses batching).
+     * Used when event spec validation is available.
+     * Note: Does not drop due to sampling - validated events are always sent.
+     */
+    callInspectorImmediately(eventBody: EventSchemaBody, onCompleted: (error: Error | null) => any): void;
+    /**
+     * Check if event should be dropped based on sampling rate.
+     */
+    private shouldDropBySampling;
+    /**
+     * Core Inspector API call logic shared by batch and immediate calls.
+     */
+    private callInspectorApi;
+}

package/dist-browser/AvoSchemaParser.d.ts

@@ -0,0 +1,20 @@
+export declare class AvoSchemaParser {
+    /**
+     * Returns true only if we have a valid encryption key and can send encrypted values.
+     * If no key is present, returns false and no property values will be sent.
+     */
+    private static canSendEncryptedValues;
+    /**
+     * Returns the encrypted property value if encryption is enabled, otherwise undefined.
+     * Never returns unencrypted values - only encrypted or nothing.
+     */
+    private static getEncryptedPropertyValueIfEnabled;
+    static extractSchema(eventProperties: Record<string, any>, publicEncryptionKey?: string, env?: string): Array<{
+        propertyName: string;
+        propertyType: string;
+        encryptedPropertyValue?: string;
+        children?: any;
+    }>;
+    private static removeDuplicates;
+    private static getPropValueType;
+}

package/dist-browser/AvoStorage.d.ts

@@ -0,0 +1,22 @@
+declare abstract class PlatformAvoStorage {
+    abstract init(shouldLog: boolean, suffix: string): void;
+    abstract getItemAsync<T>(key: string): Promise<T | null>;
+    abstract getItem<T>(key: string): T | null;
+    abstract setItem<T>(key: string, value: T): void;
+    abstract removeItem(key: string): void;
+    abstract runAfterInit(func: () => void): void;
+    abstract isInitialized(): boolean;
+    parseJson<T>(maybeItem: string | null | undefined): T | null;
+}
+export declare class AvoStorage {
+    Platform: string | null;
+    storageImpl: PlatformAvoStorage;
+    constructor(shouldLog: boolean, suffix?: string);
+    isInitialized(): boolean;
+    getItemAsync<T>(key: string): Promise<T | null>;
+    getItem<T>(key: string): T | null;
+    setItem<T>(key: string, value: T): void;
+    removeItem(key: string): void;
+    runAfterInit(func: () => void): void;
+}
+export {};

package/dist-browser/__mocks__/xhr.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="jest" />
+declare const xhrMock: {
+    open: jest.Mock<any, any, any>;
+    send: jest.Mock<any, any, any>;
+    setRequestHeader: jest.Mock<any, any, any>;
+    onload: jest.Mock<any, any, any>;
+    onerror: jest.Mock<any, any, any>;
+    ontimeout: jest.Mock<any, any, any>;
+    status: number;
+    response: string;
+};
+export default xhrMock;

package/dist-browser/__mocks__/xhrError.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="jest" />
+declare const xhrErrorMock: {
+    open: jest.Mock<any, any, any>;
+    send: jest.Mock<any, any, any>;
+    setRequestHeader: jest.Mock<any, any, any>;
+    onload: jest.Mock<any, any, any>;
+    onerror: jest.Mock<any, any, any>;
+    ontimeout: jest.Mock<any, any, any>;
+    status: number;
+    statusText: string;
+};
+export default xhrErrorMock;

package/dist-browser/__tests__/AnonymousId_test.d.ts

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

package/dist-browser/__tests__/AvoEncryption_test.d.ts

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

package/dist-browser/__tests__/AvoInspectorEventSpec_test.d.ts

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

package/dist-browser/__tests__/AvoInspector_test.d.ts

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

package/dist-browser/__tests__/BatcherPublic_test.d.ts

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

package/dist-browser/__tests__/Batcher_test.d.ts

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

package/dist-browser/__tests__/Deduplicator_test.d.ts

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

package/dist-browser/__tests__/EncryptedPropertyTracking_test.d.ts

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

package/dist-browser/__tests__/EventSpecCache_test.d.ts

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

package/dist-browser/__tests__/EventSpecFetcher_test.d.ts

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

package/dist-browser/__tests__/EventValidator_test.d.ts

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

package/dist-browser/__tests__/NetworkCallsHandler_test.d.ts

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

package/dist-browser/__tests__/Parsing_test.d.ts

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

package/dist-browser/__tests__/Storage_test.d.ts

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

package/dist-browser/__tests__/ValidationIntegration_test.d.ts

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

package/dist-browser/__tests__/constants.d.ts

@@ -0,0 +1,36 @@
+declare const defaultOptions: {
+    apiKey: string;
+    env: "prod";
+    version: string;
+    shouldLog: boolean;
+};
+declare const error: {
+    API_KEY: string;
+    VERSION: string;
+};
+declare const mockedReturns: {
+    INSTALLATION_ID: string;
+    GUID: string;
+    SESSION_ID: string;
+};
+declare const networkCallType: {
+    EVENT: string;
+    SESSION_STARTED: string;
+};
+declare const requestMsg: {
+    ERROR: string;
+    TIMEOUT: string;
+};
+declare const trackingEndpoint = "https://api.avo.app/inspector/v1/track";
+declare const sessionTimeMs: number;
+declare const type: {
+    STRING: string;
+    INT: string;
+    OBJECT: string;
+    FLOAT: string;
+    LIST: string;
+    BOOL: string;
+    NULL: string;
+    UNKNOWN: string;
+};
+export { defaultOptions, error, mockedReturns, networkCallType, requestMsg, sessionTimeMs, type, trackingEndpoint };

package/dist-browser/__tests__/helpers/encryptionHelpers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Test helper: Generates a new ECC key pair for testing encryption.
+ * This is also available in the CLI tool (bin/avo-inspector.js) for production use.
+ */
+export declare function generateKeyPair(): {
+    publicKey: string;
+    privateKey: string;
+};
+/**
+ * Test helper: Decrypts a value that was encrypted using encryptValue.
+ * Used for testing purposes only.
+ */
+export declare function decryptValue(encryptedValue: string, privateKey: string): any;

package/dist-browser/__tests__/helpers/mockFactories.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared mock factories for testing event spec related functionality.
+ * These helpers reduce duplication across test files.
+ */
+import type { PropertySpec, PropertyTypeSpec, VariantSpec, EventSpec, EventSpecResponse, EventSpecMetadata } from "../../eventSpec/AvoEventSpecFetchTypes";
+/**
+ * Creates a PropertyTypeSpec with defaults.
+ */
+export declare function createPropertyTypeSpec(overrides?: Partial<PropertyTypeSpec>): PropertyTypeSpec;
+/**
+ * Creates a PropertySpec with sensible defaults.
+ */
+export declare function createPropertySpec(overrides?: Partial<PropertySpec>): PropertySpec;
+/**
+ * Creates a required string property.
+ */
+export declare function createRequiredStringProperty(id: string, extraOverrides?: Partial<PropertySpec>): PropertySpec;
+/**
+ * Creates an optional number property.
+ */
+export declare function createNumberProperty(id: string, extraOverrides?: Partial<PropertySpec>): PropertySpec;
+/**
+ * Creates an enum property with allowed values.
+ */
+export declare function createEnumProperty(id: string, allowedValues: string[], extraOverrides?: Partial<PropertySpec>): PropertySpec;
+/**
+ * Creates a VariantSpec with defaults.
+ */
+export declare function createVariantSpec(overrides?: Partial<VariantSpec>): VariantSpec;
+/**
+ * Creates an EventSpec with defaults.
+ */
+export declare function createEventSpec(overrides?: Partial<EventSpec>): EventSpec;
+/**
+ * Creates an EventSpec with common properties for testing.
+ */
+export declare function createUserLoginEventSpec(): EventSpec;
+/**
+ * Creates EventSpecMetadata with defaults.
+ */
+export declare function createEventSpecMetadata(overrides?: Partial<EventSpecMetadata>): EventSpecMetadata;
+/**
+ * Creates an EventSpecResponse with defaults.
+ */
+export declare function createEventSpecResponse(events?: EventSpec[], metadataOverrides?: Partial<EventSpecMetadata>): EventSpecResponse;
+/**
+ * Creates a simple EventSpecResponse with one event for basic testing.
+ */
+export declare function createSimpleEventSpecResponse(eventName?: string): EventSpecResponse;

package/dist-browser/eventSpec/AvoEventSpecCache.d.ts

@@ -0,0 +1,73 @@
+import type { EventSpecResponse } from "./AvoEventSpecFetchTypes";
+/**
+ * EventSpecCache implements a dual-condition cache with LRU eviction.
+ *
+ * Cache Policy:
+ * - Entries expire after 5 minutes OR 50 cache hits, whichever comes first
+ * - When 50 cache hits occur globally, the oldest cached entry is evicted
+ * - Each cache entry tracks: spec, timestamp, and hit count
+ *
+ * Cache Key Format: ${apiKey}:${streamId}:${eventName}
+ *
+ * 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.
+ */
+export declare class EventSpecCache {
+    /** Cache storage: key -> CacheEntry */
+    private cache;
+    /** Time-to-live in milliseconds (5 minutes) */
+    private readonly TTL_MS;
+    /** Maximum cache hit count before rotating cache (50 hits) */
+    private readonly MAX_EVENT_COUNT;
+    /** Global cache hit counter to track when to rotate cache */
+    private globalEventCount;
+    /** Whether to log debug information */
+    private readonly shouldLog;
+    constructor(shouldLog?: boolean);
+    /**
+     * Generates a cache key from the provided parameters.
+     */
+    private generateKey;
+    /**
+     * Retrieves an event spec response from the cache if it exists and is valid.
+     * Returns null if the entry is missing, expired, or has exceeded event count.
+     *
+     * On cache hit, increments the hit count for this entry and the global counter.
+     */
+    get(apiKey: string, streamId: string, eventName: string): EventSpecResponse | null;
+    /**
+     * Stores an event spec response in the cache.
+     */
+    set(apiKey: string, streamId: string, eventName: string, spec: EventSpecResponse): void;
+    /**
+     * Determines if a cache entry should be evicted based on:
+     * - Age (older than 5 minutes)
+     * - Hit count (50 or more cache hits)
+     */
+    private shouldEvict;
+    /**
+     * Evicts the oldest cache entry based on timestamp.
+     * This implements the LRU (Least Recently Used) eviction policy.
+     */
+    private evictOldest;
+    /**
+     * Clears all cached entries. Useful for testing.
+     */
+    clear(): void;
+    /**
+     * Returns the current size of the cache.
+     */
+    size(): number;
+    /**
+     * Returns cache statistics for debugging.
+     */
+    getStats(): {
+        size: number;
+        globalEventCount: number;
+        entries: Array<{
+            key: string;
+            age: number;
+            eventCount: number;
+        }>;
+    };
+}

package/dist-browser/eventSpec/AvoEventSpecFetchTypes.d.ts

@@ -0,0 +1,109 @@
+/**
+ * This file is generated. Internal development changes should be made in the generator
+ * and the file should be re-generated. External contributions are welcome to submit
+ * changes directly to this file, and we'll apply them to the generator internally.
+ */
+/**
+ * Represents the type specification for a property.
+ * Can be a primitive type or a nested object structure.
+ */
+export interface PropertyTypeSpec {
+    /** The type category: "primitive" for simple types, "object" for nested structures */
+    type: "primitive" | "object";
+    /** For primitive: the type name (e.g., "string", "int"). For object: nested property specs */
+    value: string | Record<string, PropertySpec>;
+}
+/**
+ * Represents the specification for a single property in an event.
+ * Supports recursive nesting for object types.
+ */
+export interface PropertySpec {
+    /** Unique identifier for this property */
+    id: string;
+    /** Type specification - contains type category and value */
+    t: PropertyTypeSpec;
+    /** Required flag */
+    r: boolean;
+    /** Is list (array) flag */
+    l?: boolean;
+    /** Minimum value (for numeric types) */
+    min?: number;
+    /** Maximum value (for numeric types) */
+    max?: number;
+    /** Enum values (allowed values for the property) */
+    v?: string[];
+    /** Regex pattern for string validation */
+    rx?: string;
+}
+/**
+ * Represents a variant of an event with additional or modified properties.
+ */
+export interface VariantSpec {
+    /** Unique identifier for this variant */
+    variantId: string;
+    /** Event ID for this variant (base event id) */
+    eventId: string;
+    /** Suffix to append to the base event name */
+    nameSuffix: string;
+    /** Name of the variant in this source (if different from canonical name) */
+    mappedName?: string;
+    /** Properties specific to this variant */
+    props: Record<string, PropertySpec>;
+}
+/**
+ * Represents the complete specification for an event, including base event
+ * and optional variants.
+ */
+export interface EventSpec {
+    /** Unique identifier for this event */
+    id: string;
+    /** Canonical Avo name for this event */
+    name: string;
+    /** Name of the event in this source (if different from canonical name) */
+    mappedName?: string;
+    /** Properties for this event */
+    props: Record<string, PropertySpec>;
+    /** Variants of this event with additional/modified properties */
+    variants: VariantSpec[];
+}
+/**
+ * Metadata returned with the event spec response.
+ */
+export interface EventSpecMetadata {
+    /** Schema identifier */
+    schemaId: string;
+    /** Branch identifier */
+    branchId: string;
+    /** Latest action identifier (replaces versionId/createdAt) */
+    latestActionId: string;
+    /** Optional source identifier */
+    sourceId?: string;
+}
+/**
+ * Response structure from the getEventSpec endpoint.
+ * Contains an array of potential event matches (due to name mapping).
+ */
+export interface EventSpecResponse {
+    /** Array of potential event matches */
+    events: EventSpec[];
+    /** Metadata about the schema and source */
+    metadata: EventSpecMetadata;
+}
+/** Cache entry for storing event specs with metadata. */
+export interface EventSpecCacheEntry {
+    /** The cached event specification response */
+    spec: EventSpecResponse;
+    /** Timestamp when this entry was cached */
+    timestamp: number;
+    /** Number of events processed since this entry was cached */
+    eventCount: number;
+}
+/** Parameters for fetching event specifications from the API. */
+export interface FetchEventSpecParams {
+    /** The API key */
+    apiKey: string;
+    /** The stream ID */
+    streamId: string;
+    /** The name of the event */
+    eventName: string;
+}

package/dist-browser/eventSpec/AvoEventSpecFetcher.d.ts

@@ -0,0 +1,55 @@
+/**
+ * This file is generated. Internal development changes should be made in the generator
+ * and the file should be re-generated. External contributions are welcome to submit
+ * changes directly to this file, and we'll apply them to the generator internally.
+ */
+import type { EventSpecResponse, FetchEventSpecParams } from "./AvoEventSpecFetchTypes";
+/**
+ * EventSpecFetcher handles fetching event specifications from the Avo API.
+ *
+ * Endpoint: GET /streamInspectorEventShapes
+ * Base URL: http://localhost:5001/avo-web-app/us-central1 (local dev)
+ *           https://us-central1-avo-web-app.cloudfunctions.net (production)
+ */
+export declare class AvoEventSpecFetcher {
+    /** Base URL for the event spec API */
+    private readonly baseUrl;
+    /** Network timeout in milliseconds */
+    private readonly timeout;
+    /** In-flight requests to prevent duplicate fetches */
+    private inFlightRequests;
+    /** Whether to log debug information */
+    private readonly shouldLog;
+    /** 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. */
+    private generateRequestKey;
+    /**
+     * Fetches an event specification from the API.
+     *
+     * Returns null if:
+     * - The network request fails
+     * - The response has an invalid status code (non-200)
+     * - The response is invalid or malformed
+     * - The request times out
+     *
+     * This method gracefully degrades - failures do not throw errors.
+     * When null is returned, validation should be skipped for that event.
+     */
+    fetch(params: FetchEventSpecParams): Promise<EventSpecResponse | null>;
+    /** Internal fetch implementation. */
+    private fetchInternal;
+    /** Builds the complete URL with query parameters. */
+    private buildUrl;
+    /**
+     * Makes an HTTP GET request using XMLHttpRequest.
+     * Returns the parsed JSON response or null on failure.
+     */
+    private makeRequest;
+    /**
+     * Basic shape check - ensures response has the minimum expected structure.
+     * Does not perform deep validation of all fields.
+     */
+    private hasExpectedShape;
+}