@betterdb/semantic-cache 0.7.0 → 0.8.0

package/dist/analytics.d.ts

@@ -11,14 +11,35 @@ export interface ValkeyLike {
 export interface Analytics {
     init(client: ValkeyLike, name: string, configProps?: Record<string, unknown>): Promise<void>;
     capture(event: string, properties?: Record<string, unknown>): void;
+    flush(): Promise<void>;
     shutdown(): Promise<void>;
 }
 export interface AnalyticsOptions {
-    apiKey?: string;
-    host?: string;
     disabled?: boolean;
     /** Interval in ms for periodic stats snapshots. Default: 300_000 (5 min). 0 to disable. */
     statsIntervalMs?: number;
 }
 export declare const NOOP_ANALYTICS: Analytics;
+type PostHogClient = {
+    capture: (opts: {
+        distinctId?: string;
+        event: string;
+        properties?: Record<string, unknown>;
+    }) => void;
+    flush: () => Promise<void>;
+    shutdown: () => Promise<void>;
+};
+export declare class PostHogAnalytics implements Analytics {
+    private posthog;
+    private distinctId;
+    private deploymentId;
+    private readonly flushOnExit;
+    constructor(posthog: PostHogClient);
+    init(client: ValkeyLike, name: string, configProps?: Record<string, unknown>): Promise<void>;
+    private resolveDeploymentId;
+    capture(event: string, properties?: Record<string, unknown>): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
 export declare function createAnalytics(opts?: AnalyticsOptions): Promise<Analytics>;
+export {};

package/dist/analytics.js

@@ -39,8 +39,11 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NOOP_ANALYTICS = void 0;
+exports.PostHogAnalytics = exports.NOOP_ANALYTICS = void 0;
 exports.createAnalytics = createAnalytics;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
 const EVENT_PREFIX = 'semantic_cache:';
 // Build-time placeholders — replaced by scripts/inject-telemetry-defaults.mjs
 // When the placeholder is NOT replaced, the startsWith('__') guard treats it as unset.
@@ -49,41 +52,126 @@ const BAKED_POSTHOG_HOST = '__BETTERDB_POSTHOG_HOST__';
 exports.NOOP_ANALYTICS = {
     async init() { },
     capture() { },
+    async flush() { },
     async shutdown() { },
 };
 function isTelemetryOptedOut() {
     const val = process.env.BETTERDB_TELEMETRY;
     return val !== undefined && ['false', '0', 'no', 'off'].includes(val.toLowerCase());
 }
+const INSTALL_ID_ENV = 'BETTERDB_INSTANCE_ID';
+// Holds a minted id for the rest of the process when persistence fails, so
+// repeated calls (or parallel init) return one stable ephemeral identity.
+let ephemeralInstallId;
+function installIdPath() {
+    const base = process.env.XDG_STATE_HOME;
+    const root = base ? base : (0, node_path_1.join)((0, node_os_1.homedir)(), '.betterdb');
+    return (0, node_path_1.join)(root, 'instance_id');
+}
+/**
+ * Stable per-install identity for product analytics. Persisted on the local
+ * machine (not in Valkey), so a fleet of processes sharing one Valkey is
+ * counted as many installs rather than collapsing to one. Pin it via
+ * BETTERDB_INSTANCE_ID for ephemeral containers that would otherwise mint a
+ * fresh id every run. Falls back to an ephemeral per-process id when no
+ * writable location is available.
+ */
+function getInstallId() {
+    const override = process.env[INSTALL_ID_ENV];
+    if (override)
+        return override;
+    const path = installIdPath();
+    try {
+        const existing = (0, node_fs_1.readFileSync)(path, 'utf8').trim();
+        if (existing)
+            return existing;
+    }
+    catch {
+        // no existing id
+    }
+    const newId = ephemeralInstallId ?? crypto.randomUUID();
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+        (0, node_fs_1.writeFileSync)(path, newId);
+    }
+    catch {
+        // Persistence failed — hold the id for the rest of this process so
+        // repeated calls return a stable ephemeral identity.
+        ephemeralInstallId = newId;
+    }
+    return newId;
+}
 class PostHogAnalytics {
     posthog;
     distinctId = '';
+    deploymentId = '';
+    // Library consumers are frequently short-lived scripts that never call
+    // shutdown(), so PostHog's buffered events (flushAt=20, flushInterval=10s)
+    // would be dropped when the process exits before the queue drains. Flush
+    // when the event loop empties so lifecycle events are actually delivered.
+    // Only enabled instances reach here — the opt-out path returns
+    // NOOP_ANALYTICS and registers nothing, keeping disabled consumers silent.
+    flushOnExit = () => {
+        void this.flush();
+    };
     constructor(posthog) {
         this.posthog = posthog;
+        process.once('beforeExit', this.flushOnExit);
     }
     async init(client, name, configProps) {
+        this.distinctId = getInstallId();
+        this.deploymentId = await this.resolveDeploymentId(client, name);
+        const merged = { ...(configProps ?? {}) };
+        if (this.deploymentId)
+            merged.deployment_id = this.deploymentId;
+        this.capture('cache_init', merged);
+        // Flush the start event immediately so it lands even for processes that exit
+        // before the flush interval or the beforeExit hook fires.
+        await this.flush();
+    }
+    async resolveDeploymentId(client, name) {
+        // The Valkey-scoped id groups all clients pointed at the same store, so a
+        // shared-Valkey fleet can still be rolled up into one deployment.
         const idKey = `${name}:__instance_id`;
-        let id = await client.get(idKey);
-        if (!id) {
-            id = crypto.randomUUID();
+        try {
+            const existing = await client.get(idKey);
+            if (existing)
+                return existing;
+            const id = crypto.randomUUID();
             await client.set(idKey, id);
+            return id;
+        }
+        catch {
+            return '';
         }
-        this.distinctId = id;
-        this.capture('cache_init', configProps);
     }
     capture(event, properties) {
         try {
+            const props = { ...(properties ?? {}) };
+            if (this.deploymentId && props.deployment_id === undefined) {
+                props.deployment_id = this.deploymentId;
+            }
             this.posthog.capture({
                 distinctId: this.distinctId,
                 event: `${EVENT_PREFIX}${event}`,
-                properties,
+                properties: props,
             });
         }
         catch {
             // never throw from analytics
         }
     }
+    async flush() {
+        try {
+            await this.posthog.flush();
+        }
+        catch {
+            // swallow
+        }
+    }
     async shutdown() {
+        // Explicit shutdown supersedes the beforeExit backstop.
+        process.removeListener('beforeExit', this.flushOnExit);
         try {
             await this.posthog.shutdown();
         }
@@ -92,18 +180,16 @@ class PostHogAnalytics {
         }
     }
 }
+exports.PostHogAnalytics = PostHogAnalytics;
 async function createAnalytics(opts) {
     if (opts?.disabled || isTelemetryOptedOut()) {
         return exports.NOOP_ANALYTICS;
     }
-    // Key resolution: opts.apiKey → BETTERDB_POSTHOG_API_KEY env var → baked wheel value
-    const bakedKey = BAKED_POSTHOG_API_KEY.startsWith('__') ? undefined : BAKED_POSTHOG_API_KEY;
-    const apiKey = opts?.apiKey ?? process.env.BETTERDB_POSTHOG_API_KEY ?? bakedKey;
+    const apiKey = BAKED_POSTHOG_API_KEY.startsWith('__') ? undefined : BAKED_POSTHOG_API_KEY;
     if (!apiKey) {
         return exports.NOOP_ANALYTICS;
     }
-    const bakedHost = BAKED_POSTHOG_HOST.startsWith('__') ? undefined : BAKED_POSTHOG_HOST;
-    const host = opts?.host ?? process.env.BETTERDB_POSTHOG_HOST ?? bakedHost;
+    const host = BAKED_POSTHOG_HOST.startsWith('__') ? undefined : BAKED_POSTHOG_HOST;
     try {
         // @ts-ignore — posthog-node is an optional peer dep
         const { PostHog } = await Promise.resolve().then(() => __importStar(require('posthog-node')));

package/dist/types.d.ts

@@ -90,10 +90,6 @@ export interface SemanticCacheOptions {
         registry?: Registry;
     };
     analytics?: {
-        /** PostHog API key. Overrides the build-time baked key if set. */
-        apiKey?: string;
-        /** PostHog host. Overrides the build-time baked host if set. */
-        host?: string;
         /** Disable analytics. Also controlled by BETTERDB_TELEMETRY env var. */
         disabled?: boolean;
         /** Interval in ms for periodic stats snapshots. Default: 300_000 (5 min). 0 to disable. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@betterdb/semantic-cache",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Valkey-native semantic cache for LLM applications with built-in OpenTelemetry and Prometheus instrumentation",
   "keywords": [
     "valkey",