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

package/package.json

@@ -1,6 +1,6 @@
    {
   "name": "avo-inspector",
-  "version": "2.2.2-alpha",
+  "version": "2.2.2-alpha.3",
   "description": "",
   "main": "dist/index.js",
   "browser": "dist/index.js",

package/dist/browser.js.LICENSE.txt

@@ -1,5 +0,0 @@
-/*! 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-browser/AvoAnonymousId.d.ts

@@ -1,26 +0,0 @@
-/**
- * AvoAnonymousId manages a persistent anonymous user identifier.
- *
- * The anonymous ID is generated once and stored persistently across sessions.
- * It remains the same until the storage is cleared or the user uninstalls the app.
- *
- * This class is designed to be standalone and reusable across different SDK platforms
- * (Web, Node, React Native). Each platform should provide its own AvoStorage implementation.
- */
-export declare class AvoAnonymousId {
-    private static _anonymousId;
-    /**
-     * Get the anonymous ID. If it doesn't exist, generates and persists a new one.
-     * Returns "unknown" if storage is not initialized.
-     */
-    static get anonymousId(): string;
-    /**
-     * The storage key used to persist the anonymous ID.
-     */
-    static get storageKey(): string;
-    /**
-     * Clear the cached anonymous ID. The next access will reload from storage.
-     * This is primarily useful for testing.
-     */
-    static clearCache(): void;
-}

package/dist-browser/AvoBatcher.d.ts

@@ -1,26 +0,0 @@
-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, variantId?: string | null, eventSpecMetadata?: EventSpecMetadata, validationErrors?: ValidationIssue[]) => void;
-}
-export declare class AvoBatcher implements AvoBatcherType {
-    private events;
-    private batchFlushAttemptTimestamp;
-    private readonly networkCallsHandler;
-    constructor(networkCallsHandler: AvoNetworkCallsHandler);
-    handleSessionStarted(): void;
-    handleTrackSchema(eventName: string, schema: Array<{
-        propertyName: string;
-        propertyType: string;
-        children?: any;
-    }>, eventId: string | null, eventHash: string | null, variantId?: string | null, eventSpecMetadata?: EventSpecMetadata, validationErrors?: ValidationIssue[]): void;
-    private checkIfBatchNeedsToBeSent;
-    private saveEvents;
-    static get cacheKey(): string;
-}

package/dist-browser/AvoDeduplicator.d.ts

@@ -1,20 +0,0 @@
-export declare class AvoDeduplicator {
-    avoFunctionsEvents: Record<number, string>;
-    manualEvents: Record<number, string>;
-    avoFunctionsEventsParams: Record<string, Record<string, any>>;
-    manualEventsParams: Record<string, Record<string, any>>;
-    shouldRegisterEvent(eventName: string, params: Record<string, any>, fromAvoFunction: boolean): boolean;
-    private hasSameEventAs;
-    private lookForEventIn;
-    hasSeenEventParams(params: Record<string, any>, checkInAvoFunctions: boolean): boolean;
-    private lookForEventParamsIn;
-    shouldRegisterSchemaFromManually(eventName: string, eventSchema: Array<{
-        propertyName: string;
-        propertyType: string;
-        children?: any;
-    }>): boolean;
-    private hasSameShapeInAvoFunctionsAs;
-    private lookForEventSchemaIn;
-    private clearOldEvents;
-    private _clearEvents;
-}

package/dist-browser/AvoEncryption.d.ts

@@ -1,33 +0,0 @@
-/**
- * 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-browser/AvoGuid.d.ts

@@ -1,3 +0,0 @@
-export default class AvoGuid {
-    static newGuid(): string;
-}

package/dist-browser/AvoInspector.d.ts

@@ -1,78 +0,0 @@
-import { type AvoInspectorEnvValueType } from "./AvoInspectorEnv";
-import { AvoBatcher } from "./AvoBatcher";
-import { AvoStorage } from "./AvoStorage";
-import { AvoDeduplicator } from "./AvoDeduplicator";
-export declare class AvoInspector {
-    environment: AvoInspectorEnvValueType;
-    avoBatcher: AvoBatcher;
-    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;
-    static set batchSize(newSize: number);
-    private static _batchFlushSeconds;
-    static get batchFlushSeconds(): number;
-    private static _shouldLog;
-    static get shouldLog(): boolean;
-    static set shouldLog(enable: boolean);
-    private static _networkTimeout;
-    static get networkTimeout(): number;
-    static set networkTimeout(timeout: number);
-    constructor(options: {
-        apiKey: string;
-        env: AvoInspectorEnvValueType;
-        version: string;
-        appName?: string;
-        suffix?: string;
-        publicEncryptionKey?: string;
-    });
-    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;
-    }>): 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-browser/AvoInspectorEnv.d.ts

@@ -1,7 +0,0 @@
-export declare const AvoInspectorEnv: {
-    readonly Prod: "prod";
-    readonly Dev: "dev";
-    readonly Staging: "staging";
-};
-export type AvoInspectorEnvType = typeof AvoInspectorEnv;
-export type AvoInspectorEnvValueType = AvoInspectorEnvType[keyof AvoInspectorEnvType];

package/dist-browser/AvoNetworkCallsHandler.d.ts

@@ -1,74 +0,0 @@
-import type { EventSpecMetadata } from "./eventSpec/AvoEventSpecFetchTypes";
-import type { ValidationIssue } from "./eventSpec/EventValidator";
-export interface BaseBody {
-    apiKey: string;
-    appName: string;
-    appVersion: string;
-    libVersion: string;
-    env: string;
-    libPlatform: "web";
-    messageId: string;
-    trackingId: string;
-    createdAt: string;
-    sessionId: string;
-    anonymousId: string;
-    samplingRate: number;
-}
-export interface SessionStartedBody extends BaseBody {
-    type: "sessionStarted";
-}
-export interface EventSchemaBody extends BaseBody {
-    type: "event";
-    /** 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;
-    eventHash: string | null;
-}
-export declare class AvoNetworkCallsHandler {
-    private readonly apiKey;
-    private readonly envName;
-    private readonly appName;
-    private readonly appVersion;
-    private readonly libVersion;
-    private samplingRate;
-    private sending;
-    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;
-    bodyForSessionStartedCall(): SessionStartedBody;
-    bodyForEventSchemaCall(eventName: string, eventProperties: Array<{
-        propertyName: string;
-        propertyType: string;
-        children?: any;
-    }>, eventId: string | null, eventHash: string | null, variantId?: string | null, eventSpecMetadata?: EventSpecMetadata, validationErrors?: ValidationIssue[]): EventSchemaBody;
-    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-browser/AvoSchemaParser.d.ts

@@ -1,20 +0,0 @@
-export declare class AvoSchemaParser {
-    /**
-     * 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;
-    private static getPropValueType;
-}

package/dist-browser/AvoStorage.d.ts

@@ -1,22 +0,0 @@
-declare abstract class PlatformAvoStorage {
-    abstract init(shouldLog: boolean, suffix: string): void;
-    abstract getItemAsync<T>(key: string): Promise<T | null>;
-    abstract getItem<T>(key: string): T | null;
-    abstract setItem<T>(key: string, value: T): void;
-    abstract removeItem(key: string): void;
-    abstract runAfterInit(func: () => void): void;
-    abstract isInitialized(): boolean;
-    parseJson<T>(maybeItem: string | null | undefined): T | null;
-}
-export declare class AvoStorage {
-    Platform: string | null;
-    storageImpl: PlatformAvoStorage;
-    constructor(shouldLog: boolean, suffix?: string);
-    isInitialized(): boolean;
-    getItemAsync<T>(key: string): Promise<T | null>;
-    getItem<T>(key: string): T | null;
-    setItem<T>(key: string, value: T): void;
-    removeItem(key: string): void;
-    runAfterInit(func: () => void): void;
-}
-export {};

package/dist-browser/__mocks__/xhr.d.ts

@@ -1,12 +0,0 @@
-/// <reference types="jest" />
-declare const xhrMock: {
-    open: jest.Mock<any, any, any>;
-    send: jest.Mock<any, any, any>;
-    setRequestHeader: jest.Mock<any, any, any>;
-    onload: jest.Mock<any, any, any>;
-    onerror: jest.Mock<any, any, any>;
-    ontimeout: jest.Mock<any, any, any>;
-    status: number;
-    response: string;
-};
-export default xhrMock;

package/dist-browser/__mocks__/xhrError.d.ts

@@ -1,12 +0,0 @@
-/// <reference types="jest" />
-declare const xhrErrorMock: {
-    open: jest.Mock<any, any, any>;
-    send: jest.Mock<any, any, any>;
-    setRequestHeader: jest.Mock<any, any, any>;
-    onload: jest.Mock<any, any, any>;
-    onerror: jest.Mock<any, any, any>;
-    ontimeout: jest.Mock<any, any, any>;
-    status: number;
-    statusText: string;
-};
-export default xhrErrorMock;

package/dist-browser/__tests__/AnonymousId_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/AvoEncryption_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/AvoInspectorEventSpec_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/AvoInspector_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/BatcherPublic_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/Batcher_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/Deduplicator_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/EncryptedPropertyTracking_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/EventSpecCache_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/EventSpecFetcher_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/EventValidator_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/NetworkCallsHandler_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/Parsing_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/Storage_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/ValidationIntegration_test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist-browser/__tests__/constants.d.ts

@@ -1,36 +0,0 @@
-declare const defaultOptions: {
-    apiKey: string;
-    env: "prod";
-    version: string;
-    shouldLog: boolean;
-};
-declare const error: {
-    API_KEY: string;
-    VERSION: string;
-};
-declare const mockedReturns: {
-    INSTALLATION_ID: string;
-    GUID: string;
-    SESSION_ID: string;
-};
-declare const networkCallType: {
-    EVENT: string;
-    SESSION_STARTED: string;
-};
-declare const requestMsg: {
-    ERROR: string;
-    TIMEOUT: string;
-};
-declare const trackingEndpoint = "https://api.avo.app/inspector/v1/track";
-declare const sessionTimeMs: number;
-declare const type: {
-    STRING: string;
-    INT: string;
-    OBJECT: string;
-    FLOAT: string;
-    LIST: string;
-    BOOL: string;
-    NULL: string;
-    UNKNOWN: string;
-};
-export { defaultOptions, error, mockedReturns, networkCallType, requestMsg, sessionTimeMs, type, trackingEndpoint };

package/dist-browser/__tests__/helpers/encryptionHelpers.d.ts

@@ -1,13 +0,0 @@
-/**
- * Test helper: Generates a new ECC key pair for testing encryption.
- * This is also available in the CLI tool (bin/avo-inspector.js) for production use.
- */
-export declare function generateKeyPair(): {
-    publicKey: string;
-    privateKey: string;
-};
-/**
- * Test helper: Decrypts a value that was encrypted using encryptValue.
- * Used for testing purposes only.
- */
-export declare function decryptValue(encryptedValue: string, privateKey: string): any;

package/dist-browser/__tests__/helpers/mockFactories.d.ts

@@ -1,49 +0,0 @@
-/**
- * Shared mock factories for testing event spec related functionality.
- * These helpers reduce duplication across test files.
- */
-import type { PropertySpec, PropertyTypeSpec, VariantSpec, EventSpec, EventSpecResponse, EventSpecMetadata } from "../../eventSpec/AvoEventSpecFetchTypes";
-/**
- * Creates a PropertyTypeSpec with defaults.
- */
-export declare function createPropertyTypeSpec(overrides?: Partial<PropertyTypeSpec>): PropertyTypeSpec;
-/**
- * Creates a PropertySpec with sensible defaults.
- */
-export declare function createPropertySpec(overrides?: Partial<PropertySpec>): PropertySpec;
-/**
- * Creates a required string property.
- */
-export declare function createRequiredStringProperty(id: string, extraOverrides?: Partial<PropertySpec>): PropertySpec;
-/**
- * Creates an optional number property.
- */
-export declare function createNumberProperty(id: string, extraOverrides?: Partial<PropertySpec>): PropertySpec;
-/**
- * Creates an enum property with allowed values.
- */
-export declare function createEnumProperty(id: string, allowedValues: string[], extraOverrides?: Partial<PropertySpec>): PropertySpec;
-/**
- * Creates a VariantSpec with defaults.
- */
-export declare function createVariantSpec(overrides?: Partial<VariantSpec>): VariantSpec;
-/**
- * Creates an EventSpec with defaults.
- */
-export declare function createEventSpec(overrides?: Partial<EventSpec>): EventSpec;
-/**
- * Creates an EventSpec with common properties for testing.
- */
-export declare function createUserLoginEventSpec(): EventSpec;
-/**
- * Creates EventSpecMetadata with defaults.
- */
-export declare function createEventSpecMetadata(overrides?: Partial<EventSpecMetadata>): EventSpecMetadata;
-/**
- * Creates an EventSpecResponse with defaults.
- */
-export declare function createEventSpecResponse(events?: EventSpec[], metadataOverrides?: Partial<EventSpecMetadata>): EventSpecResponse;
-/**
- * Creates a simple EventSpecResponse with one event for basic testing.
- */
-export declare function createSimpleEventSpecResponse(eventName?: string): EventSpecResponse;

package/dist-browser/eventSpec/AvoEventSpecCache.d.ts

@@ -1,73 +0,0 @@
-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;
-        }>;
-    };
-}