@ecodrix/erix-client 1.0.1 → 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;
@@ -61,6 +61,32 @@ export interface EnqueueOptionsV2 {
     clientCode?: string;
     metadata?: Record<string, JsonValue>;
 }
+export interface CacheSetOptions {
+    /** TTL in milliseconds */
+    ttl?: number;
+    /** Tags for bulk invalidation */
+    tags?: string[];
+    /**
+     * Stale-While-Revalidate window in milliseconds.
+     * The server serves the old value for this duration after TTL expires
+     * while refreshing in the background.
+     */
+    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;
+    onCompleted?: (job: JobV2<T>) => void;
+    onFailed?: (job: JobV2<T>) => void;
+    onZombie?: (job: JobV2<T>) => void;
+    onError?: (err: Error) => void;
+}
 export declare class ErixClient {
     private readonly baseUrl;
     private readonly headers;
@@ -105,7 +131,7 @@ export declare class ErixClient {
         /** Dequeue the oldest job from a named queue. Returns `null` if empty. */
         pop: <T = JsonValue>(name: string) => Promise<T | null>;
     };
-    /** Advanced Queue (v2) — supports priority, delay, retries, and persistence */
+    /** Advanced Queue (v2) — supports priority, delay, retries, heartbeat, and SSE push */
     queueV2: {
         /** Enqueue a job into an advanced queue */
         push: <T = JsonValue>(queueName: string, data: T, options?: EnqueueOptionsV2) => Promise<JobV2<T>>;
@@ -117,12 +143,47 @@ export declare class ErixClient {
         fail: (jobId: string, error: string) => Promise<void>;
         /** Update job progress (0-100) */
         updateProgress: (jobId: string, progress: number) => Promise<void>;
+        /**
+         * Send a worker heartbeat to keep the job alive in the reaper.
+         * Call every 15–30 seconds from inside a long-running job handler.
+         * If silent for 60s the reaper will fail and requeue the job.
+         */
+        heartbeat: (jobId: string) => Promise<void>;
         /** Get job by ID */
         get: <T = JsonValue>(jobId: string) => Promise<JobV2<T> | null>;
+        /**
+         * Subscribe to queue events via Server-Sent Events.
+         * Returns an EventSource-like object — call `.close()` to unsubscribe.
+         *
+         * Workers should use this instead of polling `claim()` on an interval.
+         * On `job:added` or `job:active` events, call `claim()` to get the job.
+         *
+         * @example
+         * const sub = client.queueV2.subscribe('crm', {
+         *   onAdded: () => processNextJob(),
+         *   onError: (e) => console.error(e),
+         * });
+         * // later:
+         * sub.close();
+         */
+        subscribe: <T = JsonValue>(queueName: string, handlers: QueueEventHandlers<T>) => {
+            close: () => void;
+        };
     };
     pubsub: {
         /** Publish a message to a channel */
         publish: (channel: string, message: JsonValue) => Promise<void>;
+        /**
+         * Subscribe to a pub/sub channel via Server-Sent Events.
+         * Returns a controller with a `.close()` method.
+         *
+         * @example
+         * const sub = client.pubsub.subscribe('alerts', (msg) => console.log(msg));
+         * sub.close(); // unsubscribe
+         */
+        subscribe: (channel: string, onMessage: (message: JsonValue) => void, onError?: (err: Error) => void) => {
+            close: () => void;
+        };
     };
     /**
      * Check if an operation is within rate limits.
@@ -139,4 +200,100 @@ export declare class ErixClient {
         /** Get all members of a set */
         smembers: (key: string) => Promise<string[]>;
     };
+    cache: {
+        /** Get a cached value */
+        get: <T = JsonValue>(key: string) => Promise<T | null>;
+        /** Set a cached value with optional TTL, tags, and stale-while-revalidate */
+        set: (key: string, value: JsonValue, options?: CacheSetOptions) => Promise<void>;
+        /** Delete a cached key */
+        del: (key: string) => Promise<void>;
+        /** Invalidate all keys with a specific tag */
+        invalidateByTag: (tag: string) => Promise<number>;
+        /** Invalidate all keys matching multiple tags */
+        invalidateByTags: (tags: string[]) => Promise<number>;
+        /** 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.
+     *
+     * Uses native fetch with a ReadableStream reader — works in Node 18+.
+     */
+    private openEventStream;
 }

package/dist/index.js

@@ -90,7 +90,7 @@ export class ErixClient {
                 return this.list.lpop(`q:${name}`);
             },
         };
-        /** Advanced Queue (v2) — supports priority, delay, retries, and persistence */
+        /** Advanced Queue (v2) — supports priority, delay, retries, heartbeat, and SSE push */
         this.queueV2 = {
             /** Enqueue a job into an advanced queue */
             push: async (queueName, data, options = {}) => {
@@ -114,11 +114,49 @@ export class ErixClient {
             updateProgress: async (jobId, progress) => {
                 await this.req("PATCH", `/queue/v2/jobs/${jobId}/progress`, { progress });
             },
+            /**
+             * Send a worker heartbeat to keep the job alive in the reaper.
+             * Call every 15–30 seconds from inside a long-running job handler.
+             * If silent for 60s the reaper will fail and requeue the job.
+             */
+            heartbeat: async (jobId) => {
+                await this.req("PATCH", `/queue/v2/jobs/${jobId}/heartbeat`);
+            },
             /** Get job by ID */
             get: async (jobId) => {
                 const res = await this.req("GET", `/queue/v2/jobs/${jobId}`);
                 return res.job;
             },
+            /**
+             * Subscribe to queue events via Server-Sent Events.
+             * Returns an EventSource-like object — call `.close()` to unsubscribe.
+             *
+             * Workers should use this instead of polling `claim()` on an interval.
+             * On `job:added` or `job:active` events, call `claim()` to get the job.
+             *
+             * @example
+             * const sub = client.queueV2.subscribe('crm', {
+             *   onAdded: () => processNextJob(),
+             *   onError: (e) => console.error(e),
+             * });
+             * // later:
+             * sub.close();
+             */
+            subscribe: (queueName, handlers) => {
+                return this.openEventStream(`/queue/v2/${queueName}/events`, (event, data) => {
+                    const job = data;
+                    if (event === "job:added")
+                        handlers.onAdded?.(job);
+                    else if (event === "job:active")
+                        handlers.onActive?.(job);
+                    else if (event === "job:completed")
+                        handlers.onCompleted?.(job);
+                    else if (event === "job:failed")
+                        handlers.onFailed?.(job);
+                    else if (event === "job:zombie")
+                        handlers.onZombie?.(job);
+                }, handlers.onError);
+            },
         };
         // ─── PubSub ───────────────────────────────────────────────────────────
         this.pubsub = {
@@ -126,6 +164,17 @@ export class ErixClient {
             publish: async (channel, message) => {
                 await this.req("POST", "/pubsub/publish", { channel, message });
             },
+            /**
+             * Subscribe to a pub/sub channel via Server-Sent Events.
+             * Returns a controller with a `.close()` method.
+             *
+             * @example
+             * const sub = client.pubsub.subscribe('alerts', (msg) => console.log(msg));
+             * sub.close(); // unsubscribe
+             */
+            subscribe: (channel, onMessage, onError) => {
+                return this.openEventStream(`/pubsub/${encodeURIComponent(channel)}/stream`, (_event, data) => onMessage(data), onError);
+            },
         };
         // ─── Set ──────────────────────────────────────────────────────────────
         this.set_ = {
@@ -139,6 +188,139 @@ export class ErixClient {
                 return data.members;
             },
         };
+        // ─── Cache (advanced) ────────────────────────────────────────────────
+        this.cache = {
+            /** Get a cached value */
+            get: async (key) => {
+                try {
+                    const res = await this.req("GET", `/cache/${encodeURIComponent(key)}`);
+                    return res.value ?? null;
+                }
+                catch {
+                    return null;
+                }
+            },
+            /** Set a cached value with optional TTL, tags, and stale-while-revalidate */
+            set: async (key, value, options = {}) => {
+                await this.req("POST", `/cache/${encodeURIComponent(key)}`, {
+                    value,
+                    ...options,
+                });
+            },
+            /** Delete a cached key */
+            del: async (key) => {
+                await this.req("DELETE", `/cache/${encodeURIComponent(key)}`);
+            },
+            /** Invalidate all keys with a specific tag */
+            invalidateByTag: async (tag) => {
+                const res = await this.req("DELETE", `/cache/tags/${encodeURIComponent(tag)}`);
+                return res.count;
+            },
+            /** Invalidate all keys matching multiple tags */
+            invalidateByTags: async (tags) => {
+                const res = await this.req("POST", "/cache/tags/invalidate", { tags });
+                return res.count;
+            },
+            /** Get cache statistics (hit rate, size, evictions) */
+            stats: async () => {
+                const res = await this.req("GET", "/cache/_stats");
+                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 = {
@@ -223,4 +405,60 @@ export class ErixClient {
             window,
         });
     }
+    // ─── Internal SSE helper ─────────────────────────────────────────────
+    /**
+     * Opens a persistent SSE connection and dispatches named events to a handler.
+     * Returns a controller with `.close()` to terminate the connection.
+     *
+     * Uses native fetch with a ReadableStream reader — works in Node 18+.
+     */
+    openEventStream(path, onEvent, onError) {
+        const controller = new AbortController();
+        const url = `${this.baseUrl}${path}`;
+        const run = async () => {
+            try {
+                const res = await fetch(url, {
+                    headers: this.headers,
+                    signal: controller.signal,
+                });
+                if (!res.ok || !res.body) {
+                    throw new Error(`[erix-store] SSE ${path} → ${res.status}: ${res.statusText}`);
+                }
+                const reader = res.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = "";
+                let currentEvent = "message";
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const lines = buffer.split("\n");
+                    buffer = lines.pop() ?? "";
+                    for (const line of lines) {
+                        if (line.startsWith("event:")) {
+                            currentEvent = line.slice(6).trim();
+                        }
+                        else if (line.startsWith("data:")) {
+                            try {
+                                const data = JSON.parse(line.slice(5).trim());
+                                onEvent(currentEvent, data);
+                            }
+                            catch {
+                                // non-JSON data line, skip
+                            }
+                            currentEvent = "message";
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                if (!controller.signal.aborted) {
+                    onError?.(err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+        };
+        run();
+        return { close: () => controller.abort() };
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecodrix/erix-client",
-  "version": "1.0.1",
+  "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",