weifuwu 0.24.3 → 0.25.1

package/dist/mcp.d.ts

@@ -0,0 +1,34 @@
+export interface MCPClientOptions {
+    /** Command to spawn (e.g. 'npx', 'node', 'uvx'). */
+    command: string;
+    /** Arguments passed to the command. */
+    args?: string[];
+    /** Environment variables (merged with process.env). */
+    env?: Record<string, string>;
+    /** How long to wait for handshake/response (ms). Default: 15_000. */
+    timeout?: number;
+    /** Max tool response body size in bytes. Default: 10MB. */
+    maxResponseSize?: number;
+}
+/** A tool definition from an MCP server. */
+export interface MCPToolDef {
+    name: string;
+    description?: string;
+    inputSchema?: {
+        type: 'object';
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/** MCP client — spawns and manages a single MCP server subprocess. */
+export interface MCPClient {
+    /** Fetch tool definitions from the server and return AI SDK Tool objects. */
+    getTools(): Promise<Record<string, unknown>>;
+    /** Refresh tool definitions (re-call tools/list). */
+    refresh(): Promise<void>;
+    /** Call a tool by name. Returns the raw result from the MCP server. */
+    callTool(name: string, args: unknown): Promise<unknown>;
+    /** Shutdown the MCP server and release resources. */
+    close(): Promise<void>;
+}
+export declare function mcpClient(options: MCPClientOptions): MCPClient;

package/dist/notifier/client.d.ts

@@ -0,0 +1,2 @@
+import type { Notifier, NotifierOptions } from './types.ts';
+export declare function notifier(opts: NotifierOptions): Notifier;

package/dist/notifier/index.d.ts

@@ -0,0 +1,2 @@
+export { notifier } from './client.ts';
+export type { NotifierOptions, Notifier, NotifierInjected, NotifyMessage, Notification, NotifyChannel, NotifyPreferences, } from './types.ts';

package/dist/notifier/types.d.ts

@@ -0,0 +1,105 @@
+import type { Context, Middleware, Closeable } from '../types.ts';
+import type { Mailer } from '../mailer.ts';
+import type { Hub } from '../hub.ts';
+import type { SqlClient } from '../vendor.ts';
+declare module '../types.ts' {
+    interface Context {
+        notifier: Notifier;
+    }
+}
+/** Shape injected into ctx when notifier middleware is active. */
+export interface NotifierInjected {
+    notifier: Notifier;
+}
+/** Configuration for the notifier module. */
+export interface NotifierOptions {
+    /** SQL client (PostgreSQL) for persistent notifications. */
+    sql: SqlClient;
+    /** Optional mailer for email channel. */
+    mailer?: Mailer;
+    /** Optional hub for WebSocket push channel. */
+    hub?: Hub;
+    /** Default sender name for email (default: system name). */
+    fromName?: string;
+    /** Table name for notifications (default: '_notifications'). */
+    table?: string;
+    /** Max notification list page size (default: 50). */
+    pageSize?: number;
+}
+/** A notification message. */
+export interface NotifyMessage {
+    /** Notification title. */
+    title: string;
+    /** Notification body text. */
+    body?: string;
+    /** Optional action URL. */
+    actionUrl?: string;
+    /** Optional action button text. */
+    actionText?: string;
+    /** Notification type for categorization (default: 'default'). */
+    type?: string;
+    /** Arbitrary metadata (JSON object). */
+    metadata?: Record<string, unknown>;
+}
+/** A notification record from the database. */
+export interface Notification {
+    id: number;
+    user_id: number;
+    title: string;
+    body: string;
+    action_url: string | null;
+    action_text: string | null;
+    type: string;
+    metadata: Record<string, unknown>;
+    read_at: string | null;
+    created_at: string;
+}
+/** Supported notification channels. */
+export type NotifyChannel = 'inbox' | 'email' | 'ws';
+/** User's channel preferences for a notification type. */
+export interface NotifyPreferences {
+    /** Which channels are enabled. Default: ['inbox']. */
+    channels: NotifyChannel[];
+}
+/** The notifier API injected into ctx. */
+export interface Notifier extends Closeable {
+    /**
+     * Send a notification to a specific user.
+     * Routes through the user's channel preferences automatically.
+     */
+    send(to: {
+        userId: number;
+        email?: string;
+    }, message: NotifyMessage): Promise<void>;
+    /**
+     * Send a system-wide notification to all users.
+     * Useful for announcements.
+     */
+    broadcast(message: NotifyMessage): Promise<void>;
+    /** Get user's unread notification count. */
+    unreadCount(userId: number): Promise<number>;
+    /** Mark specific notifications as read. If no ids given, mark all as read. */
+    markRead(userId: number, notificationIds?: number[]): Promise<void>;
+    /** List notifications for a user, newest first. */
+    list(userId: number, opts?: {
+        limit?: number;
+        offset?: number;
+        unreadOnly?: boolean;
+    }): Promise<Notification[]>;
+    /** Get or set user's notification channel preferences. */
+    getPreferences(userId: number): Promise<NotifyPreferences>;
+    setPreferences(userId: number, prefs: NotifyPreferences): Promise<void>;
+    /** Count total notifications for a user. */
+    count(userId: number, unreadOnly?: boolean): Promise<number>;
+    /** Clean up old notifications (older than days). */
+    clean(days: number): Promise<number>;
+    /** Create the notifications and preferences tables. Safe to call multiple times. */
+    migrate(): Promise<void>;
+    /** Release resources. */
+    close(): Promise<void>;
+}
+/** Notifier middleware type. */
+export interface NotifierMiddleware extends Middleware<Context, Context & NotifierInjected>, Notifier {
+    /** Alias for backward compatibility. */
+    middleware: () => Middleware<Context, Context & NotifierInjected>;
+}

package/dist/opencode/rest.d.ts

@@ -1,8 +1,9 @@
 import { Router } from '../router.ts';
 import type { LanguageModel } from 'ai';
+import type { SqlClient } from '../vendor.ts';
 import type { SkillDef, SkillRegistry, OpencodePermissions, PendingQuestion } from './types.ts';
 interface RestDeps {
-    sql: any;
+    sql: SqlClient;
     model: LanguageModel;
     workspace: string;
     systemPrompt?: string;

package/dist/opencode/ws.d.ts

@@ -1,9 +1,9 @@
-import type { WebSocket } from '../vendor.ts';
+import type { WebSocket, SqlClient } from '../vendor.ts';
 import type { LanguageModel } from 'ai';
 import type { Context } from '../types.ts';
 import type { PendingQuestion, SkillDef, SkillRegistry, OpencodePermissions } from './types.ts';
 interface WsDeps {
-    sql: any;
+    sql: SqlClient;
     model: LanguageModel;
     workspace: string;
     systemPrompt?: string;

package/dist/queue/types.d.ts

@@ -43,7 +43,6 @@ export interface Queue extends Middleware<Context, Context & QueueInjected>, Clo
     }): Promise<string>;
     process<T>(type: string, handler: (job: QueueJob<T>) => Promise<void>): void;
     run(): Promise<void>;
-    stop(): void;
     stats(): {
         running: boolean;
         inflight: number;

package/dist/rate-limit.d.ts

@@ -1,5 +1,5 @@
 import type { Redis } from './vendor.ts';
-import type { Context, Middleware } from './types.ts';
+import type { Context, Middleware, Closeable } from './types.ts';
 /** Options for {@link rateLimit}. */
 export interface RateLimitOptions {
     /** Maximum requests within the window (default: 100). */
@@ -17,6 +17,14 @@ export interface RateLimitOptions {
     /** Redis key prefix (default: `'ratelimit:'`). */
     prefix?: string;
 }
+/** Rate limit module — middleware + stats. */
+export interface RateLimitModule extends Middleware<Context, Context>, Closeable {
+    stats(): {
+        store: string;
+        entries?: number;
+        maxEntries: number;
+    };
+}
 /**
  * Rate limiting middleware (in-memory or Redis-backed).
  *
@@ -34,7 +42,4 @@ export interface RateLimitOptions {
  * app.use(rateLimit({ store: 'redis', redis: new Redis(), max: 100 }))
  * ```
  */
-export declare function rateLimit(options?: RateLimitOptions): Middleware<Context, Context> & {
-    close: () => void;
-    stop?: () => void;
-};
+export declare function rateLimit(options?: RateLimitOptions): RateLimitModule;

package/dist/redis/client.d.ts

@@ -0,0 +1,2 @@
+import type { RedisOptions, RedisClient } from './types.ts';
+export declare function redis(opts?: string | RedisOptions): RedisClient;

package/dist/redis/index.d.ts

@@ -1,3 +1,2 @@
-import type { RedisOptions, RedisClient } from './types.ts';
-export { redis as default };
-export declare function redis(opts?: string | RedisOptions): RedisClient;
+export { redis } from './client.ts';
+export type { RedisOptions, RedisClient, RedisInjected } from './types.ts';

package/dist/router.d.ts

@@ -10,6 +10,24 @@ export type WebSocketHandler = {
     error?: (ws: WebSocket, ctx: Context, error: Error) => void | Promise<void>;
 };
 type WsUpgradeHandler = (req: IncomingMessage, socket: Duplex, head: Buffer) => void;
+/**
+ * Middleware metadata for dependency checking.
+ * Middleware factories can attach this to their return value for runtime validation.
+ *
+ * ```ts
+ * function postgres(): PostgresClient {
+ *   const mw = async (req, ctx, next) => { ... }
+ *   mw.__meta = { injects: ['sql'], depends: [] }
+ *   return Object.assign(mw, { sql, migrate, close })
+ * }
+ * ```
+ */
+export interface MiddlewareMeta {
+    /** Fields this middleware injects into ctx. */
+    injects: string[];
+    /** Fields this middleware depends on (must be injected earlier). */
+    depends: string[];
+}
 export declare class Router<T extends Context = Context> {
     private root;
     private wsRoot;
@@ -18,6 +36,8 @@ export declare class Router<T extends Context = Context> {
     private _hasWildcard;
     private _hub?;
     private _wss?;
+    /** Track which ctx fields have been injected so far (for dependency checking). */
+    private _ctxFields;
     private get wss();
     private get hub();
     /** Inject a custom hub (e.g. with Redis for cross-process broadcast). */
@@ -28,6 +48,16 @@ export declare class Router<T extends Context = Context> {
     use(mod: Router & {
         middleware: () => Middleware;
     }): Router<T>;
+    /**
+     * Check a middleware's dependency metadata and emit warnings if
+     * required fields haven't been injected yet.
+     * Attach __meta to a middleware function:
+     *
+     * ```ts
+     * mw.__meta = { injects: ['sql'], depends: ['session'] }
+     * ```
+     */
+    private _checkMiddlewareMeta;
     get(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
     post(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;
     put(path: string, ...args: [...Middleware<T, T>[], Handler<T> | Router<Context>]): Router<T>;

package/dist/serve.d.ts

@@ -1,6 +1,6 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import type { Duplex } from 'node:stream';
-import type { Handler } from './types.ts';
+import { type Handler } from './types.ts';
 export interface ServeOptions {
     port?: number;
     hostname?: string;

package/dist/session.d.ts

@@ -80,6 +80,10 @@ export declare class MemoryStore implements SessionStore {
     /** Testing only: return approximate count. */
     get size(): number;
 }
+/**
+ * Redis-backed session store.
+ * Pass to `session({ store: new RedisStore({ redis }) })`.
+ */
 export declare class RedisStore implements SessionStore {
     private redis;
     private prefix;
@@ -90,6 +94,22 @@ export declare class RedisStore implements SessionStore {
     destroy(sid: string): Promise<void>;
     close(): Promise<void>;
 }
+/**
+ * Session middleware. Injects `ctx.session` with a persistent key-value store
+ * scoped to the request. Data is automatically saved to the store on response.
+ *
+ * Defaults to memory store. Use `{ store: 'redis', redis }` for multi-process setups.
+ *
+ * ```ts
+ * import { session } from 'weifuwu'
+ * app.use(session())
+ *
+ * app.get('/visit', (req, ctx) => {
+ *   ctx.session.count = (ctx.session.count ?? 0) + 1
+ *   return Response.json({ visits: ctx.session.count })
+ * })
+ * ```
+ */
 export declare function session(options?: SessionOptions): Middleware<Context, Context & SessionInjected> & {
     close: () => Promise<void>;
     store: SessionStore;

package/dist/test-utils.d.ts

@@ -1,5 +1,7 @@
 import type { Context, Handler } from './types.ts';
 import type { SqlClient } from './vendor.ts';
+import { Router } from './router.ts';
+import { WebSocket as WSWebSocket } from 'ws';
 export interface TestResponse {
     readonly status: number;
     readonly headers: Headers;
@@ -35,7 +37,15 @@ export declare class TestRequest {
 }
 export declare class TestApp {
     private router;
+    private wsServer;
+    private wsConnections;
     constructor();
+    /**
+     * Register a WebSocket handler.
+     */
+    ws(path: string, handler: import('./router.ts').WebSocketHandler): this;
+    /** Get the raw Router (for advanced use). */
+    get _router(): Router;
     /** Add global middleware */
     use(mw: any): this;
     /** Register a GET route — supports route-level middleware via spread args. */
@@ -60,6 +70,74 @@ export declare class TestApp {
     deleteReq(path: string): TestRequest;
     /** Get the underlying handler (for advanced usage) */
     handler(): Handler;
+    /** Start building a WebSocket connection to the given path. */
+    wsReq(path: string): TestWSRequest;
+    /**
+     * Internal: ensure HTTP server is running for WebSocket connections.
+     * Starts on a random port.
+     */
+    _ensureServer(): Promise<string>;
+    /**
+     * Internal: register a WS connection for cleanup.
+     */
+    _trackConnection(conn: TestWSConnection): void;
+    /**
+     * Cleanup all WebSocket connections and stop the server.
+     */
+    close(): Promise<void>;
+}
+/** Start building a WebSocket test connection. */
+export declare class TestWSRequest {
+    private app;
+    private path;
+    private _timeout;
+    constructor(app: TestApp, path: string);
+    /** Set the timeout for operations (default: 5000ms). */
+    timeout(ms: number): this;
+    /**
+     * Connect to the WebSocket endpoint.
+     * Starts a real HTTP server (random port) if not already running.
+     */
+    connect(): Promise<TestWSConnection>;
+}
+/**
+ * A connected WebSocket for testing.
+ *
+ * ```ts
+ * const conn = await app.wsReq('/echo').connect()
+ * conn.send('hello')
+ * const msg = await conn.receive()
+ * assert.equal(msg, 'hello')
+ * conn.close()
+ * ```
+ */
+export declare class TestWSConnection {
+    private ws;
+    private _timeout;
+    private messageQueue;
+    private resolveQueue;
+    private _closed;
+    constructor(ws: WSWebSocket, timeout?: number);
+    /** Send a text message. */
+    send(data: string): void;
+    /** Send a JSON message. */
+    json(data: unknown): void;
+    /**
+     * Wait for the next message. Returns the raw text.
+     * Throws on timeout or if the connection is closed.
+     */
+    receive(timeout?: number): Promise<string>;
+    /** Wait for the next message and parse as JSON. */
+    receiveJson<T = unknown>(): Promise<T>;
+    /**
+     * Assert that no message is received within the given silence period.
+     * Useful for verifying that something did NOT happen.
+     */
+    expectSilent(ms: number): Promise<void>;
+    /** Close the connection. */
+    close(): void;
+    /** Whether the connection is closed. */
+    get closed(): boolean;
 }
 /** Create a new test app */
 export declare function testApp(): TestApp;
@@ -84,7 +162,7 @@ export interface TestDb {
  *
  * ```ts
  * const db = await createTestDb()
- * await db.sql\`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)\`
+ * await db.sql`CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT)`
  * // ... run tests ...
  * await db.destroy()  // drops the schema
  * ```
@@ -103,7 +181,7 @@ export declare function createTestDb(options?: {
  *
  * ```ts
  * await withTestDb(async (sql) => {
- *   await sql\`INSERT INTO users ...\`
+ *   await sql`INSERT INTO users ...`
  *   // All changes are rolled back after this callback returns
  * })
  * ```

package/dist/types.d.ts

@@ -19,3 +19,16 @@ export interface Closeable {
     /** Release all resources. Call once when shutting down. */
     close(): Promise<void>;
 }
+/**
+ * HTTP error with an explicit status code.
+ * Throw from a handler or middleware to return a non-200 response.
+ *
+ * ```ts
+ * if (!resource) throw new HttpError('Not found', 404)
+ * serve() catches it and returns the status code.
+ * ```
+ */
+export declare class HttpError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}

package/dist/user/client.d.ts

@@ -1,4 +1,9 @@
-import type { UserOptions, UserModule } from './types.ts';
+import type { UserOptions, UserData, UserModule } from './types.ts';
+declare module '../types.ts' {
+    interface Context {
+        user: UserData;
+    }
+}
 /**
  * User authentication module — local register/login, JWT verification, OAuth2 server, social login.
  * Supports DB-less auth via tokens/verify/proxy options.

package/dist/user/types.d.ts

@@ -81,6 +81,8 @@ export interface UserOptions {
      * If not provided and no pg, `ctx.user` is set to `{ id: userId }`.
      */
     resolveUser?: (userId: unknown) => unknown | Promise<unknown>;
+    /** Enable API key management (per-user keys with scopes). */
+    apiKeys?: boolean;
     /** Enable OAuth2 server mode (authorization code flow). */
     oauth2?: OAuth2ServerOptions;
     /**
@@ -152,6 +154,25 @@ export interface UserModule extends Router, Closeable {
     getClient: (clientId: string) => Promise<OAuth2Client | null>;
     /** Revoke an OAuth2 client. */
     revokeClient: (clientId: string) => Promise<void>;
+    /** Create a new API key for a user. Returns the full key (only shown once). */
+    createApiKey: (userId: number, name: string, scopes?: string[]) => Promise<{
+        id: number;
+        key: string;
+    }>;
+    /** List user\'s API keys (masked — only prefix + last 4 chars visible). */
+    listApiKeys: (userId: number) => Promise<ApiKeyInfo[]>;
+    /** Revoke an API key by ID. */
+    revokeApiKey: (userId: number, keyId: number) => Promise<void>;
     /** Close the underlying DB connection. */
     close: () => Promise<void>;
 }
+/** An API key record (as returned by listApiKeys — masked). */
+export interface ApiKeyInfo {
+    id: number;
+    name: string;
+    prefix: string;
+    scopes: string[];
+    last_used_at: string | null;
+    created_at: string;
+    revoked: boolean;
+}

package/dist/validate.d.ts

@@ -11,4 +11,20 @@ export interface ValidationSchemas {
     params?: ZodSchema;
     headers?: ZodSchema;
 }
+/**
+ * Request validation middleware using Zod schemas.
+ *
+ * Validates `params`, `query`, `body`, and/or `headers` against schemas.
+ * Returns 422 with error details on mismatch.
+ * Injects `ctx.parsed` with validated-and-transformed values.
+ *
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * app.get('/users/:id', validate({
+ *   params: z.object({ id: z.string() }),
+ *   query: z.object({ include: z.string().optional() }),
+ * }), handler)
+ * ```
+ */
 export declare function validate(schemas?: ValidationSchemas): Middleware;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.24.3",
+  "version": "0.25.1",
   "description": "Web-standard HTTP framework for Node.js — (req, ctx) => Response",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",