dsh-ab-wechat-scrape 0.4.0

package/lib/document.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The Markdown record one article becomes: the file that is written and the text
+ * the model reads.
+ *
+ * They are **not** the same text. The file holds the whole body; the model reads a
+ * bounded head of it plus the path, because a call that carried whole articles
+ * would pay their full length in context and the session log would carry it too.
+ * Both render the same facts, so a saved article and the call that produced it
+ * never disagree about what was retrieved.
+ * @module @deepseek-ai/dsh-ab-wechat-scrape/document
+ */
+import type { DraftedArticle, WechatArticle } from './types.ts';
+/**
+ * Render the Markdown file one article is saved as. This is the complete record:
+ * the whole body, never a window of it.
+ * @param article - the article as it was built, body included.
+ * @returns YAML front matter, the full body, and the image list.
+ */
+export declare function articleDocument(article: DraftedArticle): string;
+/**
+ * Render the model-facing text of one saved article: the facts, a head of the
+ * body, how long the body is, and where the whole of it lives.
+ * @param article - the article's canonical value, saved path included.
+ * @returns the article facts, the excerpt, the body's length, and the saved path.
+ */
+export declare function renderArticle(article: WechatArticle): string;
+//# sourceMappingURL=document.d.ts.map

package/lib/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAoB,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAgCjF;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAc/D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAU5D"}

package/lib/document.js

@@ -0,0 +1,79 @@
+/**
+ * The Markdown record one article becomes: the file that is written and the text
+ * the model reads.
+ *
+ * They are **not** the same text. The file holds the whole body; the model reads a
+ * bounded head of it plus the path, because a call that carried whole articles
+ * would pay their full length in context and the session log would carry it too.
+ * Both render the same facts, so a saved article and the call that produced it
+ * never disagree about what was retrieved.
+ * @module @deepseek-ai/dsh-ab-wechat-scrape/document
+ */
+/** Quote one value as a YAML double-quoted scalar, which is a JSON string. */
+function yamlString(value) {
+    return JSON.stringify(value);
+}
+/**
+ * The facts shared by the saved file and the model-facing text.
+ * @param article - the article's canonical value.
+ * @param body - the text to place in the body position.
+ * @returns the heading, the metadata line, and the body.
+ */
+function articleLines(article, body) {
+    const meta = [];
+    if (article.account !== '')
+        meta.push('公众号：' + article.account);
+    if (article.author !== '')
+        meta.push('作者：' + article.author);
+    if (article.publishTime !== '')
+        meta.push('发布：' + article.publishTime);
+    meta.push('链接：' + article.resolvedUrl);
+    const lines = [
+        '# ' + (article.title === '' ? '(无标题)' : article.title),
+        '',
+        meta.join(' | '),
+        '',
+        body,
+    ];
+    if (article.images.length > 0) {
+        lines.push('', '## 图片', ...article.images.map((src, index) => String(index + 1) + '. ' + src));
+    }
+    return lines;
+}
+/**
+ * Render the Markdown file one article is saved as. This is the complete record:
+ * the whole body, never a window of it.
+ * @param article - the article as it was built, body included.
+ * @returns YAML front matter, the full body, and the image list.
+ */
+export function articleDocument(article) {
+    return [
+        '---',
+        'title: ' + yamlString(article.title),
+        'account: ' + yamlString(article.account),
+        'author: ' + yamlString(article.author),
+        'publishTime: ' + yamlString(article.publishTime),
+        'source: ' + yamlString(article.resolvedUrl),
+        'cover: ' + yamlString(article.cover),
+        'chars: ' + String(article.chars),
+        'rendered: ' + String(article.rendered),
+        '---',
+        ...articleLines(article, article.body),
+    ].join('\n');
+}
+/**
+ * Render the model-facing text of one saved article: the facts, a head of the
+ * body, how long the body is, and where the whole of it lives.
+ * @param article - the article's canonical value, saved path included.
+ * @returns the article facts, the excerpt, the body's length, and the saved path.
+ */
+export function renderArticle(article) {
+    const lines = articleLines(article, article.excerpt);
+    lines.push('');
+    lines.push(article.excerptClipped
+        ? `（以上为节选，正文共 ${String(article.chars)} 字；完整内容见文件）`
+        : `（正文共 ${String(article.chars)} 字）`);
+    lines.push('文件：' + article.file);
+    return lines.join('\n');
+}
+//# sourceMappingURL=document.js.map

package/lib/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,8EAA8E;AAC9E,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;AAC9B,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,OAAyB,EAAE,IAAY;IAC3D,MAAM,IAAI,GAAa,EAAE,CAAA;IACzB,IAAI,OAAO,CAAC,OAAO,KAAK,EAAE;QAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC/D,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE;QAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC5D,IAAI,OAAO,CAAC,WAAW,KAAK,EAAE;QAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IACtE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IACtC,MAAM,KAAK,GAAG;QACZ,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;QACvD,EAAE;QACF,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;QAChB,EAAE;QACF,IAAI;KACL,CAAA;IACD,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC,CAAA;IAChG,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAuB;IACrD,OAAO;QACL,KAAK;QACL,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC;QACrC,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC;QACzC,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC;QACvC,eAAe,GAAG,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC;QACjD,UAAU,GAAG,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC;QAC5C,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC;QACrC,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;QACjC,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC;QACvC,KAAK;QACL,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC;KACvC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAAsB;IAClD,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;IACpD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,KAAK,CAAC,IAAI,CACR,OAAO,CAAC,cAAc;QACpB,CAAC,CAAC,cAAc,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa;QAClD,CAAC,CAAC,QAAQ,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CACvC,CAAA;IACD,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC"}

package/lib/fetch.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The plugin's HTTP layer: browser-like request headers, a session cookie jar,
+ * a minimum interval between requests, a cool-down a refused request imposes on
+ * the rest of the instance, bounded retries that honour the server's own retry
+ * hint, and the deployment's timeout. Kept separate from page parsing, and
+ * driven through injected transport and clock ports so tests never sleep or
+ * reach the network.
+ * @module @deepseek-ai/dsh-ab-wechat-scrape/fetch
+ */
+/** Deployment values the request layer reads. */
+export interface FetchPolicy {
+    /** User agent every request sends. */
+    userAgent: string;
+    /** Referer every request sends; omitted when empty. */
+    referer: string;
+    /** Cookie header every request sends; omitted when empty. */
+    cookie: string;
+    /** Whether cookies a response sets are replayed for the rest of the instance. */
+    cookieJar: boolean;
+    /** Minimum milliseconds between two requests from this plugin instance. */
+    minIntervalMs: number;
+    /** Random milliseconds added to each wait, so the cadence is not a fixed period. */
+    minIntervalJitterMs: number;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs: number;
+    /** Retries after the first attempt. */
+    maxRetries: number;
+    /** Base delay of the exponential backoff, in milliseconds. */
+    backoffBaseMs: number;
+    /** Longest wait a server-supplied retry hint may impose, in milliseconds. */
+    maxRetryAfterMs: number;
+}
+/** One HTML response the caller parses. */
+export interface HtmlResponse {
+    /** Final URL after redirects. */
+    url: string;
+    /** HTTP status of the final response. */
+    status: number;
+    /** Response body text. */
+    body: string;
+    /** `Set-Cookie` header values the response carried, in the order it sent them. */
+    setCookie: readonly string[];
+}
+/** Injected transport, clock, and jitter source. */
+export interface FetchDeps {
+    /** Transport used for one attempt. */
+    fetchImpl: typeof fetch;
+    /** Sleep used between attempts. */
+    sleep: (ms: number) => Promise<void>;
+    /** Clock in milliseconds. */
+    now: () => number;
+    /** Random source in [0, 1) used to jitter the backoff. */
+    random: () => number;
+}
+/** The request entry point one plugin instance owns. */
+export interface Fetcher {
+    /**
+     * Retrieve one page, pacing and retrying per the deployment policy.
+     * @param url - the page to retrieve.
+     * @param signal - caller cancellation.
+     * @returns the final response, including non-2xx statuses the caller inspects.
+     */
+    get(url: string, signal?: AbortSignal): Promise<HtmlResponse>;
+    /**
+     * Wait until the deployment's minimum interval has elapsed.
+     * @param signal - caller cancellation.
+     * @returns a promise that settles once a request may start.
+     */
+    pace(signal?: AbortSignal): Promise<void>;
+    /**
+     * Hold every later request back by one cool-down, because a page WeChat
+     * refused says the instance is already asking too fast.
+     * @param ms - milliseconds the instance stands down for.
+     */
+    coolDown(ms: number): void;
+}
+/**
+ * Build the plugin instance's fetcher.
+ * @param policy - the deployment's header, pacing, retry, and timeout values.
+ * @param overrides - test ports replacing the default transport, clock, or jitter.
+ * @returns the fetcher whose pace() the browser renderer shares.
+ */
+export declare function createFetcher(policy: FetchPolicy, overrides?: Partial<FetchDeps>): Fetcher;
+//# sourceMappingURL=fetch.d.ts.map

package/lib/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAA;IACf,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAA;IACd,iFAAiF;IACjF,SAAS,EAAE,OAAO,CAAA;IAClB,2EAA2E;IAC3E,aAAa,EAAE,MAAM,CAAA;IACrB,oFAAoF;IACpF,mBAAmB,EAAE,MAAM,CAAA;IAC3B,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAA;IACjB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,eAAe,EAAE,MAAM,CAAA;CACxB;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAA;IACd,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7B;AAED,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,sCAAsC;IACtC,SAAS,EAAE,OAAO,KAAK,CAAA;IACvB,mCAAmC;IACnC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpC,6BAA6B;IAC7B,GAAG,EAAE,MAAM,MAAM,CAAA;IACjB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,MAAM,CAAA;CACrB;AAED,wDAAwD;AACxD,MAAM,WAAW,OAAO;IACtB;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAC7D;;;;OAIG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B;AA2JD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,OAAO,CA4E9F"}

package/lib/fetch.js

@@ -0,0 +1,238 @@
+/**
+ * The plugin's HTTP layer: browser-like request headers, a session cookie jar,
+ * a minimum interval between requests, a cool-down a refused request imposes on
+ * the rest of the instance, bounded retries that honour the server's own retry
+ * hint, and the deployment's timeout. Kept separate from page parsing, and
+ * driven through injected transport and clock ports so tests never sleep or
+ * reach the network.
+ * @module @deepseek-ai/dsh-ab-wechat-scrape/fetch
+ */
+/** Statuses worth another attempt: rate limits and server-side failures. */
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+/**
+ * Headers a browser sends when navigating to a page. The client hints are
+ * deliberately absent: they must agree with the configured user agent, and a
+ * mismatch is a stronger signal than their absence. `sec-fetch-site` is absent
+ * too, because it describes the navigation the request belongs to and is set
+ * per request.
+ */
+const NAVIGATION_HEADERS = {
+    accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+    'accept-language': 'zh-CN,zh;q=0.9,en;q=0.8',
+    'cache-control': 'max-age=0',
+    'sec-fetch-dest': 'document',
+    'sec-fetch-mode': 'navigate',
+    'sec-fetch-user': '?1',
+    'upgrade-insecure-requests': '1',
+};
+/** `sec-fetch-site` for the instance's first navigation, which no page referred. */
+const FIRST_NAVIGATION_SITE = 'none';
+/** `sec-fetch-site` for every navigation after the first, which a fetched page referred. */
+const REFERRED_NAVIGATION_SITE = 'same-origin';
+const DEFAULT_DEPS = {
+    fetchImpl: fetch,
+    sleep: (ms) => new Promise(resolve => { setTimeout(resolve, ms); }),
+    now: () => Date.now(),
+    random: () => Math.random(),
+};
+/** Whether the caller already cancelled; a function call keeps TS from narrowing the flag. */
+function cancelled(signal) {
+    return signal !== undefined && signal.aborted;
+}
+/** A cancellation error the caller can distinguish from a failed request. */
+function abortError() {
+    const error = new Error('wechat: the call was cancelled');
+    error.name = 'AbortError';
+    return error;
+}
+/** Milliseconds to wait before one retry, jittered so parallel callers do not sync. */
+function backoffDelay(base, attempt, random) {
+    return Math.round(base * 2 ** attempt * (0.5 + random()));
+}
+/**
+ * Milliseconds to wait before the next attempt. A usable server hint wins,
+ * capped by the deployment, because it is the rate the server is willing to
+ * serve; otherwise the jittered backoff applies.
+ */
+function retryDelay(policy, attempt, retryAfterMs, random) {
+    if (retryAfterMs > 0)
+        return Math.min(retryAfterMs, policy.maxRetryAfterMs);
+    return backoffDelay(policy.backoffBaseMs, attempt, random);
+}
+/**
+ * Read a Retry-After header, in either of its two legal forms.
+ * @param value - the header value, or null when the response carried none.
+ * @param now - current time in milliseconds, for the HTTP-date form.
+ * @returns milliseconds to wait, or 0 when the header is absent or unusable.
+ */
+function parseRetryAfter(value, now) {
+    if (value === null || value.trim() === '')
+        return 0;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.round(seconds * 1000);
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? 0 : Math.max(0, date - now);
+}
+/**
+ * Every `Set-Cookie` value one response carried. `Headers.getSetCookie` is the
+ * only accessor that returns more than one; a runtime without it yields the
+ * single folded header, which is still better than dropping the cookies.
+ * @param headers - the response headers.
+ * @returns the header values, in the order the server sent them.
+ */
+function setCookieValues(headers) {
+    const multi = headers.getSetCookie;
+    if (typeof multi === 'function')
+        return multi.call(headers);
+    const single = headers.get('set-cookie');
+    return single === null ? [] : [single];
+}
+/**
+ * Read the name and value out of one `Set-Cookie` value, ignoring its
+ * attributes. A deletion (`Max-Age=0`) is read like any other; the server's own
+ * later value replaces it, so a stale entry cannot outlive the response that
+ * removed it on any page the walk reaches afterwards.
+ * @param value - one `Set-Cookie` header value.
+ * @returns the cookie pair, or undefined when the value carries no `name=value`.
+ */
+function cookiePair(value) {
+    const pair = value.split(';', 1)[0]?.trim() ?? '';
+    const equals = pair.indexOf('=');
+    if (equals <= 0)
+        return undefined;
+    return [pair.slice(0, equals).trim(), pair.slice(equals + 1).trim()];
+}
+/**
+ * The cookie header one request sends: the deployment's own cookies first, in
+ * the order it wrote them, then every cookie this instance has been given that
+ * the deployment's header does not already name.
+ * @param configured - the cookies parsed from the deployment's header.
+ * @param jar - cookies harvested from earlier responses, keyed by name.
+ * @returns the header value, or an empty string when no cookie is held.
+ */
+function cookieHeader(configured, jar) {
+    const named = new Set(configured.map(pair => pair[0]));
+    const parts = configured.map(pair => pair[0] + '=' + pair[1]);
+    for (const [name, value] of jar) {
+        if (!named.has(name))
+            parts.push(name + '=' + value);
+    }
+    return parts.join('; ');
+}
+/**
+ * Parse a Cookie header into ordered pairs.
+ * @param header - the deployment's Cookie header.
+ * @returns one pair per non-empty entry it carries.
+ */
+function configuredCookies(header) {
+    if (header.trim() === '')
+        return [];
+    const pairs = [];
+    for (const part of header.split(';')) {
+        const pair = cookiePair(part);
+        if (pair !== undefined)
+            pairs.push(pair);
+    }
+    return pairs;
+}
+/** Sleep that settles early when the caller cancels. */
+function sleepWithSignal(ms, sleep, signal) {
+    if (signal === undefined)
+        return sleep(ms);
+    if (signal.aborted)
+        return Promise.reject(abortError());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => { reject(abortError()); };
+        signal.addEventListener('abort', onAbort, { once: true });
+        sleep(ms).then(() => { signal.removeEventListener('abort', onAbort); resolve(); }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
+    });
+}
+/**
+ * Build the plugin instance's fetcher.
+ * @param policy - the deployment's header, pacing, retry, and timeout values.
+ * @param overrides - test ports replacing the default transport, clock, or jitter.
+ * @returns the fetcher whose pace() the browser renderer shares.
+ */
+export function createFetcher(policy, overrides = {}) {
+    const deps = { ...DEFAULT_DEPS, ...overrides };
+    const configured = configuredCookies(policy.cookie);
+    const jar = new Map();
+    let lastRequestAt = Number.NEGATIVE_INFINITY;
+    let resumeAt = Number.NEGATIVE_INFINITY;
+    let navigations = 0;
+    const pace = async (signal) => {
+        // The jitter is re-drawn for every wait, so a batch is not a fixed-period
+        // request train the way a constant interval would be.
+        const jitter = policy.minIntervalJitterMs > 0 ? Math.round(deps.random() * policy.minIntervalJitterMs) : 0;
+        const earliest = Math.max(lastRequestAt + policy.minIntervalMs + jitter, resumeAt);
+        const wait = earliest - deps.now();
+        if (wait > 0)
+            await sleepWithSignal(wait, deps.sleep, signal);
+        lastRequestAt = deps.now();
+    };
+    const coolDown = (ms) => {
+        if (ms > 0)
+            resumeAt = Math.max(resumeAt, deps.now() + ms);
+    };
+    const once = async (url, signal) => {
+        const timeout = AbortSignal.timeout(policy.timeoutMs);
+        const combined = signal === undefined ? timeout : AbortSignal.any([signal, timeout]);
+        const headers = {
+            ...NAVIGATION_HEADERS,
+            'user-agent': policy.userAgent,
+            // A browser sends the first navigation of a tab unreferred and every
+            // navigation after it as coming from the page it was already on.
+            'sec-fetch-site': navigations === 0 ? FIRST_NAVIGATION_SITE : REFERRED_NAVIGATION_SITE,
+        };
+        navigations += 1;
+        if (policy.referer !== '')
+            headers.referer = policy.referer;
+        const cookie = policy.cookieJar ? cookieHeader(configured, jar) : policy.cookie;
+        if (cookie !== '')
+            headers.cookie = cookie;
+        const response = await deps.fetchImpl(url, { headers, redirect: 'follow', signal: combined });
+        const setCookie = setCookieValues(response.headers);
+        if (policy.cookieJar) {
+            for (const value of setCookie) {
+                const pair = cookiePair(value);
+                if (pair !== undefined)
+                    jar.set(pair[0], pair[1]);
+            }
+        }
+        const body = await response.text();
+        return {
+            response: { url: response.url === '' ? url : response.url, status: response.status, body, setCookie },
+            retryAfterMs: parseRetryAfter(response.headers.get('retry-after'), deps.now()),
+        };
+    };
+    const get = async (url, signal) => {
+        if (cancelled(signal))
+            throw abortError();
+        let lastError;
+        let delayMs = 0;
+        for (let attempt = 0; attempt <= policy.maxRetries; attempt += 1) {
+            if (attempt > 0)
+                await sleepWithSignal(delayMs, deps.sleep, signal);
+            await pace(signal);
+            try {
+                const { response, retryAfterMs } = await once(url, signal);
+                if (RETRYABLE_STATUS.has(response.status) && attempt < policy.maxRetries) {
+                    lastError = new Error('wechat: HTTP ' + response.status + ' from ' + url);
+                    delayMs = retryDelay(policy, attempt, retryAfterMs, deps.random);
+                    continue;
+                }
+                return response;
+            }
+            catch (error) {
+                if (cancelled(signal))
+                    throw error;
+                lastError = error;
+                delayMs = backoffDelay(policy.backoffBaseMs, attempt, deps.random);
+            }
+        }
+        throw lastError instanceof Error ? lastError : new Error('wechat: the request to ' + url + ' failed');
+    };
+    return { get, pace, coolDown };
+}
+//# sourceMappingURL=fetch.js.map

package/lib/fetch.js.map

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

package/lib/filename.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Article-title to file-name normalization. A title arrives with path
+ * separators, characters Windows rejects, C0/C1 controls, invisible formatting
+ * characters, device names, and unbounded length, so every article passes
+ * through this module before its file is created.
+ * @module @deepseek-ai/dsh-ab-wechat-scrape/filename
+ */
+/** Extension every saved article carries. */
+export declare const FILE_EXTENSION = ".md";
+/** Base name used when neither the title nor the link yields anything usable. */
+export declare const UNTITLED = "untitled";
+/**
+ * Fold one article title into a file-name base: Unicode-normalized, with the
+ * characters no file system accepts replaced, and whitespace, separators, and
+ * edge noise collapsed.
+ * @param title - the article title as the page carried it.
+ * @returns the normalized base, or an empty string when nothing survives.
+ */
+export declare function normalizeTitle(title: string): string;
+/**
+ * A stable name for an article whose title yielded none, taken from its own
+ * link: the message identity is what makes two untitled articles different, and
+ * a name derived from it separates them without a collision suffix.
+ * @param source - the article's resolved link.
+ * @returns the normalized stem, or an empty string when the link names no identity.
+ */
+export declare function linkStem(source: string): string;
+/**
+ * Build the file name one article is saved under.
+ * @param title - the article title as the page carried it.
+ * @param maxChars - longest base name, in code points, the deployment allows.
+ * @param source - the article's resolved link, used when the title yields no name.
+ * @returns a base name carrying {@link FILE_EXTENSION}, creatable on Windows and POSIX.
+ */
+export declare function articleFileName(title: string, maxChars: number, source?: string): string;
+//# sourceMappingURL=filename.d.ts.map

package/lib/filename.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filename.d.ts","sourceRoot":"","sources":["../src/filename.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,6CAA6C;AAC7C,eAAO,MAAM,cAAc,QAAQ,CAAA;AAEnC,iFAAiF;AACjF,eAAO,MAAM,QAAQ,aAAa,CAAA;AAsBlC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQpD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAa/C;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,MAAM,CAKpF"}

package/lib/filename.js

@@ -0,0 +1,92 @@
+/**
+ * Article-title to file-name normalization. A title arrives with path
+ * separators, characters Windows rejects, C0/C1 controls, invisible formatting
+ * characters, device names, and unbounded length, so every article passes
+ * through this module before its file is created.
+ * @module @deepseek-ai/dsh-ab-wechat-scrape/filename
+ */
+/** Extension every saved article carries. */
+export const FILE_EXTENSION = '.md';
+/** Base name used when neither the title nor the link yields anything usable. */
+export const UNTITLED = 'untitled';
+/** Characters no file name may carry: Windows' reserved set, the POSIX separator, and controls. */
+const ILLEGAL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/g;
+/**
+ * Characters a file name may carry but a reader cannot see: zero-width spaces,
+ * bidirectional overrides, word joiners, and the byte-order mark. WeChat titles
+ * are full of them, and a name made only of them looks empty in a directory
+ * listing while still being a distinct file.
+ */
+const INVISIBLE_CHARACTERS = /[\u200b-\u200f\u202a-\u202e\u2060-\u2064\u206a-\u206f\ufeff]/g;
+/** Device names Windows reserves in every directory, with or without an extension. */
+const RESERVED_DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+/** Leading and trailing characters a file name may not carry on Windows. */
+const EDGE_NOISE = /^[\s.\-]+|[\s.\-]+$/g;
+/** Message identity a short link carries in its path, e.g. `/s/AbCdEf123`. */
+const SHORT_LINK_PATH = /^\/s\/([^/?#]+)$/;
+/**
+ * Fold one article title into a file-name base: Unicode-normalized, with the
+ * characters no file system accepts replaced, and whitespace, separators, and
+ * edge noise collapsed.
+ * @param title - the article title as the page carried it.
+ * @returns the normalized base, or an empty string when nothing survives.
+ */
+export function normalizeTitle(title) {
+    return title
+        .normalize('NFC')
+        .replace(INVISIBLE_CHARACTERS, '')
+        .replace(ILLEGAL_CHARACTERS, '-')
+        .replace(/\s+/g, ' ')
+        .replace(/-{2,}/g, '-')
+        .replace(EDGE_NOISE, '');
+}
+/**
+ * A stable name for an article whose title yielded none, taken from its own
+ * link: the message identity is what makes two untitled articles different, and
+ * a name derived from it separates them without a collision suffix.
+ * @param source - the article's resolved link.
+ * @returns the normalized stem, or an empty string when the link names no identity.
+ */
+export function linkStem(source) {
+    let parsed;
+    try {
+        parsed = new URL(source);
+    }
+    catch {
+        // A link that cannot be parsed names no identity to derive a stem from.
+        return '';
+    }
+    const short = SHORT_LINK_PATH.exec(parsed.pathname);
+    const identity = short?.[1]
+        ?? parsed.searchParams.get('sn')
+        ?? [parsed.searchParams.get('mid'), parsed.searchParams.get('idx')].filter(part => part !== null).join('-');
+    return identity === undefined || identity === '' ? '' : normalizeTitle(identity);
+}
+/**
+ * Build the file name one article is saved under.
+ * @param title - the article title as the page carried it.
+ * @param maxChars - longest base name, in code points, the deployment allows.
+ * @param source - the article's resolved link, used when the title yields no name.
+ * @returns a base name carrying {@link FILE_EXTENSION}, creatable on Windows and POSIX.
+ */
+export function articleFileName(title, maxChars, source = '') {
+    const normalized = normalizeTitle(title);
+    if (normalized !== '')
+        return finish(normalized, maxChars);
+    const stem = linkStem(source);
+    return finish(stem === '' ? UNTITLED : stem, maxChars);
+}
+/** Clip one base name and escape the device names Windows reserves. */
+function finish(base, maxChars) {
+    const clipped = clip(base, maxChars);
+    return (RESERVED_DEVICE_NAME.test(clipped) ? '_' + clipped : clipped) + FILE_EXTENSION;
+}
+/** Cut a base name to the ceiling without leaving edge noise or an empty name behind. */
+function clip(base, maxChars) {
+    const characters = [...base];
+    if (characters.length <= maxChars)
+        return base;
+    const cut = characters.slice(0, maxChars).join('').replace(EDGE_NOISE, '');
+    return cut === '' ? UNTITLED : cut;
+}
+//# sourceMappingURL=filename.js.map

package/lib/filename.js.map

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