avo-inspector 2.2.2-alpha → 2.2.2-alpha.2

package/README.md

@@ -123,7 +123,7 @@ This will output:
 
 ## Using Encryption
 
-Pass the `publicKey` parameter when initializing Inspector:
+Pass the `publicEncryptionKey` parameter when initializing Inspector:
 
 ```javascript
 import * as Inspector from "avo-inspector";
@@ -148,7 +148,7 @@ When encryption is enabled:
 
 # Client-Side Validation (Dev/Staging Only)
 
-When initialized with a `publicKey` in dev or staging environments, Inspector performs client-side validation of your events against your Avo Tracking Plan.
+When initialized with a `publicEncryptionKey` in dev or staging environments, Inspector performs client-side validation of your events against your Avo Tracking Plan.
 
 ## How It Works
 
@@ -186,13 +186,48 @@ inspector.trackSchemaFromEvent("User Signed Up", { name: "John" });
 The `trackSchema` method only sends pre-extracted schemas and **does not perform client-side validation** - it goes through the normal batching flow.
 
 ```javascript
-// ✅ Validates against tracking plan (when publicKey is provided)
+// ✅ Validates against tracking plan (when publicEncryptionKey is provided)
 inspector.trackSchemaFromEvent("Event Name", { prop: "value" });
 
 // ❌ Does NOT validate - only sends schema, uses batching
 inspector.trackSchema("Event Name", [{ propertyName: "prop", propertyType: "string" }]);
 ```
 
+## Accessing Validation Results
+
+`trackSchemaFromEvent` returns a `Promise<EventProperty[]>` that resolves with the validated properties. You can use this in two ways:
+
+### Fire-and-Forget (Default)
+
+Call without `await` for non-blocking behavior. The event is tracked asynchronously and validation happens in the background:
+
+```javascript
+// Non-blocking - validation runs in background
+inspector.trackSchemaFromEvent("Event Name", { prop: "value" });
+```
+
+### Await for Validation Results
+
+If you need to access validation results (e.g., for testing or debugging), you can `await` the call:
+
+```javascript
+// Blocking - wait for validation to complete
+const validatedProperties = await inspector.trackSchemaFromEvent("Event Name", { 
+  email: "user@example.com",
+  age: 25 
+});
+
+// Each property includes validation results:
+// {
+//   propertyName: "email",
+//   propertyType: "string",
+//   failedEventIds: [],    // Event IDs where this property failed validation
+//   passedEventIds: ["abc123"]  // Event IDs where this property passed validation
+// }
+```
+
+**Note:** Awaiting will block until the event spec is fetched (if not cached) and validation completes. For production use, fire-and-forget is recommended to avoid impacting your application's performance.
+
 # Batching control
 
 In order to ensure our SDK doesn't have a large impact on performance or battery life it supports event schemas batching.

package/dist/AvoBatcher.d.ts

@@ -1,13 +1,8 @@
-import { type AvoNetworkCallsHandler } from "./AvoNetworkCallsHandler";
+import { type AvoNetworkCallsHandler, type EventProperty } from "./AvoNetworkCallsHandler";
 import type { EventSpecMetadata } from "./eventSpec/AvoEventSpecFetchTypes";
-import type { ValidationIssue } from "./eventSpec/EventValidator";
 export interface AvoBatcherType {
     handleSessionStarted: () => void;
-    handleTrackSchema: (eventName: string, schema: Array<{
-        propertyName: string;
-        propertyType: string;
-        children?: any;
-    }>, eventId: string | null, eventHash: string | null, variantId?: string | null, eventSpecMetadata?: EventSpecMetadata, validationErrors?: ValidationIssue[]) => void;
+    handleTrackSchema: (eventName: string, schema: EventProperty[], eventId: string | null, eventHash: string | null, eventSpecMetadata?: EventSpecMetadata) => void;
 }
 export declare class AvoBatcher implements AvoBatcherType {
     private events;
@@ -15,11 +10,7 @@ export declare class AvoBatcher implements AvoBatcherType {
     private readonly networkCallsHandler;
     constructor(networkCallsHandler: AvoNetworkCallsHandler);
     handleSessionStarted(): void;
-    handleTrackSchema(eventName: string, schema: Array<{
-        propertyName: string;
-        propertyType: string;
-        children?: any;
-    }>, eventId: string | null, eventHash: string | null, variantId?: string | null, eventSpecMetadata?: EventSpecMetadata, validationErrors?: ValidationIssue[]): void;
+    handleTrackSchema(eventName: string, schema: EventProperty[], eventId: string | null, eventHash: string | null, eventSpecMetadata?: EventSpecMetadata): void;
     private checkIfBatchNeedsToBeSent;
     private saveEvents;
     static get cacheKey(): string;

package/dist/AvoInspector.d.ts

@@ -1,5 +1,6 @@
 import { type AvoInspectorEnvValueType } from "./AvoInspectorEnv";
 import { AvoBatcher } from "./AvoBatcher";
+import { type EventProperty } from "./AvoNetworkCallsHandler";
 import { AvoStorage } from "./AvoStorage";
 import { AvoDeduplicator } from "./AvoDeduplicator";
 export declare class AvoInspector {
@@ -33,12 +34,7 @@ export declare class AvoInspector {
         suffix?: string;
         publicEncryptionKey?: string;
     });
-    trackSchemaFromEvent(eventName: string, eventProperties: Record<string, any>): Promise<Array<{
-        propertyName: string;
-        propertyType: string;
-        encryptedPropertyValue?: string;
-        children?: any;
-    }>>;
+    trackSchemaFromEvent(eventName: string, eventProperties: Record<string, any>): Promise<EventProperty[]>;
     private _avoFunctionTrackSchemaFromEvent;
     trackSchema(eventName: string, eventSchema: Array<{
         propertyName: string;
@@ -70,9 +66,14 @@ export declare class AvoInspector {
      * Note: EventSpec fetching and validation only happens in dev/staging environments.
      */
     private fetchAndValidateEvent;
+    /**
+     * Merges validation results into the event schema.
+     * Adds failedEventIds or passedEventIds to each property based on validation.
+     */
+    private mergeValidationResults;
     /**
      * Sends an event immediately with validation data (bypasses batching).
-     * Logs validation errors if shouldLog is true.
+     * Logs validation info if shouldLog is true.
      */
     private sendEventWithValidation;
 }

package/dist/AvoNetworkCallsHandler.d.ts

@@ -1,5 +1,23 @@
 import type { EventSpecMetadata } from "./eventSpec/AvoEventSpecFetchTypes";
-import type { ValidationIssue } from "./eventSpec/EventValidator";
+/**
+ * Recursive type for schema children.
+ * - For object properties: array of EventProperty objects
+ * - For list properties: array of strings (primitive types) or nested structures
+ */
+export type SchemaChild = string | EventProperty | SchemaChild[];
+/**
+ * Property schema with optional validation results.
+ */
+export interface EventProperty {
+    propertyName: string;
+    propertyType: string;
+    encryptedPropertyValue?: string;
+    children?: SchemaChild[];
+    /** Event/variant IDs that FAILED validation (present if smaller or equal to passed) */
+    failedEventIds?: string[];
+    /** Event/variant IDs that PASSED validation (present if smaller than failed) */
+    passedEventIds?: string[];
+}
 export interface BaseBody {
     apiKey: string;
     appName: string;
@@ -13,28 +31,19 @@ export interface BaseBody {
     sessionId: string;
     anonymousId: string;
     samplingRate: number;
+    /** Event spec metadata from EventSpecResponse (moved from EventSchemaBody) */
+    eventSpecMetadata?: EventSpecMetadata;
 }
 export interface SessionStartedBody extends BaseBody {
     type: "sessionStarted";
 }
 export interface EventSchemaBody extends BaseBody {
     type: "event";
-    /** ID of the matched base event */
+    /** ID of the base event from spec (null if no spec available) */
     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;
-    }>;
+    eventProperties: EventProperty[];
     avoFunction: boolean;
     eventHash: string | null;
 }
@@ -51,11 +60,7 @@ export declare class AvoNetworkCallsHandler {
     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;
+    bodyForEventSchemaCall(eventName: string, eventProperties: EventProperty[], eventId: string | null, eventHash: string | null, eventSpecMetadata?: EventSpecMetadata): EventSchemaBody;
     private createBaseCallBody;
     /**
      * Calls Inspector API immediately with a single event (bypasses batching).

package/dist/AvoSchemaParser.d.ts

@@ -1,3 +1,4 @@
+import type { EventProperty } from "./AvoNetworkCallsHandler";
 export declare class AvoSchemaParser {
     /**
      * Returns true only if we have a valid encryption key and can send encrypted values.
@@ -9,12 +10,7 @@ export declare class AvoSchemaParser {
      * 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;
-    }>;
+    static extractSchema(eventProperties: Record<string, any>, publicEncryptionKey?: string, env?: string): EventProperty[];
     private static removeDuplicates;
     private static getPropValueType;
 }

package/dist/eventSpec/AvoEventSpecFetchTypes.d.ts

@@ -4,67 +4,89 @@
  * 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, string[]>;
+    /** Allowed values: JSON array string -> eventIds that accept these values */
+    v?: Record<string, string[]>;
+    /** Regex patterns: pattern -> eventIds that require matching this regex */
+    rx?: Record<string, string[]>;
+    /** Min/max ranges: "min,max" -> eventIds that require value in this range */
+    minmax?: Record<string, string[]>;
 }
 /**
- * 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: 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: 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, string[]>;
+    /** Allowed values: JSON array string -> eventIds that accept these values */
+    allowedValues?: Record<string, string[]>;
+    /** Regex patterns: pattern -> eventIds that require matching this regex */
+    regexPatterns?: Record<string, string[]>;
+    /** Min/max ranges: "min,max" -> eventIds that require value in this range */
+    minMaxRanges?: Record<string, string[]>;
+}
+/**
+ * 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: 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: EventSpecEntry[];
+    /** Schema metadata */
+    metadata: EventSpecMetadata;
 }
 /**
  * Metadata returned with the event spec response.
@@ -74,28 +96,18 @@ export interface EventSpecMetadata {
     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: number;
-    /** Number of events processed since this entry was cached */
+    /** Number of cache hits since this entry was cached */
     eventCount: number;
 }
 /** Parameters for fetching event specifications from the API. */
@@ -107,3 +119,23 @@ 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?: string[];
+    /** Event/variant IDs that PASSED validation (present if smaller than failed) */
+    passedEventIds?: string[];
+}
+/**
+ * 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

@@ -47,8 +47,8 @@ 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;
 }

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;