🍫 Chocolate Factory SDK

The official JavaScript/TypeScript SDK for the Chocolate Factory AI platform.

Embed AI agents into any web application in minutes — beautiful chat widgets, streaming responses, tool execution display, and a clean programmatic API for backend automation.

Features

• 💬 Chat Widget – drop a polished floating chat panel into any page with one line
• 🌊 Streaming – real-time token-by-token responses with live typing indicators
• 🛠 Tool Execution Display – animated pills that show agent tool calls as they happen
• ⚡ Agent Execution – call any agent as a function (run) or async generator (stream)
• 🎨 Fully Themeable – CSS custom properties, colour picker, font, radius, z-index
• 📦 Framework-agnostic – works with React, Vue, Svelte, Angular, plain HTML, or Node.js
• 🔒 Zero dependencies – no third-party runtime deps; ships as ESM + UMD

Installation

npm install @the-chocolate-factory/sdk
# or
pnpm add @the-chocolate-factory/sdk
# or
yarn add @the-chocolate-factory/sdk

CDN (no bundler)

<script src="https://unpkg.com/@the-chocolate-factory/sdk/dist/index.js"></script>

Quick Start

1. Embed a chat widget

import ChocolateFactory from "@the-chocolate-factory/sdk";

const cf = new ChocolateFactory({
  apiKey: "agk_xxx",           // Agent Key from Chocolate Factory
  agentId: "support-agent",    // Your agent ID
  baseUrl: "https://cf.example.com",
});

cf.chat.mount("#app");         // That's it 🎉

2. Customise the look

cf.chat.mount("#app", {
  title: "Acme Support",
  avatarUrl: "/acme-bot.png",
  welcomeMessage: "Hi! I'm here to help with your order.",
  theme: {
    primaryColor: "#7c3aed",
    borderRadius: 12,
  },
  position: "bottom-right",
});

3. HTML attribute API (zero JS needed)

<cf-chat-widget
  api-key="agk_xxx"
  agent-id="support-agent"
  base-url="https://cf.example.com"
  title="Support Bot"
  primary-color="#3b82f6"
></cf-chat-widget>

<script src="https://unpkg.com/@the-chocolate-factory/sdk/dist/index.js"></script>
<script>ChocolateFactory.registerChatWidget();</script>

4. Call an agent as a function

const result = await cf.agent.run({
  message: "Analyze this customer",
  vars: { customer: customerData },
});
console.log(result.text);

5. Stream an agent response

for await (const chunk of cf.agent.stream({ message: "Write a summary" })) {
  process.stdout.write(chunk);
}

5b. Call an agent from Node.js (API routes, server components, scripts)

The main @the-chocolate-factory/sdk entry point bundles the browser-only chat widget (a custom element that extends HTMLElement), so importing it in Node.js throws ReferenceError: HTMLElement is not defined. Use the /server entry point instead — it only exports AgentClient, ChatClient, and shared types, with no DOM dependency:

import { AgentClient } from "@the-chocolate-factory/sdk/server";

const agent = new AgentClient({
  apiKey: process.env.CF_API_KEY!,
  agentId: "support-agent",
  baseUrl: process.env.CF_BASE_URL!,
});

const result = await agent.run({ message: "Summarize this ticket" });
console.log(result.text);

6. Programmatic chat with events

const chat = cf.chat;

chat.on("message-chunk", (e) => appendToken(e.chunk ?? ""));
chat.on("message-end",   (e) => console.log("Done:", e.message));
chat.on("tool-start",    (e) => showBadge(e.tool?.name ?? ""));

await chat.send({ text: "What's my order status?" });

API Reference

new ChocolateFactory(config)

| Option | Type | Required | Description | |---|---|---|---| | apiKey | string | ✅ | Agent Key (agk_…) | | agentId | string | ✅ | Target agent ID | | baseUrl | string | ✅ | Your Chocolate Factory deployment URL | | agentPayload | Record<string, string \| number \| boolean> | – | Headers forwarded to MCP integrations |

cf.chat — ChatClient

| Method | Description | |---|---| | .send(options) | Send a message and stream the response | | .on(event, listener) | Subscribe to a chat event | | .off(event, listener) | Unsubscribe | | .mount(selector, options?) | Mount the chat widget | | .messages | Current message history | | .clearHistory() | Wipe local history |

cf.agent — AgentClient

| Method | Description | |---|---| | .run(options) | Execute the agent, return { text, usage, finishReason } | | .stream(options) | Execute the agent, return an async generator of text chunks |

Documentation

Full docs in the docs/ folder:

• Getting Started
• Chat SDK
• Agent SDK
• Authentication

Examples

| Example | Location | |---|---| | Vanilla HTML widget | examples/chat-widget/ | | Node.js agent execute | examples/agent-execute/ | | Node.js agent stream | examples/agent-stream/ |

Package output

dist/
  index.esm.js   ← ES Module (import) – full SDK incl. chat widget, browser only
  index.js       ← UMD (require / <script>) – full SDK incl. chat widget, browser only
  index.d.ts     ← TypeScript declarations
  server.esm.js  ← ES Module (import) – AgentClient + ChatClient only, Node-safe
  server.cjs     ← CommonJS (require) – AgentClient + ChatClient only, Node-safe
  server.d.ts    ← TypeScript declarations
  *.d.ts         ← Per-module declarations
  *.map          ← Source maps

Building from source

pnpm install
pnpm build

License

MIT