ehbrowser 1.0.0

package/dist/api/dto/gallery.js

@@ -0,0 +1,43 @@
+/*
+ * 画廊相关线上结构。
+ *
+ * 字段与 EhViewer 的 GalleryInfo / GalleryDetail 对齐，有三处差异：
+ * category 使用上游原始字符串而非下标；数字字段统一为 number；
+ * parent / current / first 合并为单个关系对象。
+ */
+/** 分类名，取上游原始字符串（大小写与空格保持不变） */
+export const GALLERY_CATEGORIES = [
+    "Doujinshi",
+    "Manga",
+    "Artist CG",
+    "Game CG",
+    "Western",
+    "Image Set",
+    "Non-H",
+    "Cosplay",
+    "Asian Porn",
+    "Misc",
+    "Private",
+];
+/** 对应上游 language:* 标签；translated 为独立标签，不属于语种 */
+export const GALLERY_LANGUAGES = [
+    "chinese",
+    "dutch",
+    "english",
+    "french",
+    "german",
+    "hungarian",
+    "italian",
+    "japanese",
+    "korean",
+    "polish",
+    "portuguese",
+    "russian",
+    "spanish",
+    "thai",
+    "vietnamese",
+];
+/**
+ * 一次检索取多少条。界面与启动预热都使用该值，缓存命中判定以此为准。
+ */
+export const SEARCH_PAGE_LIMIT = 24;

package/dist/api/dto/index.js

@@ -0,0 +1,6 @@
+/*
+ * DTO 出口
+ * 类型须以 export type 重新导出：verbatimModuleSyntax 下写成 export 会留下不存在的运行时绑定
+ */
+export { GALLERY_CATEGORIES, GALLERY_LANGUAGES, SEARCH_PAGE_LIMIT } from "./gallery.js";
+export { playlistKeyOf } from "./playlist.js";

package/dist/api/dto/library.js

@@ -0,0 +1,5 @@
+/*
+ * 本地库的线上结构。
+ * 对应下载根目录下的 <分辨率>@<画廊名>/ 与其中的 .ehbrowser 元数据。
+ */
+export {};

package/dist/api/dto/log.js

@@ -0,0 +1,5 @@
+/*
+ * 日志的线上结构。
+ * 服务端把每一路服务的消息同时写进日志文件并经 SSE 推给界面，界面只读最近若干条。
+ */
+export {};

package/dist/api/dto/playlist.js

@@ -0,0 +1,8 @@
+/*
+ * 播放列表的线上结构。
+ * 用户播放列表持久化在 SQLite 的 playlist_items 表，应用重启不丢失。
+ */
+/** 由 gid 与分辨率拼出 key。分辨率缺失时用 net */
+export function playlistKeyOf(gid, resolution) {
+    return `${gid}-${resolution === null || resolution === undefined || resolution === "" ? "net" : resolution}`;
+}

package/dist/api/dto/settings.js

@@ -0,0 +1,5 @@
+/*
+ * 配置的线上结构。
+ * 与 src/config/schema.ts 的内部类型保持分离：内部重构不影响对外契约，代理凭据等字段不回传。
+ */
+export {};

package/dist/api/dto/storage.js

@@ -0,0 +1,5 @@
+/*
+ * 储存空间。设置页该分组使用。
+ * 两个数字分别来自本地库扫描的占用与详情缓存的体积，清理只作用于缓存。
+ */
+export {};

package/dist/api/dto/translate.js

@@ -0,0 +1,6 @@
+/*
+ * 标签翻译词库的线上结构。
+ * 数据来自上游项目 EhTagTranslation/Database 的发布包，按需下载后移除简介，
+ * 只保留「原文 -> 中文名」，因此这里只有名字与出处，没有简介文本。
+ */
+export {};

package/dist/api/envelope.js

@@ -0,0 +1,41 @@
+/*
+ * 统一响应信封
+ * 未采用「裸数据 + HTTP 状态码」的原因：客户端只需判断一次 ok，错误统一经 error.code 区分；
+ * 校验问题随 issues 返回，可直接定位到输入框。HTTP 状态码仍按 HTTP_STATUS_BY_ERROR 设置
+ */
+/** 错误码到 HTTP 状态码的映射 */
+export const HTTP_STATUS_BY_ERROR = {
+    bad_request: 400,
+    unauthorized: 401,
+    forbidden: 403,
+    not_found: 404,
+    conflict: 409,
+    config_invalid: 422,
+    not_logged_in: 403,
+    rate_limited: 429,
+    upstream_unavailable: 502,
+    busy: 503,
+    not_implemented: 501,
+    internal: 500,
+};
+/** 构造成功响应 */
+export function ok(data, requestId) {
+    return requestId === undefined ? { ok: true, data } : { ok: true, data, requestId };
+}
+/** 构造失败响应 */
+export function fail(code, message, options = {}) {
+    const error = options.issues === undefined
+        ? { code, message }
+        : { code, message, issues: options.issues };
+    return options.requestId === undefined
+        ? { ok: false, error }
+        : { ok: false, error, requestId: options.requestId };
+}
+/** 类型收窄辅助 */
+export function isApiFailure(response) {
+    return !response.ok;
+}
+/** 取错误码对应的 HTTP 状态码 */
+export function statusForError(code) {
+    return HTTP_STATUS_BY_ERROR[code];
+}

package/dist/api/events.js

@@ -0,0 +1,20 @@
+/*
+ * 服务端到浏览器的事件推送（SSE）
+ * 配置变更、账号切换、下载进度均产生于服务端，浏览器可能同时开启多个页面；
+ * 由服务端广播替代各页面轮询。事件名与负载类型一一对应，两端共用同一张表
+ */
+export const API_EVENT_NAMES = [
+    "server.ready",
+    "config.changed",
+    "auth.changed",
+    "download.changed",
+    "library.update",
+    "library.progress",
+    "log.appended",
+];
+/** 心跳间隔；长时间无事件时保活，避免浏览器断开连接 */
+export const API_EVENT_HEARTBEAT_MS = 15000;
+/** 校验事件名；名称错误时浏览器无法接收 */
+export function isApiEventName(value) {
+    return API_EVENT_NAMES.includes(value);
+}

package/dist/api/index.js

@@ -0,0 +1,12 @@
+/*
+ * src/api 出口。对外仅暴露本文件，内部文件结构可变。
+ * 依赖方向：不引用 config / services / platform / eh，属纯契约层。
+ *
+ * @author 西博卡滋
+ * @since 1.0.0
+ */
+export * from "./envelope.js";
+export * from "./contract.js";
+export * from "./routes.js";
+export * from "./events.js";
+export * from "./dto/index.js";

package/dist/api/routes.js

@@ -0,0 +1,516 @@
+/*
+ * 路由表与 URL 工具。
+ * ROUTES 与 contract.ts 相互约束：漏写路由或写入契约中不存在的路由都会编译报错。
+ * 用法：routePath("galleries.detail", { gid, token }) + buildQueryString({ page: 2 })。
+ */
+/** 接口统一前缀 */
+export const API_BASE_PATH = "/api";
+/**
+ * 本地令牌请求头
+ * 服务端仅监听 127.0.0.1，但浏览器中的任意页面都可向 localhost 发起请求（CSRF），
+ * 因此所有接口均要求令牌；令牌每次启动重新生成，仅注入本地界面
+ */
+export const API_TOKEN_HEADER = "x-ehbrowser-token";
+/** EventSource 无法设置请求头，令牌经 query 传递 */
+export const API_TOKEN_QUERY_PARAM = "_token";
+export const ROUTES = {
+    // ── 系统 ───────────────────────────────────────────────
+    "system.health": {
+        method: "GET",
+        path: "/api/health",
+        description: "服务健康状态、版本与运行时长",
+        requiresToken: false,
+        requiresAccount: false,
+    },
+    "system.shutdown": {
+        method: "POST",
+        path: "/api/system/shutdown",
+        description: "关闭本地服务；界面与事件流随之断开",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "system.events": {
+        method: "GET",
+        path: "/api/events",
+        description: "SSE 事件流：配置变更、鉴权变更、下载进度、日志",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    // ── 配置 ───────────────────────────────────────────────
+    "config.get": {
+        method: "GET",
+        path: "/api/config",
+        description: "取配置快照（生效值 + 每个字段的来源层）",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "config.patch": {
+        method: "PATCH",
+        path: "/api/config",
+        description: "局部更新用户配置（深合并）",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "config.paths": {
+        method: "GET",
+        path: "/api/config/paths",
+        description: "数据目录及其来源层（排错用）",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "config.export": {
+        method: "POST",
+        path: "/api/config/export",
+        description: "导出配置包（可选包含账号凭据）",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "config.import": {
+        method: "POST",
+        path: "/api/config/import",
+        description: "导入配置包（自动备份并迁移版本）",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    // ── 账号与鉴权 ─────────────────────────────────────────
+    "auth.status": {
+        method: "GET",
+        path: "/api/auth/status",
+        description: "登录状态摘要（不含任何凭据）",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "auth.login": {
+        method: "POST",
+        path: "/api/auth/login",
+        description: "用账号密码登录，cookie 由服务端持有",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "auth.logout": {
+        method: "POST",
+        path: "/api/auth/logout",
+        description: "清除当前账号的登录态",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "auth.accounts.list": {
+        method: "GET",
+        path: "/api/auth/accounts",
+        description: "账号列表（脱敏）",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "auth.accounts.create": {
+        method: "POST",
+        path: "/api/auth/accounts",
+        description: "新增账号（提交 cookie 或密码）",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "auth.accounts.update": {
+        method: "PATCH",
+        path: "/api/auth/accounts/:accountId",
+        description: "更新账号备注或凭据",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "auth.accounts.remove": {
+        method: "DELETE",
+        path: "/api/auth/accounts/:accountId",
+        description: "删除账号",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "auth.accounts.activate": {
+        method: "POST",
+        path: "/api/auth/accounts/:accountId/activate",
+        description: "切换当前使用的账号",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    // ── 画廊 ───────────────────────────────────────────────
+    "galleries.search": {
+        method: "GET",
+        path: "/api/galleries",
+        description: "搜索/浏览画廊列表",
+        requiresToken: true,
+        requiresAccount: true,
+    },
+    "galleries.detailCache": {
+        method: "GET",
+        path: "/api/galleries/detail-cache",
+        description: "详情页缓存的状态（条数、上限、体积）",
+        requiresToken: true,
+        // 只读内存里的缓存，不访问上游
+        requiresAccount: false,
+    },
+    "galleries.detailCache.clear": {
+        method: "DELETE",
+        path: "/api/galleries/detail-cache",
+        description: "清空详情页缓存",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "galleries.searchCache": {
+        method: "GET",
+        path: "/api/galleries/cache",
+        description: "上一次检索的条件与结果；进程内缓存，应用重启即丢",
+        requiresToken: true,
+        // 只读本地缓存，不访问上游，因此不要求账号
+        requiresAccount: false,
+    },
+    "galleries.newer": {
+        method: "GET",
+        path: "/api/galleries/:gid/:token/newer",
+        description: "查询是否存在更新的版本，结果落盘缓存",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "galleries.detail": {
+        method: "GET",
+        path: "/api/galleries/:gid/:token",
+        description: "画廊详情（标签、预览、评论）",
+        requiresToken: true,
+        requiresAccount: true,
+    },
+    "galleries.page": {
+        method: "GET",
+        path: "/api/galleries/:gid/:token/pages/:page",
+        description: "取单页图片地址（服务端代为调用 showpage）",
+        requiresToken: true,
+        requiresAccount: true,
+    },
+    "galleries.token": {
+        method: "POST",
+        path: "/api/galleries/token",
+        description: "由单页链接反查画廊 token（gtoken）",
+        requiresToken: true,
+        requiresAccount: true,
+    },
+    "galleries.rate": {
+        method: "POST",
+        path: "/api/galleries/:gid/:token/rating",
+        description: "评分（需要 apiuid/apikey）",
+        requiresToken: true,
+        requiresAccount: true,
+    },
+    "galleries.favorite": {
+        method: "POST",
+        path: "/api/galleries/:gid/:token/favorite",
+        description: "收藏到指定分类，slot<0 表示取消收藏",
+        requiresToken: true,
+        requiresAccount: true,
+    },
+    "galleries.torrents": {
+        method: "GET",
+        path: "/api/galleries/:gid/:token/torrents",
+        description: "种子列表",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "galleries.previews": {
+        method: "GET",
+        path: "/api/galleries/:gid/:token/previews",
+        description: "某一组预览图，每 20 页一组",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "galleries.archives": {
+        method: "GET",
+        path: "/api/galleries/:gid/:token/archives",
+        description: "归档选项与账户资金",
+        requiresToken: true,
+        requiresAccount: true,
+    },
+    // ── 本地库 ─────────────────────────────────────────────
+    "library.list": {
+        method: "GET",
+        path: "/api/library",
+        description: "本地已下载的画廊列表",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "library.progress": {
+        method: "PATCH",
+        path: "/api/library/:gid/:resolution",
+        description: "写回某个本地画廊的阅读进度",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    // 图片要能直接放进 <img src>，令牌经 query 传递（与 EventSource 的处理一致）
+    "library.image": {
+        method: "GET",
+        path: "/api/library/:gid/:resolution/pages/:page",
+        description: "取本地已下载的第 page 页图片",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "library.updates": {
+        method: "GET",
+        path: "/api/library/updates",
+        description: "更新检查的缓存与进度（只读）",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "library.check": {
+        method: "POST",
+        path: "/api/library/updates",
+        description: "发起更新检查，结果经 SSE 逐条推送",
+        requiresToken: true,
+        requiresAccount: true,
+    },
+    "library.updates.forget": {
+        method: "POST",
+        path: "/api/library/updates/forget",
+        description: "从更新列表里移除若干条目（不删除本地文件）",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "library.remove": {
+        method: "DELETE",
+        path: "/api/library/:gid/:resolution",
+        description: "删除本地画廊及其目录",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    // ── 储存空间 ───────────────────────────────────────────
+    "storage.stats": {
+        method: "GET",
+        path: "/api/storage",
+        description: "本地画廊与画廊缓存的占用统计",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "storage.cleanup": {
+        method: "POST",
+        path: "/api/storage/cleanup",
+        description: "按时间清理画廊缓存",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    // ── 收藏 ───────────────────────────────────────────────
+    "favorites.state": {
+        method: "GET",
+        path: "/api/favorites",
+        description: "本地收藏夹与云端收藏分类",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "favorites.folder.create": {
+        method: "POST",
+        path: "/api/favorites/folders",
+        description: "新建本地收藏夹",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "favorites.folder.remove": {
+        method: "DELETE",
+        path: "/api/favorites/folders/:folderId",
+        description: "删除本地收藏夹及其条目",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "favorites.items": {
+        method: "GET",
+        path: "/api/favorites/folders/:folderId/items",
+        description: "本地收藏夹里的画廊",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "favorites.items.add": {
+        method: "POST",
+        path: "/api/favorites/items",
+        description: "把一个画廊加入本地收藏夹（可同时指定云端槽位）",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "favorites.items.remove": {
+        method: "DELETE",
+        path: "/api/favorites/folders/:folderId/items/:gid",
+        description: "从本地收藏夹移除一个画廊",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "favorites.items.slot": {
+        method: "PATCH",
+        path: "/api/favorites/folders/:folderId/items/:gid",
+        description: "改这条收藏的标记号（云端槽位），登录时同步到上游",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "favorites.cloud": {
+        method: "GET",
+        path: "/api/favorites/cloud",
+        description: "云端某个收藏分类里的画廊",
+        requiresToken: true,
+        requiresAccount: true,
+    },
+    "favorites.items.refresh": {
+        method: "POST",
+        path: "/api/favorites/folders/:folderId/items/refresh",
+        description: "更新标记号：把收藏从这一版挪到上游的最新版本",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    // ── 日志 ───────────────────────────────────────────────
+    "log.state": {
+        method: "GET",
+        path: "/api/logs",
+        description: "日志目录、文件名与最近若干条日志",
+        requiresToken: true,
+        // 只读内存里的环形缓冲，不访问上游
+        requiresAccount: false,
+    },
+    // ── 标签翻译词库 ───────────────────────────────────────
+    "translate.status": {
+        method: "GET",
+        path: "/api/translate",
+        description: "标签翻译词库的状态",
+        requiresToken: true,
+        // 只读本地文件，不访问上游
+        requiresAccount: false,
+    },
+    "translate.tags": {
+        method: "GET",
+        path: "/api/translate/tags",
+        description: "整份标签翻译词库（原文 → 中文名）",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "translate.update": {
+        method: "POST",
+        path: "/api/translate/update",
+        description: "从 EhTagTranslation/Database 的发布包下载并重建词库",
+        requiresToken: true,
+        // 下载的是 GitHub 的发布包，不是 E-Hentai，因此不要求登录
+        requiresAccount: false,
+    },
+    "translate.remove": {
+        method: "DELETE",
+        path: "/api/translate",
+        description: "删除本地词库，回到内置的常用翻译",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    // ── 播放列表 ───────────────────────────────────────────
+    "playlist.list": {
+        method: "GET",
+        path: "/api/playlist",
+        description: "用户播放列表与当前播放项",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "playlist.add": {
+        method: "POST",
+        path: "/api/playlist",
+        description: "把一个画廊加入用户播放列表",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "playlist.play": {
+        method: "POST",
+        path: "/api/playlist/:key/play",
+        description: "把某一项设为当前播放项",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "playlist.progress": {
+        method: "PATCH",
+        path: "/api/playlist/:key",
+        description: "写回某个画廊的播放进度",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "playlist.remove": {
+        method: "DELETE",
+        path: "/api/playlist/:key",
+        description: "从播放列表移除一项",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "playlist.clear": {
+        method: "DELETE",
+        path: "/api/playlist",
+        description: "清空播放列表",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    // ── 下载 ───────────────────────────────────────────────
+    "downloads.list": {
+        method: "GET",
+        path: "/api/downloads",
+        description: "下载任务列表",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "downloads.create": {
+        method: "POST",
+        path: "/api/downloads",
+        description: "新建归档下载任务",
+        requiresToken: true,
+        requiresAccount: true,
+    },
+    "downloads.retry": {
+        method: "POST",
+        path: "/api/downloads/:taskId/retry",
+        description: "重新排队失败或已取消的下载任务",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+    "downloads.cancel": {
+        method: "DELETE",
+        path: "/api/downloads/:taskId",
+        description: "取消或移出下载任务",
+        requiresToken: true,
+        requiresAccount: false,
+    },
+};
+/**
+ * 填充 :name 占位符。缺少参数时抛出异常，避免生成无效 URL
+ */
+export function fillPath(template, params = {}) {
+    return template.replace(/:([A-Za-z0-9_]+)/g, (_match, name) => {
+        const value = params[name];
+        if (value === undefined) {
+            throw new Error(`缺少路径参数：${name}（模板 ${template}）`);
+        }
+        return encodeURIComponent(String(value));
+    });
+}
+/**
+ * 构造查询串
+ * undefined / null / 空字符串跳过，可选字段可直接传入
+ * 数组以逗号连接（多值参数统一约定，如 categories），布尔输出 1 / 0
+ * 空格编码为 %20 而非 +，保证分类名原样传递给上游
+ */
+export function buildQueryString(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === "") {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            if (value.length === 0) {
+                continue;
+            }
+            search.set(key, value.map((item) => String(item)).join(","));
+        }
+        else if (typeof value === "boolean") {
+            search.set(key, value ? "1" : "0");
+        }
+        else {
+            search.set(key, String(value));
+        }
+    }
+    const query = search.toString().replaceAll("+", "%20");
+    return query === "" ? "" : `?${query}`;
+}
+/** 取路由路径；无路径参数的路由无需第二个实参，由条件类型约束 */
+export function routePath(name, ...args) {
+    const params = args[0];
+    return fillPath(ROUTES[name].path, (params ?? {}));
+}
+/** 存在缺失时此行编译报错，错误信息包含路由名与参数名 */
+const PATH_PARAMS_COVERAGE = true;
+void PATH_PARAMS_COVERAGE;