node-avo-inspector 1.1.0 → 1.2.0-alpha.1

package/.github/workflows/claude.yml

@@ -0,0 +1,55 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+  issues:
+    types: [opened, assigned]
+
+jobs:
+  claude:
+    if: |
+      (
+        github.event_name == 'issue_comment' &&
+        contains(github.event.comment.body || '', '@claude') &&
+        contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
+      ) ||
+      (
+        github.event_name == 'pull_request_review_comment' &&
+        contains(github.event.comment.body || '', '@claude') &&
+        contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
+      ) ||
+      (
+        github.event_name == 'pull_request_review' &&
+        contains(github.event.review.body || '', '@claude') &&
+        contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.review.author_association)
+      ) ||
+      (
+        github.event_name == 'issues' &&
+        contains(github.event.issue.body || '', '@claude') &&
+        contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.issue.author_association)
+      )
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        uses: anthropics/claude-code-action@673eb13aa77026be5c507eda12322c1a58b80f0b # v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          plugin_marketplaces: |
+            https://github.com/anthropics/claude-code.git
+          plugins: |
+            code-review@claude-code-plugins

package/dist/AvoDeduplicator.d.ts

@@ -7,18 +7,19 @@ export declare class AvoDeduplicator {
     };
     private msToConsiderOld;
     avoFunctionsEventsParams: {
-        [eventName: string]: {
+        [key: string]: {
             [propName: string]: any;
         };
     };
     manualEventsParams: {
-        [eventName: string]: {
+        [key: string]: {
             [propName: string]: any;
         };
     };
+    private static dedupKey;
     shouldRegisterEvent(eventName: string, params: {
         [propName: string]: any;
-    }, fromAvoFunction: boolean): boolean;
+    }, fromAvoFunction: boolean, streamId?: string): boolean;
     private hasSameEventAs;
     private lookForEventIn;
     hasSeenEventParams(params: {

package/dist/AvoDeduplicator.js

@@ -7,49 +7,50 @@ class AvoDeduplicator {
         this.avoFunctionsEvents = {};
         this.manualEvents = {};
         this.msToConsiderOld = 500;
+        // Keyed by streamId\0eventName to prevent cross-stream suppression on server
         this.avoFunctionsEventsParams = {};
         this.manualEventsParams = {};
     }
-    shouldRegisterEvent(eventName, params, fromAvoFunction) {
+    static dedupKey(eventName, streamId) {
+        return streamId + "\0" + eventName;
+    }
+    shouldRegisterEvent(eventName, params, fromAvoFunction, streamId = "") {
         this.clearOldEvents();
+        const key = AvoDeduplicator.dedupKey(eventName, streamId);
         if (fromAvoFunction) {
-            this.avoFunctionsEvents[Date.now()] = eventName;
-            this.avoFunctionsEventsParams[eventName] = params;
+            this.avoFunctionsEvents[Date.now()] = key;
+            this.avoFunctionsEventsParams[key] = params;
         }
         else {
-            this.manualEvents[Date.now()] = eventName;
-            this.manualEventsParams[eventName] = params;
+            this.manualEvents[Date.now()] = key;
+            this.manualEventsParams[key] = params;
         }
         let checkInAvoFunctions = !fromAvoFunction;
-        return !this.hasSameEventAs(eventName, params, checkInAvoFunctions);
+        return !this.hasSameEventAs(key, params, checkInAvoFunctions);
     }
-    hasSameEventAs(eventName, params, checkInAvoFunctions) {
+    hasSameEventAs(key, params, checkInAvoFunctions) {
         let result = false;
         if (checkInAvoFunctions) {
-            if (this.lookForEventIn(eventName, params, this.avoFunctionsEventsParams)) {
+            if (this.lookForEventIn(key, params, this.avoFunctionsEventsParams)) {
                 result = true;
             }
         }
         else {
-            if (this.lookForEventIn(eventName, params, this.manualEventsParams)) {
+            if (this.lookForEventIn(key, params, this.manualEventsParams)) {
                 result = true;
             }
         }
         if (result) {
-            delete this.avoFunctionsEventsParams[eventName];
-            delete this.manualEventsParams[eventName];
+            delete this.avoFunctionsEventsParams[key];
+            delete this.manualEventsParams[key];
         }
         return result;
     }
-    lookForEventIn(eventName, params, eventsStorage) {
-        for (const otherEventName in eventsStorage) {
-            if (eventsStorage.hasOwnProperty(otherEventName)) {
-                if (otherEventName === eventName) {
-                    const otherParams = eventsStorage[eventName];
-                    if (otherParams && (0, utils_1.deepEquals)(params, otherParams)) {
-                        return true;
-                    }
-                }
+    lookForEventIn(key, params, eventsStorage) {
+        if (eventsStorage.hasOwnProperty(key)) {
+            const otherParams = eventsStorage[key];
+            if (otherParams && (0, utils_1.deepEquals)(params, otherParams)) {
+                return true;
             }
         }
         return false;
@@ -85,9 +86,9 @@ class AvoDeduplicator {
             if (this.avoFunctionsEvents.hasOwnProperty(time)) {
                 const timestamp = Number(time) || 0;
                 if (now - timestamp > this.msToConsiderOld) {
-                    const eventName = this.avoFunctionsEvents[time];
+                    const key = this.avoFunctionsEvents[time];
                     delete this.avoFunctionsEvents[time];
-                    delete this.avoFunctionsEventsParams[eventName];
+                    delete this.avoFunctionsEventsParams[key];
                 }
             }
         }
@@ -95,9 +96,9 @@ class AvoDeduplicator {
             if (this.manualEvents.hasOwnProperty(time)) {
                 const timestamp = Number(time) || 0;
                 if (now - timestamp > this.msToConsiderOld) {
-                    const eventName = this.manualEvents[time];
+                    const key = this.manualEvents[time];
                     delete this.manualEvents[time];
-                    delete this.manualEventsParams[eventName];
+                    delete this.manualEventsParams[key];
                 }
             }
         }

package/dist/AvoEncryption.d.ts

@@ -0,0 +1,26 @@
+export declare class AvoEncryption {
+    /**
+     * Determines whether encryption should be applied.
+     *
+     * Truth table:
+     *   dev + key    => true
+     *   staging + key => true
+     *   prod + key   => false
+     *   dev + null   => false
+     *   dev + ""     => false
+     */
+    static shouldEncrypt(env: string, publicEncryptionKey: string | undefined | null): boolean;
+    /**
+     * Returns true if the propertyType represents a list type (e.g. "list(string)").
+     */
+    static isListType(propertyType: string): boolean;
+    /**
+     * Encrypts a string value using ECIES with prime256v1.
+     *
+     * Wire format: [0x00][65-byte ephemeral pubkey][16-byte IV][16-byte auth tag][ciphertext]
+     * Output is base64-encoded.
+     *
+     * Returns null on failure, logging a warning.
+     */
+    static encryptValue(value: string, recipientPubKeyHex: string): string | null;
+}

package/dist/AvoEncryption.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AvoEncryption = void 0;
+const crypto = require("crypto");
+class AvoEncryption {
+    /**
+     * Determines whether encryption should be applied.
+     *
+     * Truth table:
+     *   dev + key    => true
+     *   staging + key => true
+     *   prod + key   => false
+     *   dev + null   => false
+     *   dev + ""     => false
+     */
+    static shouldEncrypt(env, publicEncryptionKey) {
+        if (!publicEncryptionKey || publicEncryptionKey.length === 0) {
+            return false;
+        }
+        if (env === "prod") {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Returns true if the propertyType represents a list type (e.g. "list(string)").
+     */
+    static isListType(propertyType) {
+        return propertyType.startsWith("list(");
+    }
+    /**
+     * Encrypts a string value using ECIES with prime256v1.
+     *
+     * Wire format: [0x00][65-byte ephemeral pubkey][16-byte IV][16-byte auth tag][ciphertext]
+     * Output is base64-encoded.
+     *
+     * Returns null on failure, logging a warning.
+     */
+    static encryptValue(value, recipientPubKeyHex) {
+        try {
+            const recipientPubKey = Buffer.from(recipientPubKeyHex, "hex");
+            // Generate ephemeral key pair
+            const ecdh = crypto.createECDH("prime256v1");
+            ecdh.generateKeys();
+            const ephemeralPubKey = ecdh.getPublicKey(); // 65 bytes, uncompressed
+            // Compute shared secret (raw 32-byte X-coordinate)
+            const sharedSecret = ecdh.computeSecret(recipientPubKey);
+            // Derive AES key via SHA-256
+            const aesKey = crypto.createHash("sha256").update(sharedSecret).digest();
+            // Generate random 16-byte IV
+            const iv = crypto.randomBytes(16);
+            // Encrypt with AES-256-GCM
+            const cipher = crypto.createCipheriv("aes-256-gcm", aesKey, iv, {
+                authTagLength: 16,
+            });
+            const encrypted = Buffer.concat([
+                cipher.update(value, "utf8"),
+                cipher.final(),
+            ]);
+            const authTag = cipher.getAuthTag(); // 16 bytes
+            // Assemble wire format: [version][ephemeralPubKey][IV][authTag][ciphertext]
+            const wire = Buffer.concat([
+                Buffer.from([0x00]), // version byte
+                ephemeralPubKey, // 65 bytes
+                iv, // 16 bytes
+                authTag, // 16 bytes
+                encrypted, // variable length
+            ]);
+            return wire.toString("base64");
+        }
+        catch (e) {
+            console.warn(`[Avo Inspector] Warning: encryption failed for value, omitting property. ${e}`);
+            return null;
+        }
+    }
+}
+exports.AvoEncryption = AvoEncryption;

package/dist/AvoInspector.d.ts

@@ -7,6 +7,14 @@ export declare class AvoInspector {
     avoDeduplicator: AvoDeduplicator;
     apiKey: string;
     version: string;
+    private publicEncryptionKey?;
+    private eventSpecFetcher;
+    private eventSpecCache;
+    private eventValidator;
+    private generatedAnonymousId;
+    private pendingCount;
+    private keepAliveTimer;
+    private trackPending;
     private static _shouldLog;
     static get shouldLog(): boolean;
     static set shouldLog(enable: boolean);
@@ -15,16 +23,33 @@ export declare class AvoInspector {
         env: AvoInspectorEnvValueType;
         version: string;
         appName?: string;
+        publicEncryptionKey?: string;
     });
     trackSchemaFromEvent(eventName: string, eventProperties: {
         [propName: string]: any;
-    }): Promise<Array<{
+    }, streamId?: string): Promise<Array<{
         propertyName: string;
         propertyType: string;
         children?: any;
     }>>;
-    private _avoFunctionTrackSchemaFromEvent;
-    private trackSchemaInternal;
+    _avoFunctionTrackSchemaFromEvent(eventName: string, eventProperties: {
+        [propName: string]: any;
+    }, eventId: string, eventHash: string, streamId?: string): Promise<Array<{
+        propertyName: string;
+        propertyType: string;
+        children?: any;
+    }>>;
+    /**
+     * Try to fetch event spec and validate, then send a single event call.
+     * If validation succeeds, sends a validated event (with results merged in).
+     * If unavailable, sends a plain event.
+     *
+     * Uses trackPending() to keep the Node process alive until the work completes,
+     * so short-lived processes (CLIs) don't exit before the send finishes — even
+     * when the caller doesn't await the returned promise.
+     */
+    private sendEventWithOptionalValidation;
+    private doSendEventWithOptionalValidation;
     enableLogging(enable: boolean): void;
     extractSchema(eventProperties: {
         [propName: string]: any;
@@ -33,4 +58,10 @@ export declare class AvoInspector {
         propertyType: string;
         children?: any;
     }>;
+    /**
+     * Fetch event spec and validate. Returns validation results + metadata if
+     * validation succeeds, or null if unavailable (prod, no spec, fetch error).
+     */
+    private fetchAndValidate;
+    destroy(): void;
 }

package/dist/AvoInspector.js

@@ -1,14 +1,40 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AvoInspector = void 0;
 const AvoInspectorEnv_1 = require("./AvoInspectorEnv");
 const AvoSchemaParser_1 = require("./AvoSchemaParser");
 const AvoNetworkCallsHandler_1 = require("./AvoNetworkCallsHandler");
 const AvoDeduplicator_1 = require("./AvoDeduplicator");
+const AvoStreamId_1 = require("./AvoStreamId");
+const AvoEventSpecFetcher_1 = require("./eventSpec/AvoEventSpecFetcher");
+const AvoEventSpecCache_1 = require("./eventSpec/AvoEventSpecCache");
+const EventValidator_1 = require("./eventSpec/EventValidator");
 const utils_1 = require("./utils");
-const AvoGuid_1 = require("./AvoGuid");
 const libVersion = require("../package.json").version;
 class AvoInspector {
+    trackPending(promise) {
+        this.pendingCount++;
+        if (this.keepAliveTimer === null) {
+            this.keepAliveTimer = setInterval(() => { }, 60000);
+        }
+        const done = () => {
+            this.pendingCount--;
+            if (this.pendingCount === 0 && this.keepAliveTimer !== null) {
+                clearInterval(this.keepAliveTimer);
+                this.keepAliveTimer = null;
+            }
+        };
+        promise.then(done, done);
+    }
     static get shouldLog() {
         return this._shouldLog;
     }
@@ -16,6 +42,15 @@ class AvoInspector {
         this._shouldLog = enable;
     }
     constructor(options) {
+        this.eventSpecFetcher = null;
+        this.eventSpecCache = null;
+        this.eventValidator = null;
+        this.generatedAnonymousId = "";
+        // Keep the Node process alive while there are pending inspector operations.
+        // Without this, short-lived processes (e.g. CLIs) can exit before async
+        // sends complete, since the caller typically doesn't await the inspector promise.
+        this.pendingCount = 0;
+        this.keepAliveTimer = null;
         // the constructor does aggressive null/undefined checking because same code paths will be accessible from JS
         if ((0, utils_1.isValueEmpty)(options.env)) {
             this.environment = AvoInspectorEnv_1.AvoInspectorEnv.Dev;
@@ -40,32 +75,51 @@ class AvoInspector {
         else {
             this.version = options.version;
         }
+        this.publicEncryptionKey = options.publicEncryptionKey;
+        if (this.publicEncryptionKey &&
+            this.environment !== AvoInspectorEnv_1.AvoInspectorEnv.Prod) {
+            const hexPattern = /^[0-9a-fA-F]+$/;
+            const len = this.publicEncryptionKey.length;
+            // Accept both compressed (66 hex chars, prefix 02/03) and uncompressed (130 hex chars, prefix 04) P-256 keys
+            const isValidLength = len === 66 || len === 130;
+            if (!hexPattern.test(this.publicEncryptionKey) || !isValidLength) {
+                console.warn("[Avo Inspector] Warning: publicEncryptionKey does not look like a valid P-256 public key (expected 66 or 130 hex characters). Encryption may fail.");
+            }
+        }
         if (this.environment === AvoInspectorEnv_1.AvoInspectorEnv.Dev) {
             AvoInspector._shouldLog = true;
         }
         else {
             AvoInspector._shouldLog = false;
         }
-        this.avoNetworkCallsHandler = new AvoNetworkCallsHandler_1.AvoNetworkCallsHandler(this.apiKey, this.environment.toString(), options.appName || "", this.version, libVersion);
+        this.avoNetworkCallsHandler = new AvoNetworkCallsHandler_1.AvoNetworkCallsHandler(this.apiKey, this.environment.toString(), options.appName || "", this.version, libVersion, this.publicEncryptionKey);
         this.avoDeduplicator = new AvoDeduplicator_1.AvoDeduplicator();
+        // Initialize event spec validation for dev/staging only
+        if (this.environment !== AvoInspectorEnv_1.AvoInspectorEnv.Prod) {
+            this.eventSpecFetcher = new AvoEventSpecFetcher_1.AvoEventSpecFetcher(this.apiKey);
+            this.eventSpecCache = new AvoEventSpecCache_1.AvoEventSpecCache();
+            this.eventValidator = new EventValidator_1.EventValidator();
+        }
     }
-    trackSchemaFromEvent(eventName, eventProperties) {
+    trackSchemaFromEvent(eventName, eventProperties, streamId) {
         try {
-            if (this.avoDeduplicator.shouldRegisterEvent(eventName, eventProperties, false)) {
+            const avoStreamId = new AvoStreamId_1.AvoStreamId(streamId);
+            const anonymousId = avoStreamId.streamId || this.generatedAnonymousId;
+            if (this.avoDeduplicator.shouldRegisterEvent(eventName, eventProperties, false, anonymousId)) {
                 if (AvoInspector.shouldLog) {
-                    console.log("Avo Inspector: supplied event " +
+                    console.log("Avo Inspector: Supplied event " +
                         eventName +
-                        " with params " +
+                        " with params \n" +
                         JSON.stringify(eventProperties));
                 }
                 let eventSchema = this.extractSchema(eventProperties, false);
-                return this.trackSchemaInternal(eventName, eventSchema, null, null).then(() => {
+                return this.sendEventWithOptionalValidation(eventName, eventSchema, null, null, anonymousId, eventProperties).then(() => {
                     return eventSchema;
                 });
             }
             else {
                 if (AvoInspector.shouldLog) {
-                    console.log("Avo Inspector: Deduplicated event: " + eventName);
+                    console.log("Avo Inspector: Deduplicated event " + eventName);
                 }
                 return Promise.resolve([]);
             }
@@ -75,23 +129,24 @@ class AvoInspector {
             return Promise.reject("Avo Inspector: something went wrong. Please report to support@avo.app.");
         }
     }
-    _avoFunctionTrackSchemaFromEvent(eventName, eventProperties, eventId, eventHash) {
+    _avoFunctionTrackSchemaFromEvent(eventName, eventProperties, eventId, eventHash, streamId) {
         try {
-            if (this.avoDeduplicator.shouldRegisterEvent(eventName, eventProperties, true)) {
+            const anonymousId = (streamId && streamId.length > 0) ? streamId : this.generatedAnonymousId;
+            if (this.avoDeduplicator.shouldRegisterEvent(eventName, eventProperties, true, anonymousId)) {
                 if (AvoInspector.shouldLog) {
-                    console.log("Avo Inspector: supplied event " +
+                    console.log("Avo Inspector: Supplied event " +
                         eventName +
-                        " with params " +
+                        " with params \n" +
                         JSON.stringify(eventProperties));
                 }
                 let eventSchema = this.extractSchema(eventProperties, false);
-                return this.trackSchemaInternal(eventName, eventSchema, eventId, eventHash).then(() => {
+                return this.sendEventWithOptionalValidation(eventName, eventSchema, eventId, eventHash, anonymousId, eventProperties).then(() => {
                     return eventSchema;
                 });
             }
             else {
                 if (AvoInspector.shouldLog) {
-                    console.log("Avo Inspector: Deduplicated event: " + eventName);
+                    console.log("Avo Inspector: Deduplicated event " + eventName);
                 }
                 return Promise.resolve([]);
             }
@@ -101,35 +156,45 @@ class AvoInspector {
             return Promise.reject("Avo Inspector: something went wrong. Please report to support@avo.app.");
         }
     }
-    trackSchemaInternal(eventName, eventSchema, eventId, eventHash) {
-        try {
-            const seesionId = AvoGuid_1.AvoGuid.newGuid();
-            return this.avoNetworkCallsHandler
-                .callInspectorWithBatchBody([
-                this.avoNetworkCallsHandler.bodyForSessionStartedCall(seesionId),
-            ])
-                .then(() => {
-                if (AvoInspector.shouldLog) {
-                    console.log("Avo Inspector: session started sent successfully.");
-                }
-                this.avoNetworkCallsHandler.callInspectorWithBatchBody([
-                    this.avoNetworkCallsHandler.bodyForEventSchemaCall(seesionId, eventName, eventSchema, eventId, eventHash),
-                ]).then(() => {
+    /**
+     * Try to fetch event spec and validate, then send a single event call.
+     * If validation succeeds, sends a validated event (with results merged in).
+     * If unavailable, sends a plain event.
+     *
+     * Uses trackPending() to keep the Node process alive until the work completes,
+     * so short-lived processes (CLIs) don't exit before the send finishes — even
+     * when the caller doesn't await the returned promise.
+     */
+    sendEventWithOptionalValidation(eventName, eventSchema, eventId, eventHash, anonymousId, rawEventProperties) {
+        const work = this.doSendEventWithOptionalValidation(eventName, eventSchema, eventId, eventHash, anonymousId, rawEventProperties);
+        this.trackPending(work);
+        return work;
+    }
+    doSendEventWithOptionalValidation(eventName, eventSchema, eventId, eventHash, anonymousId, rawEventProperties) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const validationResult = yield this.fetchAndValidate(eventName, eventSchema, anonymousId, rawEventProperties, eventId);
+            try {
+                let body;
+                if (validationResult) {
                     if (AvoInspector.shouldLog) {
-                        console.log("Avo Inspector: schema sent successfully.");
+                        console.log("Avo Inspector: Sending validated event " + eventName);
                     }
-                });
-            })
-                .catch((err) => {
+                    const eventProps = this.avoNetworkCallsHandler.buildEventProperties(eventSchema, rawEventProperties);
+                    body = this.avoNetworkCallsHandler.bodyForValidatedEventSchemaCall(anonymousId, eventName, eventProps, eventId, eventHash, validationResult.metadata, validationResult.propertyResults);
+                }
+                else {
+                    body = this.avoNetworkCallsHandler.bodyForEventSchemaCall(anonymousId, eventName, eventSchema, eventId, eventHash, rawEventProperties);
+                }
+                yield this.avoNetworkCallsHandler.callInspectorWithBatchBody([body]);
                 if (AvoInspector.shouldLog) {
-                    console.log("Avo Inspector: schema sending failed: " + err + ".");
+                    const schemaString = eventSchema.map(p => '\t"' + p.propertyName + '": "' + p.propertyType + '"').join(";\n");
+                    console.log("Avo Inspector: Saved event " + eventName + " with schema {\n" + schemaString + "\n}");
                 }
-            });
-        }
-        catch (e) {
-            console.error("Avo Inspector: something went wrong. Please report to support@avo.app.", e);
-            return Promise.reject();
-        }
+            }
+            catch (err) {
+                console.error("Avo Inspector: schema sending failed: " + err + ".");
+            }
+        });
     }
     enableLogging(enable) {
         AvoInspector._shouldLog = enable;
@@ -147,13 +212,104 @@ class AvoInspector {
                 console.log("Avo Inspector: extracting schema from " +
                     JSON.stringify(eventProperties));
             }
-            return AvoSchemaParser_1.AvoSchemaParser.extractSchema(eventProperties);
+            const schema = AvoSchemaParser_1.AvoSchemaParser.extractSchema(eventProperties);
+            if (AvoInspector.shouldLog) {
+                const schemaString = schema.map(p => '\t"' + p.propertyName + '": "' + p.propertyType + '"').join(";\n");
+                console.log("Avo Inspector: Parsed schema {\n" + schemaString + "\n}");
+            }
+            return schema;
         }
         catch (e) {
             console.error("Avo Inspector: something went wrong. Please report to support@avo.app.", e);
             return [];
         }
     }
+    /**
+     * Fetch event spec and validate. Returns validation results + metadata if
+     * validation succeeds, or null if unavailable (prod, no spec, fetch error).
+     */
+    fetchAndValidate(eventName, eventSchema, anonymousId, rawEventProperties, eventId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.eventSpecFetcher || !this.eventSpecCache || !this.eventValidator) {
+                if (AvoInspector.shouldLog) {
+                    console.log("Avo Inspector: Skipping event spec validation for event: " + eventName
+                        + " (fetcher=" + (this.eventSpecFetcher != null)
+                        + ", cache=" + (this.eventSpecCache != null)
+                        + ", env=" + this.environment + ")");
+                }
+                return null;
+            }
+            const cacheKey = AvoEventSpecCache_1.AvoEventSpecCache.makeKey(this.apiKey, anonymousId, eventName);
+            const cache = this.eventSpecCache;
+            const validator = this.eventValidator;
+            const doValidate = (specResponse) => {
+                if (specResponse.eventSpec === null) {
+                    if (AvoInspector.shouldLog) {
+                        console.log("Avo Inspector: Event spec fetch returned null for event: " + eventName + ". Sending without validation.");
+                    }
+                    return null;
+                }
+                const eventProperties = eventSchema.map((prop) => (Object.assign({ propertyName: prop.propertyName, propertyType: prop.propertyType }, (rawEventProperties && rawEventProperties[prop.propertyName] !== undefined
+                    ? { propertyValue: String(rawEventProperties[prop.propertyName]) }
+                    : {}))));
+                if (AvoInspector.shouldLog) {
+                    console.log("Avo Inspector: Validating event: " + eventName
+                        + " with " + eventProperties.length + " properties"
+                        + " against " + specResponse.eventSpec.properties.length + " spec properties");
+                }
+                const validationId = eventId || eventName;
+                const results = validator.validate(specResponse.eventSpec, eventProperties, validationId);
+                if (AvoInspector.shouldLog) {
+                    console.log("Avo Inspector: Validation complete for event: " + eventName
+                        + " with " + results.length + " property results");
+                }
+                return { metadata: specResponse.metadata, propertyResults: results };
+            };
+            // Check cache first
+            const cached = cache.get(cacheKey);
+            if (cached !== undefined) {
+                if (AvoInspector.shouldLog) {
+                    console.log("Avo Inspector: Event spec cache hit for event: " + eventName);
+                }
+                return doValidate(cached);
+            }
+            // Cache miss — fetch spec (process stays alive via trackPending)
+            if (AvoInspector.shouldLog) {
+                console.log("Avo Inspector: Event spec cache miss for event: " + eventName + ". Fetching before sending.");
+            }
+            const fetcher = this.eventSpecFetcher;
+            return new Promise((resolve) => {
+                fetcher.fetch(eventName, anonymousId, (result) => {
+                    if (result !== null) {
+                        cache.set(cacheKey, result);
+                        resolve(doValidate(result));
+                    }
+                    else {
+                        if (AvoInspector.shouldLog) {
+                            console.log("Avo Inspector: Event spec fetch returned null for event: " + eventName + ". Cached empty response. Sending without validation.");
+                        }
+                        resolve(null);
+                    }
+                });
+            });
+        });
+    }
+    destroy() {
+        if (this.eventSpecFetcher) {
+            this.eventSpecFetcher.destroy();
+            this.eventSpecFetcher = null;
+        }
+        if (this.eventSpecCache) {
+            this.eventSpecCache.flush();
+            this.eventSpecCache = null;
+        }
+        this.eventValidator = null;
+        if (this.keepAliveTimer !== null) {
+            clearInterval(this.keepAliveTimer);
+            this.keepAliveTimer = null;
+        }
+        this.pendingCount = 0;
+    }
 }
 exports.AvoInspector = AvoInspector;
 AvoInspector._shouldLog = false;