@storyteller-platform/epub 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,714 @@
+import { Entry } from '@zip.js/zip.js';
+import { XMLParser, XMLBuilder } from 'fast-xml-parser';
+
+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}`;
+/** An XML element */
+type XmlElement<Name extends ElementName = ElementName> = {
+    ":@"?: Record<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;
+};
+declare class EpubEntry {
+    filename: string;
+    private entry;
+    private data;
+    getData(): Promise<Uint8Array<ArrayBufferLike>>;
+    setData(data: Uint8Array): void;
+    constructor(entry: Entry | {
+        filename: string;
+        data: Uint8Array;
+    });
+}
+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;
+}
+type PackageElement = XmlElement<"package"> | XmlElement<"opf:package">;
+/**
+ * A single EPUB instance.
+ *
+ * The entire EPUB contents will be read into memory.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * import { Epub, getBody, findByName, textContent } from '@smoores/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 {
+    private entries;
+    private onClose?;
+    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 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: XmlNode) => 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 zipWriter;
+    private dataWriter;
+    private rootfile;
+    private manifest;
+    private spine;
+    private packageMutex;
+    protected constructor(entries: EpubEntry[], onClose?: (() => Promise<void> | void) | undefined);
+    /**
+     * Close the Epub. Must be called before the Epub goes out
+     * of scope/is garbage collected.
+     */
+    close(): Promise<void>;
+    /**
+     * 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({ 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>;
+    private getEntry;
+    private removeEntry;
+    private getFileData;
+    private getRootfile;
+    private migratePackageDocument;
+    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>;
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /**
+     * Returns a Zip Entry path for an HREF
+     */
+    private resolveHref;
+    /**
+     * 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<"?xml"> | XmlElement<"html">)[]>;
+    /**
+     * 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>;
+    /**
+     * Write the current contents of the Epub to a new
+     * Uint8Array.
+     *
+     * This _does not_ close the Epub. It can continue to
+     * be modified after it has been written to disk. Use
+     * `epub.close()` to close the Epub.
+     *
+     * When this method is called, the "dcterms:modified"
+     * meta tag is automatically updated to the current UTC
+     * timestamp.
+     */
+    writeToArray(): Promise<Uint8Array<ArrayBufferLike>>;
+}
+
+export { type AlternateScript, type Collection, type DcCreator, type DcSubject, type DublinCore, type ElementName, Epub, type EpubMetadata, type ManifestItem, type MetadataEntry, type PackageElement, type ParsedXml, type XmlElement, type XmlNode, type XmlTextNode };