@publiwrite/html-to-epub/lib/index.d.ts

A library to generate EPUB from HTML. Inspired by epub-gen.

export interface EpubContentOptions {
    title: string;
    data: string;
    url?: string;
    author?: Array<string> | string;
    filename?: string;
    excludeFromToc?: boolean;
    beforeToc?: boolean;
    ornamentalBreakElement?: string;
}
export interface EpubOptions {
    title: string;
    description: string;
    cover?: string;
    publisher?: string;
    author?: Array<string> | string;
    tocTitle?: string;
    appendChapterTitles?: boolean;
    includeToc?: boolean;
    date?: string;
    lang?: string;
    css?: string;
    fonts?: string[];
    content: EpubContentOptions[];
    customOpfTemplatePath?: string;
    customNcxTocTemplatePath?: string;
    customHtmlTocTemplatePath?: string;
    customHtmlCoverTemplatePath?: string;
    customHtmlContentTemplatePath?: string;
    version?: number;
    userAgent?: string;
    verbose?: boolean;
    tempDir?: string;
    /**
     * gzip compression level for the final EPUB ZIP (0 = store-only,
     * 9 = max). The previous default was 9, which is ~10x slower than
     * 6 for ~2-5% smaller output; EPUB payloads are mostly fonts and
     * already-compressed images, so the marginal saving is tiny.
     * Default 6.
     */
    zipCompressionLevel?: number;
    /**
     * Max concurrent image downloads. Inline images used to be fetched
     * one-at-a-time in a serial loop. For a 30-image book over 100-200ms
     * RTT to S3/CDN this added 3-6s of pure waiting. Now bounded-parallel
     * via a true semaphore (p-limit) so a slot opens as soon as any one
     * download finishes, not when the whole batch finishes.
     * Default 8.
     */
    imageDownloadConcurrency?: number;
    /**
     * What to do when an inline image or cover image fails to fetch.
     *
     *   "warn"  (default): log if verbose, push a message to `warnings`,
     *           continue producing the EPUB. Backwards-compatible with
     *           pre-0.1.0 silent-skip behaviour.
     *   "throw": reject `render()` on the first failure. Use this when
     *           a missing image means the EPUB is unfit to ship (which
     *           is most production cases). The previous default silently
     *           shipped broken EPUBs when the network was unreachable.
     */
    assetFailureMode?: "warn" | "throw";
    /**
     * Whether to honour `file://` URLs in inline images and cover. The
     * library used to accept them unconditionally, which meant any
     * Plate-rendered `<img src="file:///etc/passwd">` would be embedded
     * verbatim in the generated EPUB. Default is now `false` (reject).
     * Set `true` only if you control the rendered HTML and need local
     * file embedding (e.g. tests or offline tooling).
     */
    allowFileUrls?: boolean;
}
interface EpubContent {
    id: string;
    href: string;
    title: string;
    data: string;
    url: string | null;
    author: Array<string>;
    filePath: string;
    templatePath: string;
    excludeFromToc: boolean;
    beforeToc: boolean;
    ornamentalBreakElement: string | null;
    isCover?: boolean;
}
interface EpubImage {
    id: string;
    url: string;
    dir: string;
    mediaType: string;
    extension: string;
}
export declare class EPub {
    uuid: string;
    title: string;
    description: string;
    cover: string | null;
    coverMediaType: string | null;
    coverExtension: string | null;
    coverDimensions: {
        width: number;
        height: number;
    };
    publisher: string;
    author: Array<string>;
    tocTitle: string;
    appendChapterTitles: boolean;
    includeToc: boolean;
    date: string;
    lang: string;
    css: string | null;
    fonts: Array<string>;
    content: Array<EpubContent>;
    images: Array<EpubImage>;
    customOpfTemplatePath: string | null;
    customNcxTocTemplatePath: string | null;
    customHtmlCoverTemplatePath: string | null;
    customHtmlContentTemplatePath: string | null;
    customHtmlTocTemplatePath: string | null;
    version: number;
    userAgent: string;
    verbose: boolean;
    tempDir: string;
    tempEpubDir: string;
    output: string;
    zipCompressionLevel: number;
    imageDownloadConcurrency: number;
    assetFailureMode: "warn" | "throw";
    allowFileUrls: boolean;
    /**
     * Populated during `render()` with one entry per inline-image or
     * cover-image fetch that failed in `"warn"` mode. Empty in `"throw"`
     * mode (the first failure short-circuits the render). Returned on the
     * `render()` result so callers can decide whether to ship the EPUB.
     */
    warnings: string[];
    private imagesByUrl;
    private httpClient;
    constructor(options: EpubOptions, output: string);
    render(): Promise<{
        result: string;
        warnings: string[];
    }>;
    private generateTempFile;
    private makeCover;
    private downloadImage;
    private downloadAllImage;
    private generate;
}
export {};