TypeScript SDK
/v1 routes and some wrappers are removed or reshaped (tenant administration, cluster operations, webhooks, dedup tokens, media embedding). See the SDK changes. Python, TypeScript and Go are the only supported SDKs.npm install @zysec-ai/relata-sdk — zero runtime dependencies. Uses native fetch, so it runs unchanged in Node.js 18+, Deno, Bun, modern browsers, and edge runtimes (Cloudflare Workers, Vercel Edge). Optional peer deps: apache-arrow + @grpc/grpc-js for Arrow Flight, @langchain/* for the adapters.
See the SDK overview for the cross-language parity matrix. This page is the TypeScript capability catalog.
Quickstart
npm install @zysec-ai/relata-sdkimport { createClient, IngestClient } from "@zysec-ai/relata-sdk";
const relata = createClient("http://localhost:9090", {
defaultPurpose: "analytics",
bearerToken: process.env.RELATA_TOKEN,
});
// /query is read-only (#782) — writes go through the governed ingest door.
const ingest = IngestClient.fromClient(relata);
await ingest.bulk("Person", [{ id: "p1", name: "Alice", email: "a@x.com" }]);
const result = await relata.query("SELECT * FROM Person LIMIT 5");
for (const row of result.rows) console.log(row.name, row.email);The SDK is async-native — every method returns a Promise. Native fetch means no connection pool to close.
The query surface
| Path | Method | Returns |
|---|---|---|
| SQL | query<T>(sql, opts?) | QueryResult<T> — opts.dialect: "sql" | "cypher" | "gql" |
| Parameterized | queryWithParams<T>(sql, params, opts?) | QueryResult<T> |
| Arrow Flight (gRPC) | queryFlight<T>(sql, opts?) | apache-arrow Table (optional peer) |
| GraphQL | graphql(query, variables?, operationName?) | unknown — variables bound server-side (#3260) |
| SPARQL | sparql(query) | Record |
| Cypher | any MATCH-prefixed string via query() | auto-routed, governed |
| GQL (ISO 39075) | query(stmt, { dialect: "gql" }) | header-selected, governed (#3265) |
| Fluent builder | relata.select("Person").where(...).limit(10).execute<T>() | QueryResult<T> |
| Paths builder | relata.select("Person").pathsBetween("a","b",{maxHops:5}).execute() | QueryResult |
import { createClient } from "@zysec-ai/relata-sdk";
const relata = createClient("http://localhost:9090", { defaultPurpose: "investigation" });
const paths = await relata.select("Person")
.pathsBetween("alice-id", "bob-id", { maxHops: 5 })
.withProvenance()
.execute();Typed domain clients
Each typed client has a static fromClient(client) factory inheriting auth/tenant/purpose/timeout:
import {
GovernanceClient, IdentityClient, ObjectClient, IngestClient,
VectorClient, SearchClient, StreamingClient, AuditClient,
TenantAdminClient, BackupClient, TokenClient, LogClient,
SystemClient, A2AClient, McpClient, S3Client,
} from "@zysec-ai/relata-sdk";| Client | Key methods | Cross-ref |
|---|---|---|
GovernanceClient | rules CRUD, Sigma import, retention/WORM/legal-holds, breakglass, alerts, DSAR | Detection Rules |
IdentityClient | label, recordUncertainty, registerLookup/listLookups/invokeLookup, eraseSubject | Identity |
ObjectClient | upsert, typedUpsert, batchUpsert, get, delete, list (TS-only) | — |
IngestClient | bulk, bulkCsv, ingestAuto, ingestCdr, otlpTraces/Logs/Metrics, ingestIter (AsyncIterable) | Ingestion |
VectorClient | knnSearch, hybridSearch, similarTo, embed/embedBatch + embedImage/Face/Audio/Video | Hybrid Search |
SearchClient | typed /search JSON door: query<T>({from, text, rankBy, filters, limit, ...}) | Search reference |
StreamingClient | queryRows (NDJSON), queryArrowRaw, watch (SSE), alerts (SSE) — all async generators | — |
AuditClient | count, entries, findByRequestId, signReceipt, exportPdf → Uint8Array | — |
TenantAdminClient | tenant CRUD, quota, sharing, platform usage/license | Enterprise edition only; the open build has one tenant |
BackupClient | create, list, restore, restoreStatus, compact, waitForRestore | Backup & Restore |
TokenClient | remember, check, revoke, stats | — |
LogClient | append, head, loadLeaves | — |
SystemClient | LLM config/test, jobs/workflows, feeds, notifications, pipelines | — |
A2AClient | submitTask, getTask, checkpoints, agentCard | — |
McpClient | initialize, listTools, callTool + 68 typed wrappers | MCP Tools |
S3Client | http, listBuckets, createBucket, putObject, getObject, deleteObject | S3 door |
Vectors & embeddings
const vc = new VectorClient(relata);
// Pure KNN over a named slot
const knn = await vc.knnSearch("Document", "embedding", [0.1,...], { k: 10, efSearch: 200 });
// Hybrid: BM25 + vector + graph, RRF-fused
const hybrid = await vc.hybridSearch("Document",
{ queryText: "graph retrieval", k: 10, rerank: true, weights: [0.2, 0.5, 0.3] });
// Embedding (6 modalities)
const e = await vc.embed("Alice Smith"); // → {embedding, model, dim}
await vc.embedImage(b64); await vc.embedFace(b64);
await vc.embedAudio(b64); await vc.embedVideo(b64);Graph & intelligence operators
All on RelataClient — 10 graph algorithms + 10 AML/financial + 3 maritime:
await relata.graphPageRank("Person", { damping: 0.85, maxIter: 20 });
await relata.graphShortestPath("alice-id", "bob-id", { maxHops: 5 });
await relata.graphCommunity("Person");
await relata.sanctionsScreen("Acme Holdings", { threshold: 0.85 });
await relata.beneficialOwnershipChain("Acme Holdings", { maxDepth: 6 });
await relata.cryptoTrace("0xabc...", "compliance");
await relata.vesselTrack(123456789, { windowSecs: 86400 });
await relata.darkFleetDetect({ maxGapHours: 48 });See Graph Analytics.
Agent memory — 10 cognitive verbs + recall-quality knobs
import { Memory } from "@zysec-ai/relata-sdk";
const mem = new Memory("http://localhost:9090", { purpose: "agent", bearerToken: "<token>" });
const id = await mem.add("Alice prefers dark mode", { confidence: 0.9 });
// retrieval-quality operators
const results = await mem.search("ui preferences", {
topK: 10, minConfidence: 0.6, recencyHalfLifeSecs: 259200,
budgetTokens: 1500, cancelThreshold: 0.92,
});
const detail = await mem.searchDetailed("ui preferences", { /* same opts */ });
// detail.recall_cost_tokens + detail.cancelled — observe the knobs' effectFull verb set: add, addBatch, search, searchDetailed, get, update, forget, associate, episodes, justify, resolve, summarise. See Agent memory reference.
Ecosystem (TS extras)
| Extra | Surface |
|---|---|
| LangChain adapter | RelataMemory — duck-typed BaseMemory (loadMemoryVariables, saveContext, clear) |
| LlamaIndex adapter | RelataMemory — put/get/getAll/reset |
| LangGraph checkpointer | RelataCheckpointer — real BaseCheckpointSaver subclass (getTuple/list/put/putWrites; deleteThread throws — server has no DELETE route) |
| Arrow Flight transport | ArrowFlightTransport + createArrowFlightTransport() — hand-rolled protobuf codec, no proto-loader |
| CLI binary | npx @zysec-ai/relata-sdk — health, status, audit (exit 2 on broken chain), nodes, query <sql>; reads RELATA_TOKEN/RELATA_PURPOSE |
Install the optional peers (@langchain/langgraph-checkpoint, @langchain/core, apache-arrow, @grpc/grpc-js) to activate the matching surface.
Authentication & multi-tenant
const relata = createClient("http://localhost:9090", {
bearerToken: process.env.RELATA_TOKEN,
defaultPurpose: "analytics",
tenant: "org-acme", // X-Relata-Tenant-Id on every request
actingAs: "user-42", // X-Acting-As (delegation)
delegatedBy: "admin-1", // X-Delegated-By
timeoutMs: 15_000,
maxRetries: 3,
retryBackoffMs: 500,
adminBaseUrl: "http://admin.internal:9090", // /admin/* + /platform/* split
});Runtime compatibility
Native fetch, zero deps — runs in Node.js 18+, Deno, Bun, modern browsers, Cloudflare Workers, Vercel Edge Functions.
Examples
~25 runnable examples in sdks/typescript/examples/. Run with Node 23+ (--experimental-strip-types), Deno, or Bun:
RELATA_TOKEN=secret node --experimental-strip-types examples/basic-query.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/memory-quickstart.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/intelligence.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/graph-algorithms.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/streaming.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/face-search.tsFull set: sdks/typescript/examples/.
Next steps
- Search and retrieval — typed
/search, multi-query batch + RRF - Agent memory reference — 10 verbs + recall-quality knobs
- Graph analytics — 10+ algorithms,
gds.*portability - Query cookbook
- Full TypeScript SDK source