avo-inspector 2.2.0 → 2.2.2-alpha.10

package/dist/eventSpec/AvoEventSpecCache.d.ts

@@ -0,0 +1,74 @@
+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 least recently used cache entry based on lastAccessed 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;
+            lastAccessedAgo: number;
+            eventCount: number;
+        }>;
+    };
+}

package/dist/eventSpec/AvoEventSpecFetchTypes.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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.
+ */
+/**
+ * Wire format - Property constraints with short field names.
+ * At most one constraint type will be present per property.
+ */
+export interface PropertyConstraintsWire {
+    /** Type name (for reference only, not validated) */
+    t: string;
+    /** Required flag (for reference only, not validated) */
+    r: boolean;
+    /** List flag - true if this is an array/list of the type */
+    l?: boolean;
+    /** Pinned values: pinnedValue -> eventIds that require this exact value */
+    p?: Record<string, Array<string>>;
+    /** Allowed values: JSON array string -> eventIds that accept these values */
+    v?: Record<string, Array<string>>;
+    /** Regex patterns: pattern -> eventIds that require matching this regex */
+    rx?: Record<string, Array<string>>;
+    /** Min/max ranges: "min,max" -> eventIds that require value in this range */
+    minmax?: Record<string, Array<string>>;
+    /** Nested property constraints for object properties */
+    children?: Record<string, PropertyConstraintsWire>;
+}
+/**
+ * Wire format - Event spec entry with short field names.
+ * A single event entry (base event + its variants).
+ * Multiple events can match the same name request due to name mapping.
+ */
+export interface EventSpecEntryWire {
+    /** Branch identifier */
+    b: string;
+    /** Base event ID */
+    id: string;
+    /** Variant IDs (baseEventId + variantIds = complete set) */
+    vids: Array<string>;
+    /** Property constraints keyed by property name */
+    p: Record<string, PropertyConstraintsWire>;
+}
+/**
+ * Wire format - Response from getEventSpec endpoint.
+ * Contains array of events that match the requested name (due to name mapping).
+ */
+export interface EventSpecResponseWire {
+    /** Array of events matching the requested name */
+    events: Array<EventSpecEntryWire>;
+    /** Schema metadata (keeps long names - small, one per response) */
+    metadata: EventSpecMetadata;
+}
+/**
+ * Internal - Property constraints with meaningful field names.
+ * At most one constraint type will be present per property.
+ */
+export interface PropertyConstraints {
+    /** Type name (for reference only, not validated) */
+    type: string;
+    /** Required flag (for reference only, not validated) */
+    required: boolean;
+    /** List flag - true if this is an array/list of items */
+    isList?: boolean;
+    /** Pinned values: pinnedValue -> eventIds that require this exact value */
+    pinnedValues?: Record<string, Array<string>>;
+    /** Allowed values: JSON array string -> eventIds that accept these values */
+    allowedValues?: Record<string, Array<string>>;
+    /** Regex patterns: pattern -> eventIds that require matching this regex */
+    regexPatterns?: Record<string, Array<string>>;
+    /** Min/max ranges: "min,max" -> eventIds that require value in this range */
+    minMaxRanges?: Record<string, Array<string>>;
+    /** Nested property constraints for object properties (for objects or list of objects) */
+    children?: Record<string, PropertyConstraints>;
+}
+/**
+ * Internal - Event spec entry with meaningful field names.
+ * A single event entry (base event + its variants).
+ */
+export interface EventSpecEntry {
+    /** Branch identifier */
+    branchId: string;
+    /** Base event ID */
+    baseEventId: string;
+    /** Variant IDs (baseEventId + variantIds = complete set) */
+    variantIds: Array<string>;
+    /** Property constraints keyed by property name */
+    props: Record<string, PropertyConstraints>;
+}
+/**
+ * Internal - Parsed response from getEventSpec endpoint.
+ * Contains array of events that match the requested name (due to name mapping).
+ */
+export interface EventSpecResponse {
+    /** Array of events matching the requested name */
+    events: Array<EventSpecEntry>;
+    /** Schema metadata */
+    metadata: EventSpecMetadata;
+}
+/** Metadata returned with the event spec response. */
+export interface EventSpecMetadata {
+    /** Schema identifier */
+    schemaId: string;
+    /** Branch identifier */
+    branchId: string;
+    /** Latest action identifier */
+    latestActionId: string;
+    /** Optional source identifier */
+    sourceId?: string;
+}
+/** Cache entry for storing event specs with metadata. */
+export interface EventSpecCacheEntry {
+    /** The cached event specification response (internal format) */
+    spec: EventSpecResponse;
+    /** Timestamp when this entry was cached (used for TTL expiration) */
+    timestamp: number;
+    /** Timestamp when this entry was last accessed (used for LRU eviction) */
+    lastAccessed: number;
+    /** Number of cache hits 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;
+}
+/**
+ * Result of validating a single property.
+ * Contains either failedEventIds or passedEventIds (whichever is smaller for bandwidth).
+ */
+export interface PropertyValidationResult {
+    /** Event/variant IDs that FAILED validation (present if smaller or equal to passed) */
+    failedEventIds?: Array<string>;
+    /** Event/variant IDs that PASSED validation (present if smaller than failed) */
+    passedEventIds?: Array<string>;
+    /** Nested validation results for child properties of object properties */
+    children?: Record<string, PropertyValidationResult>;
+}
+/**
+ * Result of validating all properties in an event.
+ * Maps property name to its validation result.
+ */
+export interface ValidationResult {
+    /** Event spec metadata */
+    metadata: EventSpecMetadata | null;
+    /** Validation results per property */
+    propertyResults: Record<string, PropertyValidationResult>;
+}

package/dist/eventSpec/AvoEventSpecFetcher.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 /trackingPlan/eventSpec
+ * Base URL: https://api.avo.app
+ */
+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, Phase 2 should skip validation 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 for wire format - ensures response has the minimum expected structure.
+     * Uses short field names from wire format.
+     */
+    private hasExpectedShape;
+    /** Parses the wire format response into internal format with meaningful field names. */
+    private static parseEventSpecResponse;
+    /** Parses a single event spec entry from wire format. */
+    private static parseEventSpecEntry;
+    /** Parses property constraints from wire format. */
+    private static parsePropertyConstraints;
+}

package/dist/eventSpec/EventValidator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * EventValidator - Client-side validation of tracking events against the Avo Tracking Plan.
+ *
+ * This module validates property values against constraints:
+ * - Pinned values (exact match required)
+ * - Allowed values (must be in list)
+ * - Regex patterns (must match pattern)
+ * - Min/max ranges (numeric values must be in range)
+ *
+ * No schema validation (types/required) is performed - only value constraints.
+ * Validation runs against ALL events/variants in the response.
+ */
+import type { EventSpecResponse, ValidationResult } from "./AvoEventSpecFetchTypes";
+/**
+ * Runtime property value - can be any JSON-compatible type
+ */
+export type RuntimePropertyValue = string | number | boolean | null | undefined | object | Array<any>;
+/**
+ * Runtime properties map
+ */
+export type RuntimeProperties = Record<string, RuntimePropertyValue>;
+/**
+ * Validates runtime properties against all events in the EventSpecResponse.
+ *
+ * For each property:
+ * - If property not in spec: no validation needed (empty result)
+ * - If property in spec: check constraints and collect failed/passed eventIds
+ * - Return whichever list is smaller for bandwidth optimization
+ *
+ * @param properties - The properties observed at runtime
+ * @param specResponse - The EventSpecResponse from the backend
+ * @returns ValidationResult with baseEventId, metadata, and per-property results
+ */
+export declare function validateEvent(properties: RuntimeProperties, specResponse: EventSpecResponse): ValidationResult;

package/dist/eventSpec/cache.d.ts

@@ -0,0 +1,73 @@
+import type { EventSpec } from "./types";
+/**
+ * EventSpecCache implements a dual-condition cache with LRU eviction.
+ *
+ * Cache Policy:
+ * - Entries expire after 5 minutes OR 50 events, whichever comes first
+ * - When 50 events are processed, the oldest cached entry is evicted
+ * - Each cache entry tracks: spec, timestamp, and eventCount
+ *
+ * Cache Key Format: ${schemaId}:${sourceId}:${eventName}:${branchId}
+ */
+export declare class EventSpecCache {
+    /** Cache storage: key -> CacheEntry */
+    private cache;
+    /** Time-to-live in milliseconds (5 minutes) */
+    private readonly TTL_MS;
+    /** Maximum event count before rotating cache (50 events) */
+    private readonly MAX_EVENT_COUNT;
+    /** Global event 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 from the cache if it exists and is valid.
+     * Returns null if the entry is missing, expired, or has exceeded event count.
+     */
+    get(schemaId: string, sourceId: string, eventName: string, branchId: string): EventSpec | null;
+    /**
+     * Stores an event spec in the cache.
+     */
+    set(schemaId: string, sourceId: string, eventName: string, branchId: string, spec: EventSpec): void;
+    /**
+     * Increments the event count for all cached entries and triggers
+     * eviction if the global event count reaches MAX_EVENT_COUNT.
+     */
+    incrementEventCount(): void;
+    /**
+     * Determines if a cache entry should be evicted based on:
+     * - Age (older than 5 minutes)
+     * - Event count (50 or more events processed)
+     */
+    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/eventSpec/fetcher.d.ts

@@ -0,0 +1,52 @@
+import type { EventSpec, FetchEventSpecParams } from "./types";
+/**
+ * EventSpecFetcher handles fetching event specifications from the Avo API.
+ *
+ * Endpoint: GET /getEventSpec
+ * Base URL: https://api.avo.app/inspector/v1
+ */
+export declare class EventSpecFetcher {
+    /** Base URL for the event spec API */
+    private readonly baseUrl;
+    /** Network timeout in milliseconds */
+    private readonly timeout;
+    /** Whether to log debug information */
+    private readonly shouldLog;
+    /** In-flight requests to prevent duplicate fetches */
+    private inFlightRequests;
+    constructor(timeout?: number, shouldLog?: boolean, 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, Phase 2 should skip validation for that event.
+     */
+    fetch(params: FetchEventSpecParams): Promise<EventSpec | 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;
+    /**
+     * Validates that the response matches the EventSpec structure.
+     */
+    private isValidEventSpec;
+}

package/dist/eventSpec/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./AvoEventSpecFetchTypes";
+export * from "./AvoEventSpecCache";
+export * from "./AvoEventSpecFetcher";
+export * from "./EventValidator";

package/dist/eventSpec/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Represents the specification for a single property in an event.
+ * Supports recursive nesting for object types.
+ */
+export interface PropertySpec {
+    /** Type - can be a primitive type string OR a nested object structure (recursive) */
+    t: string | Record<string, PropertySpec>;
+    /** 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 EventVariant {
+    /** Unique identifier for this variant */
+    variantId: string;
+    /** Suffix to append to the base event name */
+    nameSuffix: string;
+    /** Event ID for this variant */
+    eventId: 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 {
+    /** Base event specification */
+    baseEvent: {
+        /** Name of the event */
+        name: string;
+        /** Unique identifier for the event */
+        id: string;
+        /** Properties defined for the base event */
+        props: Record<string, PropertySpec>;
+    };
+    /** Optional variants of this event with additional/modified properties */
+    variants?: EventVariant[];
+}
+/**
+ * Cache entry for storing event specs with metadata.
+ */
+export interface EventSpecCacheEntry {
+    /** The cached event specification */
+    spec: EventSpec;
+    /** 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 workspace/schema ID */
+    schemaId: string;
+    /** The source ID */
+    sourceId: string;
+    /** The name of the event */
+    eventName: string;
+    /** The branch ID (defaults to "main") */
+    branchId?: string;
+}