avo-inspector 2.2.0 → 2.2.2-alpha

package/dist/eventSpec/AvoEventSpecFetcher.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 /getEventSpec
+ * Base URL: https://us-central1-avo-web-app.cloudfunctions.net
+ */
+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;
+}

package/dist/eventSpec/EventValidator.d.ts

@@ -0,0 +1,90 @@
+/**
+ * EventValidator - Client-side validation of tracking events against the Avo Tracking Plan.
+ *
+ * This module handles:
+ * 1. Matching: Identifying the most likely Event and Variant from specs
+ * 2. Validation: Checking runtime properties against the matched spec rules
+ */
+import type { EventSpecResponse, EventSpec, EventSpecMetadata, VariantSpec } from "./AvoEventSpecFetchTypes";
+/**
+ * Validation issue codes for client-side validation.
+ */
+export type ValidationIssueCode = "RequiredMissing" | "ValueBelowMin" | "ValueAboveMax" | "RegexMismatch" | "NotInAllowedValues" | "UnexpectedProperty" | "UnexpectedEvent" | "TypeMismatch";
+/**
+ * Represents a validation issue found during event validation.
+ *
+ * Note: We do NOT include the received value to avoid sending user data to the backend.
+ * The backend can correlate issues with encrypted values via propertyName matching
+ * against eventProperties.encryptedPropertyValue in the payload.
+ */
+export interface ValidationIssue {
+    /** The type of validation issue */
+    code: ValidationIssueCode;
+    /** Property ID (preferred over name) */
+    propertyId?: string;
+    /** Property name - used to correlate with encryptedPropertyValue in eventProperties */
+    propertyName?: string;
+    /** Expected value for the validation rule (from spec, not user data) */
+    expected?: string | number | boolean;
+}
+/**
+ * Result of the validation process.
+ */
+export interface ValidationResult {
+    /** ID of the matched event, null if no match found */
+    eventId: string | null;
+    /** ID of the matched variant, null if base event or no match */
+    variantId: string | null;
+    /** Event spec metadata from the response */
+    eventSpecMetadata: EventSpecMetadata;
+    /** List of all validation issues found */
+    validationErrors: ValidationIssue[];
+}
+/**
+ * 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>;
+/**
+ * Internal match result for scoring
+ */
+interface MatchCandidate {
+    event: EventSpec;
+    variant: VariantSpec | null;
+    score: number;
+}
+/**
+ * Validates a runtime event against the EventSpecResponse.
+ *
+ * @param eventName - The event name observed at runtime
+ * @param properties - The properties observed at runtime
+ * @param specResponse - The EventSpecResponse from the backend
+ * @returns ValidationResult with match info and any validation errors
+ */
+export declare function validateEvent(eventName: string, properties: RuntimeProperties, specResponse: EventSpecResponse): ValidationResult;
+/**
+ * Finds the closest matching Event and Variant for the runtime data.
+ *
+ * @param eventName - Runtime event name
+ * @param properties - Runtime properties
+ * @param events - Array of EventSpecs to match against
+ * @returns The best matching event and variant, or null if no match
+ */
+export declare function findClosestMatch(eventName: string, properties: RuntimeProperties, events: EventSpec[]): MatchCandidate | null;
+/**
+ * Validates runtime properties against the matched event and variant specs.
+ *
+ * @param properties - Runtime properties
+ * @param event - Matched EventSpec
+ * @param variant - Matched VariantSpec (or null for base event)
+ * @returns Array of validation issues found
+ */
+export declare function validateProperties(properties: RuntimeProperties, event: EventSpec, variant: VariantSpec | null): ValidationIssue[];
+/**
+ * Quick check if an event exists in the spec (without full validation).
+ */
+export declare function eventExistsInSpec(eventName: string, specResponse: EventSpecResponse): boolean;
+export {};

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/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;
+}