@ai2aim.ai/hivemind-sdk 1.0.1

package/dist/client.js

@@ -0,0 +1,871 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HivemindClient = exports.HivemindError = void 0;
+const node_https_1 = __importDefault(require("node:https"));
+// Re-export all types for consumers
+__exportStar(require("./types"), exports);
+/**
+ * Error thrown when an API request fails.
+ * Contains the HTTP status code and the raw response body for inspection.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.query("my-org", { query: "hello" });
+ * } catch (err) {
+ *   if (err instanceof HivemindError) {
+ *     console.error(`HTTP ${err.statusCode}:`, err.detail);
+ *   }
+ * }
+ * ```
+ */
+class HivemindError extends Error {
+    statusCode;
+    detail;
+    constructor(statusCode, detail, message) {
+        super(message ?? `API request failed with status ${statusCode}`);
+        this.statusCode = statusCode;
+        this.detail = detail;
+        this.name = "HivemindError";
+    }
+}
+exports.HivemindError = HivemindError;
+function resolveClientConfig(input) {
+    const baseUrl = (input.baseUrl ??
+        process.env.HIVEMIND_BASE_URL ??
+        process.env.HIVEMIND_API_URL ??
+        "").replace(/\/+$/, "");
+    const iapClientId = input.iapClientId ?? process.env.IAP_CLIENT_ID ?? "";
+    if (!baseUrl || !iapClientId) {
+        throw new HivemindError(0, null, "baseUrl and iapClientId are required. Set them in config or in env: HIVEMIND_BASE_URL (or HIVEMIND_API_URL) and IAP_CLIENT_ID.");
+    }
+    return {
+        ...input,
+        baseUrl,
+        iapClientId,
+    };
+}
+class HivemindClient {
+    baseUrl;
+    prefix;
+    config;
+    iapToken = null;
+    iapTokenExpiry = 0;
+    fetchAgent;
+    constructor(config) {
+        this.config = resolveClientConfig(config);
+        this.baseUrl = this.config.baseUrl;
+        this.prefix = this.config.apiPrefix ?? "/v1";
+        if (this.config.insecure) {
+            this.fetchAgent = new node_https_1.default.Agent({ rejectUnauthorized: false });
+        }
+    }
+    // -----------------------------------------------------------------------
+    // IAP token helper
+    // -----------------------------------------------------------------------
+    async getIapToken() {
+        if (!this.config.iapClientId)
+            return null;
+        if (this.iapToken && Date.now() < this.iapTokenExpiry - 60_000) {
+            return this.iapToken;
+        }
+        const { GoogleAuth } = await Promise.resolve().then(() => __importStar(require("google-auth-library")));
+        const auth = new GoogleAuth({
+            ...(this.config.iapServiceAccountKeyPath
+                ? { keyFile: this.config.iapServiceAccountKeyPath }
+                : {}),
+        });
+        const client = await auth.getIdTokenClient(this.config.iapClientId);
+        const headers = await client.getRequestHeaders();
+        const bearer = headers["Authorization"] ?? headers["authorization"] ?? "";
+        this.iapToken = bearer.replace(/^Bearer\s+/i, "");
+        this.iapTokenExpiry = Date.now() + 55 * 60_000;
+        return this.iapToken;
+    }
+    // -----------------------------------------------------------------------
+    // Generic HTTP helpers
+    // -----------------------------------------------------------------------
+    async request(method, path, opts = {}) {
+        const url = new URL(`${this.prefix}${path}`, this.baseUrl);
+        if (opts.query) {
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v !== undefined && v !== null)
+                    url.searchParams.set(k, v);
+            }
+        }
+        const headers = { ...opts.headers };
+        const apiKey = opts.apiKey ?? this.config.apiKey;
+        // IAP token (outermost Bearer); org API key as X-API-Key or Bearer when no IAP
+        const iapToken = await this.getIapToken();
+        if (iapToken) {
+            headers["Authorization"] = `Bearer ${iapToken}`;
+            if (apiKey)
+                headers["X-API-Key"] = apiKey;
+        }
+        else if (apiKey) {
+            headers["Authorization"] = `Bearer ${apiKey}`;
+        }
+        if (this.config.adminKey) {
+            headers["X-Admin-Key"] = this.config.adminKey;
+        }
+        if (this.config.webhookSecret) {
+            headers["X-Webhook-Secret"] = this.config.webhookSecret;
+        }
+        if (this.config.employeeId) {
+            headers["X-Employee-Id"] = this.config.employeeId;
+        }
+        let bodyPayload;
+        if (opts.formData) {
+            bodyPayload = opts.formData;
+        }
+        else if (opts.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            bodyPayload = JSON.stringify(opts.body);
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs ?? 30_000);
+        try {
+            const fetchOpts = {
+                method,
+                headers,
+                body: bodyPayload,
+                signal: controller.signal,
+            };
+            if (this.fetchAgent) {
+                fetchOpts.agent = this.fetchAgent;
+            }
+            const res = await fetch(url.toString(), fetchOpts);
+            if (res.status === 204)
+                return undefined;
+            const text = await res.text();
+            let json;
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                json = text;
+            }
+            if (!res.ok) {
+                throw new HivemindError(res.status, json);
+            }
+            return json;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    get(path, query, options) {
+        return this.request("GET", path, { query, apiKey: options?.apiKey });
+    }
+    post(path, body, options) {
+        return this.request("POST", path, { body, apiKey: options?.apiKey });
+    }
+    del(path, options) {
+        return this.request("DELETE", path, { apiKey: options?.apiKey });
+    }
+    // -----------------------------------------------------------------------
+    // Health
+    // -----------------------------------------------------------------------
+    /**
+     * Check service health status. No authentication required.
+     *
+     * @returns Service name, version, status, and aggregate statistics.
+     *
+     * **Endpoint:** `GET /v1/health`
+     *
+     * @example
+     * ```typescript
+     * const health = await client.health();
+     * console.log(health.status); // "ok"
+     * console.log(health.stats); // { organizations: 12, documents: 450, total_chunks: 3200 }
+     * ```
+     */
+    health() {
+        return this.get("/health");
+    }
+    // -----------------------------------------------------------------------
+    // Admin auth
+    // -----------------------------------------------------------------------
+    /**
+     * Exchange the bootstrap admin key for a signed session token.
+     * The token can be used as `Authorization: Bearer <token>` for admin endpoints
+     * instead of sending the raw admin key on every request.
+     *
+     * @param params - Object containing the `admin_key`.
+     * @returns Signed session token with type and expiry.
+     * @throws {@link HivemindError} 400 if admin key is not configured on the server.
+     * @throws {@link HivemindError} 401 if the admin key is invalid.
+     *
+     * **Endpoint:** `POST /v1/admin/login`
+     *
+     * @example
+     * ```typescript
+     * const { access_token, expires_in_seconds } = await client.adminLogin({
+     *   admin_key: "your-bootstrap-admin-key",
+     * });
+     * // Use access_token as Bearer token for subsequent admin requests
+     * ```
+     */
+    adminLogin(params) {
+        return this.post("/admin/login", params);
+    }
+    // -----------------------------------------------------------------------
+    // Organizations (admin)
+    // -----------------------------------------------------------------------
+    /**
+     * Create a new organization. Returns the organization details and a generated API key.
+     *
+     * **Auth:** Requires `adminKey` in client config (sends `X-Admin-Key` header).
+     *
+     * @param params - Organization creation parameters (org_id, name, tier, settings).
+     * @returns The created organization and its API key.
+     * @throws {@link HivemindError} 400 if validation fails or org already exists.
+     * @throws {@link HivemindError} 401 if admin credentials are invalid.
+     *
+     * **Endpoint:** `POST /v1/organizations`
+     *
+     * @example
+     * ```typescript
+     * const { organization, api_key } = await admin.createOrganization({
+     *   org_id: "acme-corp",
+     *   name: "Acme Corporation",
+     *   tier: "premium",
+     * });
+     * console.log("API Key:", api_key); // Store securely — shown only once
+     * ```
+     */
+    createOrganization(params) {
+        return this.post("/organizations", params);
+    }
+    /**
+     * Retrieve organization details including tier, status, and settings.
+     *
+     * **Auth:** Requires org-scoped API key (via config or `options.apiKey`).
+     *
+     * @param orgId - Organization identifier.
+     * @param options - Optional per-request overrides (e.g. `{ apiKey }`).
+     * @returns Full organization entity.
+     * @throws {@link HivemindError} 401 if API key is missing or invalid.
+     * @throws {@link HivemindError} 403 if the API key belongs to a different org.
+     * @throws {@link HivemindError} 404 if the organization does not exist.
+     *
+     * **Endpoint:** `GET /v1/organizations/{orgId}`
+     */
+    getOrganization(orgId, options) {
+        return this.get(`/organizations/${orgId}`, undefined, options);
+    }
+    /**
+     * Rotate the API key for an organization. The previous key remains valid
+     * for a 24-hour grace period.
+     *
+     * **Auth:** Requires `adminKey` in client config.
+     *
+     * @param orgId - Organization identifier.
+     * @param options - Optional per-request overrides.
+     * @returns New API key and grace period expiry for the previous key.
+     * @throws {@link HivemindError} 401 if admin credentials are invalid.
+     * @throws {@link HivemindError} 404 if the organization does not exist.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/api-keys/rotate`
+     */
+    rotateApiKey(orgId, options) {
+        return this.post(`/organizations/${orgId}/api-keys/rotate`, undefined, options);
+    }
+    /**
+     * Suspend an organization, blocking all API key access until reactivated.
+     *
+     * **Auth:** Requires `adminKey` in client config.
+     *
+     * @param orgId - Organization identifier.
+     * @param options - Optional per-request overrides.
+     * @returns Updated organization status.
+     * @throws {@link HivemindError} 401 if admin credentials are invalid.
+     * @throws {@link HivemindError} 404 if the organization does not exist.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/suspend`
+     */
+    suspendOrganization(orgId, options) {
+        return this.post(`/organizations/${orgId}/suspend`, undefined, options);
+    }
+    /**
+     * Reactivate a suspended organization, restoring API key access.
+     *
+     * **Auth:** Requires `adminKey` in client config.
+     *
+     * @param orgId - Organization identifier.
+     * @param options - Optional per-request overrides.
+     * @returns Updated organization status.
+     * @throws {@link HivemindError} 401 if admin credentials are invalid.
+     * @throws {@link HivemindError} 404 if the organization does not exist.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/reactivate`
+     */
+    reactivateOrganization(orgId, options) {
+        return this.post(`/organizations/${orgId}/reactivate`, undefined, options);
+    }
+    /**
+     * Permanently delete an organization and all associated data.
+     * This action is irreversible.
+     *
+     * **Auth:** Requires `adminKey` in client config.
+     *
+     * @param orgId - Organization identifier.
+     * @param options - Optional per-request overrides.
+     * @throws {@link HivemindError} 401 if admin credentials are invalid.
+     * @throws {@link HivemindError} 404 if the organization does not exist.
+     *
+     * **Endpoint:** `DELETE /v1/organizations/{orgId}`
+     */
+    deleteOrganization(orgId, options) {
+        return this.del(`/organizations/${orgId}`, options);
+    }
+    // -----------------------------------------------------------------------
+    // Documents
+    // -----------------------------------------------------------------------
+    /**
+     * Upload and ingest a document file (PDF, TXT, DOCX, etc.).
+     * The document is stored in GCS, split into chunks, and embedded for RAG retrieval.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param file - Document content as a `Blob` or `Buffer`.
+     * @param filename - Original filename (e.g. `"report.pdf"`).
+     * @param options - Optional per-request overrides (e.g. `{ apiKey }`).
+     * @returns Upload result with document ID, chunk count, and status.
+     * @throws {@link HivemindError} 400 if the file exceeds the maximum upload size (default 25 MB).
+     * @throws {@link HivemindError} 401 if API key is missing or invalid.
+     * @throws {@link HivemindError} 429 if rate limit is exceeded.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/documents/upload`
+     * **Content-Type:** `multipart/form-data`
+     *
+     * @example
+     * ```typescript
+     * import { readFileSync } from "fs";
+     * const file = readFileSync("./report.pdf");
+     * const result = await client.uploadDocument("acme-corp", file, "report.pdf");
+     * console.log(`Uploaded: ${result.document_id}, ${result.chunks} chunks`);
+     * ```
+     */
+    async uploadDocument(orgId, file, filename, options) {
+        const form = new FormData();
+        const blob = file instanceof Blob ? file : new Blob([file], { type: "application/octet-stream" });
+        form.append("file", blob, filename);
+        return this.request("POST", `/organizations/${orgId}/documents/upload`, { formData: form, apiKey: options?.apiKey });
+    }
+    // -----------------------------------------------------------------------
+    // Query (RAG)
+    // -----------------------------------------------------------------------
+    /**
+     * Query the organization's document knowledge base using RAG
+     * (Retrieval-Augmented Generation). Retrieves relevant document chunks,
+     * then generates a response with citations.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param params - Query parameters (query text, model, temperature, strategy).
+     * @param options - Optional per-request overrides (e.g. `{ apiKey }`).
+     * @returns Generated answer with source citations, confidence, and processing time.
+     * @throws {@link HivemindError} 401 if API key is missing or invalid.
+     * @throws {@link HivemindError} 403 if cross-organization access is attempted.
+     * @throws {@link HivemindError} 429 if rate limit or token quota is exceeded.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/query`
+     *
+     * @example
+     * ```typescript
+     * const result = await client.query("acme-corp", {
+     *   query: "What are the key findings in Q4?",
+     *   temperature: 0.2,
+     *   retrieval_strategy: "hybrid",
+     * });
+     * console.log(result.answer);
+     * console.log(result.sources); // citations with doc_id, chunk_id, score, snippet
+     * ```
+     */
+    query(orgId, params, options) {
+        return this.post(`/organizations/${orgId}/query`, params, options);
+    }
+    // -----------------------------------------------------------------------
+    // Generation
+    // -----------------------------------------------------------------------
+    /**
+     * Start an asynchronous video generation job using Vertex AI Veo.
+     * Returns a job ID — poll with `getJob()` or `waitForJob()` for results.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param params - Video generation parameters (prompt, duration, aspect_ratio, style).
+     * @param options - Optional per-request overrides.
+     * @returns Job ID and estimated processing time (HTTP 202).
+     * @throws {@link HivemindError} 429 if rate limit, video quota, or concurrent job limit is exceeded.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/generate/video`
+     *
+     * @example
+     * ```typescript
+     * const job = await client.generateVideo("acme-corp", {
+     *   prompt: "A drone flyover of a mountain lake at sunset",
+     *   duration: 8,
+     *   aspect_ratio: "16:9",
+     *   style: "cinematic",
+     * });
+     * const result = await client.waitForJob("acme-corp", job.job_id);
+     * console.log(result.result); // { output_url, signed_url }
+     * ```
+     */
+    generateVideo(orgId, params, options) {
+        return this.post(`/organizations/${orgId}/generate/video`, params, options);
+    }
+    /**
+     * Start an asynchronous image generation job using Vertex AI Imagen.
+     * Returns a job ID — poll with `getJob()` or `waitForJob()` for results.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param params - Image generation parameters (prompt, aspect_ratio, style, num_images).
+     * @param options - Optional per-request overrides.
+     * @returns Job ID and estimated processing time (HTTP 202).
+     * @throws {@link HivemindError} 429 if rate limit, image quota, or concurrent job limit is exceeded.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/generate/image`
+     *
+     * @example
+     * ```typescript
+     * const job = await client.generateImage("acme-corp", {
+     *   prompt: "A futuristic city skyline at dusk",
+     *   aspect_ratio: "16:9",
+     *   style: "digital art",
+     *   num_images: 4,
+     * });
+     * const result = await client.waitForJob("acme-corp", job.job_id);
+     * ```
+     */
+    generateImage(orgId, params, options) {
+        return this.post(`/organizations/${orgId}/generate/image`, params, options);
+    }
+    // -----------------------------------------------------------------------
+    // Jobs
+    // -----------------------------------------------------------------------
+    /**
+     * Check the status of an asynchronous job (video or image generation).
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param jobId - Job identifier (from `generateVideo()` or `generateImage()`).
+     * @param options - Optional per-request overrides.
+     * @returns Job status, result URLs (when completed), or error details (when failed).
+     * @throws {@link HivemindError} 404 if the job does not exist.
+     *
+     * **Endpoint:** `GET /v1/organizations/{orgId}/jobs/{jobId}`
+     */
+    getJob(orgId, jobId, options) {
+        return this.get(`/organizations/${orgId}/jobs/${jobId}`, undefined, options);
+    }
+    /**
+     * Poll a job until it reaches a terminal status (`completed`, `failed`, or `cancelled`).
+     *
+     * @param orgId - Organization identifier.
+     * @param jobId - Job identifier.
+     * @param intervalMs - Polling interval in milliseconds. @default 2000
+     * @param maxWaitMs - Maximum wait time in milliseconds. @default 300000 (5 min)
+     * @param options - Optional per-request overrides.
+     * @returns Final job status with result or error.
+     * @throws Error if the job does not complete within `maxWaitMs`.
+     *
+     * @example
+     * ```typescript
+     * const job = await client.generateVideo("acme-corp", { prompt: "..." });
+     * const result = await client.waitForJob("acme-corp", job.job_id, 3000, 600_000);
+     * if (result.status === "completed") console.log(result.result);
+     * ```
+     */
+    async waitForJob(orgId, jobId, intervalMs = 2000, maxWaitMs = 300_000, options) {
+        const start = Date.now();
+        while (Date.now() - start < maxWaitMs) {
+            const job = await this.getJob(orgId, jobId, options);
+            if (["completed", "failed", "cancelled"].includes(job.status)) {
+                return job;
+            }
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+        throw new Error(`Job ${jobId} did not complete within ${maxWaitMs}ms`);
+    }
+    // -----------------------------------------------------------------------
+    // Data chat
+    // -----------------------------------------------------------------------
+    /**
+     * Ask a natural-language question over BigQuery datasets.
+     * Gemini generates SQL from the question, executes it, and returns formatted results.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param params - Question and optional user ID.
+     * @param options - Optional per-request overrides.
+     * @returns Generated SQL, natural-language answer, and result rows.
+     * @throws {@link HivemindError} 429 if rate limit or token quota is exceeded.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/data-chat`
+     *
+     * @example
+     * ```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 this month."
+     * console.log(result.sql);    // Generated SQL
+     * console.log(result.rows);   // [{ active_users: 1247 }]
+     * ```
+     */
+    dataChat(orgId, params, options) {
+        return this.post(`/organizations/${orgId}/data-chat`, params, options);
+    }
+    // -----------------------------------------------------------------------
+    // Agents
+    // -----------------------------------------------------------------------
+    /**
+     * Create a custom AI agent template with system instructions and optional tool bindings.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param params - Agent name, instructions, and optional tools.
+     * @param options - Optional per-request overrides.
+     * @returns Created agent with ID, name, and enabled tools.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/agents/custom`
+     *
+     * @example
+     * ```typescript
+     * const agent = await client.createAgent("acme-corp", {
+     *   name: "Support Bot",
+     *   instructions: "You are a helpful customer support agent.",
+     *   tools: ["rag_search", "ticket_create"],
+     * });
+     * console.log(agent.agent_id);
+     * ```
+     */
+    createAgent(orgId, params, options) {
+        return this.post(`/organizations/${orgId}/agents/custom`, params, options);
+    }
+    /**
+     * Send a query to an AI agent. Routes to the specified agent type or auto-selects.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param params - Query text, user ID, and optional agent type.
+     * @param options - Optional per-request overrides.
+     * @returns Agent response text, agent type, and any tool calls made.
+     * @throws {@link HivemindError} 429 if rate limit or token quota is exceeded.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/agents/query`
+     */
+    queryAgent(orgId, params, options) {
+        return this.post(`/organizations/${orgId}/agents/query`, params, options);
+    }
+    // -----------------------------------------------------------------------
+    // Audio
+    // -----------------------------------------------------------------------
+    /**
+     * Transcribe audio content to text (speech-to-text).
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param params - Audio content and optional BCP-47 language code.
+     * @param options - Optional per-request overrides.
+     * @returns Transcription result with transcript text, confidence, and language.
+     * @throws {@link HivemindError} 429 if rate limit is exceeded.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/audio/transcribe`
+     */
+    transcribeAudio(orgId, params, options) {
+        return this.post(`/organizations/${orgId}/audio/transcribe`, params, options);
+    }
+    /**
+     * Convert text to speech (text-to-speech synthesis).
+     * Returns a signed URL to the generated audio file.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param params - Text to synthesize and optional voice name.
+     * @param options - Optional per-request overrides.
+     * @returns Audio URL, duration, and voice used.
+     * @throws {@link HivemindError} 429 if rate limit is exceeded.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/audio/synthesize`
+     */
+    synthesizeAudio(orgId, params, options) {
+        return this.post(`/organizations/${orgId}/audio/synthesize`, params, options);
+    }
+    // -----------------------------------------------------------------------
+    // Analytics / ML
+    // -----------------------------------------------------------------------
+    /**
+     * Train a predictive model on tabular data.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param params - Target column, feature columns, and training data rows.
+     * @param options - Optional per-request overrides.
+     * @returns Deployed model ID and status.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/analytics/train`
+     *
+     * @example
+     * ```typescript
+     * const model = await client.trainModel("acme-corp", {
+     *   target_column: "churn",
+     *   feature_columns: ["tenure", "monthly_charges", "total_charges"],
+     *   rows: [
+     *     { tenure: 12, monthly_charges: 50, total_charges: 600, churn: 0 },
+     *     { tenure: 2, monthly_charges: 80, total_charges: 160, churn: 1 },
+     *   ],
+     * });
+     * console.log(model.model_id); // Use with predict()
+     * ```
+     */
+    trainModel(orgId, params, options) {
+        return this.post(`/organizations/${orgId}/analytics/train`, params, options);
+    }
+    /**
+     * Run predictions using a previously trained model.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param params - Model ID and data instances to predict on.
+     * @param options - Optional per-request overrides.
+     * @returns Predictions for each input instance.
+     * @throws {@link HivemindError} 404 if the model does not exist.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/analytics/predict`
+     */
+    predict(orgId, params, options) {
+        return this.post(`/organizations/${orgId}/analytics/predict`, params, options);
+    }
+    /**
+     * Generate a time-series forecast from historical data using ARIMA-based modeling.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param params - Historical series values and optional forecast horizon (1–365).
+     * @param options - Optional per-request overrides.
+     * @returns Predicted future values.
+     *
+     * **Endpoint:** `POST /v1/organizations/{orgId}/analytics/forecast`
+     */
+    forecast(orgId, params, options) {
+        return this.post(`/organizations/${orgId}/analytics/forecast`, params, options);
+    }
+    // -----------------------------------------------------------------------
+    // Billing
+    // -----------------------------------------------------------------------
+    /**
+     * Get the monthly usage summary for an organization.
+     * Includes token, image, video, storage, and compute usage against tier limits.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param month - Month in `YYYY-MM` format. Defaults to current month.
+     * @param options - Optional per-request overrides.
+     * @returns Usage counters, tier limits, and quota status.
+     *
+     * **Endpoint:** `GET /v1/organizations/{orgId}/usage?month={month}`
+     */
+    getUsage(orgId, month, options) {
+        const query = month ? { month } : undefined;
+        return this.get(`/organizations/${orgId}/usage`, query, options);
+    }
+    /**
+     * Get the monthly invoice with detailed cost breakdown by resource type.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param month - Month in `YYYY-MM` format. Defaults to current month.
+     * @param options - Optional per-request overrides.
+     * @returns Invoice with itemized costs and total in USD.
+     *
+     * **Endpoint:** `GET /v1/organizations/{orgId}/invoice?month={month}`
+     */
+    getInvoice(orgId, month, options) {
+        const query = month ? { month } : undefined;
+        return this.get(`/organizations/${orgId}/invoice`, query, options);
+    }
+    // -----------------------------------------------------------------------
+    // Audit
+    // -----------------------------------------------------------------------
+    /**
+     * Retrieve audit log records for an organization.
+     *
+     * **Auth:** Requires org-scoped API key.
+     *
+     * @param orgId - Organization identifier.
+     * @param options - Optional per-request overrides.
+     * @returns Audit log entries with timestamps, actions, and metadata.
+     *
+     * **Endpoint:** `GET /v1/organizations/{orgId}/audit`
+     */
+    getAuditLogs(orgId, options) {
+        return this.get(`/organizations/${orgId}/audit`, undefined, options);
+    }
+    // -----------------------------------------------------------------------
+    // Scraping
+    // -----------------------------------------------------------------------
+    /**
+     * Get the current scraping runtime configuration.
+     *
+     * **Auth:** None required.
+     *
+     * @returns Execution mode, Cloud Run status, and cache statistics.
+     *
+     * **Endpoint:** `GET /v1/scraping/config`
+     */
+    getScrapingConfig() {
+        return this.get("/scraping/config");
+    }
+    /**
+     * Submit URLs for scraping. JS-heavy sites (Reddit, Twitter, LinkedIn)
+     * are auto-routed to Selenium.
+     *
+     * **Auth:** None required.
+     *
+     * @param params - Object containing the `urls` array.
+     * @returns Task ID and submission status.
+     *
+     * **Endpoint:** `POST /v1/scraping/scrape`
+     */
+    scrape(params) {
+        return this.post("/scraping/scrape", params);
+    }
+    /**
+     * Check the status and results of a scrape task.
+     *
+     * **Auth:** None required.
+     *
+     * @param taskId - Task identifier (from `scrape()`).
+     * @returns Task status and scraped results (empty while pending).
+     *
+     * **Endpoint:** `GET /v1/scraping/status/{taskId}`
+     */
+    getScrapeStatus(taskId) {
+        return this.get(`/scraping/status/${taskId}`);
+    }
+    /**
+     * Submit a scrape job and poll until results are ready.
+     *
+     * @param urls - URLs to scrape.
+     * @param intervalMs - Polling interval in milliseconds. @default 2000
+     * @param maxWaitMs - Maximum wait time in milliseconds. @default 120000 (2 min)
+     * @returns Final scrape status with results.
+     * @throws Error if the task does not complete within `maxWaitMs`.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.scrapeAndWait(
+     *   ["https://example.com", "https://example.org"],
+     *   2000,
+     *   60_000,
+     * );
+     * for (const item of result.result) {
+     *   console.log(item.title, item.full_text?.substring(0, 200));
+     * }
+     * ```
+     */
+    async scrapeAndWait(urls, intervalMs = 2000, maxWaitMs = 120_000) {
+        const { task_id } = await this.scrape({ urls });
+        const start = Date.now();
+        while (Date.now() - start < maxWaitMs) {
+            const status = await this.getScrapeStatus(task_id);
+            if (["SUCCESS", "FAILURE", "completed"].includes(status.status)) {
+                return status;
+            }
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+        throw new Error(`Scrape ${task_id} did not complete within ${maxWaitMs}ms`);
+    }
+    // -----------------------------------------------------------------------
+    // Webhooks
+    // -----------------------------------------------------------------------
+    /**
+     * Send a video generation completion webhook notification.
+     *
+     * **Auth:** Requires `webhookSecret` in client config (sends `X-Webhook-Secret` header).
+     *
+     * @param payload - Webhook payload with job_id, org_id, status, and optional metadata.
+     * @returns `{ received: true }` on success.
+     * @throws {@link HivemindError} 401 if the webhook secret is invalid.
+     *
+     * **Endpoint:** `POST /v1/webhook/video-complete`
+     */
+    sendVideoCompleteWebhook(payload) {
+        return this.post("/webhook/video-complete", payload);
+    }
+    /**
+     * Send a document processing completion webhook notification.
+     *
+     * **Auth:** Requires `webhookSecret` in client config (sends `X-Webhook-Secret` header).
+     *
+     * @param payload - Webhook payload with document_id, org_id, status, and optional metadata.
+     * @returns `{ received: true }` on success.
+     * @throws {@link HivemindError} 401 if the webhook secret is invalid.
+     *
+     * **Endpoint:** `POST /v1/webhook/document-processed`
+     */
+    sendDocumentProcessedWebhook(payload) {
+        return this.post("/webhook/document-processed", payload);
+    }
+}
+exports.HivemindClient = HivemindClient;
+//# sourceMappingURL=client.js.map