avo-inspector 2.2.2-alpha → 2.2.2-alpha.3

package/dist/eventSpec/AvoEventSpecFetchTypes.d.ts

@@ -4,98 +4,114 @@
  * 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.
+ * Wire format - Property constraints with short field names.
+ * At most one constraint type will be present per property.
  */
-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>;
+export interface PropertyConstraintsWire {
+    /** Type name (for reference only, not validated) */
+    t: string;
+    /** Required flag (for reference only, not validated) */
+    r: 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>;
 }
 /**
- * Represents the specification for a single property in an event.
- * Supports recursive nesting for object types.
+ * 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 PropertySpec {
-    /** Unique identifier for this property */
+export interface EventSpecEntryWire {
+    /** Branch identifier */
+    b: string;
+    /** Base event ID */
     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;
+    /** Variant IDs (baseEventId + variantIds = complete set) */
+    vids: Array<string>;
+    /** Property constraints keyed by property name */
+    p: Record<string, PropertyConstraintsWire>;
 }
 /**
- * Represents a variant of an event with additional or modified properties.
+ * Wire format - Response from getEventSpec endpoint.
+ * Contains array of events that match the requested name (due to name mapping).
  */
-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>;
+export interface EventSpecResponseWire {
+    /** Array of events matching the requested name */
+    events: Array<EventSpecEntryWire>;
+    /** Schema metadata (keeps long names - small, one per response) */
+    metadata: EventSpecMetadata;
 }
 /**
- * Represents the complete specification for an event, including base event
- * and optional variants.
+ * Internal - Property constraints with meaningful field names.
+ * At most one constraint type will be present per property.
  */
-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[];
+export interface PropertyConstraints {
+    /** Type name (for reference only, not validated) */
+    type: string;
+    /** Required flag (for reference only, not validated) */
+    required: 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 */
+    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>;
 }
 /**
- * Metadata returned with the event spec response.
+ * 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 (replaces versionId/createdAt) */
+    /** Latest action identifier */
     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 */
+    /** The cached event specification response (internal format) */
     spec: EventSpecResponse;
-    /** Timestamp when this entry was cached */
+    /** Timestamp when this entry was cached (used for TTL expiration) */
     timestamp: number;
-    /** Number of events processed since this entry was cached */
+    /** 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. */
@@ -107,3 +123,25 @@ export interface FetchEventSpecParams {
     /** 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

@@ -7,8 +7,8 @@ import type { EventSpecResponse, FetchEventSpecParams } from "./AvoEventSpecFetc
 /**
  * EventSpecFetcher handles fetching event specifications from the Avo API.
  *
- * Endpoint: GET /getEventSpec
- * Base URL: https://us-central1-avo-web-app.cloudfunctions.net
+ * Endpoint: GET /trackingPlan/eventSpec
+ * Base URL: https://api.avo.app
  */
 export declare class AvoEventSpecFetcher {
     /** Base URL for the event spec API */
@@ -34,7 +34,7 @@ export declare class AvoEventSpecFetcher {
      * - The request times out
      *
      * This method gracefully degrades - failures do not throw errors.
-     * When null is returned, validation should be skipped for that event.
+     * When null is returned, Phase 2 should skip validation for that event.
      */
     fetch(params: FetchEventSpecParams): Promise<EventSpecResponse | null>;
     /** Internal fetch implementation. */
@@ -47,8 +47,14 @@ export declare class AvoEventSpecFetcher {
      */
     private makeRequest;
     /**
-     * Basic shape check - ensures response has the minimum expected structure.
-     * Does not perform deep validation of all fields.
+     * 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

@@ -1,45 +1,16 @@
 /**
  * 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.
+ * 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)
  *
- * 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.
+ * No schema validation (types/required) is performed - only value constraints.
+ * Validation runs against ALL events/variants in the response.
  */
-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[];
-}
+import type { EventSpecResponse, ValidationResult } from "./AvoEventSpecFetchTypes";
 /**
  * Runtime property value - can be any JSON-compatible type
  */
@@ -49,42 +20,15 @@ export type RuntimePropertyValue = string | number | boolean | null | undefined
  */
 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.
+ * 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 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).
+ * @returns ValidationResult with baseEventId, metadata, and per-property results
  */
-export declare function eventExistsInSpec(eventName: string, specResponse: EventSpecResponse): boolean;
-export {};
+export declare function validateEvent(properties: RuntimeProperties, specResponse: EventSpecResponse): ValidationResult;

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