@prose-reader/metadata-fetcher 1.340.0 → 1.342.0

package/dist/types/fetchedMetadata.d.ts

@@ -1,10 +1,7 @@
-import { ResolvedMetadata } from '@prose-reader/archive-reader';
 import { MetadataMatch } from './match.ts';
 /**
- * What one provider had to say — the twin of `ResolvedArchiveSources`, with
- * the same contract: everything a provider contributed is also represented,
- * merged, in {@link FetchedMetadata.metadata}, so a wrong precedence opinion
- * stays revisable because the per-provider values never left the entity.
+ * What one provider had to say: every candidate, with the provider identity
+ * needed to present or revisit those results independently.
  */
 export type FetchedMetadataSource = {
     readonly provider: {
@@ -38,8 +35,9 @@ export type FailedMetadataProvider = {
     readonly status?: number;
 };
 /**
- * What remote catalogs know about a book — the equivalent of `ResolvedArchive`
- * and just as plain: structured-clone-able, persistable, cacheable.
+ * What remote catalogs found for a book, kept as ranked alternatives rather
+ * than consolidated into a potentially synthetic record. The entity is plain
+ * JSON: structured-clone-able, persistable and cacheable.
  */
 export type FetchedMetadata = {
     /**
@@ -47,19 +45,6 @@ export type FetchedMetadata = {
      * shape or meaning of existing fields changes incompatibly.
      */
     readonly version: number;
-    /**
-     * What the providers found, merged field-wise with the highest-scoring
-     * accepted match winning. Empty when nothing matched confidently enough.
-     *
-     * **Only** the remote answer: the local metadata is deliberately not folded
-     * in, so a consumer decides who wins.
-     *
-     * ```ts
-     * // trust the book over the catalog, fill the gaps from the catalog
-     * const metadata = mergeResolvedMetadata(resolved.metadata, fetched.metadata)
-     * ```
-     */
-    readonly metadata: ResolvedMetadata;
     /**
      * Every match across every provider, ranked best-first — the list a "did you
      * mean?" picker renders. Ties keep the order the providers were declared in,
@@ -73,7 +58,8 @@ export type FetchedMetadata = {
      * leaves — a consumer refusing to cache a partial answer needs it.
      *
      * ```ts
-     * const fetched = await fetchMetadata(resolved, { providers })
+     * const input = metadataInputFromResolvedArchive(resolved)
+     * const fetched = await fetchMetadata(input, { providers })
      *
      * // don't persist "we found nothing" when we simply couldn't ask
      * if (fetched.failedProviders.length === 0) cache.set(bookId, fetched)

package/dist/types/match.d.ts

@@ -3,7 +3,7 @@ import { ResolvedMetadata } from '@prose-reader/archive-reader';
  * The fields the matcher compares — only ever when **both** sides state one,
  * so what the query doesn't know cannot count against a candidate.
  */
-export type MetadataMatchField = "isbn" | "gtin" | "identifiers" | "title" | "contributors" | "series" | "publication.original.date" | "publication.original.publisher" | "publication.edition.date" | "publication.edition.publisher" | "languages" | "numberOfPages";
+export type MetadataMatchField = "isbn" | "gtin" | "identifiers" | "title" | "authors" | "series" | "publisher" | "publishedYear" | "languages" | "numberOfPages";
 /**
  * One field comparison. The compared values sit next to the score so a match
  * is explainable to a user — "same title, different edition publisher" —
@@ -36,9 +36,8 @@ export type MetadataMatch = {
     readonly score: number;
     readonly signals: ReadonlyArray<MetadataMatchSignal>;
     /**
-     * Reached `minScore`, and so contributed to the merged
-     * `FetchedMetadata.metadata`. Rejected matches are kept and ranked, for a
-     * consumer to offer for manual confirmation.
+     * Reached `minScore`. Rejected matches are kept and ranked, for a consumer
+     * to offer for manual confirmation.
      */
     readonly accepted: boolean;
     readonly metadata: ResolvedMetadata;

package/dist/types/provider.d.ts

@@ -1,5 +1,5 @@
 import { ResolvedMetadata } from '@prose-reader/archive-reader';
-export type MetadataIdentifier = NonNullable<ResolvedMetadata["identifiers"]>[number];
+import { FetchMetadataInput } from './fetchMetadataInput.ts';
 export type MetadataProviderContext = {
     /**
      * How many candidates the caller will keep. A hint for the provider's own
@@ -27,28 +27,24 @@ export type MetadataCandidate = {
 };
 /**
  * A pluggable metadata source. Implementing one is: pick a stable `id`, read
- * the terms you can search on out of the metadata, return normalized
+ * the terms you can search on out of the compact input, return normalized
  * candidates.
  *
- * Both sides of a lookup speak {@link ResolvedMetadata} — what the book said
- * going in, what the catalog says coming back. There is no separate query
- * shape to learn: the vocabulary is already sparse by contract (`field !==
- * undefined` is a reliable presence check) and already carries everything a
- * catalog could key on, down to the format-scoped corners. `metadataAuthors`
- * is exported for the one derivation that needs the role vocabulary.
+ * Inputs contain only fields understood for lookup and matching. Returned
+ * candidates remain rich {@link ResolvedMetadata} entities.
  *
  * ```ts
- * import { type MetadataProvider, metadataAuthors } from "@prose-reader/metadata-fetcher"
+ * import { type MetadataProvider } from "@prose-reader/metadata-fetcher"
  *
  * const myProvider: MetadataProvider = {
  *   id: "myCatalog",
  *   name: "My Catalog",
- *   search: async (metadata, { limit, signal }) => {
- *     if (metadata.title === undefined) return []
+ *   search: async (input, { limit, signal }) => {
+ *     if (input.title === undefined) return []
  *
  *     const response = await fetch(
- *       `https://example.com/search?q=${encodeURIComponent(metadata.title)}` +
- *         `&author=${encodeURIComponent(metadataAuthors(metadata)[0] ?? "")}`,
+ *       `https://example.com/search?q=${encodeURIComponent(input.title)}` +
+ *         `&author=${encodeURIComponent(input.authors?.[0] ?? "")}`,
  *       { signal },
  *     )
  *     const { results } = await response.json()
@@ -72,5 +68,5 @@ export type MetadataProvider = {
      * nothing to search on, or nothing found. Throwing is allowed — a failing
      * provider never fails the fetch, it lands in `failedProviders`.
      */
-    readonly search: (metadata: ResolvedMetadata, context: MetadataProviderContext) => Promise<ReadonlyArray<MetadataCandidate>>;
+    readonly search: (input: FetchMetadataInput, context: MetadataProviderContext) => Promise<ReadonlyArray<MetadataCandidate>>;
 };

package/dist/utils/hasSearchTerms.d.ts

@@ -1,7 +1,7 @@
-import { ResolvedMetadata } from '@prose-reader/archive-reader';
+import { FetchMetadataInput } from '../types/fetchMetadataInput.ts';
 /**
  * Whether a catalog has anything to go on, so a lookup with nothing to ask
  * about costs no round trip. Publication details, a language, or a page count
  * narrow a search but cannot start one.
  */
-export declare const hasSearchTerms: (metadata: ResolvedMetadata) => boolean;
+export declare const hasSearchTerms: (input: FetchMetadataInput) => boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prose-reader/metadata-fetcher",
-  "version": "1.340.0",
+  "version": "1.342.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -29,9 +29,9 @@
     "test:watch": "vitest watch"
   },
   "dependencies": {
-    "@prose-reader/archive-reader": "^1.340.0",
-    "@prose-reader/shared": "^1.340.0",
+    "@prose-reader/archive-reader": "^1.342.0",
+    "@prose-reader/shared": "^1.342.0",
     "xmldoc": "^2.0.0"
   },
-  "gitHead": "b8aea840260994b069963e15474aa1dfdbb685e7"
+  "gitHead": "99cc96dab3e29677ab017246bbad836b54720284"
 }

package/dist/merge/mergeResolvedMetadata.d.ts

@@ -1,21 +0,0 @@
-import { ResolvedMetadata } from '@prose-reader/archive-reader';
-/**
- * Merges several {@link ResolvedMetadata} into one, **first defined wins**.
- * Precedence is the caller's — pass the sources in the order you trust them.
- *
- * ```ts
- * // the book over the catalogs, catalogs filling the gaps
- * const metadata = mergeResolvedMetadata(resolved.metadata, fetched.metadata)
- * ```
- *
- * Field-wise rather than object-wise, so a source knowing only a cover
- * contributes it without hiding another's title. Two fields are additive
- * instead: `identifiers` concatenate (deduped on scheme + value, mirroring
- * `resolveMetadata`), and `belongsTo` merges `series` and `collection`
- * independently.
- *
- * Everything else takes the first stated value whole. Unioning keyword lists
- * across catalogs is a judgement call for the consumer, not for a merge that
- * has to stay predictable.
- */
-export declare const mergeResolvedMetadata: (...entries: ReadonlyArray<ResolvedMetadata | undefined>) => ResolvedMetadata;