weifuwu 0.24.3 → 0.25.1

package/README.md

@@ -210,6 +210,45 @@ app.use('/admin', mw) // path-scoped
 app.get('/admin', mw, handler) // route-level
 ```
 
+### Middleware Dependency Checking
+
+Middleware factories can declare what ctx fields they inject and depend on via
+`__meta`. The Router warns at registration time if a dependency is unsatisfied.
+
+```ts
+// postgres() declares: __meta = { injects: ['sql'], depends: [] }
+// session() declares:  __meta = { injects: ['session'], depends: [] }
+// user() declares:     __meta = { injects: ['user'], depends: ['sql', 'session'] }
+
+const app = new Router()
+app.use(user()) // ⚠️ Warns: depends on 'sql' and 'session' but they aren't registered
+// → "[weifuwu] Middleware at "global" depends on ctx.sql but it hasn't been registered yet."
+// → "Register the provider before this middleware: app.use(sql())"
+
+// Correct order:
+app.use(postgres())
+app.use(session())
+app.use(user())
+```
+
+To add `__meta` to your own middleware:
+
+```ts
+function myMiddleware() {
+  const mw = async (req, ctx, next) => {
+    ctx.myField = await setup()
+    return next(req, ctx)
+  }
+  mw.__meta = { injects: ['myField'], depends: ['sql'] }
+  return mw
+}
+```
+
+The check is purely advisory — warnings go to `console.warn`, no errors are thrown. Built-in
+middleware (`postgres`, `redis`, `session`, `aiProvider`, `rateLimit`) all have `__meta` pre-attached.
+
+_New in v0.25._
+
 ### Context
 
 The `ctx` object accumulates properties as it passes through the middleware chain. Below are all documented properties:
@@ -236,6 +275,7 @@ The `ctx` object accumulates properties as it passes through the middleware chai
 | `tenant`      | `tenant()`                       | `TenantContext`           | Current tenant info                  |
 | `parsed`      | `validate()` / `upload()`        | `{ body, files }`         | Validated/parsed request data        |
 | `layoutStack` | `ssr()` internal                 | `LayoutEntry[]`           | React layout component stack         |
+| `notifier`    | `notifier()`                     | `Notifier`                | Multi-channel notification system    |
 | `loaderData`  | User middleware                  | `Record<string, unknown>` | SSR data passed to client            |
 | `mountPath`   | `Router`                         | `string`                  | Sub-router mount path                |
 | `deploy`      | `deploy()`                       | `{ appName? }`            | Deploy gateway info                  |
@@ -417,6 +457,10 @@ graph TD
 | **Multi-process deploy**         | `deploy()`                                      | γ                      |
 | **Distributed functions (iii)**  | `iii()`                                         | β                      |
 | **Webhook receiver**             | `webhook()`                                     | β                      |
+| **MCP tool integration**         | `mcpClient()`                                   | γ                      |
+| **Notifications**                | `notifier()`                                    | α                      |
+| **API Key management**           | `user({ apiKeys: true })`                       | β                      |
+| **WebSocket testing**            | `testApp().wsReq()`                             | —                      |
 | **Social login (OAuth)**         | `user({ oauthLogin })`                          | β                      |
 | **Database migrations**          | `pg.migrate()`                                  | —                      |
 
@@ -521,6 +565,47 @@ assert.deepEqual(await res.json(), { id: '42', user: { id: 1 } })
 | `.header(k,v)` `.body(data)` `.rawBody(str)`                 | Set request properties                                |
 | `.send()` → `TestResponse`                                   | Execute and get `{ status, headers, json(), text() }` |
 
+**WebSocket testing** (new in v0.25) — `app.ws()` + `app.wsReq()`:
+
+```ts
+const app = testApp()
+app.ws('/echo', {
+  open(ws) {
+    ws.send(JSON.stringify({ type: 'connected' }))
+  },
+  message(ws, ctx, data) {
+    ws.send('echo: ' + data.toString())
+  },
+})
+
+// Connect via WebSocket
+const conn = await app.wsReq('/echo').connect()
+
+// Wait for the open message
+const openMsg = await conn.receiveJson()
+assert.equal(openMsg.type, 'connected')
+
+// Send and receive
+conn.send('hello')
+const reply = await conn.receive()
+assert.equal(reply, 'echo: hello')
+
+conn.close()
+await app.close() // cleanup server
+```
+
+| Method                                     | Description                                 |
+| ------------------------------------------ | ------------------------------------------- |
+| `app.ws(path, handler)`                    | Register a WebSocket handler                |
+| `app.wsReq(path)`                          | Start building a WebSocket connection       |
+| `.timeout(ms)`                             | Set connection timeout (default: 5000)      |
+| `.connect()` → `TestWSConnection`          | Connect and return a connection handle      |
+| `conn.send(data)` / `conn.json(obj)`       | Send a message                              |
+| `conn.receive()` / `conn.receiveJson<T>()` | Wait for the next message                   |
+| `conn.expectSilent(ms)`                    | Assert no message arrives within the period |
+| `conn.close()`                             | Close the connection                        |
+| `app.close()`                              | Close all connections and stop the server   |
+
 ### Database test isolation
 
 ```ts
@@ -1119,6 +1204,51 @@ await mail.send({
 | `from`      | `string`         | —       | Default sender address                           |
 | `send`      | `function`       | —       | Custom send function (alternative to transport)  |
 
+### mcpClient [γ] — MCP Server integration [AI]
+
+[Model Context Protocol](https://modelcontextprotocol.io) client. Spawns MCP server
+subprocesses and exposes their tools as AI SDK-compatible tool objects.
+
+```ts
+import { mcpClient, agent, aiProvider } from 'weifuwu'
+
+const fsMcp = mcpClient({
+  command: 'npx',
+  args: ['@modelcontextprotocol/server-filesystem', '/workspace'],
+})
+
+const tools = await fsMcp.getTools()
+
+const a = agent({ pg, provider: aiProvider(), tools })
+await a.run(agentId, { input: 'read package.json' })
+
+// Later, refresh tools if the server provides new ones
+await fsMcp.refresh()
+
+// Or call a tool directly
+const result = await fsMcp.callTool('echo', { text: 'hello' })
+
+await fsMcp.close() // shutdown the MCP server process
+```
+
+| Option            | Type       | Default | Description                                             |
+| ----------------- | ---------- | ------- | ------------------------------------------------------- |
+| `command`         | `string`   | —       | **Required.** Command to spawn (e.g. `'npx'`, `'node'`) |
+| `args`            | `string[]` | `[]`    | Arguments passed to the command                         |
+| `env`             | `object`   | —       | Extra environment variables                             |
+| `timeout`         | `number`   | `15000` | Handshake/response timeout (ms)                         |
+| `maxResponseSize` | `number`   | `10MB`  | Max tool response body size                             |
+
+| Method       | Description                                                               |
+| ------------ | ------------------------------------------------------------------------- |
+| `getTools()` | Fetch tool definitions, returns `Record<string, Tool>`-compatible objects |
+| `refresh()`  | Re-fetch tool definitions from the server                                 |
+| `callTool()` | Call a tool by name directly                                              |
+| `close()`    | Shutdown the MCP server process                                           |
+
+Tool schemas (JSON Schema) are automatically converted to Zod schemas for AI SDK compatibility.
+Responses are concatenated from text content items, with size limiting.
+
 ### oauthLogin (via user()) — Social login (OAuth 2.0 client) [Security]
 
 Social login is built into the [`user()`](#user-β) module via the `oauthLogin` option — no separate import needed.
@@ -1208,6 +1338,72 @@ await msg.send(channelId, 'System message', { sender_type: 'system', sender_id:
 | `.send(channel, content, opts?)` | Send message to channel                             |
 | `.close()`                       | Cleanup                                             |
 
+### notifier [α] [UX]
+
+Multi-channel notification system with inbox (DB persistent), email, and
+WebSocket push. Per-user channel preferences.
+
+```ts
+import { notifier, mailer } from 'weifuwu'
+
+const mail = mailer({ from: 'noreply@example.com', transport: '...' })
+const n = notifier({ sql: pg.sql, mailer: mail })
+await n.migrate()
+app.use(n) // injects ctx.notifier
+
+// Send a notification (routes through user's channel preferences)
+await ctx.notifier.send(
+  { userId: 42, email: 'user@example.com' },
+  { title: 'Welcome!', body: 'Thanks for joining', type: 'onboarding' },
+)
+
+// Broadcast to all users with inbox enabled
+await ctx.notifier.broadcast({
+  title: 'System maintenance tonight',
+  body: 'The system will be down from 2-4 AM',
+})
+
+// Check unread count
+const count = await ctx.notifier.unreadCount(userId)
+
+// List notifications (newest first)
+const notifications = await ctx.notifier.list(userId, { limit: 10 })
+
+// Mark as read
+await ctx.notifier.markRead(userId, [notifId])
+await ctx.notifier.markRead(userId) // mark ALL as read
+
+// User preferences
+await ctx.notifier.setPreferences(userId, { channels: ['inbox', 'email'] })
+const prefs = await ctx.notifier.getPreferences(userId)
+// → { channels: ['inbox', 'email'] }
+```
+
+| Option     | Type        | Default            | Description                     |
+| ---------- | ----------- | ------------------ | ------------------------------- |
+| `sql`      | `SqlClient` | —                  | **Required.** PostgreSQL client |
+| `mailer`   | `Mailer`    | —                  | Mailer for email channel        |
+| `hub`      | `Hub`       | —                  | Pub/sub hub for WebSocket push  |
+| `table`    | `string`    | `'_notifications'` | Notifications table name        |
+| `pageSize` | `number`    | `50`               | Default page size for list()    |
+
+| Method                           | Description                                   |
+| -------------------------------- | --------------------------------------------- |
+| `.send(to, message)`             | Send notification (routes by user preference) |
+| `.broadcast(message)`            | Send to all users with inbox enabled          |
+| `.unreadCount(userId)`           | Count unread notifications                    |
+| `.count(userId, unreadOnly?)`    | Total or unread count                         |
+| `.markRead(userId, ids?)`        | Mark notification(s) as read                  |
+| `.list(userId, opts?)`           | List notifications (paginated)                |
+| `.getPreferences(userId)`        | Get user's channel preferences                |
+| `.setPreferences(userId, prefs)` | Set user's channel preferences                |
+| `.migrate()`                     | Create tables                                 |
+| `.clean(days)`                   | Delete notifications older than N days        |
+
+**Channel routing:** Each user has channel preferences (default: `['inbox']`). When
+`sending`, the notification is delivered to each enabled channel. Email requires
+`mailer` to be configured. WebSocket requires `hub` (e.g. from `messager.wsHandler()`).
+
 ### opencode [β] [AI]
 
 AI programming assistant.
@@ -1986,6 +2182,35 @@ app.use(u.middleware()) // ctx.user
 | `.verify(token)`  | Verify JWT token                        |
 | `.middleware()`   | JWT verify middleware — sets `ctx.user` |
 
+**API Key management** — enable via `user({ apiKeys: true })`:
+
+```ts
+const auth = user({ pg, jwtSecret: process.env.JWT_SECRET, apiKeys: true })
+await auth.migrate()
+app.use(auth)
+
+// Create an API key (server-side)
+const { id, key } = await auth.createApiKey(userId, 'Deploy Key', ['read', 'deploy'])
+// key → 'sk_live_abc123...' (only shown once!)
+
+// List keys (masked)
+const keys = await auth.listApiKeys(userId)
+// → [{ id, name, prefix: 'sk_live_abc...f3a2', scopes: ['read','deploy'], last_used_at, revoked }]
+
+// Revoke a key
+await auth.revokeApiKey(userId, keyId)
+
+// REST API (auto-mounted when routes are registered)
+// POST   /api-keys       → Create (requires auth)
+// GET    /api-keys       → List (requires auth)
+// DELETE /api-keys/:id    → Revoke (requires auth)
+```
+
+API keys start with `sk_live_` and are hashed with SHA256 before storage.
+The middleware resolves API keys automatically — use them with `Authorization: Bearer sk_live_...`.
+
+_New in v0.25._
+
 ### permissions [α] — RBAC [Security]
 
 Role-based access control.

package/dist/iii/client.d.ts

@@ -1,2 +1,2 @@
 import type { IIIModule, IIIOptions } from './types.ts';
-export declare function iii(opts?: IIIOptions): IIIModule;
+export declare function iii(_opts?: IIIOptions): IIIModule;

package/dist/iii/register-worker.d.ts

@@ -5,6 +5,5 @@ export declare function registerWorker(url: string): {
     registerTrigger(input: TriggerInput): void;
     unregisterTrigger(functionId: string): void;
     trigger(request: TriggerRequest): Promise<unknown>;
-    onStream(handler: (data: any) => void): void;
     close(): void;
 };

package/dist/iii/types.d.ts

@@ -1,15 +1,15 @@
 import type { Router } from '../router.ts';
 import type { Closeable } from '../types.ts';
-import type { Redis } from '../vendor.ts';
 import type { PostgresClient } from '../postgres/types.ts';
+/** A function handler receives a payload and returns a result. */
 export type FunctionHandler = (payload: unknown, ctx: FunctionContext) => unknown | Promise<unknown>;
 export interface FunctionContext {
     engine: IIIModule;
     functionId: string;
     workerName: string;
-    triggerId?: string;
     user?: unknown;
 }
+/** Optional metadata for a trigger — iii does NOT schedule triggers, just stores them for reference. */
 export interface TriggerInput {
     type: string;
     function_id: string;
@@ -17,9 +17,6 @@ export interface TriggerInput {
 }
 export interface IIIOptions {
     pg?: PostgresClient;
-    redis?: Redis;
-    /** TTL in seconds for Redis stream keys. Default: 3600 (1 hour). Set to 0 for no expiration. */
-    streamTTL?: number;
 }
 export interface TriggerRequest {
     function_id: string;
@@ -27,19 +24,24 @@ export interface TriggerRequest {
     action?: 'sync' | 'void';
     timeout_ms?: number;
 }
-export interface TriggerOptions {
-    action?: 'sync' | 'void';
-    timeout_ms?: number;
-}
+/** III (跨进程函数调用) module — register remote workers and call functions across processes. */
 export interface IIIModule extends Router, Closeable {
     wsHandler: () => any;
+    /** Register a local worker. Its functions become callable via trigger(). */
     addWorker: (worker: Worker) => void;
+    /** Call a function by ID. Returns the function's result. */
     trigger: (request: TriggerRequest) => Promise<unknown>;
+    /** Remove a previously registered worker. */
     removeWorker: (worker: Worker) => void;
+    /** List all registered workers. */
     listWorkers: () => WorkerInfo[];
+    /** List all registered functions. */
     listFunctions: () => FunctionInfo[];
+    /** List all registered trigger metadata. */
     listTriggers: () => TriggerInfo[];
+    /** Create the database tables (currently no-op, kept for API compatibility). */
     migrate: () => Promise<void>;
+    /** Shutdown — reject pending invocations, disconnect all workers. */
     close: () => Promise<void>;
 }
 export interface WorkerInfo {
@@ -63,30 +65,37 @@ export interface TriggerInfo {
     config: Record<string, unknown>;
     workerId: string;
 }
+/** A worker — a group of related functions. */
 export interface Worker {
     readonly name: string;
+    /** Register a function that can be called remotely. */
     registerFunction: (id: string, handler: FunctionHandler, opts?: {
         description?: string;
     }) => Worker;
+    /** Unregister a function. */
     unregisterFunction: (id: string) => Worker;
+    /** Attach metadata (the module does NOT schedule — it's stored for introspection). */
     registerTrigger: (input: TriggerInput) => Worker;
+    /** Remove trigger metadata. */
     unregisterTrigger: (functionId: string) => Worker;
+    /** Get all registered functions. */
     getFunctions: () => {
         id: string;
         handler: FunctionHandler;
     }[];
+    /** Get all registered trigger metadata. */
     getTriggers: () => {
         id: string;
         input: TriggerInput;
     }[];
 }
+/** A handle to interact with a remote worker from the client side. */
 export interface RemoteWorker {
     registerFunction: (id: string, handler: FunctionHandler) => void;
     unregisterFunction: (id: string) => void;
     registerTrigger: (input: TriggerInput) => void;
     unregisterTrigger: (functionId: string) => void;
     trigger: (request: TriggerRequest) => Promise<unknown>;
-    /** Cleanup worker resources. */
     close: () => void;
 }
 export interface FunctionRegistration {
@@ -110,26 +119,3 @@ export interface WorkerRegistration {
     functions: FunctionRegistration[];
     triggers: TriggerRegistration[];
 }
-export type StreamUpdateOp = {
-    op: 'set';
-    value: unknown;
-} | {
-    op: 'merge';
-    value: Record<string, unknown>;
-} | {
-    op: 'increment';
-    value: number;
-} | {
-    op: 'decrement';
-    value: number;
-} | {
-    op: 'append';
-    value: unknown;
-} | {
-    op: 'remove';
-};
-export interface StreamSubscription {
-    stream_name: string;
-    group_id?: string;
-    item_id?: string;
-}

package/dist/iii/ws.d.ts

@@ -10,12 +10,6 @@ interface WsHandlerDeps {
         config: Record<string, unknown>;
     }) => void;
     unregisterRemoteTrigger: (workerId: string, functionId: string) => void;
-    addStreamSubscriber: (ws: WebSocket, sub: {
-        stream_name: string;
-        group_id?: string;
-        item_id?: string;
-    }) => void;
-    removeStreamSubscriber: (ws: WebSocket) => void;
     handleInvokeResult: (invocationId: string, result: unknown) => void;
     handleInvokeError: (invocationId: string, error: string) => void;
     handleInvoke: (ws: WebSocket, invocationId: string, functionId: string, payload: unknown) => void;
@@ -24,6 +18,5 @@ export declare function createWsHandler(deps: WsHandlerDeps): {
     open(_ws: WebSocket, _ctx: Context): void;
     message(ws: WebSocket, ctx: Context, data: string | Buffer): Promise<void>;
     close(ws: WebSocket): void;
-    error(ws: WebSocket): void;
 };
 export {};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export type { Context, Handler, Middleware, ErrorHandler } from './types.ts';
+export { HttpError } from './types.ts';
 export { currentTraceId, currentTrace, runWithTrace, traceElapsed, trace } from './trace.ts';
 export type { TraceContext, TraceInjected, TraceOptions } from './trace.ts';
 export { loadEnv, isDev, isProd, isBundled, getPublicEnv, env } from './env.ts';
@@ -42,7 +43,7 @@ export { streamText, generateText, generateObject, streamObject, tool, embed, em
 export { postgres, MIGRATIONS_TABLE } from './postgres/index.ts';
 export type { PostgresOptions, PostgresClient, PostgresInjected } from './postgres/types.ts';
 export { user } from './user/index.ts';
-export type { UserOptions, UserData, UserModule, OAuth2Client, OAuthProviderConfig, } from './user/types.ts';
+export type { UserOptions, UserData, UserModule, OAuth2Client, OAuthProviderConfig, ApiKeyInfo, } from './user/types.ts';
 export type { UserInjected } from './user/types.ts';
 export { redis } from './redis/index.ts';
 export type { RedisOptions, RedisClient, RedisInjected } from './redis/types.ts';
@@ -94,3 +95,7 @@ export { knowledgeBase } from './kb/index.ts';
 export type { KBOptions, KBIngestOptions, KBSearchResult, KBSearchOptions, KBListEntry, KBModule, } from './kb/types.ts';
 export { permissions } from './permissions.ts';
 export type { PermissionsOptions, PermissionsModule } from './permissions.ts';
+export { mcpClient } from './mcp.ts';
+export type { MCPClient, MCPClientOptions, MCPToolDef } from './mcp.ts';
+export { notifier } from './notifier/index.ts';
+export type { NotifierOptions, Notifier, NotifierInjected, NotifyMessage, Notification, NotifyChannel, NotifyPreferences, } from './notifier/types.ts';