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

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/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/AvoInspector.d.ts

@@ -69,8 +69,13 @@ export declare class AvoInspector {
     /**
      * 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 info if shouldLog is true.

package/dist/AvoNetworkCallsHandler.d.ts

@@ -29,7 +29,7 @@ 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;
@@ -46,6 +46,8 @@ export interface EventSchemaBody extends BaseBody {
     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;
@@ -58,9 +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: EventProperty[], eventId: string | null, eventHash: string | null, eventSpecMetadata?: EventSpecMetadata): 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/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;
         }>;
     };

package/dist/eventSpec/AvoEventSpecFetchTypes.d.ts

@@ -13,13 +13,15 @@ export interface PropertyConstraintsWire {
     /** Required flag (for reference only, not validated) */
     r: boolean;
     /** Pinned values: pinnedValue -> eventIds that require this exact value */
-    p?: Record<string, string[]>;
+    p?: Record<string, Array<string>>;
     /** Allowed values: JSON array string -> eventIds that accept these values */
-    v?: Record<string, string[]>;
+    v?: Record<string, Array<string>>;
     /** Regex patterns: pattern -> eventIds that require matching this regex */
-    rx?: Record<string, string[]>;
+    rx?: Record<string, Array<string>>;
     /** Min/max ranges: "min,max" -> eventIds that require value in this range */
-    minmax?: Record<string, string[]>;
+    minmax?: Record<string, Array<string>>;
+    /** Nested property constraints for object properties */
+    children?: Record<string, PropertyConstraintsWire>;
 }
 /**
  * Wire format - Event spec entry with short field names.
@@ -32,7 +34,7 @@ export interface EventSpecEntryWire {
     /** Base event ID */
     id: string;
     /** Variant IDs (baseEventId + variantIds = complete set) */
-    vids: string[];
+    vids: Array<string>;
     /** Property constraints keyed by property name */
     p: Record<string, PropertyConstraintsWire>;
 }
@@ -42,7 +44,7 @@ export interface EventSpecEntryWire {
  */
 export interface EventSpecResponseWire {
     /** Array of events matching the requested name */
-    events: EventSpecEntryWire[];
+    events: Array<EventSpecEntryWire>;
     /** Schema metadata (keeps long names - small, one per response) */
     metadata: EventSpecMetadata;
 }
@@ -56,13 +58,15 @@ export interface PropertyConstraints {
     /** Required flag (for reference only, not validated) */
     required: boolean;
     /** Pinned values: pinnedValue -> eventIds that require this exact value */
-    pinnedValues?: Record<string, string[]>;
+    pinnedValues?: Record<string, Array<string>>;
     /** Allowed values: JSON array string -> eventIds that accept these values */
-    allowedValues?: Record<string, string[]>;
+    allowedValues?: Record<string, Array<string>>;
     /** Regex patterns: pattern -> eventIds that require matching this regex */
-    regexPatterns?: Record<string, string[]>;
+    regexPatterns?: Record<string, Array<string>>;
     /** Min/max ranges: "min,max" -> eventIds that require value in this range */
-    minMaxRanges?: Record<string, string[]>;
+    minMaxRanges?: Record<string, Array<string>>;
+    /** Nested property constraints for object properties */
+    children?: Record<string, PropertyConstraints>;
 }
 /**
  * Internal - Event spec entry with meaningful field names.
@@ -74,7 +78,7 @@ export interface EventSpecEntry {
     /** Base event ID */
     baseEventId: string;
     /** Variant IDs (baseEventId + variantIds = complete set) */
-    variantIds: string[];
+    variantIds: Array<string>;
     /** Property constraints keyed by property name */
     props: Record<string, PropertyConstraints>;
 }
@@ -84,13 +88,11 @@ export interface EventSpecEntry {
  */
 export interface EventSpecResponse {
     /** Array of events matching the requested name */
-    events: EventSpecEntry[];
+    events: Array<EventSpecEntry>;
     /** Schema metadata */
     metadata: EventSpecMetadata;
 }
-/**
- * Metadata returned with the event spec response.
- */
+/** Metadata returned with the event spec response. */
 export interface EventSpecMetadata {
     /** Schema identifier */
     schemaId: string;
@@ -105,8 +107,10 @@ export interface EventSpecMetadata {
 export interface EventSpecCacheEntry {
     /** 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;
+    /** Timestamp when this entry was last accessed (used for LRU eviction) */
+    lastAccessed: number;
     /** Number of cache hits since this entry was cached */
     eventCount: number;
 }
@@ -125,9 +129,11 @@ export interface FetchEventSpecParams {
  */
 export interface PropertyValidationResult {
     /** Event/variant IDs that FAILED validation (present if smaller or equal to passed) */
-    failedEventIds?: string[];
+    failedEventIds?: Array<string>;
     /** Event/variant IDs that PASSED validation (present if smaller than failed) */
-    passedEventIds?: string[];
+    passedEventIds?: Array<string>;
+    /** Nested validation results for child properties of object properties */
+    children?: Record<string, PropertyValidationResult>;
 }
 /**
  * Result of validating all properties in an event.

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. */
@@ -51,4 +51,10 @@ export declare class AvoEventSpecFetcher {
      * 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/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;
+}