@hot-dev/sdk

Official JavaScript/TypeScript SDK for the Hot Dev API.

Install

npm install @hot-dev/sdk

Requires Node 20+. Server-side only — use a backend proxy for browser apps (see @hot-dev/sdk/proxy). Most management endpoints require an API key; sessions and service keys are permission-scoped and are mainly for event publishing and stream reads.

Quick start

import{HotClient}from"@hot-dev/sdk";consthot=newHotClient({token: process.env.HOT_API_KEY!,});// `baseUrl` defaults to https://api.hot.dev.// For local development with `hot dev`, pass `baseUrl: "http://localhost:4681"`.forawait(consteventofhot.streams.subscribeWithEvent({event_type: "team-agent:ask",event_data: {session_id: "web:chat:demo",user_id: "web:user:demo",user_name: "Demo User",question: "what is blocking launch?",},})){if(event.type==="stream:data"){console.log(event.data_type,event.payload);}if(event.type==="run:stop"){console.log(event.run?.result);break;}}

JavaScript and TypeScript

The SDK works from both JavaScript and TypeScript. TypeScript users get typed request and response shapes, stream event narrowing, and helper types from the subpath exports.

The package is ESM-only, so JavaScript projects should use import rather than require. JavaScript users can enable editor type hints with JSDoc:

// @ts-checkimport{HotClient}from"@hot-dev/sdk";/** @type {import("@hot-dev/sdk").PublishEventRequest} */constevent={event_type: "team-agent:ask",event_data: {question: "What changed?"},};consthot=newHotClient({token: process.env.HOT_API_KEY,});awaithot.events.publish(event);

Retries

JSON requests are retried automatically (at most twice) when the API responds 429 with a retry_after; other errors are thrown as-is. Streaming and raw requests are never retried.

Casing policy

Core API request and response types use the Hot API wire format (event_type, stream_id, event_data). SDK-only options use normal JavaScript casing (baseUrl, timeoutMs). The SDK never transforms user-owned payloads such as event_data.

Exports

Import	Purpose
@hot-dev/sdk	HotClient, core types, HotApiError
@hot-dev/sdk/streaming	SSE parsing, waitForRunResult
@hot-dev/sdk/agent	Agent event payloads, slash commands, reply folding
@hot-dev/sdk/webhook	Webhook URL builder and POST helper
@hot-dev/sdk/proxy	BFF proxy handler for Next.js routes

Full API reference: packages/sdk/README.md.

Related

• Hot Dev documentation
• SDK docs

Developing this repo

pnpm install
pnpm build
pnpm test

Uses pnpm workspaces. See AGENTS.md for maintainer notes.

License

Apache-2.0