paperkite 0.1.0

package/dist/packages/archive/src/console/service.js

@@ -0,0 +1,86 @@
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import fastifyStatic from "@fastify/static";
+import { Service } from "@paperkite/sdk";
+import { createArchiveConsoleServer } from "./server.js";
+import { createArchiveStore, resolveBackend } from "../storage/index.js";
+export class ArchiveConsoleWebService extends Service {
+    async run() {
+        const config = this.config ?? {};
+        const store = createArchiveStore({
+            url: config.url,
+            schema: config.schema
+        });
+        const server = createArchiveConsoleServer({
+            store,
+            backend: resolveBackend(config.url),
+            mediaDir: config.mediaDir,
+            session: this.session,
+            sessions: this.sessions,
+            logger: this.context.logger
+        });
+        try {
+            await store.init();
+            await server.register(fastifyStatic, {
+                root: await publicDirectory(config.publicDir),
+                index: "index.html"
+            });
+            const host = config.host ?? "127.0.0.1";
+            const port = normalizeConsolePort(config.port);
+            await listenRetrying(server, host, port, this.context.logger);
+            this.context.logger.info("archive console listening", { host, port });
+            await waitForAbort(this.signal);
+        }
+        finally {
+            await server.close().catch(() => undefined);
+            await store.close();
+        }
+    }
+}
+function normalizeConsolePort(value) {
+    const port = Number(value ?? 3379);
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw new Error("archive console port must be an integer between 1 and 65535");
+    }
+    return port;
+}
+async function listenRetrying(server, host, port, logger) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await server.listen({ host, port });
+            return;
+        }
+        catch (error) {
+            if (attempt < 6 && isEaddrinuse(error)) {
+                logger.warn("archive console port is still held by a stopping instance, retrying", { host, port });
+                await new Promise((resolvePromise) => setTimeout(resolvePromise, 500));
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+function isEaddrinuse(error) {
+    return error instanceof Error && "code" in error && error.code === "EADDRINUSE";
+}
+function waitForAbort(signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolvePromise) => {
+        signal.addEventListener("abort", () => resolvePromise(), { once: true });
+    });
+}
+async function publicDirectory(configured) {
+    if (configured)
+        return resolve(configured);
+    const local = fileURLToPath(new URL("../public", import.meta.url));
+    try {
+        await access(local);
+        return local;
+    }
+    catch {
+        return resolve(process.cwd(), "packages/archive/public");
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/packages/archive/src/console/service.js.map

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

package/dist/packages/archive/src/storage/index.d.ts

@@ -0,0 +1,6 @@
+import type { ArchiveStore, ArchiveStoreOptions } from "./model.js";
+export * from "./model.js";
+export { PostgresArchiveStore } from "./postgres.js";
+export { SqliteArchiveStore } from "./sqlite.js";
+export declare function createArchiveStore(options?: ArchiveStoreOptions): ArchiveStore;
+export declare function resolveBackend(url: string | undefined): "sqlite" | "postgres";

package/dist/packages/archive/src/storage/index.js

@@ -0,0 +1,23 @@
+import { resolve } from "node:path";
+import { PostgresArchiveStore } from "./postgres.js";
+import { SqliteArchiveStore } from "./sqlite.js";
+export * from "./model.js";
+export { PostgresArchiveStore } from "./postgres.js";
+export { SqliteArchiveStore } from "./sqlite.js";
+export function createArchiveStore(options = {}) {
+    const url = options.url ?? "sqlite:data/archive.db";
+    if (resolveBackend(url) === "sqlite") {
+        const file = url.slice("sqlite:".length) || "data/archive.db";
+        return new SqliteArchiveStore(resolve(file));
+    }
+    return new PostgresArchiveStore(url, options.schema ?? "public");
+}
+export function resolveBackend(url) {
+    const value = (url ?? "sqlite:data/archive.db").trim().toLowerCase();
+    if (value.startsWith("postgres:") || value.startsWith("postgresql:"))
+        return "postgres";
+    if (value.startsWith("sqlite:"))
+        return "sqlite";
+    throw new Error(`unknown archive backend scheme in url: ${String(url)} (use sqlite: or postgresql:)`);
+}
+//# sourceMappingURL=index.js.map

package/dist/packages/archive/src/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/archive/src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,UAAU,kBAAkB,CAAC,OAAO,GAAwB,EAAE;IAClE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,wBAAwB,CAAC;IACpD,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,iBAAiB,CAAC;QAC9D,OAAO,IAAI,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,oBAAoB,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,GAAuB;IACpD,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,wBAAwB,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrE,IAAI,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,OAAO,UAAU,CAAC;IACxF,IAAI,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,QAAQ,CAAC;IACjD,MAAM,IAAI,KAAK,CAAC,0CAA0C,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;AACxG,CAAC"}

package/dist/packages/archive/src/storage/model.d.ts

@@ -0,0 +1,296 @@
+export type TimeMode = "include" | "exclude" | "off";
+/** 一次归档抓取后落库的聊天元数据。 */
+export interface ChatRecord {
+    readonly chatId: string;
+    readonly title?: string;
+    readonly username?: string;
+    readonly type?: string;
+    readonly description?: string;
+    readonly membersCount?: number;
+}
+/** 增量锚点：该群最新已归档消息。 */
+export interface LastMessageInfo {
+    readonly messageId: number;
+    readonly date: string;
+}
+/** 消息实体（对齐 Telegram 原生 entities）：offset/length 为 UTF-16 码元，链接实体带 url。 */
+export interface MessageEntity {
+    readonly className: string;
+    readonly offset: number;
+    readonly length: number;
+    readonly url?: string;
+}
+/** 写入后端的一条消息行（字段与 messages 表一一对应）。 */
+export interface MessageRow {
+    readonly messageId: number;
+    readonly chatId: string;
+    readonly groupedId?: string;
+    readonly chatTitle?: string;
+    readonly senderId?: string;
+    readonly senderUsername?: string;
+    readonly senderFirstName?: string;
+    readonly senderLastName?: string;
+    readonly date: string;
+    readonly text: string;
+    readonly entities?: readonly MessageEntity[];
+    readonly messageType: string;
+    readonly replyToMessageId?: number;
+    readonly forwardFromId?: string;
+    readonly forwardFromName?: string;
+    readonly hasMedia: boolean;
+    readonly mediaType?: string;
+    readonly mediaFilePath?: string;
+}
+/** 写入后端的一条媒体记录行。 */
+export interface MediaRow {
+    readonly messageId: number;
+    readonly chatId: string;
+    readonly mediaType: string;
+    readonly fileName: string;
+    readonly filePath: string;
+    readonly fileSize?: number;
+    readonly mimeType?: string;
+}
+export interface BatchResult {
+    readonly messages: number;
+    readonly media: number;
+}
+/** 已落库的媒体文件完整记录（媒体文件路由用）。 */
+export interface StoredMediaFile {
+    readonly id: string;
+    readonly messageId: number;
+    readonly chatId: string;
+    readonly mediaType: string;
+    readonly fileName?: string;
+    readonly filePath?: string;
+    readonly fileSize?: number;
+    readonly mimeType?: string;
+}
+/** 同相册内的一条可预览消息（来自 messages 表）。 */
+export interface AlbumRow {
+    readonly recordId: string;
+    readonly messageId: number;
+    readonly chatId: string;
+    readonly groupedId: string;
+    readonly date: string;
+    readonly hasMedia: boolean;
+    readonly mediaType?: string;
+    readonly messageType?: string;
+    readonly mimeType?: string;
+}
+/** 检索返回的完整消息行（附媒体文件与相册行）。 */
+export interface MessageRecord {
+    readonly recordId: string;
+    readonly messageId: number;
+    readonly chatId: string;
+    readonly groupedId?: string;
+    readonly chatTitle?: string;
+    readonly date: string;
+    readonly senderId?: string;
+    readonly senderUsername?: string;
+    readonly senderFirstName?: string;
+    readonly senderLastName?: string;
+    readonly hasMedia: boolean;
+    readonly mediaType?: string;
+    readonly messageType?: string;
+    readonly mimeType?: string;
+    readonly replyToMessageId?: number;
+    /** 被回复消息的文本摘录（同会话内按消息 ID 定位，blocked = 0）。 */
+    readonly replyToText?: string;
+    readonly forwardFromId?: string;
+    readonly forwardFromName?: string;
+    /** 原始消息实体（对齐 Telegram 原生 entities，链接渲染用）。 */
+    readonly entities?: readonly MessageEntity[];
+    readonly text: string;
+    readonly mediaFiles: readonly StoredMediaFile[];
+    readonly albumRows: readonly AlbumRow[];
+}
+export interface ArchiveQuery {
+    readonly keyword?: string;
+    readonly excludeKeyword?: string;
+    /** 多会话检索：与其余条件 AND，会话之间 OR。 */
+    readonly chatIds?: readonly string[];
+    readonly chatTitle?: string;
+    readonly dateFrom?: string;
+    readonly dateTo?: string;
+    readonly timeMode?: TimeMode;
+    /** 多用户检索：与其余条件 AND，用户之间 OR。 */
+    readonly senderIds?: readonly string[];
+    readonly forwardFromId?: string;
+    readonly forwardFromName?: string;
+    readonly limit?: number;
+    readonly offset?: number;
+}
+export interface ArchiveSearchResult {
+    /** 条目视图：相册成员折叠成单个相册条目，分页按条目推进。 */
+    readonly items: readonly ContextEntry[];
+    readonly total: number;
+    /** 过滤条件命中的消息总数（相册按成员条数计，首页统计用）。 */
+    readonly totalMessages: number;
+    readonly limit: number;
+    readonly offset: number;
+}
+export interface MessageContextEntry {
+    readonly kind: "message";
+    readonly record: MessageRecord;
+}
+export interface AlbumContextEntry {
+    readonly kind: "album";
+    readonly rows: readonly MessageRecord[];
+    readonly captionText: string;
+    readonly recordId: string;
+    readonly focusRecordId?: string;
+}
+export type ContextEntry = MessageContextEntry | AlbumContextEntry;
+/** 检索用户信息：按发送者聚合后的展示字段。 */
+export interface SenderInfo {
+    readonly senderId: string;
+    readonly username?: string;
+    readonly firstName?: string;
+    readonly lastName?: string;
+}
+export interface SenderQuery {
+    readonly q?: string;
+    readonly chatId?: string;
+    readonly limit?: number;
+}
+export interface SenderSearchResult {
+    readonly items: readonly SenderInfo[];
+    readonly total: number;
+}
+/** 用户聚合概要中的单会话条目。 */
+export interface SenderSummaryChat {
+    readonly chatId: string;
+    readonly chatTitle?: string;
+    readonly count: number;
+    readonly lastDate?: string;
+    readonly lastText?: string;
+}
+/** 用户聚合概要：总计 + 按会话拆分（含每会话最新文本）。 */
+export interface SenderSummary {
+    readonly sender: SenderInfo;
+    readonly total: number;
+    readonly firstDate?: string;
+    readonly lastDate?: string;
+    readonly chats: readonly SenderSummaryChat[];
+}
+/** 回复链：锚点的回复对象与回复者；parent/children 均为上下文条目。 */
+export interface ReplyChainResult {
+    readonly parent?: ContextEntry;
+    readonly children: readonly ContextEntry[];
+    readonly replyToMessageId?: number;
+}
+/** 锚点条目及两侧上下文；beforeN/afterN 为该侧条目总数（不含锚点）。 */
+export interface ArchiveContextResult {
+    readonly anchor: ContextEntry | undefined;
+    readonly before: readonly ContextEntry[];
+    readonly after: readonly ContextEntry[];
+    readonly beforeN: number;
+    readonly afterN: number;
+}
+export declare function captionOf(rows: readonly MessageRecord[]): string;
+export declare function uniqueGroupKeys(rows: readonly Record<string, unknown>[]): (readonly [string, string])[];
+export declare function albumEntryOf(rows: readonly MessageRecord[], focusRecordId?: string): ContextEntry;
+export declare function buildContextEntries(baselines: readonly MessageRecord[], groupRows: ReadonlyMap<string, readonly MessageRecord[]>): ContextEntry[];
+/** 会话清单行：chats 元数据 + 消息表的按会话聚合。 */
+export interface ChatLedgerRow {
+    readonly chatId: string;
+    readonly title: string;
+    readonly username?: string;
+    readonly type?: string;
+    readonly description?: string;
+    readonly membersCount?: number;
+    readonly count: number;
+    readonly lastDate?: string;
+    readonly lastText?: string;
+}
+export interface ArchiveStoreOptions {
+    readonly url?: string;
+    readonly schema?: string;
+}
+/** 屏蔽词快照：词表（已归一化小写）与内存缓存版本号。 */
+export interface BlockwordState {
+    readonly words: readonly string[];
+    readonly version: number;
+}
+export type BlockwordAddResult = "added" | "exists" | "invalid";
+/** 被屏蔽用户：以 sender_id 精确匹配消息行，附展示信息供管理界面使用。 */
+export interface BlockedUserInfo {
+    readonly userId: string;
+    readonly name?: string;
+    readonly username?: string;
+}
+export interface BlockedUserInput {
+    readonly userId: string;
+    readonly name?: string;
+    readonly username?: string;
+}
+/** 屏蔽用户快照：名单与内存缓存版本号。 */
+export interface BlockedUserState {
+    readonly users: readonly BlockedUserInfo[];
+    readonly version: number;
+}
+export type BlockedUserAddResult = "added" | "exists" | "invalid";
+export interface ArchiveStore {
+    init(): Promise<void>;
+    close(): Promise<void>;
+    saveChat(chat: ChatRecord): Promise<boolean>;
+    startSyncSession(chatId: string, startDate: string, endDate: string): Promise<number>;
+    completeSyncSession(sessionId: number, messagesCount: number, mediaCount: number): Promise<void>;
+    getLastMessageInfo(chatId: string): Promise<LastMessageInfo | undefined>;
+    getChatUsername(chatId: string): Promise<string | undefined>;
+    messageIdsExist(chatId: string, messageIds: readonly number[]): Promise<ReadonlySet<number>>;
+    saveBatch(messages: readonly MessageRow[], media: readonly MediaRow[]): Promise<BatchResult>;
+    searchStructured(query: ArchiveQuery): Promise<ArchiveSearchResult>;
+    listChatLedger(limit: number): Promise<ChatLedgerRow[]>;
+    getMessageContext(recordId: string, beforeN: number, afterN: number, beforeOffset?: number, afterOffset?: number): Promise<ArchiveContextResult>;
+    getMessageByRecordId(recordId: string): Promise<MessageRecord | undefined>;
+    /** 用户维度检索：按发送者聚合（blocked = 0），支持名字/用户名/ID 匹配。 */
+    searchSenders(query: SenderQuery): Promise<SenderSearchResult>;
+    /** 用户聚合概要：不存在该用户（不看屏蔽）返回 undefined，路由映射 404。 */
+    getSenderSummary(senderId: string, chatId?: string): Promise<SenderSummary | undefined>;
+    /** 回复链：锚点不存在（含被屏蔽）返回 undefined，路由映射 404。 */
+    getReplyChain(recordId: string): Promise<ReplyChainResult | undefined>;
+    /** 按聊天引用解析消息：chatId、username 或私有频道 code 之一定位聊天，返回存档行 ID；不存在返回 undefined。 */
+    resolveMessageRef(ref: {
+        chatId?: string;
+        username?: string;
+        code?: string;
+        messageId: number;
+    }): Promise<string | undefined>;
+    getMediaFileById(id: string): Promise<StoredMediaFile | undefined>;
+    /** 屏蔽词内存缓存快照，读路径不触表。 */
+    listBlockwords(): Promise<BlockwordState>;
+    /** 写透缓存：先落库再更新内存缓存，并同步三条消息的 blocked 标志。 */
+    addBlockword(word: string): Promise<BlockwordAddResult>;
+    /** 写透缓存；删除后仅重算命中被删词的行。 */
+    removeBlockword(word: string): Promise<boolean>;
+    /** 屏蔽用户内存缓存快照，读路径不触表。 */
+    listBlockedUsers(): Promise<BlockedUserState>;
+    /** 写透缓存：先落库再更新内存缓存，并同步 sender 命中行的 blocked 标志。 */
+    addBlockedUser(input: BlockedUserInput): Promise<BlockedUserAddResult>;
+    /** 写透缓存；删除后仅重算发送者为被删用户的行。 */
+    removeBlockedUser(userId: string): Promise<boolean>;
+}
+export declare function normalizeLimit(value: number | undefined): number;
+export declare function normalizeOffset(value: number | undefined): number;
+export declare function normalizeContextLimit(value: number | undefined): number;
+export declare function normalizeTimeMode(value: TimeMode | undefined): TimeMode;
+export declare function splitTerms(value: string | undefined): string[];
+/** 解析时间输入为 UTC ISO 字符串；空值返回 undefined，非法输入抛错。 */
+export declare function normalizeDate(value: string | undefined): string | undefined;
+export declare function normalizeText(value: string | undefined): string | undefined;
+export declare const BLOCKWORD_MAX_LENGTH = 64;
+/** 屏蔽词归一化：裁剪、小写；空词或超长返回 undefined。 */
+export declare function normalizeBlockword(value: string): string | undefined;
+export declare const BLOCKED_USER_MAX_LENGTH = 64;
+/** 屏蔽用户 ID 归一化：裁剪；空串或超长返回 undefined。 */
+export declare function normalizeUserId(value: string): string | undefined;
+export declare function normalizeRecordId(value: string): string;
+export declare function mediaKey(chatId: string, messageId: number): string;
+export declare function groupKey(chatId: string, groupedId: string): string;
+export declare function paramPlaceholders(start: number, count: number): string;
+/** 实体列：JSON 串 ↔ 实体数组（空数组与空值同样视为无实体）。 */
+export declare function entitiesJson(entities: readonly MessageEntity[] | undefined): string | null;
+export declare function parseEntities(value: unknown): readonly MessageEntity[] | undefined;
+export declare function toIsoDate(value: unknown): string;

package/dist/packages/archive/src/storage/model.js

@@ -0,0 +1,151 @@
+export function captionOf(rows) {
+    return rows.find((row) => row.text.trim().length > 0)?.text ?? "";
+}
+export function uniqueGroupKeys(rows) {
+    const seen = new Set();
+    const keys = [];
+    for (const row of rows) {
+        const value = row.grouped_id;
+        if (value === undefined || value === null || value === "")
+            continue;
+        const grouped = String(value);
+        const key = groupKey(String(row.chat_id), grouped);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        keys.push([String(row.chat_id), grouped]);
+    }
+    return keys;
+}
+export function albumEntryOf(rows, focusRecordId) {
+    if (rows.length < 2)
+        return { kind: "message", record: rows[0] };
+    return {
+        kind: "album",
+        rows,
+        captionText: captionOf(rows),
+        recordId: rows[0].recordId,
+        ...(focusRecordId !== undefined ? { focusRecordId } : {})
+    };
+}
+export function buildContextEntries(baselines, groupRows) {
+    return baselines.map((row) => {
+        if (row.groupedId === undefined)
+            return { kind: "message", record: row };
+        const rows = groupRows.get(groupKey(row.chatId, row.groupedId));
+        if (rows === undefined || rows.length < 2)
+            return { kind: "message", record: row };
+        return { kind: "album", rows, captionText: captionOf(rows), recordId: row.recordId };
+    });
+}
+export function normalizeLimit(value) {
+    return clampInteger(value, 1, 200, 50);
+}
+export function normalizeOffset(value) {
+    const number = Number(value);
+    return Number.isInteger(number) && number > 0 ? number : 0;
+}
+export function normalizeContextLimit(value) {
+    return clampInteger(value, 0, 999, 10);
+}
+export function normalizeTimeMode(value) {
+    const mode = value ?? "include";
+    if (mode !== "include" && mode !== "exclude" && mode !== "off") {
+        throw new Error(`invalid time mode: ${String(value)}`);
+    }
+    return mode;
+}
+export function splitTerms(value) {
+    return (value ?? "").trim().split(/\s+/).filter(Boolean);
+}
+/** 解析时间输入为 UTC ISO 字符串；空值返回 undefined，非法输入抛错。 */
+export function normalizeDate(value) {
+    const text = (value ?? "").trim();
+    if (!text)
+        return undefined;
+    const time = Date.parse(text);
+    if (Number.isNaN(time))
+        throw new Error(`invalid date: ${value}`);
+    return new Date(time).toISOString();
+}
+export function normalizeText(value) {
+    const text = (value ?? "").trim();
+    return text || undefined;
+}
+export const BLOCKWORD_MAX_LENGTH = 64;
+/** 屏蔽词归一化：裁剪、小写；空词或超长返回 undefined。 */
+export function normalizeBlockword(value) {
+    const text = value.trim().toLowerCase();
+    if (!text || text.length > BLOCKWORD_MAX_LENGTH)
+        return undefined;
+    return text;
+}
+export const BLOCKED_USER_MAX_LENGTH = 64;
+/** 屏蔽用户 ID 归一化：裁剪；空串或超长返回 undefined。 */
+export function normalizeUserId(value) {
+    const text = value.trim();
+    if (!text || text.length > BLOCKED_USER_MAX_LENGTH)
+        return undefined;
+    return text;
+}
+export function normalizeRecordId(value) {
+    const result = value.trim();
+    if (!/^\d+$/.test(result))
+        throw new Error(`invalid message record id: ${value}`);
+    return result;
+}
+export function mediaKey(chatId, messageId) {
+    return `${chatId}:${messageId}`;
+}
+export function groupKey(chatId, groupedId) {
+    return `${chatId}:${groupedId}`;
+}
+export function paramPlaceholders(start, count) {
+    return Array.from({ length: count }, (_, index) => `$${start + index}`).join(", ");
+}
+/** 实体列：JSON 串 ↔ 实体数组（空数组与空值同样视为无实体）。 */
+export function entitiesJson(entities) {
+    return entities !== undefined && entities.length > 0 ? JSON.stringify(entities) : null;
+}
+export function parseEntities(value) {
+    if (typeof value !== "string" || value === "")
+        return undefined;
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed))
+            return undefined;
+        const entities = parsed
+            .filter((item) => typeof item === "object" && item !== null)
+            .map((item) => ({
+            className: String(item.className ?? ""),
+            offset: Number(item.offset ?? 0),
+            length: Number(item.length ?? 0),
+            ...(typeof item.url === "string" && item.url ? { url: item.url } : {})
+        }))
+            .filter((entity) => entity.className !== "" && entity.length > 0);
+        return entities.length > 0 ? entities : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function toIsoDate(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    const text = String(value).trim();
+    if (/^\d+$/.test(text)) {
+        const timestamp = Number(text);
+        return new Date(timestamp < 1e12 ? timestamp * 1_000 : timestamp).toISOString();
+    }
+    const time = Date.parse(text);
+    if (Number.isNaN(time))
+        throw new Error(`invalid date value: ${text}`);
+    return new Date(time).toISOString();
+}
+function clampInteger(value, lower, upper, fallback) {
+    const number = Number(value);
+    if (!Number.isInteger(number))
+        return fallback;
+    return Math.min(upper, Math.max(lower, number));
+}
+//# sourceMappingURL=model.js.map

package/dist/packages/archive/src/storage/model.js.map

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

package/dist/packages/archive/src/storage/postgres.d.ts

@@ -0,0 +1,67 @@
+import { type ArchiveContextResult, type ArchiveQuery, type ArchiveSearchResult, type ArchiveStore, type BatchResult, type BlockedUserAddResult, type BlockedUserInput, type BlockedUserState, type BlockwordAddResult, type BlockwordState, type ChatLedgerRow, type ChatRecord, type LastMessageInfo, type MediaRow, type MessageRecord, type MessageRow, type ReplyChainResult, type SenderQuery, type SenderSearchResult, type SenderSummary, type StoredMediaFile } from "./model.js";
+export declare class PostgresArchiveStore implements ArchiveStore {
+    readonly url: string;
+    private readonly pool;
+    private readonly schemaName;
+    private readonly schema;
+    /** 屏蔽词内存缓存（小写归一）；读路径条件固定为 blocked = FALSE，与词数无关。 */
+    private blockwords;
+    private blockwordsVersion;
+    /** 屏蔽用户内存缓存（sender_id 精确匹配）。 */
+    private blockedUsers;
+    private blockedUsersVersion;
+    constructor(url: string, schema?: string);
+    init(): Promise<void>;
+    /** 老库迁移：messages 补 blocked 标志列与 entities 实体列。 */
+    private ensureLegacyColumns;
+    /** blocked 标志维护的部分索引：置位只扫未屏蔽行，解锁只扫已屏蔽行。 */
+    private ensureBlockedIndexes;
+    close(): Promise<void>;
+    saveChat(chat: ChatRecord): Promise<boolean>;
+    startSyncSession(chatId: string, startDate: string, endDate: string): Promise<number>;
+    completeSyncSession(sessionId: number, messagesCount: number, mediaCount: number): Promise<void>;
+    getLastMessageInfo(chatId: string): Promise<LastMessageInfo | undefined>;
+    getChatUsername(chatId: string): Promise<string | undefined>;
+    messageIdsExist(chatId: string, messageIds: readonly number[]): Promise<ReadonlySet<number>>;
+    saveBatch(messages: readonly MessageRow[], media: readonly MediaRow[]): Promise<BatchResult>;
+    listBlockwords(): Promise<BlockwordState>;
+    addBlockword(word: string): Promise<BlockwordAddResult>;
+    removeBlockword(word: string): Promise<boolean>;
+    listBlockedUsers(): Promise<BlockedUserState>;
+    addBlockedUser(input: BlockedUserInput): Promise<BlockedUserAddResult>;
+    removeBlockedUser(userId: string): Promise<boolean>;
+    /** 增量置位：只置未屏蔽行中命中新词的行的标志。 */
+    private markBlockwordMatches;
+    /** 增量解锁：只重算已屏蔽且命中被删词的行，其余行不受影响。 */
+    private unmarkBlockwordMatches;
+    /** 增量置位：只置未屏蔽行中发送者为新用户的行的标志。 */
+    private markBlockedUserMatches;
+    /** 增量解锁：只重算已屏蔽且发送者为被删用户的行。 */
+    private unmarkBlockedUserMatches;
+    /**
+     * 增量解锁执行：match 命中已屏蔽行，剩余规则（holds）全不命中时解锁。
+     * 命中行先经子查询物化，避免 UPDATE 边扫索引边改 blocked 时漏行。
+     */
+    private runUnblock;
+    searchStructured(query: ArchiveQuery): Promise<ArchiveSearchResult>;
+    listChatLedger(limit: number): Promise<ChatLedgerRow[]>;
+    getMessageByRecordId(recordId: string): Promise<MessageRecord | undefined>;
+    searchSenders(query: SenderQuery): Promise<SenderSearchResult>;
+    getSenderSummary(senderId: string, chatId?: string): Promise<SenderSummary | undefined>;
+    getReplyChain(recordId: string): Promise<ReplyChainResult | undefined>;
+    resolveMessageRef(ref: {
+        chatId?: string;
+        username?: string;
+        code?: string;
+        messageId: number;
+    }): Promise<string | undefined>;
+    getMessageContext(recordId: string, beforeN: number, afterN: number, beforeOffset?: number, afterOffset?: number): Promise<ArchiveContextResult>;
+    private fetchGroupAttached;
+    private fetchGroupsAttached;
+    private groupRows;
+    getMediaFileById(id: string): Promise<StoredMediaFile | undefined>;
+    private attachMedia;
+    private fetchMediaFiles;
+    private fetchAlbumRows;
+    private table;
+}