avo-inspector 2.2.0 → 2.2.2-alpha.10

package/.claude/settings.local.json

@@ -1,7 +1,24 @@
 {
   "permissions": {
     "allow": [
-      "Bash(npm test)"
+      "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",
+      "Bash(npx ts-node:*)",
+      "Bash(git -C /Users/bjorn/code/js-avo-inspector show db2db09 -- src/eventSpec/AvoEventSpecFetchTypes.ts)",
+      "Bash(git -C /Users/bjorn/code/js-avo-inspector show db2db09 -- src/eventSpec/AvoEventSpecFetcher.ts)",
+      "Bash(git -C /Users/bjorn/code/js-avo-inspector log --all --oneline --since=\"2025-12-03\")",
+      "Bash(git -C /Users/bjorn/code/js-avo-inspector branch:*)",
+      "Bash(git -C /Users/bjorn/code/js-avo-inspector log --all --oneline -20)",
+      "Bash(git -C /Users/bjorn/code/js-avo-inspector show db2db09 --stat)",
+      "Bash(git -C /Users/bjorn/code/js-avo-inspector diff --stat)"
     ],
     "deny": [],
     "ask": []

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,149 @@
+#!/usr/bin/env node
+
+// 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)
+  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];
+const outputFlag = process.argv[3];
+
+function showHelp() {
+  console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║                    AVO INSPECTOR CLI                          ║
+╚═══════════════════════════════════════════════════════════════╝
+
+Usage:
+  npx avo-inspector <command> [options]
+
+Commands:
+  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           # 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(writeToFiles = false) {
+  console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║           Generating ECC Key Pair (secp256k1)...             ║
+╚═══════════════════════════════════════════════════════════════╝
+`);
+
+  try {
+    const { publicKey, privateKey } = generateKeyPair();
+
+    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');
+  } catch (error) {
+    console.error('❌ Error generating keys:', error.message);
+    process.exit(1);
+  }
+}
+
+// Main command router
+switch (command) {
+  case 'generate-keys':
+    const writeToFiles = outputFlag === '--output' || outputFlag === '-o';
+    generateKeys(writeToFiles);
+    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,53 @@ 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.
+     * 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.
+     */
+    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;
@@ -9,23 +29,27 @@ 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;
+    /** RSA public encryption key - allows Inspector to validate encrypted values against tracking plan */
+    publicEncryptionKey?: string;
 }
 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;
+    /** Branch ID from getEventSpec response when value validation was performed */
+    validatedBranchId?: string;
 }
 export declare class AvoNetworkCallsHandler {
     private readonly apiKey;
@@ -33,17 +57,28 @@ export declare class AvoNetworkCallsHandler {
     private readonly appName;
     private readonly appVersion;
     private readonly libVersion;
+    private readonly publicEncryptionKey?;
     private samplingRate;
     private sending;
     private static readonly trackingEndpoint;
-    constructor(apiKey: string, envName: string, appName: string, appVersion: string, libVersion: string);
+    constructor(apiKey: string, envName: string, appName: string, appVersion: string, libVersion: string, publicEncryptionKey?: 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): 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).
+     * 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/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;
+}