@hexis-ai/engram-server 0.1.4 → 0.1.5

package/dist/adapters/memory-key-store.d.ts

@@ -0,0 +1,24 @@
+import { type ApiKeyInfo, type IssuedKey, type KeyResolution, type KeyStore, type Workspace } from "../key-store";
+/**
+ * In-process KeyStore for tests and single-node dev. Volatile.
+ */
+export declare class InMemoryKeyStore implements KeyStore {
+    private readonly workspaces;
+    private readonly keys;
+    private readonly byHash;
+    createWorkspace(input: {
+        id?: string;
+        name?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Workspace>;
+    getWorkspace(id: string): Promise<Workspace | null>;
+    listWorkspaces(): Promise<Workspace[]>;
+    deleteWorkspace(id: string): Promise<void>;
+    issueKey(workspaceId: string, opts?: {
+        name?: string;
+    }): Promise<IssuedKey>;
+    listKeys(workspaceId: string): Promise<ApiKeyInfo[]>;
+    revokeKey(workspaceId: string, keyId: string): Promise<void>;
+    resolveKey(rawKey: string): Promise<KeyResolution | null>;
+    registerLegacyKey(workspaceId: string, rawKey: string, name?: string): Promise<void>;
+}

package/dist/adapters/memory-key-store.js

@@ -0,0 +1,108 @@
+import { generateRawKey, hashKey, isValidWorkspaceId, keyPrefix, } from "../key-store";
+/**
+ * In-process KeyStore for tests and single-node dev. Volatile.
+ */
+export class InMemoryKeyStore {
+    workspaces = new Map();
+    keys = new Map();
+    byHash = new Map();
+    async createWorkspace(input) {
+        const id = input.id ?? crypto.randomUUID();
+        if (!isValidWorkspaceId(id))
+            throw new Error("invalid_workspace_id");
+        const existing = this.workspaces.get(id);
+        if (existing)
+            return existing;
+        const ws = {
+            id,
+            ...(input.name !== undefined ? { name: input.name } : {}),
+            ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+            createdAt: new Date().toISOString(),
+        };
+        this.workspaces.set(id, ws);
+        return ws;
+    }
+    async getWorkspace(id) {
+        return this.workspaces.get(id) ?? null;
+    }
+    async listWorkspaces() {
+        return [...this.workspaces.values()].sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    }
+    async deleteWorkspace(id) {
+        this.workspaces.delete(id);
+        for (const [keyId, row] of this.keys) {
+            if (row.workspaceId === id) {
+                this.byHash.delete(row.keyHash);
+                this.keys.delete(keyId);
+            }
+        }
+    }
+    async issueKey(workspaceId, opts = {}) {
+        if (!this.workspaces.has(workspaceId))
+            throw new Error("workspace_not_found");
+        const raw = generateRawKey();
+        const row = {
+            id: crypto.randomUUID(),
+            workspaceId,
+            keyHash: hashKey(raw),
+            prefix: keyPrefix(raw),
+            ...(opts.name !== undefined ? { name: opts.name } : {}),
+            createdAt: new Date().toISOString(),
+        };
+        this.keys.set(row.id, row);
+        this.byHash.set(row.keyHash, row.id);
+        return { ...toInfo(row), raw };
+    }
+    async listKeys(workspaceId) {
+        return [...this.keys.values()]
+            .filter((r) => r.workspaceId === workspaceId)
+            .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+            .map(toInfo);
+    }
+    async revokeKey(workspaceId, keyId) {
+        const row = this.keys.get(keyId);
+        if (!row || row.workspaceId !== workspaceId)
+            throw new Error("key_not_found");
+        if (row.revokedAt)
+            return;
+        this.keys.set(keyId, { ...row, revokedAt: new Date().toISOString() });
+    }
+    async resolveKey(rawKey) {
+        const id = this.byHash.get(hashKey(rawKey));
+        if (!id)
+            return null;
+        const row = this.keys.get(id);
+        if (!row || row.revokedAt)
+            return null;
+        this.keys.set(id, { ...row, lastUsedAt: new Date().toISOString() });
+        return { workspaceId: row.workspaceId, keyId: row.id };
+    }
+    async registerLegacyKey(workspaceId, rawKey, name) {
+        if (!this.workspaces.has(workspaceId))
+            throw new Error("workspace_not_found");
+        const hash = hashKey(rawKey);
+        if (this.byHash.has(hash))
+            return;
+        const row = {
+            id: crypto.randomUUID(),
+            workspaceId,
+            keyHash: hash,
+            prefix: keyPrefix(rawKey),
+            ...(name !== undefined ? { name } : {}),
+            createdAt: new Date().toISOString(),
+        };
+        this.keys.set(row.id, row);
+        this.byHash.set(hash, row.id);
+    }
+}
+function toInfo(row) {
+    return {
+        id: row.id,
+        workspaceId: row.workspaceId,
+        prefix: row.prefix,
+        ...(row.name !== undefined ? { name: row.name } : {}),
+        createdAt: row.createdAt,
+        ...(row.lastUsedAt !== undefined ? { lastUsedAt: row.lastUsedAt } : {}),
+        ...(row.revokedAt !== undefined ? { revokedAt: row.revokedAt } : {}),
+    };
+}

package/dist/adapters/memory.d.ts

@@ -1,12 +1,19 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import type { PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
 import { type StorageAdapter } from "../storage";
+export interface InMemoryAdapterOptions {
+    /** Override for tests. Default: `p_${random}` with 8 chars. */
+    newPersonId?: () => string;
+}
 /**
  * In-process storage adapter for tests, dev, and small single-node deploys.
  * Idempotency: events keyed by (sessionId, seq) — duplicates overwrite by seq.
  */
 export declare class InMemoryAdapter implements StorageAdapter {
     private readonly sessions;
+    private readonly persons;
+    private readonly newPersonId;
+    constructor(opts?: InMemoryAdapterOptions);
     createSession(init: SessionInit & {
         id: string;
         createdAt: string;
@@ -17,4 +24,18 @@ export declare class InMemoryAdapter implements StorageAdapter {
         limit: number;
         channel?: string;
     }): Promise<Session[]>;
+    sessionsForPerson(personId: string, opts: {
+        limit: number;
+        channel?: string;
+        scope?: "participant" | "viewable";
+    }): Promise<Session[]>;
+    createPerson(input: PersonCreate): Promise<PersonInfo>;
+    upsertPerson(id: string, input: PersonCreate): Promise<PersonInfo>;
+    updatePerson(id: string, patch: PersonUpdate): Promise<PersonInfo | null>;
+    getPerson(id: string): Promise<PersonInfo | null>;
+    getPersons(ids: string[]): Promise<PersonInfo[]>;
+    listPersons(opts: {
+        limit: number;
+        q?: string;
+    }): Promise<PersonInfo[]>;
 }

package/dist/adapters/memory.js

@@ -1,19 +1,37 @@
 import { foldEvents } from "../storage";
+function defaultPersonId() {
+    const ALPHA = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let out = "p_";
+    for (let i = 0; i < 8; i++)
+        out += ALPHA[Math.floor(Math.random() * ALPHA.length)];
+    return out;
+}
 /**
  * In-process storage adapter for tests, dev, and small single-node deploys.
  * Idempotency: events keyed by (sessionId, seq) — duplicates overwrite by seq.
  */
 export class InMemoryAdapter {
     sessions = new Map();
+    persons = new Map();
+    newPersonId;
+    constructor(opts = {}) {
+        this.newPersonId = opts.newPersonId ?? defaultPersonId;
+    }
+    // --- Sessions -----------------------------------------------------
     async createSession(init) {
         if (this.sessions.has(init.id))
             return;
+        const participants = init.participants ?? [];
+        const viewable_by = init.viewable_by
+            ? Array.from(new Set([...init.viewable_by, ...participants]))
+            : [...participants];
         this.sessions.set(init.id, {
             row: {
                 id: init.id,
                 ...(init.title ? { title: init.title } : {}),
                 ...(init.channel ? { channel: init.channel } : {}),
-                participants: init.participants ?? [],
+                participants,
+                viewable_by,
                 createdAt: init.createdAt,
             },
             events: new Map(),
@@ -23,8 +41,20 @@ export class InMemoryAdapter {
         const s = this.sessions.get(sessionId);
         if (!s)
             throw new Error(`session not found: ${sessionId}`);
-        for (const ev of events)
+        for (const ev of events) {
             s.events.set(ev.seq, ev);
+            // Mirror participant events into the row so listSessions sees them
+            // without re-folding events at read time.
+            if (ev.type === "participant") {
+                const next = new Set([...s.row.participants, ev.personId]);
+                const view = new Set([...s.row.viewable_by, ev.personId]);
+                s.row = {
+                    ...s.row,
+                    participants: [...next],
+                    viewable_by: [...view],
+                };
+            }
+        }
     }
     async getSession(sessionId) {
         const s = this.sessions.get(sessionId);
@@ -46,4 +76,76 @@ export class InMemoryAdapter {
         all.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
         return all.slice(0, opts.limit).map((x) => x.s);
     }
+    async sessionsForPerson(personId, opts) {
+        const scope = opts.scope ?? "participant";
+        const now = new Date();
+        const all = [];
+        for (const stored of this.sessions.values()) {
+            if (opts.channel && stored.row.channel !== opts.channel)
+                continue;
+            const list = scope === "viewable" ? stored.row.viewable_by : stored.row.participants;
+            if (!list.includes(personId))
+                continue;
+            all.push({
+                s: foldEvents(stored.row, [...stored.events.values()], now),
+                createdAt: stored.row.createdAt,
+            });
+        }
+        all.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        return all.slice(0, opts.limit).map((x) => x.s);
+    }
+    // --- Persons ------------------------------------------------------
+    async createPerson(input) {
+        const id = this.newPersonId();
+        return this.upsertPerson(id, input);
+    }
+    async upsertPerson(id, input) {
+        const now = new Date().toISOString();
+        const existing = this.persons.get(id);
+        const next = {
+            id,
+            display_name: input.display_name !== undefined
+                ? input.display_name
+                : existing?.display_name ?? null,
+            created_at: existing?.created_at ?? now,
+            updated_at: now,
+        };
+        this.persons.set(id, next);
+        return next;
+    }
+    async updatePerson(id, patch) {
+        const existing = this.persons.get(id);
+        if (!existing)
+            return null;
+        const now = new Date().toISOString();
+        const next = {
+            ...existing,
+            display_name: patch.display_name !== undefined ? patch.display_name : existing.display_name,
+            updated_at: now,
+        };
+        this.persons.set(id, next);
+        return next;
+    }
+    async getPerson(id) {
+        return this.persons.get(id) ?? null;
+    }
+    async getPersons(ids) {
+        const out = [];
+        for (const id of ids) {
+            const p = this.persons.get(id);
+            if (p)
+                out.push(p);
+        }
+        return out;
+    }
+    async listPersons(opts) {
+        const q = opts.q?.trim().toLowerCase() ?? "";
+        const all = [...this.persons.values()];
+        const matched = q
+            ? all.filter((p) => p.id.toLowerCase().includes(q) ||
+                (p.display_name?.toLowerCase().includes(q) ?? false))
+            : all;
+        matched.sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+        return matched.slice(0, opts.limit);
+    }
 }

package/dist/adapters/postgres-key-store.d.ts

@@ -0,0 +1,23 @@
+import { type ApiKeyInfo, type IssuedKey, type KeyResolution, type KeyStore, type Workspace } from "../key-store";
+import type { SqlClient } from "./postgres";
+export declare class PostgresKeyStore implements KeyStore {
+    private readonly sql;
+    constructor(sql: SqlClient);
+    /** Create the key-store schema. Call once at boot. */
+    ensureSchema(): Promise<void>;
+    createWorkspace(input: {
+        id?: string;
+        name?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Workspace>;
+    getWorkspace(id: string): Promise<Workspace | null>;
+    listWorkspaces(): Promise<Workspace[]>;
+    deleteWorkspace(id: string): Promise<void>;
+    issueKey(workspaceId: string, opts?: {
+        name?: string;
+    }): Promise<IssuedKey>;
+    listKeys(workspaceId: string): Promise<ApiKeyInfo[]>;
+    revokeKey(workspaceId: string, keyId: string): Promise<void>;
+    resolveKey(rawKey: string): Promise<KeyResolution | null>;
+    registerLegacyKey(workspaceId: string, rawKey: string, name?: string): Promise<void>;
+}

package/dist/adapters/postgres-key-store.js

@@ -0,0 +1,161 @@
+import { generateRawKey, hashKey, isValidWorkspaceId, keyPrefix, } from "../key-store";
+const KEY_STORE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS engram_workspaces (
+  id          TEXT PRIMARY KEY,
+  name        TEXT,
+  metadata    JSONB NOT NULL DEFAULT '{}',
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS engram_api_keys (
+  id            TEXT PRIMARY KEY,
+  workspace_id  TEXT NOT NULL REFERENCES engram_workspaces(id) ON DELETE CASCADE,
+  key_hash      TEXT NOT NULL UNIQUE,
+  prefix        TEXT NOT NULL,
+  name          TEXT,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  last_used_at  TIMESTAMPTZ,
+  revoked_at    TIMESTAMPTZ
+);
+
+CREATE INDEX IF NOT EXISTS idx_engram_api_keys_workspace
+  ON engram_api_keys (workspace_id);
+`;
+export class PostgresKeyStore {
+    sql;
+    constructor(sql) {
+        this.sql = sql;
+    }
+    /** Create the key-store schema. Call once at boot. */
+    async ensureSchema() {
+        await this.sql.unsafe(KEY_STORE_SCHEMA_SQL);
+    }
+    async createWorkspace(input) {
+        const id = input.id ?? crypto.randomUUID();
+        if (!isValidWorkspaceId(id))
+            throw new Error("invalid_workspace_id");
+        await this.sql `
+      INSERT INTO engram_workspaces (id, name, metadata)
+      VALUES (${id}, ${input.name ?? null}, ${(input.metadata ?? {})})
+      ON CONFLICT (id) DO NOTHING
+    `;
+        const ws = await this.getWorkspace(id);
+        if (!ws)
+            throw new Error("workspace_create_failed");
+        return ws;
+    }
+    async getWorkspace(id) {
+        const rows = await this.sql `
+      SELECT id, name, metadata, created_at FROM engram_workspaces WHERE id = ${id} LIMIT 1
+    `;
+        return rows.length === 0 ? null : toWorkspace(rows[0]);
+    }
+    async listWorkspaces() {
+        const rows = await this.sql `
+      SELECT id, name, metadata, created_at FROM engram_workspaces ORDER BY created_at DESC
+    `;
+        return rows.map(toWorkspace);
+    }
+    async deleteWorkspace(id) {
+        // engram_api_keys cascades via FK. engram_sessions/events are explicit
+        // since they predate the workspaces table and have no FK to it.
+        await this.sql `DELETE FROM engram_events   WHERE workspace_id = ${id}`;
+        await this.sql `DELETE FROM engram_sessions WHERE workspace_id = ${id}`;
+        await this.sql `DELETE FROM engram_workspaces WHERE id = ${id}`;
+    }
+    async issueKey(workspaceId, opts = {}) {
+        const ws = await this.getWorkspace(workspaceId);
+        if (!ws)
+            throw new Error("workspace_not_found");
+        const raw = generateRawKey();
+        const id = crypto.randomUUID();
+        const hash = hashKey(raw);
+        const prefix = keyPrefix(raw);
+        const rows = await this.sql `
+      INSERT INTO engram_api_keys (id, workspace_id, key_hash, prefix, name)
+      VALUES (${id}, ${workspaceId}, ${hash}, ${prefix}, ${opts.name ?? null})
+      RETURNING id, workspace_id, prefix, name, created_at, last_used_at, revoked_at
+    `;
+        return { ...toInfo(rows[0]), raw };
+    }
+    async listKeys(workspaceId) {
+        const rows = await this.sql `
+      SELECT id, workspace_id, prefix, name, created_at, last_used_at, revoked_at
+      FROM engram_api_keys
+      WHERE workspace_id = ${workspaceId}
+      ORDER BY created_at DESC
+    `;
+        return rows.map(toInfo);
+    }
+    async revokeKey(workspaceId, keyId) {
+        const rows = await this.sql `
+      UPDATE engram_api_keys
+      SET revoked_at = NOW()
+      WHERE id = ${keyId}
+        AND workspace_id = ${workspaceId}
+        AND revoked_at IS NULL
+      RETURNING id
+    `;
+        if (rows.length === 0) {
+            // Distinguish "not found" from "already revoked": if the row exists at
+            // all under this workspace, treat as no-op success.
+            const check = await this.sql `
+        SELECT id FROM engram_api_keys
+        WHERE id = ${keyId} AND workspace_id = ${workspaceId} LIMIT 1
+      `;
+            if (check.length === 0)
+                throw new Error("key_not_found");
+        }
+    }
+    async resolveKey(rawKey) {
+        const hash = hashKey(rawKey);
+        const rows = await this.sql `
+      SELECT id, workspace_id FROM engram_api_keys
+      WHERE key_hash = ${hash} AND revoked_at IS NULL
+      LIMIT 1
+    `;
+        if (rows.length === 0)
+            return null;
+        const row = rows[0];
+        // Fire-and-forget last_used update. Errors here would only mask the
+        // success of the actual auth — swallow them.
+        void this.sql `
+      UPDATE engram_api_keys SET last_used_at = NOW() WHERE id = ${row.id}
+    `.catch(() => undefined);
+        return { workspaceId: row.workspace_id, keyId: row.id };
+    }
+    async registerLegacyKey(workspaceId, rawKey, name) {
+        const ws = await this.getWorkspace(workspaceId);
+        if (!ws)
+            throw new Error("workspace_not_found");
+        const hash = hashKey(rawKey);
+        const id = crypto.randomUUID();
+        await this.sql `
+      INSERT INTO engram_api_keys (id, workspace_id, key_hash, prefix, name)
+      VALUES (${id}, ${workspaceId}, ${hash}, ${keyPrefix(rawKey)}, ${name ?? "legacy"})
+      ON CONFLICT (key_hash) DO NOTHING
+    `;
+    }
+}
+function toWorkspace(r) {
+    return {
+        id: r.id,
+        ...(r.name !== null ? { name: r.name } : {}),
+        ...(r.metadata !== null && Object.keys(r.metadata).length > 0 ? { metadata: r.metadata } : {}),
+        createdAt: isoString(r.created_at),
+    };
+}
+function toInfo(r) {
+    return {
+        id: r.id,
+        workspaceId: r.workspace_id,
+        prefix: r.prefix,
+        ...(r.name !== null ? { name: r.name } : {}),
+        createdAt: isoString(r.created_at),
+        ...(r.last_used_at !== null ? { lastUsedAt: isoString(r.last_used_at) } : {}),
+        ...(r.revoked_at !== null ? { revokedAt: isoString(r.revoked_at) } : {}),
+    };
+}
+function isoString(v) {
+    return typeof v === "string" ? v : v.toISOString();
+}

package/dist/adapters/postgres.d.ts

@@ -1,5 +1,5 @@
 import type { Session } from "@hexis-ai/engram-core";
-import type { SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
+import type { PersonCreate, PersonInfo, PersonUpdate, SessionEvent, SessionInit } from "@hexis-ai/engram-sdk";
 import { type StorageAdapter } from "../storage";
 /**
  * Minimal subset of `postgres` driver's tagged-template surface that this
@@ -15,10 +15,16 @@ export interface PostgresAdapterOptions {
     /** Workspace scope baked into every row. Required for multi-tenant isolation. */
     workspaceId: string;
     sql: SqlClient;
+    /**
+     * Generates ids for newly created persons. Default: `p_${randomShort()}`.
+     * Override in tests for determinism.
+     */
+    newPersonId?: () => string;
 }
 export declare class PostgresAdapter implements StorageAdapter {
     private readonly workspaceId;
     private readonly sql;
+    private readonly newPersonId;
     constructor(opts: PostgresAdapterOptions);
     /**
      * Create the schema. Call once at boot. Safe to invoke repeatedly.
@@ -35,4 +41,18 @@ export declare class PostgresAdapter implements StorageAdapter {
         limit: number;
         channel?: string;
     }): Promise<Session[]>;
+    sessionsForPerson(personId: string, opts: {
+        limit: number;
+        channel?: string;
+        scope?: "participant" | "viewable";
+    }): Promise<Session[]>;
+    createPerson(input: PersonCreate): Promise<PersonInfo>;
+    upsertPerson(id: string, input: PersonCreate): Promise<PersonInfo>;
+    updatePerson(id: string, patch: PersonUpdate): Promise<PersonInfo | null>;
+    getPerson(id: string): Promise<PersonInfo | null>;
+    getPersons(ids: string[]): Promise<PersonInfo[]>;
+    listPersons(opts: {
+        limit: number;
+        q?: string;
+    }): Promise<PersonInfo[]>;
 }