@ai2aim.ai/hivemind-sdk 1.0.14 → 2.0.1

package/README.md

@@ -1,758 +1,334 @@
-# @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 SDK tracks the current backend contract:
+- no public organization id in request paths
+- no public billing endpoints
+- no public tier or employee-id surface
+- API keys scope their own data
 
-**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?" });
+const result = await client.query({
+  query: "Summarize the indexed knowledge base.",
+});
+
+console.log(health.status);
 console.log(result.answer);
 ```
 
-## Content Creator Scheduling
+## Bootstrap A New API Key Scope
+
+```ts
+import { HivemindClient } from "@ai2aim.ai/hivemind-sdk";
+
+const admin = new HivemindClient({
+  baseUrl: process.env.HIVEMIND_BASE_URL!,
+  adminKey: process.env.HIVEMIND_ADMIN_KEY!,
+});
 
-The SDK also exposes the Content Creator project, content, source, and publish schedule routes.
+const issued = await admin.issueApiKey({
+  name: "Acme Marketing",
+  settings: { timezone: "UTC", brand_voice: "playful" },
+});
 
-```typescript
-import { HivemindClient } from "@hivemind/sdk";
+console.log(issued.api_key);
+console.log(issued.scope.name);
+```
 
-const client = new HivemindClient({ baseUrl: process.env.HIVEMIND_BASE_URL });
-const apiKey = await getOrgApiKeyFromDb(orgId);
+## Content Creator Example
 
-const project = await client.createProject(orgId, {
+```ts
+const client = new HivemindClient({
+  baseUrl: process.env.HIVEMIND_BASE_URL!,
+  apiKey: process.env.HIVEMIND_API_KEY!,
+});
+
+const project = await client.createProject({
   name: "Launch Campaign",
-  description: "Q4 rollout",
-}, { apiKey });
+  description: "Q4 rollout workspace",
+});
 
-const item = await client.createContentItem(orgId, project.project_id, {
+const item = await client.createContentItem(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, {
+const schedule = await client.createPublishSchedule(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 admin.runDueSchedules();
-console.log(result.published);
+console.log(schedule.status);
 ```
 
 ## 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
+| `baseUrl` | No* | API base URL. Defaults to `HIVEMIND_BASE_URL` or `HIVEMIND_API_URL`. |
+| `apiPrefix` | No | Path prefix. Defaults to `/v1`. |
+| `apiKey` | No | Bearer API key for API-key-scoped routes. |
+| `adminKey` | No | Bootstrap admin key for admin routes and `issueApiKey()`. |
+| `webhookSecret` | No | Secret for webhook receiver routes. |
+| `timeoutMs` | No | Request timeout in ms. Defaults to `30000`. |
+| `insecure` | No | Reserved for self-signed TLS workflows. |
 
-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.
+\* Required unless already present in env.
 
-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:
+## Main Methods
 
-```typescript
-import { HivemindClient } from "@hivemind/sdk";
+### Core
 
-// One shared client — no API key in config
-const client = new HivemindClient({});
+```ts
+client.root();
+client.health();
+client.adminLogin({ admin_key });
+```
 
-// In your app: load API key from your DB/cache for the current org
-const apiKey = await getOrgApiKeyFromDb(orgId); // your function
+### API key scope
 
-const result = await client.query(orgId, { query: "What is the return policy?" }, { apiKey });
+```ts
+client.issueApiKey({ name, settings });
+client.getCurrentScope();
+client.rotateApiKey();
 ```
 
-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.
+### Documents and knowledge
 
-### CLI config
+```ts
+client.uploadDocument(file, "handbook.pdf");
+client.query({ query: "What is our refund policy?" });
+client.search({ query: "best B2B onboarding examples", num: 5 });
+client.getAuditLogs();
+```
 
-The CLI reads config from **environment variables** and optionally **`.hivemindrc.json`** in the current directory. Env overrides file.
+### Projects
+
+```ts
+client.createProject({ name, description });
+client.listProjects();
+client.getProject(projectId);
+client.updateProject(projectId, { status: "archived" });
+client.deleteProject(projectId);
+
+client.chatProject(projectId, { message, user_id });
+client.getProjectChatHistory(projectId, userId);
+
+client.createContentItem(projectId, params);
+client.listContentItems(projectId);
+client.getContentItem(projectId, contentId);
+client.updateContentItem(projectId, contentId, params);
+client.deleteContentItem(projectId, contentId);
+
+client.createProjectSource(projectId, params);
+client.scrapeProjectSources(projectId, { urls });
+client.listProjectSources(projectId);
+client.getProjectSource(projectId, sourceId);
+client.updateProjectSource(projectId, sourceId, params);
+client.deleteProjectSource(projectId, sourceId);
+
+client.createPublishSchedule(projectId, params);
+client.listPublishSchedules(projectId);
+client.getPublishSchedule(projectId, scheduleId);
+client.updatePublishSchedule(projectId, scheduleId, params);
+client.deletePublishSchedule(projectId, scheduleId);
+```
 
-| 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 |
+### Generation and jobs
 
-You can also set `apiKey` on the client for single-tenant use.
+```ts
+const job = await client.generateImage({ prompt: "Studio product photo" });
+const status = await client.getJob(job.job_id);
+const final = await client.waitForJob(job.job_id);
+```
 
-### Admin endpoints
+Also available:
+
+```ts
+client.generateVideo(params);
+client.generateMusic(params);
+client.dataChat(params);
+client.createAgent(params);
+client.queryAgent(params);
+client.transcribeAudio(params);
+client.synthesizeAudio(params);
+client.trainModel(params);
+client.predict(params);
+client.forecast(params);
+```
 
-If base URL is already in env, pass only `adminKey`:
+### Jira and blueprints
+
+```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);
+```
 
-```typescript
-const admin = new HivemindClient({
-  adminKey: "your-bootstrap-admin-key",
-});
+### Scraping
 
-// Create a new organization, or reuse it if it already exists
-const ensured = await admin.createOrganization({
-  org_id: "acme",
-  name: "Acme Corp",
-  tier: "premium",
-});
+```ts
+client.getScrapingConfig();
+client.scrape({ urls: ["https://example.com"] });
+client.getScrapeStatus(taskId);
+client.scrapeAndWait(["https://example.com"]);
+```
 
-if (ensured.created) {
-  console.log("API Key:", ensured.api_key);
-} else {
-  console.log("Already existed:", ensured.organization.org_id);
-}
+### Admin
+
+```ts
+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();
+client.runDueSchedules();
 ```
 
 ## CLI
 
-After install, the `hivemind` binary is available (`npx hivemind` or via `npm exec hivemind` if installed globally).
+After building, the `hivemind` binary is available.
 
 ### 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
-
 ```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 query "What is our refund policy?"
+hivemind search "content marketing trends 2026"
+hivemind api-key:issue "Acme Marketing"
+hivemind api-key:scope
+hivemind api-key:rotate
+hivemind music ambient uplifting --wait
+hivemind scrape https://example.com --wait
+hivemind scrape:status <task_id>
 hivemind schedule:run-due
+hivemind start-web
 ```
 
-### 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
+## Streaming
 
-All org-scoped methods accept an optional last argument `options?: RequestOptions` where you can pass `{ apiKey: string }` from your database or cache.
+### SSE
 
-**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).
-
-### 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);
+```ts
+for await (const evt of client.chatProjectSse("proj_123", {
+  message: "Summarize our saved sources.",
+  user_id: "sdk-user",
+})) {
+  if (evt.event === "done") {
+    console.log(evt.data.answer);
+  }
 }
 ```
 
-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
+### WebSocket
 
-| 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`);
-```
+```ts
+const ws = await client.chatProjectWebSocket("proj_123");
 
-### Query (RAG)
-
-| Method | Auth | Description |
-|---|---|---|
-| `query(orgId, params, options?)` | API Key | RAG query with retrieval and generation |
-
-**Parameters** (`QueryParams`):
-
-| 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"`      |
-
-**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                |
-| `rows`   | object[] | Result rows from BigQuery          |
-
-```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 }],
+const frame = await ws.chat({
+  message: "What are our strongest sources?",
+  user_id: "sdk-user",
 });
-```
-
-### 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`)                    |
-| `total`      | number   | Total cost in USD                    |
-| `line_items` | object[] | Itemized costs per resource type     |
-
-### 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));
+if (frame.type === "result") {
+  console.log(frame.payload.answer);
 }
-```
 
-### 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 }`) |
+ws.close();
+```
 
-**`DocumentProcessedWebhook` payload:**
+## Dashboard
 
-| 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 }`) |
+`hivemind start-web` launches a local browser dashboard with:
+- connection settings
+- API key issuance and rotation
+- query and search
+- document upload
+- project creation and chat
+- generation jobs
+- scraping
+- manual request runner
 
-## Error handling
+## Error Handling
 
-All API errors throw `HivemindError`:
+All API failures 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.query({ query: "hello" });
 } 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);
-}
-```