@ecodrix/erix-client 1.0.2 → 1.0.3

package/dist/index.d.ts

@@ -24,7 +24,7 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 export interface ErixClientOptions {
-    /** Full URL of the deployed erix-store instance, e.g. https://erix-store.onrender.com */
+    /** Full URL of the deployed erix-store instance, e.g. https://api.erix.ecodrix.com */
     baseUrl: string;
     /** Shared secret generated at deploy time — must match ERIX_API_KEY on the server */
     apiKey: string;
@@ -73,6 +73,12 @@ export interface CacheSetOptions {
      */
     staleFor?: number;
 }
+export interface SemanticGetResult<T = JsonValue> {
+    value: T;
+    key: string;
+    similarity: number;
+    isExact: boolean;
+}
 export interface QueueEventHandlers<T = JsonValue> {
     onAdded?: (job: JobV2<T>) => void;
     onActive?: (job: JobV2<T>) => void;
@@ -208,6 +214,81 @@ export declare class ErixClient {
         /** Get cache statistics (hit rate, size, evictions) */
         stats: () => Promise<unknown>;
     };
+    semantic: {
+        /**
+         * Store a value with its embedding for similarity lookups.
+         * @param key    Unique cache key
+         * @param text   Text to embed (the query/question this entry answers)
+         * @param value  The value to cache
+         * @param ttlMs  Optional TTL in milliseconds
+         * @param tags   Optional tags for bulk invalidation
+         */
+        set: (key: string, text: string, value: JsonValue, ttlMs?: number, tags?: string[]) => Promise<void>;
+        /**
+         * Exact key lookup in semantic cache.
+         */
+        get: <T = JsonValue>(key: string) => Promise<T | null>;
+        /**
+         * Find the most similar cached entry to a query string.
+         * Returns null if no entry exceeds the similarity threshold.
+         *
+         * @example
+         * // Stored: "What are your pricing plans?" → { starter: '$29', pro: '$99' }
+         * // Query:  "How much does it cost?"
+         * const result = await client.semantic.search("How much does it cost?");
+         * // → { value: {...}, similarity: 0.97, isExact: false }
+         */
+        search: <T = JsonValue>(query: string, threshold?: number) => Promise<SemanticGetResult<T> | null>;
+        /** Invalidate all semantic cache entries with a specific tag */
+        invalidateByTag: (tag: string) => Promise<number>;
+        /** Delete a single semantic cache entry */
+        del: (key: string) => Promise<void>;
+        /** Get semantic cache stats */
+        stats: () => Promise<{
+            success: boolean;
+            size: number;
+            keys: string[];
+        }>;
+    };
+    analytics: {
+        /**
+         * Get live usage counts for this tenant (from in-memory buffer).
+         * Updated in real time — no waiting for the 10s DB flush.
+         */
+        usage: () => Promise<Record<string, number>>;
+        /**
+         * Get anomaly detector stats — mean, stddev, and sample count
+         * for each monitored metric of this tenant.
+         */
+        anomalies: () => Promise<{
+            success: boolean;
+            metrics: Array<{
+                metric: string;
+                mean: number;
+                stddev: number;
+                n: number;
+            }>;
+        }>;
+        /**
+         * Subscribe to real-time anomaly alerts via SSE.
+         * The server fires an event whenever a metric exceeds 3σ.
+         *
+         * @example
+         * const sub = client.analytics.subscribeAlerts((alert) => {
+         *   console.log(`ALERT: ${alert.message}`);
+         * });
+         * sub.close();
+         */
+        subscribeAlerts: (onAlert: (alert: {
+            metric: string;
+            current: number;
+            mean: number;
+            zScore: number;
+            message: string;
+        }) => void, onError?: (err: Error) => void) => {
+            close: () => void;
+        };
+    };
     /**
      * Opens a persistent SSE connection and dispatches named events to a handler.
      * Returns a controller with `.close()` to terminate the connection.

package/dist/index.js

@@ -227,6 +227,100 @@ export class ErixClient {
                 return res.stats;
             },
         };
+        // ─── Semantic Cache (AI layer) ────────────────────────────────────────
+        this.semantic = {
+            /**
+             * Store a value with its embedding for similarity lookups.
+             * @param key    Unique cache key
+             * @param text   Text to embed (the query/question this entry answers)
+             * @param value  The value to cache
+             * @param ttlMs  Optional TTL in milliseconds
+             * @param tags   Optional tags for bulk invalidation
+             */
+            set: async (key, text, value, ttlMs, tags) => {
+                await this.req("POST", `/semantic/${encodeURIComponent(key)}`, {
+                    text,
+                    value,
+                    ttlMs,
+                    tags,
+                });
+            },
+            /**
+             * Exact key lookup in semantic cache.
+             */
+            get: async (key) => {
+                try {
+                    const res = await this.req("GET", `/semantic/${encodeURIComponent(key)}`);
+                    return res.value ?? null;
+                }
+                catch {
+                    return null;
+                }
+            },
+            /**
+             * Find the most similar cached entry to a query string.
+             * Returns null if no entry exceeds the similarity threshold.
+             *
+             * @example
+             * // Stored: "What are your pricing plans?" → { starter: '$29', pro: '$99' }
+             * // Query:  "How much does it cost?"
+             * const result = await client.semantic.search("How much does it cost?");
+             * // → { value: {...}, similarity: 0.97, isExact: false }
+             */
+            search: async (query, threshold) => {
+                try {
+                    const res = await this.req("POST", "/semantic/search", { query, threshold });
+                    return res;
+                }
+                catch {
+                    return null;
+                }
+            },
+            /** Invalidate all semantic cache entries with a specific tag */
+            invalidateByTag: async (tag) => {
+                const res = await this.req("DELETE", `/semantic/tags/${encodeURIComponent(tag)}`);
+                return res.count;
+            },
+            /** Delete a single semantic cache entry */
+            del: async (key) => {
+                await this.req("DELETE", `/semantic/${encodeURIComponent(key)}`);
+            },
+            /** Get semantic cache stats */
+            stats: async () => {
+                return this.req("GET", "/semantic/_stats");
+            },
+        };
+        // ─── Analytics ────────────────────────────────────────────────────────
+        this.analytics = {
+            /**
+             * Get live usage counts for this tenant (from in-memory buffer).
+             * Updated in real time — no waiting for the 10s DB flush.
+             */
+            usage: async () => {
+                const res = await this.req("GET", "/analytics/usage");
+                return res.usage;
+            },
+            /**
+             * Get anomaly detector stats — mean, stddev, and sample count
+             * for each monitored metric of this tenant.
+             */
+            anomalies: async () => {
+                return this.req("GET", "/analytics/anomalies");
+            },
+            /**
+             * Subscribe to real-time anomaly alerts via SSE.
+             * The server fires an event whenever a metric exceeds 3σ.
+             *
+             * @example
+             * const sub = client.analytics.subscribeAlerts((alert) => {
+             *   console.log(`ALERT: ${alert.message}`);
+             * });
+             * sub.close();
+             */
+            subscribeAlerts: (onAlert, onError) => {
+                return this.openEventStream("/analytics/anomalies/stream", (_event, data) => onAlert(data), onError);
+            },
+        };
         this.baseUrl = options.baseUrl.replace(/\/$/, ""); // strip trailing slash
         this.timeoutMs = options.timeoutMs ?? 5000;
         this.headers = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecodrix/erix-client",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Type-safe HTTP client for the erix-store in-memory data service. Zero dependencies — uses native fetch.",
   "type": "module",
   "main": "./dist/index.js",