@happyrobot-ai/sdk 0.1.0

package/client.d.ts

@@ -0,0 +1,85 @@
+/**
+ * HappyRobotClient — the main SDK entry point.
+ *
+ * @example
+ * ```ts
+ * import { HappyRobotClient } from "@happyrobot/sdk";
+ *
+ * const client = new HappyRobotClient({ apiKey: "sk_live_..." });
+ * const workflows = await client.workflows.list();
+ * ```
+ */
+import type { ClientConfig } from "./core/types";
+import { WorkflowsResource } from "./resources/workflows";
+import { VersionsResource } from "./resources/versions";
+import { NodesResource } from "./resources/nodes";
+import { RunsResource } from "./resources/runs";
+import { SessionsResource } from "./resources/sessions";
+import { MessagesResource } from "./resources/messages";
+import { VariablesResource } from "./resources/variables";
+import { PhoneNumbersResource } from "./resources/phone-numbers";
+import { SipTrunksResource } from "./resources/sip-trunks";
+import { IntegrationsResource } from "./resources/integrations";
+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";
+import { AdversarialTestsResource } from "./resources/adversarial-tests";
+import { NorthstarsResource } from "./resources/northstars";
+import { CustomEvalsResource } from "./resources/custom-evals";
+import { IssuesResource } from "./resources/issues";
+import { AuditRemarksResource } from "./resources/audit-remarks";
+export declare class HappyRobotClient {
+    private readonly http;
+    /** Workflow CRUD, publishing, runs, and templates. */
+    readonly workflows: WorkflowsResource;
+    /** Version management (fork, publish, lock, test). */
+    readonly versions: VersionsResource;
+    /** Node CRUD, config schema, and available variables. */
+    readonly nodes: NodesResource;
+    /** Run details, cancellation, and annotations. */
+    readonly runs: RunsResource;
+    /** Session details and messages. */
+    readonly sessions: SessionsResource;
+    /** Message quality flags. */
+    readonly messages: MessagesResource;
+    /** Workflow-scoped variables. */
+    readonly variables: VariablesResource;
+    /** Phone number management. */
+    readonly phoneNumbers: PhoneNumbersResource;
+    /** SIP trunk management. */
+    readonly sipTrunks: SipTrunksResource;
+    /** Integration and event discovery. */
+    readonly integrations: IntegrationsResource;
+    /** Contact lookup and history. */
+    readonly contacts: ContactsResource;
+    /** Knowledge base document management. */
+    readonly knowledgeBases: KnowledgeBasesResource;
+    /** Workflow folder organization. */
+    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. */
+    readonly apiKey: ApiKeyResource;
+    /** Adversarial suite management and execution. */
+    readonly adversarialSuites: AdversarialSuitesResource;
+    /** Adversarial test management and execution. */
+    readonly adversarialTests: AdversarialTestsResource;
+    /** Northstar quality criteria management. */
+    readonly northstars: NorthstarsResource;
+    /** Custom eval management and execution. */
+    readonly customEvals: CustomEvalsResource;
+    /** Quality issue (flag) status management. */
+    readonly issues: IssuesResource;
+    /** Audit remark feedback management. */
+    readonly auditRemarks: AuditRemarksResource;
+    constructor(config: ClientConfig);
+}

package/client.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * HappyRobotClient — the main SDK entry point.
+ *
+ * @example
+ * ```ts
+ * import { HappyRobotClient } from "@happyrobot/sdk";
+ *
+ * const client = new HappyRobotClient({ apiKey: "sk_live_..." });
+ * const workflows = await client.workflows.list();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HappyRobotClient = void 0;
+const http_1 = require("./core/http");
+const workflows_1 = require("./resources/workflows");
+const versions_1 = require("./resources/versions");
+const nodes_1 = require("./resources/nodes");
+const runs_1 = require("./resources/runs");
+const sessions_1 = require("./resources/sessions");
+const messages_1 = require("./resources/messages");
+const variables_1 = require("./resources/variables");
+const phone_numbers_1 = require("./resources/phone-numbers");
+const sip_trunks_1 = require("./resources/sip-trunks");
+const integrations_1 = require("./resources/integrations");
+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");
+const adversarial_tests_1 = require("./resources/adversarial-tests");
+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");
+class HappyRobotClient {
+    http;
+    /** Workflow CRUD, publishing, runs, and templates. */
+    workflows;
+    /** Version management (fork, publish, lock, test). */
+    versions;
+    /** Node CRUD, config schema, and available variables. */
+    nodes;
+    /** Run details, cancellation, and annotations. */
+    runs;
+    /** Session details and messages. */
+    sessions;
+    /** Message quality flags. */
+    messages;
+    /** Workflow-scoped variables. */
+    variables;
+    /** Phone number management. */
+    phoneNumbers;
+    /** SIP trunk management. */
+    sipTrunks;
+    /** Integration and event discovery. */
+    integrations;
+    /** Contact lookup and history. */
+    contacts;
+    /** Knowledge base document management. */
+    knowledgeBases;
+    /** Workflow folder organization. */
+    workflowFolders;
+    /** MCP server management. */
+    mcp;
+    /** Usage metrics (call minutes, tokens, etc.). */
+    usage;
+    /** Billing usage details and totals. */
+    billing;
+    /** API key introspection. */
+    apiKey;
+    /** Adversarial suite management and execution. */
+    adversarialSuites;
+    /** Adversarial test management and execution. */
+    adversarialTests;
+    /** Northstar quality criteria management. */
+    northstars;
+    /** Custom eval management and execution. */
+    customEvals;
+    /** Quality issue (flag) status management. */
+    issues;
+    /** Audit remark feedback management. */
+    auditRemarks;
+    constructor(config) {
+        this.http = new http_1.HttpClient(config);
+        this.workflows = new workflows_1.WorkflowsResource(this.http);
+        this.versions = new versions_1.VersionsResource(this.http);
+        this.nodes = new nodes_1.NodesResource(this.http);
+        this.runs = new runs_1.RunsResource(this.http);
+        this.sessions = new sessions_1.SessionsResource(this.http);
+        this.messages = new messages_1.MessagesResource(this.http);
+        this.variables = new variables_1.VariablesResource(this.http);
+        this.phoneNumbers = new phone_numbers_1.PhoneNumbersResource(this.http);
+        this.sipTrunks = new sip_trunks_1.SipTrunksResource(this.http);
+        this.integrations = new integrations_1.IntegrationsResource(this.http);
+        this.contacts = new contacts_1.ContactsResource(this.http);
+        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);
+        this.adversarialTests = new adversarial_tests_1.AdversarialTestsResource(this.http);
+        this.northstars = new northstars_1.NorthstarsResource(this.http);
+        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);
+    }
+}
+exports.HappyRobotClient = HappyRobotClient;
+//# sourceMappingURL=client.js.map

package/client.mjs

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

package/core/errors.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Error classes for the HappyRobot SDK.
+ *
+ * Hierarchy:
+ *   HappyRobotError (base)
+ *   ├── ApiError (any non-2xx with status, error, message, details)
+ *   │   ├── AuthenticationError (401)
+ *   │   ├── NotFoundError (404)
+ *   │   ├── ValidationError (400/422)
+ *   │   └── RateLimitError (429, includes retryAfter)
+ *   ├── TimeoutError (fetch timeout)
+ *   └── NetworkError (fetch failures)
+ */
+export declare class HappyRobotError extends Error {
+    constructor(message: string);
+}
+export interface ApiErrorBody {
+    error?: string;
+    message?: string;
+    statusCode?: number;
+    details?: unknown;
+    detail?: unknown;
+}
+export declare class ApiError extends HappyRobotError {
+    readonly status: number;
+    readonly body: ApiErrorBody;
+    constructor(status: number, body: ApiErrorBody);
+}
+export declare class AuthenticationError extends ApiError {
+    constructor(body: ApiErrorBody);
+}
+export declare class NotFoundError extends ApiError {
+    constructor(body: ApiErrorBody);
+}
+export declare class ValidationError extends ApiError {
+    constructor(status: number, body: ApiErrorBody);
+}
+export declare class RateLimitError extends ApiError {
+    readonly retryAfter: number | null;
+    constructor(body: ApiErrorBody, retryAfter: number | null);
+}
+export declare class TimeoutError extends HappyRobotError {
+    constructor(timeoutMs: number);
+}
+export declare class NetworkError extends HappyRobotError {
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}

package/core/errors.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Error classes for the HappyRobot SDK.
+ *
+ * Hierarchy:
+ *   HappyRobotError (base)
+ *   ├── ApiError (any non-2xx with status, error, message, details)
+ *   │   ├── AuthenticationError (401)
+ *   │   ├── NotFoundError (404)
+ *   │   ├── ValidationError (400/422)
+ *   │   └── RateLimitError (429, includes retryAfter)
+ *   ├── TimeoutError (fetch timeout)
+ *   └── NetworkError (fetch failures)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetworkError = exports.TimeoutError = exports.RateLimitError = exports.ValidationError = exports.NotFoundError = exports.AuthenticationError = exports.ApiError = exports.HappyRobotError = void 0;
+class HappyRobotError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HappyRobotError";
+    }
+}
+exports.HappyRobotError = HappyRobotError;
+class ApiError extends HappyRobotError {
+    status;
+    body;
+    constructor(status, body) {
+        const msg = body.message || body.error || `API error ${status}`;
+        super(msg);
+        this.name = "ApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+exports.ApiError = ApiError;
+class AuthenticationError extends ApiError {
+    constructor(body) {
+        super(401, body);
+        this.name = "AuthenticationError";
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class NotFoundError extends ApiError {
+    constructor(body) {
+        super(404, body);
+        this.name = "NotFoundError";
+    }
+}
+exports.NotFoundError = NotFoundError;
+class ValidationError extends ApiError {
+    constructor(status, body) {
+        super(status, body);
+        this.name = "ValidationError";
+    }
+}
+exports.ValidationError = ValidationError;
+class RateLimitError extends ApiError {
+    retryAfter;
+    constructor(body, retryAfter) {
+        super(429, body);
+        this.name = "RateLimitError";
+        this.retryAfter = retryAfter;
+    }
+}
+exports.RateLimitError = RateLimitError;
+class TimeoutError extends HappyRobotError {
+    constructor(timeoutMs) {
+        super(`Request timed out after ${timeoutMs}ms`);
+        this.name = "TimeoutError";
+    }
+}
+exports.TimeoutError = TimeoutError;
+class NetworkError extends HappyRobotError {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = "NetworkError";
+        this.cause = cause;
+    }
+}
+exports.NetworkError = NetworkError;
+//# sourceMappingURL=errors.js.map

package/core/errors.mjs

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

package/core/http.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Typed HTTP client for the HappyRobot API.
+ * Uses native fetch with auth, retry (exponential backoff), and timeout.
+ */
+import type { ClientConfig, RequestConfig } from "./types";
+export declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly fetchFn;
+    constructor(config: ClientConfig);
+    /**
+     * Perform a request and return the raw Response (for streaming endpoints).
+     * Applies auth and timeout but does NOT parse the body.
+     */
+    requestRaw(config: RequestConfig): Promise<Response>;
+    request<T>(config: RequestConfig): Promise<T>;
+    private buildUrl;
+    private fetchWithTimeout;
+    private parseErrorBody;
+    private createApiError;
+    private isRetryable;
+    private getBackoff;
+    private sleep;
+}

package/core/http.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * Typed HTTP client for the HappyRobot API.
+ * Uses native fetch with auth, retry (exponential backoff), and timeout.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpClient = void 0;
+const errors_1 = require("./errors");
+const DEFAULT_BASE_URL = "https://platform.happyrobot.ai/api/v2";
+const DEFAULT_TIMEOUT = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+const INITIAL_BACKOFF_MS = 500;
+class HttpClient {
+    apiKey;
+    baseUrl;
+    timeout;
+    maxRetries;
+    fetchFn;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error("apiKey is required");
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+        this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /**
+     * Perform a request and return the raw Response (for streaming endpoints).
+     * Applies auth and timeout but does NOT parse the body.
+     */
+    async requestRaw(config) {
+        const url = this.buildUrl(config.path, config.query);
+        const timeout = config.timeout ?? this.timeout;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "text/event-stream",
+            ...config.headers,
+        };
+        const response = await this.fetchWithTimeout(url, { method: config.method, headers }, timeout);
+        if (!response.ok) {
+            const errorBody = await this.parseErrorBody(response);
+            throw this.createApiError(response.status, errorBody, response);
+        }
+        return response;
+    }
+    async request(config) {
+        const url = this.buildUrl(config.path, config.query);
+        const timeout = config.timeout ?? this.timeout;
+        const maxRetries = config.maxRetries ?? this.maxRetries;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            ...config.headers,
+        };
+        if (config.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const response = await this.fetchWithTimeout(url, {
+                    method: config.method,
+                    headers,
+                    body: config.body !== undefined ? JSON.stringify(config.body) : undefined,
+                }, timeout);
+                if (response.ok) {
+                    if (response.status === 204) {
+                        return undefined;
+                    }
+                    const text = await response.text();
+                    if (!text)
+                        return undefined;
+                    return JSON.parse(text);
+                }
+                const errorBody = await this.parseErrorBody(response);
+                const error = this.createApiError(response.status, errorBody, response);
+                // Only retry on 429 and 5xx
+                if (this.isRetryable(response.status) && attempt < maxRetries) {
+                    lastError = error;
+                    const backoff = this.getBackoff(attempt, response);
+                    await this.sleep(backoff);
+                    continue;
+                }
+                throw error;
+            }
+            catch (err) {
+                if (err instanceof errors_1.ApiError)
+                    throw err;
+                if (err instanceof errors_1.TimeoutError) {
+                    if (attempt < maxRetries) {
+                        lastError = err;
+                        await this.sleep(this.getBackoff(attempt));
+                        continue;
+                    }
+                    throw err;
+                }
+                // Network errors
+                if (attempt < maxRetries) {
+                    lastError = err instanceof Error ? err : new Error(String(err));
+                    await this.sleep(this.getBackoff(attempt));
+                    continue;
+                }
+                throw new errors_1.NetworkError(err instanceof Error ? err.message : "Network request failed", err);
+            }
+        }
+        // Should not reach here, but just in case
+        throw lastError ?? new errors_1.NetworkError("Request failed after retries");
+    }
+    buildUrl(path, query) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        return url.toString();
+    }
+    async fetchWithTimeout(url, init, timeoutMs) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            return await this.fetchFn(url, { ...init, signal: controller.signal });
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === "AbortError") {
+                throw new errors_1.TimeoutError(timeoutMs);
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async parseErrorBody(response) {
+        try {
+            const text = await response.text();
+            if (!text)
+                return {};
+            return JSON.parse(text);
+        }
+        catch {
+            return {};
+        }
+    }
+    createApiError(status, body, response) {
+        switch (status) {
+            case 401:
+                return new errors_1.AuthenticationError(body);
+            case 404:
+                return new errors_1.NotFoundError(body);
+            case 400:
+            case 422:
+                return new errors_1.ValidationError(status, body);
+            case 429: {
+                const retryAfter = response.headers.get("retry-after");
+                return new errors_1.RateLimitError(body, retryAfter ? parseInt(retryAfter, 10) : null);
+            }
+            default:
+                return new errors_1.ApiError(status, body);
+        }
+    }
+    isRetryable(status) {
+        return status === 429 || status >= 500;
+    }
+    getBackoff(attempt, response) {
+        // Use Retry-After header for 429 if available
+        if (response?.status === 429) {
+            const retryAfter = response.headers.get("retry-after");
+            if (retryAfter) {
+                const seconds = parseInt(retryAfter, 10);
+                if (!isNaN(seconds))
+                    return seconds * 1000;
+            }
+        }
+        // Exponential backoff with jitter
+        const base = INITIAL_BACKOFF_MS * Math.pow(2, attempt);
+        const jitter = Math.random() * base * 0.1;
+        return base + jitter;
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.HttpClient = HttpClient;
+//# sourceMappingURL=http.js.map

package/core/http.mjs

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

package/core/pagination.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pagination utilities for the HappyRobot SDK.
+ * Provides an async iterator that auto-paginates through all pages.
+ */
+import type { HttpClient } from "./http";
+import type { PaginationQuery } from "./types";
+export interface PaginateOptions extends PaginationQuery {
+    /** Additional query parameters to include in each request. */
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Returns an async iterable that automatically fetches all pages of a
+ * paginated endpoint and yields individual items.
+ *
+ * @example
+ * ```ts
+ * for await (const workflow of paginate<Workflow>(http, "/workflows", { page_size: 50 })) {
+ *   console.log(workflow.name);
+ * }
+ * ```
+ */
+export declare function paginate<T>(http: HttpClient, path: string, options?: PaginateOptions): AsyncGenerator<T, void, undefined>;

package/core/pagination.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Pagination utilities for the HappyRobot SDK.
+ * Provides an async iterator that auto-paginates through all pages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paginate = paginate;
+/**
+ * Returns an async iterable that automatically fetches all pages of a
+ * paginated endpoint and yields individual items.
+ *
+ * @example
+ * ```ts
+ * for await (const workflow of paginate<Workflow>(http, "/workflows", { page_size: 50 })) {
+ *   console.log(workflow.name);
+ * }
+ * ```
+ */
+async function* paginate(http, path, options = {}) {
+    const { page: startPage = 1, page_size = 50, sort, ...rest } = options;
+    let currentPage = startPage;
+    while (true) {
+        const query = {
+            page: currentPage,
+            page_size,
+            sort,
+            ...rest,
+        };
+        const response = await http.request({
+            method: "GET",
+            path,
+            query,
+        });
+        for (const item of response.data) {
+            yield item;
+        }
+        if (!response.pagination.has_next_page) {
+            break;
+        }
+        currentPage++;
+    }
+}
+//# sourceMappingURL=pagination.js.map

package/core/pagination.mjs

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

package/core/sse.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Lightweight SSE (Server-Sent Events) stream parser.
+ *
+ * Consumes a `Response` body and yields typed `SSEEvent` objects.
+ */
+export interface SSEEvent<T = unknown> {
+    /** The SSE event name (e.g. "message", "connected", "session_ended"). */
+    event: string;
+    /** Parsed JSON payload. */
+    data: T;
+    /** Optional SSE `id` field. */
+    id?: string;
+}
+/**
+ * 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`.
+ */
+export declare function iterateSSE<T = unknown>(response: Response): AsyncGenerator<SSEEvent<T>, void, undefined>;