@storyteller-platform/epub 0.6.3 → 0.7.1

package/dist/upgrade.cjs

@@ -41,6 +41,7 @@ __export(upgrade_exports, {
 });
 module.exports = __toCommonJS(upgrade_exports);
 var import_nanoid = require("nanoid");
+var import_media_types = require("@storyteller-platform/media-types");
 var import_index = require("./index.cjs");
 const GUIDE_TO_EPUBTYPE = {
   acknowledgements: "acknowledgments",
@@ -88,31 +89,7 @@ const GUIDE_TO_EPUBTYPE = {
   "other.volume": "volume",
   "other.warning": "warning"
 };
-const XHTML_MEDIA_TYPES = /* @__PURE__ */ new Set([
-  "application/xhtml+xml",
-  "application/vnd.adobe-page-template+xml",
-  "text/html"
-]);
-const OEB_FONTS = /* @__PURE__ */ new Set([
-  "application/vnd.ms-opentype",
-  "application/x-font-ttf",
-  "application/x-font-otf",
-  "application/x-font-truetype",
-  "application/font-sfnt",
-  "application/font-woff",
-  "application/font-woff2",
-  "font/woff",
-  "font/woff2",
-  "font/otf",
-  "font/ttf",
-  "font/sfnt"
-]);
-const FONT_MIME_BY_EXT = {
-  ".ttf": "application/font-sfnt",
-  ".otf": "application/font-sfnt",
-  ".woff": "application/font-woff",
-  ".woff2": "font/woff2"
-};
+const XHTML_MEDIA_TYPES = /* @__PURE__ */ new Set([import_media_types.MediaType.XHTML, import_media_types.MediaType.HTML]);
 function getMetadataElement(pkg) {
   return import_index.Epub.findXmlChildByName("metadata", import_index.Epub.getXmlChildren(pkg));
 }
@@ -389,11 +366,10 @@ function removeSpineTocRef(pkg) {
   delete spine[":@"]["@_toc"];
 }
 async function collectManifestProperties(epub) {
-  var _a;
   const manifest = await epub.getManifest();
   for (const item of Object.values(manifest)) {
-    const mediaType = ((_a = item.mediaType) == null ? void 0 : _a.toLowerCase()) ?? "";
-    if (!XHTML_MEDIA_TYPES.has(mediaType)) continue;
+    const mediaType = import_media_types.MediaType.fromMime(item.mediaType ?? "");
+    if (!mediaType || !XHTML_MEDIA_TYPES.has(mediaType)) continue;
     let xml;
     try {
       xml = await epub.readXhtmlItemContents(item.id);
@@ -414,21 +390,16 @@ async function collectManifestProperties(epub) {
   }
 }
 function fixFontMimeTypes(pkg) {
-  var _a, _b;
+  var _a, _b, _c;
   const manifest = getManifestElement(pkg);
   if (!manifest) return;
   for (const item of findAllByName("item", manifest.manifest)) {
-    const mt = (((_a = item[":@"]) == null ? void 0 : _a["@_media-type"]) ?? "").toLowerCase();
-    if (!OEB_FONTS.has(mt)) continue;
-    const href = ((_b = item[":@"]) == null ? void 0 : _b["@_href"]) ?? "";
-    const dotIdx = href.lastIndexOf(".");
-    if (dotIdx === -1) continue;
-    const ext = href.slice(dotIdx).toLowerCase();
-    const corrected = FONT_MIME_BY_EXT[ext];
-    if (corrected && corrected !== mt) {
-      item[":@"] ??= {};
-      item[":@"]["@_media-type"] = corrected;
-    }
+    const declared = ((_a = item[":@"]) == null ? void 0 : _a["@_media-type"]) ?? "";
+    if (!((_b = import_media_types.MediaType.fromMime(declared)) == null ? void 0 : _b.is("font"))) continue;
+    const corrected = import_media_types.MediaType.fromPath(((_c = item[":@"]) == null ? void 0 : _c["@_href"]) ?? "");
+    if (!(corrected == null ? void 0 : corrected.is("font")) || corrected.mime === declared) continue;
+    item[":@"] ??= {};
+    item[":@"]["@_media-type"] = corrected.mime;
   }
 }
 function buildTocOl(entries) {
@@ -521,10 +492,7 @@ async function chooseNavHref(epub) {
 async function removeNcx(epub) {
   const manifest = await epub.getManifest();
   const ncxItem = Object.values(manifest).find(
-    (item) => {
-      var _a;
-      return ((_a = item.mediaType) == null ? void 0 : _a.toLowerCase()) === "application/x-dtbncx+xml";
-    }
+    (item) => import_media_types.MediaType.fromMime(item.mediaType ?? "") === import_media_types.MediaType.NCX
   );
   if (ncxItem) {
     await epub.removeManifestItem(ncxItem.id);

package/dist/upgrade.d.cts

@@ -87,6 +87,31 @@ interface DcSubject {
     authority: string;
     term: string;
 }
+interface EpubIdentifier {
+    value: string;
+    id?: string | undefined;
+    /** the value of a refining `identifier-type` meta, if present */
+    identifierType?: string | undefined;
+    /** the `scheme` of a refining `identifier-type` meta, or a legacy `opf:scheme` attribute */
+    scheme?: string | undefined;
+}
+interface EpubSource {
+    value: string;
+    id?: string | undefined;
+    /** the value of a refining `identifier-type` meta, if present */
+    identifierType?: string | undefined;
+    /** the `scheme` of a refining `identifier-type` meta, or a legacy `opf:scheme` attribute */
+    scheme?: string | undefined;
+    /**
+     * whether this source has a `source-of="pagination"` refinement
+     * or of a `<meta property="pageBreakSource">` element
+     *
+     * as of EPUB 3.4 `source-of` is advised-deprecated in favour of the
+     * publication-level `pageBreakSource` property. if you want to
+     * be sure to get the source of pagination, use {@link Epub.getPageBreakSource}
+     */
+    isPageBreakSource?: boolean | undefined;
+}
 interface AlternateScript {
     name: string;
     locale: Intl.Locale;
@@ -140,7 +165,7 @@ interface FromOptions {
  * Read-only view of an EPUB
  * Returned by Epub.using(MemoryAdapter).from(...) and by Epub.from(path, { readonly: true })
  */
-type EpubReader = Pick<Epub, "storage" | "getManifest" | "getVersion" | "getLayout" | "getBaseDirection" | "getMetadata" | "findMetadataItem" | "findAllMetadataItems" | "getIdentifier" | "getTitle" | "getSubtitle" | "getTitles" | "getLanguage" | "getPublicationDate" | "getModifiedDate" | "getDescription" | "getType" | "getCreators" | "getContributors" | "getSubjects" | "getCollections" | "getPackageVocabularyPrefixes" | "getCoverImageItem" | "getCoverImage" | "getSpineItems" | "getNcxTableOfContents" | "getGuideEntries" | "getTableOfContents" | "getLandmarks" | "getPageList" | "resolveHref" | "readFileContents" | "readItemContents" | "readXhtmlItemContents" | "getItemArchiveLength" | "discardAndClose"> & Disposable;
+type EpubReader = Pick<Epub, "storage" | "findMetadataItem" | "findAllMetadataItems" | "resolveHref" | "readFileContents" | "readItemContents" | "readXhtmlItemContents" | "discardAndClose" | Extract<keyof Epub, `get${string}`>> & Disposable;
 /**
  * Readonly Epub-instance backed by an in-memory zip handle
  * Returned by `Epub.using(MemoryAdapter).from(...)`
@@ -314,10 +339,6 @@ declare class Epub {
     static assertEpub3(epub: Epub): Promise<void>;
     copy(path?: string): Promise<Epub>;
     private removeEntry;
-    /**
-     * Read raw bytes (or utf-8 text) from the underlying adapter
-     */
-    private getFileData;
     /**
      * Length of the underlying archive entry for a manifest item, in bytes
      * Necessary to compute the readium page count which is for COMPRESSED content
@@ -366,7 +387,7 @@ declare class Epub {
      */
     findMetadataItem(predicate: (entry: MetadataEntry) => boolean): Promise<{
         id: string | undefined;
-        type: `?${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}` | `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}`;
+        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;
         };
@@ -378,7 +399,7 @@ declare class Epub {
      */
     findAllMetadataItems(predicate: (entry: MetadataEntry) => boolean): Promise<{
         id: string | undefined;
-        type: `?${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}` | `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}`;
+        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;
         };
@@ -398,12 +419,15 @@ declare class Epub {
      */
     getMetadata(): Promise<EpubMetadata>;
     /**
-     * Retrieve the identifier from the dc:identifier element
+     * Retrieve the first 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
+     *
+     * @deprecated Use {@link getUniqueIdentifier} instead to get the unique identifier,
+     * or {@link getIdentifiers} to get all identifiers.
      */
     getIdentifier(): Promise<string | null>;
     /**
@@ -413,8 +437,130 @@ declare class Epub {
      * Otherwise creates a new element
      *
      * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     *
+     * @deprecated Use {@link setUniqueIdentifier} instead.
      */
     setIdentifier(identifier: string): Promise<void>;
+    /**
+     * Retrieve the identifier with the unique identifier id
+     * in the EPUB metadata.
+     *
+     * If there is no unique identifier id, returns the first dc:identifier element.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     */
+    getUniqueIdentifier(): Promise<string | null>;
+    /**
+     * Set the unique identifier id for the EPUB.
+     *
+     * Updates the existing dc:identifier element referenced by the unique identifier id if one exists.
+     * Otherwise creates a new element with the provided identifier, and sets the unique identifier id to the new element's id.
+     *
+     * Note: you likely shouldn't change the unique identifier id unless you are producing a new EPUB.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     */
+    setUniqueIdentifier(identifier: string): Promise<void>;
+    /**
+     * Retrieve the id of the publication's unique identifier, as declared by the
+     * package element's `unique-identifier` attribute.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     */
+    getUniqueIdentifierId(): Promise<string | null>;
+    /**
+     * Collect `dc:identifier` or `dc:source` entries, attaching the value and
+     * scheme of any refining `identifier-type` meta (spec D.3.8) and a legacy
+     * `opf:scheme` attribute. Values are not interpreted.
+     *
+     * `onRefinement` is invoked for every other meta refining a collected entry,
+     * so callers can surface element-specific refinements (e.g. `source-of` on a
+     * `dc:source`).
+     */
+    private static collectDcEntries;
+    /**
+     * Retrieve every `dc:identifier` entry, returned as found.
+     *
+     * Values are not interpreted. Any refining `identifier-type` meta (spec
+     * D.3.8) or legacy `opf:scheme` attribute is surfaced on the entry, but no
+     * parsing of the value itself is attempted. To read `dc:source` entries, use
+     * {@link getSources}.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     */
+    getIdentifiers(): Promise<EpubIdentifier[]>;
+    /**
+     * Retrieve every `dc:source` entry, returned as found.
+     *
+     * Like {@link getIdentifiers}, values are not interpreted. In addition to a
+     * refining `identifier-type`, a refining `source-of` meta (spec D.3.11) is
+     * surfaced as `sourceOf`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsource
+     */
+    getSources(): Promise<EpubSource[]>;
+    /**
+     * Retrieve the `pageBreakSource` property (EPUB 3.4, spec D.2.9), the
+     * publication-level source for the source of its page break markers.
+     *
+     * This property replaces the refining `source-of="pagination"` meta (spec
+     * D.3.11), see {@link EpubSource.sourceOf}. If no `pageBreakSource` property is found,
+     * we fall back to finding a `dc:source` with a `source-of="pagination"` refinement.
+     *
+     * @link https://www.w3.org/TR/epub/#pageBreakSource
+     */
+    getPageBreakSource(): Promise<EpubSource | null>;
+    /**
+     * Set the `pageBreakSource` property (EPUB 3.4, spec D.2.9), or remove it when
+     * passed null. Replaces an existing `pageBreakSource` meta if present.
+     *
+     * Pass `none` to indicate the pagination is unique to this publication.
+     *
+     * @link https://www.w3.org/TR/epub/#pageBreakSource
+     */
+    setPageBreakSource(value: string | null): Promise<void>;
+    /**
+     * Replace the publication's `dc:identifier` entries.
+     *
+     * This replaces ALL existing `dc:identifier` elements except the publication's
+     * unique identifier (the one referenced by the package element's
+     * `unique-identifier` attribute), which is always preserved and must not be
+     * included in the provided list. If included anyway, it is ignored. See
+     * {@link setUniqueIdentifier} to change it.
+     *
+     * Identifiers are placed in the order they are provided.
+     *
+     * `dc:source` entries are not touched, use {@link setSources} for those.
+     *
+     * When an entry has an `identifierType`, it is written in the refining form
+     * (a `meta` with `property="identifier-type"`, carrying the `scheme`
+     * attribute when provided). An entry with only a `scheme` is written using
+     * the legacy `opf:scheme` attribute.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     */
+    setIdentifiers(identifiers: EpubIdentifier[]): Promise<void>;
+    /**
+     * Remove `meta` refinements pointing at any of the given ids,
+     * restricted to the given `property` values as a cleanup step
+     * Mutates `children` in place.
+     */
+    private static removeRefiningMetas;
+    /**
+     * Replace the publication's `dc:source` entries.
+     *
+     * This replaces ALL existing `dc:source` elements (and their refining
+     * `identifier-type` / `source-of` metas). `dc:identifier` entries are not
+     * touched; use {@link setIdentifiers} for those. Pass an empty array to
+     * remove all sources.
+     *
+     * When an entry has an `identifierType`, it is written in the refining form.
+     * A `sourceOf` value is written as a refining `source-of` meta (spec D.3.11).
+     * An entry with only a `scheme` uses the legacy `opf:scheme` attribute.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsource
+     */
+    setSources(sources: EpubSource[]): Promise<void>;
     /**
      * Even "EPUB 3" publications sometimes still only use the
      * EPUB 2 specification for identifying the cover image.
@@ -772,13 +918,31 @@ declare class Epub {
         resolveToRoot?: boolean;
     }): Promise<Navigation | null>;
     /**
-     * Returns a Zip Entry path for an HREF
+     * Name the entry a resolved URL addresses.
+     *
+     * A correctly authored publication percent-encodes its hrefs, so the
+     * decoded reading is the one the spec calls for and the one we prefer.
+     * Some publications instead write the entry name verbatim, so when the two
+     * readings differ we ask the archive which one it holds. A verbatim name
+     * carrying a bare `%`, as `100%.xhtml` does, is not a valid encoding at all
+     * and can only be its own answer.
+     */
+    private entryForUrl;
+    /**
+     * Resolve an href to the name of the archive entry it addresses.
+     *
+     * @param from The entry the href appears in; it resolves against that
+     *   entry's directory
+     * @throws when the href addresses something outside the publication
      */
-    private resolveInternalHref;
+    private resolveEntry;
     /**
      * Returns a path-relative-scheme-less URL, relative to the
      * container root.
      *
+     * An href that points outside the publication, such as an external link in
+     * a navigation document, is handed back unchanged.
+     *
      * @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.
@@ -1029,4 +1193,4 @@ declare class EpubFactory<A extends EpubStorageAdapterClass> {
     upgrade(path: string, options?: Epub2UpgradeOptions): Promise<EpubInstanceFor<A>>;
 }
 
-export { type AlternateScript as A, type Collection as C, type DcSubject as D, type ElementName as E, type Epub2UpgradeOptions, type FromOptions as F, type InMemoryEpubReader as I, 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, type EpubReader as j, EpubVersionError as k, EpubReadOnlyError as l, Epub as m, type EpubInstanceFor as n, EpubFactory as o, removeGuide, removeInvalidDcAttrs, removeNcx, removeSpineTocRef, setLastModified, setPackageVersion, upgradeAuthors, upgradeCover, upgradeDate, upgradeIdentifiers, upgradeLanguages, upgradeMeta, upgradePackageMetadata, upgradeTitle };
+export { type AlternateScript as A, type Collection as C, type DcSubject as D, type ElementName as E, type Epub2UpgradeOptions, type FromOptions as F, type InMemoryEpubReader as I, 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 EpubIdentifier as e, extractGuideLandmarks, type EpubSource as f, fixFontMimeTypes, type DcCreator as g, type DublinCore as h, type NavigationList as i, type Navigation as j, type PackageElement as k, type EpubReader as l, EpubVersionError as m, EpubReadOnlyError as n, Epub as o, type EpubInstanceFor as p, EpubFactory as q, removeGuide, removeInvalidDcAttrs, removeNcx, removeSpineTocRef, setLastModified, setPackageVersion, upgradeAuthors, upgradeCover, upgradeDate, upgradeIdentifiers, upgradeLanguages, upgradeMeta, upgradePackageMetadata, upgradeTitle };

package/dist/upgrade.d.ts

@@ -87,6 +87,31 @@ interface DcSubject {
     authority: string;
     term: string;
 }
+interface EpubIdentifier {
+    value: string;
+    id?: string | undefined;
+    /** the value of a refining `identifier-type` meta, if present */
+    identifierType?: string | undefined;
+    /** the `scheme` of a refining `identifier-type` meta, or a legacy `opf:scheme` attribute */
+    scheme?: string | undefined;
+}
+interface EpubSource {
+    value: string;
+    id?: string | undefined;
+    /** the value of a refining `identifier-type` meta, if present */
+    identifierType?: string | undefined;
+    /** the `scheme` of a refining `identifier-type` meta, or a legacy `opf:scheme` attribute */
+    scheme?: string | undefined;
+    /**
+     * whether this source has a `source-of="pagination"` refinement
+     * or of a `<meta property="pageBreakSource">` element
+     *
+     * as of EPUB 3.4 `source-of` is advised-deprecated in favour of the
+     * publication-level `pageBreakSource` property. if you want to
+     * be sure to get the source of pagination, use {@link Epub.getPageBreakSource}
+     */
+    isPageBreakSource?: boolean | undefined;
+}
 interface AlternateScript {
     name: string;
     locale: Intl.Locale;
@@ -140,7 +165,7 @@ interface FromOptions {
  * Read-only view of an EPUB
  * Returned by Epub.using(MemoryAdapter).from(...) and by Epub.from(path, { readonly: true })
  */
-type EpubReader = Pick<Epub, "storage" | "getManifest" | "getVersion" | "getLayout" | "getBaseDirection" | "getMetadata" | "findMetadataItem" | "findAllMetadataItems" | "getIdentifier" | "getTitle" | "getSubtitle" | "getTitles" | "getLanguage" | "getPublicationDate" | "getModifiedDate" | "getDescription" | "getType" | "getCreators" | "getContributors" | "getSubjects" | "getCollections" | "getPackageVocabularyPrefixes" | "getCoverImageItem" | "getCoverImage" | "getSpineItems" | "getNcxTableOfContents" | "getGuideEntries" | "getTableOfContents" | "getLandmarks" | "getPageList" | "resolveHref" | "readFileContents" | "readItemContents" | "readXhtmlItemContents" | "getItemArchiveLength" | "discardAndClose"> & Disposable;
+type EpubReader = Pick<Epub, "storage" | "findMetadataItem" | "findAllMetadataItems" | "resolveHref" | "readFileContents" | "readItemContents" | "readXhtmlItemContents" | "discardAndClose" | Extract<keyof Epub, `get${string}`>> & Disposable;
 /**
  * Readonly Epub-instance backed by an in-memory zip handle
  * Returned by `Epub.using(MemoryAdapter).from(...)`
@@ -314,10 +339,6 @@ declare class Epub {
     static assertEpub3(epub: Epub): Promise<void>;
     copy(path?: string): Promise<Epub>;
     private removeEntry;
-    /**
-     * Read raw bytes (or utf-8 text) from the underlying adapter
-     */
-    private getFileData;
     /**
      * Length of the underlying archive entry for a manifest item, in bytes
      * Necessary to compute the readium page count which is for COMPRESSED content
@@ -366,7 +387,7 @@ declare class Epub {
      */
     findMetadataItem(predicate: (entry: MetadataEntry) => boolean): Promise<{
         id: string | undefined;
-        type: `?${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}` | `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}`;
+        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;
         };
@@ -378,7 +399,7 @@ declare class Epub {
      */
     findAllMetadataItems(predicate: (entry: MetadataEntry) => boolean): Promise<{
         id: string | undefined;
-        type: `?${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}` | `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}`;
+        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;
         };
@@ -398,12 +419,15 @@ declare class Epub {
      */
     getMetadata(): Promise<EpubMetadata>;
     /**
-     * Retrieve the identifier from the dc:identifier element
+     * Retrieve the first 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
+     *
+     * @deprecated Use {@link getUniqueIdentifier} instead to get the unique identifier,
+     * or {@link getIdentifiers} to get all identifiers.
      */
     getIdentifier(): Promise<string | null>;
     /**
@@ -413,8 +437,130 @@ declare class Epub {
      * Otherwise creates a new element
      *
      * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     *
+     * @deprecated Use {@link setUniqueIdentifier} instead.
      */
     setIdentifier(identifier: string): Promise<void>;
+    /**
+     * Retrieve the identifier with the unique identifier id
+     * in the EPUB metadata.
+     *
+     * If there is no unique identifier id, returns the first dc:identifier element.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     */
+    getUniqueIdentifier(): Promise<string | null>;
+    /**
+     * Set the unique identifier id for the EPUB.
+     *
+     * Updates the existing dc:identifier element referenced by the unique identifier id if one exists.
+     * Otherwise creates a new element with the provided identifier, and sets the unique identifier id to the new element's id.
+     *
+     * Note: you likely shouldn't change the unique identifier id unless you are producing a new EPUB.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     */
+    setUniqueIdentifier(identifier: string): Promise<void>;
+    /**
+     * Retrieve the id of the publication's unique identifier, as declared by the
+     * package element's `unique-identifier` attribute.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     */
+    getUniqueIdentifierId(): Promise<string | null>;
+    /**
+     * Collect `dc:identifier` or `dc:source` entries, attaching the value and
+     * scheme of any refining `identifier-type` meta (spec D.3.8) and a legacy
+     * `opf:scheme` attribute. Values are not interpreted.
+     *
+     * `onRefinement` is invoked for every other meta refining a collected entry,
+     * so callers can surface element-specific refinements (e.g. `source-of` on a
+     * `dc:source`).
+     */
+    private static collectDcEntries;
+    /**
+     * Retrieve every `dc:identifier` entry, returned as found.
+     *
+     * Values are not interpreted. Any refining `identifier-type` meta (spec
+     * D.3.8) or legacy `opf:scheme` attribute is surfaced on the entry, but no
+     * parsing of the value itself is attempted. To read `dc:source` entries, use
+     * {@link getSources}.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     */
+    getIdentifiers(): Promise<EpubIdentifier[]>;
+    /**
+     * Retrieve every `dc:source` entry, returned as found.
+     *
+     * Like {@link getIdentifiers}, values are not interpreted. In addition to a
+     * refining `identifier-type`, a refining `source-of` meta (spec D.3.11) is
+     * surfaced as `sourceOf`.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsource
+     */
+    getSources(): Promise<EpubSource[]>;
+    /**
+     * Retrieve the `pageBreakSource` property (EPUB 3.4, spec D.2.9), the
+     * publication-level source for the source of its page break markers.
+     *
+     * This property replaces the refining `source-of="pagination"` meta (spec
+     * D.3.11), see {@link EpubSource.sourceOf}. If no `pageBreakSource` property is found,
+     * we fall back to finding a `dc:source` with a `source-of="pagination"` refinement.
+     *
+     * @link https://www.w3.org/TR/epub/#pageBreakSource
+     */
+    getPageBreakSource(): Promise<EpubSource | null>;
+    /**
+     * Set the `pageBreakSource` property (EPUB 3.4, spec D.2.9), or remove it when
+     * passed null. Replaces an existing `pageBreakSource` meta if present.
+     *
+     * Pass `none` to indicate the pagination is unique to this publication.
+     *
+     * @link https://www.w3.org/TR/epub/#pageBreakSource
+     */
+    setPageBreakSource(value: string | null): Promise<void>;
+    /**
+     * Replace the publication's `dc:identifier` entries.
+     *
+     * This replaces ALL existing `dc:identifier` elements except the publication's
+     * unique identifier (the one referenced by the package element's
+     * `unique-identifier` attribute), which is always preserved and must not be
+     * included in the provided list. If included anyway, it is ignored. See
+     * {@link setUniqueIdentifier} to change it.
+     *
+     * Identifiers are placed in the order they are provided.
+     *
+     * `dc:source` entries are not touched, use {@link setSources} for those.
+     *
+     * When an entry has an `identifierType`, it is written in the refining form
+     * (a `meta` with `property="identifier-type"`, carrying the `scheme`
+     * attribute when provided). An entry with only a `scheme` is written using
+     * the legacy `opf:scheme` attribute.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+     */
+    setIdentifiers(identifiers: EpubIdentifier[]): Promise<void>;
+    /**
+     * Remove `meta` refinements pointing at any of the given ids,
+     * restricted to the given `property` values as a cleanup step
+     * Mutates `children` in place.
+     */
+    private static removeRefiningMetas;
+    /**
+     * Replace the publication's `dc:source` entries.
+     *
+     * This replaces ALL existing `dc:source` elements (and their refining
+     * `identifier-type` / `source-of` metas). `dc:identifier` entries are not
+     * touched; use {@link setIdentifiers} for those. Pass an empty array to
+     * remove all sources.
+     *
+     * When an entry has an `identifierType`, it is written in the refining form.
+     * A `sourceOf` value is written as a refining `source-of` meta (spec D.3.11).
+     * An entry with only a `scheme` uses the legacy `opf:scheme` attribute.
+     *
+     * @link https://www.w3.org/TR/epub-33/#sec-opf-dcsource
+     */
+    setSources(sources: EpubSource[]): Promise<void>;
     /**
      * Even "EPUB 3" publications sometimes still only use the
      * EPUB 2 specification for identifying the cover image.
@@ -772,13 +918,31 @@ declare class Epub {
         resolveToRoot?: boolean;
     }): Promise<Navigation | null>;
     /**
-     * Returns a Zip Entry path for an HREF
+     * Name the entry a resolved URL addresses.
+     *
+     * A correctly authored publication percent-encodes its hrefs, so the
+     * decoded reading is the one the spec calls for and the one we prefer.
+     * Some publications instead write the entry name verbatim, so when the two
+     * readings differ we ask the archive which one it holds. A verbatim name
+     * carrying a bare `%`, as `100%.xhtml` does, is not a valid encoding at all
+     * and can only be its own answer.
+     */
+    private entryForUrl;
+    /**
+     * Resolve an href to the name of the archive entry it addresses.
+     *
+     * @param from The entry the href appears in; it resolves against that
+     *   entry's directory
+     * @throws when the href addresses something outside the publication
      */
-    private resolveInternalHref;
+    private resolveEntry;
     /**
      * Returns a path-relative-scheme-less URL, relative to the
      * container root.
      *
+     * An href that points outside the publication, such as an external link in
+     * a navigation document, is handed back unchanged.
+     *
      * @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.
@@ -1029,4 +1193,4 @@ declare class EpubFactory<A extends EpubStorageAdapterClass> {
     upgrade(path: string, options?: Epub2UpgradeOptions): Promise<EpubInstanceFor<A>>;
 }
 
-export { type AlternateScript as A, type Collection as C, type DcSubject as D, type ElementName as E, type Epub2UpgradeOptions, type FromOptions as F, type InMemoryEpubReader as I, 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, type EpubReader as j, EpubVersionError as k, EpubReadOnlyError as l, Epub as m, type EpubInstanceFor as n, EpubFactory as o, removeGuide, removeInvalidDcAttrs, removeNcx, removeSpineTocRef, setLastModified, setPackageVersion, upgradeAuthors, upgradeCover, upgradeDate, upgradeIdentifiers, upgradeLanguages, upgradeMeta, upgradePackageMetadata, upgradeTitle };
+export { type AlternateScript as A, type Collection as C, type DcSubject as D, type ElementName as E, type Epub2UpgradeOptions, type FromOptions as F, type InMemoryEpubReader as I, 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 EpubIdentifier as e, extractGuideLandmarks, type EpubSource as f, fixFontMimeTypes, type DcCreator as g, type DublinCore as h, type NavigationList as i, type Navigation as j, type PackageElement as k, type EpubReader as l, EpubVersionError as m, EpubReadOnlyError as n, Epub as o, type EpubInstanceFor as p, EpubFactory as q, removeGuide, removeInvalidDcAttrs, removeNcx, removeSpineTocRef, setLastModified, setPackageVersion, upgradeAuthors, upgradeCover, upgradeDate, upgradeIdentifiers, upgradeLanguages, upgradeMeta, upgradePackageMetadata, upgradeTitle };