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

package/src/__tests__/TestNetworkCallsHandlerPublic.ts

@@ -5,47 +5,52 @@ import { defaultOptions } from "./constants";
 
 describe("AvoNetworkCallsHandler", () => {
   let inspectorCallSpy: jest.SpyInstance<any, unknown[]>;
+  let consoleLogSpy: jest.SpyInstance<any, unknown[]>;
 
   let inspector: AvoInspector;
 
   const { apiKey, env, version, appName } = defaultOptions;
 
+  const eventName = "event name";
+  const properties = {
+    prop0: "",
+    prop2: false,
+    prop3: 0,
+    prop4: 0.0,
+  };
+
+  const happyPathInspectorCall = () => {
+    return Promise.resolve();
+  };
+
   beforeAll(() => {
     inspector = new AvoInspector(defaultOptions);
-    inspector.enableLogging(false);
+    inspector.enableLogging(true);
 
     inspectorCallSpy = jest
       .spyOn(AvoNetworkCallsHandler.prototype as any, "callInspectorWithBatchBody");
 
-    inspectorCallSpy.mockImplementation(() => {
-        inspector.avoNetworkCallsHandler["samplingRate"] = 0.1;
-        return Promise.resolve();
-      });
+    consoleLogSpy = jest.spyOn(console, "log").mockImplementation(() => {});
   });
 
+  beforeEach(() => {
+    inspectorCallSpy.mockImplementation(happyPathInspectorCall);
+  })
+
   afterEach(() => {
     jest.clearAllMocks();
     // @ts-ignore
     inspector.avoDeduplicator._clearEvents();
   });
 
-  test("handleTrackSchema is called on trackSchemaFromEvent", async () => {
-    const eventName = "event name";
-    const properties = {
-      prop0: "",
-      prop2: false,
-      prop3: 0,
-      prop4: 0.0,
-    };
-
-    const schema = inspector.extractSchema(properties);
-
+  test("trackSchemaFromEvent sends only event call (no sessionStarted)", async () => {
     await inspector.trackSchemaFromEvent(eventName, properties);
 
-    expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(2);
-    expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toBeCalledWith([
+    // 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,
@@ -53,13 +58,62 @@ 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", async () => {
+    await inspector.trackSchemaFromEvent(eventName, properties, "user-stream-123");
+
+    expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(1);
+    expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledWith([
+      expect.objectContaining({
+        type: "event",
+        anonymousId: "user-stream-123",
+      }),
+    ]);
+  });
+
+  test("trackSchemaFromEvent without streamId sets anonymousId to empty string", async () => {
+    await 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", async () => {
+    const consoleWarnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+    await 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)", async () => {
+    const eventId = "testId";
+    const eventHash = "testHash";
+
+    // @ts-ignore
+    await inspector._avoFunctionTrackSchemaFromEvent(
+      eventName,
+      properties,
+      eventId,
+      eventHash
     );
+
+    // Should be called once (event only, no sessionStarted)
+    expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(1);
     expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledWith([
       expect.objectContaining({
         type: "event",
@@ -70,27 +124,26 @@ 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("handleTrackSchema is called on _avoFunctionTrackSchemaFromEvent", async () => {
-    const eventName = "event name";
-    const properties = {
-      prop0: "",
-      prop2: false,
-      prop3: 0,
-      prop4: 0.0,
-    };
+  test("an error is logged if event schema call fails and AvoInspector.shouldLog is true", async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    inspectorCallSpy.mockRejectedValueOnce('Network error');
+
+    await inspector.trackSchemaFromEvent(eventName, properties);
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith('Avo Inspector: schema sending failed: Network error.');
+    consoleErrorSpy.mockRestore();
+  });
+
+  test("_avoFunctionTrackSchemaFromEvent passes empty string as anonymousId", async () => {
     const eventId = "testId";
     const eventHash = "testHash";
 
-    const schema = inspector.extractSchema(properties);
-
     // @ts-ignore
     await inspector._avoFunctionTrackSchemaFromEvent(
       eventName,
@@ -99,39 +152,57 @@ describe("AvoNetworkCallsHandler", () => {
       eventHash
     );
 
-    expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(2);
-    expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toBeCalledWith([
+    expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledWith([
       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,
-      })
-    ]
+        anonymousId: "",
+      }),
+    ]);
+  });
+
+  test("trackSchemaFromEvent with streamId containing ':' still sends the event", async () => {
+    const consoleWarnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+    await 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",
-        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: "bad:stream",
       }),
     ]);
+
+    consoleWarnSpy.mockRestore();
+  });
+
+  test("same event with different streamIds is not deduplicated", async () => {
+    await inspector.trackSchemaFromEvent(eventName, properties, "stream-a");
+    await inspector.trackSchemaFromEvent(eventName, properties, "stream-b");
+
+    expect(inspector.avoNetworkCallsHandler.callInspectorWithBatchBody).toHaveBeenCalledTimes(2);
+  });
+
+  test("trackSchemaFromEvent rejection contains the expected error string", async () => {
+    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");
+    });
+
+    await expect(
+      inspector.trackSchemaFromEvent(eventName, properties)
+    ).rejects.toBe(
+      "Avo Inspector: something went wrong. Please report to support@avo.app."
+    );
+
+    consoleErrorSpy.mockRestore();
+    (inspector.extractSchema as jest.Mock).mockRestore();
   });
 });

package/src/eventSpec/AvoEventSpecCache.ts

@@ -0,0 +1,119 @@
+import { EventSpecResponse } from "./AvoEventSpecFetchTypes";
+
+interface CacheEntry {
+  value: EventSpecResponse;
+  timestamp: number;
+  eventCount: number;
+  lastAccessed: number;
+}
+
+const MAX_EVENT_COUNT = 50;
+const TTL_MS = 60_000;
+
+export class AvoEventSpecCache {
+  private cache: Map<string, CacheEntry> = new Map();
+  private globalEventCount = 0;
+
+  static makeKey(apiKey: string, streamId: string, eventName: string): string {
+    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: string): EventSpecResponse | undefined {
+    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: string): boolean {
+    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: string, value: EventSpecResponse): void {
+    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(): void {
+    this.cache.clear();
+    this.globalEventCount = 0;
+  }
+
+  private purgeExpired(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.cache.entries()) {
+      if (now - entry.timestamp > TTL_MS) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  private evictLRU(): void {
+    let oldestKey: string | null = 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);
+    }
+  }
+}

package/src/eventSpec/AvoEventSpecFetchTypes.ts

@@ -0,0 +1,47 @@
+/**
+ * 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/src/eventSpec/AvoEventSpecFetcher.ts

@@ -0,0 +1,186 @@
+import { request, Agent } from "https";
+import { EventSpecResponse, EventSpec, EventSpecMetadata, PropertyConstraint } from "./AvoEventSpecFetchTypes";
+import { AvoInspector } from "../AvoInspector";
+
+type FetchCallback = (result: EventSpecResponse | null) => void;
+
+export class AvoEventSpecFetcher {
+  private apiKey: string;
+  private inFlight: Map<string, FetchCallback[]> = new Map();
+  private agent: Agent;
+
+  private static specEndpoint = "/trackingPlan/eventSpec";
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+    this.agent = new Agent({ keepAlive: true });
+  }
+
+  fetch(
+    eventName: string,
+    streamId: string,
+    callback: FetchCallback
+  ): void {
+    const dedupeKey = `${this.apiKey}:${streamId}:${eventName}`;
+
+    // In-flight dedup: if there's already a request in flight for this key,
+    // queue the callback
+    const existingCallbacks = this.inFlight.get(dedupeKey);
+    if (existingCallbacks) {
+      existingCallbacks.push(callback);
+      return;
+    }
+
+    // Register the callback and start the request
+    this.inFlight.set(dedupeKey, [callback]);
+
+    const queryParams = new URLSearchParams({
+      apiKey: this.apiKey,
+      eventName,
+      streamId,
+    });
+
+    const options = {
+      hostname: "api.avo.app",
+      port: 443,
+      path: `${AvoEventSpecFetcher.specEndpoint}?${queryParams.toString()}`,
+      method: "GET",
+      agent: this.agent,
+      headers: {
+        Accept: "application/json",
+      },
+    };
+
+    if (AvoInspector.shouldLog) {
+      console.log("Avo Inspector: [network] GET https://" + options.hostname + AvoEventSpecFetcher.specEndpoint + "?eventName=" + encodeURIComponent(eventName));
+    }
+
+    const req = request(options, (res) => {
+      if (AvoInspector.shouldLog) {
+        console.log("Avo Inspector: [network] Spec response status: " + res.statusCode + " " + res.statusMessage);
+      }
+      const chunks: Buffer[] = [];
+      res.on("data", (data: Buffer) => chunks.push(data));
+      res.on("end", () => {
+        let result: EventSpecResponse | null = null;
+        if (res.statusCode !== 200) {
+          if (AvoInspector.shouldLog) {
+            const body = Buffer.concat(chunks).toString();
+            console.warn("Avo Inspector: [network] Spec fetch failed with status " + res.statusCode + ": " + body);
+          }
+          this.resolveCallbacks(dedupeKey, null);
+          return;
+        }
+        try {
+          const body = Buffer.concat(chunks).toString();
+          if (AvoInspector.shouldLog) {
+            console.log("Avo Inspector: [network] Spec response body: " + body);
+          }
+          const wire = JSON.parse(body);
+          result = AvoEventSpecFetcher.parseWireResponse(wire, eventName);
+          if (AvoInspector.shouldLog) {
+            console.log("Avo Inspector: [network] Parsed spec: " + JSON.stringify(result));
+          }
+        } catch (e) {
+          if (AvoInspector.shouldLog) {
+            console.warn("Avo Inspector: [network] Failed to parse spec response: " + e);
+          }
+        }
+        this.resolveCallbacks(dedupeKey, result);
+      });
+    });
+
+    req.on("error", (err) => {
+      if (AvoInspector.shouldLog) {
+        console.error("Avo Inspector: [network] Spec fetch error: " + err);
+      }
+      this.resolveCallbacks(dedupeKey, null);
+    });
+
+    req.setTimeout(10_000);
+    req.on("timeout", () => {
+      if (AvoInspector.shouldLog) {
+        console.error("Avo Inspector: [network] Spec fetch timed out after 10s");
+      }
+      req.destroy();
+      this.resolveCallbacks(dedupeKey, null);
+    });
+
+    req.end();
+  }
+
+  private resolveCallbacks(
+    key: string,
+    result: EventSpecResponse | null
+  ): void {
+    const callbacks = this.inFlight.get(key);
+    this.inFlight.delete(key);
+
+    if (callbacks) {
+      for (const cb of callbacks) {
+        try {
+          cb(result);
+        } catch (e) {
+          // Don't let one callback failure affect others
+        }
+      }
+    }
+  }
+
+  /**
+   * 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 {
+    const metadata: EventSpecMetadata = {
+      schemaId: wire.metadata?.schemaId ?? "",
+      branchId: wire.metadata?.branchId ?? "",
+      latestActionId: wire.metadata?.latestActionId ?? "",
+      sourceId: wire.metadata?.sourceId ?? "",
+    };
+
+    if (!wire.events || !Array.isArray(wire.events) || wire.events.length === 0) {
+      return { eventSpec: null, metadata };
+    }
+
+    // Use the first event entry (the endpoint returns specs for the requested event)
+    const entry = wire.events[0];
+    const properties: PropertyConstraint[] = [];
+
+    if (entry.p && typeof entry.p === "object") {
+      for (const propName of Object.keys(entry.p)) {
+        const constraint = entry.p[propName];
+        const prop: PropertyConstraint = {
+          propertyName: propName,
+          propertyType: constraint?.t ?? "unknown",
+        };
+        // Extract regex pattern if present (rx field maps regex patterns to event IDs)
+        if (constraint?.rx && typeof constraint.rx === "object") {
+          const patterns = Object.keys(constraint.rx);
+          if (patterns.length > 0) {
+            prop.regex = patterns[0];
+          }
+        }
+        properties.push(prop);
+      }
+    }
+
+    const eventSpec: EventSpec = {
+      eventName,
+      properties,
+    };
+
+    return { eventSpec, metadata };
+  }
+
+  destroy(): void {
+    this.agent.destroy();
+  }
+}

package/src/eventSpec/EventValidator.ts

@@ -0,0 +1,74 @@
+import safeRegex from "safe-regex2";
+import {
+  EventSpec,
+  PropertyValidationResult,
+} from "./AvoEventSpecFetchTypes";
+
+interface EventProperty {
+  propertyName: string;
+  propertyType: string;
+  propertyValue?: string;
+}
+
+export class EventValidator {
+  /**
+   * Validates event properties against the spec.
+   * Returns per-property validation results with bandwidth optimization:
+   * passedEventIds is returned only when strictly smaller than failedEventIds.
+   */
+  validate(
+    spec: EventSpec,
+    eventProperties: EventProperty[],
+    eventId: string
+  ): PropertyValidationResult[] {
+    const results: PropertyValidationResult[] = [];
+    const eventPropMap = new Map<string, EventProperty>();
+
+    for (const prop of eventProperties) {
+      eventPropMap.set(prop.propertyName, prop);
+    }
+
+    for (const specProp of spec.properties) {
+      const actualProp = eventPropMap.get(specProp.propertyName);
+      let passed = false;
+
+      if (actualProp) {
+        // Type check
+        passed = actualProp.propertyType === specProp.propertyType;
+
+        // Regex check (only if type passed, regex is defined, and value is available)
+        if (passed && specProp.regex && actualProp.propertyValue !== undefined) {
+          if (!safeRegex(specProp.regex)) {
+            console.warn(
+              `[Avo Inspector] Warning: Unsafe regex pattern skipped for property "${specProp.propertyName}": ${specProp.regex}`
+            );
+          } else {
+            try {
+              const re = new RegExp(specProp.regex);
+              passed = re.test(actualProp.propertyValue);
+            } catch (e) {
+              console.warn(
+                `[Avo Inspector] Warning: Invalid regex pattern for property "${specProp.propertyName}": ${specProp.regex}`
+              );
+            }
+          }
+        }
+      }
+
+      const result: PropertyValidationResult = {
+        propertyName: specProp.propertyName,
+        failedEventIds: passed ? [] : [eventId],
+        passedEventIds: passed ? [eventId] : [],
+      };
+
+      // Bandwidth optimization: return passedEventIds only when strictly smaller than failedEventIds
+      if (result.passedEventIds.length >= result.failedEventIds.length) {
+        result.passedEventIds = [];
+      }
+
+      results.push(result);
+    }
+
+    return results;
+  }
+}