botapp-sdk

App SDK for building botapp apps. Provides the BotApp class, hosted-runtime bridge, agent-chat client, and launch-URL helpers.

Install

npm i botapp-sdk
# or pnpm add botapp-sdk

You also need the CLI to scaffold and run apps:

npm i -g botapp-cli

Quickstart

Scaffold an app, dev-tunnel it to a server, ship it.

bot login --server https://your-botapp-server   # one time
bot init my-app && cd my-app
npm install && npm run build
bot simulate                                    # opens dev tunnel
# … iterate. ctrl-c to stop. your dashboard sees your local process.
bot publish                                     # private install
bot publish --public                            # request admin review

bot simulate and bot publish coexist — simulate shadows the published install for the logged-in user only, so you can iterate against a live server without affecting other users.

Minimal app entry

import { BotApp, runHosted } from 'botapp-sdk'

const app = new BotApp({
  name: 'my-app',
  version: '1.0.0',
  async setup(ctx) {
    ctx.serveStatic('./dist')

    ctx.registerCommand('hello', {
      description: 'Say hello',
      params: {
        name: { type: 'string', required: false, default: 'world' },
      },
      handler: async (params) => `Hello, ${params.name ?? 'world'}!`,
    })
  },
})

export default app

const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {}
if (env.BOTAPP_SERVER && env.BOTAPP_APP_TOKEN) {
  await runHosted(app)
}

The hosted bridge stays dormant unless BOTAPP_SERVER and BOTAPP_APP_TOKEN are set — bot simulate and the platform-spawned runner inject them. The app process never opens a listening port; it connects out over WebSocket and the platform routes traffic to it.

SDK surfaces

| Import | Purpose | |---|---| | BotApp, runHosted from botapp-sdk | App definition + hosted-tier WS bridge | | AgentChatClient from botapp-sdk/client | Browser-side: agent picker, conversation, live job stream | | readLaunchContext, makeUrl, openUrl from botapp-sdk/launch | botapp:// deep-link reader and builder | | html, raw, escapeHtml from botapp-sdk | Safe HTML interpolation for registerWidget | | MemoryKVStore from botapp-sdk | In-process KV for tests / local adapters |

AppContext (the ctx arg in setup) exposes:

• registerCommand / registerAction / registerRoute / registerWidget
• state / userState / groupState (managed KV)
• chat.notify / chat.ask (talk to the user's daemon agent)
• tasks (create user-visible work items)
• emitEvent / onEvent / subscribeEvents
• invoke (call other apps), requestPermission, dispatchAction
• listAgents (directory of the user's paired agents)
• serveStatic (upload your built frontend to the platform)

Full API reference is in docs/APP_RUNTIME.md. Authoring patterns and recipes are in docs/APP_DEVELOPMENT.md.

Bundled docs

The npm package includes the canonical specs under docs/:

| File | What it covers | |---|---| | docs/APP_DEVELOPMENT.md | Storage model, hosted-tier patterns, GUI ↔ agent comms, tasks, deep links, portability matrix | | docs/APP_RUNTIME.md | AppContext API reference (every method + signature) | | docs/APP_PROTOCOL.md | Wire format (JSON over WebSocket) for non-TS implementations | | docs/CLI.md | bot CLI command surface | | docs/SKILL.md | Authoring playbook: scenario intake, SDK usage patterns, common pitfalls |

Coding agents: read these from node_modules/botapp-sdk/docs/ before authoring. They're the source of truth — this README is a hop, not a substitute.

Hosted-runtime model

The SDK ships one runtime path: outbound WebSocket to the botapp server. Same code runs as:

| Host | Reached via | |---|---| | Platform-spawned subprocess (default after bot publish) | local pipe → WS | | Developer laptop (bot simulate) | outbound wss:// | | Container / VPS / Kubernetes | outbound wss:// | | Cloudflare Worker / Deno Deploy / Fly | outbound wss:// |

The SDK detects the runtime and uses the host's WebSocket primitive — no port, no app.connect(), no ConnectedAdapter to instantiate.

Testing your app

bot simulate is the primary test loop. It:

1. Reads botapp.app.json.
2. Asks the server for a per-user dev token (POST /api/dev/token).
3. Spawns your entry process with BOTAPP_SERVER + BOTAPP_APP_TOKEN set.
4. Routes your dashboard's traffic for that app to your local process — only for you.

So you exercise commands, actions, routes, and widgets through the real dashboard at <server> while the code runs on your laptop. Edit, rebuild, retry. Stop with Ctrl-C and the dashboard falls through to your published install (or 404 if none).

For non-tunnel tests, the SDK also exports MemoryKVStore and LocalAdapter for in-process unit tests.

License

MIT