library-reads 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Liddle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# library-reads
+
+I read mostly through Libby. I also pick up physical books from the library and from Powell's, and now and then I'm reading something a friend lent me. This package turns a Libby export, plus a small hand-edited extras file, into a typed array of my recent reads, enriched with covers and metadata from Open Library. The output is meant to drop straight onto a "Lately" page: what I've been reading, in the order I read it.
+
+It's built around how I actually read, not around a service. If that happens to match how you read, you're welcome to it.
+
+## How It Works
+
+There are three sources. The bulk comes from a Libby timeline export, a CSV of every loan, which for me is mostly audiobooks. The second is a hand-edited `extras.yaml`: the book I'm reading right now, the physical one I checked out at the branch, the paperback from Powell's, the one a friend pressed into my hands. The third is Open Library, which fills in covers, page counts, publish years, and subjects.
+
+Libby and extras are merged by ISBN. When the same book appears in both, the extras entry wins on status and the dates are kept from both sides. So a Libby `borrowed` and an extras `finished` for the same ISBN become a single `finished` entry that still remembers when I borrowed it. Everything else passes through untouched.
+
+Enrichment is cached hard. The package talks to Open Library politely, one request per second with an identifying User-Agent, and writes what it learns to a cache file you commit to git. After the first build, unchanged books cost nothing.
+
+Each entry carries a `matchQuality` field (`'exact'`, `'fuzzy'`, or `'unmatched'`) so you can programmatically flag the entries that need a human eye, rather than grepping the warnings array for them.
+
+The one thing Libby genuinely cannot tell you is what you're reading right now; its export only lists loans you've already returned. That gap is the main reason `extras.yaml` exists.
+
+## Quick Start
+
+```bash
+pnpm add library-reads
+```
+
+```typescript
+import { getReads } from 'library-reads';
+
+const result = await getReads({
+  libby: { path: './libbytimeline-all-loans.csv' },
+  extras: { path: './extras.yaml' },
+  cache: { path: './library-reads-cache.json' },
+  userAgent: 'my-site/1.0 (me@example.com)',
+});
+
+// result.entries: ReadEntry[], sorted by sortDate descending
+// result.warnings: string[]
+// result.lastEntryDate: string | undefined
+```
+
+`userAgent` is required. Open Library asks callers to identify themselves, and it's easy to forget, so the type makes you pass it.
+
+Each entry comes back shaped roughly like this:
+
+```typescript
+{
+  title: 'The Overstory',
+  author: 'Richard Powers',
+  isbn: '9780393635522',
+  status: 'finished',
+  format: 'physical',
+  startedAt: '2026-04-01',
+  finishedAt: '2026-04-28',
+  sortDate: '2026-04-28',
+  coverUrl: 'https://covers.openlibrary.org/b/id/8758252-L.jpg',
+  pageCount: 502,
+  source: 'library',
+  provenance: 'extras',
+}
+```
+
+A word of warning about the first build: it takes a few minutes. Open Library is rate-limited to one request a second, and most books need two requests, so a few dozen entries adds up. Every build after that is effectively instant, because the cache is committed and the network is only touched for books it hasn't seen. Don't be alarmed the first time; do be glad every time after.
+
+## The `extras.yaml` Shape
+
+This file is hand-edited, and the package validates it strictly. A small example:
+
+```yaml
+# The book I'm reading right now, from Powell's last weekend.
+- title: 'The MANIAC'
+  author: 'Benjamín Labatut'
+  isbn: '9780593654477'
+  status: reading
+  format: physical
+  source: "Powell's"
+  startedAt: '2026-05-20'
+
+# A Libby audiobook I actually finished. Same ISBN as the Libby row,
+# so this promotes that loan from 'borrowed' to 'finished' on merge.
+- isbn: '9781501977831'
+  status: finished
+  finishedAt: '2026-05-22'
+  notes: 'Finished on a long walk. Murderbot stays good.'
+
+# A privately-tracked read. It stays out of the output unless I ask
+# for it with includePrivate, so I can keep a few things off the page.
+- title: 'The Body Keeps the Score'
+  author: 'Bessel van der Kolk'
+  isbn: '9780143127741'
+  status: finished
+  finishedAt: '2026-01-15'
+  private: true
+```
+
+Every entry needs a `status`, and either an `isbn` or both a `title` and an `author` (the package needs at least one way to identify the book). The rest is optional:
+
+- `format`: one of `audiobook`, `ebook`, `physical`.
+- `source`: free text for where the book came from. `'library'`, `"Powell's"`, `'borrowed from Joel'`.
+- `startedAt`, `finishedAt`, `borrowedAt`: ISO dates (`YYYY-MM-DD`).
+- `notes`: a line for yourself.
+- `olid`: an Open Library ID, to pin a specific edition when the automatic match is wrong.
+- `private`: when `true`, the entry is excluded from output unless you pass `includePrivate`.
+
+`status` is one of `borrowed`, `reading`, `finished`, or `abandoned`. The full field reference is the types file; this is just the part you'll touch by hand.
+
+## What This Doesn't Do
+
+This is the part I'd want to read first, so it's the part I'll be most honest about.
+
+**It doesn't integrate with Goodreads or StoryGraph.** I don't use either, so the package is built around Libby and a hand-edited file, because that's how I actually read. If you log your reading to Goodreads or StoryGraph, you already have good options; there are scrapers and RSS-based packages aimed squarely at you. This isn't one of them, and that's a deliberate choice rather than a missing feature. The case study goes into why.
+
+**Open Library doesn't have every book.** This bites harder than you'd expect. Libby's exports carry the ISBN of the exact edition you borrowed, which for audiobooks is usually a 979-prefix ISBN, and Open Library indexes mostly print editions. In practice, roughly two-thirds of a typical Libby export gets a 404 on exact-ISBN lookup. The package handles this without falling over: it remembers the misses so it stops asking, then falls back to a title-and-author search. Those fallbacks are marked `matchQuality === 'fuzzy'` on the entry, so you can surface them for a quick check instead of trusting every one blindly, because a fuzzy search can land on the wrong edition. When one does, the `olid` field in `extras.yaml` pins the right edition.
+
+**Repeat borrows show up as repeat entries.** If you've borrowed The Great Gatsby three times, you'll see it three times. That's on purpose. This is a timeline of a reading life, including the re-reads and the books I keep meaning to finish, not a deduplicated bibliography. "Lately" is about what's been in my life, and sometimes the same book has been in it more than once.
+
+**Currently-reading lives only in extras.** Libby's "all loans" export contains loans you've already returned; it has no idea what you have out right now. That's a limit of the source, not a bug in the package, and it's why the one thing I always keep current in `extras.yaml` is whatever I'm in the middle of.
+
+**It doesn't handle your library card.** The package reads a CSV; it doesn't talk to Libby's API. Getting the export is a manual download for now (in the Libby app: Timeline, then Actions, then Export Timeline). Automating that would mean storing patron credentials and leaning on unsanctioned OverDrive endpoints, and I'd rather not.
+
+In short:
+
+- No Goodreads or StoryGraph.
+- Not every book is in Open Library.
+- Re-reads are not deduplicated.
+- Currently-reading is manual.
+- No login; the CSV is a manual export.
+
+If you hit something outside all of that, open an issue. And before you do, the escape hatches (`olid` to pin an edition, `bust` to refetch specific keys, `cache.ignoreReads` to bypass the cache for a run) cover most of the "this one match is wrong" cases on their own.
+
+## Cache
+
+The cache file is committed to git, not ignored. That's intentional. Builds stay deterministic across clones; a fresh checkout needs no network for books it has already seen; and what Open Library told you becomes part of the project's reproducible state rather than a disposable temp file.
+
+Three options give you surgical control when you need it:
+
+- `cache.maxAgeDays`: refetch any entry older than this many days. Defaults to 180.
+- `cache.bust`: an array of cache keys to force-refetch this run, for when you know a specific record changed.
+- `cache.ignoreReads`: skip reading the cache this run, but still write it, for when you want fresh data without throwing away the file.
+
+Open Library 404s are cached too, so the books it doesn't have stop being re-fetched on every build. The cache is for everything I learned, not just the things I learned successfully.
+
+## Why This Exists
+
+I've gone to the library my whole life, most weeks, on the standing rule that you can take home as many books as you can carry. As life got busier the format shifted more toward audiobooks through Libby, but the habit never changed. This package is the engine behind a "Lately" feature on my site, a small, honest record of what I've been reading. Libraries give a lot away for free and ask for almost nothing back; a page that quietly says "here's what that gift looked like this month" felt like the right way to say thank you. The longer story is in the [case study](https://anthonyliddle.dev) (link to be updated once it's published).
+
+## License
+
+MIT, Anthony Liddle, 2026.

package/dist/index.d.ts

@@ -0,0 +1,400 @@
+//#region src/types.d.ts
+/**
+ * The state of a book in the reader's life.
+ *
+ * `borrowed` means it came into the reader's life (a Libby loan, a library
+ * pickup) but no read-through is asserted. Libby imports default to this.
+ *
+ * `reading`, `finished`, and `abandoned` are reader-asserted states that
+ * typically come from a manual entry in extras, or override a Libby borrow
+ * for the same book.
+ */
+type ReadStatus = 'borrowed' | 'reading' | 'finished' | 'abandoned';
+/**
+ * The physical or digital form of the book. Optional because Libby's export
+ * does not expose this field reliably; Open Library enrichment may populate
+ * it when known, and manual entries in extras can declare it explicitly.
+ */
+type ReadFormat = 'audiobook' | 'ebook' | 'physical';
+/**
+ * Pipeline provenance: which parser produced this entry. This is a structural
+ * value about the data path, not the user-facing origin of the book. For the
+ * latter, see the free-form `source` field on ReadEntry.
+ */
+type ReadSource = 'libby' | 'extras';
+/**
+ * A single book in the reader's recent activity. Dates are ISO date strings
+ * (YYYY-MM-DD), not Date objects, so the output is trivially serializable
+ * and free of timezone surprises.
+ */
+interface ReadEntry {
+  title: string;
+  author: string;
+  isbn?: string;
+  /** Open Library ID, when known. */
+  olid?: string;
+  status: ReadStatus;
+  format?: ReadFormat;
+  /** ISO date (YYYY-MM-DD). */
+  startedAt?: string;
+  /** ISO date (YYYY-MM-DD). */
+  finishedAt?: string;
+  /** ISO date (YYYY-MM-DD). For Libby entries, the borrow date. */
+  borrowedAt?: string;
+  coverUrl?: string;
+  pageCount?: number;
+  publishYear?: number;
+  subjects?: string[];
+  /**
+   * How this entry's enrichment data was matched against Open Library:
+   *
+   * - `exact`: matched by ISBN or OLID.
+   * - `fuzzy`: matched by title+author search, either because the entry had no
+   *   ISBN/OLID to begin with, or because the ISBN lookup returned 404 and we
+   *   fell back to search. Fuzzy matches are right most of the time but worth
+   *   verifying; consider providing an `olid` override in extras.yaml when wrong.
+   * - `unmatched`: no Open Library match at all. Cover and metadata are missing,
+   *   unless filled in from extras (title/author) or from the Libby fallback cover.
+   *
+   * Undefined when enrichment was skipped (`skipEnrichment: true`) or the entry
+   * pre-dates this field's introduction in a cached entry.
+   */
+  matchQuality?: 'exact' | 'fuzzy' | 'unmatched';
+  /**
+   * The canonical date for sorting and "lately" calculations, derived from
+   * status. ISO date string (YYYY-MM-DD). The orchestrator computes this.
+   *
+   * Derivation:
+   * - finished, abandoned -> finishedAt (preferred) or startedAt
+   * - reading -> startedAt
+   * - borrowed -> borrowedAt
+   *
+   * If none of the relevant dates exist, sortDate is the empty string and
+   * the entry will sort to the end. This shouldn't happen for valid entries
+   * but the field is required so consumers don't have to optional-chain.
+   */
+  sortDate: string;
+  /**
+   * Which parser produced this entry. Pipeline provenance, used for debugging
+   * and merge logic. NOT for display; render `source` instead when you want to
+   * show the reader where a book came from.
+   */
+  provenance: ReadSource;
+  /** When true, excluded from output unless the consumer opts in. Set from extras. */
+  private?: boolean;
+  /**
+   * Free-form origin of this read, written by the user or defaulted by the
+   * orchestrator. Examples: 'library', "Powell's", 'Audible', 'borrowed from
+   * Joel'. This is the field a consumer page should render to the reader.
+   *
+   * Distinct from `provenance`, which records which parser produced the entry
+   * (a structural, internal value used for debugging and merge logic, not for
+   * display).
+   */
+  source?: string;
+  /** Library system name, when known (e.g. from Libby). */
+  library?: string;
+  publisher?: string;
+  notes?: string;
+}
+/**
+ * The wrapped result returned by getReads. Wraps the entries array so we can
+ * surface freshness signals and soft warnings (Open Library match fallbacks,
+ * etc.) without throwing them away.
+ */
+interface ReadResult {
+  /** Entries sorted descending by the most recent date available on each entry. */
+  entries: ReadEntry[];
+  /** ISO date of the most recent activity, useful for staleness UI. */
+  lastEntryDate?: string;
+  /** Soft failures and notable events from the build (fallback matches, missing covers, etc.). */
+  warnings: string[];
+}
+/**
+ * The raw shape of a single row from a Libby timeline CSV export, after
+ * parsing but before normalization into a ReadEntry. Fields appear exactly
+ * as they do in the source CSV, with dates normalized to ISO YYYY-MM-DD.
+ * Empty-string fields in the source surface as undefined here.
+ *
+ * Field names match the CSV columns: cover, title, author, publisher, isbn,
+ * timestamp, activity, library, details.
+ */
+interface RawLibbyEntry {
+  /** OverDrive CDN URL for the cover. May be used as fallback if Open Library has no cover. */
+  cover?: string;
+  title: string;
+  author?: string;
+  publisher?: string;
+  /** ISBN as it appeared in the CSV. May be ISBN-10 or ISBN-13; not normalized here. */
+  isbn?: string;
+  /** Borrow date, normalized from the source timestamp to ISO YYYY-MM-DD. */
+  borrowedAt: string;
+  /** The activity column value. In all-loans exports this is always "Borrowed". */
+  activity: string;
+  /** Library system name, e.g. "Washington County Cooperative Library Services". */
+  library?: string;
+  /** Trimmed details column (e.g. "21 days"). Empty/whitespace-only values become undefined. */
+  details?: string;
+}
+/**
+ * The raw shape of a single entry from a hand-edited extras file (YAML or JSON),
+ * after parsing but before normalization into a ReadEntry. Fields appear exactly
+ * as the user wrote them, with status and format validated against their enums
+ * and dates validated against ISO YYYY-MM-DD.
+ *
+ * An entry must have either `isbn` OR both `title` and `author`. Entries
+ * missing both identifier paths are rejected with a warning during parse.
+ */
+interface RawExtrasEntry {
+  isbn?: string;
+  /** Open Library ID, for manual override of fuzzy enrichment matches. */
+  olid?: string;
+  title?: string;
+  author?: string;
+  status: ReadStatus;
+  format?: ReadFormat;
+  /** Free-form origin of this read: 'library', "Powell's", 'Audible', etc. */
+  source?: string;
+  /** ISO date YYYY-MM-DD. */
+  startedAt?: string;
+  /** ISO date YYYY-MM-DD. */
+  finishedAt?: string;
+  /** ISO date YYYY-MM-DD. */
+  borrowedAt?: string;
+  notes?: string;
+  /** If true, the orchestrator will exclude this entry from output by default. */
+  private?: boolean;
+}
+//#endregion
+//#region src/enrich.d.ts
+/** Distilled fields extracted from Open Library; the shape we cache and merge into ReadEntry. */
+interface EnrichmentData {
+  coverUrl?: string;
+  pageCount?: number;
+  publishYear?: number;
+  subjects?: string[];
+  /** The work OLID, normalized (e.g. 'OL12345W'). */
+  olid?: string;
+  format?: ReadFormat;
+}
+/** One row in the cache file. */
+interface CacheEntry {
+  /** ISO date string (YYYY-MM-DD) of when this entry was fetched. */
+  fetchedAt: string;
+  /** The lookup key we used: 'isbn:{isbn}', 'olid:{olid}', or 'title-author:{hash}'. */
+  lookupKey: string;
+  data: EnrichmentData;
+  /**
+   * True when the lookup definitively returned 404 (Open Library doesn't
+   * have this book). Distinguishes "we tried and it isn't there" from
+   * "we got a sparse but valid record." Negative cache entries are
+   * refetched on the same maxAgeDays schedule as positive ones; busting
+   * a key forces a refetch regardless.
+   */
+  notFound?: boolean;
+  /**
+   * How this entry was matched ('exact' | 'fuzzy' | 'unmatched'). Written on
+   * every cache entry created from now on; optional because entries written
+   * before this field existed lack it (a cache hit on such an entry yields an
+   * undefined matchQuality, and we do not refetch just to populate it).
+   */
+  matchQuality?: 'exact' | 'fuzzy' | 'unmatched';
+}
+/** The full cache file shape. Keys are the lookupKey values. */
+type Cache = Record<string, CacheEntry>;
+interface EditionPreferences {
+  /**
+   * Preferred language codes in order of preference (Open Library uses 3-letter codes:
+   * 'eng', 'spa', 'fre', 'jpn', etc.). Tried sequentially; the picker uses the first
+   * language that has at least one matching edition. Default: ['eng'].
+   *
+   * Example: a Spanish-speaking user might pass ['spa', 'eng'] to prefer Spanish
+   * editions but fall back to English when no Spanish edition exists.
+   */
+  languages?: string[];
+  /**
+   * Prefer editions that have BOTH a cover image AND a page count. Default: true.
+   * Set false if you want the original publication edition regardless of completeness.
+   */
+  preferComplete?: boolean;
+  /**
+   * Prefer the most recent edition among otherwise-equal candidates. Default: true.
+   * Set false to prefer the original publication (oldest edition).
+   */
+  preferRecent?: boolean;
+}
+interface EnrichOptions {
+  /** Required: Open Library asks for identifying requests. Format: 'package-name/version (email)'. */
+  userAgent: string;
+  /** The cache to read from and write to. Mutated by the function. */
+  cache: Cache;
+  /**
+   * Refetch entries whose fetchedAt is older than this many days. Default 180.
+   * Open Library data is mostly static but does get corrected occasionally.
+   */
+  maxAgeDays?: number;
+  /** Force-refetch these lookup keys this run, even if cached. Use for surgical corrections. */
+  bust?: string[];
+  /** Disable cache reads (still writes for next build). Useful for debugging enrichment. */
+  ignoreCache?: boolean;
+  /** Injectable fetch for testability. Defaults to globalThis.fetch. */
+  fetchImpl?: typeof globalThis.fetch;
+  /** Minimum ms between requests. Default 1000 (1 req/sec). */
+  rateLimitMs?: number;
+  /**
+   * Shared rate-limiter state. When provided, sequential `enrich` calls
+   * coordinate so that the 1 req/sec budget is honored across the entire
+   * batch, not just within each call. The orchestrator creates one and
+   * passes the same reference to every call.
+   *
+   * Shape: `{ nextAllowedAt: number }` where nextAllowedAt is a millisecond
+   * timestamp. Both reads and writes happen during a single enrich call.
+   *
+   * When omitted, each enrich call uses its own per-call state (correct in
+   * isolation but unsafe in batches).
+   */
+  rateLimiterState?: {
+    nextAllowedAt: number;
+  };
+  /**
+   * Preferences applied when picking a representative edition from a work's editions list.
+   * Defaults are Anglocentric and lean toward complete + recent editions; override via this
+   * option to prefer a different language, original publications, etc.
+   *
+   * Note: the cache stores the picked edition's data, not the raw responses. If you change
+   * these preferences between builds, cached entries reflect the OLD preferences until you
+   * bust them. The package does not auto-detect preference changes; pass
+   * `bust: Object.keys(cache)` to refetch everything and see the new picks take effect.
+   */
+  editionPreferences?: EditionPreferences;
+}
+interface EnrichResult {
+  /** The enriched entry. May equal the input if enrichment had no path or all fields failed. */
+  entry: ReadEntry;
+  /** Soft failures (404 from Open Library, fuzzy match fallback, missing fields, etc.). */
+  warnings: string[];
+  /**
+   * How the entry was matched: 'exact' (ISBN/OLID), 'fuzzy' (title+author
+   * search, primary or fallback), or 'unmatched' (no match at all). Undefined
+   * when a transport failure left the outcome unknown, or when a cache hit came
+   * from an entry written before this field existed. The orchestrator copies a
+   * defined value onto the returned entry's `matchQuality`.
+   */
+  matchQuality?: 'exact' | 'fuzzy' | 'unmatched';
+}
+/**
+ * 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.
+ */
+declare function enrich(entry: ReadEntry, options: EnrichOptions): Promise<EnrichResult>;
+//#endregion
+//#region src/extras.d.ts
+/**
+ * Result of parsing an extras file. Entries is the successfully-parsed and
+ * validated entries; warnings is a list of soft failures collected during
+ * parsing (malformed entries, unknown fields, bad dates).
+ */
+interface ParseExtrasResult {
+  entries: RawExtrasEntry[];
+  warnings: string[];
+}
+/**
+ * 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
+ */
+declare function parseExtras(content: string, format: 'yaml' | 'json'): ParseExtrasResult;
+//#endregion
+//#region src/libby.d.ts
+/**
+ * Result of parsing a Libby CSV. Entries is the successfully-parsed rows;
+ * warnings is a list of soft failures (malformed rows, unparseable dates)
+ * collected during parsing. Parsing does NOT throw on a single bad row;
+ * one weird entry should not kill the whole build.
+ */
+interface ParseLibbyResult {
+  entries: RawLibbyEntry[];
+  warnings: string[];
+}
+/**
+ * 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
+ */
+declare function parseLibbyCsv(csv: string): ParseLibbyResult;
+//#endregion
+//#region src/orchestrator.d.ts
+interface LibbyInput {
+  path?: string;
+  content?: string;
+  fetch?: () => Promise<string>;
+}
+interface ExtrasInput {
+  path?: string;
+  content?: string;
+  /** Required when using `content`; inferred from the path extension when using `path`. */
+  format?: 'yaml' | 'json';
+  fetch?: () => Promise<{
+    content: string;
+    format: 'yaml' | 'json';
+  }>;
+}
+interface CacheConfig {
+  path: string;
+  maxAgeDays?: number;
+  bust?: string[];
+  ignoreReads?: boolean;
+}
+interface GetReadsOptions {
+  libby?: LibbyInput;
+  extras?: ExtrasInput;
+  cache?: CacheConfig;
+  /** Required: Open Library asks for identifying requests. */
+  userAgent: string;
+  /** Skip Open Library enrichment entirely. Default false. */
+  skipEnrichment?: boolean;
+  /** Include entries marked `private: true`. Default false. */
+  includePrivate?: boolean;
+  /** Cap on returned entries after sort. Default unbounded. */
+  limit?: number;
+  /** Edition picker preferences passed through to the enricher. */
+  editionPreferences?: EditionPreferences;
+  /** Override fetch (testability). Passed through to the enricher. */
+  fetchImpl?: typeof globalThis.fetch;
+  /** Min ms between Open Library requests. Default 1000. */
+  rateLimitMs?: number;
+}
+/**
+ * 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
+ */
+declare function getReads(options: GetReadsOptions): Promise<ReadResult>;
+//#endregion
+export { type Cache, type CacheConfig, type CacheEntry, type EditionPreferences, type EnrichOptions, type EnrichResult, type EnrichmentData, type ExtrasInput, type GetReadsOptions, type LibbyInput, type ParseExtrasResult, type ParseLibbyResult, RawExtrasEntry, RawLibbyEntry, ReadEntry, ReadFormat, ReadResult, ReadSource, ReadStatus, enrich, getReads, parseExtras, parseLibbyCsv };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/enrich.ts","../src/extras.ts","../src/libby.ts","../src/orchestrator.ts"],"mappings":"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"}