node-avo-inspector 1.2.0 → 2.0.0-beta.1

package/src/__tests__/TestParsing.ts

@@ -1,153 +0,0 @@
-import { AvoInspector } from "../AvoInspector";
-import { defaultOptions, type } from "./constants";
-
-describe("Schema Parsing", () => {
-  const inspector = new AvoInspector(defaultOptions);
-
-  beforeAll(() => {
-    inspector.enableLogging(false);
-  });
-
-  test("Empty array returned if eventProperties are not set", () => {
-    // @ts-ignore
-    const schema = inspector.extractSchema();
-
-    expect(schema).toEqual([]);
-  });
-
-  test("Property types and names are set", () => {
-    // Given
-    const eventProperties = {
-      prop0: true,
-      prop1: 1,
-      prop2: "str",
-      prop3: 0.5,
-      prop4: undefined,
-      prop5: null,
-      prop6: { an: "object" },
-      prop7: [
-        "a",
-        "list",
-        {
-          "obj in list": true,
-          "int field": 1,
-        },
-        ["another", "list"],
-        [1, 2],
-      ],
-    };
-
-    // When
-    const res = inspector.extractSchema(eventProperties);
-
-    // Then
-    res.forEach(({ propertyName }, index) => {
-      expect(propertyName).toBe(`prop${index}`);
-    });
-
-    expect(res[0].propertyType).toBe(type.BOOL);
-    expect(res[1].propertyType).toBe(type.INT);
-    expect(res[2].propertyType).toBe(type.STRING);
-    expect(res[3].propertyType).toBe(type.FLOAT);
-    expect(res[4].propertyType).toBe(type.NULL);
-    expect(res[5].propertyType).toBe(type.NULL);
-
-    expect(res[6].propertyType).toBe(type.OBJECT);
-    expect(res[6].children).toMatchObject([
-      {
-        propertyName: "an",
-        propertyType: type.STRING,
-      },
-    ]);
-
-    expect(res[7].propertyType).toBe(type.STRINGLIST);
-    expect(res[7].children).toMatchObject([
-      type.STRING,
-      [
-        {
-          propertyName: "obj in list",
-          propertyType: type.BOOL,
-        },
-        {
-          propertyName: "int field",
-          propertyType: type.INT,
-        },
-      ],
-      [type.STRING],
-      [type.INT],
-    ]);
-  });
-
-  test("Duplicated values are removed", () => {
-    // Given
-    const eventProperties = {
-      prop0: ["true", "false", true, 10, "true", true, 11, 10, 0.1, 0.1],
-    };
-
-    // When
-    const res = inspector.extractSchema(eventProperties);
-
-    // Then
-    expect(res[0].propertyType).toBe(type.STRINGLIST);
-  });
-
-  test("Empty and falsy values are set correctly", () => {
-    // Given
-    const eventProperties = {
-      prop0: false,
-      prop1: 0,
-      prop2: "",
-      prop3: 0.0,
-      prop4: undefined,
-      prop5: null,
-      prop6: {},
-      prop7: [],
-    };
-
-    // When
-    const res = inspector.extractSchema(eventProperties);
-
-    // Then
-    expect(res[0].propertyType).toBe(type.BOOL);
-    expect(res[1].propertyType).toBe(type.INT);
-    expect(res[2].propertyType).toBe(type.STRING);
-    expect(res[3].propertyType).toBe(type.INT);
-    expect(res[4].propertyType).toBe(type.NULL);
-    expect(res[5].propertyType).toBe(type.NULL);
-
-    expect(res[6].propertyType).toBe(type.OBJECT);
-    expect(res[6].children).toMatchObject([]);
-
-    expect(res[7].propertyType).toBe(type.STRINGLIST);
-    expect(res[7].children).toMatchObject([]);
-  });
-
-  test("List of string returns list(string)", () => {
-    // Given
-    const eventProperties = {
-      prop0: ["a", "b", "c"],
-    };
-
-    // When
-    const res = inspector.extractSchema(eventProperties);
-
-    // Then
-    expect(res[0].propertyType).toBe(type.STRINGLIST);
-  });
-
-
-  test("List of multiple types returns list(`firstType`)", () => {
-    // Given
-    const eventProperties = {
-      prop0: [1.2, "two", {"three": 3}],
-    };
-
-    // When
-    const res = inspector.extractSchema(eventProperties);
-
-    // Then
-    expect(res[0].propertyType).toBe(type.FLOATLIST);
-  });
-
-
-});

package/src/__tests__/constants.ts

@@ -1,63 +0,0 @@
-import { AvoInspectorEnv } from "../AvoInspectorEnv";
-
-const defaultOptions = {
-  apiKey: "api-key-xxx",
-  env: AvoInspectorEnv.Dev,
-  version: "1",
-  shouldLog: true,
-  appName: "my-test-app",
-};
-
-const error = {
-  API_KEY:
-    "[Avo Inspector] No API key provided. Inspector can't operate without API key.",
-  VERSION:
-    "[Avo Inspector] No version provided. Many features of Inspector rely on versioning. Please provide comparable string version, i.e. integer or semantic.",
-};
-
-const mockedReturns = {
-  INSTALLATION_ID: "avo-instalation-id",
-  GUID: "generated-guid",
-  SESSION_ID: "session-id",
-};
-
-const networkCallType = {
-  EVENT: "event",
-  SESSION_STARTED: "sessionStarted",
-};
-
-const requestMsg = {
-  ERROR: "Request failed",
-  TIMEOUT: "Request timed out",
-};
-
-const trackingEndpoint = "https://api.avo.app/inspector/v1/track";
-
-const sessionTimeMs = 5 * 60 * 1000;
-
-const type = {
-  STRING: "string",
-  STRINGLIST: "list(string)",
-  INT: "int",
-  INTLIST: "list(int)",
-  OBJECT: "object",
-  OBJECTLIST: "list(object)",
-  FLOAT: "float",
-  FLOATLIST: "list(float)",
-  BOOL: "boolean",
-  BOOLLIST: "list(boolean)",
-  NULL: "null",
-  UNKNOWN: "unknown",
-  UNKNOWNLIST: "list(unknown)",
-};
-
-export {
-  defaultOptions,
-  error,
-  mockedReturns,
-  networkCallType,
-  requestMsg,
-  sessionTimeMs,
-  type,
-  trackingEndpoint,
-};

package/src/eventSpec/AvoEventSpecCache.ts

@@ -1,119 +0,0 @@
-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

@@ -1,47 +0,0 @@
-/**
- * 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

@@ -1,186 +0,0 @@
-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

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

package/src/index.ts

@@ -1,2 +0,0 @@
-export { AvoInspector } from "./AvoInspector";
-export { AvoInspectorEnv } from "./AvoInspectorEnv";

package/src/utils.ts

@@ -1,49 +0,0 @@
-const isValueEmpty = (value: string | null | undefined): boolean => {
-  return value === null || value === undefined || value.trim().length == 0;
-};
-
-function deepEquals(x: any, y: any) {
-
-  if (x === y) {
-    return true;
-  }
-
-  if (!(x instanceof Object) || !(y instanceof Object)) {
-    return false;
-  }
-
-  if (x.constructor !== y.constructor) {
-    return false;
-  }
-
-  for (var p in x) {
-    if (!x.hasOwnProperty(p)) {
-      continue;
-    }
-
-    if (!y.hasOwnProperty(p)) {
-      return false;
-    }
-
-    if (x[p] === y[p]) {
-      continue;
-    }
-
-    if (typeof x[p] !== "object") {
-      return false;
-    }
-
-    if (!deepEquals(x[p], y[p])) {
-      return false;
-    }
-  }
-
-  for (p in y) {
-    if (y.hasOwnProperty(p) && !x.hasOwnProperty(p)) {
-      return false;
-    }
-  }
-  return true;
-}
-
-export { isValueEmpty, deepEquals };

package/tsconfig.json

@@ -1,13 +0,0 @@
-{
-  "compilerOptions": {
-    "module": "CommonJS",
-    "target": "ES6",
-    "declaration": true,
-    "strict": true,
-    "noImplicitAny": true,
-    "baseUrl": "./src",
-    "outDir": "./dist"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["src/tests"]
-}