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

package/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test)",
+      "Bash(npm test:*)",
+      "Bash(npm run build:*)",
+      "Bash(yarn typecheck:*)",
+      "Bash(yarn test:*)",
+      "Bash(yarn build)",
+      "WebSearch",
+      "Bash(node -e:*)",
+      "Bash(git add:*)",
+      "mcp__linear__list_issues"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

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/bin/avo-inspector.js

@@ -2,6 +2,8 @@
 
 // Use eciesjs directly for ECC key generation
 const { PrivateKey } = require('eciesjs');
+const fs = require('fs');
+const path = require('path');
 
 function generateKeyPair() {
   // Generate a new random private key (32 bytes / 256 bits)
@@ -17,6 +19,7 @@ function generateKeyPair() {
 }
 
 const command = process.argv[2];
+const outputFlag = process.argv[3];
 
 function showHelp() {
   console.log(`
@@ -25,18 +28,24 @@ function showHelp() {
 ╚═══════════════════════════════════════════════════════════════╝
 
 Usage:
-  npx avo-inspector <command>
+  npx avo-inspector <command> [options]
 
 Commands:
-  generate-keys    Generate ECC key pair for property encryption
-  help            Show this help message
+  generate-keys           Generate ECC key pair for property encryption
+  help                   Show this help message
+
+Options:
+  --output, -o           Write keys to files instead of stdout
+                         Creates: avo-public.key and avo-private.key
 
 Examples:
-  npx avo-inspector generate-keys
+  npx avo-inspector generate-keys           # Print keys to console
+  npx avo-inspector generate-keys --output  # Write keys to files
+  npx avo-inspector generate-keys -o        # Write keys to files (short form)
   `);
 }
 
-function generateKeys() {
+function generateKeys(writeToFiles = false) {
   console.log(`
 ╔═══════════════════════════════════════════════════════════════╗
 ║           Generating ECC Key Pair (secp256k1)...             ║
@@ -46,26 +55,68 @@ function generateKeys() {
   try {
     const { publicKey, privateKey } = generateKeyPair();
 
-    console.log('✅ Key pair generated successfully!\n');
-    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
-    console.log('📋 PUBLIC KEY (safe to share with Avo SDK):\n');
-    console.log(publicKey);
-    console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
-    console.log('🔐 PRIVATE KEY (⚠️  KEEP SECURE - DO NOT COMMIT TO GIT):\n');
-    console.log(privateKey);
-    console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
-    console.log('📝 Next Steps:\n');
-    console.log('1. Use the PUBLIC KEY in your SDK initialization:\n');
-    console.log('   const inspector = new AvoInspector({');
-    console.log('     apiKey: "your-api-key",');
-    console.log('     env: AvoInspectorEnv.Dev,');
-    console.log('     version: "1.0.0",');
-    console.log('     publicKey: "<paste public key above>"');
-    console.log('   });\n');
-    console.log('   💡 The public key is not a secret - you can hardcode it or use .env\n');
-    console.log('2. Save the PRIVATE KEY externally (password manager, secure notes)');
-    console.log('   - The SDK never uses the private key');
-    console.log('   - You only need it to decrypt values in Avo\'s dashboard\n');
+    if (writeToFiles) {
+      // Write keys to files instead of printing to console
+      const publicKeyPath = path.join(process.cwd(), 'avo-public.key');
+      const privateKeyPath = path.join(process.cwd(), 'avo-private.key');
+
+      // Check if files already exist
+      if (fs.existsSync(publicKeyPath) || fs.existsSync(privateKeyPath)) {
+        console.error('❌ Error: Key files already exist in current directory.');
+        console.error('   Delete avo-public.key and avo-private.key first, or use a different directory.\n');
+        process.exit(1);
+      }
+
+      // Write public key
+      fs.writeFileSync(publicKeyPath, publicKey + '\n', { mode: 0o644 });
+      console.log(`✅ Public key written to:  ${publicKeyPath}`);
+
+      // Write private key with restrictive permissions (owner read/write only)
+      fs.writeFileSync(privateKeyPath, privateKey + '\n', { mode: 0o600 });
+      console.log(`✅ Private key written to: ${privateKeyPath}`);
+
+      console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+      console.log('⚠️  IMPORTANT: Add avo-private.key to your .gitignore!\n');
+      console.log('   echo "avo-private.key" >> .gitignore\n');
+      console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+      console.log('📝 Next Steps:\n');
+      console.log('1. Use the PUBLIC KEY in your SDK initialization:\n');
+      console.log('   const inspector = new AvoInspector({');
+      console.log('     apiKey: "your-api-key",');
+      console.log('     env: AvoInspectorEnv.Dev,');
+      console.log('     version: "1.0.0",');
+      console.log('     publicKey: fs.readFileSync("avo-public.key", "utf8").trim()');
+      console.log('   });\n');
+      console.log('2. Store avo-private.key securely (password manager, vault, etc.)');
+      console.log('   - The SDK never uses the private key');
+      console.log('   - You only need it to decrypt values in Avo\'s dashboard\n');
+    } else {
+      // Print keys to console (original behavior)
+      console.log('✅ Key pair generated successfully!\n');
+      console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+      console.log('📋 PUBLIC KEY (safe to share with Avo SDK):\n');
+      console.log(publicKey);
+      console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+      console.log('🔐 PRIVATE KEY (⚠️  KEEP SECURE - DO NOT COMMIT TO GIT):\n');
+      console.log(privateKey);
+      console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+      console.log('💡 TIP: Use --output flag to write keys to files instead:\n');
+      console.log('   npx avo-inspector generate-keys --output\n');
+      console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+      console.log('📝 Next Steps:\n');
+      console.log('1. Use the PUBLIC KEY in your SDK initialization:\n');
+      console.log('   const inspector = new AvoInspector({');
+      console.log('     apiKey: "your-api-key",');
+      console.log('     env: AvoInspectorEnv.Dev,');
+      console.log('     version: "1.0.0",');
+      console.log('     publicKey: "<paste public key above>"');
+      console.log('   });\n');
+      console.log('   💡 The public key is not a secret - you can hardcode it or use .env\n');
+      console.log('2. Save the PRIVATE KEY externally (password manager, secure notes)');
+      console.log('   - The SDK never uses the private key');
+      console.log('   - You only need it to decrypt values in Avo\'s dashboard\n');
+    }
+
     console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
     console.log('ℹ️  Note: Property encryption only works in dev/staging environments.');
     console.log('   Production data is never encrypted for performance.\n');
@@ -78,7 +129,8 @@ function generateKeys() {
 // Main command router
 switch (command) {
   case 'generate-keys':
-    generateKeys();
+    const writeToFiles = outputFlag === '--output' || outputFlag === '-o';
+    generateKeys(writeToFiles);
     break;
   case 'help':
   case '--help':

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,19 @@ 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.
+     * Recursively merges validation results for nested children.
+     */
+    private mergeValidationResults;
+    /**
+     * Merges validation result into a single property, recursively handling children.
+     */
+    private mergePropertyValidation;
     /**
      * 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;
@@ -11,32 +29,25 @@ export interface BaseBody {
     trackingId: string;
     createdAt: string;
     sessionId: string;
-    anonymousId: string;
+    streamId: 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;
+    /** Branch ID from getEventSpec response when value validation was performed */
+    validatedBranchId?: string;
 }
 export declare class AvoNetworkCallsHandler {
     private readonly apiKey;
@@ -49,13 +60,9 @@ export declare class AvoNetworkCallsHandler {
     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;
+    private fixStreamIds;
     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, validatedBranchId?: string): 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/AvoStreamId.d.ts

@@ -0,0 +1,58 @@
+/**
+ * AvoStreamId manages an ephemeral stream identifier.
+ *
+ * The stream ID is generated and stored persistently, but resets after:
+ * - 4 hours of total age AND
+ * - 2 hours of idle time (no activity)
+ *
+ * This ensures the ID is truly anonymous by not persisting indefinitely,
+ * while still maintaining session continuity during active usage.
+ */
+export declare class AvoStreamId {
+    private static _streamId;
+    private static _createdAt;
+    private static _lastActivityAt;
+    private static readonly MAX_AGE_MS;
+    private static readonly IDLE_THRESHOLD_MS;
+    private static readonly STREAM_ID_KEY;
+    private static readonly CREATED_AT_KEY;
+    private static readonly LAST_ACTIVITY_KEY;
+    /**
+     * Get the stream ID. If it doesn't exist or has expired, generates a new one.
+     * Returns "unknown" if storage is not initialized.
+     */
+    static get streamId(): string;
+    /**
+     * Check if the stream ID should be reset based on age and idle time.
+     */
+    private static shouldReset;
+    /**
+     * Load stream ID and timestamps from storage into cache.
+     */
+    private static loadFromStorage;
+    /**
+     * Generate a new stream ID and store it with timestamps.
+     */
+    private static generateAndStoreNew;
+    /**
+     * Update the last activity timestamp.
+     */
+    private static updateLastActivity;
+    /**
+     * The storage key used to persist the stream ID.
+     */
+    static get storageKey(): string;
+    /**
+     * The storage key for created at timestamp.
+     */
+    static get createdAtKey(): string;
+    /**
+     * The storage key for last activity timestamp.
+     */
+    static get lastActivityKey(): string;
+    /**
+     * Clear the cached stream ID. The next access will reload from storage.
+     * This is primarily useful for testing.
+     */
+    static clearCache(): void;
+}

package/dist/eventSpec/AvoEventSpecCache.d.ts

@@ -46,7 +46,7 @@ export declare class EventSpecCache {
      */
     private shouldEvict;
     /**
-     * Evicts the oldest cache entry based on timestamp.
+     * Evicts the least recently used cache entry based on lastAccessed timestamp.
      * This implements the LRU (Least Recently Used) eviction policy.
      */
     private evictOldest;
@@ -67,6 +67,7 @@ export declare class EventSpecCache {
         entries: Array<{
             key: string;
             age: number;
+            lastAccessedAgo: number;
             eventCount: number;
         }>;
     };