node-avo-inspector 1.1.1 → 1.2.0

package/dist/__tests__/TestEventValidator.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const EventValidator_1 = require("../eventSpec/EventValidator");
+// We need to mock safe-regex2 for some tests
+jest.mock("safe-regex2", () => {
+    const actual = jest.requireActual("safe-regex2");
+    return {
+        __esModule: true,
+        default: actual.default || actual,
+        _mockable: true,
+    };
+});
+describe("EventValidator", () => {
+    let validator;
+    beforeEach(() => {
+        validator = new EventValidator_1.EventValidator();
+        jest.spyOn(console, "warn").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+    describe("type validation", () => {
+        test("passes when property types match spec", () => {
+            const spec = {
+                eventName: "click",
+                properties: [
+                    { propertyName: "target", propertyType: "string" },
+                    { propertyName: "count", propertyType: "int" },
+                ],
+            };
+            const eventProperties = [
+                { propertyName: "target", propertyType: "string" },
+                { propertyName: "count", propertyType: "int" },
+            ];
+            const results = validator.validate(spec, eventProperties, "evt-1");
+            // All properties passed type check, so failedEventIds should be empty
+            expect(results.every((r) => r.failedEventIds.length === 0)).toBe(true);
+            // Bandwidth optimization: passedEventIds cleared because passed >= failed for each property
+            expect(results.every((r) => r.passedEventIds.length === 0)).toBe(true);
+        });
+        test("fails when property type does not match spec", () => {
+            const spec = {
+                eventName: "click",
+                properties: [{ propertyName: "count", propertyType: "int" }],
+            };
+            const eventProperties = [
+                { propertyName: "count", propertyType: "string" },
+            ];
+            const results = validator.validate(spec, eventProperties, "evt-2");
+            const countResult = results.find((r) => r.propertyName === "count");
+            expect(countResult === null || countResult === void 0 ? void 0 : countResult.failedEventIds).toContain("evt-2");
+            expect(countResult === null || countResult === void 0 ? void 0 : countResult.passedEventIds).not.toContain("evt-2");
+        });
+        test("fails for missing required properties", () => {
+            const spec = {
+                eventName: "click",
+                properties: [
+                    { propertyName: "target", propertyType: "string" },
+                    { propertyName: "count", propertyType: "int" },
+                ],
+            };
+            const eventProperties = [
+                { propertyName: "target", propertyType: "string" },
+                // count is missing
+            ];
+            const results = validator.validate(spec, eventProperties, "evt-3");
+            const countResult = results.find((r) => r.propertyName === "count");
+            expect(countResult === null || countResult === void 0 ? void 0 : countResult.failedEventIds).toContain("evt-3");
+        });
+    });
+    describe("regex validation", () => {
+        test("passes when value matches safe regex pattern (type match)", () => {
+            const spec = {
+                eventName: "navigate",
+                properties: [
+                    {
+                        propertyName: "url",
+                        propertyType: "string",
+                        regex: "^https://",
+                    },
+                ],
+            };
+            const eventProperties = [
+                { propertyName: "url", propertyType: "string", propertyValue: "https://example.com" },
+            ];
+            const results = validator.validate(spec, eventProperties, "evt-4");
+            const urlResult = results.find((r) => r.propertyName === "url");
+            // Type matches and regex matches, property passed. Bandwidth optimization: passedEventIds cleared
+            // because passed count (1) >= failed count (0)
+            expect(urlResult === null || urlResult === void 0 ? void 0 : urlResult.failedEventIds).toEqual([]);
+        });
+        test("fails when value does not match safe regex pattern", () => {
+            const spec = {
+                eventName: "navigate",
+                properties: [
+                    {
+                        propertyName: "url",
+                        propertyType: "string",
+                        regex: "^https://",
+                    },
+                ],
+            };
+            const eventProperties = [
+                { propertyName: "url", propertyType: "string", propertyValue: "http://example.com" },
+            ];
+            const results = validator.validate(spec, eventProperties, "evt-regex-fail");
+            const urlResult = results.find((r) => r.propertyName === "url");
+            expect(urlResult === null || urlResult === void 0 ? void 0 : urlResult.failedEventIds).toContain("evt-regex-fail");
+            expect(urlResult === null || urlResult === void 0 ? void 0 : urlResult.passedEventIds).not.toContain("evt-regex-fail");
+        });
+        test("logs warning and passes type check when regex syntax is invalid", () => {
+            const spec = {
+                eventName: "filter",
+                properties: [
+                    {
+                        propertyName: "pattern",
+                        propertyType: "string",
+                        regex: "[invalid",
+                    },
+                ],
+            };
+            const eventProperties = [
+                { propertyName: "pattern", propertyType: "string", propertyValue: "anything" },
+            ];
+            const results = validator.validate(spec, eventProperties, "evt-bad-regex");
+            const patternResult = results.find((r) => r.propertyName === "pattern");
+            // Invalid regex is caught, property still passes type check
+            expect(patternResult === null || patternResult === void 0 ? void 0 : patternResult.failedEventIds).toEqual([]);
+            expect(console.warn).toHaveBeenCalledWith(expect.stringContaining("[Avo Inspector] Warning"));
+        });
+        test("skips unsafe regex patterns with warning", () => {
+            const spec = {
+                eventName: "search",
+                properties: [
+                    {
+                        propertyName: "query",
+                        propertyType: "string",
+                        // Catastrophic backtracking pattern
+                        regex: "(a+)+$",
+                    },
+                ],
+            };
+            const eventProperties = [
+                { propertyName: "query", propertyType: "string", propertyValue: "aaa" },
+            ];
+            const results = validator.validate(spec, eventProperties, "evt-5");
+            // Unsafe regex should be skipped, property still passes type check
+            const queryResult = results.find((r) => r.propertyName === "query");
+            // Bandwidth optimization: passedEventIds cleared because passed count >= failed count
+            expect(queryResult === null || queryResult === void 0 ? void 0 : queryResult.failedEventIds).toEqual([]);
+            expect(console.warn).toHaveBeenCalledWith(expect.stringContaining("[Avo Inspector] Warning"));
+        });
+    });
+    describe("extra/unexpected properties", () => {
+        test("ignores properties present in event but not in the spec", () => {
+            const spec = {
+                eventName: "click",
+                properties: [
+                    { propertyName: "target", propertyType: "string" },
+                ],
+            };
+            const eventProperties = [
+                { propertyName: "target", propertyType: "string" },
+                { propertyName: "extraProp", propertyType: "int" },
+                { propertyName: "anotherExtra", propertyType: "boolean" },
+            ];
+            const results = validator.validate(spec, eventProperties, "evt-extra");
+            // Only spec properties get results — extra properties are not reported
+            expect(results).toHaveLength(1);
+            expect(results[0].propertyName).toBe("target");
+            expect(results.find((r) => r.propertyName === "extraProp")).toBeUndefined();
+            expect(results.find((r) => r.propertyName === "anotherExtra")).toBeUndefined();
+        });
+    });
+    describe("bandwidth optimization", () => {
+        test("returns passedEventIds only when strictly smaller than failedEventIds", () => {
+            const spec = {
+                eventName: "click",
+                properties: [{ propertyName: "target", propertyType: "string" }],
+            };
+            // Single pass
+            const passResults = validator.validate(spec, [{ propertyName: "target", propertyType: "string" }], "evt-pass");
+            const passResult = passResults.find((r) => r.propertyName === "target");
+            // When there's only passed and no failed, passedEventIds count (1) > failedEventIds count (0)
+            // So passedEventIds is NOT strictly smaller - it should be returned
+            // But the optimization says: return passedEventIds ONLY when strictly smaller than failedEventIds
+            // So when passedEventIds.length >= failedEventIds.length, we clear passedEventIds
+            expect(passResult === null || passResult === void 0 ? void 0 : passResult.passedEventIds).toEqual([]);
+            // Single fail
+            const failResults = validator.validate(spec, [{ propertyName: "target", propertyType: "int" }], "evt-fail");
+            const failResult = failResults.find((r) => r.propertyName === "target");
+            // failedEventIds has 1, passedEventIds has 0 -> passedEventIds is strictly smaller, return it
+            expect(failResult === null || failResult === void 0 ? void 0 : failResult.failedEventIds).toContain("evt-fail");
+        });
+    });
+});

package/dist/__tests__/TestNetworkCallsHandler.js

@@ -9,7 +9,6 @@ describe("NetworkCallsHandler", () => {
     const appName = "";
     let networkHandler;
     let baseBody;
-    const customCallback = jest.fn();
     const now = new Date();
     beforeAll(() => {
         // @ts-ignore
@@ -27,23 +26,20 @@ describe("NetworkCallsHandler", () => {
             libPlatform: "node",
             messageId: constants_1.mockedReturns.GUID,
             trackingId: "",
+            sessionId: "",
+            anonymousId: "",
             createdAt: new Date().toISOString(),
-            sessionId: constants_1.mockedReturns.SESSION_ID,
             samplingRate: 1.0,
         };
     });
     afterEach(() => {
         jest.clearAllMocks();
     });
-    test("bodyForSessionStartedCall returns base body + session started body used for session started", () => {
-        const body = networkHandler.bodyForSessionStartedCall(constants_1.mockedReturns.SESSION_ID);
-        expect(body).toEqual(Object.assign(Object.assign({}, baseBody), { type: "sessionStarted" }));
-    });
     test("bodyForEventSchemaCall returns base body + event schema used for event sending from non Codegen", () => {
         const eventName = "event name";
         const eventProperties = [{ propertyName: "prop0", propertyType: "string" }];
-        const body = networkHandler.bodyForEventSchemaCall(constants_1.mockedReturns.SESSION_ID, eventName, eventProperties, null, null);
-        expect(body).toEqual(Object.assign(Object.assign({}, baseBody), { type: "event", eventName,
+        const body = networkHandler.bodyForEventSchemaCall("", eventName, eventProperties, null, null);
+        expect(body).toEqual(Object.assign(Object.assign({}, baseBody), { anonymousId: "", type: "event", eventName,
             eventProperties, avoFunction: false, eventId: null, eventHash: null }));
     });
     test("bodyForEventSchemaCall returns base body + event schema used for event sending from Codegen", () => {
@@ -51,9 +47,40 @@ describe("NetworkCallsHandler", () => {
         const eventId = "event id";
         const eventHash = "event hash";
         const eventProperties = [{ propertyName: "prop0", propertyType: "string" }];
-        const body = networkHandler.bodyForEventSchemaCall(constants_1.mockedReturns.SESSION_ID, eventName, eventProperties, eventId, eventHash);
-        expect(body).toEqual(Object.assign(Object.assign({}, baseBody), { type: "event", eventName,
+        const body = networkHandler.bodyForEventSchemaCall("", eventName, eventProperties, eventId, eventHash);
+        expect(body).toEqual(Object.assign(Object.assign({}, baseBody), { anonymousId: "", type: "event", eventName,
             eventProperties, avoFunction: true, eventId,
             eventHash }));
     });
+    test("bodyForEventSchemaCall uses streamId as anonymousId", () => {
+        const eventName = "event name";
+        const streamId = "user-123";
+        const eventProperties = [{ propertyName: "prop0", propertyType: "string" }];
+        const body = networkHandler.bodyForEventSchemaCall(streamId, eventName, eventProperties, null, null);
+        expect(body.anonymousId).toBe("user-123");
+    });
+    test("bodyForEventSchemaCall with rawEventProperties passes them through (no encryption in dev without key)", () => {
+        const eventName = "event name";
+        const eventProperties = [{ propertyName: "prop0", propertyType: "string" }];
+        const rawEventProperties = { prop0: "hello" };
+        const body = networkHandler.bodyForEventSchemaCall("", eventName, eventProperties, null, null, rawEventProperties);
+        // Without a publicEncryptionKey, encryption is not triggered,
+        // so eventProperties should be the plain schema (not encrypted)
+        expect(body.eventProperties).toEqual(eventProperties);
+        expect(body.type).toBe("event");
+        expect(body.eventName).toBe(eventName);
+    });
+    test("base body includes publicEncryptionKey when handler is constructed with one", () => {
+        const handlerWithKey = new AvoNetworkCallsHandler_1.AvoNetworkCallsHandler(apiKey, env, "", version, inspectorVersion, "test-public-key-abc");
+        const eventName = "event name";
+        const eventProperties = [{ propertyName: "prop0", propertyType: "string" }];
+        const body = handlerWithKey.bodyForEventSchemaCall("", eventName, eventProperties, null, null);
+        expect(body.publicEncryptionKey).toBe("test-public-key-abc");
+    });
+    test("base body does not include publicEncryptionKey when handler is constructed without one", () => {
+        const eventName = "event name";
+        const eventProperties = [{ propertyName: "prop0", propertyType: "string" }];
+        const body = networkHandler.bodyForEventSchemaCall("", eventName, eventProperties, null, null);
+        expect(body.publicEncryptionKey).toBeUndefined();
+    });
 });

package/dist/__tests__/TestNetworkCallsHandlerPublic.js

@@ -25,7 +25,6 @@ describe("AvoNetworkCallsHandler", () => {
         prop4: 0.0,
     };
     const happyPathInspectorCall = () => {
-        inspector.avoNetworkCallsHandler["samplingRate"] = 0.1;
         return Promise.resolve();
     };
     beforeAll(() => {
@@ -43,12 +42,13 @@ describe("AvoNetworkCallsHandler", () => {
         // @ts-ignore
         inspector.avoDeduplicator._clearEvents();
     });
-    test("handleTrackSchema is called on trackSchemaFromEvent", () => __awaiter(void 0, void 0, void 0, function* () {
+    test("trackSchemaFromEvent sends only event call (no sessionStarted)", () => __awaiter(void 0, void 0, void 0, function* () {
         yield inspector.trackSchemaFromEvent(eventName, properties);
-        expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(2);
+        // Should be called once (event only, no sessionStarted)
+        expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(1);
         expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledWith([
             expect.objectContaining({
-                type: "sessionStarted",
+                type: "event",
                 apiKey: apiKey,
                 appName: appName,
                 appVersion: version,
@@ -56,51 +56,44 @@ describe("AvoNetworkCallsHandler", () => {
                 env: env,
                 libPlatform: "node",
                 messageId: expect.anything(),
-                trackingId: "",
+                anonymousId: "",
                 createdAt: expect.any(String),
-                sessionId: expect.anything(),
                 samplingRate: 1,
             }),
         ]);
+    }));
+    test("trackSchemaFromEvent with streamId sets anonymousId to streamId", () => __awaiter(void 0, void 0, void 0, function* () {
+        yield inspector.trackSchemaFromEvent(eventName, properties, "user-stream-123");
+        expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(1);
         expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledWith([
             expect.objectContaining({
                 type: "event",
-                apiKey: apiKey,
-                appName: appName,
-                appVersion: version,
-                libVersion: expect.anything(),
-                env: env,
-                libPlatform: "node",
-                messageId: expect.anything(),
-                trackingId: "",
-                createdAt: expect.anything(),
-                sessionId: expect.anything(),
-                samplingRate: 0.1,
+                anonymousId: "user-stream-123",
             }),
         ]);
     }));
-    test("handleTrackSchema is called on _avoFunctionTrackSchemaFromEvent", () => __awaiter(void 0, void 0, void 0, function* () {
+    test("trackSchemaFromEvent without streamId sets anonymousId to empty string", () => __awaiter(void 0, void 0, void 0, function* () {
+        yield inspector.trackSchemaFromEvent(eventName, properties);
+        expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(1);
+        expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledWith([
+            expect.objectContaining({
+                anonymousId: "",
+            }),
+        ]);
+    }));
+    test("trackSchemaFromEvent with streamId containing ':' logs warning", () => __awaiter(void 0, void 0, void 0, function* () {
+        const consoleWarnSpy = jest.spyOn(console, "warn").mockImplementation(() => { });
+        yield inspector.trackSchemaFromEvent(eventName, properties, "invalid:stream");
+        expect(consoleWarnSpy).toHaveBeenCalledWith("[Avo Inspector] Warning: streamId contains ':' which is not supported");
+        consoleWarnSpy.mockRestore();
+    }));
+    test("_avoFunctionTrackSchemaFromEvent sends only event call (no sessionStarted)", () => __awaiter(void 0, void 0, void 0, function* () {
         const eventId = "testId";
         const eventHash = "testHash";
         // @ts-ignore
         yield inspector._avoFunctionTrackSchemaFromEvent(eventName, properties, eventId, eventHash);
-        expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(2);
-        expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toBeCalledWith([
-            expect.objectContaining({
-                type: "sessionStarted",
-                apiKey: apiKey,
-                appName: appName,
-                appVersion: version,
-                libVersion: expect.anything(),
-                env: env,
-                libPlatform: "node",
-                messageId: expect.anything(),
-                trackingId: "",
-                createdAt: expect.anything(),
-                sessionId: expect.anything(),
-                samplingRate: 0.1,
-            })
-        ]);
+        // Should be called once (event only, no sessionStarted)
+        expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(1);
         expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledWith([
             expect.objectContaining({
                 type: "event",
@@ -111,17 +104,57 @@ describe("AvoNetworkCallsHandler", () => {
                 env: env,
                 libPlatform: "node",
                 messageId: expect.anything(),
-                trackingId: "",
-                createdAt: expect.anything(),
-                sessionId: expect.anything(),
-                samplingRate: 0.1,
+                anonymousId: "",
+                createdAt: expect.any(String),
             }),
         ]);
     }));
     test("an error is logged if event schema call fails and AvoInspector.shouldLog is true", () => __awaiter(void 0, void 0, void 0, function* () {
-        inspectorCallSpy.mockImplementationOnce(happyPathInspectorCall);
+        const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
         inspectorCallSpy.mockRejectedValueOnce('Network error');
         yield inspector.trackSchemaFromEvent(eventName, properties);
-        expect(consoleLogSpy).toHaveBeenCalledWith('Avo Inspector: schema sending failed: Network error.');
+        expect(consoleErrorSpy).toHaveBeenCalledWith('Avo Inspector: schema sending failed: Network error.');
+        consoleErrorSpy.mockRestore();
+    }));
+    test("_avoFunctionTrackSchemaFromEvent passes empty string as anonymousId", () => __awaiter(void 0, void 0, void 0, function* () {
+        const eventId = "testId";
+        const eventHash = "testHash";
+        // @ts-ignore
+        yield inspector._avoFunctionTrackSchemaFromEvent(eventName, properties, eventId, eventHash);
+        expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledWith([
+            expect.objectContaining({
+                anonymousId: "",
+            }),
+        ]);
+    }));
+    test("trackSchemaFromEvent with streamId containing ':' still sends the event", () => __awaiter(void 0, void 0, void 0, function* () {
+        const consoleWarnSpy = jest.spyOn(console, "warn").mockImplementation(() => { });
+        yield inspector.trackSchemaFromEvent(eventName, properties, "bad:stream");
+        // Warning is logged
+        expect(consoleWarnSpy).toHaveBeenCalledWith("[Avo Inspector] Warning: streamId contains ':' which is not supported");
+        // Event is still sent despite the warning
+        expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(1);
+        expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledWith([
+            expect.objectContaining({
+                type: "event",
+                anonymousId: "bad:stream",
+            }),
+        ]);
+        consoleWarnSpy.mockRestore();
+    }));
+    test("same event with different streamIds is not deduplicated", () => __awaiter(void 0, void 0, void 0, function* () {
+        yield inspector.trackSchemaFromEvent(eventName, properties, "stream-a");
+        yield inspector.trackSchemaFromEvent(eventName, properties, "stream-b");
+        expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(2);
+    }));
+    test("trackSchemaFromEvent rejection contains the expected error string", () => __awaiter(void 0, void 0, void 0, function* () {
+        const consoleErrorSpy = jest.spyOn(console, "error").mockImplementation(() => { });
+        // Force the catch block in trackSchemaFromEvent by making extractSchema throw
+        jest.spyOn(inspector, "extractSchema").mockImplementation(() => {
+            throw new Error("test explosion");
+        });
+        yield expect(inspector.trackSchemaFromEvent(eventName, properties)).rejects.toBe("Avo Inspector: something went wrong. Please report to support@avo.app.");
+        consoleErrorSpy.mockRestore();
+        inspector.extractSchema.mockRestore();
     }));
 });

package/dist/eventSpec/AvoEventSpecCache.d.ts

@@ -0,0 +1,19 @@
+import { EventSpecResponse } from "./AvoEventSpecFetchTypes";
+export declare class AvoEventSpecCache {
+    private cache;
+    private globalEventCount;
+    static makeKey(apiKey: string, streamId: string, eventName: string): string;
+    /**
+     * Returns the cached EventSpecResponse, or undefined on cache miss.
+     * A cached response with eventSpec: null means "no spec exists for this event".
+     */
+    get(key: string): EventSpecResponse | undefined;
+    /**
+     * Returns true if the key exists in the cache and has not expired.
+     */
+    contains(key: string): boolean;
+    set(key: string, value: EventSpecResponse): void;
+    flush(): void;
+    private purgeExpired;
+    private evictLRU;
+}

package/dist/eventSpec/AvoEventSpecCache.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AvoEventSpecCache = void 0;
+const MAX_EVENT_COUNT = 50;
+const TTL_MS = 60000;
+class AvoEventSpecCache {
+    constructor() {
+        this.cache = new Map();
+        this.globalEventCount = 0;
+    }
+    static makeKey(apiKey, streamId, eventName) {
+        return `${apiKey}\0${streamId}\0${eventName}`;
+    }
+    /**
+     * Returns the cached EventSpecResponse, or undefined on cache miss.
+     * A cached response with eventSpec: null means "no spec exists for this event".
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (entry === undefined) {
+            return undefined;
+        }
+        // TTL check
+        if (Date.now() - entry.timestamp > TTL_MS) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        // Per-entry access count eviction
+        entry.eventCount++;
+        if (entry.eventCount >= MAX_EVENT_COUNT) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        entry.lastAccessed = Date.now();
+        return entry.value;
+    }
+    /**
+     * Returns true if the key exists in the cache and has not expired.
+     */
+    contains(key) {
+        const entry = this.cache.get(key);
+        if (entry === undefined) {
+            return false;
+        }
+        if (Date.now() - entry.timestamp > TTL_MS) {
+            this.cache.delete(key);
+            return false;
+        }
+        if (entry.eventCount >= MAX_EVENT_COUNT) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    set(key, value) {
+        this.globalEventCount++;
+        // Global rotation: evict LRU entry every MAX_EVENT_COUNT operations
+        if (this.globalEventCount >= MAX_EVENT_COUNT) {
+            this.purgeExpired();
+            this.evictLRU();
+            this.globalEventCount = 0;
+        }
+        this.cache.set(key, {
+            value,
+            timestamp: Date.now(),
+            eventCount: 0,
+            lastAccessed: Date.now(),
+        });
+        // Size cap: evict oldest entries when exceeding max
+        while (this.cache.size > MAX_EVENT_COUNT) {
+            this.evictLRU();
+        }
+    }
+    flush() {
+        this.cache.clear();
+        this.globalEventCount = 0;
+    }
+    purgeExpired() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (now - entry.timestamp > TTL_MS) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    evictLRU() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.lastAccessed < oldestTime) {
+                oldestTime = entry.lastAccessed;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey !== null) {
+            this.cache.delete(oldestKey);
+        }
+    }
+}
+exports.AvoEventSpecCache = AvoEventSpecCache;

package/dist/eventSpec/AvoEventSpecFetchTypes.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Type definitions for Event Spec validation responses.
+ */
+/** A single property constraint from the spec. */
+export interface PropertyConstraint {
+    propertyName: string;
+    /** Expected type, e.g. "string", "int", "float", "boolean", "object", "list(string)" */
+    propertyType: string;
+    /** Optional regex pattern that the value must match */
+    regex?: string;
+}
+/** The spec for a single event, as returned by the API. */
+export interface EventSpec {
+    eventName: string;
+    properties: PropertyConstraint[];
+}
+/** Metadata identifying the spec source. */
+export interface EventSpecMetadata {
+    schemaId: string;
+    branchId: string;
+    latestActionId: string;
+    sourceId: string;
+}
+/** Full response from the spec endpoint. */
+export interface EventSpecResponse {
+    eventSpec: EventSpec | null;
+    metadata: EventSpecMetadata;
+}
+/** Per-property validation result. */
+export interface PropertyValidationResult {
+    propertyName: string;
+    failedEventIds: string[];
+    passedEventIds: string[];
+}
+/** Payload sent to reportValidatedEvent. */
+export interface ValidatedEventPayload {
+    streamId: string;
+    eventName: string;
+    eventSpecMetadata: EventSpecMetadata;
+    propertyResults: PropertyValidationResult[];
+}

package/dist/eventSpec/AvoEventSpecFetchTypes.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Type definitions for Event Spec validation responses.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/eventSpec/AvoEventSpecFetcher.d.ts

@@ -0,0 +1,25 @@
+import { EventSpecResponse } from "./AvoEventSpecFetchTypes";
+type FetchCallback = (result: EventSpecResponse | null) => void;
+export declare class AvoEventSpecFetcher {
+    private apiKey;
+    private inFlight;
+    private agent;
+    private static specEndpoint;
+    constructor(apiKey: string);
+    fetch(eventName: string, streamId: string, callback: FetchCallback): void;
+    private resolveCallbacks;
+    /**
+     * Parse the wire format from /trackingPlan/eventSpec into our internal types.
+     *
+     * Wire format:
+     *   { events: [{ b, id, vids, p: { "PropName": { t: "string", r: true, v: {...}, rx: {...} } } }],
+     *     metadata: { schemaId, branchId, latestActionId, sourceId } }
+     *
+     * Internal format:
+     *   { eventSpec: { eventName, properties: [{ propertyName, propertyType, regex? }] } | null,
+     *     metadata: { schemaId, branchId, latestActionId, sourceId } }
+     */
+    static parseWireResponse(wire: any, eventName: string): EventSpecResponse;
+    destroy(): void;
+}
+export {};