@hexis-ai/engram-sdk 0.12.0 → 0.14.0

package/dist/admin.d.ts

@@ -48,11 +48,36 @@ export interface CreateWorkspaceResult {
     /** Present when `issueKey !== false`. */
     key?: IssuedKey;
 }
+export interface Org {
+    id: string;
+    name?: string | null;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+}
+export interface OrgMembership {
+    orgId: string;
+    userId: string;
+    role: string;
+    joinedAt: string;
+}
+export interface CreateOrgInput {
+    id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface UpsertMemberInput {
+    /** Provide one of these — userId wins when both are present. */
+    userId?: string;
+    email?: string;
+    role?: string;
+}
+export interface OrgWorkspace {
+    id: string;
+    name: string | null;
+    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[]>;
@@ -63,6 +88,29 @@ export declare class EngramAdmin {
     }): Promise<IssuedKey>;
     listKeys(workspaceId: string): Promise<ApiKey[]>;
     revokeKey(workspaceId: string, keyId: string): Promise<void>;
+    createOrg(input?: CreateOrgInput): Promise<Org>;
+    listOrgs(): Promise<Org[]>;
+    getOrg(id: string): Promise<Org>;
+    deleteOrg(id: string): Promise<void>;
+    listOrgMembers(orgId: string): Promise<OrgMembership[]>;
+    upsertOrgMember(orgId: string, input: UpsertMemberInput): Promise<OrgMembership>;
+    removeOrgMember(orgId: string, userId: string): Promise<void>;
+    /** 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);
@@ -41,25 +42,61 @@ export class EngramAdmin {
     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());
+    // ---------- orgs (Wave G) ---------------------------------
+    async createOrg(input = {}) {
+        const r = await this.request("POST", "/admin/v1/orgs", input);
+        return r.org;
+    }
+    async listOrgs() {
+        const r = await this.request("GET", "/admin/v1/orgs");
+        return r.orgs;
+    }
+    async getOrg(id) {
+        const r = await this.request("GET", `/admin/v1/orgs/${encodeURIComponent(id)}`);
+        return r.org;
+    }
+    async deleteOrg(id) {
+        await this.request("DELETE", `/admin/v1/orgs/${encodeURIComponent(id)}`);
+    }
+    async listOrgMembers(orgId) {
+        const r = await this.request("GET", `/admin/v1/orgs/${encodeURIComponent(orgId)}/members`);
+        return r.members;
+    }
+    async upsertOrgMember(orgId, input) {
+        const r = await this.request("POST", `/admin/v1/orgs/${encodeURIComponent(orgId)}/members`, input);
+        return r.member;
+    }
+    async removeOrgMember(orgId, userId) {
+        await this.request("DELETE", `/admin/v1/orgs/${encodeURIComponent(orgId)}/members/${encodeURIComponent(userId)}`);
+    }
+    /** Create a workspace under an org and (by default) issue an api key. */
+    async createWorkspaceUnderOrg(orgId, input = {}) {
+        return this.request("POST", `/admin/v1/orgs/${encodeURIComponent(orgId)}/workspaces`, input);
+    }
+    async listOrgWorkspaces(orgId) {
+        const r = await this.request("GET", `/admin/v1/orgs/${encodeURIComponent(orgId)}/workspaces`);
+        return r.workspaces;
+    }
+    /**
+     * 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/index.d.ts

@@ -3,5 +3,5 @@ export { extractReferences, encodeResourceId, type RefCandidate, type ReferenceS
 export { parseToolName, type ParsedToolName } from "./tool-name";
 export { BufferedTelemetry, type TelemetrySession, type TelemetryMessage, type TelemetryEvent, type TelemetryPerson, type TelemetryIdentity, type TelemetryAlias, } from "./buffered";
 export { fetchIdToken, cloudRunIdTokenAuth } from "./id-token";
-export { EngramAdmin, createAdminClient, type AdminClientOptions, type CreateWorkspaceInput, type CreateWorkspaceResult, type Workspace as AdminWorkspace, type ApiKey as AdminApiKey, type IssuedKey as AdminIssuedKey, } from "./admin";
+export { EngramAdmin, createAdminClient, type AdminClientOptions, type CreateWorkspaceInput, type CreateWorkspaceResult, type Workspace as AdminWorkspace, type ApiKey as AdminApiKey, type IssuedKey as AdminIssuedKey, type Org, type OrgMembership, type CreateOrgInput, type UpsertMemberInput, type OrgWorkspace, } from "./admin";
 export type { SessionInit, SessionUpdate, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, MessageContentBlock, MessageEvent, EventBatch, PersonInfo, PersonCreate, PersonUpdate, PersonMap, AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, } from "./types";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-sdk",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "author": "hexis ltd.",
   "repository": {
     "type": "git",