Ada SDK for TypeScript

The backend client represents one authenticated namespace and shares one lazy, persistent gRPC stream per category across every principal facade.

Installation

npm install @eleven-am/ada-sdk

Node.js 20 or newer is required. Construct the backend client only in trusted server code; apiKey authenticates the entire namespace.

Backend client

import { AdaClient } from "@eleven-am/ada-sdk"

const ada = new AdaClient({
  endpoint: "https://memory.example.com",
  apiKey: process.env.ADA_API_KEY!,
  streams: {
    events: { afterEventId: savedCursor, replayLimit: 100 },
  },
})

const alice = ada.principal("alice")
const bob = ada.principal("bob")

const stopAlice = alice.events.on("memory.ingest.finished", event => {
  console.log(event.documentId)
})
const stopBob = bob.signals.on("routine.broken", signal => {
  console.log(signal)
})
const stopJob = alice.jobs.on("job.progressed", event => {
  console.log(event)
})

ada.lifecycle.on("stream.cursor", info => save(info))
ada.lifecycle.on("listener.error", info => report(info))

await alice.getMeEntity()
await ada.getPublicEventCatalog()
await ada.getSignalCatalog()

stopAlice()
stopAlice()
stopBob()
stopJob()
await ada.close()

principal("alice") accepts only a bare ID and returns a cached facade. All ingest, recall, documents, jobs, data, and summary operations are available through that facade. For example, alice.ingest(request), alice.recall(request), alice.documents.getStatus(request), and alice.data.listDocuments(request) always overwrite the request principal with "alice". The root exposes only namespace responsibilities such as catalogs, lifecycle, browser-session minting, and close.

Recall provenance is typed on each knowledge item's source:

const recalled = await alice.recall({ query: "What changed?" })
for (const item of recalled.knowledge) {
  console.log(item.source?.sourceAuthorities, item.source?.memoryGrade)
}

Use these fields instead of deprecated compatibility values in item.data.

events.on, signals.on, and jobs.on are keyed generic APIs. The literal event name determines the exact protobuf payload type and each call returns an idempotent synchronous unsubscribe function. There is no public stream object, open(), subscribe(), or async iterator.

Replay configuration belongs to the root streams.events, streams.signals, and streams.jobs options. Each accepts afterEventId, replayLimit, and bounded reconnect settings. Persist info.eventId from the typed stream.cursor lifecycle event only after the SDK has decoded and routed the envelope:

const stopCursor = ada.lifecycle.on("stream.cursor", info => {
  saveCursor(info.stream, info.eventId, info.principalId)
})

const stopTerminal = ada.lifecycle.on("stream.terminal", info => {
  reportTerminalStreamFailure(info.stream, info.error)
})

Call await ada.close() during shutdown. It is idempotent, stops reconnects, closes all three shared streams, and rejects later listener registration.

Browser

import { AdaBrowserClient } from "@eleven-am/ada-sdk/browser"

const ada = new AdaBrowserClient({
  endpoint: "https://memory.example.com",
  sessionToken,
})

const unsubscribe = ada.events.on("memory.recall.finished", event => {
  console.log(event)
})

unsubscribe()
await ada.close()

AdaBrowserClient uses gRPC-Web and is already bound to the principal encoded in its short-lived session. It has no principal() method, accepts no API key, and uses only principal-scoped streams. Never ship a namespace API key to a browser.

Mint the short-lived session in backend code with ada.createBrowserSession({ principalId: "alice", ... }), then send only its session token to the browser.