@hydradb/sdk 2.0.0 → 2.1.0

package/README.md

@@ -1,750 +1,690 @@
-# Hydra DB TypeScript SDK
-
-The official TypeScript SDK for the Hydra DB platform.
-
-Hydra DB provides memory, knowledge ingestion, retrieval, and graph context for AI applications.
-
-[Hydra DB docs](https://docs.hydradb.com/)
-
-## Features
-
-- 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
+# HydraDB TypeScript SDK
+
+The official TypeScript/JavaScript SDK for [HydraDB](https://hydradb.com) — a managed retrieval
+engine that combines vector search, full‑text search, and a knowledge graph behind a single API.
+
+- **Package:** `@hydradb/sdk`
+- **Client class:** `HydraDBClient`
+- **Version:** `2.1.0` (API version `2`)
+- **Docs:** https://docs.hydradb.com
+- **Runtime:** Node.js 18+ (works with any `fetch`-capable runtime)
+
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Client configuration](#client-configuration)
+- [Core concepts](#core-concepts)
+- [Responses & raw access](#responses--raw-access)
+- [Endpoints](#endpoints)
+  - [`query` — unified retrieval](#query--unified-retrieval)
+  - [Context (`client.context`)](#context-clientcontext)
+    - [`ingest`](#contextingest)
+    - [`list`](#contextlist)
+    - [`inspect`](#contextinspect)
+    - [`status`](#contextstatus)
+    - [`relations`](#contextrelations)
+    - [`updateSourceMetadata`](#contextupdatesourcemetadata)
+    - [`delete`](#contextdelete)
+  - [Databases (`client.databases`)](#databases-clientdatabases)
+    - [`create`](#databasescreate)
+    - [`list`](#databaseslist)
+    - [`collections`](#databasescollections)
+    - [`stats`](#databasesstats)
+    - [`status`](#databasesstatus)
+    - [`delete`](#databasesdelete)
+  - [Webhooks (`client.webhooks`)](#webhooks-clientwebhooks)
+    - [`register`](#webhooksregister)
+    - [`get`](#webhooksget)
+    - [`test`](#webhookstest)
+    - [`delete`](#webhooksdelete)
+    - [`listDeliveries`](#webhookslistdeliveries)
+    - [`getDelivery`](#webhooksgetdelivery)
+    - [`retryDelivery`](#webhooksretrydelivery)
+- [Error handling](#error-handling)
+- [Advanced](#advanced)
+  - [Per-request options (timeouts, retries, abort)](#per-request-options-timeouts-retries-abort)
+  - [Passthrough `fetch`](#passthrough-fetch)
+  - [Custom fetch & logging](#custom-fetch--logging)
+
+---
 
 ## Installation
 
 ```bash
 npm install @hydradb/sdk
-# or
-yarn add @hydradb/sdk
-# or
-pnpm add @hydradb/sdk
+# or: pnpm add @hydradb/sdk / yarn add @hydradb/sdk
 ```
 
-## Client setup
+## Quick start
 
-```ts
+```typescript
 import { HydraDBClient } from "@hydradb/sdk";
 
 const client = new HydraDBClient({
-  token: process.env.HYDRA_DB_API_KEY,
+  token: "YOUR_API_KEY", // bearer token
 });
 
-const TENANT_ID = process.env.HYDRA_TENANT_ID ?? "my-company";
-const SUB_TENANT_ID = process.env.HYDRA_SUB_TENANT_ID ?? "my-sub-tenant";
+// Run a hybrid search over a database ("tenant")
+const result = await client.query({
+  query: "What is our refund policy?",
+  database: "acme-corp",
+  type: "knowledge",
+  maxResults: 5,
+});
+
+console.log(result.data);
 ```
 
-The default API base URL is:
+Every method returns an awaitable `HttpResponsePromise`. `await`-ing it resolves to the parsed
+response body (a `HandlerEnvelope…` object whose payload is on `.data`). See
+[Responses & raw access](#responses--raw-access).
 
-```text
-https://api.hydradb.com
-```
+---
+
+## Client configuration
 
-For an on-prem deployment, pass `baseUrl`:
+```typescript
+import { HydraDBClient, HydraDBEnvironment } from "@hydradb/sdk";
 
-```ts
-const localClient = new HydraDBClient({
-  token: process.env.HYDRA_DB_API_KEY,
-  baseUrl: "https://<id>.hydradb.<domain>",
+const client = new HydraDBClient({
+  token: "YOUR_API_KEY",
+  apiVersion: "2",                          // optional, defaults to "2"
+  environment: HydraDBEnvironment.Default,  // https://api.hydradb.com
+  // baseUrl: "https://api.hydradb.com",    // override for self-hosted / staging
+  timeoutInSeconds: 60,                     // default 60
+  maxRetries: 2,                            // default 2
+  headers: { "X-Custom-Header": "value" },  // sent on every request
 });
 ```
 
-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.
+| Option             | Type                                  | Default                  | Notes |
+| ------------------ | ------------------------------------- | ------------------------ | ----- |
+| `token`            | `string \| () => string \| Promise`   | –                        | Bearer token. Accepts a supplier for dynamic/refreshing tokens. |
+| `apiVersion`       | `string`                              | `"2"`                    | Sets the `API-Version` header. |
+| `environment`      | `HydraDBEnvironment \| string`        | `Default`                | `Default` → `https://api.hydradb.com`. |
+| `baseUrl`          | `string`                              | –                        | Explicit URL; overrides `environment`. |
+| `timeoutInSeconds` | `number`                              | `60`                     | Per‑request timeout. |
+| `maxRetries`       | `number`                              | `2`                      | Automatic retries on transient failures. |
+| `headers`          | `Record<string, string>`              | –                        | Extra headers on every request. |
+| `fetch`            | `typeof fetch`                        | runtime default          | Custom fetch implementation. |
+| `logging`          | `LogConfig \| Logger`                 | silent                   | SDK logging. |
 
-> Note: request fields use **camelCase** (`tenantId`, `subTenantId`, `maxResults`, …). The SDK serializes them to the API's snake_case on the wire.
+> **Note:** all request fields use **camelCase** in TypeScript (e.g. `subTenantId`,
+> `maxResults`); the SDK maps them to the API's snake_case wire format for you.
 
-## Client structure
+---
 
-All functionality is reached through one top-level method and three sub-clients:
+## Core concepts
 
-| 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. |
+**Database vs. Collection (tenant vs. sub‑tenant).** HydraDB v2 renamed the isolation scopes:
 
-## Important tenant and sub-tenant rule
+| v2 name (canonical) | v1 alias (deprecated, still accepted) | Meaning |
+| ------------------- | ------------------------------------- | ------- |
+| `database`          | `tenantId`                            | Top‑level isolation boundary. |
+| `collection`        | `subTenantId`                         | A namespace within a database. |
 
-Use the same `tenantId` and `subTenantId` across ingest, status, query, inspect, list, and delete calls.
+The server’s `TenantAliases` middleware reconciles the two, so you can pass either — but new
+code should use `database` / `collection`. The legacy aliases will be removed in a future release.
 
-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.
+**Corpora (`type`).** Data is split into two corpora you can target independently:
+`"knowledge"` (documents), `"memory"` (agent memories), or `"all"`.
 
-## Tenant management
+---
 
-A tenant is the top-level isolated database. A sub-tenant is an optional isolated collection inside a tenant.
+## Responses & raw access
 
-### Create a standard tenant
+`await`-ing any call gives you the parsed body:
 
-```ts
-await client.tenants.create({
-  tenantId: TENANT_ID,
-});
+```typescript
+const res = await client.databases.list();
+console.log(res.data); // the payload
+console.log(res.meta); // request metadata
 ```
 
-### Create an embeddings tenant
+To also get the HTTP status and headers, call `.withRawResponse()`:
 
-Provide `embeddingsDimension` and set `isEmbeddingsTenant: true`.
+```typescript
+const { data, rawResponse } = await client.query({ query: "hi", database: "acme-corp" })
+  .withRawResponse();
 
-```ts
-await client.tenants.create({
-  tenantId: "my-embeddings-tenant",
-  isEmbeddingsTenant: true,
-  embeddingsDimension: 1536,
-});
+console.log(rawResponse.status);
+console.log(rawResponse.headers.get("x-request-id"));
+console.log(data);
 ```
 
-### 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.
+## Endpoints
 
-```ts
-await client.tenants.create({
-  tenantId: TENANT_ID,
-  tenantMetadataSchema: [
-    {
-      name: "department",
-      dataType: "string",
-      enableMatch: true,
-      enableDenseEmbedding: false,
-      enableSparseEmbedding: false,
-    },
-  ],
-});
-```
-
-### List tenants
+### `query` — unified retrieval
 
-```ts
-const tenants = await client.tenants.list();
-console.log(tenants);
-```
+`POST /query` → `HandlerEnvelopeSearchV2RetrievalResult`
 
-### List sub-tenants
+The single retrieval endpoint. Dispatches across corpus (`type`) and retrieval method
+(`queryBy`), optionally enriching results with knowledge‑graph context.
 
-```ts
-const subTenants = await client.tenants.subTenants({
-  tenantId: TENANT_ID,
+```typescript
+const result = await client.query({
+  query: "How do I rotate API keys?",
+  database: "acme-corp",          // v2 name for the tenant scope
+  type: "knowledge",              // "knowledge" | "memory" | "all"
+  queryBy: "hybrid",              // "hybrid" | "text"
+  mode: "auto",                   // "fast" | "thinking" | "auto"
+  operator: "or",                 // "or" | "and" | "phrase"
+  maxResults: 10,
+  numRelatedChunks: 3,
+  graphContext: true,             // include KG context (default true)
+  recencyBias: 0.2,
+  metadataFilters: {              // exact-match on tenant/document metadata
+    department: "security",
+    additional_metadata: { author: "ada" },
+  },
 });
 
-console.log(subTenants);
+console.log(result.data);
 ```
 
-### Check tenant infrastructure status
+**Scoping to specific collections** (preferred over the deprecated `subTenantIds`):
 
-```ts
-const infraStatus = await client.tenants.status({
-  tenantId: TENANT_ID,
-});
+```typescript
+// Equal weighting across collections
+await client.query({ query: "pricing", database: "acme-corp", collections: ["eu", "us"] });
 
-console.log(infraStatus);
+// Weighted ranking (one decimal place max)
+await client.query({ query: "pricing", database: "acme-corp", collections: { eu: 1.0, us: 0.5 } });
 ```
 
-### Tenant stats
+**Scoping to specific source IDs** — `ids` applies a hard `source_id in [...]` pre‑filter; if
+nothing matches it returns empty rather than widening to the whole corpus:
 
-```ts
-const stats = await client.tenants.stats({
-  tenantId: TENANT_ID,
-});
-
-console.log(stats);
+```typescript
+await client.query({ query: "onboarding", database: "acme-corp", ids: ["doc_123", "doc_456"] });
 ```
 
-### Delete a tenant
+Key fields (`SearchQueryRequest`):
 
-> Warning: this permanently deletes the tenant and its data.
+| Field                     | Type                                | Notes |
+| ------------------------- | ----------------------------------- | ----- |
+| `query`                   | `string`                            | The search text. |
+| `database`                | `string`                            | Tenant scope (v2). Alias: `tenantId`. |
+| `collection` / `collections` | `string` / `string[] \| Record<string, number>` | Sub‑tenant scope. Prefer over `subTenantId(s)`. |
+| `type`                    | `"knowledge" \| "memory" \| "all"`  | Corpus to query. |
+| `queryBy`                 | `"hybrid" \| "text"`                | Retrieval method. |
+| `mode`                    | `"fast" \| "thinking" \| "auto"`    | Recall mode. |
+| `operator`                | `"or" \| "and" \| "phrase"`         | Text‑match operator. |
+| `maxResults`              | `number`                            | Result cap. |
+| `numRelatedChunks`        | `number`                            | Neighboring chunks to attach. |
+| `graphContext`            | `boolean`                           | Include KG context. Default `true`. |
+| `queryApps`               | `boolean`                           | App‑aware knowledge retrieval. |
+| `queryForcefulRelations`  | `boolean`                           | Force relation expansion. Default `true`. |
+| `metadataFilters`         | `Record<string, unknown>`           | Exact‑match (nest doc metadata under `additional_metadata`). |
+| `recencyBias`             | `number`                            | Boost newer sources. |
+| `ids`                     | `string[]`                          | Restrict to specific source IDs. |
 
-```ts
-await client.tenants.delete({
-  tenantId: TENANT_ID,
-});
-```
+---
 
-## Ingest knowledge and memory
+### Context (`client.context`)
 
-`client.context.ingest()` handles both knowledge files and memory, selected via the `type` field (`"knowledge"` or `"memory"`).
+Everything about the data *inside* a database: ingesting, listing, inspecting, updating
+metadata, checking processing status, reading graph relations, and deleting.
 
-### Ingest one file
+#### `context.ingest`
 
-`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.
+`POST /context/ingest` (multipart) → `HandlerEnvelopeIngestionV2SourceUploadResponse`
 
-```ts
-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,
-});
+Ingest knowledge documents or memories. `documents` is a file upload; the other structured
+fields are JSON strings.
 
-console.log(uploadResult);
-```
+```typescript
+import { createReadStream } from "fs";
 
-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 a document file
+const res = await client.context.ingest({
+  tenantId: "acme-corp",                 // required
+  documents: createReadStream("handbook.pdf"),
+  subTenantId: "hr",
+  type: "knowledge",
+  // documentMetadata is a JSON *array* — one object per uploaded file.
+  documentMetadata: JSON.stringify([{ title: "Employee Handbook", author: "HR" }]),
+  upsert: "true",                        // form field is a string
+});
 
-### Ingest multiple files
+console.log(res.data);
 
-```ts
+// Ingest memories (no file). Each item needs "text" (or "user_assistant_pairs").
 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,
+  tenantId: "acme-corp",
+  memories: JSON.stringify([{ text: "User prefers dark mode" }]),
+  type: "memory",
 });
 ```
 
-Buffers, blobs, and streams also work:
+| Field              | Type                     | Notes |
+| ------------------ | ------------------------ | ----- |
+| `tenantId`         | `string` (required)      | Database. |
+| `documents`        | `Uploadable`             | File upload (stream, `Blob`, `Buffer`, etc.). |
+| `memories`         | `string`                 | JSON **array** string; each item needs `text` (or `user_assistant_pairs`). |
+| `documentMetadata` | `string`                 | JSON **array** string of per‑document metadata — one object per uploaded file (count must match). |
+| `appKnowledge`     | `string`                 | App‑knowledge payload. |
+| `graphPayload`     | `string`                 | Pre‑computed graph payload. |
+| `subTenantId`      | `string`                 | Collection. |
+| `type`             | `string`                 | `"knowledge"` or `"memory"`. |
+| `upsert`           | `string`                 | `"true"` to upsert on existing IDs. |
 
-```ts
-import { readFileSync } from "node:fs";
+#### `context.list`
 
-await client.context.ingest({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
+`POST /context/list` → `HandlerEnvelopeListV2SourceListResponse`
+
+List sources or memories (IDs + metadata) for a database, with filtering and pagination.
+
+```typescript
+const res = await client.context.list({
+  database: "acme-corp",
+  collection: "hr",
   type: "knowledge",
-  documents: [
-    {
-      data: readFileSync("./report.pdf"),
-      filename: "report.pdf",
-      contentType: "application/pdf",
-    },
-  ],
+  page: 1,
+  pageSize: 50,
+  includeFields: ["title", "type", "timestamp"],
+  filters: {
+    metadata: { department: "finance" },        // tenant/source metadata
+    additionalMetadata: { author: "ada" },       // document metadata
+    sourceFields: { type: "pdf" },               // well-known source fields
+  },
 });
+
+for (const source of res.data.sources ?? []) {
+  console.log(source);
+}
 ```
 
-### Ingest files with per-file metadata
+#### `context.inspect`
 
-`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`.
+`GET /context/inspect` → `HandlerEnvelopeFetchV2SourceFetchResponse`
 
-```ts
-const documentMetadata = [
-  {
-    id: "doc_a",
-    metadata: { department: "sales" },
-    additional_metadata: { author: "Alice" },
-  },
-  {
-    id: "doc_b",
-    metadata: { department: "marketing" },
-    additional_metadata: { author: "Bob" },
-    relations: {
-      cortex_source_ids: ["doc_a"],
-      properties: { relation: "same_upload_batch" },
-    },
-  },
-];
+Fetch a single ingested source: its content, inferred content, and a presigned download URL.
 
-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" },
-  ],
-  documentMetadata: JSON.stringify(documentMetadata),
-  upsert: true,
+```typescript
+const res = await client.context.inspect({
+  id: "doc_1234",              // required — source ID
+  tenantId: "acme-corp",       // required
+  subTenantId: "hr",
+  expirySeconds: 3600,         // presigned URL lifetime
+  mode: "both",                // fetch mode: "content", "url", or "both"
 });
+console.log(res.data);
 ```
 
-### Ingest app-generated knowledge
+#### `context.status`
 
-`appKnowledge` is a JSON **string** — a single source object or an array of source objects (knowledge only).
+`GET /context/status` → `HandlerEnvelopeIngestionV2BatchProcessingStatus`
 
-```ts
-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" },
-  },
-];
+Check processing status for one or more source IDs.
 
-await client.context.ingest({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
-  type: "knowledge",
-  appKnowledge: JSON.stringify(appKnowledge),
-  upsert: true,
+```typescript
+// Single source
+await client.context.status({ tenantId: "acme-corp", id: "doc_1234", subTenantId: "hr" });
+
+// Batch
+const res = await client.context.status({
+  tenantId: "acme-corp",
+  ids: ["doc_1", "doc_2", "doc_3"],
 });
+console.log(res.data);
 ```
 
-### Add memories
+#### `context.relations`
 
-`memories` is a JSON **string** — a JSON array of memory items (memory only). Each item can include `text`, `title`, `infer`, and `metadata`.
+`GET /context/relations` → `HandlerEnvelopeGraphGraphRelationsResponse`
 
-```ts
-const memories = [
-  {
-    source_id: "memory_001",
-    text: "User prefers detailed technical explanations.",
-    title: "User preference",
-    infer: true,
-    metadata: { category: "preference" },
-  },
-];
+Return knowledge‑graph relations for a whole database or a single source.
 
-await client.context.ingest({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
-  type: "memory",
-  memories: JSON.stringify(memories),
-  upsert: true,
+```typescript
+const res = await client.context.relations({
+  tenantId: "acme-corp",       // required
+  subTenantId: "hr",
+  id: "doc_1234",              // omit for database-wide relations
+  type: "knowledge",           // "knowledge" | "memory"
+  limit: 100,
+  cursor: 0,                   // pagination cursor
 });
+console.log(res.data);
 ```
 
-## Check ingestion status
+#### `context.updateSourceMetadata`
 
-`client.context.status()` reports indexing status for one or more source IDs. Pass a single `id` or a list via `ids`.
+`PATCH /context/sources/{sourceId}/metadata` → `HandlerEnvelope…MetadataEditResult`
 
-```ts
-const status = await client.context.status({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
-  ids: ["source-id-1", "source-id-2"],
-});
+Merge/upsert `tenantMetadata` and `additionalMetadata` for one source. `subTenantId` is
+required by the server.
 
-console.log(status);
+```typescript
+const res = await client.context.updateSourceMetadata({
+  sourceId: "doc_1234",        // required — path param
+  tenantId: "acme-corp",
+  subTenantId: "hr",
+  // tenantMetadata keys must be declared in the database's tenant_metadata_schema
+  // (and match the declared type). Use additionalMetadata for free-form fields.
+  tenantMetadata: { department: "finance" },
+  additionalMetadata: { author: "ada", tags: ["policy", "2026"], reviewed: true },
+});
+console.log(res.data);
 ```
 
-### Poll until ingestion finishes
+> **Note:** although the SDK exposes a `documentMetadata` parameter here, this endpoint
+> **rejects** it (HTTP 400 "document_metadata is not accepted; use additional_metadata").
+> Put per-document fields in `additionalMetadata` instead.
 
-```ts
-const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+#### `context.delete`
 
-async function waitForIngestion(ids: string[]) {
-  while (true) {
-    const status = await client.context.status({
-      tenantId: TENANT_ID,
-      subTenantId: SUB_TENANT_ID,
-      ids,
-    });
+`DELETE /context` → `HandlerEnvelopeSourcesMemoryDeleteResponse`
 
-    // Inspect the returned status fields (per the SourceStatusApiResponse
-    // schema) and break once everything has completed or errored.
-    console.log(status);
+Delete one or more sources or memories by ID.
 
-    await sleep(5000);
-  }
-}
+```typescript
+const res = await client.context.delete({
+  database: "acme-corp",
+  collection: "hr",
+  ids: ["doc_1234", "doc_5678"],
+  type: "knowledge",
+});
+console.log(res.data);
 ```
 
-## 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
-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);
-```
+### Databases (`client.databases`)
 
-### Search knowledge, memory, or both
+Manage databases (tenants) and inspect their collections, stats, and provisioning status.
 
-Use the `type` field:
+#### `databases.create`
 
-```ts
-// Knowledge only
-await client.query({ tenantId: TENANT_ID, query: "quarterly revenue", type: "knowledge" });
+`POST /databases` → `HandlerEnvelopeTenantsTenantCreateAcceptedResponse`
 
-// Memory only
-await client.query({ tenantId: TENANT_ID, query: "user preferences", type: "memory" });
+Create a new database, optionally with a custom metadata schema for its collections.
 
-// Both, merged
-await client.query({ tenantId: TENANT_ID, query: "what does the user prefer", type: "all" });
+```typescript
+const res = await client.databases.create({
+  database: "acme-corp",
+  embeddingsDimension: 1536,
+  isEmbeddingsTenant: true,
+  tenantMetadataSchema: [
+    {
+      name: "department",
+      dataType: "VARCHAR",   // BOOL | INT8..INT64 | FLOAT | DOUBLE | VARCHAR | JSON | ARRAY
+      maxLength: 128,
+      enableMatch: true,
+    },
+    { name: "priority", dataType: "INT32" },
+  ],
+});
+console.log(res.data);
 ```
 
-### Hybrid vs. keyword search
+> Creation is asynchronous — poll [`databases.status`](#databasesstatus) until infrastructure
+> is provisioned before ingesting.
 
-`alpha` controls the hybrid balance and can be a number in `0.0`–`1.0` or the string `"auto"`:
+#### `databases.list`
 
-- `1.0`: more semantic/vector weighted
-- `0.0`: more keyword/BM25 weighted
-- `"auto"`: backend chooses the balance
+`GET /databases` → `HandlerEnvelopeTenantsTenantIdsResponse`
 
-For pure keyword/BM25 search, set `queryBy: "text"` and choose an `operator`:
+List all databases for the authenticated user. Takes no request body.
 
-```ts
-const response = await client.query({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
-  query: "enterprise plan",
-  queryBy: "text",
-  operator: "phrase", // "or" | "and" | "phrase"
-  type: "knowledge",
-});
+```typescript
+const res = await client.databases.list();
+console.log(res.data);
 ```
 
-`queryBy` accepts `"hybrid"` (vector + BM25, default) or `"text"` (BM25 only). `operator` applies only when `queryBy: "text"`.
+#### `databases.collections`
 
-### Metadata filters
+`GET /databases/collections` → `HandlerEnvelopeTenantsSubTenantIdsResponse`
 
-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).
+List all collections within a database.
 
-```ts
-const response = await client.query({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
-  query: "revenue forecast",
-  maxResults: 10,
-  metadataFilters: {
-    department: "sales",
-    additional_metadata: { author: "Alice" },
-  },
-});
+```typescript
+const res = await client.databases.collections({ database: "acme-corp" });
+console.log(res.data);
 ```
 
-### All `query` options
+#### `databases.stats`
 
-| 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"`). |
+`GET /databases/stats` → `HandlerEnvelopeTenantsTenantStatsResponse`
 
-## Formatting results for an LLM
+Get collection statistics for a database.
 
-`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`.
+```typescript
+const res = await client.databases.stats({ database: "acme-corp" });
+console.log(res.data);
+```
 
-```ts
-import { HydraDBClient, buildString } from "@hydradb/sdk";
+#### `databases.status`
 
-const client = new HydraDBClient({ token: process.env.HYDRA_DB_API_KEY });
+`GET /databases/status` → `HandlerEnvelopeTenantsInfraStatusResponseV2`
 
-const response = await client.query({
-  tenantId: TENANT_ID,
-  query: "What does the user prefer?",
-});
+Check infrastructure provisioning status for a database.
 
-// Pass the full envelope or just the data — buildString handles both.
-console.log(buildString(response));
-console.log(buildString(response.data!));
+```typescript
+const res = await client.databases.status({ database: "acme-corp" });
+console.log(res.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."`.
-
-## Inspect, list, and delete sources
+#### `databases.delete`
 
-### List sources
+`DELETE /databases` → `HandlerEnvelopeTenantsTenantDeleteResponse`
 
-```ts
-const sources = await client.context.list({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
-  type: "knowledge",
-  page: 1,
-  pageSize: 50,
-});
+Delete a database and **all** associated data.
 
-console.log(sources);
+```typescript
+const res = await client.databases.delete({ database: "acme-corp" });
+console.log(res.data);
 ```
 
-List memories with `type: "memory"`.
+---
 
-### Fetch specific source IDs
+### Webhooks (`client.webhooks`)
 
-```ts
-const sources = await client.context.list({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
-  type: "knowledge",
-  ids: ["doc_a", "doc_b"],
-});
-```
+Register a single indexing webhook per org and inspect/replay its deliveries.
 
-### Filter listed data
+#### `webhooks.register`
 
-```ts
-const filtered = await client.context.list({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
-  type: "knowledge",
-  filters: {
-    tenant_metadata: { department: "sales" },
-    document_metadata: { author: "Alice" },
-  },
-});
-```
+`POST /webhooks/indexing` → `HandlerEnvelopeWebhooksWebhookRegisterResponse`
 
-### Include only selected fields
+Register (or update) the indexing webhook for this API key’s org.
 
-```ts
-const sources = await client.context.list({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
-  type: "knowledge",
-  includeFields: ["title", "document_metadata", "tenant_metadata"],
+```typescript
+const res = await client.webhooks.register({
+  url: "https://example.com/hooks/hydradb",
+  eventTypes: ["indexing.status_changed"],       // the only supported event type
+  signingSecret: "whsec_at_least_16_chars",      // must be >= 16 characters
 });
+console.log(res.data);
 ```
 
-Allowed field names:
-
-```text
-attachments, content, description, document_metadata, note, relations,
-tenant_metadata, timestamp, title, type, url
-```
+#### `webhooks.get`
 
-### Inspect a single source
+`GET /webhooks/indexing` → `HandlerEnvelopeWebhooksWebhookGetResponse`
 
-```ts
-const source = await client.context.inspect({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
-  id: "source-id-1",
-  mode: "content",
-});
+Fetch the currently registered webhook. Takes no request body.
 
-console.log(source);
+```typescript
+const res = await client.webhooks.get();
+console.log(res.data);
 ```
 
-Supported `mode` values: `content` | `url` | `both`. For presigned URLs, set `expirySeconds`:
+#### `webhooks.test`
 
-```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
+`POST /webhooks/indexing/test` → `HandlerEnvelopeWebhooksWebhookTestResponse`
 
-```ts
-const relations = await client.context.relations({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
-  id: "source-id-1",
-  type: "knowledge",
-  limit: 10,
-});
+Send a test delivery to the registered endpoint.
 
-console.log(relations);
+```typescript
+const res = await client.webhooks.test();
+console.log(res.data);
 ```
 
-Omit `id` to fetch relations across the whole sub-tenant. Use `cursor` for pagination.
+#### `webhooks.delete`
 
-### Delete sources
+`DELETE /webhooks/indexing` → `HandlerEnvelopeWebhooksWebhookDeleteResponse`
 
-Use `type` to target knowledge or memory.
+Remove the registered webhook.
 
-```ts
-await client.context.delete({
-  tenantId: TENANT_ID,
-  subTenantId: SUB_TENANT_ID,
-  ids: ["source-id-1", "source-id-2"],
-  type: "knowledge",
-});
+```typescript
+const res = await client.webhooks.delete();
+console.log(res.data);
 ```
 
-## Webhooks
+#### `webhooks.listDeliveries`
 
-Hydra DB can notify your application about events such as indexing status changes.
+`GET /webhooks/indexing/deliveries` → `HandlerEnvelopeWebhooksDeliveryListResponse`
 
-### Register a webhook
+List recent webhook deliveries, with filtering and cursor pagination.
 
-```ts
-const hook = await client.webhooks.register({
-  url: "https://example.com/hydra-webhook",
-  eventTypes: ["indexing.status_changed"],
-  signingSecret: "a-secret-at-least-16-chars",
+```typescript
+const res = await client.webhooks.listDeliveries({
+  limit: 50,
+  cursor: undefined,           // pass the previous page's cursor to continue
+  status: "failed",           // filter by delivery status
 });
-
-console.log(hook);
+console.log(res.data);
 ```
 
-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.
+#### `webhooks.getDelivery`
 
-### Get the current webhook
+`GET` → `HandlerEnvelopeWebhooksDeliveryItem`
 
-```ts
-console.log(await client.webhooks.get());
+Fetch a single delivery by ID.
+
+```typescript
+const res = await client.webhooks.getDelivery({ deliveryId: "dlv_1234" });
+console.log(res.data);
 ```
 
-### Delete the webhook
+#### `webhooks.retryDelivery`
 
-```ts
-await client.webhooks.delete();
-```
+`POST` → `HandlerEnvelopeWebhooksRetryResponse`
 
-### Send a test event
+Re‑attempt a failed delivery.
 
-```ts
-await client.webhooks.test();
+```typescript
+const res = await client.webhooks.retryDelivery({ deliveryId: "dlv_1234" });
+console.log(res.data);
 ```
 
-### List and inspect deliveries
+---
 
-```ts
-const deliveries = await client.webhooks.listDeliveries({
-  limit: 20,
-  status: "failed", // pending | failed | delivered | permanently_failed
-});
-console.log(deliveries);
+## Error handling
 
-const one = await client.webhooks.getDelivery({ deliveryId: "delivery_id" });
-console.log(one);
-```
+Non‑2xx responses throw typed errors. Each carries `statusCode`, the parsed `body`, and the
+`rawResponse`. All extend `HydraDBError`.
 
-Use `cursor` to paginate deliveries.
+```typescript
+import {
+  HydraDBClient,
+  HydraDB, // namespace with the typed error classes
+  HydraDBError,
+} from "@hydradb/sdk";
 
-### Retry a delivery
+const client = new HydraDBClient({ token: "YOUR_API_KEY" });
 
-```ts
-await client.webhooks.retryDelivery({ deliveryId: "delivery_id" });
+try {
+  await client.databases.status({ database: "does-not-exist" });
+} catch (err) {
+  if (err instanceof HydraDB.NotFoundError) {
+    console.error("not found:", err.body);
+  } else if (err instanceof HydraDBError) {
+    console.error(`API error ${err.statusCode}:`, err.body);
+  } else {
+    throw err;
+  }
+}
 ```
 
-## Accessing raw responses
+Typed error classes (under the `HydraDB` namespace): `BadRequestError` (400),
+`ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409),
+`UnprocessableEntityError` (422), `InternalServerError` (500). Network/timeout failures throw
+`HydraDBTimeoutError` / `HydraDBError`.
 
-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 { data, rawResponse } = await client
-  .query({ tenantId: TENANT_ID, query: "revenue" })
-  .withRawResponse();
+## Advanced
+
+### Per-request options (timeouts, retries, abort)
+
+Every method accepts a second `requestOptions` argument that overrides client defaults for
+that call.
+
+```typescript
+const controller = new AbortController();
 
-console.log(rawResponse.status, data.data?.chunks);
+await client.query(
+  { query: "hello", database: "acme-corp" },
+  {
+    timeoutInSeconds: 30,
+    maxRetries: 3,
+    apiVersion: "2",
+    headers: { "X-Trace-Id": "abc123" },
+    abortSignal: controller.signal,
+  },
+);
 ```
 
-## Passthrough fetch
+### Passthrough `fetch`
 
-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.
+For endpoints not yet wrapped by the SDK, `client.fetch` issues a request using the SDK's
+configured auth, retries, and logging. Relative paths resolve against the configured base URL.
 
-```ts
-const response = await client.fetch("/metrics", { method: "GET" });
-const data = await response.json();
+```typescript
+const response = await client.fetch("/some/new/endpoint", {
+  method: "POST",
+  body: JSON.stringify({ hello: "world" }),
+});
+console.log(await response.json());
 ```
 
-## Error handling
+### Custom fetch & logging
 
-```ts
-import {
-  HydraDBError,
-  HydraDBTimeoutError,
-  HydraDB,
-} from "@hydradb/sdk";
+```typescript
+import { HydraDBClient } from "@hydradb/sdk";
+import nodeFetch from "node-fetch";
 
-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);
-  }
-}
+const client = new HydraDBClient({
+  token: "YOUR_API_KEY",
+  fetch: nodeFetch as unknown as typeof fetch,
+  logging: { level: "debug" },
+});
 ```
 
-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.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
-
-- **Homepage:** [hydradb.com](https://www.hydradb.com/)
-- **Documentation:** [docs.hydradb.com](https://docs.hydradb.com/)
-- **API Reference:** [docs.hydradb.com/api-reference/introduction](https://docs.hydradb.com/api-reference/introduction)
-
-## Support
-
-If you have any questions or need help, reach out at [founders@hydradb.com](mailto:founders@hydradb.com).
+---
+
+## Endpoint reference
+
+| Group     | Method                  | HTTP                                       | Description |
+| --------- | ----------------------- | ------------------------------------------ | ----------- |
+| —         | `query`                 | `POST /query`                              | Unified hybrid/text retrieval with optional graph context. |
+| context   | `ingest`                | `POST /context/ingest`                     | Ingest documents or memories (multipart). |
+| context   | `list`                  | `POST /context/list`                       | List sources/memories with filters + pagination. |
+| context   | `inspect`               | `GET /context/inspect`                     | Fetch a source’s content + presigned URL. |
+| context   | `status`                | `GET /context/status`                      | Processing status for one or many source IDs. |
+| context   | `relations`             | `GET /context/relations`                   | KG relations for a database or source. |
+| context   | `updateSourceMetadata`  | `PATCH /context/sources/{id}/metadata`     | Merge/upsert metadata for a source. |
+| context   | `delete`                | `DELETE /context`                          | Delete sources/memories by ID. |
+| databases | `create`                | `POST /databases`                          | Create a database with optional schema. |
+| databases | `list`                  | `GET /databases`                           | List all databases. |
+| databases | `collections`           | `GET /databases/collections`               | List collections in a database. |
+| databases | `stats`                 | `GET /databases/stats`                     | Collection statistics. |
+| databases | `status`                | `GET /databases/status`                    | Infra provisioning status. |
+| databases | `delete`                | `DELETE /databases`                        | Delete a database and its data. |
+| webhooks  | `register`              | `POST /webhooks/indexing`                  | Register/update the org indexing webhook. |
+| webhooks  | `get`                   | `GET /webhooks/indexing`                   | Get the registered webhook. |
+| webhooks  | `test`                  | `POST /webhooks/indexing/test`             | Send a test delivery. |
+| webhooks  | `delete`                | `DELETE /webhooks/indexing`                | Remove the webhook. |
+| webhooks  | `listDeliveries`        | `GET /webhooks/indexing/deliveries`        | List recent deliveries. |
+| webhooks  | `getDelivery`           | `GET`                                      | Fetch one delivery by ID. |
+| webhooks  | `retryDelivery`         | `POST`                                     | Retry a failed delivery. |
+
+---
+
+_This SDK is generated from the HydraDB API definition. For the full type reference see the
+`api/` directory or https://docs.hydradb.com._