weifuwu 0.24.3 → 0.25.0

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/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/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/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/package.json

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