@hexis-ai/engram-sdk 0.13.0 → 0.15.0

package/dist/admin.d.ts

@@ -77,10 +77,7 @@ export interface OrgWorkspace {
     orgId: string;
 }
 export declare class EngramAdmin {
-    private readonly baseUrl;
-    private readonly adminToken;
-    private readonly fetchImpl;
-    private readonly authHeaders?;
+    private readonly http;
     constructor(opts: AdminClientOptions);
     createWorkspace(input?: CreateWorkspaceInput): Promise<CreateWorkspaceResult>;
     listWorkspaces(): Promise<Workspace[]>;
@@ -101,6 +98,19 @@ export declare class EngramAdmin {
     /** Create a workspace under an org and (by default) issue an api key. */
     createWorkspaceUnderOrg(orgId: string, input?: CreateWorkspaceInput): Promise<CreateWorkspaceResult>;
     listOrgWorkspaces(orgId: string): Promise<OrgWorkspace[]>;
+    /**
+     * Issue a fresh API key for a workspace under an org. Org-scoped
+     * replacement for the legacy `issueKey(workspaceId, ...)` which
+     * targeted `/admin/v1/workspaces/:id/keys`. Use this for key
+     * rotation after the initial `createWorkspaceUnderOrg`.
+     */
+    issueWorkspaceKey(orgId: string, workspaceId: string, opts?: {
+        name?: string;
+    }): Promise<IssuedKey>;
+    /** List the API keys of an org-owned workspace. */
+    listWorkspaceKeys(orgId: string, workspaceId: string): Promise<ApiKey[]>;
+    /** Revoke an API key on an org-owned workspace. */
+    revokeWorkspaceKey(orgId: string, workspaceId: string, keyId: string): Promise<void>;
     private request;
 }
 export declare function createAdminClient(opts: AdminClientOptions): EngramAdmin;

package/dist/admin.js

@@ -3,20 +3,21 @@
  * `/admin/v1/*` mount. Use from privileged contexts only — the admin token
  * is platform-root and must never reach end-user code paths.
  */
+import { createHttpClient } from "./http";
 export class EngramAdmin {
-    baseUrl;
-    adminToken;
-    fetchImpl;
-    authHeaders;
+    http;
     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;
+        this.http = createHttpClient({
+            baseUrl: opts.baseUrl,
+            ...(opts.fetch ? { fetch: opts.fetch } : {}),
+            ...(opts.authHeaders ? { authHeaders: opts.authHeaders } : {}),
+            staticHeaders: { "x-admin-token": opts.adminToken },
+            errorPrefix: "engram-admin",
+        });
     }
     async createWorkspace(input = {}) {
         return this.request("POST", "/admin/v1/workspaces", input);
@@ -76,25 +77,26 @@ export class EngramAdmin {
         const r = await this.request("GET", `/admin/v1/orgs/${encodeURIComponent(orgId)}/workspaces`);
         return r.workspaces;
     }
-    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());
+    /**
+     * Issue a fresh API key for a workspace under an org. Org-scoped
+     * replacement for the legacy `issueKey(workspaceId, ...)` which
+     * targeted `/admin/v1/workspaces/:id/keys`. Use this for key
+     * rotation after the initial `createWorkspaceUnderOrg`.
+     */
+    async issueWorkspaceKey(orgId, workspaceId, opts = {}) {
+        return this.request("POST", `/admin/v1/orgs/${encodeURIComponent(orgId)}/workspaces/${encodeURIComponent(workspaceId)}/keys`, opts);
+    }
+    /** List the API keys of an org-owned workspace. */
+    async listWorkspaceKeys(orgId, workspaceId) {
+        const r = await this.request("GET", `/admin/v1/orgs/${encodeURIComponent(orgId)}/workspaces/${encodeURIComponent(workspaceId)}/keys`);
+        return r.keys;
+    }
+    /** Revoke an API key on an org-owned workspace. */
+    async revokeWorkspaceKey(orgId, workspaceId, keyId) {
+        await this.request("DELETE", `/admin/v1/orgs/${encodeURIComponent(orgId)}/workspaces/${encodeURIComponent(workspaceId)}/keys/${encodeURIComponent(keyId)}`);
+    }
+    request(method, path, body) {
+        return this.http.request(method, path, body);
     }
 }
 export function createAdminClient(opts) {

package/dist/client.d.ts

@@ -84,14 +84,10 @@ export interface SearchRequest {
 /** @deprecated Use `SearchEnvelope` (carries `persons` map too). */
 export type SearchResponse = SearchEnvelope;
 export declare class Engram {
-    private readonly apiKey;
-    private readonly baseUrl;
-    private readonly fetchImpl;
+    private readonly http;
     private readonly flushIntervalMs;
     private readonly batchSize;
     private readonly onError;
-    private readonly apiKeyHeader;
-    private readonly authHeaders?;
     readonly maxRetries: number;
     readonly retryBackoffMs: number;
     private telemetry;

package/dist/client.js

@@ -1,15 +1,12 @@
 import { encodeResourceId, extractReferences } from "./extract";
 import { parseToolName } from "./tool-name";
 import { BufferedTelemetry, } from "./buffered";
+import { createHttpClient } from "./http";
 export class Engram {
-    apiKey;
-    baseUrl;
-    fetchImpl;
+    http;
     flushIntervalMs;
     batchSize;
     onError;
-    apiKeyHeader;
-    authHeaders;
     maxRetries;
     retryBackoffMs;
     telemetry = null;
@@ -18,16 +15,21 @@ export class Engram {
             throw new Error("Engram: apiKey is required");
         if (!opts.baseUrl)
             throw new Error("Engram: baseUrl is required");
-        this.apiKey = opts.apiKey;
-        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-        this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
         this.flushIntervalMs = opts.flushIntervalMs ?? 2000;
         this.batchSize = opts.batchSize ?? 32;
         this.onError = opts.onError ?? ((e) => console.error("[engram]", e));
-        this.apiKeyHeader = opts.apiKeyHeader ?? "authorization";
-        this.authHeaders = opts.authHeaders;
         this.maxRetries = opts.maxRetries ?? 4;
         this.retryBackoffMs = opts.retryBackoffMs ?? 500;
+        const apiKeyHeader = opts.apiKeyHeader ?? "authorization";
+        this.http = createHttpClient({
+            baseUrl: opts.baseUrl,
+            ...(opts.fetch ? { fetch: opts.fetch } : {}),
+            ...(opts.authHeaders ? { authHeaders: opts.authHeaders } : {}),
+            staticHeaders: apiKeyHeader === "authorization"
+                ? { authorization: `Bearer ${opts.apiKey}` }
+                : { "x-api-key": opts.apiKey },
+            errorPrefix: "engram",
+        });
     }
     /**
      * Langfuse-style fire-and-forget telemetry surface. Lazily initialised
@@ -254,31 +256,8 @@ export class Engram {
     get config() {
         return { flushIntervalMs: this.flushIntervalMs, batchSize: this.batchSize, onError: this.onError };
     }
-    async request(method, path, body) {
-        const headers = { "content-type": "application/json" };
-        if (this.apiKeyHeader === "authorization") {
-            headers["authorization"] = `Bearer ${this.apiKey}`;
-        }
-        else {
-            headers["x-api-key"] = this.apiKey;
-        }
-        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 ${method} ${path} ${res.status}: ${text}`);
-        }
-        if (res.status === 204)
-            return undefined;
-        const ct = res.headers.get("content-type") ?? "";
-        if (!ct.includes("application/json"))
-            return undefined;
-        return (await res.json());
+    request(method, path, body) {
+        return this.http.request(method, path, body);
     }
 }
 export class EngramSession {

package/dist/http.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Minimal JSON HTTP client shared by `Engram` (workspace api-key) and
+ * `EngramAdmin` (platform admin token). Encapsulates baseUrl normalisation,
+ * header merging, request body serialisation, and the small JSON-or-empty
+ * response contract that both clients use.
+ */
+export interface HttpClientOptions {
+    baseUrl: string;
+    fetch?: typeof fetch;
+    /** Static headers attached to every request before {@link authHeaders} overlay. */
+    staticHeaders?: Record<string, string>;
+    /**
+     * Async per-request hook returning headers to attach. Useful for short-lived
+     * credentials like Cloud Run ID tokens. Resolves before each request; values
+     * overwrite {@link staticHeaders} on conflict.
+     */
+    authHeaders?: () => Promise<Record<string, string>> | Record<string, string>;
+    /** Error-message prefix — distinguishes overlapping SDKs in stack traces. */
+    errorPrefix: string;
+}
+export interface HttpClient {
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+}
+export declare function createHttpClient(opts: HttpClientOptions): HttpClient;

package/dist/http.js

@@ -0,0 +1,37 @@
+/**
+ * Minimal JSON HTTP client shared by `Engram` (workspace api-key) and
+ * `EngramAdmin` (platform admin token). Encapsulates baseUrl normalisation,
+ * header merging, request body serialisation, and the small JSON-or-empty
+ * response contract that both clients use.
+ */
+export function createHttpClient(opts) {
+    const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    const fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    const staticHeaders = opts.staticHeaders ?? {};
+    const { authHeaders, errorPrefix } = opts;
+    return {
+        async request(method, path, body) {
+            const headers = {
+                "content-type": "application/json",
+                ...staticHeaders,
+            };
+            if (authHeaders)
+                Object.assign(headers, await authHeaders());
+            const res = await fetchImpl(`${baseUrl}${path}`, {
+                method,
+                headers,
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`${errorPrefix} ${method} ${path} ${res.status}: ${text}`);
+            }
+            if (res.status === 204)
+                return undefined;
+            const ct = res.headers.get("content-type") ?? "";
+            if (!ct.includes("application/json"))
+                return undefined;
+            return (await res.json());
+        },
+    };
+}

package/dist/types.d.ts

@@ -39,6 +39,17 @@ export interface SessionInit {
     trigger_conversation_id?: string | null;
     /** Causal lineage — an external event (e.g. calendar event id). */
     trigger_event_id?: string | null;
+    /**
+     * Host-defined "why was this side-conversation started" — set when
+     * a parent session opens a side-conv with a stated goal. Opaque to
+     * engram; the host's agent reads it back to drive resume behaviour.
+     */
+    trigger_purpose?: string | null;
+    /**
+     * Host-defined "what condition should make us resume the parent" —
+     * paired with `trigger_purpose`. Opaque to engram.
+     */
+    trigger_resume_hint?: string | null;
 }
 /** Patch for `updateSession`. */
 export interface SessionUpdate {
@@ -49,6 +60,8 @@ export interface SessionUpdate {
     model?: string | null;
     trigger_conversation_id?: string | null;
     trigger_event_id?: string | null;
+    trigger_purpose?: string | null;
+    trigger_resume_hint?: string | null;
 }
 export interface SessionAck {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-sdk",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "author": "hexis ltd.",
   "repository": {
     "type": "git",
@@ -9,7 +9,7 @@
   },
   "main": "dist/index.js",
   "dependencies": {
-    "@hexis-ai/engram-core": "^0.2.0"
+    "@hexis-ai/engram-core": "^0.3.0"
   },
   "exports": {
     ".": {