@happyrobot-ai/sdk 0.1.0

package/core/sse.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * Lightweight SSE (Server-Sent Events) stream parser.
+ *
+ * Consumes a `Response` body and yields typed `SSEEvent` objects.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.iterateSSE = iterateSSE;
+/**
+ * Async generator that reads an SSE stream from a `Response` and yields
+ * parsed events. Comments and empty keep-alive lines are silently skipped.
+ *
+ * @param response - A fetch `Response` whose body is `text/event-stream`.
+ */
+async function* iterateSSE(response) {
+    const body = response.body;
+    if (!body)
+        return;
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let currentEvent = "message";
+    let currentData = "";
+    let currentId;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // SSE events are separated by blank lines (\n\n)
+            const parts = buffer.split("\n");
+            buffer = parts.pop(); // keep incomplete line in buffer
+            for (const line of parts) {
+                if (line === "") {
+                    // Blank line = end of event
+                    if (currentData) {
+                        try {
+                            yield {
+                                event: currentEvent,
+                                data: JSON.parse(currentData),
+                                ...(currentId !== undefined && { id: currentId }),
+                            };
+                        }
+                        catch {
+                            // Non-JSON data — yield as raw string
+                            yield {
+                                event: currentEvent,
+                                data: currentData,
+                                ...(currentId !== undefined && { id: currentId }),
+                            };
+                        }
+                    }
+                    // Reset for next event
+                    currentEvent = "message";
+                    currentData = "";
+                    currentId = undefined;
+                    continue;
+                }
+                // Skip comments
+                if (line.startsWith(":"))
+                    continue;
+                const colonIdx = line.indexOf(":");
+                if (colonIdx === -1)
+                    continue;
+                const field = line.slice(0, colonIdx);
+                // Strip optional leading space after colon per SSE spec
+                const val = line[colonIdx + 1] === " " ? line.slice(colonIdx + 2) : line.slice(colonIdx + 1);
+                switch (field) {
+                    case "event":
+                        currentEvent = val;
+                        break;
+                    case "data":
+                        currentData += (currentData ? "\n" : "") + val;
+                        break;
+                    case "id":
+                        currentId = val;
+                        break;
+                }
+            }
+        }
+        // Flush any remaining event in the buffer
+        if (currentData) {
+            try {
+                yield {
+                    event: currentEvent,
+                    data: JSON.parse(currentData),
+                    ...(currentId !== undefined && { id: currentId }),
+                };
+            }
+            catch {
+                yield {
+                    event: currentEvent,
+                    data: currentData,
+                    ...(currentId !== undefined && { id: currentId }),
+                };
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+//# sourceMappingURL=sse.js.map

package/core/sse.mjs

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

package/core/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Configuration types for the HappyRobot SDK client.
+ */
+export interface ClientConfig {
+    /** API key (sk_live_... or sk_test_...). Required. */
+    apiKey: string;
+    /** Base URL of the API. Defaults to "https://platform.happyrobot.ai/api/v2". */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 30000. */
+    timeout?: number;
+    /** Max retries on 429/5xx. Defaults to 2. Uses exponential backoff. */
+    maxRetries?: number;
+    /** Custom fetch implementation for testing or custom runtimes. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface RequestConfig {
+    /** HTTP method. */
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** URL path relative to baseUrl (e.g. "/workflows"). */
+    path: string;
+    /** Query parameters (appended as URL search params). */
+    query?: Record<string, string | number | boolean | undefined>;
+    /** JSON request body. */
+    body?: unknown;
+    /** Additional headers. */
+    headers?: Record<string, string>;
+    /** Override timeout for this request. */
+    timeout?: number;
+    /** Override max retries for this request. */
+    maxRetries?: number;
+}
+/** Standard paginated response with offset-based pagination. */
+export interface PaginatedResponse<T> {
+    data: T[];
+    pagination: PaginationMetadata;
+}
+export interface PaginationMetadata {
+    page: number;
+    page_size: number;
+    total_pages: number;
+    total_records: number;
+    has_next_page: boolean;
+    has_previous_page: boolean;
+}
+/** Standard list query parameters for offset-paginated endpoints. */
+export interface PaginationQuery {
+    page?: number;
+    page_size?: number;
+    sort?: "asc" | "desc";
+}

package/core/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Configuration types for the HappyRobot SDK client.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/core/types.mjs

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

package/helpers/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * High-level convenience helpers.
+ *
+ * @example
+ * ```ts
+ * import { createVoiceAgent, triggerAndWait, createFromTemplate } from "@happyrobot/sdk/helpers";
+ * ```
+ */
+export { createVoiceAgent } from "./voice-agent";
+export type { CreateVoiceAgentOptions, CreateVoiceAgentResult } from "./voice-agent";
+export { triggerAndWait } from "./trigger-and-wait";
+export type { TriggerAndWaitOptions, TriggerAndWaitResult } from "./trigger-and-wait";
+export { createFromTemplate } from "./template-workflows";
+export type { CreateFromTemplateOptions, CreateFromTemplateResult } from "./template-workflows";

package/helpers/index.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * High-level convenience helpers.
+ *
+ * @example
+ * ```ts
+ * import { createVoiceAgent, triggerAndWait, createFromTemplate } from "@happyrobot/sdk/helpers";
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFromTemplate = exports.triggerAndWait = exports.createVoiceAgent = void 0;
+var voice_agent_1 = require("./voice-agent");
+Object.defineProperty(exports, "createVoiceAgent", { enumerable: true, get: function () { return voice_agent_1.createVoiceAgent; } });
+var trigger_and_wait_1 = require("./trigger-and-wait");
+Object.defineProperty(exports, "triggerAndWait", { enumerable: true, get: function () { return trigger_and_wait_1.triggerAndWait; } });
+var template_workflows_1 = require("./template-workflows");
+Object.defineProperty(exports, "createFromTemplate", { enumerable: true, get: function () { return template_workflows_1.createFromTemplate; } });
+//# sourceMappingURL=index.js.map

package/helpers/index.mjs

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

package/helpers/template-workflows.d.ts

@@ -0,0 +1,49 @@
+/**
+ * High-level helper: create a workflow from any template.
+ */
+import type { HappyRobotClient } from "../client";
+import type { CreateWorkflowResponse, WorkflowPublishResponse } from "../types/workflows.types";
+export interface CreateFromTemplateOptions {
+    /** Template identifier (e.g. "voice-agent", "whatsapp-agent", "email-agent"). */
+    template: string;
+    /** Display name for the workflow. */
+    name: string;
+    /** Agent system prompt. */
+    prompt?: string;
+    /** Agent initial message. */
+    initialMessage?: string;
+    /** LLM model override. */
+    model?: {
+        type: "static";
+        static: {
+            id: string;
+            name: string;
+        };
+    };
+    /** Additional template-specific inputs. */
+    inputs?: Record<string, unknown>;
+    /** Publish after creation. Defaults to false. */
+    publish?: boolean;
+    /** Target environment when publishing. Defaults to "production". */
+    environment?: "production" | "staging" | "development";
+    /** Folder ID. */
+    folderId?: string;
+}
+export interface CreateFromTemplateResult {
+    workflow: CreateWorkflowResponse;
+    publishResult?: WorkflowPublishResponse;
+}
+/**
+ * Create a workflow from any template with optional publishing.
+ *
+ * @example
+ * ```ts
+ * const { workflow } = await createFromTemplate(client, {
+ *   template: "email-agent",
+ *   name: "Email Responder",
+ *   prompt: "You handle customer emails...",
+ *   publish: true,
+ * });
+ * ```
+ */
+export declare function createFromTemplate(client: HappyRobotClient, options: CreateFromTemplateOptions): Promise<CreateFromTemplateResult>;

package/helpers/template-workflows.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * High-level helper: create a workflow from any template.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFromTemplate = createFromTemplate;
+/**
+ * Create a workflow from any template with optional publishing.
+ *
+ * @example
+ * ```ts
+ * const { workflow } = await createFromTemplate(client, {
+ *   template: "email-agent",
+ *   name: "Email Responder",
+ *   prompt: "You handle customer emails...",
+ *   publish: true,
+ * });
+ * ```
+ */
+async function createFromTemplate(client, options) {
+    const { template, name, prompt, initialMessage, model, inputs = {}, publish = false, environment = "production", folderId, } = options;
+    const workflow = await client.workflows.create({
+        name,
+        folder_id: folderId,
+        from_template: {
+            template,
+            inputs: {
+                agent_name: name,
+                prompt: {
+                    prompt_md: prompt,
+                    initial_message: initialMessage,
+                    model,
+                },
+                ...inputs,
+            },
+        }, // Template input shapes vary by template type
+    });
+    let publishResult;
+    if (publish && workflow.id) {
+        publishResult = await client.workflows.publish(workflow.id, {
+            environment,
+        });
+    }
+    return { workflow, publishResult };
+}
+//# sourceMappingURL=template-workflows.js.map

package/helpers/template-workflows.mjs

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

package/helpers/trigger-and-wait.d.ts

@@ -0,0 +1,37 @@
+/**
+ * High-level helper: trigger a workflow run and poll until it completes.
+ */
+import type { HappyRobotClient } from "../client";
+import type { RunDetail } from "../types/runs.types";
+import type { SessionItem } from "../types/sessions.types";
+export interface TriggerAndWaitOptions {
+    /** Workflow ID or slug. */
+    workflowId: string;
+    /** Trigger payload. */
+    payload?: Record<string, unknown>;
+    /** Target environment. */
+    environment?: "production" | "staging" | "development";
+    /** Maximum time to wait in milliseconds. Defaults to 300_000 (5 min). */
+    timeoutMs?: number;
+    /** Poll interval in milliseconds. Defaults to 2_000 (2 sec). */
+    pollIntervalMs?: number;
+    /** Fetch sessions when run completes. Defaults to true. */
+    fetchSessions?: boolean;
+}
+export interface TriggerAndWaitResult {
+    run: RunDetail;
+    sessions: SessionItem[];
+}
+/**
+ * Trigger a workflow run and poll until it reaches a terminal status.
+ *
+ * @example
+ * ```ts
+ * const { run, sessions } = await triggerAndWait(client, {
+ *   workflowId: "my-workflow",
+ *   payload: { phone: "+1234567890" },
+ *   timeoutMs: 300_000,
+ * });
+ * ```
+ */
+export declare function triggerAndWait(client: HappyRobotClient, options: TriggerAndWaitOptions): Promise<TriggerAndWaitResult>;

package/helpers/trigger-and-wait.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * High-level helper: trigger a workflow run and poll until it completes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.triggerAndWait = triggerAndWait;
+const errors_1 = require("../core/errors");
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "succeeded",
+    "failed",
+    "canceled",
+    "skipped",
+]);
+/**
+ * Trigger a workflow run and poll until it reaches a terminal status.
+ *
+ * @example
+ * ```ts
+ * const { run, sessions } = await triggerAndWait(client, {
+ *   workflowId: "my-workflow",
+ *   payload: { phone: "+1234567890" },
+ *   timeoutMs: 300_000,
+ * });
+ * ```
+ */
+async function triggerAndWait(client, options) {
+    const { workflowId, payload, environment = "production", timeoutMs = 300_000, pollIntervalMs = 2_000, fetchSessions = true, } = options;
+    // 1. Trigger the run
+    const { run_id } = await client.workflows.triggerRun(workflowId, {
+        payload,
+        environment,
+    });
+    if (!run_id) {
+        throw new Error("No run_id returned from trigger");
+    }
+    // 2. Poll until terminal
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const run = await client.runs.get(run_id);
+        if (TERMINAL_STATUSES.has(run.status)) {
+            // 3. Optionally fetch sessions
+            let sessions = [];
+            if (fetchSessions) {
+                try {
+                    const sessionsResponse = await client.runs.getSessions(run_id);
+                    sessions = sessionsResponse.data;
+                }
+                catch {
+                    // Sessions may not exist for non-voice runs
+                }
+            }
+            return { run, sessions };
+        }
+        await sleep(pollIntervalMs);
+    }
+    throw new errors_1.TimeoutError(timeoutMs);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=trigger-and-wait.js.map

package/helpers/trigger-and-wait.mjs

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

package/helpers/voice-agent.d.ts

@@ -0,0 +1,47 @@
+/**
+ * High-level helper: create a voice agent workflow end-to-end.
+ */
+import type { HappyRobotClient } from "../client";
+import type { CreateWorkflowResponse, WorkflowPublishResponse } from "../types/workflows.types";
+export interface CreateVoiceAgentOptions {
+    /** Display name for the workflow. */
+    name: string;
+    /** Template to use. Defaults to "voice-agent" (outbound). */
+    template?: "voice-agent" | "inbound-voice-agent";
+    /** Agent system prompt. */
+    prompt?: string;
+    /** Agent initial message. */
+    initialMessage?: string;
+    /** LLM model override (TemplatedValue format). */
+    model?: {
+        type: "static";
+        static: {
+            id: string;
+            name: string;
+        };
+    };
+    /** Whether to publish after creation. Defaults to false. */
+    publish?: boolean;
+    /** Target environment when publishing. Defaults to "production". */
+    environment?: "production" | "staging" | "development";
+    /** Folder to place the workflow in. */
+    folderId?: string;
+}
+export interface CreateVoiceAgentResult {
+    workflow: CreateWorkflowResponse;
+    publishResult?: WorkflowPublishResponse;
+}
+/**
+ * Create a voice agent workflow from a template with optional publishing.
+ *
+ * @example
+ * ```ts
+ * const { workflow } = await createVoiceAgent(client, {
+ *   name: "Sales Agent",
+ *   prompt: "You are a helpful sales assistant...",
+ *   initialMessage: "Hi, how can I help you today?",
+ *   publish: true,
+ * });
+ * ```
+ */
+export declare function createVoiceAgent(client: HappyRobotClient, options: CreateVoiceAgentOptions): Promise<CreateVoiceAgentResult>;

package/helpers/voice-agent.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * High-level helper: create a voice agent workflow end-to-end.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVoiceAgent = createVoiceAgent;
+/**
+ * Create a voice agent workflow from a template with optional publishing.
+ *
+ * @example
+ * ```ts
+ * const { workflow } = await createVoiceAgent(client, {
+ *   name: "Sales Agent",
+ *   prompt: "You are a helpful sales assistant...",
+ *   initialMessage: "Hi, how can I help you today?",
+ *   publish: true,
+ * });
+ * ```
+ */
+async function createVoiceAgent(client, options) {
+    const { name, template = "voice-agent", prompt, initialMessage, model, publish = false, environment = "production", folderId, } = options;
+    // 1. Create workflow from template
+    const workflow = await client.workflows.create({
+        name,
+        folder_id: folderId,
+        from_template: {
+            template,
+            inputs: {
+                agent_name: name,
+                prompt: {
+                    prompt_md: prompt,
+                    initial_message: initialMessage,
+                    model,
+                },
+            },
+        },
+    });
+    // 2. Optionally publish
+    let publishResult;
+    if (publish && workflow.id) {
+        publishResult = await client.workflows.publish(workflow.id, {
+            environment,
+        });
+    }
+    return { workflow, publishResult };
+}
+//# sourceMappingURL=voice-agent.js.map

package/helpers/voice-agent.mjs

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

package/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @happyrobot/sdk — TypeScript SDK for the HappyRobot Public API.
+ *
+ * @example
+ * ```ts
+ * import { HappyRobotClient } from "@happyrobot/sdk";
+ *
+ * const client = new HappyRobotClient({ apiKey: "sk_live_..." });
+ *
+ * // List all workflows
+ * const { data } = await client.workflows.list();
+ *
+ * // Iterate all workflows across pages
+ * for await (const wf of client.workflows.listAll()) {
+ *   console.log(wf.name);
+ * }
+ *
+ * // Trigger a run
+ * const { run_id } = await client.workflows.triggerRun("my-workflow", {
+ *   payload: { phone: "+1234567890" },
+ * });
+ * ```
+ */
+export { HappyRobotClient } from "./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";
+export { paginate } from "./core/pagination";
+export { iterateSSE } from "./core/sse";
+export type { SSEEvent } from "./core/sse";
+export { WorkflowsResource } from "./resources/workflows";
+export { VersionsResource } from "./resources/versions";
+export { NodesResource } from "./resources/nodes";
+export type { TestNodeBody, TestNodeOutput, TestNodeResponse } from "./resources/nodes";
+export { RunsResource } from "./resources/runs";
+export { SessionsResource } from "./resources/sessions";
+export { MessagesResource } from "./resources/messages";
+export { VariablesResource } from "./resources/variables";
+export { PhoneNumbersResource } from "./resources/phone-numbers";
+export { SipTrunksResource } from "./resources/sip-trunks";
+export { IntegrationsResource } from "./resources/integrations";
+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";
+export { AdversarialTestsResource } from "./resources/adversarial-tests";
+export { NorthstarsResource } from "./resources/northstars";
+export { CustomEvalsResource } from "./resources/custom-evals";
+export { IssuesResource } from "./resources/issues";
+export { AuditRemarksResource } from "./resources/audit-remarks";
+export type * from "./types/workflows.types";
+export type * from "./types/versions.types";
+export type * from "./types/nodes.types";
+export type * from "./types/runs.types";
+export type * from "./types/sessions.types";
+export type * from "./types/phone-numbers.types";
+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";
+export type * from "./types/workflow-folders.types";
+export type * from "./types/adversarial-suites.types";
+export type * from "./types/adversarial-tests.types";
+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";