weifuwu 0.32.0 → 0.33.0

package/dist/kb/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * KB — RAG knowledge base module.
+ *
+ * Splits documents into chunks, embeds via DashScope text-embedding-v4,
+ * stores vectors in PostgreSQL with pgvector, and provides similarity search.
+ *
+ * Requires `postgres()` middleware registered first.
+ *
+ * @example
+ * ```ts
+ * import { serve, Router, postgres, kb } from 'weifuwu'
+ *
+ * const app = new Router()
+ * app.use(postgres())
+ * app.use(kb())
+ *
+ * // Import
+ * app.post('/api/kb/import', async (req, ctx) => {
+ *   const { title, content } = await req.json()
+ *   const result = await ctx.kb.importText(title, content)
+ *   return Response.json(result, { status: 201 })
+ * })
+ *
+ * // Search (RAG)
+ * app.post('/api/kb/search', async (req, ctx) => {
+ *   const { query } = await req.json()
+ *   const results = await ctx.kb.search(query, { limit: 5 })
+ *   return Response.json(results)
+ * })
+ *
+ * // Use with agent
+ * app.use(agent({
+ *   model: openai('deepseek-v4-flash', { baseURL: 'https://api.deepseek.com/v1' }),
+ *   knowledge: {
+ *     search: async (query, ctx) => ctx.kb.search(query),
+ *   },
+ * }))
+ * ```
+ */
+export { KB } from './module.ts';
+export type { KBAPI, KBOptions, Document, Chunk, SearchResult, ImportOptions, SearchOptions, } from './types.ts';
+import type { Context, Middleware } from '../types.ts';
+import type { KBAPI, KBOptions } from './types.ts';
+/**
+ * KB factory — creates the KB instance and returns a middleware
+ * that injects `ctx.kb`.
+ *
+ * Must be used **after** `postgres()`.
+ *
+ * ```ts
+ * app.use(postgres())
+ * app.use(kb())
+ * ```
+ */
+export declare function kb(opts?: KBOptions): Middleware<Context, Context & {
+    kb: KBAPI;
+}>;

package/dist/kb/module.d.ts

@@ -0,0 +1,37 @@
+/**
+ * KB — RAG knowledge base module.
+ *
+ * Splits documents into chunks, embeds them via DashScope text-embedding-v4,
+ * stores vectors in PostgreSQL with pgvector, and provides similarity search.
+ *
+ * Depends on `postgres()` middleware registered first.
+ *
+ * ```ts
+ * import { serve, Router, postgres, kb } from 'weifuwu'
+ *
+ * const app = new Router()
+ * app.use(postgres())
+ * app.use(kb())
+ *
+ * // Import
+ * await ctx.kb.importText('Getting Started', 'First, install the package...')
+ *
+ * // Search
+ * const results = await ctx.kb.search('how to install?', { limit: 5 })
+ * ```
+ */
+import type { Context, Handler, SqlClient } from '../types.ts';
+import type { KBAPI, KBOptions } from './types.ts';
+export declare class KB {
+    private migrated;
+    private embedFn;
+    private dimensions;
+    private chunkSize;
+    private chunkOverlap;
+    constructor(opts?: KBOptions);
+    private ms;
+    migrate(sql: SqlClient): Promise<void>;
+    private ensureMigrated;
+    bind(ctx: Context): KBAPI;
+    middleware(req: Request, ctx: Context, next: Handler): Promise<Response>;
+}

package/dist/kb/types.d.ts

@@ -0,0 +1,83 @@
+declare module '../types.ts' {
+    interface Context {
+        /** KB — RAG knowledge base module. */
+        kb: import('./types.ts').KBAPI;
+    }
+}
+export interface Document {
+    id: string;
+    title: string;
+    source: string | null;
+    metadata: Record<string, unknown>;
+    chunk_count: number;
+    created_at: Date;
+    updated_at: Date;
+}
+export interface Chunk {
+    id: string;
+    document_id: string | null;
+    content: string;
+    chunk_index: number;
+    tokens: number;
+    created_at: Date;
+}
+export interface SearchResult {
+    chunk_id: string;
+    document_id: string | null;
+    content: string;
+    score: number;
+    source?: string;
+    title?: string;
+}
+export interface ImportOptions {
+    /** Source identifier (e.g. URL, filename). */
+    source?: string;
+    /** Arbitrary metadata stored in the document. */
+    metadata?: Record<string, unknown>;
+    /** Chunk size in tokens (default: 512). */
+    chunkSize?: number;
+    /** Chunk overlap in tokens (default: 64). */
+    chunkOverlap?: number;
+}
+export interface SearchOptions {
+    /** Number of results (default: 5, max: 50). */
+    limit?: number;
+    /** Minimum similarity score filter (0-1). */
+    minScore?: number;
+    /** Optional metadata filter. */
+    filter?: Record<string, unknown>;
+}
+export interface KBOptions {
+    /** Embedding function. Defaults to DashScope text-embedding-v4. */
+    embed?: (text: string) => Promise<number[]>;
+    /** Embedding dimensions (default: 1536 for text-embedding-v4). */
+    dimensions?: number;
+    /** Default chunk size in tokens (default: 512). */
+    chunkSize?: number;
+    /** Chunk overlap in tokens (default: 64). */
+    chunkOverlap?: number;
+    /** User table name for reference (default: 'users'). */
+    usersTable?: string;
+}
+export interface KBAPI {
+    /** Import text: split into chunks, embed, and store. Returns document + chunks. */
+    importText(title: string, text: string, opts?: ImportOptions): Promise<{
+        document: Document;
+        chunks: Chunk[];
+    }>;
+    /** Import multiple documents at once. */
+    importDocuments(docs: Array<{
+        title: string;
+        content: string;
+    } & ImportOptions>): Promise<Document[]>;
+    /** RAG search: embed query → vector similarity search → return chunks. */
+    search(query: string, opts?: SearchOptions): Promise<SearchResult[]>;
+    /** List all documents. */
+    list(): Promise<Document[]>;
+    /** Get a document by id. */
+    get(id: string): Promise<Document | null>;
+    /** Get chunks for a document. */
+    getChunks(documentId: string): Promise<Chunk[]>;
+    /** Delete a document and its chunks. */
+    delete(id: string): Promise<boolean>;
+}

package/dist/messager/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Messager — instant messaging module for weifuwu.
+ *
+ * Requires `postgres()` and `user()` middleware registered first.
+ *
+ * @example
+ * ```ts
+ * import { serve, Router, postgres, user, messager } from 'weifuwu'
+ *
+ * const app = new Router()
+ * app.use(postgres())
+ * app.use(user())
+ * app.use(messager())
+ *
+ * // WebSocket — auto-join all conversations on connect
+ * app.ws('/ws', {
+ *   async open(ws, ctx) {
+ *     for (const c of await ctx.messager.getConversations()) {
+ *       ctx.ws.join(`conversation:${c.id}`)
+ *     }
+ *   },
+ * })
+ *
+ * // REST API
+ * app.post('/api/conversations', async (req, ctx) => {
+ *   const { type, title, userIds } = await req.json()
+ *   return type === 'direct'
+ *     ? Response.json(await ctx.messager.createDirectConversation(userIds[0]))
+ *     : Response.json(await ctx.messager.createGroupConversation(title, userIds))
+ * })
+ *
+ * app.get('/api/conversations', async (req, ctx) => {
+ *   return Response.json(await ctx.messager.getConversations())
+ * })
+ *
+ * app.post('/api/conversations/:id/messages', async (req, ctx) => {
+ *   const { body } = await req.json()
+ *   const msg = await ctx.messager.sendMessage(ctx.params.id, body)
+ *   return Response.json(msg, { status: 201 })
+ * })
+ *
+ * app.get('/api/conversations/:id/messages', async (req, ctx) => {
+ *   const url = new URL(req.url)
+ *   const opts = {
+ *     before: url.searchParams.get('before') || undefined,
+ *     limit: parseInt(url.searchParams.get('limit') || '50'),
+ *   }
+ *   return Response.json(await ctx.messager.getMessages(ctx.params.id, opts))
+ * })
+ *
+ * serve(app)
+ * ```
+ */
+export { Messager } from './module.ts';
+export type { MessagerAPI, MessagerOptions, Conversation, ConversationType, Participant, ParticipantUser, Message, MessagePreview, CreateGroupInput, GetMessagesOptions, } from './types.ts';
+import type { Context, Middleware } from '../types.ts';
+import type { MessagerAPI, MessagerOptions } from './types.ts';
+/**
+ * Messager factory — creates the Messager instance and returns
+ * a middleware that injects `ctx.messager`.
+ *
+ * Must be used **after** `postgres()` and `user()`.
+ *
+ * ```ts
+ * app.use(postgres())
+ * app.use(user())
+ * app.use(messager())
+ * ```
+ */
+export declare function messager(opts?: MessagerOptions): Middleware<Context, Context & {
+    messager: MessagerAPI;
+}>;

package/dist/messager/module.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Messager — instant messaging module for weifuwu.
+ *
+ * Depends on `postgres()` and `user()` middleware registered first.
+ *
+ * ```ts
+ * import { serve, Router, postgres, user, messager } from 'weifuwu'
+ *
+ * const app = new Router()
+ * app.use(postgres())
+ * app.use(user())
+ * app.use(messager())
+ *
+ * app.ws('/ws', {
+ *   async open(ws, ctx) {
+ *     for (const c of await ctx.messager.getConversations()) {
+ *       ctx.ws.join(`conversation:${c.id}`)
+ *     }
+ *   },
+ * })
+ *
+ * app.post('/api/messages', async (req, ctx) => {
+ *   const { conversationId, body } = await req.json()
+ *   const msg = await ctx.messager.sendMessage(conversationId, body)
+ *   return Response.json(msg, { status: 201 })
+ * })
+ * ```
+ */
+import type { Context, Handler, SqlClient } from '../types.ts';
+import type { MessagerAPI, MessagerOptions } from './types.ts';
+export declare class Messager {
+    private migrated;
+    private prefix;
+    private usersTable;
+    constructor(opts?: MessagerOptions);
+    private get tConversations();
+    private get tParticipants();
+    private get tMessages();
+    private get tUsers();
+    private q;
+    migrate(sql: SqlClient): Promise<void>;
+    private ensureMigrated;
+    bind(ctx: Context): MessagerAPI;
+    private _getConversationById;
+    middleware(req: Request, ctx: Context, next: Handler): Promise<Response>;
+}

package/dist/messager/types.d.ts

@@ -0,0 +1,99 @@
+declare module '../types.ts' {
+    interface Context {
+        /** Messager instance for conversations and messages. */
+        messager: import('./types.ts').MessagerAPI;
+    }
+}
+export type ConversationType = 'direct' | 'group';
+export interface Conversation {
+    id: string;
+    type: ConversationType;
+    title: string | null;
+    created_by: string;
+    created_at: Date;
+    updated_at: Date;
+    /** Number of participants (convenience field) */
+    participant_count?: number;
+    /** Last message preview (for list display) */
+    last_message?: MessagePreview | null;
+    /** Current user's unread count in this conversation */
+    unread_count?: number;
+}
+export interface Participant {
+    conversation_id: string;
+    user_id: string;
+    role: 'member' | 'admin';
+    last_read_at: Date | null;
+    joined_at: Date;
+    is_active: boolean;
+}
+/** A user in a conversation (includes user_name for display). */
+export interface ParticipantUser extends Participant {
+    user_name: string;
+    user_email: string;
+    user_avatar?: string;
+}
+export interface Message {
+    id: string;
+    conversation_id: string;
+    sender_id: string;
+    sender_name?: string;
+    body: string;
+    created_at: Date;
+    updated_at: Date;
+    edited: boolean;
+    deleted_at: Date | null;
+}
+/** Lightweight message used for conversation last_message preview. */
+export interface MessagePreview {
+    id: string;
+    body: string;
+    sender_id: string;
+    sender_name: string;
+    created_at: Date;
+}
+export interface CreateGroupInput {
+    title: string;
+    userIds: string[];
+}
+export interface GetMessagesOptions {
+    /** Return messages created before this ID (cursor pagination). */
+    before?: string;
+    /** Number of messages (default: 50, max: 200). */
+    limit?: number;
+}
+export interface MessagerOptions {
+    /** PostgreSQL table prefix for messager tables (default: '' — 'conversations', 'participants', 'messages'). */
+    tablePrefix?: string;
+    /** User table name for sender name lookups (default: 'users'). */
+    usersTable?: string;
+}
+export interface MessagerAPI {
+    /** Find or create a direct conversation with another user. */
+    createDirectConversation(otherUserId: string): Promise<Conversation>;
+    /** Create a group conversation. */
+    createGroupConversation(title: string, userIds: string[]): Promise<Conversation>;
+    /** Get conversation by ID. Returns null if not found or caller is not a participant. */
+    getConversation(conversationId: string): Promise<Conversation | null>;
+    /** List current user's active conversations, most recent first. */
+    getConversations(): Promise<Conversation[]>;
+    /** Add participants to a group conversation. Only group admin can do this. */
+    addParticipants(conversationId: string, userIds: string[]): Promise<void>;
+    /** Remove yourself or (as admin) another participant from a group conversation. */
+    removeParticipant(conversationId: string, userId?: string): Promise<boolean>;
+    /** Send a message to a conversation. Returns the created message. */
+    sendMessage(conversationId: string, body: string): Promise<Message>;
+    /** Get messages in a conversation, newest first (cursor pagination). */
+    getMessages(conversationId: string, opts?: GetMessagesOptions): Promise<Message[]>;
+    /** Edit a message (only by the original sender, within 24h). */
+    editMessage(messageId: string, body: string): Promise<Message | null>;
+    /** Soft-delete a message (only by the original sender). */
+    deleteMessage(messageId: string): Promise<boolean>;
+    /** Mark all messages in a conversation as read. */
+    markRead(conversationId: string): Promise<void>;
+    /** Get unread message count across all conversations. */
+    getUnreadCount(): Promise<{
+        total: number;
+        byConversation: Record<string, number>;
+    }>;
+}

package/dist/types.d.ts

@@ -19,7 +19,7 @@ export interface WebSocket {
     removeEventListener(event: string, handler: (...args: unknown[]) => void): void;
 }
 export type { Redis, RedisOptions } from 'ioredis';
-/** User injected by auth() middleware. */
+/** User injected by user() or custom auth middleware. */
 export interface User {
     id: string;
     role?: string;
@@ -42,7 +42,7 @@ export interface Context {
     params: Record<string, string>;
     query: Record<string, string>;
     mountPath?: string;
-    /** Currently authenticated user (set by user/auth middleware). */
+    /** Currently authenticated user (set by user() or custom auth middleware). */
     user?: unknown;
     /** Server-side data loaded for the current page (React SSR). */
     loaderData?: Record<string, unknown>;

package/dist/user/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * User module — complete authentication & user management system.
+ *
+ * Requires `postgres()` middleware registered first (provides `ctx.sql`).
+ *
+ * @example
+ * ```ts
+ * import { serve, Router, postgres, user, requireRole } from 'weifuwu'
+ *
+ * const app = new Router()
+ * app.use(postgres())
+ * app.use(user({ secret: process.env.JWT_SECRET }))
+ *
+ * // Public routes
+ * app.post('/api/register', async (req, ctx) => {
+ *   const result = await ctx.userModule.register(await req.json())
+ *   return Response.json(result)
+ * })
+ *
+ * app.post('/api/login', async (req, ctx) => {
+ *   const { email, password } = await req.json()
+ *   const result = await ctx.userModule.login(email, password)
+ *   if (!result) return new Response('Unauthorized', { status: 401 })
+ *   return Response.json(result)
+ * })
+ *
+ * // Protected — any authenticated user
+ * app.get('/api/me', async (req, ctx) => {
+ *   if (!ctx.user) return new Response('Unauthorized', { status: 401 })
+ *   return Response.json(ctx.user)
+ * })
+ *
+ * // Protected — admin only
+ * app.get('/api/admin/users', requireRole('admin'), async (req, ctx) => {
+ *   const users = await ctx.userModule.listUsers()
+ *   return Response.json(users)
+ * })
+ *
+ * serve(app)
+ * ```
+ */
+export { UserModule } from './module.ts';
+export { requireRole } from './types.ts';
+export type { UserModuleAPI, UserModuleOptions, UserRecord, CreateUserInput, UpdateUserInput, TokenPayload, } from './types.ts';
+import type { Context, Middleware } from '../types.ts';
+import type { UserModuleAPI, UserModuleOptions } from './types.ts';
+/**
+ * User system factory — creates the UserModule instance and returns
+ * a middleware that injects `ctx.userModule` (per-request bound API)
+ * and resolves `ctx.user` from JWT tokens.
+ *
+ * Must be used **after** `postgres()` so that `ctx.sql` is available.
+ *
+ * ```ts
+ * app.use(postgres())
+ * app.use(user({ secret: process.env.JWT_SECRET }))
+ * ```
+ */
+export declare function user(opts?: UserModuleOptions): Middleware<Context, Context & {
+    userModule: UserModuleAPI;
+}>;

package/dist/user/module.d.ts

@@ -0,0 +1,64 @@
+/**
+ * User module — authentication, registration, and user CRUD.
+ *
+ * Depends on `postgres()` middleware registered first (provides `ctx.sql`).
+ *
+ * ```ts
+ * import { serve, Router, postgres, user } from 'weifuwu'
+ *
+ * const app = new Router()
+ * app.use(postgres())
+ * app.use(user({ secret: process.env.JWT_SECRET }))
+ *
+ * app.post('/api/register', async (req, ctx) => {
+ *   const result = await ctx.userModule.register(await req.json())
+ *   return Response.json(result)
+ * })
+ *
+ * app.post('/api/login', async (req, ctx) => {
+ *   const { email, password } = await req.json()
+ *   const result = await ctx.userModule.login(email, password)
+ *   if (!result) return new Response('Unauthorized', { status: 401 })
+ *   return Response.json(result)
+ * })
+ *
+ * app.get('/api/me', async (req, ctx) => {
+ *   if (!ctx.user) return new Response('Unauthorized', { status: 401 })
+ *   return Response.json(ctx.user)
+ * })
+ * ```
+ */
+import type { Context, Handler, SqlClient } from '../types.ts';
+import type { UserModuleAPI, UserModuleOptions } from './types.ts';
+export declare class UserModule {
+    readonly table: string;
+    readonly secret: string;
+    readonly tokenExpiry: number;
+    private migrated;
+    constructor(opts?: UserModuleOptions);
+    migrate(sql: SqlClient): Promise<void>;
+    /**
+     * Create a per-request `UserModuleAPI` bound to the request's SQL context.
+     * Called internally by the middleware. Thread-safe because each request
+     * gets its own closure with a captured `ctx`.
+     */
+    bind(ctx: Context): UserModuleAPI;
+    private ensureMigrated;
+    private _register;
+    private _createUser;
+    private _getUserById;
+    private _getUserByEmail;
+    private _updateUser;
+    private _deleteUser;
+    private _listUsers;
+    private _login;
+    private _changePassword;
+    private _generateToken;
+    private _verifyToken;
+    private _refreshToken;
+    /**
+     * Middleware entry point. Injects `ctx.userModule` (per-request bound API)
+     * and resolves `ctx.user` from the Authorization header or `token` cookie.
+     */
+    middleware(req: Request, ctx: Context, next: Handler): Promise<Response>;
+}

package/dist/user/types.d.ts

@@ -0,0 +1,98 @@
+import type { Middleware } from '../types.ts';
+declare module '../types.ts' {
+    interface Context {
+        /** User module instance for downstream CRUD and auth operations. */
+        userModule: import('./types.ts').UserModuleAPI;
+    }
+}
+/** User record stored in the database. Password field is never exposed. */
+export interface UserRecord {
+    id: string;
+    email: string;
+    name: string;
+    role: string;
+    avatar?: string;
+    is_active: boolean;
+    created_at: Date;
+    updated_at: Date;
+    last_login_at?: Date;
+}
+export interface CreateUserInput {
+    email: string;
+    name: string;
+    password: string;
+    role?: string;
+    avatar?: string;
+    is_active?: boolean;
+}
+export interface UpdateUserInput {
+    name?: string;
+    email?: string;
+    password?: string;
+    role?: string;
+    avatar?: string;
+    is_active?: boolean;
+}
+/** JWT-like HMAC token payload. */
+export interface TokenPayload {
+    sub: string;
+    email: string;
+    role: string;
+    iat: number;
+    exp: number;
+}
+export interface UserModuleOptions {
+    /** HMAC secret for signing tokens (default: process.env.JWT_SECRET). */
+    secret?: string;
+    /** Token expiry in ms (default: 7 days). */
+    tokenExpiry?: number;
+    /** PostgreSQL table name (default: 'users'). */
+    table?: string;
+}
+/**
+ * Per-request user module API injected via `ctx.userModule`.
+ * Each method is already bound to the request's SQL context,
+ * so callers never need to pass `ctx`.
+ */
+export interface UserModuleAPI {
+    /** Register a new user. Returns user + signed token. */
+    register(input: CreateUserInput): Promise<{
+        user: UserRecord;
+        token: string;
+    }>;
+    /** Create a user directly (no token). Throws if email exists. */
+    createUser(input: CreateUserInput): Promise<UserRecord>;
+    /** Authenticate with email + password. Returns user + token or null. */
+    login(email: string, password: string): Promise<{
+        user: UserRecord;
+        token: string;
+    } | null>;
+    /** Lookup user by primary key. */
+    getUserById(id: string): Promise<UserRecord | null>;
+    /** Lookup user by email. */
+    getUserByEmail(email: string): Promise<UserRecord | null>;
+    /** Update user fields. Returns updated record or null if not found. */
+    updateUser(id: string, input: Partial<UpdateUserInput>): Promise<UserRecord | null>;
+    /** Soft-delete (deactivate) a user. Returns false if not found. */
+    deleteUser(id: string): Promise<boolean>;
+    /** List users. Defaults to active only; pass true to include deactivated. */
+    listUsers(includeInactive?: boolean): Promise<UserRecord[]>;
+    /** Change password — verifies currentPassword before updating. */
+    changePassword(id: string, currentPassword: string, newPassword: string): Promise<boolean>;
+    /** Verify a plaintext password against a stored scrypt hash. */
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    /** Generate a signed HMAC token for a user. */
+    generateToken(user: UserRecord): Promise<string>;
+    /** Verify and decode a token. Returns payload or null if expired/invalid. */
+    verifyToken(token: string): Promise<TokenPayload | null>;
+    /** Re-issue a token with a fresh expiry. Returns null if token is invalid. */
+    refreshToken(token: string): Promise<string | null>;
+}
+/**
+ * Middleware factory: returns a middleware that checks `ctx.user.role`.
+ *
+ * ```ts
+ * app.get('/admin', requireRole('admin'), handler)
+ * ```
+ */
+export declare function requireRole(...roles: string[]): Middleware;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Web-standard HTTP microframework for Node.js — (req, ctx) => Response",
   "exports": {
     ".": {