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

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

package/dist/eventSpec/AvoEventSpecFetcher.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AvoEventSpecFetcher = void 0;
+const https_1 = require("https");
+const AvoInspector_1 = require("../AvoInspector");
+class AvoEventSpecFetcher {
+    constructor(apiKey) {
+        this.inFlight = new Map();
+        this.apiKey = apiKey;
+        this.agent = new https_1.Agent({ keepAlive: true });
+    }
+    fetch(eventName, streamId, callback) {
+        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_1.AvoInspector.shouldLog) {
+            console.log("Avo Inspector: [network] GET https://" + options.hostname + AvoEventSpecFetcher.specEndpoint + "?eventName=" + encodeURIComponent(eventName));
+        }
+        const req = (0, https_1.request)(options, (res) => {
+            if (AvoInspector_1.AvoInspector.shouldLog) {
+                console.log("Avo Inspector: [network] Spec response status: " + res.statusCode + " " + res.statusMessage);
+            }
+            const chunks = [];
+            res.on("data", (data) => chunks.push(data));
+            res.on("end", () => {
+                let result = null;
+                if (res.statusCode !== 200) {
+                    if (AvoInspector_1.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_1.AvoInspector.shouldLog) {
+                        console.log("Avo Inspector: [network] Spec response body: " + body);
+                    }
+                    const wire = JSON.parse(body);
+                    result = AvoEventSpecFetcher.parseWireResponse(wire, eventName);
+                    if (AvoInspector_1.AvoInspector.shouldLog) {
+                        console.log("Avo Inspector: [network] Parsed spec: " + JSON.stringify(result));
+                    }
+                }
+                catch (e) {
+                    if (AvoInspector_1.AvoInspector.shouldLog) {
+                        console.warn("Avo Inspector: [network] Failed to parse spec response: " + e);
+                    }
+                }
+                this.resolveCallbacks(dedupeKey, result);
+            });
+        });
+        req.on("error", (err) => {
+            if (AvoInspector_1.AvoInspector.shouldLog) {
+                console.error("Avo Inspector: [network] Spec fetch error: " + err);
+            }
+            this.resolveCallbacks(dedupeKey, null);
+        });
+        req.setTimeout(10000);
+        req.on("timeout", () => {
+            if (AvoInspector_1.AvoInspector.shouldLog) {
+                console.error("Avo Inspector: [network] Spec fetch timed out after 10s");
+            }
+            req.destroy();
+            this.resolveCallbacks(dedupeKey, null);
+        });
+        req.end();
+    }
+    resolveCallbacks(key, result) {
+        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, eventName) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        const metadata = {
+            schemaId: (_b = (_a = wire.metadata) === null || _a === void 0 ? void 0 : _a.schemaId) !== null && _b !== void 0 ? _b : "",
+            branchId: (_d = (_c = wire.metadata) === null || _c === void 0 ? void 0 : _c.branchId) !== null && _d !== void 0 ? _d : "",
+            latestActionId: (_f = (_e = wire.metadata) === null || _e === void 0 ? void 0 : _e.latestActionId) !== null && _f !== void 0 ? _f : "",
+            sourceId: (_h = (_g = wire.metadata) === null || _g === void 0 ? void 0 : _g.sourceId) !== null && _h !== void 0 ? _h : "",
+        };
+        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 = [];
+        if (entry.p && typeof entry.p === "object") {
+            for (const propName of Object.keys(entry.p)) {
+                const constraint = entry.p[propName];
+                const prop = {
+                    propertyName: propName,
+                    propertyType: (_j = constraint === null || constraint === void 0 ? void 0 : constraint.t) !== null && _j !== void 0 ? _j : "unknown",
+                };
+                // Extract regex pattern if present (rx field maps regex patterns to event IDs)
+                if ((constraint === null || constraint === void 0 ? void 0 : 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 = {
+            eventName,
+            properties,
+        };
+        return { eventSpec, metadata };
+    }
+    destroy() {
+        this.agent.destroy();
+    }
+}
+exports.AvoEventSpecFetcher = AvoEventSpecFetcher;
+AvoEventSpecFetcher.specEndpoint = "/trackingPlan/eventSpec";

package/dist/eventSpec/EventValidator.d.ts

@@ -0,0 +1,15 @@
+import { EventSpec, PropertyValidationResult } from "./AvoEventSpecFetchTypes";
+interface EventProperty {
+    propertyName: string;
+    propertyType: string;
+    propertyValue?: string;
+}
+export declare 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[];
+}
+export {};

package/dist/eventSpec/EventValidator.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventValidator = void 0;
+const safe_regex2_1 = require("safe-regex2");
+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, eventProperties, eventId) {
+        const results = [];
+        const eventPropMap = new Map();
+        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 (!(0, safe_regex2_1.default)(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 = {
+                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;
+    }
+}
+exports.EventValidator = EventValidator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-avo-inspector",
-  "version": "1.1.0",
+  "version": "1.2.0-alpha.1",
   "description": "Avo Inspector for Node.js",
   "main": "dist/index.js",
   "repository": "https://github.com/avohq/node-avo-inspector",
@@ -42,5 +42,7 @@
     "ts-jest": "^29.2.4",
     "typescript": "*"
   },
-  "dependencies": {}
+  "dependencies": {
+    "safe-regex2": "^5.0.0"
+  }
 }

package/src/AvoDeduplicator.ts

@@ -5,33 +5,41 @@ export class AvoDeduplicator {
   manualEvents: { [time: number]: string } = {};
   private msToConsiderOld = 500;
 
+  // Keyed by streamId\0eventName to prevent cross-stream suppression on server
   avoFunctionsEventsParams: {
-    [eventName: string]: { [propName: string]: any };
+    [key: string]: { [propName: string]: any };
   } = {};
-  manualEventsParams: { [eventName: string]: { [propName: string]: any } } = {};
+  manualEventsParams: { [key: string]: { [propName: string]: any } } = {};
+
+  private static dedupKey(eventName: string, streamId: string): string {
+    return streamId + "\0" + eventName;
+  }
 
   shouldRegisterEvent(
     eventName: string,
     params: { [propName: string]: any },
-    fromAvoFunction: boolean
+    fromAvoFunction: boolean,
+    streamId: string = ""
   ): boolean {
     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);
   }
 
   private hasSameEventAs(
-    eventName: string,
+    key: string,
     params: { [propName: string]: any },
     checkInAvoFunctions: boolean
   ): boolean {
@@ -39,37 +47,33 @@ export class AvoDeduplicator {
 
     if (checkInAvoFunctions) {
       if (
-        this.lookForEventIn(eventName, params, this.avoFunctionsEventsParams)
+        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;
   }
 
   private lookForEventIn(
-    eventName: string,
+    key: string,
     params: { [propName: string]: any },
-    eventsStorage: { [eventName: string]: { [propName: string]: any } }
+    eventsStorage: { [key: string]: { [propName: string]: any } }
   ): boolean {
-    for (const otherEventName in eventsStorage) {
-      if (eventsStorage.hasOwnProperty(otherEventName)) {
-        if (otherEventName === eventName) {
-          const otherParams = eventsStorage[eventName];
-          if (otherParams && deepEquals(params, otherParams)) {
-            return true;
-          }
-        }
+    if (eventsStorage.hasOwnProperty(key)) {
+      const otherParams = eventsStorage[key];
+      if (otherParams && deepEquals(params, otherParams)) {
+        return true;
       }
     }
     return false;
@@ -116,9 +120,9 @@ export 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];
         }
       }
     }
@@ -127,9 +131,9 @@ export 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/src/AvoEncryption.ts

@@ -0,0 +1,90 @@
+import * as crypto from "crypto";
+
+export 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 {
+    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: string): boolean {
+    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: string,
+    recipientPubKeyHex: string
+  ): string | null {
+    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;
+    }
+  }
+}