@hexis-ai/engram-sdk 0.3.0 → 0.5.0

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import type { ScoredSession, SearchOptions, Session, SessionStep } from "@hexis-ai/engram-core";
 import { type RefCandidate } from "./extract";
-import type { EventBatch, PersonCreate, PersonInfo, PersonMap, PersonUpdate, SessionEvent, SessionInit } from "./types";
+import type { AliasInfo, AliasUpsert, EventBatch, IdentityInfo, IdentityUpsert, PersonCreate, PersonInfo, PersonMap, PersonUpdate, SessionEvent, SessionInit } from "./types";
 /**
  * Envelope returned by session endpoints. The persons map is deduped
  * across whatever sessions the response carries so display info isn't
@@ -142,6 +142,29 @@ export declare class Engram {
             channel?: string;
             scope?: "participant" | "viewable";
         }) => Promise<SessionListEnvelope>;
+        /**
+         * Upsert an alias for this person. Name comparisons are
+         * case-insensitive — writing `Yuuri` and `YUURI` hits the same row.
+         */
+        upsertAlias: (id: string, name: string, input: AliasUpsert) => Promise<AliasInfo>;
+        /** This person's aliases, newest-used-first. */
+        aliases: (id: string) => Promise<{
+            aliases: AliasInfo[];
+        }>;
+        /** This person's identities, newest-linked-first. */
+        identities: (id: string) => Promise<{
+            identities: IdentityInfo[];
+        }>;
+    };
+    /** Identity operations — resolve a global ref (`slack:U…`, `email:…`)
+     *  to its identity record + person id. */
+    readonly identities: {
+        /** Upsert by ref. Refs are reassignable — writing with a new
+         *  `person_id` reroutes the ref. Returns 404 if `person_id` is
+         *  unknown. */
+        upsert: (ref: string, input: IdentityUpsert) => Promise<IdentityInfo>;
+        /** Look up by ref. Returns 404 if the ref is unknown. */
+        get: (ref: string) => Promise<IdentityInfo>;
     };
     /** Internal: ship an event batch to the server. */
     sendBatch(sessionId: string, batch: EventBatch): Promise<void>;

package/dist/client.js

@@ -97,6 +97,25 @@ export class Engram {
             const tail = qs.toString();
             return this.request("GET", `/v1/persons/${encodeURIComponent(id)}/sessions${tail ? `?${tail}` : ""}`);
         },
+        /**
+         * Upsert an alias for this person. Name comparisons are
+         * case-insensitive — writing `Yuuri` and `YUURI` hits the same row.
+         */
+        upsertAlias: (id, name, input) => this.request("PUT", `/v1/persons/${encodeURIComponent(id)}/aliases/${encodeURIComponent(name)}`, input),
+        /** This person's aliases, newest-used-first. */
+        aliases: (id) => this.request("GET", `/v1/persons/${encodeURIComponent(id)}/aliases`),
+        /** This person's identities, newest-linked-first. */
+        identities: (id) => this.request("GET", `/v1/persons/${encodeURIComponent(id)}/identities`),
+    };
+    /** Identity operations — resolve a global ref (`slack:U…`, `email:…`)
+     *  to its identity record + person id. */
+    identities = {
+        /** Upsert by ref. Refs are reassignable — writing with a new
+         *  `person_id` reroutes the ref. Returns 404 if `person_id` is
+         *  unknown. */
+        upsert: (ref, input) => this.request("PUT", `/v1/identities/${encodeURIComponent(ref)}`, input),
+        /** Look up by ref. Returns 404 if the ref is unknown. */
+        get: (ref) => this.request("GET", `/v1/identities/${encodeURIComponent(ref)}`),
     };
     /** Internal: ship an event batch to the server. */
     async sendBatch(sessionId, batch) {

package/dist/index.d.ts

@@ -3,4 +3,4 @@ export { extractReferences, encodeResourceId, type RefCandidate, type ReferenceS
 export { parseToolName, type ParsedToolName } from "./tool-name";
 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 type { SessionInit, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, EventBatch, PersonInfo, PersonCreate, PersonUpdate, PersonMap, } from "./types";
+export type { SessionInit, SessionAck, SessionEvent, StepEvent, ParticipantEvent, TitleEvent, EndEvent, EventBatch, PersonInfo, PersonCreate, PersonUpdate, PersonMap, AliasInfo, AliasUpsert, IdentityInfo, IdentityUpsert, } from "./types";

package/dist/types.d.ts

@@ -76,6 +76,67 @@ export interface PersonCreate {
 export interface PersonUpdate {
     display_name?: string | null;
 }
+/**
+ * One alias (alternate name) for a person, mirrored from monet's
+ * identity-resolution layer. Names are stored case-sensitively for
+ * display but compared lowercase, so writing "Yuuri" and "YUURI" hits
+ * the same row.
+ */
+export interface AliasInfo {
+    person_id: string;
+    name: string;
+    /** Provenance tag — e.g. `slack-resolver`, `manual`, `gcal-attendee`. */
+    caller: string;
+    usage_count: number;
+    /** Calendar date (`YYYY-MM-DD`) of the most recent use. */
+    last_used: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface AliasUpsert {
+    caller: string;
+    /** `YYYY-MM-DD`. */
+    last_used: string;
+    /**
+     * When the alias already exists, bump `usage_count` by 1 and replace
+     * `caller` / `last_used` with the new values. Default true. Pass
+     * `false` for idempotent backfills where you want the existing row
+     * untouched if it already exists.
+     */
+    increment?: boolean;
+}
+/**
+ * One external identity mapped to an engram person. Hosts (monet) use
+ * the same ref convention they always have — `slack:U12345`,
+ * `email:foo@bar.com`, `google:1234567890` — so engram can serve as
+ * the resolver for any system that already speaks that vocabulary.
+ */
+export interface IdentityInfo {
+    /** Stable global handle, e.g. `slack:U12345`. */
+    ref: string;
+    person_id: string;
+    service: string;
+    external_id: string;
+    display_name: string | null;
+    source: string | null;
+    is_primary: boolean | null;
+    picture: string | null;
+    /** `YYYY-MM-DD`. */
+    linked_at: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface IdentityUpsert {
+    person_id: string;
+    service: string;
+    external_id: string;
+    display_name?: string | null;
+    source?: string | null;
+    is_primary?: boolean | null;
+    picture?: string | null;
+    /** `YYYY-MM-DD`. */
+    linked_at: string;
+}
 /**
  * Map of person_id → PersonInfo, deduped across whatever `Session`s the
  * response contains. Returned at the envelope level so list responses

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexis-ai/engram-sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Host SDK for engram. Records agent session steps and ships them to an engram server.",
   "keywords": [
     "engram",