@waniwani/sdk 0.11.11 → 0.11.13

package/README.md

@@ -3,148 +3,114 @@
 [![npm](https://img.shields.io/npm/v/@waniwani/sdk.svg)](https://www.npmjs.com/package/@waniwani/sdk)
 [![license](https://img.shields.io/npm/l/@waniwani/sdk.svg)](./LICENSE)
 
-> The official SDK for [WaniWani](https://waniwani.ai). Build, ship, and measure conversational MCP apps.
+> Open-source SDK for building **MCP funnels**: sales funnels, lead generation, booking, and quote flows that run as a single MCP tool inside ChatGPT, Claude, Cursor, and any MCP-capable client.
 
-`@waniwani/sdk` is the developer-facing library for your MCP (Model Context Protocol) server. It provides **event tracking** and **multi-step conversational flows**.
+An **MCP funnel** is a multi-step conversation, hosted on your MCP server, that drives a user or agent from intent to outcome (a qualified lead, a booking, a quote, a purchase). One typed state graph compiles to one MCP tool. MIT licensed, bring your own store, optional hosted tier.
 
-- **Zero runtime dependencies.** Sub-5KB core bundle, safe for serverless and edge runtimes.
-- **Works with any MCP runtime.** [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk), [Skybridge](https://github.com/alpic-ai/skybridge), [`@vercel/mcp-handler`](https://www.npmjs.com/package/@vercel/mcp-handler).
-- **Fully typed.** Zod state schemas, inferred node contexts, typed event properties.
-- **Automatic tool tracking.** One call to `withWaniwani(server)` and every tool invocation is tracked.
-- **LangGraph-inspired flows.** Compile a state graph into a single MCP tool that drives multi-turn conversations.
+## Why this exists
 
-> **Status:** pre-alpha. APIs and behavior may change between releases. Pin versions in production.
+- **ChatGPT, Claude, and Cursor are the new browsers. MCP is the store.** One edit to your messaging deploys to every MCP-capable client and your own site.
+- **Conversational funnels are the new web forms.** They are where money will be made in the AI-distribution era. Recreating a real funnel inside MCP is harder than it looks.
+- **LLMs are not built to replicate forms.** Left to themselves, they rush through structured collection: they skip fields, paraphrase questions, and break validation. A real funnel needs deterministic order, typed fields, validation, branching, and resumable state across tool calls.
+- **Generic agent builders are not shaped for funnels.** LangChain and LangGraph are general-purpose. They expose every primitive, leaving you to re-invent funnel ergonomics (interrupts, re-ask on error, auto-skip pre-filled fields, widget cards, deterministic step order) on every project.
+- **`createFlow` is the missing abstraction.** A typed state graph (Zod-typed state, named nodes, direct and conditional edges, interrupts, widget signals) compiles to a single MCP tool. Funnel-shaped by design, not by convention.
+- **Production-validated.** Forked out of internal distribution MCPs we shipped for paying customers (insurance quoting, pet care, lead capture, booking). Open-sourced once we hit the same pattern enough times.
 
-## Install
+## What you can build today
 
-```bash
-bun add @waniwani/sdk
-# or
-pnpm add @waniwani/sdk
-# or
-npm install @waniwani/sdk
-# or
-yarn add @waniwani/sdk
-```
-
-Requires Node 18.17+ and an MCP server runtime.
-
-## Quick start
+- **[Sales funnel MCP](https://docs.waniwani.ai/guides/sales-funnel)**. Qualify intent, capture lead data, branch on stage, push to CRM.
+- **[Lead generation MCP](https://docs.waniwani.ai/guides/lead-generation)**. Collect email, role, use case. Webhook to your CRM.
+- **[Booking MCP](https://docs.waniwani.ai/guides/booking)**. Pick a service, check availability, pick a slot, confirm.
+- **[Insurance or pricing quote MCP](https://docs.waniwani.ai/guides/insurance-quote)**. Collect details, validate, call your pricing API, return widget cards.
 
-### 1. Get an API key
+Any other multi-step MCP tool where order, validation, and resumability matter.
 
-Sign in to [app.waniwani.ai](https://app.waniwani.ai), create an MCP environment, and copy its API key. Keys are prefixed with `wwk_` and shown in full only once. Expose it to your server as `WANIWANI_API_KEY`:
+## 30-second example
 
 ```bash
-# .env
-WANIWANI_API_KEY=wwk_...
+bun add @waniwani/sdk @modelcontextprotocol/sdk zod
 ```
 
-### 2. Wrap your MCP server
-
 ```ts
-import express from "express";
-import { withWaniwani } from "@waniwani/sdk/mcp";
+// hello.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import "dotenv/config";
-
-const server = new McpServer({ name: "my-mcp-app", version: "0.0.1" });
-
-server.registerTool(/* ... your tools ... */);
-
-// One call. Every registered tool is now tracked automatically.
-withWaniwani(server);
-
-// Connect the Streamable HTTP transport
-const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-await server.connect(transport);
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createFlow, END, MemoryKvStore, START } from "@waniwani/sdk/mcp";
+import { z } from "zod";
 
-const app = express();
-app.use(express.json());
-app.post("/mcp", (req, res) => transport.handleRequest(req, res, req.body));
-app.listen(3000);
+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: () => ({ 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());
 ```
 
-Every tool call produces a `tool.called` event with duration, status, input/output, and session correlation, all visible in your WaniWani dashboard within seconds.
-
-### 3. Track custom events
-
-```ts
-import { waniwani } from "@waniwani/sdk";
-
-const wani = waniwani();
-
-await wani.track({
-  event: "quote.succeeded",
-  properties: { amount: 99, currency: "USD" },
-  meta: extra._meta, // correlates the event with the current MCP session
-});
+```bash
+bun run hello.ts
 ```
 
-### 4. Build a flow
+That is a complete MCP server with one flow-driven tool, runnable over stdio. Connect it to ChatGPT, Claude, or any MCP client.
 
-Multi-turn conversations, compiled into a single MCP tool:
+For production, swap `MemoryKvStore` for a real backend (Redis, Upstash, Cloudflare KV, DynamoDB, anything with `get` / `set` / `delete`), or set `WANIWANI_API_KEY` for hosted state plus tracking, funnel analytics, knowledge base, and a chat widget. Same code.
 
-```ts
-import { createFlow, END, START } from "@waniwani/sdk/mcp";
-import { z } from "zod";
+## How WaniWani compares
 
-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("ask_email", async ({ interrupt }) =>
-    interrupt({ email: { question: "What's your work email?" } }),
-  )
-  .addNode("ask_use_case", async ({ 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();
-
-await onboardingFlow.register(server);
-```
+**vs. LangChain / LangGraph.** General-purpose agent graphs. WaniWani is funnel-shaped: interrupts, re-ask on validation, auto-skip pre-filled fields, widget delegation, typed state via Zod. Smaller surface, sharper fit for MCP funnels.
 
-The engine handles state persistence, resumption, branching, and validation. The model calls one tool and the rest is managed server-side.
+**vs. hand-rolling on the raw MCP SDK.** You would serialize state through the model on every turn. WaniWani persists state server-side under the session id, so the model carries nothing between calls.
 
-## Documentation
+**vs. closed-source platform SDKs.** MIT licensed. The flow engine has zero runtime dependency on `app.waniwani.ai`. Bring any KV backend. The hosted tier is opt-in via `WANIWANI_API_KEY` and unlocks tracking, KB, chat widget, and managed flow state without changing your code.
 
-Full product documentation lives at **[docs.waniwani.ai](https://docs.waniwani.ai)**:
+## Two tiers
 
-- [Introduction](https://docs.waniwani.ai/introduction)
-- [Quickstart](https://docs.waniwani.ai/quickstart)
-- [Setup](https://docs.waniwani.ai/setup/installation)
-- [Event Tracking](https://docs.waniwani.ai/tracking/overview)
-- [Flows](https://docs.waniwani.ai/flows/overview)
+| Surface | Tier | What you get |
+|---|---|---|
+| `createFlow`, `StateGraph`, `KvStore`, `MemoryKvStore` | **OSS** | Multi-step conversational flows, runnable with no API key |
+| `WaniwaniKvStore` | Free tier | Hosted, encrypted-at-rest flow state on `app.waniwani.ai` |
+| `withWaniwani`, `useWaniwani` | Both | Tool tracking, session bridging, browser hook (no-op without a key) |
+| `waniwani()`, `tracking`, `kb` | Free tier | Event tracking, funnel analytics, knowledge base |
+| `ChatWidget`, `ChatEmbed`, `embed.js` | Free tier | Embeddable chat UI |
 
-The same docs are also available in this repository under [`docs/`](./docs).
+Get a free key at [app.waniwani.ai](https://app.waniwani.ai).
 
-## What's inside the package
+## Documentation
 
-| Entry point               | What it gives you                                                              |
-| ------------------------- | ------------------------------------------------------------------------------ |
-| `@waniwani/sdk`           | `waniwani()` client: event tracking, identify, flush, shutdown.                |
-| `@waniwani/sdk/mcp`       | `withWaniwani`, `createFlow`, `createTool`, `createResource`, flow primitives. |
-| `@waniwani/sdk/mcp/react` | React hooks for WaniWani-powered widgets.                                      |
+Full docs at **[docs.waniwani.ai](https://docs.waniwani.ai)**. Same source as [`./docs/`](./docs) in this repo.
 
-Most users only need `@waniwani/sdk` and `@waniwani/sdk/mcp`.
+**Build something:**
+- [Sales funnel MCP](https://docs.waniwani.ai/guides/sales-funnel)
+- [Lead generation MCP](https://docs.waniwani.ai/guides/lead-generation)
+- [Booking MCP](https://docs.waniwani.ai/guides/booking)
+- [Insurance or pricing quote MCP](https://docs.waniwani.ai/guides/insurance-quote)
 
-## Examples
+**Learn the engine:**
+- [Quickstart](https://docs.waniwani.ai/quickstart)
+- [Flows overview](https://docs.waniwani.ai/flows/overview)
+- [KV store adapters](https://docs.waniwani.ai/flows/kv-store)
+- [Self-hosting](https://docs.waniwani.ai/deployment/self-hosting)
 
-- **[Alpic x WaniWani demo](https://github.com/WaniWani-AI/alpic-x-waniwani-demo)**: a Skybridge MCP server with a full `createFlow` booking journey.
+**Add the platform:**
+- [Tracking](https://docs.waniwani.ai/tracking/overview)
+- [Knowledge base](https://docs.waniwani.ai/knowledge-base/overview)
+- [Chat widget](https://docs.waniwani.ai/chat/embed)
 
 ## Links
 
@@ -157,4 +123,4 @@ Most users only need `@waniwani/sdk` and `@waniwani/sdk/mcp`.
 
 [MIT](./LICENSE) © WaniWani
 
-"WaniWani" is a trademark of WaniWani. The license covers the code, not the name.
+"WaniWani" is a trademark of WaniWani Inc. The license covers the code, not the name.