library-reads 0.1.0

package/dist/index.js

@@ -0,0 +1,1090 @@
+import { createHash } from "node:crypto";
+import { parse } from "yaml";
+import { parse as parse$1 } from "csv-parse/sync";
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { extname } from "node:path";
+//#region src/enrich.ts
+function isString$1(value) {
+	return typeof value === "string";
+}
+function isPlainObject$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Map Open Library's free-form `physical_format` to our format enum. Imperfect by
+* design: anything with a value that is not clearly audio or electronic is treated
+* as physical; the user can override via extras. Missing/empty yields undefined.
+*/
+function inferFormat(physicalFormat) {
+	if (physicalFormat === void 0 || physicalFormat.trim() === "") return;
+	const value = physicalFormat.toLowerCase();
+	if (value.includes("audio") || value.includes("mp3") || value.includes("sound recording")) return "audiobook";
+	if (value.includes("ebook") || value.includes("electronic") || value.includes("online")) return "ebook";
+	return "physical";
+}
+/** Extract a four-digit year from a free-form publish date, or undefined. */
+function extractYear(publishDate) {
+	if (publishDate === void 0) return;
+	const match = publishDate.match(/\d{4}/);
+	return match ? Number(match[0]) : void 0;
+}
+/** Construct the large-cover URL for an Open Library cover ID. */
+function coverUrlFromId(coverId) {
+	return `https://covers.openlibrary.org/b/id/${coverId}-L.jpg`;
+}
+/** Strip hyphens and whitespace from an ISBN; leave everything else as-is. */
+function normalizeIsbn(isbn) {
+	return isbn.replace(/[-\s]/g, "");
+}
+/** Normalize a string for hashing: lowercase, collapse internal whitespace, trim. */
+function normalizeForHash(value) {
+	return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+/** 16-char sha256 prefix of the normalized 'title|author' key, for compact cache keys. */
+function hashTitleAuthor(title, author) {
+	const key = `${normalizeForHash(title)}|${normalizeForHash(author)}`;
+	return createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+/** True when a cache entry is older than maxAgeDays and should be refetched. */
+function shouldRefetch(cacheEntry, maxAgeDays) {
+	const fetchedAt = new Date(cacheEntry.fetchedAt).getTime();
+	return (Date.now() - fetchedAt) / (1e3 * 60 * 60 * 24) > maxAgeDays;
+}
+/** True when an edition is compatible with a language code (missing languages match anything). */
+function editionMatchesLanguage(edition, code) {
+	if (!edition.languages || edition.languages.length === 0) return true;
+	return edition.languages.some((language) => language.key === `/languages/${code}`);
+}
+/** True when an edition has both a cover and a page count. */
+function editionIsComplete(edition) {
+	return edition.covers !== void 0 && edition.covers.length > 0 && edition.number_of_pages !== void 0;
+}
+/**
+* Pick a representative edition from a work's editions list, applying a sequence of
+* filters that each degrade gracefully: format match (when a format is declared),
+* language preference (first preferred language with any match wins), completeness,
+* then recency. Falls back to the first remaining edition when no year resolves a tie.
+*
+* The caller fills in all preference defaults before calling, so this function never
+* has to reason about unset fields.
+*/
+function pickEdition(editions, preferences, entryFormat) {
+	if (editions.length === 0) return;
+	let candidates = editions;
+	if (entryFormat !== void 0) {
+		const matches = candidates.filter((e) => inferFormat(e.physical_format) === entryFormat);
+		if (matches.length > 0) candidates = matches;
+	}
+	for (const code of preferences.languages) {
+		const matches = candidates.filter((e) => editionMatchesLanguage(e, code));
+		if (matches.length > 0) {
+			candidates = matches;
+			break;
+		}
+	}
+	if (preferences.preferComplete) {
+		const matches = candidates.filter(editionIsComplete);
+		if (matches.length > 0) candidates = matches;
+	}
+	const dated = candidates.map((edition) => ({
+		edition,
+		year: extractYear(edition.publish_date)
+	})).filter((item) => item.year !== void 0).sort((a, b) => a.year - b.year);
+	if (dated.length > 0) return preferences.preferRecent ? dated[dated.length - 1].edition : dated[0].edition;
+	return candidates[0];
+}
+/**
+* Apply enrichment data to an entry without overwriting fields the entry already has.
+* User-provided title and author always win; Open Library fills only the gaps.
+*/
+function mergeEnrichment(entry, data) {
+	const merged = { ...entry };
+	if (merged.coverUrl === void 0 && data.coverUrl !== void 0) merged.coverUrl = data.coverUrl;
+	if (merged.pageCount === void 0 && data.pageCount !== void 0) merged.pageCount = data.pageCount;
+	if (merged.publishYear === void 0 && data.publishYear !== void 0) merged.publishYear = data.publishYear;
+	if (merged.subjects === void 0 && data.subjects !== void 0) merged.subjects = data.subjects;
+	if (merged.olid === void 0 && data.olid !== void 0) merged.olid = data.olid;
+	if (merged.format === void 0 && data.format !== void 0) merged.format = data.format;
+	return merged;
+}
+/** Sleep for the given number of milliseconds. */
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Normalize an OLID for lookup keys and endpoint construction: trim and uppercase. */
+function normalizeOlid(olid) {
+	return olid.trim().toUpperCase();
+}
+/** Strip the `/works/` (or `/books/`, `/authors/`) prefix from a key, leaving the OLID. */
+function olidFromKey(key) {
+	const olid = key.split("/").pop();
+	return olid && olid.length > 0 ? olid : void 0;
+}
+/** Narrow an unknown JSON value to the edition fields we read. */
+function asEdition(data) {
+	if (!isPlainObject$1(data)) return {};
+	const edition = {};
+	if (isString$1(data.physical_format)) edition.physical_format = data.physical_format;
+	if (Array.isArray(data.covers)) edition.covers = data.covers.filter((cover) => typeof cover === "number");
+	if (typeof data.number_of_pages === "number") edition.number_of_pages = data.number_of_pages;
+	if (isString$1(data.publish_date)) edition.publish_date = data.publish_date;
+	if (Array.isArray(data.languages)) edition.languages = data.languages.filter(isPlainObject$1).map((language) => language.key).filter(isString$1).map((key) => ({ key }));
+	if (Array.isArray(data.works)) edition.works = data.works.filter(isPlainObject$1).map((work) => work.key).filter(isString$1).map((key) => ({ key }));
+	return edition;
+}
+/** Narrow a `/works/{olid}/editions.json` response to an editions array. */
+function asEditionsList(data) {
+	if (isPlainObject$1(data) && Array.isArray(data.entries)) return data.entries.map(asEdition);
+	return [];
+}
+/** Narrow a work response to its subjects array, if any non-empty strings are present. */
+function asSubjects(data) {
+	if (isPlainObject$1(data) && Array.isArray(data.subjects)) {
+		const subjects = data.subjects.filter(isString$1);
+		return subjects.length > 0 ? subjects : void 0;
+	}
+}
+/** Narrow a `/search.json` response to its first doc's relevant fields. */
+function asSearchDoc(data) {
+	if (!isPlainObject$1(data) || !Array.isArray(data.docs) || data.docs.length === 0) return;
+	const doc = data.docs[0];
+	if (!isPlainObject$1(doc)) return;
+	const result = {};
+	if (isString$1(doc.key)) result.workOlid = olidFromKey(doc.key);
+	if (typeof doc.cover_i === "number") result.coverId = doc.cover_i;
+	if (Array.isArray(doc.subject)) {
+		const subjects = doc.subject.filter(isString$1);
+		if (subjects.length > 0) result.subjects = subjects;
+	}
+	return result;
+}
+/** The work OLID linked from an edition's `works` array, if present. */
+function workOlidFromEdition(edition) {
+	const key = edition.works?.[0]?.key;
+	return key ? olidFromKey(key) : void 0;
+}
+/** Apply an edition's fields to the accumulating enrichment data, filling only gaps. */
+function applyEdition(edition, data) {
+	if (data.coverUrl === void 0 && edition.covers && edition.covers.length > 0) data.coverUrl = coverUrlFromId(edition.covers[0]);
+	if (data.pageCount === void 0 && edition.number_of_pages !== void 0) data.pageCount = edition.number_of_pages;
+	if (data.publishYear === void 0) {
+		const year = extractYear(edition.publish_date);
+		if (year !== void 0) data.publishYear = year;
+	}
+	if (data.format === void 0) {
+		const format = inferFormat(edition.physical_format);
+		if (format !== void 0) data.format = format;
+	}
+}
+/** Whether a string is present and non-whitespace. */
+function isNonEmpty(value) {
+	return value !== void 0 && value.trim() !== "";
+}
+const OPEN_LIBRARY = "https://openlibrary.org";
+/**
+* Enrich a single ReadEntry with metadata from Open Library, using and updating the
+* provided cache. See the module docs and EnrichOptions for the lookup strategy.
+*
+* User-provided title and author always win; Open Library fills only missing fields.
+* The cache is mutated in place and is only written when every request in the lookup
+* sequence succeeded (a 2xx, parseable response). Transport and HTTP failures push a
+* warning, leave the cache untouched (so the next build retries), and return whatever
+* partial enrichment was gathered.
+*/
+async function enrich(entry, options) {
+	const warnings = [];
+	const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+	const maxAgeDays = options.maxAgeDays ?? 180;
+	const rateLimitMs = options.rateLimitMs ?? 1e3;
+	const bust = new Set(options.bust ?? []);
+	const preferences = {
+		languages: options.editionPreferences?.languages ?? ["eng"],
+		preferComplete: options.editionPreferences?.preferComplete ?? true,
+		preferRecent: options.editionPreferences?.preferRecent ?? true
+	};
+	const label = entry.title;
+	let lookupKey;
+	if (isNonEmpty(entry.olid)) lookupKey = `olid:${normalizeOlid(entry.olid)}`;
+	else if (isNonEmpty(entry.isbn)) lookupKey = `isbn:${normalizeIsbn(entry.isbn)}`;
+	else if (isNonEmpty(entry.title) && isNonEmpty(entry.author)) lookupKey = `title-author:${hashTitleAuthor(entry.title, entry.author)}`;
+	else {
+		warnings.push(`Entry '${label}': no enrichment path (missing olid, isbn, and title+author)`);
+		return {
+			entry,
+			warnings,
+			matchQuality: "unmatched"
+		};
+	}
+	const hasTitleAndAuthor = isNonEmpty(entry.title) && isNonEmpty(entry.author);
+	const usable = (c) => c !== void 0 && !bust.has(c.lookupKey) && !shouldRefetch(c, maxAgeDays);
+	if (!options.ignoreCache) {
+		const cached = options.cache[lookupKey];
+		if (usable(cached)) {
+			if (cached.notFound && lookupKey.startsWith("isbn:") && hasTitleAndAuthor) {
+				const fallbackKey = `title-author:${hashTitleAuthor(entry.title, entry.author)}`;
+				const fallback = options.cache[fallbackKey];
+				if (usable(fallback)) return {
+					entry: mergeEnrichment(entry, fallback.data),
+					warnings,
+					matchQuality: fallback.matchQuality
+				};
+			}
+			return {
+				entry: mergeEnrichment(entry, cached.data),
+				warnings,
+				matchQuality: cached.matchQuality
+			};
+		}
+	}
+	const rateLimiter = options.rateLimiterState ?? { nextAllowedAt: 0 };
+	let anyFailure = false;
+	const data = {};
+	const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+	/** Cache a successful (possibly sparse) enrichment under a key. */
+	const writePositive = (key, quality) => {
+		options.cache[key] = {
+			fetchedAt: today,
+			lookupKey: key,
+			data,
+			matchQuality: quality
+		};
+	};
+	/** Cache a definitive 404 ("Open Library has no record") under a key. */
+	const writeNotFound = (key) => {
+		options.cache[key] = {
+			fetchedAt: today,
+			lookupKey: key,
+			data: {},
+			notFound: true,
+			matchQuality: "unmatched"
+		};
+	};
+	/**
+	* Fetch a JSON endpoint with the shared rate limit. A 404 is a definitive
+	* "not found": it returns `{ ok: false, notFound: true }` without a warning
+	* or setting anyFailure, because what a 404 means depends on the caller (a
+	* primary lookup caches it as a dead end; a secondary lookup just yields no
+	* extra data). Transport errors, other non-2xx, and parse failures push a
+	* warning and set anyFailure so the positive cache is skipped and the next
+	* build retries.
+	*/
+	const fetchJson = async (url) => {
+		const now = Date.now();
+		if (now < rateLimiter.nextAllowedAt) await sleep(rateLimiter.nextAllowedAt - now);
+		rateLimiter.nextAllowedAt = Date.now() + rateLimitMs;
+		let response;
+		try {
+			response = await fetchImpl(url, { headers: { "User-Agent": options.userAgent } });
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			warnings.push(`Entry '${label}': failed to reach Open Library (${message})`);
+			anyFailure = true;
+			return {
+				ok: false,
+				notFound: false
+			};
+		}
+		if (response.status === 404) return {
+			ok: false,
+			notFound: true
+		};
+		if (!response.ok) {
+			warnings.push(`Entry '${label}': Open Library returned ${response.status} for ${url}`);
+			anyFailure = true;
+			return {
+				ok: false,
+				notFound: false
+			};
+		}
+		try {
+			return {
+				ok: true,
+				data: await response.json()
+			};
+		} catch {
+			warnings.push(`Entry '${label}': Open Library returned an unparseable response for ${url}`);
+			anyFailure = true;
+			return {
+				ok: false,
+				notFound: false
+			};
+		}
+	};
+	/** Fetch a work and apply its subjects. Secondary lookup; a miss is non-fatal. */
+	const fetchWork = async (workOlid) => {
+		const result = await fetchJson(`${OPEN_LIBRARY}/works/${workOlid}.json`);
+		if (!result.ok) return;
+		data.olid = workOlid;
+		const subjects = asSubjects(result.data);
+		if (data.subjects === void 0 && subjects !== void 0) data.subjects = subjects;
+	};
+	/** Fetch a work's editions list and apply a representative edition. Secondary; a miss is non-fatal. */
+	const fetchRepresentativeEdition = async (workOlid) => {
+		const result = await fetchJson(`${OPEN_LIBRARY}/works/${workOlid}/editions.json`);
+		if (!result.ok) return;
+		const picked = pickEdition(asEditionsList(result.data), preferences, entry.format);
+		if (picked !== void 0) applyEdition(picked, data);
+	};
+	/**
+	* Run the title+author search, applying any matched doc to `data`. Returns
+	* 'found' (a doc matched and was applied), 'empty' (a clean response with no
+	* usable doc: the book is not in Open Library), or 'failed' (a transport/HTTP/
+	* parse problem already warned; leave the cache untouched for a retry). The
+	* caller pushes the verify-this warning, since the wording differs between a
+	* primary search and an ISBN-404 fallback.
+	*/
+	const searchTitleAuthor = async () => {
+		const result = await fetchJson(`${OPEN_LIBRARY}/search.json?title=${encodeURIComponent(entry.title)}&author=${encodeURIComponent(entry.author)}&limit=1`);
+		if (!result.ok) return result.notFound ? "empty" : "failed";
+		const doc = asSearchDoc(result.data);
+		if (doc === void 0) return "empty";
+		if (doc.subjects !== void 0) data.subjects = doc.subjects;
+		if (doc.workOlid !== void 0) {
+			data.olid = doc.workOlid;
+			await fetchRepresentativeEdition(doc.workOlid);
+		}
+		if (data.coverUrl === void 0 && doc.coverId !== void 0) data.coverUrl = coverUrlFromId(doc.coverId);
+		return "found";
+	};
+	const noRecord = `Entry '${label}': Open Library has no record for ${lookupKey}`;
+	let matchQuality;
+	if (isNonEmpty(entry.olid)) {
+		const olid = normalizeOlid(entry.olid);
+		const result = await fetchJson(olid.endsWith("W") ? `${OPEN_LIBRARY}/works/${olid}.json` : `${OPEN_LIBRARY}/books/${olid}.json`);
+		if (result.ok) {
+			if (olid.endsWith("W")) {
+				data.olid = olid;
+				const subjects = asSubjects(result.data);
+				if (subjects !== void 0) data.subjects = subjects;
+				await fetchRepresentativeEdition(olid);
+			} else {
+				const edition = asEdition(result.data);
+				applyEdition(edition, data);
+				const workOlid = workOlidFromEdition(edition);
+				if (workOlid !== void 0) await fetchWork(workOlid);
+			}
+			matchQuality = "exact";
+			if (!anyFailure) writePositive(lookupKey, "exact");
+		} else if (result.notFound) {
+			warnings.push(noRecord);
+			writeNotFound(lookupKey);
+			matchQuality = "unmatched";
+		}
+	} else if (isNonEmpty(entry.isbn)) {
+		const result = await fetchJson(`${OPEN_LIBRARY}/isbn/${normalizeIsbn(entry.isbn)}.json`);
+		if (result.ok) {
+			const edition = asEdition(result.data);
+			applyEdition(edition, data);
+			const workOlid = workOlidFromEdition(edition);
+			if (workOlid !== void 0) await fetchWork(workOlid);
+			matchQuality = "exact";
+			if (!anyFailure) writePositive(lookupKey, "exact");
+		} else if (result.notFound) if (hasTitleAndAuthor) {
+			const fallbackKey = `title-author:${hashTitleAuthor(entry.title, entry.author)}`;
+			const outcome = await searchTitleAuthor();
+			if (outcome === "found") {
+				warnings.push(`Entry '${label}': ISBN not found in Open Library; fell back to title+author search`);
+				matchQuality = "fuzzy";
+				if (!anyFailure) writePositive(fallbackKey, "fuzzy");
+				writeNotFound(lookupKey);
+			} else if (outcome === "empty") {
+				warnings.push(noRecord);
+				writeNotFound(lookupKey);
+				writeNotFound(fallbackKey);
+				matchQuality = "unmatched";
+			}
+		} else {
+			warnings.push(noRecord);
+			writeNotFound(lookupKey);
+			matchQuality = "unmatched";
+		}
+	} else {
+		const outcome = await searchTitleAuthor();
+		if (outcome === "found") {
+			warnings.push(`Entry '${label}': matched by fuzzy title+author search; verify the result and consider adding an olid override`);
+			matchQuality = "fuzzy";
+			if (!anyFailure) writePositive(lookupKey, "fuzzy");
+		} else if (outcome === "empty") {
+			warnings.push(noRecord);
+			writeNotFound(lookupKey);
+			matchQuality = "unmatched";
+		}
+	}
+	return {
+		entry: mergeEnrichment(entry, data),
+		warnings,
+		matchQuality
+	};
+}
+//#endregion
+//#region src/extras.ts
+const READ_STATUSES = [
+	"borrowed",
+	"reading",
+	"finished",
+	"abandoned"
+];
+const READ_FORMATS = [
+	"audiobook",
+	"ebook",
+	"physical"
+];
+/** Fields the schema knows about. Anything else triggers an unknown-field warning. */
+const KNOWN_FIELDS = new Set([
+	"isbn",
+	"olid",
+	"title",
+	"author",
+	"status",
+	"format",
+	"source",
+	"startedAt",
+	"finishedAt",
+	"borrowedAt",
+	"notes",
+	"private"
+]);
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function isString(value) {
+	return typeof value === "string";
+}
+/** A present, non-whitespace string. Whitespace-only counts as empty. */
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
+function isBoolean(value) {
+	return typeof value === "boolean";
+}
+function isPresent(value) {
+	return value !== void 0 && value !== null;
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isReadStatus(value) {
+	return isString(value) && READ_STATUSES.includes(value);
+}
+function isReadFormat(value) {
+	return isString(value) && READ_FORMATS.includes(value);
+}
+/** Render a value for a warning message: strings in single quotes, others as JSON. */
+function show(value) {
+	return isString(value) ? `'${value}'` : JSON.stringify(value);
+}
+/** Human-readable label for an entry in warnings: title, else isbn, else position. */
+function entryLabel(item, index) {
+	if (isNonEmptyString(item.title)) return `'${item.title}'`;
+	if (isNonEmptyString(item.isbn)) return `'${item.isbn}'`;
+	return `#${index + 1}`;
+}
+/** Describe the JSON-ish type of a value for the root-not-a-list warning. */
+function describeType(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	return `a ${typeof value}`;
+}
+/**
+* Validate a present date value against strict ISO YYYY-MM-DD, rejecting
+* rollover dates like 2026-13-45 and non-dates like 2026-02-30. On failure a
+* warning is pushed and undefined is returned.
+*/
+function validateDate(value, field, label, warnings) {
+	if (isString(value) && ISO_DATE.test(value)) {
+		const [year, month, day] = value.split("-").map(Number);
+		const date = new Date(Date.UTC(year, month - 1, day));
+		if (date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day) return value;
+	}
+	warnings.push(`Entry ${label}: '${field}' must be ISO YYYY-MM-DD, got ${show(value)}`);
+}
+/**
+* Validate one raw item against the extras schema. Returns a RawExtrasEntry on
+* success, or undefined (with a warning pushed) when the item is rejected.
+* Unknown fields produce warnings but do not reject the entry.
+*/
+function validateEntry(item, index, warnings) {
+	if (!isPlainObject(item)) {
+		warnings.push(`Entry #${index + 1}: entry must be an object`);
+		return;
+	}
+	const label = entryLabel(item, index);
+	if (!isReadStatus(item.status)) {
+		if (isPresent(item.status)) warnings.push(`Entry ${label}: 'status' must be one of ${READ_STATUSES.join(", ")}, got ${show(item.status)}`);
+		else warnings.push(`Entry ${label}: missing required field 'status'`);
+		return;
+	}
+	const status = item.status;
+	const hasIsbn = isNonEmptyString(item.isbn);
+	const hasTitleAndAuthor = isNonEmptyString(item.title) && isNonEmptyString(item.author);
+	if (!hasIsbn && !hasTitleAndAuthor) {
+		warnings.push(`Entry ${label}: must have either 'isbn' or both 'title' and 'author'`);
+		return;
+	}
+	const entry = { status };
+	for (const field of [
+		"isbn",
+		"olid",
+		"title",
+		"author",
+		"notes"
+	]) {
+		const value = item[field];
+		if (!isPresent(value)) continue;
+		if (!isNonEmptyString(value)) {
+			warnings.push(`Entry ${label}: '${field}' must be a non-empty string`);
+			return;
+		}
+		entry[field] = value;
+	}
+	if (isPresent(item.format)) {
+		if (!isReadFormat(item.format)) {
+			warnings.push(`Entry ${label}: 'format' must be one of ${READ_FORMATS.join(", ")}, got ${show(item.format)}`);
+			return;
+		}
+		entry.format = item.format;
+	}
+	if (isPresent(item.source)) {
+		if (!isNonEmptyString(item.source)) {
+			warnings.push(`Entry ${label}: 'source' must be a non-empty string`);
+			return;
+		}
+		entry.source = item.source;
+	}
+	for (const field of [
+		"startedAt",
+		"finishedAt",
+		"borrowedAt"
+	]) {
+		if (!isPresent(item[field])) continue;
+		const validated = validateDate(item[field], field, label, warnings);
+		if (validated === void 0) return;
+		entry[field] = validated;
+	}
+	if (isPresent(item.private)) {
+		if (!isBoolean(item.private)) {
+			warnings.push(`Entry ${label}: 'private' must be a boolean`);
+			return;
+		}
+		entry.private = item.private;
+	}
+	for (const key of Object.keys(item)) if (!KNOWN_FIELDS.has(key)) warnings.push(`Entry ${label}: unknown field '${key}'`);
+	return entry;
+}
+/**
+* Parse the text content of an extras file into raw entries.
+*
+* The file must be a list (YAML sequence or JSON array) of entry objects.
+* Each entry is validated against the schema; entries that fail validation
+* are skipped with a warning rather than throwing. A completely malformed
+* file (invalid YAML/JSON, root not a list) returns empty entries with one
+* warning describing the failure.
+*
+* @param content the raw text of the extras file
+* @param format 'yaml' or 'json'
+* @returns a ParseExtrasResult with successfully-validated entries and warnings
+*/
+function parseExtras(content, format) {
+	const warnings = [];
+	let parsed;
+	try {
+		parsed = format === "yaml" ? parse(content) : JSON.parse(content);
+	} catch (error) {
+		return {
+			entries: [],
+			warnings: [`Invalid ${format === "yaml" ? "YAML" : "JSON"}: ${error instanceof Error ? error.message : String(error)}`]
+		};
+	}
+	if (!Array.isArray(parsed)) return {
+		entries: [],
+		warnings: [`Extras root must be a list of entries, got ${describeType(parsed)}`]
+	};
+	const entries = [];
+	for (let i = 0; i < parsed.length; i++) {
+		const entry = validateEntry(parsed[i], i, warnings);
+		if (entry !== void 0) entries.push(entry);
+	}
+	return {
+		entries,
+		warnings
+	};
+}
+//#endregion
+//#region src/libby.ts
+/** The exact columns a Libby all-loans export is expected to have, in order. */
+const EXPECTED_COLUMNS = [
+	"cover",
+	"title",
+	"author",
+	"publisher",
+	"isbn",
+	"timestamp",
+	"activity",
+	"library",
+	"details"
+];
+/**
+* Pull the first non-empty line of the CSV and split it into trimmed,
+* lower-cased column names. Returns undefined when there is no such line.
+* Header names never contain commas, so a naive split is sufficient.
+*/
+function extractHeaderColumns(csv) {
+	for (const line of csv.split(/\r?\n/)) {
+		if (line.trim() === "") continue;
+		return line.split(",").map((column) => column.trim().toLowerCase());
+	}
+}
+/** Full English month names to their two-digit number, for date normalization. */
+const MONTHS = new Map([
+	["January", "01"],
+	["February", "02"],
+	["March", "03"],
+	["April", "04"],
+	["May", "05"],
+	["June", "06"],
+	["July", "07"],
+	["August", "08"],
+	["September", "09"],
+	["October", "10"],
+	["November", "11"],
+	["December", "12"]
+]);
+/** Trim a field and treat an empty result as missing. */
+function clean(value) {
+	if (value === void 0) return;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+/**
+* Normalize a Libby timestamp ("Month DD, YYYY HH:MM", US locale) to an ISO
+* date string (YYYY-MM-DD). The time is dropped. Returns undefined when the
+* value is missing or does not match the expected shape.
+*/
+function toIsoDate(timestamp) {
+	if (timestamp === void 0) return;
+	const match = /^([A-Za-z]+)\s+(\d{1,2}),\s+(\d{4})\b/.exec(timestamp.trim());
+	if (match === null) return;
+	const [, monthName, day, year] = match;
+	if (monthName === void 0 || day === void 0 || year === void 0) return;
+	const month = MONTHS.get(monthName);
+	if (month === void 0) return;
+	return `${year}-${month}-${day.padStart(2, "0")}`;
+}
+/**
+* Parse the text of a Libby timeline CSV export into raw entries.
+*
+* Dates are normalized to ISO YYYY-MM-DD. Empty-string fields become undefined.
+* Trailing whitespace and blank lines are tolerated. Rows missing a title or
+* with an unparseable date are skipped with a warning rather than throwing.
+*
+* @param csv the raw text content of a libbytimeline-all-loans.csv file
+* @returns a ParseLibbyResult with successfully-parsed entries and any warnings
+*/
+function parseLibbyCsv(csv) {
+	const entries = [];
+	const warnings = [];
+	const header = extractHeaderColumns(csv);
+	if (header === void 0) {
+		warnings.push(`Header missing: expected [${EXPECTED_COLUMNS.join(", ")}] but the CSV had no header row`);
+		return {
+			entries,
+			warnings
+		};
+	}
+	if (!(header.length === EXPECTED_COLUMNS.length && header.every((column, index) => column === EXPECTED_COLUMNS[index]))) {
+		warnings.push(`Header mismatch: expected [${EXPECTED_COLUMNS.join(", ")}] but found [${header.join(", ")}]`);
+		return {
+			entries,
+			warnings
+		};
+	}
+	const parsed = parse$1(csv, {
+		columns: (record) => record.map((column) => column.trim().toLowerCase()),
+		skip_empty_lines: true,
+		trim: false,
+		relax_column_count: true
+	});
+	const rows = Array.isArray(parsed) ? parsed : [];
+	for (let i = 0; i < rows.length; i++) {
+		const row = rows[i];
+		if (row === void 0) continue;
+		const title = clean(row.title);
+		if (title === void 0) {
+			warnings.push(`Skipping row ${i + 1}: missing title`);
+			continue;
+		}
+		const borrowedAt = toIsoDate(row.timestamp);
+		if (borrowedAt === void 0) {
+			warnings.push(`Skipping "${title}": unparseable date ${JSON.stringify(row.timestamp ?? "")}`);
+			continue;
+		}
+		entries.push({
+			cover: clean(row.cover),
+			title,
+			author: clean(row.author),
+			publisher: clean(row.publisher),
+			isbn: clean(row.isbn),
+			borrowedAt,
+			activity: clean(row.activity) ?? "",
+			library: clean(row.library),
+			details: clean(row.details)
+		});
+	}
+	return {
+		entries,
+		warnings
+	};
+}
+//#endregion
+//#region src/orchestrator.ts
+/** Map `.yaml`/`.yml` to yaml, `.json` to json, anything else to undefined. */
+function inferFormatFromPath(path) {
+	const ext = extname(path).toLowerCase();
+	if (ext === ".yaml" || ext === ".yml") return "yaml";
+	if (ext === ".json") return "json";
+}
+/** Resolve a LibbyInput to its raw text content, dispatching on the mode provided. */
+async function resolveLibbyInput(input) {
+	if (input.content !== void 0) return {
+		content: input.content,
+		warnings: []
+	};
+	if (input.path !== void 0) return {
+		content: await readFile(input.path, "utf-8"),
+		warnings: []
+	};
+	if (input.fetch !== void 0) return {
+		content: await input.fetch(),
+		warnings: []
+	};
+	return { warnings: ["Libby input provided but none of `path`, `content`, or `fetch` was set"] };
+}
+/** Resolve an ExtrasInput to its raw content and format, dispatching on the mode provided. */
+async function resolveExtrasInput(input) {
+	if (input.content !== void 0) {
+		if (input.format === void 0) return { warnings: ["Extras `content` requires an explicit `format` ('yaml' or 'json')"] };
+		return {
+			content: input.content,
+			format: input.format,
+			warnings: []
+		};
+	}
+	if (input.path !== void 0) {
+		const format = inferFormatFromPath(input.path);
+		if (format === void 0) return { warnings: [`Extras path ${input.path} has an unknown extension; expected .yaml, .yml, or .json`] };
+		return {
+			content: await readFile(input.path, "utf-8"),
+			format,
+			warnings: []
+		};
+	}
+	if (input.fetch !== void 0) {
+		const { content, format } = await input.fetch();
+		return {
+			content,
+			format,
+			warnings: []
+		};
+	}
+	return { warnings: ["Extras input provided but none of `path`, `content`, or `fetch` was set"] };
+}
+/**
+* Read and parse the cache file. A missing file is the normal first-build case
+* (empty cache, no warning). Malformed JSON or any other read error yields an
+* empty cache plus a warning, so a bad cache file never blocks a build.
+*/
+async function readCacheFile(path) {
+	let raw;
+	try {
+		raw = await readFile(path, "utf-8");
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return {
+			cache: {},
+			warnings: []
+		};
+		return {
+			cache: {},
+			warnings: [`Cache file ${path} could not be read (${error instanceof Error ? error.message : String(error)}); starting fresh`]
+		};
+	}
+	try {
+		return {
+			cache: JSON.parse(raw),
+			warnings: []
+		};
+	} catch {
+		return {
+			cache: {},
+			warnings: [`Cache file ${path} is not valid JSON; starting fresh`]
+		};
+	}
+}
+/**
+* Write the cache to disk atomically: write a sibling tmp file, then rename it
+* over the target (atomic on POSIX and modern Windows). On failure the tmp file
+* is cleaned up and the error is re-thrown.
+*/
+async function writeCacheFile(path, cache) {
+	const tmpPath = `${path}.tmp`;
+	try {
+		await writeFile(tmpPath, JSON.stringify(cache, null, 2), "utf-8");
+		await rename(tmpPath, path);
+	} catch (error) {
+		await rm(tmpPath, { force: true });
+		throw error;
+	}
+}
+/** Convert a raw Libby row into a borrowed ReadEntry. sortDate is filled later. */
+function normalizeLibbyEntry(raw) {
+	return {
+		title: raw.title,
+		author: raw.author ?? "",
+		isbn: raw.isbn,
+		status: "borrowed",
+		borrowedAt: raw.borrowedAt,
+		library: raw.library,
+		publisher: raw.publisher,
+		source: "library",
+		sortDate: "",
+		provenance: "libby"
+	};
+}
+/** Convert a raw extras entry into a ReadEntry, preserving every user field. sortDate filled later. */
+function normalizeExtrasEntry(raw) {
+	return {
+		title: raw.title ?? "",
+		author: raw.author ?? "",
+		isbn: raw.isbn,
+		olid: raw.olid,
+		status: raw.status,
+		format: raw.format,
+		startedAt: raw.startedAt,
+		finishedAt: raw.finishedAt,
+		borrowedAt: raw.borrowedAt,
+		source: raw.source,
+		notes: raw.notes,
+		private: raw.private,
+		sortDate: "",
+		provenance: "extras"
+	};
+}
+/** Normalize an ISBN for matching: strip hyphens and whitespace, then lowercase. */
+function isbnMatchKey(isbn) {
+	if (isbn === void 0 || isbn.trim() === "") return;
+	return isbn.replace(/[-\s]/g, "").toLowerCase();
+}
+/**
+* Merge a Libby entry and an extras entry that share an ISBN into one entry.
+* The extras entry is canonical: its status wins (so a borrow can be promoted
+* to finished), and most fields prefer extras with Libby as fallback. Dates are
+* additive (a union), and Libby's library/publisher are always preserved.
+*/
+function mergePair(libby, extras) {
+	return {
+		title: extras.title || libby.title,
+		author: extras.author || libby.author,
+		isbn: extras.isbn ?? libby.isbn,
+		olid: extras.olid ?? libby.olid,
+		status: extras.status,
+		format: extras.format ?? libby.format,
+		startedAt: extras.startedAt ?? libby.startedAt,
+		finishedAt: extras.finishedAt ?? libby.finishedAt,
+		borrowedAt: extras.borrowedAt ?? libby.borrowedAt,
+		source: extras.source ?? libby.source,
+		notes: extras.notes ?? libby.notes,
+		private: extras.private ?? false,
+		library: libby.library,
+		publisher: libby.publisher,
+		sortDate: "",
+		provenance: "extras"
+	};
+}
+/**
+* Merge Libby and extras entries by normalized ISBN. Entries sharing an ISBN
+* are merged into one (extras canonical); entries without a counterpart, or
+* without an ISBN at all, pass through unchanged.
+*
+* `libbyCoverByEntry` carries the Libby cover fallback (see getReads). When a
+* merge consumes a Libby entry that had a fallback cover, the association is
+* forwarded to the new merged entry so the fallback survives the merge.
+*/
+function mergeByIsbn(libby, extras, libbyCoverByEntry) {
+	const extrasByIsbn = /* @__PURE__ */ new Map();
+	for (const entry of extras) {
+		const key = isbnMatchKey(entry.isbn);
+		if (key !== void 0) extrasByIsbn.set(key, entry);
+	}
+	const consumed = /* @__PURE__ */ new Set();
+	const merged = [];
+	for (const entry of libby) {
+		const key = isbnMatchKey(entry.isbn);
+		const match = key !== void 0 ? extrasByIsbn.get(key) : void 0;
+		if (key !== void 0 && match !== void 0) {
+			const mergedEntry = mergePair(entry, match);
+			const libbyCover = libbyCoverByEntry.get(entry);
+			if (libbyCover !== void 0) libbyCoverByEntry.set(mergedEntry, libbyCover);
+			merged.push(mergedEntry);
+			consumed.add(key);
+		} else merged.push(entry);
+	}
+	for (const entry of extras) {
+		const key = isbnMatchKey(entry.isbn);
+		if (key !== void 0 && consumed.has(key)) continue;
+		merged.push(entry);
+	}
+	return {
+		merged,
+		warnings: []
+	};
+}
+/** Derive the canonical sort date for an entry from its status. */
+function computeSortDate(entry) {
+	const status = entry.status;
+	if (status === "finished" || status === "abandoned") return entry.finishedAt ?? entry.startedAt ?? "";
+	if (status === "reading") return entry.startedAt ?? "";
+	return entry.borrowedAt ?? "";
+}
+/**
+* Whether a warning signals a transport/HTTP failure (Open Library failing to
+* answer), as opposed to a definitive 404 ("not found"), a fuzzy match, or a
+* missing enrichment path. A 404 is a clean answer, not unavailability, so it
+* must NOT count toward the rollup. The enricher reports a primary 404 as
+* "...has no record for..." (not matched here), but a secondary 404 can still
+* surface as "returned 404", so the status matcher explicitly excludes 404.
+*/
+function isTransportFailure(warning) {
+	if (warning.includes("failed to reach Open Library")) return true;
+	if (warning.includes("Open Library returned an unparseable response")) return true;
+	const httpMatch = /Open Library returned (\d+) for/.exec(warning);
+	return httpMatch !== null && httpMatch[1] !== "404";
+}
+/** Count the warnings that signal a transport/HTTP failure (excludes 404, fuzzy match, no path). */
+function countTransportFailures(warnings) {
+	return warnings.filter(isTransportFailure).length;
+}
+/**
+* The package's main entry point. Reads Libby and/or extras input, parses,
+* normalizes, enriches via Open Library, and returns a sorted, deduplicated,
+* privacy-filtered array of ReadEntry.
+*
+* At least one of `libby` or `extras` must be provided. Calling with neither
+* returns an empty result with a warning.
+*
+* @param options the source inputs, cache config, and behavior flags
+* @returns ReadResult with entries (sorted desc by sortDate), warnings, lastEntryDate
+*/
+async function getReads(options) {
+	const warnings = [];
+	if (options.libby === void 0 && options.extras === void 0) {
+		warnings.push("No input provided: pass at least one of `libby` or `extras`");
+		return {
+			entries: [],
+			warnings
+		};
+	}
+	let libbyContent;
+	if (options.libby !== void 0) {
+		const resolved = await resolveLibbyInput(options.libby);
+		libbyContent = resolved.content;
+		warnings.push(...resolved.warnings);
+	}
+	let extrasContent;
+	let extrasFormat;
+	if (options.extras !== void 0) {
+		const resolved = await resolveExtrasInput(options.extras);
+		extrasContent = resolved.content;
+		extrasFormat = resolved.format;
+		warnings.push(...resolved.warnings);
+	}
+	const libbyRaw = [];
+	if (libbyContent !== void 0) {
+		const parsed = parseLibbyCsv(libbyContent);
+		libbyRaw.push(...parsed.entries);
+		warnings.push(...parsed.warnings);
+	}
+	const extrasRaw = [];
+	if (extrasContent !== void 0 && extrasFormat !== void 0) {
+		const parsed = parseExtras(extrasContent, extrasFormat);
+		extrasRaw.push(...parsed.entries);
+		warnings.push(...parsed.warnings);
+	}
+	let cache = {};
+	if (options.cache !== void 0 && options.cache.ignoreReads !== true) {
+		const resolved = await readCacheFile(options.cache.path);
+		cache = resolved.cache;
+		warnings.push(...resolved.warnings);
+	}
+	const libbyCoverByEntry = /* @__PURE__ */ new Map();
+	const { merged, warnings: mergeWarnings } = mergeByIsbn(libbyRaw.map((raw) => {
+		const entry = normalizeLibbyEntry(raw);
+		if (raw.cover !== void 0 && raw.cover.trim() !== "") libbyCoverByEntry.set(entry, raw.cover);
+		return entry;
+	}), extrasRaw.map(normalizeExtrasEntry), libbyCoverByEntry);
+	warnings.push(...mergeWarnings);
+	let entries = merged;
+	if (options.skipEnrichment !== true) entries = await enrichAll(merged, cache, options, warnings, libbyCoverByEntry);
+	for (const entry of entries) if (entry.coverUrl === void 0) {
+		const libbyCover = libbyCoverByEntry.get(entry);
+		if (libbyCover !== void 0) entry.coverUrl = libbyCover;
+	}
+	for (const entry of entries) entry.sortDate = computeSortDate(entry);
+	if (options.includePrivate !== true) entries = entries.filter((entry) => entry.private !== true);
+	entries.sort((a, b) => a.sortDate < b.sortDate ? 1 : a.sortDate > b.sortDate ? -1 : 0);
+	if (options.limit !== void 0) entries = entries.slice(0, Math.max(0, options.limit));
+	if (options.cache !== void 0) await writeCacheFile(options.cache.path, cache);
+	const lastEntryDate = entries.length > 0 ? entries[0].sortDate : void 0;
+	return {
+		entries,
+		warnings,
+		lastEntryDate
+	};
+}
+/**
+* Enrich every entry with a shared rate limiter and a fetch wrapper that counts
+* requests, so the orchestrator can tell which entries actually hit the network
+* (cache hits and no-path entries never do). Prepends an "Open Library appears
+* to be unavailable" rollup when more than half of the real attempts failed at
+* the transport/HTTP layer.
+*
+* `enrich` returns a fresh entry object, so the Libby cover fallback association
+* is forwarded from each input entry to its enriched counterpart, keeping the
+* post-enrichment fallback pass keyed on the entries that are actually returned.
+*/
+async function enrichAll(merged, cache, options, warnings, libbyCoverByEntry) {
+	const rateLimiterState = { nextAllowedAt: 0 };
+	const baseFetch = options.fetchImpl ?? globalThis.fetch;
+	let fetchCount = 0;
+	const countingFetch = (input, init) => {
+		fetchCount++;
+		return baseFetch(input, init);
+	};
+	let attempts = 0;
+	let failedAttempts = 0;
+	const enriched = [];
+	for (const entry of merged) {
+		const before = fetchCount;
+		const result = await enrich(entry, {
+			userAgent: options.userAgent,
+			cache,
+			fetchImpl: countingFetch,
+			rateLimiterState,
+			rateLimitMs: options.rateLimitMs,
+			editionPreferences: options.editionPreferences,
+			maxAgeDays: options.cache?.maxAgeDays,
+			bust: options.cache?.bust
+		});
+		if (result.matchQuality !== void 0) result.entry.matchQuality = result.matchQuality;
+		enriched.push(result.entry);
+		warnings.push(...result.warnings);
+		const libbyCover = libbyCoverByEntry.get(entry);
+		if (libbyCover !== void 0 && result.entry !== entry) libbyCoverByEntry.set(result.entry, libbyCover);
+		if (fetchCount > before) {
+			attempts += 1;
+			if (countTransportFailures(result.warnings) > 0) failedAttempts += 1;
+		}
+	}
+	if (attempts > 0 && failedAttempts * 2 > attempts) warnings.unshift(`Open Library appears to be unavailable (${failedAttempts} of ${attempts} enrichment attempts failed); cached data was used where possible`);
+	return enriched;
+}
+//#endregion
+export { enrich, getReads, parseExtras, parseLibbyCsv };
+
+//# sourceMappingURL=index.js.map