@hexis-ai/engram-server 0.1.7 → 0.3.0

package/dist/routes/sessions.js

@@ -0,0 +1,51 @@
+import { Hono } from "hono";
+import { eventBatchSchema, parseJsonBody, sessionInitSchema } from "../schemas";
+import { clampLimit, resolvePersonMap } from "./helpers";
+/**
+ * Session routes. Mount under `/v1`:
+ *   POST /v1/sessions            create a session
+ *   POST /v1/sessions/:id/events append events
+ *   GET  /v1/sessions/:id        fetch one session + its persons map
+ *   GET  /v1/sessions            list recent sessions + persons map
+ */
+export function sessionsRoutes(cfg) {
+    const app = new Hono();
+    app.post("/sessions", async (c) => {
+        const body = await parseJsonBody(c, sessionInitSchema);
+        if (body instanceof Response)
+            return body;
+        const id = body.id ?? cfg.newSessionId();
+        const createdAt = new Date().toISOString();
+        await c.var.ctx.storage.createSession({ ...body, id, createdAt });
+        return c.json({ id });
+    });
+    app.post("/sessions/:id/events", async (c) => {
+        const id = c.req.param("id");
+        const body = await parseJsonBody(c, eventBatchSchema);
+        if (body instanceof Response)
+            return body;
+        try {
+            await c.var.ctx.storage.appendEvents(id, body.events);
+        }
+        catch (e) {
+            return c.json({ error: "session_not_found", message: e.message }, 404);
+        }
+        return c.body(null, 204);
+    });
+    app.get("/sessions/:id", async (c) => {
+        const id = c.req.param("id");
+        const s = await c.var.ctx.storage.getSession(id);
+        if (!s)
+            return c.json({ error: "session_not_found" }, 404);
+        const persons = await resolvePersonMap(c.var.ctx.storage, [s]);
+        return c.json({ session: s, persons });
+    });
+    app.get("/sessions", async (c) => {
+        const limit = clampLimit(c, cfg.defaultListLimit, cfg.maxListLimit);
+        const channel = c.req.query("channel") || undefined;
+        const sessions = await c.var.ctx.storage.listSessions({ limit, channel });
+        const persons = await resolvePersonMap(c.var.ctx.storage, sessions);
+        return c.json({ sessions, persons });
+    });
+    return app;
+}

package/dist/schemas.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Zod schemas for every request body the server accepts. These are the
+ * trust boundary: handlers parse with `parseJsonBody` and never cast raw
+ * JSON straight onto a wire type.
+ *
+ * The wire types themselves live in `@hexis-ai/engram-sdk` (dependency-free,
+ * reusable by language ports). Each schema is `satisfies z.ZodType<…>` so a
+ * drift between a schema and its wire type fails the build here.
+ */
+import { z } from "zod";
+import type { Context } from "hono";
+export declare const sessionInitSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    channel: z.ZodOptional<z.ZodString>;
+    participants: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    viewable_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const sessionEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"step">;
+    seq: z.ZodNumber;
+    at: z.ZodString;
+    tool: z.ZodString;
+    resources: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"participant">;
+    seq: z.ZodNumber;
+    at: z.ZodString;
+    personId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"title">;
+    seq: z.ZodNumber;
+    at: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"end">;
+    seq: z.ZodNumber;
+    at: z.ZodString;
+}, z.core.$strip>], "type">;
+export declare const eventBatchSchema: z.ZodObject<{
+    events: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"step">;
+        seq: z.ZodNumber;
+        at: z.ZodString;
+        tool: z.ZodString;
+        resources: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"participant">;
+        seq: z.ZodNumber;
+        at: z.ZodString;
+        personId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"title">;
+        seq: z.ZodNumber;
+        at: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"end">;
+        seq: z.ZodNumber;
+        at: z.ZodString;
+    }, z.core.$strip>], "type">>;
+}, z.core.$strip>;
+export declare const personCreateSchema: z.ZodObject<{
+    display_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const personUpdateSchema: z.ZodObject<{
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const searchRequestSchema: z.ZodObject<{
+    query: z.ZodUnion<readonly [z.ZodObject<{
+        sessionId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        session: z.ZodObject<{
+            steps: z.ZodArray<z.ZodObject<{
+                tool: z.ZodString;
+                resources: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>>;
+            participants: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>]>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const createWorkspaceSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    issueKey: z.ZodOptional<z.ZodBoolean>;
+    keyName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const issueKeySchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Read and validate a JSON request body. Returns the parsed value, or a
+ * `Response` (400) the caller should return as-is:
+ *
+ *   const body = await parseJsonBody(c, sessionInitSchema);
+ *   if (body instanceof Response) return body;
+ */
+export declare function parseJsonBody<T>(c: Context, schema: z.ZodType<T>): Promise<T | Response>;

package/dist/schemas.js

@@ -0,0 +1,108 @@
+/**
+ * Zod schemas for every request body the server accepts. These are the
+ * trust boundary: handlers parse with `parseJsonBody` and never cast raw
+ * JSON straight onto a wire type.
+ *
+ * The wire types themselves live in `@hexis-ai/engram-sdk` (dependency-free,
+ * reusable by language ports). Each schema is `satisfies z.ZodType<…>` so a
+ * drift between a schema and its wire type fails the build here.
+ */
+import { z } from "zod";
+// --- Sessions --------------------------------------------------------
+export const sessionInitSchema = z.object({
+    id: z.string().min(1).optional(),
+    title: z.string().optional(),
+    channel: z.string().optional(),
+    participants: z.array(z.string()).optional(),
+    viewable_by: z.array(z.string()).optional(),
+});
+const stepEventSchema = z.object({
+    type: z.literal("step"),
+    seq: z.number().int().nonnegative(),
+    at: z.string(),
+    tool: z.string(),
+    resources: z.array(z.string()),
+});
+const participantEventSchema = z.object({
+    type: z.literal("participant"),
+    seq: z.number().int().nonnegative(),
+    at: z.string(),
+    personId: z.string(),
+});
+const titleEventSchema = z.object({
+    type: z.literal("title"),
+    seq: z.number().int().nonnegative(),
+    at: z.string(),
+    title: z.string(),
+});
+const endEventSchema = z.object({
+    type: z.literal("end"),
+    seq: z.number().int().nonnegative(),
+    at: z.string(),
+});
+export const sessionEventSchema = z.discriminatedUnion("type", [
+    stepEventSchema,
+    participantEventSchema,
+    titleEventSchema,
+    endEventSchema,
+]);
+export const eventBatchSchema = z.object({
+    events: z.array(sessionEventSchema),
+});
+// --- Persons ---------------------------------------------------------
+export const personCreateSchema = z.object({
+    display_name: z.string().optional(),
+});
+export const personUpdateSchema = z.object({
+    display_name: z.string().nullable().optional(),
+});
+// --- Search ----------------------------------------------------------
+const searchQuerySchema = z.union([
+    z.object({ sessionId: z.string().min(1) }),
+    z.object({
+        session: z.object({
+            steps: z.array(z.object({ tool: z.string(), resources: z.array(z.string()) })),
+            participants: z.array(z.string()).optional(),
+        }),
+    }),
+]);
+export const searchRequestSchema = z.object({
+    query: searchQuerySchema,
+    // `options` is forwarded as-is to engram-core's pure `search()`, which
+    // tolerates partial/absent options. Only the query (which drives storage
+    // lookups) needs strict validation here.
+    options: z.record(z.string(), z.unknown()).optional(),
+});
+// --- Admin -----------------------------------------------------------
+export const createWorkspaceSchema = z.object({
+    id: z.string().optional(),
+    name: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    issueKey: z.boolean().optional(),
+    keyName: z.string().optional(),
+});
+export const issueKeySchema = z.object({
+    name: z.string().optional(),
+});
+// --- Helper ----------------------------------------------------------
+/**
+ * Read and validate a JSON request body. Returns the parsed value, or a
+ * `Response` (400) the caller should return as-is:
+ *
+ *   const body = await parseJsonBody(c, sessionInitSchema);
+ *   if (body instanceof Response) return body;
+ */
+export async function parseJsonBody(c, schema) {
+    let raw;
+    try {
+        raw = await c.req.json();
+    }
+    catch {
+        return c.json({ error: "invalid_json" }, 400);
+    }
+    const result = schema.safeParse(raw);
+    if (!result.success) {
+        return c.json({ error: "invalid_body", issues: result.error.issues }, 400);
+    }
+    return result.data;
+}

package/dist/server.d.ts

@@ -1,20 +1,8 @@
 import { Hono } from "hono";
-import type { StorageAdapter } from "./storage";
+import type { AuthResolver, Env } from "./context";
 import { type AdminOptions } from "./admin";
-/**
- * Resolve an API key (raw `Authorization: Bearer <key>` token) into a
- * workspace context. Throwing or returning null short-circuits to 401.
- */
-export interface AuthResolver {
-    (apiKey: string): Promise<WorkspaceContext | null> | WorkspaceContext | null;
-}
-export interface WorkspaceContext {
-    workspaceId: string;
-    /** The storage adapter scoped to this workspace. */
-    storage: StorageAdapter;
-}
 export interface CreateServerOptions {
-    /** Resolves Bearer tokens into workspace contexts. */
+    /** Resolves Bearer / X-Api-Key tokens into workspace contexts. */
     auth: AuthResolver;
     /**
      * Generates session ids. Defaults to `crypto.randomUUID()`.
@@ -32,11 +20,9 @@ export interface CreateServerOptions {
      */
     admin?: AdminOptions;
 }
-interface Env {
-    Variables: {
-        ctx: WorkspaceContext;
-        request_id: string;
-    };
-}
+/**
+ * Build the engram HTTP app. Wiring only: this sets up cross-cutting
+ * middleware (request id + access log), the workspace auth gate, and mounts
+ * the `/v1` route modules (`routes/*`) and the optional `/admin/v1` router.
+ */
 export declare function createServer(opts: CreateServerOptions): Hono<Env>;
-export {};

package/dist/server.js

@@ -1,11 +1,20 @@
 import { Hono } from "hono";
-import { buildIndex, search, } from "@hexis-ai/engram-core";
 import { log, newRequestId } from "./logger";
 import { createAdminRouter } from "./admin";
+import { sessionsRoutes } from "./routes/sessions";
+import { personsRoutes } from "./routes/persons";
+import { searchRoutes } from "./routes/search";
+/**
+ * Build the engram HTTP app. Wiring only: this sets up cross-cutting
+ * middleware (request id + access log), the workspace auth gate, and mounts
+ * the `/v1` route modules (`routes/*`) and the optional `/admin/v1` router.
+ */
 export function createServer(opts) {
-    const newId = opts.newSessionId ?? (() => crypto.randomUUID());
-    const defaultLimit = opts.defaultListLimit ?? 100;
-    const maxLimit = opts.maxListLimit ?? 500;
+    const cfg = {
+        newSessionId: opts.newSessionId ?? (() => crypto.randomUUID()),
+        defaultListLimit: opts.defaultListLimit ?? 100,
+        maxListLimit: opts.maxListLimit ?? 500,
+    };
     const app = new Hono();
     // Request id + access log middleware. Runs for every route.
     app.use("*", async (c, next) => {
@@ -54,6 +63,7 @@ export function createServer(opts) {
     if (opts.admin) {
         app.route("/admin/v1", createAdminRouter(opts.admin));
     }
+    // Workspace auth gate — every `/v1/*` route runs behind this.
     app.use("/v1/*", async (c, next) => {
         const apiKey = c.req.header("x-api-key") ??
             c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
@@ -68,157 +78,8 @@ export function createServer(opts) {
     // Identity probe — echoes the workspace the caller's key resolves to.
     // Used by clients (e.g. engram-web) to label which tenant they're viewing.
     app.get("/v1/me", (c) => c.json({ workspaceId: c.var.ctx.workspaceId }));
-    // --- Sessions --------------------------------------------------------
-    app.post("/v1/sessions", async (c) => {
-        const body = (await c.req.json().catch(() => null));
-        if (body === null)
-            return c.json({ error: "invalid_json" }, 400);
-        const id = body.id ?? newId();
-        const createdAt = new Date().toISOString();
-        await c.var.ctx.storage.createSession({
-            ...body,
-            id,
-            createdAt,
-        });
-        return c.json({ id });
-    });
-    app.post("/v1/sessions/:id/events", async (c) => {
-        const id = c.req.param("id");
-        const body = (await c.req.json().catch(() => null));
-        if (!body || !Array.isArray(body.events)) {
-            return c.json({ error: "events_array_required" }, 400);
-        }
-        try {
-            await c.var.ctx.storage.appendEvents(id, body.events);
-        }
-        catch (e) {
-            return c.json({ error: "session_not_found", message: e.message }, 404);
-        }
-        return c.body(null, 204);
-    });
-    app.get("/v1/sessions/:id", async (c) => {
-        const id = c.req.param("id");
-        const s = await c.var.ctx.storage.getSession(id);
-        if (!s)
-            return c.json({ error: "session_not_found" }, 404);
-        const persons = await resolvePersonMap(c.var.ctx.storage, [s]);
-        return c.json({ session: s, persons });
-    });
-    app.get("/v1/sessions", async (c) => {
-        const limit = clampLimit(c, defaultLimit, maxLimit);
-        const channel = c.req.query("channel") || undefined;
-        const sessions = await c.var.ctx.storage.listSessions({ limit, channel });
-        const persons = await resolvePersonMap(c.var.ctx.storage, sessions);
-        return c.json({ sessions, persons });
-    });
-    app.post("/v1/search", async (c) => {
-        const body = (await c.req.json().catch(() => null));
-        if (!body || !body.query)
-            return c.json({ error: "query_required" }, 400);
-        const corpus = await c.var.ctx.storage.listSessions({ limit: maxLimit });
-        let queryQuery;
-        if ("sessionId" in body.query) {
-            const q = await c.var.ctx.storage.getSession(body.query.sessionId);
-            if (!q)
-                return c.json({ error: "query_session_not_found" }, 404);
-            queryQuery = q;
-        }
-        else {
-            queryQuery = body.query.session;
-        }
-        const index = buildIndex(corpus);
-        const opts = body.options ?? {};
-        const queryParticipants = opts.queryParticipants ?? queryQuery.participants ?? [];
-        const results = search(queryQuery.steps, index, {
-            ...opts,
-            queryParticipants,
-        });
-        const persons = await resolvePersonMap(c.var.ctx.storage, results.map((r) => r.session));
-        return c.json({ results, persons });
-    });
-    // --- Persons ---------------------------------------------------------
-    app.post("/v1/persons", async (c) => {
-        const body = (await c.req.json().catch(() => null));
-        if (body === null)
-            return c.json({ error: "invalid_json" }, 400);
-        const p = await c.var.ctx.storage.createPerson(body);
-        return c.json(p, 201);
-    });
-    app.put("/v1/persons/:id", async (c) => {
-        const id = c.req.param("id");
-        const body = (await c.req.json().catch(() => null));
-        if (body === null)
-            return c.json({ error: "invalid_json" }, 400);
-        const p = await c.var.ctx.storage.upsertPerson(id, body);
-        return c.json(p);
-    });
-    app.patch("/v1/persons/:id", async (c) => {
-        const id = c.req.param("id");
-        const body = (await c.req.json().catch(() => null));
-        if (body === null)
-            return c.json({ error: "invalid_json" }, 400);
-        const p = await c.var.ctx.storage.updatePerson(id, body);
-        if (!p)
-            return c.json({ error: "person_not_found" }, 404);
-        return c.json(p);
-    });
-    app.get("/v1/persons/:id", async (c) => {
-        const id = c.req.param("id");
-        const p = await c.var.ctx.storage.getPerson(id);
-        if (!p)
-            return c.json({ error: "person_not_found" }, 404);
-        return c.json(p);
-    });
-    app.get("/v1/persons", async (c) => {
-        const limit = clampLimit(c, defaultLimit, maxLimit);
-        const q = c.req.query("q") || undefined;
-        const persons = await c.var.ctx.storage.listPersons({ limit, q });
-        return c.json({ persons });
-    });
-    app.get("/v1/persons/:id/sessions", async (c) => {
-        const id = c.req.param("id");
-        const limit = clampLimit(c, defaultLimit, maxLimit);
-        const channel = c.req.query("channel") || undefined;
-        const scopeRaw = c.req.query("scope");
-        const scope = scopeRaw === "viewable" ? "viewable" : "participant";
-        const sessions = await c.var.ctx.storage.sessionsForPerson(id, {
-            limit,
-            channel,
-            scope,
-        });
-        const persons = await resolvePersonMap(c.var.ctx.storage, sessions);
-        return c.json({ sessions, persons });
-    });
+    app.route("/v1", sessionsRoutes(cfg));
+    app.route("/v1", personsRoutes(cfg));
+    app.route("/v1", searchRoutes(cfg));
     return app;
 }
-function clampLimit(c, def, max) {
-    const raw = c.req.query("limit");
-    if (!raw)
-        return def;
-    const n = parseInt(raw, 10);
-    if (isNaN(n) || n < 1)
-        return def;
-    return Math.min(n, max);
-}
-/**
- * Build a deduped person_id → PersonInfo map covering every person id
- * referenced by `sessions` (participants ∪ viewable_by). Returns {} if
- * there are no session rows. Persons that exist as ids in sessions but
- * have no engram_persons row are simply absent from the map.
- */
-async function resolvePersonMap(storage, sessions) {
-    const ids = new Set();
-    for (const s of sessions) {
-        for (const id of s.participants ?? [])
-            ids.add(id);
-        for (const id of s.viewable_by ?? [])
-            ids.add(id);
-    }
-    if (ids.size === 0)
-        return {};
-    const list = await storage.getPersons([...ids]);
-    const map = {};
-    for (const p of list)
-        map[p.id] = p;
-    return map;
-}