@waniwani/sdk 0.9.4 → 0.9.5
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.
- package/README.md +104 -115
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,164 +1,153 @@
|
|
|
1
|
-
# @waniwani
|
|
1
|
+
# @waniwani/sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@waniwani/sdk)
|
|
4
|
+
[](./LICENSE)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
> The official SDK for [WaniWani](https://waniwani.ai) — build, ship, and measure conversational MCP apps.
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
`@waniwani/sdk` is the developer-facing library that plugs into your MCP (Model Context Protocol) server and gives you **event tracking** and **multi-step conversational flows** out of the box.
|
|
8
9
|
|
|
9
|
-
-
|
|
10
|
-
-
|
|
10
|
+
- **Zero runtime dependencies** — sub-5KB bundle, safe for serverless and edge runtimes.
|
|
11
|
+
- **Works with any MCP runtime** — [Skybridge](https://github.com/alpic-ai/skybridge), [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk), [`@vercel/mcp-handler`](https://www.npmjs.com/package/@vercel/mcp-handler).
|
|
12
|
+
- **Fully typed** — Zod-powered state schemas, inferred node contexts, typed event properties.
|
|
13
|
+
- **Automatic tool tracking** — one line wraps your server and every tool call ships to your dashboard.
|
|
14
|
+
- **LangGraph-inspired flows** — compile a state graph into a single MCP tool that drives multi-turn conversations.
|
|
11
15
|
|
|
12
|
-
|
|
16
|
+
> **Status:** pre-alpha. APIs and behaviour may change between releases — pin versions in production.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
13
19
|
|
|
14
20
|
```bash
|
|
15
|
-
npm install @waniwani
|
|
21
|
+
npm install @waniwani/sdk
|
|
22
|
+
# or
|
|
23
|
+
pnpm add @waniwani/sdk
|
|
24
|
+
# or
|
|
25
|
+
bun add @waniwani/sdk
|
|
16
26
|
```
|
|
17
27
|
|
|
18
|
-
|
|
28
|
+
Requires Node 18.17+ and an MCP server runtime.
|
|
19
29
|
|
|
20
|
-
|
|
21
|
-
import { waniwani } from "@waniwani";
|
|
30
|
+
## Quick start
|
|
22
31
|
|
|
23
|
-
|
|
24
|
-
apiKey: "your-api-key", // or WANIWANI_API_KEY
|
|
25
|
-
});
|
|
32
|
+
### 1. Get an API key
|
|
26
33
|
|
|
27
|
-
|
|
28
|
-
event: "tool.called",
|
|
29
|
-
properties: { name: "pricing", type: "pricing" },
|
|
30
|
-
meta: extra._meta,
|
|
31
|
-
});
|
|
34
|
+
Sign in to [app.waniwani.ai](https://app.waniwani.ai), create an MCP environment, and copy its API key. Expose it to your server as `WANIWANI_API_KEY`:
|
|
32
35
|
|
|
33
|
-
|
|
36
|
+
```bash
|
|
37
|
+
# .env
|
|
38
|
+
WANIWANI_API_KEY=ww_live_...
|
|
34
39
|
```
|
|
35
40
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
New SDK versions send tracking data to **V2 only**:
|
|
41
|
+
### 2. Wrap your MCP server
|
|
39
42
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
+
```ts
|
|
44
|
+
import { waniwani } from "@waniwani/sdk";
|
|
45
|
+
import { withWaniwani } from "@waniwani/sdk/mcp";
|
|
46
|
+
import { McpServer } from "skybridge/server";
|
|
47
|
+
import "dotenv/config";
|
|
43
48
|
|
|
44
|
-
|
|
49
|
+
const server = new McpServer(
|
|
50
|
+
{ name: "my-mcp-app", version: "0.0.1" },
|
|
51
|
+
{ capabilities: {} },
|
|
52
|
+
);
|
|
45
53
|
|
|
46
|
-
|
|
54
|
+
server.registerTool(/* ... your tools ... */);
|
|
47
55
|
|
|
48
|
-
|
|
56
|
+
// One line — every registered tool is now tracked automatically.
|
|
57
|
+
withWaniwani(server, { client: waniwani() });
|
|
49
58
|
|
|
50
|
-
|
|
51
|
-
const client = waniwani({
|
|
52
|
-
apiKey: "...", // defaults to WANIWANI_API_KEY env var
|
|
53
|
-
baseUrl: "...", // defaults to https://app.waniwani.ai
|
|
54
|
-
tracking: {
|
|
55
|
-
endpointPath: "/api/mcp/events/v2/batch",
|
|
56
|
-
flushIntervalMs: 1000,
|
|
57
|
-
maxBatchSize: 20,
|
|
58
|
-
maxBufferSize: 1000,
|
|
59
|
-
maxRetries: 3,
|
|
60
|
-
retryBaseDelayMs: 200,
|
|
61
|
-
retryMaxDelayMs: 2000,
|
|
62
|
-
shutdownTimeoutMs: 2000,
|
|
63
|
-
},
|
|
64
|
-
});
|
|
59
|
+
server.run();
|
|
65
60
|
```
|
|
66
61
|
|
|
67
|
-
|
|
62
|
+
Every tool call produces a `tool.called` event with duration, status, input/output, and session correlation — all visible in your WaniWani dashboard within seconds.
|
|
63
|
+
|
|
64
|
+
### 3. Track custom events
|
|
68
65
|
|
|
69
|
-
|
|
66
|
+
```ts
|
|
67
|
+
import { waniwani } from "@waniwani/sdk";
|
|
70
68
|
|
|
71
|
-
|
|
69
|
+
const wani = waniwani();
|
|
72
70
|
|
|
73
|
-
|
|
74
|
-
await client.track({
|
|
71
|
+
await wani.track({
|
|
75
72
|
event: "quote.succeeded",
|
|
76
73
|
properties: { amount: 99, currency: "USD" },
|
|
77
|
-
meta: extra._meta,
|
|
78
|
-
});
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
Legacy-compatible shape:
|
|
82
|
-
|
|
83
|
-
```typescript
|
|
84
|
-
await client.track({
|
|
85
|
-
eventType: "tool.called",
|
|
86
|
-
sessionId: "session-123",
|
|
87
|
-
toolName: "pricing",
|
|
88
|
-
toolType: "pricing",
|
|
89
|
-
metadata: { source: "legacy" },
|
|
74
|
+
meta: extra._meta, // correlates the event with the current MCP session
|
|
90
75
|
});
|
|
91
76
|
```
|
|
92
77
|
|
|
93
|
-
###
|
|
78
|
+
### 4. Build a flow
|
|
94
79
|
|
|
95
|
-
|
|
80
|
+
Multi-turn conversations, compiled into a single MCP tool:
|
|
96
81
|
|
|
97
|
-
|
|
82
|
+
```ts
|
|
83
|
+
import { createFlow, END, START } from "@waniwani/sdk/mcp";
|
|
84
|
+
import { z } from "zod";
|
|
98
85
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
86
|
+
export const onboardingFlow = createFlow({
|
|
87
|
+
id: "onboarding",
|
|
88
|
+
title: "User Onboarding",
|
|
89
|
+
description: "Use when a new user wants to get started.",
|
|
90
|
+
state: {
|
|
91
|
+
email: z.string().describe("Work email"),
|
|
92
|
+
useCase: z.string().describe("What they want to build"),
|
|
93
|
+
},
|
|
94
|
+
})
|
|
95
|
+
.addNode("ask_email", async ({ interrupt }) =>
|
|
96
|
+
interrupt({ email: { question: "What's your work email?" } }),
|
|
97
|
+
)
|
|
98
|
+
.addNode("ask_use_case", async ({ interrupt }) =>
|
|
99
|
+
interrupt({
|
|
100
|
+
useCase: {
|
|
101
|
+
question: "What do you want to build?",
|
|
102
|
+
suggestions: ["Analytics", "Support", "Lead capture"],
|
|
103
|
+
},
|
|
104
|
+
}),
|
|
105
|
+
)
|
|
106
|
+
.addEdge(START, "ask_email")
|
|
107
|
+
.addEdge("ask_email", "ask_use_case")
|
|
108
|
+
.addEdge("ask_use_case", END)
|
|
109
|
+
.compile();
|
|
110
|
+
|
|
111
|
+
await onboardingFlow.register(server);
|
|
103
112
|
```
|
|
104
113
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
- `session.started`
|
|
108
|
-
- `tool.called`
|
|
109
|
-
- `quote.requested`
|
|
110
|
-
- `quote.succeeded`
|
|
111
|
-
- `quote.failed`
|
|
112
|
-
- `link.clicked`
|
|
113
|
-
- `purchase.completed`
|
|
114
|
-
|
|
115
|
-
## Declarative Event Tracking
|
|
116
|
-
|
|
117
|
-
Track conversions and funnel steps without writing JavaScript — just add data attributes to your HTML elements.
|
|
118
|
-
|
|
119
|
-
### `data-ww-conversion`
|
|
114
|
+
The engine handles state persistence, resumption, branching, and validation. The model just calls one tool — everything else is managed server-side.
|
|
120
115
|
|
|
121
|
-
|
|
116
|
+
## Documentation
|
|
122
117
|
|
|
123
|
-
|
|
124
|
-
<button data-ww-conversion="purchase value:49.99 currency:EUR">Buy Now</button>
|
|
125
|
-
<button data-ww-conversion="signup">Sign Up Free</button>
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
| Token | Description |
|
|
129
|
-
|-------|-------------|
|
|
130
|
-
| First token | Conversion name (required) |
|
|
131
|
-
| Any `key:value` | Included as event metadata |
|
|
132
|
-
|
|
133
|
-
### `data-ww-step`
|
|
118
|
+
Full product documentation lives at **[docs.waniwani.ai](https://docs.waniwani.ai)** (powered by Mintlify):
|
|
134
119
|
|
|
135
|
-
|
|
120
|
+
- [Introduction](https://docs.waniwani.ai/introduction)
|
|
121
|
+
- [Quickstart](https://docs.waniwani.ai/quickstart)
|
|
122
|
+
- [Setup](https://docs.waniwani.ai/setup/installation)
|
|
123
|
+
- [Event Tracking](https://docs.waniwani.ai/tracking/overview)
|
|
124
|
+
- [Flows](https://docs.waniwani.ai/flows/overview)
|
|
136
125
|
|
|
137
|
-
|
|
138
|
-
<button data-ww-step="pricing">View Pricing</button>
|
|
139
|
-
<button data-ww-step="select-plan plan:premium">Select Plan</button>
|
|
140
|
-
<button data-ww-step="checkout">Checkout</button>
|
|
141
|
-
```
|
|
126
|
+
The same docs are also available in this repository under [`docs/`](./docs).
|
|
142
127
|
|
|
143
|
-
|
|
128
|
+
## What's inside the package
|
|
144
129
|
|
|
145
|
-
|
|
130
|
+
| Entry point | What it gives you |
|
|
131
|
+
| ------------------------- | ------------------------------------------------------------------------------ |
|
|
132
|
+
| `@waniwani/sdk` | `waniwani()` client: event tracking, identify, flush, shutdown. |
|
|
133
|
+
| `@waniwani/sdk/mcp` | `withWaniwani`, `createFlow`, `createTool`, `createResource`, flow primitives. |
|
|
134
|
+
| `@waniwani/sdk/mcp/react` | React hooks for WaniWani-powered widgets. |
|
|
135
|
+
| `@waniwani/sdk/chat` | Chat UI components for embedding conversations. |
|
|
136
|
+
| `@waniwani/sdk/kb` | Knowledge base client. |
|
|
146
137
|
|
|
147
|
-
|
|
138
|
+
Most users only need `@waniwani/sdk` and `@waniwani/sdk/mcp`.
|
|
148
139
|
|
|
149
|
-
|
|
140
|
+
## Examples
|
|
150
141
|
|
|
151
|
-
|
|
152
|
-
bun run typecheck && bun run lint && bun run build && bun run test
|
|
153
|
-
```
|
|
142
|
+
- **[Alpic x WaniWani demo](https://github.com/alpic-ai/apps-sdk-template)** — a Skybridge MCP server with a full `createFlow` booking journey.
|
|
154
143
|
|
|
155
|
-
##
|
|
144
|
+
## Links
|
|
156
145
|
|
|
157
|
-
-
|
|
158
|
-
-
|
|
159
|
-
-
|
|
160
|
-
-
|
|
146
|
+
- **Website** — [waniwani.ai](https://waniwani.ai)
|
|
147
|
+
- **Dashboard** — [app.waniwani.ai](https://app.waniwani.ai)
|
|
148
|
+
- **Docs** — [docs.waniwani.ai](https://docs.waniwani.ai)
|
|
149
|
+
- **Issues** — [github.com/WaniWani-AI/sdk/issues](https://github.com/WaniWani-AI/sdk/issues)
|
|
161
150
|
|
|
162
151
|
## License
|
|
163
152
|
|
|
164
|
-
MIT
|
|
153
|
+
[MIT](./LICENSE) © WaniWani
|