@antseed/telemetry 0.0.0-stage → 0.1.1

package/dist/posthog.js

@@ -0,0 +1,90 @@
+/**
+ * Bounded PostHog transport. Captures queue in memory and leave in batches
+ * (`/batch/`), with a short timeout and no retries. Every failure is
+ * swallowed: telemetry never affects a request, startup or shutdown.
+ */
+export const POSTHOG_CAPTURE_TIMEOUT_MS = 4_000;
+export function createPostHogSender(options) {
+    const batchUrl = `${options.host.replace(/\/+$/, '')}/batch/`;
+    const timeoutMs = options.timeoutMs ?? POSTHOG_CAPTURE_TIMEOUT_MS;
+    return async (events) => {
+        if (events.length === 0)
+            return;
+        try {
+            await fetch(batchUrl, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ api_key: options.projectApiKey, batch: events }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch {
+            // PostHog outages, offline machines, DNS failures: all ignored.
+        }
+    };
+}
+export class BatchQueue {
+    options;
+    queue = [];
+    timer = null;
+    inFlight = null;
+    maxQueue;
+    maxBatch;
+    flushIntervalMs;
+    constructor(options) {
+        this.options = options;
+        this.maxQueue = options.maxQueue ?? 1_000;
+        this.maxBatch = options.maxBatch ?? 100;
+        this.flushIntervalMs = options.flushIntervalMs ?? 2_000;
+    }
+    get size() {
+        return this.queue.length;
+    }
+    push(event) {
+        this.queue.push(event);
+        if (this.queue.length > this.maxQueue)
+            this.queue.splice(0, this.queue.length - this.maxQueue);
+        if (!this.timer) {
+            this.timer = setTimeout(() => {
+                this.timer = null;
+                void this.flush();
+            }, this.flushIntervalMs);
+            this.timer.unref?.();
+        }
+    }
+    /** Sends everything queued. Safe to call concurrently; never rejects. */
+    async flush() {
+        if (this.inFlight)
+            await this.inFlight;
+        while (this.queue.length > 0) {
+            // Before every batch: an opt-out while an earlier batch was sending stops the rest.
+            if (this.options.isEnabled && !this.options.isEnabled()) {
+                this.queue.length = 0;
+                return;
+            }
+            const batch = this.queue.splice(0, this.maxBatch);
+            // Through a promise, so a sender that throws before returning one is contained too.
+            this.inFlight = Promise.resolve().then(() => this.options.send(batch)).catch(() => undefined);
+            await this.inFlight;
+            this.inFlight = null;
+        }
+    }
+    /** Flushes, waiting at most `timeoutMs`. */
+    async close(timeoutMs = 750) {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        let timeout = null;
+        await Promise.race([
+            this.flush(),
+            new Promise((resolve) => {
+                timeout = setTimeout(resolve, timeoutMs);
+                timeout.unref?.();
+            }),
+        ]);
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+//# sourceMappingURL=posthog.js.map

package/dist/posthog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"posthog.js","sourceRoot":"","sources":["../src/posthog.ts"],"names":[],"mappings":"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"}

package/dist/sanitize.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The privacy boundary. Every property of every event passes through here:
+ * - keys not on the event's allowlist are dropped;
+ * - a key with allowed values or a pattern takes only strings, and a key
+ *   with a range only numbers: a value of another type is dropped;
+ * - string values with a validator must be one of its values;
+ * - strings without one are truncated to 64 characters (and may be pattern-checked);
+ * - numbers are rounded and bounded; booleans pass; anything else is dropped.
+ */
+export declare const MAX_STRING_LENGTH = 64;
+/** What an event may carry: allowed keys, value sets and patterns. */
+export type EventSchema = {
+    /** Allowed property keys. */
+    keys: ReadonlySet<string>;
+    /** Allowed values per string property. */
+    values?: Readonly<Record<string, ReadonlySet<string>>>;
+    /** Required shape per free-form string property. */
+    patterns?: Readonly<Record<string, RegExp>>;
+    /** Numeric properties that must be integers in [min, max]. */
+    ranges?: Readonly<Record<string, readonly [number, number]>>;
+};
+export type EventCatalog = Readonly<Record<string, EventSchema>>;
+export type SanitizedProperties = Record<string, string | number | boolean>;
+/** Public model ids: a conservative slug, or the fixed placeholder. */
+export declare const PUBLIC_MODEL_ID_PATTERN: RegExp;
+/** Random v4 UUIDs, for correlating two events of one request. */
+export declare const RANDOM_REQUEST_ID_PATTERN: RegExp;
+export declare const HTTP_STATUS_RANGE: readonly [number, number];
+/** Returns null when the event is not in the catalog: unknown events are never sent. */
+export declare function sanitizeEventProperties(catalog: EventCatalog, event: string, properties: Readonly<Record<string, unknown>> | null | undefined): SanitizedProperties | null;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,sEAAsE;AACtE,MAAM,MAAM,WAAW,GAAG;IACxB,6BAA6B;IAC7B,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,0CAA0C;IAC1C,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACvD,oDAAoD;IACpD,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5C,8DAA8D;IAC9D,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CAC9D,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;AAEjE,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAE5E,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,QAAwD,CAAC;AAC7F,kEAAkE;AAClE,eAAO,MAAM,yBAAyB,QAA2E,CAAC;AAClH,eAAO,MAAM,iBAAiB,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAc,CAAC;AAEvE,wFAAwF;AACxF,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GAC/D,mBAAmB,GAAG,IAAI,CA+B5B"}

package/dist/sanitize.js

@@ -0,0 +1,59 @@
+/**
+ * The privacy boundary. Every property of every event passes through here:
+ * - keys not on the event's allowlist are dropped;
+ * - a key with allowed values or a pattern takes only strings, and a key
+ *   with a range only numbers: a value of another type is dropped;
+ * - string values with a validator must be one of its values;
+ * - strings without one are truncated to 64 characters (and may be pattern-checked);
+ * - numbers are rounded and bounded; booleans pass; anything else is dropped.
+ */
+export const MAX_STRING_LENGTH = 64;
+/** Public model ids: a conservative slug, or the fixed placeholder. */
+export const PUBLIC_MODEL_ID_PATTERN = /^(?:custom_or_unknown|[a-z0-9][a-z0-9._:/-]{0,63})$/;
+/** Random v4 UUIDs, for correlating two events of one request. */
+export const RANDOM_REQUEST_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export const HTTP_STATUS_RANGE = [100, 599];
+/** Returns null when the event is not in the catalog: unknown events are never sent. */
+export function sanitizeEventProperties(catalog, event, properties) {
+    const schema = catalog[event];
+    if (!schema)
+        return null;
+    const out = {};
+    for (const [key, value] of Object.entries(properties ?? {})) {
+        if (!schema.keys.has(key))
+            continue;
+        const stringOnly = schema.values?.[key] !== undefined || schema.patterns?.[key] !== undefined;
+        const numberOnly = schema.ranges?.[key] !== undefined;
+        if (stringOnly && typeof value !== 'string')
+            continue;
+        if (numberOnly && typeof value !== 'number')
+            continue;
+        if (typeof value === 'boolean') {
+            out[key] = value;
+        }
+        else if (typeof value === 'number') {
+            if (!Number.isFinite(value))
+                continue;
+            const range = schema.ranges?.[key];
+            if (range) {
+                if (!Number.isInteger(value) || value < range[0] || value > range[1])
+                    continue;
+                out[key] = value;
+                continue;
+            }
+            out[key] = Math.round(Math.max(-Number.MAX_SAFE_INTEGER, Math.min(Number.MAX_SAFE_INTEGER, value)));
+        }
+        else if (typeof value === 'string') {
+            const allowed = schema.values?.[key];
+            if (allowed && !allowed.has(value))
+                continue;
+            const pattern = schema.patterns?.[key];
+            if (pattern && !pattern.test(value))
+                continue;
+            out[key] = value.length > MAX_STRING_LENGTH ? value.slice(0, MAX_STRING_LENGTH) : value;
+        }
+        // Objects, arrays, null, undefined and functions are dropped.
+    }
+    return out;
+}
+//# sourceMappingURL=sanitize.js.map

package/dist/sanitize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../src/sanitize.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@antseed/telemetry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Privacy-safe product telemetry shared by the Antseed desktop app, gateway and buyer: buckets, failure classifiers, a strict sanitizer, consent resolution and a bounded PostHog transport",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "prebuild": "node ../../scripts/remove-paths.mjs dist",
+    "build": "tsc",
+    "test": "node ../../scripts/remove-paths.mjs test-dist && tsc -p tsconfig.test.json && node --test test-dist/*.test.js",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.