@hydradb/sdk 0.0.1 → 0.0.3

package/README.md

@@ -1,100 +1,147 @@
 # 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, graph context, and raw-vector workflows 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
+- 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
 
-## 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 local development, pass `baseUrl`:
+
+```ts
+const localClient = new HydraDBClient({
+  token: process.env.HYDRA_DB_API_KEY,
+  baseUrl: "http://localhost:8080",
+});
+```
+
+## Important tenant and sub-tenant rule
 
-## Tenant Management
+Use the same `tenant_id` and `sub_tenant_id` across upload, verify, recall, fetch, and delete calls.
 
-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)
+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.
 
-### Create a Tenant
+## Tenant management
+
+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({
+await client.tenant.create({
   tenant_id: TENANT_ID,
 });
 ```
 
-You can also create a tenant optimised for raw vector embeddings:
+### Create an embeddings tenant
+
+Raw embedding APIs require a tenant created with `is_embeddings_tenant: true` and a fixed embedding dimension.
 
 ```ts
-const embeddingsTenant = await client.tenant.create({
+await client.tenant.create({
   tenant_id: "my-embeddings-tenant",
   is_embeddings_tenant: true,
   embeddings_dimension: 1536,
 });
 ```
 
-### Get Sub-Tenant IDs
+### Create a tenant with metadata schema
+
+```ts
+await client.tenant.create({
+  tenant_id: TENANT_ID,
+  tenant_metadata_schema: [
+    {
+      name: "department",
+      data_type: "VARCHAR",
+      enable_match: true,
+      enable_dense_embedding: false,
+      enable_sparse_embedding: false,
+    },
+  ],
+});
+```
+
+### List sub-tenant IDs
 
 ```ts
 const subTenants = await client.tenant.getSubTenantIds({
   tenant_id: TENANT_ID,
 });
-// subTenants.sub_tenant_ids -> string[]
+
+console.log(subTenants.sub_tenant_ids);
 ```
 
-### Get Infrastructure Status
+### List tenant IDs
 
-Check whether the tenant's underlying infrastructure is ready:
+```ts
+const tenants = await client.tenant.getTenantIds();
+console.log(tenants.tenant_ids);
+```
+
+### Check tenant infrastructure status
 
 ```ts
 const infraStatus = await client.tenant.getInfraStatus({
   tenant_id: TENANT_ID,
 });
+
+console.log(infraStatus);
 ```
 
-### Monitor Tenant Stats
+### Monitor tenant stats
 
 ```ts
 const stats = await client.tenant.monitor({
   tenant_id: 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({
@@ -102,42 +149,101 @@ await client.tenant.deleteTenant({
 });
 ```
 
----
+## Upload knowledge
 
-## Index Your Data
+Use `client.upload.knowledge()` to upload files to the knowledge base.
 
-### Upload Knowledge (Files)
+The SDK sends a multipart request to:
 
-Upload documents to make them retrievable via natural language search. Supports PDFs, text files, and other document formats.
+```text
+POST /ingestion/upload_knowledge
+```
+
+### Upload one file
 
 ```ts
-import fs from "node:fs";
+const uploadResult = await client.upload.knowledge({
+  tenant_id: TENANT_ID,
+  sub_tenant_id: SUB_TENANT_ID,
+  files: [
+    {
+      path: "./report.pdf",
+      filename: "report.pdf",
+      contentType: "application/pdf",
+    },
+  ],
+  upsert: true,
+});
+
+const sourceId = uploadResult.results?.[0]?.source_id;
+console.log("source_id:", sourceId);
+console.log("initial_status:", uploadResult.results?.[0]?.status);
+```
 
+### Upload multiple files
+
+```ts
 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"),
+    {
+      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
+
+console.log(uploadResult.results);
+```
+
+You can also pass buffers, blobs, streams, or a file object with metadata:
+
+```ts
+import { readFileSync } from "node:fs";
+
+await client.upload.knowledge({
+  tenant_id: TENANT_ID,
+  sub_tenant_id: SUB_TENANT_ID,
+  files: [
+    {
+      data: readFileSync("./report.pdf"),
+      filename: "report.pdf",
+      contentType: "application/pdf",
+    },
+  ],
+});
 ```
 
-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:
+### Upload with metadata
+
+`file_metadata` must be a JSON string. The array length should match the `files` array length.
+
+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
 
 ```ts
 const fileMetadata = [
   {
-    id: "doc_a",
-    tenant_metadata: { dept: "sales" },
-    document_metadata: { author: "Alice" },
+    file_id: "doc_a",
+    metadata: { department: "sales" },
+    additional_metadata: { author: "Alice" },
   },
   {
-    id: "doc_b",
-    tenant_metadata: { dept: "marketing" },
-    document_metadata: { author: "Bob" },
+    file_id: "doc_b",
+    metadata: { department: "marketing" },
+    additional_metadata: { author: "Bob" },
     relations: {
       cortex_source_ids: ["doc_a"],
       properties: { relation: "same_upload_batch" },
@@ -145,21 +251,61 @@ const fileMetadata = [
   },
 ];
 
-const uploadWithMeta = await client.upload.knowledge({
+const uploadResult = await client.upload.knowledge({
   tenant_id: TENANT_ID,
   sub_tenant_id: SUB_TENANT_ID,
   files: [
-    fs.readFileSync("a.pdf"),
-    fs.readFileSync("b.pdf"),
+    {
+      path: "./a.pdf",
+      filename: "a.pdf",
+      contentType: "application/pdf",
+    },
+    {
+      path: "./b.pdf",
+      filename: "b.pdf",
+      contentType: "application/pdf",
+    },
   ],
   file_metadata: JSON.stringify(fileMetadata),
   upsert: true,
 });
+
+console.log(uploadResult.results);
 ```
 
-### Verify Processing Status
+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`.
 
-After uploading, check when files have finished indexing:
+### Upload app-generated knowledge
+
+You can index app-generated source objects without uploading files by passing `app_knowledge` as a JSON string.
+
+```ts
+const appKnowledge = [
+  {
+    id: "app_source_1",
+    title: "CRM Account Note",
+    content: "Acme is interested in the enterprise plan.",
+    type: "crm_note",
+    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),
+  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.
+
+Use `client.upload.verifyProcessing()` with the returned `source_id` values.
 
 ```ts
 const status = await client.upload.verifyProcessing({
@@ -167,14 +313,80 @@ const status = await client.upload.verifyProcessing({
   sub_tenant_id: SUB_TENANT_ID,
   file_ids: ["source-id-1", "source-id-2"],
 });
-// status.statuses[0].indexing_status -> "queued" | "processing" | "completed" | "errored"
+
+console.log(status.statuses);
+```
+
+Current processing status values:
+
+```text
+queued
+processing
+graph_creation
+completed
+success
+errored
+```
+
+Meaning:
+
+| 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 |
+
+### Poll until ingestion finishes
+
+```ts
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function waitForIngestion(fileIds: string[]) {
+  while (true) {
+    const status = await client.upload.verifyProcessing({
+      tenant_id: TENANT_ID,
+      sub_tenant_id: SUB_TENANT_ID,
+      file_ids: fileIds,
+    });
+
+    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;
+    }
+
+    await sleep(5000);
+  }
+}
+
+const fileIds = uploadResult.results?.map((item) => item.source_id).filter(Boolean) ?? [];
+await waitForIngestion(fileIds);
 ```
 
-### Add Memories
+## Add memories
 
-Index free-form text, markdown content, or conversation pairs as searchable memories.
+Use `client.upload.addMemory()` to add text, markdown, or conversation memories.
 
-**Plain text:**
+The SDK sends JSON to:
+
+```text
+POST /memories/add_memory
+```
+
+### Add plain text memory
 
 ```ts
 await client.upload.addMemory({
@@ -183,15 +395,19 @@ await client.upload.addMemory({
   upsert: true,
   memories: [
     {
-      text: "User prefers detailed explanations and dark mode",
+      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" },
     },
   ],
 });
 ```
 
-**Markdown:**
+### Add markdown memory
 
 ```ts
 await client.upload.addMemory({
@@ -200,16 +416,17 @@ await client.upload.addMemory({
   upsert: true,
   memories: [
     {
-      text: "# Meeting Notes\n\n## Key Points\n- Budget approved\n- Launch date: Q2",
+      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,
-      title: "Meeting Notes",
     },
   ],
 });
 ```
 
-**User–assistant conversation pairs:**
+### Add user/assistant conversation memory
 
 ```ts
 await client.upload.addMemory({
@@ -218,119 +435,107 @@ await client.upload.addMemory({
   upsert: true,
   memories: [
     {
+      source_id: "conversation_001",
       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." },
+        {
+          user: "How do I like reports?",
+          assistant: "You prefer weekly summary reports with charts.",
+        },
       ],
       infer: true,
       user_name: "John",
-      custom_instructions: "Extract user preferences",
+      custom_instructions: "Extract durable user preferences.",
     },
   ],
 });
 ```
 
-### Delete a Memory
+### Delete a memory
 
 ```ts
 await client.upload.deleteMemory({
   tenant_id: TENANT_ID,
   sub_tenant_id: SUB_TENANT_ID,
-  memory_id: "memory-source-id",
+  memory_id: "memory_001",
 });
 ```
 
----
-
-## Search & Retrieval
+## Search and retrieval
 
-### Full Recall
+### Full recall
 
-Hybrid semantic + keyword search across both knowledge and memories:
+Hybrid semantic and keyword retrieval across indexed content.
 
 ```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
+  query: "What did the account notes say about Acme?",
   max_results: 10,
+  mode: "fast",
+  alpha: 0.8,
+  recency_bias: 0,
+  graph_context: true,
 });
-// results.chunks -> VectorStoreChunk[]
-// results.sources -> SourceInfo[]
+
+console.log(results.chunks);
+console.log(results.sources);
 ```
 
-### Recall Preferences
+`alpha` can be a number from `0.0` to `1.0`, or the string `"auto"`.
+
+### Recall preferences
 
-Search only user memory/preference data:
+Search user memory and preference data.
 
 ```ts
 const preferences = await client.recall.recallPreferences({
   tenant_id: TENANT_ID,
   sub_tenant_id: SUB_TENANT_ID,
-  query: "dark mode preference",
+  query: "report format preference",
   max_results: 5,
 });
+
+console.log(preferences.chunks);
 ```
 
-### Boolean Recall
+### Boolean recall
 
-Exact keyword / phrase / boolean search (BM25):
+Keyword, phrase, and BM25-style search.
 
 ```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"
+  query: "enterprise plan",
+  operator: "phrase",
+  search_mode: "sources",
   max_results: 10,
-  search_mode: "memories",  // "sources" | "memories"
 });
-```
-
-### Q&A (LLM-powered answer)
-
-Ask a question and get a grounded answer generated by an LLM over your indexed content:
 
-```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,
-});
+console.log(boolResults.chunks);
 ```
 
-You can optionally choose the LLM provider and model:
+Supported `operator` values:
 
-```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,
-});
+```text
+or
+and
+phrase
 ```
 
----
+Supported `search_mode` values:
 
-## Fetch & Inspect Data
+```text
+sources
+memories
+```
 
-### List All Data
+## Fetch and inspect data
 
-List sources (knowledge) or memories with optional filtering and pagination:
+### List knowledge sources
 
 ```ts
-// List knowledge sources
 const sources = await client.fetch.listData({
   tenant_id: TENANT_ID,
   sub_tenant_id: SUB_TENANT_ID,
@@ -339,15 +544,25 @@ const sources = await client.fetch.listData({
   page_size: 50,
 });
 
-// List user memories
+console.log(sources.data);
+console.log(sources.pagination);
+```
+
+### List memories
+
+```ts
 const memories = await client.fetch.listData({
   tenant_id: TENANT_ID,
   sub_tenant_id: SUB_TENANT_ID,
   kind: "memories",
+  page: 1,
+  page_size: 50,
 });
+
+console.log(memories.data);
 ```
 
-Filter by metadata:
+### Filter listed data
 
 ```ts
 const filtered = await client.fetch.listData({
@@ -355,43 +570,70 @@ const filtered = await client.fetch.listData({
   sub_tenant_id: SUB_TENANT_ID,
   kind: "knowledge",
   filters: {
-    tenant_metadata: { dept: "sales" },
+    tenant_metadata: { department: "sales" },
+    document_metadata: { author: "Alice" },
+    source_fields: { type: "crm_note" },
   },
 });
+
+console.log(filtered.data);
 ```
 
-### Fetch Source Content
+### Reduce list payload size
+
+For `kind: "knowledge"`, you can use `include_fields` to return only selected source 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"],
+});
+
+console.log(slimSources.data);
+```
 
-Retrieve the full content of a specific source by its ID:
+### Fetch source content
 
 ```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"
+  source_id: "source-id-1",
+  mode: "content",
 });
+
+console.log(source);
 ```
 
-### Fetch Graph Relations
+Supported `mode` values:
+
+```text
+content
+url
+both
+```
 
-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",
+  source_id: "source-id-1",
   is_memory: false,
   limit: 10,
 });
+
+console.log(relations);
 ```
 
----
+If you omit `source_id`, the endpoint can return relations across the sub-tenant.
 
-## Delete Data
+## Delete data
 
-Delete one or more sources (knowledge or memories) by their IDs:
+Use `client.data.delete()` to delete one or more source IDs.
 
 ```ts
 await client.data.delete({
@@ -401,168 +643,189 @@ await client.data.delete({
 });
 ```
 
----
+## Graph health
 
-## API Key Management
-
-> **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.
-
-Create scoped API keys for controlled access:
+Fetch high-degree graph nodes for a tenant or sub-tenant.
 
 ```ts
-const newKey = await client.key.createApiKey({
-  owner: "service-account@myapp.com",
-  scopes: ["query"],
-  env: "live",
-  prefix: "sk",
+const superNodes = await client.graphHealth.getSuperNodes({
+  tenant_id: TENANT_ID,
+  sub_tenant_id: SUB_TENANT_ID,
+  degree_threshold: 50,
+  limit: 20,
 });
-// newKey.full_api_key -> the actual key (only shown once)
-```
-
----
 
-## Raw Embeddings
+console.log(superNodes);
+```
 
-Use Hydra DB as a vector store with your own embeddings — useful when you want to manage embedding generation yourself.
+## Raw embeddings
 
-> **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,
-> });
-> ```
+Raw embedding APIs are for bring-your-own-vector workflows. They require an embeddings tenant.
 
-### Insert Embeddings
+### Insert raw embeddings
 
 ```ts
 await client.embeddings.insert({
-  tenant_id: TENANT_ID,
+  tenant_id: "my-embeddings-tenant",
   sub_tenant_id: SUB_TENANT_ID,
   upsert: true,
   embeddings: [
     {
-      source_id: "my-doc-001",
-      metadata: { category: "finance", year: 2024 },
+      source_id: "doc_001",
+      metadata: { category: "finance", year: 2026 },
       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 */] },
+        {
+          chunk_id: "doc_001_chunk_0",
+          embedding: [0.1, 0.2, 0.3],
+        },
       ],
     },
   ],
 });
 ```
 
-### Search by Vector
+The vector length must match the `embeddings_dimension` used when creating the embeddings tenant.
 
-Find the most similar chunks to a query embedding:
+### Search raw embeddings
 
 ```ts
-const searchResults = await client.embeddings.search({
-  tenant_id: TENANT_ID,
+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 /* ... 1536 dims */],
+  query_embedding: [0.1, 0.2, 0.3],
   limit: 10,
 });
-// searchResults -> RawEmbeddingSearchResult[]
-```
 
-### Filter Embeddings
+console.log(rawResults);
+```
 
-Retrieve stored embeddings for a specific source or set of chunk IDs:
+### Filter raw embeddings
 
 ```ts
-// By source
 const bySource = await client.embeddings.filter({
-  tenant_id: TENANT_ID,
+  tenant_id: "my-embeddings-tenant",
   sub_tenant_id: SUB_TENANT_ID,
-  source_id: "my-doc-001",
+  source_id: "doc_001",
   limit: 50,
 });
 
-// By chunk IDs
+console.log(bySource);
+```
+
+```ts
 const byChunks = await client.embeddings.filter({
-  tenant_id: TENANT_ID,
+  tenant_id: "my-embeddings-tenant",
   sub_tenant_id: SUB_TENANT_ID,
-  chunk_ids: ["my-doc-001-chunk-0", "my-doc-001-chunk-1"],
+  chunk_ids: ["doc_001_chunk_0"],
 });
+
+console.log(byChunks);
 ```
 
-### Delete Embeddings
+### Delete raw embeddings
 
 ```ts
-// Delete all embeddings for a source
 await client.embeddings.delete({
-  tenant_id: TENANT_ID,
+  tenant_id: "my-embeddings-tenant",
   sub_tenant_id: SUB_TENANT_ID,
-  source_id: "my-doc-001",
+  source_id: "doc_001",
 });
+```
 
-// Delete specific chunks
+```ts
 await client.embeddings.delete({
-  tenant_id: TENANT_ID,
+  tenant_id: "my-embeddings-tenant",
   sub_tenant_id: SUB_TENANT_ID,
-  chunk_ids: ["my-doc-001-chunk-0"],
+  chunk_ids: ["doc_001_chunk_0"],
 });
 ```
 
----
-
-## Platform Metrics
+## API key management
 
-Retrieve platform-level health and usage metrics:
+> This endpoint is meant for an authenticated dashboard/admin context. Do not expose admin credentials in client-side applications.
 
 ```ts
-const metrics = await client.metricsMetricsGet();
+const apiKey = await client.key.createApiKey({
+  owner: "service-account@example.com",
+  scopes: ["ingest", "query"],
+  env: "live",
+  prefix: "sk",
+});
+
+console.log(apiKey.full_api_key);
 ```
 
----
+## Platform metrics
 
-## SDK Method Reference
+```ts
+const metrics = await client.metricsMetricsGet();
+console.log(metrics);
+```
 
-| 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`
+## 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.
 
-## Type Safety & IDE Support
+```ts
+const response = await client.passthroughFetch("/metrics", {
+  method: "GET",
+});
 
-The SDK provides exact type parity with the API:
+const data = await response.json();
+console.log(data);
+```
 
-- **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
+## Error handling
 
-Your IDE will automatically provide autocompletion, type-checking, inline documentation, and compile-time validation for every method. Just hit **Cmd+Space / Ctrl+Space**.
+```ts
+import { HydraDBError, HydraDBTimeoutError } from "@hydradb/sdk";
+
+try {
+  await client.upload.knowledge({
+    tenant_id: TENANT_ID,
+    sub_tenant_id: SUB_TENANT_ID,
+    files: [{ path: "./missing.pdf" }],
+  });
+} catch (error) {
+  if (error instanceof HydraDBTimeoutError) {
+    console.error("Request timed out", error);
+  } else if (error instanceof HydraDBError) {
+    console.error("Hydra DB API error", error.statusCode, error.body);
+  } else {
+    console.error("Unexpected error", error);
+  }
+}
+```
+
+## 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 |
 
 ---
 

package/dist/api/resources/fetch/client/requests/GraphRelationsBySourceIdFetchRequest.d.ts

@@ -1,19 +1,20 @@
 /**
  * @example
  *     {
- *         source_id: "<str>",
  *         tenant_id: "tenant_1234"
  *     }
  */
 export interface GraphRelationsBySourceIdFetchRequest {
-    /** The source ID to fetch relations for */
-    source_id: string;
+    /** Source ID. If omitted, returns relations across the entire sub-tenant. */
+    source_id?: string | null;
     /** Unique identifier for the tenant/organization */
     tenant_id?: string;
     /** Whether to fetch relations for memories */
     is_memory?: boolean;
     /** Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used. */
     sub_tenant_id?: string | null;
-    /** Maximum number of relations to return */
+    /** Maximum number of relation groups to return */
     limit?: number;
+    /** Pagination cursor. Pass next_cursor from a previous response. */
+    cursor?: number | null;
 }

package/dist/api/types/SourceGraphRelationsResponse.d.ts

@@ -2,6 +2,10 @@ import type * as HydraDB from "../index.js";
 export interface SourceGraphRelationsResponse {
     /** List of relations retrieved */
     relations: (HydraDB.TripletWithEvidence | null)[];
+    /** Whether the result was truncated due to the limit */
+    is_truncated?: boolean | undefined;
+    /** Opaque cursor for fetching the next page. Pass this value as the 'cursor' query parameter to continue pagination. None when there are no more results. */
+    next_cursor?: (number | null) | undefined;
     /** Indicates whether the request was successful */
     success?: boolean | undefined;
     /** Response message describing the operation result */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydradb/sdk",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "The official TypeScript SDK for the Hydra DB platform.",
   "author": "Nishkarsh Shrivastava <nishkarsh@hydradb.com>",
   "main": "./dist/index.js",