@hexis-ai/engram-sdk 0.1.4 → 0.1.6

package/dist/admin.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Admin SDK: provisions workspaces and API keys against an engram-server
+ * `/admin/v1/*` mount. Use from privileged contexts only — the admin token
+ * is platform-root and must never reach end-user code paths.
+ */
+export interface AdminClientOptions {
+    baseUrl: string;
+    adminToken: string;
+    fetch?: typeof fetch;
+    /**
+     * Async hook resolved per-request that returns additional headers.
+     * Use for short-lived credentials like Cloud Run ID tokens — the platform
+     * admin token already travels in `X-Admin-Token`, so the host can put a
+     * Google ID token in `Authorization` here without colliding.
+     */
+    authHeaders?: () => Promise<Record<string, string>> | Record<string, string>;
+}
+export interface Workspace {
+    id: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+export interface ApiKey {
+    id: string;
+    workspaceId: string;
+    prefix: string;
+    name?: string;
+    createdAt: string;
+    lastUsedAt?: string;
+    revokedAt?: string;
+}
+export interface IssuedKey extends ApiKey {
+    /** Plaintext key. Stored only by the caller; never retrievable again. */
+    raw: string;
+}
+export interface CreateWorkspaceInput {
+    id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    /** Whether to also issue an initial API key. Default true. */
+    issueKey?: boolean;
+    /** Optional name applied to the initial API key. */
+    keyName?: string;
+}
+export interface CreateWorkspaceResult {
+    workspace: Workspace;
+    /** Present when `issueKey !== false`. */
+    key?: IssuedKey;
+}
+export declare class EngramAdmin {
+    private readonly baseUrl;
+    private readonly adminToken;
+    private readonly fetchImpl;
+    private readonly authHeaders?;
+    constructor(opts: AdminClientOptions);
+    createWorkspace(input?: CreateWorkspaceInput): Promise<CreateWorkspaceResult>;
+    listWorkspaces(): Promise<Workspace[]>;
+    getWorkspace(id: string): Promise<Workspace>;
+    deleteWorkspace(id: string): Promise<void>;
+    issueKey(workspaceId: string, opts?: {
+        name?: string;
+    }): Promise<IssuedKey>;
+    listKeys(workspaceId: string): Promise<ApiKey[]>;
+    revokeKey(workspaceId: string, keyId: string): Promise<void>;
+    private request;
+}
+export declare function createAdminClient(opts: AdminClientOptions): EngramAdmin;

package/dist/admin.js

@@ -0,0 +1,67 @@
+/**
+ * Admin SDK: provisions workspaces and API keys against an engram-server
+ * `/admin/v1/*` mount. Use from privileged contexts only — the admin token
+ * is platform-root and must never reach end-user code paths.
+ */
+export class EngramAdmin {
+    baseUrl;
+    adminToken;
+    fetchImpl;
+    authHeaders;
+    constructor(opts) {
+        if (!opts.baseUrl)
+            throw new Error("EngramAdmin: baseUrl is required");
+        if (!opts.adminToken)
+            throw new Error("EngramAdmin: adminToken is required");
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+        this.adminToken = opts.adminToken;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+        this.authHeaders = opts.authHeaders;
+    }
+    async createWorkspace(input = {}) {
+        return this.request("POST", "/admin/v1/workspaces", input);
+    }
+    async listWorkspaces() {
+        const r = await this.request("GET", "/admin/v1/workspaces");
+        return r.workspaces;
+    }
+    async getWorkspace(id) {
+        return this.request("GET", `/admin/v1/workspaces/${encodeURIComponent(id)}`);
+    }
+    async deleteWorkspace(id) {
+        await this.request("DELETE", `/admin/v1/workspaces/${encodeURIComponent(id)}`);
+    }
+    async issueKey(workspaceId, opts = {}) {
+        return this.request("POST", `/admin/v1/workspaces/${encodeURIComponent(workspaceId)}/keys`, opts);
+    }
+    async listKeys(workspaceId) {
+        const r = await this.request("GET", `/admin/v1/workspaces/${encodeURIComponent(workspaceId)}/keys`);
+        return r.keys;
+    }
+    async revokeKey(workspaceId, keyId) {
+        await this.request("DELETE", `/admin/v1/workspaces/${encodeURIComponent(workspaceId)}/keys/${encodeURIComponent(keyId)}`);
+    }
+    async request(method, path, body) {
+        const headers = {
+            "content-type": "application/json",
+            "x-admin-token": this.adminToken,
+        };
+        if (this.authHeaders)
+            Object.assign(headers, await this.authHeaders());
+        const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`engram-admin ${method} ${path} ${res.status}: ${text}`);
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+}
+export function createAdminClient(opts) {
+    return new EngramAdmin(opts);
+}

package/dist/client.d.ts

@@ -1,6 +1,23 @@
 import type { ScoredSession, SearchOptions, Session, SessionStep } from "@hexis-ai/engram-core";
 import { type RefCandidate } from "./extract";
-import type { EventBatch, SessionInit } from "./types";
+import type { EventBatch, PersonCreate, PersonInfo, PersonMap, PersonUpdate, SessionInit } from "./types";
+/**
+ * Envelope returned by session endpoints. The persons map is deduped
+ * across whatever sessions the response carries so display info isn't
+ * repeated per row.
+ */
+export interface SessionEnvelope {
+    session: Session;
+    persons: PersonMap;
+}
+export interface SessionListEnvelope {
+    sessions: Session[];
+    persons: PersonMap;
+}
+export interface SearchEnvelope {
+    results: ScoredSession[];
+    persons: PersonMap;
+}
 export interface EngramOptions {
     apiKey: string;
     baseUrl: string;
@@ -63,9 +80,8 @@ export interface SearchRequest {
     };
     options?: SearchOptions;
 }
-export interface SearchResponse {
-    results: ScoredSession[];
-}
+/** @deprecated Use `SearchEnvelope` (carries `persons` map too). */
+export type SearchResponse = SearchEnvelope;
 export declare class Engram {
     private readonly apiKey;
     private readonly baseUrl;
@@ -78,17 +94,46 @@ export declare class Engram {
     readonly maxRetries: number;
     readonly retryBackoffMs: number;
     constructor(opts: EngramOptions);
+    /** Probe identity — returns the workspace the configured key resolves to. */
+    me(): Promise<{
+        workspaceId: string;
+    }>;
     /** Begin a new session. Returns a handle for buffering events. */
     startSession(init?: SessionInit): Promise<EngramSession>;
-    /** Fetch a single Session by id. */
-    getSession(id: string): Promise<Session>;
-    /** List recent sessions (server defines defaults & limits). */
+    /** Fetch a single session by id, plus the persons map for its participants/viewers. */
+    getSession(id: string): Promise<SessionEnvelope>;
+    /** List recent sessions plus the deduped persons map across them. */
     listSessions(opts?: {
         limit?: number;
         channel?: string;
-    }): Promise<Session[]>;
+    }): Promise<SessionListEnvelope>;
     /** Run a search. */
-    search(req: SearchRequest): Promise<SearchResponse>;
+    search(req: SearchRequest): Promise<SearchEnvelope>;
+    /** Person operations. The host (e.g. monet) resolves platform identities
+     *  to person ids before storing sessions; this namespace lets it own the
+     *  underlying person records (display name + canonical id). */
+    readonly persons: {
+        /** Allocate a new person id and return the row. */
+        create: (input: PersonCreate) => Promise<PersonInfo>;
+        /** Upsert at a host-supplied id (backfill / fallback). */
+        upsert: (id: string, input: PersonCreate) => Promise<PersonInfo>;
+        /** Patch profile fields. Returns 404 if id is unknown. */
+        update: (id: string, patch: PersonUpdate) => Promise<PersonInfo>;
+        get: (id: string) => Promise<PersonInfo>;
+        /** Free-text search (substring across id + display_name). */
+        list: (opts?: {
+            limit?: number;
+            q?: string;
+        }) => Promise<{
+            persons: PersonInfo[];
+        }>;
+        /** Sessions where this person appears in participants (default) or viewable_by. */
+        sessions: (id: string, opts?: {
+            limit?: number;
+            channel?: string;
+            scope?: "participant" | "viewable";
+        }) => Promise<SessionListEnvelope>;
+    };
     /** Internal: ship an event batch to the server. */
     sendBatch(sessionId: string, batch: EventBatch): Promise<void>;
     /** Internal accessor used by EngramSession to honor SDK config. */
@@ -109,7 +154,9 @@ export declare class EngramSession {
     private ended;
     constructor(engram: Engram, id: string);
     recordStep(input: RecordStepInput): SessionStep;
-    addParticipant(identityRef: string): void;
+    /** Append a participant to the running session. `personId` must already be
+     *  resolved by the host (engram-server does not resolve platform identities). */
+    addParticipant(personId: string): void;
     setTitle(title: string): void;
     /** Mark the session ended and flush buffered events. */
     end(): Promise<void>;

package/dist/client.js

@@ -27,16 +27,20 @@ export class Engram {
         this.maxRetries = opts.maxRetries ?? 4;
         this.retryBackoffMs = opts.retryBackoffMs ?? 500;
     }
+    /** Probe identity — returns the workspace the configured key resolves to. */
+    async me() {
+        return this.request("GET", "/v1/me");
+    }
     /** Begin a new session. Returns a handle for buffering events. */
     async startSession(init = {}) {
         const ack = await this.request("POST", "/v1/sessions", init);
         return new EngramSession(this, ack.id);
     }
-    /** Fetch a single Session by id. */
+    /** Fetch a single session by id, plus the persons map for its participants/viewers. */
     async getSession(id) {
         return this.request("GET", `/v1/sessions/${encodeURIComponent(id)}`);
     }
-    /** List recent sessions (server defines defaults & limits). */
+    /** List recent sessions plus the deduped persons map across them. */
     async listSessions(opts = {}) {
         const qs = new URLSearchParams();
         if (opts.limit !== undefined)
@@ -50,6 +54,41 @@ export class Engram {
     async search(req) {
         return this.request("POST", "/v1/search", req);
     }
+    // ---- Persons ----
+    /** Person operations. The host (e.g. monet) resolves platform identities
+     *  to person ids before storing sessions; this namespace lets it own the
+     *  underlying person records (display name + canonical id). */
+    persons = {
+        /** Allocate a new person id and return the row. */
+        create: (input) => this.request("POST", "/v1/persons", input),
+        /** Upsert at a host-supplied id (backfill / fallback). */
+        upsert: (id, input) => this.request("PUT", `/v1/persons/${encodeURIComponent(id)}`, input),
+        /** Patch profile fields. Returns 404 if id is unknown. */
+        update: (id, patch) => this.request("PATCH", `/v1/persons/${encodeURIComponent(id)}`, patch),
+        get: (id) => this.request("GET", `/v1/persons/${encodeURIComponent(id)}`),
+        /** Free-text search (substring across id + display_name). */
+        list: (opts = {}) => {
+            const qs = new URLSearchParams();
+            if (opts.limit !== undefined)
+                qs.set("limit", String(opts.limit));
+            if (opts.q)
+                qs.set("q", opts.q);
+            const tail = qs.toString();
+            return this.request("GET", `/v1/persons${tail ? `?${tail}` : ""}`);
+        },
+        /** Sessions where this person appears in participants (default) or viewable_by. */
+        sessions: (id, opts = {}) => {
+            const qs = new URLSearchParams();
+            if (opts.limit !== undefined)
+                qs.set("limit", String(opts.limit));
+            if (opts.channel)
+                qs.set("channel", opts.channel);
+            if (opts.scope)
+                qs.set("scope", opts.scope);
+            const tail = qs.toString();
+            return this.request("GET", `/v1/persons/${encodeURIComponent(id)}/sessions${tail ? `?${tail}` : ""}`);
+        },
+    };
     /** Internal: ship an event batch to the server. */
     async sendBatch(sessionId, batch) {
         if (batch.events.length === 0)
@@ -112,12 +151,14 @@ export class EngramSession {
         this.enqueue(ev);
         return { tool, resources };
     }
-    addParticipant(identityRef) {
+    /** Append a participant to the running session. `personId` must already be
+     *  resolved by the host (engram-server does not resolve platform identities). */
+    addParticipant(personId) {
         const ev = {
             type: "participant",
             seq: this.seq++,
             at: new Date().toISOString(),
-            identityRef,
+            personId,
         };
         this.enqueue(ev);
     }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export { Engram, EngramSession, type EngramOptions, type RecordStepInput, type SearchRequest, type SearchResponse, } from "./client";
+export { Engram, EngramSession, type EngramOptions, type RecordStepInput, type SearchRequest, type SearchResponse, type SearchEnvelope, type SessionEnvelope, type SessionListEnvelope, } from "./client";
 export { extractReferences, encodeResourceId, type RefCandidate, type ReferenceService, type ReferenceAction, } from "./extract";
 export { parseToolName, type ParsedToolName } from "./tool-name";
 export { fetchIdToken, cloudRunIdTokenAuth } from "./id-token";
-export type { SessionInit, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, EventBatch, } from "./types";
+export { EngramAdmin, createAdminClient, type AdminClientOptions, type CreateWorkspaceInput, type CreateWorkspaceResult, type Workspace as AdminWorkspace, type ApiKey as AdminApiKey, type IssuedKey as AdminIssuedKey, } from "./admin";
+export type { SessionInit, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, EventBatch, PersonInfo, PersonCreate, PersonUpdate, PersonMap, } from "./types";

package/dist/index.js

@@ -2,3 +2,4 @@ export { Engram, EngramSession, } from "./client";
 export { extractReferences, encodeResourceId, } from "./extract";
 export { parseToolName } from "./tool-name";
 export { fetchIdToken, cloudRunIdTokenAuth } from "./id-token";
+export { EngramAdmin, createAdminClient, } from "./admin";

package/dist/types.d.ts

@@ -13,7 +13,18 @@ export interface SessionInit {
      * (e.g. `chat_ui`, `slack_dm`, `cron:dailyDigest`).
      */
     channel?: string;
+    /**
+     * Person ids that took part. The host (e.g. monet) is responsible for
+     * resolving platform identities (slack:U..., email:...) to person ids
+     * before calling startSession.
+     */
     participants?: string[];
+    /**
+     * Person ids that may view this session. Defaults to participants when
+     * omitted. engram-server unions this with participants to guarantee
+     * `participants ⊆ viewable_by`.
+     */
+    viewable_by?: string[];
 }
 export interface SessionAck {
     id: string;
@@ -29,7 +40,8 @@ export interface ParticipantEvent {
     type: "participant";
     seq: number;
     at: string;
-    identityRef: string;
+    /** Person id (resolved by the host). */
+    personId: string;
 }
 export interface TitleEvent {
     type: "title";
@@ -46,3 +58,27 @@ export type SessionEvent = StepEvent | ParticipantEvent | TitleEvent | EndEvent;
 export interface EventBatch {
     events: SessionEvent[];
 }
+/**
+ * Minimal representation engram-server returns for any person. Hosts cache
+ * `display_name` for UI rendering; richer profile attributes (role, team,
+ * etc.) are intentionally NOT here — those belong to HR / source-of-truth
+ * systems the host integrates with.
+ */
+export interface PersonInfo {
+    id: string;
+    display_name: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface PersonCreate {
+    display_name?: string;
+}
+export interface PersonUpdate {
+    display_name?: string | null;
+}
+/**
+ * Map of person_id → PersonInfo, deduped across whatever `Session`s the
+ * response contains. Returned at the envelope level so list responses
+ * don't repeat the same person info per row.
+ */
+export type PersonMap = Record<string, PersonInfo>;

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@hexis-ai/engram-sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Host SDK for engram. Records agent session steps and ships them to an engram server.",
-  "keywords": ["engram", "agents", "claude", "anthropic", "sdk", "observability"],
+  "keywords": [
+    "engram",
+    "agents",
+    "claude",
+    "anthropic",
+    "sdk",
+    "observability"
+  ],
   "homepage": "https://github.com/hexis-ltd/engram#readme",
   "repository": {
     "type": "git",
@@ -40,7 +47,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@hexis-ai/engram-core": "^0.1.4"
+    "@hexis-ai/engram-core": "^0.1.5"
   },
   "publishConfig": {
     "access": "public"