@khorsheed/dsh-reader 0.3.0 → 0.3.2

package/lib/types/types.d.ts

@@ -15,6 +15,8 @@
  *
  * @module @khorsheed/dsh-reader/types
  */
+import type { ReaderMedia } from './media.ts';
+export type { ReaderMedia } from './media.ts';
 /** What a source is: a syndication feed, or one manually saved article link. */
 export type ReaderSourceKind = 'rss' | 'link';
 /** Fetch state of one source's most recent attempt. */
@@ -95,8 +97,9 @@ export interface ReaderSource {
     /** Human-readable failure of the last attempt, when `status` is `error`. */
     readonly error?: string;
     /**
-     * True when the host's fetch seam cut the payload at its size limit
-     * (`maxBodyChars`, 100 000 by default). A truncated XML document cannot be
+     * True when the fetch cut the payload at its size limit (`maxBodyChars`:
+     * the reader's own 2 000 000, or the seam's limit where the reader fetches
+     * through it). A truncated XML document cannot be
      * parsed and a truncated HTML page yields a partial article, so every
      * consumer treats this as "incomplete" and says so rather than guessing.
      */
@@ -415,6 +418,11 @@ export interface ReaderEntry {
      * text is real but stops where the cap landed. The detail view says so.
      */
     readonly partial?: boolean;
+    /**
+     * The video or audio this entry plays, decided per ITEM (media.ts): a feed
+     * enclosure, a recognized video link, or a saved link's synthetic page.
+     */
+    readonly media?: ReaderMedia;
 }
 /** One source as the browser sees it (no payload: bodies are fetched on demand). */
 export interface ReaderSourceSummary {
@@ -567,6 +575,38 @@ export declare const MAX_TOTAL_BODY_CHARS: number;
  * governs it exactly like an inline body, and eviction deletes the file.
  */
 export declare const INLINE_BODY_MAX_CHARS: number;
+/**
+ * Hosts that bounce every first visit through a cookie handshake, not a login.
+ *
+ * Springer Nature answers a cookie-less request with a 303 to
+ * `idp.<brand>/authorize?response_type=cookie`, which mints a one-time code and
+ * sends the browser back to the article (measured 2026-10-04 on
+ * link.springer.com and www.nature.com). The host fetch does not follow the
+ * cross-origin hop and keeps no cookies, so the plain fetch can never finish
+ * it; a headless browser does (the rendered fetch read the full EPJ Data
+ * Science article). The `idp` name alone would read as a login wall.
+ */
+export declare const COOKIE_HANDSHAKE_HOSTS: ReadonlySet<string>;
+/**
+ * Whether a fetch failure is a cross-origin hop into a known cookie handshake.
+ *
+ * @param message - the seam's recorded failure message.
+ * @returns true when the failure is the handshake, which a browser completes.
+ */
+export declare function isCookieHandshake(message: string): boolean;
+/**
+ * The article a challenge page stands in front of, when its URL names it.
+ *
+ * A bot wall usually redirects to its own page and carries the original in a
+ * query parameter (mp.weixin.qq.com → `/mp/wappoc_appmsgcaptcha?…&target_url=`).
+ * Builds before 2026-10-04 saved that landing URL as the link itself, which
+ * then titled the card and was what every retry — the rendered fetch included
+ * — asked for; the state normalizer walks such a link back with this.
+ *
+ * @param url - a stored link.
+ * @returns the http(s) target, or `undefined` when the URL is not a challenge landing.
+ */
+export declare function challengeTarget(url: string): string | undefined;
 /**
  * Build a display label for a source from its URL: the registrable-ish host
  * plus the last meaningful path segment, which is what distinguishes several
@@ -726,4 +766,52 @@ export interface ReaderImageResult {
     /** Why the rescue failed, when it did. */
     readonly error?: string;
 }
+export type * from './notes-types.ts';
+/** An article's 润色 layer as the browser shows it. */
+export interface ReaderPolishView {
+    /** Paragraphs in the article (the ¶ numbering the model read). */
+    readonly total: number;
+    readonly done: number;
+    /** ¶ number (1-based, as a string key) → the agent's translation. */
+    readonly paragraphs: Readonly<Record<string, string>>;
+    /** Paragraphs the reader turned back to the machine translation. */
+    readonly off: readonly number[];
+    readonly updatedAt: string;
+    readonly complete: boolean;
+}
+/** What a video / audio card says about its transcript. */
+export type MediaCardState = 'platform' | 'local' | 'none' | 'fetching' | 'queued' | 'transcribing' | 'failed';
+/** One media card's transcript state (absent: never opened, nothing known). */
+export interface MediaCardStatus {
+    readonly state: MediaCardState;
+    /** 0–1, while transcribing. */
+    readonly progress?: number;
+    /** Jobs ahead in the engine's queue, while queued. */
+    readonly ahead?: number;
+}
+/** The wall's media cards, plus whether local transcription is installed. */
+export interface MediaCardStates {
+    readonly engine: boolean;
+    readonly states: Readonly<Record<string, MediaCardStatus>>;
+}
+/** Where an entry's local transcription stands. */
+export type LocalTranscriptState = 'unavailable' | 'needs-models' | 'fetching' | 'queued' | 'transcribing' | 'speakers' | 'done' | 'failed' | 'idle';
+/** What the browser polls. */
+export interface LocalTranscriptStatus {
+    readonly entryId: string;
+    readonly state: LocalTranscriptState;
+    /** 0–1 across fetching the audio and transcribing it. */
+    readonly progress?: number;
+    /** Jobs ahead in the engine's queue. */
+    readonly ahead?: number;
+    /** Bytes of speech models still to download (`needs-models`). */
+    readonly bytes?: number;
+    /** The transcript so far (or in full, once `done`). */
+    readonly html?: string;
+    /** The language the transcript is in, once known. */
+    readonly language?: string;
+    /** How many voices the transcript has, once the speakers pass settled it. */
+    readonly speakers?: number;
+    readonly error?: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -79,6 +79,72 @@ export const MAX_TOTAL_BODY_CHARS = 12 * 1024 * 1024;
  * governs it exactly like an inline body, and eviction deletes the file.
  */
 export const INLINE_BODY_MAX_CHARS = 256 * 1024;
+/**
+ * Hosts that bounce every first visit through a cookie handshake, not a login.
+ *
+ * Springer Nature answers a cookie-less request with a 303 to
+ * `idp.<brand>/authorize?response_type=cookie`, which mints a one-time code and
+ * sends the browser back to the article (measured 2026-10-04 on
+ * link.springer.com and www.nature.com). The host fetch does not follow the
+ * cross-origin hop and keeps no cookies, so the plain fetch can never finish
+ * it; a headless browser does (the rendered fetch read the full EPJ Data
+ * Science article). The `idp` name alone would read as a login wall.
+ */
+export const COOKIE_HANDSHAKE_HOSTS = new Set(['idp.springer.com', 'idp.nature.com']);
+/**
+ * Whether a fetch failure is a cross-origin hop into a known cookie handshake.
+ *
+ * @param message - the seam's recorded failure message.
+ * @returns true when the failure is the handshake, which a browser completes.
+ */
+export function isCookieHandshake(message) {
+    const origin = /cross-origin redirect to (\S+)/i.exec(message)?.[1];
+    if (origin === undefined)
+        return false;
+    try {
+        return COOKIE_HANDSHAKE_HOSTS.has(new URL(origin).hostname.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The article a challenge page stands in front of, when its URL names it.
+ *
+ * A bot wall usually redirects to its own page and carries the original in a
+ * query parameter (mp.weixin.qq.com → `/mp/wappoc_appmsgcaptcha?…&target_url=`).
+ * Builds before 2026-10-04 saved that landing URL as the link itself, which
+ * then titled the card and was what every retry — the rendered fetch included
+ * — asked for; the state normalizer walks such a link back with this.
+ *
+ * @param url - a stored link.
+ * @returns the http(s) target, or `undefined` when the URL is not a challenge landing.
+ */
+export function challengeTarget(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+    if (!/captcha|challenge/i.test(parsed.pathname))
+        return undefined;
+    for (const key of ['target_url', 'targetUrl', 'return_url', 'redirect_url']) {
+        const value = parsed.searchParams.get(key);
+        if (value === null)
+            continue;
+        try {
+            const target = new URL(value);
+            if (target.protocol === 'https:' || target.protocol === 'http:')
+                return target.toString();
+        }
+        catch {
+            // Not a URL: try the next name.
+        }
+    }
+    return undefined;
+}
 /**
  * Build a display label for a source from its URL: the registrable-ish host
  * plus the last meaningful path segment, which is what distinguishes several

package/lib/types/xiaoyuzhou.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Xiaoyuzhou (小宇宙): episode and podcast pages → what the reader stores.
+ *
+ * Xiaoyuzhou publishes no RSS. Its pages do carry their data as Next.js
+ * `__NEXT_DATA__` JSON (measured 2026-10-20): an episode page has
+ * `props.pageProps.episode` with the audio enclosure, duration, shownotes and
+ * podcast; a podcast page has `props.pageProps.podcast.episodes[]`. A podcast
+ * page is turned into an RSS document on the host, so subscribing to it is an
+ * ordinary feed subscription for every other part of the reader.
+ *
+ * Pure: the host fetches the page and hands over its text.
+ *
+ * @module @khorsheed/dsh-reader/xiaoyuzhou
+ */
+/** One episode, as the reader needs it. */
+export interface XiaoyuzhouEpisode {
+    readonly id: string;
+    readonly title: string;
+    readonly audio: string;
+    readonly durationSec?: number;
+    readonly publishedAt?: string;
+    /** The shownotes (Xiaoyuzhou's own HTML), else the plain description. */
+    readonly notesHtml?: string;
+    readonly image?: string;
+    readonly podcastTitle?: string;
+}
+/**
+ * Read an episode page.
+ *
+ * @param html - the page's HTML.
+ * @returns the episode, or `undefined` when the page carries none.
+ */
+export declare function readEpisodePage(html: string): XiaoyuzhouEpisode | undefined;
+/**
+ * Turn a podcast page into an RSS document the reader subscribes to like any
+ * other feed.
+ *
+ * @param html - the podcast page's HTML.
+ * @param pageUrl - the page's URL (the channel link).
+ * @returns the RSS text, or `undefined` when the page carries no podcast.
+ */
+export declare function podcastPageToRss(html: string, pageUrl: string): string | undefined;
+//# sourceMappingURL=xiaoyuzhou.d.ts.map

package/lib/types/xiaoyuzhou.js

@@ -0,0 +1,134 @@
+/**
+ * Xiaoyuzhou (小宇宙): episode and podcast pages → what the reader stores.
+ *
+ * Xiaoyuzhou publishes no RSS. Its pages do carry their data as Next.js
+ * `__NEXT_DATA__` JSON (measured 2026-10-20): an episode page has
+ * `props.pageProps.episode` with the audio enclosure, duration, shownotes and
+ * podcast; a podcast page has `props.pageProps.podcast.episodes[]`. A podcast
+ * page is turned into an RSS document on the host, so subscribing to it is an
+ * ordinary feed subscription for every other part of the reader.
+ *
+ * Pure: the host fetches the page and hands over its text.
+ *
+ * @module @khorsheed/dsh-reader/xiaoyuzhou
+ */
+/** The page's Next.js data, or `undefined` when the page has none. */
+function nextData(html) {
+    const match = /<script id="__NEXT_DATA__"[^>]*>([\s\S]*?)<\/script>/.exec(html);
+    if (match === null)
+        return undefined;
+    try {
+        return JSON.parse(match[1]);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A nested record field, tolerantly. */
+function field(value, ...path) {
+    let current = value;
+    for (const key of path) {
+        if (typeof current !== 'object' || current === null)
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/** A string field, or `undefined`. */
+function str(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+/** One episode record → the reader's shape. */
+function readEpisode(record, podcastTitle) {
+    const id = str(field(record, 'eid'));
+    const title = str(field(record, 'title'));
+    const audio = str(field(record, 'enclosure', 'url')) ?? str(field(record, 'media', 'source', 'url'));
+    if (id === undefined || title === undefined || audio === undefined)
+        return undefined;
+    const duration = Number(field(record, 'duration'));
+    const notes = str(field(record, 'shownotes')) ?? str(field(record, 'description'));
+    const image = str(field(record, 'image', 'picUrl')) ?? str(field(record, 'podcast', 'image', 'picUrl'));
+    const podcast = podcastTitle ?? str(field(record, 'podcast', 'title'));
+    const publishedAt = str(field(record, 'pubDate'));
+    return {
+        id,
+        title,
+        audio,
+        ...(Number.isFinite(duration) && duration > 0 ? { durationSec: duration } : {}),
+        ...(publishedAt === undefined ? {} : { publishedAt }),
+        ...(notes === undefined ? {} : { notesHtml: notes }),
+        ...(image === undefined ? {} : { image }),
+        ...(podcast === undefined ? {} : { podcastTitle: podcast }),
+    };
+}
+/**
+ * Read an episode page.
+ *
+ * @param html - the page's HTML.
+ * @returns the episode, or `undefined` when the page carries none.
+ */
+export function readEpisodePage(html) {
+    return readEpisode(field(nextData(html), 'props', 'pageProps', 'episode'));
+}
+/** Escape text for XML content and attributes. */
+function xml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/** CDATA, safe against a literal `]]>` in the content. */
+function cdata(text) {
+    return `<![CDATA[${text.replace(/]]>/g, ']]]]><![CDATA[>')}]]>`;
+}
+/** The MIME type an audio URL most likely has. */
+function audioType(url) {
+    const path = url.toLowerCase().split('?')[0] ?? '';
+    if (path.endsWith('.m4a') || path.endsWith('.mp4'))
+        return 'audio/mp4';
+    return 'audio/mpeg';
+}
+/**
+ * Turn a podcast page into an RSS document the reader subscribes to like any
+ * other feed.
+ *
+ * @param html - the podcast page's HTML.
+ * @param pageUrl - the page's URL (the channel link).
+ * @returns the RSS text, or `undefined` when the page carries no podcast.
+ */
+export function podcastPageToRss(html, pageUrl) {
+    const podcast = field(nextData(html), 'props', 'pageProps', 'podcast');
+    const title = str(field(podcast, 'title'));
+    if (title === undefined)
+        return undefined;
+    const episodes = Array.isArray(field(podcast, 'episodes')) ? field(podcast, 'episodes') : [];
+    const items = episodes.flatMap(record => {
+        const episode = readEpisode(record, title);
+        if (episode === undefined)
+            return [];
+        const date = episode.publishedAt === undefined ? undefined : new Date(episode.publishedAt);
+        return [[
+                '<item>',
+                `<title>${xml(episode.title)}</title>`,
+                `<link>https://www.xiaoyuzhoufm.com/episode/${episode.id}</link>`,
+                `<guid isPermaLink="false">xiaoyuzhou:${episode.id}</guid>`,
+                date === undefined || Number.isNaN(date.getTime()) ? '' : `<pubDate>${date.toUTCString()}</pubDate>`,
+                episode.notesHtml === undefined ? '' : `<description>${cdata(episode.notesHtml)}</description>`,
+                `<enclosure url="${xml(episode.audio)}" type="${audioType(episode.audio)}" length="0"/>`,
+                episode.durationSec === undefined ? '' : `<itunes:duration>${String(episode.durationSec)}</itunes:duration>`,
+                episode.image === undefined ? '' : `<itunes:image href="${xml(episode.image)}"/>`,
+                '</item>',
+            ].filter(line => line !== '').join('')];
+    });
+    const description = str(field(podcast, 'description'));
+    const image = str(field(podcast, 'image', 'picUrl'));
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<rss version="2.0" xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd">',
+        '<channel>',
+        `<title>${xml(title)}</title>`,
+        `<link>${xml(pageUrl)}</link>`,
+        description === undefined ? '' : `<description>${xml(description)}</description>`,
+        image === undefined ? '' : `<image><url>${xml(image)}</url><title>${xml(title)}</title><link>${xml(pageUrl)}</link></image>`,
+        ...items,
+        '</channel>',
+        '</rss>',
+    ].filter(line => line !== '').join('\n');
+}

package/lib/types/ytdlp.d.ts

@@ -0,0 +1,111 @@
+import { type Cue } from './captions.ts';
+/** The release asset for this platform, or `undefined` where none is published. */
+export declare function releaseAsset(platform?: NodeJS.Platform, arch?: string): string | undefined;
+/** The subset of yt-dlp's info JSON the reader reads. */
+export interface YtDlpInfo {
+    readonly id?: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly duration?: number;
+    readonly thumbnail?: string;
+    readonly uploader?: string;
+    readonly channel?: string;
+    readonly channel_id?: string;
+    readonly upload_date?: string;
+    readonly timestamp?: number;
+    readonly language?: string;
+    readonly webpage_url?: string;
+    readonly subtitles?: Record<string, readonly {
+        ext: string;
+    }[]>;
+    readonly automatic_captions?: Record<string, readonly {
+        ext: string;
+    }[]>;
+}
+/** The caption track chosen for a video. */
+export interface CaptionTrack {
+    readonly lang: string;
+    readonly auto: boolean;
+    readonly ext: string;
+}
+/**
+ * Choose the caption track: the uploader's own captions in the video's
+ * language first, then any uploaded track, then the platform's automatic
+ * captions in the ORIGINAL language (YouTube marks it `<lang>-orig`; the other
+ * auto tracks are machine translations, which are also what trips its rate
+ * limit). Manual and automatic tracks are equally "captions" to the reader
+ * (2026-10-20); the choice only prefers the better one.
+ *
+ * @param info - the video's info JSON.
+ */
+export declare function chooseCaptionTrack(info: YtDlpInfo): CaptionTrack | undefined;
+/**
+ * Run a process to completion, honoring an abort signal and reporting stdout
+ * lines as they come.
+ */
+export declare function runStreaming(file: string, args: readonly string[], options: {
+    signal?: AbortSignal;
+    onLine?: (line: string) => void;
+    timeoutMs: number;
+}): Promise<void>;
+/** The yt-dlp manager. */
+export declare class YtDlp {
+    private readonly configured?;
+    private readonly binDir;
+    private readonly tmpRoot;
+    private ensuring;
+    /**
+     * @param stateRoot - the reader's state root (the managed binary lives under `bin/`).
+     * @param configured - a deployment-configured binary path, which wins.
+     */
+    constructor(stateRoot: string, configured?: string | undefined);
+    /** The binary to run: the configured one, else the managed one (fetched / updated as needed). */
+    binary(): Promise<string>;
+    /** Fetch the standalone release on first use; self-update it when stale. */
+    private ensureManaged;
+    /** The version of the binary in use. */
+    version(): Promise<string>;
+    /** The common flags: no download, no formats needed, Node as the JS runtime. */
+    private base;
+    /**
+     * A video's metadata.
+     *
+     * @param url - the video page URL.
+     */
+    info(url: string): Promise<YtDlpInfo>;
+    /**
+     * A channel's newest videos (a flat listing: no video is opened).
+     *
+     * YouTube's own channel feed (`feeds/videos.xml`) answers 404 (measured
+     * 2026-10-20), so the listing is yt-dlp's; `approximate_date` gives each
+     * entry a day-precision date.
+     *
+     * @param url - the channel URL.
+     * @param limit - how many of the newest videos.
+     */
+    channel(url: string, limit?: number): Promise<{
+        title?: string;
+        entries: YtDlpInfo[];
+    }>;
+    /**
+     * A video's audio track, downloaded for local transcription (the smallest
+     * audio-only format; the platform's combined stream when there is none).
+     *
+     * @param url - the video page URL.
+     * @param dir - an empty directory the file lands in.
+     * @param options - abort, and download progress 0–1.
+     * @returns the downloaded file.
+     */
+    audio(url: string, dir: string, options?: {
+        signal?: AbortSignal;
+        onProgress?: (fraction: number) => void;
+    }): Promise<string>;
+    /**
+     * One caption track's cues.
+     *
+     * @param url - the video page URL.
+     * @param track - the chosen track.
+     */
+    captions(url: string, track: CaptionTrack): Promise<Cue[]>;
+}
+//# sourceMappingURL=ytdlp.d.ts.map