weifuwu 0.5.1 → 0.7.0

package/README.md

@@ -19,7 +19,12 @@ Everything follows the same `(req, ctx) => Response` contract. The Router handle
 - **GraphQL** — `graphql(handler)` sub-Router with GraphiQL IDE
 - **AI streaming** — `ai(handler)` sub-Router via Vercel AI SDK
 - **AI workflows** — `workflow(handler)` sub-Router — intent-to-execution pipelines with `tool()` + SSE
-- **PostgreSQL** — `postgres()` — zod-to-DDL, auto-migration, 6 CRUD methods, `ctx.sql` escape hatch
+- **AI Agent** — `agent()` — server-side AI agents with chat/workflow/knowledge types, OpenAI-compatible, Ollama-ready
+- **Messaging** — `messager()` — real-time chat with channels, WebSocket, agent routing, webhook support
+- **Tenant BaaS** — `tenant()` — multi-tenant dynamic tables, auto REST + GraphQL, row-level isolation, pgvector/HNSW
+- **Redis** — `redis()` — ioredis client, `ctx.redis`, middleware
+- **Queue** — `queue()` — Redis-backed job queue with immediate, delayed, and cron scheduling
+- **Auth** — `user()` — register/login/JWT + OAuth2 Server (authorization code + PKCE + client_credentials)
 - **Static files** — `serveStatic()` with ETag, 304, MIME, directory index
 - **Cookie** — `getCookies()`, `setCookie()`, `deleteCookie()` — immutable
 - **Error handling** — global `onError()`
@@ -258,14 +263,366 @@ await pg.close()                             // explicit close
 | `id: z.string().uuid().optional()` | `UUID PRIMARY KEY DEFAULT gen_random_uuid()` |
 | `id: z.string()` | `TEXT PRIMARY KEY` (you pass the value) |
 
-## WebSocket
+## Authentication
+
+Built-in user management — password login, JWT, and OAuth2 Server. Zero config beyond PostgreSQL and a secret key.
 
 ```ts
+import { serve, Router, postgres, user } from 'weifuwu'
+
 const app = new Router()
-  .ws('/chat/:room', {
-    open(ws, ctx) {
-      ws.send(`Connected to room: ${ctx.params.room}`)
-    },
+const pg = postgres()
+await pg.migrate()
+
+const auth = user({ pg, jwtSecret: process.env.JWT_SECRET! })
+
+// POST /auth/register  { email, password, name }
+// POST /auth/login     { email, password }
+// GET  /auth/oauth/authorize?client_id=...&redirect_uri=...&response_type=code
+// POST /auth/oauth/consent
+// POST /auth/oauth/token  (grant_type=authorization_code|client_credentials)
+app.use('/auth', auth.router())
+
+// Protected routes — verifies JWT, sets ctx.user
+app.get('/me', auth.middleware(), async (req, ctx) => {
+  return Response.json(ctx.user)
+  // { id, email, name, role }
+})
+```
+
+Password hashing uses `crypto.scryptSync` + `timingSafeEqual` (Node.js built-in, zero deps). JWT tokens use the `jsonwebtoken` package. The users table (`_users` by default) is auto-created on first `migrate()`.
+
+### OAuth2 Server
+
+Enable OAuth2 Server to let third-party apps (SPA, mobile, microservices) authenticate users through your app.
+
+```ts
+const auth = user({
+  pg,
+  jwtSecret: process.env.JWT_SECRET!,
+  oauth2: { server: true },
+})
+
+await auth.migrate()  // creates _users + _oauth2_clients + _oauth2_codes + _oauth2_tokens
+
+// Register a client app (programmatic — CLI, admin UI, seed script)
+const client = await auth.registerClient({
+  name: 'My SPA',
+  redirectUris: ['https://myapp.com/callback'],
+})
+// → { clientId, clientSecret, name, redirectUris }
+
+// Use auth middleware to protect routes — OAuth2 JWT tokens work seamlessly
+app.get('/api/data', auth.middleware(), handler)
+```
+
+#### Supported Grant Types
+
+| Grant | Use Case | PKCE |
+|-------|----------|------|
+| `authorization_code` (with client_secret) | Server-side apps | Optional |
+| `authorization_code` (with `code_challenge`/`code_verifier`) | SPA / Mobile apps | Required |
+| `client_credentials` | Machine-to-machine | — |
+
+#### Flow (Authorization Code + PKCE)
+
+```
+1. 第三方 App 引导用户:
+    GET /oauth/authorize?client_id=xxx&redirect_uri=https://app.com/cb
+                       &response_type=code&code_challenge=S256&state=yyy
+
+2. 用户未登录 → 302 到 /login?redirect=... → 登录后自动回到授权页
+
+3. 用户确认授权 → POST /oauth/consent { approve: true, client_id, ... }
+   302 redirect_uri?code=xxx&state=yyy
+
+4. 第三方 App POST /oauth/token
+   { grant_type: authorization_code, code, client_id, client_secret,
+     redirect_uri, code_verifier }
+   → { access_token, token_type: "Bearer", expires_in, refresh_token }
+
+5. access_token 是标准 JWT，auth.middleware() 和 auth.verify() 直接可用
+```
+
+#### Client Management
+
+```ts
+const client  = await auth.registerClient({ name, redirectUris })
+const found   = await auth.getClient(client.clientId)
+await auth.revokeClient(client.clientId)
+```
+
+#### Using OAuth2 Tokens with the Built-in Auth Middleware
+
+OAuth2 Server 签发的 `access_token` 与密码登录的 JWT 使用同一 `jwtSecret`，payload 向下兼容（`sub`、`email`、`role`），所以 `auth()` 无需任何修改即可验证 OAuth2 签发的 token：
+
+```ts
+import { auth } from 'weifuwu'
+
+// 同一个 auth() 中间件同时支持密码登录 JWT 和 OAuth2 JWT
+app.get('/api', auth({ verify: (token) => auth.verify(token) }), handler)
+```
+
+For `client_credentials` tokens (machine-to-machine), `verify()` returns `null` since no user is associated.
+
+## Tenant BaaS
+
+Built-in multi-tenant backend-as-a-service — define tables at runtime via API, get RESTful CRUD + GraphQL automatically, with row-level tenant isolation.
+
+```ts
+import { serve, Router, postgres, user, tenant } from 'weifuwu'
+
+const pg = postgres()
+const u = user({ pg, jwtSecret: process.env.JWT_SECRET! })
+const t = tenant({ pg, usersTable: '_users' })
+
+await pg.migrate()
+await u.migrate()
+await t.migrate()           // creates _tenants, _tenant_members, _user_tables
+
+const app = new Router()
+app.use('/auth', u.router())
+app.use('/api', u.middleware())     // → ctx.user
+app.use('/api', t.middleware())     // → ctx.tenant
+app.use('/api', t.router())        // → management + data CRUD
+app.use('/graphql', t.graphql())   // → dynamic GraphQL
+```
+
+### System tables
+
+| Table | Purpose |
+|-------|---------|
+| `_tenants` | Tenant records (`id TEXT PK DEFAULT gen_random_uuid()`, `name`, `created_at`) |
+| `_tenant_members` | User-tenant membership (`tenant_id`, `user_id`, `role`) |
+| `_user_tables` | Dynamic table definitions (`tenant_id`, `slug`, `fields JSONB`) |
+
+### Dynamic table API
+
+Create a table at runtime:
+
+```json
+POST /api/tables
+{
+  "slug": "articles",
+  "fields": [
+    { "name": "title", "type": "string", "required": true },
+    { "name": "content", "type": "text" },
+    { "name": "status", "type": "enum", "options": ["draft", "published"], "default": "draft" },
+    { "name": "views", "type": "integer", "default": 0 },
+    { "name": "embedding", "type": "vector", "dimensions": 1536, "index": "hnsw" }
+  ]
+}
+```
+
+→ Creates a PostgreSQL table with `id SERIAL PK`, `tenant_id TEXT NOT NULL`, and the specified columns, plus indexes. The table name is internally scoped to the tenant.
+
+### Field types
+
+| type | PostgreSQL | Index support |
+|------|-----------|---------------|
+| `string` | `TEXT` | `true`, `unique` |
+| `integer` | `INTEGER` | `true`, `desc`, `unique` |
+| `float` | `DOUBLE PRECISION` | `true`, `desc` |
+| `boolean` | `BOOLEAN` | `true` |
+| `text` | `TEXT` | `true` |
+| `datetime` | `TIMESTAMPTZ` | `true`, `desc` |
+| `date` | `DATE` | `true`, `desc` |
+| `enum` | `TEXT` (with validation) | `true` |
+| `json` | `JSONB` | `gin` |
+| `vector` | `vector(n)` (pgvector) | `hnsw` (HNSW, vector_cosine_ops) |
+
+### Relationships
+
+Declare a foreign key via the `relation` field:
+
+```json
+{ "name": "article_id", "type": "integer", "relation": { "table": "articles", "onDelete": "cascade" } }
+```
+
+Supported relationship patterns:
+
+| Pattern | Detection | REST | GraphQL |
+|---------|-----------|------|---------|
+| **belongs_to** | Field with `relation` | — | `comment.article` resolver |
+| **has_many** | Another table has a relation pointing here | `GET /api/articles/:id/comments` | `article.comments` resolver |
+| **M2M** | Junction table with exactly two relation fields | `GET /api/articles/:id/tags` (bypasses junction) | `article.tags` / `tag.articles` resolver |
+| **Self-ref** | Relation field pointing to same table | — | With depth control |
+
+### RESTful API
+
+All routes require `ctx.tenant` (set by `t.middleware()`). All queries automatically filter by `tenant_id`.
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/sys/tenants` | POST | Create tenant, caller becomes admin |
+| `/sys/tenants` | GET | List user's tenants |
+| `/sys/tenants/invite` | POST | Invite user by email (admin) |
+| `/sys/tenants/members/:userId` | DELETE | Remove member (admin) |
+| `/sys/tables` | POST/GET | Create / list dynamic tables |
+| `/sys/tables/:slug` | GET/PATCH/DELETE | Get schema / add fields / drop table |
+| `/:slug` | GET | List rows (limit, offset, sort) |
+| `/:slug` | POST | Create row |
+| `/:slug/:id` | GET/PATCH/DELETE | Get / update / delete row |
+| `/:slug/:id/:_nested` | GET | List related rows (has_many / M2M) |
+| `/:slug/:id/:_nested` | POST | Create related row (auto-fills relation field) |
+
+### Vector search
+
+```http
+GET /api/articles?search_vector=[0.1,0.2,...]&search_field=embedding&search_limit=10
+```
+
+Returns rows ordered by cosine distance (`<=>`), includes `_distance` field. Supports `l2` (`<->`) and `ip` (`<#>`):
+
+```http
+GET /api/articles?search_vector=[...]&search_field=embedding&search_distance=l2
+```
+
+### GraphQL
+
+Dynamic GraphQL schema generated per-request based on the authenticated tenant's tables:
+
+```graphql
+type Article {
+  id: ID!
+  title: String!
+  content: String
+  status: String
+  comments(limit: Int, offset: Int): [Comment!]!
+}
+
+type Query {
+  articles(limit: Int, offset: Int): [Article!]!
+  getArticle(id: ID!): Article
+}
+
+type Mutation {
+  createArticle(data: CreateArticleInput!): Article!
+  updateArticle(id: ID!, data: PatchArticleInput!): Article!
+  deleteArticle(id: ID!): Boolean!
+}
+```
+
+Built with `graphql-js` native constructors (`GraphQLObjectType`), no SDL generation, no `makeExecutableSchema`.
+
+### Middleware
+
+`t.middleware()` extracts the tenant context:
+
+1. Requires `ctx.user` (from `u.middleware()`)
+2. Looks up user's tenant memberships
+3. Single tenant → automatically set `ctx.tenant`
+4. Multiple tenants → require `X-Tenant-ID` header, return 300 with tenant list if missing
+5. No tenants → 403
+
+### Tenant lifecycle
+
+```ts
+const t = tenant({ pg, usersTable: '_users' })
+
+// Create a tenant — the caller becomes admin
+const tenant = await (await fetch('http://localhost/api/sys/tenants', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer <jwt>' },
+  body: JSON.stringify({ name: 'Acme Corp' }),
+})).json()
+// → { id: "uuid", name: "Acme Corp", created_at: "..." }
+
+// Invite a member
+await fetch('http://localhost/api/sys/tenants/invite', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer <jwt>' },
+  body: JSON.stringify({ email: 'colleague@acme.com', role: 'member' }),
+})
+```
+
+## AI Agent
+
+Server-side AI agents with OpenAI-compatible API. Built-in chat, workflow (tool-calling), and knowledge (RAG) types. Works out of the box with Ollama or any OpenAI-compatible provider.
+
+```ts
+import { agent } from 'weifuwu'
+
+const agents = agent({ pg })
+
+await agents.migrate()
+app.use('/api', agents.router())
+```
+
+| Type | Description | Execution |
+|------|-------------|-----------|
+| `chat` | Pure conversation | `streamText()` / `generateText()` |
+| `workflow` | Tool-calling agent | `streamText({ tools })` |
+
+### Knowledge (RAG)
+
+Add documents to any agent — `searchKnowledge` tool auto-injected:
+
+```ts
+await agents.addKnowledge(agentId, 'Title', 'Document content...')
+// The agent automatically calls searchKnowledge when answering
+```
+
+### Streaming
+
+```http
+POST /agents/:id/run  { input: "hello", stream: true }
+→ event-stream (fullStream SSE: text-delta, tool-call, tool-result, finish)
+```
+
+### Programmatic API
+
+```ts
+const result = await agents.run(agentId, { input: 'hello', stream: false })
+// { output: "Hello!", elapsed: 1234 }
+```
+
+## Messager
+
+Real-time chat with channels, WebSocket, and agent routing.
+
+```ts
+import { messager, agent } from 'weifuwu'
+
+const agents = agent({ pg })
+const msg = messager({ pg, agents })
+
+await msg.migrate()
+app.use('/api', msg.router())
+app.ws('/ws', u.middleware(), msg.wsHandler())
+```
+
+### Channels
+
+```http
+POST   /channels            name, type (channel|dm), members
+GET    /channels
+GET    /channels/:id
+```
+
+### Messages
+
+```http
+GET  /channels/:id/messages     ?limit=50&before={id}
+POST /channels/:id/messages     content, sender_type, type
+POST /channels/:id/read         last_message_id
+```
+
+### WebSocket
+
+```json
+{ "type": "message",  "channel_id": 1, "content": "Hi" }
+{ "type": "typing",   "channel_id": 1, "is_typing": true }
+{ "type": "read",     "channel_id": 1, "last_message_id": 42 }
+```
+
+### Programmatic send
+
+```ts
+await msg.send(channelId, 'System message', { sender_type: 'system' })
+```
+
+## WebSocket
     message(ws, ctx, data) {
       ws.send(`echo: ${data}`)
     },
@@ -654,6 +1011,48 @@ const app = new Router()
 
 Returns `{ stop, port, hostname, ready }`.
 
+### `user(options)`
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `pg` | — | PostgreSQL client from `postgres()` |
+| `jwtSecret` | — | Secret key for JWT signing |
+| `table` | `'_users'` | Users table name |
+| `expiresIn` | `'24h'` | JWT expiration |
+| `oauth2.server` | `false` | Enable OAuth2 Server |
+
+Returns `UserModule` — `{ router, middleware, migrate, register, login, verify, registerClient, getClient, revokeClient, close }`.
+
+### `tenant(options)`
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `pg` | — | PostgreSQL client from `postgres()` |
+| `usersTable` | — | Users table name (matching the `table` option passed to `user()`) |
+
+Returns `TenantModule` — `{ migrate, middleware, router, graphql, close }`.
+
+### `agent(options)`
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `pg` | — | PostgreSQL client from `postgres()` |
+| `model` | env `OPENAI_MODEL` → Ollama | `LanguageModel` from ai SDK |
+| `embeddingModel` | env `OPENAI_EMBEDDING_MODEL` → Ollama | `EmbeddingModel` for knowledge RAG |
+| `embeddingDimension` | `1024` | Vector dimension for pgvector |
+| `tools` | — | Tools for workflow-type agents (ai SDK `Tool` objects) |
+
+Returns `AgentModule` — `{ migrate, router, run, addKnowledge, close }`.
+
+### `messager(options)`
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `pg` | — | PostgreSQL client from `postgres()` |
+| `agents` | — | `AgentModule` instance (enables agent message routing) |
+
+Returns `MessagerModule` — `{ migrate, router, wsHandler, send, close }`.
+
 ### `tsx(options)`
 
 | Option | Default | Description |
@@ -690,6 +1089,12 @@ Returns `Promise<Router>`.
 | Import | Description |
 |--------|-------------|
 | `postgres(options?)` | PostgreSQL connection + auto-migration + 6 CRUD methods |
+| `redis(options?)` | Redis client (ioredis) — injects `ctx.redis` |
+| `queue(options?)` | Redis-backed job queue — immediate, delayed, cron scheduling |
+| `user(options)` | Built-in authentication (password + OAuth2 Server + JWT, middleware) |
+| `tenant(options)` | Multi-tenant BaaS — dynamic tables, REST + GraphQL auto-generation, row-level isolation |
+| `agent(options)` | AI Agent — chat/workflow/knowledge, Ollama-ready, programmatic API |
+| `messager(options)` | Real-time messaging — channels, WebSocket, agent routing, webhooks |
 | `graphql(handler)` | GraphQL endpoint (GET/POST + GraphiQL) |
 | `ai(handler)` | AI streaming endpoint (POST) |
 | `workflow(handler)` | Workflow engine (POST + SSE) |

package/dist/agent/client.d.ts

@@ -0,0 +1,2 @@
+import type { AgentOptions, AgentModule } from './types.ts';
+export declare function agent(options: AgentOptions): AgentModule;

package/dist/agent/index.d.ts

@@ -0,0 +1,2 @@
+export { agent } from './client.ts';
+export type { AgentOptions, AgentModule, AgentConfig, RunParams, RunResult } from './types.ts';

package/dist/agent/migrate.d.ts

@@ -0,0 +1,6 @@
+import type { Sql } from 'postgres';
+export interface MigrateOptions {
+    sql: Sql<{}>;
+    embeddingDimension: number;
+}
+export declare function migrate(opts: MigrateOptions): Promise<void>;

package/dist/agent/rest.d.ts

@@ -0,0 +1,12 @@
+import type { Sql } from 'postgres';
+import { Router } from '../router.ts';
+import type { RunParams } from './types.ts';
+interface RestDeps {
+    sql: Sql<{}>;
+    runner: {
+        run: (agentId: number, params: RunParams) => Promise<any>;
+        addKnowledge: (agentId: number, title: string, content: string) => Promise<any>;
+    };
+}
+export declare function buildRouter(deps: RestDeps): Router;
+export {};

package/dist/agent/run.d.ts

@@ -0,0 +1,14 @@
+import type { LanguageModel, EmbeddingModel, Tool } from 'ai';
+import type { Sql } from 'postgres';
+import type { RunParams, RunResult, KnowledgeDoc } from './types.ts';
+interface RunnerDeps {
+    sql: Sql<{}>;
+    getModel: () => LanguageModel;
+    getEmbeddingModel: () => EmbeddingModel;
+    userTools?: Record<string, Tool>;
+}
+export declare function createRunner(deps: RunnerDeps): {
+    run: (agentId: number, params: RunParams) => Promise<RunResult>;
+    addKnowledge: (agentId: number, title: string, content: string) => Promise<KnowledgeDoc>;
+};
+export {};

package/dist/agent/types.d.ts

@@ -0,0 +1,51 @@
+import type { LanguageModel, EmbeddingModel, Tool } from 'ai';
+export interface AgentConfig {
+    id: number;
+    tenant_id: string | null;
+    name: string;
+    description: string;
+    type: 'chat' | 'workflow';
+    model: string;
+    system_prompt: string;
+    owner_id: number;
+    active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+export interface KnowledgeDoc {
+    id: number;
+    agent_id: number;
+    title: string;
+    content: string;
+    embedding?: number[];
+    metadata: Record<string, unknown>;
+    created_at: string;
+}
+export interface RunParams {
+    input: string;
+    stream?: boolean;
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
+}
+export type RunResult = {
+    output: string;
+    elapsed: number;
+} | {
+    stream: ReadableStream<Uint8Array>;
+};
+export interface AgentOptions {
+    pg: any;
+    model?: LanguageModel;
+    embeddingModel?: EmbeddingModel;
+    embeddingDimension?: number;
+    tools?: Record<string, Tool>;
+}
+export interface AgentModule {
+    migrate: () => Promise<void>;
+    router: () => any;
+    run: (agentId: number, params: RunParams) => Promise<RunResult>;
+    addKnowledge: (agentId: number, title: string, content: string) => Promise<KnowledgeDoc>;
+    close: () => Promise<void>;
+}

package/dist/index.d.ts

@@ -27,3 +27,15 @@ export { tool, createWorkflowEngine, createSSEManager, generateWorkflow, workflo
 export type { Tool, Workflow, WorkflowEngine, WorkflowState, SSEEvent, WorkflowOptions, WorkflowHandler } from './workflow/index.ts';
 export { postgres } from './postgres/index.ts';
 export type { PostgresOptions, PostgresClient, TableProxy, ListOptions, TableBuilder } from './postgres/types.ts';
+export { user } from './user/index.ts';
+export type { UserOptions, UserData, UserModule, OAuth2Client } from './user/types.ts';
+export { redis } from './redis/index.ts';
+export type { RedisOptions, RedisClient } from './redis/types.ts';
+export { queue } from './queue/index.ts';
+export type { QueueOptions, QueueJob, Queue } from './queue/types.ts';
+export { tenant } from './tenant/index.ts';
+export type { TenantOptions, TenantModule, TenantContext, FieldDef, FieldType, RelationDef, UserTableRow } from './tenant/types.ts';
+export { agent } from './agent/index.ts';
+export type { AgentOptions, AgentModule, AgentConfig, RunParams, RunResult, KnowledgeDoc } from './agent/types.ts';
+export { messager } from './messager/index.ts';
+export type { MessagerOptions, MessagerModule, Channel, ChannelMember, Message } from './messager/types.ts';