@hydradb/sdk 0.0.3 → 2.0.1

package/README.md

@@ -2,20 +2,20 @@
 
 The official TypeScript SDK for the Hydra DB platform.
 
-Hydra DB provides memory, knowledge ingestion, retrieval, graph context, and raw-vector workflows for AI applications.
+Hydra DB provides memory, knowledge ingestion, retrieval, and graph context for AI applications.
 
 [Hydra DB docs](https://docs.hydradb.com/)
 
 ## Features
 
-- Upload files into a tenant knowledge base
-- Add free-form memories, markdown, and user/assistant conversation memories
-- Verify ingestion status after upload
-- Search indexed knowledge and memories
-- Fetch uploaded source content and graph relations
-- Manage tenants and API keys
-- Store, search, filter, and delete raw embeddings
-- Use passthrough requests for endpoints not yet wrapped by the SDK
+- 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
 
 ## Installation
 
@@ -46,20 +46,35 @@ The default API base URL is:
 https://api.hydradb.com
 ```
 
-For local development, pass `baseUrl`:
+For an on-prem deployment, pass `baseUrl`:
 
 ```ts
 const localClient = new HydraDBClient({
   token: process.env.HYDRA_DB_API_KEY,
-  baseUrl: "http://localhost:8080",
+  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 `tenant_id` and `sub_tenant_id` across upload, verify, recall, fetch, and delete calls.
+Use the same `tenantId` and `subTenantId` across ingest, status, query, inspect, list, and delete calls.
 
-If you upload with a `sub_tenant_id` and then verify or search without it, you may check a different namespace. That can make statuses look inconsistent, for example `queued` in one namespace and `graph_creation` in another.
+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.
 
 ## Tenant management
 
@@ -68,72 +83,74 @@ A tenant is the top-level isolated database. A sub-tenant is an optional isolate
 ### Create a standard tenant
 
 ```ts
-await client.tenant.create({
-  tenant_id: TENANT_ID,
+await client.tenants.create({
+  tenantId: TENANT_ID,
 });
 ```
 
 ### Create an embeddings tenant
 
-Raw embedding APIs require a tenant created with `is_embeddings_tenant: true` and a fixed embedding dimension.
+Provide `embeddingsDimension` and set `isEmbeddingsTenant: true`.
 
 ```ts
-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,
 });
 ```
 
-### Create a tenant with metadata schema
+### 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
-await client.tenant.create({
-  tenant_id: TENANT_ID,
-  tenant_metadata_schema: [
+await client.tenants.create({
+  tenantId: TENANT_ID,
+  tenantMetadataSchema: [
     {
       name: "department",
-      data_type: "VARCHAR",
-      enable_match: true,
-      enable_dense_embedding: false,
-      enable_sparse_embedding: false,
+      dataType: "string",
+      enableMatch: true,
+      enableDenseEmbedding: false,
+      enableSparseEmbedding: false,
     },
   ],
 });
 ```
 
-### List sub-tenant IDs
+### List tenants
 
 ```ts
-const subTenants = await client.tenant.getSubTenantIds({
-  tenant_id: TENANT_ID,
-});
-
-console.log(subTenants.sub_tenant_ids);
+const tenants = await client.tenants.list();
+console.log(tenants);
 ```
 
-### List tenant IDs
+### List sub-tenants
 
 ```ts
-const tenants = await client.tenant.getTenantIds();
-console.log(tenants.tenant_ids);
+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);
@@ -144,28 +161,25 @@ console.log(stats);
 > 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,
 });
 ```
 
-## Upload knowledge
+## Ingest knowledge and memory
 
-Use `client.upload.knowledge()` to upload files to the knowledge base.
+`client.context.ingest()` handles both knowledge files and memory, selected via the `type` field (`"knowledge"` or `"memory"`).
 
-The SDK sends a multipart request to:
+### Ingest one file
 
-```text
-POST /ingestion/upload_knowledge
-```
-
-### Upload one file
+`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
-const uploadResult = await client.upload.knowledge({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  files: [
+const uploadResult = await client.context.ingest({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
+  documents: [
     {
       path: "./report.pdf",
       filename: "report.pdf",
@@ -175,44 +189,36 @@ const uploadResult = await client.upload.knowledge({
   upsert: true,
 });
 
-const sourceId = uploadResult.results?.[0]?.source_id;
-console.log("source_id:", sourceId);
-console.log("initial_status:", uploadResult.results?.[0]?.status);
+console.log(uploadResult);
 ```
 
-### Upload multiple files
+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
-const uploadResult = await client.upload.knowledge({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  files: [
-    {
-      path: "./a.pdf",
-      filename: "a.pdf",
-      contentType: "application/pdf",
-    },
-    {
-      path: "./notes.txt",
-      filename: "notes.txt",
-      contentType: "text/plain",
-    },
+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,
 });
-
-console.log(uploadResult.results);
 ```
 
-You can also pass buffers, blobs, streams, or a file object with metadata:
+Buffers, blobs, and streams also work:
 
 ```ts
 import { readFileSync } from "node:fs";
 
-await client.upload.knowledge({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  files: [
+await client.context.ingest({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
+  documents: [
     {
       data: readFileSync("./report.pdf"),
       filename: "report.pdf",
@@ -222,26 +228,19 @@ await client.upload.knowledge({
 });
 ```
 
-### Upload with metadata
-
-`file_metadata` must be a JSON string. The array length should match the `files` array length.
+### Ingest files with per-file metadata
 
-Supported metadata object fields:
-
-- `file_id`: optional custom source ID
-- `metadata`: tenant-level metadata
-- `additional_metadata`: document-level metadata
-- `relations`: forceful relations to other Cortex/Hydra source IDs
+`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 = [
   {
-    file_id: "doc_a",
+    id: "doc_a",
     metadata: { department: "sales" },
     additional_metadata: { author: "Alice" },
   },
   {
-    file_id: "doc_b",
+    id: "doc_b",
     metadata: { department: "marketing" },
     additional_metadata: { author: "Bob" },
     relations: {
@@ -251,544 +250,434 @@ const fileMetadata = [
   },
 ];
 
-const uploadResult = await client.upload.knowledge({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  files: [
-    {
-      path: "./a.pdf",
-      filename: "a.pdf",
-      contentType: "application/pdf",
-    },
-    {
-      path: "./b.pdf",
-      filename: "b.pdf",
-      contentType: "application/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,
 });
-
-console.log(uploadResult.results);
 ```
 
-Do not use old metadata keys such as `id`, `tenant_metadata`, or `document_metadata` inside `file_metadata` for file upload. The current upload endpoint expects `file_id`, `metadata`, and `additional_metadata`.
-
-### Upload app-generated knowledge
+### Ingest app-generated knowledge
 
-You can index app-generated source objects without uploading files by passing `app_knowledge` as a JSON string.
+`appKnowledge` is a JSON **string** — a single source object or an array of source objects (knowledge only).
 
 ```ts
 const appKnowledge = [
   {
     id: "app_source_1",
     title: "CRM Account Note",
-    content: "Acme is interested in the enterprise plan.",
-    type: "crm_note",
+    content: { text: "Acme is interested in the enterprise plan." },
+    type: "document",
     tenant_metadata: { department: "sales" },
     document_metadata: { source: "crm" },
   },
 ];
 
-await client.upload.knowledge({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  app_knowledge: JSON.stringify(appKnowledge),
+await client.context.ingest({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
+  appKnowledge: JSON.stringify(appKnowledge),
   upsert: true,
 });
 ```
 
-`app_sources` still exists in the generated SDK as a deprecated alias, but new code should use `app_knowledge`.
-
-## Verify ingestion status
-
-Upload can return `queued` immediately. That means the file was accepted by the ingestion pipeline, not that indexing is complete.
+### Add memories
 
-Use `client.upload.verifyProcessing()` with the returned `source_id` values.
+`memories` is a JSON **string** — a JSON array of memory items (memory only). Each item can include `text`, `title`, `infer`, and `metadata`.
 
 ```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 memories = [
+  {
+    source_id: "memory_001",
+    text: "User prefers detailed technical explanations.",
+    title: "User preference",
+    infer: true,
+    metadata: { category: "preference" },
+  },
+];
 
-console.log(status.statuses);
+await client.context.ingest({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "memory",
+  memories: JSON.stringify(memories),
+  upsert: true,
+});
 ```
 
-Current processing status values:
+## Check ingestion status
 
-```text
-queued
-processing
-graph_creation
-completed
-success
-errored
-```
+`client.context.status()` reports indexing status for one or more source IDs. Pass a single `id` or a list via `ids`.
 
-Meaning:
+```ts
+const status = await client.context.status({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  ids: ["source-id-1", "source-id-2"],
+});
 
-| Status | Meaning |
-|---|---|
-| `queued` | Upload accepted and waiting for processing |
-| `processing` | Parsing, chunking, embedding, or indexing is running |
-| `graph_creation` | Vector indexing is done, graph creation is still running |
-| `completed` | Ingestion finished |
-| `success` | Alias for completed |
-| `errored` | Ingestion failed |
+console.log(status);
+```
 
 ### Poll until ingestion finishes
 
 ```ts
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
-async function waitForIngestion(fileIds: string[]) {
+async function waitForIngestion(ids: string[]) {
   while (true) {
-    const status = await client.upload.verifyProcessing({
-      tenant_id: TENANT_ID,
-      sub_tenant_id: SUB_TENANT_ID,
-      file_ids: fileIds,
+    const status = await client.context.status({
+      tenantId: TENANT_ID,
+      subTenantId: SUB_TENANT_ID,
+      ids,
     });
 
-    const statuses = status.statuses;
-    console.log(statuses);
-
-    const failed = statuses.find((item) => item.indexing_status === "errored");
-    if (failed) {
-      throw new Error(failed.error_message ?? `Ingestion failed for ${failed.file_id}`);
-    }
-
-    const done = statuses.every((item) =>
-      item.indexing_status === "completed" || item.indexing_status === "success"
-    );
-
-    if (done) {
-      return statuses;
-    }
+    // Inspect the returned status fields (per the SourceStatusApiResponse
+    // schema) and break once everything has completed or errored.
+    console.log(status);
 
     await sleep(5000);
   }
 }
-
-const fileIds = uploadResult.results?.map((item) => item.source_id).filter(Boolean) ?? [];
-await waitForIngestion(fileIds);
 ```
 
-## Add memories
-
-Use `client.upload.addMemory()` to add text, markdown, or conversation memories.
-
-The SDK sends JSON to:
-
-```text
-POST /memories/add_memory
-```
+## Query (retrieval)
 
-### Add plain text memory
+`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.addMemory({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  upsert: true,
-  memories: [
-    {
-      source_id: "memory_001",
-      text: "User prefers detailed technical explanations.",
-      title: "User preference",
-      infer: true,
-      user_name: "John",
-      metadata: { category: "preference" },
-      additional_metadata: { source: "chat" },
-    },
-  ],
+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,
 });
-```
-
-### Add markdown memory
 
-```ts
-await client.upload.addMemory({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  upsert: true,
-  memories: [
-    {
-      source_id: "meeting_notes_001",
-      title: "Meeting Notes",
-      text: "# Meeting Notes\n\n- Budget approved\n- Launch planned for Q2",
-      is_markdown: true,
-      infer: false,
-    },
-  ],
-});
+console.log(response.data?.chunks);
+console.log(response.data?.sources);
 ```
 
-### Add user/assistant conversation memory
+### Search knowledge, memory, or both
+
+Use the `type` field:
 
 ```ts
-await client.upload.addMemory({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  upsert: true,
-  memories: [
-    {
-      source_id: "conversation_001",
-      user_assistant_pairs: [
-        {
-          user: "How do I like reports?",
-          assistant: "You prefer weekly summary reports with charts.",
-        },
-      ],
-      infer: true,
-      user_name: "John",
-      custom_instructions: "Extract durable user preferences.",
-    },
-  ],
-});
-```
+// Knowledge only
+await client.query({ tenantId: TENANT_ID, query: "quarterly revenue", type: "knowledge" });
 
-### Delete a memory
+// Memory only
+await client.query({ tenantId: TENANT_ID, query: "user preferences", type: "memory" });
 
-```ts
-await client.upload.deleteMemory({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  memory_id: "memory_001",
-});
+// Both, merged
+await client.query({ tenantId: TENANT_ID, query: "what does the user prefer", type: "all" });
 ```
 
-## Search and retrieval
+### Hybrid vs. keyword search
+
+`alpha` controls the hybrid balance and can be a number in `0.0`–`1.0` or the string `"auto"`:
 
-### Full recall
+- `1.0`: more semantic/vector weighted
+- `0.0`: more keyword/BM25 weighted
+- `"auto"`: backend chooses the balance
 
-Hybrid semantic and keyword retrieval across indexed content.
+For pure keyword/BM25 search, set `queryBy: "text"` and choose an `operator`:
 
 ```ts
-const results = await client.recall.fullRecall({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  query: "What did the account notes say about Acme?",
-  max_results: 10,
-  mode: "fast",
-  alpha: 0.8,
-  recency_bias: 0,
-  graph_context: true,
+const response = await client.query({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  query: "enterprise plan",
+  queryBy: "text",
+  operator: "phrase", // "or" | "and" | "phrase"
+  type: "knowledge",
 });
-
-console.log(results.chunks);
-console.log(results.sources);
 ```
 
-`alpha` can be a number from `0.0` to `1.0`, or the string `"auto"`.
+`queryBy` accepts `"hybrid"` (vector + BM25, default) or `"text"` (BM25 only). `operator` applies only when `queryBy: "text"`.
 
-### Recall preferences
+### Metadata filters
 
-Search user memory and preference data.
+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 preferences = await client.recall.recallPreferences({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  query: "report format preference",
-  max_results: 5,
+const response = await client.query({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  query: "revenue forecast",
+  maxResults: 10,
+  metadataFilters: {
+    department: "sales",
+    additional_metadata: { author: "Alice" },
+  },
 });
-
-console.log(preferences.chunks);
 ```
 
-### Boolean recall
+### All `query` options
 
-Keyword, phrase, and BM25-style search.
+| 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 boolResults = await client.recall.booleanRecall({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  query: "enterprise plan",
-  operator: "phrase",
-  search_mode: "sources",
-  max_results: 10,
-});
+## Formatting results for an LLM
 
-console.log(boolResults.chunks);
-```
+`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`.
 
-Supported `operator` values:
+```ts
+import { HydraDBClient, buildString } from "@hydradb/sdk";
 
-```text
-or
-and
-phrase
-```
+const client = new HydraDBClient({ token: process.env.HYDRA_DB_API_KEY });
 
-Supported `search_mode` values:
+const response = await client.query({
+  tenantId: TENANT_ID,
+  query: "What does the user prefer?",
+});
 
-```text
-sources
-memories
+// Pass the full envelope or just the data — buildString handles both.
+console.log(buildString(response));
+console.log(buildString(response.data!));
 ```
 
-## Fetch and 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 knowledge sources
+## Inspect, list, and delete sources
+
+### List sources
 
 ```ts
-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,
 });
 
-console.log(sources.data);
-console.log(sources.pagination);
+console.log(sources);
 ```
 
-### List memories
+List memories with `type: "memory"`.
+
+### Fetch specific source IDs
 
 ```ts
-const memories = await client.fetch.listData({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  kind: "memories",
-  page: 1,
-  page_size: 50,
+const sources = await client.context.list({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
+  ids: ["doc_a", "doc_b"],
 });
-
-console.log(memories.data);
 ```
 
 ### 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: { department: "sales" },
     document_metadata: { author: "Alice" },
-    source_fields: { type: "crm_note" },
   },
 });
-
-console.log(filtered.data);
 ```
 
-### Reduce list payload size
-
-For `kind: "knowledge"`, you can use `include_fields` to return only selected source fields.
+### Include only selected fields
 
 ```ts
-const slimSources = await client.fetch.listData({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  kind: "knowledge",
-  include_fields: ["title", "document_metadata", "timestamp"],
+const sources = await client.context.list({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  type: "knowledge",
+  includeFields: ["title", "document_metadata", "tenant_metadata"],
 });
+```
 
-console.log(slimSources.data);
+Allowed field names:
+
+```text
+attachments, content, description, document_metadata, note, relations,
+tenant_metadata, timestamp, title, type, url
 ```
 
-### Fetch source content
+### Inspect a single source
 
 ```ts
-const source = await client.fetch.content({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  source_id: "source-id-1",
+const source = await client.context.inspect({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  id: "source-id-1",
   mode: "content",
 });
 
 console.log(source);
 ```
 
-Supported `mode` values:
+Supported `mode` values: `content` | `url` | `both`. For presigned URLs, set `expirySeconds`:
 
-```text
-content
-url
-both
+```ts
+const source = await client.context.inspect({
+  tenantId: TENANT_ID,
+  subTenantId: SUB_TENANT_ID,
+  id: "source-id-1",
+  mode: "url",
+  expirySeconds: 3600,
+});
 ```
 
 ### Fetch graph relations
 
 ```ts
-const relations = await client.fetch.graphRelationsBySourceId({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  source_id: "source-id-1",
-  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);
 ```
 
-If you omit `source_id`, the endpoint can return relations across the sub-tenant.
+Omit `id` to fetch relations across the whole sub-tenant. Use `cursor` for pagination.
 
-## Delete data
+### Delete sources
 
-Use `client.data.delete()` to delete one or more source 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",
 });
 ```
 
-## Graph health
+## Webhooks
+
+Hydra DB can notify your application about events such as indexing status changes.
 
-Fetch high-degree graph nodes for a tenant or sub-tenant.
+### Register a webhook
 
 ```ts
-const superNodes = await client.graphHealth.getSuperNodes({
-  tenant_id: TENANT_ID,
-  sub_tenant_id: SUB_TENANT_ID,
-  degree_threshold: 50,
-  limit: 20,
+const hook = await client.webhooks.register({
+  url: "https://example.com/hydra-webhook",
+  eventTypes: ["indexing.status_changed"],
+  signingSecret: "a-secret-at-least-16-chars",
 });
 
-console.log(superNodes);
+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.
 
-Raw embedding APIs are for bring-your-own-vector workflows. They require an embeddings tenant.
-
-### Insert raw embeddings
+### Get the current webhook
 
 ```ts
-await client.embeddings.insert({
-  tenant_id: "my-embeddings-tenant",
-  sub_tenant_id: SUB_TENANT_ID,
-  upsert: true,
-  embeddings: [
-    {
-      source_id: "doc_001",
-      metadata: { category: "finance", year: 2026 },
-      embeddings: [
-        {
-          chunk_id: "doc_001_chunk_0",
-          embedding: [0.1, 0.2, 0.3],
-        },
-      ],
-    },
-  ],
-});
+console.log(await client.webhooks.get());
 ```
 
-The vector length must match the `embeddings_dimension` used when creating the embeddings tenant.
-
-### Search raw embeddings
+### Delete the webhook
 
 ```ts
-const rawResults = await client.embeddings.search({
-  tenant_id: "my-embeddings-tenant",
-  sub_tenant_id: SUB_TENANT_ID,
-  query_embedding: [0.1, 0.2, 0.3],
-  limit: 10,
-});
-
-console.log(rawResults);
+await client.webhooks.delete();
 ```
 
-### Filter raw embeddings
+### Send a test event
 
 ```ts
-const bySource = await client.embeddings.filter({
-  tenant_id: "my-embeddings-tenant",
-  sub_tenant_id: SUB_TENANT_ID,
-  source_id: "doc_001",
-  limit: 50,
-});
-
-console.log(bySource);
+await client.webhooks.test();
 ```
 
+### List and inspect deliveries
+
 ```ts
-const byChunks = await client.embeddings.filter({
-  tenant_id: "my-embeddings-tenant",
-  sub_tenant_id: SUB_TENANT_ID,
-  chunk_ids: ["doc_001_chunk_0"],
+const deliveries = await client.webhooks.listDeliveries({
+  limit: 20,
+  status: "failed", // pending | failed | delivered | permanently_failed
 });
+console.log(deliveries);
 
-console.log(byChunks);
+const one = await client.webhooks.getDelivery({ deliveryId: "delivery_id" });
+console.log(one);
 ```
 
-### Delete raw embeddings
+Use `cursor` to paginate deliveries.
 
-```ts
-await client.embeddings.delete({
-  tenant_id: "my-embeddings-tenant",
-  sub_tenant_id: SUB_TENANT_ID,
-  source_id: "doc_001",
-});
-```
+### Retry a delivery
 
 ```ts
-await client.embeddings.delete({
-  tenant_id: "my-embeddings-tenant",
-  sub_tenant_id: SUB_TENANT_ID,
-  chunk_ids: ["doc_001_chunk_0"],
-});
+await client.webhooks.retryDelivery({ deliveryId: "delivery_id" });
 ```
 
-## API key management
+## Accessing raw responses
 
-> This endpoint is meant for an authenticated dashboard/admin context. Do not expose admin credentials in client-side applications.
+Most methods return an `HttpResponsePromise`, which you can `await` for the parsed body or call `.withRawResponse()` on to also get headers and status.
 
 ```ts
-const apiKey = await client.key.createApiKey({
-  owner: "service-account@example.com",
-  scopes: ["ingest", "query"],
-  env: "live",
-  prefix: "sk",
-});
+const { data, rawResponse } = await client
+  .query({ tenantId: TENANT_ID, query: "revenue" })
+  .withRawResponse();
 
-console.log(apiKey.full_api_key);
-```
-
-## Platform metrics
-
-```ts
-const metrics = await client.metricsMetricsGet();
-console.log(metrics);
+console.log(rawResponse.status, data.data?.chunks);
 ```
 
 ## Passthrough fetch
 
-Use `client.passthroughFetch()` for API endpoints that are not yet wrapped by the generated SDK. It uses the SDK's configured auth headers, base URL, timeout, retry, and fetch settings.
+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 response = await client.passthroughFetch("/metrics", {
-  method: "GET",
-});
-
+const response = await client.fetch("/metrics", { method: "GET" });
 const data = await response.json();
-console.log(data);
 ```
 
 ## Error handling
 
 ```ts
-import { HydraDBError, HydraDBTimeoutError } from "@hydradb/sdk";
+import {
+  HydraDBError,
+  HydraDBTimeoutError,
+  HydraDB,
+} from "@hydradb/sdk";
 
 try {
-  await client.upload.knowledge({
-    tenant_id: TENANT_ID,
-    sub_tenant_id: SUB_TENANT_ID,
-    files: [{ path: "./missing.pdf" }],
+  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 {
@@ -797,37 +686,58 @@ try {
 }
 ```
 
+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 | API path | Description |
-|---|---|---|
-| `client.tenant.create()` | `POST /tenants/create` | Create a standard or embeddings tenant |
-| `client.tenant.getSubTenantIds()` | `GET /tenants/sub_tenant_ids` | List sub-tenant IDs |
-| `client.tenant.getTenantIds()` | `GET /tenants/tenant_ids` | List tenant IDs |
-| `client.tenant.getInfraStatus()` | `GET /tenants/infra/status` | Check tenant infrastructure |
-| `client.tenant.monitor()` | `GET /tenants/monitor` | Get tenant stats |
-| `client.tenant.deleteTenant()` | `DELETE /tenants/delete` | Delete a tenant |
-| `client.upload.knowledge()` | `POST /ingestion/upload_knowledge` | Upload files or app knowledge |
-| `client.upload.verifyProcessing()` | `POST /ingestion/verify_processing` | Check ingestion status |
-| `client.upload.addMemory()` | `POST /memories/add_memory` | Add memories |
-| `client.upload.deleteMemory()` | `DELETE /memories/delete_memory` | Delete one memory |
-| `client.recall.fullRecall()` | `POST /recall/search` | Hybrid semantic and keyword recall |
-| `client.recall.recallPreferences()` | `POST /recall/preferences` | Search preferences/memories |
-| `client.recall.booleanRecall()` | `POST /recall/boolean` | Boolean/BM25 recall |
-| `client.fetch.listData()` | `POST /fetch/list` | List knowledge or memories |
-| `client.fetch.content()` | `POST /fetch/source` | Fetch source content or URL |
-| `client.fetch.graphRelationsBySourceId()` | `GET /fetch/graph_relations` | Fetch graph relations |
-| `client.data.delete()` | `POST /data/delete` | Delete sources |
-| `client.graphHealth.getSuperNodes()` | `GET /graph_health/super_nodes` | Fetch graph super nodes |
-| `client.embeddings.insert()` | `POST /embeddings/insert_raw_embeddings` | Insert raw embeddings |
-| `client.embeddings.search()` | `POST /embeddings/search_raw_embeddings` | Search raw embeddings |
-| `client.embeddings.filter()` | `POST /embeddings/filter_raw_embeddings` | Filter raw embeddings |
-| `client.embeddings.delete()` | `DELETE /embeddings/delete` | Delete raw embeddings |
-| `client.key.createApiKey()` | `POST /api_keys/create` | Create API key |
-| `client.metricsMetricsGet()` | `GET /metrics` | Platform metrics |
-| `client.passthroughFetch()` | any path | Authenticated passthrough request |
-
----
+| SDK method | Description |
+|---|---|
+| `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
 
@@ -837,5 +747,4 @@ try {
 
 ## 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).