waniwani-sdk

name: waniwani-sdk description: "MCP distribution SDK: build sales funnels, lead generation, booking flows, insurance quote flows, pricing quote flows, and any multi-step conversational MCP app with @waniwani/sdk. Open source createFlow engine (no API key required) with pluggable state backends (in-memory, Redis, Upstash, Cloudflare KV, DynamoDB, or hosted). Optional free tier adds a revenue-first event taxonomy (track leads, prices shown/compared, options selected, and conversions — including off-platform purchases), funnel analytics, knowledge base, and a chat widget. Trigger when the user wants to add an MCP funnel, sales funnel, lead gen flow, booking flow, quote flow, knowledge base / FAQ tool, or embedded chat to an MCP server — or to instrument tracking on a @waniwani/sdk app: emit or track events, record a conversion or revenue, attribute an off-platform purchase back to a lead, or measure where users drop off in a funnel." license: MIT metadata: author: Waniwani

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. Open-source flow engine, with an optional free tier for hosted state, event tracking, funnel analytics, knowledge base, and a playground. The split:

• Open source — createFlow, StateGraph, the KvStore interface, MemoryKvStore. Runs with no API key against any state backend you implement.
• Free tier — set WANIWANI_API_KEY to unlock hosted flow state, event tracking, funnel analytics, knowledge base, and the dashboard playground.

Docs: docs.waniwani.ai Dashboard: app.waniwani.ai

Install

bun add @waniwani/sdk

Core flow engine has no required runtime dependencies. Peer dependencies (@modelcontextprotocol/sdk, zod, etc.) vary by entry point — see the export table below.

Quick start — open source path

For developers who want pure OSS with no telemetry:

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"),
    useCase: z.string().describe("What they want to build"),
  },
})
  .addNode("ask_email", ({ interrupt }) =>
    interrupt({ email: { question: "What's your work email?" } })
  )
  .addNode("ask_use_case", ({ interrupt }) =>
    interrupt({ useCase: { question: "What do you want to build?" } })
  )
  .addEdge(START, "ask_email")
  .addEdge("ask_email", "ask_use_case")
  .addEdge("ask_use_case", END)
  .compile({ store: new MemoryKvStore() });

await onboardingFlow.register(server);

MemoryKvStore is fine for dev/tests. For production self-hosting, see kv-store.md for Redis, Upstash, Cloudflare KV, and DynamoDB adapters.

Quick start — free tier path

Same code, hosted features added:

# .env
WANIWANI_API_KEY=wwk_...

// Drop the `store` argument — flow state now lives on app.waniwani.ai
const flow = createFlow({ /* …same… */ }).compile();

// Optional: auto-track every tool call
import { withWaniwani } from "@waniwani/sdk/mcp";
withWaniwani(server);

Get a free key at app.waniwani.ai. See setup.md for full configuration.

Export paths

Tier reference

Open source (no API key required)

createFlow plus its supporting types. Drives multi-step conversations: pause on interrupts, branch on conditions, persist state across calls. Compiles into a single MCP tool the model invokes.

State persistence is pluggable through the KvStore interface. Built-in:

• MemoryKvStore — in-process Map, dev only
• WaniwaniKvStore — hosted (free tier; selected automatically when API key is set)

Or write a 10-line adapter for any backend. See kv-store.md.

If no { store } is passed and WANIWANI_API_KEY is not set, .compile() throws with a clear error pointing at the fix. No silent fallback.

Free tier (one env var: WANIWANI_API_KEY)

Adds hosted features on top of the OSS flow engine.

• Hosted flow state — WaniwaniKvStore used by default when no { store } is passed.
• Event tracking — a typed, revenue-first funnel taxonomy (lead → price_shown / prices_compared / option_selected → converted) via flat track.* helpers; withWaniwani(server) auto-captures tool.called. Off-platform conversions correlate by externalUserId. See events.md.
• Knowledge base — createKbClient() for ingest/search.
• Funnel analytics — flow graphs auto-sync to the dashboard.
• Chat widget — ChatEmbed talks directly to app.waniwani.ai.

withWaniwani(server) is safe to call with or without an API key — its auto-captured tool.called events are internally guarded, and session-ID bridging and widget metadata forwarding still happen. Your own tracking calls are not guarded: client.track.*, identify(), and the scoped context.waniwani throw WANIWANI_API_KEY is not set when no key is configured, so guard them in code paths that must also run keyless. See events.md.

Legacy

The following are still exported for back-compat with existing customer MCPs but are no longer documented for new code: createTool, createResource, registerTools, toNextJsHandler, toExpressJsHandler, createApiHandler, all MCP-widget React hooks (WidgetProvider, useWidgetClient, useToolOutput, etc.) except useWaniwani, InitializeNextJsInIframe, LoadingWidget, DevModeProvider, detectPlatform, isMCPApps, isOpenAI.

Never recommend these for new code. They will move to dedicated @waniwani/sdk/legacy* entry points in a future minor release. Existing apps using them keep working.

@waniwani/sdk/evals has been removed entirely — see legacy/evals.

Reading guide

Guided playbooks

When a playbook exists for the user's task, follow the playbook step by step instead of writing code directly. The playbooks include prerequisite checks, interactive design steps, and testing instructions.

Upgrading the SDK

@waniwani/sdk is 0.x, so minor version bumps can break the public API. Whenever you raise the SDK version in a project — editing package.json, running bun add @waniwani/sdk@latest, or fixing a build that started failing after an upgrade — do not treat it as a drop-in. Read the changelog for every breaking change between the old and new version and auto-apply the documented migration (each one is a mechanical codemod), then run bun run typecheck && bun test. Full procedure in upgrading.md.

Common mistakes

• createFlow().compile() throws "no flow store configured" — Pass { store: new MemoryKvStore() } to .compile() for dev, or set WANIWANI_API_KEY for the hosted store, or pass a custom KV adapter.
• Creating multiple clients — Create one waniwani() in lib/waniwani.ts and import everywhere.
• Wrong import paths — Flow primitives + KV: @waniwani/sdk/mcp. useWaniwani: @waniwani/sdk/mcp/react. Chat widget: @waniwani/sdk/chat.
• Forgetting START/END edges — Every flow needs addEdge(START, firstNode) and addEdge(lastNode, END).
• Calling interrupt/showWidget directly — These come from the handler context: ({ interrupt }) => interrupt(...).
• Suggesting createTool / createResource for new code — These are legacy. Use createFlow instead. They remain exported only for back-compat.