@waniwani/sdk 0.11.10 → 0.11.12

package/README.md

@@ -3,91 +3,33 @@
 [![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 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.
 
-`@waniwani/sdk` is the developer-facing library for your MCP (Model Context Protocol) server. It provides **event tracking** and **multi-step conversational flows**.
+`@waniwani/sdk` turns your MCP server into a distribution surface. Build:
 
-- **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.
+- **Sales funnels and lead generation** — qualify leads, capture intent, route to the right step. Multi-step conversations compiled into a single MCP tool.
+- **Booking and reservation flows** — collect what you need, branch on conditions, confirm.
+- **Quote flows** (insurance, pricing, custom) — gather inputs, call your pricing API, return a quote, optionally render a widget.
+- **Knowledge base and embedded chat** — ground answers in your docs, ship a chat widget for your site.
 
-> **Status:** pre-alpha. APIs and behavior may change between releases. Pin versions in production.
+The SDK is split into two tiers:
 
-## Install
+- **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.
+- **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.
 
-```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.
+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.
 
-## Quick start
+> **Status:** pre-alpha. APIs may change between releases. Pin versions in production.
 
-### 1. Get an API key
-
-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`:
+## Quick start — open source (no API key)
 
 ```bash
-# .env
-WANIWANI_API_KEY=wwk_...
-```
-
-### 2. Wrap your MCP server
-
-```ts
-import express from "express";
-import { withWaniwani } from "@waniwani/sdk/mcp";
-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);
-
-const app = express();
-app.use(express.json());
-app.post("/mcp", (req, res) => transport.handleRequest(req, res, req.body));
-app.listen(3000);
-```
-
-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
-});
+bun add @waniwani/sdk
 ```
 
-### 4. Build a flow
-
-Multi-turn conversations, compiled into a single MCP tool:
-
 ```ts
-import { createFlow, END, START } from "@waniwani/sdk/mcp";
+// flow.ts
+import { createFlow, END, MemoryKvStore, START } from "@waniwani/sdk/mcp";
 import { z } from "zod";
 
 export const onboardingFlow = createFlow({
@@ -99,10 +41,10 @@ export const onboardingFlow = createFlow({
     useCase: z.string().describe("What they want to build"),
   },
 })
-  .addNode("ask_email", async ({ interrupt }) =>
+  .addNode("ask_email", () =>
     interrupt({ email: { question: "What's your work email?" } }),
   )
-  .addNode("ask_use_case", async ({ interrupt }) =>
+  .addNode("ask_use_case", () =>
     interrupt({
       useCase: {
         question: "What do you want to build?",
@@ -113,38 +55,95 @@ export const onboardingFlow = createFlow({
   .addEdge(START, "ask_email")
   .addEdge("ask_email", "ask_use_case")
   .addEdge("ask_use_case", END)
-  .compile();
+  .compile({ store: new MemoryKvStore() });
 
 await onboardingFlow.register(server);
 ```
 
-The engine handles state persistence, resumption, branching, and validation. The model calls one tool and the rest is managed server-side.
+`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`.
+
+## Quick start — free tier (with API key)
+
+```bash
+bun add @waniwani/sdk
+export WANIWANI_API_KEY=wwk_...
+```
+
+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.
+
+```ts
+const onboardingFlow = createFlow({ /* ...same config... */ })
+  // ...same nodes and edges...
+  .compile(); // no store → uses hosted flow state
+```
+
+Want event tracking too?
+
+```ts
+import { waniwani } from "@waniwani/sdk";
+import { withWaniwani } from "@waniwani/sdk/mcp";
+
+// Auto-track every tool call:
+withWaniwani(server);
+
+// Or track custom events:
+const wani = waniwani();
+await wani.track({
+  event: "quote.succeeded",
+  properties: { amount: 99, currency: "USD" },
+  meta: extra._meta,
+});
+```
+
+Get an API key at [app.waniwani.ai](https://app.waniwani.ai).
+
+## What's in each tier
+
+| Surface | Tier | What you get |
+|---|---|---|
+| `createFlow`, `StateGraph`, `KvStore`, `MemoryKvStore` | **OSS** | Multi-step conversational flows, runnable with no API key |
+| `WaniwaniKvStore` | Free tier | Hosted flow state on `app.waniwani.ai` |
+| `withWaniwani` | Both | Tool tracking + session bridging (no-op without an API key) |
+| `waniwani()`, `tracking`, `kb`, `createTrackingRoute` | Free tier | Event tracking, knowledge base, funnel routing |
+| `ChatWidget`, `ChatEmbed`, themes, `embed.js` | Free tier | Embeddable chat UI |
+| `useWaniwani` | Both | React hook for browser-side tracking (no-op until configured) |
+
+## Package entry points
+
+| Entry point | Use it for |
+|---|---|
+| `@waniwani/sdk` | `waniwani()` client, `defineConfig`, `WaniWaniError` |
+| `@waniwani/sdk/mcp` | `createFlow`, `KvStore`, `MemoryKvStore`, `withWaniwani`, tracking helpers |
+| `@waniwani/sdk/mcp/react` | `useWaniwani` (the only non-legacy hook here) |
+| `@waniwani/sdk/chat` | `ChatWidget`, `ChatBar`, `ChatCard`, `ChatEmbed`, themes |
+| `@waniwani/sdk/chat/embed.js` | Self-contained `<script>` install for any website |
+| `@waniwani/sdk/chat/styles.css` | Prebuilt Tailwind styles for `chat/` components |
+| `@waniwani/sdk/kb` | `createKbClient` for knowledge base ingest/search |
 
 ## Documentation
 
-Full product documentation lives at **[docs.waniwani.ai](https://docs.waniwani.ai)**:
+Full docs at **[docs.waniwani.ai](https://docs.waniwani.ai)** — same source as [`./docs/`](./docs) in this repo.
 
-- [Introduction](https://docs.waniwani.ai/introduction)
+- [Introduction](https://docs.waniwani.ai/introduction) — tiers and pitch
 - [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)
+- [KV store adapters](https://docs.waniwani.ai/flows/kv-store)
+- [Self-hosting](https://docs.waniwani.ai/flows/self-hosting)
+- [Tracking](https://docs.waniwani.ai/tracking/overview)
+- [Knowledge base](https://docs.waniwani.ai/knowledge-base/overview)
 
-The same docs are also available in this repository under [`docs/`](./docs).
-
-## What's inside the package
-
-| 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.                                      |
+## Legacy
 
-Most users only need `@waniwani/sdk` and `@waniwani/sdk/mcp`.
+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.
 
-## Examples
+- `createTool`, `createResource`, `registerTools` from `@waniwani/sdk/mcp`
+- `toNextJsHandler` from `@waniwani/sdk/next-js`
+- `toExpressJsHandler` from `@waniwani/sdk/express-js`
+- `createApiHandler` from `@waniwani/sdk/chat/server`
+- `WidgetProvider`, `useWidgetClient`, `useDisplayMode`, `useToolOutput`, etc. from `@waniwani/sdk/mcp/react`
+- `InitializeNextJsInIframe`, `LoadingWidget`, `DevModeProvider`
 
-- **[Alpic x WaniWani demo](https://github.com/WaniWani-AI/alpic-x-waniwani-demo)**: a Skybridge MCP server with a full `createFlow` booking journey.
+See the [Legacy docs section](https://docs.waniwani.ai/legacy/tools-resources) for migration notes.
 
 ## Links