weifuwu 0.23.2 → 0.23.3

package/dist/request-id.d.ts

@@ -1,8 +1,27 @@
 import type { Context, Middleware } from './types.ts';
+/** Options for {@link requestId}. */
 export interface RequestIdOptions {
+    /** Header name for request ID (default: `'X-Request-ID'`). */
     header?: string;
+    /** Custom ID generator (default: `crypto.randomUUID`). */
     generator?: () => string;
 }
+/**
+ * Request ID middleware.
+ *
+ * Reads an incoming `X-Request-ID` header (or custom header name) from the
+ * request. If absent, generates a new UUID. Sets the response header and
+ * injects `ctx.requestId`.
+ *
+ * ```ts
+ * import { requestId } from 'weifuwu'
+ * app.use(requestId())
+ *
+ * app.get('/', (req, ctx) => {
+ *   console.log('request ID:', ctx.requestId)
+ * })
+ * ```
+ */
 export declare function requestId(options?: RequestIdOptions): Middleware<Context, Context & {
     requestId: string;
 }>;

package/dist/seo.d.ts

@@ -1,39 +1,104 @@
 import type { Middleware } from './types.ts';
 import { Router } from './router.ts';
+/** A rule in `robots.txt`. */
 export interface RobotsRule {
+    /** User-agent this rule applies to (default: `'*'`). */
     userAgent?: string;
+    /** Path(s) to allow. */
     allow?: string | string[];
+    /** Path(s) to disallow. */
     disallow?: string | string[];
 }
+/** A URL entry in `sitemap.xml`. */
 export interface SitemapUrl {
+    /** Absolute URL of the page. */
     loc: string;
+    /** Last modification date (ISO 8601). */
     lastmod?: string;
+    /** Expected change frequency. */
     changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    /** Priority (0.0 to 1.0). */
     priority?: number;
 }
+/** Configuration for sitemap generation. */
 export interface SitemapConfig {
+    /** Static list of URLs to include. */
     urls?: SitemapUrl[];
+    /** Dynamic URL resolver (called on each sitemap request, or cached per `cacheTTL`). */
     resolve?: () => SitemapUrl[] | Promise<SitemapUrl[]>;
+    /** Cache TTL in ms (default: 3600000 = 1 hour). Set 0 to disable cache. */
     cacheTTL?: number;
 }
+/** Configuration for per-path response headers. */
 export interface SeoHeadersConfig {
+    /** `X-Robots-Tag` header value. Use a function for path-dependent values. */
     'X-Robots-Tag'?: string | ((path: string) => string | undefined);
 }
+/** Options for {@link seo}. */
 export interface SeoOptions {
+    /** Rules for `robots.txt`. */
     robots?: RobotsRule[];
+    /** Configuration for `sitemap.xml`. */
     sitemap?: SitemapConfig;
+    /** Per-path response headers. */
     headers?: SeoHeadersConfig;
     baseUrl?: string;
 }
+/**
+ * SEO middleware — sets `X-Robots-Tag` headers per path.
+ * Used standalone or included automatically by {@link seo}.
+ *
+ * ```ts
+ * app.use(seoMiddleware({
+ *   headers: { 'X-Robots-Tag': (path) => path.startsWith('/admin') ? 'noindex' : undefined },
+ * }))
+ * ```
+ */
 export declare function seoMiddleware(options?: SeoOptions): Middleware;
+/**
+ * SEO module — serves `robots.txt` and `sitemap.xml`.
+ *
+ * ```ts
+ * import { seo } from 'weifuwu'
+ *
+ * app.use(seo({
+ *   robots: [{ userAgent: '*', allow: '/', disallow: '/admin' }],
+ *   sitemap: {
+ *     resolve: async () => [
+ *       { loc: 'https://example.com/', changefreq: 'daily', priority: 1.0 },
+ *     ],
+ *   },
+ * }))
+ * ```
+ */
 export declare function seo(options?: SeoOptions): Router;
+/** Options for {@link seoTags}. */
 export interface SeoTagsConfig {
+    /** Page title (`<title>` + `og:title`). */
     title?: string;
+    /** Meta description. */
     description?: string;
+    /** Open Graph image URL. */
     ogImage?: string;
+    /** Override `og:title` (defaults to `title`). */
     ogTitle?: string;
+    /** Override `og:description` (defaults to `description`). */
     ogDescription?: string;
+    /** Twitter card type. */
     twitterCard?: 'summary' | 'summary_large_image';
+    /** Canonical URL (`<link rel="canonical">`). */
     canonical?: string;
 }
+/**
+ * Generate `<meta>` and `<link>` tag HTML string for SEO.
+ *
+ * ```ts
+ * const tags = seoTags({
+ *   title: 'My App',
+ *   description: 'A description',
+ *   ogImage: 'https://example.com/og.png',
+ * })
+ * // <meta name="description" content="A description" />...
+ * ```
+ */
 export declare function seoTags(config: SeoTagsConfig): string;

package/dist/sse.d.ts

@@ -1,9 +1,46 @@
+/**
+ * Format an SSE message string with a named event type.
+ *
+ * ```ts
+ * formatSSE('ping', { ts: Date.now() })
+ * // "event: ping\ndata: {"ts":...}\n\n"
+ * ```
+ */
 export declare function formatSSE(event: string, data: unknown): string;
+/**
+ * Format an SSE message string with only a data line (no event type).
+ *
+ * ```ts
+ * formatSSEData({ message: 'hello' })
+ * // "data: {"message":"hello"}\n\n"
+ * ```
+ */
 export declare function formatSSEData(data: unknown): string;
+/** An SSE event to be sent via {@link createSSEStream}. */
 export interface SSEEvent {
+    /** Event type (maps to `event:` field). */
     event: string;
+    /** Event payload (serialized as JSON in `data:` field). */
     data: unknown;
 }
+/**
+ * Create a Server-Sent Events (SSE) `Response` from an async iterable.
+ *
+ * Each item in the iterable is serialized as an SSE message:
+ * - If the item has a `.type` property → `event: {type}` + `data: {item}`
+ * - Otherwise → `data: {item}`
+ *
+ * Errors are sent as `event: error` messages. `AbortError` is silently ignored.
+ *
+ * ```ts
+ * app.get('/events', () => {
+ *   async function* generate() {
+ *     yield { type: 'ping', data: { ts: Date.now() } }
+ *   }
+ *   return createSSEStream(generate())
+ * })
+ * ```
+ */
 export declare function createSSEStream(iterable: AsyncIterable<any>, opts?: {
     headers?: Record<string, string>;
     status?: number;

package/dist/static.d.ts

@@ -1,7 +1,23 @@
 import type { Handler } from './types.ts';
+/** Options for {@link serveStatic}. */
 export interface ServeStaticOptions {
+    /** Directory index filename (default: `'index.html'`). */
     index?: string;
+    /** `Cache-Control max-age` in seconds. */
     maxAge?: number;
+    /** Add `immutable` to `Cache-Control` (requires `maxAge`). */
     immutable?: boolean;
 }
+/**
+ * Static file serving handler.
+ *
+ * Serves files from a root directory. Supports ETag/304, directory index,
+ * Content-Type detection by extension, and directory traversal protection.
+ *
+ * ```ts
+ * import { serveStatic, Router } from 'weifuwu'
+ * const app = new Router()
+ * app.get('/static/*', serveStatic('./public'))
+ * ```
+ */
 export declare function serveStatic(root: string, options?: ServeStaticOptions): Handler;

package/dist/stream.d.ts

@@ -1,14 +1,29 @@
 import type { Context } from './types.ts';
+/** Options for {@link streamResponse}. */
 export interface StreamOpts {
+    /** Request context (for injecting hydration data). */
     ctx: Context;
+    /** Base path for SSR asset URLs. */
     base: string;
+    /** Tailwind CSS context. */
     tailwind?: {
         css: string;
         url: string;
     };
+    /** Whether in development mode (injects livereload script). */
     isDev: boolean;
+    /** HTTP status code (default: 200). */
     status?: number;
+    /** Serialized loader data injected into the HTML shell. */
     loaderData?: Record<string, unknown>;
 }
 export declare function readStream(stream: ReadableStream): Promise<string>;
+/**
+ * Create an HTML response from a React SSR stream.
+ *
+ * Injects the React stream into an HTML shell, adds hydration script,
+ * loader data script, tailwind CSS, and (in dev mode) livereload script.
+ *
+ * Used internally by {@link ssr}.
+ */
 export declare function streamResponse(reactStream: ReadableStream, opts: StreamOpts, hydrationScript?: string): Response;

package/dist/trace.d.ts

@@ -1,15 +1,51 @@
 export interface TraceContext {
+    /** Unique identifier for the current request trace. */
     traceId: string;
+    /** Timestamp (ms since epoch) when the trace started. */
     startTime: number;
 }
-/** Returns the current request's trace ID, or undefined if outside a request. */
+/**
+ * Get the current request's trace ID.
+ * Returns `undefined` when called outside a request context (e.g. at startup).
+ *
+ * ```ts
+ * const traceId = currentTraceId()
+ * log.info({ traceId }, 'request started')
+ * ```
+ */
 export declare function currentTraceId(): string | undefined;
-/** Returns the current full trace context, or undefined if outside a request. */
+/**
+ * Get the full current trace context ({ traceId, startTime }).
+ * Returns `undefined` outside a request.
+ */
 export declare function currentTrace(): TraceContext | undefined;
 /**
- * Run a function inside a trace context. Used internally by serve().
- * If an incoming trace header is present, it's reused; otherwise a new one is generated.
+ * Run a function inside a trace context.
+ * Used internally by `serve()` for every incoming request.
+ * If `incomingTraceId` is provided (e.g. from an `X-Trace-Id` header) it is reused;
+ * otherwise a new UUID is generated.
+ *
+ * ```ts
+ * const result = runWithTrace(req.headers.get('x-trace-id'), () => {
+ *   return handleRequest(req)
+ * })
+ * ```
+ *
+ * @param incomingTraceId - Optional trace ID from upstream. Pass `null` to auto-generate.
+ * @param fn - Function to execute within the trace scope.
+ * @returns The return value of `fn`.
  */
 export declare function runWithTrace<T>(incomingTraceId: string | null, fn: () => T): T;
-/** Elapsed time in ms since the trace started. */
+/**
+ * Milliseconds elapsed since the current trace started.
+ * Returns `0` if called outside a request context.
+ *
+ * ```ts
+ * app.use(async (req, ctx, next) => {
+ *   const res = await next(req, ctx)
+ *   console.log('handled in', traceElapsed(), 'ms')
+ *   return res
+ * })
+ * ```
+ */
 export declare function traceElapsed(): number;

package/dist/types.d.ts

@@ -4,10 +4,19 @@ export interface Context {
     user?: unknown;
     parsed?: Record<string, unknown>;
     mountPath?: string;
-    theme?: string;
+    theme?: {
+        value: string;
+        set?: (value: string, loc?: string) => Response;
+    };
+    flash?: {
+        value: unknown;
+        set: (data: unknown, location?: string) => Response;
+    };
     i18n?: {
         locale: string;
+        messages?: Record<string, unknown>;
         t: (key: string, params?: Record<string, string>, fallback?: string) => string;
+        set?: (value: string, loc?: string) => Response;
     };
     env?: Record<string, string>;
     layoutStack?: {

package/dist/upload.d.ts

@@ -1,14 +1,44 @@
 import type { Middleware } from './types.ts';
+/** A parsed file from a multipart upload. */
 export interface UploadedFile {
+    /** Original filename from the client. */
     name: string;
+    /** MIME type from the `Content-Type` part header. */
     type: string;
+    /** File size in bytes. */
     size: number;
+    /** Path where the file was saved (when `dir` option is set). */
     path?: string;
+    /** File content as Buffer (when `dir` option is not set). */
     buffer?: Buffer;
 }
+/** Options for {@link upload}. */
 export interface UploadOptions {
+    /** Directory to save uploaded files. If not set, files stay in memory via `.buffer`. */
     dir?: string;
+    /** Maximum file size in bytes. Default: 10 MB. Set `0` to allow unlimited. */
     maxFileSize?: number;
+    /** Allowed MIME types (e.g. `['image/jpeg', 'image/png']`). Empty array allows all. */
     allowedTypes?: string[];
 }
+/**
+ * Multipart file upload middleware.
+ *
+ * Parses `multipart/form-data` requests, extracting files and fields.
+ * Files can be saved to disk (`dir` option) or kept in memory as Buffers.
+ * Parsed fields are available in `ctx.parsed`.
+ *
+ * ```ts
+ * import { upload } from 'weifuwu'
+ *
+ * // Save to disk
+ * app.use(upload({ dir: './uploads', maxFileSize: 5_000_000 }))
+ *
+ * // In-memory
+ * app.post('/upload', async (req, ctx) => {
+ *   const file = ctx.parsed?.file as UploadedFile
+ *   console.log(file.name, file.type, file.buffer!.length)
+ * })
+ * ```
+ */
 export declare function upload(options?: UploadOptions): Middleware;

package/dist/use-action.d.ts

@@ -1,14 +1,42 @@
+/** Options for {@link useAction}. */
 export interface UseActionOptions<T = any> {
+    /** HTTP method (default: `'POST'`). */
     method?: string;
+    /** Additional request headers. */
     headers?: Record<string, string>;
+    /** Called with the response data on success. */
     onSuccess?: (data: T) => void;
+    /** Called with the error on failure. */
     onError?: (err: Error) => void;
 }
+/** Return value of {@link useAction}. */
 export interface UseActionReturn<T = any> {
+    /** Submit the action. Pass a body to send as JSON (or FormData). */
     submit: (body?: any) => Promise<T | undefined>;
+    /** Response data from the last successful submission. */
     data: T | null;
+    /** Error from the last failed submission. */
     error: Error | null;
+    /** Whether a submission is in progress. */
     pending: boolean;
+    /** Reset data and error to their initial states. */
     reset: () => void;
 }
+/**
+ * Hook to submit form actions via `fetch`. Handles JSON serialization,
+ * CSRF token injection, and loading/error state.
+ *
+ * ```tsx
+ * import { useAction } from 'weifuwu/react'
+ *
+ * function SaveButton() {
+ *   const { submit, pending, error } = useAction('/api/save')
+ *   return (
+ *     <button onClick={() => submit({ title: 'Hello' })} disabled={pending}>
+ *       {pending ? 'Saving...' : 'Save'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
 export declare function useAction<T = any>(url: string | URL, options?: UseActionOptions<T>): UseActionReturn<T>;

package/dist/use-agent-stream.d.ts

@@ -1,27 +1,49 @@
+/** Streaming state for all agents in a channel. */
 export interface AgentStreamState {
-    /** Accumulated streaming text per agent, keyed by agent_id */
+    /** Accumulated streaming text per agent, keyed by `agent_id`. */
     streams: Record<number, string>;
-    /** Whether any agent is currently streaming (typing) */
+    /** Whether any agent is currently streaming (typing). */
     streaming: boolean;
-    /** Set of agent IDs currently streaming */
+    /** Set of agent IDs currently streaming. */
     activeAgents: Set<number>;
 }
+/** Options for {@link useAgentStream}. */
 export interface UseAgentStreamOptions {
-    /** WebSocket path, e.g. '/ws' */
+    /** WebSocket path, e.g. `'/ws'`. */
     wsPath: string;
-    /** Channel ID to listen for agent streams */
+    /** Channel ID to listen for agent streams. */
     channelId: number;
-    /** Called when a stream finishes (agent done generating) */
+    /** Called when an agent finishes generating. */
     onStreamEnd?: (agentId: number, fullText: string) => void;
-    /** Called on stream error */
+    /** Called on stream error. */
     onError?: (agentId: number, error: string) => void;
 }
+/** Return value of {@link useAgentStream}. */
 export interface UseAgentStreamReturn {
-    /** Accumulated streaming state */
+    /** Accumulated streaming state for all agents. */
     stream: AgentStreamState;
-    /** Get accumulated text for a specific agent */
+    /** Get accumulated text for a specific agent by ID. */
     getAgentText: (agentId: number) => string;
-    /** Whether a specific agent is currently streaming */
+    /** Whether a specific agent is currently streaming. */
     isAgentStreaming: (agentId: number) => boolean;
 }
+/**
+ * React hook to consume agent AI streaming output via WebSocket.
+ *
+ * Connects to a WebSocket endpoint, listens for `agent_stream`,
+ * `agent_stream_end`, and `agent_error` messages, and accumulates
+ * the token stream per agent.
+ *
+ * ```tsx
+ * import { useAgentStream } from 'weifuwu/react'
+ *
+ * function Chat() {
+ *   const { stream, getAgentText } = useAgentStream({
+ *     wsPath: '/ws/chat',
+ *     channelId: 1,
+ *   })
+ *   return <pre>{getAgentText(1)}</pre>
+ * }
+ * ```
+ */
 export declare function useAgentStream(opts: UseAgentStreamOptions): UseAgentStreamReturn;

package/dist/use-flash-message.d.ts

@@ -1 +1,17 @@
+/**
+ * React hook to read the server-flashed message on the client side.
+ *
+ * Reads `window.__WEIFUWU_CTX.flash.value` (set by the flash middleware
+ * during SSR). Returns `null` when no flash message is present.
+ *
+ * ```tsx
+ * import { useFlashMessage } from 'weifuwu/react'
+ *
+ * function FlashNotice() {
+ *   const flash = useFlashMessage<{ type: string; text: string }>()
+ *   if (!flash) return null
+ *   return <div className={flash.type}>{flash.text}</div>
+ * }
+ * ```
+ */
 export declare function useFlashMessage<T = any>(): T | null;

package/dist/use-websocket.d.ts

@@ -1,17 +1,42 @@
+/** Options for {@link useWebsocket}. */
 export type UseWebsocketOptions = {
+    /** Called when a message is received. */
     onMessage?: (data: string) => void;
+    /** Auto-reconnect config. Set to `false` to disable. Default: `{ maxRetries: 10, delay: 3000 }`. */
     reconnect?: boolean | {
         maxRetries?: number;
         delay?: number;
     };
+    /** WebSocket sub-protocols. */
     protocols?: string | string[];
+    /** Whether the WebSocket is enabled. Set to `false` to keep closed. Default: `true`. */
     enabled?: boolean;
 };
+/** Return value of {@link useWebsocket}. */
 export type UseWebsocketReturn = {
+    /** Send data through the WebSocket. */
     send: (data: string | ArrayBuffer | Blob) => void;
+    /** Close the WebSocket manually. */
     close: () => void;
+    /** Current `WebSocket.readyState`. */
     readyState: number;
+    /** The last received message string. */
     lastMessage: string | null;
+    /** Manually trigger reconnection. */
     reconnect: () => void;
 };
+/**
+ * React hook for WebSocket connections with auto-reconnect.
+ *
+ * ```tsx
+ * import { useWebsocket } from 'weifuwu/react'
+ *
+ * function Chat() {
+ *   const { send, lastMessage, readyState } = useWebsocket('/ws/chat', {
+ *     onMessage: (data) => console.log('received:', data),
+ *   })
+ *   return <button onClick={() => send('Hello')}>Send</button>
+ * }
+ * ```
+ */
 export declare function useWebsocket(url: string | URL | (() => string | URL | null), options?: UseWebsocketOptions): UseWebsocketReturn;

package/dist/user/client.d.ts

@@ -1,2 +1,17 @@
 import type { UserOptions, UserModule } from './types.ts';
+/**
+ * User authentication module — local register/login, JWT verification, OAuth2 server, social login.
+ *
+ * ```ts
+ * import { user, postgres } from 'weifuwu'
+ *
+ * const pg = postgres({ connection: DATABASE_URL })
+ * const auth = user({ pg, jwtSecret: process.env.JWT_SECRET })
+ *
+ * await auth.migrate()
+ *
+ * app.use(auth.middleware())   // inject `ctx.user` on every request
+ * app.use('/', auth)           // mount auth routes: /register, /login
+ * ```
+ */
 export declare function user(options: UserOptions): UserModule;

package/dist/user/oauth2.d.ts

@@ -7,6 +7,16 @@ interface OAuth2Deps {
     jwtSecret: string;
     expiresIn: string | number;
 }
+/**
+ * Create an OAuth2 authorization code server.
+ *
+ * Registers routes:
+ * - `GET /oauth/authorize` — authorization page (user consent)
+ * - `POST /oauth/consent` — user grants/denies access
+ * - `POST /oauth/token` — exchange code for access token
+ *
+ * Used internally by the user module when `oauth2: { server: true }` is set.
+ */
 export declare function createOAuth2Server(deps: OAuth2Deps): {
     authorizeHandler: (req: Request, _ctx: Context) => Promise<Response>;
     consentHandler: (req: Request) => Promise<Response>;