astro-book-bridge 0.2.0 → 0.2.1

package/dist/catalog.d.ts

@@ -0,0 +1,70 @@
+import { type BookCatalog } from './schema.js';
+import { type ResolvedCoverOptions } from './covers.js';
+export interface MetadataSourceOptions {
+    /** ISBNs to import even when no Goodreads feed is configured. */
+    isbns?: string[];
+    /** Enrich books already fetched from other sources. Defaults to true. */
+    enrich?: boolean;
+}
+export interface GoogleBooksSourceOptions extends MetadataSourceOptions {
+    /** Optional Google Books API key; useful for quota management. */
+    apiKey?: string;
+}
+export interface CoverOptions {
+    /** Keep provider URLs (default) or download reusable copies into public/. */
+    mode?: 'remote' | 'local';
+    /** Directory for local covers, relative to project root. Defaults to public/book-covers. */
+    directory?: string;
+    /** Image URL used when a provider has no cover or a download fails. */
+    fallbackUrl?: string;
+}
+export interface BookBridgeOptions {
+    /** Optional Goodreads shelf RSS URL, for example https://www.goodreads.com/review/list_rss/USER_ID?shelf=read */
+    rssUrl?: string;
+    /** Open Library metadata. `true` enriches ISBNs from the configured feed. */
+    openLibrary?: boolean | MetadataSourceOptions;
+    /** Google Books metadata. `true` enriches ISBNs from the configured feed. */
+    googleBooks?: boolean | GoogleBooksSourceOptions;
+    /** JSON overrides relative to the Astro project root. Missing file means no overrides. */
+    overrides?: string;
+    /** Optional directory of Markdown or MDX review overrides. */
+    markdownOverrides?: string;
+    /** Cache directory relative to the Astro project root. Set false to disable cache. */
+    cache?: string | false;
+    /** Remote or local cover behaviour. */
+    covers?: CoverOptions;
+    /** Optional JSON catalog written after a successful build, relative to project root. */
+    output?: string;
+    /** Request timeout in milliseconds. Defaults to 10 seconds. */
+    timeoutMs?: number;
+    /** Use the last successful RSS response after a fetch failure. Defaults to true. */
+    staleIfError?: boolean;
+    /** Warn (default) or stop the build when sources disagree on a title for the same ID. */
+    conflicts?: 'warn' | 'error';
+}
+/** @deprecated Use BookBridgeOptions. */
+export type GoodreadsBridgeOptions = BookBridgeOptions;
+export interface ResolvedBookBridgeOptions {
+    rssUrl?: string;
+    openLibrary?: Required<MetadataSourceOptions>;
+    googleBooks?: Required<MetadataSourceOptions> & {
+        apiKey?: string;
+    };
+    overrides: string;
+    markdownOverrides: string;
+    cache: string | false;
+    covers: ResolvedCoverOptions;
+    output?: string;
+    timeoutMs: number;
+    staleIfError: boolean;
+    conflicts: 'warn' | 'error';
+    root: string;
+}
+/** @deprecated Use ResolvedBookBridgeOptions. */
+export type ResolvedGoodreadsBridgeOptions = ResolvedBookBridgeOptions;
+export interface CatalogLogger {
+    warn(message: string): void;
+}
+export declare function resolveOptions(options: BookBridgeOptions, root: string): ResolvedBookBridgeOptions;
+/** Fetches, enriches and optionally persists a catalog for the virtual module. */
+export declare function buildCatalog(options: ResolvedBookBridgeOptions, logger?: CatalogLogger): Promise<BookCatalog>;

package/dist/catalog.js

@@ -0,0 +1,184 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, join, resolve } from 'node:path';
+import { parseGoodreadsRss } from './rss.js';
+import { combineSourceBooks, mergeBooks } from './merge.js';
+import { fetchGoogleBooks, fetchOpenLibraryBooks } from './providers.js';
+import { bookOverridesSchema } from './schema.js';
+import { assertValidIsbn } from './identifiers.js';
+import { loadMarkdownOverrides } from './markdown.js';
+import { applyCoverPolicy } from './covers.js';
+export function resolveOptions(options, root) {
+    const sourceOptions = (source) => {
+        if (!source)
+            return undefined;
+        return { isbns: source === true ? [] : source.isbns ?? [], enrich: source === true ? true : source.enrich ?? true };
+    };
+    const openLibrary = sourceOptions(options.openLibrary);
+    const googleBooks = options.googleBooks
+        ? { ...sourceOptions(options.googleBooks), apiKey: options.googleBooks === true ? undefined : options.googleBooks.apiKey }
+        : undefined;
+    const hasDirectIsbns = Boolean(openLibrary?.isbns.length || googleBooks?.isbns.length);
+    for (const value of [...(openLibrary?.isbns ?? []), ...(googleBooks?.isbns ?? [])])
+        assertValidIsbn(value, 'Configured ISBN');
+    if (!options.rssUrl?.trim() && !hasDirectIsbns) {
+        throw new Error('[astro-book-bridge] Configure rssUrl or provide ISBNs to openLibrary/googleBooks.');
+    }
+    return {
+        rssUrl: options.rssUrl?.trim() || undefined,
+        openLibrary,
+        googleBooks,
+        root,
+        overrides: options.overrides ?? 'src/content/book-overrides.json',
+        markdownOverrides: options.markdownOverrides ?? 'src/content/book-overrides',
+        cache: options.cache === false ? false : options.cache ?? '.astro/book-bridge',
+        covers: {
+            mode: options.covers?.mode ?? 'remote',
+            directory: options.covers?.directory ?? 'public/book-covers',
+            fallbackUrl: options.covers?.fallbackUrl,
+        },
+        output: options.output,
+        timeoutMs: options.timeoutMs ?? 10_000,
+        staleIfError: options.staleIfError ?? true,
+        conflicts: options.conflicts ?? 'warn',
+    };
+}
+function atRoot(root, target) {
+    return isAbsolute(target) ? target : resolve(root, target);
+}
+function providerCachePath(cache, provider) {
+    if (!cache)
+        return undefined;
+    if (extname(cache) === '.json') {
+        return provider === 'goodreads-rss' ? cache : `${cache.slice(0, -5)}.${provider}.json`;
+    }
+    return join(cache, `${provider}.json`);
+}
+async function readCache(path, key) {
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        return value.key === key && value.data !== undefined && typeof value.fetchedAt === 'string' ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    await rename(temporary, path);
+}
+async function fetchWithCache(label, path, key, load, options, logger) {
+    try {
+        const data = await load();
+        if (path)
+            await writeJson(path, { data, key, fetchedAt: new Date().toISOString() });
+        return { data, usedCache: false };
+    }
+    catch (error) {
+        const cached = path ? await readCache(path, key) : undefined;
+        if (options.staleIfError && cached) {
+            logger?.warn(`[astro-book-bridge] ${label} fetch failed; using cached data from ${cached.fetchedAt}.`);
+            return { data: cached.data, usedCache: true };
+        }
+        throw error;
+    }
+}
+async function fetchRss(url, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { signal: controller.signal, headers: { Accept: 'application/rss+xml, application/xml, text/xml' } });
+        if (!response.ok)
+            throw new Error(`RSS returned HTTP ${response.status}.`);
+        return await response.text();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function loadOverrides(path) {
+    try {
+        return bookOverridesSchema.parse(JSON.parse(await readFile(path, 'utf8')));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { books: [] };
+        throw new Error(`[astro-book-bridge] Invalid overrides file (${path}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Fetches, enriches and optionally persists a catalog for the virtual module. */
+export async function buildCatalog(options, logger) {
+    const cacheDirectory = options.cache ? atRoot(options.root, options.cache) : undefined;
+    const remoteBooks = [];
+    let usedCache = false;
+    if (options.rssUrl) {
+        try {
+            const result = await fetchWithCache('RSS', providerCachePath(cacheDirectory, 'goodreads-rss'), options.rssUrl, () => fetchRss(options.rssUrl, options.timeoutMs), options, logger);
+            remoteBooks.push(...parseGoodreadsRss(result.data));
+            usedCache ||= result.usedCache;
+        }
+        catch (error) {
+            if (!options.openLibrary && !options.googleBooks) {
+                throw new Error(`[astro-book-bridge] Could not fetch RSS: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            else {
+                logger?.warn(`[astro-book-bridge] RSS fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    const sourceIsbns = remoteBooks.flatMap((book) => [book.isbn13, book.isbn].flatMap((value) => {
+        if (!value)
+            return [];
+        try {
+            return [assertValidIsbn(value, `RSS ISBN for "${book.title}"`)];
+        }
+        catch (error) {
+            logger?.warn(`[astro-book-bridge] ${error instanceof Error ? error.message : String(error)} Skipping metadata enrichment for this identifier.`);
+            return [];
+        }
+    }));
+    const sourceIsbnsFor = (source) => [...new Set([...source.isbns, ...(source.enrich ? sourceIsbns : [])])];
+    if (options.openLibrary) {
+        try {
+            const identifiers = sourceIsbnsFor(options.openLibrary).sort();
+            const result = await fetchWithCache('Open Library', providerCachePath(cacheDirectory, 'open-library'), identifiers.join(','), () => fetchOpenLibraryBooks(identifiers, options.timeoutMs), options, logger);
+            remoteBooks.push(...result.data);
+            usedCache ||= result.usedCache;
+        }
+        catch (error) {
+            logger?.warn(`[astro-book-bridge] Open Library fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const googleBooks = options.googleBooks;
+    if (googleBooks) {
+        try {
+            const identifiers = sourceIsbnsFor(googleBooks).sort();
+            const result = await fetchWithCache('Google Books', providerCachePath(cacheDirectory, 'google-books'), identifiers.join(','), () => fetchGoogleBooks(identifiers, options.timeoutMs, googleBooks.apiKey), options, logger);
+            remoteBooks.push(...result.data);
+            usedCache ||= result.usedCache;
+        }
+        catch (error) {
+            logger?.warn(`[astro-book-bridge] Google Books fetch failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (remoteBooks.length === 0) {
+        throw new Error('[astro-book-bridge] No books could be fetched from the configured sources.');
+    }
+    const overrides = await loadOverrides(atRoot(options.root, options.overrides));
+    const markdownOverrides = await loadMarkdownOverrides(atRoot(options.root, options.markdownOverrides));
+    const combinedBooks = combineSourceBooks(remoteBooks, (message) => {
+        if (options.conflicts === 'error')
+            throw new Error(`[astro-book-bridge] ${message}`);
+        logger?.warn(`[astro-book-bridge] ${message}`);
+    });
+    const books = await applyCoverPolicy(mergeBooks(combinedBooks, [...overrides.books, ...markdownOverrides]), options.root, options.covers, options.timeoutMs, (message) => logger?.warn(message));
+    const catalog = {
+        books,
+        generatedAt: new Date().toISOString(),
+        source: { rssUrl: options.rssUrl, usedCache, providers: [...new Set(combinedBooks.map((book) => book.source ?? 'goodreads-rss'))] },
+    };
+    if (options.output)
+        await writeJson(atRoot(options.root, options.output), catalog);
+    return catalog;
+}

package/dist/covers.d.ts

@@ -0,0 +1,8 @@
+import type { Book } from './schema.js';
+export interface ResolvedCoverOptions {
+    mode: 'remote' | 'local';
+    directory: string;
+    fallbackUrl?: string;
+}
+/** Stores remote covers in public/ while retaining source attribution for templates. */
+export declare function applyCoverPolicy(books: Book[], root: string, options: ResolvedCoverOptions, timeoutMs: number, warn: (message: string) => void): Promise<Book[]>;

package/dist/covers.js

@@ -0,0 +1,79 @@
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { relative, resolve } from 'node:path';
+const extensionsByType = {
+    'image/avif': 'avif',
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/webp': 'webp',
+};
+function localUrl(root, directory, file) {
+    const publicDirectory = resolve(root, 'public');
+    const path = resolve(root, directory, file);
+    const pathFromPublic = relative(publicDirectory, path);
+    if (pathFromPublic.startsWith('..')) {
+        throw new Error('[astro-book-bridge] covers.directory must be inside the project public directory.');
+    }
+    return `/${pathFromPublic.split('\\').join('/')}`;
+}
+async function existingCover(directory, hash) {
+    for (const extension of Object.values(extensionsByType)) {
+        const path = resolve(directory, `${hash}.${extension}`);
+        try {
+            await access(path);
+            return path;
+        }
+        catch {
+            // Try the next common image extension.
+        }
+    }
+    return undefined;
+}
+async function cacheOneCover(book, root, options, timeoutMs) {
+    const originalUrl = book.coverSourceUrl ?? book.imageUrl;
+    if (!originalUrl)
+        return options.fallbackUrl ? { ...book, imageUrl: options.fallbackUrl } : book;
+    const hash = createHash('sha256').update(originalUrl).digest('hex').slice(0, 24);
+    const directory = resolve(root, options.directory);
+    const existing = await existingCover(directory, hash);
+    if (existing) {
+        const extension = existing.split('.').pop();
+        return { ...book, imageUrl: localUrl(root, options.directory, `${hash}.${extension}`), coverSourceUrl: originalUrl, coverAttribution: { provider: book.coverProvider ?? book.source, url: originalUrl } };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(originalUrl, { signal: controller.signal, headers: { Accept: 'image/avif,image/webp,image/png,image/jpeg,image/*;q=0.8' } });
+        if (!response.ok)
+            throw new Error(`returned HTTP ${response.status}`);
+        const contentType = response.headers.get('content-type')?.split(';')[0].toLowerCase() ?? '';
+        if (!contentType.startsWith('image/'))
+            throw new Error(`returned unexpected content type ${contentType || 'unknown'}`);
+        const extension = extensionsByType[contentType] ?? 'jpg';
+        await mkdir(directory, { recursive: true });
+        await writeFile(resolve(directory, `${hash}.${extension}`), Buffer.from(await response.arrayBuffer()));
+        return { ...book, imageUrl: localUrl(root, options.directory, `${hash}.${extension}`), coverSourceUrl: originalUrl, coverAttribution: { provider: book.coverProvider ?? book.source, url: originalUrl } };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Stores remote covers in public/ while retaining source attribution for templates. */
+export async function applyCoverPolicy(books, root, options, timeoutMs, warn) {
+    if (options.mode === 'remote') {
+        return books.map((book) => book.imageUrl ? { ...book, coverSourceUrl: book.coverSourceUrl ?? book.imageUrl, coverAttribution: { provider: book.coverProvider ?? book.source, url: book.coverSourceUrl ?? book.imageUrl } } : options.fallbackUrl ? { ...book, imageUrl: options.fallbackUrl } : book);
+    }
+    const result = [...books];
+    for (let start = 0; start < books.length; start += 4) {
+        await Promise.all(books.slice(start, start + 4).map(async (book, index) => {
+            try {
+                result[start + index] = await cacheOneCover(book, root, options, timeoutMs);
+            }
+            catch (error) {
+                warn(`[astro-book-bridge] Could not cache cover for "${book.title}": ${error instanceof Error ? error.message : String(error)}.`);
+                result[start + index] = options.fallbackUrl ? { ...book, imageUrl: options.fallbackUrl } : book;
+            }
+        }));
+    }
+    return result;
+}

package/dist/identifiers.d.ts

@@ -0,0 +1,6 @@
+/** Removes presentation punctuation from an ISBN while retaining a possible X check digit. */
+export declare function normalizeIsbn(value: string): string;
+export declare function isValidIsbn10(value: string): boolean;
+export declare function isValidIsbn13(value: string): boolean;
+export declare function isValidIsbn(value: string): boolean;
+export declare function assertValidIsbn(value: string, field?: string): string;

package/dist/identifiers.js

@@ -0,0 +1,27 @@
+/** Removes presentation punctuation from an ISBN while retaining a possible X check digit. */
+export function normalizeIsbn(value) {
+    return value.replace(/[^0-9Xx]/g, '').toUpperCase();
+}
+export function isValidIsbn10(value) {
+    const isbn = normalizeIsbn(value);
+    if (!/^\d{9}[\dX]$/.test(isbn))
+        return false;
+    const sum = [...isbn].reduce((total, digit, index) => total + (digit === 'X' ? 10 : Number(digit)) * (10 - index), 0);
+    return sum % 11 === 0;
+}
+export function isValidIsbn13(value) {
+    const isbn = normalizeIsbn(value);
+    if (!/^\d{13}$/.test(isbn))
+        return false;
+    const sum = [...isbn].slice(0, 12).reduce((total, digit, index) => total + Number(digit) * (index % 2 === 0 ? 1 : 3), 0);
+    return (10 - (sum % 10)) % 10 === Number(isbn[12]);
+}
+export function isValidIsbn(value) {
+    return isValidIsbn10(value) || isValidIsbn13(value);
+}
+export function assertValidIsbn(value, field = 'ISBN') {
+    const normalized = normalizeIsbn(value);
+    if (!isValidIsbn(normalized))
+        throw new Error(`${field} must be a valid ISBN-10 or ISBN-13: ${value}.`);
+    return normalized;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { AstroIntegration } from 'astro';
+import { type BookBridgeOptions } from './catalog.js';
+export type { Book, BookCatalog, BookOverride, BookSourceName, GoodreadsBook } from './schema.js';
+export type { BookBridgeOptions, CoverOptions, GoogleBooksSourceOptions, GoodreadsBridgeOptions, MetadataSourceOptions } from './catalog.js';
+export { buildCatalog } from './catalog.js';
+export { parseGoodreadsRss } from './rss.js';
+export { assertValidIsbn, isValidIsbn, isValidIsbn10, isValidIsbn13, normalizeIsbn } from './identifiers.js';
+export declare const virtualModuleId = "astro-book-bridge:catalog";
+/**
+ * Astro integration exposing a multi-source book catalog through
+ * `astro-book-bridge:catalog`.
+ */
+export default function bookBridge(options: BookBridgeOptions): AstroIntegration;

package/dist/index.js

@@ -0,0 +1,71 @@
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { buildCatalog, resolveOptions } from './catalog.js';
+export { buildCatalog } from './catalog.js';
+export { parseGoodreadsRss } from './rss.js';
+export { assertValidIsbn, isValidIsbn, isValidIsbn10, isValidIsbn13, normalizeIsbn } from './identifiers.js';
+export const virtualModuleId = 'astro-book-bridge:catalog';
+const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+function virtualModule(options, logger) {
+    let server;
+    let catalog;
+    const invalidate = () => {
+        catalog = undefined;
+        const module = server?.moduleGraph.getModuleById(resolvedVirtualModuleId);
+        if (module)
+            server?.moduleGraph.invalidateModule(module);
+        server?.ws.send({ type: 'full-reload' });
+    };
+    return {
+        name: 'astro-book-bridge',
+        resolveId(id) {
+            return id === virtualModuleId ? resolvedVirtualModuleId : undefined;
+        },
+        async load(id) {
+            if (id !== resolvedVirtualModuleId)
+                return undefined;
+            catalog ??= buildCatalog(options, logger);
+            const result = await catalog;
+            return `export const catalog = ${JSON.stringify(result)};\nexport const books = catalog.books;\nexport default books;`;
+        },
+        configureServer(devServer) {
+            server = devServer;
+            devServer.watcher.add(resolve(options.root, options.overrides));
+            devServer.watcher.on('change', (path) => {
+                if (path === resolve(options.root, options.overrides))
+                    invalidate();
+            });
+        },
+    };
+}
+/**
+ * Astro integration exposing a multi-source book catalog through
+ * `astro-book-bridge:catalog`.
+ */
+export default function bookBridge(options) {
+    return {
+        name: 'astro-book-bridge',
+        hooks: {
+            'astro:config:setup': ({ config, logger, updateConfig }) => {
+                const root = fileURLToPath(config.root);
+                const resolvedOptions = resolveOptions(options, root);
+                updateConfig({
+                    vite: {
+                        plugins: [virtualModule(resolvedOptions, logger)],
+                    },
+                });
+            },
+            'astro:config:done': ({ injectTypes }) => {
+                injectTypes({
+                    filename: 'astro-book-bridge.d.ts',
+                    content: `declare module '${virtualModuleId}' {
+  import type { Book, BookCatalog } from 'astro-book-bridge';
+  export const catalog: BookCatalog;
+  export const books: Book[];
+  export default books;
+}`,
+                });
+            },
+        },
+    };
+}

package/dist/markdown.d.ts

@@ -0,0 +1,3 @@
+import { type BookOverride } from './schema.js';
+/** Loads one book override per Markdown/MDX file from a directory. */
+export declare function loadMarkdownOverrides(directory: string): Promise<BookOverride[]>;

package/dist/markdown.js

@@ -0,0 +1,47 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { bookOverrideSchema } from './schema.js';
+async function markdownFiles(directory) {
+    try {
+        const entries = await readdir(directory, { withFileTypes: true });
+        const nested = await Promise.all(entries.map(async (entry) => {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory())
+                return markdownFiles(path);
+            return ['.md', '.mdx'].includes(extname(entry.name).toLowerCase()) ? [path] : [];
+        }));
+        return nested.flat();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+function parseFrontmatter(contents, path) {
+    if (!contents.startsWith('---')) {
+        throw new Error(`Markdown override (${path}) must start with YAML frontmatter.`);
+    }
+    const closeIndex = contents.indexOf('\n---', 3);
+    if (closeIndex === -1)
+        throw new Error(`Markdown override (${path}) has unclosed frontmatter.`);
+    const frontmatter = contents.slice(3, closeIndex).trim();
+    const body = contents.slice(closeIndex + 4).trim();
+    const fields = parseYaml(frontmatter);
+    if (!fields || typeof fields !== 'object' || Array.isArray(fields)) {
+        throw new Error(`Markdown override (${path}) frontmatter must be a YAML object.`);
+    }
+    return bookOverrideSchema.parse({ ...fields, review: fields.review ?? (body || undefined) });
+}
+/** Loads one book override per Markdown/MDX file from a directory. */
+export async function loadMarkdownOverrides(directory) {
+    return Promise.all((await markdownFiles(directory)).sort().map(async (path) => {
+        try {
+            return parseFrontmatter(await readFile(path, 'utf8'), path);
+        }
+        catch (error) {
+            throw new Error(`[astro-book-bridge] Invalid Markdown override: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }));
+}

package/dist/merge.d.ts

@@ -0,0 +1,8 @@
+import type { Book, BookOverride, GoodreadsBook } from './schema.js';
+/** Goodreads ID always wins; ISBN13 and ISBN are used only as fallbacks. */
+export declare function mergeBooks(remoteBooks: GoodreadsBook[], overrides: BookOverride[]): Book[];
+/**
+ * Coalesces books returned by multiple providers. Provider order determines
+ * metadata priority: later providers only fill fields that are still missing.
+ */
+export declare function combineSourceBooks(sourceBooks: GoodreadsBook[], onConflict?: (message: string) => void): GoodreadsBook[];

package/dist/merge.js

@@ -0,0 +1,79 @@
+import { normalizeIsbn } from './identifiers.js';
+function normalized(value) {
+    return value ? normalizeIsbn(value) : undefined;
+}
+function key(value) {
+    return normalized(value);
+}
+function uniqueIndex(overrides, field) {
+    const index = new Map();
+    for (const override of overrides) {
+        const value = field === 'goodreadsId' ? override[field] : key(override[field]);
+        if (!value)
+            continue;
+        if (index.has(value)) {
+            throw new Error(`Duplicate ${field} override key: ${value}.`);
+        }
+        index.set(value, override);
+    }
+    return index;
+}
+/** Goodreads ID always wins; ISBN13 and ISBN are used only as fallbacks. */
+export function mergeBooks(remoteBooks, overrides) {
+    const byGoodreadsId = uniqueIndex(overrides, 'goodreadsId');
+    const byIsbn13 = uniqueIndex(overrides, 'isbn13');
+    const byIsbn = uniqueIndex(overrides, 'isbn');
+    return remoteBooks.map((remote) => {
+        const override = (remote.goodreadsId ? byGoodreadsId.get(remote.goodreadsId) : undefined) ??
+            (key(remote.isbn13) ? byIsbn13.get(key(remote.isbn13)) : undefined) ??
+            (key(remote.isbn) ? byIsbn.get(key(remote.isbn)) : undefined);
+        const { goodreadsId: _goodreadsId, isbn: _isbn, isbn13: _isbn13, ...local } = override ?? {};
+        return { ...remote, ...local, source: remote.source ?? 'goodreads-rss', sources: remote.sources ?? [remote.source ?? 'goodreads-rss'] };
+    });
+}
+function identifierKey(value) {
+    return value?.trim() || undefined;
+}
+/**
+ * Coalesces books returned by multiple providers. Provider order determines
+ * metadata priority: later providers only fill fields that are still missing.
+ */
+export function combineSourceBooks(sourceBooks, onConflict) {
+    const books = [];
+    const byGoodreadsId = new Map();
+    const byIsbn13 = new Map();
+    const byIsbn = new Map();
+    for (const incoming of sourceBooks) {
+        const match = (identifierKey(incoming.goodreadsId) ? byGoodreadsId.get(identifierKey(incoming.goodreadsId)) : undefined) ??
+            (key(incoming.isbn13) ? byIsbn13.get(key(incoming.isbn13)) : undefined) ??
+            (key(incoming.isbn) ? byIsbn.get(key(incoming.isbn)) : undefined);
+        const book = match ?? { ...incoming, coverProvider: incoming.coverProvider ?? (incoming.imageUrl ? incoming.source : undefined), sources: [incoming.source ?? 'goodreads-rss'] };
+        if (match) {
+            const hadImage = Boolean(book.imageUrl);
+            if (match.title.localeCompare(incoming.title, undefined, { sensitivity: 'base' }) !== 0) {
+                const identifier = incoming.goodreadsId ?? incoming.isbn13 ?? incoming.isbn ?? 'unknown identifier';
+                onConflict?.(`Conflicting titles for ${identifier}: "${match.title}" (${match.source ?? 'unknown'}) and "${incoming.title}" (${incoming.source ?? 'unknown'}). Keeping the first source.`);
+            }
+            for (const [field, value] of Object.entries(incoming)) {
+                if (value !== undefined && book[field] === undefined) {
+                    book[field] = value;
+                }
+            }
+            if (!hadImage && incoming.imageUrl)
+                book.coverProvider = incoming.coverProvider ?? incoming.source;
+            const source = incoming.source;
+            if (source && !book.sources?.includes(source))
+                book.sources = [...(book.sources ?? []), source];
+        }
+        else {
+            books.push(book);
+        }
+        if (book.goodreadsId)
+            byGoodreadsId.set(book.goodreadsId, book);
+        if (key(book.isbn13))
+            byIsbn13.set(key(book.isbn13), book);
+        if (key(book.isbn))
+            byIsbn.set(key(book.isbn), book);
+    }
+    return books;
+}

package/dist/providers.d.ts

@@ -0,0 +1,4 @@
+import type { GoodreadsBook } from './schema.js';
+export declare function fetchJson(url: string, timeoutMs: number): Promise<unknown>;
+export declare function fetchOpenLibraryBooks(isbns: string[], timeoutMs: number): Promise<GoodreadsBook[]>;
+export declare function fetchGoogleBooks(isbns: string[], timeoutMs: number, apiKey?: string): Promise<GoodreadsBook[]>;

package/dist/providers.js

@@ -0,0 +1,95 @@
+import { normalizeIsbn } from './identifiers.js';
+function text(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function stringList(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string' && Boolean(item.trim())) : undefined;
+}
+function objectList(value) {
+    return Array.isArray(value) ? value.filter((item) => Boolean(item) && typeof item === 'object') : undefined;
+}
+export async function fetchJson(url, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { signal: controller.signal, headers: { Accept: 'application/json' } });
+        if (!response.ok)
+            throw new Error(`returned HTTP ${response.status}.`);
+        return await response.json();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function fetchOpenLibraryBooks(isbns, timeoutMs) {
+    const identifiers = [...new Set(isbns.map(normalizeIsbn).filter(Boolean))];
+    if (identifiers.length === 0)
+        return [];
+    const url = new URL('https://openlibrary.org/api/books.json');
+    url.searchParams.set('bibkeys', identifiers.map((value) => `ISBN:${value}`).join(','));
+    url.searchParams.set('jscmd', 'data');
+    const response = await fetchJson(url.toString(), timeoutMs);
+    return Object.values(response).flatMap((entry) => {
+        if (!entry || typeof entry !== 'object')
+            return [];
+        const data = entry;
+        const title = text(data.title);
+        if (!title)
+            return [];
+        const identifiers = data.identifiers;
+        const cover = data.cover;
+        return [{
+                source: 'open-library',
+                title,
+                author: objectList(data.authors)?.map((author) => text(author.name)).filter(Boolean).join(', ') || undefined,
+                isbn: stringList(identifiers?.isbn_10)?.[0],
+                isbn13: stringList(identifiers?.isbn_13)?.[0],
+                link: text(data.url),
+                imageUrl: text(cover?.large) ?? text(cover?.medium) ?? text(cover?.small),
+                coverSourceUrl: text(cover?.large) ?? text(cover?.medium) ?? text(cover?.small),
+                coverProvider: text(cover?.large) ?? text(cover?.medium) ?? text(cover?.small) ? 'open-library' : undefined,
+                description: text(data.description),
+                publisher: objectList(data.publishers)?.map((publisher) => text(publisher.name)).filter(Boolean).join(', ') || undefined,
+                publishedDate: text(data.publish_date),
+                pageCount: typeof data.number_of_pages === 'number' ? data.number_of_pages : undefined,
+                subjects: objectList(data.subjects)?.map((subject) => text(subject.name)).filter((subject) => Boolean(subject)),
+                previewLink: objectList(data.ebooks)?.map((ebook) => text(ebook.preview_url)).find(Boolean),
+            }];
+    });
+}
+export async function fetchGoogleBooks(isbns, timeoutMs, apiKey) {
+    const books = await Promise.all([...new Set(isbns.map(normalizeIsbn).filter(Boolean))].map(async (value) => {
+        const url = new URL('https://www.googleapis.com/books/v1/volumes');
+        url.searchParams.set('q', `isbn:${value}`);
+        if (apiKey)
+            url.searchParams.set('key', apiKey);
+        const response = await fetchJson(url.toString(), timeoutMs);
+        const volume = response.items?.[0];
+        const info = volume?.volumeInfo;
+        const title = text(info?.title);
+        if (!title)
+            return undefined;
+        const industryIdentifiers = Array.isArray(info?.industryIdentifiers) ? info?.industryIdentifiers : [];
+        const cover = info?.imageLinks;
+        return {
+            source: 'google-books',
+            title,
+            author: stringList(info?.authors)?.join(', '),
+            isbn: text(industryIdentifiers.find((id) => id.type === 'ISBN_10')?.identifier),
+            isbn13: text(industryIdentifiers.find((id) => id.type === 'ISBN_13')?.identifier),
+            link: text(info?.infoLink),
+            previewLink: text(info?.previewLink),
+            imageUrl: text(cover?.thumbnail)?.replace(/^http:/, 'https:'),
+            coverSourceUrl: text(cover?.thumbnail)?.replace(/^http:/, 'https:'),
+            coverProvider: text(cover?.thumbnail) ? 'google-books' : undefined,
+            description: text(info?.description),
+            averageRating: typeof info?.averageRating === 'number' ? info.averageRating : undefined,
+            publisher: text(info?.publisher),
+            publishedDate: text(info?.publishedDate),
+            pageCount: typeof info?.pageCount === 'number' ? info.pageCount : undefined,
+            subjects: stringList(info?.categories),
+            language: text(info?.language),
+        };
+    }));
+    return books.filter((book) => Boolean(book));
+}

package/dist/rss.d.ts

@@ -0,0 +1,3 @@
+import type { GoodreadsBook } from './schema.js';
+/** Parses the Goodreads shelf RSS XML into stable, source-only book fields. */
+export declare function parseGoodreadsRss(xml: string): GoodreadsBook[];

package/dist/rss.js

@@ -0,0 +1,57 @@
+import { XMLParser } from 'fast-xml-parser';
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    trimValues: true,
+    parseTagValue: false,
+});
+function text(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const result = String(value).trim();
+    return result || undefined;
+}
+function number(value) {
+    const result = Number(text(value));
+    return Number.isFinite(result) ? result : undefined;
+}
+function values(value) {
+    if (Array.isArray(value))
+        return value;
+    if (value && typeof value === 'object')
+        return [value];
+    return [];
+}
+function idFromLink(link) {
+    return link?.match(/(?:book\/show|review\/show)\/(\d+)/)?.[1];
+}
+/** Parses the Goodreads shelf RSS XML into stable, source-only book fields. */
+export function parseGoodreadsRss(xml) {
+    const document = parser.parse(xml);
+    const items = values(document.rss?.channel?.item);
+    if (!document.rss?.channel) {
+        throw new Error('The response is not a valid RSS document (missing rss.channel).');
+    }
+    return items.flatMap((item) => {
+        const title = text(item.title);
+        if (!title)
+            return [];
+        const link = text(item.link);
+        return [{
+                source: 'goodreads-rss',
+                title,
+                goodreadsId: text(item.book_id) ?? idFromLink(text(item.guid)) ?? idFromLink(link),
+                isbn: text(item.isbn),
+                isbn13: text(item.isbn13),
+                author: text(item.author_name) ?? text(item['dc:creator']),
+                link,
+                imageUrl: text(item.book_image_url) ?? text(item.image_url),
+                coverSourceUrl: text(item.book_image_url) ?? text(item.image_url),
+                coverProvider: text(item.book_image_url) ?? text(item.image_url) ? 'goodreads-rss' : undefined,
+                description: text(item.book_description) ?? text(item.description),
+                averageRating: number(item.average_rating),
+                userRating: number(item.user_rating),
+                readAt: text(item.user_read_at),
+                addedAt: text(item.user_date_added) ?? text(item.pubDate),
+            }];
+    });
+}

package/dist/schema.d.ts

@@ -0,0 +1,257 @@
+import { z } from 'zod';
+export declare const bookOverrideSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    goodreadsId: z.ZodOptional<z.ZodString>;
+    isbn: z.ZodOptional<z.ZodString>;
+    isbn13: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+    review: z.ZodOptional<z.ZodString>;
+    recommended: z.ZodOptional<z.ZodBoolean>;
+    featured: z.ZodOptional<z.ZodBoolean>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    goodreadsId?: string | undefined;
+    isbn?: string | undefined;
+    isbn13?: string | undefined;
+    slug?: string | undefined;
+    note?: string | undefined;
+    review?: string | undefined;
+    recommended?: boolean | undefined;
+    featured?: boolean | undefined;
+    tags?: string[] | undefined;
+}, {
+    goodreadsId?: string | undefined;
+    isbn?: string | undefined;
+    isbn13?: string | undefined;
+    slug?: string | undefined;
+    note?: string | undefined;
+    review?: string | undefined;
+    recommended?: boolean | undefined;
+    featured?: boolean | undefined;
+    tags?: string[] | undefined;
+}>, {
+    goodreadsId?: string | undefined;
+    isbn?: string | undefined;
+    isbn13?: string | undefined;
+    slug?: string | undefined;
+    note?: string | undefined;
+    review?: string | undefined;
+    recommended?: boolean | undefined;
+    featured?: boolean | undefined;
+    tags?: string[] | undefined;
+}, {
+    goodreadsId?: string | undefined;
+    isbn?: string | undefined;
+    isbn13?: string | undefined;
+    slug?: string | undefined;
+    note?: string | undefined;
+    review?: string | undefined;
+    recommended?: boolean | undefined;
+    featured?: boolean | undefined;
+    tags?: string[] | undefined;
+}>, {
+    goodreadsId?: string | undefined;
+    isbn?: string | undefined;
+    isbn13?: string | undefined;
+    slug?: string | undefined;
+    note?: string | undefined;
+    review?: string | undefined;
+    recommended?: boolean | undefined;
+    featured?: boolean | undefined;
+    tags?: string[] | undefined;
+}, {
+    goodreadsId?: string | undefined;
+    isbn?: string | undefined;
+    isbn13?: string | undefined;
+    slug?: string | undefined;
+    note?: string | undefined;
+    review?: string | undefined;
+    recommended?: boolean | undefined;
+    featured?: boolean | undefined;
+    tags?: string[] | undefined;
+}>, {
+    goodreadsId?: string | undefined;
+    isbn?: string | undefined;
+    isbn13?: string | undefined;
+    slug?: string | undefined;
+    note?: string | undefined;
+    review?: string | undefined;
+    recommended?: boolean | undefined;
+    featured?: boolean | undefined;
+    tags?: string[] | undefined;
+}, {
+    goodreadsId?: string | undefined;
+    isbn?: string | undefined;
+    isbn13?: string | undefined;
+    slug?: string | undefined;
+    note?: string | undefined;
+    review?: string | undefined;
+    recommended?: boolean | undefined;
+    featured?: boolean | undefined;
+    tags?: string[] | undefined;
+}>;
+export declare const bookOverridesSchema: z.ZodObject<{
+    books: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodObject<{
+        goodreadsId: z.ZodOptional<z.ZodString>;
+        isbn: z.ZodOptional<z.ZodString>;
+        isbn13: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodString>;
+        review: z.ZodOptional<z.ZodString>;
+        recommended: z.ZodOptional<z.ZodBoolean>;
+        featured: z.ZodOptional<z.ZodBoolean>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        goodreadsId?: string | undefined;
+        isbn?: string | undefined;
+        isbn13?: string | undefined;
+        slug?: string | undefined;
+        note?: string | undefined;
+        review?: string | undefined;
+        recommended?: boolean | undefined;
+        featured?: boolean | undefined;
+        tags?: string[] | undefined;
+    }, {
+        goodreadsId?: string | undefined;
+        isbn?: string | undefined;
+        isbn13?: string | undefined;
+        slug?: string | undefined;
+        note?: string | undefined;
+        review?: string | undefined;
+        recommended?: boolean | undefined;
+        featured?: boolean | undefined;
+        tags?: string[] | undefined;
+    }>, {
+        goodreadsId?: string | undefined;
+        isbn?: string | undefined;
+        isbn13?: string | undefined;
+        slug?: string | undefined;
+        note?: string | undefined;
+        review?: string | undefined;
+        recommended?: boolean | undefined;
+        featured?: boolean | undefined;
+        tags?: string[] | undefined;
+    }, {
+        goodreadsId?: string | undefined;
+        isbn?: string | undefined;
+        isbn13?: string | undefined;
+        slug?: string | undefined;
+        note?: string | undefined;
+        review?: string | undefined;
+        recommended?: boolean | undefined;
+        featured?: boolean | undefined;
+        tags?: string[] | undefined;
+    }>, {
+        goodreadsId?: string | undefined;
+        isbn?: string | undefined;
+        isbn13?: string | undefined;
+        slug?: string | undefined;
+        note?: string | undefined;
+        review?: string | undefined;
+        recommended?: boolean | undefined;
+        featured?: boolean | undefined;
+        tags?: string[] | undefined;
+    }, {
+        goodreadsId?: string | undefined;
+        isbn?: string | undefined;
+        isbn13?: string | undefined;
+        slug?: string | undefined;
+        note?: string | undefined;
+        review?: string | undefined;
+        recommended?: boolean | undefined;
+        featured?: boolean | undefined;
+        tags?: string[] | undefined;
+    }>, {
+        goodreadsId?: string | undefined;
+        isbn?: string | undefined;
+        isbn13?: string | undefined;
+        slug?: string | undefined;
+        note?: string | undefined;
+        review?: string | undefined;
+        recommended?: boolean | undefined;
+        featured?: boolean | undefined;
+        tags?: string[] | undefined;
+    }, {
+        goodreadsId?: string | undefined;
+        isbn?: string | undefined;
+        isbn13?: string | undefined;
+        slug?: string | undefined;
+        note?: string | undefined;
+        review?: string | undefined;
+        recommended?: boolean | undefined;
+        featured?: boolean | undefined;
+        tags?: string[] | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    books: {
+        goodreadsId?: string | undefined;
+        isbn?: string | undefined;
+        isbn13?: string | undefined;
+        slug?: string | undefined;
+        note?: string | undefined;
+        review?: string | undefined;
+        recommended?: boolean | undefined;
+        featured?: boolean | undefined;
+        tags?: string[] | undefined;
+    }[];
+}, {
+    books?: {
+        goodreadsId?: string | undefined;
+        isbn?: string | undefined;
+        isbn13?: string | undefined;
+        slug?: string | undefined;
+        note?: string | undefined;
+        review?: string | undefined;
+        recommended?: boolean | undefined;
+        featured?: boolean | undefined;
+        tags?: string[] | undefined;
+    }[] | undefined;
+}>;
+export type BookOverride = z.infer<typeof bookOverrideSchema>;
+export type BookOverrides = z.infer<typeof bookOverridesSchema>;
+export type BookSourceName = 'goodreads-rss' | 'open-library' | 'google-books';
+export interface GoodreadsBook {
+    source?: BookSourceName;
+    sources?: BookSourceName[];
+    goodreadsId?: string;
+    isbn?: string;
+    isbn13?: string;
+    title: string;
+    author?: string;
+    link?: string;
+    imageUrl?: string;
+    description?: string;
+    averageRating?: number;
+    userRating?: number;
+    readAt?: string;
+    addedAt?: string;
+    publisher?: string;
+    publishedDate?: string;
+    pageCount?: number;
+    subjects?: string[];
+    language?: string;
+    previewLink?: string;
+    /** Original provider URL for a remote cover, retained when a local cover cache is used. */
+    coverSourceUrl?: string;
+    /** Provider that supplied the active cover; may differ from the book's primary metadata source. */
+    coverProvider?: BookSourceName;
+    coverAttribution?: {
+        provider: BookSourceName;
+        url: string;
+    };
+}
+export type Book = GoodreadsBook & Omit<BookOverride, 'goodreadsId' | 'isbn' | 'isbn13'> & {
+    /** First configured source that supplied this book. */
+    source: BookSourceName;
+    /** Every configured source successfully merged into this book. */
+    sources: BookSourceName[];
+};
+export interface BookCatalog {
+    books: Book[];
+    generatedAt: string;
+    source: {
+        rssUrl?: string;
+        usedCache: boolean;
+        providers: BookSourceName[];
+    };
+}

package/dist/schema.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { isValidIsbn, isValidIsbn13 } from './identifiers.js';
+const identifier = z.string().trim().min(1);
+export const bookOverrideSchema = z
+    .object({
+    goodreadsId: identifier.optional(),
+    isbn: identifier.optional(),
+    isbn13: identifier.optional(),
+    slug: z.string().trim().min(1).optional(),
+    note: z.string().optional(),
+    review: z.string().optional(),
+    recommended: z.boolean().optional(),
+    featured: z.boolean().optional(),
+    tags: z.array(z.string()).optional(),
+})
+    .refine((book) => book.goodreadsId || book.isbn || book.isbn13, {
+    message: 'Each override needs goodreadsId, isbn, or isbn13.',
+})
+    .refine((book) => !book.isbn || isValidIsbn(book.isbn), {
+    message: 'isbn must be a valid ISBN-10 or ISBN-13.',
+    path: ['isbn'],
+})
+    .refine((book) => !book.isbn13 || isValidIsbn13(book.isbn13), {
+    message: 'isbn13 must be a valid ISBN-13.',
+    path: ['isbn13'],
+});
+export const bookOverridesSchema = z.object({
+    books: z.array(bookOverrideSchema).default([]),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-book-bridge",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "packageManager": "pnpm@12.4.2",
   "description": "Build a typed, locally enriched Astro book catalog from Goodreads RSS, Open Library and Google Books.",
   "type": "module",