blomios/ReadaBook
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(api,web): enrichissement métadonnées — hints locaux et scoring des correspondances

Browse Source 
Recherche de fiches par nom peu fiable : sans ISBN, les providers
étaient interrogés avec des titres bruts peu discriminants.

- extraction de hints locaux (titre/auteur/année/isbn du fichier et du
  nom de fichier) persistés dans books.local_metadata_json
- nouveau use-case ScoreMetadataMatch : tri des résultats par score de
  correspondance avant sélection du meilleur candidat
- providers (google-books, open-library, bnf, local) durcis et nourris
  par les hints ; colonne + index local_metadata_json avec migrations
  idempotentes (création et rebuild legacy)
- web : nettoyage de la description de la fiche livre
  (cleanBookDescription, white-space pre-line)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Git Agent
2026-08-23 18:07:29 +02:00
parent 5de46a6f6d
commit 18d73a4db6
21 changed files with 829 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
apps/api/src/metadata/adapters/bnf.provider.ts
View File

@ -1,6 +1,6 @@
import { Injectable } from "@nestjs/common";
import { XMLParser } from "fast-xml-parser";
import { MetadataLookup, MetadataMatch, MetadataProvider, MetadataProviderConfig } from "../metadata.types.js";
import { MetadataLookup, MetadataMatch, MetadataProvider, MetadataProviderConfig, MetadataSearchQuery } from "../metadata.types.js";
import { toIsbn13 } from "../use-cases/extract-identifiers.js";
const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@_", removeNSPrefix: true });
@ -11,30 +11,52 @@ export class BnfProvider implements MetadataProvider {
async lookup(lookup: MetadataLookup, _config: MetadataProviderConfig): Promise<MetadataMatch | null> {
const isbn = lookup.identifiers.isbn13 ?? lookup.identifiers.isbn10;
const query = isbn
? `bib.isbn all "${isbn}"`
: `bib.title all "${lookup.title.replace(/"/g, " ")}"`;
if (!isbn) {
const matches = await this.searchByMetadata({ title: lookup.title, author: lookup.author, year: lookup.local.year }, _config);
return matches[0] ?? null;
}
const query = `bib.isbn all "${isbn}"`;
const matches = await this.searchSru(query, 1, lookup.identifiers.isbn13);
return matches[0] ?? null;
}
async searchByMetadata(query: MetadataSearchQuery, _config: MetadataProviderConfig): Promise<MetadataMatch[]> {
const title = query.title.replace(/"/g, " ");
const author = query.author?.replace(/"/g, " ");
const sruQuery = [`bib.title all "${title}"`, author ? `bib.author all "${author}"` : null, query.year ? `bib.date all "${query.year}"` : null]
.filter(Boolean)
.join(" and ");
return this.searchSru(sruQuery, 5, query.isbn ? toIsbn13(query.isbn) : null);
}
private async searchSru(query: string, maximumRecords: number, expectedIsbn13: string | null): Promise<MetadataMatch[]> {
const url = new URL("https://catalogue.bnf.fr/api/SRU");
url.searchParams.set("version", "1.2");
url.searchParams.set("operation", "searchRetrieve");
url.searchParams.set("query", query);
url.searchParams.set("maximumRecords", "1");
url.searchParams.set("maximumRecords", String(maximumRecords));
const response = await fetch(url, { signal: AbortSignal.timeout(5000) });
if (!response.ok) return null;
if (!response.ok) return [];
const parsed = parser.parse(await response.text());
const record = parsed?.searchRetrieveResponse?.records?.record?.recordData?.record;
if (!record) return null;
const fields = asArray(record.datafield);
return {
title: subfield(fields, "200", "a") ?? undefined,
author: subfield(fields, "200", "f") ?? ([subfield(fields, "700", "b"), subfield(fields, "700", "a")].filter(Boolean).join(" ") || null),
description: subfield(fields, "330", "a"),
isbn: bestIsbn(fields, lookup.identifiers.isbn13),
language: subfield(fields, "101", "a"),
publisher: subfield(fields, "210", "c") ?? subfield(fields, "214", "c"),
publishedDate: cleanDate(subfield(fields, "210", "d") ?? subfield(fields, "214", "d"))
};
const records = asArray(parsed?.searchRetrieveResponse?.records?.record)
.map((entry) => (entry.recordData as Record<string, unknown> | undefined)?.record)
.filter((record): record is Record<string, unknown> => Boolean(record));
if (!records.length) return [];
return records
.map((record) => {
const fields = asArray(record.datafield);
return {
title: subfield(fields, "200", "a") ?? undefined,
author: subfield(fields, "200", "f") ?? ([subfield(fields, "700", "b"), subfield(fields, "700", "a")].filter(Boolean).join(" ") || null),
description: subfield(fields, "330", "a"),
isbn: bestIsbn(fields, expectedIsbn13),
language: subfield(fields, "101", "a"),
publisher: subfield(fields, "210", "c") ?? subfield(fields, "214", "c"),
publishedDate: cleanDate(subfield(fields, "210", "d") ?? subfield(fields, "214", "d"))
};
})
.sort((left, right) => Number(Boolean(right.isbn)) - Number(Boolean(left.isbn)));
}
}
@ -60,7 +82,11 @@ function bestIsbn(fields: Array<Record<string, unknown>>, expectedIsbn13: string
.filter((item) => item["@_code"] === "a")
.map((item) => String(item["#text"] ?? "").replace(/[^0-9X]/gi, ""))
.filter(Boolean);
return values.find((candidate) => toIsbn13(candidate) === expectedIsbn13) ?? values.find((candidate) => toIsbn13(candidate)) ?? null;
return (
values.find((candidate) => Boolean(expectedIsbn13) && toIsbn13(candidate) === expectedIsbn13) ??
values.find((candidate) => Boolean(toIsbn13(candidate))) ??
null
);
}
function cleanDate(value: string | null): string | null {

36
apps/api/src/metadata/adapters/google-books.provider.ts
View File

@ -1,5 +1,5 @@
import { Injectable } from "@nestjs/common";
import { MetadataLookup, MetadataMatch, MetadataProvider, MetadataProviderConfig } from "../metadata.types.js";
import { MetadataLookup, MetadataMatch, MetadataProvider, MetadataProviderConfig, MetadataSearchQuery } from "../metadata.types.js";
import { toIsbn13 } from "../use-cases/extract-identifiers.js";
@Injectable()
@ -8,9 +8,11 @@ export class GoogleBooksProvider implements MetadataProvider {
async lookup(lookup: MetadataLookup, config: MetadataProviderConfig): Promise<MetadataMatch | null> {
const isbn = lookup.identifiers.isbn13 ?? lookup.identifiers.isbn10;
const query = isbn
? `isbn:${isbn}`
: `intitle:${lookup.title}${lookup.author ? `+inauthor:${lookup.author}` : ""}`;
if (!isbn) {
const matches = await this.searchByMetadata({ title: lookup.title, author: lookup.author, year: lookup.local.year }, config);
return matches[0] ?? null;
}
const query = `isbn:${isbn}`;
const url = new URL("https://www.googleapis.com/books/v1/volumes");
url.searchParams.set("q", query);
url.searchParams.set("maxResults", "1");
@ -32,6 +34,30 @@ export class GoogleBooksProvider implements MetadataProvider {
isbn: isbnFromIndustryIdentifiers(info.industryIdentifiers, lookup.identifiers.isbn13)
};
}
async searchByMetadata(query: MetadataSearchQuery, config: MetadataProviderConfig): Promise<MetadataMatch[]> {
const url = new URL("https://www.googleapis.com/books/v1/volumes");
url.searchParams.set("q", `intitle:${query.title}${query.author ? `+inauthor:${query.author}` : ""}`);
url.searchParams.set("maxResults", "5");
url.searchParams.set("printType", "books");
if (config.apiKey) url.searchParams.set("key", config.apiKey);
const response = await fetch(url, { signal: AbortSignal.timeout(4000) });
if (!response.ok) return [];
const data = (await response.json()) as { items?: Array<{ volumeInfo?: Record<string, unknown> }> };
return (data.items ?? [])
.map((item) => item.volumeInfo)
.filter((info): info is Record<string, unknown> => Boolean(info))
.map((info) => ({
title: stringValue(info.title) ?? undefined,
author: arrayJoin(info.authors),
description: stringValue(info.description),
language: stringValue(info.language),
publisher: stringValue(info.publisher),
publishedDate: stringValue(info.publishedDate),
isbn: isbnFromIndustryIdentifiers(info.industryIdentifiers, query.isbn ? toIsbn13(query.isbn) : null)
}));
}
}
function stringValue(value: unknown): string | null {
@ -45,7 +71,7 @@ function arrayJoin(value: unknown): string | null {
function isbnFromIndustryIdentifiers(value: unknown, expectedIsbn13: string | null): string | null {
if (!Array.isArray(value)) return null;
const entries = value as Array<{ type?: unknown; identifier?: unknown }>;
const matching = entries.find((entry) => toIsbn13(stringValue(entry.identifier) ?? "") === expectedIsbn13)?.identifier;
const matching = entries.find((entry) => Boolean(expectedIsbn13) && toIsbn13(stringValue(entry.identifier) ?? "") === expectedIsbn13)?.identifier;
if (matching) return stringValue(matching);
const isbn13 = entries.find((entry) => entry.type === "ISBN_13")?.identifier;
const isbn10 = entries.find((entry) => entry.type === "ISBN_10")?.identifier;

13
apps/api/src/metadata/adapters/local.provider.ts
View File

@ -1,5 +1,5 @@
import { Injectable } from "@nestjs/common";
import { MetadataLookup, MetadataMatch, MetadataProvider, MetadataProviderConfig } from "../metadata.types.js";
import { MetadataLookup, MetadataMatch, MetadataProvider, MetadataProviderConfig, MetadataSearchQuery } from "../metadata.types.js";
@Injectable()
export class LocalMetadataProvider implements MetadataProvider {
@ -13,4 +13,15 @@ export class LocalMetadataProvider implements MetadataProvider {
identifiers: lookup.identifiers
};
}
async searchByMetadata(query: MetadataSearchQuery, _config: MetadataProviderConfig): Promise<MetadataMatch[]> {
return [
{
title: query.title,
author: query.author,
isbn: query.isbn ?? null,
publishedDate: query.year ?? null
}
];
}
}

50
apps/api/src/metadata/adapters/open-library.provider.ts
View File

@ -1,5 +1,5 @@
import { Injectable } from "@nestjs/common";
import { MetadataLookup, MetadataMatch, MetadataProvider, MetadataProviderConfig } from "../metadata.types.js";
import { MetadataLookup, MetadataMatch, MetadataProvider, MetadataProviderConfig, MetadataSearchQuery } from "../metadata.types.js";
import { toIsbn13 } from "../use-cases/extract-identifiers.js";
@Injectable()
@ -11,26 +11,45 @@ export class OpenLibraryProvider implements MetadataProvider {
if (isbn) {
return this.lookupIsbn(isbn, lookup.identifiers.isbn13);
}
const query = `title:${lookup.title}${lookup.author ? ` author:${lookup.author}` : ""}`;
if (lookup.sourceId) {
return this.lookupEdition(lookup.sourceId, lookup.identifiers.isbn13);
}
const matches = await this.searchByMetadata({ title: lookup.title, author: lookup.author, year: lookup.local.year }, _config);
return matches[0] ?? null;
}
async searchByMetadata(query: MetadataSearchQuery, _config: MetadataProviderConfig): Promise<MetadataMatch[]> {
const url = new URL("https://openlibrary.org/search.json");
url.searchParams.set("q", query);
url.searchParams.set("limit", "1");
url.searchParams.set("title", query.title);
if (query.author) url.searchParams.set("author", query.author);
if (query.year) url.searchParams.set("first_publish_year", query.year);
url.searchParams.set("limit", "5");
const response = await fetch(url, {
headers: { "User-Agent": "ReadaBook/0.1 local-library-manager" },
signal: AbortSignal.timeout(4000)
});
if (!response.ok) return null;
if (!response.ok) return [];
const data = (await response.json()) as { docs?: Array<Record<string, unknown>> };
const doc = data.docs?.[0];
if (!doc) return null;
return {
return (data.docs ?? []).map((doc) => ({
title: stringValue(doc.title) ?? undefined,
sourceId: firstArrayValue(doc.edition_key) ?? stringValue(doc.cover_edition_key),
author: arrayJoin(doc.author_name),
language: firstArrayValue(doc.language),
publisher: firstArrayValue(doc.publisher),
publishedDate: String(doc.first_publish_year ?? "") || null,
isbn: bestIsbn(doc.isbn, lookup.identifiers.isbn13)
};
isbn: bestIsbn(doc.isbn, query.isbn ? toIsbn13(query.isbn) : null)
}));
}
private async lookupEdition(sourceId: string, expectedIsbn13: string | null): Promise<MetadataMatch | null> {
const editionKey = sourceId.replace(/^\/?books\//, "");
if (!editionKey) return null;
const response = await fetch(`https://openlibrary.org/books/${encodeURIComponent(editionKey)}.json`, {
headers: { "User-Agent": "ReadaBook/0.1 local-library-manager" },
signal: AbortSignal.timeout(4000)
});
if (!response.ok) return null;
return this.editionToMatch((await response.json()) as Record<string, unknown>, expectedIsbn13);
}
private async lookupIsbn(isbn: string, expectedIsbn13: string | null): Promise<MetadataMatch | null> {
@ -39,7 +58,10 @@ export class OpenLibraryProvider implements MetadataProvider {
signal: AbortSignal.timeout(4000)
});
if (!response.ok) return null;
const edition = (await response.json()) as Record<string, unknown>;
return this.editionToMatch((await response.json()) as Record<string, unknown>, expectedIsbn13);
}
private async editionToMatch(edition: Record<string, unknown>, expectedIsbn13: string | null): Promise<MetadataMatch> {
const author = await this.lookupAuthorName(edition.authors);
return {
title: stringValue(edition.title) ?? undefined,
@ -81,7 +103,11 @@ function arrayJoin(value: unknown): string | null {
function bestIsbn(value: unknown, expectedIsbn13: string | null): string | null {
if (!Array.isArray(value)) return null;
const values = value.map(String);
return values.find((candidate) => toIsbn13(candidate) === expectedIsbn13) ?? values.find((candidate) => toIsbn13(candidate)) ?? null;
return (
values.find((candidate) => Boolean(expectedIsbn13) && toIsbn13(candidate) === expectedIsbn13) ??
values.find((candidate) => Boolean(toIsbn13(candidate))) ??
null
);
}
function asStringArray(value: unknown): string[] {