Waniwani SDK (@waniwani/sdk)

The MCP distribution SDK. Build sales funnels, lead generation, booking, insurance quote, and pricing quote apps on top of your MCP server.

Read the docs before you write code

This file is a map, not a manual. The full, current documentation lives at docs.waniwani.ai/sdk/introduction and it is the only source of truth for API shapes, option names, event properties, and version behavior. The SDK is 0.x and moves fast, so anything you remember about it may already be wrong.

Before you answer an API question or write a line of @waniwani/sdk code, fetch the relevant docs page from the map below. When this file and the docs disagree, the docs win.

If you can fetch only one thing, fetch docs.waniwani.ai/llms.txt: it is the complete page index, always current, and cheap to read.

Where things live in the docs

Dashboard and free API key: app.waniwani.ai.

The one thing to get right without fetching: the tier split

• Open source, no API key. createFlow, StateGraph, START, END, the KvStore interface, MemoryKvStore. Runs against any state backend you implement.
• Free tier, one env var (WANIWANI_API_KEY). Same SDK, plus hosted flow state, event tracking, funnel analytics, knowledge base, email, chat widget, and the dashboard playground.

Default to the OSS path. Reach for the free tier when the user asks for tracking, analytics, hosted state, KB, or chat, and say plainly that it needs a key.

Minimal shape, enough to orient yourself before you fetch the flow docs:

import { createFlow, MemoryKvStore, START, END } from "@waniwani/sdk/mcp";
import { z } from "zod";

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"),
  },
})
  .addNode("ask_email", ({ interrupt }) =>
    interrupt({ email: { question: "What's your work email?" } })
  )
  .addEdge(START, "ask_email")
  .addEdge("ask_email", END)
  .compile({ store: new MemoryKvStore() });

await onboardingFlow.register(server);

Drop the { store } argument once WANIWANI_API_KEY is set and flow state moves to app.waniwani.ai. With neither a store nor a key, .compile() throws and tells you how to fix it. There is no silent fallback.

Removed surfaces

Changed in 0.24.0: a flow's tool listing no longer names state fields under stateUpdates, and flow.config._meta no longer types or sends _flowGraph (read flow.flowGraph). In 0.24.0 to 0.24.2, start merges no stateUpdates, and continue and reset merge only fields the run has asked. npx skills add Waniwani-AI/sdk -s migrate-waniwani-sdk-0.23-to-0.24 applies the migration.

Changed in 0.25.0: the session's first question or widget lists every state field in fields, and any call writes a declared field whose value fits its schema, including one no question asks. Everything in state is exposed that way, so a lookup id or price the user must not choose stays out of state (key it by ctx.sessionId in your own store). Wrap a consent or a must-see widget pick in neverPrefilled(schema) so only an answer to its own question counts. npx skills add Waniwani-AI/sdk -s migrate-waniwani-sdk-0.24-to-0.25 applies the migration, from 0.24.x or straight from 0.23.x.

Removed in 0.23.0: withWaniwani's captureTelemetry option and the CaptureTelemetryOptions type. Use captureIntent / CaptureIntentOptions. Wrapped tools now advertise one optional intent string instead of a telemetry object. npx skills add Waniwani-AI/sdk -s migrate-waniwani-sdk-0.22-to-0.23 applies the migration.

Removed in 0.20.0. An import error for any of these means the code is on a pre-0.20 pattern: createTool, createResource, registerTools, toNextJsHandler, toExpressJsHandler, createApiHandler, ChatCard, every MCP-widget React hook except useWaniwani (WidgetProvider, useWidgetClient, useToolOutput, and the rest), InitializeNextJsInIframe, LoadingWidget, DevModeProvider, detectPlatform, isMCPApps, isOpenAI.

The @waniwani/sdk/legacy, @waniwani/sdk/legacy/react, @waniwani/sdk/legacy/next-js, @waniwani/sdk/legacy/express-js, @waniwani/sdk/chat/server, @waniwani/sdk/next-js, and @waniwani/sdk/express-js entry points no longer exist.

Use createFlow for multi-step tools, server.registerTool for single-shot ones, and WaniwaniChat for chat. npx skills add Waniwani-AI/sdk -s migrate-waniwani-sdk-0.19-to-0.20 applies the whole migration.

@waniwani/sdk/evals was removed entirely. See the changelog.

Upgrading

@waniwani/sdk is 0.x, so minor bumps can break the public API. Whenever you raise the version in a project, whether by editing package.json, running bun add @waniwani/sdk@latest, or chasing a build that started failing, do not treat it as a drop-in.

1. Read the changelog, starting at the Breaking changes at a glance table, then every ## <version>: section above your old version and at or below your new one.
2. Apply each documented migration. They are written as mechanical codemods, so apply them rather than paraphrasing them.
3. Run bun run typecheck && bun test.

Every version hop also ships a self-contained migration skill you can invoke directly, named migrate-waniwani-sdk-<from>-to-<to>. For the latest release:

npx skills add Waniwani-AI/sdk -s migrate-waniwani-sdk-0.24-to-0.25

Guided playbooks

When a playbook covers the user's task, follow it step by step instead of writing code directly. Each one includes prerequisite checks, interactive design steps, and testing instructions.

Two sibling skills handle tracking work end to end:

npx skills add Waniwani-AI/sdk -s instrument-tracking   # add funnel events across existing flows
npx skills add Waniwani-AI/sdk -s audit-tracking        # read-only audit of an app's instrumentation

Common mistakes

• createFlow().compile() throws "no flow store configured": pass { store: new MemoryKvStore() } for dev, set WANIWANI_API_KEY for the hosted store, or pass your own KV adapter.
• Creating multiple clients: create one waniwani() in lib/waniwani.ts and import it everywhere.
• Wrong import paths: flow primitives and KV come from @waniwani/sdk/mcp, useWaniwani from @waniwani/sdk/mcp/react, the chat widget from @waniwani/sdk/chat.
• Forgetting START / END edges: every flow needs addEdge(START, firstNode) and addEdge(lastNode, END).
• Adding a first node just to greet the user or state a GDPR notice: an opening node is skipped once its fields are filled, by an earlier action or by an answer the user gave up front, so that message may never land. Use intro on the flow config instead (/sdk/flows/intro).
• Writing instructions into createFlow({ description }): the description is the whole consent card a ChatGPT user approves. Numbered protocols, Do NOT, You MUST call X first and other attempts to steer the model get flagged as a Suspicious Instruction on that card. Describe what the flow does in a sentence or two; the engine puts the protocol on each response as nextStep (/sdk/reference/flow-tool-contract).
• Calling interrupt / showWidget directly: they come from the handler context, ({ interrupt }) => interrupt(...).
• Answering from memory: if you have not fetched the docs page for what you are writing, fetch it.