@duyquangnvx/webnovel-downloader 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,862 @@
+import { z, ZodType } from 'zod';
+import { CheerioAPI } from 'cheerio';
+
+declare const UrlSchema: z.ZodBranded<z.ZodString, "Url">;
+/**
+ * An absolute URL string, branded after validation so an unchecked string
+ * cannot be passed where a real URL is required. Library output is already
+ * branded; to brand untrusted input, use `parseUrl` from `data-model/parse.ts`.
+ */
+type Url = z.infer<typeof UrlSchema>;
+declare const ChapterIndexSchema: z.ZodBranded<z.ZodNumber, "ChapterIndex">;
+/**
+ * A chapter's position in the table of contents, branded as a non-negative
+ * integer. Indices are **0-based**: chapter 1 is index 0. Build one with
+ * {@link chapterIndex}.
+ */
+type ChapterIndex = z.infer<typeof ChapterIndexSchema>;
+/**
+ * Build a validated ChapterIndex from a plain number. Throws if `input` is not
+ * a non-negative integer. This is the public way to construct the bounds for
+ * `DownloadOptions.chapterRange` (indices are 0-based: chapter 1 is index 0).
+ */
+declare function chapterIndex(input: number): ChapterIndex;
+declare const AdapterIdSchema: z.ZodBranded<z.ZodString, "AdapterId">;
+/** Stable identifier for a site adapter (e.g. `"truyenfull"`), branded as a non-empty string. */
+type AdapterId = z.infer<typeof AdapterIdSchema>;
+declare const IsoDateSchema: z.ZodBranded<z.ZodString, "IsoDate">;
+/** An ISO-8601 datetime string (e.g. `"2026-06-17T09:30:00.000Z"`), branded after validation. */
+type IsoDate = z.infer<typeof IsoDateSchema>;
+declare const ResumeTokenSchema: z.ZodBranded<z.ZodString, "ResumeToken">;
+/**
+ * Opaque token returned on a partial download (see {@link DownloadPartial}).
+ * Pass it back via `DownloadOptions.resume` to continue where the run left off.
+ * Branded as a non-empty string.
+ */
+type ResumeToken = z.infer<typeof ResumeTokenSchema>;
+
+declare const NovelStatusSchema: z.ZodEnum<["ongoing", "completed", "hiatus", "unknown"]>;
+declare const NovelMetadataSchema: z.ZodReadonly<z.ZodObject<{
+    sourceUrl: z.ZodBranded<z.ZodString, "Url">;
+    sourceSite: z.ZodBranded<z.ZodString, "AdapterId">;
+    title: z.ZodString;
+    author: z.ZodString;
+    description: z.ZodString;
+    coverUrl: z.ZodOptional<z.ZodBranded<z.ZodString, "Url">>;
+    genres: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
+    status: z.ZodEnum<["ongoing", "completed", "hiatus", "unknown"]>;
+    totalChapters: z.ZodOptional<z.ZodNumber>;
+    fetchedAt: z.ZodDate;
+}, "strip", z.ZodTypeAny, {
+    status: "ongoing" | "completed" | "hiatus" | "unknown";
+    sourceUrl: string & z.BRAND<"Url">;
+    sourceSite: string & z.BRAND<"AdapterId">;
+    title: string;
+    author: string;
+    description: string;
+    genres: readonly string[];
+    fetchedAt: Date;
+    coverUrl?: (string & z.BRAND<"Url">) | undefined;
+    totalChapters?: number | undefined;
+}, {
+    status: "ongoing" | "completed" | "hiatus" | "unknown";
+    sourceUrl: string;
+    sourceSite: string;
+    title: string;
+    author: string;
+    description: string;
+    genres: readonly string[];
+    fetchedAt: Date;
+    coverUrl?: string | undefined;
+    totalChapters?: number | undefined;
+}>>;
+declare const ChapterRefSchema: z.ZodReadonly<z.ZodObject<{
+    index: z.ZodBranded<z.ZodNumber, "ChapterIndex">;
+    title: z.ZodString;
+    url: z.ZodBranded<z.ZodString, "Url">;
+    volume: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    index: number & z.BRAND<"ChapterIndex">;
+    url: string & z.BRAND<"Url">;
+    volume?: string | undefined;
+}, {
+    title: string;
+    index: number;
+    url: string;
+    volume?: string | undefined;
+}>>;
+declare const ChapterSchema: z.ZodReadonly<z.ZodObject<{
+    index: z.ZodBranded<z.ZodNumber, "ChapterIndex">;
+    title: z.ZodString;
+    url: z.ZodBranded<z.ZodString, "Url">;
+    volume: z.ZodOptional<z.ZodString>;
+    content: z.ZodString;
+    fetchedAt: z.ZodDate;
+    wordCount: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    fetchedAt: Date;
+    index: number & z.BRAND<"ChapterIndex">;
+    url: string & z.BRAND<"Url">;
+    content: string;
+    wordCount: number;
+    volume?: string | undefined;
+}, {
+    title: string;
+    fetchedAt: Date;
+    index: number;
+    url: string;
+    content: string;
+    wordCount: number;
+    volume?: string | undefined;
+}>>;
+declare const NovelDataSchema: z.ZodReadonly<z.ZodObject<{
+    metadata: z.ZodReadonly<z.ZodObject<{
+        sourceUrl: z.ZodBranded<z.ZodString, "Url">;
+        sourceSite: z.ZodBranded<z.ZodString, "AdapterId">;
+        title: z.ZodString;
+        author: z.ZodString;
+        description: z.ZodString;
+        coverUrl: z.ZodOptional<z.ZodBranded<z.ZodString, "Url">>;
+        genres: z.ZodReadonly<z.ZodArray<z.ZodString, "many">>;
+        status: z.ZodEnum<["ongoing", "completed", "hiatus", "unknown"]>;
+        totalChapters: z.ZodOptional<z.ZodNumber>;
+        fetchedAt: z.ZodDate;
+    }, "strip", z.ZodTypeAny, {
+        status: "ongoing" | "completed" | "hiatus" | "unknown";
+        sourceUrl: string & z.BRAND<"Url">;
+        sourceSite: string & z.BRAND<"AdapterId">;
+        title: string;
+        author: string;
+        description: string;
+        genres: readonly string[];
+        fetchedAt: Date;
+        coverUrl?: (string & z.BRAND<"Url">) | undefined;
+        totalChapters?: number | undefined;
+    }, {
+        status: "ongoing" | "completed" | "hiatus" | "unknown";
+        sourceUrl: string;
+        sourceSite: string;
+        title: string;
+        author: string;
+        description: string;
+        genres: readonly string[];
+        fetchedAt: Date;
+        coverUrl?: string | undefined;
+        totalChapters?: number | undefined;
+    }>>;
+    chapters: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
+        index: z.ZodBranded<z.ZodNumber, "ChapterIndex">;
+        title: z.ZodString;
+        url: z.ZodBranded<z.ZodString, "Url">;
+        volume: z.ZodOptional<z.ZodString>;
+        content: z.ZodString;
+        fetchedAt: z.ZodDate;
+        wordCount: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        fetchedAt: Date;
+        index: number & z.BRAND<"ChapterIndex">;
+        url: string & z.BRAND<"Url">;
+        content: string;
+        wordCount: number;
+        volume?: string | undefined;
+    }, {
+        title: string;
+        fetchedAt: Date;
+        index: number;
+        url: string;
+        content: string;
+        wordCount: number;
+        volume?: string | undefined;
+    }>>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    metadata: Readonly<{
+        status: "ongoing" | "completed" | "hiatus" | "unknown";
+        sourceUrl: string & z.BRAND<"Url">;
+        sourceSite: string & z.BRAND<"AdapterId">;
+        title: string;
+        author: string;
+        description: string;
+        genres: readonly string[];
+        fetchedAt: Date;
+        coverUrl?: (string & z.BRAND<"Url">) | undefined;
+        totalChapters?: number | undefined;
+    }>;
+    chapters: readonly Readonly<{
+        title: string;
+        fetchedAt: Date;
+        index: number & z.BRAND<"ChapterIndex">;
+        url: string & z.BRAND<"Url">;
+        content: string;
+        wordCount: number;
+        volume?: string | undefined;
+    }>[];
+}, {
+    metadata: Readonly<{
+        status: "ongoing" | "completed" | "hiatus" | "unknown";
+        sourceUrl: string;
+        sourceSite: string;
+        title: string;
+        author: string;
+        description: string;
+        genres: readonly string[];
+        fetchedAt: Date;
+        coverUrl?: string | undefined;
+        totalChapters?: number | undefined;
+    }>;
+    chapters: readonly Readonly<{
+        title: string;
+        fetchedAt: Date;
+        index: number;
+        url: string;
+        content: string;
+        wordCount: number;
+        volume?: string | undefined;
+    }>[];
+}>>;
+
+/** Publication state of a novel: `"ongoing" | "completed" | "hiatus" | "unknown"`. */
+type NovelStatus = z.infer<typeof NovelStatusSchema>;
+/**
+ * Novel-level metadata (title, author, cover, genres, status, …) without any
+ * chapter bodies. `totalChapters` is the source's reported count and may be
+ * absent if the site doesn't expose one — never inferred from fetched chapters.
+ */
+type NovelMetadata = z.infer<typeof NovelMetadataSchema>;
+/**
+ * A lightweight pointer to a chapter (index, title, URL, optional volume)
+ * produced while walking the table of contents — before the body is fetched.
+ * See {@link Chapter} for the fetched form.
+ */
+type ChapterRef = z.infer<typeof ChapterRefSchema>;
+/**
+ * A fully fetched chapter: a {@link ChapterRef} plus normalized `content`
+ * (plain text, paragraphs separated by blank lines) and `wordCount`.
+ */
+type Chapter = z.infer<typeof ChapterSchema>;
+/**
+ * The complete result of a download: {@link NovelMetadata} plus the fetched
+ * {@link Chapter}s, sorted by source index. On a partial download the array
+ * has gaps at the indices that permanently failed (indices are never
+ * renumbered).
+ */
+type NovelData = z.infer<typeof NovelDataSchema>;
+
+/**
+ * Base class for every error this library raises or returns. Each subclass
+ * carries a stable, machine-readable `code` (e.g. `"ADAPTER_NOT_FOUND"`) so
+ * callers can branch on `err.code` instead of `instanceof`.
+ */
+declare abstract class DownloadError extends Error {
+    abstract readonly code: string;
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * No registered adapter can handle the given URL (`code: "ADAPTER_NOT_FOUND"`).
+ * `download()` returns this in its `{ status: "error" }` envelope;
+ * `fetchMetadata()` throws it.
+ */
+declare class AdapterNotFoundError extends DownloadError {
+    readonly url: string;
+    readonly code: "ADAPTER_NOT_FOUND";
+    constructor(url: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A non-retryable HTTP error response (`code: "HTTP_ERROR"`); carries `status` and `url`. */
+declare class HttpError extends DownloadError {
+    readonly status: number;
+    readonly url: Url;
+    readonly code: "HTTP_ERROR";
+    constructor(status: number, url: Url, message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The host signalled rate limiting, e.g. HTTP 429 (`code: "RATE_LIMITED"`); `retryAfterMs` if known. */
+declare class RateLimitedError extends DownloadError {
+    readonly url: Url;
+    readonly retryAfterMs?: number | undefined;
+    readonly code: "RATE_LIMITED";
+    constructor(url: Url, retryAfterMs?: number | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Malformed input or an unparseable/invalid response (`code: "PARSE_ERROR"`) —
+ * e.g. a bad URL, an out-of-range `chapterRange` bound, or adapter output that
+ * fails schema validation. Carries optional `url` and `snippet` for debugging.
+ */
+declare class ParseError extends DownloadError {
+    readonly code: "PARSE_ERROR";
+    readonly url: Url | undefined;
+    readonly snippet: string | undefined;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        url?: Url;
+        snippet?: string;
+    });
+}
+/**
+ * A single chapter could not be fetched (`code: "CHAPTER_FETCH_FAILED"`);
+ * carries the failing `ref`. Surfaces in {@link DownloadPartial}'s `failures`.
+ */
+declare class ChapterFetchError extends DownloadError {
+    readonly ref: ChapterRef;
+    readonly code: "CHAPTER_FETCH_FAILED";
+    constructor(ref: ChapterRef, options?: {
+        cause?: unknown;
+    });
+}
+/** A request exceeded its timeout (`code: "TIMEOUT"`). */
+declare class TimeoutError extends DownloadError {
+    readonly url: Url;
+    readonly code: "TIMEOUT";
+    constructor(url: Url, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The operation was aborted via an `AbortSignal` (`code: "CANCELLED"`).
+ * `download()` **throws** this rather than returning an error envelope.
+ */
+declare class CancelledError extends DownloadError {
+    readonly code: "CANCELLED";
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A browser-tier request was required but neither `patchright` nor `playwright`
+ * is installed (`code: "BROWSER_MODULE_NOT_INSTALLED"`). The message lists the
+ * install commands and the `http-only` opt-out.
+ */
+declare class BrowserModuleNotInstalledError extends DownloadError {
+    readonly code: "BROWSER_MODULE_NOT_INSTALLED";
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Suggested remedy on a {@link ChallengeUnresolvedError}:
+ * `"manual-solve"` (launch a headed browser and solve once) or
+ * `"transport-config"` (raise the navigation timeout / use a stronger transport).
+ */
+type ChallengeUnresolvedHint = "manual-solve" | "transport-config";
+/**
+ * A Cloudflare challenge could not be cleared within the navigation timeout
+ * (`code: "CHALLENGE_UNRESOLVED"`). `hint` indicates how to recover; the message
+ * spells out the concrete fix.
+ */
+declare class ChallengeUnresolvedError extends DownloadError {
+    readonly url: Url;
+    readonly hint: ChallengeUnresolvedHint;
+    readonly code: "CHALLENGE_UNRESOLVED";
+    constructor(url: Url, hint: ChallengeUnresolvedHint, options?: {
+        cause?: unknown;
+    });
+}
+
+/** One chapter that could not be fetched, with the error and the attempt count. */
+interface ChapterFailure {
+    readonly ref: ChapterRef;
+    readonly error: DownloadError;
+    readonly attempts: number;
+}
+/** Every chapter in range was fetched. */
+interface DownloadSuccess {
+    readonly status: "success";
+    readonly data: NovelData;
+}
+/**
+ * The novel was fetched but some chapters permanently failed. `data` holds the
+ * chapters that succeeded (with gaps at the failed indices); `failures` lists
+ * the rest.
+ */
+interface DownloadPartial {
+    readonly status: "partial";
+    readonly data: NovelData;
+    readonly failures: readonly ChapterFailure[];
+    /**
+     * Present only when the caller passed `options.resume`. Without resume
+     * enabled there is no state file to point at, so no token can be issued.
+     * Pass it back via `options.resume` to retry just the failed chapters.
+     */
+    readonly resumeToken?: ResumeToken;
+}
+/**
+ * The download could not produce a novel (bad/unknown URL, metadata or TOC
+ * failure). Note: an aborted download throws `CancelledError` rather than
+ * returning this.
+ */
+interface DownloadFailed {
+    readonly status: "error";
+    readonly error: DownloadError;
+}
+/**
+ * The outcome of `Downloader.download()`. Discriminate on `status`:
+ * `"success"`, `"partial"`, or `"error"`.
+ */
+type DownloadResult = DownloadSuccess | DownloadPartial | DownloadFailed;
+
+/**
+ * Lifecycle events delivered to `DownloadOptions.onEvent`. Discriminate on
+ * `type`. `progress` is throttled to ~1/sec (plus a guaranteed final emit) and
+ * `toc:progress` is deduped on `discovered`; the rest fire as they occur.
+ * `rate-limit:wait` only fires for the built-in transport (not a custom
+ * `HttpClient`), and carries the `host` so callers can attribute the wait.
+ */
+type DownloadEvent = {
+    type: "metadata:fetched";
+    metadata: NovelMetadata;
+} | {
+    type: "toc:progress";
+    discovered: number;
+} | {
+    type: "toc:complete";
+    total: number;
+} | {
+    type: "chapter:start";
+    ref: ChapterRef;
+} | {
+    type: "chapter:success";
+    chapter: Chapter;
+} | {
+    type: "chapter:failed";
+    ref: ChapterRef;
+    error: DownloadError;
+} | {
+    type: "progress";
+    completed: number;
+    total: number;
+} | {
+    type: "cache:hit";
+    url: Url;
+} | {
+    type: "rate-limit:wait";
+    host: string;
+    waitMs: number;
+};
+
+/** Per-request options passed to {@link HttpClient.get}. */
+interface HttpRequestOptions {
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly signal?: AbortSignal;
+    /** Request timeout in ms. */
+    readonly timeoutMs?: number;
+}
+/** A fetched response: status, headers, the decoded `body` string, and the final `url` (post-redirect). */
+interface HttpResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+    readonly url: Url;
+}
+/**
+ * The transport contract. Implement this to plug a custom transport (e.g. a
+ * SaaS render service) into a `Downloader` via its `http` option, bypassing the
+ * built-in tiered client — you then own retries, caching, and challenge
+ * handling. See `examples/custom-transport.ts`.
+ */
+interface HttpClient {
+    get(url: Url, opts?: HttpRequestOptions): Promise<HttpResponse>;
+}
+/** Pino log levels, plus `"silent"` to disable logging entirely. */
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "silent";
+/**
+ * Minimal structured-logging interface (a pino-compatible subset). Pass your
+ * own to `createDownloader({ logger })`, or build one with {@link createLogger}.
+ */
+interface Logger {
+    trace(obj: object, msg?: string): void;
+    trace(msg: string): void;
+    debug(obj: object, msg?: string): void;
+    debug(msg: string): void;
+    info(obj: object, msg?: string): void;
+    info(msg: string): void;
+    warn(obj: object, msg?: string): void;
+    warn(msg: string): void;
+    error(obj: object, msg?: string): void;
+    error(msg: string): void;
+    child(bindings: object): Logger;
+}
+
+interface AdapterContext$1 {
+    readonly http: HttpClient;
+    readonly logger: Logger;
+    readonly signal: AbortSignal;
+    readonly novelMetadata?: NovelMetadata;
+}
+interface SiteAdapter$1 {
+    readonly id: AdapterId;
+    readonly displayName: string;
+    readonly hostnames: readonly string[];
+    readonly preferredTransport?: "http" | "browser";
+    canHandle(url: string): boolean;
+    fetchMetadata(url: Url, ctx: AdapterContext$1): Promise<NovelMetadata>;
+    fetchChapterList(url: Url, ctx: AdapterContext$1): AsyncIterable<ChapterRef>;
+    fetchChapter(ref: ChapterRef, ctx: AdapterContext$1): Promise<Chapter>;
+}
+
+/** Per-host request throttling, applied across every `download()` on a `Downloader`. */
+interface RateLimitOptions {
+    /** Sustained requests per second per host. Default: 2. */
+    readonly requestsPerSecond: number;
+    /** Token-bucket capacity (max burst before throttling). Default: `requestsPerSecond`. */
+    readonly burst?: number;
+}
+/** Automatic retry policy for transient HTTP failures. */
+interface RetryOptions {
+    /** Max retry attempts after the first try. Default: 3. */
+    readonly retries: number;
+    /** Delay growth between attempts. Default: `"exponential"`. */
+    readonly backoff: "exponential" | "linear" | "fixed";
+    /** Floor for the backoff delay, in ms. Default: 500. */
+    readonly minDelayMs?: number;
+    /** Ceiling for the backoff delay, in ms. Default: 30000. */
+    readonly maxDelayMs?: number;
+    /** HTTP status codes that trigger a retry. Default: `[408, 429, 500, 502, 503, 504]`. */
+    readonly retryOn?: readonly number[];
+}
+/** On-disk HTTP response cache (ETag/304 revalidation). */
+interface CacheOptions {
+    /** Directory for cached responses. */
+    readonly dir: string;
+    /** Max age before a cached entry is considered stale, in ms. Default: 7 days. */
+    readonly maxAgeMs?: number;
+}
+/**
+ * How to resume an interrupted download:
+ * - `true` — use a default state file keyed by URL under the user cache dir.
+ * - `{ stateFile }` — use an explicit state file path.
+ * - `{ token }` — resume from a {@link ResumeToken} issued by a prior partial run.
+ */
+type ResumeOptions = true | {
+    readonly stateFile: string;
+} | {
+    readonly token: ResumeToken;
+};
+/** Per-call options for `Downloader.download()` / `fetchMetadata()`. */
+interface DownloadOptions {
+    /** Concurrent chapter fetches. Default: 4. */
+    readonly concurrency?: number;
+    /** Enable the on-disk HTTP response cache. */
+    readonly cache?: CacheOptions;
+    /** Enable resumable state so an interrupted run can continue. */
+    readonly resume?: ResumeOptions;
+    /** Chapter body format. Only `"text"` is supported. */
+    readonly contentFormat?: "text";
+    /**
+     * Limit the download to a contiguous slice. Bounds are **0-based and
+     * inclusive** (chapter 1 is index 0), so `{ from: 0, to: 9 }` is the first 10
+     * chapters. A non-integer or negative bound resolves to `{ status: "error" }`.
+     */
+    readonly chapterRange?: {
+        from?: number;
+        to?: number;
+    };
+    /** Abort the download. When it fires, `download()` rejects with `CancelledError`. */
+    readonly signal?: AbortSignal;
+    /** Progress/lifecycle callback; receives every {@link DownloadEvent}. */
+    readonly onEvent?: (event: DownloadEvent) => void;
+    /** Force a specific adapter instead of resolving one from the URL. */
+    readonly adapter?: SiteAdapter$1;
+}
+/**
+ * Transport selection:
+ * - `"auto"` — undici first, escalate to a real browser on a Cloudflare challenge.
+ * - `"http-only"` — never launch a browser; browser-only adapters throw.
+ * - `"browser-required"` — route every request through the browser.
+ */
+type TransportMode = "auto" | "http-only" | "browser-required";
+/** Tuning for the headless-browser transport tier. */
+interface TransportBrowserOptions {
+    /** Launch a visible window (e.g. to solve a Cloudflare challenge by hand). Default: false. */
+    readonly headed?: boolean;
+    /** Idle time before the shared browser is closed, in ms. Default: 60000. */
+    readonly idleTimeoutMs?: number;
+    /** Path to a specific Chromium binary instead of the bundled one. */
+    readonly executablePath?: string;
+    /** Per-navigation timeout for browser page loads, in ms. */
+    readonly navigationTimeoutMs?: number;
+}
+/** Full transport configuration: a {@link TransportMode} plus optional browser tuning. */
+interface TransportConfig {
+    readonly mode: TransportMode;
+    readonly browserOptions?: TransportBrowserOptions;
+}
+
+/**
+ * Build a pino-backed {@link Logger} at the given level (default `"silent"`).
+ * Pass it to `createDownloader({ logger })`, or use the `logLevel` shortcut on
+ * `createDownloader` to skip constructing one.
+ */
+declare function createLogger(opts?: {
+    level?: LogLevel;
+}): Logger;
+
+interface ChromiumNamespace {
+    launch(opts: BrowserLaunchOptions): Promise<RuntimeBrowser>;
+}
+interface BrowserLaunchOptions {
+    readonly headless?: boolean;
+    readonly executablePath?: string;
+}
+interface RuntimeBrowser {
+    newContext(opts?: {
+        userAgent?: string;
+    }): Promise<RuntimeContext>;
+    close(): Promise<void>;
+    isConnected(): boolean;
+}
+interface RuntimeContext {
+    newPage(): Promise<RuntimePage>;
+    cookies(urls?: readonly string[]): Promise<readonly RuntimeCookie[]>;
+    close(): Promise<void>;
+}
+interface RuntimePage {
+    goto(url: string, opts?: {
+        timeout?: number;
+        waitUntil?: "domcontentloaded" | "load";
+        signal?: AbortSignal;
+    }): Promise<RuntimeResponse | null>;
+    content(): Promise<string>;
+    on(event: "response", handler: (res: RuntimeResponse) => void): void;
+    off(event: "response", handler: (res: RuntimeResponse) => void): void;
+    title(): Promise<string>;
+    evaluate(script: string): Promise<unknown>;
+    /**
+     * Register a script that runs in the page's main world before any other
+     * scripts on every navigation. Required to bridge into the main world from
+     * patchright's isolated `evaluate()` context — adapters install a relay
+     * that listens for DOM events from isolated-world `evaluate()` and invokes
+     * page-defined functions (e.g. `loadBookIndex`).
+     */
+    addInitScript(script: string): Promise<void>;
+    close(): Promise<void>;
+}
+interface RuntimeResponse {
+    url(): string;
+    status(): number;
+    headers(): Record<string, string>;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}
+interface RuntimeCookie {
+    readonly name: string;
+    readonly value: string;
+    readonly domain?: string;
+    readonly path?: string;
+}
+interface BrowserModule {
+    readonly name: "patchright" | "playwright";
+    readonly chromium: ChromiumNamespace;
+}
+/** Adapter-facing interface exposed via AdapterContext.browser. */
+interface BrowserClient {
+    navigate(url: Url, signal: AbortSignal, opts?: NavigateOptions): Promise<BrowserPage>;
+}
+interface NavigateOptions {
+    /**
+     * A JS expression installed via `Page.addInitScript` before the first
+     * navigation. Runs in the page's main world (where the page's globals are
+     * defined), giving adapters a way to bridge from patchright's isolated
+     * `evaluate()` context into main-world functions.
+     */
+    readonly initScript?: string;
+}
+interface WaitForResponseTextOpts {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly parse: "text";
+    /**
+     * Ignore already-buffered responses and wait strictly for a new one. Set
+     * when the adapter is about to trigger a fresh XHR and must not match the
+     * previous identical request still cached in the buffer.
+     */
+    readonly skipBuffer?: boolean;
+}
+interface WaitForResponseJsonOpts<T> {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly parse: "json";
+    readonly schema: ZodType<T>;
+    readonly skipBuffer?: boolean;
+}
+interface BrowserPage {
+    waitForResponse(pattern: RegExp, opts: WaitForResponseTextOpts): Promise<{
+        url: Url;
+        status: number;
+        body: string;
+    }>;
+    waitForResponse<T>(pattern: RegExp, opts: WaitForResponseJsonOpts<T>): Promise<{
+        url: Url;
+        status: number;
+        body: T;
+    }>;
+    content(): Promise<string>;
+    /**
+     * Evaluate a JS expression in the page context. With patchright the script
+     * runs in an isolated world: DOM is shared but the page's window globals
+     * are not visible. To trigger main-world code, install a relay via
+     * `BrowserClient.navigate({ initScript })` and dispatch a DOM event from
+     * here — DOM events bridge across the world boundary.
+     */
+    evaluate(script: string): Promise<unknown>;
+    close(): Promise<void>;
+}
+
+/**
+ * Runtime services handed to every adapter method: the {@link HttpClient}, a
+ * logger, the abort signal, an optional browser client (present only for
+ * browser-tier adapters), and — during chapter fetches — the already-fetched
+ * novel metadata.
+ */
+interface AdapterContext extends AdapterContext$1 {
+    readonly browser?: BrowserClient;
+}
+/**
+ * The contract every site adapter implements. Register custom adapters via
+ * `createDownloader({ adapters })` or the `Downloader` constructor. Extending
+ * {@link BaseAdapter} covers `canHandle` and the HTML/JSON helpers for you.
+ * See `docs/adapter-spec.md`.
+ */
+interface SiteAdapter {
+    /** Stable adapter id, also stamped onto `NovelMetadata.sourceSite`. */
+    readonly id: AdapterId;
+    /** Human-readable site name. */
+    readonly displayName: string;
+    /** Hostnames this adapter claims (used by the default `canHandle`). */
+    readonly hostnames: readonly string[];
+    /**
+     * Optional transport hint. Adapters that require a real browser (e.g. for
+     * XHR-rendered TOCs or Cloudflare-protected pages) set this to `"browser"`.
+     * Omitting the field (or setting it to `"http"`) selects the default HTTP
+     * transport.
+     */
+    readonly preferredTransport?: "http" | "browser";
+    /** Whether this adapter handles `url` (typically a hostname match). */
+    canHandle(url: string): boolean;
+    /** Fetch novel-level metadata. Throw a {@link DownloadError} subclass on failure. */
+    fetchMetadata(url: Url, ctx: AdapterContext): Promise<NovelMetadata>;
+    /**
+     * Yield chapter references for the whole table of contents. Refs MUST be
+     * yielded in ascending `index` order — the pipeline short-circuits a
+     * `chapterRange` once it passes the upper bound and relies on this ordering.
+     */
+    fetchChapterList(url: Url, ctx: AdapterContext): AsyncIterable<ChapterRef>;
+    /** Fetch and normalize one chapter body. */
+    fetchChapter(ref: ChapterRef, ctx: AdapterContext): Promise<Chapter>;
+}
+/**
+ * Convenience base for adapters: implements `canHandle` (hostname match) and
+ * provides protected `loadHtml` / `fetchJson` helpers. Extend it and implement
+ * the three `fetch*` methods.
+ */
+declare abstract class BaseAdapter implements SiteAdapter {
+    abstract readonly id: AdapterId;
+    abstract readonly displayName: string;
+    abstract readonly hostnames: readonly string[];
+    readonly preferredTransport?: "http" | "browser";
+    abstract fetchMetadata(url: Url, ctx: AdapterContext): Promise<NovelMetadata>;
+    abstract fetchChapterList(url: Url, ctx: AdapterContext): AsyncIterable<ChapterRef>;
+    abstract fetchChapter(ref: ChapterRef, ctx: AdapterContext): Promise<Chapter>;
+    canHandle(url: string): boolean;
+    protected loadHtml(url: Url, ctx: AdapterContext): Promise<CheerioAPI>;
+    protected fetchJson(url: Url, ctx: AdapterContext): Promise<unknown>;
+}
+
+/**
+ * Orchestrates a download: resolves a site adapter from the URL, fetches
+ * metadata + the table of contents, then fetches chapters concurrently with
+ * shared rate-limiting, retries, optional caching, and resumable state.
+ *
+ * Most callers use the shared `downloader` singleton or `createDownloader()`
+ * rather than constructing this directly. An instance owns a per-host transport
+ * (and may hold a browser pool), so call {@link Downloader.dispose} when done.
+ */
+declare class Downloader {
+    #private;
+    /**
+     * Build a downloader from a set of adapters. `rateLimit`, `retry`, and
+     * `transport` configure the shared per-host transport (set once here, not
+     * per call). Provide `http` to replace the entire transport stack with a
+     * custom {@link HttpClient}. Prefer `createDownloader()` for the built-in
+     * adapters; use this constructor for a custom adapter set or transport.
+     */
+    constructor(opts: {
+        adapters: readonly SiteAdapter[];
+        http?: HttpClient;
+        logger?: Logger;
+        transport?: TransportConfig | TransportMode;
+        rateLimit?: RateLimitOptions;
+        retry?: RetryOptions;
+        /** @internal — test seam for browser module loading */
+        browserModuleLoader?: () => Promise<BrowserModule>;
+        /** @internal — test seam: replaces the real UndiciHttpClient leaf */
+        undiciOverride?: HttpClient;
+        logLevel?: LogLevel;
+    });
+    /** Release held resources (closes the browser pool, if any). Safe to call once when done. */
+    dispose(): Promise<void>;
+    /** True when a built-in/registered adapter can handle this URL. */
+    canHandle(url: string): boolean;
+    /** Plain, serializable list of the sites this instance can download. */
+    supportedSites(): readonly {
+        id: AdapterId;
+        displayName: string;
+        hostnames: readonly string[];
+    }[];
+    /** @internal — for tests only. Returns a ready ctx and a release fn. */
+    _ctxFor(adapter: SiteAdapter, signal: AbortSignal): Promise<{
+        ctx: AdapterContext;
+        release: () => Promise<void>;
+    }>;
+    /**
+     * Low-level single-stage metadata fetch. Unlike `download()`, this returns a
+     * bare value and therefore **throws** on failure (`AdapterNotFoundError`,
+     * `ParseError`, or any `DownloadError`). Use `download()` if you want the
+     * `{ status: "error" }` envelope instead of exceptions.
+     */
+    fetchMetadata(url: string, options?: DownloadOptions): Promise<NovelMetadata>;
+    /**
+     * Download a novel end to end. Returns a {@link DownloadResult} envelope —
+     * `"success"`, `"partial"` (some chapters failed; carries a `resumeToken`
+     * when `options.resume` is set), or `"error"` (including an unsupported or
+     * malformed URL). The only thrown error is `CancelledError`, when
+     * `options.signal` aborts. Use `options.onEvent` for progress.
+     */
+    download(url: string, options?: DownloadOptions): Promise<DownloadResult>;
+}
+
+/** Fresh instances of every built-in site adapter. */
+declare function builtinAdapters(): SiteAdapter[];
+/** Options for {@link createDownloader}. All fields are optional. */
+interface CreateDownloaderOptions {
+    /** Transport mode/config. Default: `{ mode: "auto" }` (headless). */
+    readonly transport?: TransportConfig | TransportMode;
+    /** Replace the entire transport stack with a custom {@link HttpClient}. */
+    readonly http?: HttpClient;
+    readonly logger?: Logger;
+    /** Convenience: build a pino logger at this level when no `logger` is given. */
+    readonly logLevel?: LogLevel;
+    /** Adapters to register. Defaults to every built-in adapter. */
+    readonly adapters?: readonly SiteAdapter[];
+    readonly rateLimit?: RateLimitOptions;
+    readonly retry?: RetryOptions;
+}
+/**
+ * Build a Downloader wired with the built-in site adapters. Unlike the shared
+ * `downloader` singleton, this lets you set the transport (e.g. a headed
+ * browser for a manual Cloudflare solve), a custom HttpClient, or a logger.
+ * Call `dispose()` when done — the instance may hold a browser pool.
+ */
+declare function createDownloader(opts?: CreateDownloaderOptions): Downloader;
+/** Shared singleton: every built-in adapter, default (auto) transport. */
+declare const downloader: Downloader;
+
+export { type AdapterContext, type AdapterId, AdapterNotFoundError, BaseAdapter, BrowserModuleNotInstalledError, type CacheOptions, CancelledError, ChallengeUnresolvedError, type ChallengeUnresolvedHint, type Chapter, type ChapterFailure, ChapterFetchError, type ChapterIndex, type ChapterRef, type CreateDownloaderOptions, DownloadError, type DownloadEvent, type DownloadFailed, type DownloadOptions, type DownloadPartial, type DownloadResult, type DownloadSuccess, Downloader, type HttpClient, HttpError, type IsoDate, type LogLevel, type Logger, type NovelData, type NovelMetadata, type NovelStatus, ParseError, type RateLimitOptions, RateLimitedError, type ResumeOptions, type ResumeToken, type RetryOptions, type SiteAdapter, TimeoutError, type TransportBrowserOptions, type TransportConfig, type TransportMode, type Url, builtinAdapters, chapterIndex, createDownloader, createLogger, downloader };