@happyrobot-ai/sdk 0.1.2 → 0.1.4

package/README.md

@@ -113,15 +113,16 @@ const { workflow } = await createFromTemplate(client, {
 | `client.knowledgeBases` | `KnowledgeBasesResource` | Knowledge base document management |
 | `client.workflowFolders` | `WorkflowFoldersResource` | Workflow folder organization |
 | `client.mcp` | `MCPResource` | MCP server management |
-| `client.usage` | `UsageResource` | Usage metrics (call minutes, tokens, etc.) |
 | `client.billing` | `BillingResource` | Billing usage details and totals |
 | `client.apiKey` | `ApiKeyResource` | API key introspection |
+| `client.artifacts` | `ArtifactsResource` | Resolve fresh artifact URLs |
 | `client.adversarialSuites` | `AdversarialSuitesResource` | Adversarial suite management and execution |
 | `client.adversarialTests` | `AdversarialTestsResource` | Adversarial test management and execution |
 | `client.northstars` | `NorthstarsResource` | Northstar quality criteria management |
 | `client.customEvals` | `CustomEvalsResource` | Custom eval management and execution |
 | `client.issues` | `IssuesResource` | Quality issue (flag) status management |
 | `client.auditRemarks` | `AuditRemarksResource` | Audit remark feedback management |
+| `client.chat` | `ChatResource` | Chat session management, messaging, and file uploads |
 
 ---
 
@@ -301,6 +302,20 @@ await client.messages.createFlag("message-id", { type: "incorrect", note: "..."
 
 ---
 
+## `client.artifacts`
+
+```ts
+const resolved = await client.artifacts.resolve({
+  s3_keys: ["artifacts/<media_id>/extracted_text.txt"],
+});
+```
+
+| Method | HTTP | Path | Description |
+|---|---|---|---|
+| `resolve(body)` | POST | `/artifacts/resolve` | Resolve fresh presigned URLs for artifacts |
+
+---
+
 ## `client.variables`
 
 Variables are scoped to a workflow.
@@ -507,28 +522,6 @@ await client.mcp.refresh("mcp-id");
 
 ---
 
-## `client.usage`
-
-All methods accept a `UsageQuery` with `workflow_id`, `start_date`, and `end_date`.
-
-```ts
-const data = await client.usage.callMinutes({ workflow_id: "wf-id", start_date: "2024-01-01", end_date: "2024-01-31" });
-await client.usage.llmTokens({ ... });
-await client.usage.textCount({ ... });
-await client.usage.ocrCount({ ... });
-await client.usage.rpaMinutes({ ... });
-```
-
-| Method | HTTP | Path | Description |
-|---|---|---|---|
-| `callMinutes(query)` | GET | `/usage/call-minutes` | Voice call minutes consumed |
-| `llmTokens(query)` | GET | `/usage/llm-tokens` | LLM tokens consumed |
-| `textCount(query)` | GET | `/usage/text-count` | Text messages sent |
-| `ocrCount(query)` | GET | `/usage/ocr-count` | OCR operations performed |
-| `rpaMinutes(query)` | GET | `/usage/rpa-minutes` | RPA automation minutes consumed |
-
----
-
 ## `client.billing`
 
 ```ts
@@ -729,6 +722,154 @@ await client.auditRemarks.deleteFeedback("audit-remark-id");
 
 ---
 
+## Chat (`client.chat` + `HappyRobotChatClient`)
+
+Build custom chat UIs powered by your workflows. Uses a two-tier auth model:
+
+1. **Your server** creates a scoped client token using the API key (keeps it secret)
+2. **Your browser** uses `HappyRobotChatClient` with that token for all chat operations
+
+### Server-side: Create a client token
+
+```ts
+// --- YOUR SERVER (e.g. Next.js API route, Express handler) ---
+import { HappyRobotClient } from "@happyrobot-ai/sdk";
+
+const client = new HappyRobotClient({ apiKey: process.env.HAPPYROBOT_API_KEY });
+
+app.post("/api/chat-token", async (req, res) => {
+  const { token, expires_at } = await client.chat.createToken({
+    workflow_id: "your-workflow-id",
+  });
+  res.json({ token, expires_at });
+});
+```
+
+### Browser-side: `HappyRobotChatClient`
+
+```ts
+// --- YOUR BROWSER CODE (React, Vue, vanilla JS, etc.) ---
+import { HappyRobotChatClient } from "@happyrobot-ai/sdk";
+
+// 1. Get a client token from your server
+const { token } = await fetch("/api/chat-token", { method: "POST" }).then(r => r.json());
+
+// 2. Initialize the browser-side client
+const chat = new HappyRobotChatClient({ token });
+
+// 3. Create a session
+const { session_id } = await chat.createSession();
+
+// 4. Connect bidirectional WebSocket
+const connection = chat.connect(session_id, {
+  onResponseStart: () => {
+    // Show typing indicator
+  },
+  onResponseChunk: (content) => {
+    // Append streamed text to the UI
+  },
+  onResponseEnd: (content) => {
+    // Full response complete — hide typing indicator
+  },
+  onSessionClosed: (event) => {
+    // Session ended: event.status, event.reason, event.duration
+  },
+  onTokenExpired: () => {
+    // Token expired — fetch a new token from your server and reconnect
+  },
+});
+
+// 5. Send messages through the WebSocket
+const ack = await connection.sendMessage({ content: "Hello!" });
+console.log(ack.message.id); // server-assigned message ID
+
+// 6. Send messages with file attachments
+const artifact = await chat.uploadFile(fileBlob, "photo.png", "image/png");
+await connection.sendMessage({ content: "Here's the photo", artifacts: [artifact] });
+
+// 7. Get history (page reload, reconnect)
+const { messages } = await chat.getHistory(session_id);
+
+// 8. Clean up
+connection.close();
+```
+
+### Browser-side: File uploads
+
+```ts
+// Option A: Use the convenience method (handles all 3 steps)
+const artifact = await chat.uploadFile(fileBlob, "photo.png", "image/png");
+await connection.sendMessage({
+  content: "Here's the photo",
+  artifacts: [artifact],
+});
+
+// Option B: Manual 3-step flow for more control
+const upload = await chat.getPresignedUpload({ filename: "photo.png", mime_type: "image/png" });
+await fetch(upload.upload_url, { method: "PUT", body: fileBlob, headers: { "Content-Type": "image/png" } });
+await chat.completeUpload({
+  artifact_id: upload.artifact_id,
+  s3_uri: upload.s3_uri,
+  filename: "photo.png",
+  mime_type: "image/png",
+  size_bytes: fileBlob.size,
+});
+await connection.sendMessage({
+  content: "Here's the photo",
+  artifacts: [{ media_id: upload.artifact_id, mime_type: "image/png", filename: "photo.png", size_bytes: fileBlob.size }],
+});
+```
+
+### `HappyRobotClient` (server-side)
+
+| Method | Description |
+|---|---|
+| `client.chat.createToken({ workflow_id, env? })` | Create a scoped client token (1 hour expiry) |
+
+### `HappyRobotChatClient` (browser-side)
+
+| Method | Description |
+|---|---|
+| `chat.createSession()` | Create a new chat session |
+| `chat.connect(sessionId, handlers)` | Open bidirectional WebSocket — returns `ChatConnection` |
+| `chat.sendMessage(sessionId, { content, artifacts? })` | Send a user message via HTTP (fallback if WS unavailable) |
+| `chat.getHistory(sessionId)` | Get message history |
+| `chat.uploadFile(file, filename, mimeType)` | Upload a file (convenience method) |
+| `chat.getPresignedUpload({ filename, mime_type })` | Get presigned S3 upload URL |
+| `chat.completeUpload({ artifact_id, s3_uri, ... })` | Register uploaded artifact |
+
+### `ChatConnection`
+
+| Method | Description |
+|---|---|
+| `connection.sendMessage({ content, artifacts? })` | Send a message via WebSocket. Returns a `Promise` that resolves with the server ack |
+| `connection.close()` | Close the WebSocket connection |
+| `connection.ws` | The underlying `WebSocket` instance |
+
+### WebSocket Events
+
+**Server → Client:**
+
+| Event | Fields | Description |
+|---|---|---|
+| `connected` | `session_id` | Connection established |
+| `response-start` | `content` | AI started generating a response |
+| `response-chunk` | `content` | Partial response text |
+| `response-end` | `content` | Complete response text |
+| `session-closed` | `session_id`, `status`, `reason`, `duration`, `timestamp` | Session ended |
+| `token-expired` | — | JWT expired — reconnect with a fresh token |
+| `message-ack` | `id`, `message` | Server confirmed the message was sent |
+| `message-error` | `id`, `error` | Server failed to send the message |
+| `heartbeat` | — | Keep-alive (every 15s) |
+
+**Client → Server:**
+
+| Event | Fields | Description |
+|---|---|---|
+| `message` | `content`, `artifacts?`, `id?` | Send a user message. `id` is echoed back in ack/error |
+
+---
+
 ## Pagination
 
 List methods that are paginated return a `PaginatedResponse<T>`:

package/chat-client.d.ts

@@ -0,0 +1,106 @@
+/**
+ * HappyRobotChatClient — lightweight browser-side client for chat sessions.
+ *
+ * Initialized with a scoped client token (created server-side via
+ * `client.chat.createToken()`). Does NOT require an API key.
+ *
+ * @example
+ * ```ts
+ * import { HappyRobotChatClient } from "@happyrobot-ai/sdk";
+ *
+ * // Token comes from your server
+ * const chat = new HappyRobotChatClient({ token });
+ *
+ * const { session_id } = await chat.createSession();
+ *
+ * chat.connect(session_id, {
+ *   onResponseStart: () => { },
+ *   onResponseChunk: (content) => { },
+ *   onResponseEnd: (content) => { },
+ *   onSessionClosed: (event) => { },
+ * });
+ *
+ * await chat.sendMessage(session_id, { content: "Hello!" });
+ * ```
+ */
+import type { ChatClientConfig, CreateChatSessionResponse, SendChatMessageBody, SendChatMessageResponse, ChatHistoryResponse, PresignedUploadQuery, PresignedUploadResponse, CompleteUploadBody, CompleteUploadResponse, ChatWsSessionClosedEvent, ChatWsMessageAckEvent } from "./types/chat.types";
+export interface ChatConnectionHandlers {
+    /** AI started generating a response. */
+    onResponseStart?: () => void;
+    /** Partial response text chunk. */
+    onResponseChunk?: (content: string) => void;
+    /** Complete response text. */
+    onResponseEnd?: (content: string) => void;
+    /** Session was closed by the server. */
+    onSessionClosed?: (event: ChatWsSessionClosedEvent) => void;
+    /** Connection established. */
+    onConnected?: (sessionId: string) => void;
+    /** Token expired — reconnect with a fresh token to continue. */
+    onTokenExpired?: () => void;
+    /** WebSocket error. */
+    onError?: (error: Event) => void;
+    /** WebSocket closed. */
+    onClose?: (event: {
+        code: number;
+        reason: string;
+    }) => void;
+}
+export interface ChatConnection {
+    /** Close the WebSocket connection only (no server-side cleanup). */
+    close(): void;
+    /**
+     * End the session on the server (stops the AI agent) and close the WebSocket.
+     * Use this when the user is done with the conversation.
+     */
+    endSession(): Promise<void>;
+    /** Send a message through the WebSocket. Returns the ack from the server. */
+    sendMessage(body: SendChatMessageBody): Promise<ChatWsMessageAckEvent>;
+    /** The underlying WebSocket instance. */
+    readonly ws: WebSocket;
+}
+export declare class HappyRobotChatClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly fetchFn;
+    constructor(config: ChatClientConfig);
+    /** Create a new chat session. */
+    createSession(): Promise<CreateChatSessionResponse>;
+    /** Send a user message to a chat session. */
+    sendMessage(sessionId: string, body: SendChatMessageBody): Promise<SendChatMessageResponse>;
+    /** Get message history for a chat session. */
+    getHistory(sessionId: string): Promise<ChatHistoryResponse>;
+    /**
+     * Get a presigned S3 URL for file upload.
+     *
+     * Upload flow:
+     * 1. `getPresignedUpload()` — get the upload URL
+     * 2. `PUT` the file directly to `upload_url`
+     * 3. `completeUpload()` — register the artifact
+     * 4. Include the artifact in `sendMessage()` via the `artifacts` array
+     */
+    getPresignedUpload(query: PresignedUploadQuery): Promise<PresignedUploadResponse>;
+    /** Register an uploaded artifact after direct S3 upload. */
+    completeUpload(body: CompleteUploadBody): Promise<CompleteUploadResponse>;
+    /**
+     * Upload a file and return the artifact metadata ready for `sendMessage()`.
+     *
+     * Convenience method that combines `getPresignedUpload()`, S3 upload, and
+     * `completeUpload()` into a single call.
+     */
+    uploadFile(file: Blob, filename: string, mimeType: string): Promise<{
+        media_id: string;
+        mime_type: string;
+        filename: string;
+        size_bytes: number;
+    }>;
+    /**
+     * Connect a bidirectional WebSocket for sending messages and receiving
+     * real-time AI response streaming.
+     *
+     * Returns a `ChatConnection` with `sendMessage()` and `close()` methods.
+     * Pass event handlers to react to streaming chunks, completed responses,
+     * and session lifecycle events.
+     */
+    connect(sessionId: string, handlers?: ChatConnectionHandlers): ChatConnection;
+    private request;
+}

package/chat-client.js

@@ -0,0 +1,251 @@
+"use strict";
+/**
+ * HappyRobotChatClient — lightweight browser-side client for chat sessions.
+ *
+ * Initialized with a scoped client token (created server-side via
+ * `client.chat.createToken()`). Does NOT require an API key.
+ *
+ * @example
+ * ```ts
+ * import { HappyRobotChatClient } from "@happyrobot-ai/sdk";
+ *
+ * // Token comes from your server
+ * const chat = new HappyRobotChatClient({ token });
+ *
+ * const { session_id } = await chat.createSession();
+ *
+ * chat.connect(session_id, {
+ *   onResponseStart: () => { },
+ *   onResponseChunk: (content) => { },
+ *   onResponseEnd: (content) => { },
+ *   onSessionClosed: (event) => { },
+ * });
+ *
+ * await chat.sendMessage(session_id, { content: "Hello!" });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HappyRobotChatClient = void 0;
+const DEFAULT_BASE_URL = "https://platform.happyrobot.ai/api/v2";
+class HappyRobotChatClient {
+    token;
+    baseUrl;
+    fetchFn;
+    constructor(config) {
+        if (!config.token) {
+            throw new Error("token is required");
+        }
+        this.token = config.token;
+        const customBaseUrl = config.baseUrl;
+        const isTesting = typeof process !== "undefined" && process.env?.HR_TESTING === "true";
+        if (customBaseUrl && !isTesting) {
+            throw new Error("baseUrl can not be overridden");
+        }
+        this.baseUrl = (customBaseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** Create a new chat session. */
+    async createSession() {
+        return this.request("POST", "/chat/sessions");
+    }
+    /** Send a user message to a chat session. */
+    async sendMessage(sessionId, body) {
+        return this.request("POST", `/chat/sessions/${enc(sessionId)}/messages`, body);
+    }
+    /** Get message history for a chat session. */
+    async getHistory(sessionId) {
+        return this.request("GET", `/chat/sessions/${enc(sessionId)}/history`);
+    }
+    /**
+     * Get a presigned S3 URL for file upload.
+     *
+     * Upload flow:
+     * 1. `getPresignedUpload()` — get the upload URL
+     * 2. `PUT` the file directly to `upload_url`
+     * 3. `completeUpload()` — register the artifact
+     * 4. Include the artifact in `sendMessage()` via the `artifacts` array
+     */
+    async getPresignedUpload(query) {
+        const params = new URLSearchParams({
+            filename: query.filename,
+            mime_type: query.mime_type,
+        });
+        return this.request("GET", `/chat/upload/presigned?${params.toString()}`);
+    }
+    /** Register an uploaded artifact after direct S3 upload. */
+    async completeUpload(body) {
+        return this.request("POST", "/chat/upload/complete", body);
+    }
+    /**
+     * Upload a file and return the artifact metadata ready for `sendMessage()`.
+     *
+     * Convenience method that combines `getPresignedUpload()`, S3 upload, and
+     * `completeUpload()` into a single call.
+     */
+    async uploadFile(file, filename, mimeType) {
+        const upload = await this.getPresignedUpload({
+            filename,
+            mime_type: mimeType,
+        });
+        await this.fetchFn(upload.upload_url, {
+            method: "PUT",
+            body: file,
+            headers: { "Content-Type": mimeType },
+        });
+        const completed = await this.completeUpload({
+            artifact_id: upload.artifact_id,
+            s3_uri: upload.s3_uri,
+            filename,
+            mime_type: mimeType,
+            size_bytes: file.size,
+        });
+        return {
+            media_id: completed.artifact_id,
+            mime_type: mimeType,
+            filename,
+            size_bytes: file.size,
+        };
+    }
+    /**
+     * Connect a bidirectional WebSocket for sending messages and receiving
+     * real-time AI response streaming.
+     *
+     * Returns a `ChatConnection` with `sendMessage()` and `close()` methods.
+     * Pass event handlers to react to streaming chunks, completed responses,
+     * and session lifecycle events.
+     */
+    connect(sessionId, handlers = {}) {
+        const wsBase = this.baseUrl
+            .replace(/^http:/, "ws:")
+            .replace(/^https:/, "wss:");
+        const url = `${wsBase}/chat/sessions/${enc(sessionId)}/ws?token=${enc(this.token)}`;
+        const ws = new WebSocket(url);
+        // Pending message-ack/message-error callbacks keyed by client-generated id.
+        const pending = new Map();
+        ws.onmessage = (event) => {
+            try {
+                const data = JSON.parse(event.data);
+                switch (data.type) {
+                    case "connected":
+                        handlers.onConnected?.(data.session_id);
+                        break;
+                    case "response-start":
+                        handlers.onResponseStart?.();
+                        break;
+                    case "response-chunk":
+                        handlers.onResponseChunk?.(data.content);
+                        break;
+                    case "response-end":
+                        handlers.onResponseEnd?.(data.content);
+                        break;
+                    case "session-closed":
+                        handlers.onSessionClosed?.(data);
+                        break;
+                    case "token-expired":
+                        handlers.onTokenExpired?.();
+                        break;
+                    case "message-ack": {
+                        const id = data.id;
+                        if (id && pending.has(id)) {
+                            pending.get(id).resolve(data);
+                            pending.delete(id);
+                        }
+                        break;
+                    }
+                    case "message-error": {
+                        const id = data.id;
+                        if (id && pending.has(id)) {
+                            pending.get(id).reject(new Error(data.error));
+                            pending.delete(id);
+                        }
+                        break;
+                    }
+                    case "heartbeat":
+                        break;
+                }
+            }
+            catch {
+                // Ignore malformed messages
+            }
+        };
+        ws.onerror = (event) => {
+            handlers.onError?.(event);
+        };
+        ws.onclose = (event) => {
+            // Reject all pending messages on close
+            for (const [, { reject }] of pending) {
+                reject(new Error("WebSocket closed"));
+            }
+            pending.clear();
+            handlers.onClose?.(event);
+        };
+        const sendMessage = (body) => {
+            return new Promise((resolve, reject) => {
+                if (ws.readyState !== WebSocket.OPEN) {
+                    reject(new Error("WebSocket is not open"));
+                    return;
+                }
+                const id = crypto.randomUUID();
+                pending.set(id, { resolve, reject });
+                ws.send(JSON.stringify({
+                    type: "message",
+                    id,
+                    content: body.content,
+                    ...(body.artifacts && body.artifacts.length > 0
+                        ? { artifacts: body.artifacts }
+                        : {}),
+                }));
+            });
+        };
+        const endSession = async () => {
+            await this.request("POST", `/chat/sessions/${enc(sessionId)}/close`);
+            ws.close();
+        };
+        return {
+            close: () => ws.close(),
+            endSession,
+            sendMessage,
+            get ws() {
+                return ws;
+            },
+        };
+    }
+    // ── Internal ──
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            Accept: "application/json",
+        };
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        const response = await this.fetchFn(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            const errorBody = await response.text().catch(() => "");
+            let parsed = {};
+            try {
+                parsed = JSON.parse(errorBody);
+            }
+            catch {
+                // ignore
+            }
+            throw new Error(parsed.error ||
+                parsed.message ||
+                `Request failed with status ${response.status}`);
+        }
+        const text = await response.text();
+        if (!text)
+            return undefined;
+        return JSON.parse(text);
+    }
+}
+exports.HappyRobotChatClient = HappyRobotChatClient;
+function enc(s) {
+    return encodeURIComponent(s);
+}
+//# sourceMappingURL=chat-client.js.map

package/chat-client.mjs

@@ -0,0 +1,3 @@
+// ESM wrapper — re-exports CJS module
+export { default } from "./chat-client.js";
+export * from "./chat-client.js";

package/client.d.ts

@@ -24,7 +24,6 @@ import { ContactsResource } from "./resources/contacts";
 import { KnowledgeBasesResource } from "./resources/knowledge-bases";
 import { WorkflowFoldersResource } from "./resources/workflow-folders";
 import { MCPResource } from "./resources/mcp";
-import { UsageResource } from "./resources/usage";
 import { BillingResource } from "./resources/billing";
 import { ApiKeyResource } from "./resources/api-key";
 import { AdversarialSuitesResource } from "./resources/adversarial-suites";
@@ -33,6 +32,8 @@ import { NorthstarsResource } from "./resources/northstars";
 import { CustomEvalsResource } from "./resources/custom-evals";
 import { IssuesResource } from "./resources/issues";
 import { AuditRemarksResource } from "./resources/audit-remarks";
+import { ChatResource } from "./resources/chat";
+import { ArtifactsResource } from "./resources/artifacts";
 export declare class HappyRobotClient {
     private readonly http;
     /** Workflow CRUD, publishing, runs, and templates. */
@@ -63,8 +64,6 @@ export declare class HappyRobotClient {
     readonly workflowFolders: WorkflowFoldersResource;
     /** MCP server management. */
     readonly mcp: MCPResource;
-    /** Usage metrics (call minutes, tokens, etc.). */
-    readonly usage: UsageResource;
     /** Billing usage details and totals. */
     readonly billing: BillingResource;
     /** API key introspection. */
@@ -81,5 +80,9 @@ export declare class HappyRobotClient {
     readonly issues: IssuesResource;
     /** Audit remark feedback management. */
     readonly auditRemarks: AuditRemarksResource;
+    /** Chat session management and messaging. */
+    readonly chat: ChatResource;
+    /** Artifact URL resolution. */
+    readonly artifacts: ArtifactsResource;
     constructor(config: ClientConfig);
 }

package/client.js

@@ -27,7 +27,6 @@ const contacts_1 = require("./resources/contacts");
 const knowledge_bases_1 = require("./resources/knowledge-bases");
 const workflow_folders_1 = require("./resources/workflow-folders");
 const mcp_1 = require("./resources/mcp");
-const usage_1 = require("./resources/usage");
 const billing_1 = require("./resources/billing");
 const api_key_1 = require("./resources/api-key");
 const adversarial_suites_1 = require("./resources/adversarial-suites");
@@ -36,6 +35,8 @@ const northstars_1 = require("./resources/northstars");
 const custom_evals_1 = require("./resources/custom-evals");
 const issues_1 = require("./resources/issues");
 const audit_remarks_1 = require("./resources/audit-remarks");
+const chat_1 = require("./resources/chat");
+const artifacts_1 = require("./resources/artifacts");
 class HappyRobotClient {
     http;
     /** Workflow CRUD, publishing, runs, and templates. */
@@ -66,8 +67,6 @@ class HappyRobotClient {
     workflowFolders;
     /** MCP server management. */
     mcp;
-    /** Usage metrics (call minutes, tokens, etc.). */
-    usage;
     /** Billing usage details and totals. */
     billing;
     /** API key introspection. */
@@ -84,6 +83,10 @@ class HappyRobotClient {
     issues;
     /** Audit remark feedback management. */
     auditRemarks;
+    /** Chat session management and messaging. */
+    chat;
+    /** Artifact URL resolution. */
+    artifacts;
     constructor(config) {
         this.http = new http_1.HttpClient(config);
         this.workflows = new workflows_1.WorkflowsResource(this.http);
@@ -100,7 +103,6 @@ class HappyRobotClient {
         this.knowledgeBases = new knowledge_bases_1.KnowledgeBasesResource(this.http);
         this.workflowFolders = new workflow_folders_1.WorkflowFoldersResource(this.http);
         this.mcp = new mcp_1.MCPResource(this.http);
-        this.usage = new usage_1.UsageResource(this.http);
         this.billing = new billing_1.BillingResource(this.http);
         this.apiKey = new api_key_1.ApiKeyResource(this.http);
         this.adversarialSuites = new adversarial_suites_1.AdversarialSuitesResource(this.http);
@@ -109,6 +111,8 @@ class HappyRobotClient {
         this.customEvals = new custom_evals_1.CustomEvalsResource(this.http);
         this.issues = new issues_1.IssuesResource(this.http);
         this.auditRemarks = new audit_remarks_1.AuditRemarksResource(this.http);
+        this.chat = new chat_1.ChatResource(this.http);
+        this.artifacts = new artifacts_1.ArtifactsResource(this.http);
     }
 }
 exports.HappyRobotClient = HappyRobotClient;

package/core/http.js

@@ -22,8 +22,9 @@ class HttpClient {
         }
         this.apiKey = config.apiKey;
         const customBaseUrl = config.baseUrl;
-        if (customBaseUrl && !config.apiKey.startsWith("sk_test_")) {
-            throw new Error("baseUrl can only be overridden with a test API key (sk_test_...)");
+        const isTesting = typeof process !== "undefined" && process.env?.HR_TESTING === "true";
+        if (customBaseUrl && !isTesting) {
+            throw new Error("baseUrl can not be overridden");
         }
         this.baseUrl = (customBaseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
         this.timeout = config.timeout ?? DEFAULT_TIMEOUT;

package/index.d.ts

@@ -22,6 +22,8 @@
  * ```
  */
 export { HappyRobotClient } from "./client";
+export { HappyRobotChatClient } from "./chat-client";
+export type { ChatConnectionHandlers, ChatConnection } from "./chat-client";
 export type { ClientConfig, RequestConfig, PaginatedResponse, PaginationMetadata, PaginationQuery } from "./core/types";
 export { HappyRobotError, ApiError, AuthenticationError, NotFoundError, ValidationError, RateLimitError, TimeoutError, NetworkError, } from "./core/errors";
 export type { ApiErrorBody } from "./core/errors";
@@ -43,7 +45,6 @@ export { ContactsResource } from "./resources/contacts";
 export { KnowledgeBasesResource } from "./resources/knowledge-bases";
 export { WorkflowFoldersResource } from "./resources/workflow-folders";
 export { MCPResource } from "./resources/mcp";
-export { UsageResource } from "./resources/usage";
 export { BillingResource } from "./resources/billing";
 export { ApiKeyResource } from "./resources/api-key";
 export { AdversarialSuitesResource } from "./resources/adversarial-suites";
@@ -52,6 +53,8 @@ export { NorthstarsResource } from "./resources/northstars";
 export { CustomEvalsResource } from "./resources/custom-evals";
 export { IssuesResource } from "./resources/issues";
 export { AuditRemarksResource } from "./resources/audit-remarks";
+export { ChatResource } from "./resources/chat";
+export { ArtifactsResource } from "./resources/artifacts";
 export type * from "./types/workflows.types";
 export type * from "./types/versions.types";
 export type * from "./types/nodes.types";
@@ -62,7 +65,6 @@ export type * from "./types/sip-trunks.types";
 export type * from "./types/integrations.types";
 export type * from "./types/contacts.types";
 export type * from "./types/knowledge-bases.types";
-export type * from "./types/usage.types";
 export type * from "./types/variables.types";
 export type * from "./types/messages.types";
 export type * from "./types/mcp.types";
@@ -73,3 +75,5 @@ export type * from "./types/northstars.types";
 export type * from "./types/custom-evals.types";
 export type * from "./types/issues.types";
 export type * from "./types/audit-remarks.types";
+export type * from "./types/chat.types";
+export type * from "./types/artifacts.types";

package/index.js

@@ -23,10 +23,12 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AuditRemarksResource = exports.IssuesResource = exports.CustomEvalsResource = exports.NorthstarsResource = exports.AdversarialTestsResource = exports.AdversarialSuitesResource = exports.ApiKeyResource = exports.BillingResource = exports.UsageResource = exports.MCPResource = exports.WorkflowFoldersResource = exports.KnowledgeBasesResource = exports.ContactsResource = exports.IntegrationsResource = exports.SipTrunksResource = exports.PhoneNumbersResource = exports.VariablesResource = exports.MessagesResource = exports.SessionsResource = exports.RunsResource = exports.NodesResource = exports.VersionsResource = exports.WorkflowsResource = exports.iterateSSE = exports.paginate = exports.NetworkError = exports.TimeoutError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.ApiError = exports.HappyRobotError = exports.HappyRobotClient = void 0;
-// ── Client ──
+exports.ArtifactsResource = exports.ChatResource = exports.AuditRemarksResource = exports.IssuesResource = exports.CustomEvalsResource = exports.NorthstarsResource = exports.AdversarialTestsResource = exports.AdversarialSuitesResource = exports.ApiKeyResource = exports.BillingResource = exports.MCPResource = exports.WorkflowFoldersResource = exports.KnowledgeBasesResource = exports.ContactsResource = exports.IntegrationsResource = exports.SipTrunksResource = exports.PhoneNumbersResource = exports.VariablesResource = exports.MessagesResource = exports.SessionsResource = exports.RunsResource = exports.NodesResource = exports.VersionsResource = exports.WorkflowsResource = exports.iterateSSE = exports.paginate = exports.NetworkError = exports.TimeoutError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.ApiError = exports.HappyRobotError = exports.HappyRobotChatClient = exports.HappyRobotClient = void 0;
+// ── Clients ──
 var client_1 = require("./client");
 Object.defineProperty(exports, "HappyRobotClient", { enumerable: true, get: function () { return client_1.HappyRobotClient; } });
+var chat_client_1 = require("./chat-client");
+Object.defineProperty(exports, "HappyRobotChatClient", { enumerable: true, get: function () { return chat_client_1.HappyRobotChatClient; } });
 var errors_1 = require("./core/errors");
 Object.defineProperty(exports, "HappyRobotError", { enumerable: true, get: function () { return errors_1.HappyRobotError; } });
 Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return errors_1.ApiError; } });
@@ -69,8 +71,6 @@ var workflow_folders_1 = require("./resources/workflow-folders");
 Object.defineProperty(exports, "WorkflowFoldersResource", { enumerable: true, get: function () { return workflow_folders_1.WorkflowFoldersResource; } });
 var mcp_1 = require("./resources/mcp");
 Object.defineProperty(exports, "MCPResource", { enumerable: true, get: function () { return mcp_1.MCPResource; } });
-var usage_1 = require("./resources/usage");
-Object.defineProperty(exports, "UsageResource", { enumerable: true, get: function () { return usage_1.UsageResource; } });
 var billing_1 = require("./resources/billing");
 Object.defineProperty(exports, "BillingResource", { enumerable: true, get: function () { return billing_1.BillingResource; } });
 var api_key_1 = require("./resources/api-key");
@@ -87,4 +87,8 @@ var issues_1 = require("./resources/issues");
 Object.defineProperty(exports, "IssuesResource", { enumerable: true, get: function () { return issues_1.IssuesResource; } });
 var audit_remarks_1 = require("./resources/audit-remarks");
 Object.defineProperty(exports, "AuditRemarksResource", { enumerable: true, get: function () { return audit_remarks_1.AuditRemarksResource; } });
+var chat_1 = require("./resources/chat");
+Object.defineProperty(exports, "ChatResource", { enumerable: true, get: function () { return chat_1.ChatResource; } });
+var artifacts_1 = require("./resources/artifacts");
+Object.defineProperty(exports, "ArtifactsResource", { enumerable: true, get: function () { return artifacts_1.ArtifactsResource; } });
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyrobot-ai/sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "TypeScript SDK for the HappyRobot Public API",
   "main": "./index.js",
   "module": "./index.mjs",
@@ -37,7 +37,8 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/happyrobot-ai/app-v2"
+    "url": "git+https://github.com/happyrobot-ai/app-v2.git",
+    "directory": "packages/public_api"
   },
   "dependencies": {}
 }

package/resources/artifacts.d.ts

@@ -0,0 +1,7 @@
+import type { HttpClient } from "../core/http";
+import type { ResolveArtifactsBody, ResolveArtifactsResponse } from "../types/artifacts.types";
+export declare class ArtifactsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    resolve(body: ResolveArtifactsBody): Promise<ResolveArtifactsResponse>;
+}

package/resources/artifacts.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArtifactsResource = void 0;
+class ArtifactsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async resolve(body) {
+        return this.http.request({
+            method: "POST",
+            path: "/artifacts/resolve",
+            body,
+        });
+    }
+}
+exports.ArtifactsResource = ArtifactsResource;
+//# sourceMappingURL=artifacts.js.map

package/resources/artifacts.mjs

@@ -0,0 +1,3 @@
+// ESM wrapper — re-exports CJS module
+export { default } from "./artifacts.js";
+export * from "./artifacts.js";

package/resources/chat.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Chat resource — client.chat.*
+ *
+ * Server-side only. Creates scoped client tokens that are passed to the
+ * browser-side `HappyRobotChatClient`.
+ *
+ * @example
+ * ```ts
+ * const client = new HappyRobotClient({ apiKey: "sk_live_..." });
+ * const { token } = await client.chat.createToken({ workflow_id: "..." });
+ * // Pass `token` to the browser → new HappyRobotChatClient({ token })
+ * ```
+ */
+import type { HttpClient } from "../core/http";
+import type { CreateChatTokenBody, CreateChatTokenResponse } from "../types/chat.types";
+export declare class ChatResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a scoped client token for browser-side chat operations.
+     *
+     * Call this from your server, then pass the returned `token` to the browser
+     * where it can be used to initialize `HappyRobotChatClient`.
+     */
+    createToken(body: CreateChatTokenBody): Promise<CreateChatTokenResponse>;
+}

package/resources/chat.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Chat resource — client.chat.*
+ *
+ * Server-side only. Creates scoped client tokens that are passed to the
+ * browser-side `HappyRobotChatClient`.
+ *
+ * @example
+ * ```ts
+ * const client = new HappyRobotClient({ apiKey: "sk_live_..." });
+ * const { token } = await client.chat.createToken({ workflow_id: "..." });
+ * // Pass `token` to the browser → new HappyRobotChatClient({ token })
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatResource = void 0;
+class ChatResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Create a scoped client token for browser-side chat operations.
+     *
+     * Call this from your server, then pass the returned `token` to the browser
+     * where it can be used to initialize `HappyRobotChatClient`.
+     */
+    async createToken(body) {
+        return this.http.request({
+            method: "POST",
+            path: "/chat/tokens",
+            body,
+        });
+    }
+}
+exports.ChatResource = ChatResource;
+//# sourceMappingURL=chat.js.map

package/resources/chat.mjs

@@ -0,0 +1,3 @@
+// ESM wrapper — re-exports CJS module
+export { default } from "./chat.js";
+export * from "./chat.js";

package/resources/usage.d.ts

@@ -1,27 +0,0 @@
-/**
- * Usage resource — client.usage.*
- *
- * Maps to:
- *   GET /usage/call-minutes
- *   GET /usage/llm-tokens
- *   GET /usage/text-count
- *   GET /usage/ocr-count
- *   GET /usage/rpa-minutes
- */
-import type { HttpClient } from "../core/http";
-import type { UsageQuery, DetailedUsageResponse } from "../types/usage.types";
-export declare class UsageResource {
-    private readonly http;
-    constructor(http: HttpClient);
-    /** Get call minutes usage. */
-    callMinutes(query: UsageQuery): Promise<DetailedUsageResponse>;
-    /** Get LLM token usage. */
-    llmTokens(query: UsageQuery): Promise<DetailedUsageResponse>;
-    /** Get text message count usage. */
-    textCount(query: UsageQuery): Promise<DetailedUsageResponse>;
-    /** Get OCR count usage. */
-    ocrCount(query: UsageQuery): Promise<DetailedUsageResponse>;
-    /** Get RPA minutes usage. */
-    rpaMinutes(query: UsageQuery): Promise<DetailedUsageResponse>;
-    private toQuery;
-}

package/resources/usage.js

@@ -1,70 +0,0 @@
-"use strict";
-/**
- * Usage resource — client.usage.*
- *
- * Maps to:
- *   GET /usage/call-minutes
- *   GET /usage/llm-tokens
- *   GET /usage/text-count
- *   GET /usage/ocr-count
- *   GET /usage/rpa-minutes
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.UsageResource = void 0;
-class UsageResource {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    /** Get call minutes usage. */
-    async callMinutes(query) {
-        return this.http.request({
-            method: "GET",
-            path: "/usage/call-minutes",
-            query: this.toQuery(query),
-        });
-    }
-    /** Get LLM token usage. */
-    async llmTokens(query) {
-        return this.http.request({
-            method: "GET",
-            path: "/usage/llm-tokens",
-            query: this.toQuery(query),
-        });
-    }
-    /** Get text message count usage. */
-    async textCount(query) {
-        return this.http.request({
-            method: "GET",
-            path: "/usage/text-count",
-            query: this.toQuery(query),
-        });
-    }
-    /** Get OCR count usage. */
-    async ocrCount(query) {
-        return this.http.request({
-            method: "GET",
-            path: "/usage/ocr-count",
-            query: this.toQuery(query),
-        });
-    }
-    /** Get RPA minutes usage. */
-    async rpaMinutes(query) {
-        return this.http.request({
-            method: "GET",
-            path: "/usage/rpa-minutes",
-            query: this.toQuery(query),
-        });
-    }
-    toQuery(query) {
-        const { workflow_id, start_date, end_date } = query;
-        const ids = Array.isArray(workflow_id) ? workflow_id : [workflow_id];
-        return {
-            workflow_id: ids.join(","),
-            start_date,
-            end_date,
-        };
-    }
-}
-exports.UsageResource = UsageResource;
-//# sourceMappingURL=usage.js.map

package/resources/usage.mjs

@@ -1,3 +0,0 @@
-// ESM wrapper — re-exports CJS module
-export { default } from "./usage.js";
-export * from "./usage.js";