@storyteller-platform/epub 0.4.10 → 0.5.0

package/dist/upgrade.d.cts

@@ -0,0 +1,909 @@
+import { XMLParser, XMLBuilder } from 'fast-xml-parser';
+
+interface Landmark {
+    href: string;
+    title: string;
+    type: string;
+}
+interface Epub2UpgradeOptions {
+    /**
+     * The path to the output file. If provided, the input file will be copied to the output path.
+     */
+    outputPath?: string;
+    /**
+     * Whether to remove the NCX file, as it's technically optional in EPUB 3.
+     */
+    removeNcx?: boolean;
+}
+declare function upgradeIdentifiers(pkg: PackageElement): void;
+declare function upgradeTitle(pkg: PackageElement): void;
+declare function upgradeLanguages(pkg: PackageElement): void;
+declare function upgradeAuthors(pkg: PackageElement): void;
+declare function upgradeDate(pkg: PackageElement): void;
+declare function upgradeMeta(pkg: PackageElement): void;
+declare function upgradeCover(pkg: PackageElement): void;
+declare function removeInvalidDcAttrs(pkg: PackageElement): void;
+declare function setLastModified(pkg: PackageElement): void;
+declare function upgradePackageMetadata(pkg: PackageElement): void;
+declare function extractGuideLandmarks(pkg: PackageElement): Landmark[];
+declare function removeGuide(pkg: PackageElement): void;
+declare function removeSpineTocRef(pkg: PackageElement): void;
+declare function collectManifestProperties(epub: Epub): Promise<void>;
+declare function fixFontMimeTypes(pkg: PackageElement): void;
+declare function buildTocOl(entries: NavigationItem[]): XmlElement<"ol">;
+declare function buildNavDocument(epub: Epub, tocEntries: NavigationItem[], landmarks: Landmark[]): Promise<string>;
+declare function setPackageVersion(pkg: PackageElement, version: string): void;
+declare function chooseNavHref(epub: Epub): Promise<string>;
+declare function removeNcx(epub: Epub): Promise<void>;
+
+declare global {
+    namespace Intl {
+        interface Locale {
+            textInfo: {
+                direction: "rtl" | "ltr";
+            };
+        }
+    }
+}
+type Letter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
+type QuestionMark = "?";
+/** A valid name for an XML element (must start with a letter) */
+type ElementName = `${Letter | Uppercase<Letter> | QuestionMark}${string}`;
+type PropertyPrefix = "@_";
+/** An XML element */
+type XmlElement<Name extends ElementName = ElementName> = {
+    ":@"?: Record<`${PropertyPrefix}${string}`, string>;
+} & {
+    [key in Name]: ParsedXml;
+};
+/** A text node in an XML document */
+type XmlTextNode = {
+    "#text": string;
+};
+/** A valid XML node. May be either an element or a text node. */
+type XmlNode = XmlElement | XmlTextNode;
+/** An XML structure */
+type ParsedXml = Array<XmlNode>;
+type ManifestItem = {
+    id: string;
+    href: string;
+    mediaType?: string | undefined;
+    fallback?: string | undefined;
+    mediaOverlay?: string | undefined;
+    properties?: string[] | undefined;
+};
+type MetadataEntry = {
+    id?: string | undefined;
+    type: ElementName;
+    properties: Record<string, string>;
+    value: string | undefined;
+};
+type EpubMetadata = MetadataEntry[];
+interface DcSubject {
+    value: string;
+    authority: string;
+    term: string;
+}
+interface AlternateScript {
+    name: string;
+    locale: Intl.Locale;
+}
+interface DcCreator {
+    name: string;
+    role?: string;
+    roleScheme?: string;
+    fileAs?: string;
+    alternateScripts?: AlternateScript[];
+}
+interface DublinCore {
+    title: string;
+    language: Intl.Locale;
+    identifier: string;
+    date?: Date;
+    subjects?: Array<string | DcSubject>;
+    creators?: DcCreator[];
+    contributors?: DcCreator[];
+    type?: string;
+}
+interface Collection {
+    name: string;
+    type?: string;
+    position?: string;
+}
+interface NavigationItem {
+    title: string;
+    href?: string;
+    children?: NavigationList;
+}
+type NavigationList = NavigationItem[];
+interface Navigation {
+    title?: string;
+    children: NavigationList;
+}
+interface GuideItem {
+    href: string;
+    title: string;
+    type: string;
+}
+type PackageElement = XmlElement<"package">;
+declare class EpubVersionError extends Error {
+}
+/**
+ * A single EPUB instance.
+ *
+ * The entire EPUB contents will be read into memory.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * import { Epub, getBody, findByName, textContent } from '@storyteller-platform/epub';
+ *
+ * const epub = await Epub.from('./path/to/book.epub');
+ * const title = await epub.getTitle();
+ * const spineItems = await epub.getSpineItems();
+ * const chptOne = spineItems[0];
+ * const chptOneXml = await epub.readXhtmlItemContents(chptOne.id);
+ *
+ * const body = getBody(chptOneXml);
+ * const h1 = Epub.findXmlChildByName('h1', body);
+ * const headingText = textContent(h1);
+ *
+ * await epub.setTitle(headingText);
+ * await epub.writeToFile('./path/to/updated.epub');
+ * await epub.close();
+ * ```
+ *
+ * @link https://www.w3.org/TR/epub-33/
+ */
+declare class Epub {
+    protected extractPath: string;
+    protected inputPath: string | undefined;
+    static xmlParser: XMLParser;
+    static xhtmlParser: XMLParser;
+    static xmlBuilder: XMLBuilder;
+    static xhtmlBuilder: XMLBuilder;
+    /**
+     * Format a duration, provided as a number of seconds, as
+     * a SMIL clock value, to be used for Media Overlays.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-duration
+     */
+    static formatSmilDuration(duration: number): string;
+    /**
+     * Given an XML structure representing a complete XHTML document,
+     * add a `link` element to the `head` of the document.
+     *
+     * This method modifies the provided XML structure.
+     */
+    static addLinkToXhtmlHead(xml: ParsedXml, link: {
+        rel: string;
+        href: string;
+        type: string;
+    }): void;
+    /**
+     * Given an XML structure representing a complete XHTML document,
+     * return the sub-structure representing the children of the
+     * document's body element.
+     */
+    static getXhtmlBody(xml: ParsedXml): ParsedXml;
+    static createXmlElement<Name extends ElementName>(name: Name, properties: Record<string, string>, children?: XmlNode[]): XmlElement<Name>;
+    static createXmlTextNode(text: string): XmlTextNode;
+    /**
+     * Given an XML structure representing a complete XHTML document,
+     * return a string representing the concatenation of all text nodes
+     * in the document.
+     */
+    static getXhtmlTextContent(xml: ParsedXml): string;
+    /**
+     * Given an XMLElement, return its attributes.
+     */
+    static getXmlAttributes(element: XmlElement): Record<string, string>;
+    /**
+     * Given an XMLElement, return its tag name.
+     */
+    static getXmlElementName<Name extends ElementName>(element: XmlElement<Name>): Name;
+    /**
+     * Given an XMLElement, return a list of its children
+     */
+    static getXmlChildren<Name extends ElementName>(element: XmlElement<Name>): ParsedXml;
+    static replaceXmlChildren<Name extends ElementName>(element: XmlElement<Name>, children: XmlNode[]): void;
+    /**
+     * Given an XML structure, find the first child matching
+     * the provided name and optional filter.
+     */
+    static findXmlChildByName<Name extends ElementName>(name: Name, xml: ParsedXml, filter?: (node: XmlElement<Name>) => boolean): XmlElement<Name> | undefined;
+    /**
+     * Given an XML structure, find the first descendant matching
+     * the provided name and optional filter.
+     *
+     * Will perform a breadth first search for the element, returning
+     * the highest element in the tree matching the name and filter.
+     */
+    static findXmlDescendantByName<Name extends ElementName>(name: Name, xml: ParsedXml, filter?: (node: XmlElement<Name>) => boolean): XmlElement<Name> | undefined;
+    /**
+     * Given an XMLNode, determine whether it represents
+     * a text node or an XML element.
+     */
+    static isXmlTextNode(node: XmlNode): node is XmlTextNode;
+    private rootfile;
+    private manifest;
+    private spine;
+    private packageMutex;
+    protected constructor(extractPath: string, inputPath: string | undefined);
+    /**
+     * Construct an Epub instance, optionally beginning
+     * with the provided metadata.
+     *
+     * @param dublinCore Core metadata terms
+     * @param additionalMetadata An array of additional metadata entries
+     */
+    static create(path: string, { title, language, identifier, date, subjects, type, creators, contributors, }: DublinCore, additionalMetadata?: EpubMetadata): Promise<Epub>;
+    /**
+     * Construct an Epub instance by reading an existing EPUB
+     * publication.
+     *
+     * @param pathOrData Must be either a string representing the
+     *        path to an EPUB file on disk, or a Uint8Array representing
+     *        the data of the EPUB publication.
+     */
+    static from(pathOrData: string | Uint8Array): Promise<Epub>;
+    /**
+     * Open an EPUB publication and return an Epub instance.
+     */
+    private static open;
+    copy(path?: string): Promise<Epub>;
+    private removeEntry;
+    private getFileData;
+    getRootfile(): Promise<string>;
+    private getPackageDocument;
+    private getPackageElement;
+    /**
+     * Safely modify the package document, without race conditions.
+     *
+     * Since the reading the package document is an async process,
+     * multiple simultaneously dispatched function calls that all
+     * attempt to modify it can clobber each other's changes. This
+     * method uses a mutex to ensure that each update runs exclusively.
+     *
+     * @param producer The function to update the package document. If
+     *    it returns a new package document, that will be persisted, otherwise
+     *    it will be assumed that the package document was modified in place.
+     */
+    private withPackage;
+    /**
+     * Retrieve the manifest for the Epub.
+     *
+     * This is represented as a map from each manifest items'
+     * id to the rest of its properties.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-manifest
+     */
+    getManifest(): Promise<Record<string, ManifestItem>>;
+    /**
+     * Returns the first index in the metadata element's children array
+     * that matches the provided predicate.
+     *
+     * Note: This may technically be different than the index in the
+     * getMetadata() array, as it includes non-metadata nodes, like
+     * text nodes. These are technically not allowed, but may exist,
+     * nonetheless. As consumers only ever see the getMetadata()
+     * array, this method is only meant to be used internally.
+     */
+    private findMetadataIndex;
+    /**
+     * Returns the item in the metadata element's children array
+     * that matches the provided predicate.
+     */
+    findMetadataItem(predicate: (entry: MetadataEntry) => boolean): Promise<{
+        id: string | undefined;
+        type: `a${string}` | `b${string}` | `c${string}` | `d${string}` | `e${string}` | `f${string}` | `g${string}` | `h${string}` | `i${string}` | `j${string}` | `k${string}` | `l${string}` | `m${string}` | `n${string}` | `o${string}` | `p${string}` | `q${string}` | `r${string}` | `s${string}` | `t${string}` | `u${string}` | `v${string}` | `w${string}` | `x${string}` | `y${string}` | `z${string}` | `A${string}` | `B${string}` | `C${string}` | `D${string}` | `E${string}` | `F${string}` | `G${string}` | `H${string}` | `I${string}` | `J${string}` | `K${string}` | `L${string}` | `M${string}` | `N${string}` | `O${string}` | `P${string}` | `Q${string}` | `R${string}` | `S${string}` | `T${string}` | `U${string}` | `V${string}` | `W${string}` | `X${string}` | `Y${string}` | `Z${string}` | `?${string}`;
+        properties: {
+            [k: string]: string;
+        };
+        value: string | undefined;
+    } | null>;
+    /**
+     * Returns the item in the metadata element's children array
+     * that matches the provided predicate.
+     */
+    findAllMetadataItems(predicate: (entry: MetadataEntry) => boolean): Promise<{
+        id: string | undefined;
+        type: `a${string}` | `b${string}` | `c${string}` | `d${string}` | `e${string}` | `f${string}` | `g${string}` | `h${string}` | `i${string}` | `j${string}` | `k${string}` | `l${string}` | `m${string}` | `n${string}` | `o${string}` | `p${string}` | `q${string}` | `r${string}` | `s${string}` | `t${string}` | `u${string}` | `v${string}` | `w${string}` | `x${string}` | `y${string}` | `z${string}` | `A${string}` | `B${string}` | `C${string}` | `D${string}` | `E${string}` | `F${string}` | `G${string}` | `H${string}` | `I${string}` | `J${string}` | `K${string}` | `L${string}` | `M${string}` | `N${string}` | `O${string}` | `P${string}` | `Q${string}` | `R${string}` | `S${string}` | `T${string}` | `U${string}` | `V${string}` | `W${string}` | `X${string}` | `Y${string}` | `Z${string}` | `?${string}`;
+        properties: {
+            [k: string]: string;
+        };
+        value: string | undefined;
+    }[]>;
+    private static parseMetadataItem;
+    /**
+     * Retrieve the metadata entries for the Epub.
+     *
+     * This is represented as an array of metadata entries,
+     * in the order that they're presented in the Epub package document.
+     *
+     * For more useful semantic representations of metadata, use
+     * specific methods such as `getTitle()` and `getAuthors()`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-metadata
+     */
+    getMetadata(): Promise<EpubMetadata>;
+    /**
+     * Retrieve the identifier from the dc:identifier element
+     * in the EPUB metadata.
+     *
+     * If there is no dc:identifier element, returns null.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     */
+    getIdentifier(): Promise<string | null>;
+    /**
+     * Set the dc:identifier metadata element with the provided string.
+     *
+     * Updates the existing dc:identifier element if one exists.
+     * Otherwise creates a new element
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     */
+    setIdentifier(identifier: string): Promise<void>;
+    /**
+     * Even "EPUB 3" publications sometimes still only use the
+     * EPUB 2 specification for identifying the cover image.
+     * This is a private method that is used as a fallback if
+     * we fail to find the cover image according to the EPUB 3
+     * spec.
+     */
+    private getEpub2CoverImage;
+    /**
+     * Retrieve the cover image manifest item.
+     *
+     * This does not return the actual image data. To
+     * retrieve the image data, pass this item's id to
+     * epub.readItemContents, or use epub.getCoverImage()
+     * instead.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-cover-image
+     */
+    getCoverImageItem(): Promise<ManifestItem | null>;
+    /**
+     * Retrieve the cover image data as a byte array.
+     *
+     * This does not include, for example, the cover image's
+     * filename or mime type. To retrieve the image manifest
+     * item, use epub.getCoverImageItem().
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-cover-image
+     */
+    getCoverImage(): Promise<Uint8Array<ArrayBufferLike> | null>;
+    /**
+     * Set the cover image for the EPUB.
+     *
+     * Adds a manifest item with the `cover-image` property, per
+     * the EPUB 3 spec, and then writes the provided image data to
+     * the provided href within the publication.
+     */
+    setCoverImage(href: string, data: Uint8Array): Promise<void>;
+    /**
+     * Retrieve the publication date from the dc:date element
+     * in the EPUB metadata as a Date object.
+     *
+     * If there is no dc:date element, returns null.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcdate
+     */
+    getPublicationDate(): Promise<Date | null>;
+    /**
+     * Set the dc:date metadata element with the provided date.
+     *
+     * Updates the existing dc:date element if one exists.
+     * Otherwise creates a new element
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcdate
+     */
+    setPublicationDate(date: Date): Promise<void>;
+    /**
+     * Retrieve the modified date from the dcterms:modified metadata
+     * in the EPUB metadata as a Date object.
+     *
+     * If there is no meta element with dcterms:modified, returns null.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-metadata-last-modified
+     */
+    getModifiedDate(): Promise<Date | null>;
+    /**
+     * Retrieve the layout from the rendition:layout meta element
+     * in the EPUB metadata.
+     *
+     * If there is no meta element, returns 'reflowable'.
+     *
+     * @link https://www.w3.org/TR/epub-33/#layout
+     */
+    getLayout(): Promise<"reflowable" | "pre-paginated">;
+    /**
+     * Retrieve the base direction from the package element.
+     *
+     * If there is no `dir` attribute on the package element,
+     * returns 'auto'.
+     *
+     * @link https://www.w3.org/TR/epub-33/#attrdef-dir
+     */
+    getBaseDirection(): Promise<"ltr" | "rtl" | "auto">;
+    /**
+     * Set the dc:type metadata element.
+     *
+     * Updates the existing dc:type element if one exists.
+     * Otherwise creates a new element.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dctype
+     */
+    setType(type: string): Promise<void>;
+    /**
+     * Retrieve the publication type from the dc:type element
+     * in the EPUB metadata.
+     *
+     * If there is no dc:type element, returns null.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dctype
+     */
+    getType(): Promise<MetadataEntry | null>;
+    /**
+     * Add a subject to the EPUB metadata.
+     *
+     * @param subject May be a string representing just a schema-less
+     *  subject name, or a DcSubject object
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsubject
+     */
+    addSubject(subject: string | DcSubject): Promise<void>;
+    /**
+     * Remove a subject from the EPUB metadata.
+     *
+     * Removes the subject at the provided index. This index
+     * refers to the array returned by `epub.getSubjects()`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+     */
+    removeSubject(index: number): Promise<void>;
+    /**
+     * Retrieve the list of subjects for this EPUB.
+     *
+     * Subjects without associated authority and term metadata
+     * will be returned as strings. Otherwise, they will
+     * be represented as DcSubject objects, with a value,
+     * authority, and term.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsubject
+     */
+    getSubjects(): Promise<(string | DcSubject)[]>;
+    /**
+     * Retrieve the Epub's language as specified in its
+     * package document metadata.
+     *
+     * If no language metadata is specified, returns null.
+     * Returns the language as an Intl.Locale instance.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dclanguage
+     */
+    getLanguage(): Promise<Intl.Locale | null>;
+    /**
+     * Update the Epub's language metadata entry.
+     *
+     * Updates the existing dc:language element if one exists.
+     * Otherwise creates a new element
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dclanguage
+     */
+    setLanguage(locale: Intl.Locale): Promise<void>;
+    /**
+     * Retrieve the title of the Epub.
+     *
+     * @param main Optional - whether to return only the first title segment
+     *  if multiple are found. Otherwise, will follow the spec to combine title
+     *  segments
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dctitle
+     */
+    getTitle(expanded?: boolean): Promise<string | null>;
+    /**
+     * Retrieve the subtitle of the Epub, if it exists.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dctitle
+     */
+    getSubtitle(): Promise<string | null>;
+    /**
+     * Retrieve all title entries of the Epub.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dctitle
+     */
+    getTitles(): Promise<{
+        title: string;
+        type: string | null;
+    }[]>;
+    /**
+     * Update the Epub's description metadata entry.
+     *
+     * Updates the existing dc:description element if one exists.
+     * Otherwise creates a new element. Any non-ASCII symbols,
+     * `&`, `<`, `>`, `"`, `'`, and `\``` will be encoded as HTML entities.
+     */
+    setDescription(description: string): Promise<void>;
+    /**
+     * Retrieve the Epub's description as specified in its
+     * package document metadata.
+     *
+     * If no description metadata is specified, returns null.
+     * Returns the description as a string. Descriptions may
+     * include HTML markup.
+     */
+    getDescription(): Promise<string | null>;
+    /**
+     * Return the set of custom vocabulary prefixes set on this publication's
+     * root package element.
+     *
+     * Returns a map from prefix to URI
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-prefix-attr
+     */
+    getPackageVocabularyPrefixes(): Promise<Record<string, string>>;
+    /**
+     * Set a custom vocabulary prefix on the root package element.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-prefix-attr
+     */
+    setPackageVocabularyPrefix(prefix: string, uri: string): Promise<void>;
+    /**
+     * Set the title of the Epub.
+     *
+     * This will replace all existing dc:title elements with
+     * this title. It will be given title-type "main".
+     *
+     * To set specific titles and their types, use epub.setTitles().
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dctitle
+     */
+    setTitle(title: string): Promise<void>;
+    setTitles(entries: {
+        title: string;
+        type: string | null;
+    }[]): Promise<void>;
+    /**
+     * Retrieve the list of collections.
+     */
+    getCollections(): Promise<Collection[]>;
+    /**
+     * Add a collection to the EPUB metadata.
+     *
+     * If index is provided, the collection will be placed at
+     * that index in the list of collections. Otherwise, it
+     * will be added to the end of the list.
+     */
+    addCollection(collection: Collection, index?: number): Promise<void>;
+    /**
+     * Remove a collection from the EPUB metadata.
+     *
+     * Removes the collection at the provided index. This index
+     * refers to the array returned by `epub.getCollections()`.
+     */
+    removeCollection(index: number): Promise<void>;
+    /**
+     * Retrieve the list of creators.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+     */
+    getCreators(type?: "creator" | "contributor"): Promise<DcCreator[]>;
+    /**
+     * Retrieve the list of contributors.
+     *
+     * This is a convenience method for
+     * `epub.getCreators('contributor')`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccontributor
+     */
+    getContributors(): Promise<DcCreator[]>;
+    /**
+     * Add a creator to the EPUB metadata.
+     *
+     * If index is provided, the creator will be placed at
+     * that index in the list of creators. Otherwise, it
+     * will be added to the end of the list.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+     */
+    addCreator(creator: DcCreator, index?: number, type?: "creator" | "contributor"): Promise<void>;
+    /**
+     * Remove a creator from the EPUB metadata.
+     *
+     * Removes the creator at the provided index. This index
+     * refers to the array returned by `epub.getCreators()`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+     */
+    removeCreator(index: number, type?: "creator" | "contributor"): Promise<void>;
+    /**
+     * Remove a contributor from the EPUB metadata.
+     *
+     * Removes the contributor at the provided index. This index
+     * refers to the array returned by `epub.getContributors()`.
+     *
+     * This is a convenience method for
+     * `epub.removeCreator(index, 'contributor')`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+     */
+    removeContributor(index: number): Promise<void>;
+    /**
+     * Add a contributor to the EPUB metadata.
+     *
+     * If index is provided, the creator will be placed at
+     * that index in the list of creators. Otherwise, it
+     * will be added to the end of the list.
+     *
+     * This is a convenience method for
+     * `epub.addCreator(contributor, index, 'contributor')`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dccreator
+     */
+    addContributor(contributor: DcCreator, index?: number): Promise<void>;
+    private getSpine;
+    /**
+     * Retrieve the manifest items that make up the Epub's spine.
+     *
+     * The spine specifies the order that the contents of the Epub
+     * should be displayed to users by default.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-spine-elem
+     */
+    getSpineItems(): Promise<ManifestItem[]>;
+    /**
+     * Add an item to the spine of the EPUB.
+     *
+     * If `index` is undefined, the item will be added
+     * to the end of the spine. Otherwise it will be
+     * inserted at the specified index.
+     *
+     * If the manifestId does not correspond to an item
+     * in the manifest, this will throw an error.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-spine-elem
+     */
+    addSpineItem(manifestId: string, index?: number): Promise<void>;
+    /**
+     * Remove the spine item at the specified index.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-spine-elem
+     */
+    removeSpineItem(index: number): Promise<void>;
+    private getNavigationChildren;
+    private getNavigation;
+    /**
+     * Returns the structured table of contents navigation document
+     * as a Navigation object.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-nav-toc
+     */
+    getTableOfContents({ resolveToRoot, }?: {
+        resolveToRoot?: boolean;
+    }): Promise<Navigation | null>;
+    /**
+     * Returns the structured landmarks navigation document
+     * as a Navigation object
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-nav-landmarks
+     */
+    getLandmarks({ resolveToRoot, }?: {
+        resolveToRoot?: boolean;
+    }): Promise<Navigation | null>;
+    /**
+     * Returns the structured page list navigation document
+     * as a Navigation object
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-nav-landmarks
+     */
+    getPageList({ resolveToRoot, }?: {
+        resolveToRoot?: boolean;
+    }): Promise<Navigation | null>;
+    /**
+     * Returns a Zip Entry path for an HREF
+     */
+    private resolveInternalHref;
+    /**
+     * Returns a path-relative-scheme-less URL, relative to the
+     * container root.
+     *
+     * @param href The href to resolve
+     * @param [relativeTo] Optional - The href to resolve this href relative to.
+         Use if resolving a relative href from a file other than the package document.
+     */
+    resolveHref(href: string, relativeTo?: string, { toRoot }?: {
+        toRoot?: boolean | undefined;
+    }): Promise<string>;
+    /**
+     * Retrieve the contents of a file, given its href.
+     *
+     * Optionally takes the href that this href should be resolved relative to,
+     * and an encoding parameter.
+     *
+     * @param href The href of the file to retrieve
+     * @param [relitaveTo] Optional - The href to resolve this href relative to.
+     *   Use if resolving a relative href from a file other than the package document.
+     * @param [encoding] Optional - Must be the string "utf-8". If provided,
+     *   the function will encode the data into a unicode string.
+     *   Otherwise, the data will be returned as a byte array.
+     */
+    readFileContents(href: string, relativeTo?: string): Promise<Uint8Array>;
+    readFileContents(href: string, relativeTo: string | undefined, encoding: "utf-8"): Promise<string>;
+    /**
+     * Retrieve the contents of a manifest item, given its id.
+     *
+     * @param id The id of the manifest item to retrieve
+     * @param [encoding] Optional - must be the string "utf-8". If
+     *  provided, the function will encode the data into a unicode string.
+     *  Otherwise, the data will be returned as a byte array.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-contentdocs
+     */
+    readItemContents(id: string): Promise<Uint8Array>;
+    readItemContents(id: string, encoding: "utf-8"): Promise<string>;
+    /**
+     * Create a new XHTML document with the given body
+     * and head.
+     *
+     * @param body The XML nodes to place in the body of the document
+     * @param head Optional - the XMl nodes to place in the head
+     * @param language Optional - defaults to the EPUB's language
+     */
+    createXhtmlDocument(body: ParsedXml, head?: ParsedXml, language?: Intl.Locale): Promise<(XmlElement<"html"> | XmlElement<"?xml">)[]>;
+    /**
+     * Retrieves the contents of an XHTML item, given its manifest id.
+     *
+     * @param id The id of the manifest item to retrieve
+     * @param [as] Optional - whether to return the parsed XML document tree,
+     *  or the concatenated text of the document. Defaults to the parsed XML tree.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-xhtml
+     */
+    readXhtmlItemContents(id: string, as?: "xhtml"): Promise<ParsedXml>;
+    readXhtmlItemContents(id: string, as: "text"): Promise<string>;
+    private writeEntryContents;
+    /**
+     * Write new contents for an existing manifest item,
+     * specified by its id.
+     *
+     * The id must reference an existing manifest item. If
+     * creating a new item, use `epub.addManifestItem()` instead.
+     *
+     * @param id The id of the manifest item to write new contents for
+     * @param contents The new contents. May be either a utf-8 encoded string
+     *  or a byte array, as determined by the encoding
+     * @param [encoding] Optional - must be the string "utf-8". If provided,
+     *  the contents will be interpreted as a unicode string. Otherwise, the
+     *  contents must be a byte array.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-contentdocs
+     */
+    writeItemContents(id: string, contents: Uint8Array): Promise<void>;
+    writeItemContents(id: string, contents: string, encoding: "utf-8"): Promise<void>;
+    /**
+     * Write new contents for an existing XHTML item,
+     * specified by its id.
+     *
+     * The id must reference an existing manifest item. If
+     * creating a new item, use `epub.addManifestItem()` instead.
+     *
+     * @param id The id of the manifest item to write new contents for
+     * @param contents The new contents. Must be a parsed XML tree.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-xhtml
+     */
+    writeXhtmlItemContents(id: string, contents: ParsedXml): Promise<void>;
+    removeManifestItem(id: string): Promise<void>;
+    /**
+     * Create a new manifest item and write its contents to a
+     * new entry.
+     *
+     * @param id The id of the manifest item to write new contents for
+     * @param contents The new contents. May be either a parsed XML tree
+     *  or a unicode string, as determined by the `as` argument.
+     * @param encoding Optional - whether to interpret contents as a parsed
+     *  XML tree, a unicode string, or a byte array. Defaults to a byte array.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-manifest
+     * @link https://www.w3.org/TR/epub-33/#sec-contentdocs
+     */
+    addManifestItem(item: ManifestItem, contents: ParsedXml, encoding: "xml"): Promise<void>;
+    addManifestItem(item: ManifestItem, contents: string, encoding: "utf-8"): Promise<void>;
+    addManifestItem(item: ManifestItem, contents: Uint8Array): Promise<void>;
+    /**
+     * Update the manifest entry for an existing item.
+     *
+     * To update the contents of an entry, use `epub.writeItemContents()`
+     * or `epub.writeXhtmlItemContents()`
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-manifest
+     */
+    updateManifestItem(id: string, newItem: Omit<ManifestItem, "id">): Promise<void>;
+    /**
+     * Add a new metadata entry to the Epub.
+     *
+     * This method, like `epub.getMetadata()`, operates on
+     * metadata entries. For more useful semantic representations
+     * of metadata, use specific methods such as `setTitle()` and
+     * `setLanguage()`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-metadata
+     */
+    addMetadata(entry: MetadataEntry): Promise<void>;
+    /**
+     * Replace a metadata entry with a new one.
+     *
+     * The `predicate` argument will be used to determine which entry
+     * to replace. The first metadata entry that matches the
+     * predicate will be replaced.
+     *
+     * @param predicate Calls predicate once for each metadata entry,
+     *  until it finds one where predicate returns true
+     * @param entry The new entry to replace the found entry with
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-metadata
+     */
+    replaceMetadata(predicate: (entry: MetadataEntry) => boolean, entry: MetadataEntry): Promise<void>;
+    /**
+     * Remove one or more metadata entries.
+     *
+     * The `predicate` argument will be used to determine which entries
+     * to remove. The all metadata entries that match the
+     * predicate will be removed.
+     *
+     * @param predicate Calls predicate once for each metadata entry,
+     *  removing any for which it returns true
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-pkg-metadata
+     */
+    removeMetadata(predicate: (entry: MetadataEntry) => boolean): Promise<void>;
+    /**
+     * Returns the EPUB version declared on the package element.
+     */
+    getVersion(): Promise<string>;
+    /**
+     * Parse the NCX table of contents, if one exists, and return
+     * a tree of TocEntry nodes.
+     *
+     * Useful for both EPUB 2 publications (where the NCX is the
+     * primary navigation) and EPUB 3 publications that retain an
+     * NCX for backwards compatibility.
+     */
+    getNcxTableOfContents(): Promise<NavigationList>;
+    private parseNavPoints;
+    /**
+     * Retrieve the guide entries from the package document.
+     *
+     * The guide element is deprecated in EPUB 3 in favor of
+     * the landmarks nav, but many publications still include it.
+     */
+    getGuideEntries(): Promise<GuideItem[]>;
+    discardAndClose(): void;
+    /**
+     * Write the current contents of the Epub to a new
+     * EPUB archive on disk.
+     *
+     * When this method is called, the "dcterms:modified"
+     * meta tag is automatically updated to the current UTC
+     * timestamp.
+     */
+    saveAndClose(): Promise<void>;
+    /**
+     * Upgrade an EPUB 2 publication to EPUB 3 in place, returning a new, valid Epub 3 instance.
+     *
+     * Performs the following transformations:
+     *  - upgrades OPF metadata to EPUB 3 conventions
+     *  - scans XHTML documents and adds manifest item properties
+     *  - parses the NCX into a TOC tree and generates a nav.xhtml
+     *  - removes the NCX file and the guide element (configurable)
+     *  - fixes common font MIME types
+     *  - bumps the package version to 3.0
+     *  - goes over each xhtml item and rewrites it using XMLParser to make sure the output is valid XHTML
+     */
+    static upgrade(path: string, options?: Epub2UpgradeOptions): Promise<Epub>;
+    [Symbol.dispose](): void;
+}
+
+export { type AlternateScript as A, type Collection as C, type DcSubject as D, type ElementName as E, type Epub2UpgradeOptions, type Landmark, type ManifestItem as M, type NavigationItem as N, type ParsedXml as P, type XmlElement as X, type XmlTextNode as a, type XmlNode as b, buildNavDocument, buildTocOl, type MetadataEntry as c, chooseNavHref, collectManifestProperties, type EpubMetadata as d, type DcCreator as e, extractGuideLandmarks, type DublinCore as f, fixFontMimeTypes, type NavigationList as g, type Navigation as h, type PackageElement as i, EpubVersionError as j, Epub as k, removeGuide, removeInvalidDcAttrs, removeNcx, removeSpineTocRef, setLastModified, setPackageVersion, upgradeAuthors, upgradeCover, upgradeDate, upgradeIdentifiers, upgradeLanguages, upgradeMeta, upgradePackageMetadata, upgradeTitle };