@waniwani/sdk 0.11.12 → 0.11.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +69 -102
  2. package/dist/chat/embed.js +65 -65
  3. package/dist/chat/embed.js.map +1 -1
  4. package/dist/chat/index.d.ts +8 -0
  5. package/dist/chat/index.js +7 -7
  6. package/dist/chat/index.js.map +1 -1
  7. package/dist/chat/styles.css +1 -1
  8. package/package.json +1 -1
package/README.md CHANGED
@@ -3,147 +3,114 @@
3
3
  [![npm](https://img.shields.io/npm/v/@waniwani/sdk.svg)](https://www.npmjs.com/package/@waniwani/sdk)
4
4
  [![license](https://img.shields.io/npm/l/@waniwani/sdk.svg)](./LICENSE)
5
5
 
6
- > Open-source SDK for MCP funnels. Build sales funnels, lead generation, booking, insurance quote, and pricing quote flows on top of your MCP server. Free hosted tier for analytics, knowledge base, and chat.
6
+ > 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.
7
7
 
8
- `@waniwani/sdk` turns your MCP server into a distribution surface. Build:
8
+ 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.
9
9
 
10
- - **Sales funnels and lead generation** — qualify leads, capture intent, route to the right step. Multi-step conversations compiled into a single MCP tool.
11
- - **Booking and reservation flows** — collect what you need, branch on conditions, confirm.
12
- - **Quote flows** (insurance, pricing, custom) — gather inputs, call your pricing API, return a quote, optionally render a widget.
13
- - **Knowledge base and embedded chat** — ground answers in your docs, ship a chat widget for your site.
10
+ ## Why this exists
14
11
 
15
- The SDK is split into two tiers:
12
+ - **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.
13
+ - **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.
14
+ - **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.
15
+ - **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.
16
+ - **`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.
17
+ - **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.
16
18
 
17
- - **Open source** — `createFlow` and the `KvStore` interface. LangGraph-inspired multi-step conversations, compiled into a single MCP tool. No API key needed. Plug in any state backend (in-memory, Redis, Upstash, Cloudflare KV) — or run pure self-hosted.
18
- - **Free tier** — add `WANIWANI_API_KEY` for hosted flow state, event tracking, funnel analytics, knowledge base, and a local playground. One env var. Same code.
19
+ ## What you can build today
19
20
 
20
- A separate [legacy section](#legacy) holds APIs we still ship for back-compat (`createTool`, `createResource`, chat-server adapters, MCP-widget React hooks) but no longer document for new code.
21
+ - **[Sales funnel MCP](https://docs.waniwani.ai/guides/sales-funnel)**. Qualify intent, capture lead data, branch on stage, push to CRM.
22
+ - **[Lead generation MCP](https://docs.waniwani.ai/guides/lead-generation)**. Collect email, role, use case. Webhook to your CRM.
23
+ - **[Booking MCP](https://docs.waniwani.ai/guides/booking)**. Pick a service, check availability, pick a slot, confirm.
24
+ - **[Insurance or pricing quote MCP](https://docs.waniwani.ai/guides/insurance-quote)**. Collect details, validate, call your pricing API, return widget cards.
21
25
 
22
- > **Status:** pre-alpha. APIs may change between releases. Pin versions in production.
26
+ Any other multi-step MCP tool where order, validation, and resumability matter.
23
27
 
24
- ## Quick start — open source (no API key)
28
+ ## 30-second example
25
29
 
26
30
  ```bash
27
- bun add @waniwani/sdk
31
+ bun add @waniwani/sdk @modelcontextprotocol/sdk zod
28
32
  ```
29
33
 
30
34
  ```ts
31
- // flow.ts
35
+ // hello.ts
36
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
37
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
32
38
  import { createFlow, END, MemoryKvStore, START } from "@waniwani/sdk/mcp";
33
39
  import { z } from "zod";
34
40
 
35
- export const onboardingFlow = createFlow({
36
- id: "onboarding",
37
- title: "User Onboarding",
38
- description: "Use when a new user wants to get started.",
39
- state: {
40
- email: z.string().describe("Work email"),
41
- useCase: z.string().describe("What they want to build"),
42
- },
41
+ const flow = createFlow({
42
+ id: "hello",
43
+ title: "Hello World",
44
+ description: "Say hello and ask a question.",
45
+ state: { name: z.string().describe("Your name") },
43
46
  })
44
- .addNode("ask_email", () =>
45
- interrupt({ email: { question: "What's your work email?" } }),
46
- )
47
- .addNode("ask_use_case", () =>
48
- interrupt({
49
- useCase: {
50
- question: "What do you want to build?",
51
- suggestions: ["Analytics", "Support", "Lead capture"],
52
- },
53
- }),
54
- )
55
- .addEdge(START, "ask_email")
56
- .addEdge("ask_email", "ask_use_case")
57
- .addEdge("ask_use_case", END)
47
+ .addNode({
48
+ id: "ask",
49
+ run: ({ interrupt }) =>
50
+ interrupt({ name: { question: "What's your name?" } }),
51
+ })
52
+ .addNode({
53
+ id: "greet",
54
+ run: () => ({ greeted: true }),
55
+ })
56
+ .addEdge(START, "ask")
57
+ .addEdge("ask", "greet")
58
+ .addEdge("greet", END)
58
59
  .compile({ store: new MemoryKvStore() });
59
60
 
60
- await onboardingFlow.register(server);
61
+ const server = new McpServer({ name: "hello-mcp", version: "1.0.0" });
62
+ await flow.register(server);
63
+ await server.connect(new StdioServerTransport());
61
64
  ```
62
65
 
63
- `MemoryKvStore` is fine for local dev and tests. For self-hosted production, implement the [`KvStore`](src/mcp/server/kv/kv-store.ts) interface against Redis, Upstash, Cloudflare KV, DynamoDB — anything with `get` / `set` / `delete`.
64
-
65
- ## Quick start — free tier (with API key)
66
-
67
66
  ```bash
68
- bun add @waniwani/sdk
69
- export WANIWANI_API_KEY=wwk_...
67
+ bun run hello.ts
70
68
  ```
71
69
 
72
- The same flow works with zero code changes — drop the `store` argument and state lives on `app.waniwani.ai`, plus you get tracking, funnel, and the dashboard.
70
+ That is a complete MCP server with one flow-driven tool, runnable over stdio. Connect it to ChatGPT, Claude, or any MCP client.
73
71
 
74
- ```ts
75
- const onboardingFlow = createFlow({ /* ...same config... */ })
76
- // ...same nodes and edges...
77
- .compile(); // no store → uses hosted flow state
78
- ```
72
+ 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.
79
73
 
80
- Want event tracking too?
74
+ ## How WaniWani compares
81
75
 
82
- ```ts
83
- import { waniwani } from "@waniwani/sdk";
84
- import { withWaniwani } from "@waniwani/sdk/mcp";
85
-
86
- // Auto-track every tool call:
87
- withWaniwani(server);
88
-
89
- // Or track custom events:
90
- const wani = waniwani();
91
- await wani.track({
92
- event: "quote.succeeded",
93
- properties: { amount: 99, currency: "USD" },
94
- meta: extra._meta,
95
- });
96
- ```
76
+ **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.
77
+
78
+ **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.
97
79
 
98
- Get an API key at [app.waniwani.ai](https://app.waniwani.ai).
80
+ **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.
99
81
 
100
- ## What's in each tier
82
+ ## Two tiers
101
83
 
102
84
  | Surface | Tier | What you get |
103
85
  |---|---|---|
104
86
  | `createFlow`, `StateGraph`, `KvStore`, `MemoryKvStore` | **OSS** | Multi-step conversational flows, runnable with no API key |
105
- | `WaniwaniKvStore` | Free tier | Hosted flow state on `app.waniwani.ai` |
106
- | `withWaniwani` | Both | Tool tracking + session bridging (no-op without an API key) |
107
- | `waniwani()`, `tracking`, `kb`, `createTrackingRoute` | Free tier | Event tracking, knowledge base, funnel routing |
108
- | `ChatWidget`, `ChatEmbed`, themes, `embed.js` | Free tier | Embeddable chat UI |
109
- | `useWaniwani` | Both | React hook for browser-side tracking (no-op until configured) |
110
-
111
- ## Package entry points
112
-
113
- | Entry point | Use it for |
114
- |---|---|
115
- | `@waniwani/sdk` | `waniwani()` client, `defineConfig`, `WaniWaniError` |
116
- | `@waniwani/sdk/mcp` | `createFlow`, `KvStore`, `MemoryKvStore`, `withWaniwani`, tracking helpers |
117
- | `@waniwani/sdk/mcp/react` | `useWaniwani` (the only non-legacy hook here) |
118
- | `@waniwani/sdk/chat` | `ChatWidget`, `ChatBar`, `ChatCard`, `ChatEmbed`, themes |
119
- | `@waniwani/sdk/chat/embed.js` | Self-contained `<script>` install for any website |
120
- | `@waniwani/sdk/chat/styles.css` | Prebuilt Tailwind styles for `chat/` components |
121
- | `@waniwani/sdk/kb` | `createKbClient` for knowledge base ingest/search |
87
+ | `WaniwaniKvStore` | Free tier | Hosted, encrypted-at-rest flow state on `app.waniwani.ai` |
88
+ | `withWaniwani`, `useWaniwani` | Both | Tool tracking, session bridging, browser hook (no-op without a key) |
89
+ | `waniwani()`, `tracking`, `kb` | Free tier | Event tracking, funnel analytics, knowledge base |
90
+ | `ChatWidget`, `ChatEmbed`, `embed.js` | Free tier | Embeddable chat UI |
91
+
92
+ Get a free key at [app.waniwani.ai](https://app.waniwani.ai).
122
93
 
123
94
  ## Documentation
124
95
 
125
- Full docs at **[docs.waniwani.ai](https://docs.waniwani.ai)** — same source as [`./docs/`](./docs) in this repo.
96
+ Full docs at **[docs.waniwani.ai](https://docs.waniwani.ai)**. Same source as [`./docs/`](./docs) in this repo.
97
+
98
+ **Build something:**
99
+ - [Sales funnel MCP](https://docs.waniwani.ai/guides/sales-funnel)
100
+ - [Lead generation MCP](https://docs.waniwani.ai/guides/lead-generation)
101
+ - [Booking MCP](https://docs.waniwani.ai/guides/booking)
102
+ - [Insurance or pricing quote MCP](https://docs.waniwani.ai/guides/insurance-quote)
126
103
 
127
- - [Introduction](https://docs.waniwani.ai/introduction) — tiers and pitch
104
+ **Learn the engine:**
128
105
  - [Quickstart](https://docs.waniwani.ai/quickstart)
129
- - [Flows](https://docs.waniwani.ai/flows/overview)
106
+ - [Flows overview](https://docs.waniwani.ai/flows/overview)
130
107
  - [KV store adapters](https://docs.waniwani.ai/flows/kv-store)
131
- - [Self-hosting](https://docs.waniwani.ai/flows/self-hosting)
108
+ - [Self-hosting](https://docs.waniwani.ai/deployment/self-hosting)
109
+
110
+ **Add the platform:**
132
111
  - [Tracking](https://docs.waniwani.ai/tracking/overview)
133
112
  - [Knowledge base](https://docs.waniwani.ai/knowledge-base/overview)
134
-
135
- ## Legacy
136
-
137
- The following exports are preserved for back-compat with existing customer MCPs but are no longer documented. New code should use `createFlow` instead. They will move to dedicated `@waniwani/sdk/legacy*` entry points in a future minor release.
138
-
139
- - `createTool`, `createResource`, `registerTools` from `@waniwani/sdk/mcp`
140
- - `toNextJsHandler` from `@waniwani/sdk/next-js`
141
- - `toExpressJsHandler` from `@waniwani/sdk/express-js`
142
- - `createApiHandler` from `@waniwani/sdk/chat/server`
143
- - `WidgetProvider`, `useWidgetClient`, `useDisplayMode`, `useToolOutput`, etc. from `@waniwani/sdk/mcp/react`
144
- - `InitializeNextJsInIframe`, `LoadingWidget`, `DevModeProvider`
145
-
146
- See the [Legacy docs section](https://docs.waniwani.ai/legacy/tools-resources) for migration notes.
113
+ - [Chat widget](https://docs.waniwani.ai/chat/embed)
147
114
 
148
115
  ## Links
149
116
 
@@ -156,4 +123,4 @@ See the [Legacy docs section](https://docs.waniwani.ai/legacy/tools-resources) f
156
123
 
157
124
  [MIT](./LICENSE) © WaniWani
158
125
 
159
- "WaniWani" is a trademark of WaniWani. The license covers the code, not the name.
126
+ "WaniWani" is a trademark of WaniWani Inc. The license covers the code, not the name.