@prose-reader/metadata-fetcher 1.336.0

package/dist/match/scoreMetadataCandidate.d.ts

@@ -0,0 +1,37 @@
+import { ResolvedMetadata } from '@prose-reader/archive-reader';
+import { MetadataMatchSignal } from '../types/match.ts';
+/**
+ * Intent, not statistics: identifiers *are* the book, a title is what a human
+ * recognizes it by, everything else corroborates. An edition detail that
+ * differs must never sink an otherwise convincing match on its own.
+ */
+export declare const METADATA_MATCH_WEIGHTS: {
+    readonly isbn: 1;
+    readonly gtin: 1;
+    readonly identifiers: 0.6;
+    readonly title: 0.8;
+    readonly contributors: 0.5;
+    readonly series: 0.3;
+    readonly published: 0.2;
+    readonly publisher: 0.15;
+    readonly languages: 0.15;
+    readonly numberOfPages: 0.15;
+};
+export type ScoredMetadataCandidate = {
+    readonly score: number;
+    readonly signals: ReadonlyArray<MetadataMatchSignal>;
+};
+/**
+ * How well a candidate agrees with the query, field by field, and why. Every
+ * provider is scored by these rules, so their scores stay comparable:
+ *
+ * - **Only comparable fields count** — a field is compared when both sides
+ *   state it, so what the book doesn't know can neither raise nor lower a
+ *   candidate, and nothing in common scores `0`.
+ * - **The aggregate is a weighted average** ({@link METADATA_MATCH_WEIGHTS}),
+ *   putting a rich query and a sparse one on the same scale.
+ * - **A stated identifier settles it, both ways** — agreeing pins the score to
+ *   `1`, contradicting to `0`. The latter is what sinks the wrong edition that
+ *   agrees on everything a weighted average can see.
+ */
+export declare const scoreMetadataCandidate: (query: ResolvedMetadata, candidate: ResolvedMetadata) => ScoredMetadataCandidate;

package/dist/match/scoreMetadataCandidate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/match/similarity.d.ts

@@ -0,0 +1,20 @@
+/** `Les Misérables` ≡ `les miserables`, `Dune: Messiah` ≡ `dune messiah`. */
+export declare const normalizeForComparison: (value: string) => string;
+/**
+ * Sørensen–Dice coefficient over character bigrams, `0` to `1`.
+ *
+ * Bigrams rather than an edit distance: titles disagree by whole words far
+ * more often than by typos. Spaces are stripped so `Spider-Man` and
+ * `Spider Man` stay exact.
+ */
+export declare const textSimilarity: (a: string, b: string) => number;
+/**
+ * {@link textSimilarity}, with `Dune` matched against `Dune: a novel`.
+ *
+ * Only when **one** side states a subtitle: that asymmetry is the same title
+ * catalogued at a different depth. When both state one, both catalogers meant
+ * it — `Dune: Book One` and `Dune: Messiah` are two books.
+ */
+export declare const titleSimilarity: (a: string, b: string) => number;
+/** {@link textSimilarity} on sorted tokens: `Herbert, Frank` ≡ `Frank Herbert`. */
+export declare const personNameSimilarity: (a: string, b: string) => number;

package/dist/match/similarity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/merge/mergeResolvedMetadata.d.ts

@@ -0,0 +1,21 @@
+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;

package/dist/merge/mergeResolvedMetadata.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/providers/openLibrary/createOpenLibraryProvider.d.ts

@@ -0,0 +1,32 @@
+import { MetadataProvider } from '../../types/provider.ts';
+export declare const OPEN_LIBRARY_PROVIDER_ID = "openLibrary";
+export type OpenLibraryProviderOptions = {
+    /** API origin. Defaults to `https://openlibrary.org`. */
+    readonly baseUrl?: string;
+    /** Cover service origin. Defaults to `https://covers.openlibrary.org`. */
+    readonly coversBaseUrl?: string;
+    /** For tests, a custom agent, or a caching layer. Defaults to the global one. */
+    readonly fetch?: typeof globalThis.fetch;
+    /**
+     * Open Library's API etiquette asks for an identifying `User-Agent` (app
+     * name + contact) and throttles anonymous traffic harder.
+     */
+    readonly userAgent?: string;
+};
+/**
+ * Open Library — the Internet Archive's open bibliographic catalog. Free, no
+ * key, covers books broadly (much less so comics and manga).
+ *
+ * ```ts
+ * const provider = createOpenLibraryProvider({
+ *   userAgent: "MyReader/1.0 (contact@example.com)",
+ * })
+ * ```
+ *
+ * Lookup strategy, at most two requests: an **ISBN search** when the book
+ * states one — the catalog then verifies the identity for us — falling back
+ * to a **title (+ first author) search** when the ISBN is unknown to it or
+ * absent. A query with neither an ISBN nor a title yields no candidates
+ * rather than a fishing expedition.
+ */
+export declare const createOpenLibraryProvider: (options?: OpenLibraryProviderOptions) => MetadataProvider;

package/dist/providers/openLibrary/createOpenLibraryProvider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/providers/openLibrary/marcLanguage.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Normalizes one MARC language code to its BCP 47 primary subtag. Unknown
+ * codes (the long tail of MARC) pass through lowercased rather than being
+ * dropped — a language we can't name is still a language the record stated.
+ */
+export declare const marcLanguageToBcp47: (code: string) => string | undefined;

package/dist/providers/openLibrary/parse.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One entry of an Open Library `search.json` response, field names mirroring
+ * the API (same rule as the archive parsers: a parsed source looks like its
+ * source document). Every field is optional — the API omits what it doesn't
+ * have, and the `fields` parameter decides what it may return at all.
+ *
+ * @see https://openlibrary.org/dev/docs/api/search
+ */
+export type OpenLibraryDoc = {
+    /** Work key, e.g. `/works/OL45883W`. */
+    readonly key?: string;
+    readonly title?: string;
+    readonly subtitle?: string;
+    readonly author_name?: ReadonlyArray<string>;
+    readonly first_publish_year?: number;
+    readonly publisher?: ReadonlyArray<string>;
+    /** MARC 21 language codes (`eng`, `fre`), not BCP 47. */
+    readonly language?: ReadonlyArray<string>;
+    readonly subject?: ReadonlyArray<string>;
+    readonly number_of_pages_median?: number;
+    /** Cover id, addressing `covers.openlibrary.org`. */
+    readonly cover_i?: number;
+};
+/**
+ * Reads the `docs` of a `search.json` payload. A payload that isn't a record,
+ * or carries no `docs` array, yields an empty list: an unexpected response
+ * shape is "this catalog has nothing for us", not a crash.
+ */
+export declare const parseOpenLibrarySearchResponse: (payload: unknown) => ReadonlyArray<OpenLibraryDoc>;

package/dist/providers/openLibrary/resolve.d.ts

@@ -0,0 +1,44 @@
+import { ResolvedMetadata } from '@prose-reader/archive-reader';
+import { OpenLibraryDoc } from './parse.ts';
+/**
+ * A popular work carries hundreds of subject headings, most of them long-tail
+ * noise ("Accessible book", "Protected DAISY"), which would dwarf the entity a
+ * consumer persists. The API puts the meaningful ones first.
+ */
+export declare const OPEN_LIBRARY_MAX_SUBJECTS = 25;
+/**
+ * Where every {@link OpenLibraryDoc} field lands in {@link ResolvedMetadata},
+ * compile-enforced: adding a field to the parser without declaring its home is
+ * a type error. The archive parsers' losslessness contract, and the mapping
+ * documentation.
+ */
+export declare const openLibraryMetadataHomes: {
+    readonly key: "identifiers";
+    readonly title: "title";
+    readonly subtitle: "title";
+    readonly author_name: "contributors";
+    readonly first_publish_year: "published";
+    readonly publisher: "publisher";
+    readonly language: "languages";
+    readonly subject: "subjects";
+    readonly number_of_pages_median: "numberOfPages";
+    readonly cover_i: "cover";
+};
+export declare const OPEN_LIBRARY_IDENTIFIER_SCHEME = "OpenLibrary";
+/**
+ * Normalizes one search hit into the cross-format vocabulary. Two choices
+ * worth stating:
+ *
+ * - **`title` folds in `subtitle`** (`Dune: Messiah`): the vocabulary has one
+ *   title field, and an OPF `dc:title` normally carries the subtitle too, so
+ *   comparing a bare title against a full one would cost match score.
+ * - **`isbn` is set only for an ISBN lookup**, to the queried one — the API
+ *   answered "this work has that ISBN", a fact about the record. A hit
+ *   describes a *work*, whose editions each have their own ISBN, so picking
+ *   one out of a title search would be fabrication.
+ */
+export declare const resolveOpenLibraryDoc: (doc: OpenLibraryDoc, options: {
+    readonly coversBaseUrl: string;
+    /** The ISBN this record was looked up by, when it was. */
+    readonly isbn?: string;
+}) => ResolvedMetadata;

package/dist/providers/openLibrary/resolve.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/providers/responseError.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Thrown by a provider when a catalog answered with a failing status. Carrying
+ * it is what lets `fetchMetadata` report *why* a provider dropped out: `429`
+ * is "ask again later", `503` is "the catalog is down", and a consumer decides
+ * differently for each.
+ *
+ * ```ts
+ * if (!response.ok) {
+ *   throw new MetadataProviderResponseError(response.status, "My Catalog search failed")
+ * }
+ * ```
+ */
+export declare class MetadataProviderResponseError extends Error {
+    readonly status: number;
+    constructor(status: number, message?: string);
+}
+/**
+ * The HTTP status behind a thrown error, when there is one.
+ *
+ * Structural rather than `instanceof`, so a provider built on another HTTP
+ * client works unadapted. No status means it was never a response — network,
+ * parse, bug — which is itself the answer.
+ */
+export declare const responseErrorStatus: (error: unknown) => number | undefined;

package/dist/report.d.ts

@@ -0,0 +1,2 @@
+import { Report as SharedReport } from '@prose-reader/shared';
+export declare const Report: SharedReport;

package/dist/types/fetchedMetadata.d.ts

@@ -0,0 +1,86 @@
+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.
+ */
+export type FetchedMetadataSource = {
+    readonly provider: {
+        readonly id: string;
+        readonly name: string;
+    };
+    /**
+     * Every candidate the provider returned, scored, ranked best-first and
+     * capped to `limit` — rejected ones included, since "found three books, none
+     * convincing" is an answer rather than an absence.
+     */
+    readonly matches: ReadonlyArray<MetadataMatch>;
+};
+/**
+ * Per-provider detail, keyed by {@link MetadataProvider.id}. Open-ended:
+ * unlike the closed set of archive sources, the keys are whatever providers
+ * you passed.
+ */
+export type FetchedMetadataSources = Readonly<Record<string, FetchedMetadataSource>>;
+export type FailedMetadataProvider = {
+    readonly id: string;
+    /**
+     * Set when the failure was a response rather than a network error, a
+     * malformed payload or a bug — the difference between "rate limited, ask
+     * again later" (`429`), "the catalog is down" (`5xx`) and "we asked wrong"
+     * (`4xx`), which a bare "it failed" cannot express.
+     *
+     * Providers report it by throwing `MetadataProviderResponseError`, or any
+     * error carrying a numeric `status`.
+     */
+    readonly status?: number;
+};
+/**
+ * What remote catalogs know about a book — the equivalent of `ResolvedArchive`
+ * and just as plain: structured-clone-able, persistable, cacheable.
+ */
+export type FetchedMetadata = {
+    /**
+     * Schema version, for consumers persisting the entity. Bumped only when the
+     * 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,
+     * so that order doubles as your tie-break precedence.
+     */
+    readonly matches: ReadonlyArray<MetadataMatch>;
+    readonly sources: FetchedMetadataSources;
+    /**
+     * Providers whose search threw, each with its HTTP `status` when the catalog
+     * answered with one. Always present, and the only trace a swallowed failure
+     * leaves — a consumer refusing to cache a partial answer needs it.
+     *
+     * ```ts
+     * const fetched = await fetchMetadata(resolved, { providers })
+     *
+     * // don't persist "we found nothing" when we simply couldn't ask
+     * if (fetched.failedProviders.length === 0) cache.set(bookId, fetched)
+     *
+     * // rate limited rather than broken: worth asking again, later
+     * const throttled = fetched.failedProviders.filter(({ status }) => status === 429)
+     * ```
+     */
+    readonly failedProviders: ReadonlyArray<FailedMetadataProvider>;
+};

package/dist/types/match.d.ts

@@ -0,0 +1,48 @@
+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" | "publisher" | "published" | "languages" | "numberOfPages";
+/**
+ * One field comparison. The compared values sit next to the score so a match
+ * is explainable to a user — "same title, different publisher" — without
+ * re-deriving anything.
+ */
+export type MetadataMatchSignal = {
+    readonly field: MetadataMatchField;
+    /** How much the two values agree, `0` (nothing in common) to `1` (equal). */
+    readonly score: number;
+    /** The field's relative importance in the aggregate (see `METADATA_MATCH_WEIGHTS`). */
+    readonly weight: number;
+    /** The local value that was compared, rendered for display. */
+    readonly query: string;
+    /** The candidate value that was compared, rendered for display. */
+    readonly candidate: string;
+};
+/**
+ * A scored candidate: the metadata a provider found, plus why we believe (or
+ * don't) that it is the same book.
+ */
+export type MetadataMatch = {
+    readonly providerId: string;
+    /**
+     * Aggregate confidence, `0` to `1`: the weight-averaged score of every
+     * comparable field — except when both sides state an identifier, which
+     * settles it outright: `1` if it agrees (an ISBN/GTIN match *is* the book),
+     * `0` if it contradicts. `0` too when the two sides had no field in common
+     * to compare.
+     */
+    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.
+     */
+    readonly accepted: boolean;
+    readonly metadata: ResolvedMetadata;
+    readonly id?: string;
+    readonly url?: string;
+    readonly raw?: unknown;
+};

package/dist/types/provider.d.ts

@@ -0,0 +1,76 @@
+import { ResolvedMetadata } from '@prose-reader/archive-reader';
+export type MetadataIdentifier = NonNullable<ResolvedMetadata["identifiers"]>[number];
+export type MetadataProviderContext = {
+    /**
+     * How many candidates the caller will keep. A hint for the provider's own
+     * page size — the fetch enforces it as a hard cap after ranking anyway, so
+     * returning more is allowed but wasteful.
+     */
+    readonly limit: number;
+    readonly signal?: AbortSignal;
+};
+/**
+ * One record a provider believes could be the book. A provider's whole job is
+ * to search its catalog and normalize each hit into {@link ResolvedMetadata};
+ * it does **not** score its own candidates — the fetch does that, identically
+ * for everyone, so scores stay comparable.
+ */
+export type MetadataCandidate = {
+    readonly metadata: ResolvedMetadata;
+    readonly id?: string;
+    readonly url?: string;
+    /**
+     * The provider's own record — provenance, and the escape hatch for fields
+     * with no home in the vocabulary. Kept only when `includeRaw` is on.
+     */
+    readonly raw?: unknown;
+};
+/**
+ * A pluggable metadata source. Implementing one is: pick a stable `id`, read
+ * the terms you can search on out of the metadata, 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.
+ *
+ * ```ts
+ * import { type MetadataProvider, metadataAuthors } from "@prose-reader/metadata-fetcher"
+ *
+ * const myProvider: MetadataProvider = {
+ *   id: "myCatalog",
+ *   name: "My Catalog",
+ *   search: async (metadata, { limit, signal }) => {
+ *     if (metadata.title === undefined) return []
+ *
+ *     const response = await fetch(
+ *       `https://example.com/search?q=${encodeURIComponent(metadata.title)}` +
+ *         `&author=${encodeURIComponent(metadataAuthors(metadata)[0] ?? "")}`,
+ *       { signal },
+ *     )
+ *     const { results } = await response.json()
+ *
+ *     return results.slice(0, limit).map((result) => ({
+ *       id: result.id,
+ *       url: `https://example.com/book/${result.id}`,
+ *       raw: result,
+ *       metadata: { title: result.name, isbn: result.isbn },
+ *     }))
+ *   },
+ * }
+ * ```
+ */
+export type MetadataProvider = {
+    /** Unique across the providers of one fetch: it keys the result's `sources`. */
+    readonly id: string;
+    readonly name: string;
+    /**
+     * The candidates the catalog has, best-effort: an empty list when there is
+     * 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>>;
+};

package/dist/utils/hasSearchTerms.d.ts

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

package/dist/utils/hasSearchTerms.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/json.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Readers for `JSON.parse` output. A catalog's payload is third-party data, so
+ * it enters as `unknown` and every field goes through a guard: a renamed or
+ * nulled field reads as absent instead of crashing the fetch, or producing a
+ * candidate with `undefined` where a string was promised.
+ */
+export declare const isJsonRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const readString: (record: Record<string, unknown>, key: string) => string | undefined;
+export declare const readNumber: (record: Record<string, unknown>, key: string) => number | undefined;
+export declare const readStringArray: (record: Record<string, unknown>, key: string) => ReadonlyArray<string> | undefined;
+export declare const readRecordArray: (record: Record<string, unknown>, key: string) => ReadonlyArray<Record<string, unknown>>;

package/dist/utils/metadataAuthors.d.ts

@@ -0,0 +1,8 @@
+import { ResolvedMetadata } from '@prose-reader/archive-reader';
+/**
+ * The names to match a publication on: those credited as `author`, else — for
+ * a publication crediting nobody as one, like a comic archive listing only a
+ * penciler — every contributor. Order is preserved (sources list the lead
+ * creator first) and duplicates are dropped.
+ */
+export declare const metadataAuthors: (metadata: ResolvedMetadata) => ReadonlyArray<string>;

package/dist/utils/omitUndefined.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns a copy of `obj` without the keys whose value is `undefined`, so
+ * results stay sparse (an absent key and an `undefined` value are the same
+ * statement: "nothing was found for this field").
+ */
+export declare const omitUndefined: <T extends object>(obj: T) => T;

package/dist/utils/toIsbn13.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Put an ISBN in its 13-digit form so the two printed on the same book compare
+ * equal. A book carries an ISBN-10 in its OPF and an ISBN-13 in a catalog
+ * record all the time; comparing them verbatim would read as "different
+ * books", which — ISBN being a decisive match signal — is the most damaging
+ * false negative the matcher can produce.
+ *
+ * Input is put through `normalizeIsbn`, the same function that produces
+ * {@link ResolvedMetadata.isbn} in the first place, so the hyphenated and
+ * prefixed forms a human types (`978-0-441-01359-3`, `ISBN 0-441-01359-7`)
+ * are recognized rather than silently dropped.
+ *
+ * Returns `undefined` when nothing ISBN-shaped can be recovered (check digits
+ * are not verified: a wrong one still identifies the intended book).
+ */
+export declare const toIsbn13: (isbn: string) => string | undefined;

package/dist/utils/toIsbn13.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@prose-reader/metadata-fetcher",
+  "version": "1.336.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "prose-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "license": "MIT",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "start": "vite build --watch --mode development",
+    "build": "tsc && vite build",
+    "test": "vitest run --coverage",
+    "tsc": "tsc",
+    "test:watch": "vitest watch"
+  },
+  "dependencies": {
+    "@prose-reader/archive-reader": "^1.336.0",
+    "@prose-reader/shared": "^1.336.0"
+  },
+  "gitHead": "312ee6e898b4e4b2389bc23789082cf31f9db2f9"
+}