@storyteller-platform/epub 0.6.2 → 0.7.0

package/dist/index.js

@@ -550,12 +550,15 @@ ${JSON.stringify(element, null, 2)}`
     return metadata;
   }
   /**
-   * 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.
    */
   async getIdentifier() {
     const metadata = await this.getMetadata();
@@ -569,6 +572,8 @@ ${JSON.stringify(element, null, 2)}`
    * Otherwise creates a new element
    *
    * @link https://www.w3.org/TR/epub-33/#sec-opf-dcidentifier
+   *
+   * @deprecated Use {@link setUniqueIdentifier} instead.
    */
   async setIdentifier(identifier) {
     await this.replaceMetadata(({ type }) => type === "dc:identifier", {
@@ -577,6 +582,395 @@ ${JSON.stringify(element, null, 2)}`
       value: identifier
     });
   }
+  /**
+   * 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
+   */
+  async getUniqueIdentifier() {
+    const metadata = await this.getMetadata();
+    const uniqueId = await this.getUniqueIdentifierId();
+    if (!uniqueId) {
+      return null;
+    }
+    const entry = metadata.find(
+      ({ type, id }) => type === "dc:identifier" && id === uniqueId
+    );
+    return (entry == null ? void 0 : entry.value) ?? 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
+   */
+  async setUniqueIdentifier(identifier) {
+    await this.withPackage(async (packageElement) => {
+      const metadata = Epub.findXmlChildByName(
+        "metadata",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!metadata) {
+        throw new Error(
+          "Failed to parse EPUB: found no metadata element in package document"
+        );
+      }
+      let uniqueId = await this.getUniqueIdentifierId();
+      if (!uniqueId) {
+        const newUniqueId = nanoid();
+        packageElement[":@"] = {
+          ...packageElement[":@"],
+          "@_unique-identifier": newUniqueId
+        };
+        uniqueId = newUniqueId;
+      }
+      const children = Epub.getXmlChildren(metadata);
+      const entry = Epub.findXmlChildByName(
+        "dc:identifier",
+        children,
+        (node) => {
+          var _a;
+          return ((_a = node[":@"]) == null ? void 0 : _a["@_id"]) === uniqueId;
+        }
+      );
+      if (entry) {
+        children.splice(
+          children.indexOf(entry),
+          1,
+          Epub.createXmlElement("dc:identifier", { id: uniqueId }, [
+            Epub.createXmlTextNode(identifier)
+          ])
+        );
+        return;
+      }
+      children.push(
+        Epub.createXmlElement("dc:identifier", { id: uniqueId }, [
+          Epub.createXmlTextNode(identifier)
+        ])
+      );
+    });
+  }
+  /**
+   * 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
+   */
+  async getUniqueIdentifierId() {
+    var _a;
+    const packageElement = await this.getPackageElement();
+    return ((_a = packageElement[":@"]) == null ? void 0 : _a["@_unique-identifier"]) ?? 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`).
+   */
+  static collectDcEntries(metadata, type, onRefinement) {
+    const entries = metadata.filter((entry) => entry.type === type && entry.value !== void 0).map((entry) => ({
+      // filtered above, so value is defined
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      value: entry.value,
+      ...entry.id && { id: entry.id },
+      ...entry.properties["opf:scheme"] && {
+        scheme: entry.properties["opf:scheme"]
+      }
+    }));
+    for (const meta of metadata) {
+      if (meta.type !== "meta" || meta.value === void 0) continue;
+      const property = meta.properties["property"];
+      const refines = meta.properties["refines"];
+      if (!property || !refines) continue;
+      const target = entries.find((t) => t.id === refines.slice(1));
+      if (!target) continue;
+      if (property === "identifier-type") {
+        target.identifierType = meta.value;
+        if (meta.properties["scheme"]) target.scheme = meta.properties["scheme"];
+      } else {
+        onRefinement == null ? void 0 : onRefinement(target, property, meta.value);
+      }
+    }
+    return entries;
+  }
+  /**
+   * 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
+   */
+  async getIdentifiers() {
+    const metadata = await this.getMetadata();
+    return Epub.collectDcEntries(metadata, "dc:identifier");
+  }
+  /**
+   * 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
+   */
+  async getSources() {
+    const metadata = await this.getMetadata();
+    return Epub.collectDcEntries(
+      metadata,
+      "dc:source",
+      (source, property) => {
+        if (property === "source-of") {
+          source.isPageBreakSource = true;
+        }
+      }
+    );
+  }
+  /**
+   * 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
+   */
+  async getPageBreakSource() {
+    const entry = await this.findMetadataItem(
+      (item) => item.type === "meta" && item.properties["property"] === "pageBreakSource" && !!item.value
+    );
+    if (entry) {
+      return {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        value: entry.value,
+        id: entry.id,
+        identifierType: void 0,
+        scheme: void 0,
+        isPageBreakSource: true
+      };
+    }
+    const sources = await this.getSources();
+    const source = sources.find((source2) => source2.isPageBreakSource);
+    if (source) {
+      return source;
+    }
+    return 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
+   */
+  async setPageBreakSource(value) {
+    if (value === null) {
+      await this.removeMetadata(
+        (item) => item.properties["property"] === "pageBreakSource"
+      );
+      return;
+    }
+    await this.replaceMetadata(
+      (item) => item.properties["property"] === "pageBreakSource",
+      { type: "meta", properties: { property: "pageBreakSource" }, value }
+    );
+  }
+  /**
+   * 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
+   */
+  async setIdentifiers(identifiers) {
+    const uniqueId = await this.getUniqueIdentifierId();
+    await this.withPackage((packageElement) => {
+      var _a;
+      const metadata = Epub.findXmlChildByName(
+        "metadata",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!metadata)
+        throw new Error(
+          "Failed to parse EPUB: found no metadata element in package document"
+        );
+      const children = Epub.getXmlChildren(metadata);
+      const removedIds = /* @__PURE__ */ new Set();
+      for (let i = children.length - 1; i >= 0; i--) {
+        const node = children[i];
+        if (Epub.isXmlTextNode(node) || Epub.getXmlElementName(node) !== "dc:identifier") {
+          continue;
+        }
+        const id = (_a = node[":@"]) == null ? void 0 : _a["@_id"];
+        if (id && id === uniqueId) {
+          continue;
+        }
+        if (id) {
+          removedIds.add(id);
+        }
+        children.splice(i, 1);
+      }
+      Epub.removeRefiningMetas(children, removedIds, ["identifier-type"]);
+      for (const identifier of identifiers) {
+        if (identifier.id && identifier.id === uniqueId) continue;
+        const id = identifier.id ?? (identifier.identifierType !== void 0 ? nanoid() : void 0);
+        children.push(
+          Epub.createXmlElement(
+            "dc:identifier",
+            {
+              ...id && { id },
+              ...identifier.scheme && identifier.identifierType === void 0 && {
+                "opf:scheme": identifier.scheme
+              }
+            },
+            [Epub.createXmlTextNode(identifier.value)]
+          )
+        );
+        if (identifier.identifierType !== void 0 && id) {
+          children.push(
+            Epub.createXmlElement(
+              "meta",
+              {
+                refines: `#${id}`,
+                property: "identifier-type",
+                ...identifier.scheme && { scheme: identifier.scheme }
+              },
+              [Epub.createXmlTextNode(identifier.identifierType)]
+            )
+          );
+        }
+      }
+    });
+  }
+  /**
+   * Remove `meta` refinements pointing at any of the given ids,
+   * restricted to the given `property` values as a cleanup step
+   * Mutates `children` in place.
+   */
+  static removeRefiningMetas(children, ids, properties) {
+    var _a, _b, _c;
+    for (let i = children.length - 1; i >= 0; i--) {
+      const node = children[i];
+      if (Epub.isXmlTextNode(node) || Epub.getXmlElementName(node) !== "meta") {
+        continue;
+      }
+      const property = (_a = node[":@"]) == null ? void 0 : _a["@_property"];
+      if (!property || !properties.includes(property)) continue;
+      const refines = (_c = (_b = node[":@"]) == null ? void 0 : _b["@_refines"]) == null ? void 0 : _c.slice(1);
+      if (refines && ids.has(refines)) {
+        children.splice(i, 1);
+      }
+    }
+  }
+  /**
+   * 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
+   */
+  async setSources(sources) {
+    await this.withPackage((packageElement) => {
+      var _a;
+      const metadata = Epub.findXmlChildByName(
+        "metadata",
+        Epub.getXmlChildren(packageElement)
+      );
+      if (!metadata)
+        throw new Error(
+          "Failed to parse EPUB: found no metadata element in package document"
+        );
+      const children = Epub.getXmlChildren(metadata);
+      const removedIds = /* @__PURE__ */ new Set();
+      for (let i = children.length - 1; i >= 0; i--) {
+        const node = children[i];
+        if (Epub.isXmlTextNode(node) || Epub.getXmlElementName(node) !== "dc:source") {
+          continue;
+        }
+        const id = (_a = node[":@"]) == null ? void 0 : _a["@_id"];
+        if (id) {
+          removedIds.add(id);
+        }
+        children.splice(i, 1);
+      }
+      Epub.removeRefiningMetas(children, removedIds, [
+        "identifier-type",
+        "source-of"
+      ]);
+      for (const source of sources) {
+        const needsId = source.identifierType !== void 0 || source.isPageBreakSource;
+        const id = source.id ?? (needsId ? nanoid() : void 0);
+        children.push(
+          Epub.createXmlElement(
+            "dc:source",
+            {
+              ...id && { id },
+              ...source.scheme && source.identifierType === void 0 && {
+                "opf:scheme": source.scheme
+              }
+            },
+            [Epub.createXmlTextNode(source.value)]
+          )
+        );
+        if (source.identifierType !== void 0 && id) {
+          children.push(
+            Epub.createXmlElement(
+              "meta",
+              {
+                refines: `#${id}`,
+                property: "identifier-type",
+                ...source.scheme && { scheme: source.scheme }
+              },
+              [Epub.createXmlTextNode(source.identifierType)]
+            )
+          );
+        }
+        if (source.isPageBreakSource && id) {
+          children.push(
+            Epub.createXmlElement(
+              "meta",
+              { refines: `#${id}`, property: "source-of" },
+              [Epub.createXmlTextNode("pagination")]
+            )
+          );
+        }
+      }
+    });
+  }
   /**
    * Even "EPUB 3" publications sometimes still only use the
    * EPUB 2 specification for identifying the cover image.
@@ -1257,7 +1651,14 @@ ${JSON.stringify(element, null, 2)}`
     const creatorEntries = metadata.filter(
       (entry) => entry.type === `dc:${type}`
     );
-    const creators = creatorEntries.map(({ value }) => value).filter((value) => !!value).map((value) => ({ name: value }));
+    const creators = [];
+    const creatorsById = /* @__PURE__ */ new Map();
+    for (const entry of creatorEntries) {
+      if (!entry.value) continue;
+      const creator = { name: entry.value };
+      creators.push(creator);
+      if (entry.id) creatorsById.set(entry.id, creator);
+    }
     metadata.forEach((entry) => {
       if (entry.type !== "meta" || entry.properties["property"] !== "file-as" && entry.properties["property"] !== "role" && entry.properties["property"] !== "alternate-script" || !entry.value) {
         return;
@@ -1265,7 +1666,7 @@ ${JSON.stringify(element, null, 2)}`
       const creatorIdref = entry.properties["refines"];
       if (!creatorIdref) return;
       const creatorId = creatorIdref.slice(1);
-      const creator = creatorEntries.filter((entry2) => entry2.id === creatorId && !!entry2.value).map((creator2) => ({ name: creator2.value }))[0];
+      const creator = creatorsById.get(creatorId);
       if (!creator) return;
       if (entry.properties["alternate-script"]) {
         if (!entry.properties["xml:lang"]) return;

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(...)`
@@ -366,7 +391,7 @@ declare class Epub {
      */
     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}`;
+        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}`;
         properties: {
             [k: string]: string;
         };
@@ -378,7 +403,7 @@ declare class Epub {
      */
     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}`;
+        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}`;
         properties: {
             [k: string]: string;
         };
@@ -398,12 +423,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 +441,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.
@@ -1029,4 +1179,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 };