Busymate AI SDK for the Web — 0.1.0

Official versioned web SDK for Busymate AI hosted chat: @busymate/ai-web. One package for every web integration: the embed (launcher, panel or inline), end-user identity linking with a server-signed token, the busymate-ai-v1 bridge pinned to wire contract v1, typed events with link-status reason codes, and CSP and iframe guidance.

busymate.ai keeps serving the hosted chat and updates it every day. This SDK pins the page side of the wire, so those updates never change what your page sends or accepts. The plain snippet keeps working; migration shows how to move.

• TypeScript, typed, zero runtime dependencies.
• ESM and CommonJS for bundlers, plus a script-tag build (dist/busymate-ai-web.iife.js, ~10 KB gzipped) that defines window.BusymateAIWeb.
• SSR-safe: importing and creating a chat touches no DOM; mount() does nothing outside a browser.

Install from the GitHub release

npm install @busymate/ai-web

Or install the packed tarball attached to the 0.1.0 release:

npm install https://github.com/serebano/busymate-ai-sdk-web/releases/download/0.1.0/busymate-ai-web-0.1.0.tgz

Script tag: download busymate-ai-web.iife.js from the same release, serve it from your own origin (or CDN) and pin its SHA-256 with integrity (the hash is in the release notes):

<script src="/vendor/busymate-ai-web-0.1.0.iife.js" integrity="sha256-…" crossorigin="anonymous"></script>

Or pin the git tag and build it (dist/ is not committed):

git clone --branch 0.1.0 --depth 1 https://github.com/serebano/busymate-ai-sdk-web.git vendor/busymate-ai-sdk-web
(cd vendor/busymate-ai-sdk-web && npm ci && npm run build)
npm install ./vendor/busymate-ai-sdk-web

Integrate

import { createBusymateChat, mintFromEndpoint } from "@busymate/ai-web";

const chat = createBusymateChat({
  assistant: "acme",                       // Console › Integration
  origin: "https://acme.busymate.ai",      // or your verified custom domain
  mode: "launcher",                        // "launcher" | "panel" | "inline"
  getIdentity: mintFromEndpoint("/api/bmai/identity"), // YOUR authenticated endpoint; null when signed out
});

chat.onLinkStatus((s) => console.debug("busymate link", s.state, s.reason));
chat.on("ready", ({ visitorKind }) => console.debug("chat ready as", visitorKind));
chat.mount();

// Wire YOUR auth events, not your router:
auth.onSignIn(() => chat.identityChanged());   // sign-in, token rotation
auth.onSwitch(() => chat.switchAccount());     // another account
auth.onSignOut(() => chat.logout());           // never skip this one

Script tag:

<script src="/vendor/busymate-ai-web-0.1.0.iife.js"></script>
<script>
  const chat = BusymateAIWeb.createBusymateChat({ assistant: "acme" });
  chat.mount();
</script>

1. Read identity linking: your backend signs a one-time ES256 token; never put a key in the page.
2. Configure the complete reference and events.
3. Apply the CSP and iframe guidance.
4. Add your page's origin to Console › Integration › allowed origins. Otherwise the SDK reports origin_not_allowed.

Run the examples

npm ci && npm run build
node example-app/server.mjs                         # plain HTML: http://localhost:5180/example-app/plain/
cd example-app/react && npm install && npm run dev  # React: http://localhost:5181/

The examples consume this package (no copied SDK code). The plain page configures the assistant, origin, mode, locale, theme and your mint endpoint, drives every call and logs every event. Use a test workspace that allows http://localhost:5180.

Build, test and versions

python3 scripts/verify-release.py
npm ci
npm run build && npm run check:dist && npm run typecheck && npm run lint && npm test

CI (sdk-check) runs that on Ubuntu, macOS and Windows (the unit tests drive the pinned wire against a stand-in frame), packs the tarball, installs it into the React example and builds it, and checks that the ESM, CommonJS and script-tag builds load without a DOM and export the same API. The release notes record the live check against the hosted chat. CI does not certify your backend's token signing or your workspace's allowed origins.

Distribution 0.1.0 speaks wire contract v1 (bridge busymate-ai-v1, identity busymate.identity/v1). The version is 0.x, not 1.0.0 like the native SDKs, because the link-status reason vocabulary reported by the hosted chat (busymate-ai-src#2069) is not settled yet; the wire itself is stable, and 1.0.0 follows once those codes land. The release manifest pins the contract and wire source hashes. This repository is canonical for web SDK releases; busymate.ai documentation owns the human integration guide. See the changelog and wire contract.