@prose-reader/metadata-fetcher 1.344.0 → 1.345.0

package/dist/providers/googleBooks/identifier.d.ts

@@ -0,0 +1,14 @@
+import { MetadataIdentifier } from '@prose-reader/archive-reader';
+import { FetchMetadataInput } from '../../types/fetchMetadataInput.ts';
+export declare const GOOGLE_BOOKS_IDENTIFIER_SCHEME = "GoogleBooks";
+export type GoogleBooksLookup = {
+    readonly id: string;
+    /** The book's exact identifier spelling, echoed only after Google confirms it. */
+    readonly identifier: MetadataIdentifier;
+};
+/**
+ * Recognizes an authored Google Books volume id and the official Google Books
+ * website/API URL forms. Arbitrary scheme-less strings are not reinterpreted
+ * as ids: callers with a raw id should label it `GoogleBooks`.
+ */
+export declare const googleBooksLookupFromInput: (input: FetchMetadataInput) => GoogleBooksLookup | undefined;

package/dist/providers/googleBooks/identifier.test.d.ts

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

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

@@ -0,0 +1,44 @@
+export type GoogleBooksIndustryIdentifier = {
+    readonly type?: string;
+    readonly identifier: string;
+};
+export type GoogleBooksImageLinks = {
+    readonly smallThumbnail?: string;
+    readonly thumbnail?: string;
+    readonly small?: string;
+    readonly medium?: string;
+    readonly large?: string;
+    readonly extraLarge?: string;
+};
+export type GoogleBooksSeriesInfo = {
+    readonly bookDisplayNumber?: string;
+};
+/**
+ * The subset of a Google Books `volumeInfo` record that has a normalized home.
+ * Every field remains optional because the public catalog is sparse in practice.
+ */
+export type GoogleBooksVolumeInfo = {
+    readonly title?: string;
+    readonly subtitle?: string;
+    readonly authors?: ReadonlyArray<string>;
+    readonly publisher?: string;
+    readonly publishedDate?: string;
+    readonly description?: string;
+    readonly industryIdentifiers?: ReadonlyArray<GoogleBooksIndustryIdentifier>;
+    readonly pageCount?: number;
+    readonly categories?: ReadonlyArray<string>;
+    readonly language?: string;
+    readonly imageLinks?: GoogleBooksImageLinks;
+    readonly infoLink?: string;
+    readonly canonicalVolumeLink?: string;
+    readonly seriesInfo?: GoogleBooksSeriesInfo;
+};
+/** One Google Books volume, retaining the source's nested field names. */
+export type GoogleBooksVolume = {
+    readonly id?: string;
+    readonly volumeInfo?: GoogleBooksVolumeInfo;
+};
+/** Reads one public Google Books Volume resource from untrusted JSON. */
+export declare const parseGoogleBooksVolume: (payload: unknown) => GoogleBooksVolume | undefined;
+/** Reads the `items` array of a Google Books volumes search response. */
+export declare const parseGoogleBooksVolumesResponse: (payload: unknown) => ReadonlyArray<GoogleBooksVolume>;

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

@@ -0,0 +1,41 @@
+import { MetadataIdentifier, ResolvedMetadata } from '@prose-reader/archive-reader';
+import { GoogleBooksImageLinks, GoogleBooksVolume } from './parse.ts';
+export declare const GOOGLE_BOOKS_MAX_SUBJECTS = 25;
+/** Compile-enforced homes for the top-level Volume resource fields. */
+export declare const googleBooksVolumeMetadataHomes: {
+    id: "identifiers";
+    volumeInfo: "metadata";
+};
+/** Compile-enforced map from every parsed Google Books field to its home. */
+export declare const googleBooksVolumeInfoMetadataHomes: {
+    title: "title";
+    subtitle: "title";
+    authors: "contributors";
+    publisher: "publication.edition.publisher";
+    publishedDate: "publication.edition.date";
+    description: "description";
+    industryIdentifiers: "identifiers";
+    pageCount: "numberOfPages";
+    categories: "subjects";
+    language: "languages";
+    imageLinks: "cover";
+    infoLink: "candidate.url";
+    canonicalVolumeLink: "candidate.url";
+    seriesInfo: "title";
+};
+/**
+ * Prefer the largest cover Google announced and force HTTPS. Preserve the
+ * query exactly: changing Google's `zoom`, `edge` or signed `imgtk` parameters
+ * can turn a valid cover into its "image not available" placeholder.
+ */
+export declare const googleBooksCoverUrl: (imageLinks: GoogleBooksImageLinks | undefined) => string | undefined;
+export type ResolveGoogleBooksVolumeOptions = {
+    /** Exact Google Books identifier that this response confirmed. */
+    readonly matchedIdentifier?: MetadataIdentifier;
+    /** ISBN query that this response confirmed, even if the payload omits it. */
+    readonly matchedIsbn?: string;
+};
+/** Normalizes one Google Books volume into the cross-format vocabulary. */
+export declare const resolveGoogleBooksVolume: (volume: GoogleBooksVolume, options?: ResolveGoogleBooksVolumeOptions) => ResolvedMetadata;
+/** The human-facing Google Books page for a candidate. */
+export declare const googleBooksVolumeUrl: (volume: GoogleBooksVolume) => string | undefined;

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

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

package/dist/providers/googleBooks/search.d.ts

@@ -0,0 +1,12 @@
+import { MetadataProvider } from '../../types/provider.ts';
+type GoogleBooksSearchOptions = {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly fetch: typeof globalThis.fetch;
+};
+/**
+ * Creates the Google Books lookup pipeline. Lookup order is an exact volume
+ * identifier, ISBN, then title plus first author with a title-only fallback.
+ */
+export declare const createGoogleBooksSearch: (options: GoogleBooksSearchOptions) => MetadataProvider["search"];
+export {};

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

@@ -1,4 +1,4 @@
-import { ResolvedMetadata } from '@prose-reader/archive-reader';
+import { MetadataIdentifier, ResolvedMetadata } from '@prose-reader/archive-reader';
 import { OpenLibraryDoc } from './parse.ts';
 /**
  * A popular work carries hundreds of subject headings, most of them long-tail
@@ -32,18 +32,15 @@ export declare const OPEN_LIBRARY_IDENTIFIER_SCHEME = "OpenLibrary";
  * - **`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.
+ * - **An ISBN identifier is added only for an ISBN lookup**, using the queried
+ *   value — the API answered "this work has that ISBN", a fact about the
+ *   record. A title-search hit describes a *work*, whose editions each have
+ *   their own ISBN, so picking one 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;
     /** The source identifier that an exact Gutenberg-id lookup confirmed. */
-    readonly matchedProjectGutenbergIdentifier?: {
-        readonly value: string;
-        readonly scheme?: string;
-    };
+    readonly matchedProjectGutenbergIdentifier?: MetadataIdentifier;
 }) => ResolvedMetadata;

package/dist/providers/projectGutenberg/identifier.d.ts

@@ -1,4 +1,5 @@
-import { FetchMetadataInput, MetadataIdentifier } from '../../types/fetchMetadataInput.ts';
+import { MetadataIdentifier } from '@prose-reader/archive-reader';
+import { FetchMetadataInput } from '../../types/fetchMetadataInput.ts';
 export declare const PROJECT_GUTENBERG_IDENTIFIER_SCHEME = "ProjectGutenberg";
 export type ProjectGutenbergLookup = {
     readonly id: string;

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

@@ -1,4 +1,4 @@
-import { ResolvedMetadata } from '@prose-reader/archive-reader';
+import { MetadataIdentifier, ResolvedMetadata } from '@prose-reader/archive-reader';
 import { ProjectGutenbergRecord } from './parse.ts';
 export declare const PROJECT_GUTENBERG_MAX_SUBJECTS = 25;
 /** Compile-enforced map from every parsed RDF field to its resolved home. */
@@ -19,8 +19,5 @@ export declare const projectGutenbergMetadataHomes: {
 };
 export declare const resolveProjectGutenbergRecord: (record: ProjectGutenbergRecord, options: {
     readonly baseUrl: string;
-    readonly matchedIdentifier: {
-        readonly value: string;
-        readonly scheme?: string;
-    };
+    readonly matchedIdentifier: MetadataIdentifier;
 }) => ResolvedMetadata;

package/dist/types/fetchMetadataInput.d.ts

@@ -1,10 +1,4 @@
-/** An identifier a metadata provider can use for lookup or matching. */
-export type MetadataIdentifier = {
-    /** Identifier exactly as announced by the source. */
-    readonly value: string;
-    /** Identifier namespace, such as `DOI`, `URL` or `ProjectGutenberg`. */
-    readonly scheme?: string;
-};
+import { MetadataIdentifier } from '@prose-reader/archive-reader';
 /**
  * The compact description of a publication that metadata providers understand
  * for lookup and matching. Rich catalog-only values belong on returned
@@ -15,8 +9,7 @@ export type FetchMetadataInput = {
     readonly title?: string;
     /** Author names, lead author first. */
     readonly authors?: ReadonlyArray<string>;
-    readonly isbn?: string;
-    readonly gtin?: string;
+    /** Scheme-scoped publication and catalog identifiers. */
     readonly identifiers?: ReadonlyArray<MetadataIdentifier>;
     /** Series name, when it helps identify or disambiguate the publication. */
     readonly series?: string;

package/dist/types/provider.d.ts

@@ -53,7 +53,10 @@ export type MetadataCandidate = {
  *       id: result.id,
  *       url: `https://example.com/book/${result.id}`,
  *       raw: result,
- *       metadata: { title: result.name, isbn: result.isbn },
+ *       metadata: {
+ *         title: result.name,
+ *         identifiers: [{ value: result.isbn, scheme: "ISBN" }],
+ *       },
  *     }))
  *   },
  * }

package/dist/utils/identifierValues.d.ts

@@ -0,0 +1,5 @@
+import { MetadataIdentifier } from '@prose-reader/archive-reader';
+/** ISBNs may arrive through ComicInfo's broader GTIN field. */
+export declare const isbnIdentifierValue: (identifiers: ReadonlyArray<MetadataIdentifier> | undefined) => string | undefined;
+/** ISBN-13 is also a GTIN-13, so both announced schemes are accepted. */
+export declare const gtinIdentifierValue: (identifiers: ReadonlyArray<MetadataIdentifier> | undefined) => string | undefined;

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

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

package/dist/utils/retryWithBackoff.d.ts

@@ -0,0 +1,20 @@
+export type RetryWithBackoffOptions = {
+    /** Total calls, including the initial one. Must be a positive integer. */
+    readonly attempts: number;
+    /** Delay before the second call. Later delays double. */
+    readonly initialDelayMs: number;
+    /** Upper bound for one delay, including jitter. */
+    readonly maxDelayMs?: number;
+    /** Adds up to one base delay of randomness. Defaults to `true`. */
+    readonly jitter?: boolean;
+    /** Decides whether a failed call is safe and useful to repeat. */
+    readonly shouldRetry: (error: unknown, attempt: number) => boolean;
+    /** Stops future attempts and cancels a wait between attempts. */
+    readonly signal?: AbortSignal;
+};
+/**
+ * Repeats a failing asynchronous operation with abortable exponential backoff.
+ * `attempts` is the total call count, not the number of retries. The original
+ * error is rethrown when it is not retryable or the final attempt fails.
+ */
+export declare const retryWithBackoff: <Value>(operation: (attempt: number) => Promise<Value>, options: RetryWithBackoffOptions) => Promise<Value>;

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

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

package/dist/utils/toIsbn13.d.ts

@@ -5,10 +5,10 @@
  * 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.
+ * Input is put through `normalizeIsbn`, the same normalization used for ISBN
+ * identifiers, 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prose-reader/metadata-fetcher",
-  "version": "1.344.0",
+  "version": "1.345.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.344.0",
-    "@prose-reader/shared": "^1.344.0",
+    "@prose-reader/archive-reader": "^1.345.0",
+    "@prose-reader/shared": "^1.345.0",
     "xmldoc": "^2.0.0"
   },
-  "gitHead": "3eac02f8c2fca1f9900d411ed573ab9a281731c0"
+  "gitHead": "f2f6e09d604f1f8e539d01ddd70c6a799c9d82cd"
 }