avo-inspector 2.2.0 → 2.2.2-alpha

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,101 @@ 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 `publicKey` 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 `publicKey` 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 publicKey is provided)
+inspector.trackSchemaFromEvent("Event Name", { prop: "value" });
+
+// ❌ Does NOT validate - only sends schema, uses batching
+inspector.trackSchema("Event Name", [{ propertyName: "prop", propertyType: "string" }]);
+```
+
 # 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,13 @@
 import { type AvoNetworkCallsHandler } 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) => void;
+    }>, eventId: string | null, eventHash: string | null, variantId?: string | null, eventSpecMetadata?: EventSpecMetadata, validationErrors?: ValidationIssue[]) => void;
 }
 export declare class AvoBatcher implements AvoBatcherType {
     private events;
@@ -17,7 +19,7 @@ export declare class AvoBatcher implements AvoBatcherType {
         propertyName: string;
         propertyType: string;
         children?: any;
-    }>, eventId: string | null, eventHash: string | null): void;
+    }>, eventId: string | null, eventHash: string | null, variantId?: string | null, eventSpecMetadata?: EventSpecMetadata, validationErrors?: ValidationIssue[]): 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

@@ -8,6 +8,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 +31,48 @@ export declare class AvoInspector {
         version: string;
         appName?: string;
         suffix?: string;
+        publicEncryptionKey?: string;
     });
-    trackSchemaFromEvent(eventName: string, eventProperties: Record<string, any>): Array<{
+    trackSchemaFromEvent(eventName: string, eventProperties: Record<string, any>): Promise<Array<{
         propertyName: string;
         propertyType: string;
+        encryptedPropertyValue?: string;
         children?: any;
-    }>;
+    }>>;
     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;
+    /**
+     * Sends an event immediately with validation data (bypasses batching).
+     * Logs validation errors if shouldLog is true.
+     */
+    private sendEventWithValidation;
 }

package/dist/AvoNetworkCallsHandler.d.ts

@@ -1,3 +1,5 @@
+import type { EventSpecMetadata } from "./eventSpec/AvoEventSpecFetchTypes";
+import type { ValidationIssue } from "./eventSpec/EventValidator";
 export interface BaseBody {
     apiKey: string;
     appName: string;
@@ -17,14 +19,23 @@ export interface SessionStartedBody extends BaseBody {
 }
 export interface EventSchemaBody extends BaseBody {
     type: "event";
-    eventName: string;
+    /** ID of the matched base event */
+    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;
     }>;
     avoFunction: boolean;
-    eventId: string | null;
     eventHash: string | null;
 }
 export declare class AvoNetworkCallsHandler {
@@ -44,6 +55,20 @@ export declare class AvoNetworkCallsHandler {
         propertyName: string;
         propertyType: string;
         children?: any;
-    }>, eventId: string | null, eventHash: string | null): EventSchemaBody;
+    }>, eventId: string | null, eventHash: string | null, variantId?: string | null, eventSpecMetadata?: EventSpecMetadata, validationErrors?: ValidationIssue[]): 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,7 +1,18 @@
 export declare class AvoSchemaParser {
-    static extractSchema(eventProperties: Record<string, any>): Array<{
+    /**
+     * 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): Array<{
         propertyName: string;
         propertyType: string;
+        encryptedPropertyValue?: string;
         children?: any;
     }>;
     private static removeDuplicates;

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

package/dist/eventSpec/AvoEventSpecFetchTypes.d.ts

@@ -0,0 +1,109 @@
+/**
+ * This file is generated. Internal development changes should be made in the generator
+ * and the file should be re-generated. External contributions are welcome to submit
+ * 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.
+ */
+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>;
+}
+/**
+ * Represents the specification for a single property in an event.
+ * Supports recursive nesting for object types.
+ */
+export interface PropertySpec {
+    /** Unique identifier for this property */
+    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;
+}
+/**
+ * Represents a variant of an event with additional or modified properties.
+ */
+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>;
+}
+/**
+ * Represents the complete specification for an event, including base event
+ * and optional variants.
+ */
+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[];
+}
+/**
+ * Metadata returned with the event spec response.
+ */
+export interface EventSpecMetadata {
+    /** Schema identifier */
+    schemaId: string;
+    /** Branch identifier */
+    branchId: string;
+    /** Latest action identifier (replaces versionId/createdAt) */
+    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 */
+    spec: EventSpecResponse;
+    /** Timestamp when this entry was cached */
+    timestamp: number;
+    /** Number of events processed since this entry was cached */
+    eventCount: number;
+}
+/** Parameters for fetching event specifications from the API. */
+export interface FetchEventSpecParams {
+    /** The API key */
+    apiKey: string;
+    /** The stream ID */
+    streamId: string;
+    /** The name of the event */
+    eventName: string;
+}