ehbrowser 1.0.0

package/dist/eh/auth.js

@@ -0,0 +1,89 @@
+/*
+ * 登录与通行证获取。
+ * 登录在论坛域完成（表单 POST），igneous 由画廊站在登录后下发。
+ * 出口节点会影响 igneous 是否下发：拿不到时通常需要更换节点后重新登录。
+ */
+import { cookiesOf, hasLoginCookies, isIgneousValue, pickLoginCookies, toCookieMap, } from "./cookies.js";
+import { callApi } from "./http.js";
+const FORUM_ORIGIN = "https://forums.e-hentai.org";
+const FORUM_LOGIN_URL = `${FORUM_ORIGIN}/index.php?act=Login&CODE=01`;
+const FORUM_LOGIN_REFERER = `${FORUM_ORIGIN}/index.php?act=Login&CODE=00`;
+/** 表单登录论坛。失败时上游不下发凭据 Cookie，此处据此抛错 */
+export async function forumLogin(credentials) {
+    const body = new URLSearchParams({
+        referer: FORUM_LOGIN_REFERER,
+        b: "",
+        bt: "",
+        UserName: credentials.username,
+        PassWord: credentials.password,
+        CookieDate: "1",
+    }).toString();
+    const response = await callApi({
+        url: FORUM_LOGIN_URL,
+        method: "POST",
+        body,
+        headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            referer: FORUM_LOGIN_REFERER,
+            origin: FORUM_ORIGIN,
+        },
+    });
+    const picked = pickLoginCookies(cookiesOf(response));
+    if (!hasLoginCookies(picked)) {
+        throw new Error("登录失败：未获得凭据 Cookie。账号密码可能有误，或当前出口节点被上游拒绝");
+    }
+    const result = {
+        ipbMemberId: picked.ipbMemberId ?? "",
+        ipbPassHash: picked.ipbPassHash ?? "",
+    };
+    if (picked.ipbSessionId !== undefined) {
+        result.ipbSessionId = picked.ipbSessionId;
+    }
+    return result;
+}
+/**
+ * 用凭据 Cookie 访问画廊站以取得 igneous
+ * 外站与里站各试一次：不同出口节点下发的域不同
+ * 里站一次仅作兜底，连不上（代理不放行、节点不稳）不影响整体流程，因此逐个 try：
+ * 两个站点都问不到时返回 null，由调用方决定如何提示
+ */
+export async function fetchIgneous(jar, options = {}) {
+    const cookies = toCookieMap(jar);
+    const targets = [
+        { url: "https://e-hentai.org/", site: "e-hentai" },
+        { url: "https://exhentai.org/", site: "exhentai" },
+    ];
+    for (const target of targets) {
+        let response;
+        try {
+            response = await callApi({
+                url: target.url,
+                site: target.site,
+                cookies,
+                followRedirects: false,
+            });
+        }
+        catch (error) {
+            options.onFailure?.(target.site, error);
+            continue;
+        }
+        const found = cookiesOf(response)["igneous"];
+        if (found !== undefined && isIgneousValue(found)) {
+            return found;
+        }
+    }
+    return null;
+}
+/** 里站是否可访问：未登录或 igneous 无效时会被 302 到 remoteapi */
+export async function probeExAccess(jar) {
+    const response = await callApi({
+        url: "https://exhentai.org/",
+        site: "exhentai",
+        cookies: toCookieMap(jar),
+        followRedirects: false,
+    });
+    if (response.status >= 300 && response.status < 400) {
+        return false;
+    }
+    return response.status === 200 && !response.text.includes("sadpanda");
+}

package/dist/eh/cookies.js

@@ -0,0 +1,65 @@
+/*
+ * Cookie 处理。上游使用 IPB 论坛体系，字段名固定。
+ * 仅在服务端使用；解析结果是纯数据，可直接写入 auth_setting。
+ */
+/** Set-Cookie 逐条解析为键值。只取第一段，忽略 expires / path 等属性 */
+export function parseSetCookie(lines) {
+    const out = {};
+    for (const line of lines) {
+        const first = line.split(";", 1)[0] ?? "";
+        const separator = first.indexOf("=");
+        if (separator <= 0) {
+            continue;
+        }
+        const name = first.slice(0, separator).trim();
+        const value = first.slice(separator + 1).trim();
+        if (name !== "") {
+            out[name] = value;
+        }
+    }
+    return out;
+}
+export function cookiesOf(response) {
+    return parseSetCookie(response.setCookie);
+}
+/** 只保留对接上游需要的字段，session_id、uconfig 之类丢弃 */
+export function pickLoginCookies(cookies) {
+    const picked = {};
+    for (const [source, target] of [
+        ["ipb_member_id", "ipbMemberId"],
+        ["ipb_pass_hash", "ipbPassHash"],
+        ["igneous", "igneous"],
+        ["ipb_session_id", "ipbSessionId"],
+    ]) {
+        const value = cookies[source];
+        if (value !== undefined) {
+            picked[target] = value;
+        }
+    }
+    return picked;
+}
+/** 拿到 member id 与 pass hash 才算登录成功；igneous 可能稍后才下发 */
+export function hasLoginCookies(cookies) {
+    return (cookies.ipbMemberId ?? "") !== "" && (cookies.ipbPassHash ?? "") !== "";
+}
+/** 拼成请求头用的对象，空值不发送 */
+export function toCookieMap(jar) {
+    const map = {};
+    if (jar.ipbMemberId !== undefined && jar.ipbMemberId !== "") {
+        map["ipb_member_id"] = jar.ipbMemberId;
+    }
+    if (jar.ipbPassHash !== undefined && jar.ipbPassHash !== "") {
+        map["ipb_pass_hash"] = jar.ipbPassHash;
+    }
+    if (jar.igneous !== undefined && jar.igneous !== "") {
+        map["igneous"] = jar.igneous;
+    }
+    if (jar.ipbSessionId !== undefined && jar.ipbSessionId !== "") {
+        map["ipb_session_id"] = jar.ipbSessionId;
+    }
+    return map;
+}
+/** igneous 约十几位；旧的 9 位版本已被上游作废，空值与 mystery 均视为无效 */
+export function isIgneousValue(value) {
+    return value !== "" && value !== "mystery" && value.length >= 12;
+}

package/dist/eh/favorites.js

@@ -0,0 +1,94 @@
+/*
+ * 收藏相关接口。
+ * 收藏与取消收藏走 gallerypopups.php 的表单提交：favcat >= 0 放进对应分类，-1 表示取消。
+ * 分类名与数量、分类里的画廊都从 favorites.php 取；需要登录，未登录时上游返回登录页。
+ * 页面解析用宽松匹配：上游结构变化时只会解析不到（界面上表现为空），不会中断整个流程。
+ */
+import { isLoginRequired, LoginRequiredError, callApi } from "./http.js";
+import { siteOrigin } from "./urls.js";
+function requestOf(options, url, body = "") {
+    return {
+        url,
+        method: "POST",
+        site: options.site,
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body,
+        ...(options.cookies === undefined ? {} : { cookies: options.cookies }),
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    };
+}
+function favoritesUrl(site, query = "") {
+    return `${siteOrigin(site)}/favorites.php${query}`;
+}
+/**
+ * 收藏或取消收藏。
+ * 上游返回的是一个 HTML 弹窗；这里只看状态码与是否被重定向到登录页。
+ */
+export async function setFavorite(gid, token, slot, options) {
+    const url = `${siteOrigin(options.site)}/gallerypopups.php?gid=${gid}` +
+        `&t=${encodeURIComponent(token)}&act=addfav`;
+    const body = `favcat=${slot}&favnote=&submit=Apply+Changes`;
+    const response = await callApi(requestOf(options, url, body));
+    if (isLoginRequired(response)) {
+        throw new LoginRequiredError("收藏需要登录后操作");
+    }
+    if (response.status >= 400) {
+        throw new Error(`收藏接口返回 HTTP ${response.status}`);
+    }
+}
+/**
+ * 云端收藏夹的名称与数量。
+ * 默认名是 Favorites 0～9，用户改过名字的按页面上的文字；解析不到时返回空列表。
+ */
+export async function fetchFavoriteCategories(options) {
+    const response = await callApi(requestOf(options, favoritesUrl(options.site)));
+    if (isLoginRequired(response)) {
+        throw new LoginRequiredError("收藏需要登录后操作");
+    }
+    if (response.status >= 400) {
+        return [];
+    }
+    const found = new Map();
+    // 形如 href="?favcat=0">名称</a>  (12)
+    const pattern = /favcat=(\d+)[^>]*>([^<]{0,64})<\/a>[\s\S]{0,80}?\((\d{1,7})\)/g;
+    for (const matched of response.text.matchAll(pattern)) {
+        const slot = Number(matched[1]);
+        const raw = matched[2]?.trim() ?? "";
+        if (!Number.isInteger(slot) || slot < 0 || slot > 9 || found.has(slot)) {
+            continue;
+        }
+        found.set(slot, {
+            slot,
+            name: raw === "" ? `Favorites ${slot}` : raw.replaceAll("&amp;", "&"),
+            count: Number(matched[3]),
+        });
+    }
+    return [...found.values()].sort((a, b) => a.slot - b.slot);
+}
+/**
+ * 某个分类里的画廊。
+ * 只取第一页：收藏页同样分页，这里先返回第一页的内容。
+ */
+export async function fetchFavoriteGalleryPairs(slot, options) {
+    const response = await callApi(requestOf(options, favoritesUrl(options.site, `?favcat=${slot}`)));
+    if (isLoginRequired(response)) {
+        throw new LoginRequiredError("收藏需要登录后操作");
+    }
+    if (response.status >= 400) {
+        return [];
+    }
+    const pairs = [];
+    const seen = new Set();
+    const pattern = /\/g\/(\d+)\/([0-9a-fA-F]{8,})\//g;
+    for (const matched of response.text.matchAll(pattern)) {
+        const gid = Number(matched[1]);
+        const token = matched[2] ?? "";
+        if (!Number.isFinite(gid) || token === "" || seen.has(gid)) {
+            continue;
+        }
+        seen.add(gid);
+        pairs.push([gid, token]);
+    }
+    return pairs;
+}

package/dist/eh/html.js

@@ -0,0 +1,158 @@
+/*
+ * 站点 HTML 解析。上游只提供 api.php 的元数据接口，列表、详情与图片页需自行解析。
+ *
+ * 选择器按 2026-09 的页面结构编写。上游改版时本文件会最先失效，因此解析失败一律返回空值，不抛错。
+ */
+/** 搜索页返回 451 属正常：上游对部分出口 IP 打该状态码但仍给出结果 */
+export function isUsablePage(status) {
+    return status === 200 || status === 451;
+}
+/**
+ * 从缩略图格子的 style 里取出精灵图与偏移
+ * 形如 width:200px;height:300px;background:transparent url(<图>) -200px 0 no-repeat
+ * 旧版上游一页一张图，此时没有偏移，按 0 处理
+ */
+function parseThumbCell(inner) {
+    const url = /url\((['"]?)([^'")]+)\1\)/.exec(inner)?.[2] ?? "";
+    const size = /width:\s*(\d+)px;\s*height:\s*(\d+)px/.exec(inner);
+    // 第二个数值常常省略单位，形如 -200px 0
+    const offset = /\)\s*(-?\d+)px\s+(-?\d+)(?:px)?/.exec(inner);
+    return {
+        thumbUrl: decodeEntities(url),
+        width: size === null ? 0 : Number(size[1]),
+        height: size === null ? 0 : Number(size[2]),
+        offsetX: offset === null ? 0 : Number(offset[1]),
+        offsetY: offset === null ? 0 : Number(offset[2]),
+    };
+}
+export function parseGalleryPage(html, gid) {
+    const tagGroups = new Map();
+    for (const found of html.matchAll(/<a[^>]*id="td_([a-z]+):[^"]*"[^>]*>([^<]*)<\/a>/g)) {
+        const namespace = found[1] ?? "";
+        const name = decodeEntities((found[2] ?? "").trim());
+        if (namespace === "" || name === "") {
+            continue;
+        }
+        const bucket = tagGroups.get(namespace) ?? [];
+        bucket.push(name);
+        tagGroups.set(namespace, bucket);
+    }
+    const previews = [];
+    const pageTokens = new Map();
+    // 缩略图没有 img 标签：一格是一个 200x300 的 div，背景是整张精灵图，通过 offset 定位到自身那一格
+    for (const found of html.matchAll(/<a[^>]*href="https?:\/\/[^"]*\/s\/([0-9a-f]{10})\/(\d+)-(\d+)"[^>]*>([\s\S]{0,600}?)<\/a>/g)) {
+        const token = found[1] ?? "";
+        const hrefGid = Number(found[2]);
+        const page = Number(found[3]);
+        const inner = found[4] ?? "";
+        if (token === "" || !Number.isInteger(page) || hrefGid !== gid) {
+            continue;
+        }
+        const cell = parseThumbCell(inner);
+        if (!pageTokens.has(page)) {
+            pageTokens.set(page, token);
+        }
+        previews.push({ page, ...cell });
+    }
+    const ratingLabel = textOf(html, /<td[^>]*id="rating_label"[^>]*>([\s\S]{0,200}?)<\/td>/);
+    const ratingMatch = /([0-9]+(?:\.[0-9]+)?)/.exec(ratingLabel);
+    return {
+        title: decodeEntities(textOf(html, /<h1[^>]*id="gn"[^>]*>([\s\S]*?)<\/h1>/)),
+        titleJpn: decodeEntities(textOf(html, /<h1[^>]*id="gj"[^>]*>([\s\S]*?)<\/h1>/)),
+        category: decodeEntities(textOf(html, /<div[^>]*id="gdc"[^>]*>[\s\S]{0,200}?<a[^>]*>([^<]+)<\/a>/)),
+        uploader: decodeEntities(textOf(html, /<div[^>]*id="gdn"[^>]*>([\s\S]{0,200}?)<\/div>/).replace(/\s+<a[\s\S]*$/, "")),
+        postedText: textOf(html, /Posted:<\/td>\s*<td[^>]*>([^<]*)</),
+        pageCount: toInteger(textOf(html, /(?:Length|File Count):<\/td>\s*<td[^>]*>([^<]*)</)),
+        sizeText: textOf(html, /File Size:<\/td>\s*<td[^>]*>([^<]*)</),
+        rating: ratingMatch === null ? null : Number(ratingMatch[1]),
+        ratingCount: toInteger(textOf(html, /<span[^>]*id="rating_count"[^>]*>([\s\S]{0,80}?)</)) ?? 0,
+        favoriteCount: toInteger(textOf(html, /<td[^>]*id="favcount"[^>]*>([\s\S]{0,80}?)</)) ?? 0,
+        tagGroups: [...tagGroups].map(([namespace, tags]) => ({ namespace, tags })),
+        previewPages: previews,
+        archiveAvailable: html.includes("archiver.php"),
+        pageTokens,
+    };
+}
+export function parseImagePage(html, gid) {
+    return {
+        showkey: /showkey="([^"]+)"/.exec(html)?.[1] ?? null,
+        previousToken: pageTokenOf(html, "prev", gid),
+        nextToken: pageTokenOf(html, "next", gid),
+    };
+}
+/** 搜索页只取 (gid, token) 对，其余字段由 gdata 补全。结果行的 class 在内层 div 上，故只按 href 匹配 */
+export function parseSearchResults(html) {
+    const out = [];
+    const seen = new Set();
+    for (const found of html.matchAll(/<a[^>]*href="https?:\/\/[^"]*\/g\/(\d+)\/([0-9a-f]{10})\/"/g)) {
+        const gid = Number(found[1]);
+        const token = found[2] ?? "";
+        if (!Number.isInteger(gid) || token === "" || seen.has(gid)) {
+            continue;
+        }
+        seen.add(gid);
+        out.push({ gid, token });
+    }
+    return out;
+}
+export function parseArchiveList(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        return null;
+    }
+    const record = parsed;
+    const list = Array.isArray(record["archives"]) ? record["archives"] : [];
+    const options = [];
+    for (const item of list) {
+        if (item === null || typeof item !== "object") {
+            continue;
+        }
+        const entry = item;
+        const resolution = String(entry["res"] ?? entry["dltype"] ?? "");
+        if (resolution === "") {
+            continue;
+        }
+        options.push({
+            resolution,
+            label: String(entry["name"] ?? resolution),
+            sizeText: String(entry["size"] ?? ""),
+            costText: String(entry["cost"] ?? ""),
+            viaHath: entry["hath"] === true || entry["hathdl_xres"] !== undefined,
+        });
+    }
+    return { options, fundsText: String(record["funds"] ?? "") };
+}
+function pageTokenOf(html, direction, gid) {
+    const pattern = new RegExp(`<a[^>]*id="${direction}"[^>]*href="https?://[^"]*/s/([0-9a-f]{10})/${gid}-\\d+"`);
+    return pattern.exec(html)?.[1] ?? null;
+}
+function textOf(html, pattern) {
+    const found = pattern.exec(html);
+    if (found === null) {
+        return "";
+    }
+    return (found[1] ?? "")
+        .replace(/<[^>]*>/g, "")
+        .replace(/&nbsp;/g, " ")
+        .trim();
+}
+function toInteger(text) {
+    const digits = text.replace(/[^0-9]/g, "");
+    return digits === "" ? null : Number(digits);
+}
+function decodeEntities(text) {
+    return text
+        .replaceAll("&lt;", "<")
+        .replaceAll("&gt;", ">")
+        .replaceAll("&quot;", '"')
+        .replaceAll("&#39;", "'")
+        .replaceAll("&amp;", "&")
+        .replace(/\s+/g, " ")
+        .trim();
+}

package/dist/eh/http.js

@@ -0,0 +1,214 @@
+/*
+ * 上游 HTTP 传输层。负责代理、Cookie 注入、请求头、超时与请求节流。
+ * 仅依赖 undici 与 Node 内置模块，不引用 api / config / services。
+ *
+ * 使用 undici 自带的 fetch 而非全局 fetch：Node 内置的是 undici 7，
+ * 与本项目安装的 undici 8 之间 handler 接口不一致，外部 dispatcher 会被拒绝
+ * （UND_ERR_INVALID_ARG: invalid onRequestStart method）。
+ *
+ * ProxyAgent 只支持 HTTP/HTTPS 代理，SOCKS5 会直接报错。
+ */
+import { ProxyAgent, fetch as undiciFetch } from "undici";
+import { errorCode } from "../platform/errors.js";
+const SITE_ORIGINS = {
+    "e-hentai": "https://e-hentai.org",
+    exhentai: "https://exhentai.org",
+};
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** 连发上限的兜底值：与配置默认值一致，配置未下发时也按「连发 5 次再等」处理 */
+const DEFAULT_BURST_LIMIT = 5;
+let dispatcher = null;
+let minIntervalMs = 0;
+/** 一批里最多连发几次；发满后等待 minIntervalMs 再开始下一批 */
+let burstLimit = DEFAULT_BURST_LIMIT;
+/** 当前这一批已经发了几次 */
+let sentInBurst = 0;
+let lastStartedAt = 0;
+let queue = Promise.resolve();
+/** 设置代理，参数形如 http://127.0.0.1:7897 */
+export function setProxyAgent(server, username, password) {
+    const url = new URL(server);
+    if (url.protocol === "socks5:" || url.protocol === "socks:") {
+        throw new Error(`ProxyAgent 不支持 SOCKS5 代理：${server}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`代理协议不支持：${url.protocol}`);
+    }
+    const options = {
+        uri: `${url.protocol}//${url.host}`,
+    };
+    if (username !== undefined && username !== "") {
+        const credentials = Buffer.from(`${username}:${password ?? ""}`).toString("base64");
+        options.token = `Basic ${credentials}`;
+    }
+    dispatcher = new ProxyAgent(options);
+}
+/** 清除代理，恢复直连 */
+export function clearProxyAgent() {
+    dispatcher = null;
+}
+/** 当前代理通道；未配置代理为 null。归档下载与本模块共用同一条通道 */
+export function getDispatcher() {
+    return dispatcher;
+}
+export function hasProxyAgent() {
+    return dispatcher !== null;
+}
+/**
+ * 设置限流：连续 burst 次请求之后等 intervalMs 再继续，0 间隔表示不限制
+ * 上游建议连续 4～5 次后等待约 5 秒，因此这里限制的是一批之后的那次等待，
+ * 而不是每次请求之间都等。每次请求之间都等时，一次操作要发好几条请求（详情要 gdata + 画廊页），
+ * 多开几个页面就会排成长队
+ */
+export function setRequestInterval(ms, burst = DEFAULT_BURST_LIMIT) {
+    minIntervalMs = Math.max(0, ms);
+    burstLimit = Math.max(1, Math.trunc(burst));
+}
+/** 发起一次上游请求，经串行队列与最小间隔节流 */
+export async function callApi(request) {
+    return schedule(() => send(request));
+}
+/** 同上，并将响应解析为 JSON */
+export async function callApiJson(request) {
+    const response = await callApi(request);
+    try {
+        return JSON.parse(response.text);
+    }
+    catch (error) {
+        throw new Error(`上游返回的不是 JSON（HTTP ${response.status}）：${response.text.slice(0, 200)}`, { cause: error });
+    }
+}
+/** 跳过空值，拼为 Cookie 头 */
+export function buildCookieHeader(cookies) {
+    return Object.entries(cookies)
+        .filter(([, value]) => value !== "")
+        .map(([key, value]) => `${key}=${value}`)
+        .join("; ");
+}
+/** 里站未登录时返回 302 指向 remoteapi，继续跟随会形成重定向循环 */
+export function isExAccessDenied(response) {
+    const location = response.headers["location"] ?? "";
+    if (response.status >= 300 && response.status < 400) {
+        return location.includes("remoteapi.php") || location.includes("?poni=no");
+    }
+    return response.url.includes("?poni=no");
+}
+/** 需要登录的页面（归档、种子直链等）未登录时 302 到登录页，正文亦为登录表单 */
+export function isLoginRequired(response) {
+    const location = response.headers["location"] ?? "";
+    if (response.status >= 300 && response.status < 400) {
+        return /login|bounce/i.test(location);
+    }
+    return /<title>[^<]*Login/i.test(response.text.slice(0, 2048));
+}
+/** 登录态不足导致的失败。服务端据此回 401 语义，而非上游不可达 */
+export class LoginRequiredError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LoginRequiredError";
+    }
+}
+/**
+ * 连接阶段失败的重试次数
+ * 代理节点不稳时常见「TCP 已连接、TLS 握手被重置」，这类失败意味着请求没有送达上游，
+ * 重发是安全的；收到响应之后再出错则不在这里重试
+ */
+const CONNECT_ATTEMPTS = 3;
+const RETRY_DELAY_MS = 800;
+/** 只认「连接未建立」这类失败：域名解析、连接被拒、握手被重置、socket 被关闭 */
+function isConnectFailure(error) {
+    const code = errorCode(error);
+    if (code === "ECONNRESET" ||
+        code === "ECONNREFUSED" ||
+        code === "ENOTFOUND" ||
+        code === "EAI_AGAIN" ||
+        code === "EPIPE" ||
+        code === "UND_ERR_SOCKET") {
+        return true;
+    }
+    const message = error instanceof Error ? error.message : "";
+    return /disconnected before secure TLS|socket hang up|other side closed/i.test(message);
+}
+/** 建连失败时重试；其余错误直接抛出 */
+async function connect(url, init, signal) {
+    let lastError = new Error("请求失败");
+    for (let attempt = 1; attempt <= CONNECT_ATTEMPTS; attempt += 1) {
+        try {
+            return await undiciFetch(url, init);
+        }
+        catch (error) {
+            lastError = error;
+            if (signal?.aborted === true || !isConnectFailure(error)) {
+                throw error;
+            }
+            if (attempt < CONNECT_ATTEMPTS) {
+                await sleep(RETRY_DELAY_MS * attempt);
+            }
+        }
+    }
+    throw lastError;
+}
+async function send(request) {
+    const site = request.site ?? "e-hentai";
+    const headers = {
+        referer: `${SITE_ORIGINS[site]}/`,
+        origin: SITE_ORIGINS[site],
+        ...request.headers,
+    };
+    if (request.cookies !== undefined) {
+        headers["cookie"] = buildCookieHeader(request.cookies);
+    }
+    if (request.body !== undefined && headers["content-type"] === undefined) {
+        headers["content-type"] = "application/json";
+    }
+    const response = await connect(request.url, {
+        method: request.method ?? "GET",
+        headers,
+        body: request.body,
+        redirect: request.followRedirects === true ? "follow" : "manual",
+        signal: combineSignals(request.signal, request.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        dispatcher: dispatcher ?? undefined,
+    }, request.signal);
+    return {
+        status: response.status,
+        url: response.url,
+        headers: Object.fromEntries(response.headers),
+        setCookie: response.headers.getSetCookie(),
+        text: await response.text(),
+    };
+}
+/** 取消信号与超时信号合取。无取消信号时只保留超时 */
+function combineSignals(signal, timeoutMs) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    if (signal === undefined) {
+        return timeout;
+    }
+    return AbortSignal.any([signal, timeout]);
+}
+/**
+ * 串行队列与连发上限。上游的限流建议是「连续 4～5 次后等待约 5 秒」，
+ * 因此不是每次请求之间都等一个间隔：先连发最多 maxSequentialRequests 次，发完这批再等 requestIntervalMs。
+ * 等待从「上一批最后一次开始」算起，队列空闲一段时间之后自然不再等待
+ */
+function schedule(task) {
+    const run = async () => {
+        if (sentInBurst >= burstLimit) {
+            const wait = minIntervalMs - (Date.now() - lastStartedAt);
+            if (wait > 0) {
+                await sleep(wait);
+            }
+            sentInBurst = 0;
+        }
+        lastStartedAt = Date.now();
+        sentInBurst += 1;
+        return task();
+    };
+    const next = queue.then(run, run);
+    queue = next.then(() => undefined, () => undefined);
+    return next;
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/eh/index.js

@@ -0,0 +1,13 @@
+/*
+ * 上游客户端。
+ * http.ts 为传输层，api.ts 为接口封装，types.ts 为上游结构。
+ */
+export * from "./http.js";
+export * from "./api.js";
+export * from "./urls.js";
+export * from "./html.js";
+export * from "./cookies.js";
+export * from "./auth.js";
+export * from "./archives.js";
+export * from "./favorites.js";
+export { MAX_ENTRIES_PER_REQUEST, UPSTREAM_API } from "./types.js";

package/dist/eh/types.js

@@ -0,0 +1,11 @@
+/*
+ * 上游接口返回的原始结构。字段名与上游一致，归一化由服务层完成
+ * 上游常把数字以字符串返回（posted、filecount、rating），此处保留原始类型
+ */
+/** 接口地址：外站在 api 子域，里站在 s 子域 */
+export const UPSTREAM_API = {
+    "e-hentai": "https://api.e-hentai.org/api.php",
+    exhentai: "https://s.exhentai.org/api.php",
+};
+/** 单次请求的条目上限，两个接口一致 */
+export const MAX_ENTRIES_PER_REQUEST = 25;