@ai2aim.ai/hivemind-sdk 1.0.15 → 3.1.1

package/README.md

@@ -1,858 +1,230 @@
-# @hivemind/sdk
+# @ai2aim.ai/hivemind-sdk
 
-Node.js / TypeScript SDK for the **Hivemind** API.
-Covers every endpoint — organizations, RAG queries, generation, scraping, analytics, billing, audio, agents, admin, Jira integration, and more.
-Includes a **CLI** (`hivemind`) for init, config, health, helper utilities, query, search, org creation, music generation, scraping, and manual schedule execution.
+Node.js / TypeScript SDK for the API-key-scoped Hivemind API.
 
-## Install
+The current contract is:
+- no public organization id in request paths
+- no public employee-id surface
+- no public billing, tier, or project/content APIs
+- each API key owns its own data scope
+- the SDK only sends the matching credential type per route group: API key for scoped routes, admin key for admin routes, and webhook secret for webhook routes
+- social content generation is available through `/v1/generate/social` with platform-specific analysis, SEO review, and guardrail output
 
-**From this repo (local):**
+## Install
 
 ```bash
 cd sdk
 npm install
 npm run build
-
-# Then in your other project:
-npm install ../path-to/VERTEX-AI/sdk
 ```
 
-**Or publish to a private registry and install normally:**
+Then from another project:
 
 ```bash
-npm install @hivemind/sdk
+npm install ../path-to/VERTEX-AI/sdk
 ```
 
-## Quick start
-
-Set **HIVEMIND_BASE_URL** (or HIVEMIND_API_URL) in your environment once. Then create clients with only the overrides you need (e.g. `adminKey`, `apiKey`); baseUrl is read from env when omitted.
+## Quick Start
 
-```typescript
-import { HivemindClient } from "@hivemind/sdk";
+```ts
+import { HivemindClient } from "@ai2aim.ai/hivemind-sdk";
 
 const client = new HivemindClient({
-  apiKey: "vtx_myorg_abc123...", // or pass per-request via options
+  baseUrl: process.env.HIVEMIND_BASE_URL!,
+  apiKey: process.env.HIVEMIND_API_KEY!,
 });
 
 const health = await client.health();
-const result = await client.query("my-org", { query: "What is the return policy?" });
-console.log(result.answer);
-```
-
-## Content Creator Scheduling
-
-The SDK also exposes the Content Creator project, content, source, and publish schedule routes.
-
-```typescript
-import { HivemindClient } from "@hivemind/sdk";
-
-const client = new HivemindClient({ baseUrl: process.env.HIVEMIND_BASE_URL });
-const apiKey = await getOrgApiKeyFromDb(orgId);
-
-const project = await client.createProject(orgId, {
-  name: "Launch Campaign",
-  description: "Q4 rollout",
-}, { apiKey });
-
-const item = await client.createContentItem(orgId, project.project_id, {
-  item_type: "article",
-  title: "Launch Post",
-  content: "We are launching this quarter.",
-  status: "ready",
-}, { apiKey });
-
-const schedule = await client.createPublishSchedule(orgId, project.project_id, {
-  content_id: item.content_id,
-  target_platforms: ["linkedin", "x"],
-  publish_at: "2026-03-17T12:00:00Z",
-}, { apiKey });
-
-console.log(schedule.status); // "scheduled"
-```
-
-In normal deployments, the backend processes due schedules automatically with its background content schedule runner. The manual admin fallback is:
-
-```typescript
-const admin = new HivemindClient({
-  baseUrl: process.env.HIVEMIND_BASE_URL,
-  adminKey: process.env.HIVEMIND_ADMIN_KEY,
+const result = await client.search({
+  query: "Summarize the indexed knowledge base.",
+  num: 5,
 });
 
-const result = await admin.runDueSchedules();
-console.log(result.published);
-```
-
-## Configuration
-
-| Option | Required | Description |
-|---|---|---|
-| `baseUrl` | No* | API base URL; defaults to **HIVEMIND_BASE_URL** or **HIVEMIND_API_URL** |
-| `apiPrefix` | No | Path prefix (default `/v1`) |
-| `apiKey` | No | Org API key; or pass per-request (see below) |
-| `adminKey` | No | Bootstrap admin key for admin endpoints |
-| `webhookSecret` | No | Secret for webhook endpoints |
-
-\* Required: either pass in config or set the env var.
-| `employeeId` | No | Employee ID header for RBAC |
-| `timeoutMs` | No | Request timeout in ms (default 30 000) |
-| `insecure` | No | Skip TLS verification for self-signed certs |
-
-### API key from your database or cache
-
-You do **not** need to put the org API key in the client config. Store it in **your system’s database or cache** (e.g. per tenant/org) and pass it per request via the optional `options` parameter.
-
-Set **HIVEMIND_BASE_URL** (or HIVEMIND_API_URL) in your environment. Then create one shared client with no API key; pass the key from your store on each org-scoped call:
-
-```typescript
-import { HivemindClient } from "@hivemind/sdk";
-
-// One shared client — no API key in config
-const client = new HivemindClient({});
-
-// In your app: load API key from your DB/cache for the current org
-const apiKey = await getOrgApiKeyFromDb(orgId); // your function
+const social = await client.generateSocialContent({
+  prompt: "Promote our AI writing assistant for startup marketers.",
+  platforms: ["x", "linkedin", "instagram"],
+  objective: "leads",
+  tone: "professional",
+  writing_style: "thought_leadership",
+  length: "short",
+  call_to_action: "Book a demo this week.",
+  primary_keyword: "AI writing assistant",
+  secondary_keywords: ["startup marketing", "content workflow"],
+  variation_count: 2,
+});
 
-const result = await client.query(orgId, { query: "What is the return policy?" }, { apiKey });
+console.log(health.status);
+console.log(result.organic);
+console.log(social.variants[0]?.body);
 ```
 
-All org-scoped methods accept an optional last argument `options?: RequestOptions` with `{ apiKey?: string }`. Use it to pass the key from your store instead of setting it on the client.
-
-### CLI config
-
-The CLI reads config from **environment variables** and optionally **`.hivemindrc.json`** in the current directory. Env overrides file.
-
-| Env | Description |
-|---|---|
-| `HIVEMIND_BASE_URL` | API base URL (required) |
-| `HIVEMIND_API_KEY` | Org API key (for org-scoped commands) |
-| `HIVEMIND_ADMIN_KEY` | Admin key for org:create and schedule:run-due |
-| `HIVEMIND_API_PREFIX` | Path prefix (default `/v1`) |
-| `HIVEMIND_INSECURE` | Set to `true` to skip TLS verification |
-| `HIVEMIND_TIMEOUT_MS` | Request timeout in ms |
-
-You can also set `apiKey` on the client for single-tenant use.
-
-### Admin endpoints
+## Bootstrap A New API Key Scope
 
-If base URL is already in env, pass only `adminKey`:
-
-```typescript
+```ts
 const admin = new HivemindClient({
-  adminKey: "your-bootstrap-admin-key",
+  baseUrl: process.env.HIVEMIND_BASE_URL!,
+  adminKey: process.env.HIVEMIND_ADMIN_KEY!,
 });
 
-// Create a new organization, or reuse it if it already exists
-const ensured = await admin.createOrganization({
-  org_id: "acme",
-  name: "Acme Corp",
-  tier: "premium",
+const issued = await admin.issueApiKey({
+  name: "Acme Marketing",
+  settings: { timezone: "UTC", brand_voice: "playful" },
 });
 
-if (ensured.created) {
-  console.log("API Key:", ensured.api_key);
-} else {
-  console.log("Already existed:", ensured.organization.org_id);
-}
+console.log(issued.api_key);
+console.log(issued.scope.name);
+```
+
+## Main Methods
+
+### Core
+
+```ts
+client.root();
+client.health();
+client.adminLogin({ admin_key });
+```
+
+### API key scope
+
+```ts
+client.issueApiKey({ name, settings });
+client.getCurrentScope();
+client.rotateApiKey();
+```
+
+### Knowledge and generation
+
+```ts
+client.uploadDocument(file, "handbook.pdf");
+client.search({ query: "best B2B onboarding examples", num: 5 });
+
+client.generateVideo(params);
+client.generateImage(params);
+client.generateMusic(params);
+client.generateSocialContent(params);
+client.getJob(jobId);
+client.waitForJob(jobId);
+```
+
+### Audio, analytics, and agents
+
+```ts
+client.transcribeAudio(params);
+client.synthesizeAudio(params);
+client.trainModel(params);
+client.predict(params);
+client.forecast(params);
+client.createAgent(params);
+client.queryAgent(params);
+client.dataChat(params);
+```
+
+### Jira, blueprints, and managed documents
+
+```ts
+client.connectJira(params);
+client.getJiraStatus();
+client.syncJira(params);
+client.disconnectJira();
+
+client.createBlueprint(params);
+client.listBlueprints();
+client.getBlueprint(blueprintId);
+client.updateBlueprint(blueprintId, params);
+client.publishBlueprint(blueprintId);
+client.archiveBlueprint(blueprintId);
+client.deleteBlueprint(blueprintId);
+
+client.createDocumentFromBlueprint(params);
+client.listManagedDocuments();
+client.getManagedDocument(documentId);
+client.updateDocumentSection(documentId, params);
+client.performDocumentWorkflow(documentId, params);
+client.generateDocumentSection(documentId, params);
+client.deleteManagedDocument(documentId);
+```
+
+### Scraping and admin
+
+```ts
+client.getScrapingConfig();
+client.scrape({ urls: ["https://example.com"] });
+client.getScrapeStatus(taskId);
+client.scrapeAndWait(["https://example.com"]);
+
+client.getAdminConfig();
+client.getAdminConfigOverrides();
+client.updateAdminSetting({ key, value });
+client.getLogLevel();
+client.setLogLevel({ level: "DEBUG" });
+client.getLoggers();
+client.getInboundTraffic();
+client.resetInboundTraffic();
+client.getOutboundStatus();
+client.getCors();
+client.setCors("*");
+client.getRateLimits();
+client.resetRateLimit(scopeId);
+client.listJobs();
+client.getFeatureFlags();
+client.getFeatureFlag(key);
+client.setFeatureFlag({ key, enabled: true });
+client.deleteFeatureFlag(key);
+client.getMaintenanceMode();
+client.setMaintenanceMode({ enabled: true, message: "Maintenance" });
+client.getCacheStats();
+client.flushCache();
+client.getAdminAudit();
+client.getSystemInfo();
 ```
 
 ## CLI
 
-After install, the `hivemind` binary is available (`npx hivemind` or via `npm exec hivemind` if installed globally).
-
-### Commands
-
-| Command | Description |
-|---|---|
-| `hivemind init` | Create `.hivemindrc.json` and `.env.example` in the current directory |
-| `hivemind config` | Print resolved config (secrets masked) |
-| `hivemind health` | Call the API health endpoint |
-| `hivemind helper validate` | Validate config and test connection |
-| `hivemind helper env` | Print env var template for copy-paste |
-| `hivemind query <org_id> <question>` | Run a RAG query (needs API key) |
-| `hivemind search <org_id> <query>` | Run source discovery search (needs API key) |
-| `hivemind org:create <org_id> <name>` | Create an organization (needs admin key) |
-| `hivemind music <org_id> <genre> <mood>` | Start music generation (needs API key) |
-| `hivemind scrape <url...>` | Submit URLs to scrape |
-| `hivemind scrape:status <task_id>` | Get scrape task status and result |
-| `hivemind schedule:run-due` | Manually process due Content Creator schedules (needs admin key) |
-
-### Examples
+After building, the `hivemind` binary is available.
 
 ```bash
-# Initialize config in current directory
 hivemind init
-
-# Only create .env.example
-hivemind init --env-only
-
-# Check connection
-export HIVEMIND_BASE_URL=https://your-api.com
+hivemind config
 hivemind health
-
-# Validate config and ping API
 hivemind helper validate
-
-# Print env template
 hivemind helper env
-
-# Run a RAG query (requires HIVEMIND_API_KEY)
-hivemind query my-org "What is the return policy?"
-
-# Run source discovery search
-hivemind search my-org "content marketing 2026" --type news --num 10
-
-# Create org (requires HIVEMIND_ADMIN_KEY)
-hivemind org:create acme "Acme Corp" --tier premium
-
-# Generate music and wait for completion
-hivemind music my-org ambient uplifting --duration 30 --wait
-
-# Scrape URLs and wait for results
-hivemind scrape https://example.com https://example.org --wait
-
-# Manually run due Content Creator schedules
-hivemind schedule:run-due
-```
-
-### Options
-
-- **`-d, --dir <path>`** (for init, config, health, helper, query, search, org:create, music, scrape, schedule:run-due): Directory to use for `.hivemindrc.json` (default: current directory).
-- **`-u, --url <url>`** (health): Override base URL for a one-off health check.
-- **`--skip-ping`** (helper validate): Validate config only, do not call the API.
-
-### Search, music, and schedules
-
-```typescript
-const search = await client.search("my-org", {
-  query: "best B2B content strategy",
-  type: "news",
-  num: 10,
-});
-
-const musicJob = await client.generateMusic("my-org", {
-  genre: "ambient",
-  mood: "uplifting",
-  duration: 30,
-});
-
-const music = await client.waitForJob("my-org", musicJob.job_id);
-
-const schedules = await client.listPublishSchedules("my-org", "proj_123", { apiKey });
-```
-
-## All methods
-
-All org-scoped methods accept an optional last argument `options?: RequestOptions` where you can pass `{ apiKey: string }` from your database or cache.
-
-**Authentication types:**
-- **Admin** — Set `adminKey` in client config. Sends `X-Admin-Key` header.
-- **API Key** — Set `apiKey` in config or pass per-request via `options.apiKey`. Sent as `Authorization: Bearer <key>`.
-- **Webhook** — Set `webhookSecret` in client config. Sends `X-Webhook-Secret` header.
-- **None** — No authentication required.
-
-All responses are wrapped in the standard envelope:
-```json
-{ "success": true, "statusCode": 200, "data": { ... }, "message": "Request successful" }
-```
-The SDK returns the **`data`** payload directly (unwrapped). If you need the full envelope (e.g. `message`, `statusCode`), use `client.requestEnvelope<T>(method, path, opts)`.
-
-The envelope types `ApiEnvelope<T>` and `ApiErrorBody` are exported from the SDK for use in your own code.
-
-### Health
-
-| Method | Auth | Description |
-|---|---|---|
-| `health()` | None | Service health check |
-
-**Returns** `HealthResponse`:
-
-| Field     | Type   | Description                                           |
-|-----------|--------|-------------------------------------------------------|
-| `service` | string | Service name                                          |
-| `version` | string | Service version                                       |
-| `status`  | string | Health status (`"ok"`)                                |
-| `stats`   | object | `{ organizations, documents, total_chunks }`          |
-
-### Admin auth
-
-| Method | Auth | Description |
-|---|---|---|
-| `adminLogin({ admin_key })` | None | Exchange admin key for a signed session token |
-
-**Parameters** (`AdminLoginParams`):
-
-| Field       | Type   | Required | Description                |
-|-------------|--------|----------|----------------------------|
-| `admin_key` | string | Yes      | The bootstrap admin key    |
-
-**Returns** `AdminLoginResponse`:
-
-| Field                | Type   | Description                              |
-|----------------------|--------|------------------------------------------|
-| `access_token`       | string | Signed JWT session token                 |
-| `token_type`         | string | Always `"bearer"`                        |
-| `expires_in_seconds` | number | Token validity (default 28800 = 8 hours) |
-
-```typescript
-const { access_token } = await client.adminLogin({ admin_key: "your-admin-key" });
-```
-
-### Organizations
-
-| Method | Auth | Description |
-|---|---|---|
-| `createOrganization(params, options?)` | Admin | Create org idempotently; returns existing org instead of throwing on duplicates |
-| `ensureOrganization(params)` | Admin | Create org if missing, or return existing org without throwing |
-| `getAdminOrganization(orgId)` | Admin | Get org details with admin credentials |
-| `getOrganization(orgId, options?)` | API Key | Get org details |
-| `rotateApiKey(orgId, options?)` | Admin | Rotate org API key (24h grace period for old key) |
-| `suspendOrganization(orgId, options?)` | Admin | Suspend an org (blocks API access) |
-| `reactivateOrganization(orgId, options?)` | Admin | Reactivate a suspended org |
-| `deleteOrganization(orgId, options?)` | Admin | Permanently delete an org (irreversible) |
-
-**`createOrganization` parameters** (`OrgCreateParams`):
-
-| Field      | Type   | Required | Default      | Description                                    |
-|------------|--------|----------|--------------|------------------------------------------------|
-| `org_id`   | string | Yes      | —            | Unique org identifier (2–64 chars)             |
-| `name`     | string | Yes      | —            | Display name (2–128 chars)                     |
-| `tier`     | string | No       | `"standard"` | `"free"`, `"standard"`, `"premium"`, `"enterprise"` |
-| `settings` | object | No       | `{}`         | Custom org settings                            |
-
-**Returns** `OrgEnsureResponse` by default:
-
-| Field          | Type                 | Description                                   |
-|----------------|----------------------|-----------------------------------------------|
-| `created`      | `true \| false`      | Whether this call created the org             |
-| `organization` | Organization         | Full organization entity                      |
-| `api_key`      | `string \| null`     | Generated API key, or `null` if org existed   |
-
-```typescript
-const ensured = await admin.createOrganization({
-  org_id: "acme-corp",
-  name: "Acme Corporation",
-  tier: "premium",
-});
-
-if (ensured.created) {
-  console.log("New API key:", ensured.api_key);
-} else {
-  console.log("Organization already existed:", ensured.organization.org_id);
-}
-```
-
-If you want strict create-only behavior and prefer duplicate orgs to throw:
-
-```typescript
-const created = await admin.createOrganization(
-  {
-    org_id: "acme-corp",
-    name: "Acme Corporation",
-    tier: "premium",
-  },
-  { allowExisting: false },
-);
-console.log("New API key:", created.api_key);
-```
-
-### Documents
-
-| Method | Auth | Description |
-|---|---|---|
-| `uploadDocument(orgId, file, filename, options?)` | API Key | Upload a document (Buffer or Blob) |
-
-**Parameters:**
-
-| Param      | Type           | Required | Description                           |
-|------------|----------------|----------|---------------------------------------|
-| `orgId`    | string         | Yes      | Organization identifier               |
-| `file`     | Blob \| Buffer | Yes      | Document content                      |
-| `filename` | string         | Yes      | Original filename (e.g. `"report.pdf"`) |
-
-**Returns** `DocumentUploadResponse`:
-
-| Field         | Type   | Description                               |
-|---------------|--------|-------------------------------------------|
-| `document_id` | string | Unique document identifier                |
-| `org_id`      | string | Organization ID                           |
-| `filename`    | string | Original filename                         |
-| `chunks`      | number | Number of text chunks created             |
-| `status`      | string | Processing status (e.g. `"processed"`)    |
-
-```typescript
-import { readFileSync } from "fs";
-const file = readFileSync("./report.pdf");
-const result = await client.uploadDocument("acme-corp", file, "report.pdf");
-console.log(`${result.chunks} chunks created`);
+hivemind search "content marketing trends 2026"
+hivemind api-key:issue "Acme Marketing"
+hivemind api-key:scope
+hivemind api-key:rotate
+hivemind social "Launch our AI assistant for startup marketers" --platforms x,linkedin,instagram --objective leads --tone professional --style thought_leadership --keyword "AI writing assistant" --variations 2
+hivemind music ambient uplifting --wait
+hivemind scrape https://example.com --wait
+hivemind scrape:status <task_id>
+hivemind start-web
 ```
 
-### Query (RAG)
+## Dashboard
 
-| Method | Auth | Description |
-|---|---|---|
-| `query(orgId, params, options?)` | API Key | RAG query with retrieval and generation |
+`hivemind start-web` launches a local browser dashboard with:
+- connection settings
+- API key issuance and rotation
+- search
+- document upload
+- generation jobs
+- social content generation
+- scraping
+- admin quick actions
+- manual request runner
 
-**Parameters** (`QueryParams`):
+## Error Handling
 
-| Field                | Type   | Required | Default      | Description                               |
-|----------------------|--------|----------|--------------|-------------------------------------------|
-| `query`              | string | Yes      | —            | Query text                                |
-| `user_id`            | string | No       | `null`       | User identifier for tracking              |
-| `model_type`         | string | No       | `"gemini-pro"` | Gemini model for generation             |
-| `temperature`        | number | No       | `0.2`        | Sampling temperature (0.0–1.0)            |
-| `retrieval_strategy` | string | No       | `"hybrid"`   | `"hybrid"`, `"dense"`, or `"sparse"`      |
+All API failures throw `HivemindError`.
 
-**Returns** `QueryResponse`:
-
-| Field        | Type     | Description                                     |
-|--------------|----------|-------------------------------------------------|
-| `answer`     | string   | Generated answer text                           |
-| `sources`    | object[] | Source citations (doc_id, chunk_id, score, snippet) |
-| `model_type` | string   | Model used                                      |
-
-```typescript
-const result = await client.query("acme-corp", {
-  query: "What are the key findings in Q4?",
-  temperature: 0.2,
-});
-console.log(result.answer);
-result.sources.forEach(s => console.log(s.doc_id, s.score));
-```
-
-### Generation
-
-| Method | Auth | Description |
-|---|---|---|
-| `generateVideo(orgId, params, options?)` | API Key | Start async video generation (Vertex AI Veo) |
-| `generateImage(orgId, params, options?)` | API Key | Start async image generation (Vertex AI Imagen) |
-
-**`generateVideo` parameters** (`GenerateVideoParams`):
-
-| Field          | Type   | Required | Default  | Description                        |
-|----------------|--------|----------|----------|------------------------------------|
-| `prompt`       | string | Yes      | —        | Video generation prompt            |
-| `duration`     | number | No       | `8`      | Duration: `4`, `6`, or `8` seconds |
-| `aspect_ratio` | string | No       | `"16:9"` | Aspect ratio                       |
-| `style`        | string | No       | `null`   | Visual style hint                  |
-| `user_id`      | string | No       | `null`   | User identifier                    |
-
-**`generateImage` parameters** (`GenerateImageParams`):
-
-| Field          | Type   | Required | Default | Description                   |
-|----------------|--------|----------|---------|-------------------------------|
-| `prompt`       | string | Yes      | —       | Image generation prompt       |
-| `aspect_ratio` | string | No       | `"1:1"` | Aspect ratio                  |
-| `style`        | string | No       | `null`  | Visual style hint             |
-| `num_images`   | number | No       | `1`     | Number of images (1–8)        |
-| `user_id`      | string | No       | `null`  | User identifier               |
-
-**Both return** `JobAcceptedResponse` (HTTP 202):
-
-| Field            | Type   | Description                                   |
-|------------------|--------|-----------------------------------------------|
-| `job_id`         | string | Job ID — use with `getJob()` / `waitForJob()` |
-| `status`         | string | Always `"processing"`                         |
-| `estimated_time` | number | Estimated processing time in seconds          |
-
-```typescript
-const job = await client.generateVideo("acme-corp", {
-  prompt: "A drone flyover of a mountain lake at sunset",
-  duration: 8,
-  style: "cinematic",
-});
-const result = await client.waitForJob("acme-corp", job.job_id);
-console.log(result.result); // { output_url, signed_url }
-```
-
-### Jobs
-
-| Method | Auth | Description |
-|---|---|---|
-| `getJob(orgId, jobId, options?)` | API Key | Get job status |
-| `waitForJob(orgId, jobId, intervalMs?, maxWaitMs?, options?)` | API Key | Poll until job reaches terminal status |
-
-**Returns** `JobStatusResponse`:
-
-| Field    | Type           | Description                                          |
-|----------|----------------|------------------------------------------------------|
-| `job_id` | string         | Job identifier                                       |
-| `status` | string         | `"processing"`, `"completed"`, `"failed"`, `"cancelled"` |
-| `result` | object \| null | Result payload when completed (e.g. `{ output_url, signed_url }`) |
-| `error`  | string \| null | Error message if failed                              |
-
-**`waitForJob` parameters:**
-
-| Param        | Type   | Default   | Description                 |
-|--------------|--------|-----------|-----------------------------|
-| `intervalMs` | number | `2000`    | Polling interval (ms)       |
-| `maxWaitMs`  | number | `300000`  | Maximum wait time (ms)      |
-
-### Data chat
-
-| Method | Auth | Description |
-|---|---|---|
-| `dataChat(orgId, params, options?)` | API Key | Natural-language questions over BigQuery |
-
-**Parameters** (`DataChatParams`):
-
-| Field      | Type   | Required | Description                    |
-|------------|--------|----------|--------------------------------|
-| `question` | string | Yes      | Natural-language question      |
-| `user_id`  | string | No       | User identifier for tracking   |
-
-**Returns** `DataChatResponse`:
-
-| Field       | Type     | Description                              |
-|-------------|----------|------------------------------------------|
-| `answer`    | string   | Natural-language answer                  |
-| `sql`       | string   | Generated SQL query                      |
-| `data`      | object[] | Result rows returned by the query        |
-| `row_count` | number   | Number of rows returned                  |
-| `tool_used` | string   | Backend tool used (e.g. `"alloydb"`)     |
-
-```typescript
-const result = await client.dataChat("acme-corp", {
-  question: "How many active users this month?",
-});
-console.log(result.answer); // "There are 1,247 active users."
-console.log(result.sql);    // "SELECT COUNT(DISTINCT user_id) FROM ..."
-```
-
-### Agents
-
-| Method | Auth | Description |
-|---|---|---|
-| `createAgent(orgId, params, options?)` | API Key | Create a custom AI agent template |
-| `queryAgent(orgId, params, options?)` | API Key | Query an AI agent |
-
-**`createAgent` parameters** (`AgentCreateParams`):
-
-| Field          | Type     | Required | Default | Description                     |
-|----------------|----------|----------|---------|---------------------------------|
-| `name`         | string   | Yes      | —       | Agent name (2–64 chars)         |
-| `instructions` | string   | Yes      | —       | System instructions (min 4 chars) |
-| `tools`        | string[] | No       | `[]`    | Tool identifiers to enable      |
-
-**`queryAgent` parameters** (`AgentQueryParams`):
-
-| Field        | Type   | Required | Default  | Description              |
-|--------------|--------|----------|----------|--------------------------|
-| `query`      | string | Yes      | —        | User query               |
-| `user_id`    | string | Yes      | —        | User identifier          |
-| `agent_type` | string | No       | `"auto"` | Agent type to route to   |
-
-### Audio
-
-| Method | Auth | Description |
-|---|---|---|
-| `transcribeAudio(orgId, params, options?)` | API Key | Speech-to-text transcription |
-| `synthesizeAudio(orgId, params, options?)` | API Key | Text-to-speech synthesis |
-
-**`transcribeAudio` parameters** (`AudioTranscribeParams`):
-
-| Field           | Type   | Required | Default    | Description               |
-|-----------------|--------|----------|------------|---------------------------|
-| `audio_text`    | string | No       | —          | Legacy text fallback      |
-| `audio_url`     | string | No       | —          | Audio URL for Scribe      |
-| `language_code` | string | No       | `"en-US"`  | BCP-47 language code      |
-| `model_id`      | string | No       | `"scribe_v2"` | STT model override     |
-
-**`synthesizeAudio` parameters** (`AudioSynthesizeParams`):
-
-| Field            | Type   | Required | Default              | Description                    |
-|------------------|--------|----------|----------------------|--------------------------------|
-| `text`           | string | Yes      | —                    | Text to synthesize             |
-| `voice_name`     | string | No       | `"en-US-Neural2-J"` | Voice identifier / voice ID    |
-| `model_id`       | string | No       | backend default      | ElevenLabs TTS model override  |
-| `output_format`  | string | No       | backend default      | Output format override         |
-| `language_code`  | string | No       | —                    | ISO 639-1 language code        |
-| `seed`           | number | No       | —                    | Deterministic synthesis seed   |
-| `voice_settings` | object | No       | backend default      | Per-request voice settings     |
-
-### Analytics / ML
-
-| Method | Auth | Description |
-|---|---|---|
-| `trainModel(orgId, params, options?)` | API Key | Train a predictive model on tabular data |
-| `predict(orgId, params, options?)` | API Key | Run predictions with a trained model |
-| `forecast(orgId, params, options?)` | API Key | Time-series forecast (ARIMA-based) |
-
-**`trainModel` parameters** (`TrainModelParams`):
-
-| Field             | Type     | Required | Description                 |
-|-------------------|----------|----------|-----------------------------|
-| `target_column`   | string   | Yes      | Column to predict           |
-| `feature_columns` | string[] | Yes      | Feature column names        |
-| `rows`            | object[] | Yes      | Training data rows          |
-
-**`predict` parameters** (`PredictParams`):
-
-| Field       | Type     | Required | Description                  |
-|-------------|----------|----------|------------------------------|
-| `model_id`  | string   | Yes      | Trained model ID             |
-| `instances` | object[] | Yes      | Data instances to predict on |
-
-**`forecast` parameters** (`ForecastParams`):
-
-| Field     | Type     | Required | Default | Description                    |
-|-----------|----------|----------|---------|--------------------------------|
-| `series`  | number[] | Yes      | —       | Historical time-series values  |
-| `horizon` | number   | No       | `30`    | Forecast horizon (1–365)       |
-
-```typescript
-// Train
-const model = await client.trainModel("acme-corp", {
-  target_column: "churn",
-  feature_columns: ["tenure", "monthly_charges"],
-  rows: [{ tenure: 12, monthly_charges: 50, churn: 0 }],
-});
-
-// Predict
-const { predictions } = await client.predict("acme-corp", {
-  model_id: model.model_id,
-  instances: [{ tenure: 6, monthly_charges: 65 }],
-});
-```
-
-### Billing
-
-| Method | Auth | Description |
-|---|---|---|
-| `getUsage(orgId, month?, options?)` | API Key | Monthly usage summary with tier limits |
-| `getInvoice(orgId, month?, options?)` | API Key | Monthly invoice with cost breakdown |
-
-**Optional `month` parameter:** `YYYY-MM` format. Defaults to current month.
-
-**`getUsage` returns** `UsageSummaryResponse`:
-
-| Field             | Type     | Description                                    |
-|-------------------|----------|------------------------------------------------|
-| `org_id`          | string   | Organization ID                                |
-| `month`           | string   | Month (`YYYY-MM`)                              |
-| `usage`           | object   | `{ tokens_used, images_generated, videos_generated, storage_bytes, compute_hours }` |
-| `limits`          | object   | Tier limits                                    |
-| `within_quota`    | boolean  | Whether all metrics are within quota           |
-| `exceeded_limits` | string[] | List of exceeded metric names                  |
-
-**`getInvoice` returns** `InvoiceResponse`:
-
-| Field      | Type   | Description                           |
-|------------|--------|---------------------------------------|
-| `org_id`   | string | Organization ID                       |
-| `month`    | string | Month (`YYYY-MM`)                     |
-| `usage`    | object | Usage counters for the billing period |
-| `costs`    | object | Cost breakdown by resource type       |
-| `total`    | number | Total cost for the period             |
-| `currency` | string | Currency code (e.g. `"USD"`)          |
-
-### Audit
-
-| Method | Auth | Description |
-|---|---|---|
-| `getAuditLogs(orgId, options?)` | API Key | List audit log records |
-
-**Returns** `AuditLogResponse`:
-
-| Field     | Type           | Description        |
-|-----------|----------------|--------------------|
-| `org_id`  | string         | Organization ID    |
-| `records` | AuditRecord[]  | Audit log entries  |
-
-Each `AuditRecord`:
-
-| Field      | Type           | Description                             |
-|------------|----------------|-----------------------------------------|
-| `timestamp`| string         | ISO 8601 timestamp                      |
-| `action`   | string         | Action (e.g. `"query.execute"`)         |
-| `resource` | string         | Resource path                           |
-| `status`   | string         | `"success"` or `"failure"`              |
-| `user_id`  | string \| null | User who performed the action           |
-| `metadata` | object         | Additional context                      |
-
-### Scraping
-
-| Method | Auth | Description |
-|---|---|---|
-| `getScrapingConfig()` | None | Runtime scraping configuration |
-| `scrape({ urls })` | None | Submit URLs for scraping |
-| `getScrapeStatus(taskId)` | None | Check scrape task status and results |
-| `scrapeAndWait(urls, intervalMs?, maxWaitMs?)` | None | Submit + poll until results are ready |
-
-**`scrape` parameters** (`ScrapeParams`):
-
-| Field  | Type     | Required | Description                     |
-|--------|----------|----------|---------------------------------|
-| `urls` | string[] | Yes      | URLs to scrape                  |
-
-**`getScrapeStatus` returns** `ScrapeStatusResponse`:
-
-| Field     | Type              | Description                                        |
-|-----------|-------------------|----------------------------------------------------|
-| `task_id` | string            | Task identifier                                    |
-| `status`  | string            | `"PENDING"`, `"SUCCESS"`, `"FAILURE"`, `"completed"` |
-| `result`  | ScrapeResultItem[] | Scraped results (each with url, title, full_text)  |
-
-```typescript
-const result = await client.scrapeAndWait(["https://example.com"]);
-for (const page of result.result) {
-  console.log(page.title, page.full_text?.substring(0, 200));
-}
-```
-
-### Webhooks
-
-| Method | Auth | Description |
-|---|---|---|
-| `sendVideoCompleteWebhook(payload)` | Webhook | Send video completion notification |
-| `sendDocumentProcessedWebhook(payload)` | Webhook | Send document processing notification |
-
-**`VideoCompleteWebhook` payload:**
-
-| Field      | Type   | Required | Description                         |
-|------------|--------|----------|-------------------------------------|
-| `job_id`   | string | Yes      | Job identifier                      |
-| `org_id`   | string | Yes      | Organization identifier             |
-| `status`   | string | Yes      | Completion status                   |
-| `metadata` | object | No       | Additional data (e.g. `{ output_uri }`) |
-
-**`DocumentProcessedWebhook` payload:**
-
-| Field         | Type   | Required | Description                         |
-|---------------|--------|----------|-------------------------------------|
-| `document_id` | string | Yes      | Document identifier                 |
-| `org_id`      | string | Yes      | Organization identifier             |
-| `status`      | string | Yes      | Processing status                   |
-| `metadata`    | object | No       | Additional data (e.g. `{ chunks }`) |
-
-## Real-time transports
-
-In addition to standard REST, the SDK supports **Server-Sent Events (SSE)** and **WebSocket** for streaming endpoints. Currently, project chat is the first endpoint to support these transports; additional endpoints can be added using the same primitives.
-
-### SSE (Server-Sent Events)
-
-Use `chatProjectSse()` to receive chat results as a stream of typed events:
-
-```typescript
-for await (const evt of client.chatProjectSse("acme", "proj-1", {
-  message: "Summarize our sources",
-  user_id: "u1",
-})) {
-  switch (evt.event) {
-    case "start":
-      console.log("Stream started for", evt.data.project_id);
-      break;
-    case "done":
-      console.log("Answer:", evt.data.answer);
-      break;
-    case "error":
-      console.error("Error:", evt.data.message);
-      break;
-  }
-}
-```
-
-**Endpoint:** `POST /v1/organizations/{orgId}/projects/{projectId}/chat/stream`
-
-**Event types:**
-
-| Event   | Data shape                       | Description                        |
-|---------|----------------------------------|------------------------------------|
-| `start` | `{ org_id, project_id }`         | Stream has started                 |
-| `done`  | `QueryResponse`                  | Final result (same shape as REST)  |
-| `error` | `{ message: string }`            | An error occurred                  |
-
-The SSE parser is also available standalone for custom use:
-
-```typescript
-import { parseSseStream } from "@ai2aim.ai/hivemind-sdk";
-
-const res = await fetch(url, { method: "POST", body, headers });
-for await (const event of parseSseStream(res.body!)) {
-  console.log(event.event, event.data);
-}
-```
-
-### WebSocket
-
-Use `chatProjectWebSocket()` to open a persistent connection for interactive chat:
-
-```typescript
-const ws = await client.chatProjectWebSocket("acme", "proj-1", {
-  apiKey: "vtx_...",
-});
-
-const frame = await ws.chat({
-  message: "What are our top sources?",
-  user_id: "u1",
-});
-
-if (frame.type === "result") {
-  console.log(frame.payload.answer);
-} else {
-  console.error(frame.message);
-}
-
-ws.close();
-```
-
-**Endpoint:** `WS /v1/organizations/{orgId}/projects/{projectId}/chat/ws?api_key=...`
-
-**Authentication:** The API key is sent as a `?api_key=` query parameter (browser-safe; `Authorization` headers are not available for browser WebSocket connections).
-
-**Client command frame:**
-
-```json
-{ "type": "chat", "message": "...", "user_id": "...", "temperature": 0.2 }
-```
-
-**Server response frames:**
-
-| `type`   | Shape                                | Description                          |
-|----------|--------------------------------------|--------------------------------------|
-| `result` | `{ type: "result", payload: QueryResponse }` | Successful chat result      |
-| `error`  | `{ type: "error", message: string }` | An error occurred                    |
-
-### Node.js vs browser
-
-- **SSE** uses the standard `fetch` API (`ReadableStream`), available in all modern browsers and Node 18+.
-- **WebSocket** uses `globalThis.WebSocket`. Browsers have this natively. Node 22+ includes a built-in `WebSocket`. For Node 18–21, install the [`ws`](https://www.npmjs.com/package/ws) package and assign `globalThis.WebSocket = require("ws")` before using WebSocket methods.
-- The `signal` option on `chatProjectWebSocket()` allows you to use an `AbortController` to close the connection from the outside.
-
-## Error handling
-
-All API errors throw `HivemindError`:
-
-```typescript
-import { HivemindClient, HivemindError } from "@hivemind/sdk";
+```ts
+import { HivemindClient, HivemindError } from "@ai2aim.ai/hivemind-sdk";
 
 try {
-  await client.query("my-org", { query: "hello" });
+  await client.search({ query: "hello", num: 3 });
 } catch (err) {
   if (err instanceof HivemindError) {
     console.error(err.statusCode, err.detail);
   }
 }
 ```
-
-`createOrganization(params)` and `ensureOrganization(params)` are idempotent for
-duplicate organizations by default. Pass `createOrganization(params, { allowExisting: false })`
-if you want duplicate-org responses to throw `HivemindError`.
-
-## Vercel / Next.js example
-
-```typescript
-// app/api/query/route.ts (Next.js App Router)
-import { HivemindClient } from "@hivemind/sdk";
-import { NextResponse } from "next/server";
-
-// With HIVEMIND_API_URL set in env
-const client = new HivemindClient({
-  apiKey: process.env.HIVEMIND_API_KEY!,
-});
-
-export async function POST(req: Request) {
-  const { query } = await req.json();
-  const result = await client.query("my-org", { query });
-  return NextResponse.json(result);
-}
-```