# App config
Source: https://docs.waniwani.ai/kit/app-config

waniwani.config.ts names the MCP server, hands the host an overview at connect time, and tunes the template's search tool and tracking.

Every kit app has one `waniwani.config.ts` at its root, default-exporting `defineApp({ ... })`. The CLI reads it to name the server, and the runtime forwards the rest to the host and to the SDK.

```ts waniwani.config.ts theme={null}
import { defineApp } from "@waniwani/kit";

export default defineApp({
  name: "oney",
  title: "Oney: split your payment",
  overview: `You help shoppers split a purchase into instalments with Oney.

RULES:
- Never quote a monthly amount yourself. Call check-eligibility and let it do the arithmetic.
- Never list the plans in text. Show the select-plan widget and let it render them.`,
});
```

## Options

<ResponseField name="name" type="string">
  The MCP server name, e.g. `oney-split-payment`. Hosts show `title` to humans and use this one as the id.
</ResponseField>

<ResponseField name="title" type="string">
  Shown to humans in connector UIs.
</ResponseField>

<ResponseField name="version" type="string">
  Defaults to the `version` in the app's `package.json`.
</ResponseField>

<ResponseField name="overview" type="string">
  What this app is and how its tools fit together, handed to the host LLM once in the `initialize` handshake: which tool to reach for, what order things happen in, how to read what comes back, tone, guardrails. Reaches the wire as the MCP server's `instructions`.

  How a single tool behaves belongs in that tool's own `description`. A description travels with every `tools/list` and reaches the model at the moment it is choosing that tool. The overview is read once at connect, so a client that connected before an edit keeps the old copy until it reconnects, and a host is free to drop it altogether. Put nothing load-bearing in it.
</ResponseField>

<ResponseField name="search" type="SearchOptions">
  Tune, or decline, the `search` tool the distribution template ships on top of the [knowledge base](/sdk/knowledge-base/overview).

  <Expandable title="search options">
    <ResponseField name="enabled" type="boolean">
      Whether the template registers the tool at all. `false` is the only way an app can decline it. A deployment with no corpus behind it is better off without the tool than with one answering confidently out of the wrong file.
    </ResponseField>

    <ResponseField name="topK" type="number">
      Passages to ask for, 1 to 20.
    </ResponseField>

    <ResponseField name="minScore" type="number">
      Similarity floor, 0 to 1, under which a passage is dropped rather than ranked last.
    </ResponseField>

    <ResponseField name="metadata" type="Record<string, string>">
      Exact-match filter on chunk metadata. A passage must carry all of these pairs to come back.
    </ResponseField>

    <ResponseField name="timeoutMs" type="number">
      Give up on a slow search and answer as though nothing matched.
    </ResponseField>

    <ResponseField name="includeSources" type="boolean">
      Name the source document on each passage.
    </ResponseField>

    <ResponseField name="preamble" type="string">
      Framing prepended to the answer text. Retrieved passages are third-party text on their way into a prompt; this is where an app says they are reference material rather than instructions.
    </ResponseField>

    <ResponseField name="notFound" type="string">
      The whole answer when no passage comes back: nothing matched, the search outran `timeoutMs`, or the knowledge base failed. An app whose corpus carries regulated information should write both halves in its own words, the refusal the user reads and the human to go to instead. `preamble` is not applied on top of it.
    </ResponseField>

    <ResponseField name="invoking" type="string">
      Status text the host shows while the call is in flight.
    </ResponseField>

    <ResponseField name="invoked" type="string">
      Status text the host shows once the call has returned.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tracking" type="TrackingOptions">
  Forwarded whole to the SDK's [`withWaniwani()`](/sdk/configuration/wrap-server). Set `WANIWANI_API_KEY` in the app's `.env` for events to reach the platform; without it tracking is a no-op.

  <Expandable title="tracking options">
    <ResponseField name="toolType" type="ToolType | (toolName: string) => ToolType | undefined">
      One category for every tool, or a function mapping a tool name to a category. Categories: `pricing`, `product_info`, `availability`, `support`, `other`.
    </ResponseField>

    <ResponseField name="metadata" type="Record<string, unknown>">
      Merged into every tracked event.
    </ResponseField>

    <ResponseField name="flushAfterToolCall" type="boolean">
      Flush the tracking transport after each tool call. This is the one that matters on serverless: an invocation frozen between tool calls takes any unsent batch with it.
    </ResponseField>

    <ResponseField name="injectWidgetToken" type="boolean">
      Put widget tracking config in each tool response's `_meta.waniwani`, so a widget in the browser can send its own events.
    </ResponseField>

    <ResponseField name="stripLocationFields" type="string[]">
      Field names to strip from location `_meta` before events are sent. Pass `["latitude", "longitude"]` to drop coordinates and keep the rest.
    </ResponseField>

    <ResponseField name="applyFieldRedactions" type="boolean">
      Replace flow state fields marked with `redacted()` before they are tracked. Wire it to an env var to keep real values in development and redact in production.
    </ResponseField>
  </Expandable>
</ResponseField>

## Where each value ends up

| Option            | Reaches                                                           |
| ----------------- | ----------------------------------------------------------------- |
| `name`, `version` | the `McpServer` constructor                                       |
| `title`           | `serverInfo.title`, shown by connector UIs                        |
| `overview`        | `instructions` in the `initialize` response                       |
| `search`          | the template's `search` tool, through the generated `waniwani.ts` |
| `tracking`        | `withWaniwani()` around the server                                |


# Commands
Source: https://docs.waniwani.ai/kit/commands

The six waniwani commands, the four stages every one of them runs (scan, check, codegen, run), and what the build check catches before a request does.

```bash theme={null}
waniwani init [dir]          # scaffold an app folder, install, ready to dev
waniwani check               # validate the folder
waniwani dev                 # generate + dev server + regenerate on change
waniwani build               # generate + production build
waniwani start               # run the production build
waniwani eject [--out dir]   # hand the plumbing over and step out
```

Running `waniwani` with no command is `dev`. The scaffolded `package.json` maps `check`, `dev`, `build` and `start` to npm scripts, so `npm run dev` and `waniwani dev` are the same thing.

`init` writes files and stops there; its prompts and flags are on the [Quickstart](/kit/quickstart#what-init-asks). Every other command runs the same four stages before doing its own work.

## The four stages

```mermaid theme={null}
flowchart LR
    subgraph app["oney/ (what you own)"]
        cfg["waniwani.config.ts"]
        tools["tools/*.ts"]
        widgets["widgets/&lt;name&gt;/<br/>widget.ts + ui.tsx"]
        flows["flows/*.ts"]
        api["api/**/*.ts"]
        wk["well-known/**/*.ts"]
    end

    subgraph tpl["WaniWani-AI/mcp-distribution-template (public, separate repo)"]
        raw["vite.config.ts · package.json · tsconfig.json<br/>src/index.css (Tailwind)<br/>alpic.json · Dockerfile"]
    end

    subgraph cli["@waniwani/kit (what we own)"]
        scan["scan<br/><i>convention → manifest</i>"]
        check["check<br/><i>fail at build time</i>"]
        gen["codegen<br/><i>emit a real project</i>"]
        runtime["src/server.ts<br/><i>registerApp()</i>"]
    end

    subgraph out[".waniwani/ (build output, disposable)"]
        server["src/server.ts · src/waniwani.ts"]
        views["src/views/*.tsx"]
        appsrc["src/app/ (your source, copied)"]
        deployfiles["Dockerfile · alpic.json"]
    end

    app --> scan --> check --> gen --> out
    runtime -.imported by.-> server
    raw -.fetched at a pinned SHA, copied byte for byte.-> deployfiles
    out --> deploy["dev · build · start"]
    app -.waniwani eject.-> ejected["a plain repo<br/><i>no CLI, no @waniwani/kit</i>"]
```

1. **scan** walks the folder and turns convention into a manifest.
2. **check** validates structure from the filesystem, then imports every server-safe module for real.
3. **codegen** resolves the distribution template at a pinned commit, copies its plumbing byte for byte, generates registration and view entries from the manifest, and copies your source under `src/app/`.
4. **run** hands the result to the framework's `dev`, `build` or `start`, with the output rewritten in Waniwani's voice.

`.waniwani/` is disposable and safe to delete. Keep it out of git, the way `.next/` is; `init` writes that line into `.gitignore` for you.

## dev

`dev` watches the folder, mirrors changes into `.waniwani/`, and leaves nodemon and Vite HMR to do the rest. An edit to a tool reaches the MCP endpoint in about a second. The MCP endpoint is `/mcp` on the dev port, and the dev server's root serves the framework's own page for calling tools without a chat client.

To reach the dev server from ChatGPT or Claude, expose it with a [tunnel](/sdk/guides/tunnel), or bind the repo to a hosted agent with [`@waniwani/cli`](/sdk/cli/overview) and run against the hosted playground.

## What the build check catches

Errors that would otherwise surface as a 500 at request time, or as a widget that silently never renders:

```text theme={null}
✗ Build check failed

  widgets/broken
  └ missing widget.ts
    every widget folder needs a widget.ts with `export default defineWidget({ ... })`

  flows/split-payment.ts
  └ showWidget references the widget "select-plans", which does not exist
    known widgets: broken, select-plan
```

Structure comes from the filesystem. The rest comes from importing every server-safe module, so a flow that fails to compile fails the build, as does a missing default export, a tool with no description, or a runtime configuration mistake:

```text theme={null}
  flows/no-store.ts
  └ failed to load
    [waniwani] createFlow "no_store": no flow store configured. …
```

`check` reads the app's `.env` before importing anything, for the same reason `dev` does: a flow whose store comes from `WANIWANI_API_KEY` would otherwise fail its own check over a variable sitting in the file next to it.

## Environment variables the CLI reads

| Variable                     | Effect                                                                                                                                         |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `WANIWANI_DEBUG=1`           | Print the CLI's own diagnostics: which template was resolved, how many files it copied, stack traces.                                          |
| `WANIWANI_OFFLINE=1`         | Skip the npm lookup `init` and `check` make for the newest SDK; see [Flows](/kit/flows#which-sdk-version-an-app-gets).                         |
| `WANIWANI_TEMPLATE=<source>` | Override the distribution template for one command, with a branch ref or a local checkout. `--template <source>` does the same per invocation. |

Variables for the app itself, such as `WANIWANI_API_KEY`, go in the app's `.env`; see [Deploy](/kit/deploy#secrets-and-environment-variables).


# Deploy
Source: https://docs.waniwani.ai/kit/deploy

Deploying a kit app is a git push. Vercel needs a four-line vercel.json, Docker and Alpic read their config from the build, and secrets come from the app's .env or the platform.

`waniwani init` asks where the app deploys, because the answer decides the one config file the repo carries:

```text theme={null}
◆  Where will this deploy?
│  ● Vercel (git push, or `vercel deploy --prebuilt`)
│  ○ Docker
│  ○ Alpic
│  ○ I don't know yet
│  ↑/↓ to navigate • Enter: confirm
└
```

Pass `--host vercel`, `--host container`, `--host alpic` or `--host none` to answer ahead of time.

## Vercel

Only Vercel leaves anything behind, and it is four lines:

```json vercel.json theme={null}
{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "framework": null
}
```

`framework: null` selects the `Other` preset. That one key is the only thing a repo cannot say any other way: the preset is a project setting Vercel resolves *before* the build command runs, so a project whose dashboard says `Next.js` or `Express` fails on the preset and never reaches the build. `Other` is what runs the `build` script and adopts what the build produced.

```text theme={null}
Error: No Next.js version detected.
```

Nothing else belongs in that file. `waniwani build` writes a Build Output tree inside `.waniwani/` (the bundled function, the static assets, the routing config) and the build's last step moves it to `.vercel/output` at the app root, the one path where Vercel adopts one. A `buildCommand` would restate the `build` script that already runs, and a `routes` table would duplicate routing the build writes. Both go stale against a kit that moved on; `framework: null` is a fact about the project, so it never changes.

```bash theme={null}
git push                          # a git-connected project builds and serves it
vercel deploy --prebuilt          # or upload the tree a local build produced
```

A prebuilt deploy skips the preset question entirely, since it uploads the tree and asks Vercel to build nothing.

<Accordion title="Why the build routes /api/* itself">
  One thing the kit decides on the app's behalf, in that tree's own routing table:

  ```json theme={null}
  { "src": "/api(/.*)?", "dest": "/mcp" }
  ```

  Vercel reserves a root `api/` directory. It compiles every file under one into a serverless function of its own, and an endpoint module is not a Vercel handler, since `defineEndpoint({ ... })` is an object. The reservation cannot be waived, because the file list is read before the build command runs:

  ```text theme={null}
  Error: File not found: /vercel/path0/api/cal/book.ts
  ```

  So the route goes in ahead of the tree's `filesystem` handler, which is the phase those functions sit in. `/api/*` reaches the server the kit built, and the ones Vercel made are never routed to. They still cost build time, two dead functions per app.
</Accordion>

<Warning>
  An app carrying a `vercel.json` from an earlier setup has to lose everything in it but `framework`. A `buildCommand` that stages the tree by hand deletes what the build just placed. `waniwani check` names the keys that fight the build.
</Warning>

## Docker

The build writes a `Dockerfile` and `.dockerignore` into `.waniwani/`, so the image is built from there:

```bash theme={null}
waniwani build
docker build .waniwani
```

## Alpic

`alpic.json` also comes out of the build:

```bash theme={null}
waniwani build
cd .waniwani && alpic deploy
```

## Secrets and environment variables

`.env` and `.env.local` sit next to `waniwani.config.ts`, and every command reads them before it runs anything. A variable already exported in the shell or set by CI wins over both files, and a hosted deploy sets its variables on the platform and reads no file at all.

```bash .env theme={null}
# Optional. Without it the app still runs: flows use MemoryKvStore and
# withWaniwani degrades to a no-op. With it, flow state is hosted and tracking
# reaches app.waniwani.ai.
WANIWANI_API_KEY=
```

Loading them this early is what lets a module build its client at import time:

```ts lib/waniwani.ts theme={null}
export const wani = waniwani({ apiKey: process.env.WANIWANI_API_KEY });
```

The generated project runs from `.waniwani/`, one level below the file, and a module's imports are evaluated before any line of the module that pulled it in, so neither `dotenv/config` nor a load inside generated code arrives in time. `waniwani check` reads the same files for the same reason.

On a hosted deploy, environment variables live on the platform. A Vercel project that sets its variables for production alone gets previews with none, which for an app whose flow reads `WANIWANI_API_KEY` at import time means a function that fails to boot. Set them for every environment the project serves.

Get an API key from the [Waniwani dashboard](/sdk/configuration/api-key). What the key turns on is described under [Waniwani Platform](/sdk/platform/overview).


# Eject
Source: https://docs.waniwani.ai/kit/eject

waniwani eject writes the server, the bundler config and the deploy files into your repo, rewrites the imports, and removes @waniwani/kit from the dependencies. One way only.

`waniwani eject` writes the plumbing into the repo itself and leaves. What comes out is the same tree a build was producing all along, with your source moved under `src/app/`:

```text theme={null}
oney/
├── src/app/{tools,widgets,flows,lib}/        your code, moved
├── src/_runtime/                             the runtime, vendored as source
├── src/{server,waniwani}.ts                  entry and registration
├── src/views/<widget>.tsx                    view entries
├── vite.config.ts  alpic.json  vercel.json   bundling and deploy
├── Dockerfile  .dockerignore                 container deploy
└── tsconfig.json  package.json
```

Every `@waniwani/kit` import gets rewritten to `./_runtime/…`, and the dependency drops out of `package.json`. From then on the repo runs on Skybridge's own CLI (`dev`, `build`, `start`) with no Waniwani in the loop.

```bash theme={null}
waniwani eject               # in place
waniwani eject --out ../oney-ejected
```

Ejecting in place moves the files instead of copying them, so the originals go once the copy is on disk and the repo is never left holding two versions of a file that can drift. `--out <dir>` leaves the source repo untouched. Either way the CLI prints what moved. Eject refuses to overwrite existing plumbing unless you pass `--force`, and it runs one way, with nothing to turn an ejected repo back.

## Why the source moves under src/

Your source has to move under `src/` for the compiled server to land where Skybridge's entry wrapper looks for it. `tsc` derives `rootDir` from the widest common ancestor of the files it compiles, so source sitting beside `src/` rather than inside it pushes every emitted path down a level and the wrapper's import misses.

## The trade eject makes

What an ejected repo gives up is the generator, and with it:

* **the build check**, so `showWidget("typo")` becomes a runtime failure again
* **name-from-filesystem**, so adding a widget means editing `src/waniwani.ts` and adding an entry under `src/views/`
* **runtime fixes**, since `src/_runtime/` is a fork from the moment it lands


# Endpoints
Source: https://docs.waniwani.ai/kit/endpoints

api/ holds HTTP endpoints the widget calls from the browser, invisible to the model. well-known/ serves the same kind of handler at the root of the domain.

A widget runs in an iframe on another origin, and it can call its own server without going through the model at all. Booking a slot, loading a calendar, looking up a price, receiving a webhook: `api/` is where those live. The path comes from the file's position, the folder name included, so there is nothing to keep in step with the `fetch()` on the other side:

```text theme={null}
api/cal/slots.ts          →  /api/cal/slots
api/webhooks/stripe.ts    →  /api/webhooks/stripe
api/cal/index.ts          →  /api/cal
```

```ts api/cal/slots.ts theme={null}
import { defineEndpoint } from "@waniwani/kit";
import { fetchCalSlots } from "../../lib/cal.js";

export default defineEndpoint({
  method: "post",
  handler: async (req, res) => {
    const { timeZone } = req.body;
    res.json({ slots: await fetchCalSlots(regionFor(timeZone)) });
  },
});
```

The widget reaches it at the origin the host hands the view, which is the dev port locally and the deployed origin inside ChatGPT or Claude:

```tsx theme={null}
const apiUrl = (path: string) => `${window.skybridge?.serverUrl ?? ""}${path}`;
const response = await fetch(apiUrl("/api/cal/slots"), { method: "POST", body });
```

## What the runtime adds

Four things arrive with every endpoint, so no app writes them:

|                  | What the runtime does                                                                                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **CORS**         | on by default, preflight included, advertising the methods `method` declares and no others                                                                               |
| **JSON body**    | `express.json()`, because the framework installs no parser of its own and `req.body` would be `undefined`                                                                |
| **method guard** | anything outside `method` gets a 405 and an `Allow` header, instead of reaching a handler written for a POST                                                             |
| **errors**       | a handler that throws answers JSON with the message, logged as `[waniwani] endpoint "/api/..." failed`, so a `fetch()` waiting on JSON never receives an HTML error page |

<ResponseField name="method" type="HttpMethod | HttpMethod[]">
  Restrict the endpoint to these methods. Leaving it off accepts every method.
</ResponseField>

<ResponseField name="cors" type="boolean">
  `false` opts out of CORS.
</ResponseField>

<ResponseField name="json" type="boolean">
  `false` opts out of the JSON body parser.
</ResponseField>

<ResponseField name="handler" type="RequestHandler">
  An Express handler. Throwing is safe: the runtime answers 500 and logs.
</ResponseField>

<Note>
  **Reach for a tool instead when the model is the caller.** An endpoint never shows up in `tools/list` and the model cannot see that it was called, so it costs the conversation nothing. That suits a calendar the widget paints for itself, and rules it out for anything the model has to reason about or quote back. See [Tools](/kit/tools).
</Note>

Endpoints share the process with `/mcp`, so `lib/` is one set of modules for both, and the build check prints what it mounted:

```text theme={null}
✓ Build check passed — 1 widget, 1 flow, 3 endpoints
  widget     show-book-call
  flow       demo-qualification
  api        /api/cal/book
  api        /api/cal/slots
  well-known /.well-known/openai-apps-challenge
```

## well-known/ is for the root of the domain

Some paths are not the app's to name. `/.well-known/openai-apps-challenge` proves to OpenAI that a deployment is yours; `security.txt` and `apple-app-site-association` answer to standards of their own. Whoever reads them looks at the root of the domain or nowhere, so `/api/` is not an option and neither is a config key.

`well-known/` is `api/` with a different prefix. It takes the same `defineEndpoint`, gets CORS, the method guard and the error envelope from the runtime, and the path still comes from the file's position:

```text theme={null}
well-known/openai-apps-challenge.ts   →  /.well-known/openai-apps-challenge
well-known/security.txt.ts            →  /.well-known/security.txt
```

The folder on disk has no dot. npm strips a `.`-prefixed directory out of a published tarball and the generator treats dotfiles as tooling rather than source, so a literal `.well-known/` would never reach the build. The dot goes back on when the URL is built.

A handler runs per request, which is what a value that differs per environment needs:

```ts well-known/openai-apps-challenge.ts theme={null}
import { defineEndpoint } from "@waniwani/kit";

export default defineEndpoint({
  method: "get",
  handler: (_req, res) => {
    const token = process.env.OPENAI_APPS_CHALLENGE_TOKEN;
    if (!token) return void res.status(404).json({ error: "not configured" });
    res.type("text/plain").send(token);
  },
});
```

The verifier compares the body byte for byte, and `res.send(string)` on its own would label it `text/html`, hence `res.type("text/plain")`. A 404 when the token is unset makes an unconfigured environment look unclaimed.

<Warning>
  Two names are refused: `oauth-authorization-server` and `oauth-protected-resource`. The framework serves those itself once an app configures OAuth, and an app's endpoints mount ahead of the framework's, so a file at either one would answer a client's discovery request with a body it cannot use. `waniwani check` says so by name.
</Warning>

On Vercel this needs no routing of its own. The reservation that forces a route for `/api/*` does not exist under `.well-known`, and the build writes no static file there, so the request misses the filesystem phase and the catch-all already in the tree carries it to the server. See [Deploy](/kit/deploy).


# Flows
Source: https://docs.waniwani.ai/kit/flows

A flow in a kit app is an @waniwani/sdk flow used unchanged. Default-export createFlow(...).compile() from flows/ and the runtime registers it as a tool.

A flow is an SDK primitive used unchanged. `createFlow(...).compile()` returns something the runtime registers directly, so everything the [SDK documents about flows](/sdk/flows/overview) applies here as written.

```ts flows/split-payment.ts theme={null}
import { createFlow, END, MemoryKvStore, START } from "@waniwani/sdk/mcp";

export default createFlow({ id: "split_payment", title, description, state })
  .addNode({
    id: "ask_amount",
    run: ({ interrupt }) => interrupt({ amount: { question: "How much is the basket?" } }),
  })
  .addNode({
    id: "show_plans",
    run: ({ state, showWidget }) =>
      showWidget({ tool: "select-plan", field: "selectedPlanId", data: { /* … */ } }),
  })
  .addEdge(START, "ask_amount")
  .addEdge("ask_amount", "show_plans")
  .addEdge("show_plans", END)
  .compile({ store: new MemoryKvStore() });
```

The tool name comes from the flow's `id`, so this one registers as `split_payment`. The filename only has to sit under `flows/`.

`showWidget({ tool: "select-plan" })` names a [widget](/kit/widgets) by its folder name, and the build check verifies that the folder exists. A typo fails `waniwani check` with the list of known widgets rather than a runtime error in a conversation.

## The store

`compile()` needs a store. `MemoryKvStore` keeps state in the process and is enough for local development. For production, pass one of the [KV store adapters](/sdk/flows/kv-store), or set `WANIWANI_API_KEY` in the app's `.env` to use the platform's hosted state. The env file is loaded before any module is imported, so a store built from `process.env` at the top of the file works; see [Deploy](/kit/deploy#secrets-and-environment-variables).

A flow whose store is missing fails the build check with the SDK's own message:

```text theme={null}
  flows/no-store.ts
  └ failed to load
    [waniwani] createFlow "no_store": no flow store configured. …
```

## Which SDK version an app gets

`@waniwani/sdk` is a peer dependency. The app's own `package.json` names the version, and the kit states only the floor underneath it, so an app that upgrades keeps that choice through every build. Nothing rewrites the range.

`waniwani init` writes the newest published SDK it can reach, capped with a caret, and falls back to the declared floor when npm is unreachable. Set `WANIWANI_OFFLINE=1` to skip the lookup entirely.

The SDK is 0.x, where a caret stops at the next minor. `^0.20.0` picks up 0.20.1 on the next install and never crosses to 0.21 on its own. When a newer minor is published, `waniwani check` says so and names the one-line edit. Taking it is the app's call, since under 0.x a minor is a breaking change.

## Further reading

<CardGroup>
  <Card title="Flow engine" icon="diagram-project" href="/sdk/flows/overview">
    Nodes, edges, interrupts and state, in the SDK docs.
  </Card>

  <Card title="Build a funnel" icon="filter" href="/sdk/guides/funnels">
    Complete `createFlow` recipes: sales, lead generation, booking, quotes.
  </Card>
</CardGroup>


# Folder convention
Source: https://docs.waniwani.ai/kit/folder-convention

Which folders @waniwani/kit reads, what each one becomes on the MCP server, and how tool names are derived from the filesystem.

```text theme={null}
oney/
├── waniwani.config.ts          defineApp({ name, title, overview })
├── tools/
│   └── check-eligibility.ts    export default defineTool({ ..., run })
├── widgets/
│   └── select-plan/
│       ├── widget.ts           export default defineWidget({ ..., data })
│       └── ui.tsx              export default function Component()
├── flows/
│   └── split-payment.ts        export default createFlow(...).compile()   ← SDK
├── api/
│   └── cal/slots.ts            export default defineEndpoint({ ..., handler })
├── well-known/
│   └── openai-apps-challenge.ts   ditto, served at the root of the domain
└── lib/                        anything else is just modules
```

Names come from the filesystem, verbatim. `tools/check-eligibility.ts` registers as `check-eligibility`, and `widgets/select-plan/` registers as `select-plan`. Nothing has to be listed in a registry, so no widget can sit defined and unwired.

| Folder                 | Becomes                                         | Notes                                                               |
| ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------- |
| `tools/<name>.ts`      | one MCP tool                                    | `.ts`, `.tsx` and `.mts` are picked up                              |
| `widgets/<name>/`      | one MCP tool plus a `ui://` resource            | needs `widget.ts` and `ui.tsx`                                      |
| `flows/<name>.ts`      | one MCP tool, registered from the SDK unchanged | whatever `.compile()` returns                                       |
| `api/<path>.ts`        | one HTTP endpoint at `/api/<path>`              | for the browser, invisible to the model                             |
| `well-known/<path>.ts` | the same endpoint at `/.well-known/<path>`      | for whoever asked the app to prove itself; the folder loses its dot |
| anything else          | plain modules                                   | the CLI leaves it alone                                             |

The app folder imports `@waniwani/kit`, plus `@waniwani/sdk` when it uses flows, and nothing else. Skybridge, transports and build configuration all stay outside it.

## Each folder in depth

<CardGroup>
  <Card title="App config" icon="gear" href="/kit/app-config">
    `waniwani.config.ts`: name, title, the overview the host reads at connect, search and tracking options.
  </Card>

  <Card title="Tools" icon="wrench" href="/kit/tools">
    One file per tool, with Zod shapes for input and output.
  </Card>

  <Card title="Widgets" icon="window" href="/kit/widgets">
    Why a widget is two files, and the hooks `ui.tsx` gets.
  </Card>

  <Card title="Flows" icon="diagram-project" href="/kit/flows">
    A compiled SDK flow, default-exported and registered as is.
  </Card>

  <Card title="Endpoints" icon="globe" href="/kit/endpoints">
    `api/` for the widget's own server calls, `well-known/` for the root of the domain.
  </Card>

  <Card title="Styling" icon="palette" href="/kit/styling">
    Tailwind utilities in `ui.tsx`, with the tokens coming from the template's stylesheet.
  </Card>
</CardGroup>

## What lives outside the folder

`.waniwani/` is build output, the way `.next/` is. Every command regenerates it and it stays out of git. Your `.env` and `.env.local` sit next to `waniwani.config.ts` and are read before any command runs; see [Deploy](/kit/deploy#secrets-and-environment-variables).


# What is the Kit?
Source: https://docs.waniwani.ai/kit/introduction

@waniwani/kit builds an MCP app from a folder. You write tools, widgets and flows; one CLI turns the folder into a deployable MCP server and owns every piece of plumbing.

`@waniwani/kit` builds an MCP app as a folder. You write tools, widgets and flows into a directory, and one CLI turns that directory into a deployable MCP server. Your repo holds none of the plumbing. The server bootstrap, the transport wiring and the build configuration live in the package.

Your side is the distribution MCP itself, meaning the tools, the widgets, the funnel and the content. The kit owns everything technical underneath it: the server, the transport, bundling, the deploy files, and keeping up with framework upgrades.

```text theme={null}
oney/                          # what you write
├── waniwani.config.ts
├── tools/check-eligibility.ts
├── widgets/select-plan/{widget.ts,ui.tsx}
└── flows/split-payment.ts

waniwani build                 # → .waniwani/, an ordinary npm project
```

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/kit/quickstart">
    Scaffold an app with `init` and have the dev server running in one command.
  </Card>

  <Card title="Folder convention" icon="folder-tree" href="/kit/folder-convention">
    Which folder becomes which MCP surface, and how names are derived.
  </Card>

  <Card title="Widgets" icon="window" href="/kit/widgets">
    Two files per widget, one schema for input, output and props.
  </Card>

  <Card title="Deploy" icon="cloud-arrow-up" href="/kit/deploy">
    Vercel, Docker or Alpic. The build writes the config, so deploying is a push.
  </Card>
</CardGroup>

## The three packages

Three packages ship under the `@waniwani` scope. The pair people mix up is the kit and the SDK, so start there.

|                     | What it is                                                                                                                                                                     | You use it when                                                                                                                                  |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`@waniwani/sdk`** | A **library**. Flows (typed state graphs that compile to one MCP tool), event tracking, knowledge base, chat widget. You supply the `McpServer`, the transport and the build.  | You already have an MCP server, or you want one you control down to the last line, and you want funnels, tracking or a knowledge base inside it. |
| **`@waniwani/kit`** | A **framework**. Folder convention, build CLI, shared server runtime. It owns the server, the transport, the bundler and the deploy files, so your repo can hold none of them. | You want to ship an MCP app and own no plumbing.                                                                                                 |
| **`@waniwani/cli`** | The **platform CLI**. `login`, `logout`, `switch`, `connect`. OAuth into Waniwani, bind a repo to a hosted agent, run against the hosted playground.                           | You want your local server wired to app.waniwani.ai.                                                                                             |

The SDK is documented under the [SDK tab](/sdk/introduction) and the platform CLI on [its own page](/sdk/cli/overview).

## Kit against SDK, in code

With the SDK, the server is a file you write and keep:

```ts src/server.ts theme={null}
// yours to maintain
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const server = new McpServer({ name: "oney", version: "1.0.0" });

server.registerTool(
  { name: "check-eligibility", title, description, inputSchema, annotations },
  async (input) => { /* … */ },
);
await flow.register(server);
await server.connect(new StreamableHTTPServerTransport(/* … */));
```

Around that file you also own a `tsconfig.json`, a bundler config for any widget UI, a `Dockerfile` and the deploy config each host wants.

With the kit, you write the part that answers the question and nothing around it:

```ts tools/check-eligibility.ts theme={null}
export default defineTool({ title, description, input, output, hints, run });
```

The kit finds that file, derives its tool name, registers it, bundles any widget that goes with it, and emits a deployable project. One copy of the plumbing exists, it lives in the package, and fixing it costs one publish plus a dependency bump per app.

The kit depends on the SDK, and the SDK knows nothing about the kit. Inside a kit app, `createFlow(...)` comes from the SDK, while `defineApp`, `defineTool`, `defineWidget` and the server that registers them come from the kit.

## What the kit gives you

* **Names from the filesystem.** `tools/check-eligibility.ts` registers as `check-eligibility`. Nothing is listed in a registry, so no widget can sit defined and unwired.
* **Failures surface at build time.** Structure is validated from the filesystem, then every server-safe module is imported for real. A flow that names a widget which does not exist fails the build instead of a request.
* **One runtime for every app.** Error envelopes, annotation defaults, the CSP block and tracking through `withWaniwani` sit in one place.
* **Leaving is one command.** `waniwani eject` writes the plumbing into your repo and steps out. See [Eject](/kit/eject).

## Next

Run through the [Quickstart](/kit/quickstart), or read the [folder convention](/kit/folder-convention) first if you would rather know the rules before typing.


# Quickstart
Source: https://docs.waniwani.ai/kit/quickstart

Scaffold an MCP app with `npx @waniwani/kit init`, or write the four files by hand: an app config, a tool, and a two-file widget.

```bash theme={null}
npx @waniwani/kit init oney
cd oney && npm run dev
```

`init` writes a folder that already answers: an app config, one tool, and the widget that displays what the tool returned. It installs, and the dev server is one command away. Running it inside an existing repo merges into that repo's `package.json` and `.gitignore` instead of replacing them.

## What init asks

In a terminal it asks three questions, arrow keys and Enter:

```text theme={null}
┌  A new MCP app
│
◇  App name
│  oney
│
◆  What should it come with?
│  ● A tool and a widget (the hand-off between them, wired up)
│  ○ Just a tool
│  ↑/↓ to navigate • Enter: confirm
└
```

The third question is where the app deploys (Vercel, Docker, Alpic, or "I don't know yet"). That answer decides the one config file the repo carries; see [Deploy](/kit/deploy).

Every question has a flag that answers it ahead of time, and a question whose answer is already in hand is skipped:

| Flag                                      | Answers                                                                                   |
| ----------------------------------------- | ----------------------------------------------------------------------------------------- |
| `--name <name>`                           | App name                                                                                  |
| `--minimal`                               | Just a tool, no widget                                                                    |
| `--host <vercel\|alpic\|container\|none>` | Where it deploys                                                                          |
| `--yes`                                   | Every default, no questions. Also what happens with no terminal to ask in: a pipe, or CI. |
| `--no-install`                            | Skip the install step                                                                     |
| `--force`                                 | Overwrite files that already exist                                                        |

Where the app lands follows the argument. `init oney` creates `oney/`, `init .` uses the current folder, and a bare `init` asks for a name and reads the answer as both: a name of its own creates `./<name>/`, while the offered default, your current folder's name, scaffolds in place.

## The same app, by hand

The rest of this page is what those files hold, written out. [examples/oney](https://github.com/WaniWani-AI/kit/tree/main/examples/oney) is the same app finished, if you would rather read it than type it.

<Steps>
  <Step title="Install">
    ```bash theme={null}
    mkdir oney && cd oney
    npm init -y
    npm i @waniwani/kit @waniwani/sdk react react-dom zod
    ```

    Set `"type": "module"` and the scripts:

    ```json package.json theme={null}
    {
      "type": "module",
      "scripts": {
        "check": "waniwani check",
        "dev": "waniwani dev",
        "build": "waniwani build",
        "start": "waniwani start"
      }
    }
    ```

    The kit asks for `@waniwani/sdk` 0.20 or later, React 19 and Zod 4 as peers.
  </Step>

  <Step title="Name the app and tell the model how to behave">
    ```ts waniwani.config.ts theme={null}
    import { defineApp } from "@waniwani/kit";

    export default defineApp({
      name: "oney",
      title: "Oney: split your payment",
      overview: `You help shoppers split a purchase into instalments with Oney.

    RULES:
    - Never quote a monthly amount yourself. Call check-eligibility and let it do the arithmetic.
    - Never list the plans in text. Show the select-plan widget and let it render them.`,
    });
    ```

    `overview` reaches the host LLM once, in the `initialize` handshake. It says what the app is and which tool to reach for when. How a single tool behaves goes in that tool's own `description`, which travels with every `tools/list`. The full option list is on [App config](/kit/app-config).
  </Step>

  <Step title="Write a tool">
    The filename becomes the tool name.

    ```ts tools/check-eligibility.ts theme={null}
    import { defineTool } from "@waniwani/kit";
    import { z } from "zod";
    import { buildPlans } from "../lib/plans.js";

    export default defineTool({
      title: "Check instalment eligibility",
      description:
        "Work out which instalment plans a basket qualifies for. Call this before showing any plans, and before quoting any figure.",
      input: {
        amount: z.number().positive().describe("Basket total in euros, e.g. 249.90"),
        country: z.enum(["FR", "ES", "PT"]).default("FR"),
      },
      output: {
        eligible: z.boolean(),
        plans: z.array(z.object({ id: z.string(), monthly: z.number(), fee: z.number() })),
      },
      hints: { readOnly: true },
      run: ({ amount, country }) =>
        amount < 50
          ? { eligible: false, plans: [] }
          : { eligible: true, plans: buildPlans(amount, country) },
    });
    ```

    `input` and `output` are Zod shapes, written as plain objects rather than `z.object({ … })`. `hints` becomes MCP annotations, with the runtime filling in the `title` that Claude's Connectors Directory requires. More on [Tools](/kit/tools).
  </Step>

  <Step title="Write a widget">
    The folder name becomes the tool name, and the widget takes two files.

    ```ts widgets/select-plan/widget.ts theme={null}
    import { defineWidget } from "@waniwani/kit";
    import { z } from "zod";

    const plan = z.object({
      id: z.string(),
      label: z.string().describe("Short label, e.g. '3×'."),
      monthly: z.number(),
      fee: z.number(),
    });

    export default defineWidget({
      title: "Choose an instalment plan",
      description:
        "Show the instalment plan picker. Call this once check-eligibility has returned plans, passing them straight through. The widget renders every figure itself: do NOT list the plans in text.",
      data: {
        amount: z.number(),
        plans: z.array(plan).describe("Plans returned by check-eligibility, unmodified."),
      },
      llmText: (data) =>
        `The picker is on screen with ${data.plans.length} plans. Wait for the user to pick one.`,
    });
    ```

    ```tsx widgets/select-plan/ui.tsx theme={null}
    import { useSendFollowUpMessage, useWidget } from "@waniwani/kit/web";
    import widget from "./widget.js";

    export default function SelectPlan() {
      const { data } = useWidget(widget);
      const sendFollowUp = useSendFollowUpMessage();
      if (!data) return <div className="font-sans text-ink-muted">Loading your plans…</div>;

      return (
        <div className="font-sans text-ink">
          {data.plans.map((plan) => (
            <button
              key={plan.id}
              type="button"
              onClick={() => sendFollowUp(`I'll take the ${plan.label} plan.`)}
            >
              {plan.label}: €{plan.monthly}/month
            </button>
          ))}
        </div>
      );
    }
    ```

    `widget.ts` is imported by the server and by the browser bundle, so it stays free of React and CSS. Why the split exists is on [Widgets](/kit/widgets).
  </Step>

  <Step title="Run it">
    ```bash theme={null}
    npm run dev
    ```

    `dev` watches the folder, mirrors changes into `.waniwani/`, and leaves nodemon and Vite HMR to do the rest. An edit to `tools/check-eligibility.ts` reaches the MCP endpoint in about a second. Point a client at `/mcp`, or open the dev server's root in a browser to call the tools without a chat client.
  </Step>
</Steps>

## Next

<CardGroup>
  <Card title="Folder convention" icon="folder-tree" href="/kit/folder-convention">
    Every folder the kit reads, and what each one becomes.
  </Card>

  <Card title="Flows" icon="diagram-project" href="/kit/flows">
    Drop a compiled SDK flow into `flows/` and it registers as a tool.
  </Card>

  <Card title="Commands" icon="terminal" href="/kit/commands">
    `check`, `dev`, `build`, `start` and the four stages they share.
  </Card>

  <Card title="Deploy" icon="cloud-arrow-up" href="/kit/deploy">
    What `git push` needs on Vercel, Docker and Alpic.
  </Card>
</CardGroup>


# Styling
Source: https://docs.waniwani.ai/kit/styling

Widgets are styled with Tailwind utility classes in ui.tsx. The design tokens and the dark variant come from the template's stylesheet, and no app-level CSS is bundled.

A widget styles itself with utility classes in its `ui.tsx`. There is no `styles.css` at any level of an app folder, and nothing imports one:

```tsx theme={null}
<span className="text-xs font-bold tracking-wide text-ink-muted dark:text-slate-400">
```

`text-ink-muted` comes from the distribution template's `src/index.css`, which is the Tailwind entry and the design system in one file:

```css src/index.css theme={null}
@import "tailwindcss";

/* The host hands the colour scheme to the view rather than to the browser, so
   `dark:` hangs off a class instead of `prefers-color-scheme`. */
@custom-variant dark (&:where(.dark, .dark *));

@theme {
  --font-sans: "Inter", system-ui, sans-serif;
  --color-ink: #0a1334;
  --color-ink-muted: #5a628a;
  --color-surface: #ffffff;
}
```

Every entry under `@theme` becomes a utility, so `--color-ink` gives you `text-ink` and `bg-ink`. Rebranding every app on the template is a matter of editing those four values in the template repo. The generator writes one import of that file into each `src/views/<widget>.tsx` entry, and since each view is its own bundle, Tailwind emits only the utilities that view's source uses.

## The dark class

A view is mounted alone in its own iframe, so there is no shared ancestor to hang the variant off. Each widget puts the class on its own root, driven by the theme the host reports:

```tsx theme={null}
import { useLayout } from "@waniwani/kit/web";

const { theme } = useLayout();
return <div className={theme === "dark" ? "dark" : ""}>…</div>;
```

## The stylesheet's origins

`src/index.css` pulls Inter from Google Fonts, and a host that enforces the widget CSP drops undeclared requests without erroring, so the font falls back and the widget looks subtly wrong. Codegen reads the origins off the stylesheet and the runtime merges them into every widget's `resourceDomains`, alongside whatever the widget declares itself. `fonts.googleapis.com` brings `fonts.gstatic.com` with it, since the second is only reachable by following the first.

## Why app-level CSS is refused

Tailwind v4 rejects `@apply` in any file that has not imported Tailwind itself:

```text theme={null}
Cannot apply unknown utility class `text-ink`. Are you using CSS modules or
similar and missing `@reference`?
```

Fixing that from an app folder means writing a `@reference` at a path into the generated tree, which does not exist in the author's own repo. One place for a class name beats two, so the build check names a stray `styles.css` rather than letting it sit there doing nothing:

```text theme={null}
  widgets/select-plan/styles.css
  └ app CSS is not bundled — nothing imports this file
    style with Tailwind utility classes in ui.tsx; the template's src/index.css
    carries the @theme tokens and the `dark` variant
```


# Tools
Source: https://docs.waniwani.ai/kit/tools

One file under tools/ is one MCP tool. defineTool takes a title, a description, Zod shapes for input and output, hints that become annotations, and a run function.

A file at `tools/<name>.ts` that default-exports `defineTool({ ... })` registers as the MCP tool `<name>`. Rename the file and the tool renames with it. `.ts`, `.tsx` and `.mts` are picked up.

```ts tools/check-eligibility.ts theme={null}
import { defineTool } from "@waniwani/kit";
import { z } from "zod";
import { buildPlans } from "../lib/plans.js";

export default defineTool({
  title: "Check instalment eligibility",
  description:
    "Work out which instalment plans a basket qualifies for. Call this before showing any plans, and before quoting any figure.",
  input: {
    amount: z.number().positive().describe("Basket total in euros, e.g. 249.90"),
    country: z.enum(["FR", "ES", "PT"]).default("FR"),
  },
  output: {
    eligible: z.boolean(),
    plans: z.array(z.object({ id: z.string(), monthly: z.number(), fee: z.number() })),
  },
  hints: { readOnly: true },
  run: ({ amount, country }) =>
    amount < 50
      ? { eligible: false, plans: [] }
      : { eligible: true, plans: buildPlans(amount, country) },
});
```

## Fields

<ResponseField name="title" type="string">
  Shown to humans in connector UIs.
</ResponseField>

<ResponseField name="description" type="string">
  LLM-facing. The only thing the model reads before deciding to call this, so it says when to call it and what not to do instead. A tool with no description fails the build check.
</ResponseField>

<ResponseField name="input" type="Shape">
  A Zod shape written as a plain object, `{ amount: z.number() }` rather than `z.object({ ... })`. `.describe()` on a field reaches the model as that argument's description. `run` receives the parsed value, typed off this shape.
</ResponseField>

<ResponseField name="output" type="Shape">
  The structured output schema, also a plain Zod shape. The runtime advertises it in `tools/list` and validates what `run` returns against it.
</ResponseField>

<ResponseField name="hints" type="ToolHints">
  Behavioural hints for the host LLM. The runtime translates them into MCP `annotations` and always fills in the `title` annotation that Claude's Connectors Directory requires.

  <Expandable title="hints">
    <ResponseField name="readOnly" type="boolean">
      The tool only reads. Defaults to `true` for widgets.
    </ResponseField>

    <ResponseField name="destructive" type="boolean">
      The tool can destroy data.
    </ResponseField>

    <ResponseField name="openWorld" type="boolean">
      The tool reaches out to the open internet.
    </ResponseField>

    <ResponseField name="idempotent" type="boolean">
      Calling twice with the same input has the same effect as calling once.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="run" type="(input) => ToolResult | Promise<ToolResult>">
  The handler. It may be async.
</ResponseField>

## What run can return

| Return                  | Becomes                                         |
| ----------------------- | ----------------------------------------------- |
| a string                | the model-facing text                           |
| a plain object          | `structuredContent`, plus a JSON text fallback  |
| a full `CallToolResult` | passed through, for the rare tool that needs it |

A `run` that throws returns an error envelope telling the host to offer a retry rather than invent a result, so exceptions are safe to let propagate.

## Writing the description

The `description` is what the model sees at the moment it is choosing a tool, so the starter template's version tells the model when to call it and what to avoid:

```ts theme={null}
description:
  "Find products matching what the shopper asked for. Call this before naming any product or quoting any price, and never answer either from memory. Pass the shopper's own words as the query.",
```

How the tools fit together across a conversation goes in the app's [`overview`](/kit/app-config) instead, which the host reads once at connect.

## Tool or endpoint

A tool appears in `tools/list` and costs a turn, and the model can reason about what came back. An [endpoint](/kit/endpoints) under `api/` is invisible to the model and is called by the widget itself from the browser. Reach for a tool when the model is the caller.


# Widgets
Source: https://docs.waniwani.ai/kit/widgets

A widget is a folder with two files: widget.ts holds the contract and ui.tsx the React component. One data schema serves as tool input, structured output and component props.

A folder at `widgets/<name>/` registers as the MCP tool `<name>` plus a `ui://` resource the host renders. It needs two files: `widget.ts`, which default-exports `defineWidget({ ... })`, and `ui.tsx`, which default-exports a React component.

```ts widgets/select-plan/widget.ts theme={null}
import { defineWidget } from "@waniwani/kit";
import { z } from "zod";

const plan = z.object({
  id: z.string(),
  label: z.string().describe("Short label, e.g. '3×'."),
  monthly: z.number(),
  fee: z.number(),
});

export default defineWidget({
  title: "Choose an instalment plan",
  description:
    "Show the instalment plan picker. Call this once check-eligibility has returned plans, passing them straight through. The widget renders every figure itself: do NOT list the plans in text.",
  data: {
    amount: z.number(),
    plans: z.array(plan).describe("Plans returned by check-eligibility, unmodified."),
  },
  llmText: (data) =>
    `The picker is on screen with ${data.plans.length} plans. Wait for the user to pick one.`,
});
```

```tsx widgets/select-plan/ui.tsx theme={null}
import { useLayout, useSendFollowUpMessage, useWidget } from "@waniwani/kit/web";
import widget from "./widget.js";

export default function SelectPlan() {
  const { data } = useWidget(widget);
  const sendFollowUp = useSendFollowUpMessage();
  const { theme } = useLayout();
  const root = theme === "dark" ? "dark" : "";

  if (!data) return <div className={`${root} font-sans text-ink-muted`}>Loading your plans…</div>;

  return (
    <div className={`${root} font-sans text-ink dark:text-slate-100`}>
      {data.plans.map((plan) => (
        <button
          key={plan.id}
          type="button"
          onClick={() => sendFollowUp(`I'll take the ${plan.label} plan.`)}
        >
          {plan.label}: €{plan.monthly}/month
        </button>
      ))}
    </div>
  );
}
```

## Why a widget is two files

`widget.ts` gets imported by the server and by the browser bundle, so it stays free of React and CSS. It carries one `data` schema, which serves as the tool's input schema, its structured output, and the type the component receives:

```tsx theme={null}
const { data } = useWidget(widget); // typed off `data`, no generated helpers
```

The usual approach puts `generateHelpers<AppType>()` in a shared file typed against the server, which makes a widget's type depend on the server's shape. Here the widget owns its own contract, so the two cannot drift.

`data` arrives as soon as the host has the tool input, which on most hosts happens before the server responds, so render optimistically and reach for `isReady` when you need the final value.

## Contract fields

<ResponseField name="title" type="string">
  Shown to humans in connector UIs, and used as the `title` annotation.
</ResponseField>

<ResponseField name="description" type="string">
  LLM-facing. When to show this widget, and how to frame it. The starter template's version tells the model what to say before calling and what not to repeat afterwards.
</ResponseField>

<ResponseField name="data" type="Shape">
  A plain Zod shape. Input schema, structured output and component props, all from this one definition.
</ResponseField>

<ResponseField name="hints" type="ToolHints">
  Same as on a [tool](/kit/tools#fields). `readOnly` defaults to `true` for widgets.
</ResponseField>

<ResponseField name="llmText" type="(data) => string">
  Text handed to the model alongside the rendered widget. Use it to say what the model should not repeat, and what it should wait for. Without it the runtime sends a default that tells the model the widget displays all the detail itself and to wait for the user to interact with it.
</ResponseField>

<ResponseField name="load" type="(input) => data | Promise<data>">
  Optional server-side loader, for widgets whose data comes from an API rather than from the model. Defaults to echoing the input through. A `load` that throws returns an error envelope telling the host something went wrong on your side and to offer a retry.
</ResponseField>

<ResponseField name="autoHeight" type="boolean">
  Let the host size the widget's frame to its content. A card whose height depends on its data is cut off or padded out by any fixed frame. Set it to `false` for a widget that renders its own scroll area.
</ResponseField>

<ResponseField name="csp" type="WidgetCsp">
  <Expandable title="csp">
    <ResponseField name="connectDomains" type="string[]">
      Domains the widget may `fetch()`.
    </ResponseField>

    <ResponseField name="resourceDomains" type="string[]">
      Domains the widget may load images, fonts and scripts from. The origins of the template's stylesheet are merged in for you; see [Styling](/kit/styling).
    </ResponseField>

    <ResponseField name="redirectDomains" type="string[]">
      Domains the widget may open externally without the host's safe-link confirmation.
    </ResponseField>
  </Expandable>
</ResponseField>

## Hooks in ui.tsx

Everything a component needs comes from `@waniwani/kit/web`.

| Hook                                                                             | What it gives you                                                          |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `useWidget(widget)`                                                              | `{ data, isLoading, isReady }`, typed off the widget's `data` shape        |
| `useWidgetState(initial)`                                                        | Per-widget state that survives re-renders and is handed back to the host   |
| `useSendFollowUpMessage()`                                                       | Send a message as the user, which is how a click moves the conversation on |
| `useCallTool()`                                                                  | Call one of the app's tools from the widget                                |
| `useLayout()`                                                                    | The host's layout, including `theme` for the `dark` class                  |
| `useDisplayMode()`, `useRequestSize()`, `useRequestModal()`, `useRequestClose()` | Ask the host to change how the widget is shown                             |
| `useOpenExternal()`, `useSetOpenInAppUrl()`                                      | Open links outside the host                                                |
| `useUser()`, `useFiles()`, `useDownload()`                                       | Read what the host shares about the user, and hand files back and forth    |
| `mountView`                                                                      | The entry the generator uses; you will not call it yourself                |

`useWidget().data` is the model's input until the server answers, so an `if (!data)` guard only covers the first paint. Guard on `isReady` for anything that must wait for `load()`.

## What a request does

```mermaid theme={null}
sequenceDiagram
    participant Host as ChatGPT / Claude
    participant Server as registerApp() (the shared runtime)
    participant App as your code

    Host->>Server: tools/call select-plan
    Server->>Server: validate against the widget's `data` schema
    Server->>App: load(input), optional
    App-->>Server: data
    Server->>Server: structuredContent + llmText + annotations
    Server-->>Host: result + ui:// resource
    Host->>Server: resources/read ui://widgets/.../select-plan.html
    Server-->>Host: HTML pointing at the built bundle
```

Every arrow that leaves `App` out is runtime code. Error envelopes, annotation defaults (including the `title` Claude's Connectors Directory requires), the "do not narrate the widget" instruction, the CSP block and tracking through `withWaniwani` all sit in one place, for every app.

## Calling from a flow

A [flow](/kit/flows) shows a widget by folder name, and the build check verifies that the folder exists:

```ts theme={null}
showWidget({ tool: "select-plan", field: "selectedPlanId", data: { /* … */ } })
```


# Connect your AI client
Source: https://docs.waniwani.ai/mcp-server/connect

Add the Waniwani MCP server to claude.ai, Claude Code, Cursor, or ChatGPT and sign in with your Waniwani account — no API keys.

Waniwani runs the MCP server in two regions. Add the URL for the region where your organization lives:

| Region | MCP URL                          |
| ------ | -------------------------------- |
| US     | `https://mcp.waniwani.ai/mcp`    |
| EU     | `https://eu.mcp.waniwani.ai/mcp` |

It's a remote MCP server (Streamable HTTP) that authenticates with OAuth 2.1. There is no API key to paste: you add the URL, your client opens a browser window, you sign in to Waniwani and approve the requested permissions. From then on the connection acts as *you* — same organizations, same role.

<Note>
  Each region is an independent stack with its own data. Sign in on the endpoint that matches your **data residency** — the region you chose when you [created your organization](/platform/regions). The US endpoint won't show organizations that live in the EU, and vice versa. The examples below use the US URL; if your data is in the EU, swap in `https://eu.mcp.waniwani.ai/mcp`.
</Note>

## Claude (claude.ai and desktop)

1. Open **Settings → Connectors**.
2. Click **Add custom connector**.
3. Enter `https://mcp.waniwani.ai/mcp` and confirm.
4. A Waniwani sign-in window opens — sign in and approve the permissions.

On Team and Enterprise plans, an admin may need to enable custom connectors for your workspace first.

## Claude Code

```bash theme={null}
claude mcp add --transport http waniwani https://mcp.waniwani.ai/mcp
```

Then run `/mcp` inside Claude Code and select **waniwani** to complete the browser sign-in.

## Cursor

Add the server to `~/.cursor/mcp.json` (or **Settings → MCP → Add new MCP server**):

```json ~/.cursor/mcp.json theme={null}
{
  "mcpServers": {
    "waniwani": {
      "url": "https://mcp.waniwani.ai/mcp"
    }
  }
}
```

Cursor prompts you to authenticate in the browser the first time it connects.

## ChatGPT

Custom MCP connectors require developer mode:

1. Open **Settings → Apps & Connectors → Advanced settings** and enable **Developer mode**.
2. Back in **Connectors**, click **Create** and enter `https://mcp.waniwani.ai/mcp`.
3. Complete the sign-in when prompted.

<Note>
  Client UIs change quickly. If a menu has moved, follow your client's own guide for adding a **remote MCP server** and use the URL above — the server implements the standard discovery flow, so any MCP-capable client that supports OAuth can connect.
</Note>

## What happens when you sign in

<Steps>
  <Step title="Your client discovers Waniwani">
    The client reads the server's metadata and learns which Waniwani stack handles sign-in for that region (`app.waniwani.ai` for US, `eu.app.waniwani.ai` for EU). It registers itself automatically — no manual client IDs.
  </Step>

  <Step title="You sign in to Waniwani">
    The browser opens your usual Waniwani login. If you're already signed in, you go straight to consent.
  </Step>

  <Step title="You approve the permissions">
    The consent screen itemizes exactly what the connection may do (read environments and analytics, create environments and keys, and so on). You only see permissions your account is entitled to.
  </Step>

  <Step title="Connected">
    The client receives a token bound to this server and your approved permissions. Every call it makes runs under your identity.
  </Step>
</Steps>

## First thing to try

> Who am I signed in to Waniwani as, and what can you do for me here?

Your client will call the server's `whoami` and `search` tools and report your account, your organizations, and the available operations. From there, ask for what you want in plain language — see [the overview](/mcp-server/overview) for example prompts.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The consent screen shows fewer permissions than I expected">
    That's by design. The permission list is narrowed to what your account is entitled to — for example, internal Waniwani staff permissions never appear for customer accounts. Approve what's shown; it's everything available to you.
  </Accordion>

  <Accordion title="Calls suddenly fail with an authentication error">
    Your token expired or was invalidated. Most clients refresh automatically; if yours doesn't, disconnect and reconnect the server (re-running the sign-in) to mint a fresh token.
  </Accordion>

  <Accordion title="I can't switch to another organization (NOT_ORG_MEMBER)">
    `set_active_org` only switches to organizations you belong to — the API rejects anything else with a `NOT_ORG_MEMBER` error. Ask *"who am I?"* — the `whoami` tool lists the organizations you can act on and their ids.
  </Accordion>

  <Accordion title="I switched organizations in the dashboard, but this connection still uses the old one">
    Expected. Each connection carries its own active organization, independent of the dashboard — switching in one place doesn't switch the other. Ask the model to switch here too (it calls `set_active_org`), or check where you stand with *"who am I?"*.
  </Accordion>

  <Accordion title="The model says an operation doesn't exist">
    The available surface is curated and grows over time. Ask the model to run `search` again — it returns the live catalog with exact signatures. If what you need isn't there yet, tell us.
  </Accordion>
</AccordionGroup>


# How it works
Source: https://docs.waniwani.ai/mcp-server/how-it-works

Four tools, OAuth scopes, org context, and sandboxed execution: what happens between your prompt and the Waniwani API.

The server is deliberately small: four tools that compose, rather than one tool per API endpoint.

## The four tools

| Tool             | What it does                                                                                                                                                |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `whoami`         | Returns your identity: user id, granted permissions, the organizations you can act on, and which one is active.                                             |
| `set_active_org` | Switches your active organization for subsequent calls. Membership is enforced server-side.                                                                 |
| `search`         | Lists the Waniwani API operations available to `execute`, with full TypeScript signatures — inputs *and* response shapes. Takes an optional keyword filter. |
| `execute`        | Runs a short piece of JavaScript in an isolated sandbox. The code calls operations as `api.<name>(input)` and returns a value.                              |

## The loop

A request like *"give me a digest of activity for the last 7 days"* plays out as:

1. The model calls `search("analytics")` and reads the typed signatures.

2. It writes a snippet and calls `execute`:

   ```js theme={null}
   const envs = await api.listEnvironments();
   // arguments elided — `search` returns the exact signatures
   const summaries = await Promise.all(
     envs.map((env) => api.getEnvironmentAnalytics(/* ... */)),
   );
   return summaries;
   ```

3. The returned data lands back in the conversation, and the model writes your digest.

Because `execute` runs real code, the model can chain, filter, and aggregate in a single round trip instead of stitching together a dozen separate tool calls. Top-level `await` is supported, and whatever the snippet `return`s comes back as the tool result.

## Org context

Operations run against your **active organization**:

* When you first connect, it starts as the organization you last used in the dashboard.
* `set_active_org` switches it, and the switch is enforced server-side: you can only activate organizations you belong to.
* The switch applies to **this connection only**. The dashboard and any other connected clients each keep their own active organization, so driving Waniwani from your AI client never silently moves your browser session — or vice versa.
* It takes effect on your next call: the server invalidates the connection's current token and your client silently refreshes into the new organization.

`whoami` always tells you where you currently stand.

## Permissions: scopes and consent

When you connect, the consent screen itemizes the connection's permissions as OAuth scopes:

| Scope                      | Grants                                                                           |
| -------------------------- | -------------------------------------------------------------------------------- |
| `orgs:read` / `orgs:write` | See your organizations and membership / invite members                           |
| `mcp:read` / `mcp:write`   | Read environments and analytics / create environments and API keys               |
| `kb:read` / `kb:write`     | Read / write the knowledge base *(operations not yet exposed through `execute`)* |

Two properties worth knowing:

* **You only see what you're entitled to.** The consent screen narrows the list to your account's role — permissions reserved for Waniwani staff never appear for customer accounts.
* **Scopes are enforced on every API call, server-side.** The MCP server doesn't get to be generous: each `api.*` operation is re-checked against your token's scopes and your org membership by the Waniwani API itself.

## Security model

* **OAuth 2.1, no API keys.** You sign in through `app.waniwani.ai` — the same login as the dashboard. The token your client receives is bound to this server specifically and to the scopes you approved.
* **The sandbox never sees your token.** Code submitted through `execute` runs in an isolated sandbox that can reach only the curated `api.*` operations. Your credentials are attached to outbound API calls *outside* the sandbox — code running inside it has no way to read or exfiltrate them.
* **Every call is your call.** All operations execute under your identity with your permissions. The connection can do nothing your account can't do in the dashboard.
* **Stateless by design.** The server keeps no session state and stores no conversation content; each request is authenticated independently by your token. Disconnecting the server from your client severs its access.

## Limits worth knowing

* The exposed operation surface is curated and grows over time — `search` is the source of truth, not this page.
* The active organization is per-connection: switching it here doesn't affect the dashboard or other connected clients, and switching in the dashboard doesn't affect this connection.
* Long or heavy aggregations should be scoped (a date range, a single environment): `execute` snippets run within a bounded execution window.


# Waniwani MCP server
Source: https://docs.waniwani.ai/mcp-server/overview

Connect Claude, Cursor, or ChatGPT to the Waniwani platform and drive it from a conversation — environments, API keys, analytics digests, session breakdowns.

The Waniwani MCP server lets your AI client operate the Waniwani platform for you. Add the server URL for your region, sign in with your Waniwani account, and ask for the things you would otherwise click through the dashboard for.

## Server URL

Use the URL for the region your organization's data lives in — the region you chose when you created the organization:

<CodeGroup>
  ```text US theme={null}
  https://mcp.waniwani.ai/mcp
  ```

  ```text EU theme={null}
  https://eu.mcp.waniwani.ai/mcp
  ```
</CodeGroup>

If you sign in to the dashboard at `app.waniwani.ai`, use the **US** URL. If you sign in at `eu.app.waniwani.ai`, use the **EU** URL. Each region is an independent stack: the US endpoint won't show organizations that live in the EU, and vice versa. See [Regions & data residency](/platform/regions) for how residency is set, and [Connect your AI client](/mcp-server/connect) for the per-client setup.

<Note>
  This is **Waniwani's own MCP server** — the one that drives *the platform*. It is not the MCP funnel server you build with the SDK. Everywhere else in these docs, "your MCP server" means the one you ship to your users; this tab is about the one we host for you.
</Note>

## What you can ask it

* "Give me a digest of activity across my environments for the last 7 days."
* "Create a new environment called *staging* and hand me its API key."
* "Which sessions hit production yesterday? Where did people drop off?"
* "What sources are sending events to my production environment?"
* "Compare this week's activity to last week's across all my environments."
* "Invite [jane@acme.com](mailto:jane@acme.com) to our organization."

## What it can do

| Category                    | Examples                                                                                             |
| --------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Environments & API keys** | List your environments, create one, issue an environment's API key                                   |
| **Analytics & sessions**    | Activity summaries over a date range, funnel flow breakdowns, per-session drill-downs, event sources |
| **Organization**            | Check who you're signed in as, switch your active org, invite a teammate                             |

The surface grows over time, so this table stays deliberately coarse. The server's own `search` tool is the live catalog: once connected, ask *"what Waniwani operations are available?"* and your client will list every operation with its exact signature.

## How you use it

1. [Connect your client](/mcp-server/connect) — add the URL above, sign in, approve the permissions. No API keys involved.
2. Ask in plain language. The model discovers the right operations and calls them with your identity — every call is permission-checked server-side.
3. Results come back into the conversation.

Everything the connection can do is bounded by your own Waniwani account: your organizations, your role, the permissions you approved at sign-in. The mechanics are on [How it works](/mcp-server/how-it-works).


# Submit to the ChatGPT Plugin Store
Source: https://docs.waniwani.ai/platform/guides/chatgpt/overview

Start here to list your Waniwani-built MCP server in the ChatGPT Plugin Store: pick whether Waniwani submits on your behalf or you submit from your own OpenAI account, and see what each path costs you.

Listing your app in the ChatGPT Plugin Store means filling a long form at [platform.openai.com/plugins](https://platform.openai.com/plugins) and passing OpenAI's review. The first decision is who runs that form.

## Who runs the submission

|                                  | Waniwani submits for you                                             | You submit yourself                                                   |
| -------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Who fills the form               | Waniwani, from a seat in your organization                           | You                                                                   |
| OpenAI account                   | Yours, created before anything else starts                           | Yours                                                                 |
| Identity verification            | Yours to complete, and it can take days                              | Same                                                                  |
| Access we need                   | An invite to your org with "Apps Management" set to Write            | None                                                                  |
| "Developer" shown on the listing | Your company                                                         | Your company                                                          |
| Where the plugin entry lives     | Your OpenAI organization                                             | Your OpenAI organization                                              |
| What you spend time on           | The account setup, the invite, and one asset handover                | The same setup, plus eleven tabs, tool justifications, and test cases |
| Pick this when                   | You want the listing out without anyone internally learning the form | Someone on your side wants to own the submission end to end           |

The listing ends up in your OpenAI organization under your company name on both paths, and the assets you prepare are identical. What changes is who sits in the form. Waniwani drafts your tool justifications, test cases, and starter prompts either way.

<CardGroup>
  <Card title="We submit for you" icon="handshake" href="/platform/guides/chatgpt/we-submit">
    From an empty OpenAI account to a submitted plugin: what you set up, what you invite us to, what you send, and what we do with it.
  </Card>

  <Card title="You submit yourself" icon="store" href="/platform/guides/chatgpt/you-submit">
    The full tab-by-tab checklist for the form: account setup, MCP, tool justification, test cases, screenshots, compliance.
  </Card>
</CardGroup>

## Yours either way

These stay on your side whichever path you take:

* **An OpenAI organization** with a verified developer or business identity. Verification can take days, so start it early.
* **Privacy policy and terms of service**, live on your domain and reachable without a login.
* **A monitored support channel.** Reviewers may test it.

## Check eligibility first

Confirm your app clears the [two hard eligibility limits](/platform/guides/overview#two-hard-eligibility-limits): no moving money or crypto inside the conversation, and no AI generation of images, video, or audio.

<Note>
  Submitting the form does not guarantee a listing. OpenAI reviews every plugin, and approval is separate from going live: once a plugin is approved, someone still has to publish it from the plugins portal.
</Note>

<CardGroup>
  <Card title="Tool justification template" icon="shield-check" href="/platform/guides/templates/tool-justification">
    Every tool's annotations and justification text, laid out before the form opens.
  </Card>

  <Card title="Test cases template" icon="list-check" href="/platform/guides/templates/test-cases">
    The 5 positive and 3 negative cases reviewers run against your app.
  </Card>

  <Card title="Claude submission" icon="plug" href="/platform/guides/claude">
    Listing the same app in Claude's Connectors Directory.
  </Card>

  <Card title="After you submit" icon="chart-line" href="/platform/guides/post-submission">
    Drive traffic to your listing once it is live.
  </Card>
</CardGroup>


# Waniwani submits for you
Source: https://docs.waniwani.ai/platform/guides/chatgpt/we-submit

The managed path for a ChatGPT Plugin Store listing, from an empty OpenAI account onward: create the organization, verify identity, invite Waniwani, hand over the assets, and we fill and submit the form from inside your org.

The app is agreed and ready, so this page is what happens next. Two things are yours: setting up an OpenAI organization and giving us access to it, then handing over the assets. We do the rest from inside your organization, which is why the listing, the Developer name, and the plugin entry all belong to you.

Assume you have no OpenAI account today. Part 1 starts there.

## Part 1: your OpenAI organization

Do these in order. Business verification has to be submitted before you send any invite, because an unverified organization does not carry the permissions an invited seat needs. Verification also takes the longest, so start it the day you read this.

<Steps>
  <Step title="Create the account and organization">
    Sign up at [platform.openai.com](https://platform.openai.com). Use an address your company controls, such as a shared or role mailbox, since this account will own the plugin listing for as long as it exists. One organization per company is enough.
  </Step>

  <Step title="Submit business verification, before anything else">
    OpenAI blocks plugin submission until the organization has a **verified developer or business identity**, so submit individual or business verification from your organization settings as soon as the account exists. It can take days and sometimes asks for documents.

    <Warning>
      Send this before you invite anyone. Invites issued from an unverified organization do not come with the access we need, and redoing them after verification clears wastes a round trip.
    </Warning>
  </Step>

  <Step title="Invite Waniwani into the organization">
    Once verification is submitted and the organization shows as verified, invite the addresses your Waniwani contact gives you under [Settings → Organization → People](https://platform.openai.com/settings/organization/people). The seat needs a role with the **"Apps Management"** permission set to **"Write"**, which is what the plugin form checks. Roles are configured at [organization roles](https://platform.openai.com/settings/organization/people/roles).

    We only need that permission. Nothing about your API keys, billing, or usage is part of this.
  </Step>

  <Step title="Tell us when both are done">
    Message us once verification has cleared and the invite is accepted. We check we can reach the plugins portal in your org before you spend time on Part 2.
  </Step>
</Steps>

## Part 2: what you send us

Send it in one batch to your Waniwani contact, or to [contact@waniwani.ai](mailto:contact@waniwani.ai). Anything missing blocks the submission, so it is worth doing in one pass.

<Steps>
  <Step title="Two logos, light and dark">
    PNG, square, one light-mode version and one dark-mode version. Leave off borders and rounded corners, since ChatGPT applies circular cropping itself. The icon needs enough contrast to read on a dark background.
  </Step>

  <Step title="Listing copy">
    Four fields, all public:

    * **Name.** The customer-facing product or workflow name.
    * **Subtitle.** 30 characters maximum, and the limit is strict. Describe what the app does in plain words; marketing language gets flagged.
    * **Description.** Two to three sentences on what the app does and why someone wants it, then three to five bullets of key capabilities. Factual, no hype. See [how to structure it](/platform/guides/chatgpt/you-submit#writing-the-description).
    * **Category.** One of ChatGPT's predefined categories, matching your primary function.

    Send it in English (US) at minimum. If you want other locales, send a translated subtitle and description per locale.
  </Step>

  <Step title="Four live URLs">
    * **Website.** The root URL, since deep links get flagged.
    * **Support.** A monitored URL or email address. Reviewers may test it.
    * **Privacy policy.** A live page on your domain.
    * **Terms of service.** Same.

    Open each one in a private browser window before sending. A privacy policy that 404s or asks for a login is an immediate rejection, and it is the failure we see most often.
  </Step>

  <Step title="Three decisions">
    * **Regional availability.** All [ChatGPT-supported countries](https://help.openai.com/en/articles/7947663-chatgpt-supported-countries), or a specific list. Restrict it if your service only operates in certain regions.
    * **Commerce.** If your app touches purchasing, tell us what you sell and where the transaction completes. For regulated products such as insurance, the chat shows a quote estimate and the user is redirected to your site to finalize.
    * **Release notes.** One short paragraph describing this version. It may be shown publicly.
  </Step>
</Steps>

## Your checklist

* [ ] OpenAI account created on a company-controlled address
* [ ] Business verification submitted and cleared, before any invite goes out
* [ ] Waniwani invited afterwards, with "Apps Management" set to Write
* [ ] Verification and invite acceptance confirmed to us
* [ ] Light and dark PNG logos, square, no borders
* [ ] Name, 30-character subtitle, description, category
* [ ] Translations per extra locale, if any
* [ ] Website, support, privacy policy, and terms URLs, each verified in a private window
* [ ] Regional availability decided
* [ ] Commerce flow described, if applicable
* [ ] Release notes written

## What we do next

1. We create the plugin in your organization and enter your production MCP server URL, authentication, and content security policy on the MCP tab.
2. We complete domain verification and run the tool scan. OpenAI issues a token that has to sit at `/.well-known/openai-apps-challenge` on the challenge host. We host it ourselves on a `waniwani.run` domain, and when the host is yours we send you the token to serve at that exact path, where it stays for the whole review.
3. We fill every remaining tab: Info, Skills, Prompts, Testing, Global, Submit.
4. We send you everything we produced for your sign-off: the [tool justifications](/platform/guides/templates/tool-justification), the [test cases](/platform/guides/templates/test-cases), the starter prompts, the recording, and the screenshots. Check them against how the app behaves, since reviewers run the test cases live against it.
5. We submit, and OpenAI's review begins. Reviewer questions come to us first, and we come back to you only when the answer is yours to give.
6. On approval, nothing appears in the store until you give the go-ahead. Publishing is a separate step and we take it on your word.

None of this becomes your problem:

* Deploying your app at a stable versioned MCP URL.
* Tool annotations and CSP metadata in the server code.
* Domain verification and the tool scan.
* The demo recording and the widget screenshots, produced to OpenAI's specs and sent to you for approval.
* Reviewer demo credentials, if your app requires sign-in. We prepare an account a reviewer can use without MFA, SMS codes, email confirmation, or private-network access, since an auth flow with extra confirmation steps is one a reviewer cannot finish.
* The first draft of your tool justifications, test cases, and starter prompts.
* The eleven tabs of the form, and the back and forth during review.

<Note>
  Everything sits in your organization, so you keep the plugin entry whatever happens to our working relationship. Remove our seat and the listing stays where it is, editable by your own team. The [self-serve guide](/platform/guides/chatgpt/you-submit) is the same form, documented tab by tab, if you ever take it over.
</Note>

<CardGroup>
  <Card title="The form, tab by tab" icon="store" href="/platform/guides/chatgpt/you-submit">
    What we fill in on your behalf, and the guide to follow if you take the form over yourself.
  </Card>

  <Card title="Claude submission" icon="plug" href="/platform/guides/claude">
    Anthropic requires the final submit from an Owner of your own Claude workspace, so that one works differently.
  </Card>
</CardGroup>


# Submit from your own OpenAI account
Source: https://docs.waniwani.ai/platform/guides/chatgpt/you-submit

A tab-by-tab checklist for listing your Waniwani-built MCP server as a plugin in the ChatGPT Plugin Store yourself: account setup, MCP server, tool justification, test cases, starter prompts, screenshots, and policy compliance.

This guide covers everything you need to list your MCP server as a plugin in the ChatGPT Plugin Store when someone on your side runs the form. Most of the engineering work (server, versioning, tool annotations) is already handled. Your job is to prepare the assets and decisions below, then put them into the form.

You create the plugin at [platform.openai.com/plugins](https://platform.openai.com/plugins) and fill in a form split across tabs: **Info → MCP → Skills → Prompts → Testing → Global → Submit**. This guide follows that order, with a short setup section first. OpenAI's own walkthrough is at [Submit plugins](https://learn.chatgpt.com/docs/submit-plugins).

<Note>
  Waniwani can [fill and submit this form for you](/platform/guides/chatgpt/we-submit) instead. You still create the OpenAI organization and verify its identity, then invite us to a seat with "Apps Management" set to Write, and we take the form from there.
</Note>

<Warning>
  Submitting the form does not guarantee a listing. OpenAI reviews every plugin, and the **Tool justification** and **Test cases** sections are where most rejections happen, so give them the most attention.
</Warning>

## Before you start: OpenAI account and access

Sort these out before you open the form, or you will be blocked at the first tab.

* **Apps Management role.** The account that submits needs the **"Apps Management"** permission set to **"Write"** in your organization role. Check it under [Platform → organization roles](https://platform.openai.com/settings/organization/people/roles).
* **Verified identity.** You need a **verified developer or business identity** in the OpenAI Platform. Complete individual or business verification in your organization settings first; verification can take time, so start early.
* **Public URLs live.** Website, support contact, privacy policy, and terms of service must be publicly reachable (see [Plugin info](#3-info-tab-plugin-info) below).
* **Reviewer credentials.** If your plugin requires sign-in, prepare **demo credentials** that work for a reviewer **without MFA, SMS, email confirmation, or private-network access**. Reviewers cannot complete an auth flow that has extra confirmation steps.

### Creating the plugin

1. Go to [platform.openai.com/plugins](https://platform.openai.com/plugins) and select **Create plugin**.
2. Choose a submission type:

   * **Skills only.** A package of reusable workflows, no MCP server.
   * **With MCP.** A plugin backed by your MCP server, either MCP-only or MCP plus skills.

   For a Waniwani-built plugin, choose **With MCP**. Skills are optional (see the [Skills tab](#5-skills-tab-optional)).

## 1. MCP tab: server, versioned and deployed

The form requires a stable production MCP Server URL, entered on the **MCP** tab.

1. Go to [app.waniwani.ai/mcp](https://app.waniwani.ai/mcp) and confirm your app is listed.
2. Use the dropdown next to your app to copy its production MCP URL.
3. Verify it follows the versioned pattern, for example `https://v1.<your-app>.mcp.waniwani.run/mcp`.
4. On the MCP tab, enter the URL, configure authentication, set the content security policy, then complete domain verification and select **Scan Tools** so OpenAI can read your tool definitions.

<Warning>
  **Domain verification is a common blocker.** OpenAI generates a verification token that must be served at a specific well-known path on your challenge host:

  `https://<challenge-base-host>/.well-known/openai-apps-challenge`

  Plan for this step in advance rather than discovering it mid-form. If you are a managed Waniwani customer, coordinate the timing with us so we can host the token at that path together.
</Warning>

<Note>
  Before you run **Scan Tools**, make sure tool responses contain no secrets, undisclosed user fields, or unnecessary personal data. Reviewers inspect the scanned tool output. For managed Waniwani apps this is handled in the server code.
</Note>

## 2. Logo: light and dark versions

Provide two versions of your plugin's icon.

* **Format:** PNG.
* **Shape:** square. Do not add borders or rounded corners; ChatGPT applies circular cropping automatically.
* One **light mode** version and one **dark mode** version.

## 3. Info tab: plugin info

Prepare these fields in advance. Use the **customer-facing product or workflow name**, and make sure every URL matches your verified publisher identity.

| Field                    | Requirements                                                                                                                                                       | Example                           |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- |
| **Name**                 | Your plugin's display name. How users find and recognize it. Keep it short and on-brand.                                                                           | `Your Plugin Name`                |
| **Subtitle**             | Short, plain-language phrase. **30 characters max** (the limit is strict, count carefully). Describe the function in plain words; marketing language gets flagged. | `Find the best deals near you`    |
| **Description**          | Clear description of what the plugin does and why people want it. Concrete value, no exaggerated or misleading claims. Appears publicly.                           | See guidance below                |
| **Category**             | One of ChatGPT's predefined categories. Pick the one matching your primary function.                                                                               | `Finance`                         |
| **Developer**            | Your company name, shown publicly on the listing.                                                                                                                  | `Your Company`                    |
| **Website URL**          | Your main company or product website. Use the root URL (deep links get flagged) and make sure it loads cleanly.                                                    | `https://yourcompany.com`         |
| **Support URL or Email** | A working, monitored channel. Reviewers may test it.                                                                                                               | `support@yourcompany.com`         |
| **Privacy Policy URL**   | A live, publicly accessible page. Confirm it in a private window: if it 404s or needs a login, it is rejected.                                                     | `https://yourcompany.com/privacy` |
| **Terms of Service URL** | A live, publicly accessible page (same check as above).                                                                                                            | `https://yourcompany.com/terms`   |
| **Demo Recording URL**   | A video showing your plugin working across all main use cases and tools.                                                                                           | A public YouTube or Loom link     |

### Writing the description

Structure it like this:

1. **Opening paragraph:** what the plugin does and the value it provides (two to three sentences).
2. **"What you can do with \[Plugin Name]":** three to five bullet points of key capabilities.
3. Keep it factual and user-centric, and avoid hype.

For tone and length, study how live plugins write theirs, for example [Compare the Market](https://chatgpt.com/apps/compare-the-market/asdk_app_69a41e8393c48191bf5b3ecfb7963af9), [Aviva](https://chatgpt.com/apps/aviva/asdk_app_69a6eb598b4c8191b10712ed489e8e11), and [Tuio](https://chatgpt.com/apps/tuio/asdk_app_6970fc7c958881918cfa39d58fc37e82).

### Recording the demo

The video must cover all main use cases and tools across every platform you support (web, iOS, Android). A practical recipe:

1. Record several runs of the plugin working across different scenarios.
2. Stitch them into one video, one scenario after another.
3. Speed it up to at least 2x. The point is for a reviewer to see what the plugin does quickly.

### If your plugin involves commerce

You will be asked to confirm your purchasing flow and to describe the products you intend to sell. For regulated products such as insurance, be transparent that you help users get a **quote estimate**: if they like it, they are redirected to your website to finalize. Do not present a "final price" inside the chat.

## 4. Tool justification (critical step)

This is the hardest part and the most common reason for rejection. For **every tool** your MCP server exposes, OpenAI requires three annotation hints, each with a written justification. If they are not set, OpenAI assumes the worst defaults: `readOnlyHint = false`, `openWorldHint = true`, `destructiveHint = true`.

| Annotation      | Question it answers                                                  | Values   |
| --------------- | -------------------------------------------------------------------- | -------- |
| **Read Only**   | Does this tool only read data without modifying anything?            | Yes / No |
| **Open World**  | Does this tool call an external API or service outside your control? | Yes / No |
| **Destructive** | Can this tool delete, overwrite, or irreversibly modify data?        | Yes / No |

For each annotation on each tool, the form wants a short written justification explaining why the value is accurate. Tools that touch external services may also need CSP metadata (`connect_domains`, `resource_domains`).

Use the [Tool justification template](/platform/guides/templates/tool-justification) to lay out every tool, its annotation values, and the justification text before you open the form. For managed Waniwani apps, the annotations and CSP metadata are set in the server code for you, and you receive the justifications pre-filled to review and paste.

## 5. Skills tab (optional)

Skills are self-contained, reusable workflow packages. You can submit **skills only** (no MCP server) or bundle skills alongside your plugin. If you have no skills to ship, leave this tab empty.

* Upload the final **skill bundle** with a tested file structure.
* Confirm the bundle works end to end before uploading. A broken bundle is a rejection.

For most Waniwani-built plugins you can skip this tab; talk to us if you want to package workflows as skills.

## 6. Prompts tab: starter prompts

Provide specific **starter prompts** that demonstrate your plugin's key workflows. These are the example prompts ChatGPT surfaces to users.

* Make each prompt concrete and adaptable. "Find pet insurance for a 3-year-old labrador" works; "Help me with insurance" is too generic to demonstrate anything.
* Cover your main tools and use cases, matching the positive test cases below.

## 7. Testing tab: 5 positive and 3 negative test cases

OpenAI reviewers run these to validate your plugin, and they are reviewed carefully.

* **At least 5 positive cases:** scenarios where the plugin should trigger and work. For each, the form asks for the scenario, the user prompt, which tools fire, and the expected output.
* **At least 3 negative cases:** prompts where the plugin should **not** trigger. For each, the form asks for the scenario and the prompt.

Lay them out first with the [Test cases template](/platform/guides/templates/test-cases).

<Note>
  If your plugin requires sign-in, provide the **reviewer demo credentials** here (or where the form asks for them). They must let a reviewer complete every test case **without MFA, SMS, email confirmation, or private-network access**.
</Note>

## 8. Global tab: regional availability

Decide whether the plugin is worldwide or restricted.

* **All countries:** available in every [ChatGPT-supported country](https://help.openai.com/en/articles/7947663-chatgpt-supported-countries).
* **Specific countries:** list them. Restrict if your service only operates in certain regions or the content is only relevant there.

## 9. Translations and locale

Parts of the form must be in English.

* **English (US)** is always required as the base locale.
* You can add other locales (for example français, español, Deutsch). For each, provide a translated **Subtitle** and **Description**.
* ChatGPT may auto-translate some fields, but your own translations ensure quality.

## 10. Screenshots

Provide screenshots of your plugin's widgets in action.

* **Format:** PNG.
* **Width:** 706px. **Height:** minimum 400px, recommended maximum 860px.
* At least 1 screenshot at 2x (retina quality), maximum 4.
* Each screenshot needs an example user message that would produce what's shown.
* The first three appear on install views and are reused across sizes and locales, so lead with your strongest states.

## 11. Submit tab: policy compliance and release notes

On the final **Submit** tab you confirm that your plugin:

* Complies with [OpenAI's Terms](https://openai.com/policies/connectors-actions-terms/) and [Submission Guidelines](https://developers.openai.com/apps-sdk/app-developer-guidelines), which you have reviewed.
* Complies with applicable industry laws and regulations.
* Does **not** initiate or execute money, crypto, or investment transfers.
* Does **not** serve or display advertisements.
* Uses third-party content and API endpoints you have the rights to.
* Is **not** designed for or marketed to children under 13, and you confirm it is suitable for 13+ or 18+.

You also provide **Release Notes**, a required field that may be shown publicly, then attest that everything is accurate.

<Note>
  Approval is not the same as going live. After OpenAI approves your plugin, you choose **when to publish** from the plugins portal; the listing appears in the ChatGPT Plugin Store only once you publish it.
</Note>

## Summary checklist

* [ ] "Apps Management" role set to Write, and developer/business identity verified
* [ ] Reviewer demo credentials that work without MFA/SMS/email confirmation
* [ ] Versioned MCP server deployed and reachable
* [ ] Domain verified at `/.well-known/openai-apps-challenge`, tools scanned
* [ ] Light and dark PNG logos (square, no borders)
* [ ] All plugin info fields prepared (mind the 30-character subtitle limit)
* [ ] Tool annotations set in the server with written justifications
* [ ] Skill bundle uploaded, if applicable
* [ ] Starter prompts written
* [ ] 5 positive and 3 negative test cases written
* [ ] Regional availability decided
* [ ] English base locale, plus translations if needed
* [ ] Screenshots (PNG, 706px wide, 400 to 860px tall, max 4)
* [ ] Demo recording ready
* [ ] Privacy Policy and Terms of Service URLs live
* [ ] Commerce disclosures prepared, if applicable

<CardGroup>
  <Card title="Tool justification template" icon="shield-check" href="/platform/guides/templates/tool-justification">
    Lay out every tool's annotations and justification text before you open the form.
  </Card>

  <Card title="Test cases template" icon="list-check" href="/platform/guides/templates/test-cases">
    The 5 positive and 3 negative cases, ready to fill in.
  </Card>

  <Card title="Have Waniwani submit instead" icon="handshake" href="/platform/guides/chatgpt/we-submit">
    Set up the org, invite us to a seat, hand over the assets once, and the form stops being your problem.
  </Card>

  <Card title="After you submit" icon="chart-line" href="/platform/guides/post-submission">
    Drive traffic to your listing once it is live.
  </Card>
</CardGroup>


# Submit to the Claude Connectors Directory
Source: https://docs.waniwani.ai/platform/guides/claude

How to list your Waniwani-built MCP app in Claude's Connectors Directory: the Team/Enterprise prerequisite, what to prepare in advance, and a step-by-step walkthrough of the in-product submission portal.

This guide takes you from zero to a submitted app in Claude's [Connectors Directory](https://claude.com/docs/connectors/building/submission). Apps built on Waniwani have most of the engineering handled (server, tool annotations, assets); your job is to meet one prerequisite, prepare a handful of assets, and walk through the portal.

<Warning>
  **You submit from your own Claude account.** Unlike ChatGPT, where Waniwani can submit on your behalf if you prefer, Anthropic's in-product portal requires your own **Claude Team or Enterprise** organization and an Owner of it. Waniwani prepares the server, annotations, assets, and the wording for every field; the final submit happens from your workspace.
</Warning>

## Before you start

Submission happens inside [claude.ai](https://claude.ai), not an external form. To reach the portal you need a Team or Enterprise organization (admin settings are not available on individual or Pro plans).

* [ ] Create a **Claude Team** (or Enterprise) organization at [claude.ai](https://claude.ai).
* [ ] Make sure the person submitting is an **Owner or Primary Owner**. Only Enterprise orgs can delegate this through a custom role with the *Directory management* permission; Team plans keep it with Owners.
* [ ] Find the portal at **Settings → "Your MCP servers" (Beta) → "Submit a server"** (direct link: `https://claude.ai/admin-settings/directory/submissions/new`).

Once approved, the connector appears at [claude.ai/directory](https://claude.ai/directory) for other Claude organizations to install.

## What to prepare

The portal is a wizard of about 11 steps (Introduction, Connection, Tools, Listing, Use cases, Company, Authentication, Data handling, Test and launch, Compliance, Review). Your progress is saved in the browser, but you can only have one submission open at a time, so gather everything below before you start.

### Production MCP server URL

The submission needs a stable production MCP Server URL over HTTPS.

1. Go to [app.waniwani.ai/mcp](https://app.waniwani.ai/mcp) and confirm your app is listed.
2. Use the dropdown next to your app to copy its production MCP URL.

### Tool annotations

This is the most common reason for rejection. Annotations must be set in the server code **before** submission. For managed Waniwani apps they are set for you; see the [Tool justification template](/platform/guides/templates/tool-justification) for what each value means.

What Claude enforces:

* **Every tool needs a `title`** plus the correct hint (`readOnlyHint: true` for reads, `destructiveHint: true` for writes/deletes). These control Claude's auto-permission behavior.
* **Read/write separation.** A single tool may not combine safe reads (GET/HEAD/OPTIONS) with writes (POST/PUT/PATCH/DELETE). Catch-all tools are rejected.
* **Tool names of 64 characters or fewer**, with descriptions that accurately state what the tool does and when it runs (reviewers test against real behavior).
* **Freeform or custom-query tools** (that accept caller-built endpoints, query strings, or bodies) must name or link the target API in their description.
* **No prompt-injection-style instructions** in descriptions. Describe what the tool does, not how Claude should behave. No hidden, encoded, or behavior-overriding directives.

<Warning>
  Put the annotations inside the `annotations` object, not at the top level. Set `annotations.title` plus `annotations.readOnlyHint: true` for read-only tools, or `annotations.destructiveHint: true` for tools that write or delete. A top-level `title` alone still trips a "Missing annotations: title" error on the Tools step.
</Warning>

### Listing copy

Claude's character limits differ from ChatGPT's.

| Field           | Requirements                                                | Notes                                                                                                                                         |
| --------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**        | Your connector's display name                               | Max 100 characters. Short, recognizable, on-brand.                                                                                            |
| **Slug**        | URL identifier, prefilled from the name                     | **Permanent after submission.** Lowercase letters, numbers, and hyphens only.                                                                 |
| **One-liner**   | A short phrase describing function and value                | Max 200 characters (the form calls this "One-liner"). Avoid marketing language.                                                               |
| **Description** | What the app does and why users value it. Appears publicly. | Max 2,000 characters. Factual, user-centric, no hype.                                                                                         |
| **Categories**  | The 1 to 5 categories matching your primary function        | The label is **Financial Services** (not "Finance"). Insurance or health apps may also fit **Consumer Health** or **Health & Life Sciences**. |
| **Icon**        | Optional custom icon URL                                    | A URL field, not a file upload. SVG and PNG both work. Preview with the **Check icon** button.                                                |

Claude listings are much shorter than ChatGPT's: a tight one-liner plus a sentence or two, not a multi-paragraph blurb. Model yours on live consumer-facing listings with interactive widgets, such as **Era Context** ("Manage your personal finances using Claude") or **Booking.com** ("Find hotels, homes and more"), and note how short the copy is.

### Icon

The icon is an optional custom icon URL in the Listing step. Leave it blank and the directory falls back to your MCP server's favicon.

* SVG works (verified on a live submission); PNG works too. A square asset renders most consistently.
* The favicon fallback often renders dark-on-dark and disappears. Set a contrast-safe custom icon URL and preview it with the **Check icon** button.
* Design guidance is in the [MCP Apps for Claude Figma file](https://www.figma.com/community/file/1597641111449594397/mcp-apps-for-claude).

### Screenshots

Most MCP apps ship interactive widgets, so screenshots are required (a tool-only server with no UI skips this step). Hard requirements:

* **Format:** PNG (no video or GIF).
* **Width:** at least 1000px.
* **Count:** 3 to 5 images.
* **Crop to the app response only.** Do not include the prompt or Claude's chat chrome.
* **Aspect ratio:** any, kept consistent across the set.
* Provide the prompt text separately for each screenshot.
* No separate mobile assets; one batch covers all surfaces.

What to capture:

* Lead with your highest-value widget state (the populated quote card, the storefront answer, the analytics view), not an empty or loading state.
* Show populated data using the same fully-populated test account you give reviewers. No lorem ipsum.
* Use 3 to 5 distinct moments that tell a flow (answer, then personalized quote, then confirmation) rather than near-identical frames.
* Capture the widget at its natural rendered size so text stays legible at 1000px or wider.
* Avoid PII or real customer data; use representative seed data.

### Public URLs

All three must be live and public at review time.

| Asset                    | Requirement                                                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Documentation URL**    | Public setup and usage docs, live by submission. A help-center article, a blog post, or a page in these docs all work.               |
| **Privacy Policy URL**   | A live, publicly accessible HTTPS page covering what data is collected, why, who sees it, retention, user control, and contact info. |
| **Support URL or email** | A monitored support channel. Required in the Listing step.                                                                           |

<Warning>
  A missing or incomplete privacy policy is an immediate rejection. Open each URL in a private window to confirm it loads without a login.
</Warning>

### Company and contact details

Because you submit from your own org, the listing's company details are **yours**, not Waniwani's.

* [ ] Organization name and details.
* [ ] A primary contact on a working, monitored channel (reviewers may reach out).

## The form, step by step

Work through the wizard in order. Two quirks to know up front:

* **Re-selecting the connector resets fields.** Re-verify everything after any reconnect.
* **One submission at a time.** The wizard behaves like a single session; state is saved in the browser, but you cannot have more than one form submission open at once.

### Connection

Paste your production MCP URL. Set **URL configuration** to **Universal URL** (everyone connects to the same URL). This is correct in almost every case. Only use **Multiple URLs** (a fixed list) or **URL pattern** (a regex, for per-tenant or versioned subdomains) if you are specifically instructed to.

### Tools

Tools, prompts, and resources sync automatically from your server URL. If your annotations are set correctly (see [What to prepare](#tool-annotations)), this step passes on its own.

<Accordion title="Redeploying the app does not refresh the tools">
  The portal reads tools from your cached custom-connector schema. If you change the MCP app, reconnect or refresh the custom connector on claude.ai: open it in another tab and refresh the connector you are submitting for.
</Accordion>

### Listing

Paste the [listing copy](#listing-copy) you prepared: name, slug, one-liner, description, categories, icon URL, and support URL. Remember the slug is **permanent after submission**, and preview the icon with the **Check icon** button.

### Use cases

The Use cases step asks for:

* **Primary use cases:** the main tasks users accomplish, with a few example prompts.
* **Connection requirements:** what accounts, permissions, or setup a user needs before connecting.
* **Read / write capabilities:** a radio (Read only / Write only / Read and write).

<Warning>
  The read/write radio is validated against your tool annotations. Choosing "Read only" while any tool is annotated as a write or destructive triggers an error. Match it to your tools.
</Warning>

### Company

Enter your organization's details and primary contact (see [Company and contact details](#company-and-contact-details)).

### Authentication

In almost every case a Waniwani MCP app needs **no authentication**, so pick *No authentication* unless told otherwise.

<Accordion title="Rare case: the app needs user authentication">
  If your connector accesses **private user data**, Claude requires **OAuth 2.0**. The Authentication step offers several modes: OAuth with Dynamic Client Registration (DCR), OAuth with a Client ID Metadata Document (CIMD), OAuth with Anthropic-held client credentials, custom URL/credentials at connection time, and no authentication, plus a "Partial auth" toggle.

  * With **DCR** (clients self-register, as Waniwani-hosted servers do) there is nothing to register; the form shows it is supported out of the box.
  * For **CIMD, Anthropic-held, or static-client** modes, register the redirect URI `https://claude.ai/api/mcp/auth_callback`.
</Accordion>

### Data handling

* [ ] **API ownership:** confirm your server calls first-party APIs (or legitimately proxied services). The MCP server domain should match your service domain.
* [ ] **Sensitive data:** flag any sensitive data your tools touch.
* [ ] **External links:** declare allowed link URIs (HTTPS origins or custom URI schemes you own). Third-party or unowned schemes are removed during review.

### Test and launch

Reviewers must be able to exercise every tool end to end. In most cases no special instructions are needed.

<Accordion title="Rare case: a test account is needed">
  If a test account is required, we recommend stating that one will be provided on request, so you do not need it ready at submission, only when a reviewer asks.

  * Provide **fully populated** credentials when asked (empty accounts are rejected).
  * Provide step-by-step access instructions detailed enough to reach and run every tool.
  * Confirm every tool runs end to end via MCP Inspector or as a custom connector in Claude.
</Accordion>

### Compliance

Review and acknowledge all of Anthropic's policies (the Software Directory Terms and Policy, and the connector directory guidelines).

<Note>
  Anthropic does not support connectors that execute financial asset transfers (money or crypto) or perform AI image, video, or audio generation. Design tools that produce diagrams or charts are fine.
</Note>

### Review and submit

* [ ] Resolve any quality warnings shown on the Review step.
* [ ] Submit.

Submitting does not guarantee a listing.

## Common rejection reasons

* Missing tool titles or annotations.
* Behavioral instructions embedded in tool descriptions.
* A missing or incomplete privacy policy.

## References

* [Submitting to the Connectors Directory](https://claude.com/docs/connectors/building/submission)
* [Pre-submission checklist and review criteria](https://claude.com/docs/connectors/building/review-criteria)
* [Connectors Directory FAQ](https://support.claude.com/en/articles/11596036-anthropic-connectors-directory-faq)
* [Submission portal](https://claude.ai/admin-settings/directory/submissions/new)

<CardGroup>
  <Card title="Tool justification template" icon="shield-check" href="/platform/guides/templates/tool-justification">
    Lay out every tool's annotations before you submit.
  </Card>

  <Card title="ChatGPT submission" icon="store" href="/platform/guides/chatgpt/overview">
    Listing the same app in the ChatGPT Plugin Store.
  </Card>

  <Card title="After you submit" icon="chart-line" href="/platform/guides/post-submission">
    Drive traffic to your app once it is live.
  </Card>

  <Card title="Connect a client" icon="plug" href="/mcp-server/connect">
    Add the Waniwani MCP server to Claude, Cursor, or ChatGPT.
  </Card>
</CardGroup>


# Submit your app to ChatGPT and Claude
Source: https://docs.waniwani.ai/platform/guides/overview

How to list an MCP app built on Waniwani in the ChatGPT Plugin Store and Claude's Connectors Directory: prerequisites, who submits each one, and what each review needs.

Once your app is built and deployed on Waniwani, the next step is getting it listed in the assistant directories so people can find and install it. There are two directories today: the **ChatGPT Plugin Store** and **Claude's Connectors Directory**. This section walks through what each one needs and gives you copy-pasteable templates for the parts reviewers scrutinize most.

<Note>
  A listing is never guaranteed. Both OpenAI and Anthropic review every app for quality and policy, and they may follow up with questions. These guides get you through review with the fewest surprises, but completing a form is not the same as being approved.
</Note>

## Who submits

Both directories publish the listing under your company name, from an account your organization owns. What differs is who is allowed to sit in the form:

|                                        | ChatGPT Plugin Store                                                       | Claude Connectors Directory                                     |
| -------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Who submits                            | You, or Waniwani from a seat we are invited to in your OpenAI organization | You, from your own Claude organization (required by Anthropic)  |
| Account you need                       | An OpenAI organization with a verified developer or business identity      | A Claude **Team or Enterprise** workspace, with you as an Owner |
| Where the listing's "Developer" points | Your company                                                               | Your company                                                    |

For ChatGPT, the choice is yours: [submit yourself](/platform/guides/chatgpt/you-submit) or [invite us in and have Waniwani handle the mechanics](/platform/guides/chatgpt/we-submit). For Claude, Anthropic requires the listing to come from the app owner's own workspace, so the final submit always happens on your side. In both cases Waniwani prepares everything you paste in.

## What both directories require

Prepare these before you start either form. They are common to both reviews:

<Steps>
  <Step title="A versioned, production MCP server URL">
    The form needs a stable HTTPS MCP URL. Find yours at [app.waniwani.ai/mcp](https://app.waniwani.ai/mcp): your apps are listed there, and the dropdown next to each one copies its production URL. It follows a versioned pattern, for example `https://v1.<your-app>.mcp.waniwani.run/mcp`.
  </Step>

  <Step title="Correct tool annotations in the server">
    Every tool needs accurate hints (read-only, destructive, and for ChatGPT also open-world) plus a written justification. This is the single most common reason apps get rejected. See the [Tool justification template](/platform/guides/templates/tool-justification). For managed Waniwani apps these are set in the server code for you before submission.
  </Step>

  <Step title="A live privacy policy and support channel">
    Both reviews require a publicly accessible privacy policy URL and a monitored support URL or email. Open each link in a private browser window to confirm it loads without a login. A missing or gated privacy policy is an immediate rejection.
  </Step>

  <Step title="A public documentation URL">
    Claude requires a live documentation URL at review time, and it helps your ChatGPT listing too. These submission guides themselves can serve as your documentation URL if you do not have a dedicated page yet.
  </Step>

  <Step title="Listing copy and a logo">
    A name, a short tagline, a description, and a square logo (a contrast-safe icon that reads on dark backgrounds). The exact limits differ per directory and are covered in each guide.
  </Step>
</Steps>

## Two hard eligibility limits

Both assistants reject the same two categories of app, so confirm yours does neither inside the chat:

* **No moving money or crypto inside the conversation.** Handing the user off to your own site to finish a purchase is fine. Showing a quote or an estimate is fine.
* **No AI generation of images, video, or audio.** Tools that produce diagrams or charts are fine.

## Pick your path

<CardGroup>
  <Card title="ChatGPT submission" icon="store" href="/platform/guides/chatgpt/overview">
    Pick who runs the Plugin Store submission, then follow that path: what you prepare, or the full tab-by-tab form checklist.
  </Card>

  <Card title="Claude submission" icon="plug" href="/platform/guides/claude">
    The Connectors Directory flow: Team/Enterprise prerequisite, the in-product portal, annotations, and listing details.
  </Card>

  <Card title="After you submit" icon="chart-line" href="/platform/guides/post-submission">
    Submitting is the start. How to drive traffic to your app and capture it: agent on your site, GEO, and PR.
  </Card>

  <Card title="Templates" icon="copy" href="/platform/guides/templates/tool-justification">
    Copy-pasteable tool justification and test-case templates for the parts reviewers check hardest.
  </Card>
</CardGroup>


# After you submit: drive traffic to your app
Source: https://docs.waniwani.ai/platform/guides/post-submission

Submitting your app is the start, not the finish. The three levers that get traffic to your app and capture it: putting the agent on your website, GEO, and PR, plus the KPIs to track.

Getting listed is the start, not the finish. Today, ChatGPT and Claude do **not** suggest apps proactively: your app shows up when the assistant searches the web and finds content saying it exists and how to use it. So once you are submitted, the real work is to **drive traffic to the app** and **capture that value on your own site**. This page explains what to do, in what order, and how to measure it.

## The two milestones

1. **Traffic on the app** inside ChatGPT and Claude: installs, conversations, and the quotes or leads it generates.
2. **Traffic on the agent on your website:** sessions, leads captured, and conversion compared to your classic funnel.

## The three levers

| Lever                             | What it is for                                                                                                                |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Put the agent on your website** | Capture value where you control the experience, without depending on the assistant's recommendation.                          |
| **Do GEO**                        | Make the assistants aware the app exists so they suggest it when a user asks.                                                 |
| **Do PR and comms**               | Create third-party corroboration (assistants weigh information that appears across several sources) and drive direct traffic. |

### Lever 1: put the agent on your website

The fastest way to capture leads is to run the same agent on your own site, where you control the experience and do not depend on an assistant surfacing your app. The Waniwani [chat widget](/sdk/chat/embed) embeds the agent on any page. This is the highest-leverage step, so do it first.

### Lever 2: GEO (generative engine optimization)

GEO is the practice of publishing content that teaches assistants your app exists and how to install it, so they describe it correctly and suggest it when relevant.

It works. We ran a controlled experiment on an app with zero starting authority (NA Drink Finder, an independent ChatGPT app) on a brand-new domain, with no other marketing input, just content: 74 GEO-optimized articles over 33 days, with 1,881 prompts tracked across ChatGPT, Perplexity, and Google AI Overview.

| Metric                                                              | Before | After                                   |
| ------------------------------------------------------------------- | ------ | --------------------------------------- |
| ChatGPT describes the app correctly as a ChatGPT app                | 4.5%   | 45.7% (10x)                             |
| Hardest case: prompts where the app name is **not** in the question | 0%     | about 30%                               |
| ChatGPT wrongly describes it as a mobile app                        | 40.9%  | 17.1%                                   |
| ChatGPT denies the ChatGPT app exists                               | 4.5%   | 0%                                      |
| Install syntax `@AppName` present in the answer                     | 0%     | up to 50% of answers citing our content |

The takeaway: before GEO, ChatGPT did not suggest the app, described it as a mobile app, or said it did not exist. After publishing content, it described the app correctly **and** explained how to install it. Answers citing our content described the app correctly 2.3x more often.

Read the full write-up at [waniwani.ai/research/chatgpt-app-geo-experiment](https://waniwani.ai/research/chatgpt-app-geo-experiment).

### Lever 3: PR and comms

Comms has two goals: create third-party corroboration and generate direct traffic. A reusable plan for a launch:

1. **Press release** (under 500 words, with a "first" or "new" angle, your site URL, and your app URL).
2. **Pitch one reference industry publication** (one trade outlet beats ten generic tech blogs).
3. **LinkedIn:** one post from the company page and one personal post from the founder (personal posts reach further).
4. **Email** your prospect and partner base announcing the launch.
5. **A results post at day 30 or 60** ("we generated X quotes through ChatGPT in one month"). This is highly citable and creates a second wave of content.

A strong angle compounds: the first live insurance app on ChatGPT got picked up by industry press precisely because "first" is newsworthy. Find the equivalent "first" or "new" angle for your category.

## KPIs to track

**The app (ChatGPT and Claude)**

| KPI                                                           | Source                       |
| ------------------------------------------------------------- | ---------------------------- |
| App installs                                                  | OpenAI / Anthropic dashboard |
| Sessions and conversations on the app                         | Waniwani                     |
| Quotes or leads generated via the app                         | Waniwani                     |
| Redirects to the website (UTM)                                | Your analytics               |
| Share of tracked prompts where the assistant mentions the app | Waniwani (GEO)               |
| Answer quality (app described correctly, install flow given)  | Waniwani (GEO)               |
| Citation rate of your content                                 | Waniwani (GEO)               |

**The agent on your website**

| KPI                                                                             | Source                 |
| ------------------------------------------------------------------------------- | ---------------------- |
| Sessions on the agent                                                           | Waniwani               |
| Funnel: visitors, engaged (more than 1 prompt), email captured, qualified leads | Waniwani               |
| Email capture rate                                                              | Waniwani               |
| Conversion vs the classic form funnel                                           | Waniwani and your data |

## What to expect

Set expectations early: the assistants will not surface your app on day one. Treat the weeks after launch as an ongoing program rather than a single event. Review the KPIs above on a regular cadence (a bi-weekly check-in works well), and let the data point you at which lever to push next.

<CardGroup>
  <Card title="Embed the agent" icon="code" href="/sdk/chat/embed">
    Put the same agent on your website with the chat widget.
  </Card>

  <Card title="Tracking and analytics" icon="chart-line" href="/sdk/tracking/overview">
    The sessions, events, and funnel metrics behind these KPIs.
  </Card>
</CardGroup>


# Test cases template
Source: https://docs.waniwani.ai/platform/guides/templates/test-cases

A copy-pasteable template for the ChatGPT Plugin Store test-case step: the 5 positive cases where your app should trigger and the 3 negative cases where it should not.

OpenAI reviewers run your test cases to validate your app, so this section is reviewed carefully. You need at least **5 positive** cases (where the app should trigger and work) and at least **3 negative** cases (where it should not). Lay them out here before you open the form, then paste each value in.

<Note>
  For managed Waniwani apps you receive these pre-filled based on your app's tools and behavior. Review them to confirm they match how your app actually works before submitting.
</Note>

## Positive test cases (minimum 5)

Scenarios where your app **should** trigger and work correctly. For each, the form asks for the scenario, the user prompt, which tools fire, and the expected output.

| # | Scenario                      | User prompt (paste into form)      | Tools triggered | Expected output            |
| - | ----------------------------- | ---------------------------------- | --------------- | -------------------------- |
| 1 | What the user is trying to do | The exact prompt a user would type | `tool_name`     | What the app should return |
| 2 |                               |                                    |                 |                            |
| 3 |                               |                                    |                 |                            |
| 4 |                               |                                    |                 |                            |
| 5 |                               |                                    |                 |                            |

Add rows for any additional use cases worth covering.

## Negative test cases (minimum 3)

Prompts where your app should **not** trigger. These confirm your app does not activate inappropriately. For each, the form asks for the scenario and a prompt.

| # | Scenario             | User prompt (paste into form)      | Why the app should NOT trigger |
| - | -------------------- | ---------------------------------- | ------------------------------ |
| 1 | An unrelated request | A prompt outside your app's domain | Why this is out of scope       |
| 2 |                      |                                    |                                |
| 3 |                      |                                    |                                |

## Writing good test cases

* **Positive cases should be realistic.** Use prompts a real user would actually type, phrased naturally, not keyword-stuffed prompts engineered to trigger the app.
* **Cover distinct paths.** Spread the five across different tools and use cases rather than five variations of the same request.
* **Negative cases should be plausibly nearby.** The strongest negatives are requests in an adjacent area where the app should stay quiet, not random unrelated prompts. They show the app has well-defined boundaries.
* **Match the expected output to reality.** Reviewers run these against your live app, so describe what it genuinely returns.

<CardGroup>
  <Card title="Back to ChatGPT submission" icon="store" href="/platform/guides/chatgpt/overview">
    Where this template fits in the full checklist.
  </Card>

  <Card title="Tool justification template" icon="shield-check" href="/platform/guides/templates/tool-justification">
    The other section reviewers check hardest.
  </Card>
</CardGroup>


# Tool justification template
Source: https://docs.waniwani.ai/platform/guides/templates/tool-justification

A copy-pasteable template for the ChatGPT Plugin Store tool-annotation step: list every tool, its read-only / open-world / destructive values, and the written justification reviewers require.

The tool-annotation step is the most common reason a ChatGPT submission is rejected. For **every tool** your MCP server exposes, OpenAI requires three annotation values and a written justification for each. This page gives you a template to lay them all out before you open the form, and a reference for what each value means.

<Note>
  For managed Waniwani apps, the annotations are already set in the server code and you receive these justifications pre-filled to review and paste. This template is for laying them out yourself or for checking that the prepared values match what your app actually does.
</Note>

## How to use this

1. Add one row per tool to the table below.
2. Fill the Yes/No values to match how each tool behaves (use the reference at the bottom if unsure).
3. Write a one or two sentence justification for each value, stating plainly why it is accurate.
4. When the form scans your server, confirm the values it shows match this table, then paste your justifications.

## Tool annotations

Copy this table and fill one row per tool:

| Tool name     | Read Only | Read Only justification    | Open World | Open World justification   | Destructive | Destructive justification  |
| ------------- | --------- | -------------------------- | ---------- | -------------------------- | ----------- | -------------------------- |
| `tool_name_1` | Yes / No  | Why this value is accurate | Yes / No   | Why this value is accurate | Yes / No    | Why this value is accurate |
| `tool_name_2` | Yes / No  | Why this value is accurate | Yes / No   | Why this value is accurate | Yes / No    | Why this value is accurate |
| `tool_name_3` | Yes / No  | Why this value is accurate | Yes / No   | Why this value is accurate | Yes / No    | Why this value is accurate |

Add or remove rows so the count matches your server exactly.

## CSP metadata

If any tool interacts with external services, list its domains:

| Tool name     | Connect domains       | Resource domains      |
| ------------- | --------------------- | --------------------- |
| `tool_name_1` | `api.yourcompany.com` | `cdn.yourcompany.com` |

## What each annotation means

| Annotation      | Question                                                                                 | Set to **Yes** when                                                                              | Set to **No** when                                                                                                             |
| --------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| **Read Only**   | Does this tool only read data without modifying anything?                                | The tool only fetches or displays data; nothing is created, updated, or deleted.                 | The tool creates, updates, or deletes any data.                                                                                |
| **Open World**  | Does the tool interact with an open world of external entities, or is its domain closed? | The tool calls an external API or service the user defines (a web search, an arbitrary backend). | The tool only uses local data, renders UI with no external calls, or uses pre-approved internal APIs fully under your control. |
| **Destructive** | Can this tool delete, overwrite, or irreversibly modify data?                            | The tool can delete records, overwrite data, or cause irreversible changes.                      | The tool only reads or creates new data without modifying or deleting existing records.                                        |

<Note>
  If the annotations are not set, OpenAI assumes the worst defaults: `readOnlyHint = false`, `openWorldHint = true`, `destructiveHint = true`. That is why setting and justifying them accurately matters. For more background, see the [MCP tool annotations post](https://blog.modelcontextprotocol.io/posts/2026-03-16-tool-annotations/).
</Note>

<CardGroup>
  <Card title="Back to ChatGPT submission" icon="store" href="/platform/guides/chatgpt/overview">
    Where this template fits in the full checklist.
  </Card>

  <Card title="Test cases template" icon="list-check" href="/platform/guides/templates/test-cases">
    The other section reviewers check hardest.
  </Card>
</CardGroup>


# What is Waniwani?
Source: https://docs.waniwani.ai/platform/introduction

Waniwani turns AI assistants like ChatGPT and Claude into a channel you can show up in, convert from, and measure.

People used to start with a search engine. Now they ask ChatGPT, Claude, and other AI assistants — and they act on what those assistants tell them. That shift moves the first, most important moment of your funnel out of your website and into a conversation you don't control.

**Waniwani is how you show up in that conversation, turn it into a customer, and measure what happened.**

## What Waniwani does

Instead of a static page a person reads, Waniwani lets you publish a guided, multi-step experience that runs *inside* the assistant. The assistant asks the right questions, captures the answers, branches on what it learns, and walks the person all the way to a booking, a quote, a signup, or a qualified lead — without ever leaving the chat.

You get the three things a channel needs to matter:

* **Presence** — be discoverable and citable when an assistant answers questions in your space.
* **Conversion** — run real funnels in the conversation, not just a link out to your site.
* **Measurement** — see which assistants drive sessions, where people drop off, and what converts.

## How it fits together

Waniwani is built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), the open standard AI assistants use to connect to outside tools and data. Connecting your funnel to an assistant is the same kind of integration as connecting any other MCP tool — so the same experience works across every MCP-capable assistant at once.

There's an open-source SDK for building the experience, a hosted platform for state, analytics, and content, and a managed MCP server that exposes it to assistants. You'll find each of those in its own section.

## Where to go next

This page is the high-level picture. The rest of the docs go deep:

* **SDK** — build and ship your funnels.
* **MCP Server** — connect Waniwani to ChatGPT, Claude, and other assistants.
* **[Regions & data residency](/platform/regions)** — pick EU or US when you create an organization.


# Regions & data residency
Source: https://docs.waniwani.ai/platform/regions

Waniwani runs in two regions — EU and US. You pick where an organization's data lives when you create it, and everything for that org stays on that stack.

Waniwani runs in **two regions**, EU and US. Each is an independent stack with its own database: an organization's data lives entirely in the region you choose and never crosses to the other.

| Region | Dashboard                    | MCP server                       |
| ------ | ---------------------------- | -------------------------------- |
| **US** | `https://app.waniwani.ai`    | `https://mcp.waniwani.ai/mcp`    |
| **EU** | `https://eu.app.waniwani.ai` | `https://eu.mcp.waniwani.ai/mcp` |

## Choosing a region

You choose a region **when you create an organization**. Before the org-creation wizard runs, Waniwani prompts you to pick your **data residency**:

* **EU** — for teams that need European storage and processing (EU residency requirements).
* **US** — for US-based teams and global teams without EU residency needs.

Your choice applies to **that organization**. Everything downstream — the workspace, members, environments, API keys, conversations, analytics, and stored content — is created on the region's stack and stays there.

<Note>
  Data residency is set per organization and can't be changed after creation. If you need both regions, create a separate organization on each stack.
</Note>

## Signing in

Sign in on the dashboard for the region your organization lives in:

* **US:** [app.waniwani.ai](https://app.waniwani.ai)
* **EU:** [eu.app.waniwani.ai](https://eu.app.waniwani.ai)

The US dashboard won't show organizations that live in the EU, and vice versa. If you pick a region during onboarding that differs from the stack you signed in on, Waniwani moves you to the right stack and you continue there — your account (email, name, linked sign-in providers) is portable, but sessions and org data always stay local to each region.

## Connecting AI clients

The [Waniwani MCP server](/mcp-server/overview) — the one that lets an AI client operate the platform for you — is also regional. Use the MCP URL for the region your data lives in, and sign in on the matching stack:

* **US:** `https://mcp.waniwani.ai/mcp`
* **EU:** `https://eu.mcp.waniwani.ai/mcp`

See [Connect your AI client](/mcp-server/connect) for the per-region setup in Claude, Cursor, and ChatGPT.


# Service accounts
Source: https://docs.waniwani.ai/platform/scopes

Issue a workspace-wide service-account key, choose the scopes it can hold, and control destructive operations.

When you connect WaniWani to a workspace-wide tool — for example the [Claude-in-Slack connector](/mcp-server/connect) — an organization admin issues a **service-account key** (`wws_…`) from **Settings → Service accounts**. The key acts on its own labelled identity, and the admin chooses up front exactly how much of the organization it may touch:

* a set of **scopes** — the resources the key can read and write, and
* a **destructive-operations** toggle — whether it may deploy, connect a repo, or delete whole resources.

The key is shown once, at creation. You can revoke it at any time, which takes effect immediately.

## Permissions & scopes

A key carries a fixed set of scopes, chosen when you issue it. Each area has a `read` and a `write` scope, and the key holds exactly the ones you select.

<Note>
  A new key is **read-only** — `mcp:read` and `kb:read` — until you add more scopes.
</Note>

| Scope                 | Description                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------ |
| `mcp:read`            | View agents and their environments, channels, and deployments                              |
| `mcp:write`           | Create and edit agents, environments, and channels                                         |
| `kb:read`             | View knowledge base sources and their content                                              |
| `kb:write`            | Add, edit, and remove knowledge base content                                               |
| `analytics:read`      | View traffic, sessions, funnels, and insights                                              |
| `analytics:write`     | Create and edit funnels and analytics views                                                |
| `evals:read`          | View evaluations, evaluators, and their results                                            |
| `evals:write`         | Create, edit, and run evaluations                                                          |
| `conversations:read`  | View personas, their conversations, and shared submissions                                 |
| `conversations:write` | Manage personas and conversation submissions                                               |
| `competition:read`    | View tracked competitor companies                                                          |
| `competition:write`   | Add and edit tracked competitor companies                                                  |
| `geo:read`            | View GEO visibility: brand presence in AI answers, monitored prompts, and competitor stats |
| `geo:write`           | Manage GEO tracking: monitored prompts, sources, and tags                                  |

## Destructive operations

Some actions can't be undone or take a running agent offline. A service-account key may perform them **only when the “Allow destructive operations” toggle is enabled** for that key. The toggle is **off by default** and is independent of the scopes above: a key with `mcp:write` can edit content, but it still cannot run a destructive action unless the toggle is on.

<Warning>
  The toggle only affects service-account keys. It does not change what a signed-in teammate can do, and it does not widen the key's scopes — it only unlocks the operations below for scopes the key already holds.
</Warning>

With the toggle enabled, the key may:

**Deploy & connect**

* Clone managed project repo to GitHub
* Connect project to a user-owned GitHub repo
* Deploy the latest commit on an environment's branch
* Migrate a managed project to a user-owned repo
* Promote a channel
* Redeploy a past deployment's commit
* Roll back production to a past deployment

**Delete a whole resource**

* Delete a project
* Delete environment
* Delete environment channel

Everyday content changes — including deleting individual items such as a knowledge-base source, an evaluator, or an email template — need only the matching `write` scope and are **not** gated by this toggle.


# Changelog
Source: https://docs.waniwani.ai/sdk/changelog

Release notes for the Waniwani SDK, including breaking changes and deprecated APIs.

This page tracks API changes that require code updates, organized by the version that introduced them. Deprecations are safe to ignore short-term — the old shape keeps working until the removal version listed in the deprecation notice.

## Deprecations at a glance

| API                                                                                         | Status      | Since  | Removed in |
| ------------------------------------------------------------------------------------------- | ----------- | ------ | ---------- |
| `track.lead()` (alias of `track.leadQualified()`)                                           | **Removed** | 0.15.1 | 0.16.0     |
| `.addNode(id, run, options?)` (positional)                                                  | Deprecated  | 0.12.0 | 0.13.0     |
| `createTool`, `createResource`, `registerTools` from `@waniwani/sdk/mcp`                    | **Removed** | 0.12.0 | 0.20.0     |
| MCP-widget React host (`WidgetProvider`, `useToolOutput`, …) from `@waniwani/sdk/mcp/react` | **Removed** | 0.12.0 | 0.20.0     |
| `toNextJsHandler` from `@waniwani/sdk/next-js`                                              | **Removed** | 0.12.0 | 0.20.0     |
| `toExpressJsHandler` from `@waniwani/sdk/express-js`                                        | **Removed** | 0.12.0 | 0.20.0     |
| Chat-server types from `@waniwani/sdk/chat/server`                                          | **Removed** | 0.12.0 | 0.20.0     |
| `ChatCard` from `@waniwani/sdk/chat`                                                        | **Removed** | 0.12.0 | 0.20.0     |
| `evals/*` (entire subtree)                                                                  | **Removed** | 0.12.0 | 0.12.0     |

<Tip>
  TypeScript will strike through deprecated signatures in your IDE. Hover for the replacement.
</Tip>

## Breaking changes at a glance

| Change                                                                                                                                                                                                       | Kind             | Version | Auto-fixable                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | ------- | ------------------------------------------------ |
| Entire legacy tier deleted: `@waniwani/sdk/legacy*`, `@waniwani/sdk/next-js`, `@waniwani/sdk/express-js`, `@waniwani/sdk/chat/server`, and `ChatCard` from `@waniwani/sdk/chat`                              | Removal          | 0.20.0  | Partly (codemod below; widget hooks need a port) |
| Generic funnel events `quote.requested` / `quote.succeeded` / `quote.failed` / `purchase.completed` removed from the `track()` taxonomy (with their property types and legacy input fields)                  | Removal          | 0.18.0  | Yes (codemod below)                              |
| `useWaniwani()` no longer auto-discovers config (removed `WidgetProvider` context read + self-connecting host bridge); resolves from explicit `{ endpoint, source }` or a passed `toolResponseMetadata` only | Behavior change  | 0.17.0  | Yes (codemod below)                              |
| `useWaniwani()` returns the typed server `track` surface; string `track(name, props)`, `step()`, `conversion()`, and the `capture` option are removed                                                        | API change       | 0.16.0  | Yes (codemod below)                              |
| Widget auto-capture event names (`widget_click`, `widget_scroll`, `widget_form_*`, `widget_link_click`, `widget_error`) removed from `EventType`                                                             | Removal          | 0.16.0  | Yes (codemod below)                              |
| Widget config `_meta` key: `waniwani` becomes `waniwani/widget`                                                                                                                                              | Rename           | 0.16.0  | Yes (codemod below)                              |
| `track.lead()` alias removed (deprecated since 0.15.1)                                                                                                                                                       | Removal          | 0.16.0  | Yes (codemod below)                              |
| `createTrackingRoute` accepts the V2 batch envelope instead of the snake\_case widget payload                                                                                                                | Contract change  | 0.16.0  | Yes (codemod below)                              |
| `track.lead()` → `track.leadQualified()`, event `"lead"` → `"lead_qualified"`                                                                                                                                | Rename           | 0.15.0  | Yes (codemod below)                              |
| `addConditionalEdge(from, condition)` → `addConditionalEdge(from, to, condition)`                                                                                                                            | Signature change | 0.14.0  | Yes (codemod below)                              |

<Note>
  When you bump `@waniwani/sdk` across a minor version (`0.x` minors can break), scan this page for every breaking change between your old and new version and apply the documented migration. Each one below is a mechanical rewrite an agent or codemod can apply in a single pass, followed by `bun run typecheck && bun test`.
</Note>

<Tip>
  **Migrate automatically.** Every version hop with breaking changes ships a self-contained migration skill named `migrate-waniwani-sdk-<from>-to-<to>`. Add the one for your hop and an agent applies the whole section for you:

  ```bash theme={null}
  npx skills add Waniwani-AI/sdk -s migrate-waniwani-sdk-0.19-to-0.20
  ```
</Tip>

***

## 0.20.0: the legacy tier is deleted

<Tip>
  Apply this entire section automatically: `npx skills add Waniwani-AI/sdk -s migrate-waniwani-sdk-0.19-to-0.20`, then invoke it from your project on 0.19.x.
</Tip>

0.12.0 moved the MCP-widget-in-host stack and the chat-server BFF adapters to `@waniwani/sdk/legacy*` and kept the old paths re-exporting every symbol. 0.20.0 deletes all of it. There is no shim: these are module-resolution errors at build time, not deprecation warnings.

### Entry points removed

| Entry point                       | Held                                                                                                                     |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `@waniwani/sdk/legacy`            | `createTool`, `createResource`, `registerTools` and their types                                                          |
| `@waniwani/sdk/legacy/react`      | `WidgetProvider`, `useWidgetClient`, every widget host hook, `LoadingWidget`, `DevModeProvider`, mocks, `detectPlatform` |
| `@waniwani/sdk/legacy/next-js`    | `toNextJsHandler`                                                                                                        |
| `@waniwani/sdk/legacy/express-js` | `toExpressJsHandler`                                                                                                     |
| `@waniwani/sdk/next-js`           | `toNextJsHandler` (0.12 back-compat alias)                                                                               |
| `@waniwani/sdk/express-js`        | `toExpressJsHandler` (0.12 back-compat alias)                                                                            |
| `@waniwani/sdk/chat/server`       | `createApiHandler` types, `extractGeoFromHeaders`, `GeoLocation`                                                         |

`@waniwani/sdk`, `@waniwani/sdk/mcp`, `@waniwani/sdk/mcp/react`, `@waniwani/sdk/mcp/react/skybridge`, `@waniwani/sdk/chat`, `@waniwani/sdk/kb` and the two chat assets are untouched.

`ChatCard` and `ChatCardProps` are gone from `@waniwani/sdk/chat`.

### `RegisteredTool` moved rather than disappeared

The OSS flow API's `showWidget` accepts `RegisteredTool | string`, so the type outlived the tier that defined it:

```ts theme={null}
// Before
import type { RegisteredTool } from "@waniwani/sdk/legacy";

// After
import type { RegisteredTool } from "@waniwani/sdk/mcp";
```

The shape is unchanged and structural (`{ id, title, description, register }`), so any object you already pass to `showWidget` still satisfies it.

### `@modelcontextprotocol/ext-apps` is no longer a peer dependency

Only the legacy widget clients imported it. If your app talks to a widget host directly, depend on it yourself; nothing in the SDK asks for it any more.

### Rewrite 1 — `createTool` becomes `registerTool`

`createTool` returned an object with a `register(server)` method. Register on the server instead, and return MCP's content shape from the handler rather than `{ text, data }`.

```ts theme={null}
// Before
import { createTool, registerTools } from "@waniwani/sdk/mcp";

export const searchTool = createTool(
  {
    id: "search",
    title: "Search",
    description: "Search the knowledge base",
    inputSchema: { query: z.string() },
    annotations: { readOnlyHint: true },
  },
  async ({ query }, { waniwani }) => {
    await waniwani?.track.priceShown({ amount: 49, currency: "EUR" });
    return { text: `Results for "${query}"`, data: { query } };
  },
);

await registerTools(server, [searchTool]);
```

```ts theme={null}
// After
import { extractScopedClient } from "@waniwani/sdk/mcp";

server.registerTool(
  "search",
  {
    title: "Search",
    description: "Search the knowledge base",
    inputSchema: { query: z.string() },
    annotations: { title: "Search", readOnlyHint: true },
  },
  async ({ query }, extra) => {
    const waniwani = extractScopedClient(extra);
    await waniwani?.track.priceShown({ amount: 49, currency: "EUR" });
    return {
      content: [{ type: "text" as const, text: `Results for "${query}"` }],
      structuredContent: { query },
    };
  },
);
```

Mechanical parts of the rewrite:

* `config.id` becomes `registerTool`'s first argument; the rest of `config` becomes the second, minus `id`, `resource`, `invoking`, `invoked` and `autoInjectResultText`.
* `{ text }` becomes `{ content: [{ type: "text" as const, text }] }`.
* `{ text, data }` becomes the same plus `structuredContent: data`.
* The handler's second parameter changes from `{ extra, waniwani }` to MCP's `extra`. Read `extra._meta` directly and get the scoped client with `extractScopedClient(extra)`, still exported from `@waniwani/sdk/mcp`.
* Add `annotations.title`. `createTool` accepted a top-level `title`, and Claude's Connectors Directory requires one inside `annotations`.

For a tool that pauses, branches or holds state across turns, port it to `createFlow` instead of `registerTool`. That is the surface the whole tier was deprecated in favour of.

### Rewrite 2 — widget tools carry their own `_meta`

`createTool` derived widget metadata from `config.resource`. Write it out:

```ts theme={null}
// After — the _meta createTool used to build for a resource-backed tool
_meta: {
  "openai/outputTemplate": openaiUri,
  "openai/toolInvocation/invoking": "Loading...",
  "openai/toolInvocation/invoked": "Loaded",
  "openai/widgetAccessible": true,
  "openai/resultCanProduceWidget": true,
  ui: { resourceUri: mcpUri },
  "ui/resourceUri": mcpUri,
}
```

`invoking` and `invoked` default to `"Loading..."` and `"Loaded"`. Add `ui.autoHeight: true` when the resource set `autoHeight`. `createResource` built `mcpUri` as `ui://widgets/ext-apps/{id}.html`; keep whatever URI you already serve.

### Rewrite 3 — drop the chat BFF

`toNextJsHandler`, `toExpressJsHandler` and `createApiHandler` existed so the chat widget could proxy through your backend. `WaniwaniChat` talks to `app.waniwani.ai` directly, so the route goes away entirely.

```tsx theme={null}
// Before — app/api/waniwani/[[...path]]/route.ts
import { toNextJsHandler } from "@waniwani/sdk/next-js";
export const { GET, POST } = toNextJsHandler(client);

// and, on the page
<ChatCard api="/api/waniwani" />
```

```tsx theme={null}
// After — delete the route file
import { WaniwaniChat } from "@waniwani/sdk/chat";

<WaniwaniChat token="wwp_..." channelId="51c3658a-..." />
```

Keep a backend of your own only if you were using `beforeRequest` to inject per-visitor context or a self-hosted model. In that case stay on `ChatEmbed` and point `api` at a route you write yourself; the SDK no longer ships the router.

### Rewrite 4 — widget React hooks

`WidgetProvider` and the host bridge hooks (`useToolOutput`, `useCallTool`, `useDisplayMode`, `useSendFollowUp`, and the rest) have no drop-in replacement in the SDK. Widgets belong to the app framework now:

* Tracking from inside a widget: `useWaniwani` from `@waniwani/sdk/mcp/react`, or `@waniwani/sdk/mcp/react/skybridge` when skybridge hosts the widget. Both survive 0.20.
* Everything else (host handshake, display mode, tool calls, follow-ups): use the kit's widget runtime.

***

## 0.18.0: quote and purchase events removed from the taxonomy

<Tip>
  Apply this entire section automatically: `npx skills add Waniwani-AI/sdk -s migrate-waniwani-sdk-0.17-to-0.18`, then invoke it from your project on 0.17.x.
</Tip>

The generic funnel events `quote.requested`, `quote.succeeded`, `quote.failed`, and `purchase.completed` are removed from `EVENT_TYPES` and the `TrackEvent` union. They predate the typed revenue taxonomy (`price_shown`, `prices_compared`, `option_selected`, `lead_qualified`, `converted`), which models the same funnel stages with typed properties and flat `track.*` helpers. `link.clicked` is **not** affected and remains a first-class event.

Removed with them:

* The type exports `QuoteSucceededProperties` and `PurchaseCompletedProperties`
* The legacy input fields `quoteAmount`, `quoteCurrency`, `purchaseAmount`, `purchaseCurrency` on `LegacyTrackEvent`

### Breaking: `quote.*` and `purchase.completed` no longer typecheck

#### Before

```ts theme={null}
await client.track({ event: "quote.requested" });
await client.track({ event: "quote.succeeded", properties: { amount: 120, currency: "EUR" } });
await client.track({ event: "purchase.completed", properties: { amount: 490, currency: "EUR" } });
```

#### After

```ts theme={null}
await client.track.priceShown({ amount: 120, currency: "EUR" });
await client.track.converted({ amount: 490, currency: "EUR" });
```

#### Migration

1. `track({ event: "quote.succeeded", properties: { amount, currency } })` (or legacy `eventType: "quote.succeeded"` with `quoteAmount` / `quoteCurrency`) becomes `track.priceShown({ amount, currency })`. Keep any identity fields (`sessionId`, `externalUserId`, `meta`) on the call.
2. `track({ event: "purchase.completed", properties: { amount, currency } })` (or legacy `purchaseAmount` / `purchaseCurrency`) becomes `track.converted({ amount, currency })`.
3. `track({ event: "quote.requested" })` and `track({ event: "quote.failed" })`: delete the call. The funnel start is already covered by the auto-captured `tool.called` and `session.started`.
4. Replace type imports: `QuoteSucceededProperties` with `PriceShownProperties`, `PurchaseCompletedProperties` with `ConvertedProperties`.

No `@deprecated` shim: the names are removed outright, so `tsc` surfaces every call site as an error. After applying, run `bun run typecheck && bun test`.

***

## 0.17.0: `useWaniwani()` is host-agnostic

<Tip>
  Apply this entire section automatically: `npx skills add Waniwani-AI/sdk -s migrate-waniwani-sdk-0.16-to-0.17`, then invoke it from your project on 0.16.x.
</Tip>

`useWaniwani()` from `@waniwani/sdk/mcp/react` takes the tool-response `_meta` as data and never opens a host connection of its own. It resolves config (endpoint, source, widget token, session id) from **explicit options** or a **`toolResponseMetadata` object you pass**.

New in this release:

* `@waniwani/sdk/mcp/react/skybridge` — a skybridge-host adapter for `useWaniwani`. It reads skybridge's `useToolInfo().responseMetadata` and feeds it to the core hook, so skybridge widgets call `useWaniwani()` bare. `skybridge` is an optional peer dependency.
* `toolResponseMetadata` option on `useWaniwani` (from `@waniwani/sdk/mcp/react`) — pass the host's tool-response `_meta` on any host you already have it from.

### Breaking: `useWaniwani()` no longer auto-discovers its config

Config resolution is now: explicit `{ endpoint, source }`, or a `toolResponseMetadata` object you pass, and nothing else. The hook does not read a `WidgetProvider` context and does not connect to the widget host to find the config. A bare `useWaniwani()` that relied on that auto-discovery returns a no-op widget (no `sessionId`; `track.*` does nothing).

<Note>
  This break does not surface in `tsc`. A bare `useWaniwani()` still typechecks and fails only at runtime, by tracking nothing. Find call sites by auditing imports of `useWaniwani`, not by chasing type errors.
</Note>

Why: on an MCP-Apps host the tool-response `_meta` is delivered once, to whichever host bridge is connected and listening at that moment. In a skybridge widget that bridge is skybridge. A hook opening a second connection raced it and missed the one-shot on Claude. The core hook now takes the metadata as data; the skybridge adapter supplies it.

#### Before

```tsx theme={null}
import { useWaniwani } from "@waniwani/sdk/mcp/react";

// relied on auto-discovery via WidgetProvider / a self-opened host connection
const wani = useWaniwani();
```

#### After — skybridge-hosted widget (the common case)

Change the import; the call stays bare.

```tsx theme={null}
import { useWaniwani } from "@waniwani/sdk/mcp/react/skybridge";

const wani = useWaniwani(); // reads skybridge's useToolInfo().responseMetadata
```

#### After — any other host

Pass the metadata you already hold, or an explicit endpoint.

```tsx theme={null}
import { useWaniwani } from "@waniwani/sdk/mcp/react";

const wani = useWaniwani({ toolResponseMetadata }); // the host's tool-response _meta
// bring-your-own backend, unchanged:
const wani2 = useWaniwani({ endpoint: "https://…/v2/track", source: "chatgpt" });
```

#### Migration

1. Grep for imports of `useWaniwani` from `@waniwani/sdk/mcp/react`.
2. If the project uses skybridge (`skybridge` dependency / imports of `skybridge/web`), change the import to `@waniwani/sdk/mcp/react/skybridge` and leave the call bare. Any options passed (`source`, `token`, `sessionId`, `metadata`) are forwarded, so keep them.
3. Otherwise, pass `toolResponseMetadata` (the host's tool-response `_meta`) to the call, or leave an existing explicit `{ endpoint, source }` call as-is.

No `@deprecated` shim: the self-connect path was unreliable (a no-op on Claude) and the `WidgetProvider`-context read belonged to the retired legacy widget host, so both are removed outright. After applying, run `bun run typecheck && bun test`; because `tsc` cannot see this break, the completion check is that every bare `useWaniwani()` call site has moved to one of the forms above.

***

## 0.16.0: one tracking client on every surface

Tracking is a single client that exists on four surfaces: the server (`waniwani()`), tool handlers and flow nodes (the scoped client), MCP-app widgets (`useWaniwani()`), and chat host pages (`chat.track`). The browser surfaces send the same typed events through the same batching transport as the server, with session identity stamped automatically. See [Events](/sdk/tracking/events) and [Widgets & chat](/sdk/tracking/widgets).

<Tip>
  Apply this entire section automatically: `npx skills add Waniwani-AI/sdk -s migrate-waniwani-sdk-0.15-to-0.16`, then invoke it from your project on 0.15.x.
</Tip>

New in this release:

* `useWaniwani().track` is the typed `TrackFn`: `track({ event, properties })` plus the flat revenue helpers (`track.priceShown()`, `track.converted()`, ...). One `widget_render` event is emitted automatically on init. The hook works without the legacy `WidgetProvider`.
* `WaniWani.chat.track` / `WaniWani.chat.identify` on the `<script>` embed, and `track` / `identify` on the `WaniwaniChat` ref handle. Session attaches live once the chat server assigns it; the anonymous `visitorId` covers events before that.
* `createFrontendClient` from `@waniwani/sdk`: the browser tracking primitive both surfaces wrap.
* `context.waniwani.sessionId` on the scoped client: read the resolved session id and store it with your own records to attribute off-platform events later.
* `visitorId` as a first-class correlation field on `TrackInput` and the V2 envelope.
* `EVENT_TYPES` runtime constant, and `extractScopedClient` exported from `@waniwani/sdk/mcp`.

### Breaking: `useWaniwani()` surface

The widget hook returns `{ sessionId, track, identify, flush }`. The string-based `track(name, properties)`, `step(name, meta)`, `conversion(name, data)`, and the `capture` option are gone, along with DOM auto-capture and its event names.

#### Before

```tsx theme={null}
const wani = useWaniwani({ capture: { click: true, scroll: true } });
wani.track("plan_viewed", { plan: "pro" });
wani.step("selected_plan");
wani.conversion("purchase", { amount: 49 });
```

#### After

```tsx theme={null}
const wani = useWaniwani();
wani.track.priceShown({ amount: 49, currency: "EUR" });
wani.track.optionSelected({ id: "pro", amount: 49, currency: "EUR" });
wani.track.converted({ amount: 49, currency: "EUR" });
```

#### Migration (codemod)

1. Delete any `capture` option passed to `useWaniwani()`.
2. Replace `wani.step(...)` and `wani.conversion(...)` with the typed revenue helper that matches the funnel stage (`optionSelected`, `converted`, ...).
3. Replace string calls `wani.track("<name>", props)`:
   * If `<name>` is a typed event, use the object form: `wani.track({ event: "<name>", properties: props })`.
   * Otherwise, model the moment with the closest typed event; there are no custom event names in the typed surface.
4. Remove any type imports of `AutoCaptureToggles` or `WidgetTrackFn`; `track` is the same `TrackFn` type the server client uses.
5. Run `bun run typecheck && bun test`.

### Breaking: widget auto-capture event names removed from `EventType`

`widget_click`, `widget_link_click`, `widget_error`, `widget_scroll`, `widget_form_field`, and `widget_form_submit` are no longer part of the `EventType` union. `widget_render` remains and is emitted automatically. Dashboards keep historical events; nothing new arrives under the removed names. Code that referenced them in `track()` calls or type positions must switch to typed taxonomy events.

### Breaking: widget config meta key is `waniwani/widget`

`withWaniwani` injects the widget tracking config into tool responses under `_meta["waniwani/widget"]`, following the `waniwani/*` namespacing every other SDK meta key uses. `useWaniwani()` reads the new key. Only code that read `_meta.waniwani` directly needs updating:

```ts theme={null}
// Before
const config = toolResponseMetadata?.waniwani;
// After
const config = toolResponseMetadata?.["waniwani/widget"];
```

Widgets on older SDK versions paired with a 0.16 server (or the reverse) will not resolve tracking config; upgrade both sides together.

### Breaking: `track.lead()` removed

Deprecated since 0.15.1, removed on schedule. Replace `.track.lead(` with `.track.leadQualified(` (see the 0.15.0 entry below for the full codemod). The mapper no longer rewrites the event name `"lead"`; send `"lead_qualified"`.

### Breaking: `createTrackingRoute` accepts the V2 batch envelope

The proxy route parses the same V2 batch shape the frontend client sends (`{ events: [{ id, name, correlation, properties, ... }] }`). Point `createFrontendClient` or `useWaniwani({ endpoint })` at your route and no further change is needed; hand-rolled clients posting the old snake\_case widget payload (`event_type`, `session_id`) must switch to the V2 envelope documented in [Events](/sdk/tracking/events).

***

## 0.15.0: `lead` becomes `lead_qualified`

The lead event is named `lead_qualified`, its helper is `track.leadQualified()`, and its properties are `LeadQualifiedProperties`: `externalId`, `email`, and `name` alongside `source`. The typed input is `RevenueLeadQualifiedInput` (`RevenueLeadInput` and `LeadProperties` no longer exist).

`lead_qualified` means the person met your qualification bar (finished the qualifying questions, requested a demo, matched your target profile). It belongs at the node where qualification completes, not at flow entry; see [Instrumentation](/sdk/tracking/instrumentation) for placement rules.

### Why

`lead` under-specified what the event represented, so integrations fired it anywhere from flow entry to CRM push and funnels were not comparable across projects. The name now states the semantic, and the new properties (`externalId` as your CRM record id, plus `email` and `name`) give the dashboard real dedup and join keys instead of an anonymous count.

### Before

```ts theme={null}
await client.track.lead({ source: "newsletter", externalUserId: "user_123" });

await client.track({ event: "lead", properties: { source: "newsletter" }, sessionId });
```

### After

```ts theme={null}
await client.track.leadQualified({
  externalId: "lead_abc123", // your CRM/lead record id, the strongest dedup key
  email: "jane@example.com",
  name: "Jane Doe",
  source: "newsletter",
  externalUserId: "user_123",
});

await client.track({ event: "lead_qualified", properties: { source: "newsletter" }, sessionId });
```

All new properties are optional; a bare `track.leadQualified({ source })` is valid.

### Migration (codemod)

1. Replace every `.track.lead(` call with `.track.leadQualified(`.
2. Replace `event: "lead"` with `event: "lead_qualified"` in generic `track()` calls (and `eventType: "lead"` in the legacy shape).
3. Replace type imports: `RevenueLeadInput` → `RevenueLeadQualifiedInput`, `LeadProperties` → `LeadQualifiedProperties`.
4. Where the call site has them available, enrich the event: pass your lead record id as `externalId`, plus `email` and `name`.
5. Run `bun run typecheck && bun test`.

### Compatibility

* `track.lead()` exists as a `@deprecated` alias since **0.15.1**: it emits a `lead_qualified` event and will be removed in **0.16.0**. On 0.15.0 exactly, the alias is absent and step 1 is required to compile.
* The transport normalizes the event name `"lead"` to `"lead_qualified"` at runtime (since 0.15.1), so already-compiled pre-0.15 callers keep producing valid events. The `EventType` union does not accept `"lead"`, so TypeScript call sites must migrate.

### Verifying

```bash theme={null}
grep -rn "track\.lead(\|\"lead\"\|'lead'" src/ app/ lib/  # should return no tracking call sites
bun run typecheck
bun test
```

***

## 0.14.0: `addConditionalEdge` declares its branch targets

`addConditionalEdge` now takes the reachable nodes explicitly as the second argument: `addConditionalEdge(from, to, condition)`. The condition's return type is constrained to `to`, so a branch can never route to an undeclared node, and the flow graph used for funnel analytics and Mermaid diagrams is correct by construction.

### Why

Before 0.14.0, graph introspection discovered a conditional edge's targets by stringifying the condition function and scanning its source for node names. That heuristic was fragile: it broke under minification, missed dynamically-computed targets, and produced false positives when a node id appeared as a comparison value or in a comment — so funnel analytics could show the wrong branches. Declaring `to` removes the guesswork entirely.

### Before

```ts theme={null}
.addConditionalEdge("analyze_email", (state) =>
  state.isCompanyEmail ? "done" : "ask_company",
)
```

### After

```ts theme={null}
.addConditionalEdge("analyze_email", ["done", "ask_company"], (state) =>
  state.isCompanyEmail ? "done" : "ask_company",
)
```

### Migration (codemod)

For each `.addConditionalEdge(from, condition)` call, insert a second argument: an array of every node the condition can return (including `END` if it returns `END`). The simplest reliable source for that array is the set of literal node names returned by the condition body.

1. Find every two-argument `.addConditionalEdge(` call.
2. Read the condition body and collect every node name (string literal or `END`) it can return.
3. Insert that list, deduplicated, as the new second argument — leaving the condition as the third.
4. Run `bun run typecheck`. The compiler now flags any return value missing from `to`, so any over- or under-declared list surfaces immediately. Fix by aligning `to` with what the condition actually returns.

```ts theme={null}
// Before
.addConditionalEdge("route_country", (state) => {
  if (state.country === "FR") return "fr_path";
  if (state.country === "DE") return "de_path";
  return "default_path";
})

// After
.addConditionalEdge(
  "route_country",
  ["fr_path", "de_path", "default_path"],
  (state) => {
    if (state.country === "FR") return "fr_path";
    if (state.country === "DE") return "de_path";
    return "default_path";
  },
)
```

### Verifying

```bash theme={null}
bun run typecheck   # condition return type is now checked against `to`
bun test
```

If typecheck reports `Type '"x"' is not assignable to type '"a" | "b"'`, the condition returns a node missing from `to` — add it. If it reports an unused-looking target, the condition never returns it — safe to leave (over-declaration is allowed) or trim.

***

## 0.12.0: Legacy reorganization

The MCP-widget-in-host stack (`createTool` / `createResource` / `WidgetProvider` and host bridge hooks) and the chat-server BFF adapters (`toNextJsHandler`, `toExpressJsHandler`, `createApiHandler`) were moved to dedicated `@waniwani/sdk/legacy*` entry points. New code should use `createFlow` from `@waniwani/sdk/mcp` and the direct-to-backend `ChatEmbed` from `@waniwani/sdk/chat`.

The **old entry points still re-export every symbol unchanged** — your imports keep working without edits. The legacy entry points exist so you can adopt the final import paths now and avoid the next major bump.

### Why

* **OSS-first framing.** `@waniwani/sdk/mcp` is now the OSS surface: `createFlow`, `StateGraph`, `KvStore`, `MemoryKvStore`. No API key required, no hosted dependency on the core path.
* **Smaller default bundle.** Splitting the legacy surface off lets host-only React hooks and the chat-server router stay out of the OSS bundle once the re-exports are dropped.
* **Sunset signal.** The chat widget will talk directly to `app.waniwani.ai` in a future release, removing the need for a self-hosted BFF. The Next.js / Express adapters become unnecessary.

### Migration matrix

Every row is a mechanical rewrite — no behavior changes, only the import path. An LLM or codemod can apply all of these in one pass.

| Symbol(s)                                                                                                                                                                                                                              | Old import                  | New import                                                                                                                                                                  |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createTool`, `registerTools`, `ToolConfig`, `ToolHandler`, `ToolHandlerContext`, `RegisteredTool`, `ToolToolCallback`                                                                                                                 | `@waniwani/sdk/mcp`         | `@waniwani/sdk/legacy`                                                                                                                                                      |
| `createResource`, `ResourceConfig`, `RegisteredResource`, `WidgetCSP`                                                                                                                                                                  | `@waniwani/sdk/mcp`         | `@waniwani/sdk/legacy`                                                                                                                                                      |
| `detectPlatform`, `isMCPApps`, `isOpenAI`, `WidgetPlatform`                                                                                                                                                                            | `@waniwani/sdk/mcp`         | `@waniwani/sdk/legacy/react`                                                                                                                                                |
| `HostContext`, `ToolCallResult`, `ToolResult`, `UnifiedWidgetClient`                                                                                                                                                                   | `@waniwani/sdk/mcp`         | `@waniwani/sdk/legacy/react`                                                                                                                                                |
| `WidgetProvider`, `useWidgetClient`                                                                                                                                                                                                    | `@waniwani/sdk/mcp/react`   | `@waniwani/sdk/legacy/react`                                                                                                                                                |
| `useToolOutput`, `useToolResponseMetadata`, `useCallTool`, `useSendFollowUp`, `useFlowAction`, `useUpdateModelContext`                                                                                                                 | `@waniwani/sdk/mcp/react`   | `@waniwani/sdk/legacy/react`                                                                                                                                                |
| `useDisplayMode`, `useRequestDisplayMode`, `useTheme`, `useLocale`, `useSafeArea`, `useMaxHeight`, `useWidgetState`, `useOpenExternal`, `useIsChatGptApp`                                                                              | `@waniwani/sdk/mcp/react`   | `@waniwani/sdk/legacy/react`                                                                                                                                                |
| `InitializeNextJsInIframe`, `LoadingWidget`                                                                                                                                                                                            | `@waniwani/sdk/mcp/react`   | `@waniwani/sdk/legacy/react`                                                                                                                                                |
| `DevModeProvider`, `getMockState`, `initializeMockOpenAI`, `updateMockDisplayMode`, `updateMockGlobal`, `updateMockTheme`, `updateMockToolOutput`                                                                                      | `@waniwani/sdk/mcp/react`   | `@waniwani/sdk/legacy/react`                                                                                                                                                |
| `DeviceType`, `DisplayMode`, `SafeArea`, `SafeAreaInsets`, `Theme`, `UnknownObject`, `UserAgent` (widget host types)                                                                                                                   | `@waniwani/sdk/mcp/react`   | `@waniwani/sdk/legacy/react`                                                                                                                                                |
| `FlowActionResult`, `ModelContextContentBlock`, `ModelContextUpdate`, `SendFollowUpOptions`                                                                                                                                            | `@waniwani/sdk/mcp/react`   | `@waniwani/sdk/legacy/react`                                                                                                                                                |
| `toNextJsHandler`, `NextJsHandlerOptions`, `NextJsHandlerResult`                                                                                                                                                                       | `@waniwani/sdk/next-js`     | `@waniwani/sdk/legacy/next-js`                                                                                                                                              |
| `toExpressJsHandler`, `ExpressJsHandlerOptions`, `ExpressJsHandlerResult`, `ExpressLikeRequest`, `ExpressLikeResponse`, `ExpressMiddleware`, `ChatOptions`                                                                             | `@waniwani/sdk/express-js`  | `@waniwani/sdk/legacy/express-js`                                                                                                                                           |
| `ApiHandler`, `ApiHandlerOptions`, `BeforeRequestContext`, `BeforeRequestResult`, `ClientVisitorContext`, `VisitorMeta`, `WebSearchConfig`, `GeoLocation`, `extractGeoFromHeaders`, `WaniWaniError` (when imported from `chat/server`) | `@waniwani/sdk/chat/server` | *stays* — `@waniwani/sdk/chat/server` is a re-export shim around `legacy/chat/server/*`. No required rewrite. Will be removed alongside the chat-server adapters in 0.14.0. |
| `ChatCard`, `ChatCardProps`                                                                                                                                                                                                            | `@waniwani/sdk/chat`        | `WaniwaniChat` if you use the hosted Platform, `ChatEmbed` if you run the chat backend yourself (see below)                                                                 |

`useWaniwani`, `UseWaniwaniOptions`, and `WaniwaniWidget` stay on `@waniwani/sdk/mcp/react` — that hook is non-legacy.

### What stays the same

These remain on `@waniwani/sdk/mcp` and are the recommended surface for new code:

* `createFlow`, `StateGraph`, `START`, `END`, `redacted`, `createFlowTestHarness`, `AddNodeConfig`, all flow-related types
* `KvStore`, `MemoryKvStore`, `WaniwaniKvStore`
* `withWaniwani`, `WithWaniwaniOptions`
* `createTrackingRoute`, `TrackingRouteOptions`
* `ScopedWaniWaniClient`
* `McpServer`, `ZodRawShapeCompat` (shared MCP types)

And on `@waniwani/sdk`:

* `waniwani()`, `defineConfig`, `WaniWaniError`, all tracking helpers

### Codemod recipe (one-shot)

An agent updating a downstream repo can apply these substitutions in order. Each is a string-level rewrite of an `import … from "<path>"` statement — semantics are preserved end-to-end.

```bash theme={null}
# 1. Server-side MCP primitives → @waniwani/sdk/legacy
#    (createTool, createResource, registerTools, and their associated types)
#    Rewrite any import of { createTool | createResource | registerTools |
#    ToolConfig | ToolHandler | ToolHandlerContext | RegisteredTool |
#    ToolToolCallback | ResourceConfig | RegisteredResource | WidgetCSP }
#    from "@waniwani/sdk/mcp" → "@waniwani/sdk/legacy"

# 2. Widget host hooks/components/types → @waniwani/sdk/legacy/react
#    Rewrite any import of { WidgetProvider | useWidgetClient | useToolOutput |
#    useToolResponseMetadata | useCallTool | useSendFollowUp | useFlowAction |
#    useUpdateModelContext | useDisplayMode | useRequestDisplayMode | useTheme |
#    useLocale | useSafeArea | useMaxHeight | useWidgetState | useOpenExternal |
#    useIsChatGptApp | InitializeNextJsInIframe | LoadingWidget |
#    DevModeProvider | getMockState | initializeMockOpenAI |
#    updateMockDisplayMode | updateMockGlobal | updateMockTheme |
#    updateMockToolOutput | DeviceType | DisplayMode | SafeArea |
#    SafeAreaInsets | Theme | UnknownObject | UserAgent | FlowActionResult |
#    ModelContextContentBlock | ModelContextUpdate | SendFollowUpOptions |
#    HostContext | ToolCallResult | ToolResult | UnifiedWidgetClient |
#    detectPlatform | isMCPApps | isOpenAI | WidgetPlatform }
#    from "@waniwani/sdk/mcp/react" → "@waniwani/sdk/legacy/react"
#
#    Leave imports of { useWaniwani | UseWaniwaniOptions | WaniwaniWidget }
#    on "@waniwani/sdk/mcp/react" — those are non-legacy.

# 3. Next.js adapter → @waniwani/sdk/legacy/next-js
#    Rewrite "@waniwani/sdk/next-js" → "@waniwani/sdk/legacy/next-js"
#    (every export of the old path was moved; no symbol-level filtering needed)

# 4. Express adapter → @waniwani/sdk/legacy/express-js
#    Rewrite "@waniwani/sdk/express-js" → "@waniwani/sdk/legacy/express-js"

# 5. Chat-server types
#    "@waniwani/sdk/chat/server" still works as a re-export shim.
#    No required rewrite. If you want to drop the shim early, point the imports
#    at the legacy server-types module that backs your adapter.
```

If you split imports across files, the only ambiguous case is **step 1 vs step 3 (Express) when both come from the same root**. Mechanical rule: **the source path determines the destination, not the symbol name**. The same symbol does not appear in two unrelated source paths within this matrix.

### Verifying a one-shot migration

After substituting, the codebase should still typecheck and run unchanged. Run:

```bash theme={null}
bun run typecheck
bun run lint
bun test
```

If you see errors of the form `Module '"@waniwani/sdk/mcp"' has no exported member 'X'`, it means that symbol is being moved entirely out of the old path in a later major (0.14.0). Until then the old import keeps working — the matrix above tells you the final destination.

### Verifying a customer codebase has zero legacy imports

To audit a downstream repo for any remaining legacy imports:

```bash theme={null}
# Any import from a legacy path
grep -rn "@waniwani/sdk/legacy" src/ app/ pages/

# Legacy symbols still pulled through non-legacy paths.
# These greps only flag the moved symbols; OSS symbols (createFlow, KvStore,
# withWaniwani, useWaniwani, …) stay on the original paths and are not matched.

grep -rEn 'createTool|createResource|registerTools|ToolConfig|ToolHandler|ToolHandlerContext|RegisteredTool|ToolToolCallback|ResourceConfig|RegisteredResource|WidgetCSP|detectPlatform|isMCPApps|isOpenAI|WidgetPlatform|HostContext|ToolCallResult|ToolResult|UnifiedWidgetClient' src/ app/ pages/ \
  | grep "@waniwani/sdk/mcp"

grep -rEn 'WidgetProvider|useWidgetClient|useToolOutput|useToolResponseMetadata|useCallTool|useSendFollowUp|useFlowAction|useUpdateModelContext|useDisplayMode|useRequestDisplayMode|useTheme|useLocale|useSafeArea|useMaxHeight|useWidgetState|useOpenExternal|useIsChatGptApp|InitializeNextJsInIframe|LoadingWidget|DevModeProvider' src/ app/ pages/ \
  | grep "@waniwani/sdk/mcp/react"

grep -rEn 'from ["'\'']@waniwani/sdk/next-js["'\'']' src/ app/ pages/
grep -rEn 'from ["'\'']@waniwani/sdk/express-js["'\'']' src/ app/ pages/
```

The first command should produce hits (those are the new paths). The remaining commands should produce **either zero hits, or the same lines as before the migration** (meaning the back-compat shim is doing its job and you can defer the rewrite).

### `ChatCard` → `ChatEmbed`

`ChatCard` is still exported but marked `@deprecated`. It wraps `ChatEmbed` with always-visible card chrome (header, border, fixed dimensions) and assumes the Waniwani-hosted backend.

<Note>
  Because `ChatCard` assumed the hosted backend, most callers want [`WaniwaniChat`](/sdk/chat/react), not `ChatEmbed` — it keeps the hosted wiring and adds dashboard configuration, visitor correlation, and tracking. Reach for `ChatEmbed`, as the rewrite below shows, only if you run the chat backend yourself.
</Note>

```tsx theme={null}
// Before
import { ChatCard } from "@waniwani/sdk/chat";

<ChatCard
  apiKey={process.env.NEXT_PUBLIC_WANIWANI_API_KEY}
  title="Assistant"
  width={500}
  height={600}
  welcomeMessage="Hi! How can I help?"
/>
```

```tsx theme={null}
// After — bring-your-own-backend, no card chrome
import { ChatEmbed } from "@waniwani/sdk/chat";

<ChatEmbed
  api="/api/my-chat-endpoint"
  welcome={{ title: "Assistant", description: "Hi! How can I help?" }}
/>
```

`ChatEmbed` does not fetch `/config` or `/tool` against the Waniwani host — you point `api` at your own endpoint and (optionally) supply `mcp.resourceEndpoint` if your backend serves widget resources.

### `evals/*` removed

The `src/evals/*` subtree (chat eval runner, scorers, reporter) was removed entirely. No re-export shim. If you imported `runChatEval`, `createScorer`, or any sibling from `@waniwani/sdk/evals`, the build will fail on upgrade — there is no equivalent in this release. Eval tooling has moved to the Waniwani platform and is no longer shipped in-SDK.

***

## 0.12.0: `addNode` object form

The positional `.addNode(id, run, options?)` signature is deprecated in favor of an options-bag form. Metadata sits at the top of the call where the eye lands, the handler is a named field, and future options can be added without widening a positional signature.

### Before

```ts theme={null}
flow
  .addNode("ask_family_details", ({ interrupt }) => {
    return interrupt({
      partnerName: { question: "What is your partner's name?" },
      numKids: { question: "How many children do you have?" },
    });
  }, { label: "Ask family details" });
```

### After

```ts theme={null}
flow.addNode({
  id: "ask_family_details",
  label: "Ask family details",
  run: ({ interrupt }) =>
    interrupt({
      partnerName: { question: "What is your partner's name?" },
      numKids: { question: "How many children do you have?" },
    }),
});
```

### What changed

* `id` replaces the first positional argument.
* `run` replaces the second positional argument (the handler).
* `label` and `hideFromFunnel` move from the third `options` argument onto the same config object.
* `label` is now optional. When omitted, it defaults to `id`. The positional form required `label` whenever you passed an `options` object.

### Compatibility

Both signatures are supported. The positional form is marked `@deprecated` and will be removed in **0.13.0**. You can mix the two within the same flow during the transition. There is no functional difference between the two shapes.

### Type export

A new `AddNodeConfig<TState, TName>` type is exported from `@waniwani/sdk/mcp` if you need to type a config object outside the call site.

```ts theme={null}
import type { AddNodeConfig } from "@waniwani/sdk/mcp";

const askEmail: AddNodeConfig<MyState, "ask_email"> = {
  id: "ask_email",
  run: ({ interrupt }) =>
    interrupt({ email: { question: "What's your email?" } }),
};

flow.addNode(askEmail);
```


# Chat embed
Source: https://docs.waniwani.ai/sdk/chat/embed

Drop-in chat for any website. The dashboard generates the snippet — you paste it.

The chat embed is a self-contained IIFE bundle that drops the Waniwani chat into any website. It talks directly to `app.waniwani.ai`, so no backend proxy is required on your side.

<Note>
  **Platform feature.** The dashboard generates the embed snippet for your project. [Open app.waniwani.ai](https://app.waniwani.ai) to get yours, or read more about the [Platform](/sdk/platform/overview).
</Note>

## Quick start

1. Open your project on [app.waniwani.ai](https://app.waniwani.ai) and copy the chat embed snippet from the project settings.
2. Paste it into your site's HTML, alongside a mount point where you want the chat to appear:

```html theme={null}
<!-- Where the chat appears, sized by your CSS -->
<div data-waniwani-embed style="height: 600px; max-width: 480px;"></div>

<!-- The <script> tag you copied from the dashboard goes here. -->
```

That's it. The chat mounts inside your marker div via Shadow DOM (so its styles never leak into your page).

The snippet carries identifiers only — your project token, the channel ID, and the API URL. Title, welcome message, placeholder, suggestions, thread history and tool-call display are never baked in: the embed fetches them from your channel at runtime, so changing them in the dashboard updates live sites with no redeploy. Theming is the exception — it has no dashboard equivalent and is set on the tag (`data-theme`) or in CSS. **Don't hand-author the snippet** — the channel ID is issued by the Platform and required for the embed to route correctly.

## Modes

The embed renders in one of two modes, set with `data-mode` on the `<script>` tag:

| Mode               | What it does                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inline` (default) | Mounts the chat into a `<div data-waniwani-embed></div>` marker on the page. You control the size with CSS or `data-height`. If no marker exists, one is created in front of the `<script>` tag, so a bare snippet works with no markup changes — note that a container we create renders as a centered card (max-width `28rem`, rounded, bordered), while one you place is styled entirely by you. |
| `floating`         | Docks a compact composer bar at the bottom center of the viewport. Clicking it expands the bar, and starting a conversation opens the full chat panel — bottom-anchored and width-capped on desktop, full-screen on mobile. No marker element needed.                                                                                                                                               |

Use `inline` when the chat is part of the page (a section, or the page hero). Use `floating` when it should be available everywhere without taking up layout space.

```html theme={null}
<!-- Inline: the chat lives in your layout -->
<script src="…/embed.js" data-token="wwp_..." data-channel-id="..." defer></script>

<!-- Floating: a docked composer bar at the bottom of the viewport -->
<script src="…/embed.js" data-token="wwp_..." data-channel-id="..." data-mode="floating" defer></script>
```

If you want React-component-level control over the inline mount, see [Chat in React](/sdk/chat/react).

## Sizing

Inline mode only — in `floating` mode the panel sizes itself.

The embed fills its container. Give the `<div data-waniwani-embed>` a definite size via CSS, or set `data-height` on the script tag:

```html theme={null}
<!-- Fixed height -->
<div data-waniwani-embed style="height: 600px;"></div>

<!-- Bounded by max-height -->
<div data-waniwani-embed style="max-height: 80vh;"></div>

<!-- Flex column child -->
<div style="display: flex; flex-direction: column; max-height: 800px;">
  <div data-waniwani-embed style="flex: 1 1 auto; min-height: 0;"></div>
</div>
```

A container you leave unstyled is `500px` tall. That default is written with `:where()`, so it carries no specificity and any rule you write beats it — including `height: auto` to let the chat grow with its content. A `ResizeObserver` mirrors the container's `max-height` onto the embed so padding and borders are respected.

## Overriding attributes

You can edit `data-*` attributes on the `<script>` tag to tweak behavior. Do it sparingly: an attribute set here permanently outranks the channel config the embed fetches from the dashboard (resolution order is dashboard → `data-*` → `init()`), so a title pinned on the tag can no longer be changed by whoever owns the channel.

| Attribute                    | Type                       | Notes                                                                                                                                                                                                                                                                                                       |
| ---------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-mode`                  | string                     | `"inline"` (default) or `"floating"`. See [Modes](#modes).                                                                                                                                                                                                                                                  |
| `data-height`                | string                     | Height of the inline container. Any CSS length (`"500px"`, `"80vh"`) or a bare number treated as px. Defaults to `500px`. Ignored in `floating` mode.                                                                                                                                                       |
| `data-title`                 | string                     | Header title. No default — with no title (and no thread history) the chat renders headerless.                                                                                                                                                                                                               |
| `data-hide-header`           | boolean                    | Force-hide the sticky header when your page already provides its own chrome.                                                                                                                                                                                                                                |
| `data-welcome-message`       | string                     | Greeting shown before the first message.                                                                                                                                                                                                                                                                    |
| `data-placeholder`           | string                     | Input field placeholder.                                                                                                                                                                                                                                                                                    |
| `data-suggestions`           | string (comma-separated)   | Initial suggestion chips.                                                                                                                                                                                                                                                                                   |
| `data-suggestion-origins`    | string (comma-separated)   | Which providers may fill the per-turn pill row: any of `"channel"`, `"page"`, `"flow"`, `"followup"`. Defaults to `"channel,page,followup"` — include `"flow"` to render pills from a flow's `interrupt({ suggestions })`. An empty value renders none. Initial chips (`data-suggestions`) show either way. |
| `data-enable-thread-history` | boolean                    | Persist threads in IndexedDB. Defaults to `false`.                                                                                                                                                                                                                                                          |
| `data-locale`                | string                     | UI language for built-in labels: `"en"`, `"fr"`, `"es"`. Defaults to detecting from `<html lang>` / `navigator.language`, falling back to English.                                                                                                                                                          |
| `data-disclaimer`            | string \| `"false"`        | AI transparency notice under the input (EU AI Act). A string overrides the default wording; `"false"` (or `"0"`) hides it.                                                                                                                                                                                  |
| `data-css`                   | string                     | URL to a custom stylesheet loaded into the shadow root. Targets the stable `.ww-*` classes — see [Theming](/sdk/chat/theming).                                                                                                                                                                              |
| `data-theme`                 | string                     | `"light"` (default), `"dark"`, or `"auto"` (follows `prefers-color-scheme`).                                                                                                                                                                                                                                |
| `data-assistant-bubble`      | boolean                    | Render assistant replies in a filled, themeable bubble. Defaults to `false` (plain text).                                                                                                                                                                                                                   |
| `data-visitor-id`            | string                     | Override the anonymous visitor id with one you already track (a PostHog / Amplitude / Segment distinct id, your own cookie). See [Link visitors to your analytics](#link-visitors-to-your-analytics).                                                                                                       |
| `data-show-tool-calls`       | boolean \| `"titles-only"` | `true` (default) makes each step expandable to its request/response JSON, `"titles-only"` shows step labels, `false` hides the chain and reasoning trace.                                                                                                                                                   |
| `data-disable-page-view`     | boolean                    | Opt out of the `page.viewed` event fired once on mount. Set on surfaces where a page view would pollute the funnel (internal tools, previews, authenticated app shells).                                                                                                                                    |

Floating mode only:

| Attribute            | Type   | Notes                                                                                                                                |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data-launcher-text` | string | Placeholder shown in the docked composer bar (e.g. `"Ask anything…"`). Falls back to `data-placeholder`, then to a localized prompt. |
| `data-appear-delay`  | number | Milliseconds before the dock animates in, letting the page settle first. Defaults to `2000`. `0` shows it immediately.               |

Per-URL show/hide rules for the floating bar are configured in the dashboard, not on the script tag.

Leave the wiring attributes (`data-token`, `data-channel-id`, `data-api`, the script `src`) as the dashboard generated them.

Beyond the `data-theme` preset and `data-assistant-bubble`, individual colors, fonts, and bubble shapes have no `data-*` equivalent — set `--ww-*` CSS variables instead. They inherit through the widget's Shadow DOM, so declare them on `[data-waniwani-embed]` in inline mode, or anywhere on the host page (`:root` works) in floating mode, where there is no container of your own. See [Theming & customization](/sdk/chat/theming) for the full variable list and deep-customization recipes.

Full type definitions: [`EmbedConfig`](https://github.com/WaniWani-AI/sdk/blob/main/src/chat/web/embed/config.ts) and [`ChatTheme`](https://github.com/WaniWani-AI/sdk/blob/main/src/chat/web/%40types.ts).

## Programmatic init

For runtime control (computing options dynamically, mounting on demand), drop the `data-token` attribute from the script tag and call `init()` manually. You still need the wiring attributes from a dashboard-issued snippet:

```html theme={null}
<div data-waniwani-embed></div>

<!-- Keep the script src and data-channel-id from the dashboard snippet,
     just remove data-token so the embed doesn't auto-init. -->
<script
  src="https://cdn.jsdelivr.net/npm/@waniwani/sdk@latest/dist/chat/embed.js"
  data-channel-id="..."
  defer
></script>
<script>
  window.addEventListener("DOMContentLoaded", () => {
    window.WaniWani.chat.init({
      token: "wwp_...", // from the dashboard snippet
      welcomeMessage: computeGreetingForUser(),
    });
  });
</script>
```

`init()` returns an instance with `destroy()` and `sendMessage(text)`. You can also call `window.WaniWani.chat.destroy()` and `window.WaniWani.chat.sendMessage("...")` directly on the global.

`init()` also accepts an `onEvent` callback that mirrors chat lifecycle events (opens, messages, errors, link clicks) into your own analytics — Amplitude, Segment, gtag — with your page's identity attached automatically. See [Widget events (onEvent)](/sdk/chat/widget-events).

## Link visitors to your analytics

By default the embed mints its own anonymous **visitor id**, a stable opaque value persisted in the browser's `localStorage`. It rides on every chat request and tracking event, so a visit is attributable before the first message mints a session (see [Sessions](/sdk/tracking/sessions)).

If your site already tracks visitors with PostHog, Amplitude, Segment, or a first-party cookie, override that id with your own. Waniwani then correlates its sessions and events to the same visitor you see in your analytics, and your server-side MCP tools and flows read the id back as `context.waniwani.visitorId`, so they can send events straight to the same analytics tool the id came from.

There are three ways to set it. Pick the one that matches when your id is available.

### If you know the id up front

Set it declaratively on the script tag:

```html theme={null}
<script
  src="https://cdn.jsdelivr.net/npm/@waniwani/sdk@latest/dist/chat/embed.js"
  data-token="wwp_..."
  data-channel-id="..."
  data-visitor-id="the-id-from-your-system"
  defer
></script>
```

Or pass it to `init()` when you initialize programmatically. `init()` accepts a string or a resolver (sync or async), so you can read the id inline:

```js theme={null}
window.WaniWani.chat.init({
  token: "wwp_...",
  visitorId: "the-id-from-your-system",
  // or a resolver: visitorId: () => posthog.get_distinct_id(),
});
```

### If the id resolves asynchronously (the common case)

Analytics SDKs usually assign a distinct id only after they bootstrap, so read it when it's ready and hand it to the widget. `setVisitorId()` is safe to call at any time, before or after `init()`, and the new id applies to the next chat request and tracking event:

```js theme={null}
// PostHog
posthog.onFeatureFlags(() => {
  window.WaniWani.chat.setVisitorId(posthog.get_distinct_id());
});

// Amplitude
const amplitudeId = amplitude.getDeviceId();
if (amplitudeId) {
  window.WaniWani.chat.setVisitorId(amplitudeId);
}
```

A blank value is ignored, so an id that isn't ready yet never wipes a good one. Read the id the widget will send with `window.WaniWani.chat.getVisitorId()`.

<Note>
  The visitor id identifies a **device / browser**, not a signed-in account. When a visitor logs in, keep the visitor id and additionally call [`identify()`](/sdk/tracking/identify) with your account id, so anonymous and known activity stitch together.
</Note>

## Self-hosting the JS bundle

If you'd rather not load from a CDN, pin a specific SDK version and serve the bundled file yourself. The `data-*` attributes still come from the dashboard snippet — you're only swapping where `embed.js` is served from:

```bash theme={null}
bun add @waniwani/sdk
cp node_modules/@waniwani/sdk/dist/chat/embed.js public/waniwani-embed.js
```

Then point the dashboard-issued snippet at your local copy:

```html theme={null}
<div data-waniwani-embed></div>
<script
  src="/waniwani-embed.js"
  data-token="wwp_..."
  data-channel-id="..."
  defer
></script>
```

## How it works

1. The script reads its own `data-*` attributes (token, channel ID, mode, theming, content overrides).
2. On `DOMContentLoaded` (or immediately, if the DOM is already ready), it mounts the chat via Shadow DOM — inside `[data-waniwani-embed]` in `inline` mode, or in its own anchored container in `floating` mode.
3. The chat calls `app.waniwani.ai/api/mcp/chat` with the project token and streams responses back through Server-Sent Events.
4. Conversation history lives only in memory by default; set `data-enable-thread-history` to persist threads in IndexedDB on the user's device.

No server-side integration on your side.


# Chat in React
Source: https://docs.waniwani.ai/sdk/chat/react

Embed the Waniwani chat as a React component in your app.

Two React components ship from `@waniwani/sdk/chat`. Pick based on who runs the chat backend:

| Component          | Use when                                  | Backend        |
| ------------------ | ----------------------------------------- | -------------- |
| **`WaniwaniChat`** | You want the hosted chat. **Start here.** | Ours, no setup |
| `ChatEmbed`        | You self-host the chat backend            | Yours          |

The React components mount inline: they render wherever you place them in your layout, and you control the container. There is no launcher or floating bubble in the React path — for that, use the [embed script](/sdk/chat/embed) in `floating` mode.

<Note>
  **Platform feature.** Requires a Waniwani project token (`wwp_...`). [Get one at app.waniwani.ai](https://app.waniwani.ai) or read more about the [Platform](/sdk/platform/overview).
</Note>

## Install

```bash theme={null}
bun add @waniwani/sdk
```

Add the stylesheet to your app once (e.g. in `_app.tsx` or your root layout):

```ts theme={null}
import "@waniwani/sdk/chat/styles.css";
```

## WaniwaniChat

The hosted chat. Pass your project token and channel ID and it talks to `app.waniwani.ai` directly — no API route, no proxy, no backend work on your side.

```tsx theme={null}
import { WaniwaniChat } from "@waniwani/sdk/chat";

<WaniwaniChat token="wwp_..." channelId="..." />;
```

The system prompt, welcome message, placeholder, suggestions, thread history and tool-call display are configured per channel in the dashboard, so business users can change them without a deploy. Theming has no dashboard equivalent — set it in code via `overrides.appearance`.

### Sizing and placement

`WaniwaniChat` fills its parent. Put it wherever you want it and size the container:

```tsx theme={null}
<section style={{ height: 600, maxWidth: 480 }}>
  <WaniwaniChat token="wwp_..." channelId="..." />
</section>
```

To use it as a full-width page hero, give the wrapper the height you want and let the chat fill it. `className` is applied to the root element if you'd rather style it directly.

### Per-page overrides

The dashboard is the source of truth. Use `overrides` only for a local tweak that doesn't justify a separate channel:

```tsx theme={null}
<WaniwaniChat
  token="wwp_..."
  channelId="..."
  overrides={{
    title: "Coverage guide",
    hideHeader: false,
    placeholder: "Tell me what's going on…",
    suggestions: ["I lost my coverage", "I'm turning 65 soon"],
    showToolCalls: "titles-only",
    appearance: { theme: "light", variables: { primaryColor: "#FFB929" } },
  }}
/>;
```

| Override              | Notes                                                                                                                                                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`               | Sticky header title                                                                                                                                                                                                               |
| `hideHeader`          | Force-hide the header when your page already provides chrome                                                                                                                                                                      |
| `welcomeMessage`      | Greeting before the first user message                                                                                                                                                                                            |
| `welcome`             | Rich welcome screen (icon, title, suggestion cards). Takes precedence over `welcomeMessage`                                                                                                                                       |
| `placeholder`         | Input placeholder                                                                                                                                                                                                                 |
| `suggestions`         | Initial suggestion chips                                                                                                                                                                                                          |
| `suggestionOrigins`   | Which providers may fill the per-turn pill row: any of `"channel"`, `"page"`, `"flow"`, `"followup"`. Defaults to `["channel", "page", "followup"]` — include `"flow"` to render pills from a flow's `interrupt({ suggestions })` |
| `enableThreadHistory` | Persist threads in IndexedDB                                                                                                                                                                                                      |
| `showToolCalls`       | `true` (default), `"titles-only"`, or `false`                                                                                                                                                                                     |
| `allowAttachments`    | Enable file attachments in the input                                                                                                                                                                                              |
| `appearance`          | Theme preset plus per-property overrides. Not dashboard-backed — this is where theming is set — see [Theming](/sdk/chat/theming)                                                                                                  |
| `classNames`          | Per-slot class overrides — see [Deep customization](#deep-customization)                                                                                                                                                          |
| `disclaimer`          | AI transparency notice under the input. A string overrides the wording, `false` hides it                                                                                                                                          |
| `locale`              | UI language for built-in labels: `"en"`, `"fr"`, `"es"`. Detected from `<html lang>` / `navigator.language` when unset                                                                                                            |
| `messages`            | Per-key overrides on the resolved locale catalog, to tweak individual built-in strings                                                                                                                                            |
| `disablePageView`     | Opt out of the `page.viewed` event fired once on mount. Set on surfaces where a page view would pollute the funnel                                                                                                                |
| `api`                 | Chat API URL. Rarely needed — defaults to `https://app.waniwani.ai/api/mcp/chat`                                                                                                                                                  |
| `mcpServerUrl`        | Override the MCP server URL. Rarely needed                                                                                                                                                                                        |

### Tracking from the host page

The `ref` exposes a `ChatHandle` with `track` and `identify` alongside the chat controls. `identify` takes the user id as its first argument, with optional traits second — it is not an object:

```tsx theme={null}
import { WaniwaniChat, type ChatHandle } from "@waniwani/sdk/chat";

const chat = useRef<ChatHandle>(null);

<WaniwaniChat ref={chat} token="wwp_..." channelId="..." />;

chat.current?.identify(user.id, { plan: "pro" });
chat.current?.track.leadQualified({ /* … */ });
```

Both are present on `WaniwaniChat` only — the bare `ChatEmbed` primitive has no Waniwani credential to send events with. See [Identify](/sdk/tracking/identify).

## ChatEmbed

A bare-bones primitive for when you run the chat backend yourself. `api` is required and there is no default; pass any endpoint implementing the [Vercel AI SDK chat protocol](https://ai-sdk.dev) and the component handles the rest.

<Note>
  Reach for `ChatEmbed` only when self-hosting. If you're using the Waniwani Platform, `WaniwaniChat` gives you the same UI plus dashboard configuration, visitor correlation, and tracking.
</Note>

```tsx theme={null}
import { ChatEmbed } from "@waniwani/sdk/chat";

<ChatEmbed
  api="/api/my-chat"
  body={{ environmentId, sessionId }}
  appearance={{ theme: "dark" }}
/>;
```

## Link visitors to your analytics

Both components accept a `visitorId` prop to override the anonymous id the widget generates with one you already track (a PostHog / Amplitude / Segment distinct id, your own cookie). Waniwani correlates its sessions and events to the same visitor your analytics sees, and your server-side MCP tools and flows read it back as `context.waniwani.visitorId`. Leave it unset to keep the auto-generated, `localStorage`-persisted id.

`visitorId` accepts a string, or a resolver that returns one. The resolver may be sync or async, which is handy when your analytics SDK only exposes its id after it bootstraps:

```tsx theme={null}
// A string you already hold
<WaniwaniChat token="wwp_..." channelId="..." visitorId={myCookieId} />;

// A sync resolver
<WaniwaniChat token="wwp_..." channelId="..." visitorId={() => posthog.get_distinct_id()} />;

// An async resolver — the widget uses the auto id until this settles
<WaniwaniChat
  token="wwp_..."
  channelId="..."
  visitorId={async () => (await analytics.ready()).anonymousId}
/>;
```

A blank or failed result is ignored, so a not-ready id never wipes a good one. The value is read live on every request, so updating it applies to the next message. See [Sessions](/sdk/tracking/sessions) for how the three correlation ids fit together.

<Tip>
  For an expensive async resolver, pass a stable reference (`useCallback`) so it isn't re-invoked on every render.
</Tip>

### Attachments

`ChatEmbed` takes the documents module's state as a prop, since it fetches no remote config of its own:

```tsx theme={null}
<ChatEmbed
  api="/api/my-chat"
  documentUpload={{
    enabled: true,
    maxBytes: 52428800,
    maxPdfPages: 1000,
    maxFiles: 10,
    accept: ["application/pdf", "image/png", "image/jpeg"],
  }}
/>;
```

The composer offers a paperclip, a drop target and paste only while `enabled` is true, and the upload endpoint enforces the same flag. `WaniwaniChat` and the script embed read all of this from the dashboard, so they need none of it. See [Documents](/sdk/modules/documents) for what an agent does with the files.

### Authentication

`headers` goes out with every chat request, and document uploads reuse it, so one bearer usually covers both.

```tsx theme={null}
<ChatEmbed api="/api/my-chat" headers={{ Authorization: `Bearer ${token}` }} />;
```

Set `uploadHeaders` when your upload endpoint takes a different credential than your chat endpoint. It is merged over `headers` on the document upload and discard calls, and leaves the chat request alone.

```tsx theme={null}
<ChatEmbed
  api="/api/my-chat"
  headers={{ Authorization: `Bearer ${token}`, "X-Tenant-Id": tenant }}
  uploadHeaders={{ Authorization: `Bearer ${uploadToken}` }}
/>;
```

Uploads there go out with the upload token and still carry `X-Tenant-Id`. Only the names you repeat are replaced, and the match ignores case, so `authorization` overrides `Authorization`.

Both land in the browser, so put only public credentials in them.

## Theming

Both components take an appearance preset (`light`, `dark`, or `auto`) with optional per-property overrides layered on top:

```tsx theme={null}
<WaniwaniChat
  token="wwp_..."
  channelId="..."
  overrides={{
    appearance: {
      theme: "light",
      variables: {
        primaryColor: "#03d916",
        borderRadius: 12,
        messageBorderRadius: 20,
        fontSize: 15,
      },
    },
  }}
/>;
```

`auto` follows the host's `prefers-color-scheme`. `variables` accepts every `ChatTheme` token — colors, message-bubble radius/padding/max-width, base font size and line height. The full token and CSS-variable list lives on [Theming & customization](/sdk/chat/theming).

## Deep customization

Two escape hatches when tokens aren't enough:

* **`appearance.assistantBubble`** — opt-in filled bubble for assistant replies (plain text by default), styled by `assistantBubbleColor` / `assistantBubbleTextColor`.
* **`classNames`** — per-slot class overrides merged onto the widget's own classes: `root`, `header`, `message`, `userBubble`, `assistantBubble`, `input`. Pass it directly on `ChatEmbed`, or as `overrides.classNames` on `WaniwaniChat`.

```tsx theme={null}
<ChatEmbed
  api="/api/my-chat"
  appearance={{ assistantBubble: true }}
  classNames={{
    header: "uppercase tracking-wide",
    userBubble: "shadow-md",
  }}
/>;
```

Recipes and the list of what remains non-themeable: [Theming & customization](/sdk/chat/theming).

## Mirroring events into your analytics

The hosted `WaniwaniChat` component accepts an `onEvent` prop that fires on chat lifecycle events (messages, session start, errors, link clicks) so you can mirror widget activity into your own analytics — Segment, Amplitude, gtag — with the page's identity attached automatically. `ChatEmbed`, the bring-your-own-backend primitive, does not expose it. See [Widget events (onEvent)](/sdk/chat/widget-events).


# Theming & customization
Source: https://docs.waniwani.ai/sdk/chat/theming

Rebrand the chat widget — colors, typography, message bubbles, and deep CSS customization — on both the script embed and the React component.

Every surface of the chat widget is themeable through the same token system, whether you use the [script embed](/sdk/chat/embed) or the [React component](/sdk/chat/react). Defaults are pinned so an untouched widget looks the same across releases — you only override what you care about.

## Presets

Pick `light` (default), `dark`, or `auto` (follows the visitor's `prefers-color-scheme`):

```html theme={null}
<!-- Script embed -->
<script src="…/embed.js" data-token="wwp_..." data-theme="dark"></script>
```

```tsx theme={null}
// React
<WaniwaniChat token="wwp_..." channelId="..." overrides={{ appearance: { theme: "auto" } }} />
```

## Theme tokens

Layer per-property overrides on top of a preset. The same keys work everywhere:

```tsx theme={null}
// React — ChatEmbed or WaniwaniChat (via overrides.appearance)
<ChatEmbed
  api="/api/my-chat"
  appearance={{
    theme: "light",
    variables: {
      primaryColor: "#0a6c74",
      userBubbleColor: "#0a6c74",
      userBubbleTextColor: "#ffffff",
      messageBorderRadius: 20,
      messagePaddingX: 18,
      messageMaxWidth: "75%",
      fontFamily: "Georgia, serif",
      fontSize: 15,
      lineHeight: "1.6",
    },
  }}
/>
```

```js theme={null}
// Script embed — programmatic init
window.WaniWani.chat.init({
  token: "wwp_...",
  appearance: {
    theme: "light",
    variables: { primaryColor: "#0a6c74", messageBorderRadius: 20 },
  },
});
```

## CSS variables

The widget exposes a `--ww-*` namespace that pierces the Shadow DOM boundary, so the script embed can be themed from your page's own CSS:

```html theme={null}
<style>
  [data-waniwani-embed] {
    --ww-primary: #0a6c74;
    --ww-msg-radius: 20px;
    --ww-font: "Inter", sans-serif;
  }
</style>
<div data-waniwani-embed></div>
```

In `floating` mode there is no container of your own, so declare the variables on any ancestor — `:root` is the simplest. They inherit down into the widget either way.

Unset variables fall back to the preset's defaults, and your overrides win in both light and dark modes.

`borderWidth` and `boxShadow` are the panel's opt-in chrome — both are no-ops until you set them, so a widget slotted into your own bordered container doesn't draw a second border. In the script embed they apply to the `[data-waniwani-embed]` container rather than the chat inside it, since the container clips anything drawn within.

| CSS Variable                 | Theme token                | Property                         | Default (light) | Default (dark) |
| ---------------------------- | -------------------------- | -------------------------------- | --------------- | -------------- |
| `--ww-primary`               | `primaryColor`             | Primary brand colour             | `#6366f1`       | `#6366f1`      |
| `--ww-primary-fg`            | `primaryForeground`        | Text on primary                  | `#1f2937`       | `#ffffff`      |
| `--ww-bg`                    | `backgroundColor`          | Panel background                 | `#ffffff`       | `#212121`      |
| `--ww-text`                  | `textColor`                | Default text colour              | `#1f2937`       | `#ececec`      |
| `--ww-muted`                 | `mutedColor`               | Secondary text                   | `#6b7280`       | `#8e8ea0`      |
| `--ww-border`                | `borderColor`              | Border colour                    | `#e5e7eb`       | `#444444`      |
| `--ww-border-width`          | `borderWidth`              | Panel border width (px)          | `0`             | `0`            |
| `--ww-shadow`                | `boxShadow`                | Panel box-shadow shorthand       | `none`          | `none`         |
| `--ww-assistant-bubble`      | `assistantBubbleColor`     | Assistant bubble bg              | `#f3f4f6`       | `#2f2f2f`      |
| `--ww-assistant-bubble-text` | `assistantBubbleTextColor` | Assistant bubble text            | `#1f2937`       | `#ececec`      |
| `--ww-user-bubble`           | `userBubbleColor`          | User bubble bg                   | `#f4f4f4`       | `#303030`      |
| `--ww-user-bubble-text`      | `userBubbleTextColor`      | User bubble text                 | `#1f2937`       | `#ffffff`      |
| `--ww-input-bg`              | `inputBackgroundColor`     | Input field bg                   | `#f9fafb`       | `#2f2f2f`      |
| `--ww-header-bg`             | `headerBackgroundColor`    | Header background                | `#ffffff`       | `#1e1e1e`      |
| `--ww-header-text`           | `headerTextColor`          | Header text                      | `#1f2937`       | `#ececec`      |
| `--ww-status`                | `statusColor`              | Status dot                       | `#22c55e`       | `#22c55e`      |
| `--ww-tool-card`             | `toolCardColor`            | Tool call card bg                | `#f4f4f5`       | `#262626`      |
| `--ww-glass-tint`            | `glassTint`                | Floating bar glass tint          | `unset`         | `unset`        |
| `--ww-glass-tint-opacity`    | `glassTintStrength`        | Floating bar glass tint strength | `unset`         | `unset`        |
| `--ww-radius`                | `borderRadius`             | Panel border-radius              | `16px`          | `16px`         |
| `--ww-msg-radius`            | `messageBorderRadius`      | Message bubble radius            | `8px`           | `8px`          |
| `--ww-msg-pad-x`             | `messagePaddingX`          | Message bubble padding X         | `16px`          | `16px`         |
| `--ww-msg-pad-y`             | `messagePaddingY`          | Message bubble padding Y         | `12px`          | `12px`         |
| `--ww-msg-max-width`         | `messageMaxWidth`          | Message bubble max width         | `80%`           | `80%`          |
| `--ww-font`                  | `fontFamily`               | Font family                      | system stack    | system stack   |
| `--ww-font-size`             | `fontSize`                 | Base message font size           | `1rem`          | `1rem`         |
| `--ww-line-height`           | `lineHeight`               | Base message line height         | `1.5`           | `1.5`          |

`glassTint` and `glassTintStrength` tint the floating bar's frosted-glass surface — the expanded suggestion card and open panel in `floating` mode — layering a colour over the existing backdrop blur. `glassTint` takes any CSS colour string; `glassTintStrength` is a unitless string from `"0"` to `"1"` setting how strongly the tint is applied. Both are set programmatically through `appearance.variables`:

```tsx theme={null}
// React — tint the floating bar's frosted glass with a brand colour
<WaniwaniChat
  token="wwp_..."
  channelId="..."
  overrides={{
    appearance: {
      variables: { glassTint: "#0a6c74", glassTintStrength: "0.12" },
    },
  }}
/>
```

Like `borderWidth` and `boxShadow`, they're additive: leave them unset and the floating bar renders exactly as before.

## Assistant message bubble (opt-in)

Assistant replies render as plain text by default. Turn them into filled bubbles — styled by `assistantBubbleColor` / `assistantBubbleTextColor`, sharing the user bubble's radius and padding — with `assistantBubble`:

```html theme={null}
<!-- Script tag: "true"/"1" or a bare attribute enable it; "false" forces it off -->
<script src="…/embed.js" data-token="wwp_..." data-assistant-bubble="true"></script>
```

```tsx theme={null}
// React
<WaniwaniChat
  token="wwp_..."
  channelId="..."
  overrides={{ appearance: { assistantBubble: true } }}
/>
```

Leave it unset and assistant messages stay bubble-less — existing widgets are unchanged.

## Deep customization

Tokens cover colors, typography, and bubble shape. To restyle an element beyond what a token exposes, target it directly.

**React** — pass `classNames` (available on `ChatEmbed` directly, or `overrides.classNames` on `WaniwaniChat`). Each string is merged onto that slot:

```tsx theme={null}
<WaniwaniChat
  token="wwp_..."
  channelId="..."
  overrides={{
    classNames: {
      root: "my-chat",
      header: "ww:uppercase ww:tracking-wide",
      userBubble: "ww:shadow-md",
      input: "ww:ring-2 ww:ring-[#0a6c74]",
    },
  }}
/>
```

Slots: `root`, `header`, `message`, `userBubble`, `assistantBubble`, `input`.

**Script embed** — the widget renders in a Shadow DOM, so your page's own selectors cannot reach inside. Inject a stylesheet with `data-css` and target the stable semantic classes:

```html theme={null}
<script
  src="…/embed.js"
  data-token="wwp_..."
  data-css="https://your.site/widget.css"
></script>
```

```css theme={null}
/* widget.css — loaded into the widget's Shadow DOM */
.ww-header { letter-spacing: 0.02em; }
.ww-input { box-shadow: 0 0 0 2px rgba(10, 108, 116, 0.25); }
.ww-message-user .ww-bubble { box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1); }
.ww-message-assistant .ww-bubble { border: 1px solid #0a6c74; }
```

Stable hooks: `.ww-message`, `.ww-message-user`, `.ww-message-assistant`, `.ww-bubble`, `.ww-header`, `.ww-input`. These are guaranteed selectors — the internal `ww:`-prefixed utility classes are not.

## What is not themeable

To set expectations for a full rebrand, these are intentionally fixed today:

* **Typographic scale beyond the base** — `fontSize` / `lineHeight` set the message base; per-heading sizes inside markdown and built-in label sizes/weights are not individually exposed.
* **Chrome corner radii** — `messageBorderRadius` shapes message bubbles only; tool-call cards, the chain-of-thought accordion, menus, and welcome-screen buttons keep their fixed radii.
* **Floating launcher accent** — the dock's animated border-glow uses a fixed accent gradient.
* **"Powered by" mark** — the footer logo is not removable via theming.

For anything in this list, [reach out](https://waniwani.ai) — some are candidates for future tokens.

Full type definitions: [`ChatTheme` and `ChatClassNames`](https://github.com/WaniWani-AI/sdk/blob/main/src/chat/web/%40types.ts).


# Widget events (onEvent)
Source: https://docs.waniwani.ai/sdk/chat/widget-events

Mirror chat widget activity into your own analytics with the onEvent callback.

The chat widget can mirror its lifecycle events into the host page through a single `onEvent` callback. Both hosted surfaces accept it: `WaniWani.chat.init({ onEvent })` on the script embed, and the `onEvent` prop on the React component.

The embed mounts in your page's DOM (the shadow root isolates styles only), so the callback runs in your page's own JS context. Forward events straight into `window.amplitude`, `window.analytics`, or `gtag` and your page-side analytics SDK attaches its own user identity automatically — no server-side identity plumbing, and no Amplitude/Segment SDK is ever loaded inside the widget.

<Note>
  **When to use which channel.** `onEvent` mirrors widget activity into **your** analytics on the host page — it never leaves the browser unless your callback sends it somewhere. It is separate from platform ingest tracking (`WaniWani.chat.track`, funnel events, the typed event catalog), which sends events **to the Waniwani platform** for funnel analytics. Use `onEvent` to see chat activity next to your existing product analytics; use [tracking events](/sdk/tracking/events) to power Waniwani funnels. The two channels are independent and can be used together.
</Note>

## The events

| Event                | Fired when                                                                                                                                         | Extra `properties`                                                                                                                                                        |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chat.ready`         | Widget mounted and config resolved, or the readiness timeout elapses (all modes; fires even on pages where visibility rules hide the floating bar) | —                                                                                                                                                                         |
| `chat.opened`        | Full chat panel opened (floating mode only; the collapsed dock does not count)                                                                     | —                                                                                                                                                                         |
| `chat.closed`        | Full chat panel closed (floating mode only; a page-gate hiding an open panel also emits this)                                                      | —                                                                                                                                                                         |
| `message.sent`       | The visitor (or the imperative API, e.g. `sendMessage`) submits a message (never includes the message text)                                        | —                                                                                                                                                                         |
| `message.received`   | Assistant reply finished (never includes the message text)                                                                                         | —                                                                                                                                                                         |
| `session.started`    | Server assigned the session id on the first exchange (restored threads don't re-fire)                                                              | `{ sessionId }`                                                                                                                                                           |
| `thread.changed`     | Thread created or switched (requires thread history)                                                                                               | `{ threadId }`                                                                                                                                                            |
| `chat.error`         | Chat request failed                                                                                                                                | `{ message }` (truncated to 200 chars)                                                                                                                                    |
| `suggestion.clicked` | Suggestion pill or welcome card clicked (dock pills, in-chat pills, welcome cards)                                                                 | `{ text, index, origin }` (`index` is `-1` when the position is unknown; `origin` is `"channel"`, `"page"`, `"flow"`, or `"followup"` — which provider supplied the pill) |
| `link.clicked`       | Anchor clicked inside the conversation                                                                                                             | `{ url }` (absolute URL)                                                                                                                                                  |

Do not assume `chat.opened` precedes the first `message.sent`: a send from the docked bar opens the panel and sends in one action, and the open transition is reported after the send.

<Note>
  **Separate from the `track()` taxonomy.** Some `onEvent` names (`session.started`, `link.clicked`) also exist as event names in the hosted `track()` funnel taxonomy — same concepts, but a separate client-side channel with different payload shapes. `onEvent` events are not `client.track()` events, do not feed the platform funnel dashboard, and should not be forwarded into `client.track()` as-is even where names coincide.
</Note>

## The payload

Every callback receives a `WidgetEvent` — exported from `@waniwani/sdk/chat` alongside `WidgetEventName` and `WidgetMode`:

```ts theme={null}
import type { WidgetEvent, WidgetEventName, WidgetMode } from "@waniwani/sdk/chat";

// WidgetEvent is a discriminated union on `name`:
// {
//   name: WidgetEventName;              // one of the 10 events above
//   mode: WidgetMode;                   // "inline" | "floating"
//   sessionId?: string;                 // undefined before the first exchange
//   timestamp: number;                  // epoch milliseconds at emit time
//   properties?: { ... };               // per-event extras from the table above
// }
```

`mode` is the embed surface: `"floating"` for the floating bar, `"inline"` for an in-page mount. `<WaniwaniChat>` reports `"inline"` — it is an in-page mount, and this is the same `mode` tag its server-side events (chat requests, `page.viewed`) carry, so both streams correlate.

Narrowing on `name` types `properties` automatically:

```ts theme={null}
function handle(event: WidgetEvent) {
  if (event.name === "suggestion.clicked") {
    // event.properties is { text: string; index: number }
  }
}
```

Event names are neutral and fixed — the widget never adopts your analytics naming. Map them to your own schema inside the callback.

## Script embed → Amplitude

`onEvent` is programmatic-only on the script embed: a function cannot be expressed as a `data-*` attribute, so pass it to `WaniWani.chat.init()`.

```html theme={null}
<script src="https://app.waniwani.ai/embed.js" defer></script>
<script>
  document.addEventListener("DOMContentLoaded", () => {
    const names = {
      "chat.opened": "chat_opened",
      "chat.closed": "chat_closed",
      "message.sent": "user_message",
      "message.received": "bot_message",
    };
    WaniWani.chat.init({
      token: "wwp_...",
      mode: "floating",
      onEvent: (event) => {
        window.amplitude.track(names[event.name] || event.name, {
          page: window.location.pathname,
          sessionId: event.sessionId,
        });
      },
    });
  });
</script>
```

Because the Amplitude snippet on your page already identified the user, every mirrored event lands in Amplitude under that same identity.

## React → Segment

The `WaniwaniChat` component takes the same callback as an `onEvent` prop (`chat.opened`/`chat.closed` are floating-embed-only and never fire here):

```tsx theme={null}
import { WaniwaniChat, type WidgetEvent } from "@waniwani/sdk/chat";

function Support() {
  const handleWidgetEvent = (event: WidgetEvent) => {
    window.analytics.track(event.name, {
      mode: event.mode,
      sessionId: event.sessionId,
      ...(event.name === "chat.error"
        ? { errorMessage: event.properties.message }
        : {}),
    });
  };

  return (
    <WaniwaniChat token="wwp_..." channelId="..." onEvent={handleWidgetEvent} />
  );
}
```

## Privacy

Message content never passes through this channel. `message.sent` and `message.received` tell the host *that* a message was exchanged, never what was said. The one text field that does flow through is `suggestion.clicked`'s `text` — suggestion pills are operator-authored config, not user input.

## Error isolation

Exceptions thrown by your callback are swallowed and logged as a console warning; they never break the widget or block other subscribers. Still, keep the callback fast — it runs synchronously on the widget's event path.

<Warning>
  `ChatEmbed`, the bring-your-own-backend React primitive, does **not** expose `onEvent`. Like `track`/`identify`, it is a hosted-surface feature of `WaniwaniChat` and the script embed.
</Warning>


# CLI overview
Source: https://docs.waniwani.ai/sdk/cli/overview

The @waniwani/cli connects a local repo to a Waniwani agent and runs your MCP server against the hosted playground in one command.

`@waniwani/cli` is the official command-line tool for [Waniwani](https://app.waniwani.ai). It wires a local repo to a Waniwani agent, runs your MCP server locally against the hosted playground, and removes the manual steps of provisioning GitHub, Vercel, and API keys.

The CLI is **optional**. [`@waniwani/sdk`](/sdk/configuration/installation) works on its own — the CLI is the fastest way to skip the dashboard for project setup and local development.

<Note>
  `waniwani init`, `check`, `build`, `start` and `eject` belong to [`@waniwani/kit`](/kit/commands), the framework that builds an MCP app from a folder, and so does the `dev` that regenerates the app on every change. This page covers the platform CLI: `login`, `logout` and `connect`, plus a `dev` that bridges a local server to the hosted playground.
</Note>

## Install

<CodeGroup>
  ```bash bun theme={null}
  bun add -g @waniwani/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @waniwani/cli
  ```

  ```bash npm theme={null}
  npm install -g @waniwani/cli
  ```

  ```bash yarn theme={null}
  yarn global add @waniwani/cli
  ```
</CodeGroup>

Requires Node.js 20 or later.

## Quickstart

```bash theme={null}
waniwani login     # browser-based OAuth2 PKCE
waniwani connect   # pick an org + agent, writes waniwani.json
waniwani dev       # run local MCP, open playground bridged to localhost
```

Three commands. Your local MCP server is now reachable from ChatGPT, Claude, and Cursor through the Waniwani playground, with no tunnel setup.

## Commands

| Command                        | What it does                                                                |
| ------------------------------ | --------------------------------------------------------------------------- |
| [`waniwani login`](#login)     | Browser-based OAuth2 PKCE. Stores tokens in `.waniwani/settings.json`.      |
| [`waniwani logout`](#logout)   | Clear local credentials.                                                    |
| [`waniwani connect`](#connect) | Pick an org, pick or create an agent, write the binding to `waniwani.json`. |
| [`waniwani dev`](#dev)         | Run your MCP locally and open the Waniwani playground against it.           |

### login

```bash theme={null}
waniwani login [--no-browser] [--json]
```

Runs the OAuth2 PKCE flow: spins up a local callback server on port `54321`, opens your browser to `app.waniwani.ai`, exchanges the code for an access token, and persists access + refresh tokens to `.waniwani/settings.json` in the current directory.

If you're already logged in with an expired token, it auto-refreshes and exits. Pass `--no-browser` to print the URL instead of launching a browser (useful on headless machines).

### logout

```bash theme={null}
waniwani logout [--json]
```

Clears the stored auth tokens. Keeps non-auth config (like `apiUrl`) intact. No-op if you're already logged out.

### connect

```bash theme={null}
waniwani connect
```

Interactive only. Walks you through:

1. **Pick an organization.** If you're in one org, it's auto-selected.
2. **Pick or create an agent.** Either select an existing project, create a new **managed** agent (Waniwani provisions a GitHub repo + Vercel project from the [MCP distribution template](https://github.com/WaniWani-AI/mcp-distribution-template) with API keys pre-wired), or create a new **external** agent (you host the MCP server; the CLI gives you a production API key to set as `WANIWANI_API_KEY`).
3. **Write the binding.** Writes `waniwani.json` at the repo root with `$schema`, `orgId`, and `projectId`. If the file already exists, the CLI merges the keys in; if the shape isn't recognized, it prints the snippet for you to paste. If a legacy `waniwani.config.ts` is present, it's removed after the JSON file is written.

Re-run anytime to switch the repo to a different agent.

#### Managed vs external agents

|                       | Managed                                                                                                     | External                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Where the server runs | Waniwani-hosted Vercel project                                                                              | Your infra (Docker, Cloudflare Workers, fly.io, etc.)   |
| Source code           | Auto-provisioned from [mcp-distribution-template](https://github.com/WaniWani-AI/mcp-distribution-template) | Yours                                                   |
| API key               | Pre-configured in the Vercel env                                                                            | Printed once by the CLI — save it as `WANIWANI_API_KEY` |
| Deploys on            | Push to `main`                                                                                              | Whatever you already use                                |

See [Deployment](/sdk/deployment/overview) for the full picture.

### dev

```bash theme={null}
waniwani dev [-p <port>]
```

Interactive only. The end-to-end local dev loop:

1. Ensures you're logged in (runs `login` if not) and that `waniwani.json` has a `projectId` (runs `connect` if not).
2. Detects your package manager (`bun` / `pnpm` / `yarn` / `npm`) and spawns the dev script with `PORT` set.
3. Waits for the local server to bind to the port.
4. Creates a dev session against the Waniwani API and starts a heartbeat.
5. Opens the playground at `app.waniwani.ai/agents/<projectId>/playground?localMode=1` so chat traffic routes to your local server.
6. Ctrl-C tears the dev session down cleanly.

**Options:**

* `-p, --port <port>` — Port the local MCP listens on. Defaults to `devPort` in `waniwani.json`, or `3000`.

`dev` runs your existing dev script — it does not start the MCP for you. The script must bind to `process.env.PORT`.

## Global flags

| Flag        | Description                                                                                                          |
| ----------- | -------------------------------------------------------------------------------------------------------------------- |
| `--json`    | Output as JSON. Supported by `login` and `logout`. Interactive commands (`connect`, `dev`) error out under `--json`. |
| `--verbose` | Enable verbose logging.                                                                                              |
| `--version` | Print the CLI version.                                                                                               |
| `--help`    | Print help.                                                                                                          |

## Configuration

### Auth & local state — `.waniwani/settings.json`

Per-repo, gitignored. Holds OAuth tokens and the resolved API URL:

```json theme={null}
{
  "apiUrl": "https://app.waniwani.ai",
  "accessToken": "…",
  "refreshToken": "…",
  "expiresAt": "2026-05-20T12:00:00Z",
  "clientId": "…"
}
```

Access tokens auto-refresh on 401. Add `.waniwani/` to your `.gitignore`.

### Project config — `waniwani.json`

Shared with [`@waniwani/sdk`](/sdk/configuration/installation). `waniwani connect` writes `$schema`, `orgId`, and `projectId`; other fields are optional and consumed by the SDK and the `dev` command:

```json waniwani.json theme={null}
{
  "$schema": "https://docs.waniwani.ai/waniwani.json",
  "orgId": "org_…",
  "projectId": "proj_…",
  "devPort": 3000
}
```

The `$schema` field unlocks autocomplete and validation in editors that support JSON Schema (VS Code, JetBrains, Neovim with LSP). It's ignored at runtime.

Legacy `waniwani.config.ts` files are still read for now (with a deprecation warning), but new projects should use `waniwani.json`. Running `waniwani connect` against a repo that has a `.ts` file removes it and writes a `.json` in its place.

### Environment variables

| Variable           | Purpose                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------- |
| `WANIWANI_API_URL` | Override the API base URL. Defaults to `https://app.waniwani.ai`.                                     |
| `WANIWANI_API_KEY` | Use a long-lived API key instead of OAuth (useful in CI). See [API keys](/sdk/configuration/api-key). |

Resolution order for the API URL: env var → `waniwani.json` → `.waniwani/settings.json` → default. For auth: API key → OAuth tokens (with auto-refresh).

## Typical workflow

```bash theme={null}
# One-time
bun add -g @waniwani/cli
waniwani login

# Per-project
cd my-mcp-server
waniwani connect              # creates / picks the agent, writes waniwani.json
waniwani dev                  # runs the dev loop bridged to the playground
```

To start a fresh project, clone the template first:

```bash theme={null}
git clone https://github.com/WaniWani-AI/mcp-distribution-template.git my-mcp-server
cd my-mcp-server
bun install
waniwani connect
waniwani dev
```

## For AI coding agents

If you're [Claude Code](https://claude.com/claude-code), Cursor, or another AI agent setting up Waniwani in a user's repo:

1. Confirm the user is in an MCP project (`@waniwani/sdk` in `package.json`, or it's the [distribution template](https://github.com/WaniWani-AI/mcp-distribution-template)). If not, scaffold one with the [SDK quickstart](/sdk/quickstart) first.
2. Run `waniwani login` — opens the browser; the user authenticates once.
3. Run `waniwani connect` — interactive; ask the user which org / agent they want, or recommend "managed" if they don't already host.
4. Run `waniwani dev` to verify the bridge works.

The CLI is interactive — `connect` and `dev` cannot run under `--json`. Pair it with the [agent skill](/sdk/guides/skills) for code generation:

```bash theme={null}
bunx skills add Waniwani-AI/sdk -s waniwani-sdk
```

The skill teaches your agent the SDK APIs (flows, tracking, widgets, knowledge base). The CLI handles platform wiring. They're independent — install whichever you need.

## Source

* **npm:** [`@waniwani/cli`](https://www.npmjs.com/package/@waniwani/cli)
* **GitHub:** [Waniwani-AI/cli](https://github.com/WaniWani-AI/cli)
* **Issues:** [github.com/WaniWani-AI/cli/issues](https://github.com/WaniWani-AI/cli/issues)

MIT licensed, like the rest of the Waniwani stack.


# Waniwani vs LangGraph
Source: https://docs.waniwani.ai/sdk/compare/vs-langgraph

When to use createFlow vs LangChain's LangGraph for MCP funnels and multi-step conversational tools.

LangGraph is LangChain's graph framework for agent workflows. `@waniwani/sdk` is a graph framework specifically for MCP funnels. The two overlap. They are not interchangeable.

This page is for developers who already know LangGraph and are evaluating whether to use it for a multi-step MCP tool.

## TL;DR

|                                | LangGraph                            | `@waniwani/sdk` (createFlow)                                                                                |
| ------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| **Scope**                      | General-purpose agent graphs         | MCP funnels specifically                                                                                    |
| **Primary output**             | A runnable graph                     | An MCP tool registered on a server                                                                          |
| **State persistence**          | Pluggable checkpointer, Python-first | Pluggable KvStore, MCP-session-keyed                                                                        |
| **Built-in funnel ergonomics** | Build them yourself                  | Built in: interrupts, re-ask on validation, multi-field interrupts, auto-skip filled fields, widget signals |
| **MCP integration**            | None, you wire it                    | One call: `flow.register(server)`                                                                           |
| **Typed state**                | Pydantic / TypedDict                 | Zod, end-to-end type inference                                                                              |
| **Language**                   | Python first, JS port secondary      | TypeScript only                                                                                             |
| **License**                    | MIT                                  | MIT                                                                                                         |

If you are building a general-purpose agent (multiple LLM calls, retrievers, tool selection, planning), pick LangGraph. If you are building a funnel that runs as one MCP tool inside ChatGPT or Claude, pick `createFlow`.

## What each one is

**LangGraph** is a graph runtime. You declare nodes (functions), edges (direct or conditional), and a shared state object. The runtime drives the graph. It is unopinionated about what the nodes do, what the state contains, or how the graph is exposed.

**`createFlow`** is also a graph runtime. The difference is opinion. A flow compiles to a single MCP tool. Nodes return state updates, interrupt signals, or widget signals. Interrupts pause the graph to ask a typed question, validate the answer, and re-ask on failure. State is keyed by the MCP session id and persisted to a `KvStore`. The graph is funnel-shaped on purpose.

## When LangGraph is the better choice

* You need an agent that plans, picks tools, and loops over its own output.
* You want multiple LLM calls inside the graph itself, not just a single tool surface.
* You need retrievers, parallel branches, or supervisor patterns.
* Your team is Python-first and the rest of your stack lives in LangChain.
* You are not building for MCP, or MCP is one surface among many.

## When `createFlow` is the better choice

* You are building a multi-step MCP tool: sales funnel, lead generation, booking, quote, intake.
* You want deterministic step order with typed validation, not agent improvisation.
* You want to skip the work of wiring an MCP tool around your graph.
* You want state persistence keyed to the MCP session, not a homegrown checkpointer.
* You want widget cards for confirmation steps without inventing a protocol.

## Side by side: a two-question funnel

The simplest case where the difference shows up.

**LangGraph (conceptual):**

```python theme={null}
from langgraph.graph import StateGraph, START, END
from typing import TypedDict

class State(TypedDict, total=False):
    name: str
    email: str

def ask_name(state):
    # You implement: pause the graph, expose a question to whatever UI is
    # driving, parse the response, validate, re-ask on failure, write to state.
    ...

def ask_email(state):
    # Same again. Validation, re-ask, persistence: all on you.
    ...

graph = StateGraph(State)
graph.add_node("ask_name", ask_name)
graph.add_node("ask_email", ask_email)
graph.add_edge(START, "ask_name")
graph.add_edge("ask_name", "ask_email")
graph.add_edge("ask_email", END)
app = graph.compile()
# You still have to: expose this as an MCP tool, route the MCP session id to
# the checkpointer, decide how interrupts are rendered to the model, etc.
```

**`createFlow`:**

```ts theme={null}
import { createFlow, END, MemoryKvStore, START } from "@waniwani/sdk/mcp";
import { z } from "zod";

const flow = createFlow({
  id: "intake",
  title: "Intake",
  description: "Collect name and email.",
  state: {
    name: z.string().describe("Full name"),
    email: z.string().email().describe("Email address"),
  },
})
  .addNode({
    id: "ask_name",
    run: ({ interrupt }) => interrupt({ name: { question: "What's your name?" } }),
  })
  .addNode({
    id: "ask_email",
    run: ({ interrupt }) => interrupt({ email: { question: "What's your email?" } }),
  })
  .addEdge(START, "ask_name")
  .addEdge("ask_name", "ask_email")
  .addEdge("ask_email", END)
  .compile({ store: new MemoryKvStore() });

await flow.register(server);
```

Both are graph definitions. The `createFlow` version compiles to a working MCP tool. The LangGraph version is a graph that still needs to be wrapped, exposed, and given an interaction protocol.

## What you would re-implement on top of LangGraph

If you choose LangGraph for an MCP funnel, you take on:

1. **MCP tool surface.** Declare the tool, marshal arguments, route results.
2. **Session-keyed state.** Map the MCP session id to a checkpointer thread id.
3. **Interrupt semantics.** Pause the graph, emit a structured question, resume on the next tool call.
4. **Validation loop.** Re-ask on schema failure without advancing the graph.
5. **Auto-skip filled fields.** If state already has `email`, skip `ask_email`.
6. **Widget signals.** If you want non-text rendering (cards, pickers), invent a protocol.
7. **Multi-field interrupts.** Ask several questions in one turn when the model can fill them at once.

These are the funnel ergonomics `createFlow` ships built in. None are hard individually. Together they are a project.

## What `createFlow` does not do

To be clear about scope:

* **No agent loop.** A flow is a deterministic graph driven by tool calls, not an LLM-controlled agent.
* **No retrieval.** Use [`@waniwani/sdk/kb`](/sdk/knowledge-base/overview) or your own retriever inside a node.
* **No Python.** TypeScript only.
* **No graph composition primitives** (subgraphs, supervisors). A flow is a single graph compiled to a single tool.

If you need any of those, LangGraph or a hybrid is the right call. You can also call into a LangGraph (or any other) agent from inside a flow node.

## Migration sketch

If you have a LangGraph workflow that is funnel-shaped:

1. Replace `TypedDict` state with a Zod schema map.
2. Replace each node body with either `interrupt({...})`, a state-returning function, or a widget signal.
3. Replace `add_edge` and `add_conditional_edges` with `.addEdge` and `.addConditionalEdge`.
4. Replace the checkpointer with a [KV store adapter](/sdk/flows/kv-store).
5. Call `.register(server)` instead of wiring an MCP tool by hand.

The graph shape stays. The wrapping disappears.

## Next

<CardGroup>
  <Card title="Why MCP funnels" icon="lightbulb" href="/sdk/why-mcp-funnels">
    The distribution shift behind the SDK.
  </Card>

  <Card title="Quickstart" icon="play" href="/sdk/quickstart">
    A complete flow in under 30 lines.
  </Card>

  <Card title="Flow engine" icon="diagram-project" href="/sdk/flows/overview">
    Nodes, edges, interrupts, branching.
  </Card>

  <Card title="KV store adapters" icon="database" href="/sdk/flows/kv-store">
    Redis, Upstash, Cloudflare KV, DynamoDB.
  </Card>
</CardGroup>


# API Keys
Source: https://docs.waniwani.ai/sdk/configuration/api-key

Create, configure, and rotate Waniwani API keys.

Every Waniwani client authenticates with a single API key scoped to one **MCP environment**. When you create a project, two environments are provisioned automatically: **Staging** and **Production**, each with its own unique API key.

The key you use determines which environment your data (events, sessions, knowledge base) is stored in. Use the Staging key during development and the Production key for live traffic. This keeps your data cleanly separated.

## Managed projects

Both API keys (Staging and Production) are pre-configured in your deployed instance. You can view and rotate them from your MCP app page under **Settings > API Keys**.

No manual setup needed for managed projects. API keys are pre-configured in your environment.

## Self-hosted projects

When you create a self-hosted project, you get your **Production** API key right away. Set it in the environment where your MCP server runs:

```bash .env theme={null}
WANIWANI_API_KEY=wwk_...
```

```ts theme={null}
import { waniwani } from "@waniwani/sdk";

const wani = waniwani(); // reads WANIWANI_API_KEY from env
```

Manage the variable wherever you normally keep secrets (`.env` file, your platform's secret manager, etc.).

To set up a **Staging** environment, create one from your project's dashboard and use its key for local dev and preview deploys.

<Warning>
  API keys grant rights to ingest events and mint widget tokens for their environment. Treat them as server-side secrets. Never commit them to git, never ship them in client-side bundles.
</Warning>

## Per-environment keys

Use the **Staging** key during development and the **Production** key for your live deployment. Mixing environments pollutes your metrics and makes rotation harder.

| Environment | When to use                   | Where the env var lives               |
| ----------- | ----------------------------- | ------------------------------------- |
| Production  | Live traffic                  | Platform secret manager               |
| Staging     | Local dev and preview deploys | `.env` (gitignored) / preview secrets |

## Rotate a key

Rotate from the environment settings in the dashboard. Clients using the old key start receiving `401 Unauthorized`; the SDK's transport detects auth failures and stops retrying, so you get a clean shutdown instead of a retry storm.

## Troubleshooting

If events do not appear in the dashboard:

1. Confirm `WANIWANI_API_KEY` is set in the process running the MCP server (setting it only in your shell is not enough).
2. Check for typos. The key is a single string, no quotes, no trailing whitespace.
3. Look for `[waniwani]` lines in your server logs.
4. Trigger a tool call. The dashboard only shows events from real traffic.

## Also supported

Pass the key explicitly when you need multiple clients in one process (multi-tenant setups):

```ts theme={null}
import { waniwani } from "@waniwani/sdk";

const wani = waniwani({ apiKey: process.env.TENANT_A_KEY });
```

Next: [wrap your MCP server](/sdk/configuration/wrap-server).


# Environment Variables
Source: https://docs.waniwani.ai/sdk/configuration/environment-variables

All environment variables recognized by the Waniwani SDK.

The SDK reads the following environment variables at runtime. None are required at import time; they are checked when the relevant feature is used.

## Authentication

| Variable           | Required | Description                                                                                                           |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `WANIWANI_API_KEY` | Yes      | API key for your MCP environment. See [API Keys](/sdk/configuration/api-key).                                         |
| `WANIWANI_API_URL` | No       | Override the API base URL. Defaults to `https://app.waniwani.ai`. Use `https://eu.app.waniwani.ai` for the EU region. |

## Logging

By default the SDK is silent. Set one of these to enable internal logs (prefixed `[waniwani:*]`):

| Variable             | Values                                 | Description                                                 |
| -------------------- | -------------------------------------- | ----------------------------------------------------------- |
| `WANIWANI_LOG_LEVEL` | `debug` \| `warn` \| `error` \| `none` | Controls SDK log verbosity. Defaults to `none`.             |
| `WANIWANI_DEBUG`     | Any truthy value                       | Legacy shorthand. Equivalent to `WANIWANI_LOG_LEVEL=debug`. |

If both are set, `WANIWANI_LOG_LEVEL` takes precedence.

```bash .env theme={null}
# Enable debug logs
WANIWANI_LOG_LEVEL=debug
```

## Encryption

| Variable                  | Required | Description                                                                                                                                        |
| ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WANIWANI_ENCRYPTION_KEY` | No       | Base64-encoded 32-byte key for AES-256-GCM encryption of KV store values. When set, all values written through the KV store are encrypted at rest. |


# Installation
Source: https://docs.waniwani.ai/sdk/configuration/installation

Install @waniwani/sdk in a new or existing project.

## Choose your approach

<CardGroup>
  <Card title="Start from template" icon="rocket" href="#option-a-start-from-template">
    Clone a ready-to-go MCP app (server + widgets + UI) with the SDK pre-configured. Best for **new projects**.
  </Card>

  <Card title="Add to existing project" icon="plus" href="#option-b-add-to-existing-project">
    Install the SDK package into your existing MCP server or app. Best for **existing projects**.
  </Card>
</CardGroup>

The SDK is open source and works without an API key. Set `WANIWANI_API_KEY` to connect the [Waniwani Platform](/sdk/platform/overview) and unlock hosted state, tracking, knowledge base, and the chat widget on top.

***

## Option A: Start from template

The [MCP Distribution Template](https://github.com/WaniWani-AI/mcp-distribution-template) gives you a production-ready **MCP app** (server + widgets + UI) with the SDK, event tracking, flows, and widgets already wired up.

<Note>
  The template is an MCP app. If you only need a bare MCP server (no widgets or embedded UI), skip to [Option B](#option-b-add-to-existing-project) or follow the [Quickstart](/sdk/quickstart). The SDK works for both.
</Note>

<Steps>
  <Step title="Create your repo">
    Click **"Use this template"** on [GitHub](https://github.com/WaniWani-AI/mcp-distribution-template) to create a new repository from the template, or clone it directly:

    ```bash theme={null}
    git clone https://github.com/WaniWani-AI/mcp-distribution-template.git my-mcp-server
    cd my-mcp-server
    ```
  </Step>

  <Step title="Install and run">
    ```bash theme={null}
    bun install
    cp .env.example .env
    bun dev
    ```

    The template runs without an API key. Set `WANIWANI_API_KEY` in `.env` to connect the [Platform](/sdk/platform/overview) and enable hosted state, tracking, and the dashboard.
  </Step>

  <Step title="Customize">
    The template includes a reference flow (Alpine ski lessons) you can replace with your own. If you have the [agent skill](/sdk/guides/skills) installed, run `/waniwani-sdk initialize` to interactively scaffold a flow tailored to your business.
  </Step>
</Steps>

***

## Option B: Add to existing project

### Requirements

* Node.js 18.17 or newer (Node 20+ recommended)
* An MCP server runtime. The SDK is tested against:
  * [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
  * [Skybridge](https://github.com/alpic-ai/skybridge) (Alpic)
  * [`@vercel/mcp-handler`](https://www.npmjs.com/package/@vercel/mcp-handler)
* A Waniwani account at [app.waniwani.ai](https://app.waniwani.ai) — optional, only needed for [Platform](/sdk/platform/overview) features.

`@modelcontextprotocol/sdk` and `zod` are peer dependencies. Install them in your project if you do not already have them.

### Install

<CodeGroup>
  ```bash bun theme={null}
  bun add @waniwani/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @waniwani/sdk
  ```

  ```bash npm theme={null}
  npm install @waniwani/sdk
  ```

  ```bash yarn theme={null}
  yarn add @waniwani/sdk
  ```
</CodeGroup>

<Note>
  The SDK has zero runtime dependencies and targets a sub-5KB core bundle. It runs in long-lived Node processes, serverless functions, and edge runtimes.
</Note>

### Pick what you need

Three things you can add independently to an existing MCP server. Any subset works.

| Add                    | What it gives you                                                                                          | API key                                                                               |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `createFlow`           | Multi-step typed flows registered as a single MCP tool. The primary entry point.                           | Not required. Required only if you want hosted state instead of bringing a `KvStore`. |
| `withWaniwani(server)` | Wraps existing `registerTool` handlers to emit tracking events and bridge session IDs. No handler changes. | Required for events. Bridging works without.                                          |
| `waniwani()` client    | Direct calls to Platform APIs (custom events, `identify()`, KB search).                                    | Required.                                                                             |

### Add a flow to an existing server

Assume you already have an `McpServer` instance with some tools registered on it. Define a flow and `.register()` it alongside them:

```ts theme={null}
import { createFlow, END, MemoryKvStore, START } from "@waniwani/sdk/mcp";
import { z } from "zod";
import { server } from "./mcp-server"; // your existing McpServer

const onboardingFlow = createFlow({
  id: "onboarding",
  title: "User Onboarding",
  description: "Use when a new user wants to get started.",
  state: { name: z.string().describe("Their name") },
})
  .addNode({
    id: "ask_name",
    run: ({ interrupt }) =>
      interrupt({ name: { question: "What is your name?" } }),
  })
  .addEdge(START, "ask_name")
  .addEdge("ask_name", END)
  .compile({ store: new MemoryKvStore() });

await onboardingFlow.register(server);
```

`MemoryKvStore` is fine for development and tests. For production, plug in a real backend (Redis, Upstash, Cloudflare KV, DynamoDB) or set `WANIWANI_API_KEY` to use hosted state. See [KV store adapters](/sdk/flows/kv-store).

### Wrap an existing server for Platform tracking

If your server already has plain `registerTool` handlers and you just want them tracked, wrap it once. No changes to the handlers themselves:

```ts theme={null}
import { withWaniwani } from "@waniwani/sdk/mcp";
import { server } from "./mcp-server"; // your existing McpServer

withWaniwani(server);
```

```bash .env theme={null}
WANIWANI_API_KEY=wwk_...
```

Every wrapped tool call now emits a `tool.called` event to your [Waniwani dashboard](https://app.waniwani.ai). Without an API key, the wrapper still bridges session IDs and forwards widget metadata but emits no events. Safe to wrap unconditionally. See [Wrap your server](/sdk/configuration/wrap-server) for all options.

## Create a Platform client

The `waniwani()` client is needed only when you call Platform APIs directly (custom event tracking via `track()`, `identify()`, KB search). It is **not** required for `createFlow` or `withWaniwani`.

```ts theme={null}
import { waniwani } from "@waniwani/sdk";

const wani = waniwani();
```

With no arguments, the client reads `WANIWANI_API_KEY` from the environment and uses `https://app.waniwani.ai` as the base URL.

See [API keys](/sdk/configuration/api-key) for how to obtain and configure the key, and [Client & KV store reference](/sdk/reference/kv-store-api) for the full client config.

## Also supported

* **Project config file.** Drop a `waniwani.json` at the project root with `$schema` set to `https://docs.waniwani.ai/waniwani.json`. The SDK auto-loads it on the first `waniwani()` call; the CLI uses the same file for `connect`/`dev`/evals. No explicit import required.

Next: [get your API key](/sdk/configuration/api-key) (if you want Platform features), then [wrap your MCP server](/sdk/configuration/wrap-server).


# Security
Source: https://docs.waniwani.ai/sdk/configuration/security

Encryption at rest, key management, and security best practices.

## Encryption at rest

Flow state is stored server-side via the Waniwani KV store. The SDK supports **AES-256-GCM encryption** -- values are encrypted before they leave your MCP server process and decrypted on read. The Waniwani server never sees plaintext flow state.

<CardGroup>
  <Card title="Managed project" icon="cloud" href="#managed-projects">
    Encryption is automatic. Waniwani generates and manages the key for you -- nothing to configure.
  </Card>

  <Card title="Self-hosted project" icon="server" href="#self-hosted-projects">
    You generate a key and add it to your MCP server's environment.
  </Card>
</CardGroup>

***

### Managed projects

Encryption is enabled automatically. Waniwani generates and stores the encryption key as an environment variable in your deployed instance. No setup is needed -- flow state is encrypted out of the box and the key is never exposed.

### Self-hosted projects

You need to generate a key and add it to your MCP server's environment:

```bash theme={null}
openssl rand -base64 32
```

```bash .env theme={null}
WANIWANI_ENCRYPTION_KEY=<base64-encoded 32-byte key>
```

The SDK picks up the key automatically -- no code changes required. When the key is not set, values are stored as plain JSON.

### How it works

When `WANIWANI_ENCRYPTION_KEY` is set:

1. **On write** -- the SDK serializes the value to JSON, encrypts it with AES-256-GCM using a random 12-byte IV, and stores an encrypted envelope in the KV store.
2. **On read** -- the SDK detects the encrypted envelope, decrypts the ciphertext, and returns the original value.

### Key rotation

The SDK does not support automatic key rotation. To rotate:

1. Set the new key in your environment.
2. Trigger each active flow so its state is re-read with the old key (which will fail) and re-written with the new key.

In practice, the simplest approach is to let existing sessions expire naturally and apply the new key to new sessions only.

<Warning>
  If you lose the encryption key, encrypted flow state cannot be recovered. Back up the key in your secret manager.
</Warning>

## API key handling

API keys (`WANIWANI_API_KEY`) authenticate your MCP server to the Waniwani platform. Treat them as server-side secrets:

* Never commit them to version control.
* Never include them in client-side bundles.
* Store them in your platform's secret manager or a gitignored `.env` file.
* Use separate keys for Staging and Production environments.

See [API Keys](/sdk/configuration/api-key) for setup and rotation details.

## Transport security

All communication between the SDK and the Waniwani API uses HTTPS (TLS 1.2+). No additional configuration is needed.

## Tenant isolation

Each API key is scoped to a single MCP environment. The Waniwani API enforces tenant isolation at the key level -- one key cannot access another environment's data (events, sessions, KV store, knowledge base).


# Wrap your MCP server
Source: https://docs.waniwani.ai/sdk/configuration/wrap-server

Optional convenience wrapper that adds tool tracking, session bridging, and widget metadata forwarding.

`withWaniwani(server)` is an optional convenience that instruments an MCP server. It activates Platform tracking when an API key is configured, and stays a no-op-but-still-useful wrapper when it isn't.

<Note>
  **Not required for OSS flows.** `createFlow` works without `withWaniwani`. Use this wrapper when you want auto-tracking, session-id bridging, or widget metadata forwarding on top.
</Note>

## What it does, with `WANIWANI_API_KEY`

Every tool invocation produces a `tool.called` event containing name, type, duration, status, input, output, client info, and session correlation. Flow graphs are synced to the dashboard so the funnel view lights up automatically.

```ts theme={null}
import { withWaniwani } from "@waniwani/sdk/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({ name: "my-mcp-app", version: "0.0.1" });

server.registerTool(/* ... */);

withWaniwani(server);
```

## What it does, without an API key

The wrapper still adds two genuinely useful things, even with no key configured:

1. **Transport session-ID bridging.** When the MCP transport carries a session ID via the `Mcp-Session-Id` header but the request `_meta` doesn't include one, the wrapper copies it into `_meta.waniwani/sessionId` so flow nodes and downstream tools can see the correlation.
2. **Widget definition metadata forwarding.** Widget keys declared on a tool's definition `_meta` (`openai/outputTemplate`, `ui/resourceUri`, etc.) are forwarded into each tool result's `_meta`, so chat UIs that only see results can still render widgets.

The wrapper's own auto-capture (`tool.called`) silently no-ops without a key, so wrapping unconditionally is safe. Your own `client.track.*` and `identify()` calls are different: they throw `WANIWANI_API_KEY is not set` when no key is configured, so guard them (`waniwani?.track...` on the scoped client) on code paths that must also run keyless.

## When to use it

| You want                                            | Use `withWaniwani`?                          |
| --------------------------------------------------- | -------------------------------------------- |
| Only run OSS flows, no telemetry                    | Optional (still useful for session bridging) |
| OSS flows + Platform tracking                       | Yes                                          |
| Hosted everything (flow state + tracking + funnel)  | Yes                                          |
| Just custom event tracking via `waniwani().track()` | No, call `track()` directly                  |

## Options

```ts theme={null}
import { withWaniwani } from "@waniwani/sdk/mcp";
import { waniwani } from "@waniwani/sdk";

withWaniwani(server, {
  client: waniwani(),
  toolType: (name) => (name.startsWith("get_price") ? "pricing" : "other"),
  metadata: { deployment: "production" },
  flushAfterToolCall: false,
  injectWidgetToken: true,
  onError: (err) => console.error("[waniwani]", err),
});
```

<ResponseField name="client" type="WaniWaniClient">
  The client used for tracking. Defaults to `waniwani()`, which picks up `WANIWANI_API_KEY` from the environment.
</ResponseField>

<ResponseField name="toolType" type="ToolType | (name: string) => ToolType | undefined">
  Classify tools into dashboard buckets: `"pricing"`, `"product_info"`, `"availability"`, `"support"`, or `"other"`. Accepts a literal or a function that maps a tool name to a type.
</ResponseField>

<ResponseField name="metadata" type="Record<string, unknown>">
  Extra fields merged into every `tool.called` event. Use this to tag deployments, tenants, or releases.
</ResponseField>

<ResponseField name="flushAfterToolCall" type="boolean">
  Force a flush after every tool call. Turn this on in serverless runtimes where the process may be frozen between invocations. Leave it off for long-running Node processes.
</ResponseField>

<ResponseField name="injectWidgetToken" type="boolean">
  Inject the widget tracking config (endpoint, a short-lived widget token, session id, source) into tool responses under `_meta["waniwani/widget"]`, so browser widgets can post events directly to Waniwani without a proxy route. `useWaniwani()` reads this automatically. Without an API key, the token is omitted and only the endpoint metadata is injected.
</ResponseField>

<ResponseField name="onError" type="(error: Error) => void">
  Callback for non-fatal tracking errors. Tracking failures never block tool execution; use this callback when you want visibility into them.
</ResponseField>

<Tip>
  Call order does not matter. `withWaniwani` walks existing `_registeredTools` at call time and intercepts `registerTool` for any future registrations. It is idempotent: a second call on the same server is a no-op.
</Tip>

## Tracked event shape

| Field           | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| `name`          | Registered tool name                                             |
| `type`          | Category derived from the `toolType` option                      |
| `durationMs`    | Handler execution time                                           |
| `status`        | `"ok"` or `"error"`                                              |
| `errorMessage`  | Present when the handler threw or returned `isError`             |
| `input`         | Tool arguments                                                   |
| `output`        | Handler response                                                 |
| `clientName`    | MCP client name (for example `chatgpt`, `claude`)                |
| `clientVersion` | MCP client version                                               |
| `sessionId`     | Correlated from `_meta` (see [Sessions](/sdk/tracking/sessions)) |

Errors (thrown or `{ isError: true }`) are tracked and then re-thrown or returned unchanged, so your tool's error contract is preserved.

## Custom events inside tools

For anything beyond `tool.called`, use the request-scoped client the wrapper attaches to `extra["waniwani/client"]`. Session correlation is already merged in; you pass nothing.

```ts theme={null}
import { extractScopedClient } from "@waniwani/sdk/mcp";

server.registerTool(
  "get_quote",
  { /* tool config */ },
  async ({ amount, currency }, extra) => {
    const waniwani = extractScopedClient(extra);
    await waniwani?.track.priceShown({ amount, currency });

    return { content: [{ type: "text", text: `Quoted ${amount} ${currency}` }] };
  },
);
```

## Session-scoped client in flows

Inside a [flow](/sdk/flows/overview) node, `ctx.waniwani` is the same scoped client, so `ctx.waniwani.track({ event, properties })` needs no session plumbing either. The resolved session id is readable as `ctx.waniwani.sessionId`; store it with your own records to attribute later off-platform events back to the conversation (see [Sessions](/sdk/tracking/sessions)).


# Deployment
Source: https://docs.waniwani.ai/sdk/deployment/overview

Run your Waniwani-powered MCP app on Managed Hosting or self-host it yourself (Docker, Alpic, Vercel).

Where your MCP server runs is independent of whether you connect the [Waniwani Platform](/sdk/platform/overview). This page covers the two server-hosting options. The Platform layer (tracking, KB, chat, hosted state) works the same in both.

<CardGroup>
  <Card title="Managed Hosting" icon="cloud" href="#managed-hosting">
    Waniwani hosts your app. Provisioned, pre-configured, push to main and it deploys. Fastest path.
  </Card>

  <Card title="Self-hosted" icon="server" href="#self-hosted-server">
    You host the app yourself. Docker, Alpic, or Vercel. Connect by giving us the MCP URL.
  </Card>
</CardGroup>

Both paths use the same [MCP Distribution Template](https://github.com/WaniWani-AI/mcp-distribution-template). Pick based on where you want the server to live.

## Managed Hosting

When you create a managed project in the [Waniwani dashboard](https://app.waniwani.ai), we provision a copy of the distribution template fully wired up: API keys set, hosted URL assigned, everything ready. You don't configure anything.

Typical workflow:

<Steps>
  <Step title="Create the project">
    From [app.waniwani.ai](https://app.waniwani.ai), create a managed project. We spin up a repo from the template and deploy it on our managed hosting. Your tools, flows, widgets, and chat surface are live immediately.
  </Step>

  <Step title="Take ownership of the code">
    Move the provisioned repo into your own GitHub organization when you want full control over the codebase. You keep the managed hosting; you just own the source now.
  </Step>

  <Step title="Push to main">
    Every push to `main` auto-deploys to our managed hosting environment. API keys, URLs, and tracking continue to flow without any setup on your side.
  </Step>
</Steps>

Best for: getting started fast, teams that don't want to run infrastructure, and projects that want one less moving part to maintain.

## Self-hosted server

You run the server. By default we recommend connecting the [Platform](/sdk/platform/overview): set `WANIWANI_API_KEY` and you get hosted state + dashboards on top of your self-hosted server, with no extra infra. If you want to push that further and self-host the state layer too, see [Advanced: bring your own session cache](#advanced-bring-your-own-session-cache) below. If you want zero Platform dependency at all (no API key, no outbound calls), see the [open-source self-hosting walkthrough](/sdk/deployment/self-hosting).

The [MCP Distribution Template](https://github.com/WaniWani-AI/mcp-distribution-template) ships three deployment targets. Pick whichever fits your stack.

<CardGroup>
  <Card title="Docker" icon="box" href="#docker">
    Run anywhere a container runs.
  </Card>

  <Card title="Alpic" icon="bolt" href="#alpic">
    MCP-native runtime.
  </Card>

  <Card title="Vercel" icon="triangle" href="#vercel">
    One command from the template root.
  </Card>
</CardGroup>

### Docker

The template ships a `Dockerfile`. Build and run anywhere a container runs (Fly.io, Render, Railway, ECS, GCP Cloud Run, your own VPS, Kubernetes).

```bash theme={null}
docker build -t my-mcp-app .
docker run --env-file .env -p 3000:3000 my-mcp-app
```

Set `WANIWANI_API_KEY` and any backend secrets in the runtime's environment.

### Alpic

Deploy to [Alpic](https://github.com/alpic-ai/skybridge), an MCP-native hosting runtime. Follow Alpic's deployment instructions for the template repo. The SDK is tested against the Skybridge runtime, so flows, tracking, and widgets work out of the box.

### Vercel

```bash theme={null}
vercel deploy
```

From the template root. Set `WANIWANI_API_KEY` and any backend secrets in your Vercel project's environment variables.

### Connect to Waniwani

Once your app is deployed, copy its public MCP URL (the endpoint where MCP clients send `initialize` / `tools/call` requests). In the Waniwani dashboard, create a self-hosted project and paste that URL. Waniwani uses it as the entry point for chat requests, widget rendering, and analytics ingestion.

### Advanced: bring your own session cache

By default a self-hosted server uses `WaniwaniKvStore` for flow state when `WANIWANI_API_KEY` is set (encrypted at rest, hosted by Waniwani, no infra). That's the recommended setup.

If you want zero dependency on `app.waniwani.ai` for state too, plug in your own `KvStore` adapter at `.compile()` time:

```ts theme={null}
import { createFlow } from "@waniwani/sdk/mcp";
import { flowStore } from "./kv-store"; // your Redis / Upstash / DynamoDB / SQLite adapter

const flow = createFlow({ /* ... */ }).compile({ store: flowStore });
```

See [KV store adapters](/sdk/flows/kv-store) for recipes (Redis, Upstash, Cloudflare KV, DynamoDB, SQLite) and the full [open-source self-hosting](/sdk/deployment/self-hosting) walkthrough.

Your server, your state. You can still send tracking events to the Platform by calling `withWaniwani(server)`, or skip that entirely for a fully open-source setup.

## Platform features are orthogonal

Tracking, KB, chat, funnel analytics, and hosted state are Platform features. They are independent of where your server lives and where your state lives. Both Managed Hosting and self-hosted servers emit events through `withWaniwani(server)` and `client.track()`, and both surface in the same Waniwani dashboard. See the [Platform overview](/sdk/platform/overview) for what's included and [Tracking](/sdk/tracking/overview) for the event pipeline.


# Self-hosting
Source: https://docs.waniwani.ai/sdk/deployment/self-hosting

Two pieces you can self-host independently: the MCP app and the KV store.

A Waniwani deployment has **two pieces you can self-host independently**:

1. **The MCP app** — the server that hosts your `createFlow` tools and serves MCP clients.
2. **The KV store** — where flow state lives between tool calls.

These are orthogonal. The most common setup is "self-host the MCP app, let Waniwani host the KV store" — your infra for the server, the [Waniwani Platform](/sdk/platform/overview) for state and dashboards. The next step is self-hosting the KV too, eliminating any outbound call to `app.waniwani.ai`.

|                                | KV on `WaniwaniKvStore`                                                      | KV self-hosted                        |
| ------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------- |
| **MCP app self-hosted**        | Hybrid: your infra for the server, hosted state. Recommended starting point. | Fully open source. No outbound calls. |
| **MCP app on Managed Hosting** | Fully managed.                                                               | Not supported.                        |

## 1. Self-host the MCP app

Deploy the server you wrote on infrastructure you control. By itself this gets you self-hosted MCP + hosted state (the Hybrid row above).

### Scaffold

Start from the [MCP Distribution Template](https://github.com/WaniWani-AI/mcp-distribution-template) or any MCP server of your own:

```bash theme={null}
bun add @waniwani/sdk
```

### Wire up the server

```ts server.ts theme={null}
import express from "express";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { onboardingFlow } from "./flow";

const server = new McpServer({ name: "my-mcp-app", version: "0.0.1" });
await onboardingFlow.register(server);

const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
await server.connect(transport);

const app = express();
app.use(express.json());
app.post("/mcp", (req, res) => transport.handleRequest(req, res, req.body));
app.listen(3000);
```

When `.compile()` is called with no `store` and `WANIWANI_API_KEY` is set, the SDK uses `WaniwaniKvStore` automatically. That's the Hybrid setup.

### Deploy

Any platform that can run Node 18.17+ works: Vercel, Render, Railway, Fly.io, Cloudflare Workers, AWS Lambda, Google Cloud Run. See [Deployment overview](/sdk/deployment/overview) for the choice between this and Managed Hosting.

### Register with Waniwani

In the [Waniwani dashboard](https://app.waniwani.ai), create a self-hosted project and paste your deployed MCP URL. Waniwani routes chat requests, widget rendering, and analytics ingestion through that URL.

## 2. Self-host the KV store

Pass your own `KvStore` to `.compile()` and the engine never touches `app.waniwani.ai` for state. Useful when you have data-residency constraints, run in fully open-source mode, or want all state inside your existing infrastructure.

### Pick a backend

See [KV store adapters](/sdk/flows/kv-store) for recipes. Quick decision tree:

* **Vercel / Netlify / Cloudflare Workers** → Upstash Redis or Cloudflare KV
* **AWS Lambda** → DynamoDB
* **Long-running Node** → ioredis against a managed Redis (Render, Railway, Fly)
* **Local box** → SQLite via `better-sqlite3`

### Implement the interface

```ts kv-store.ts theme={null}
import type { KvStore } from "@waniwani/sdk/mcp";
import { Redis } from "@upstash/redis";

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
});

export const flowStore: KvStore = {
  async get(key) { return (await redis.get(key)) as never; },
  async set(key, value) { await redis.set(key, value); },
  async delete(key) { await redis.del(key); },
};
```

### Pass it to `.compile()`

```ts flow.ts theme={null}
import { createFlow, END, START } from "@waniwani/sdk/mcp";
import { flowStore } from "./kv-store";

export const onboardingFlow = createFlow({ /* ... */ })
  .addNode({ /* ... */ })
  .addEdge(START, "...")
  .addEdge("...", END)
  .compile({ store: flowStore });
```

State now reads and writes against your backend. Nothing about flow state ever leaves your infrastructure.

## Fully open-source mode

Combine the two: self-host the MCP app, pass a custom `KvStore`, omit `WANIWANI_API_KEY`. Result: no outbound calls to `app.waniwani.ai`, no telemetry, no hosted dashboards. The engine is fully usable in this mode.

### Verifying it's truly offline

```bash theme={null}
# 1. No WANIWANI_API_KEY in env
echo $WANIWANI_API_KEY
# (empty)

# 2. Run with network observability
DEBUG=* bun run start 2>&1 | grep waniwani
# (no requests to app.waniwani.ai)
```

The only outbound calls the SDK makes are when the `waniwani()` client is instantiated with an API key, or when `WaniwaniKvStore` is used. Neither happens in fully open-source mode.

## Switching modes later

The same code moves between modes by editing one or two lines:

* **OSS → Hybrid:** drop the `store` argument from `.compile()`, set `WANIWANI_API_KEY`.
* **Hybrid → OSS:** pass a custom `store` to `.compile()`.
* **Self-hosted → Managed Hosting:** see [Deployment overview](/sdk/deployment/overview#managed-hosting).

Existing sessions stay where they started; there is no automatic state migration between stores.


# Architecture
Source: https://docs.waniwani.ai/sdk/flows/architecture

What happens between an MCP tool call and the flow engine's response, and why a KV store is required.

A flow is a single MCP tool. The model calls that tool, the engine drives the graph one step at a time, and the response tells the model whether to ask the user something, render a widget, or stop. Between calls, everything the engine knows about the conversation lives in the KV store, keyed by the MCP session id.

This page walks through one full round-trip. If you understand the picture below, debugging "why doesn't the flow remember what I said?" becomes trivial.

## The pieces

```mermaid theme={null}
flowchart LR
    Client["MCP client<br/>(ChatGPT, Claude, ...)"]
    subgraph Server["Your MCP server"]
      Tool["Flow tool"]
      KV[("KV store")]
      Tool <-->|loads / saves| KV
    end
    Client -->|tools/call| Tool
    Tool -->|response| Client
```

The KV store is the only place the flow engine looks for state between two tool calls. Your MCP server itself can be either stateful (a long-running process, e.g. stdio or single-instance HTTP) or stateless (a serverless function where every call is a fresh process). The engine doesn't assume either — it always requires a `KvStore`. In a stateful runtime, `MemoryKvStore` is enough, because the process holds the state across calls. In a stateless runtime, you need a real backing store (Redis, Upstash, Cloudflare KV, DynamoDB, or `WaniwaniKvStore`) so state survives between cold starts and instances.

## First call: `action: "start"`

```mermaid theme={null}
sequenceDiagram
    participant Client as MCP client
    participant Tool as Flow tool handler
    participant Engine as Flow engine
    participant KV as KV store

    Client->>Tool: tools/call ({ action: "start", intent, stateUpdates })
    Tool->>Engine: invoke
    Engine->>KV: get(sessionId)
    KV-->>Engine: null (first call)
    Engine->>Engine: init state from stateUpdates
    Engine->>Engine: run START → action nodes...
    Engine->>Engine: hit ask_email (interrupt)
    Engine->>KV: set(sessionId, { step: "ask_email", state: {} })
    Engine-->>Tool: { status: "interrupt", questions: {...} }
    Tool-->>Client: response
```

After this call, the KV holds:

```json theme={null}
{
  "step": "ask_email",
  "state": {}
}
```

The flow has paused. The next tool call (with the user's answer) will resume from here.

## Next call: `action: "continue"`

```mermaid theme={null}
sequenceDiagram
    participant Client as MCP client
    participant Tool as Flow tool handler
    participant Engine as Flow engine
    participant KV as KV store

    Client->>Tool: tools/call ({ action: "continue", stateUpdates: { email: "..." } })
    Tool->>Engine: invoke
    Engine->>KV: get(sessionId)
    KV-->>Engine: { step: "ask_email", state: {} }
    Engine->>Engine: apply stateUpdates, run validators
    Engine->>Engine: advance along edge to next node
    Engine->>Engine: run action nodes... hit ask_use_case
    Engine->>KV: set(sessionId, { step: "ask_use_case", state: { email: "..." } })
    Engine-->>Tool: { status: "interrupt", questions: {...} }
    Tool-->>Client: response
```

Every `continue` is the same shape: load → apply updates → advance → save → respond.

When the engine reaches `END`, the response status is `"complete"` and the KV key is deleted, so a stale `continue` call can't accidentally resume a finished session.

## What's in the stored value

The value at a given session key is small and deterministic:

```ts theme={null}
type StoredValue = {
  step: string;                          // current node name (or "END" briefly)
  state: Partial<TState>;                // merged state so far, typed against schema
  pendingWidget?: {                      // present only when paused at a showWidget node
    tool: string;
    data?: Record<string, unknown>;
  };
};
```

Each session maps to one key. The key is derived from the MCP session identifier (`_meta.waniwani/sessionId`, or `Mcp-Session-Id` from the transport). One session, one key, one ongoing flow run.

## What's *not* in the KV store

The KV powers the flow engine only. The following live in a separate pipeline:

* **Tracking events.** `tool.called`, `price_shown`, etc. are emitted by `withWaniwani(server)` and `client.track()`, batched, and POSTed to the events endpoint. Independent of the KV store.
* **Funnel analytics and dashboards.** Built from tracking events on the server side. Reading them never touches your KV.
* **Knowledge base content.** Lives in Waniwani's hosted KB service, unrelated to flow state.

You can self-host the KV and still get hosted dashboards by also calling `withWaniwani(server)` with `WANIWANI_API_KEY` set. The two systems compose.

## Common gotchas

<AccordionGroup>
  <Accordion title="Flow appears to 'forget' between turns">
    The KV reset between calls. Two common causes:

    1. **`MemoryKvStore` in a serverless runtime.** Each invocation is a fresh process, so the in-memory `Map` is empty every time. Use a real backend (Redis, Upstash, Cloudflare KV) or set `WANIWANI_API_KEY` to use `WaniwaniKvStore`.
    2. **Missing session id in `_meta`.** If the MCP client doesn't propagate a session id, the engine derives a different key on every call. `withWaniwani(server)` bridges the transport-level session id into `_meta` for you. Install it.
  </Accordion>

  <Accordion title="Every tool call starts a new flow">
    Same root cause as above (missing or changing session id), but with a different symptom: the engine never finds a stored value, so it always behaves like `action: "start"`. Inspect what your transport puts in `Mcp-Session-Id` and what arrives in `_meta` on the server. They should be stable across a conversation.
  </Accordion>

  <Accordion title="State doesn't match the schema after a deploy">
    You changed the flow's state schema, then deployed. Sessions that were mid-flow have stored values that no longer match the new schema. The safest fix is to invalidate old sessions: delete the prefix in your KV, or version your flow id (`"onboarding_v2"`).
  </Accordion>

  <Accordion title="Concurrent calls on the same session">
    MCP clients serialize calls within a conversation, so concurrent `continue`s on one session are rare. If you see racy reads/writes in your KV, the cause is usually two clients sharing one session id by accident (often a misconfigured proxy). Make sure each conversation has a unique session id.
  </Accordion>

  <Accordion title="Widget never resolves">
    A `showWidget` node stores `pendingWidget` in the KV and returns `status: "widget"`. The engine resumes only when the next `continue` carries `stateUpdates` that fill the `field` declared in `showWidget(...)`. If your display tool never writes that field, the flow stays paused forever. Confirm the display tool's handler is producing the expected key in `stateUpdates`.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup>
  <Card title="Nodes" icon="circle-nodes" href="/sdk/flows/nodes">
    The three kinds of nodes and the context they receive.
  </Card>

  <Card title="KV store adapters" icon="database" href="/sdk/flows/kv-store">
    Pick a backend or write your own in 10 lines.
  </Card>

  <Card title="Tool contract" icon="plug" href="/sdk/reference/flow-tool-contract">
    Wire-level reference for `FlowToolInput` and response statuses.
  </Card>

  <Card title="Waniwani Platform" icon="layer-group" href="/sdk/platform/overview">
    What runs without an API key, what unlocks when you connect the Platform.
  </Card>
</CardGroup>


# Edges
Source: https://docs.waniwani.ai/sdk/flows/edges

Wire nodes together: direct edges, conditional branching, loops.

Edges define the order in which nodes run. Every node needs an outgoing edge. Every flow needs an edge out of `START` and must be able to reach `END`.

## Sentinels

Two reserved node names control flow boundaries:

* `START`: the entry point. Exactly one edge must originate from it.
* `END`: the terminal marker. Any node pointing to `END` finishes the flow when reached.

```ts theme={null}
import { createFlow, END, START } from "@waniwani/sdk/mcp";
```

## Direct edges

Use `.addEdge(from, to)` for unconditional transitions. Each node can have at most one outgoing edge.

```ts theme={null}
flow
  .addEdge(START, "ask_email")
  .addEdge("ask_email", "ask_use_case")
  .addEdge("ask_use_case", "record")
  .addEdge("record", END);
```

<Warning>
  Calling `addEdge` twice from the same node throws at build time. If you need a second outgoing path, replace the first call with `addConditionalEdge`.
</Warning>

## Conditional edges

Use `.addConditionalEdge(from, to, condition)` when the next node depends on state. Declare every node the branch can reach in the `to` array, then `condition` receives `Partial<TState>` and returns which of those nodes to go to next. It can be async.

The condition's return type is **constrained to `to`** — returning a node you did not list is a compile error. Because `to` is the declared set of targets, graph introspection (funnel analytics, Mermaid diagrams) reads it directly, so the graph stays correct even when the branch target is computed dynamically.

```ts theme={null}
flow
  .addNode({
    id: "ask_email",
    run: ({ interrupt }) =>
      interrupt({ email: { question: "What's your email?" } }),
  })
  .addNode({
    id: "analyze_email",
    run: ({ state }) => {
      const domain = state.email?.split("@")[1] ?? "";
      const generic = new Set(["gmail.com", "yahoo.com", "outlook.com"]);
      return { isCompanyEmail: !generic.has(domain) };
    },
  })
  .addNode({
    id: "ask_company",
    run: ({ interrupt }) =>
      interrupt({ companyName: { question: "What company are you with?" } }),
  })
  .addNode({ id: "done", run: () => ({ ready: true }) })
  .addEdge(START, "ask_email")
  .addEdge("ask_email", "analyze_email")
  .addConditionalEdge("analyze_email", ["done", "ask_company"], (state) =>
    state.isCompanyEmail ? "done" : "ask_company",
  )
  .addEdge("ask_company", "done")
  .addEdge("done", END);
```

Async conditions work for branches that depend on external lookups:

```ts theme={null}
.addConditionalEdge(
  "check_inventory",
  ["confirm_order", "offer_alternative"],
  async (state) => {
    const inStock = await inventoryService.check(state.sku!);
    return inStock ? "confirm_order" : "offer_alternative";
  },
)
```

The return type is checked against the `to` list, so a typo in a branch target — or a target you forgot to declare — fails type-checking.

## Reaching END

When execution reaches `END`, the engine returns `status: "complete"` to the model and deletes the session's flow state so a stale `continue` call cannot resume it. Any node can point to `END`, directly or conditionally.

```ts theme={null}
.addConditionalEdge("review", [END, "ask_corrections"], (state) =>
  state.approved ? END : "ask_corrections",
)
```

## Loops

A conditional edge that points back to an earlier node creates a loop. Useful for retries or collection gathering.

```ts theme={null}
.addNode({
  id: "ask_item",
  run: ({ interrupt }) =>
    interrupt({ item: { question: "Add an item (or say 'done')" } }),
})
.addNode({
  id: "append",
  run: ({ state }) => ({
    items: [...(state.items ?? []), state.item].filter(Boolean) as string[],
  }),
})
.addEdge("ask_item", "append")
.addConditionalEdge("append", ["finalize", "ask_item"], (state) =>
  state.item === "done" ? "finalize" : "ask_item",
)
```

The engine enforces a hard cap of 50 iterations per tool call to prevent runaway loops between action nodes. You will still need `END` reachable from every branch or the flow can stall.

## Compile-time validation

`.compile()` validates the graph before returning. It throws if:

* No edge exists from `START`.
* A `START` edge or direct edge points at an undeclared node.
* A conditional edge declares a `to` target that is not a registered node.
* A conditional edge declares an empty `to` list.
* A node has no outgoing edge.
* An edge is declared `from` a non-existent node.

Errors surface immediately at startup, not at the first user interaction.

## Visualizing the graph

Both the builder and the compiled flow expose `graph()`, which returns a Mermaid `flowchart TD` string. Conditional edges render one dashed arrow per declared `to` target.

```ts theme={null}
console.log(flow.graph());
```

```mermaid theme={null}
flowchart TD
  __start__((Start))
  ask_email[ask_email]
  analyze_email[analyze_email]
  ask_company[ask_company]
  done[done]
  __end__((End))
  __start__ --> ask_email
  ask_email --> analyze_email
  analyze_email -.-> done
  analyze_email -.-> ask_company
  ask_company --> done
  done --> __end__
```


# Interrupts
Source: https://docs.waniwani.ai/sdk/flows/interrupts

Pause the flow to ask the user one or more questions.

An interrupt is the mechanism by which a flow collects information from the user. When a node returns `interrupt(...)`, the engine returns `status: "interrupt"` to the model, persists the current step, and waits. On the next `action: "continue"` call, the user's answers arrive in `stateUpdates`, validators run, and the engine advances along the node's outgoing edge.

## What gets persisted

Between an interrupt and the matching continue call, the flow store holds:

* The current step name (which node is paused).
* The full state snapshot at the time of pause.
* For single-question interrupts, the field being asked.

Everything else (handler closures, validator functions) lives in the compiled flow in memory. Validators are registered when a handler first returns an interrupt and are keyed by `"nodeName:fieldName"`. They are not serialized.

This has one operational consequence: if the server process restarts between the interrupt and the continue call, persisted state is reloaded but validator functions are rebuilt from the handler's return value as the interrupt re-executes. The interrupt handler must therefore be deterministic enough to produce the same validator for a given state.

## Single question

The smallest interrupt asks one question that writes its answer to one field.

```ts theme={null}
.addNode({
  id: "ask_email",
  run: ({ interrupt }) =>
    interrupt({
      email: { question: "What's your work email?" },
    }),
})
```

The key (`email`) must be a field in the flow's state schema. TypeScript enforces this.

## Suggestions

Pass `suggestions` to give the model a concrete list to offer. Pairs well with `z.enum()` state fields so the model validates the user's choice against a fixed set.

```ts theme={null}
.addNode({
  id: "ask_level",
  run: ({ interrupt }) =>
    interrupt({
      level: {
        question: "What's your ski level?",
        suggestions: ["beginner", "intermediate", "advanced"],
      },
    }),
})
```

Suggestions serve two audiences at once. The assistant receives them as candidate answers on every host, regardless of any configuration. In the Waniwani chat widget they can also render as clickable pills above the input — clicking one sends it as the visitor's answer — but only when the host chat surface opts the `"flow"` suggestion origin in:

* `<WaniwaniChat>`: `overrides={{ suggestionOrigins: ["channel", "page", "flow", "followup"] }}`
* `<script>` embed: `data-suggestion-origins="channel,page,flow,followup"`
* `<ChatEmbed>` (bare primitive): `suggestions={{ origins: ["flow"] }}`

Pills appear only when the step has **exactly one question still open**. That is evaluated at runtime, not from how you wrote the call: a four-question interrupt where three fields are already filled has one open question, so it gets pills. A step with two or more open questions gets none, because no single pill could answer them all. Other MCP hosts (ChatGPT, Claude) are unaffected either way: they have no pill row, and what they receive is unchanged.

## Hidden context

Sometimes the question you show the user differs from the guidance you want to give the model. Put the guidance in `context`. It is passed through the protocol marked as hidden, so the model uses it to shape phrasing without showing it verbatim.

Per-question context lives inside the question config:

```ts theme={null}
interrupt({
  email: {
    question: "What's your work email?",
    context: "Politely reject generic domains like gmail.com.",
  },
});
```

Interrupt-wide context lives in the second argument:

```ts theme={null}
interrupt(
  {
    date: { question: "When would you like to book?" },
  },
  {
    context: "Help the user commit to a relative date. Never suggest past dates.",
  },
);
```

## Multi-question interrupts

A single interrupt can ask several questions at once. The model asks them in one conversational message and the user's answers arrive together.

```ts theme={null}
.addNode({
  id: "ask_contact",
  run: ({ interrupt }) =>
    interrupt(
      {
        name: { question: "What's your name?" },
        email: { question: "What's your email?" },
      },
      { context: "Ask both in one natural message." },
    ),
})
```

If the user only answers some of the questions, the engine re-presents the interrupt with the unanswered ones filtered in. Validators run only once every field in the interrupt is filled.

## Validation and re-ask

Add a `validate` function to reject bad answers or enrich state.

```ts theme={null}
interrupt({
  email: {
    question: "What's your work email?",
    validate: (value) => {
      if (!value.includes("@")) {
        throw new Error("That doesn't look like an email.");
      }
      return { email: value.trim().toLowerCase() };
    },
  },
});
```

`value` is typed from the Zod schema for that field. The function can:

* Return `void` to accept the answer as-is.
* Return a `Partial<TState>` object to merge extra updates (for example, an enriched lookup result).
* Throw an `Error` (not return a string) to reject the answer.

On a thrown error, the engine:

1. Clears the offending field from state.
2. Re-presents the same interrupt.
3. Prepends `ERROR: <message>` to that specific question's `context` so the model can relay the reason naturally.

Other questions in a multi-question interrupt are not cleared. Only the failing field is re-asked.

Validators run after all fields for an interrupt are filled, and before the engine advances along the outgoing edge. Any updates they return are visible in the next node.

## Nested fields

If state uses `z.object()` for one level of nesting, target sub-fields with dot-paths.

```ts theme={null}
state: {
  driver: z.object({
    name: z.string().describe("Driver name"),
    license: z.string().describe("License number"),
  }),
}

// In a node:
interrupt({
  "driver.name": { question: "What's the driver's name?" },
  "driver.license": { question: "What's their license number?" },
})
```

Only one level of nesting is supported. See [State](/sdk/flows/state).

## Auto-skip when a field is already filled

If the user's opening message provides an answer (passed via `stateUpdates` on `action: "start"`), the engine skips any interrupt whose fields are already populated. For multi-question interrupts, already-answered questions are filtered out and only the unanswered ones are presented. An interrupt whose fields are all filled is skipped entirely.

Values of `undefined`, `null`, and `""` do not count as filled.

## Gotchas

* **Throw, do not return strings.** A validator that returns a string is treated as `void`, so the answer is accepted. Throw `new Error("...")` to reject.
* **Validators run on all-filled, not per-question.** In a multi-question interrupt, a validator for question A will not fire until question B is also answered. Design validations accordingly.
* **Validator closures can reference `state` from the handler.** That `state` is the snapshot at the time the handler ran, not at the time the user answered. If you need the freshest state, do the lookup inside the validator using the value argument plus your own fetch, not the closed-over `state`.
* **The field is cleared on error, not the whole interrupt.** After a failed validation, only the failing field is empty. The user's other answers remain.


# KV store adapters
Source: https://docs.waniwani.ai/sdk/flows/kv-store

Plug any key-value backend into createFlow via the KvStore interface.

<Note>
  **Open source.** The KV store interface works without an API key. The hosted `WaniwaniKvStore` requires the [Waniwani Platform](/sdk/platform/overview).
</Note>

A flow needs a place to persist its state between MCP calls. MCP tools are stateless, so without a store the engine has nothing to resume from on the next `continue` call. **Every compiled flow is therefore required to have a store.** `.compile()` throws at compile time if you pass neither a `store` argument nor configure `WANIWANI_API_KEY`.

`createFlow` persists this state through a tiny `KvStore` interface. Implement it against any key-value backend: Redis, Upstash, Cloudflare KV, DynamoDB, even a SQLite table. The SDK ships two implementations out of the box, and you can write your own in \~10 lines.

<Note>
  The KV store powers the flow engine only. It is **not** what drives dashboards, funnel analytics, or event tracking. Those are a separate pipeline fed by `withWaniwani(server)` and `client.track()`. You can run a fully self-hosted KV (no API key, nothing leaves your infra) and still get hosted dashboards by also calling `withWaniwani(server)` with `WANIWANI_API_KEY` set. The two paths are independent.
</Note>

## The interface

```ts theme={null}
export interface KvStore<T = Record<string, unknown>> {
  get(key: string): Promise<T | null>;
  set(key: string, value: T): Promise<void>;
  delete(key: string): Promise<void>;
}
```

That's it. The engine handles serialization, session-key derivation, expiry semantics, and concurrency.

## Built-in implementations

The SDK ships two implementations. Pick one or write your own (recipes below).

```ts theme={null}
import { MemoryKvStore, WaniwaniKvStore } from "@waniwani/sdk/mcp";

// In-memory Map, resets on restart. For development and tests.
const flow = createFlow({ /* ... */ }).compile({ store: new MemoryKvStore() });

// Hosted on app.waniwani.ai. Auto-selected when WANIWANI_API_KEY is set
// and no explicit store is passed.
const flow = createFlow({ /* ... */ }).compile(); // picks WaniwaniKvStore

// Or instantiate it manually.
const flow = createFlow({ /* ... */ }).compile({ store: new WaniwaniKvStore() });
```

See the [Platform overview](/sdk/platform/overview) for when the hosted store makes sense versus a self-hosted adapter.

## Adapter recipes

Drop-in `KvStore` implementations for common backends.

### Upstash Redis (serverless, HTTP)

```ts theme={null}
import type { KvStore } from "@waniwani/sdk/mcp";
import { Redis } from "@upstash/redis";

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL!,
  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
});

export const upstashStore: KvStore = {
  async get(key) {
    return (await redis.get(key)) as never;
  },
  async set(key, value) {
    await redis.set(key, value);
  },
  async delete(key) {
    await redis.del(key);
  },
};
```

### Node Redis (`ioredis` or `redis`)

```ts theme={null}
import type { KvStore } from "@waniwani/sdk/mcp";
import Redis from "ioredis";

const redis = new Redis(process.env.REDIS_URL!);

export const redisStore: KvStore = {
  async get(key) {
    const raw = await redis.get(key);
    return raw ? JSON.parse(raw) : null;
  },
  async set(key, value) {
    await redis.set(key, JSON.stringify(value));
  },
  async delete(key) {
    await redis.del(key);
  },
};
```

### Cloudflare Workers KV

```ts theme={null}
import type { KvStore } from "@waniwani/sdk/mcp";

export function cloudflareKvStore(ns: KVNamespace): KvStore {
  return {
    async get(key) {
      return ns.get<Record<string, unknown>>(key, "json");
    },
    async set(key, value) {
      await ns.put(key, JSON.stringify(value));
    },
    async delete(key) {
      await ns.delete(key);
    },
  };
}

// In your worker:
const flow = createFlow({ /* ... */ }).compile({
  store: cloudflareKvStore(env.FLOW_STATE_KV),
});
```

### DynamoDB

```ts theme={null}
import type { KvStore } from "@waniwani/sdk/mcp";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
  DynamoDBDocumentClient,
  DeleteCommand,
  GetCommand,
  PutCommand,
} from "@aws-sdk/lib-dynamodb";

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const TABLE = "flow_state";

export const dynamoStore: KvStore = {
  async get(key) {
    const res = await ddb.send(new GetCommand({ TableName: TABLE, Key: { pk: key } }));
    return (res.Item?.value as never) ?? null;
  },
  async set(key, value) {
    await ddb.send(new PutCommand({ TableName: TABLE, Item: { pk: key, value } }));
  },
  async delete(key) {
    await ddb.send(new DeleteCommand({ TableName: TABLE, Key: { pk: key } }));
  },
};
```

### SQLite (better-sqlite3)

Quick local persistence without standing up a separate service.

```ts theme={null}
import type { KvStore } from "@waniwani/sdk/mcp";
import Database from "better-sqlite3";

const db = new Database("flow-state.db");
db.exec("CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value TEXT)");

const getStmt = db.prepare("SELECT value FROM kv WHERE key = ?");
const setStmt = db.prepare("INSERT OR REPLACE INTO kv (key, value) VALUES (?, ?)");
const delStmt = db.prepare("DELETE FROM kv WHERE key = ?");

export const sqliteStore: KvStore = {
  async get(key) {
    const row = getStmt.get(key) as { value: string } | undefined;
    return row ? JSON.parse(row.value) : null;
  },
  async set(key, value) {
    setStmt.run(key, JSON.stringify(value));
  },
  async delete(key) {
    delStmt.run(key);
  },
};
```

## Encryption at rest

`WaniwaniKvStore` encrypts values at rest with AES-256-GCM before they leave the SDK. You don't have to do anything; it's handled inside the store.

For self-hosted stores, encryption is your responsibility. If your backend doesn't provide encryption at rest, wrap your adapter:

```ts theme={null}
import type { KvStore } from "@waniwani/sdk/mcp";
import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";

function encrypted(inner: KvStore, key: Buffer): KvStore {
  return {
    async get(k) {
      const raw = await inner.get(k);
      if (!raw) return null;
      // ...decrypt with key, return parsed value
    },
    async set(k, value) {
      // ...encrypt JSON.stringify(value) with key
      await inner.set(k, /* encrypted envelope */);
    },
    async delete(k) {
      await inner.delete(k);
    },
  };
}
```

The `KvStore` interface composes trivially. Encrypt at the wrapper boundary; the engine stays unaware.

## What gets stored

Each session maps to one key. The engine stores:

* The current node (or `END` when complete)
* The merged state object so far
* A pending widget reference, if the current node is a `showWidget` step

Keys are derived from the MCP session identifier (`_meta.waniwani/sessionId` or `Mcp-Session-Id`), so isolating sessions is automatic. Values are JSON-serializable plain objects.

## Choosing a backend

| Goal                                 | Pick                         |
| ------------------------------------ | ---------------------------- |
| Local dev, tests, ephemeral          | `MemoryKvStore`              |
| Zero infra, encrypted at rest        | `WaniwaniKvStore` (Platform) |
| Vercel / Netlify / serverless edge   | Upstash Redis adapter        |
| Cloudflare Workers                   | Workers KV adapter           |
| AWS Lambda                           | DynamoDB adapter             |
| Single-node Node.js with persistence | SQLite or Node Redis         |

Picking `WaniwaniKvStore` does not by itself enable dashboards or funnel analytics. Those come from tracking events emitted by `withWaniwani(server)`. The two systems are independent.


# Nodes
Source: https://docs.waniwani.ai/sdk/flows/nodes

Handlers that advance the flow: action, interrupt, or widget.

A node is one step in a flow. You register it with `.addNode({ id, run, label?, hideFromFunnel? })`. The `run` handler receives a context object and returns one of three things:

1. A plain state update (action node).
2. An interrupt signal (pause and ask).
3. A widget signal (pause and delegate to a display tool).

The return type determines what the engine does next.

```ts theme={null}
flow.addNode({
  id: "ask_email",
  run: ({ interrupt }) =>
    interrupt({ email: { question: "What is your work email?" } }),
});
```

<Tip>
  An older positional form (`addNode(id, run, options?)`) is also accepted, but is deprecated. See [Changelog / 0.12.0](/sdk/changelog#0-12-0-addnode-object-form).
</Tip>

## Node context

Every handler receives a single argument with this shape:

```ts theme={null}
type NodeContext<TState> = {
  state: Partial<TState>;
  meta?: Record<string, unknown>;
  interrupt: TypedInterrupt<TState>;
  showWidget: TypedShowWidget<TState>;
  waniwani?: ScopedWaniWaniClient;
};
```

<ResponseField name="state" type="Partial<TState>">
  Current flow state. Partial because earlier nodes may not have filled every field yet.
</ResponseField>

<ResponseField name="meta" type="Record<string, unknown> | undefined">
  The MCP request `_meta` for this tool call. Rarely needed directly. Use `waniwani` for tracking.
</ResponseField>

<ResponseField name="interrupt" type="TypedInterrupt<TState>">
  Helper to build an interrupt signal. Field keys are typed against the state schema. See [Interrupts](/sdk/flows/interrupts).
</ResponseField>

<ResponseField name="showWidget" type="TypedShowWidget<TState>">
  Helper to build a widget signal. Accepts a tool id as a string, or a `RegisteredTool` object (`{ id, title, description, register }`, imported as a type from `@waniwani/sdk/mcp`).
</ResponseField>

<ResponseField name="waniwani" type="ScopedWaniWaniClient | undefined">
  A session-scoped tracking client. Present when the MCP server is wrapped with [`withWaniwani()`](/sdk/configuration/wrap-server). Undefined otherwise.
</ResponseField>

## Action nodes

An action node returns a plain state update. The engine deep-merges the update into state and advances along the node's outgoing edge without pausing.

```ts theme={null}
.addNode({
  id: "normalize_email",
  run: ({ state }) => {
    if (!state.email) return {};
    return { email: state.email.trim().toLowerCase() };
  },
})
```

Action nodes are where you put transformations, API calls, database writes, and analytics. Multiple action nodes in a row all run inside one tool call. The engine only pauses when a node returns an interrupt or widget signal.

```ts theme={null}
.addNode({
  id: "check_stock",
  run: async ({ state, waniwani }) => {
    const inStock = await stockService.check(state.sku);
    await waniwani?.track({
      event: "tool.called",
      properties: { name: "check_stock", type: "other" },
    });
    return { inStock };
  },
})
```

## Interrupt nodes

An interrupt node returns `interrupt(...)`. The engine stores the graph step, returns `status: "interrupt"` to the model, and waits for a `continue` call. When the user answers, the node's validators run (if any) and the engine advances.

```ts theme={null}
.addNode({
  id: "ask_ski_level",
  run: ({ interrupt }) =>
    interrupt({
      level: {
        question: "What's your ski level?",
        suggestions: ["beginner", "intermediate", "advanced"],
      },
    }),
})
```

See [Interrupts](/sdk/flows/interrupts) for multi-question interrupts, hidden context, validation, and re-ask on error.

## Widget nodes

A widget node returns `showWidget({ tool, ... })`. The engine returns `status: "widget"` pointing at a display tool registered on your MCP server, and the flow pauses. When the user interacts, the host calls the flow back with `action: "continue"` and whatever values you want stored in `stateUpdates`.

```ts theme={null}
.addNode({
  id: "show_pricing",
  run: ({ state, showWidget }) =>
    showWidget({
      tool: "show_pricing",
      data: {
        postalCode: state.postalCode!,
        sqm: Number(state.squareMeters),
      },
      field: "selectedPlan",
    }),
})
```

<Note>
  The positional form `showWidget(tool, config)` is **deprecated** but still supported for back-compat. Migrate to the object form for new code.
</Note>

Setting `field` enables the same auto-skip behavior as interrupts: if `selectedPlan` is already filled when the flow reaches this node, the widget is skipped. Setting `interactive: false` makes the widget display-only and auto-advances after it renders.

<Note>
  The flow itself is a data-only tool. It never returns `structuredContent`. The display tool referenced by `showWidget` is the one that renders the widget. Register the display tool with [Skybridge's](https://docs.skybridge.tech) `server.registerWidget(name, meta, schema, handler)` and the flow with `flow.register(server)` — Skybridge handles all the widget-binding metadata for you. See the [Pet insurance example](/sdk/guides/pet-insurance#register-the-widget-display-tools) for the full pattern.
</Note>

## Async handlers

Handlers can be sync or async. Most real handlers are async because they touch external services:

```ts theme={null}
.addNode({
  id: "fetch_pricing",
  run: async ({ state }) => {
    const prices = await pricingApi.quote({
      postalCode: state.postalCode!,
      size: state.squareMeters!,
    });
    return { prices };
  },
})
```

## Naming and uniqueness

Node names are internal identifiers. They appear in Mermaid diagrams (`flow.graph()`), compile-time validation errors, and error messages at runtime. Use `snake_case`, keep them short, prefer verbs for actions and `ask_*` for interrupts.

Node names must be unique within a flow. Adding the same name twice throws at build time. `START` and `END` are reserved and cannot be used as node names.


# Flows Overview
Source: https://docs.waniwani.ai/sdk/flows/overview

Multi-step MCP tools for sales funnels, lead generation, booking, and quote apps. Defined as a graph.

<Note>
  **Open source.** Works without an API key. Connect the [Waniwani Platform](/sdk/platform/overview) to add tracking, knowledge base, chat, and hosted state.
</Note>

A flow is a graph of nodes that compiles into a single MCP tool. Each tool call runs the engine one step at a time: it asks a question, validates the answer, branches on state, then persists progress server-side under the MCP session id. The model never has to carry a token between calls.

## Flows are MCP funnels

Most apps people build with flows are funnels: a sales funnel, a lead generation flow, a booking flow, an insurance quote flow, a pricing quote flow. The two vocabularies map cleanly:

| Funnel term              | Flow term                |
| ------------------------ | ------------------------ |
| Funnel step / page       | Node                     |
| Drop-off / conversion    | Edge taken vs. abandoned |
| Form field               | Interrupt                |
| Branching question       | Conditional edge         |
| Funnel state (lead data) | Flow state (typed)       |

If you're building an MCP funnel, you're building a flow. The rest of this page is the graph engine that powers it.

Flows exist because multi-step conversations need explicit state. Whether your MCP server runs as a long-running process or a serverless function, anything longer than a single-shot Q\&A (onboarding, quoting, qualification, triage, lead capture, booking) otherwise becomes a hand-rolled state machine serialized through the model.

## What you declare

1. **State.** The fields the flow collects, as a map of Zod schemas. State is type-inferred.
2. **Nodes.** Handlers that return state updates, an interrupt signal, or a widget signal.
3. **Edges.** How nodes connect. Direct or conditional.

You call `.compile()` on the graph to get a `RegisteredFlow`, then register it on your MCP server.

## Minimal flow

```ts theme={null}
import { createFlow, END, MemoryKvStore, START } from "@waniwani/sdk/mcp";
import { z } from "zod";

export const onboardingFlow = createFlow({
  id: "onboarding",
  title: "User Onboarding",
  description: "Use when a new user wants to get started.",
  state: {
    email: z.string().describe("Work email"),
    useCase: z.string().describe("What they want to build"),
  },
})
  .addNode({
    id: "ask_email",
    run: ({ interrupt }) =>
      interrupt({ email: { question: "What is your work email?" } }),
  })
  .addNode({
    id: "ask_use_case",
    run: ({ interrupt }) =>
      interrupt({
        useCase: {
          question: "What do you want to build?",
          suggestions: ["Analytics", "Support", "Lead capture"],
        },
      }),
  })
  .addEdge(START, "ask_email")
  .addEdge("ask_email", "ask_use_case")
  .addEdge("ask_use_case", END)
  .compile({ store: new MemoryKvStore() });
```

`MemoryKvStore` is fine for development and tests. For production, plug in a real backend (Redis, Upstash, Cloudflare KV, DynamoDB) or set `WANIWANI_API_KEY` to use hosted state. See [KV store adapters](/sdk/flows/kv-store).

Register it on your server:

```ts theme={null}
await onboardingFlow.register(server);
```

That is a complete, working flow. See [Register](/sdk/flows/register) for full server wiring.

## Execution model

Every tool call drives the engine until it hits one of three outcomes:

* **Interrupt.** Pause and ask the user one or more questions. The response carries `status: "interrupt"`.
* **Widget.** Pause and delegate rendering to a display tool. The response carries `status: "widget"`.
* **Complete.** The graph reached `END`. The response carries `status: "complete"` and server-side state is deleted.

Between those pause points, the engine auto-advances through action nodes (nodes that return a plain state update). No round-trip to the model. A single tool call can run several action nodes before hitting the next interrupt.

State persists between calls in the flow store, keyed by the session id extracted from `_meta`. You pick the store at `.compile()` time. See [KV store adapters](/sdk/flows/kv-store) and the [Platform overview](/sdk/platform/overview) for the hosted option.

## Tool contract

A compiled flow registers itself as a single MCP tool. The model calls it with `{ action: "start" | "continue", intent?, stateUpdates? }` and receives one of four response statuses: `interrupt`, `widget`, `complete`, or `error`. You don't usually parse responses yourself; the protocol is documented in the generated tool description so the model knows how to call it.

See [Flow tool contract](/sdk/reference/flow-tool-contract) for the full input/output schema.

## What to read next

<CardGroup>
  <Card title="Architecture" icon="diagram-project" href="/sdk/flows/architecture">
    How a tool call drives the engine, and why the KV store is required.
  </Card>

  <Card title="State" icon="database" href="/sdk/flows/state">
    Declare the fields the flow collects. Type inference flows from here.
  </Card>

  <Card title="Nodes" icon="circle-nodes" href="/sdk/flows/nodes">
    The three kinds of nodes and the context they receive.
  </Card>

  <Card title="Edges" icon="arrow-right" href="/sdk/flows/edges">
    Direct edges, conditional edges, loops, and compile-time validation.
  </Card>

  <Card title="Interrupts" icon="hand" href="/sdk/flows/interrupts">
    Pausing, resuming, validation, and re-ask on error.
  </Card>

  <Card title="Register" icon="plug" href="/sdk/flows/register">
    Wire the compiled flow onto an MCP server end-to-end.
  </Card>
</CardGroup>


# Compile & Register
Source: https://docs.waniwani.ai/sdk/flows/register

Compile a flow and wire it onto an MCP server.

Once nodes and edges are in place, you compile the graph and register it. `.compile()` returns a `RegisteredFlow` that maps onto the standard `server.registerTool(name, config, handler)` contract.

## Compile

```ts theme={null}
const onboardingFlow = createFlow({
  id: "onboarding",
  title: "User Onboarding",
  description: "Use when a new user wants to get started.",
  state: { /* ... */ },
})
  .addNode({ id: "...", run: () => ({}) })
  .addEdge(/* ... */)
  .compile();
```

`.compile()` validates the graph (see [Edges](/sdk/flows/edges)) and throws immediately if the graph is malformed. Accepts one optional argument for a custom state store:

```ts theme={null}
.compile({ store: myCustomStore });
```

The default is `WaniwaniFlowStore`, which uses the Waniwani API as a key-value store keyed by session id. It reads `WANIWANI_API_KEY` and `WANIWANI_API_URL` from env.

## The RegisteredFlow shape

```ts theme={null}
type RegisteredFlow = {
  name: string;            // MCP tool name (equals config.id)
  config: ToolConfig;      // title, description, inputSchema, annotations
  handler: FlowToolHandler;
  register: (server: McpServer) => Promise<void>;
  graph: () => string;     // Mermaid flowchart TD
};
```

## Registering

Use the `register` shortcut for the common case:

```ts theme={null}
await onboardingFlow.register(server);
```

Or call `server.registerTool` directly if you prefer:

```ts theme={null}
server.registerTool(
  onboardingFlow.name,
  onboardingFlow.config,
  onboardingFlow.handler,
);
```

Both are equivalent.

## Registering widget display tools alongside flows

When a flow uses `showWidget({ tool: "name", ... })`, the named display tool must be registered on the same server. Use [Skybridge's](https://docs.skybridge.tech) `server.registerWidget(name, meta, schema, handler)` — it binds the widget name to the matching React component under `web/src/widgets/<name>.tsx` and emits the widget-rendering metadata that ChatGPT, Claude, and other MCP clients understand. You don't need to set `_meta.openai/outputTemplate` by hand.

```ts theme={null}
server
  .registerWidget(
    "show_pricing",
    { description: "Display the pricing plan grid. Do NOT list plans in text." },
    { inputSchema: { /* zod fields */ }, annotations: { readOnlyHint: true } },
    async (input) => ({
      structuredContent: input,
      content: [{ type: "text", text: "Pricing shown" }],
      isError: false,
    }),
  )
  .registerTool(quoteFlow.name, quoteFlow.config, quoteFlow.handler);
```

See the [Pet insurance example](/sdk/guides/pet-insurance#register-the-widget-display-tools) for a complete server.

## Minimal end-to-end wiring

A complete `server/src/app.ts` looks like this:

```ts server/src/app.ts theme={null}
import "dotenv/config";
import { McpServer } from "skybridge/server";
import { withWaniwani } from "@waniwani/sdk/mcp";
import { onboardingFlow } from "./flows/onboarding.js";
import { quoteFlow } from "./flows/quote.js";

export const server = new McpServer(
  { name: "my-mcp-app", version: "0.0.1" },
  { capabilities: {} },
)
  .registerTool(onboardingFlow.name, onboardingFlow.config, onboardingFlow.handler)
  .registerTool(quoteFlow.name, quoteFlow.config, quoteFlow.handler);

// Wrap after registrations to auto-track every tool call.
withWaniwani(server);

export type AppType = typeof server;
```

`withWaniwani` is idempotent — calling it twice on the same server is a no-op. The `skybridge/server` import is what the [MCP distribution template](https://github.com/WaniWani-AI/mcp-distribution-template) uses as the dev/build runtime; it provides the `.registerWidget(...)` fluent API plus widget mounting for the React components under `web/src/widgets/`.

## Debugging a compiled flow

### Inspect the graph

`flow.graph()` returns a Mermaid diagram of the compiled flow. Log it at startup in development:

```ts theme={null}
if (process.env.NODE_ENV !== "production") {
  console.log(onboardingFlow.graph());
}
```

Paste the output into any Mermaid renderer.

### Unit-test with `createFlowTestHarness`

The SDK ships a test harness that drives a compiled flow without spinning up a real transport or store. Import it from `@waniwani/sdk/mcp`:

```ts theme={null}
import { createFlowTestHarness } from "@waniwani/sdk/mcp";
import { onboardingFlow } from "./flows/onboarding.js";

const harness = await createFlowTestHarness(onboardingFlow);

const first = await harness.start("Get me onboarded");
// first.status === "interrupt"
// first.field === "email"

const second = await harness.continueWith({ email: "alice@example.com" });
// second.status === "interrupt"
// second.field === "useCase"
```

The harness API is:

* `start(intent, stateUpdates?)`: begins a run. `intent` is positional.
* `continueWith(stateUpdates?)`: resumes the paused run.
* `lastState()`: returns the persisted `FlowTokenContent` when a store is passed via `createFlowTestHarness(flow, { stateStore })`.

Each call returns a `FlowTestResult` that is the parsed `FlowContent` (interrupt, widget, complete, or error) plus a `decodedState` field populated when a store is supplied. Use it to write deterministic tests for branching, validation, and state transitions.


# State & Persistence
Source: https://docs.waniwani.ai/sdk/flows/state

Typed fields collected by the flow, persisted via the pluggable KvStore interface.

This page covers the state schema: the typed fields a flow collects. A flow also needs a place to persist that state between MCP calls. See [Persistence](/sdk/flows/kv-store), which is required for any flow to work.

## State schema

Every flow declares `state` as a map of field names to Zod schemas. The runtime state type is inferred from this map, so `ctx.state` is fully typed inside every node. Field descriptions also feed the model's tool description, so it knows what to collect.

```ts theme={null}
import { createFlow } from "@waniwani/sdk/mcp";
import { z } from "zod";

const flow = createFlow({
  id: "quote",
  title: "Quote",
  description: "Collect quote inputs.",
  state: {
    postalCode: z.string().describe("ZIP or postal code of the property"),
    squareMeters: z.number().describe("Home size in square meters"),
    heating: z
      .enum(["gas", "electric", "oil", "heat_pump"])
      .describe("Primary heating source"),
  },
});
```

Inside a node:

```ts theme={null}
.addNode({
  id: "summarize",
  run: ({ state }) => {
    // state is Partial<{
    //   postalCode: string;
    //   squareMeters: number;
    //   heating: "gas" | "electric" | "oil" | "heat_pump";
    // }>
    return { summary: `${state.postalCode}, ${state.squareMeters}m2` };
  },
})
```

<Tip>
  Always add `.describe()` to every field. It is what the model reads when phrasing questions and deciding which values it can pre-fill. The most load-bearing piece of documentation your flow ships with.
</Tip>

## State is always partial

At any point during execution, only the fields filled by earlier nodes are populated. The engine types `ctx.state` as `Partial<TState>`, so always guard when reading fields.

```ts theme={null}
.addNode({
  id: "review",
  run: ({ state }) => {
    if (!state.email || !state.company) {
      return {};
    }
    return { reviewed: true };
  },
})
```

## Field types

Prefer constrained types. The more constrained a field, the better the model fills it.

| Field shape           | Use                          |
| --------------------- | ---------------------------- |
| Fixed choices         | `z.enum([...])`              |
| Free-form text        | `z.string()`                 |
| Bounded numbers       | `z.number().min(0).max(100)` |
| Booleans              | `z.boolean()`                |
| Lists                 | `z.array(z.string())`        |
| Nested group (1 deep) | `z.object({ ... })`          |

### Enums pair well with suggestions

```ts theme={null}
state: {
  level: z
    .enum(["beginner", "intermediate", "advanced"])
    .describe("The user's ski level"),
}
```

An interrupt that lists the same values as `suggestions` will lead the model to offer exactly those and validate the answer against the enum.

## Nested state

Use `z.object()` when a sub-entity has multiple fields. Only one level of nesting is supported.

```ts theme={null}
state: {
  driver: z
    .object({
      name: z.string().describe("Driver's full name"),
      licenseNumber: z.string().describe("Driving license number"),
    })
    .describe("Driver details"),
  pickupDate: z.string().describe("Pickup date (YYYY-MM-DD)"),
}
```

Interrupts target nested fields with dot-paths:

```ts theme={null}
.addNode({
  id: "ask_driver",
  run: ({ interrupt }) =>
    interrupt({
      "driver.name": { question: "What's the driver's name?" },
      "driver.licenseNumber": { question: "What's their license number?" },
    }),
})
```

Action nodes that return nested objects are deep-merged, so returning `{ driver: { name: "John" } }` does not wipe `driver.licenseNumber`.

<Warning>
  `driver.address.city` will not work. Flatten deeper hierarchies or handle the sub-object in one question that fills the whole `z.object()` at once.
</Warning>

## Pre-filling from the user's message

When the user's opening message already contains answers (for example, "I'm in 75011, quote me a half-day lesson"), the model can pass them in `stateUpdates` on the very first call:

```json theme={null}
{ "action": "start", "intent": "...", "stateUpdates": { "postalCode": "75011" } }
```

The engine auto-skips any node whose target field is already filled (values of `undefined`, `null`, or `""` do not count as filled). No extra configuration is needed. Just make sure field descriptions are clear enough for the model to map message content to field names.

## How state updates happen

Nodes update state in three places:

1. **Action nodes** return a plain object that is deep-merged into state.
2. **Interrupts** store the user's answer at the field key used in `interrupt({ field: { question } })`.
3. **Interrupt validators** (see [Interrupts](/sdk/flows/interrupts)) can return additional state updates after a user answer passes validation.

All three paths are typed against the state schema.


# Booking
Source: https://docs.waniwani.ai/sdk/guides/booking

Build a booking MCP app: pick a service, check availability, pick a slot, confirm. Runs as a single MCP tool.

This page shows you how to **build a booking MCP app** with `@waniwani/sdk`. The user picks a service, the funnel checks availability, the user picks a slot, the funnel confirms. Runs as one MCP tool inside ChatGPT, Claude, or any MCP client.

## What you'll build

A booking flow that:

1. Asks **what service** they want (haircut, consultation, demo, etc.)
2. Calls your **availability API** (action node)
3. Asks the user to **pick a slot**
4. **Confirms the booking** with your backend
5. Returns a **booking reference**

## Flow graph

```mermaid theme={null}
graph TD
    S((Start)) --> SV[ask_service]
    SV --> A[fetch_availability]
    A --> SL[ask_slot]
    SL --> N[ask_name_email]
    N --> C[confirm_booking]
    C --> END((End))
```

## Code

```ts theme={null}
import { createFlow, START, END } from "@waniwani/sdk/mcp";
import { z } from "zod";
import { bookingApi } from "./booking-api";

export const bookingFunnel = createFlow({
  id: "booking",
  title: "Booking",
  description: "Use when the user wants to book a service. Collects service, slot, and contact info, then confirms the booking.",
  state: {
    service: z.string().describe("Which service the user wants to book"),
    availableSlots: z.array(z.string()).describe("ISO timestamps fetched from the API"),
    slot: z.string().describe("Chosen ISO timestamp"),
    name: z.string().describe("Full name"),
    email: z.string().describe("Email for the confirmation"),
    bookingRef: z.string().optional().describe("Booking reference (set on confirmation)"),
  },
})
  .addNode({
    id: "ask_service",
    label: "Pick a service",
    run: ({ interrupt }) =>
      interrupt({
        service: {
          question: "What would you like to book?",
          suggestions: ["Consultation", "Demo", "Onboarding session"],
        },
      }),
  })
  .addNode({
    id: "fetch_availability",
    label: "Fetch availability",
    hideFromFunnel: true,
    run: async ({ state }) => {
      const slots = await bookingApi.listAvailability(state.service);
      return { availableSlots: slots };
    },
  })
  .addNode({
    id: "ask_slot",
    label: "Pick a slot",
    run: ({ state, interrupt }) =>
      interrupt({
        slot: {
          question: "Pick a time that works for you.",
          suggestions: state.availableSlots,
          context: `Available slots (ISO timestamps): ${state.availableSlots.join(", ")}. Present these to the user in their local timezone in a friendly format. When they pick one, set slot to the matching ISO timestamp.`,
        },
      }),
  })
  .addNode({
    id: "ask_name_email",
    label: "Capture contact",
    run: ({ interrupt }) =>
      interrupt({
        name: { question: "Your name?" },
        email: { question: "And your email for the confirmation?" },
      }),
  })
  .addNode({
    id: "confirm_booking",
    label: "Confirm booking",
    run: async ({ state }) => {
      const booking = await bookingApi.create({
        service: state.service,
        slot: state.slot,
        name: state.name,
        email: state.email,
      });
      return { bookingRef: booking.ref };
    },
  })
  .addEdge(START, "ask_service")
  .addEdge("ask_service", "fetch_availability")
  .addEdge("fetch_availability", "ask_slot")
  .addEdge("ask_slot", "ask_name_email")
  .addEdge("ask_name_email", "confirm_booking")
  .addEdge("confirm_booking", END)
  .compile();
```

## Register

```ts theme={null}
await bookingFunnel.register(server);
```

## Patterns this uses

* **Action nodes for API calls.** `fetch_availability` and `confirm_booking` run without user interaction. See [Flows → Nodes](/sdk/flows/nodes).
* **Suggestions passed at runtime.** `ask_slot` uses suggestions computed from `state.availableSlots`. See [Flows → Interrupts](/sdk/flows/interrupts).
* **Conditional re-asking.** Add a `validate` callback on `slot` to re-ask if the slot was taken between fetch and confirm.

## Variants

* **Recurring availability cache.** Skip the `fetch_availability` node by pre-loading slots and rotating them daily.
* **Multi-service with conditional branching.** Branch on `service` to ask different follow-up questions (e.g. "Bringing a guest?" only for consultations). See [Flows → Edges](/sdk/flows/edges).
* **Add a confirmation widget.** Use `showWidget` to display the booking card visually. See the [Pet Insurance Quote example](/sdk/guides/pet-insurance) for the widget handoff pattern.

## Add funnel analytics

Set `WANIWANI_API_KEY` and you'll see step-by-step drop-off using the node labels: **Pick a service → Pick a slot → Capture contact → Confirm booking**. `fetch_availability` is hidden from the funnel (`hideFromFunnel: true`) because it's plumbing, not a user-facing step. Helps you spot whether users abandon at slot selection or contact info. See [Tracking → Overview](/sdk/tracking/overview).

## Next

<CardGroup>
  <Card title="Build a sales funnel MCP" icon="filter" href="/sdk/guides/sales-funnel" />

  <Card title="Build an insurance quote MCP" icon="shield" href="/sdk/guides/insurance-quote" />

  <Card title="Widgets in flows" icon="window-maximize" href="/sdk/guides/pet-insurance" />

  <Card title="Conditional edges" icon="code-branch" href="/sdk/flows/edges" />
</CardGroup>


# Commands
Source: https://docs.waniwani.ai/sdk/guides/commands

Guided commands available with the Waniwani SDK agent skill.

The Waniwani SDK skill ships with guided commands (playbooks) that walk your AI agent through common tasks step by step. After [installing the skill](/sdk/guides/skills), invoke them as slash commands in Claude Code, Cursor, or any compatible agent.

```bash theme={null}
/waniwani-sdk <command>
```

## initialize

Scaffold a new MCP distribution project from the Waniwani template. The agent interactively gathers your brand, use case, and data source, then generates a production-ready flow with widgets.

```bash theme={null}
/waniwani-sdk initialize
```

**What it does:**

1. **Gathers context** -- asks for your website URL, use case (quote flow, booking, lead qualification, etc.), data source (real API or mock), and customer profile.
2. **Extracts branding** -- visits your website in the background to pull colors, logo, fonts, and tone.
3. **Presents a plan** -- shows the proposed flow structure, widgets, and data approach for your approval.
4. **Scaffolds the project** -- updates `package.json`, sets up `.env`, installs dependencies.
5. **Removes demo content** -- clears the reference implementation (Alpine ski lessons) so you start clean.
6. **Generates flow + widgets** -- creates the flow file with state, nodes, edges, and widget components styled to your brand.
7. **Wires everything up** -- registers tools, widgets, and tracking in the server entry point.
8. **Tests** -- builds and starts the dev server so you can walk through the flow immediately.

**Best for:** Starting a brand-new MCP project from scratch.

***

## create-flow

Build a multi-step conversational flow from scratch in an existing project. The agent designs the state schema, node graph, and edges based on your description.

```bash theme={null}
/waniwani-sdk create-flow
```

**What it does:**

1. **Checks prerequisites** -- verifies `@waniwani/sdk` is installed, `WANIWANI_API_KEY` is set, and a client singleton exists. Fixes anything missing.
2. **Understands your goal** -- asks you to describe the flow in one sentence (lead qualification, onboarding, quote/pricing, support triage, survey, etc.).
3. **Designs the state** -- creates a Zod schema with `.describe()` on every field so the AI knows what each piece of data is for.
4. **Designs the nodes** -- maps each step to an interrupt node (asks questions), action node (silent computation), or widget node (shows UI).
5. **Designs the edges** -- connects nodes sequentially and adds conditional edges for branching logic.
6. **Generates the flow file** -- writes the complete flow with `createFlow`, `START`/`END` edges, and `.compile()`.
7. **Registers the flow** -- wires it into your MCP server route by calling the compiled flow's `register(server)`.
8. **Tests** -- starts the dev server and walks you through triggering and completing the flow.

**Best for:** Adding a new flow to an existing MCP project.

***

## tunnel

Start your local MCP dev server and expose it via a public tunnel so remote clients (ChatGPT, Claude, etc.) can reach it.

```bash theme={null}
/waniwani-sdk tunnel
```

**What it does:**

1. **Finds the dev command** -- reads your `package.json` for the dev script.
2. **Starts the server** -- runs the dev command in the background and detects the port.
3. **Picks a tunnel provider** -- checks for `cloudflared` (preferred, no account needed) or `ngrok`. If neither is installed, provides installation instructions.
4. **Opens the tunnel** -- starts the tunnel and prints both the local and public URLs.

**Output example:**

```
MCP server tunneled:

  Local:  http://localhost:3001
  Public: https://abc123.trycloudflare.com

Use the public URL as your MCP server endpoint.
```

**Best for:** Testing your local MCP server with remote AI clients without deploying.


# Funnels overview
Source: https://docs.waniwani.ai/sdk/guides/funnels

Build sales funnels, lead generation, booking, and quote apps as MCP funnels on top of your MCP server.

An **MCP funnel** is a multi-step conversation, hosted on your MCP server, that drives a user from intent to outcome (a qualified lead, a booking, a quote, a purchase). ChatGPT, Claude, and any other MCP-capable client become the front-end. Your funnel runs as a single MCP tool.

`@waniwani/sdk` is the SDK for building MCP funnels. The engine is open source. The [Waniwani Platform](/sdk/platform/overview) adds funnel analytics, hosted state, knowledge base, and a chat widget on top.

## What you can build

<CardGroup>
  <Card title="Sales funnel MCP" icon="filter" href="/sdk/guides/sales-funnel">
    Qualify intent, capture lead data, route to the right next step.
  </Card>

  <Card title="Lead generation MCP" icon="user-plus" href="/sdk/guides/lead-generation">
    Collect email, role, and use case. Push to your CRM.
  </Card>

  <Card title="Booking MCP" icon="calendar" href="/sdk/guides/booking">
    Pick a service, pick a slot, confirm. Branch on availability.
  </Card>

  <Card title="Insurance quote MCP" icon="shield" href="/sdk/guides/insurance-quote">
    Collect details, validate, return a quote with widget cards.
  </Card>
</CardGroup>

## Funnel vocabulary ↔ flow vocabulary

If you're new to the SDK, the funnel terms map cleanly to the flow engine:

| Funnel term              | Flow term                                        |
| ------------------------ | ------------------------------------------------ |
| Funnel step / page       | Node (`addNode({ id, label, run })`)             |
| Step name (in dashboard) | `label`                                          |
| Drop-off / conversion    | Edge taken vs. abandoned                         |
| Form field               | Interrupt                                        |
| Branching question       | Conditional edge                                 |
| Funnel state (lead data) | Flow state (typed)                               |
| Funnel analytics         | Platform: node visits, completion rate, drop-off |

Everything you'd describe in funnel-speak compiles into a flow. Read [Flows / Overview](/sdk/flows/overview) for the engine.

## Anatomy of an MCP funnel

```ts theme={null}
import { createFlow, START, END } from "@waniwani/sdk/mcp";
import { z } from "zod";

export const funnel = createFlow({
  id: "sales_funnel",
  title: "Sales Funnel",
  description: "Use when a visitor wants to learn more, book a demo, or buy.",
  state: {
    intent: z.enum(["learn", "demo", "buy"]).describe("What the user wants"),
    email: z.string().describe("Work email"),
    company: z.string().describe("Company name"),
  },
})
  .addNode({
    id: "qualify",
    label: "Qualify intent",
    run: ({ interrupt }) =>
      interrupt({
        intent: {
          question: "What brings you here today?",
          suggestions: ["Learn more", "Book a demo", "Buy now"],
        },
      }),
  })
  .addNode({
    id: "capture",
    label: "Capture lead",
    run: ({ interrupt }) =>
      interrupt({
        email: { question: "What's your work email?" },
        company: { question: "Which company?" },
      }),
  })
  .addEdge(START, "qualify")
  .addEdge("qualify", "capture")
  .addEdge("capture", END)
  .compile();
```

Register it on your MCP server and the funnel is live in ChatGPT, Claude, or any MCP client.

## Why MCP for funnels

* **No website, no form, no chatbot widget.** The funnel runs inside the AI client the user already uses.
* **One tool call, many turns.** The engine handles state, validation, branching, and resumption.
* **Funnel analytics out of the box.** Connect the [Waniwani Platform](/sdk/platform/overview) and every node visit becomes a funnel step in the dashboard.

## Next

<CardGroup>
  <Card title="Build a sales funnel MCP" icon="filter" href="/sdk/guides/sales-funnel" />

  <Card title="Build a lead generation MCP" icon="user-plus" href="/sdk/guides/lead-generation" />

  <Card title="Build a booking MCP app" icon="calendar" href="/sdk/guides/booking" />

  <Card title="Build an insurance quote MCP" icon="shield" href="/sdk/guides/insurance-quote" />
</CardGroup>


# Insurance quote
Source: https://docs.waniwani.ai/sdk/guides/insurance-quote

Build an insurance quote MCP: collect pet/vehicle/home details, validate, call your pricing API, return a quote with widget cards.

This page shows you how to **build an insurance quote MCP** with `@waniwani/sdk`. The funnel collects what you need, validates it server-side, calls your pricing API, and shows the user a quote, all as one MCP tool inside ChatGPT, Claude, or any MCP client.

## Production example

The most complete example in the docs is the **[Pet Insurance Quote flow](/sdk/guides/pet-insurance)**. It demonstrates every pattern an insurance quote funnel needs:

* **Open-ended extraction.** One question pulls 5+ fields out of free-form text.
* **Conversational follow-ups.** Ask the rest 1-2 at a time, not as a form.
* **Async validation.** Breed and location validated against your API before quoting.
* **Conditional branching.** Different paths for mixed breeds, indoor cats, etc.
* **Confirmation widget.** Show a summary card, let the user correct anything.
* **Correction loop.** Corrections re-validate and re-display until the user confirms.
* **Pricing widget.** Call the pricing API, render a grid of plan cards.
* **Adjustment loop.** User tweaks deductible/copay, recalculate, re-render.
* **Compliance rules in the description.** Embedded "no recommendation" guardrails.

Open [the Pet Insurance Quote example](/sdk/guides/pet-insurance) for the full \~250-line code.

## Why an MCP funnel beats a quote form

* **The AI asks naturally.** Users say "I have a 2-year-old Golden Retriever named Max, he's neutered" and the flow extracts 5 fields in one turn. A form would ask each separately.
* **No leaving the conversation.** Users get quotes inside ChatGPT or Claude. No tab switch, no friction.
* **Compliance lives in the tool description.** Insurance, finance, and healthcare can encode "no recommendation" rules where the model always reads them.
* **Branching is trivial.** Mixed breed? Indoor cat? Conditional edges, not nested form fields.

## Skeleton for any quote vertical

The pet insurance flow's shape works for **vehicle insurance**, **home insurance**, **business insurance**, and any vertical with the same shape: collect details, validate, quote, adjust.

```ts theme={null}
import { createFlow, START, END } from "@waniwani/sdk/mcp";
import { z } from "zod";

export const quoteFunnel = createFlow({
  id: "vehicle_insurance_quote",
  title: "Vehicle Insurance Quote",
  description: "Use when a user wants a price quote for vehicle insurance.",
  state: {
    // Fields the user provides
    make: z.string().describe("Vehicle make"),
    model: z.string().describe("Vehicle model"),
    year: z.number().describe("Vehicle year"),
    postcode: z.string().describe("Owner postcode"),
    // Resolved by validation
    vehicleId: z.string().describe("Resolved vehicle ID from your DB"),
    // Confirmation state
    confirmed: z.boolean().describe("User confirmed the details"),
    // Quote state
    quoteId: z.string().describe("Quote ID returned by pricing API"),
    deductible: z.number().optional().describe("Chosen deductible"),
    pricingAction: z.enum(["adjust", "done"]).describe("Adjust loop control"),
  },
})
  .addNode({
    id: "ask_vehicle",
    label: "Ask about vehicle",
    run: ({ interrupt }) =>
      interrupt({
        make: {
          question: "Tell me about your vehicle: make, model, year, and your postcode.",
          context: "Extract make, model, year, and postcode from the user's response.",
        },
      }),
  })
  .addNode({
    id: "validate",
    label: "Validate vehicle + postcode",
    hideFromFunnel: true,
    run: async ({ state }) => {
      // your validation API call
      return { vehicleId: "..." };
    },
  })
  .addNode({
    id: "show_confirmation",
    label: "Confirm details",
    run: ({ state, showWidget }) => {
      // see Pet Insurance Quote example for the showWidget pattern
      return showWidget(/* ... */);
    },
  })
  .addNode({
    id: "show_pricing",
    label: "Show pricing",
    run: async ({ state, showWidget }) => {
      // call pricing API, render widget
      return { quoteId: "...", /* ... */ };
    },
  })
  // ... edges and adjustment loop
  .compile();
```

See the [full Pet Insurance Quote code](/sdk/guides/pet-insurance) for working versions of `show_confirmation`, `show_pricing`, the correction loop, and the adjustment loop.

## Add funnel analytics

Set `WANIWANI_API_KEY` to track step-by-step drop-off across your quote funnel: `ask_vehicle → validate → show_confirmation → show_pricing`. The dashboard shows you where users abandon, typically at confirmation or at the price reveal. See [Tracking / Overview](/sdk/tracking/overview).

## Next

<CardGroup>
  <Card title="Pet Insurance Quote (full example)" icon="shield" href="/sdk/guides/pet-insurance" />

  <Card title="Widgets in flows" icon="window-maximize" href="/sdk/guides/pet-insurance" />

  <Card title="Build a booking MCP app" icon="calendar" href="/sdk/guides/booking" />

  <Card title="Build a sales funnel MCP" icon="filter" href="/sdk/guides/sales-funnel" />
</CardGroup>


# Lead generation
Source: https://docs.waniwani.ai/sdk/guides/lead-generation

Build a lead generation MCP funnel: capture email, role, and use case, validate, push to your CRM or webhook.

This page shows you how to **build a lead generation MCP funnel** with `@waniwani/sdk`. Lead gen is the simplest MCP funnel: a few questions, validation, and a handoff. Runs as a single MCP tool inside any MCP client.

## What you'll build

A lead capture flow that:

1. Asks for **work email**, with format validation
2. Asks for **role** and **use case**
3. Looks up the company by email domain (action node, no user prompt)
4. Pushes to your **CRM or webhook**

## Flow graph

```mermaid theme={null}
graph TD
    S((Start)) --> E[ask_email]
    E --> R[ask_role_and_use_case]
    R --> L[lookup_company]
    L --> P[push_lead]
    P --> END((End))
```

## Code

```ts theme={null}
import { createFlow, START, END } from "@waniwani/sdk/mcp";
import { z } from "zod";
import { crm, enrichment } from "./services";

export const leadGenFunnel = createFlow({
  id: "lead_generation",
  title: "Lead Generation",
  description: "Use when a visitor expresses interest and we need to capture them as a lead. Collects email, role, and use case, then pushes to CRM.",
  state: {
    email: z.string().describe("Work email, used to identify the lead"),
    role: z.string().describe("Role at company (e.g. 'PM', 'Engineering Manager')"),
    useCase: z.string().describe("What they want to build or solve"),
    company: z.string().optional().describe("Company name, enriched from email domain"),
    leadId: z.string().optional().describe("CRM lead ID, set after push"),
  },
})
  .addNode({
    id: "ask_email",
    label: "Ask for email",
    run: ({ interrupt }) =>
      interrupt({
        email: {
          question: "What's your work email?",
          validate: (email: string) => {
            if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
              throw new Error("Please share a valid work email.");
            }
          },
        },
      }),
  })
  .addNode({
    id: "ask_role_and_use_case",
    label: "Ask role + use case",
    run: ({ interrupt }) =>
      interrupt({
        role: { question: "What's your role?" },
        useCase: {
          question: "What are you hoping to build?",
          suggestions: [
            "Customer support",
            "Lead capture / sales",
            "Internal tools",
            "Something else",
          ],
        },
      }),
  })
  .addNode({
    id: "lookup_company",
    label: "Enrich from email",
    hideFromFunnel: true,
    run: async ({ state }) => {
      const enriched = await enrichment.lookupByEmail(state.email);
      return { company: enriched?.company };
    },
  })
  .addNode({
    id: "push_lead",
    label: "Push to CRM",
    run: async ({ state, waniwani }) => {
      const lead = await crm.createLead({
        email: state.email,
        role: state.role,
        useCase: state.useCase,
        company: state.company,
      });
      waniwani?.identify(state.email!);
      waniwani?.track.leadQualified({
        externalId: lead.id,
        email: state.email,
        source: "mcp_chat",
      });
      return { leadId: lead.id };
    },
  })
  .addEdge(START, "ask_email")
  .addEdge("ask_email", "ask_role_and_use_case")
  .addEdge("ask_role_and_use_case", "lookup_company")
  .addEdge("lookup_company", "push_lead")
  .addEdge("push_lead", END)
  .compile();
```

## Register

```ts theme={null}
import { withWaniwani } from "@waniwani/sdk/mcp";

await leadGenFunnel.register(server);
withWaniwani(server); // injects the scoped `waniwani` client into node handlers
```

## Why this works as an MCP funnel

* **No form, no friction.** The user is already in ChatGPT or Claude. They never leave.
* **The AI asks the questions in plain language.** Better completion rate than a form.
* **Validation runs server-side.** If the email is malformed, the engine re-asks automatically.
* **Enrichment happens silently.** `lookup_company` is an action node, no user interaction.

## Add funnel analytics

Set `WANIWANI_API_KEY` and every step is tracked. The funnel view shows three steps: **Ask for email → Ask role + use case → Push to CRM** (the labels are taken from each node's `label` field). `lookup_company` uses `hideFromFunnel: true` because enrichment is plumbing, not a step the user can drop off at. See [Tracking / Overview](/sdk/tracking/overview).

The `push_lead` node is also where the qualified-lead event fires: the person answered every qualifying question and now exists in your CRM, so `track.leadQualified()` carries the CRM record id as `externalId` (the dedup key) alongside the email. The `identify()` call right before it attaches the email to the session, so a `converted` event sent later from your backend with the same `externalUserId` joins back to this lead. Placement rules for every funnel event are in [Instrumentation](/sdk/tracking/instrumentation).

## Next

<CardGroup>
  <Card title="Build a sales funnel MCP" icon="filter" href="/sdk/guides/sales-funnel" />

  <Card title="Build a booking MCP app" icon="calendar" href="/sdk/guides/booking" />

  <Card title="Validation in interrupts" icon="check-double" href="/sdk/flows/interrupts" />

  <Card title="Push events to your stack" icon="webhook" href="/sdk/tracking/events" />
</CardGroup>


# Pet insurance (real example)
Source: https://docs.waniwani.ai/sdk/guides/pet-insurance

Walk-through of a real production pet insurance quoting flow we built for a Waniwani customer. Showcases open-ended questions, validation, conditional branching, widgets, and correction loops.

This is a real flow shipped in production by a Waniwani customer — a pet insurance distributor selling policies through their own MCP. It's the kind of build we open-sourced Waniwani for: a multi-step quote conversation that has to feel natural, validate input strictly, branch on edge cases (mixed-breed dogs), and let the user correct themselves without restarting.

We're showing it here, simplified and anonymized, because every pattern in it is one we hit repeatedly across customer projects — and the shape of the answer is what `createFlow` was designed around.

<Note>
  API calls use a fictional `petApi` and the pricing logic is anonymized. The graph shape, validation patterns, widget hand-off, and correction loop are exactly as deployed.
</Note>

## Flow graph

```mermaid theme={null}
graph TD
    S((Start)) --> A[ask_about_pet]
    A --> B[ask_remaining_details]
    B -->|mixed breed dog| MB[ask_mixed_breed_breeds]
    B -->|otherwise| V[validate_details]
    MB --> V
    V --> C[show_confirmation]
    C -->|confirmed| P[show_pricing]
    C -->|correction| F[fix_details]
    F --> V
    P --> R[recalculate_pricing]
    R --> P
```

## Patterns demonstrated

<CardGroup>
  <Card title="Open-ended questions" icon="comments">
    One natural question extracts multiple state fields at once.
  </Card>

  <Card title="Conversational follow-ups" icon="message">
    Asks remaining questions 1-2 at a time with warm, contextual reactions.
  </Card>

  <Card title="Rich system prompt" icon="scroll">
    Compliance rules and tone guidance embedded in the tool description.
  </Card>

  <Card title="Conditional branching" icon="code-branch">
    Different paths based on animal type and breed composition.
  </Card>

  <Card title="Async validation" icon="check-double">
    Server-side breed and location validation between questions and confirmation.
  </Card>

  <Card title="Widget display" icon="window-maximize">
    Confirmation card and pricing cards rendered via display tools.
  </Card>

  <Card title="Correction loop" icon="rotate-left">
    User fixes details → re-validate → re-display until confirmed.
  </Card>

  <Card title="Pricing adjustment loop" icon="sliders">
    User tweaks deductible/copay → recalculate → show updated prices.
  </Card>
</CardGroup>

## Full flow

```ts theme={null}
import { createFlow, END, START } from "@waniwani/sdk/mcp";
import { z } from "zod";
import { petApi } from "./api";
import { showPetSummaryTool, showPricingTool } from "./display-tools";

export const quoteFlow = createFlow({
  id: "pet_insurance_quote",
  title: "Pet Insurance Quote",
  description: `Get a pet insurance quote. Use when a user wants to insure their dog or cat, get a price quote, or learn about available insurance packages.

NO-RECOMMENDATION RULE (CRITICAL - applies to the ENTIRE conversation):
- NEVER recommend, suggest, or steer the user toward any specific plan, not even implicitly.
- NEVER use social proof ("most people choose…") or comparative framing ("best protection…").
- When asked "what do you recommend?", warmly decline: explain you can only provide factual information, and invite them to ask about coverage details so they can decide themselves.
- When comparing plans, present ONLY factual differences (price, limits, what's included).

TONE - conversational, not a form:
- You are a warm, knowledgeable assistant, like a friend who happens to know everything about pet insurance.
- React to what the user shares with genuine interest (e.g., "Goldens are such great dogs!")
- Use the pet's name once you know it.
- Keep text short. Use widgets for structured information.
- Explain difficult concepts simply, avoid insurance jargon.

DO: Talk like a friend. React genuinely. Be frank and truthful.
DON'T: Sound sales-y. Be judgmental. Use walls of text. Be robotic.`,
  state: {
    animalType: z
      .enum(["dog", "cat"])
      .describe(
        "Type of animal. Infer from the breed when obvious (e.g. Golden Retriever → dog, Persian → cat).",
      ),
    petName: z.string().describe("The pet's name"),
    breed: z
      .string()
      .describe(
        "The pet's breed as stated by the user. Fix obvious spelling mistakes (e.g. 'Retriver' → 'Retriever'). Leave empty when isMixedBreed is true.",
      ),
    breedId: z
      .string()
      .describe("Resolved breed ID from the API (set by validation, not the user)"),
    isMixedBreed: z
      .boolean()
      .optional()
      .describe(
        "Whether the pet is a mixed breed. Set to true when user mentions a mix, crossbreed, or multiple breeds. When setting to true, MUST also set mixedBreed to {} in the same stateUpdates.",
      ),
    mixedBreed: z
      .object({
        knowsBreeds: z
          .boolean()
          .describe("true if user named at least one breed, false if they don't know"),
        breed1: z.string().optional().describe("First breed in the mix"),
        breed1Id: z.string().optional().describe("First breed API ID (set by system)"),
        breed2: z.string().optional().describe("Second breed in the mix (optional)"),
        breed2Id: z.string().optional().describe("Second breed API ID (set by system)"),
      })
      .optional()
      .describe(
        "MUST be set whenever isMixedBreed is true. If user named breeds: { knowsBreeds: true, breed1: '...', breed2: '...' }. If user just said 'mixed' without naming breeds: { knowsBreeds: false }.",
      ),
    gender: z
      .enum(["male", "female"])
      .describe(
        "The pet's gender. Infer from pronouns: he/him/his → male, she/her → female. Also accept boy/girl.",
      ),
    isNeutered: z.boolean().describe("Whether the pet is neutered/spayed"),
    birthDate: z
      .string()
      .describe(
        "Birth date in YYYY-MM-DD format. Accept any format from the user ('2 years old', 'March 2023', etc.) and convert yourself. Never ask the user to reformat.",
      ),
    indoorOutdoor: z
      .enum(["indoor", "outdoor"])
      .optional()
      .describe("Whether the cat is indoor or outdoor (cats only, skip for dogs)"),
    municipality: z.string().describe("City or municipality where the owner lives"),
    isCurrentlyInsured: z
      .enum(["yes", "no"])
      .describe("Whether the pet is currently insured with another provider"),
    confirmed: z.boolean().describe("Whether the user confirmed their pet details"),
    quoteId: z.string().describe("Quote ID returned by the pricing API"),
    deductible: z
      .number()
      .optional()
      .describe("Fixed deductible amount. Default: 500. Options: 0, 250, 500, 750."),
    copay: z
      .number()
      .optional()
      .describe(
        "Copay percentage as decimal. Default: 0.20. Options: 0.15 (15%), 0.20 (20%), 0.25 (25%).",
      ),
    pricingAction: z
      .enum(["adjust", "done"])
      .describe(
        "Set to 'adjust' when user wants to change deductible/copay. Set to 'done' when satisfied.",
      ),
  },
})

  // ─── Node 1: Open-ended question ─────────────────────────────────────
  // One natural question → extract as many fields as possible from free-form text
  .addNode({
    id: "ask_about_pet",
    run: ({ interrupt }) => {
      return interrupt({
        petName: {
          question: "Tell me about your pet!",
          context: `Warmly greet the user and ask an OPEN-ENDED question. Something like:
"I'd love to help you explore insurance options! Tell me a bit about your pet - what kind of animal, their name, breed, age… anything you'd like to share :)"

Do NOT list specific questions. Let the user share naturally.

From their response, extract as many fields as possible into stateUpdates:
- animalType: infer from breed when obvious
- petName, breed, gender (from pronouns), isNeutered, birthDate (any format → YYYY-MM-DD)
- isCurrentlyInsured, municipality
- isMixedBreed + mixedBreed if they mention a mix

Only extract what is clearly stated. Do NOT guess missing fields.`,
        },
      });
    },
  })

  // ─── Node 2: Conversational follow-ups ───────────────────────────────
  // Only ask what's still missing, 1-2 questions at a time
  .addNode({
    id: "ask_remaining_details",
    run: async ({ state, interrupt }) => {
    const breedList = await petApi.getBreedList(state.animalType);

    const sharedContext = `You're having a natural conversation, NOT filling out a form. Ask remaining questions ONE OR TWO at a time, weaving them in naturally. React to what the user shared previously with genuine interest before asking the next thing.

Good follow-ups:
- "Love that name! And what breed is ${state.petName}?"
- "A Golden Retriever, great choice! Is ${state.petName} a boy or a girl?"
- "Got it! And roughly how old is ${state.petName}?"

${breedList ? `Valid breed names: ${breedList}. Match the user's input to the closest name from this list.` : ""}

IMPORTANT: Do NOT ask all remaining questions at once. Keep it conversational.
FORMATTING: Write in flowing prose, not bullet points.`;

    return interrupt(
      {
        ...(!state.animalType
          ? { animalType: { question: "Is it a dog or a cat?" } }
          : {}),
        ...(!state.petName
          ? { petName: { question: "What's your pet's name?" } }
          : {}),
        ...(!state.breed && !state.isMixedBreed
          ? {
              breed: {
                question: "What breed?",
                context: breedList
                  ? `Valid breeds: ${breedList}. Match the user's input to the closest official name.`
                  : undefined,
                validate: state.animalType
                  ? async (breed: string) => {
                      return petApi.validateBreed(state.animalType!, breed);
                    }
                  : undefined,
              },
            }
          : {}),
        ...(!state.gender ? { gender: { question: "Male or female?" } } : {}),
        ...(state.isNeutered == null
          ? { isNeutered: { question: "Neutered/spayed?" } }
          : {}),
        ...(!state.birthDate
          ? { birthDate: { question: "When was your pet born?" } }
          : {}),
        ...(!state.isCurrentlyInsured
          ? { isCurrentlyInsured: { question: "Currently insured?" } }
          : {}),
        ...(!state.municipality
          ? { municipality: { question: "What city do you live in?" } }
          : {}),
        ...(state.animalType === "cat" && !state.indoorOutdoor
          ? { indoorOutdoor: { question: "Indoor or outdoor cat?" } }
          : {}),
      },
      { context: sharedContext },
    );
    },
  })

  // ─── Node 3: Mixed breed - collect breed names ───────────────────────
  .addNode({
    id: "ask_mixed_breed_breeds",
    run: async ({ state, interrupt }) => {
      if (!state.isMixedBreed || state.mixedBreed?.breed1) return {};

      const breedList = await petApi.getBreedList(state.animalType);

      return interrupt({
        "mixedBreed.breed1": {
          question: "Which breeds is your dog a mix of?",
          context: `Ask naturally: "Which breeds is ${state.petName} a mix of?" They must provide at least one, the second is optional.${breedList ? `\n\nValid breeds: ${breedList}. Match each to the closest official name.` : ""}`,
          validate: async (breed1) => {
            if (!breed1) return;
            return petApi.validateMixedBreed(state.animalType!, {
              ...state.mixedBreed,
              breed1,
            });
          },
        },
      });
    },
  })

  // ─── Node 4: Validate breed + location against API ───────────────────
  .addNode({
    id: "validate_details",
    run: async ({ state }) => {
      const [breedResult, locationResult] = await Promise.all([
        state.isMixedBreed && state.mixedBreed
          ? petApi.validateMixedBreed(state.animalType!, state.mixedBreed)
          : petApi.validateBreed(state.animalType!, state.breed!),
        petApi.validateLocation(state.municipality!),
      ]);

      return { ...breedResult, ...locationResult };
    },
  })

  // ─── Node 5: Show confirmation widget ────────────────────────────────
  .addNode({
    id: "show_confirmation",
    run: ({ state, showWidget }) => {
      const mb = state.mixedBreed;
      let displayBreed = state.breed ?? "";
      if (mb) {
        const parts = [mb.breed1, mb.breed2].filter(Boolean);
        displayBreed = parts.length > 0 ? `${parts.join(" & ")} Mix` : "Mixed breed";
      }

      return showWidget({
        tool: "show_pet_summary",
        field: "confirmed",
        data: {
          animalType: state.animalType,
          petName: state.petName,
          breed: displayBreed,
          gender: state.gender,
          isNeutered: state.isNeutered,
          birthDate: state.birthDate,
          indoorOutdoor: state.indoorOutdoor,
          municipality: state.municipality,
        },
      });
    },
  })

  // ─── Node 5b: Reset confirmed for correction loop ───────────────────
  .addNode({
    id: "fix_details",
    run: () => ({ confirmed: undefined }),
  })

  // ─── Node 6: Show pricing widget ────────────────────────────────────
  .addNode({
    id: "show_pricing",
    run: async ({ state, showWidget }) => {
      const currentDeductible = state.deductible ?? 500;
      const currentCopay = state.copay ?? 0.2;

      const quote = await petApi.getQuote({
        animalType: state.animalType!,
        breedId: state.breedId!,
        birthDate: state.birthDate!,
        gender: state.gender!,
        neutered: !!state.isNeutered,
        municipality: state.municipality!,
        deductible: currentDeductible,
        copay: currentCopay,
      });

      return {
        quoteId: quote.id,
        ...showWidget({
          tool: "show_pricing",
          data: {
            petName: state.petName,
            quoteId: quote.id,
            plans: quote.plans,
          },
        }),
      };
    },
  })

  // ─── Node 6b: Reset pricingAction for adjustment loop ───────────────
  .addNode({
    id: "recalculate_pricing",
    run: () => ({ pricingAction: undefined as unknown as "adjust" | "done" }),
  })

  // ─── Edges ──────────────────────────────────────────────────────────
  .addEdge(START, "ask_about_pet")
  .addEdge("ask_about_pet", "ask_remaining_details")
  .addConditionalEdge("ask_remaining_details", (state) => {
    if (state.animalType === "dog" && state.isMixedBreed)
      return "ask_mixed_breed_breeds";
    return "validate_details";
  })
  .addEdge("ask_mixed_breed_breeds", "validate_details")
  .addEdge("validate_details", "show_confirmation")
  .addConditionalEdge("show_confirmation", (state) =>
    state.confirmed ? "show_pricing" : "fix_details",
  )
  .addEdge("fix_details", "validate_details")
  .addEdge("show_pricing", "recalculate_pricing")
  .addEdge("recalculate_pricing", "show_pricing")
  .compile();
```

## Register the widget display tools

`showWidget({ tool: "show_pet_summary", ... })` and `showWidget({ tool: "show_pricing", ... })` in the flow refer to widget names the model will call to render each card. Register them with [Skybridge's](https://docs.skybridge.tech) `registerWidget` — it binds the named widget to the matching React component under `web/src/widgets/` and handles all of the OpenAI/Claude render plumbing for you:

```ts server/src/app.ts theme={null}
import { McpServer } from "skybridge/server";
import { withWaniwani } from "@waniwani/sdk/mcp";
import { z } from "zod";
import { quoteFlow } from "./flows/quote.js";

export const server = new McpServer(
  { name: "pet-insurance-mcp", version: "0.0.1" },
  { capabilities: {} },
)
  .registerWidget(
    "show_pet_summary",
    {
      description:
        "You MUST call this tool to display the pet summary card. Do NOT repeat the pet details in text.",
    },
    {
      inputSchema: {
        animalType: z.enum(["dog", "cat"]),
        petName: z.string(),
        breed: z.string(),
        gender: z.enum(["male", "female"]),
        isNeutered: z.boolean(),
        birthDate: z.string(),
        indoorOutdoor: z.enum(["indoor", "outdoor"]).optional(),
        municipality: z.string(),
      },
      annotations: { readOnlyHint: true, openWorldHint: false },
    },
    async (input) => ({
      structuredContent: input,
      content: [{ type: "text", text: `Pet summary for ${input.petName}` }],
      isError: false,
    }),
  )
  .registerWidget(
    "show_pricing",
    {
      description:
        "You MUST call this tool to display the pricing plan grid. The widget renders every plan — do NOT list them in text.",
    },
    {
      inputSchema: {
        petName: z.string(),
        quoteId: z.string(),
        plans: z.array(
          z.object({
            name: z.string(),
            monthlyPrice: z.number(),
            coverageLimit: z.number(),
            deductible: z.number(),
            copay: z.number(),
            highlights: z.array(z.string()),
          }),
        ),
      },
      annotations: { readOnlyHint: true, openWorldHint: false },
    },
    async (input) => ({
      structuredContent: input,
      content: [{ type: "text", text: `Pricing for ${input.petName}` }],
      isError: false,
    }),
  )
  .registerTool(quoteFlow.name, quoteFlow.config, quoteFlow.handler);

withWaniwani(server);
```

The widget itself lives at `web/src/widgets/show_pet_summary.tsx` (and `show_pricing.tsx`) and mounts via `mountWidget` from `skybridge/web`. The widget name passed to `registerWidget` matches the file name — that's how Skybridge wires the binding, so you never deal with `_meta.openai/outputTemplate` URIs by hand.

<Note>
  Skybridge ships in the [MCP distribution template](https://github.com/WaniWani-AI/mcp-distribution-template) as the default dev/build runtime. If you're starting from that template (`bun dev` runs `skybridge dev`), `registerWidget` is already available on the server you instantiate. See the [Skybridge docs](https://docs.skybridge.tech) for the full widget mounting API.
</Note>

## Key patterns explained

<AccordionGroup>
  <Accordion title="Why the system prompt lives in description">
    The `description` field of a flow becomes the MCP tool's description. It's the first thing the model reads when deciding how to use the tool. By embedding compliance rules and tone guidance here, you ensure **every single interaction** follows your guidelines without relying on external system prompts you don't control.

    This is especially powerful for regulated industries (insurance, finance, healthcare) where the AI must never give recommendations or advice.
  </Accordion>

  <Accordion title="How open-ended extraction works">
    The `ask_about_pet` node asks one broad question but declares `petName` as its interrupt field. The `context` instructs the model to extract **all** recognizable fields from the user's free-form response into `stateUpdates`.

    This creates the feeling of a natural conversation: the user says "I have a 2-year-old Golden Retriever named Max, he's neutered" and the flow captures 5+ fields in one turn. The next node then only asks what's still missing.
  </Accordion>

  <Accordion title="The correction loop pattern">
    After `show_confirmation` displays the summary widget:

    * If the user says "looks good" → `confirmed = true` → proceed to pricing
    * If the user says "actually his name is Max, not Mac" → `confirmed = false` + correction in stateUpdates → `fix_details` resets confirmed → `validate_details` re-runs → `show_confirmation` re-displays with corrected data

    This loop continues until the user explicitly confirms. The flow never proceeds with incorrect data.
  </Accordion>

  <Accordion title="The pricing adjustment loop">
    After showing pricing plans, the user might say "can I see prices with a lower deductible?" The model sets the new deductible value and `pricingAction: "adjust"`. The `recalculate_pricing` node resets `pricingAction` to `undefined`, which loops back to `show_pricing`, which calls the API with the new parameters and re-renders the widget.

    This pattern works for any "configure → preview → adjust" cycle.
  </Accordion>

  <Accordion title="How flows call widgets (the showWidget handoff)">
    Flows don't render widgets directly. Instead, `showWidget` creates a special interrupt that **instructs the LLM to call a separate display tool**. Here's the sequence:

    1. The flow node calls `showWidget({ tool: "show_pricing", data })` and pauses.
    2. The flow engine returns an interrupt to the LLM with a standardized instruction to call the named display tool.
    3. The LLM writes a short intro message, then calls the display tool.
    4. The display tool renders the widget in the chat UI.
    5. After the user interacts with the widget, the LLM continues the flow with updated state.

    The `field` parameter tells the flow which state field the widget interaction resolves (e.g., `confirmed`). The `data` is passed directly to the widget component for rendering. Any per-widget AI guidance (conversational framing, compliance notes, etc.) belongs in the display tool's own response, not in `showWidget`.

    ```ts theme={null}
    // The flow pauses here and tells the LLM to call show_pet_summary
    return showWidget({
      tool: "show_pet_summary",
      field: "confirmed",  // Which state field this resolves
      data: { petName, breed, ... },  // Passed to the widget
    });
    ```

    This separation means the flow controls **when** and **with what data** a widget appears, while the LLM controls the **conversational framing** around it.
  </Accordion>

  <Accordion title="Validate callbacks for real-time enrichment">
    The `breed` interrupt field in `ask_remaining_details` has a `validate` callback:

    ```ts theme={null}
    validate: async (breed: string) => {
      return petApi.validateBreed(state.animalType!, breed);
    }
    ```

    This runs server-side when the model provides a breed name. If the breed doesn't exist in the database, the validation throws an error with suggestions and the flow automatically re-asks the user. If it succeeds, it can return state updates (like `breedId`) that enrich the state without an extra round-trip.
  </Accordion>
</AccordionGroup>


# Sales funnel
Source: https://docs.waniwani.ai/sdk/guides/sales-funnel

Build a sales funnel MCP app: qualify intent, capture lead data, branch by stage, push to your CRM.

This page shows you how to **build a sales funnel MCP app** with `@waniwani/sdk`. The funnel runs as a single MCP tool inside ChatGPT, Claude, or any MCP client. The engine handles state and branching server-side.

## What you'll build

A sales funnel that:

1. **Qualifies intent**: learn, evaluate, or buy
2. **Captures lead info**: email, company, role, team size
3. **Branches by stage**: different next steps for "evaluating" vs. "ready to buy"
4. **Hands off to your CRM**: call your API in the last action node

## Flow graph

```mermaid theme={null}
graph TD
    S((Start)) --> Q[qualify_intent]
    Q -->|learn| L[capture_email_only]
    Q -->|evaluate| E[capture_company_role]
    Q -->|buy| B[capture_full_lead]
    L --> P[push_to_crm]
    E --> P
    B --> P
    P --> END((End))
```

## Code

```ts theme={null}
import { createFlow, START, END } from "@waniwani/sdk/mcp";
import { z } from "zod";
import { crm } from "./crm";

export const salesFunnel = createFlow({
  id: "sales_funnel",
  title: "Sales Funnel",
  description: `Use when a visitor wants to learn more about the product, evaluate it for their team, or buy. Qualify intent first, then capture the right lead information for the stage.`,
  state: {
    intent: z.enum(["learn", "evaluate", "buy"]).describe("Stage of buyer journey"),
    email: z.string().describe("Work email"),
    company: z.string().optional().describe("Company name"),
    role: z.string().optional().describe("Role at company"),
    teamSize: z.string().optional().describe("Team size (e.g. '1-10', '11-50', '50+')"),
    leadId: z.string().optional().describe("CRM lead ID (set after push)"),
  },
})
  .addNode({
    id: "qualify_intent",
    label: "Qualify intent",
    run: ({ interrupt }) =>
      interrupt({
        intent: {
          question: "What brings you here today?",
          suggestions: [
            "Just learning about the product",
            "Evaluating for my team",
            "Ready to buy",
          ],
        },
      }),
  })
  .addNode({
    id: "capture_email_only",
    label: "Capture email",
    run: ({ interrupt }) =>
      interrupt({ email: { question: "What's your work email?" } }),
  })
  .addNode({
    id: "capture_company_role",
    label: "Capture company + role",
    run: ({ interrupt }) =>
      interrupt({
        email: { question: "Work email?" },
        company: { question: "Which company?" },
        role: { question: "What's your role?" },
      }),
  })
  .addNode({
    id: "capture_full_lead",
    label: "Capture full lead",
    run: ({ interrupt }) =>
      interrupt({
        email: { question: "Work email?" },
        company: { question: "Which company?" },
        role: { question: "What's your role?" },
        teamSize: { question: "How big is your team?" },
      }),
  })
  .addNode({
    id: "push_to_crm",
    label: "Push to CRM",
    run: async ({ state }) => {
      const lead = await crm.createLead({
        email: state.email,
        company: state.company,
        role: state.role,
        teamSize: state.teamSize,
        stage: state.intent,
      });
      return { leadId: lead.id };
    },
  })
  .addEdge(START, "qualify_intent")
  .addConditionalEdge("qualify_intent", (state) => {
    if (state.intent === "learn") return "capture_email_only";
    if (state.intent === "evaluate") return "capture_company_role";
    return "capture_full_lead";
  })
  .addEdge("capture_email_only", "push_to_crm")
  .addEdge("capture_company_role", "push_to_crm")
  .addEdge("capture_full_lead", "push_to_crm")
  .addEdge("push_to_crm", END)
  .compile();
```

## Register on your MCP server

```ts theme={null}
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { salesFunnel } from "./flows/sales-funnel";

const server = new McpServer({ name: "my-mcp", version: "0.0.1" });
await salesFunnel.register(server);
```

That's it. The funnel is now a tool the AI client can call. The engine runs the graph, pauses on interrupts, branches by intent, and calls your CRM in `push_to_crm`.

## Patterns this uses

* **Conditional edges.** Different paths by `intent`. See [Flows / Edges](/sdk/flows/edges).
* **Multi-field interrupts.** Capture several fields per turn. See [Flows / Interrupts](/sdk/flows/interrupts).
* **Action nodes.** `push_to_crm` runs without user interaction. See [Flows / Nodes](/sdk/flows/nodes).

## Add funnel analytics

Set `WANIWANI_API_KEY` and every node visit is tracked. The dashboard shows step-by-step drop-off across `qualify_intent → capture_* → push_to_crm`. See [Tracking / Overview](/sdk/tracking/overview).

## Next

<CardGroup>
  <Card title="Build a lead generation MCP" icon="user-plus" href="/sdk/guides/lead-generation" />

  <Card title="Build a booking MCP app" icon="calendar" href="/sdk/guides/booking" />

  <Card title="Build an insurance quote MCP" icon="shield" href="/sdk/guides/insurance-quote" />

  <Card title="Flows reference" icon="diagram-project" href="/sdk/flows/overview" />
</CardGroup>


# Agent Skills
Source: https://docs.waniwani.ai/sdk/guides/skills

Install the Waniwani SDK skill for Claude Code, Cursor, and other AI agents.

The Waniwani SDK is available as an [agent skill](https://agentskills.io) for Claude Code, Cursor, GitHub Copilot, and 20+ other AI coding agents. Once installed, your agent knows how to integrate the SDK without you having to explain the API.

<Columns>
  <Card title="Waniwani SDK" icon="code" href="#waniwani-sdk">
    Tracking, flows, widgets, knowledge base, and chat components.
  </Card>

  <Card title="Instrument tracking" icon="wand-magic-sparkles" href="#instrument-tracking">
    Auto-insert funnel events across your flows.
  </Card>

  <Card title="Audit tracking" icon="magnifying-glass-chart" href="#audit-tracking">
    Verify events are valid and find missing funnel events.
  </Card>

  <Card title="OpenAI Submission" icon="file-check" href="#openai-app-submission">
    Generate Tool Justification and Test Cases for the ChatGPT Plugin Store.
  </Card>
</Columns>

## Waniwani SDK

### Install

<CodeGroup>
  ```bash npx theme={null}
  npx skills add Waniwani-AI/sdk -s waniwani-sdk
  ```

  ```bash bunx theme={null}
  bunx skills add Waniwani-AI/sdk -s waniwani-sdk
  ```
</CodeGroup>

The skill is installed into your project's `.claude/skills/` directory (or equivalent for other agents).

### What's included

The skill teaches your agent how to:

* **Set up the SDK** -- install, configure env vars, create a client singleton
* **Track events** -- `withWaniwani` auto-tracking, custom events, sessions
* **Build flows** -- multi-step conversational state machines with interrupts, validation, conditional edges
* **Create tools with widgets** -- register a tool and its widget resource on the MCP server, and track from inside the widget with `useWaniwani`
* **Add a knowledge base** -- ingest markdown, search with embeddings, build FAQ tools
* **Embed chat** -- React component and script-tag embed with theming

### Usage

After installing, just describe what you want in natural language. Your agent will use the skill automatically:

* *"Add Waniwani tracking to my MCP server"*
* *"Create a multi-step onboarding flow"*
* *"Add a knowledge base FAQ tool"*
* *"Embed a chat widget on my landing page"*

## Instrument tracking

Applies the [placement rules](/sdk/tracking/instrumentation) to your codebase: inventories your flows, maps every node to the event taxonomy, and inserts guarded tracking calls with metadata read from your flow state.

<CodeGroup>
  ```bash npx theme={null}
  npx skills add Waniwani-AI/sdk -s instrument-tracking
  ```

  ```bash bunx theme={null}
  bunx skills add Waniwani-AI/sdk -s instrument-tracking
  ```
</CodeGroup>

Then ask your agent:

* *"Instrument tracking across my flows"*
* *"Track qualified leads in my demo flow"*

## Audit tracking

The read-only counterpart to instrument-tracking. It fetches the latest [event definitions](/sdk/tracking/events) from these docs, inventories every tracking call across your server, flows, widgets, and chat embed, verifies that only events from the defined taxonomy are sent, and reports missing funnel events with a suggested payload for each. Run it before instrumenting, or as a periodic health check.

<CodeGroup>
  ```bash npx theme={null}
  npx skills add Waniwani-AI/sdk -s audit-tracking
  ```

  ```bash bunx theme={null}
  bunx skills add Waniwani-AI/sdk -s audit-tracking
  ```
</CodeGroup>

Then ask your agent:

* *"Audit the tracking in this MCP"*
* *"Are we sending any events that aren't defined?"*
* *"Which funnel events are we missing?"*

It reports violations (undefined or manually sent auto-events), risks (unguarded calls, wrong import entry), a per-flow coverage map, and the missing events. It never edits code; pair it with instrument-tracking to apply the fixes.

## OpenAI App Submission

When submitting your MCP server to the ChatGPT Plugin Store, you need to provide Tool Justification and Test Cases documents. The Waniwani dashboard handles this for you: go to your project's submission page and use the built-in Codex assistant to generate a `chatgpt-app-submission.json` file, then upload it to auto-fill the form.

The generated file includes:

1. **Tool Justification** -- annotations (Read Only, Open World, Destructive) with justifications for every tool
2. **Test Cases** -- positive and negative test scenarios for OpenAI reviewers

## Learn more

* [skills.sh](https://skills.sh) -- Browse and discover agent skills
* [agentskills.io](https://agentskills.io) -- The open Agent Skills specification


# Tunnel
Source: https://docs.waniwani.ai/sdk/guides/tunnel

Expose your local MCP server to ChatGPT, Claude, and other remote clients.

MCP clients like ChatGPT and Claude need a public URL to reach your server. A tunnel forwards traffic from a public URL to your local dev server -- no deployment required.

<Note>
  If you started from the [MCP Distribution Template](https://github.com/WaniWani-AI/mcp-distribution-template), `bun dev` already spawns a Cloudflare tunnel and prints the public URL. You don't need this guide. Continue only if you're running a custom dev server.
</Note>

## 1. Start your dev server

```bash theme={null}
bun run dev
# or: npm run dev, node dist/index.js, etc.
```

Note the port your server is listening on (usually `3000`, `8080`, or `8787`). Check your server logs or `package.json` for the exact port.

## 2. Start a tunnel

<Tabs>
  <Tab title="cloudflared (recommended)">
    [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) requires no account for quick tunnels.

    **Install:**

    <CodeGroup>
      ```bash macOS theme={null}
      brew install cloudflared
      ```

      ```bash Linux theme={null}
      curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg > /dev/null
      echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main' | sudo tee /etc/apt/sources.list.d/cloudflared.list
      sudo apt update && sudo apt install cloudflared
      ```
    </CodeGroup>

    **Run:**

    ```bash theme={null}
    cloudflared tunnel --url http://localhost:3000
    ```

    Cloudflared prints a public URL like `https://<random>.trycloudflare.com`. Use that as your MCP server endpoint.
  </Tab>

  <Tab title="ngrok">
    [ngrok](https://ngrok.com) requires a free account and auth token.

    **Install:**

    <CodeGroup>
      ```bash macOS theme={null}
      brew install ngrok
      ```

      ```bash Linux theme={null}
      snap install ngrok
      ```
    </CodeGroup>

    **Authenticate (once):**

    ```bash theme={null}
    ngrok config add-authtoken <your-token>
    ```

    **Run:**

    ```bash theme={null}
    ngrok http 3000
    ```

    ngrok prints a public URL like `https://<random>.ngrok-free.app`.
  </Tab>
</Tabs>

## 3. Use the tunnel URL

Replace `localhost` with the tunnel URL in your MCP client config:

```json theme={null}
{
  "mcpServers": {
    "my-server": {
      "url": "https://<tunnel-url>/mcp"
    }
  }
}
```

Both the dev server and the tunnel must stay running. If either stops, the public URL stops working.

## Using the agent skill

If you have the [Waniwani SDK agent skill](/sdk/guides/skills) installed, you can run the `/waniwani-sdk tunnel` command and your AI agent will handle the entire setup for you -- detecting the dev server port, picking an available tunnel provider, and printing the public URL. See [Commands](/sdk/guides/commands#tunnel) for details.

## Good to know

* **Quick tunnels generate a new URL each time.** For a stable URL, set up a [named Cloudflare tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel/) or use an ngrok paid plan.
* **stdio transport does not need a tunnel.** Tunnels are only needed for HTTP-based transports (Streamable HTTP, SSE).
* **ngrok free tier** has rate limits and session expiry (typically 2 hours).


# Introduction
Source: https://docs.waniwani.ai/sdk/introduction

Open-source SDK for MCP funnels. Build sales funnels, lead generation, booking, and quote flows on top of your MCP server.

`@waniwani/sdk` lets you build multi-step conversational funnels on top of any MCP server. A single MCP tool drives the conversation: it asks the next question, validates the answer, branches on state, and persists progress across calls. ChatGPT, Claude, and any other MCP-capable client become the front-end.

## What people build with it

<CardGroup>
  <Card title="Sales funnels" icon="filter" href="/sdk/guides/sales-funnel">
    Qualify intent, capture lead data, route to the right next step.
  </Card>

  <Card title="Lead generation" icon="user-plus" href="/sdk/guides/lead-generation">
    Collect email, role, and use case. Push to your CRM.
  </Card>

  <Card title="Booking flows" icon="calendar" href="/sdk/guides/booking">
    Pick a service, pick a slot, confirm. Branch on availability.
  </Card>

  <Card title="Insurance and pricing quotes" icon="shield" href="/sdk/guides/insurance-quote">
    Collect details, validate, return a quote with widget cards.
  </Card>
</CardGroup>

## How it works

You declare a flow as a typed state graph. The graph compiles to one MCP tool that the model can call. The engine runs the graph, pauses to ask questions, branches on state, and resumes on the next tool call. Nothing in the model has to carry state between turns.

The flow engine is open source. Set `WANIWANI_API_KEY` to connect the [Waniwani Platform](/sdk/platform/overview), which adds hosted state, tracking, funnel analytics, knowledge base, and a chat widget on top.

The SDK is a library: you supply the `McpServer`, the transport and the build. If you would rather own none of that and write only tools, widgets and flows into a folder, start with the [Kit](/kit/introduction), which depends on the SDK and registers your flows unchanged.

## Next

Head to the [Quickstart](/sdk/quickstart) to get a flow running in under 5 minutes, or jump straight into [building a funnel](/sdk/guides/funnels).


# Knowledge Base
Source: https://docs.waniwani.ai/sdk/knowledge-base/overview

Ingest markdown files and search with embeddings.

<Note>
  **Platform feature.** Requires `WANIWANI_API_KEY`. Works whether your MCP server is self-hosted or on Managed Hosting. [About the Platform](/sdk/platform/overview).
</Note>

The SDK includes a knowledge base client for semantic search. Ingest markdown files, then search from any tool handler.

## Setup

The KB client is available on the Waniwani client instance:

```ts theme={null}
import { waniwani } from "@waniwani/sdk";

const wani = waniwani(); // reads WANIWANI_API_KEY from env
```

## Ingest files

Load markdown content into your knowledge base. Ingestion is **destructive** and replaces all existing chunks.

```ts theme={null}
await wani.kb.ingest([
  {
    filename: "pricing.md",
    content: "# Pricing\n\nOur plans start at $9/month...",
    metadata: { category: "billing" },
  },
  {
    filename: "returns.md",
    content: "# Return Policy\n\n30-day return window...",
    metadata: { category: "support" },
  },
]);
```

The managed project template includes a ready-made `embed` script:

```bash theme={null}
bun embed
```

### Ingest script for self-hosted projects

If you're running your own MCP server, create a simple script to read your docs and push them to Waniwani. This runs standalone and doesn't need to be inside an MCP server.

```ts scripts/kb-ingest.ts theme={null}
import { readdir, readFile } from "node:fs/promises";
import { join } from "node:path";
import { waniwani } from "@waniwani/sdk";

const client = waniwani(); // reads WANIWANI_API_KEY from env

const knowledgeDir = join(import.meta.dirname, "../knowledge");
const files = await readdir(knowledgeDir);
const mdFiles = files.filter((f) => f.endsWith(".md"));

console.log(`Ingesting ${mdFiles.length} files from ${knowledgeDir}`);

const docs = await Promise.all(
  mdFiles.map(async (filename) => ({
    filename,
    content: await readFile(join(knowledgeDir, filename), "utf-8"),
  })),
);

const result = await client.kb.ingest(docs);
console.log(`Done: ${result.chunksIngested} chunks from ${result.filesProcessed} files`);
```

Run it with `npx tsx scripts/kb-ingest.ts` or `bun scripts/kb-ingest.ts`.

<Info>
  A built-in `waniwani embed` CLI command is coming soon to `@waniwani/cli`, so you won't need a custom script.
</Info>

### Ingest input

<ResponseField name="filename" type="string">
  Identifier for the source file.
</ResponseField>

<ResponseField name="content" type="string">
  Markdown content. Chunked server-side.
</ResponseField>

<ResponseField name="metadata" type="Record<string, string>">
  Arbitrary key-value pairs stored with each chunk. Can be used to filter search results.
</ResponseField>

### Ingest response

```ts theme={null}
{ chunksIngested: number; filesProcessed: number }
```

## Search

```ts theme={null}
const results = await wani.kb.search("What is the return policy?", {
  topK: 5,       // 1–20, default 5
  minScore: 0.3, // 0–1, default 0.3
  metadata: { category: "support" }, // exact-match filter
});
```

Each result contains:

```ts theme={null}
{
  source: string;    // filename
  heading: string;   // section heading
  content: string;   // chunk text
  score: number;     // similarity score (0–1)
  metadata?: Record<string, string>;
}
```

### Using search in a tool

```ts theme={null}
server.registerTool(
  "faq",
  {
    title: "FAQ",
    description: "Answer questions from the knowledge base",
    inputSchema: { question: z.string() },
    annotations: { readOnlyHint: true },
  },
  async ({ question }) => {
    const results = await wani.kb.search(question, { topK: 5 });

    if (results.length === 0) {
      return {
        content: [{ type: "text", text: "No relevant information found." }],
      };
    }

    const formatted = results
      .map((r) => `### ${r.heading}\n${r.content}`)
      .join("\n\n");

    return {
      content: [{ type: "text", text: formatted }],
    };
  },
);
```

## List sources

List all ingested files with their chunk counts:

```ts theme={null}
const sources = await wani.kb.sources();
// [{ source: "pricing.md", chunkCount: 12, createdAt: "2025-..." }, ...]
```


# Documents
Source: https://docs.waniwani.ai/sdk/modules/documents

Read a PDF or an image into typed fields, from a URL or from a file the visitor attaches.

<Note>
  **Platform feature.** Requires `WANIWANI_API_KEY`. Works whether your MCP server is self-hosted or on Managed Hosting. [About the Platform](/sdk/platform/overview).
</Note>

Modules are capabilities you turn on per agent in the dashboard. The documents module reads a PDF or an image and gives you back the fields you asked for, shaped by a Zod schema.

A document reaches your agent one of two ways. Either you already have a URL and hand it over, or a visitor attaches a file in the chat widget and the platform stores it for you.

## Setup

The documents client sits on the Waniwani client instance:

```ts theme={null}
import { waniwani } from "@waniwani/sdk";

const wani = waniwani(); // reads WANIWANI_API_KEY from env
```

## Read a document you have a URL for

Describe what you want with a Zod schema and pass the URL:

```ts theme={null}
import { z } from "zod";

const invoice = z.object({
  invoiceNumber: z.string().nullable(),
  total: z.number().nullable(),
  dueDate: z.string().nullable(),
});

const { fields, pageCount } = await wani.documents.extract({
  url: "https://example.com/invoice.pdf",
  filename: "invoice.pdf",
  schema: invoice,
});

console.log(fields.invoiceNumber, pageCount);
```

`filename` is not decoration. It is how an unsupported type gets refused before anything is fetched.

<Warning>
  Extraction runs in strict mode, so mark every field the document might not answer `.nullable()`. A field that is not nullable and not present makes the whole extraction fail rather than coming back empty.
</Warning>

The URL has to be publicly fetchable. Private and loopback addresses are refused.

## What you get back

```ts theme={null}
{
  fields,          // your schema's shape, parsed. A null field is one the document did not legibly answer.
  pageCount,       // pages processed and billed
  pageConfidence,  // mean per-page OCR confidence, or null when none was reported
  documentId,      // handle for this extraction, valid for the 7-day retention window
}
```

## Read a file the visitor attached

Turn **Modules → Documents** on for the agent first. While it is off the widget shows no paperclip and the upload endpoint answers 403, so nothing arrives.

With it on, the visitor gets a paperclip, a drop target and paste. The bytes go straight from the browser to storage, never through your server, and your tool call arrives with a handle instead of a file.

Read it off the scoped client:

```ts theme={null}
import { extractScopedClient } from "@waniwani/sdk/mcp";
import { z } from "zod";

const summary = z.object({
  title: z.string().nullable(),
  summary: z.string().nullable(),
});

server.registerTool(
  "read_attachment",
  {
    title: "Read an attached file",
    description:
      "Read a document or image the visitor attached to this conversation. Takes no arguments: the attachment is already on the request.",
    inputSchema: {},
  },
  async (_args, extra) => {
    const wani = extractScopedClient(extra);
    const document = wani?.attachedDocuments[0];

    if (!wani || !document) {
      return { content: [{ type: "text", text: "Nothing is attached to this message." }] };
    }

    const { fields } = await wani.documents.extract({
      documentId: document.documentId,
      schema: summary,
    });

    return { content: [{ type: "text", text: `${document.filename}: ${fields.summary}` }] };
  },
);
```

Each entry carries `documentId`, `filename` and `mediaType`. Only the id is load-bearing, and there is no filename to pass to `extract()` because the platform kept it.

<Note>
  Your agent needs a tool like this before the toggle does anything visible. The platform stores the file and hands over an id; reading it is the agent's job.
</Note>

Give the tool a description that names the case plainly, including screenshots and photos. A model that does not believe it can read images will refuse before it ever calls your tool.

### On your own chat route

If you run the chat backend yourself rather than using the hosted widget, pull the same handles out of the request body:

```ts theme={null}
import { readAttachedDocuments } from "@waniwani/sdk";

const documents = readAttachedDocuments(body);
```

It accepts the whole body, reads the `documents` array when the widget sent one, and otherwise falls back to the latest user turn in `messages`.

## Read only some pages

Billing is per page processed, so narrow the range when you know where the answer is. Indexes are zero-based, and the option is ignored for images.

```ts theme={null}
await wani.documents.extract({
  documentId,
  schema: invoice,
  pages: [0, 1], // the first two pages
});
```

## Limits

|                   |                                      |
| ----------------- | ------------------------------------ |
| File size         | 50 MB                                |
| PDF length        | 1,000 pages                          |
| Types             | PDF, PNG, JPEG, TIFF, BMP, GIF, WEBP |
| Files per message | 10                                   |
| Retention         | 7 days                               |

Both the size and page caps are the OCR vendor's. A PDF is counted before the vendor is called, so an oversized document is refused rather than billed.

After 7 days the stored file is gone and its `documentId` no longer resolves. Extract what you need and keep the fields, not the id.

## Widget configuration

The hosted widget picks the module state up on its own, so `WaniwaniChat` and the script embed need no code for any of this.

`ChatEmbed`, the bring-your-own-backend primitive, takes it as a prop instead, and can send the upload calls under a different credential than the chat. See [Chat in React](/sdk/chat/react).


# Waniwani Platform
Source: https://docs.waniwani.ai/sdk/platform/overview

Optional hosted layer that adds tracking, knowledge base, chat widget, and hosted flow state to any MCP server you run.

The SDK is open source and runs without an API key. The **Platform** is an optional hosted layer at [app.waniwani.ai](https://app.waniwani.ai) that adds features the engine alone doesn't ship: event tracking, funnel analytics, a knowledge base, a chat widget, and hosted flow state.

The Platform works the same whether your MCP server is on your own infra or on [Managed Hosting](/sdk/deployment/overview). A single environment variable, `WANIWANI_API_KEY`, switches it on.

## Two independent choices

Where your server runs and whether you connect the Platform are independent decisions:

|                        | No Platform                                                | With Platform                                                                          |
| ---------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Self-hosted server** | Pure open source. Engine on your infra, no outbound calls. | Your infra for the server, our backend for KB, chat, tracking, and (optionally) state. |
| **Managed Hosting**    | Not applicable.                                            | Fully managed. We host the server and the Platform.                                    |

Pick the combination that fits. Most teams start at "self-hosted + Platform" or "Managed Hosting + Platform", and a smaller set runs pure open source.

## What the Platform adds

| Feature           | Entry point                                                                                              | What it gives you                                     |
| ----------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Event tracking    | [`withWaniwani(server)`](/sdk/configuration/wrap-server), [`waniwani().track()`](/sdk/tracking/overview) | `tool.called` events, custom events, dashboard ingest |
| Funnel analytics  | Automatic from tracked node visits                                                                       | Conversion, drop-off, completion rate per node        |
| Knowledge base    | [`@waniwani/sdk/kb`](/sdk/knowledge-base/overview)                                                       | Markdown ingest, semantic search from any tool        |
| Chat widget       | [`@waniwani/sdk/chat`](/sdk/chat/embed)                                                                  | Drop-in chat against your project, in script or React |
| Hosted flow state | [`WaniwaniKvStore`](/sdk/flows/kv-store) (auto-selected)                                                 | Encrypted-at-rest state with zero infra               |

All of these require `WANIWANI_API_KEY`. None of them require Managed Hosting.

## Enable it

```bash .env theme={null}
WANIWANI_API_KEY=wwk_...
```

[Create a free key at app.waniwani.ai](https://app.waniwani.ai). See [API keys](/sdk/configuration/api-key) for staging vs production setup.

With the key set, `createFlow().compile()` selects `WaniwaniKvStore` automatically when no `store` argument is passed, `withWaniwani(server)` starts emitting tracked events, and the KB / chat clients work end to end.

## What works without it

The engine is fully usable with no key:

* `createFlow`, `StateGraph`, `START`, `END`, `redacted` from `@waniwani/sdk/mcp`
* `KvStore` interface and `MemoryKvStore` (plus any adapter you write for Redis, Upstash, Cloudflare KV, DynamoDB, SQLite)
* `withWaniwani(server)` as a no-op wrapper that still bridges transport session IDs and forwards widget metadata
* `useWaniwani()` browser hook in degrade-to-no-op mode

`createFlow().compile()` requires a `store` when no API key is configured. With neither, it throws at compile time:

```
Error: [waniwani] createFlow "...": no flow store configured.
Pass { store } to .compile(). Use MemoryKvStore from "@waniwani/sdk/mcp"
for local development, or plug in a Redis/Upstash/Cloudflare KV adapter
for production. Alternatively, set WANIWANI_API_KEY to use hosted flow
state on app.waniwani.ai.
```

This is intentional. No silent fallback to a backend that does not exist in production. See [self-hosting the engine](/sdk/deployment/self-hosting) for the fully offline path.

## Going from open source to Platform

One line. Drop the `store` argument and set the env var:

```diff theme={null}
- .compile({ store: flowStore });
+ .compile(); // uses WaniwaniKvStore when WANIWANI_API_KEY is set
```

Existing sessions stay where they started: pre-switch sessions keep reading from your KV backend, new sessions persist on `app.waniwani.ai`. There is no automatic migration.

To keep self-hosted state and only add Platform tracking on top, keep the explicit `store` and call `withWaniwani(server)`. Tracking fires to `app.waniwani.ai`; flow state stays in your backend. The two pipelines are independent.

## Pricing

The Platform has a free plan. Set the API key and you are in. Limits and paid plans are listed at [app.waniwani.ai](https://app.waniwani.ai).


# Quickstart
Source: https://docs.waniwani.ai/sdk/quickstart

Boot a flow-driven MCP server in 60 seconds. No API key required.

A complete, runnable MCP server with one flow, in under 30 lines. No HTTP, no API key, no infrastructure. Runs over stdio so any MCP client can connect.

## 1. Install

```bash theme={null}
bun add @waniwani/sdk @modelcontextprotocol/sdk zod
```

## 2. Write the server

```ts hello.ts theme={null}
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createFlow, END, MemoryKvStore, START } from "@waniwani/sdk/mcp";
import { z } from "zod";

const flow = createFlow({
  id: "hello",
  title: "Hello World",
  description: "Say hello and ask a question.",
  state: { name: z.string().describe("Your name") },
})
  .addNode({
    id: "ask",
    run: ({ interrupt }) =>
      interrupt({ name: { question: "What's your name?" } }),
  })
  .addNode({
    id: "greet",
    run: ({ state }) => ({ greeted: true }),
  })
  .addEdge(START, "ask")
  .addEdge("ask", "greet")
  .addEdge("greet", END)
  .compile({ store: new MemoryKvStore() });

const server = new McpServer({ name: "hello-mcp", version: "1.0.0" });
await flow.register(server);
await server.connect(new StdioServerTransport());
```

## 3. Run it

```bash theme={null}
bun run hello.ts
```

That's a complete MCP server with one flow-driven tool. Connect it to ChatGPT, Claude, or any MCP client over stdio.

State lives in memory and resets on restart. Good for development. For production, swap `MemoryKvStore` for a real backend (see [KV store adapters](/sdk/flows/kv-store)) or set `WANIWANI_API_KEY` to use the [Waniwani Platform](/sdk/platform/overview) for hosted state.

## Next

<CardGroup>
  <Card title="Build a funnel" icon="filter" href="/sdk/guides/funnels">
    Sales funnels, lead gen, booking, quote flows.
  </Card>

  <Card title="Flow engine" icon="diagram-project" href="/sdk/flows/overview">
    Nodes, edges, interrupts, conditional branching.
  </Card>

  <Card title="Waniwani Platform" icon="layer-group" href="/sdk/platform/overview">
    What the SDK does without a key, and what unlocks when you connect the Platform.
  </Card>

  <Card title="Self-hosting" icon="server" href="/sdk/deployment/self-hosting">
    Deploy the OSS path end-to-end.
  </Card>
</CardGroup>

## Starter template

For a more complete project with chat widget, dev tunnel, and a sample funnel pre-wired:

```bash theme={null}
git clone https://github.com/WaniWani-AI/mcp-distribution-template.git my-mcp-server
cd my-mcp-server
bun install
bun dev
```


# SDK entry points
Source: https://docs.waniwani.ai/sdk/reference/entry-points

Which package path exports what.

The SDK is split into entry points so you only import what you need. The core flow engine ships zero runtime dependencies; the rest is opt-in.

| Entry point                         | What you get                                                                                                                               | Requires API key?             |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
| `@waniwani/sdk`                     | `waniwani()` client, `WaniWaniError`                                                                                                       | Yes                           |
| `@waniwani/sdk/mcp`                 | `createFlow`, `StateGraph`, `START`, `END`, `KvStore`, `MemoryKvStore`, `WaniwaniKvStore`, `withWaniwani`, scoped client, tracking helpers | No (key unlocks hosted parts) |
| `@waniwani/sdk/mcp/react`           | `useWaniwani` host-agnostic tracking hook (takes `toolResponseMetadata` or explicit `{ endpoint, source }`)                                | No                            |
| `@waniwani/sdk/mcp/react/skybridge` | `useWaniwani` skybridge adapter — bare call resolves config from skybridge's `useToolInfo()`                                               | No                            |
| `@waniwani/sdk/chat`                | `WaniwaniChat`, `ChatEmbed`, `McpAppFrame`, themes, `embed.js`, `styles.css`                                                               | Yes                           |
| `@waniwani/sdk/kb`                  | Knowledge-base client (`createKbClient`)                                                                                                   | Yes                           |

See the [Platform overview](/sdk/platform/overview) for what "Requires API key" means in practice.

## Bundle sizes

* `@waniwani/sdk/mcp` core path: under 5 KB gzipped
* `@waniwani/sdk/chat` (full widget bundle): \~650 KB (React included; tree-shakeable when you import individual layouts)
* `@waniwani/sdk` client + tracking: \~10 KB gzipped

## Peer dependencies

* `@modelcontextprotocol/sdk` (required for server entry points)
* `zod` (required for flow state schemas)
* `react` (only required when using `@waniwani/sdk/chat` or `@waniwani/sdk/mcp/react`)
* `skybridge` (optional; only required when using `@waniwani/sdk/mcp/react/skybridge`)


# Event schema
Source: https://docs.waniwani.ai/sdk/reference/event-schema

TrackEvent shape, the built-in event names, and the typed properties for each.

The full type-level reference for events sent via `wani.track()`. Usage recipes are in [Events](/sdk/tracking/events).

## `TrackEvent`

```ts theme={null}
import type { TrackInput } from "@waniwani/sdk";

type TrackEvent = {
  event: EventType;                     // required, one of the built-in names
  properties?: Record<string, unknown>; // typed per event name
  meta?: Record<string, unknown>;       // MCP request _meta
  metadata?: Record<string, unknown>;   // free-form metadata on the envelope
  sessionId?: string;                   // explicit override, usually omit
  traceId?: string;
  requestId?: string;
  correlationId?: string;
  externalUserId?: string;
  visitorId?: string;                   // anonymous device id, counts as identity
  eventId?: string;                     // supply your own id (idempotency)
  timestamp?: string | Date;            // defaults to now
  source?: string;                      // defaults to "@waniwani/sdk"
};
```

<ResponseField name="event" type="EventType">
  The event name. Must be one of the built-in `EventType` values listed below.
</ResponseField>

<ResponseField name="properties" type="Record<string, unknown>">
  Event payload. For built-in events, the type is narrowed (for example, `link.clicked` expects `{ url?: string }`).
</ResponseField>

<ResponseField name="meta" type="Record<string, unknown>">
  MCP request metadata, typically `extra._meta` inside a tool handler. This is where the SDK reads the session id from. See [Sessions](/sdk/tracking/sessions).
</ResponseField>

<ResponseField name="sessionId" type="string">
  Explicit session id override. Prefer passing `meta` instead.
</ResponseField>

<ResponseField name="externalUserId" type="string">
  External user identifier. Equivalent to calling `identify()` inline. See [Identify](/sdk/tracking/identify).
</ResponseField>

<ResponseField name="visitorId" type="string">
  Anonymous visitor id (the analytics "device id"). Counts as identity on its own; the chat widget uses it for pre-session events like `page.viewed`. See [Sessions](/sdk/tracking/sessions).
</ResponseField>

<ResponseField name="eventId" type="string">
  Client-generated id. If you omit it, the SDK generates `evt_<uuid>`. Supplying your own enables idempotent resends.
</ResponseField>

`track()` returns `{ eventId }` as soon as the envelope is enqueued, before the network request completes.

## `EventType` union

A closed union exported from `@waniwani/sdk`. Only these names are accepted by `track()`. The same list is available at runtime as the `EVENT_TYPES` constant.

| Event name        | Typed properties           | Notes                                                                                                                                                                                                                                 |
| ----------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session.started` | none                       | Emitted by the Waniwani backend when it sees a new session id. Do not send it yourself.                                                                                                                                               |
| `page.viewed`     | `PageViewedProperties`     | Emitted automatically by the chat widget on init, attributed to an anonymous `visitorId`. Do not send it yourself.                                                                                                                    |
| `tool.called`     | `ToolCalledProperties`     | Emitted automatically by `withWaniwani(server)`. Do not send it yourself. A handler that throws also carries `cause`, the same closed set `session.error` uses; a handler that returns `{ isError: true }` without throwing does not. |
| `widget_render`   | none                       | Emitted automatically by `useWaniwani()` when a widget initializes with resolved tracking config. Do not send it yourself.                                                                                                            |
| `session.error`   | `SessionErrorProperties`   | Emitted automatically by the flow engine when a step fails. There is no public API to send it yourself, and application code never emits it.                                                                                          |
| `link.clicked`    | `LinkClickedProperties`    | An outbound link was followed.                                                                                                                                                                                                        |
| `user.identified` | none                       | Prefer `client.identify()` over sending this directly.                                                                                                                                                                                |
| `price_shown`     | `PriceShownProperties`     | Revenue funnel step: one price was shown. Prefer `track.priceShown()`.                                                                                                                                                                |
| `prices_compared` | `PricesComparedProperties` | Revenue funnel step: two or more options shown side by side. Prefer `track.pricesCompared()`.                                                                                                                                         |
| `option_selected` | `OptionSelectedProperties` | Revenue funnel step: the user picked an option. Prefer `track.optionSelected()`.                                                                                                                                                      |
| `lead_qualified`  | `LeadQualifiedProperties`  | The person met your qualification bar. Prefer `track.leadQualified()`.                                                                                                                                                                |
| `converted`       | `ConvertedProperties`      | The user became paying, possibly later and off-platform. Prefer `track.converted()`.                                                                                                                                                  |

The five revenue events also have flat typed helpers on `track` (for example `wani.track.leadQualified({ ... })`). Each helper accepts its event's properties plus the shared tracking context (`sessionId`, `externalUserId`, `meta`, and so on). Placement guidance for each lives in [Instrumentation](/sdk/tracking/instrumentation).

## Typed property interfaces

```ts theme={null}
import type {
  ToolCalledProperties,
  SessionErrorProperties,
  LinkClickedProperties,
  PriceShownProperties,
  PricesComparedProperties,
  OptionSelectedProperties,
  LeadQualifiedProperties,
  ConvertedProperties,
} from "@waniwani/sdk";

interface ToolCalledProperties {
  name?: string;
  type?: "pricing" | "product_info" | "availability" | "support" | "other";
  /** Retrieval traces for kb.search() calls made inside this tool handler. */
  kbSearch?: KbSearchTrace[];
  /** Stamped when the handler throws. Absent when it returns `{ isError: true }`. */
  cause?: SessionErrorProperties["cause"];
}

interface SessionErrorProperties {
  /**
   * agent_failed: a flow step failed (unknown node, missing edge, throwing
   * handler, iteration cap). upstream_failed: a flow state store read or
   * write failed. tool_failed: reserved, not emitted by the SDK yet.
   */
  code: "agent_failed" | "tool_failed" | "upstream_failed";
  cause:
    | "timeout"
    | "rate_limited"
    | "upstream_4xx"
    | "upstream_5xx"
    | "network"
    | "invalid_output"
    | "flow_dead_end"
    | "flow_unknown_node"
    | "flow_loop"
    | "unknown";
  /** The tool the failure is attributed to, if any. */
  tool?: string;
  /** The flow node that failed, if any. */
  node?: string;
}

interface LinkClickedProperties {
  url?: string;
}

interface PriceShownProperties {
  amount: number;
  currency: string;
  itemId?: string;
  label?: string;
}

interface PricesComparedProperties {
  options: Array<{ id: string; amount: number; currency: string }>;
}

interface OptionSelectedProperties {
  id: string;
  amount: number;
  currency: string;
}

interface LeadQualifiedProperties {
  /** Your own lead id (e.g. the record id your CRM returns). The strongest dedup key. */
  externalId?: string;
  /** The lead's email, if known. */
  email?: string;
  /** The lead's name, if known. */
  name?: string;
}

interface ConvertedProperties {
  amount: number;
  currency: string;
  /** When the conversion actually happened, for backdated off-platform sales. */
  occurredAt?: string;
}
```

<Note>
  `session.error` carries no error message, stack, or handler input, only the bounded tokens above. The `code` and `cause` unions are available at runtime as the `SESSION_ERROR_CODES` and `ERROR_CAUSES` constants exported from `@waniwani/sdk`. That keeps the properties safe to surface to a customer. The SDK also writes a `console.error` line prefixed `[waniwani][session-error]`, but that line carries only the same `code:tool:cause` token and the node name, not the thrown error. To keep the underlying error, log it yourself in the handler where it is thrown.
</Note>

<Note>
  Browser surfaces (`useWaniwani()`, `chat.track`) send the same `EventType` union through the same envelope; there is no separate widget event schema. See [Widgets & chat](/sdk/tracking/widgets).
</Note>


# Flow tool contract
Source: https://docs.waniwani.ai/sdk/reference/flow-tool-contract

FlowToolInput shape and the response statuses a compiled flow emits.

A compiled flow registers itself as a single MCP tool. This page documents the wire contract between the model and that tool. You don't usually parse it yourself, but it's the reference if you're building tracing, replay, or test harnesses.

## Input

```ts theme={null}
type FlowToolInput = {
  action: "start" | "continue";
  intent?: string; // required when action is "start"
  stateUpdates?: Record<string, unknown>;
};
```

* `start` begins a new run. `intent` is a short summary of why the user triggered the flow. `stateUpdates` can pre-fill any known fields so the engine auto-skips those questions.
* `continue` resumes the current run with the user's latest answers in `stateUpdates`.

The full input schema lives in the generated tool description, so the model knows how to call it without docs.

## Response statuses

Every tool call drives the engine until it hits one of four outcomes:

| Status      | Meaning                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------ |
| `interrupt` | Pause and ask the user one or more questions. The response carries the question payload.   |
| `widget`    | Pause and delegate rendering to a display tool. The response carries the widget reference. |
| `complete`  | The graph reached `END`. Server-side state is deleted.                                     |
| `error`     | The handler threw or validation failed. The response carries an error message.             |

Between pause points, the engine auto-advances through action nodes (nodes that return a plain state update). No round-trip to the model. A single tool call can run several action nodes before hitting the next pause.

## State persistence

State persists between calls in the flow store, keyed by the session id extracted from `_meta`. Default behavior is described in the [Platform overview](/sdk/platform/overview):

* Without an explicit `store` and without `WANIWANI_API_KEY`, `.compile()` throws at compile time.
* With an explicit `store: KvStore`, state lives wherever your adapter writes.
* With `WANIWANI_API_KEY` and no explicit `store`, the SDK selects `WaniwaniKvStore` and state lives on `app.waniwani.ai`.

See [State](/sdk/flows/state) for the state schema side of the contract, and [KV store adapters](/sdk/flows/kv-store) for backend options.


# Client & KV store reference
Source: https://docs.waniwani.ai/sdk/reference/kv-store-api

Type signatures for the waniwani() client and the KvStore interface.

This page is the type-level reference for the two main extension points in the SDK: the `KvStore` interface (any flow uses it) and the `waniwani()` client (used by [Platform](/sdk/platform/overview) features).

## `KvStore` interface

```ts theme={null}
export interface KvStore<T = Record<string, unknown>> {
  get(key: string): Promise<T | null>;
  set(key: string, value: T): Promise<void>;
  delete(key: string): Promise<void>;
}
```

That is the entire contract. The engine handles serialization, session-key derivation, expiry semantics, and concurrency. Implement it against any backend with those three operations. See [KV store adapters](/sdk/flows/kv-store) for ready-made recipes.

### Built-in implementations

* **`MemoryKvStore`** from `@waniwani/sdk/mcp`. An in-memory `Map`. Resets on process restart.
* **`WaniwaniKvStore`** from `@waniwani/sdk/mcp`. Persists against `app.waniwani.ai`. Selected automatically when `WANIWANI_API_KEY` is set and no explicit `store` is passed.

### What gets stored

Each session maps to one key. The engine stores:

* The current node (or `END` when complete)
* The merged state object so far
* A pending widget reference, if the current node is a `showWidget` step

Keys are derived from the MCP session identifier (`_meta.waniwani/sessionId` or `Mcp-Session-Id`), so isolating sessions is automatic. Values are JSON-serializable plain objects.

## `waniwani()` client

```ts theme={null}
import { waniwani } from "@waniwani/sdk";

const wani = waniwani({
  apiKey: process.env.WANIWANI_API_KEY,
  apiUrl: "https://app.waniwani.ai",
  tracking: {
    flushIntervalMs: 500,
    maxBatchSize: 50,
    maxRetries: 5,
    shutdownTimeoutMs: 5000,
  },
});
```

All fields are optional. With no arguments, the client reads `WANIWANI_API_KEY` from the environment and targets `https://app.waniwani.ai`.

<ResponseField name="apiKey" type="string">
  Your MCP environment API key. Defaults to `process.env.WANIWANI_API_KEY`. If both are missing, `track()` / `flush()` / `shutdown()` throw at runtime.
</ResponseField>

<ResponseField name="apiUrl" type="string">
  Base URL of the Waniwani API. Override for self-hosted deployments or staging backends.
</ResponseField>

<ResponseField name="tracking" type="object">
  Fine-tune the event tracking transport.

  <Expandable title="tracking options">
    <ResponseField name="endpointPath" type="string">
      Path appended to `apiUrl` when POSTing batches.
    </ResponseField>

    <ResponseField name="flushIntervalMs" type="number">
      How often the buffered transport flushes events.
    </ResponseField>

    <ResponseField name="maxBatchSize" type="number">
      Maximum events per HTTP request.
    </ResponseField>

    <ResponseField name="maxBufferSize" type="number">
      Maximum in-memory buffer size. Oldest events are dropped beyond this.
    </ResponseField>

    <ResponseField name="maxRetries" type="number">
      Retry attempts on transient failures.
    </ResponseField>

    <ResponseField name="retryBaseDelayMs" type="number">
      Base delay for exponential backoff between retries.
    </ResponseField>

    <ResponseField name="retryMaxDelayMs" type="number">
      Maximum backoff delay between retries.
    </ResponseField>

    <ResponseField name="shutdownTimeoutMs" type="number">
      How long `shutdown()` waits for in-flight events before returning.
    </ResponseField>
  </Expandable>
</ResponseField>

## Graceful shutdown

In Node environments, the SDK attaches handlers for `beforeExit`, `SIGINT`, and `SIGTERM` that flush buffered events automatically. For serverless, edge runtimes, tests, or short-lived scripts, call `shutdown()` explicitly:

```ts theme={null}
const result = await wani.shutdown({ timeoutMs: 5000 });
// => { timedOut: false, pendingEvents: 0 }
```


# Events
Source: https://docs.waniwani.ai/sdk/tracking/events

Every event the SDK can send, and how to send them from the server, a widget, or the chat embed.

<Note>
  **Platform feature.** Requires `WANIWANI_API_KEY` on the server. Browser surfaces authenticate with a public token (`wwp_...`) or an injected widget token instead. [About the Platform](/sdk/platform/overview).
</Note>

Events are a single typed taxonomy, sent through one `track` surface that is identical everywhere it appears:

```ts theme={null}
await track({ event: "link.clicked", properties: { url: "https://acme.com/pricing" } });
await track.priceShown({ amount: 49, currency: "EUR" });
await track.leadQualified({ email: "jane@acme.com" });
await track.converted({ amount: 85, currency: "EUR" });
```

That same `track` exists on four surfaces, each of which attaches session identity for you:

| Surface                      | Where `track` lives                        | Identity attached automatically                   |
| ---------------------------- | ------------------------------------------ | ------------------------------------------------- |
| MCP tool handler / flow node | `context.waniwani.track` (scoped client)   | `sessionId` from the request meta                 |
| MCP-app widget (browser)     | `useWaniwani().track`                      | `sessionId` injected by `withWaniwani`            |
| Chat host page               | `WaniWani.chat.track` / `ChatHandle.track` | `visitorId` always; `sessionId` too once assigned |
| Your backend / scripts       | `waniwani().track`                         | none, pass `externalUserId` or `sessionId`        |

The first three need no identity plumbing at all. Only the top-level backend client requires you to say who the event belongs to. See [Sessions](/sdk/tracking/sessions) for the identity model and [Widgets](/sdk/tracking/widgets) for the browser surfaces.

## The event catalog

The `EventType` union is a closed, typed set, exported at runtime as `EVENT_TYPES` from `@waniwani/sdk`. These are all the events:

| Event             | Sent by                           | Properties                 | When                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------- | --------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page.viewed`     | Chat widget, automatic            | `PageViewedProperties`     | A visitor lands on a page where the chat widget is present. Attributed to the anonymous `visitorId`, never a session.                                                                                                                                                                                                                                                                                                            |
| `session.started` | Waniwani backend, automatic       | none                       | First time the backend sees a new `sessionId`. Never send it yourself.                                                                                                                                                                                                                                                                                                                                                           |
| `tool.called`     | `withWaniwani(server)`, automatic | `ToolCalledProperties`     | Every tool invocation: name, type, duration, status, input/output, KB retrieval traces. A handler that throws also carries `cause`; a handler that returns `{ isError: true }` does not.                                                                                                                                                                                                                                         |
| `widget_render`   | `useWaniwani()`, automatic        | none                       | A widget initialized with resolved tracking config. The top of the widget funnel.                                                                                                                                                                                                                                                                                                                                                |
| `session.error`   | Flow engine, automatic            | `SessionErrorProperties`   | The flow engine hit a failure. `code: "agent_failed"` covers step execution: an unknown node, a missing outgoing edge (including a missing start edge), a throwing step handler, or the iteration cap. `code: "upstream_failed"` covers flow state store reads and writes that fail. Carries no error message, stack, or handler input, only bounded tokens. There is no public API to send it; application code never emits it. |
| `user.identified` | `identify()` on any surface       | free-form traits           | A stable user id was attached. Prefer calling `identify()` over sending this directly.                                                                                                                                                                                                                                                                                                                                           |
| `lead_qualified`  | you, `track.leadQualified()`      | `LeadQualifiedProperties`  | The lead qualified: the conversation produced a concrete handoff toward your business. Once per flow run. See the definition below.                                                                                                                                                                                                                                                                                              |
| `price_shown`     | you, `track.priceShown()`         | `PriceShownProperties`     | You showed the user one price.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `prices_compared` | you, `track.pricesCompared()`     | `PricesComparedProperties` | You showed two or more options side by side.                                                                                                                                                                                                                                                                                                                                                                                     |
| `option_selected` | you, `track.optionSelected()`     | `OptionSelectedProperties` | The user picked one of the options.                                                                                                                                                                                                                                                                                                                                                                                              |
| `converted`       | you, `track.converted()`          | `ConvertedProperties`      | The user became paying, possibly later and off-platform.                                                                                                                                                                                                                                                                                                                                                                         |
| `link.clicked`    | you, generic `track()`            | `LinkClickedProperties`    | An outbound link was followed.                                                                                                                                                                                                                                                                                                                                                                                                   |

Type shapes for every property interface live in the [event schema reference](/sdk/reference/event-schema). Placement guidance (which event belongs at which flow node) lives in [Instrumentation](/sdk/tracking/instrumentation).

Any event name outside this table is rejected: the `TrackEvent` union will not typecheck it, and the ingest API does not power funnels with it. Model your funnel with the events above instead of inventing names.

## What counts as a qualified lead

`lead_qualified` means the conversation produced a concrete handoff toward your business. A lead is qualified whenever the user:

* is redirected to your pricing page or to your own website,
* books a call or a meeting,
* is sent an email (a quote recap, a follow-up, a booking confirmation),
* or otherwise meets an explicit qualification bar you defined (finished the qualifying questions, requested a demo, matched your target profile).

Knowing who the user is does not qualify them. When you learn an email, a phone number, or a first and last name, call `identify()`: that attaches identity to the session and is the join key for later attribution, but it does not mean the lead is qualified yet. `identify` says "we know who this is"; `lead_qualified` says "this person is worth your sales attention". Most funnels emit both, at different moments. See [Identify](/sdk/tracking/identify) and [Instrumentation](/sdk/tracking/instrumentation) for placement.

The chat backend also logs `chat.user_message` and `chat.assistant_message` server-side for every exchange; you never send those from code.

Everything on this page is **platform ingest**: events sent to Waniwani to power funnel analytics. The chat widget also offers a separate host-callback channel — `onEvent` — that mirrors widget lifecycle events into **your own** page-side analytics (Amplitude, Segment, gtag) without touching the Waniwani ingest. See [Widget events (onEvent)](/sdk/chat/widget-events).

## Revenue helpers

The five revenue funnel events have flat typed helpers on `track` (there is no `track.revenue.*` namespace). Each accepts its event's properties plus the shared tracking context (`sessionId`, `externalUserId`, `visitorId`, `meta`).

| Helper                                                          | Event             |
| --------------------------------------------------------------- | ----------------- |
| `track.leadQualified({ externalId?, email?, name? })`           | `lead_qualified`  |
| `track.priceShown({ amount, currency, itemId?, label? })`       | `price_shown`     |
| `track.pricesCompared({ options: [{ id, amount, currency }] })` | `prices_compared` |
| `track.optionSelected({ id, amount, currency })`                | `option_selected` |
| `track.converted({ amount, currency, occurredAt? })`            | `converted`       |

`occurredAt` on `converted` backdates an off-platform sale to when it actually happened; the event itself may arrive months later.

## Sending events

### From a tool handler or flow node

Wrap the server once with `withWaniwani(server)`, then use the scoped client from the handler context. Session identity is already attached; you pass nothing.

```ts theme={null}
.addNode("show_quote", async ({ state, waniwani }) => {
  await waniwani?.track.priceShown({ amount: state.premium, currency: "EUR" });
  return {};
})
```

```ts theme={null}
server.registerTool("get_quote", { /* config */ }, async ({ amount }, extra) => {
  const waniwani = extra["waniwani/client"];
  await waniwani?.track.priceShown({ amount, currency: "EUR" });
  return { content: [{ type: "text", text: "Quoted" }] };
});
```

The scoped client also exposes the resolved session id as `waniwani.sessionId`. Store it with your own records (a lead, an order) and you can attribute an off-platform event back to the conversation later.

### From a widget or the chat embed

The browser surfaces expose the same `track`. See [Widgets](/sdk/tracking/widgets) for setup; the calls are identical:

```tsx theme={null}
const wani = useWaniwani();
wani.track.optionSelected({ id: "pro", amount: 49, currency: "EUR" });
```

```js theme={null}
WaniWani.chat.track.converted({ amount: 85, currency: "EUR" });
```

### From your backend

Create one top-level client (for example in `lib/waniwani.ts`) and pass identity explicitly on every call. This is how an off-platform conversion finds its original lead:

```ts theme={null}
import { waniwani } from "@waniwani/sdk";

const client = waniwani(); // reads WANIWANI_API_KEY from env

await client.track.converted({
  amount: 85,
  currency: "EUR",
  externalUserId: "user_123",           // the join key captured during the funnel
  occurredAt: "2026-06-09T10:00:00Z",
});
```

If you stored the scoped client's `sessionId` during the conversation, `sessionId: storedSessionId` works as the join key too.

## The identity rule

Every event must carry a `sessionId`, an `externalUserId`, or a `visitorId`. The ingest API rejects events with none, and the SDK warns at enqueue time. The scoped client, the widget hook, and the chat embed satisfy this automatically; the top-level backend client is the one place you pass identity yourself.

## Return value

```ts theme={null}
const { eventId } = await client.track({ event: "link.clicked", properties: { url: "https://acme.com/pricing" }, externalUserId: "user_123" });
```

`eventId` is stable and safe to log. It is assigned before the envelope leaves the process, so logging it tells you an event was accepted into the buffer, not that it reached the backend. `track()` returns as soon as the envelope is enqueued, before the network request completes.

## Flushing

The transport flushes on a timer and on batch size. In long-running processes you do not need to call `flush()` yourself. In serverless functions, call it before the function returns:

```ts theme={null}
await client.flush();
```

Or stop the transport entirely:

```ts theme={null}
const { timedOut, pendingEvents } = await client.shutdown({ timeoutMs: 5000 });
```

Browser surfaces additionally flush with `keepalive` requests when the page is hidden or unloading, so events survive navigation.


# Identify Users
Source: https://docs.waniwani.ai/sdk/tracking/identify

Attach an external user id to the current session.

<Note>
  **Platform feature.** Requires `WANIWANI_API_KEY`. Works whether your MCP server is self-hosted or on Managed Hosting. [About the Platform](/sdk/platform/overview).
</Note>

`identify()` sends a `user.identified` event and attaches an `externalUserId` to the current session's correlation ids. Use it as soon as you know who the user is: they shared an email, a phone number, a first and last name, or your system knows a stable id (a database id, a CRM record id, a Stripe customer id).

<Note>
  Identified is not qualified. Learning an email, a phone number, or a name means `identify()`; it does not make the lead qualified yet. `lead_qualified` fires separately, when the conversation produces a concrete handoff toward your business (a redirect to your pricing page or website, a booked call, an email sent to the user). See [what counts as a qualified lead](/sdk/tracking/events#what-counts-as-a-qualified-lead).
</Note>

## Signature

```ts theme={null}
identify(
  userId: string,
  properties?: Record<string, unknown>,
  meta?: Record<string, unknown>,
): Promise<{ eventId: string }>;
```

Under the hood it calls `track()` with `event: "user.identified"` and passes `userId` as `externalUserId`. The call returns `{ eventId }` immediately, the same as `track()`.

<ResponseField name="userId" type="string">
  A stable external identifier for the user. Database id, CRM record id, Stripe customer id, or similar. Emails work but are not ideal because they change.
</ResponseField>

<ResponseField name="properties" type="Record<string, unknown>">
  User-level traits (name, email, plan, signup date, and so on). These land in the event `properties` payload.
</ResponseField>

<ResponseField name="meta" type="Record<string, unknown>">
  MCP request metadata, typically `extra._meta`. Required so the identify call can be correlated with the current session.
</ResponseField>

## Usage

```ts theme={null}
await wani.identify(
  "user_01HX123ABC",
  { email: "customer@example.com", plan: "pro" },
  extra._meta,
);
```

A typical pattern is to call `identify()` from the tool that first learns the user's identity:

```ts theme={null}
server.registerTool(
  "submit_email",
  { /* ... */ },
  async ({ email }, extra) => {
    await wani.identify(email, { email }, extra._meta);
    return { content: [{ type: "text", text: "Thanks" }] };
  },
);
```

## Identify inline with `track()`

If the same tool call both learns the identity and produces a domain event, pass `externalUserId` on the `track()` call instead of making a separate `identify()` call:

```ts theme={null}
await wani.track.priceShown({
  amount: 99,
  currency: "USD",
  externalUserId: "user_01HX123ABC",
  meta: extra._meta,
});
```

This produces one event instead of two.

## Inside tools and flows

When the server is wrapped with `withWaniwani()`, the scoped client on `waniwani` in flow nodes (or via `extractScopedClient(extra)` in a hand-registered tool) already has the request's `_meta` attached, so `identify()` takes only `userId` and optional `properties`:

```ts theme={null}
// Inside a flow node
.addNode({
  id: "record_email",
  run: async ({ state, waniwani }) => {
    if (state.email) {
      await waniwani?.identify(state.email, { email: state.email });
    }
    return {};
  },
})
```

## From the browser

The browser surfaces expose the same call with identity plumbing built in. In an MCP-app widget, `useWaniwani().identify()` stamps the user id on every later widget event; on a chat host page, `WaniWani.chat.identify()` (or `ChatHandle.identify`) ties the visitor and chat session to your user id:

```tsx theme={null}
const wani = useWaniwani();
wani.identify("user_123", { plan: "pro" });
```

```js theme={null}
WaniWani.chat.identify("user_123", { plan: "pro" });
```

See [Widgets & chat](/sdk/tracking/widgets).

## Anonymous vs. identified sessions

Sessions start anonymous. They get a `sessionId` from `_meta` but no `externalUserId`. When you call `identify()` (or pass `externalUserId` on a `track()` call), future events in the session carry the user id. How the backend back-fills earlier events in the same session for a newly identified user is a server-side concern, not something the SDK controls.

<Tip>
  Calling `identify()` multiple times with the same `userId` is fine. Each call is an independent `user.identified` event.
</Tip>


# Instrumentation
Source: https://docs.waniwani.ai/sdk/tracking/instrumentation

Where each funnel event belongs in a flow, and how to auto-instrument it with the instrument-tracking skill.

<Note>
  **Platform feature.** Requires `WANIWANI_API_KEY`. Works whether your MCP server is self-hosted or on Managed Hosting. [About the Platform](/sdk/platform/overview).
</Note>

Instrumentation is the mapping between your flow's nodes and the Waniwani event taxonomy: which node emits which event, with which metadata. Get the mapping right and the dashboard shows a funnel that explains where users drop off and which conversations turn into revenue. This page gives you the placement rules, and a skill that applies them to your codebase automatically.

## The taxonomy

The event set is closed and typed. Model every funnel stage with one of these; there is no custom event name.

| Stage         | Event             | Emit via                                                   | Notes                                                    |
| ------------- | ----------------- | ---------------------------------------------------------- | -------------------------------------------------------- |
| Landing       | `page.viewed`     | chat widget, automatic                                     | Attributed to an anonymous `visitorId`.                  |
| Activity      | `tool.called`     | `withWaniwani(server)`, automatic                          | One per tool invocation, with timing and status.         |
| Identity      | `user.identified` | `waniwani?.identify(userId, properties?)`                  | Attach a stable external id as soon as one is known.     |
| Qualification | `lead_qualified`  | `waniwani?.track.leadQualified({ ... })`                   | The person met your qualification bar.                   |
| Step          | `price_shown`     | `waniwani?.track.priceShown({ amount, currency })`         | You showed one price.                                    |
| Step          | `prices_compared` | `waniwani?.track.pricesCompared({ options })`              | You showed two or more options side by side.             |
| Step          | `option_selected` | `waniwani?.track.optionSelected({ id, amount, currency })` | The user picked one of those options.                    |
| Conversion    | `converted`       | `waniwani?.track.converted({ amount, currency })`          | The user became paying, possibly later and off-platform. |

Inside a flow node, `waniwani` comes from the handler context and already carries the session identity. Full type shapes are in the [Event schema](/sdk/reference/event-schema).

## Placing `lead_qualified`

`lead_qualified` is your code declaring that the conversation produced a concrete handoff toward your business. A lead is qualified whenever the user:

* is redirected to your pricing page or to your own website (the moment right before `openExternal(...)` or the redirect widget is the natural emit point),
* books a call or a meeting,
* is sent an email (a quote recap, a follow-up, a booking confirmation),
* or meets an explicit qualification bar you defined (finished the qualifying questions, requested a demo, matched your target profile).

Three rules:

1. **It fires at the handoff, not at flow entry.** Starting a flow is activity (`tool.called` covers it). The event belongs where the handoff happens: the node that pushes the lead to your CRM, or the widget callback that redirects the user to your site.
2. **It fires once per flow run.**
3. **Fill every property you can.** The properties are the join keys the dashboard uses to dedupe leads and connect them to your system.

| Property     | What to pass                                                                                                                                  |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `externalId` | Your own lead id, for example the record id your CRM or lead API returns. The strongest dedup key, so place the event after that push exists. |
| `email`      | The lead's email, from whichever state field holds it.                                                                                        |
| `name`       | The lead's name, if collected.                                                                                                                |

```ts theme={null}
.addNode({
  id: "push_lead",
  label: "Push to CRM",
  run: async ({ state, waniwani }) => {
    const lead = await crm.createLead({
      email: state.email,
      role: state.role,
      useCase: state.useCase,
    });
    waniwani?.track.leadQualified({
      externalId: lead.id,
      email: state.email,
    });
    return { leadId: lead.id };
  },
})
```

<Note>
  Sharing an email, a phone number, or a first and last name mid-conversation is `identify(userId, { ... })`, not a qualified lead. `identify` attaches identity; `lead_qualified` declares the handoff happened. Most flows emit both, at different nodes.
</Note>

## Placement rules for the rest

* **`identify` as early as possible.** The first node where an email or user id is in state calls `waniwani?.identify(state.email)`. This is what lets an off-platform `converted` find its way back to the session.
* **Price events go where the numbers are.** The node that computes a single price emits `priceShown`; the node that presents multiple plans emits `pricesCompared`; the node that runs after the user picked (the selection is now in state) emits `optionSelected`.
* **`converted` only on real conversion.** A confirmed booking or completed purchase inside the flow. If the sale closes later on your own site, emit it from your backend with the same `externalUserId` you identified during the flow, or with the `waniwani.sessionId` you stored on the lead. See [Sessions](/sdk/tracking/sessions).
* **Emit from node handlers, never from `validate` callbacks.** Validation can run several times per answer and would duplicate events.
* **Always guard with `waniwani?.`.** The scoped client is `undefined` when the server is not wrapped with `withWaniwani(server)`, and tracking throws without an API key. Optional chaining keeps keyless runs working.
* **Never pass `sessionId` manually inside a flow.** The scoped client carries it.

## A fully instrumented flow

```
START
  -> welcome            (interrupt: email)            identify(state.email)
  -> qualify            (interrupt: role, team size)
  -> push_lead          (action, CRM returns id)      lead_qualified { externalId, email }
  -> compute_quote      (action)                      price_shown { amount, currency }
  -> show_plans         (widget: 3 plans)             prices_compared { options }
  -> confirm_plan       (action)                      option_selected { id, amount, currency }
  -> book               (action)                      converted { amount, currency }
  -> END
```

Not every flow has every stage. A lead-gen flow can end at `lead_qualified`; a support flow may only ever `identify`. Forcing events onto nodes that do not represent that stage corrupts the funnel.

## Auto-instrument with the skill

The `instrument-tracking` agent skill applies everything on this page to your codebase: it inventories your flows, maps every node to the taxonomy, inserts guarded tracking calls with metadata read from your flow state, wraps the server with `withWaniwani` if needed, and runs your typecheck.

<CodeGroup>
  ```bash npx theme={null}
  npx skills add Waniwani-AI/sdk -s instrument-tracking
  ```

  ```bash bunx theme={null}
  bunx skills add Waniwani-AI/sdk -s instrument-tracking
  ```
</CodeGroup>

Then ask your agent, in natural language:

* *"Instrument tracking across my flows"*
* *"Track qualified leads in my demo flow"*
* *"Add conversion tracking to the booking flow"*

The skill also runs well as a subagent at the end of a scaffolding session, so a freshly generated flow ships instrumented from its first deploy. It reports the final node-to-event mapping as a table, so you can review every placement before committing.

## Audit an existing app

The `audit-tracking` skill is the read-only counterpart. It fetches the latest event definitions from these docs, inventories every tracking call across the server, flows, widgets, and chat embed, verifies that only events from the taxonomy are sent, and reports missing funnel events with a suggested payload for each. Run it before instrumenting, or as a periodic health check on an already instrumented app.

<CodeGroup>
  ```bash npx theme={null}
  npx skills add Waniwani-AI/sdk -s audit-tracking
  ```

  ```bash bunx theme={null}
  bunx skills add Waniwani-AI/sdk -s audit-tracking
  ```
</CodeGroup>

Then ask your agent, in natural language:

* *"Audit the tracking in this MCP"*
* *"Are we sending any events that aren't defined?"*
* *"Which funnel events are we missing?"*

## Checklist

* Exactly one `leadQualified` per flow run, placed at the qualification bar, with `externalId` when your CRM returns one.
* `identify` runs at the earliest node where a stable id exists.
* Every tracking call is guarded with `waniwani?.` and none passes `sessionId`.
* `withWaniwani(server)` wraps the server.
* Off-platform conversions send `converted` from your backend with the identified `externalUserId`.

## Next

<CardGroup>
  <Card title="Event schema" icon="table" href="/sdk/reference/event-schema" />

  <Card title="Identify" icon="user" href="/sdk/tracking/identify" />

  <Card title="Sessions" icon="link" href="/sdk/tracking/sessions" />

  <Card title="Agent skills" icon="wand-magic-sparkles" href="/sdk/guides/skills" />
</CardGroup>


# Event Tracking Overview
Source: https://docs.waniwani.ai/sdk/tracking/overview

Send events from your MCP server to the Waniwani dashboard.

<Note>
  **Platform feature.** Requires `WANIWANI_API_KEY`. Works whether your MCP server is self-hosted or on Managed Hosting. [About the Platform](/sdk/platform/overview).
</Note>

The tracking module ships events from your MCP server to the Waniwani backend. You call `client.track()`, the SDK enqueues the event in memory, and a background transport batches and posts it to `POST /api/mcp/events/v2/batch`. Tracking never blocks your tool handler.

## Mental model

<CardGroup>
  <Card title="Events" icon="bolt" href="/sdk/tracking/events">
    A typed record of something that happened (a tool call, a quote, a purchase). Has a name, properties, and correlation ids.
  </Card>

  <Card title="Sessions" icon="link" href="/sdk/tracking/sessions">
    A session groups events from one conversation. On every SDK surface except the top-level backend client, the session id attaches to events automatically.
  </Card>

  <Card title="Widgets & chat" icon="window" href="/sdk/tracking/widgets">
    The same `track` client in the browser: `useWaniwani()` in MCP-app widgets, `chat.track` on chat host pages. Session identity included.
  </Card>

  <Card title="Identify" icon="user" href="/sdk/tracking/identify">
    Attach an `externalUserId` to the current session so events get linked to a real user.
  </Card>

  <Card title="Automatic tool tracking" icon="wand-magic-sparkles" href="/sdk/configuration/wrap-server">
    `withWaniwani(server)` wraps every tool handler and emits `tool.called` for you with timing and status.
  </Card>
</CardGroup>

## Track your first event

```ts theme={null}
import { waniwani } from "@waniwani/sdk";

const wani = waniwani(); // reads WANIWANI_API_KEY from env

// Inside a tool handler
await wani.track.priceShown({
  amount: 1299,
  currency: "EUR",
  meta: extra._meta, // associates the event with the current session
});

// In serverless runtimes, flush before the function returns
await wani.flush();
```

That is the whole happy path. Everything else on the following pages is detail.

## How the transport behaves

When you call `track()`, the SDK:

1. Normalizes the input into a canonical Events API V2 envelope (see [events-api-v2-contract](https://github.com/waniwani-ai/sdk)).
2. Generates a deterministic event id (`evt_<uuid>`).
3. Pushes the envelope on an in-memory buffer and returns `{ eventId }` immediately.
4. A background timer flushes the buffer every `flushIntervalMs` (default `1000`), or sooner when the batch fills (`maxBatchSize`, default `20`).
5. Retries transient failures (`408`, `425`, `429`, `5xx`) with exponential backoff, up to `maxRetries` (default `3`).
6. Stops retrying on `401` / `403` auth errors to avoid retry storms.

### Long-running vs. serverless

| Runtime                   | How to make sure events ship                                                                                   |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Long-running Node process | Nothing. The SDK attaches `beforeExit`, `SIGINT`, and `SIGTERM` hooks that call `shutdown()` automatically.    |
| Serverless / short-lived  | Call `await wani.flush()` before the function returns, or pass `flushAfterToolCall: true` to `withWaniwani()`. |

## Client API

```ts theme={null}
interface TrackingClient {
  track(event: TrackInput): Promise<{ eventId: string }>;
  identify(
    userId: string,
    properties?: Record<string, unknown>,
    meta?: Record<string, unknown>,
  ): Promise<{ eventId: string }>;
  flush(): Promise<void>;
  shutdown(options?: { timeoutMs?: number }): Promise<{
    timedOut: boolean;
    pendingEvents: number;
  }>;
}
```

<CardGroup>
  <Card title="track(event)" icon="plus" href="/sdk/tracking/events">
    Enqueue an event.
  </Card>

  <Card title="identify(userId, properties?, meta?)" icon="user" href="/sdk/tracking/identify">
    Send a `user.identified` event and attach the user id to the session.
  </Card>

  <Card title="flush()" icon="water">
    Wait for the current buffer to drain.
  </Card>

  <Card title="shutdown({ timeoutMs? })" icon="power-off">
    Flush and stop the transport. Returns `{ timedOut, pendingEvents }`.
  </Card>
</CardGroup>

<Note>
  All four methods throw synchronously if no `apiKey` was resolved (from config or `WANIWANI_API_KEY`). If you instantiate `waniwani()` without an api key, the client is inert and calling `track()` will throw.
</Note>


# Sessions
Source: https://docs.waniwani.ai/sdk/tracking/sessions

How identity attaches to events automatically across hosts — sessionId, visitorId, externalUserId — how to read each, and how to link back to a session later.

<Note>
  **Platform feature.** Requires `WANIWANI_API_KEY` on the server. [About the Platform](/sdk/platform/overview).
</Note>

A session represents one conversation between a user and an MCP client or the chat widget. Events are grouped into a session by a `sessionId`, and on every SDK surface except the top-level backend client that id attaches to your events automatically. You read it when you need to link a session to your own systems; you almost never pass it.

## Identity: three ids, any one will do

Every event is attributed by **one or more** of three correlation ids. The ingest API accepts an event that carries any one of them and rejects an event that carries none:

| Id               | What it identifies            | Lifetime                                                     |
| ---------------- | ----------------------------- | ------------------------------------------------------------ |
| `sessionId`      | One conversation              | Created when a conversation starts; ends with it             |
| `visitorId`      | One anonymous browser/device  | Persists across visits, before and without any session       |
| `externalUserId` | A known user in *your* system | Whatever id you already keep (db id, Stripe customer, email) |

You rarely choose between them. Each host provides whatever identity it natively has, the SDK maps it for you, and you read whichever is present:

| Host                                     | `sessionId`                  | `visitorId` | `externalUserId`                                |
| ---------------------------------------- | ---------------------------- | ----------- | ----------------------------------------------- |
| **Web chat** (widget / `<script>` embed) | ✅ once a conversation starts | ✅ always    | when you `identify()`                           |
| **ChatGPT app**                          | ✅                            | —           | ✅ ChatGPT's anonymous user id (`openai/userId`) |
| **Claude / other MCP client**            | ✅ transport session          | —           | when you `identify()`                           |
| **Backend / scripts**                    | you pass it                  | —           | you pass it                                     |

`visitorId` exists only on the web, because it is a browser-side construct; the chat embed sends it on every request, so a web event is always attributable even before its first message mints a session. On ChatGPT and Claude there is no `visitorId` — the host's own session (and, for ChatGPT, an anonymous user id) carries attribution instead. The practical rule for reading identity in server code: `waniwani.visitorId ?? waniwani.externalUserId ?? waniwani.sessionId` — take whatever the current host gives you.

## Where the session id comes from

| Surface              | Origin of the id                                                                               | How events get it                                                 |
| -------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| MCP tool / flow node | The host's request meta, or the `Mcp-Session-Id` transport header bridged in by `withWaniwani` | The scoped client (`context.waniwani`) merges it into every event |
| MCP-app widget       | Injected by `withWaniwani` into tool response `_meta["waniwani/widget"]`                       | `useWaniwani()` stamps it on every event                          |
| Chat widget          | Assigned by the chat server on the first exchange (`x-session-id` response header)             | `chat.track` reads it live on every call                          |
| Backend / scripts    | You                                                                                            | Pass `sessionId` (or `externalUserId`) on the call                |

Inside `_meta`, the SDK reads the first non-empty string among `waniwani/sessionId`, `openai/sessionId`, `openai/session`, `sessionId`, `conversationId`, and `mcp-session-id`. When the host only carries a transport-level session (the `Mcp-Session-Id` header), `withWaniwani` promotes it into `_meta.waniwani/sessionId` so everything downstream sees it. You do not deal with any of this directly.

## Reading the ids

Every surface exposes the resolved ids so you can persist them and attribute later activity back to the conversation. In a flow node or tool handler the scoped client exposes all three — read whichever the host provides:

```ts theme={null}
// In a flow node or tool handler
.addNode("qualify", async ({ state, waniwani }) => {
  await crm.updateLead(state.leadId, {
    chatSession: waniwani?.sessionId,
    visitor: waniwani?.visitorId,          // present on web, undefined elsewhere
    userId: waniwani?.externalUserId,      // present once identified / on ChatGPT
  });
  return {};
})
```

```tsx theme={null}
// In an MCP-app widget
const wani = useWaniwani();
console.log(wani.sessionId);
```

```js theme={null}
// On a chat host page
WaniWani.chat.getSessionId();          // undefined until the first message
```

```tsx theme={null}
// With the React chat component
const ref = useRef<ChatHandle>(null);
ref.current?.sessionId;
```

The `<script>` embed's `onEvent` callback also carries `sessionId` on every lifecycle event, which is the easiest way to mirror it into your own analytics.

## Linking back to a session later

The point of reading the id: a conversion that happens days later, outside the conversation, can still land in the right session. Store the id during the conversation, then send the event from your backend with it:

```ts theme={null}
// Later, in your billing webhook
import { client } from "./lib/waniwani";

await client.track.converted({
  amount: 85,
  currency: "EUR",
  sessionId: lead.chatSession,          // the id you stored from waniwani.sessionId
  occurredAt: "2026-06-09T10:00:00Z",
});
```

`externalUserId` works the same way when you identified the user instead of storing the session (see [Identify](/sdk/tracking/identify)). Use whichever id your system already keeps.

## Anonymous visitors

The web `visitorId` is a stable, opaque id persisted in the browser (`localStorage`), minted synchronously on first use so it is present on the very first event or chat request — no async, no dependency on a secure context. `page.viewed` carries **only** a `visitorId`, deliberately, so landings do not mint sessions and the "landed vs. started a conversation" funnel stays meaningful.

### Bring your own visitor id

Override the auto-generated id with one your site already tracks (a PostHog / Amplitude / Segment distinct id, your own cookie). Waniwani then correlates to the same visitor your analytics sees, and your server code reads the id back as `waniwani.visitorId`, so a flow or tool can push events to the same analytics tool the id came from. On the `<script>` embed, set `data-visitor-id` or call `WaniWani.chat.setVisitorId(id)` once your analytics SDK is ready; with the React component, pass the `visitorId` prop. Full recipes: [Link visitors to your analytics](/sdk/chat/embed#link-visitors-to-your-analytics).

## Manual session ids

For background jobs, backfills, or tests where no surface provides an id, set `sessionId` explicitly:

```ts theme={null}
await client.track.converted({
  amount: 4999,
  currency: "USD",
  sessionId: "session_01HX...",
});
```

<Warning>
  Inside tool handlers, flow nodes, widgets, and the chat embed, never pass `sessionId` manually. The surface already carries it; a manual value can only disagree with the real one.
</Warning>

## Session lifecycle

The Waniwani backend emits `session.started` the first time it sees a new `sessionId`. You never send it yourself. Sessions have no hard close; the backend treats them as closed after an idle window. A returning user either resumes the same session (within the window) or starts a fresh one, depending on what the host client sends.


# Widgets & chat
Source: https://docs.waniwani.ai/sdk/tracking/widgets

Track funnel events from MCP-app widgets and chat host pages with the same client the server uses.

<Note>
  **Platform feature.** The browser surfaces authenticate with credentials they already hold: a widget token injected by `withWaniwani`, or the chat widget's public `wwp_...` token. No API key ships to the browser. [About the Platform](/sdk/platform/overview).
</Note>

Widgets are where funnel steps actually happen: the user compares plans, picks an option, clicks the buy link. Both browser surfaces expose the same `track` client as the server, with session identity attached automatically.

## MCP-app widgets: `useWaniwani()`

For widgets rendered inside tool responses (ChatGPT apps, Claude MCP apps). Requirements: the MCP server is wrapped with `withWaniwani(server)`, which injects the tracking endpoint, a short-lived widget token, and the session id into each tool response under `_meta["waniwani/widget"]`.

`useWaniwani()` is host-agnostic: it takes that metadata as data and opens no connection to the widget host itself. How you hand it the metadata depends on your host.

**skybridge-hosted widgets.** Import the hook from the skybridge adapter entry and call it bare. It reads skybridge's `useToolInfo().responseMetadata` and feeds it to the hook for you:

```tsx theme={null}
import { useWaniwani } from "@waniwani/sdk/mcp/react/skybridge";

function PlanPicker({ plans }) {
  const wani = useWaniwani();

  return plans.map((plan) => (
    <button
      key={plan.id}
      onClick={() =>
        wani.track.optionSelected({ id: plan.id, amount: plan.price, currency: "EUR" })
      }
    >
      {plan.name}
    </button>
  ));
}
```

`skybridge` is an optional peer dependency of the SDK; a skybridge project already has it.

**Any other host.** Import from `@waniwani/sdk/mcp/react` and pass the tool-response `_meta` your host exposes as `toolResponseMetadata`:

```tsx theme={null}
import { useWaniwani } from "@waniwani/sdk/mcp/react";

const wani = useWaniwani({ toolResponseMetadata });
```

The returned widget surface:

| Member                      | What it does                                                                                    |
| --------------------------- | ----------------------------------------------------------------------------------------------- |
| `track(event)`              | Send any typed event, session attached: `track({ event: "link.clicked", properties: { url } })` |
| `track.priceShown()` etc.   | The five flat revenue helpers, same as the server                                               |
| `identify(userId, traits?)` | Emits `user.identified` and stamps `externalUserId` on later events                             |
| `sessionId`                 | The id stamped on this widget's events, for correlating with your own systems                   |
| `flush()`                   | Flush buffered events immediately                                                               |

One `widget_render` event is emitted automatically when the hook initializes with resolved config, so "widget shown" exists as a funnel step even if you track nothing manually.

With no resolved endpoint and source (no metadata, no explicit options), the hook returns a no-op widget, so rendering never breaks.

### Explicit configuration

When the widget cannot resolve config from the host (or you proxy events through your own backend), pass the endpoint directly. `source` is required in this mode so events attribute to a channel:

```tsx theme={null}
const wani = useWaniwani({
  endpoint: "https://yourapp.com/api/waniwani/track",
  source: "web",
});
```

Pair this with [`createTrackingRoute`](/sdk/configuration/wrap-server) on your backend when you want zero Waniwani credentials in the browser.

## Chat host pages: `chat.track`

The chat embed and `WaniwaniChat` hold the public token and the server-assigned session, so the host page can send funnel events with zero setup. Events carry the `sessionId` once the first exchange assigns one, and the anonymous `visitorId` before that.

With the `<script>` embed:

```html theme={null}
<script>
  document.querySelector("#buy").addEventListener("click", () => {
    WaniWani.chat.track.converted({ amount: 85, currency: "EUR" });
  });

  // When your page knows who the user is:
  WaniWani.chat.identify("user_123", { plan: "pro" });
</script>
```

With the React component, the same surface lives on the ref handle:

```tsx theme={null}
import { useRef } from "react";
import { WaniwaniChat, type ChatHandle } from "@waniwani/sdk/chat";

function Page() {
  const chat = useRef<ChatHandle>(null);

  return (
    <>
      <WaniwaniChat ref={chat} token="wwp_..." channelId="51c3658a-..." />
      <button onClick={() => chat.current?.track?.optionSelected({ id: "pro", amount: 49, currency: "EUR" })}>
        Choose Pro
      </button>
    </>
  );
}
```

`track` and `identify` are absent on the bare `ChatEmbed` primitive, which is bring-your-own-backend and holds no Waniwani credential.

To mirror chat lifecycle events (opened, closed, message sent/received) into your own analytics instead, use the embed's `onEvent` callback; it runs in the page's JS context and carries the `sessionId`.

## Custom surfaces: `createFrontendClient`

Both surfaces above are wrappers around one primitive, exported for anything they do not cover:

```ts theme={null}
import { createFrontendClient } from "@waniwani/sdk";

const client = createFrontendClient({
  endpoint: "https://app.waniwani.ai/api/mcp/events/v2/batch",
  token: "wwp_...",                        // public token or widget JWT
  source: "web",
  identity: () => ({ sessionId: currentSessionId, visitorId }),
});

await client.track.priceShown({ amount: 49, currency: "EUR" });
```

It shares the server client's mapper and batching transport, adds keepalive flushing on page hide/unload, and reads `identity()` at emit time so late-arriving ids (a session assigned mid-page) are picked up without recreating the client.

## Delivery behavior

* Events batch in memory and flush on a short timer, on batch size, and with `keepalive` requests when the page is hidden or unloading.
* Tracking never throws into the host page; failures are logged and dropped.
* On an auth failure (expired widget token, revoked public token) the transport stops and logs the reason once, instead of retrying forever.


# Why MCP funnels
Source: https://docs.waniwani.ai/sdk/why-mcp-funnels

Why ChatGPT, Claude, and Cursor change distribution, and why conversational funnels are the new web forms.

A distribution shift is underway. ChatGPT, Claude, and Cursor are becoming the new browsers. MCP is the store. The way users find products, get qualified, book, and buy is moving from web forms inside web pages to conversational funnels inside AI clients.

This page explains why we believe that, and why `@waniwani/sdk` exists.

## The distribution shift

For twenty years the web ran on the same loop: a user lands on a page, fills a form, gets routed to the next step. Sales funnels, lead generation, booking, quoting. Money moved through forms.

That loop is moving. The interface a user starts a buying journey in is increasingly an AI client, not a browser tab. ChatGPT, Claude, and Cursor are where attention concentrates. MCP is the protocol those clients use to call third-party tools. From the user's perspective: they describe what they want, the AI client calls your MCP server, your server runs the funnel.

The implications are not subtle:

* **One server, every surface.** One MCP server reaches ChatGPT, Claude, Cursor, and any other MCP-capable client. One edit to your messaging deploys everywhere.
* **No website, no form, no chatbot widget.** The funnel runs inside the AI client the user already uses.
* **The funnel is a tool call.** The same tool call drives the conversation, validates input, branches, persists state.

## Conversational funnels are the new web forms

The shape of the work has not changed. A funnel still has steps. A booking funnel still asks for a service, a slot, and a confirmation. An insurance funnel still collects details, validates, and returns a quote. A lead funnel still captures email, role, and use case.

What changes is the rendering surface. The funnel runs inside an AI client. The model is the front-end. The funnel logic still lives on your server.

This is good news: the business outcomes you care about (qualified leads, booked appointments, returned quotes, completed purchases) translate directly. It is bad news only if you assume the AI client will run the funnel for you. It will not.

## Why LLMs cannot run funnels on their own

A funnel needs five things:

1. **Deterministic order.** Steps run in a known sequence.
2. **Typed fields.** Email is an email, date is a date.
3. **Validation.** Bad input is rejected and re-asked.
4. **Branching.** The next step depends on the current answer.
5. **Resumable state.** Every step builds on the last, across many tool calls.

LLMs left to themselves do none of these reliably. They paraphrase questions, skip fields, accept malformed input, drop state between turns. This is not a bug in the model. It is a mismatch: a stateless system cannot run a stateful process.

The fix is to make the funnel deterministic on the server, and let the model do what it is good at: rendering the next question, interpreting the answer, handing back to the server.

## Why generic agent frameworks are not the right fit

Frameworks like LangChain and LangGraph are general-purpose agent builders. They expose every primitive: graphs, tools, memory, retrievers, planners. You can build a funnel on top of them. You can also build a database on top of `malloc`.

The cost is that every funnel ergonomic (interrupt on a missing field, re-ask on validation failure, skip a step whose state is already known, hand off to a widget for confirmation, persist state under the MCP session id) is something you re-invent on every project. The frameworks give you the road. They do not give you the car.

`createFlow` is funnel-shaped by design. A node is a step. An interrupt is a form field. An edge is a transition. A conditional edge is a branching question. Typed state via Zod is your lead data. The graph compiles to one MCP tool. The engine runs it.

See [Waniwani vs LangGraph](/sdk/compare/vs-langgraph) for a direct comparison.

## Production-validated

We did not start with this abstraction. We arrived at it.

`@waniwani/sdk` is forked from internal distribution MCPs we shipped for paying customers: insurance quoting, pet care, lead capture, booking. We hit the same pattern enough times to extract it, and open-sourced once the shape stabilized.

The hosted tier (analytics, KV store, embeddable widgets, knowledge base) is opt-in via a single env var. The engine works standalone with any get/set/delete backend.

## What this means for you

If you are building distribution into AI clients, you have three options:

1. **Hand-roll on the raw MCP SDK.** You serialize state through the model on every turn. The model forgets, paraphrases, skips. You re-invent re-ask, validation, and branching on every project.
2. **Build on a generic agent framework.** You get graph primitives but write all the funnel ergonomics yourself.
3. **Use `createFlow`.** You declare state, nodes, and edges. The engine handles interrupts, validation, branching, and resumption, and compiles to one MCP tool.

This SDK exists because we believe option three should be the default. The funnel is the unit of distribution in the AI era, and the abstraction should be funnel-shaped.

## Next

<CardGroup>
  <Card title="Quickstart" icon="play" href="/sdk/quickstart">
    Boot a flow-driven MCP server in 60 seconds.
  </Card>

  <Card title="Build a funnel" icon="filter" href="/sdk/guides/funnels">
    Sales funnels, lead gen, booking, quote flows.
  </Card>

  <Card title="vs LangGraph" icon="scale-balanced" href="/sdk/compare/vs-langgraph">
    Direct comparison with LangChain's graph framework.
  </Card>

  <Card title="Flow engine" icon="diagram-project" href="/sdk/flows/overview">
    Nodes, edges, interrupts, conditional branching.
  </Card>
</CardGroup>