@oobe-protocol-labs/synapse-client-sdk 1.2.1 → 2.0.0

package/dist/esm/ai/persistence/index.js

@@ -0,0 +1,94 @@
+/**
+ * @module ai/persistence
+ * @description Synapse AI Persistence Layer — Redis, PostgreSQL, and in-memory
+ * adapters for long-term storage of agent snapshots, sessions, receipts,
+ * and metrics.
+ *
+ * ## Architecture
+ *
+ * All adapters implement the universal {@link PersistenceStore} interface
+ * **and** the `PersistenceAdapter` interface from {@link AgentRegistry},
+ * so they work everywhere:
+ *
+ * ```ts
+ * // As a standalone store
+ * const store = new RedisPersistence({ client: redis });
+ * await store.saveAgent(snapshot);
+ *
+ * // As AgentRegistry backend
+ * const registry = new AgentRegistry({ persistence: store });
+ * ```
+ *
+ * ## Adapters
+ *
+ * | Adapter | Backing store | Best for |
+ * |---|---|---|
+ * | {@link MemoryStore} | In-process `Map` | Testing, dev, CLI tools |
+ * | {@link RedisPersistence} | Redis / Valkey | Sessions, caching, pub/sub |
+ * | {@link PostgresPersistence} | PostgreSQL | Analytics, receipts, audit |
+ *
+ * ## Dependency injection
+ *
+ * Redis and PostgreSQL adapters accept a pre-configured client instance
+ * via their constructor config. No runtime dependencies are bundled —
+ * install `ioredis` or `pg` as needed.
+ *
+ * @example Redis quick start
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { RedisPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const store = new RedisPersistence({ client: redis, defaultTtl: 3600 });
+ * await store.connect();
+ *
+ * await store.saveAgent(gateway.snapshot());
+ * await store.saveSession(sessionRecord);
+ * await store.recordMetric('agent-1', 'calls', 42);
+ * ```
+ *
+ * @example PostgreSQL quick start
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { PostgresPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const store = new PostgresPersistence({ client: pool });
+ * await store.connect(); // auto-creates tables
+ *
+ * await store.saveAgent(gateway.snapshot());
+ * const receipts = await store.listReceipts('agent-1', { limit: 50 });
+ * const stats = await store.getTableStats();
+ * ```
+ *
+ * @example Dual-store pattern (Redis cache + PostgreSQL archive)
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { Pool } from 'pg';
+ * import { RedisPersistence, PostgresPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const cache   = new RedisPersistence({ client: new Redis(), defaultTtl: 300 });
+ * const archive = new PostgresPersistence({ client: new Pool() });
+ * await Promise.all([cache.connect(), archive.connect()]);
+ *
+ * // Write to both, read from cache first
+ * async function saveAgent(snapshot) {
+ *   await Promise.all([cache.saveAgent(snapshot), archive.saveAgent(snapshot)]);
+ * }
+ *
+ * async function loadAgent(id) {
+ *   return (await cache.loadAgent(id)) ?? archive.loadAgent(id);
+ * }
+ * ```
+ *
+ * @since 1.2.2
+ */
+/* ── Types ───────────────────────────────────────────────────── */
+export { PersistenceError, } from './types.js';
+/* ── Helpers ─────────────────────────────────────────────────── */
+export { serialize, deserialize, buildKey, parseKey, extractAgentId, buildSchema, buildKvCleanupSql, SCHEMA_VERSION, } from './helpers.js';
+/* ── Adapters ────────────────────────────────────────────────── */
+export { MemoryStore } from './memory.js';
+export { RedisPersistence } from './redis.js';
+export { PostgresPersistence } from './postgresql.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/ai/persistence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/ai/persistence/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAEH,oEAAoE;AACpE,OAAO,EACL,gBAAgB,GAcjB,MAAM,SAAS,CAAC;AAEjB,oEAAoE;AACpE,OAAO,EACL,SAAS,EACT,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,cAAc,GACf,MAAM,WAAW,CAAC;AAEnB,oEAAoE;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}

package/dist/esm/ai/persistence/memory.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @module ai/persistence/memory
+ * @description In-memory persistence store for Synapse AI gateway data.
+ *
+ * Ideal for testing, local development, and single-process deployments
+ * where external database infrastructure is unnecessary.
+ *
+ * Features:
+ * - TTL support on generic key-value entries
+ * - Optional max-entries eviction (FIFO)
+ * - Full {@link PersistenceStore} API
+ * - Drop-in `PersistenceAdapter` for {@link AgentRegistry}
+ *
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * import { MemoryStore } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const store = new MemoryStore();
+ * await store.connect();
+ *
+ * await store.saveAgent(gateway.snapshot());
+ * const snap = await store.loadAgent('agent-1');
+ * ```
+ */
+import type { PersistenceStore, MemoryStoreConfig, SetOptions, ListOptions, MetricQueryOpts, SessionRecord, ReceiptRecord, MetricPoint } from './types';
+import type { GatewaySnapshot } from '../gateway/types';
+/**
+ * @description In-memory implementation of {@link PersistenceStore}.
+ *
+ * Data is stored in `Map` instances and does **not** survive process restarts.
+ * TTL is checked lazily on read (no background timers).
+ *
+ * @since 1.2.2
+ */
+export declare class MemoryStore implements PersistenceStore {
+    readonly name = "memory";
+    private readonly maxEntries;
+    private readonly kv;
+    private readonly agents;
+    private readonly sessions;
+    private readonly receipts;
+    private readonly metrics;
+    constructor(config?: MemoryStoreConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, opts?: SetOptions): Promise<void>;
+    del(key: string): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    saveAgent(snapshot: GatewaySnapshot): Promise<void>;
+    loadAgent(agentId: string): Promise<GatewaySnapshot | null>;
+    deleteAgent(agentId: string): Promise<boolean>;
+    listAgents(): Promise<string[]>;
+    saveSession(record: SessionRecord): Promise<void>;
+    loadSession(agentId: string, sessionId: string): Promise<SessionRecord | null>;
+    deleteSessions(agentId: string): Promise<number>;
+    listSessions(agentId: string, opts?: ListOptions): Promise<SessionRecord[]>;
+    saveReceipt(record: ReceiptRecord): Promise<void>;
+    listReceipts(agentId: string, opts?: ListOptions): Promise<ReceiptRecord[]>;
+    recordMetric(agentId: string, key: string, value: number, labels?: Record<string, string>): Promise<void>;
+    queryMetrics(agentId: string, key: string, opts?: MetricQueryOpts): Promise<MetricPoint[]>;
+    save(agentId: string, snapshot: GatewaySnapshot): Promise<void>;
+    load(agentId: string): Promise<GatewaySnapshot | null>;
+    delete(agentId: string): Promise<void>;
+    keys(): Promise<string[]>;
+    private enforceEviction;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/esm/ai/persistence/memory.d.ts.map

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

package/dist/esm/ai/persistence/memory.js

@@ -0,0 +1,188 @@
+/**
+ * @module ai/persistence/memory
+ * @description In-memory persistence store for Synapse AI gateway data.
+ *
+ * Ideal for testing, local development, and single-process deployments
+ * where external database infrastructure is unnecessary.
+ *
+ * Features:
+ * - TTL support on generic key-value entries
+ * - Optional max-entries eviction (FIFO)
+ * - Full {@link PersistenceStore} API
+ * - Drop-in `PersistenceAdapter` for {@link AgentRegistry}
+ *
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * import { MemoryStore } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const store = new MemoryStore();
+ * await store.connect();
+ *
+ * await store.saveAgent(gateway.snapshot());
+ * const snap = await store.loadAgent('agent-1');
+ * ```
+ */
+import { serialize, deserialize } from './helpers.js';
+/**
+ * @description In-memory implementation of {@link PersistenceStore}.
+ *
+ * Data is stored in `Map` instances and does **not** survive process restarts.
+ * TTL is checked lazily on read (no background timers).
+ *
+ * @since 1.2.2
+ */
+export class MemoryStore {
+    name = 'memory';
+    maxEntries;
+    /* ── Storage maps ──────────────────────────────────────── */
+    kv = new Map();
+    agents = new Map();
+    sessions = new Map(); // key = agentId:sessionId
+    receipts = new Map(); // key = agentId
+    metrics = new Map(); // key = agentId:metricKey
+    constructor(config = {}) {
+        this.maxEntries = config.maxEntries ?? 0;
+    }
+    /* ── Lifecycle ─────────────────────────────────────────── */
+    async connect() { }
+    async disconnect() { }
+    async ping() { return true; }
+    /* ── Generic KV ────────────────────────────────────────── */
+    async get(key) {
+        const entry = this.kv.get(key);
+        if (!entry)
+            return null;
+        if (entry.expiresAt && Date.now() > entry.expiresAt) {
+            this.kv.delete(key);
+            return null;
+        }
+        return deserialize(entry.json);
+    }
+    async set(key, value, opts) {
+        this.enforceEviction();
+        const entry = { json: serialize(value) };
+        if (opts?.ttl && opts.ttl > 0) {
+            entry.expiresAt = Date.now() + opts.ttl * 1000;
+        }
+        this.kv.set(key, entry);
+    }
+    async del(key) {
+        return this.kv.delete(key);
+    }
+    async has(key) {
+        const entry = this.kv.get(key);
+        if (!entry)
+            return false;
+        if (entry.expiresAt && Date.now() > entry.expiresAt) {
+            this.kv.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /* ── Agents ────────────────────────────────────────────── */
+    async saveAgent(snapshot) {
+        this.agents.set(snapshot.agentId, snapshot);
+    }
+    async loadAgent(agentId) {
+        return this.agents.get(agentId) ?? null;
+    }
+    async deleteAgent(agentId) {
+        return this.agents.delete(agentId);
+    }
+    async listAgents() {
+        return [...this.agents.keys()];
+    }
+    /* ── Sessions ──────────────────────────────────────────── */
+    async saveSession(record) {
+        this.sessions.set(`${record.agentId}:${record.id}`, record);
+    }
+    async loadSession(agentId, sessionId) {
+        return this.sessions.get(`${agentId}:${sessionId}`) ?? null;
+    }
+    async deleteSessions(agentId) {
+        const prefix = `${agentId}:`;
+        let count = 0;
+        for (const key of this.sessions.keys()) {
+            if (key.startsWith(prefix)) {
+                this.sessions.delete(key);
+                count++;
+            }
+        }
+        return count;
+    }
+    async listSessions(agentId, opts = {}) {
+        const prefix = `${agentId}:`;
+        let results = [];
+        for (const [key, rec] of this.sessions) {
+            if (key.startsWith(prefix)) {
+                if (opts.status && rec.status !== opts.status)
+                    continue;
+                results.push(rec);
+            }
+        }
+        // Sort by createdAt descending
+        results.sort((a, b) => b.createdAt - a.createdAt);
+        const offset = opts.offset ?? 0;
+        const limit = opts.limit ?? results.length;
+        return results.slice(offset, offset + limit);
+    }
+    /* ── Receipts ──────────────────────────────────────────── */
+    async saveReceipt(record) {
+        const list = this.receipts.get(record.agentId) ?? [];
+        list.push(record);
+        this.receipts.set(record.agentId, list);
+    }
+    async listReceipts(agentId, opts = {}) {
+        const list = this.receipts.get(agentId) ?? [];
+        // Sort by settledAt descending (most recent first)
+        const sorted = [...list].sort((a, b) => b.settledAt - a.settledAt);
+        const offset = opts.offset ?? 0;
+        const limit = opts.limit ?? sorted.length;
+        return sorted.slice(offset, offset + limit);
+    }
+    /* ── Metrics ───────────────────────────────────────────── */
+    async recordMetric(agentId, key, value, labels) {
+        const mk = `${agentId}:${key}`;
+        const list = this.metrics.get(mk) ?? [];
+        list.push({ timestamp: Date.now(), value, labels });
+        this.metrics.set(mk, list);
+    }
+    async queryMetrics(agentId, key, opts = {}) {
+        const mk = `${agentId}:${key}`;
+        let points = this.metrics.get(mk) ?? [];
+        if (opts.from != null)
+            points = points.filter(p => p.timestamp >= opts.from);
+        if (opts.to != null)
+            points = points.filter(p => p.timestamp <= opts.to);
+        // Most recent first
+        points = [...points].sort((a, b) => b.timestamp - a.timestamp);
+        if (opts.limit != null)
+            points = points.slice(0, opts.limit);
+        return points;
+    }
+    /* ── PersistenceAdapter compat ─────────────────────────── */
+    async save(agentId, snapshot) {
+        return this.saveAgent(snapshot);
+    }
+    async load(agentId) {
+        return this.loadAgent(agentId);
+    }
+    async delete(agentId) {
+        this.agents.delete(agentId);
+    }
+    async keys() {
+        return this.listAgents();
+    }
+    /* ── Internals ─────────────────────────────────────────── */
+    enforceEviction() {
+        if (this.maxEntries > 0 && this.kv.size >= this.maxEntries) {
+            // FIFO: remove the oldest key
+            const firstKey = this.kv.keys().next().value;
+            if (firstKey)
+                this.kv.delete(firstKey);
+        }
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/esm/ai/persistence/memory.js.map

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

package/dist/esm/ai/persistence/postgresql.d.ts

@@ -0,0 +1,119 @@
+/**
+ * @module ai/persistence/postgresql
+ * @description PostgreSQL persistence adapter for Synapse AI gateway data.
+ *
+ * Stores agent snapshots, sessions, receipts, and metric time-series in
+ * PostgreSQL using JSONB columns, with automatic schema migration on
+ * first `connect()`.
+ *
+ * Bring your own client — the adapter works with any library that satisfies
+ * the {@link PgLike} interface:
+ * - **pg** (`new Pool()` or `new Client()`)
+ * - **@vercel/postgres** (`createPool()`)
+ * - **@neondatabase/serverless** (`neon()`)
+ *
+ * @since 1.2.2
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { PostgresPersistence } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const store = new PostgresPersistence({ client: pool });
+ * await store.connect(); // runs migrations
+ *
+ * await store.saveAgent(gateway.snapshot());
+ * const receipts = await store.listReceipts('agent-1', { limit: 50 });
+ *
+ * // Drop-in for AgentRegistry:
+ * const registry = new AgentRegistry({ persistence: store });
+ * ```
+ */
+import type { PersistenceStore, PostgresStoreConfig, SetOptions, ListOptions, MetricQueryOpts, SessionRecord, ReceiptRecord, MetricPoint } from './types';
+import type { GatewaySnapshot } from '../gateway/types';
+/**
+ * @description PostgreSQL implementation of {@link PersistenceStore}.
+ *
+ * Table layout (default prefix `synapse`):
+ * ```
+ * synapse_agents          (agent_id PK, snapshot JSONB)
+ * synapse_sessions        (agent_id + id PK, state JSONB, status)
+ * synapse_receipts        (id PK, agent_id, receipt JSONB)
+ * synapse_metrics         (id BIGSERIAL, agent_id, metric_key, value, labels, recorded_at)
+ * synapse_kv              (key PK, value JSONB, expires_at)
+ * synapse_schema_version  (version PK, applied_at)
+ * ```
+ *
+ * @since 1.2.2
+ */
+export declare class PostgresPersistence implements PersistenceStore {
+    readonly name = "postgresql";
+    private readonly client;
+    private readonly prefix;
+    private readonly autoMigrate;
+    private migrated;
+    constructor(config: PostgresStoreConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    /**
+     * @description Run schema migrations.
+     *
+     * Called automatically on `connect()` if `autoMigrate` is `true` (default).
+     * Safe to call multiple times — all DDL uses `IF NOT EXISTS`.
+     *
+     * @since 1.2.2
+     */
+    migrate(): Promise<void>;
+    private t;
+    get<T = unknown>(key: string): Promise<T | null>;
+    set(key: string, value: unknown, opts?: SetOptions): Promise<void>;
+    del(key: string): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    saveAgent(snapshot: GatewaySnapshot): Promise<void>;
+    loadAgent(agentId: string): Promise<GatewaySnapshot | null>;
+    deleteAgent(agentId: string): Promise<boolean>;
+    listAgents(): Promise<string[]>;
+    saveSession(record: SessionRecord): Promise<void>;
+    loadSession(agentId: string, sessionId: string): Promise<SessionRecord | null>;
+    deleteSessions(agentId: string): Promise<number>;
+    listSessions(agentId: string, opts?: ListOptions): Promise<SessionRecord[]>;
+    saveReceipt(record: ReceiptRecord): Promise<void>;
+    listReceipts(agentId: string, opts?: ListOptions): Promise<ReceiptRecord[]>;
+    recordMetric(agentId: string, key: string, value: number, labels?: Record<string, string>): Promise<void>;
+    queryMetrics(agentId: string, key: string, opts?: MetricQueryOpts): Promise<MetricPoint[]>;
+    /**
+     * @description Delete expired KV entries and old metric data.
+     *
+     * Call periodically (e.g. via a cron job) to reclaim storage.
+     *
+     * @param {object} [opts] - Cleanup options
+     * @param {number} [opts.metricsOlderThanDays=90] - Delete metrics older than N days
+     * @returns {Promise<{ kvDeleted: number; metricsDeleted: number }>}
+     * @since 1.2.2
+     */
+    cleanup(opts?: {
+        metricsOlderThanDays?: number;
+    }): Promise<{
+        kvDeleted: number;
+        metricsDeleted: number;
+    }>;
+    /**
+     * @description Get the currently applied schema version.
+     * @returns {Promise<number>} Schema version, or `0` if not yet migrated.
+     * @since 1.2.2
+     */
+    getSchemaVersion(): Promise<number>;
+    /**
+     * @description Get row counts for all tables (useful for monitoring).
+     * @returns {Promise<Record<string, number>>} Table name → row count
+     * @since 1.2.2
+     */
+    getTableStats(): Promise<Record<string, number>>;
+    save(agentId: string, snapshot: GatewaySnapshot): Promise<void>;
+    load(agentId: string): Promise<GatewaySnapshot | null>;
+    delete(agentId: string): Promise<void>;
+    keys(): Promise<string[]>;
+}
+//# sourceMappingURL=postgresql.d.ts.map

package/dist/esm/ai/persistence/postgresql.d.ts.map

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