@weifuwujs/messages 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,260 @@
-# Temporary Holding Version
+# 站内信（`@weifuwujs/messages`）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+用户通知的最小完整形态：**服务端发送（幂等）** + **REST 收件箱** + **WebSocket 实时推送** +
+**断线 `since` 补投**，memory / sqlite / postgres 三驱动共用同一套契约测试。适合站内信、系统通知、
+"任务完成"提醒这类"写入一次、本人可查、要实时"的场景。
+
+不适合的：IM 聊天（双向会话、打字状态、已读回执）、服务间消息总线（用 [`@weifuwujs/tasks`](./packages/tasks/README.md) 或
+MQ）、给非登录用户群发（消息挂在用户上，先有账号）。
+
+## 十分钟接入
+
+最快的路径是脚手架 + 包内叠加模板：
+
+```bash
+npx @weifuwujs/weifuwu init my-app
+cd my-app
+cp -r "$(npm root)/@weifuwujs/auth/templates/react-router-auth/." .
+cp -r "$(npm root)/@weifuwujs/messages/templates/react-router-messages/." .
+npx @weifuwujs/auth migrate
+npx @weifuwujs/messages migrate   # 欢迎信 + 徽标 + /notifications 页 + WS 实时
+npm run dev
+```
+
+手工接入只有四步（**选驱动 → `createMessages` → `install(app)` → `send`**）：
+
+```ts messages
+import { createApp } from '@weifuwujs/weifuwu'
+import { createMessages } from '@weifuwujs/messages'
+import { sqliteMessageStore } from '@weifuwujs/messages/sqlite'
+
+const messages = createMessages({
+  store: sqliteMessageStore('data/messages.db'), // 构造即迁移（幂等）
+})
+
+const app = createApp()
+messages.install(app) // REST + WebSocket 一条线（都要求登录，未认证 401），并随 app.close() 收连接
+
+await messages.send({
+  userId: 'user-1',
+  kind: 'welcome',
+  title: '欢迎使用',
+  body: '从这条消息开始。',
+  idempotencyKey: 'welcome:user-1', // 重复发送只入库一次，不覆盖
+})
+```
+
+`send` 是**服务端 API，不暴露 HTTP**（通知面不能被客户端伪造）；消息落库后在线的本人立刻收到 WS 推送。
+
+配合 auth 的注册欢迎信 recipe：
+
+```ts messages-auth
+import { createApp } from '@weifuwujs/weifuwu'
+import { createAuth } from '@weifuwujs/auth'
+import { sqliteAuthStore } from '@weifuwujs/auth/sqlite'
+import { createMessages } from '@weifuwujs/messages'
+import { sqliteMessageStore } from '@weifuwujs/messages/sqlite'
+
+const app = createApp()
+const messages = createMessages({ store: sqliteMessageStore('data/messages.db') })
+const auth = createAuth({
+  store: sqliteAuthStore('data/auth.db'),
+  hooks: {
+    onRegister: (user) => {
+      void messages.send({
+        userId: user.id,
+        kind: 'welcome',
+        title: '欢迎使用',
+        idempotencyKey: `welcome:${user.id}`, // 重投/重试只入一条
+      })
+    },
+  },
+})
+
+auth.install(app) // HTTP + WS 统一鉴权（ctx.auth.user）
+app.mount(auth)
+messages.install(app) // 必须叠在 auth 之后：REST/WS 都看 ctx.auth.user
+```
+
+## 后台任务完成通知（tasks recipe）
+
+长任务在 [`./tasks`](./tasks.md) 里跑完，用消息把结果送到用户手里；`idempotencyKey` 按业务主键命名，
+任务重试（至少一次执行）也不会重复打扰用户：
+
+```ts messages-tasks
+import { createApp } from '@weifuwujs/weifuwu'
+import { createMessages, memoryMessageStore } from '@weifuwujs/messages'
+import { createTasks, memoryTaskStore } from '@weifuwujs/tasks'
+
+const messages = createMessages({ store: memoryMessageStore() })
+const tasks = createTasks({ store: memoryTaskStore() })
+
+tasks.handle(
+  'generate-report',
+  async (payload: { userId: string; reportId: string }) => {
+    await messages.send({
+      userId: payload.userId,
+      kind: 'report',
+      title: '报表已生成',
+      idempotencyKey: `report-done:${payload.reportId}`, // 任务重试不重复通知
+    })
+  },
+)
+
+const app = createApp()
+messages.install(app)
+tasks.install(app) // worker 随 app.close() 优雅停止
+
+await tasks.enqueue(
+  'generate-report',
+  { userId: 'user-1', reportId: 'r1' },
+  { idempotencyKey: 'report:r1' },
+)
+```
+
+## API 速览
+
+`createMessages(options)`
+
+| 选项 | 默认 | 说明 |
+| --- | --- | --- |
+| `store` | 必填 | 三驱动之一或你自己的 `MessageStore` |
+| `bus` | 进程内 | `localMessageBus()`；多副本换 `redisMessageBus()`（见下） |
+| `onSend` | — | 新消息落库后回调；抛错只告警（已持久化），幂等命中不触发 |
+| `routePrefix` | `/messages` | REST 前缀 |
+| `pageSize` | `20`（上限 100） | 列表默认页大小 |
+| `syncLimit` | `100` | 断线补投单次最大条数（`hasMore` 后续页） |
+| `now` / `logger` | — | 可注入时钟、日志器 |
+
+`messages` 实例：`send` / `list` / `unread` / `markRead` / `markAllRead` / `routes` / `install` /
+`connections` / `publish` / `ready` / `close` / `migrate`。
+
+`send(input)` → `{ message, created }`：`input = { userId, title, kind?, body?, data?, idempotencyKey? }`；
+`created: false` 表示幂等键命中（返回已有消息，**不覆盖**）。推荐键名 `<动作>:<业务主键>`。
+
+REST（`messages.install(app)` / `app.mount(messages)` 后；一律 401 守卫 + 仅本人）：
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/messages` | 本人消息（`unread`/`kind`/`limit`/`cursor` 查询）→ `{ items, nextCursor, unread }`（按 `(createdAt,id)` 降序） |
+| GET | `/messages/unread` | `{ unread }`（徽标轮询兜底） |
+| POST | `/messages/read` | `{ ids }` → `{ updated }`（幂等） |
+| POST | `/messages/read-all` | → `{ updated }` |
+
+## WebSocket 协议
+
+连接 `GET /messages/ws`（未认证 401）；`?since=<cursor>` 控制补投：
+
+- 连接建立后**先**收到 `{ type: 'unread', unread }` 快照，再收实时事件；
+- `since` 非空且合法 → 先推 `{ type: 'sync', items, hasMore, unread }`（**升序**，subscribe-first：
+  宁可重投不可丢失）；`hasMore` 时用最后一条的游标再连一次续补；
+- `since` 为空/省略 → 视为全量 `sync`；非法游标 → `1008` 关闭；
+- 之后：`send` → `{ type: 'message', message }` + `{ type: 'unread', unread }`；
+  `markRead`/`markAllRead` → `{ type: 'unread', unread }`。
+
+投递语义是**至少一次**：断线重连可能重投，客户端**按 message.id 去重**即恰好一次。`unread` 是快照值，
+不是增量。
+
+## 断线不丢不重（客户端重连配方）
+
+客户端记住"最新已见消息"的游标（列表升序取 `items[0]`，或 `sync` 的最后一条），重连时带上：
+
+```ts
+import { encodeCursor } from '@weifuwujs/messages'
+
+// 收到列表/同步结果后：
+const latest = page.items[0] // 降序列表的第一条 = 最新
+const since = latest
+  ? encodeCursor({ id: latest.id, createdAt: new Date(latest.createdAt) })
+  : ''
+
+// 重连：ws://…/messages/ws?since=<since>，把 sync.items + 实时 message 合并进同一个 Map
+const byId = new Map<string, { id: string }>()
+for (const item of [...sync.items, ...live]) byId.set(item.id, item)
+```
+
+重复应用同一批事件时 `byId` 不变——这就是"不重复"的全部代价。
+
+## 三驱动与运维
+
+| 驱动 | 入口 | 建表 | 说明 |
+| --- | --- | --- | --- |
+| memory | `@weifuwujs/messages` 的 `memoryMessageStore()` | — | 测试/单进程 demo |
+| sqlite | `@weifuwujs/messages/sqlite` | 构造即迁移 | 默认 `weifuwu-messages migrate` 目标（`sqlite:data/messages.db`） |
+| postgres | `@weifuwujs/messages/postgres` | 构造即迁移 + advisory lock | 多副本必须：`UNIQUE(user_id, idempotency_key)` 让幂等原子 |
+
+```bash
+weifuwu-messages migrate                                    # sqlite:data/messages.db
+weifuwu-messages migrate --store postgres://user:pw@host/db # 多进程并发安全（pg advisory xact lock）
+```
+
+redis **不作为消息主存**（不保证持久，丢了就是丢了）；它的位置在下面的实时总线。
+
+## 多副本部署
+
+单进程默认 `localMessageBus()`（进程内 fan-out）。多副本时每个实例都连同一个主存，并把总线换成 Redis：
+
+```ts messages-multi
+import { createMessages } from '@weifuwujs/messages'
+import { postgresMessageStore } from '@weifuwujs/messages/postgres'
+import { redisMessageBus } from '@weifuwujs/messages/redis'
+
+const bus = redisMessageBus('redis://localhost:6379', { prefix: 'myapp:messages' })
+const messages = createMessages({
+  store: postgresMessageStore('postgres://user:pw@localhost:5432/app'),
+  bus,
+})
+
+await messages.ready() // 启动时等一次订阅就绪；之后 send 先发本节点再广播
+// … 服务运行：A 实例 send，持有 WS 的 B 实例也会推送
+await messages.close() // 只关自有连接与自有 bus；注入的 bus 生命周期归调用方
+await bus.close() // 所以注入时由你负责关闭
+```
+
+- 按用户**按需订阅** `prefix:<userId>`：本节点有该用户连接才订阅，最后一个连接断开后自动退订；
+- `redisMessageBus(url)` 自己创建/关闭连接；传已有 `ioredis` 客户端则只 `duplicate()` 订阅连接，**不关注入的客户端**；
+- 跨节点仍是至少一次：WS 下多节点可能对同一用户重复投递，客户端按 id 去重。
+
+## 自定义驱动
+
+实现 `MessageStore`（`insert`/`list`/`unreadCount`/`markRead`/`markAllRead`/`migrate?`）后，先用同一套
+契约验证再上线：
+
+```ts messages-custom
+import { memoryMessageStore } from '@weifuwujs/messages'
+import { messagesStoreContract } from '@weifuwujs/messages/testing'
+
+// 换成你的驱动：messagesStoreContract('my-store', () => myMessageStore())
+messagesStoreContract('my-store', () => memoryMessageStore())
+```
+
+契约覆盖：幂等键不覆盖、降序分页稳定（同毫秒按 id）、只影响本人、`markRead` 幂等、未读计数。
+
+## 测试辅助（`/testing`）
+
+自定义 `MessageStore` / `MessageBus` 驱动与内置驱动共跑同一套契约：
+
+```ts
+import {
+  messagesStoreContract,
+  messageBusContract,
+} from '@weifuwujs/messages/testing'
+
+messagesStoreContract('my-store', () => myMessageStore())
+messageBusContract('my-bus', () => myMessageBus())
+// 第三个参数可选：{ skip: true } 或 { skip: '未实现清理' }
+```
+
+工厂**会被套件多次调用**：每次须返回独立的 store（sqlite 驱动用 `':memory:'` 或唯一路径）——
+复用同一文件会状态泄漏并假红。
+
+契约覆盖：insert/get（IDOR 防线）、幂等键、游标分页不重不漏、unread 计数与已读隔离、
+listAfter 补投、watch/unwatch 订阅泄漏回归。
+
+## 安全与边界
+
+- 所有 store 查询强制 `userId`，越权读取/标记直接表现为"查无此件"；REST/WS 未认证 401；
+- `title`/`body` 按**纯文本**存储，渲染层负责转义；`data` 只透传、不参与查询；
+- `app.close()` 会断开全部 WS；`messages.close()` 幂等，注入 bus 时先关 `messages` 再关 bus；
+- 群发/广播是**多次 `send`**（没有 fan-out API），量级大时用 [`./tasks`](./tasks.md) 异步扇出；
+- 明确非目标：IM、跨服务消息总线、消息编辑/撤回、附件。

package/dist/bus.d.ts

@@ -0,0 +1,7 @@
+import type { MessageBus } from './types.ts';
+/**
+ * 进程内总线：单副本默认。
+ * `watch`/`publish` 同步派发（事件不会跨进程，也不做异步缓冲）。
+ */
+export declare function localMessageBus(): MessageBus;
+//# sourceMappingURL=bus.d.ts.map

package/dist/bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.d.ts","sourceRoot":"","sources":["../src/bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,YAAY,CAAA;AAE3D;;;GAGG;AACH,wBAAgB,eAAe,IAAI,UAAU,CAuB5C"}

package/dist/bus.js

@@ -0,0 +1,30 @@
+/**
+ * 进程内总线：单副本默认。
+ * `watch`/`publish` 同步派发（事件不会跨进程，也不做异步缓冲）。
+ */
+export function localMessageBus() {
+    const handlers = new Map();
+    return {
+        publish(userId, event) {
+            const set = handlers.get(userId);
+            if (!set)
+                return;
+            for (const handler of [...set])
+                handler(event);
+        },
+        watch(userId, handler) {
+            let set = handlers.get(userId);
+            if (!set) {
+                set = new Set();
+                handlers.set(userId, set);
+            }
+            set.add(handler);
+            return () => {
+                set.delete(handler);
+                if (set.size === 0)
+                    handlers.delete(userId);
+            };
+        },
+    };
+}
+//# sourceMappingURL=bus.js.map

package/dist/bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.js","sourceRoot":"","sources":["../src/bus.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA+C,CAAA;IAEvE,OAAO;QACL,OAAO,CAAC,MAAM,EAAE,KAAK;YACnB,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YAChC,IAAI,CAAC,GAAG;gBAAE,OAAM;YAChB,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,GAAG,CAAC;gBAAE,OAAO,CAAC,KAAK,CAAC,CAAA;QAChD,CAAC;QAED,KAAK,CAAC,MAAM,EAAE,OAAO;YACnB,IAAI,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YAC9B,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAA;gBACf,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;YAC3B,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;YAChB,OAAO,GAAG,EAAE;gBACV,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;gBACnB,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;oBAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YAC7C,CAAC,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+function parseArgs(argv) {
+    const command = argv[0] ?? 'help';
+    let root = process.cwd();
+    let store;
+    const rest = [];
+    for (let index = 1; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === '--root' || arg.startsWith('--root=')) {
+            const value = arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : argv[++index];
+            if (!value)
+                throw new Error('--root 需要提供一个值');
+            root = resolve(value);
+        }
+        else if (arg === '--store' || arg.startsWith('--store=')) {
+            const value = arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : argv[++index];
+            if (!value)
+                throw new Error('--store 需要提供一个值');
+            store = value;
+        }
+        else {
+            rest.push(arg);
+        }
+    }
+    return { command, root, store, rest };
+}
+/** `migrate [--store sqlite:<path>]`（CLI 不加载用户代码） */
+async function openMessageStore(options) {
+    const spec = options.store ?? 'sqlite:data/messages.db';
+    if (spec.startsWith('sqlite:')) {
+        const path = resolve(options.root, spec.slice('sqlite:'.length));
+        const { sqliteMessageStore } = await import("./stores/sqlite.js");
+        const store = sqliteMessageStore(path);
+        return { store, close: async () => store.close() };
+    }
+    if (spec.startsWith('postgres://') || spec.startsWith('postgresql://')) {
+        const { postgresMessageStore } = await import("./stores/postgres.js");
+        const store = postgresMessageStore(spec);
+        return { store, close: () => store.close() };
+    }
+    throw new Error(`无法识别的 --store：${spec}（支持 sqlite:<path> 与 postgres://…）`);
+}
+async function messagesMigrate(options) {
+    const spec = options.store ?? 'sqlite:data/messages.db';
+    const { store, close } = await openMessageStore(options);
+    try {
+        await store.migrate?.();
+        console.log(spec.startsWith('sqlite:')
+            ? `messages 迁移完成：${resolve(options.root, spec.slice('sqlite:'.length))}`
+            : `messages 迁移完成：${spec}`);
+    }
+    finally {
+        await close();
+    }
+}
+function printHelp() {
+    console.log(`用法：weifuwu-messages <命令> [选项]
+
+命令：
+  migrate   迁移 messages 数据表（sqlite/postgres）
+
+选项：
+  --root <dir>   项目根目录，默认当前目录
+  --store <url>  数据源，默认 sqlite:data/messages.db（支持 sqlite:<path> 与 postgres://…）
+`);
+}
+const options = parseArgs(process.argv.slice(2));
+try {
+    if (options.command === 'migrate')
+        await messagesMigrate(options);
+    else if (options.command === 'help')
+        printHelp();
+    else {
+        throw new Error(`未知 messages 子命令：${options.command}（可用：migrate）`);
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/cursor.d.ts

@@ -0,0 +1,20 @@
+import type { Message } from './types.ts';
+/**
+ * 分页游标：`<createdAtMs(36)>.<id>`。
+ * 自带时间戳，翻页不依赖游标消息仍然存在（被清理/删除也不影响）。
+ */
+export declare function encodeCursor(message: Pick<Message, 'id' | 'createdAt'>): string;
+export interface DecodedCursor {
+    createdAtMs: number;
+    id: string;
+}
+export declare function decodeCursor(cursor: string): DecodedCursor | null;
+/** `(createdAt, id)` 双键降序比较（同毫秒稳定） */
+export declare function compareDesc(a: Pick<Message, 'id' | 'createdAt'>, b: Pick<Message, 'id' | 'createdAt'>): number;
+/** 消息是否严格排在游标之后（更早一页） */
+export declare function isAfterCursor(message: Pick<Message, 'id' | 'createdAt'>, cursor: DecodedCursor): boolean;
+/** `(createdAt, id)` 双键升序比较（断线补投按旧→新） */
+export declare function compareAsc(a: Pick<Message, 'id' | 'createdAt'>, b: Pick<Message, 'id' | 'createdAt'>): number;
+/** 消息是否严格排在游标之后（更晚一条，补投用） */
+export declare function isBeyondCursor(message: Pick<Message, 'id' | 'createdAt'>, cursor: DecodedCursor): boolean;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAEzC;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,WAAW,CAAC,GAAG,MAAM,CAE/E;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAA;IACnB,EAAE,EAAE,MAAM,CAAA;CACX;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAMjE;AAED,sCAAsC;AACtC,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,WAAW,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,WAAW,CAAC,GAAG,MAAM,CAK9G;AAED,yBAAyB;AACzB,wBAAgB,aAAa,CAC3B,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,WAAW,CAAC,EAC1C,MAAM,EAAE,aAAa,GACpB,OAAO,CAIT;AAED,yCAAyC;AACzC,wBAAgB,UAAU,CACxB,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,WAAW,CAAC,EACpC,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,WAAW,CAAC,GACnC,MAAM,CAKR;AAED,6BAA6B;AAC7B,wBAAgB,cAAc,CAC5B,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,WAAW,CAAC,EAC1C,MAAM,EAAE,aAAa,GACpB,OAAO,CAIT"}

package/dist/cursor.js

@@ -0,0 +1,49 @@
+/**
+ * 分页游标：`<createdAtMs(36)>.<id>`。
+ * 自带时间戳，翻页不依赖游标消息仍然存在（被清理/删除也不影响）。
+ */
+export function encodeCursor(message) {
+    return `${message.createdAt.getTime().toString(36)}.${message.id}`;
+}
+export function decodeCursor(cursor) {
+    const dot = cursor.indexOf('.');
+    if (dot <= 0 || dot === cursor.length - 1)
+        return null;
+    const createdAtMs = Number.parseInt(cursor.slice(0, dot), 36);
+    if (!Number.isFinite(createdAtMs))
+        return null;
+    return { createdAtMs, id: cursor.slice(dot + 1) };
+}
+/** `(createdAt, id)` 双键降序比较（同毫秒稳定） */
+export function compareDesc(a, b) {
+    const byTime = b.createdAt.getTime() - a.createdAt.getTime();
+    if (byTime !== 0)
+        return byTime;
+    if (a.id === b.id)
+        return 0;
+    return a.id < b.id ? 1 : -1;
+}
+/** 消息是否严格排在游标之后（更早一页） */
+export function isAfterCursor(message, cursor) {
+    const ms = message.createdAt.getTime();
+    if (ms !== cursor.createdAtMs)
+        return ms < cursor.createdAtMs;
+    return message.id < cursor.id;
+}
+/** `(createdAt, id)` 双键升序比较（断线补投按旧→新） */
+export function compareAsc(a, b) {
+    const byTime = a.createdAt.getTime() - b.createdAt.getTime();
+    if (byTime !== 0)
+        return byTime;
+    if (a.id === b.id)
+        return 0;
+    return a.id < b.id ? -1 : 1;
+}
+/** 消息是否严格排在游标之后（更晚一条，补投用） */
+export function isBeyondCursor(message, cursor) {
+    const ms = message.createdAt.getTime();
+    if (ms !== cursor.createdAtMs)
+        return ms > cursor.createdAtMs;
+    return message.id > cursor.id;
+}
+//# sourceMappingURL=cursor.js.map

package/dist/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAA0C;IACrE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,OAAO,CAAC,EAAE,EAAE,CAAA;AACpE,CAAC;AAOD,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC/B,IAAI,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACtD,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAA;IAC7D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAA;IAC9C,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAA;AACnD,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,WAAW,CAAC,CAAoC,EAAE,CAAoC;IACpG,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,CAAA;IAC5D,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAA;IAC/B,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE;QAAE,OAAO,CAAC,CAAA;IAC3B,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAC7B,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,aAAa,CAC3B,OAA0C,EAC1C,MAAqB;IAErB,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,CAAA;IACtC,IAAI,EAAE,KAAK,MAAM,CAAC,WAAW;QAAE,OAAO,EAAE,GAAG,MAAM,CAAC,WAAW,CAAA;IAC7D,OAAO,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE,CAAA;AAC/B,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,UAAU,CACxB,CAAoC,EACpC,CAAoC;IAEpC,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,CAAA;IAC5D,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAA;IAC/B,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE;QAAE,OAAO,CAAC,CAAA;IAC3B,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAC7B,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,cAAc,CAC5B,OAA0C,EAC1C,MAAqB;IAErB,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,CAAA;IACtC,IAAI,EAAE,KAAK,MAAM,CAAC,WAAW;QAAE,OAAO,EAAE,GAAG,MAAM,CAAC,WAAW,CAAA;IAC7D,OAAO,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE,CAAA;AAC/B,CAAC"}

package/dist/hub.d.ts

@@ -0,0 +1,15 @@
+import type { WebSocketConnection } from '@weifuwujs/weifuwu';
+import type { MessagesEvent } from './types.ts';
+/** 进程内实时投递（跨节点见阶段 3.3 MessageBus） */
+export interface MessageHub {
+    /** 登记连接，返回注销函数（`onClose` 里调用） */
+    add(userId: string, socket: WebSocketConnection): () => void;
+    /** 只发给该用户的在线连接；连接刚断开时静默跳过 */
+    publish(userId: string, event: MessagesEvent): void;
+    /** 在线连接数（省略 userId = 全部） */
+    connections(userId?: string): number;
+    /** 关闭全部连接（`app.close()` 用） */
+    closeAll(): void;
+}
+export declare function localMessageHub(): MessageHub;
+//# sourceMappingURL=hub.d.ts.map

package/dist/hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub.d.ts","sourceRoot":"","sources":["../src/hub.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAAA;IAC5D,6BAA6B;IAC7B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;IACnD,4BAA4B;IAC5B,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACpC,8BAA8B;IAC9B,QAAQ,IAAI,IAAI,CAAA;CACjB;AAED,wBAAgB,eAAe,IAAI,UAAU,CA+C5C"}

package/dist/hub.js

@@ -0,0 +1,51 @@
+export function localMessageHub() {
+    const byUser = new Map();
+    const all = new Set();
+    return {
+        add(userId, socket) {
+            let set = byUser.get(userId);
+            if (!set) {
+                set = new Set();
+                byUser.set(userId, set);
+            }
+            set.add(socket);
+            all.add(socket);
+            return () => {
+                set.delete(socket);
+                if (set.size === 0)
+                    byUser.delete(userId);
+                all.delete(socket);
+            };
+        },
+        publish(userId, event) {
+            const set = byUser.get(userId);
+            if (!set || set.size === 0)
+                return;
+            const payload = JSON.stringify(event);
+            for (const socket of [...set]) {
+                if (socket.readyState !== 'open')
+                    continue;
+                try {
+                    socket.send(payload);
+                }
+                catch {
+                    // 连接刚好断开：注销由 onClose 负责，推送静默跳过
+                }
+            }
+        },
+        connections(userId) {
+            if (userId === undefined)
+                return all.size;
+            return byUser.get(userId)?.size ?? 0;
+        },
+        closeAll() {
+            for (const socket of [...all]) {
+                if (socket.readyState === 'open')
+                    socket.close(1001, 'server shutdown');
+            }
+            all.clear();
+            byUser.clear();
+        },
+    };
+}
+//# sourceMappingURL=hub.js.map

package/dist/hub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub.js","sourceRoot":"","sources":["../src/hub.ts"],"names":[],"mappings":"AAeA,MAAM,UAAU,eAAe;IAC7B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoC,CAAA;IAC1D,MAAM,GAAG,GAAG,IAAI,GAAG,EAAuB,CAAA;IAE1C,OAAO;QACL,GAAG,CAAC,MAAM,EAAE,MAAM;YAChB,IAAI,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YAC5B,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,GAAG,GAAG,IAAI,GAAG,EAAE,CAAA;gBACf,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;YACzB,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YACf,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YACf,OAAO,GAAG,EAAE;gBACV,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;gBAClB,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;oBAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;gBACzC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YACpB,CAAC,CAAA;QACH,CAAC;QAED,OAAO,CAAC,MAAM,EAAE,KAAK;YACnB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YAC9B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC;gBAAE,OAAM;YAClC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;YACrC,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;gBAC9B,IAAI,MAAM,CAAC,UAAU,KAAK,MAAM;oBAAE,SAAQ;gBAC1C,IAAI,CAAC;oBACH,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;gBACtB,CAAC;gBAAC,MAAM,CAAC;oBACP,+BAA+B;gBACjC,CAAC;YACH,CAAC;QACH,CAAC;QAED,WAAW,CAAC,MAAM;YAChB,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,GAAG,CAAC,IAAI,CAAA;YACzC,OAAO,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,IAAI,CAAC,CAAA;QACtC,CAAC;QAED,QAAQ;YACN,KAAK,MAAM,MAAM,IAAI,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;gBAC9B,IAAI,MAAM,CAAC,UAAU,KAAK,MAAM;oBAAE,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAA;YACzE,CAAC;YACD,GAAG,CAAC,KAAK,EAAE,CAAA;YACX,MAAM,CAAC,KAAK,EAAE,CAAA;QAChB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createMessages } from './messages.ts';
+export { localMessageBus } from './bus.ts';
+export { memoryMessageStore } from './stores/memory.ts';
+export { decodeCursor, encodeCursor } from './cursor.ts';
+export type { CreateMessagesOptions, InsertMessageInput, InstallMessagesOptions, ListAfterPage, ListAfterQuery, ListPage, ListQuery, Message, MessageBus, MessageLogger, MessageStore, Messages, MessagesEvent, MessagesEventMap, SendInput, SendResult, StoreInsertResult, } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACxD,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,cAAc,EACd,QAAQ,EACR,SAAS,EACT,OAAO,EACP,UAAU,EACV,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,UAAU,EACV,iBAAiB,GAClB,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createMessages } from "./messages.js";
+export { localMessageBus } from "./bus.js";
+export { memoryMessageStore } from "./stores/memory.js";
+export { decodeCursor, encodeCursor } from "./cursor.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA"}

package/dist/messages.d.ts

@@ -0,0 +1,10 @@
+import type { CreateMessagesOptions, Messages } from './types.ts';
+/**
+ * 站内信/通知中心：持久化 + 未读计数 + 本人可见的只读 REST。
+ *
+ * - `send` 是服务端发送入口（HTTP 不暴露写消息，防越权群发）；
+ * - 至少一次 + 按 id 去重由客户端/实时层承担，幂等键由 store 唯一约束承担；
+ * - 实时推送（WebSocket）见后续阶段，`messages.routes()` 先提供轮询兜底。
+ */
+export declare function createMessages(options: CreateMessagesOptions): Messages;
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,qBAAqB,EAIrB,QAAQ,EAIT,MAAM,YAAY,CAAA;AAqBnB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,QAAQ,CAsQvE"}