feat: documenting mppx WS

package.json

@@ -54,7 +54,7 @@
     "tiktoken": "^1.0.22",
     "typescript": "^5",
     "unplugin-icons": "^23.0.1",
-    "vite": "^7",
+    "vite": "^8.0.5",
     "vite-plugin-mkcert": "^1.17.10",
     "vitest": "^4.0.18"
   },

src/pages/guides/streamed-payments.mdx

@@ -644,6 +644,12 @@ for await (const word of stream) {
 const receipt = await session.close()
 ```
 
+## WebSocket alternative
+
+The examples above use Server-Sent Events (SSE) for streaming. If your use case benefits from a persistent bidirectional connection — for example, interactive chat or real-time sessions — you can stream over WebSocket instead. The session payment flow is the same (channel open, voucher signing, close), but vouchers and content travel over a single socket rather than separate HTTP requests.
+
+On the server, use [`tempo.Ws.serve()`](/sdk/typescript/server/Ws.serve) to bridge a WebSocket to the session payment flow. On the client, use [`session.ws()`](/sdk/typescript/client/Method.tempo.session-manager#sessionwsinput-init) instead of `session.sse()`.
+
 ## Next steps
 
 <Cards>

src/pages/sdk/typescript/client/Method.tempo.session-manager.mdx

@@ -67,6 +67,56 @@ for await (const message of stream) {
 await session.close()
 ```
 
+### With WebSocket streaming
+
+Open a paid WebSocket session. The session manager handles the HTTP `402` probe, channel open, and in-band voucher signing. Payment control frames are intercepted internally — your socket listeners only see application messages.
+
+```ts
+import { tempo } from 'mppx/client'
+import { privateKeyToAccount } from 'viem/accounts'
+
+const session = tempo.session({
+  account: privateKeyToAccount('0x...'),
+  maxDeposit: '1',
+})
+
+const url = new URL('wss://api.example.com/ws/chat')
+url.searchParams.set('prompt', 'Tell me something interesting')
+
+const socket = await session.ws(url, {
+  onReceipt(receipt) {
+    console.log('Receipt:', receipt)
+  },
+})
+
+socket.addEventListener('message', (event) => {
+  process.stdout.write(event.data)
+})
+
+await new Promise<void>((resolve) => {
+  socket.addEventListener('close', () => resolve(), { once: true })
+})
+
+const receipt = await session.close()
+```
+
+:::tip
+In Node.js or other server-side runtimes without a global `WebSocket`, pass the constructor to `tempo.session()`:
+
+```ts
+import { WebSocket } from 'isows'
+import { tempo } from 'mppx/client'
+import { privateKeyToAccount } from 'viem/accounts'
+
+const session = tempo.session({
+  account: privateKeyToAccount('0x...'),
+  maxDeposit: '1',
+  webSocket: WebSocket,
+})
+```
+
+:::
+
 ### With explicit open
 
 Open the channel before the first request. This separates the on-chain deposit transaction from the first API call.
@@ -110,6 +160,14 @@ type SessionManager = {
       signal?: AbortSignal
     },
   ): Promise<AsyncIterable<string>>
+  ws(
+    input: string | URL,
+    init?: {
+      onReceipt?: (receipt: SessionReceipt) => void
+      protocols?: string | string[]
+      signal?: AbortSignal
+    },
+  ): Promise<WebSocket>
   close(): Promise<SessionReceipt | undefined>
 }
 ```
@@ -208,6 +266,21 @@ Function that returns a viem client for the given chain ID.
 
 Maximum deposit in human-readable units (for example `"10"` for 10 tokens). Caps the server's suggested deposit and enables automatic channel management.
 
+### webSocket (optional)
+
+- **Type:** `WebSocketConstructor`
+
+WebSocket constructor for runtimes without a global `WebSocket` (e.g. Node.js). Required for `session.ws()` in non-browser environments. Use [`isows`](https://github.com/nickmccurdy/isows) for isomorphic support.
+
+```ts
+import { WebSocket } from 'isows'
+
+const session = tempo.session({
+  account,
+  webSocket: WebSocket,
+})
+```
+
 ## Methods
 
 ### `session.close()`
@@ -232,7 +305,7 @@ console.log(response.cumulative)
 
 ### `session.open(options?)`
 
-Opens the payment channel explicitly. You must make at least one `fetch()` or `sse()` call first to receive a 402 Challenge from the server.
+Opens the payment channel explicitly. You must make at least one `fetch()`, `sse()`, or `ws()` call first to receive a 402 Challenge from the server.
 
 - **options.deposit** (`bigint`, optional) — Raw deposit amount in token units.
 
@@ -261,6 +334,31 @@ for await (const message of stream) {
 }
 ```
 
+### `session.ws(input, init?)`
+
+Opens a paid WebSocket connection. Performs the HTTP `402` probe, creates the first credential, opens the socket, and sends the auth frame. Returns a `WebSocket` that only surfaces application messages — payment control frames are handled internally.
+
+- **input** (`string | URL`) — The WebSocket URL (`ws:` or `wss:`).
+- **init.onReceipt** (`(receipt: SessionReceipt) => void`, optional) — Called when the server sends a payment Receipt.
+- **init.protocols** (`string | string[]`, optional) — WebSocket sub-protocols.
+- **init.signal** (`AbortSignal`, optional) — Aborts the payment flow and closes the socket.
+
+```ts
+const socket = await session.ws('wss://api.example.com/ws/chat', {
+  onReceipt: (receipt) => console.log('paid:', receipt),
+})
+
+socket.addEventListener('message', (event) => {
+  console.log(event.data)
+})
+```
+
+:::info
+
+The returned `WebSocket` is a managed wrapper. Messages are buffered until the first listener is installed, so you won't miss frames between `await session.ws()` and adding your `message` listener.
+
+:::
+
 ## Properties
 
 ### `session.channelId`

src/pages/sdk/typescript/server/Method.tempo.session.mdx

@@ -161,6 +161,10 @@ Whether to wait for open transactions to confirm on-chain before responding. Whe
 
 ## Related
 
+### `tempo.Ws.serve`
+
+WebSocket transport for session streams. Bridges a WebSocket connection to the same session payment flow, with in-band authorization, voucher top-ups, and cooperative close over a single socket. See [`Ws.serve`](/sdk/typescript/server/Ws.serve) for full documentation.
+
 ### `tempo.settle`
 
 One-shot settlement: reads the highest voucher from the store and submits it on-chain. Use this for periodic batch settlement outside the request handler.

src/pages/sdk/typescript/server/Ws.serve.mdx

@@ -0,0 +1,167 @@
+# `Ws.serve` [WebSocket session transport]
+
+Bridges a WebSocket connection to a Tempo session payment flow. Handles in-band authorization, voucher top-ups, per-unit charging, and cooperative close over a single socket.
+
+The initial `402` challenge is still served over HTTP — the client probes the endpoint, receives the challenge, then upgrades to WebSocket for the rest of the session.
+
+:::info
+
+`Ws.serve` does not perform the HTTP upgrade itself. Use your framework's WebSocket upgrade mechanism (e.g. `ws`, Bun, Deno, Cloudflare) and pass the accepted socket.
+
+:::
+
+## Usage
+
+```ts
+import { Mppx, Store, tempo } from 'mppx/server'
+import { WebSocketServer } from 'ws'
+
+const store = Store.memory()
+
+const mppx = Mppx.create({
+  methods: [tempo.session({ account: '0x...', store })],
+  secretKey: 'my-secret',
+})
+
+const route = mppx.session({
+  amount: '0.000075',
+  unitType: 'token',
+})
+
+const wss = new WebSocketServer({ noServer: true })
+
+wss.on('connection', (socket, req) => {
+  const url = new URL(req.url ?? '/', `ws://${req.headers.host}`)
+
+  tempo.Ws.serve({
+    socket,
+    store,
+    url,
+    route,
+    generate: async function* (stream) {
+      for await (const token of getTokens()) {
+        await stream.charge()
+        yield token
+      }
+    },
+  })
+})
+```
+
+### With HTTP 402 probe
+
+The same `route` handler serves both the initial HTTP `402` challenge and the WebSocket credential verification:
+
+```ts
+import { Mppx, Store, tempo } from 'mppx/server'
+
+const store = Store.memory()
+
+const mppx = Mppx.create({
+  methods: [tempo.session({ account: '0x...', store })],
+  secretKey: 'my-secret',
+})
+
+const route = mppx.session({ amount: '0.001', unitType: 'request' })
+
+export async function handler(request: Request): Promise<Response> {
+  const result = await route(request)
+  if (result.status === 402) return result.challenge
+  return result.withReceipt(new Response('Use the WebSocket endpoint for streaming.'))
+}
+```
+
+### With amount validation
+
+Pin the per-tick price when the route is backed by `Mppx.compose()` with multiple offers. Without this, a client could select the cheapest composed offer for the same stream.
+
+```ts
+import { Store, tempo } from 'mppx/server'
+
+const store = Store.memory()
+
+tempo.Ws.serve({
+  amount: '0.000075',
+  socket,
+  store,
+  url: 'ws://localhost/ws/chat',
+  route,
+  generate: async function* (stream) {
+    yield 'hello'
+  },
+})
+```
+
+## How it works
+
+1. **Client probes** the HTTP endpoint and receives a `402` challenge
+2. **Client opens** a WebSocket and sends the signed credential as the first frame
+3. **Server verifies** the credential by routing it through the same `route` handler as a synthetic `POST` with only the `Authorization` header
+4. **Server streams** application data, calling `stream.charge()` before each unit
+5. When the voucher is exhausted, the server sends a **`payment-need-voucher`** control frame and pauses until the client sends a higher cumulative voucher
+6. When the stream ends or the client sends a **`payment-close-request`**, the server sends a `payment-close-ready` frame with the final receipt
+7. The client signs a **close credential** and the server settles the channel
+
+## Parameters
+
+### socket
+
+- **Type:** `Socket`
+
+The WebSocket connection. Accepts any implementation with `send`, `close`, and either `addEventListener`/`removeEventListener` (browser-style) or `on`/`off` (Node-style) methods.
+
+### store
+
+- **Type:** `Store.Store | ChannelStore`
+
+Channel store for persisting session state. Must be the same store instance used by `tempo.session()`.
+
+### url
+
+- **Type:** `string | URL`
+
+The WebSocket URL. Used to construct synthetic requests for credential verification. `ws:` and `wss:` protocols are normalized to `http:` and `https:`.
+
+### route
+
+- **Type:** `(request: Request) => Promise<SessionRouteResult>`
+
+The session route handler from `mppx.session()`. Receives synthetic `POST` requests carrying only the `Authorization` header — no cookies, bodies, or upgrade headers.
+
+### generate
+
+- **Type:** `AsyncIterable<string> | ((stream: SessionController) => AsyncIterable<string>)`
+
+The content generator. When passed a function, it receives a `SessionController` with a `charge()` method that must be called before yielding each billable unit. When passed a bare `AsyncIterable`, charging happens automatically before each yielded value.
+
+### amount (optional)
+
+- **Type:** `string`
+
+Expected per-tick amount in raw units. When set, credentials whose challenge amount does not match are rejected with a `402` error.
+
+### pollIntervalMs (optional)
+
+- **Type:** `number`
+- **Default:** `100`
+
+Interval in milliseconds for polling the channel store when waiting for a voucher top-up. Only used when the store does not support `waitForUpdate`.
+
+## Control frame protocol
+
+All WebSocket frames are JSON objects with an `mpp` discriminator field. Application data and payment control frames share the same socket but are fully isolated — the managed socket returned by `session.ws()` on the client only surfaces application messages.
+
+| Frame | Direction | Purpose |
+|---|---|---|
+| `authorization` | Client → Server | Signed credential (open, top-up, or close) |
+| `payment-receipt` | Server → Client | Voucher receipt after successful verification |
+| `payment-need-voucher` | Server → Client | Request a higher cumulative voucher |
+| `payment-close-request` | Client → Server | Request graceful close |
+| `payment-close-ready` | Server → Client | Final receipt before close credential |
+| `payment-error` | Server → Client | Error with status code and message |
+| `message` | Server → Client | Application data (content) |
+
+## Related
+
+- [tempo.session (client manager)](/sdk/typescript/client/Method.tempo.session-manager) — client-side `session.ws()` method
+- [tempo.session (server)](/sdk/typescript/server/Method.tempo.session) — server-side session method configuration

vocs.config.ts

@@ -571,6 +571,16 @@ export default defineConfig({
                       },
                     ],
                   },
+                  {
+                    text: "WebSocket",
+                    collapsed: true,
+                    items: [
+                      {
+                        text: "Ws.serve",
+                        link: "/sdk/typescript/server/Ws.serve",
+                      },
+                    ],
+                  },
                   {
                     text: "Utilities",
                     collapsed: true,