@hexis-ai/engram-sdk 0.11.0 → 0.12.0

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.
@@ -106,6 +147,12 @@ export class BufferedTelemetry {
 class BufferedSession {
     engram;
     id;
+    /**
+     * Resolves to `true` when POST /v1/sessions acked, `false` on
+     * transport failure. Never rejects — preserves Bun's strict
+     * unhandled-rejection contract even when callers don't await
+     * the buffer (Langfuse-style fire-and-forget).
+     */
     ready;
     inner;
     ended = false;
@@ -113,14 +160,12 @@ class BufferedSession {
         this.engram = engram;
         this.id = init.id;
         this.inner = new EngramSession(engram, init.id);
-        // Fire-and-forget POST /v1/sessions. The ready promise is awaited
-        // before the first flush so messages enqueued before the create
-        // ack don't race.
         this.ready = engram
             .startSessionWithoutHandle(init)
+            .then(() => true)
             .catch((e) => {
             engram.config.onError(e);
-            throw e;
+            return false;
         });
     }
     message(input) {
@@ -170,9 +215,6 @@ class BufferedSession {
      * info and the host now has more (e.g. resolved channel later).
      */
     update(input) {
-        // Only patch the fields callers might actually mutate post-creation;
-        // skip `participants` / `viewable_by` which are append-only via
-        // participant events.
         const patch = {};
         if (input.title !== undefined)
             patch.title = input.title;
@@ -190,33 +232,28 @@ class BufferedSession {
             patch.trigger_event_id = input.trigger_event_id;
         if (Object.keys(patch).length === 0)
             return;
-        void this.ready
-            .then(() => this.engram.updateSession(this.id, patch))
-            .catch((e) => this.engram.config.onError(e));
+        void this.ready.then((ok) => {
+            if (!ok)
+                return;
+            return this.engram
+                .updateSession(this.id, patch)
+                .catch((e) => this.engram.config.onError(e));
+        });
     }
     async flush() {
-        // Don't fail downstream flushes if the create eventually succeeds
-        // after a retry — but skip flushing if the create has permanently
-        // failed (ready rejected).
-        try {
-            await this.ready;
-        }
-        catch {
+        const ok = await this.ready;
+        if (!ok)
             return;
-        }
-        await this.inner.flush();
+        await this.inner.flush().catch((e) => this.engram.config.onError(e));
     }
     async shutdown() {
         if (this.ended)
             return;
         this.ended = true;
-        try {
-            await this.ready;
-        }
-        catch {
+        const ok = await this.ready;
+        if (!ok)
             return;
-        }
-        await this.inner.end();
+        await this.inner.end().catch((e) => this.engram.config.onError(e));
     }
 }
 // --- Helpers --------------------------------------------------------------

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 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.0",
+  "version": "0.12.0",
   "author": "hexis ltd.",
   "repository": {
     "type": "git",