@hydradb/sdk 0.0.2 → 2.0.0

package/README.md

@@ -1,143 +1,248 @@
 # Hydra DB TypeScript SDK
 
-The official TypeScript SDK for the Hydra DB platform. Build powerful, context-aware AI applications in your Node.js or TypeScript projects.
+The official TypeScript SDK for the Hydra DB platform.
 
-**Hydra DB** is your plug-and-play memory infrastructure. It powers intelligent, context-aware retrieval for any AI app or agent. Whether you're building a customer support bot, research copilot, or internal knowledge assistant - Hydra DB handles all!
+Hydra DB provides memory, knowledge ingestion, retrieval, and graph context for AI applications.
 
-[Learn more about the SDK from our docs](https://docs.hydradb.com/)
+[Hydra DB docs](https://docs.hydradb.com/)
 
-## Core features
+## Features
 
-* **Dynamic retrieval and querying** that always retrieves the most relevant context
-* **Built-in long-term memory** that evolves with every user interaction
-* **Personalization hooks** for user preferences, intent, and history
-* **Raw embeddings support** for bring-your-own vector workflows
-* **Developer-first SDK** with the most flexible APIs and fine-grained controls
+- Ingest knowledge files, app-generated knowledge, and memories
+- Track ingestion/indexing status of sources
+- Retrieve knowledge and/or memory with a single `query` call (hybrid or keyword search, optional graph context)
+- Inspect, list, and delete sources, and fetch graph relations
+- Manage tenants and sub-tenants
+- Register and manage webhooks and inspect deliveries
+- Format retrieval results for LLM prompts with `buildString`
+- Make authenticated passthrough requests for endpoints not yet wrapped by the SDK
 
-## Getting started
+## Installation
 
-### Installation
-
-```
-npm i @hydra_db/node
+```bash
+npm install @hydradb/sdk
 # or
-yarn add @hydra_db/node
+yarn add @hydradb/sdk
 # or
-pnpm add @hydra_db/node
+pnpm add @hydradb/sdk
 ```
 
-### Client setup
+## Client setup
 
 ```ts
-import { HydraDBClient } from "@hydra_db/node";
-
-process.loadEnvFile(".env");
+import { HydraDBClient } from "@hydradb/sdk";
 
 const client = new HydraDBClient({
   token: process.env.HYDRA_DB_API_KEY,
 });
 
 const TENANT_ID = process.env.HYDRA_TENANT_ID ?? "my-company";
-const SUB_TENANT_ID = process.env.HYDRA_SUB_TENANT_ID ?? "";
+const SUB_TENANT_ID = process.env.HYDRA_SUB_TENANT_ID ?? "my-sub-tenant";
+```
+
+The default API base URL is:
+
+```text
+https://api.hydradb.com
 ```
 
----
+For an on-prem deployment, pass `baseUrl`:
+
+```ts
+const localClient = new HydraDBClient({
+  token: process.env.HYDRA_DB_API_KEY,
+  baseUrl: "https://<id>.hydradb.<domain>",
+});
+```
+
+The client targets API version `2` by default; override it with `apiVersion`. Other client options include `headers`, `timeoutInSeconds` (default `60`), `maxRetries`, `environment`, and a custom `fetch` implementation.
+
+> Note: request fields use **camelCase** (`tenantId`, `subTenantId`, `maxResults`, …). The SDK serializes them to the API's snake_case on the wire.
+
+## Client structure
+
+All functionality is reached through one top-level method and three sub-clients:
+
+| Accessor | Purpose |
+|---|---|
+| `client.query(...)` | Retrieve knowledge and/or memory in a single call. |
+| `client.context` | Ingest, inspect, list, delete sources, and fetch graph relations. |
+| `client.tenants` | Create, list, delete, and inspect tenants. |
+| `client.webhooks` | Register and manage webhooks and inspect deliveries. |
+
+## Important tenant and sub-tenant rule
+
+Use the same `tenantId` and `subTenantId` across ingest, status, query, inspect, list, and delete calls.
 
-## Tenant Management
+If you ingest with a `subTenantId` and then check status or search without it, you may be looking at a different namespace. Omitting `subTenantId` uses the default sub-tenant created during tenant setup.
 
-A `tenant` is a single isolated database. Within it you can create further isolated collections called `sub-tenants`. [Learn more](https://docs.hydradb.com/essentials/multi-tenant)
+## Tenant management
 
-### Create a Tenant
+A tenant is the top-level isolated database. A sub-tenant is an optional isolated collection inside a tenant.
+
+### Create a standard tenant
 
 ```ts
-const tenantResponse = await client.tenant.create({
-  tenant_id: TENANT_ID,
+await client.tenants.create({
+  tenantId: TENANT_ID,
 });
 ```
 
-You can also create a tenant optimised for raw vector embeddings:
+### Create an embeddings tenant
+
+Provide `embeddingsDimension` and set `isEmbeddingsTenant: true`.
 
 ```ts
-const embeddingsTenant = await client.tenant.create({
-  tenant_id: "my-embeddings-tenant",
-  is_embeddings_tenant: true,
-  embeddings_dimension: 1536,
+await client.tenants.create({
+  tenantId: "my-embeddings-tenant",
+  isEmbeddingsTenant: true,
+  embeddingsDimension: 1536,
 });
 ```
 
-### Get Sub-Tenant IDs
+### Create a tenant with a metadata schema
+
+Each field can enable filtering (`enableMatch`), semantic search (`enableDenseEmbedding`), and/or keyword search (`enableSparseEmbedding`). Fields with embeddings enabled must be string-typed.
 
 ```ts
-const subTenants = await client.tenant.getSubTenantIds({
-  tenant_id: TENANT_ID,
+await client.tenants.create({
+  tenantId: TENANT_ID,
+  tenantMetadataSchema: [
+    {
+      name: "department",
+      dataType: "string",
+      enableMatch: true,
+      enableDenseEmbedding: false,
+      enableSparseEmbedding: false,
+    },
+  ],
 });
-// subTenants.sub_tenant_ids -> string[]
 ```
 
-### Get Infrastructure Status
+### List tenants
+
+```ts
+const tenants = await client.tenants.list();
+console.log(tenants);
+```
+
+### List sub-tenants
 
-Check whether the tenant's underlying infrastructure is ready:
+```ts
+const subTenants = await client.tenants.subTenants({
+  tenantId: TENANT_ID,
+});
+
+console.log(subTenants);
+```
+
+### Check tenant infrastructure status
 
 ```ts
-const infraStatus = await client.tenant.getInfraStatus({
-  tenant_id: TENANT_ID,
+const infraStatus = await client.tenants.status({
+  tenantId: TENANT_ID,
 });
+
+console.log(infraStatus);
 ```
 
-### Monitor Tenant Stats
+### Tenant stats
 
 ```ts
-const stats = await client.tenant.monitor({
-  tenant_id: TENANT_ID,
+const stats = await client.tenants.stats({
+  tenantId: TENANT_ID,
 });
+
+console.log(stats);
 ```
 
-### Delete a Tenant
+### Delete a tenant
 
-> **Warning:** This is irreversible and permanently removes all data.
+> Warning: this permanently deletes the tenant and its data.
 
 ```ts
-await client.tenant.deleteTenant({
-  tenant_id: TENANT_ID,
+await client.tenants.delete({
+  tenantId: TENANT_ID,
 });
 ```
 
----
+## Ingest knowledge and memory
 
-## Index Your Data
+`client.context.ingest()` handles both knowledge files and memory, selected via the `type` field (`"knowledge"` or `"memory"`).
 
-### Upload Knowledge (Files)
+### Ingest one file
 
-Upload documents to make them retrievable via natural language search. Supports PDFs, text files, and other document formats.
+`documents` accepts a list of uploadable files. Each entry can be a file path (`{ path, filename?, contentType? }`), a file-like object with metadata (`{ data, filename?, contentType? }`), or a raw buffer/blob/stream.
 
 ```ts
-import fs from "node:fs";
+const uploadResult = await client.context.ingest({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
+  documents: [
+    {
+      path: "./report.pdf",
+      filename: "report.pdf",
+      contentType: "application/pdf",
+    },
+  ],
+  upsert: true,
+});
 
-const uploadResult = await client.upload.knowledge({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  files: [
-    fs.readFileSync("report.pdf"),
-    fs.readFileSync("notes.txt"),
+console.log(uploadResult);
+```
+
+The initial response typically reports a `queued` status — the file was accepted into the ingestion queue, not finished. Use `client.context.status()` to track progress.
+
+### Ingest multiple files
+
+```ts
+await client.context.ingest({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
+  documents: [
+    { path: "./a.pdf", filename: "a.pdf", contentType: "application/pdf" },
+    { path: "./notes.txt", filename: "notes.txt", contentType: "text/plain" },
   ],
   upsert: true,
 });
-// uploadResult.results[0].source_id -> ID you can use later
 ```
 
-You can attach metadata to each file by passing a JSON string. Each object in the array corresponds to the file at the same index:
+Buffers, blobs, and streams also work:
+
+```ts
+import { readFileSync } from "node:fs";
+
+await client.context.ingest({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
+  documents: [
+    {
+      data: readFileSync("./report.pdf"),
+      filename: "report.pdf",
+      contentType: "application/pdf",
+    },
+  ],
+});
+```
+
+### Ingest files with per-file metadata
+
+`documentMetadata` is a JSON **string** — a JSON array of per-file metadata objects (knowledge only). Each object may include `id`, `metadata`, `additional_metadata`, `infer`, and `relations`. Array length should match `documents`.
 
 ```ts
-const fileMetadata = [
+const documentMetadata = [
   {
     id: "doc_a",
-    tenant_metadata: { dept: "sales" },
-    document_metadata: { author: "Alice" },
+    metadata: { department: "sales" },
+    additional_metadata: { author: "Alice" },
   },
   {
     id: "doc_b",
-    tenant_metadata: { dept: "marketing" },
-    document_metadata: { author: "Bob" },
+    metadata: { department: "marketing" },
+    additional_metadata: { author: "Bob" },
     relations: {
       cortex_source_ids: ["doc_a"],
       properties: { relation: "same_upload_batch" },
@@ -145,426 +250,494 @@ const fileMetadata = [
   },
 ];
 
-const uploadWithMeta = await client.upload.knowledge({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  files: [
-    fs.readFileSync("a.pdf"),
-    fs.readFileSync("b.pdf"),
+await client.context.ingest({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
+  documents: [
+    { path: "./a.pdf", filename: "a.pdf", contentType: "application/pdf" },
+    { path: "./b.pdf", filename: "b.pdf", contentType: "application/pdf" },
   ],
-  file_metadata: JSON.stringify(fileMetadata),
+  documentMetadata: JSON.stringify(documentMetadata),
   upsert: true,
 });
 ```
 
-### Verify Processing Status
+### Ingest app-generated knowledge
 
-After uploading, check when files have finished indexing:
+`appKnowledge` is a JSON **string** — a single source object or an array of source objects (knowledge only).
 
 ```ts
-const status = await client.upload.verifyProcessing({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  file_ids: ["source-id-1", "source-id-2"],
+const appKnowledge = [
+  {
+    id: "app_source_1",
+    title: "CRM Account Note",
+    content: { text: "Acme is interested in the enterprise plan." },
+    type: "document",
+    tenant_metadata: { department: "sales" },
+    document_metadata: { source: "crm" },
+  },
+];
+
+await client.context.ingest({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
+  appKnowledge: JSON.stringify(appKnowledge),
+  upsert: true,
 });
-// status.statuses[0].indexing_status -> "queued" | "processing" | "completed" | "errored"
 ```
 
-### Add Memories
+### Add memories
 
-Index free-form text, markdown content, or conversation pairs as searchable memories.
-
-**Plain text:**
+`memories` is a JSON **string** — a JSON array of memory items (memory only). Each item can include `text`, `title`, `infer`, and `metadata`.
 
 ```ts
-await client.upload.addMemory({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
+const memories = [
+  {
+    source_id: "memory_001",
+    text: "User prefers detailed technical explanations.",
+    title: "User preference",
+    infer: true,
+    metadata: { category: "preference" },
+  },
+];
+
+await client.context.ingest({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "memory",
+  memories: JSON.stringify(memories),
   upsert: true,
-  memories: [
-    {
-      text: "User prefers detailed explanations and dark mode",
-      infer: true,
-      user_name: "John",
-    },
-  ],
 });
 ```
 
-**Markdown:**
+## Check ingestion status
+
+`client.context.status()` reports indexing status for one or more source IDs. Pass a single `id` or a list via `ids`.
 
 ```ts
-await client.upload.addMemory({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  upsert: true,
-  memories: [
-    {
-      text: "# Meeting Notes\n\n## Key Points\n- Budget approved\n- Launch date: Q2",
-      is_markdown: true,
-      infer: false,
-      title: "Meeting Notes",
-    },
-  ],
+const status = await client.context.status({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  ids: ["source-id-1", "source-id-2"],
 });
+
+console.log(status);
 ```
 
-**User–assistant conversation pairs:**
+### Poll until ingestion finishes
 
 ```ts
-await client.upload.addMemory({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  upsert: true,
-  memories: [
-    {
-      user_assistant_pairs: [
-        { user: "What are my preferences?", assistant: "You prefer dark mode and detailed explanations." },
-        { user: "How do I like my reports?", assistant: "You prefer weekly summary reports with charts." },
-      ],
-      infer: true,
-      user_name: "John",
-      custom_instructions: "Extract user preferences",
-    },
-  ],
-});
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function waitForIngestion(ids: string[]) {
+  while (true) {
+    const status = await client.context.status({
+      tenantId: TENANT_ID,
+      subTenantId: SUB_TENANT_ID,
+      ids,
+    });
+
+    // Inspect the returned status fields (per the SourceStatusApiResponse
+    // schema) and break once everything has completed or errored.
+    console.log(status);
+
+    await sleep(5000);
+  }
+}
 ```
 
-### Delete a Memory
+## Query (retrieval)
+
+`client.query()` is the single retrieval entry point. It searches knowledge, memory, or both, with optional graph context. It returns a promise resolving to a `QueryApiResponse`; the retrieval payload is on `.data`.
 
 ```ts
-await client.upload.deleteMemory({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  memory_id: "memory-source-id",
+const response = await client.query({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  query: "What did the account notes say about Acme?",
+  maxResults: 10,
+  mode: "fast",
+  alpha: 0.8,
+  recencyBias: 0,
+  graphContext: true,
 });
+
+console.log(response.data?.chunks);
+console.log(response.data?.sources);
 ```
 
----
+### Search knowledge, memory, or both
 
-## Search & Retrieval
+Use the `type` field:
 
-### Full Recall
+```ts
+// Knowledge only
+await client.query({ tenantId: TENANT_ID, query: "quarterly revenue", type: "knowledge" });
 
-Hybrid semantic + keyword search across both knowledge and memories:
+// Memory only
+await client.query({ tenantId: TENANT_ID, query: "user preferences", type: "memory" });
 
-```ts
-const results = await client.recall.fullRecall({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  query: "Which mode does the user prefer?",
-  alpha: 0.8,        // 1.0 = pure semantic, 0.0 = pure keyword
-  recency_bias: 0,   // 0.0 = no bias, 1.0 = strongly prefer recent
-  max_results: 10,
-});
-// results.chunks -> VectorStoreChunk[]
-// results.sources -> SourceInfo[]
+// Both, merged
+await client.query({ tenantId: TENANT_ID, query: "what does the user prefer", type: "all" });
 ```
 
-### Recall Preferences
+### Hybrid vs. keyword search
+
+`alpha` controls the hybrid balance and can be a number in `0.0`–`1.0` or the string `"auto"`:
 
-Search only user memory/preference data:
+- `1.0`: more semantic/vector weighted
+- `0.0`: more keyword/BM25 weighted
+- `"auto"`: backend chooses the balance
+
+For pure keyword/BM25 search, set `queryBy: "text"` and choose an `operator`:
 
 ```ts
-const preferences = await client.recall.recallPreferences({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  query: "dark mode preference",
-  max_results: 5,
+const response = await client.query({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  query: "enterprise plan",
+  queryBy: "text",
+  operator: "phrase", // "or" | "and" | "phrase"
+  type: "knowledge",
 });
 ```
 
-### Boolean Recall
+`queryBy` accepts `"hybrid"` (vector + BM25, default) or `"text"` (BM25 only). `operator` applies only when `queryBy: "text"`.
+
+### Metadata filters
 
-Exact keyword / phrase / boolean search (BM25):
+Top-level keys match tenant metadata (and must correspond to fields defined in `tenantMetadataSchema`). To filter on document-level fields you sent as `additional_metadata` at ingestion, nest them under `additional_metadata` (the key `document_metadata` is also accepted as a legacy alias).
 
 ```ts
-const boolResults = await client.recall.booleanRecall({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  query: "dark mode",
-  operator: "phrase",   // "or" | "and" | "phrase"
-  max_results: 10,
-  search_mode: "memories",  // "sources" | "memories"
+const response = await client.query({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  query: "revenue forecast",
+  maxResults: 10,
+  metadataFilters: {
+    department: "sales",
+    additional_metadata: { author: "Alice" },
+  },
 });
 ```
 
-### Q&A (LLM-powered answer)
+### All `query` options
 
-Ask a question and get a grounded answer generated by an LLM over your indexed content:
+| Option | Type | Description |
+|---|---|---|
+| `tenantId` | `string` | Tenant identifier (required). |
+| `query` | `string` | Search terms (required). |
+| `subTenantId` | `string` | Optional sub-tenant identifier. |
+| `maxResults` | `number` | Maximum number of results. |
+| `mode` | `string` | `"fast"` or `"thinking"`. |
+| `alpha` | `string \| number` | Hybrid balance (`0.0`–`1.0` or `"auto"`). |
+| `recencyBias` | `number` | Preference for newer content (`0.0`–`1.0`). |
+| `graphContext` | `boolean` | Enable graph context (on by default in v2; set `false` to omit). |
+| `queryForcefulRelations` | `boolean` | Search forceful relations in thinking mode. |
+| `additionalContext` | `string` | Extra context to guide retrieval. |
+| `queryApps` | `boolean` | Run a parallel app-aware retrieval lane and fuse results. |
+| `metadataFilters` | `object` | Key-value metadata filters. |
+| `type` | `string` | `"knowledge"`, `"memory"`, or `"all"`. |
+| `queryBy` | `string` | `"hybrid"` or `"text"`. |
+| `operator` | `string` | `"or"`, `"and"`, or `"phrase"` (only with `queryBy: "text"`). |
 
-```ts
-const answer = await client.recall.qna({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  question: "What is the user's preferred reporting format?",
-  mode: "fast",          // "fast" | "thinking"
-  search_mode: "memories",
-  max_chunks: 6,
-});
-```
+## Formatting results for an LLM
 
-You can optionally choose the LLM provider and model:
+`buildString` formats a query result (or its `.data`) into a plain string ready for prompt injection. It is exported from the package root and from `@hydradb/sdk/helpers`.
 
 ```ts
-const customAnswer = await client.recall.qna({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  question: "Summarise the budget decisions from the meeting notes.",
-  mode: "thinking",
-  search_mode: "sources",
-  max_chunks: 10,
-  llm_provider: "anthropic",
-  model: "claude-sonnet-4-6",
-  temperature: 0.2,
-  max_tokens: 1024,
+import { HydraDBClient, buildString } from "@hydradb/sdk";
+
+const client = new HydraDBClient({ token: process.env.HYDRA_DB_API_KEY });
+
+const response = await client.query({
+  tenantId: TENANT_ID,
+  query: "What does the user prefer?",
 });
-```
 
----
+// Pass the full envelope or just the data — buildString handles both.
+console.log(buildString(response));
+console.log(buildString(response.data!));
+```
 
-## Fetch & Inspect Data
+The output renders chunks under a `=== CONTEXT ===` header, with graph relations and synthesis context appended when present. If there is nothing to render, it returns `"No relevant context found."`.
 
-### List All Data
+## Inspect, list, and delete sources
 
-List sources (knowledge) or memories with optional filtering and pagination:
+### List sources
 
 ```ts
-// List knowledge sources
-const sources = await client.fetch.listData({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  kind: "knowledge",
+const sources = await client.context.list({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
   page: 1,
-  page_size: 50,
+  pageSize: 50,
 });
 
-// List user memories
-const memories = await client.fetch.listData({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  kind: "memories",
+console.log(sources);
+```
+
+List memories with `type: "memory"`.
+
+### Fetch specific source IDs
+
+```ts
+const sources = await client.context.list({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
+  ids: ["doc_a", "doc_b"],
 });
 ```
 
-Filter by metadata:
+### Filter listed data
 
 ```ts
-const filtered = await client.fetch.listData({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  kind: "knowledge",
+const filtered = await client.context.list({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
   filters: {
-    tenant_metadata: { dept: "sales" },
+    tenant_metadata: { department: "sales" },
+    document_metadata: { author: "Alice" },
   },
 });
 ```
 
-### Fetch Source Content
+### Include only selected fields
+
+```ts
+const sources = await client.context.list({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
+  includeFields: ["title", "document_metadata", "tenant_metadata"],
+});
+```
+
+Allowed field names:
+
+```text
+attachments, content, description, document_metadata, note, relations,
+tenant_metadata, timestamp, title, type, url
+```
 
-Retrieve the full content of a specific source by its ID:
+### Inspect a single source
 
 ```ts
-const source = await client.fetch.content({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  source_id: "your-source-id",
-  mode: "content",   // "content" | "url" | "both"
+const source = await client.context.inspect({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  id: "source-id-1",
+  mode: "content",
 });
+
+console.log(source);
 ```
 
-### Fetch Graph Relations
+Supported `mode` values: `content` | `url` | `both`. For presigned URLs, set `expirySeconds`:
+
+```ts
+const source = await client.context.inspect({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  id: "source-id-1",
+  mode: "url",
+  expirySeconds: 3600,
+});
+```
 
-Retrieve the graph relations (linked sources) for a given source:
+### Fetch graph relations
 
 ```ts
-const relations = await client.fetch.graphRelationsBySourceId({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  source_id: "your-source-id",
-  is_memory: false,
+const relations = await client.context.relations({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  id: "source-id-1",
+  type: "knowledge",
   limit: 10,
 });
+
+console.log(relations);
 ```
 
----
+Omit `id` to fetch relations across the whole sub-tenant. Use `cursor` for pagination.
 
-## Delete Data
+### Delete sources
 
-Delete one or more sources (knowledge or memories) by their IDs:
+Use `type` to target knowledge or memory.
 
 ```ts
-await client.data.delete({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
+await client.context.delete({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
   ids: ["source-id-1", "source-id-2"],
+  type: "knowledge",
 });
 ```
 
----
-
-## API Key Management
+## Webhooks
 
-> **Note:** This endpoint requires a dashboard session token (obtained via your Hydra DB dashboard login), not a standard API key. Use it from a server-side admin context where you have a valid user session.
+Hydra DB can notify your application about events such as indexing status changes.
 
-Create scoped API keys for controlled access:
+### Register a webhook
 
 ```ts
-const newKey = await client.key.createApiKey({
-  owner: "service-account@myapp.com",
-  scopes: ["query"],
-  env: "live",
-  prefix: "sk",
+const hook = await client.webhooks.register({
+  url: "https://example.com/hydra-webhook",
+  eventTypes: ["indexing.status_changed"],
+  signingSecret: "a-secret-at-least-16-chars",
 });
-// newKey.full_api_key -> the actual key (only shown once)
-```
 
----
+console.log(hook);
+```
 
-## Raw Embeddings
+When `signingSecret` is set, every delivery includes an `X-HydraDB-Signature: sha256=<hmac>` header computed as `HMAC-SHA256(key=signingSecret, msg=raw_body)`. The secret must be at least 16 characters; omit it to disable signing.
 
-Use Hydra DB as a vector store with your own embeddings — useful when you want to manage embedding generation yourself.
+### Get the current webhook
 
-> **Note:** Raw embeddings require a tenant created with `is_embeddings_tenant: true` and a fixed `embeddings_dimension`. A standard knowledge tenant does not support raw embedding operations.
->
-> ```ts
-> await client.tenant.create({
->   tenant_id: "my-embeddings-tenant",
->   is_embeddings_tenant: true,
->   embeddings_dimension: 1536,
-> });
-> ```
+```ts
+console.log(await client.webhooks.get());
+```
 
-### Insert Embeddings
+### Delete the webhook
 
 ```ts
-await client.embeddings.insert({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  upsert: true,
-  embeddings: [
-    {
-      source_id: "my-doc-001",
-      metadata: { category: "finance", year: 2024 },
-      embeddings: [
-        { chunk_id: "my-doc-001-chunk-0", embedding: [0.1, 0.2, 0.3 /* ... 1536 dims */] },
-        { chunk_id: "my-doc-001-chunk-1", embedding: [0.4, 0.5, 0.6 /* ... 1536 dims */] },
-      ],
-    },
-  ],
-});
+await client.webhooks.delete();
 ```
 
-### Search by Vector
+### Send a test event
 
-Find the most similar chunks to a query embedding:
+```ts
+await client.webhooks.test();
+```
+
+### List and inspect deliveries
 
 ```ts
-const searchResults = await client.embeddings.search({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  query_embedding: [0.1, 0.2, 0.3 /* ... 1536 dims */],
-  limit: 10,
+const deliveries = await client.webhooks.listDeliveries({
+  limit: 20,
+  status: "failed", // pending | failed | delivered | permanently_failed
 });
-// searchResults -> RawEmbeddingSearchResult[]
+console.log(deliveries);
+
+const one = await client.webhooks.getDelivery({ deliveryId: "delivery_id" });
+console.log(one);
 ```
 
-### Filter Embeddings
+Use `cursor` to paginate deliveries.
 
-Retrieve stored embeddings for a specific source or set of chunk IDs:
+### Retry a delivery
 
 ```ts
-// By source
-const bySource = await client.embeddings.filter({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  source_id: "my-doc-001",
-  limit: 50,
-});
-
-// By chunk IDs
-const byChunks = await client.embeddings.filter({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  chunk_ids: ["my-doc-001-chunk-0", "my-doc-001-chunk-1"],
-});
+await client.webhooks.retryDelivery({ deliveryId: "delivery_id" });
 ```
 
-### Delete Embeddings
+## Accessing raw responses
+
+Most methods return an `HttpResponsePromise`, which you can `await` for the parsed body or call `.withRawResponse()` on to also get headers and status.
 
 ```ts
-// Delete all embeddings for a source
-await client.embeddings.delete({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  source_id: "my-doc-001",
-});
+const { data, rawResponse } = await client
+  .query({ tenantId: TENANT_ID, query: "revenue" })
+  .withRawResponse();
 
-// Delete specific chunks
-await client.embeddings.delete({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  chunk_ids: ["my-doc-001-chunk-0"],
-});
+console.log(rawResponse.status, data.data?.chunks);
 ```
 
----
+## Passthrough fetch
 
-## Platform Metrics
-
-Retrieve platform-level health and usage metrics:
+Use `client.fetch()` for endpoints not yet wrapped by the SDK. It uses the SDK's configured auth, base URL, timeout, and retry settings. Relative paths resolve against the configured base URL.
 
 ```ts
-const metrics = await client.metricsMetricsGet();
+const response = await client.fetch("/metrics", { method: "GET" });
+const data = await response.json();
 ```
 
----
-
-## SDK Method Reference
+## Error handling
 
-| Method | Description |
+```ts
+import {
+  HydraDBError,
+  HydraDBTimeoutError,
+  HydraDB,
+} from "@hydradb/sdk";
+
+try {
+  await client.context.ingest({
+    tenantId: TENANT_ID,
+    subTenantId: SUB_TENANT_ID,
+    type: "knowledge",
+    documents: [{ path: "./missing.pdf" }],
+  });
+} catch (error) {
+  if (error instanceof HydraDBTimeoutError) {
+    console.error("Request timed out", error);
+  } else if (error instanceof HydraDB.UnauthorizedError) {
+    console.error("Invalid or missing API key");
+  } else if (error instanceof HydraDBError) {
+    console.error("Hydra DB API error", error.statusCode, error.body);
+  } else {
+    console.error("Unexpected error", error);
+  }
+}
+```
+
+Typed status errors are available under the `HydraDB` namespace:
+
+```text
+HydraDB.BadRequestError
+HydraDB.UnauthorizedError
+HydraDB.ForbiddenError
+HydraDB.NotFoundError
+HydraDB.UnprocessableEntityError
+HydraDB.TooManyRequestsError
+HydraDB.InternalServerError
+HydraDB.ServiceUnavailableError
+```
+
+`HydraDBError` (base) and `HydraDBTimeoutError` are exported from the package root.
+
+## SDK method reference
+
+| SDK method | Description |
 |---|---|
-| `client.tenant.create` | Create a new tenant (standard or embeddings) |
-| `client.tenant.getSubTenantIds` | List all sub-tenant IDs within a tenant |
-| `client.tenant.getInfraStatus` | Check tenant infrastructure readiness |
-| `client.tenant.monitor` | Get tenant usage and stats |
-| `client.tenant.deleteTenant` | Permanently delete a tenant and all its data |
-| `client.upload.knowledge` | Upload files to the knowledge base |
-| `client.upload.verifyProcessing` | Poll indexing status of uploaded files |
-| `client.upload.addMemory` | Index text, markdown, or conversation pairs as memories |
-| `client.upload.deleteMemory` | Delete a specific memory by ID |
-| `client.recall.fullRecall` | Hybrid semantic + keyword search |
-| `client.recall.recallPreferences` | Search user memory / preference data only |
-| `client.recall.booleanRecall` | Exact keyword / phrase / boolean search |
-| `client.recall.qna` | LLM-powered question answering over indexed content |
-| `client.fetch.listData` | List all knowledge sources or memories |
-| `client.fetch.content` | Fetch full content of a source by ID |
-| `client.fetch.graphRelationsBySourceId` | Fetch graph relations for a source |
-| `client.data.delete` | Delete sources or memories by ID |
-| `client.key.createApiKey` | Create a scoped API key *(requires dashboard session token)* |
-| `client.embeddings.insert` | Store raw vector embeddings *(requires embeddings tenant)* |
-| `client.embeddings.search` | Vector similarity search |
-| `client.embeddings.filter` | Retrieve embeddings by source or chunk IDs |
-| `client.embeddings.delete` | Delete embeddings by source or chunk IDs |
-| `client.metricsMetricsGet` | Retrieve platform metrics |
-
-> **Method Mapping:** `client.<group>.<method>` mirrors `api.hydradb.com/<group>/<method>`
->
-> For example: `client.upload.knowledge()` → `POST /ingestion/upload_knowledge`
-
----
-
-## Type Safety & IDE Support
-
-The SDK provides exact type parity with the API:
-
-- **Request parameters** — every field (required, optional, type, validation) is reflected in the method signature
-- **Response objects** — return types match the exact JSON schema from each endpoint
-- **Nested objects** — complex parameters and responses preserve their full structure
-
-Your IDE will automatically provide autocompletion, type-checking, inline documentation, and compile-time validation for every method. Just hit **Cmd+Space / Ctrl+Space**.
-
----
+| `client.query()` | Retrieve knowledge and/or memory in a single call. |
+| `client.context.ingest()` | Ingest knowledge files, app-generated knowledge, or memories. |
+| `client.context.status()` | Check ingestion/indexing status for source IDs. |
+| `client.context.inspect()` | Fetch a single source's content or URL. |
+| `client.context.list()` | List knowledge sources or memories. |
+| `client.context.delete()` | Delete one or more source IDs. |
+| `client.context.relations()` | Fetch graph relations for a source or sub-tenant. |
+| `client.tenants.create()` | Create a standard or embeddings tenant. |
+| `client.tenants.list()` | List tenants. |
+| `client.tenants.delete()` | Delete a tenant. |
+| `client.tenants.status()` | Check tenant infrastructure status. |
+| `client.tenants.subTenants()` | List sub-tenants for a tenant. |
+| `client.tenants.stats()` | Get tenant stats. |
+| `client.webhooks.register()` | Register a webhook. |
+| `client.webhooks.get()` | Get the current webhook. |
+| `client.webhooks.delete()` | Delete the webhook. |
+| `client.webhooks.test()` | Send a test event. |
+| `client.webhooks.listDeliveries()` | List webhook deliveries. |
+| `client.webhooks.getDelivery()` | Get a single delivery. |
+| `client.webhooks.retryDelivery()` | Retry a delivery. |
+| `client.fetch()` | Authenticated passthrough request. |
+| `buildString()` | Format a query result into an LLM-ready string. |
+
+## Notes for contributors
+
+This SDK is generated from the Hydra DB API definition with Fern. The generated clients live in `Client.ts` and under `api/resources/{context,tenants,webhooks}/client/Client.ts`. If method signatures change in the generated code, update this README to match.
+
+Before publishing, verify these stay consistent:
+
+- Package name and version in `package.json` (`@hydradb/sdk`)
+- Installation command in this README
+- Request fields use camelCase
+- The ingest payload shapes (`documentMetadata`, `appKnowledge`, and `memories` are JSON strings)
 
 ## Links
 
@@ -574,5 +747,4 @@ Your IDE will automatically provide autocompletion, type-checking, inline docume
 
 ## Support
 
-If you have any questions or need help, reach out at [founders@hydradb.com](mailto:founders@usecortex.ai).
-
+If you have any questions or need help, reach out at [founders@hydradb.com](mailto:founders@hydradb.com).