avo-inspector 2.2.0 → 2.2.2-alpha.2

package/CHANGELOG.md

@@ -1,3 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.2.1-alpha] - 2025-11-24
+
+### Added
+
+- **ECC Property Value Encryption**: Optional `publicEncryptionKey` parameter on SDK initialization enables zero-knowledge encryption of property values in dev/staging environments using ECIES (Elliptic Curve Integrated Encryption Scheme). Avo never has access to the private key, ensuring complete data privacy.
+  - Uses secp256k1 curve with AES-256-GCM for hybrid encryption
+  - Only encrypts in dev/staging environments (production sends schema only)
+  - Adds optional `encryptedPropertyValue` field to event schema
+  - CLI tool for key generation: `npx avo-inspector generate-keys`
+  - Note: Key generation and decryption are not exported from SDK (use CLI tool for keys, decryption happens in Avo's dashboard)
+
+- **EventSpec Fetching**: Automatically fetches and caches event specifications from Avo API in dev/staging environments
+  - Non-blocking async API calls
+  - In-memory caching for performance
+  - NOT called in production (prod remains simple and fast)
+  - Foundation for Phase 2: event validation
+
+### Changed
+
+- Production environment now optimized: no property values, no encryption, no EventSpec API calls
+- Dev/Staging environments now support rich debugging with encrypted values and event specs
+
+### Dependencies
+
+- Added `eciesjs` ^0.4.11 for ECC/ECIES encryption
+
 ## 2.2.0
 
 - Add anonymous ID support to track events without user identification
@@ -22,4 +55,4 @@ Security update
 
 ## 1.3.0
 
-Multiple Avo Inspector instances support, with the optional `suffix` constructor parameter
+Multiple Avo Inspector instances support, with the optional `suffix` constructor parameter

package/README.md

@@ -98,6 +98,136 @@ let schema = inspector.extractSchema({
 
 You can experiment with this method to see how more complex schemas look, for example with nested lists and objects.
 
+# Property Value Encryption (Dev/Staging Only)
+
+Inspector supports encrypting property values in development and staging environments. This allows you to see actual property values in Avo's debugging tools without exposing sensitive data, since only you hold the private decryption key.
+
+## Key Features
+
+- Uses ECC (Elliptic Curve Cryptography) with secp256k1 for strong security
+- Zero-knowledge architecture: Avo never has access to your private key
+- No message size limitations
+- Only active in dev/staging environments (production is unaffected)
+
+## Generating Keys
+
+Use the built-in CLI tool to generate a key pair:
+
+```bash
+npx avo-inspector generate-keys
+```
+
+This will output:
+- **Public key**: Pass this to the SDK to enable encryption
+- **Private key**: Save this externally (you'll use it to decrypt values in Avo's dashboard)
+
+## Using Encryption
+
+Pass the `publicEncryptionKey` parameter when initializing Inspector:
+
+```javascript
+import * as Inspector from "avo-inspector";
+
+let inspector = new Inspector.AvoInspector({
+  apiKey: "your api key",
+  env: Inspector.AvoInspectorEnv.Dev,
+  version: "1.0.0",
+  publicEncryptionKey: "your-public-key-hex-string" // Enable encryption
+});
+```
+
+**Note:** The public key is not a secret - you can hardcode it, store it in `.env`, or configure it however you prefer. The SDK only uses the public key to encrypt values before sending them to Avo.
+
+**Private key:** Save it securely (password manager, secure notes). Never expose it to the SDK. You only need it when viewing encrypted values in Avo's dashboard.
+
+When encryption is enabled:
+- Property values are encrypted before being sent to Avo
+- You can decrypt them in Avo's dashboard using your private key
+- Works with all data types: strings, numbers, booleans, objects, arrays, null
+- Handles large payloads (1KB+) without issues
+
+# Client-Side Validation (Dev/Staging Only)
+
+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
+
+1. **Event Spec Fetching**: When you track an event, Inspector fetches the event specification from Avo's backend (results are cached for performance).
+
+2. **Event Matching**: Inspector matches your event to the closest event in your tracking plan, considering event names, mapped names, and variant-specific properties.
+
+3. **Property Validation**: Your event properties are validated against the spec rules:
+   - Required properties are present
+   - Property types match (string, int, float, boolean, object, list)
+   - Numeric values are within min/max bounds
+   - String values match regex patterns
+   - Enum values are in the allowed list
+   - Pinned values match exactly (variant-specific fixed values)
+   - No unexpected properties are sent
+
+4. **Immediate Reporting**: Validated events bypass batching and are sent immediately to Inspector, ensuring you get real-time feedback.
+
+## Validation Errors
+
+If logging is enabled, validation errors are logged to the console:
+
+```javascript
+inspector.enableLogging(true);
+
+// If "User Signed Up" requires an "email" property:
+inspector.trackSchemaFromEvent("User Signed Up", { name: "John" });
+// Console: [Avo Inspector] Validation errors for event "User Signed Up": [{ code: "RequiredMissing", propertyName: "email" }]
+```
+
+## Important: trackSchema Does Not Validate
+
+**Note:** Client-side validation only works with `trackSchemaFromEvent`, which has access to actual property values needed for validation.
+
+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 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

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+// Use eciesjs directly for ECC key generation
+const { PrivateKey } = require('eciesjs');
+
+function generateKeyPair() {
+  // Generate a new random private key (32 bytes / 256 bits)
+  const privateKey = new PrivateKey();
+
+  // Derive the public key from the private key
+  const publicKey = privateKey.publicKey;
+
+  return {
+    publicKey: publicKey.toHex(),
+    privateKey: privateKey.toHex()
+  };
+}
+
+const command = process.argv[2];
+
+function showHelp() {
+  console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║                    AVO INSPECTOR CLI                          ║
+╚═══════════════════════════════════════════════════════════════╝
+
+Usage:
+  npx avo-inspector <command>
+
+Commands:
+  generate-keys    Generate ECC key pair for property encryption
+  help            Show this help message
+
+Examples:
+  npx avo-inspector generate-keys
+  `);
+}
+
+function generateKeys() {
+  console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║           Generating ECC Key Pair (secp256k1)...             ║
+╚═══════════════════════════════════════════════════════════════╝
+`);
+
+  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');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+    console.log('ℹ️  Note: Property encryption only works in dev/staging environments.');
+    console.log('   Production data is never encrypted for performance.\n');
+  } catch (error) {
+    console.error('❌ Error generating keys:', error.message);
+    process.exit(1);
+  }
+}
+
+// Main command router
+switch (command) {
+  case 'generate-keys':
+    generateKeys();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+    showHelp();
+    break;
+  case undefined:
+    console.error('❌ No command specified\n');
+    showHelp();
+    process.exit(1);
+    break;
+  default:
+    console.error(`❌ Unknown command: ${command}\n`);
+    showHelp();
+    process.exit(1);
+}

package/dist/AvoBatcher.d.ts

@@ -1,11 +1,8 @@
-import { type AvoNetworkCallsHandler } from "./AvoNetworkCallsHandler";
+import { type AvoNetworkCallsHandler, type EventProperty } from "./AvoNetworkCallsHandler";
+import type { EventSpecMetadata } from "./eventSpec/AvoEventSpecFetchTypes";
 export interface AvoBatcherType {
     handleSessionStarted: () => void;
-    handleTrackSchema: (eventName: string, schema: Array<{
-        propertyName: string;
-        propertyType: string;
-        children?: any;
-    }>, eventId: string | null, eventHash: string | null) => void;
+    handleTrackSchema: (eventName: string, schema: EventProperty[], eventId: string | null, eventHash: string | null, eventSpecMetadata?: EventSpecMetadata) => void;
 }
 export declare class AvoBatcher implements AvoBatcherType {
     private events;
@@ -13,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): 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/AvoEncryption.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Generates a new ECC key pair for encryption/decryption.
+ * Uses secp256k1 curve (P-256 family) which provides 128-bit security.
+ *
+ * @returns An object containing the private and public keys as hex strings
+ */
+export declare function generateKeyPair(): {
+    privateKey: string;
+    publicKey: string;
+};
+/**
+ * Encrypts a value using ECC public key encryption (ECIES).
+ * The encrypted output can only be decrypted by the client using their private key.
+ * This ensures that Avo cannot decrypt the values on the backend.
+ *
+ * ECIES uses hybrid encryption (ECDH + AES-256-GCM) which provides:
+ * - No message size limitations
+ * - Fast encryption even for large values
+ * - Strong authentication via GCM
+ *
+ * @param value - The value to encrypt (any type - will be JSON stringified)
+ * @param publicKey - The ECC public key in hex format provided by the client
+ * @returns Base64-encoded encrypted string that can only be decrypted with the private key
+ */
+export declare function encryptValue(value: any, publicKey: string): string;
+/**
+ * Decrypts a value that was encrypted with encryptValue.
+ *
+ * @param encryptedValue - The base64-encoded encrypted string
+ * @param privateKey - The ECC private key in hex format
+ * @returns The original decrypted value (parsed from JSON)
+ */
+export declare function decryptValue(encryptedValue: string, privateKey: string): any;

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 {
@@ -8,6 +9,11 @@ export declare class AvoInspector {
     avoDeduplicator: AvoDeduplicator;
     apiKey: string;
     version: string;
+    private avoNetworkCallsHandler;
+    private publicEncryptionKey?;
+    private streamId?;
+    private eventSpecCache?;
+    private eventSpecFetcher?;
     static avoStorage: AvoStorage;
     private static _batchSize;
     static get batchSize(): number;
@@ -26,25 +32,48 @@ export declare class AvoInspector {
         version: string;
         appName?: string;
         suffix?: string;
+        publicEncryptionKey?: string;
     });
-    trackSchemaFromEvent(eventName: string, eventProperties: Record<string, any>): Array<{
-        propertyName: string;
-        propertyType: string;
-        children?: any;
-    }>;
+    trackSchemaFromEvent(eventName: string, eventProperties: Record<string, any>): Promise<EventProperty[]>;
     private _avoFunctionTrackSchemaFromEvent;
     trackSchema(eventName: string, eventSchema: Array<{
         propertyName: string;
         propertyType: string;
+        encryptedPropertyValue?: string;
         children?: any;
-    }>): void;
+    }>): Promise<void>;
     private trackSchemaInternal;
     enableLogging(enable: boolean): void;
     extractSchema(eventProperties: Record<string, any>, shouldLogIfEnabled?: boolean): Array<{
         propertyName: string;
         propertyType: string;
+        encryptedPropertyValue?: string;
         children?: any;
     }>;
     setBatchSize(newBatchSize: number): void;
     setBatchFlushSeconds(newBatchFlushSeconds: number): void;
+    /**
+     * Fetches the event spec if spec fetching is enabled.
+     * Used by trackSchema when we don't have raw properties to validate.
+     *
+     * Note: EventSpec fetching only happens in dev/staging environments.
+     */
+    private fetchEventSpecIfNeeded;
+    /**
+     * Fetches event spec and validates the event against it.
+     * Returns ValidationResult if spec is available, null otherwise.
+     *
+     * 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 info if shouldLog is true.
+     */
+    private sendEventWithValidation;
 }

package/dist/AvoNetworkCallsHandler.d.ts

@@ -1,3 +1,23 @@
+import type { EventSpecMetadata } from "./eventSpec/AvoEventSpecFetchTypes";
+/**
+ * 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,20 +31,20 @@ 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";
-    eventName: string;
-    eventProperties: Array<{
-        propertyName: string;
-        propertyType: string;
-        children?: any;
-    }>;
-    avoFunction: boolean;
+    /** ID of the base event from spec (null if no spec available) */
     eventId: string | null;
+    /** Name seen in code */
+    eventName?: string;
+    eventProperties: EventProperty[];
+    avoFunction: boolean;
     eventHash: string | null;
 }
 export declare class AvoNetworkCallsHandler {
@@ -40,10 +60,20 @@ 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): 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).
+     * Used when event spec validation is available.
+     * Note: Does not drop due to sampling - validated events are always sent.
+     */
+    callInspectorImmediately(eventBody: EventSchemaBody, onCompleted: (error: Error | null) => any): void;
+    /**
+     * Check if event should be dropped based on sampling rate.
+     */
+    private shouldDropBySampling;
+    /**
+     * Core Inspector API call logic shared by batch and immediate calls.
+     */
+    private callInspectorApi;
 }

package/dist/AvoSchemaParser.d.ts

@@ -1,9 +1,16 @@
+import type { EventProperty } from "./AvoNetworkCallsHandler";
 export declare class AvoSchemaParser {
-    static extractSchema(eventProperties: Record<string, any>): Array<{
-        propertyName: string;
-        propertyType: string;
-        children?: any;
-    }>;
+    /**
+     * Returns true only if we have a valid encryption key and can send encrypted values.
+     * If no key is present, returns false and no property values will be sent.
+     */
+    private static canSendEncryptedValues;
+    /**
+     * Returns the encrypted property value if encryption is enabled, otherwise undefined.
+     * Never returns unencrypted values - only encrypted or nothing.
+     */
+    private static getEncryptedPropertyValueIfEnabled;
+    static extractSchema(eventProperties: Record<string, any>, publicEncryptionKey?: string, env?: string): EventProperty[];
     private static removeDuplicates;
     private static getPropValueType;
 }

package/dist/browser.js.LICENSE.txt

@@ -0,0 +1,5 @@
+/*! noble-ciphers - MIT License (c) 2023 Paul Miller (paulmillr.com) */
+
+/*! noble-curves - MIT License (c) 2022 Paul Miller (paulmillr.com) */
+
+/*! noble-hashes - MIT License (c) 2022 Paul Miller (paulmillr.com) */

package/dist/eventSpec/AvoEventSpecCache.d.ts

@@ -0,0 +1,73 @@
+import type { EventSpecResponse } from "./AvoEventSpecFetchTypes";
+/**
+ * EventSpecCache implements a dual-condition cache with LRU eviction.
+ *
+ * Cache Policy:
+ * - Entries expire after 5 minutes OR 50 cache hits, whichever comes first
+ * - When 50 cache hits occur globally, the oldest cached entry is evicted
+ * - Each cache entry tracks: spec, timestamp, and hit count
+ *
+ * Cache Key Format: ${apiKey}:${streamId}:${eventName}
+ *
+ * Note: Event count only increments on cache hits, not on every tracked event.
+ * This ensures the cache evicts based on actual usage, not overall tracking volume.
+ */
+export declare class EventSpecCache {
+    /** Cache storage: key -> CacheEntry */
+    private cache;
+    /** Time-to-live in milliseconds (5 minutes) */
+    private readonly TTL_MS;
+    /** Maximum cache hit count before rotating cache (50 hits) */
+    private readonly MAX_EVENT_COUNT;
+    /** Global cache hit 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 response from the cache if it exists and is valid.
+     * Returns null if the entry is missing, expired, or has exceeded event count.
+     *
+     * On cache hit, increments the hit count for this entry and the global counter.
+     */
+    get(apiKey: string, streamId: string, eventName: string): EventSpecResponse | null;
+    /**
+     * Stores an event spec response in the cache.
+     */
+    set(apiKey: string, streamId: string, eventName: string, spec: EventSpecResponse): void;
+    /**
+     * Determines if a cache entry should be evicted based on:
+     * - Age (older than 5 minutes)
+     * - Hit count (50 or more cache hits)
+     */
+    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;
+        }>;
+    };
+}