@chatcops/store-redis 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CoderCops
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @chatcops/store-redis
 
-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.
+Redis storage adapter for ChatCops supporting both `@upstash/redis` (HTTP / serverless) and `ioredis` (TCP / persistent connections).
+
+Implements all four ChatCops storage interfaces:
+- **conversations**: metadata in Redis hashes, messages as JSON lists, conversation IDs in a sorted set ordered by `updated_at`, with atomic version-checked appends, updates, removals, listing, and purging.
+- **counters**: atomic increments with fixed TTL reset for rate limits and budgets.
+- **kv**: JSON key-value store with `setIfAbsent` (`NX`) for distributed locking.
+- **events**: analytics event collection and querying.
+
+## Installation
+
+```bash
+npm install @chatcops/store-redis
+```
+
+For Upstash / serverless:
+```bash
+npm install @upstash/redis
+```
+
+For standalone Redis (Node.js runtime):
+```bash
+npm install ioredis
+```
+
+## Setup on Vercel
+
+### 1. Using `@upstash/redis` (Recommended for Edge / Serverless)
+
+The `@upstash/redis` client communicates over HTTP REST, making it ideal for Vercel Serverless and Edge Functions without persistent TCP connection limits:
+
+```typescript
+import { Redis } from '@upstash/redis';
+import { redisStorage } from '@chatcops/store-redis';
+import { chatcopsVercelHandler } from '@chatcops/server';
+
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+});
+
+const storage = redisStorage({
+  redis,
+  prefix: 'chatcops', // default: 'chatcops'
+  conversationTtlMs: 30 * 24 * 60 * 60 * 1000, // default: 30 days
+});
+
+export const POST = chatcopsVercelHandler({
+  storage,
+  provider: { type: 'openai', apiKey: process.env.OPENAI_API_KEY },
+  systemPrompt: 'You are a helpful assistant.',
+});
+```
+
+### 2. Using `ioredis` via `fromIoRedis` (Node.js Serverless Functions)
+
+When connecting directly to a standard Redis instance (or Redis cluster / Valkey) in Vercel Node.js Serverless Functions:
+
+```typescript
+import RedisIo from 'ioredis';
+import { fromIoRedis, redisStorage } from '@chatcops/store-redis';
+import { chatcopsVercelHandler } from '@chatcops/server';
+
+// Reuse connection across warm lambda invocations
+const io = new RedisIo(process.env.REDIS_URL!, {
+  maxRetriesPerRequest: 3,
+});
+
+const storage = redisStorage({
+  redis: fromIoRedis(io),
+  prefix: 'chatcops',
+});
+
+export const POST = chatcopsVercelHandler({
+  storage,
+  provider: { type: 'openai', apiKey: process.env.OPENAI_API_KEY },
+  systemPrompt: 'You are a helpful assistant.',
+});
+```
+
+## Options
+
+`redisStorage({ redis, prefix, conversationTtlMs })`
+
+- `redis`: Either a `@upstash/redis` client instance or an adapter created with `fromIoRedis(ioClient)`.
+- `prefix` (optional, default `'chatcops'`): Key prefix applied to all Redis keys for multi-tenant and environment isolation.
+- `conversationTtlMs` (optional, default 30 days): TTL applied to conversation keys (`PEXPIRE`).
+
+## Events Architecture: Hourly Count Hashes
+
+Analytics events are stored using **hourly count hashes** rather than capped streams (`XADD`).
+
+- **Why hourly count hashes over streams**: Redis Streams enforce strictly increasing entry IDs, which causes failures when events arrive out-of-order or with client timestamps in the past. Additionally, querying event counts aggregated by hour or day from a stream requires scanning and parsing historical stream logs client-side.
+- **Hourly count hashes**: Events are bucketed by UTC hour (`{<prefix>}:events:<hour>`) and tracked in a sorted set index (`{<prefix>}:events:hours`). Each hash stores counts keyed by event type (`HINCRBY`). Queries efficiently read only the active hour buckets within the query window and aggregate into hourly or daily totals directly.
+- **Hour-rounding query semantics**: Because events are pre-aggregated into 1-hour UTC buckets, queries round `from` down to the start of its UTC hour (`Math.floor(from / HOUR_MS) * HOUR_MS`) and `to` up to the end of its UTC hour (`Math.ceil(to / HOUR_MS) * HOUR_MS`), ensuring partial-hour queries accurately select all overlapping hourly buckets.
+
+## Redis Cluster Compatibility
+
+All keys generated for a given prefix share the `{<prefix>}` hash tag (e.g. `{chatcops}:conversations`, `{chatcops}:conv:<id>:meta`, `{chatcops}:events:hours`), ensuring all keys for that prefix reside in the same Redis Cluster hash slot while preserving isolation between prefixes. Every script-accessed key is explicitly passed through the `KEYS` array.

package/dist/adapter.d.ts

@@ -0,0 +1,30 @@
+import type { IoRedisLike, RedisLike } from './types.js';
+/**
+ * Safely decodes a result from an eval script or parses a JSON string.
+ * If the client (like @upstash/redis) already automatically deserialized the result
+ * from JSON, returns it directly. If it is a JSON string (like raw responses from ioredis),
+ * parses it into the target type.
+ */
+export declare function decodeEvalResult<T>(value: unknown): T;
+/**
+ * Consolidated internal alias for JSON string parsing.
+ */
+export declare const parseJson: typeof decodeEvalResult;
+/**
+ * Normalizes an unknown value into an array, falling back to an empty array
+ * if the value is nullish or was encoded as an empty table/object by Lua cjson.
+ */
+export declare function normalizeList<T>(value: unknown): T[];
+/**
+ * Formats a prefix into a stable Redis Cluster hash slot tag.
+ * Always wraps the prefix in braces so different prefixes like 'x' and '{x}'
+ * remain isolated while co-locating keys within each prefix into a single hash slot.
+ */
+export declare function formatSlotPrefix(prefix: string): string;
+/**
+ * Adapts an ioredis client instance into the minimal RedisLike interface compatible
+ * with @upstash/redis, correctly handling ioredis's eval(script, numKeys, ...keysAndArgs)
+ * signature and JSON value parsing.
+ */
+export declare function fromIoRedis(redis: IoRedisLike): RedisLike;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAmB,MAAM,YAAY,CAAC;AAE1E;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAUrD;AAED;;GAEG;AACH,eAAO,MAAM,SAAS,yBAAmB,CAAC;AAE1C;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,EAAE,CAGpD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,CAuDzD"}

package/dist/adapter.js

@@ -0,0 +1,96 @@
+/**
+ * Safely decodes a result from an eval script or parses a JSON string.
+ * If the client (like @upstash/redis) already automatically deserialized the result
+ * from JSON, returns it directly. If it is a JSON string (like raw responses from ioredis),
+ * parses it into the target type.
+ */
+export function decodeEvalResult(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string') {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    return value;
+}
+/**
+ * Consolidated internal alias for JSON string parsing.
+ */
+export const parseJson = decodeEvalResult;
+/**
+ * Normalizes an unknown value into an array, falling back to an empty array
+ * if the value is nullish or was encoded as an empty table/object by Lua cjson.
+ */
+export function normalizeList(value) {
+    if (Array.isArray(value))
+        return value;
+    return [];
+}
+/**
+ * Formats a prefix into a stable Redis Cluster hash slot tag.
+ * Always wraps the prefix in braces so different prefixes like 'x' and '{x}'
+ * remain isolated while co-locating keys within each prefix into a single hash slot.
+ */
+export function formatSlotPrefix(prefix) {
+    return `{${prefix}}`;
+}
+/**
+ * Adapts an ioredis client instance into the minimal RedisLike interface compatible
+ * with @upstash/redis, correctly handling ioredis's eval(script, numKeys, ...keysAndArgs)
+ * signature and JSON value parsing.
+ */
+export function fromIoRedis(redis) {
+    if (!redis) {
+        throw new TypeError('fromIoRedis requires a redis client instance');
+    }
+    return {
+        eval: async (script, keys = [], args = []) => {
+            const numKeys = keys.length;
+            const evalArgs = (args ?? []).map((a) => typeof a === 'number' ? a : String(a));
+            const res = await redis.eval(script, numKeys, ...keys, ...evalArgs);
+            return res;
+        },
+        get: async (key) => {
+            const raw = await redis.get(key);
+            if (raw === null || raw === undefined)
+                return null;
+            return parseJson(raw);
+        },
+        set: async (key, value, opts) => {
+            const valStr = typeof value === 'string' ? value : JSON.stringify(value);
+            const args = [];
+            if (opts?.ex !== undefined) {
+                args.push('EX', opts.ex);
+            }
+            else if (opts?.px !== undefined) {
+                args.push('PX', opts.px);
+            }
+            if (opts?.nx) {
+                args.push('NX');
+            }
+            else if (opts?.xx) {
+                args.push('XX');
+            }
+            if (opts?.keepttl) {
+                args.push('KEEPTTL');
+            }
+            return redis.set(key, valStr, ...args);
+        },
+        del: (...keys) => {
+            if (keys.length === 0)
+                return Promise.resolve(0);
+            return redis.del(...keys);
+        },
+        quit: () => (typeof redis.quit === 'function' ? redis.quit() : Promise.resolve()),
+        close: () => (typeof redis.quit === 'function' ? redis.quit() : Promise.resolve()),
+        disconnect: () => {
+            if (typeof redis.disconnect === 'function')
+                redis.disconnect();
+        },
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

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

package/dist/conversations.d.ts

@@ -0,0 +1,26 @@
+import { type AppendOptions, type ChatMessage, type Conversation, type ConversationStore, type ConversationSummary, type ListQuery } from '@chatcops/core';
+import type { RedisLike } from './types.js';
+export declare class RedisConversationStore implements ConversationStore {
+    private readonly redis;
+    private readonly zsetKey;
+    private readonly slotPrefix;
+    private readonly ttlMs;
+    constructor(redis: RedisLike, prefix: string, ttlMs: number);
+    private metaKey;
+    private messagesKey;
+    private serializeMetadata;
+    get(id: string): Promise<Conversation | null>;
+    save(conversation: Conversation): Promise<void>;
+    append(id: string, messages: ChatMessage[], options?: AppendOptions): Promise<{
+        version: number;
+    }>;
+    updateMessage(id: string, message: ChatMessage): Promise<boolean>;
+    removeMessage(id: string, messageId: string): Promise<boolean>;
+    delete(id: string): Promise<void>;
+    list(query: ListQuery): Promise<{
+        items: ConversationSummary[];
+        cursor?: string;
+    }>;
+    purge(before: number): Promise<number>;
+}
+//# sourceMappingURL=conversations.d.ts.map

package/dist/conversations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversations.d.ts","sourceRoot":"","sources":["../src/conversations.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,WAAW,EAEhB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA6W5C,qBAAa,sBAAuB,YAAW,iBAAiB;IAM5D,OAAO,CAAC,QAAQ,CAAC,KAAK;IALxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAGZ,KAAK,EAAE,SAAS,EACjC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM;IAOf,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,iBAAiB;IAWnB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAwD7C,IAAI,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAe/C,MAAM,CACV,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,WAAW,EAAE,EACvB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IA2BzB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAajE,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAY9D,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQjC,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA+GlF,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAsC7C"}