@hexis-ai/engram-sdk 0.11.1 → 0.13.0

package/dist/admin.d.ts

@@ -48,6 +48,34 @@ 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;
@@ -63,6 +91,16 @@ 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[]>;
     private request;
 }
 export declare function createAdminClient(opts: AdminClientOptions): EngramAdmin;

package/dist/admin.js

@@ -41,6 +41,41 @@ export class EngramAdmin {
     async revokeKey(workspaceId, keyId) {
         await this.request("DELETE", `/admin/v1/workspaces/${encodeURIComponent(workspaceId)}/keys/${encodeURIComponent(keyId)}`);
     }
+    // ---------- 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;
+    }
     async request(method, path, body) {
         const headers = {
             "content-type": "application/json",

package/dist/buffered.d.ts

@@ -70,6 +70,47 @@ export type TelemetryEvent = {
     type: "end";
     at?: string;
 };
+/**
+ * Person observation. Same Langfuse-style semantics as session():
+ * host-supplied id, idempotent on the engram side (PUT /v1/persons/:id).
+ * Subsequent calls with the same id COALESCE — partial-info updates
+ * never clobber richer fields set earlier.
+ */
+export interface TelemetryPerson {
+    id: string;
+    displayName?: string;
+    role?: string | null;
+    team?: string | null;
+    source?: string;
+}
+/**
+ * Identity observation — links a global ref like `slack:U12345` or
+ * `email:foo@bar.com` to a person id. Idempotent (PUT
+ * /v1/identities/:ref); writing a new person_id reroutes the ref.
+ */
+export interface TelemetryIdentity {
+    ref: string;
+    personId: string;
+    service: string;
+    externalId: string;
+    displayName?: string | null;
+    source?: string | null;
+    picture?: string | null;
+    isPrimary?: boolean | null;
+    linkedAt: string;
+}
+/**
+ * Alias observation — a name the person goes by. The engram side
+ * key-collapses on (person_id, lower(name)); same name twice with
+ * `increment: true` bumps usage_count (default).
+ */
+export interface TelemetryAlias {
+    personId: string;
+    name: string;
+    caller: string;
+    lastUsed: string;
+    increment?: boolean;
+}
 /**
  * Internal coordinator that owns per-session buffers and gates flushes
  * on session-creation acks. Exposed on the parent Engram via
@@ -94,6 +135,17 @@ export declare class BufferedTelemetry {
     message(input: TelemetryMessage): void;
     /** Observe an arbitrary session event (participant / title / step / end). */
     event(input: TelemetryEvent): void;
+    /**
+     * Observe a person. Unlike session events these don't fan out to a
+     * per-session buffer — each call is an immediate fire-and-forget
+     * PUT via the SDK's low-level `persons.upsert`. Transport failures
+     * surface via onError and are not retried.
+     */
+    person(input: TelemetryPerson): void;
+    /** Observe an identity (ref → person_id link). */
+    identity(input: TelemetryIdentity): void;
+    /** Observe an alias (person nickname). */
+    alias(input: TelemetryAlias): void;
     /**
      * Drain every per-session buffer in parallel. Safe to call at any
      * point; failures route to onError, never thrown.

package/dist/buffered.js

@@ -76,6 +76,47 @@ export class BufferedTelemetry {
         }
         handle.event(input);
     }
+    /**
+     * Observe a person. Unlike session events these don't fan out to a
+     * per-session buffer — each call is an immediate fire-and-forget
+     * PUT via the SDK's low-level `persons.upsert`. Transport failures
+     * surface via onError and are not retried.
+     */
+    person(input) {
+        void this.engram.persons
+            .upsert(input.id, {
+            ...(input.displayName !== undefined ? { display_name: input.displayName } : {}),
+            ...(input.role !== undefined ? { role: input.role } : {}),
+            ...(input.team !== undefined ? { team: input.team } : {}),
+            ...(input.source !== undefined ? { source: input.source } : {}),
+        })
+            .catch((e) => this.engram.config.onError(e));
+    }
+    /** Observe an identity (ref → person_id link). */
+    identity(input) {
+        void this.engram.identities
+            .upsert(input.ref, {
+            person_id: input.personId,
+            service: input.service,
+            external_id: input.externalId,
+            ...(input.displayName !== undefined ? { display_name: input.displayName } : {}),
+            ...(input.source !== undefined ? { source: input.source } : {}),
+            ...(input.picture !== undefined ? { picture: input.picture } : {}),
+            ...(input.isPrimary !== undefined ? { is_primary: input.isPrimary } : {}),
+            linked_at: input.linkedAt,
+        })
+            .catch((e) => this.engram.config.onError(e));
+    }
+    /** Observe an alias (person nickname). */
+    alias(input) {
+        void this.engram.persons
+            .upsertAlias(input.personId, input.name, {
+            caller: input.caller,
+            last_used: input.lastUsed,
+            ...(input.increment !== undefined ? { increment: input.increment } : {}),
+        })
+            .catch((e) => this.engram.config.onError(e));
+    }
     /**
      * Drain every per-session buffer in parallel. Safe to call at any
      * point; failures route to onError, never thrown.

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import type { ScoredSession, SearchOptions, Session, SessionStep } from "@hexis-ai/engram-core";
 import { type RefCandidate } from "./extract";
 import type { AliasInfo, AliasUpsert, EventBatch, IdentityInfo, IdentityUpsert, MessageContentBlock, PersonCreate, PersonInfo, PersonMap, PersonUpdate, SessionEvent, SessionInit, SessionUpdate } from "./types";
-import { type TelemetryEvent, type TelemetryMessage, type TelemetrySession } from "./buffered";
+import { type TelemetryAlias, type TelemetryEvent, type TelemetryIdentity, type TelemetryMessage, type TelemetryPerson, type TelemetrySession } from "./buffered";
 /**
  * Envelope returned by session endpoints. The persons map is deduped
  * across whatever sessions the response carries so display info isn't
@@ -117,6 +117,24 @@ export declare class Engram {
      * tool step, end). Same fire-and-forget contract.
      */
     event(input: TelemetryEvent): void;
+    /**
+     * Observe a person record (display_name / role / team / source).
+     * Idempotent on the engram side — partial-info updates COALESCE.
+     * Fire-and-forget; transport failures route to `onError`.
+     */
+    person(input: TelemetryPerson): void;
+    /**
+     * Observe an identity (`slack:U1`, `email:foo@bar.com`, …) and link
+     * it to a person id. Writing a new person_id to an existing ref
+     * reroutes the ref. Fire-and-forget.
+     */
+    identity(input: TelemetryIdentity): void;
+    /**
+     * Observe an alias (a name the person goes by). Engram side
+     * collapses on (person_id, lower(name)); same name twice with
+     * `increment: true` bumps usage_count. Fire-and-forget.
+     */
+    alias(input: TelemetryAlias): void;
     /**
      * Drain every per-session buffer. Call before short-lived processes
      * exit; long-lived servers can rely on auto-flush (flushIntervalMs).

package/dist/client.js

@@ -60,6 +60,30 @@ export class Engram {
     event(input) {
         this.bufferedTelemetry.event(input);
     }
+    /**
+     * Observe a person record (display_name / role / team / source).
+     * Idempotent on the engram side — partial-info updates COALESCE.
+     * Fire-and-forget; transport failures route to `onError`.
+     */
+    person(input) {
+        this.bufferedTelemetry.person(input);
+    }
+    /**
+     * Observe an identity (`slack:U1`, `email:foo@bar.com`, …) and link
+     * it to a person id. Writing a new person_id to an existing ref
+     * reroutes the ref. Fire-and-forget.
+     */
+    identity(input) {
+        this.bufferedTelemetry.identity(input);
+    }
+    /**
+     * Observe an alias (a name the person goes by). Engram side
+     * collapses on (person_id, lower(name)); same name twice with
+     * `increment: true` bumps usage_count. Fire-and-forget.
+     */
+    alias(input) {
+        this.bufferedTelemetry.alias(input);
+    }
     /**
      * Drain every per-session buffer. Call before short-lived processes
      * exit; long-lived servers can rely on auto-flush (flushIntervalMs).

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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 { BufferedTelemetry, type TelemetrySession, type TelemetryMessage, type TelemetryEvent, } from "./buffered";
+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.11.1",
+  "version": "0.13.0",
   "author": "hexis ltd.",
   "repository": {
     "type": "git",