node-avo-inspector 1.1.1 → 1.2.0

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;
+  }
+}