mcp-libraryofcongress 1.0.0

package/dist/loc/client.js

@@ -0,0 +1,987 @@
+// src/errors.ts
+var LocError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "LocError";
+    this.code = code;
+    this.details = details;
+  }
+};
+var notFound = (message, details) => new LocError("not_found", message, details);
+var invalidInput = (message, hint) => new LocError("invalid_input", message, hint ? { hint } : {});
+var rateLimited = (message, details) => new LocError("rate_limited", message, {
+  hint: "Wait a moment and ask again. This says nothing about whether the Library holds what you asked for.",
+  ...details
+});
+var parseFailure = (message, details) => new LocError("parse_failure", message, {
+  hint: "The Library may have changed how it answers. Please report this at https://github.com/smeet666/mcp-libraryofcongress/issues with the arguments you used.",
+  ...details
+});
+var networkError = (message, details) => new LocError("network_error", message, details);
+var timeout = (message, details) => new LocError("timeout", message, details);
+
+// src/version.ts
+var PKG_VERSION = "1.0.0";
+var REPO_URL = "https://github.com/smeet666/mcp-libraryofcongress";
+
+// src/config.ts
+var LOG_LEVELS = ["silent", "error", "info", "debug"];
+var MIN_ALLOWED_INTERVAL_MS = 3e3;
+var MAX_ALLOWED_INTERVAL_MS = 6e4;
+var DEFAULT_INTERVAL_MS = 6e3;
+var DEFAULT_NEWSPAPER_TIMEOUT_MS = 9e4;
+var DEFAULT_USER_AGENT = `mcp-libraryofcongress/${PKG_VERSION} (+${REPO_URL})`;
+function createLogger(level) {
+  const rank = LOG_LEVELS.indexOf(level);
+  const write = (at, message) => {
+    if (rank === 0 || LOG_LEVELS.indexOf(at) > rank) return;
+    process.stderr.write(`[mcp-libraryofcongress] ${at}: ${message}
+`);
+  };
+  return {
+    debug: (m) => write("debug", m),
+    info: (m) => write("info", m),
+    // A warning goes out at the error level so it survives the default
+    // setting: a caller has to know that rows were dropped.
+    warn: (m) => write("error", m),
+    error: (m) => write("error", m)
+  };
+}
+function readInteger(env, name, fallback, min, max) {
+  const raw = env[name];
+  if (raw === void 0 || raw.trim() === "") return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+    process.stderr.write(
+      `[mcp-libraryofcongress] error: ${name}="${raw}" is not a whole number; using ${fallback}.
+`
+    );
+    return fallback;
+  }
+  if (value < min || value > max) {
+    process.stderr.write(
+      `[mcp-libraryofcongress] error: ${name}=${value} is outside ${min}..${max}; using ${fallback}.
+`
+    );
+    return fallback;
+  }
+  return value;
+}
+function loadConfig(env = process.env) {
+  const level = env.LOC_LOG_LEVEL;
+  const logLevel = level && LOG_LEVELS.includes(level) ? level : "error";
+  if (level && !LOG_LEVELS.includes(level)) {
+    process.stderr.write(
+      `[mcp-libraryofcongress] error: LOC_LOG_LEVEL="${level}" is not one of ${LOG_LEVELS.join(", ")}; using error.
+`
+    );
+  }
+  const custom = env.LOC_USER_AGENT?.trim();
+  return {
+    // A caller who wants to be recognised may say who they are, and the
+    // contact address stays attached: the Library has to be able to reach a
+    // human about traffic it did not expect.
+    userAgent: custom ? `${custom} ${DEFAULT_USER_AGENT}` : DEFAULT_USER_AGENT,
+    minIntervalMs: readInteger(
+      env,
+      "LOC_MIN_INTERVAL_MS",
+      DEFAULT_INTERVAL_MS,
+      MIN_ALLOWED_INTERVAL_MS,
+      MAX_ALLOWED_INTERVAL_MS
+    ),
+    // A catalogue page carries a row for every match on it.
+    timeoutMs: readInteger(env, "LOC_TIMEOUT_MS", 3e4, 1e3, 12e4),
+    newspaperTimeoutMs: readInteger(
+      env,
+      "LOC_NEWSPAPER_TIMEOUT_MS",
+      DEFAULT_NEWSPAPER_TIMEOUT_MS,
+      1e3,
+      3e5
+    ),
+    maxRetries: readInteger(env, "LOC_MAX_RETRIES", 3, 0, 8),
+    cacheTtlMs: readInteger(env, "LOC_CACHE_TTL_MS", 9e5, 0, 864e5),
+    cacheMaxEntries: readInteger(env, "LOC_CACHE_MAX_ENTRIES", 200, 1, 5e3),
+    logLevel
+  };
+}
+
+// src/loc/cache.ts
+var Cache = class {
+  constructor(ttlMs, maxEntries) {
+    this.ttlMs = ttlMs;
+    this.maxEntries = maxEntries;
+  }
+  ttlMs;
+  maxEntries;
+  entries = /* @__PURE__ */ new Map();
+  get(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      this.entries.delete(key);
+      return void 0;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return entry.value;
+  }
+  set(key, value) {
+    if (this.ttlMs <= 0) return;
+    this.entries.delete(key);
+    this.entries.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    while (this.entries.size > this.maxEntries) {
+      const oldest = this.entries.keys().next();
+      if (oldest.done) break;
+      this.entries.delete(oldest.value);
+    }
+  }
+  get size() {
+    return this.entries.size;
+  }
+};
+
+// src/loc/http.ts
+var RETRYABLE = /* @__PURE__ */ new Set([408, 425, 429, 500, 502, 503, 504]);
+var PUSH_BACK = /* @__PURE__ */ new Set([429, 503]);
+var LONGEST_WAIT_MS = 3e4;
+var RETRIES_AFTER_SILENCE = 1;
+function parseRetryAfter(value, now = Date.now()) {
+  if (!value) return null;
+  const trimmed = value.trim();
+  const seconds = Number(trimmed);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1e3);
+  const at = Date.parse(trimmed);
+  if (Number.isNaN(at)) return null;
+  return Math.max(0, at - now);
+}
+function backoffMs(attempt) {
+  const base2 = Math.min(16e3, 1e3 * 2 ** attempt);
+  return base2 + Math.floor(Math.random() * 500);
+}
+async function fetchText(options) {
+  const { url, userAgent, timeoutMs, maxRetries, limiter, logger } = options;
+  const doFetch = options.fetchImpl ?? fetch;
+  let lastError = null;
+  let askedWaitMs = 0;
+  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+    if (askedWaitMs > 0) {
+      logger.debug(`waiting ${askedWaitMs}ms, as asked`);
+      await new Promise((resolve) => setTimeout(resolve, askedWaitMs));
+      askedWaitMs = 0;
+    }
+    await limiter.beforeRequest();
+    const controller = new AbortController();
+    const deadline = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      logger.debug(`GET ${url}`);
+      const response = await doFetch(url, {
+        signal: controller.signal,
+        redirect: "follow",
+        headers: { "user-agent": userAgent, accept: "application/json, text/plain, */*" }
+      });
+      if (response.ok) {
+        limiter.succeeded();
+        return await response.text();
+      }
+      if (PUSH_BACK.has(response.status)) {
+        limiter.pushBack();
+        await response.body?.cancel().catch(() => void 0);
+        const asked = parseRetryAfter(response.headers.get("retry-after"));
+        if (asked !== null && asked > LONGEST_WAIT_MS) {
+          throw rateLimited(
+            `The Library of Congress asked this client to wait ${Math.round(asked / 1e3)} seconds (HTTP ${response.status}).`,
+            { url, status: response.status }
+          );
+        }
+        if (attempt >= maxRetries) {
+          throw rateLimited(
+            `The Library of Congress asked this client to slow down (HTTP ${response.status}).`,
+            { url, status: response.status }
+          );
+        }
+        askedWaitMs = asked ?? backoffMs(attempt);
+        lastError = new Error(`HTTP ${response.status}`);
+        continue;
+      }
+      if (RETRYABLE.has(response.status) && attempt < maxRetries) {
+        await response.body?.cancel().catch(() => void 0);
+        lastError = new Error(`HTTP ${response.status}`);
+        askedWaitMs = backoffMs(attempt);
+        continue;
+      }
+      if (response.status === 400 || response.status === 422) {
+        throw invalidInput(
+          "The Library of Congress would not accept this request.",
+          "Check the query. A quotation mark or bracket left unbalanced is read as syntax."
+        );
+      }
+      if (response.status === 404 || response.status === 410) {
+        throw notFound("The Library of Congress holds nothing at this address.", {
+          url,
+          status: response.status
+        });
+      }
+      throw networkError(`The Library of Congress answered HTTP ${response.status}.`, {
+        url,
+        status: response.status
+      });
+    } catch (error) {
+      clearTimeout(deadline);
+      if (error instanceof Error && error.name === "LocError") throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        lastError = error;
+        if (attempt >= Math.min(maxRetries, RETRIES_AFTER_SILENCE)) {
+          throw timeout(
+            `No answer from the Library of Congress within ${timeoutMs}ms. The newspaper corpus in particular can take tens of seconds.`,
+            { url }
+          );
+        }
+        askedWaitMs = backoffMs(attempt);
+        continue;
+      }
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt >= maxRetries) {
+        throw networkError(`Could not reach the Library of Congress: ${lastError.message}`, {
+          url
+        });
+      }
+      askedWaitMs = backoffMs(attempt);
+      continue;
+    } finally {
+      clearTimeout(deadline);
+    }
+  }
+  throw networkError(
+    `Could not reach the Library of Congress: ${lastError?.message ?? "no attempt was made"}`,
+    { url }
+  );
+}
+async function fetchJson(options) {
+  const body = await fetchText(options);
+  try {
+    return JSON.parse(body);
+  } catch {
+    throw parseFailure("The Library of Congress answered with something that is not JSON.", {
+      url: options.url
+    });
+  }
+}
+
+// src/loc/paths.ts
+var HOST = "https://www.loc.gov";
+var FORMAT_ROUTE = {
+  books: "/books/",
+  photos: "/photos/",
+  maps: "/maps/",
+  audio: "/audio/",
+  "film-and-videos": "/film-and-videos/",
+  manuscripts: "/manuscripts/",
+  "notated-music": "/notated-music/",
+  newspapers: "/newspapers/"
+};
+var FORMAT_ROUTES = Object.keys(FORMAT_ROUTE);
+var NEWSPAPER_PAGES_ROUTE = "/collections/chronicling-america/";
+var COLLECTIONS_ROUTE = "/collections/";
+var ITEM_ROUTE = "/item/";
+var PARAM = {
+  /** Asks for JSON rather than a web page. */
+  format: "fo",
+  /** The words to look for. */
+  query: "q",
+  /** Results per page. */
+  perPage: "c",
+  /** Which page, from 1. */
+  page: "sp",
+  /** A year range, written from/to. */
+  dates: "dates",
+  /** Facet filters, several of them separated by a vertical bar. */
+  facets: "fa",
+  /** Sort order. */
+  sort: "sb",
+  /** Which top-level blocks to return, which is what keeps a page small. */
+  attributes: "at",
+  /** Widens a search past what the Library has digitised. */
+  all: "all"
+};
+var WANTED_BLOCKS = "results,pagination";
+var FACET_FIELD = {
+  subject: "subject",
+  location: "location",
+  language: "language",
+  contributor: "contributor",
+  partof: "partof",
+  /** The state a newspaper was published in, as the newspaper corpus files it. */
+  state: "location_state",
+  /** A newspaper, named with the town and the years it ran. */
+  publication: "partof_title"
+};
+var SORT = {
+  relevance: "",
+  newest: "date_desc",
+  oldest: "date",
+  title: "title_s"
+};
+var ROW_FIELD = {
+  id: "id",
+  url: "url",
+  title: "title",
+  date: "date",
+  contributor: "contributor",
+  originalFormat: "original_format",
+  onlineFormat: "online_format",
+  location: "location",
+  subject: "subject",
+  description: "description",
+  partOf: "partof",
+  digitized: "digitized",
+  /** Newspaper pages only, from here down. */
+  pageNumber: "number_page",
+  publicationTitle: "partof_title",
+  state: "location_state",
+  /** How many records a collection gathers. */
+  count: "count",
+  /** Lists what a collection holds. */
+  items: "items"
+};
+var ITEM_FIELD = {
+  id: "id",
+  url: "url",
+  title: "title",
+  date: "date",
+  contributorNames: "contributor_names",
+  description: "description",
+  notes: "notes",
+  subjects: "subjects",
+  location: "location",
+  language: "language",
+  partOf: "partof",
+  repository: "repository",
+  callNumber: "call_number",
+  rights: "rights_advisory",
+  rightsFallback: "rights_information",
+  originalFormat: "original_format"
+};
+var MOST_SUBJECTS = 12;
+var itemUrl = (identifier) => `${HOST}${ITEM_ROUTE}${identifier.split("/").map(encodeURIComponent).join("/")}/`;
+
+// src/loc/urls.ts
+var YEAR_BOUND = { earliest: 1e3, latest: 9999 };
+function base(path) {
+  const url = new URL(HOST + path);
+  url.searchParams.set(PARAM.format, "json");
+  url.searchParams.set(PARAM.attributes, WANTED_BLOCKS);
+  return url;
+}
+function facetString(facets) {
+  return Object.entries(facets).filter(([, value]) => typeof value === "string" && value.trim() !== "").map(([field, value]) => `${FACET_FIELD[field]}:${value.trim().toLowerCase()}`).join("|");
+}
+function catalogueUrl(q) {
+  const url = base(FORMAT_ROUTE[q.format]);
+  url.searchParams.set(PARAM.query, q.query);
+  url.searchParams.set(PARAM.perPage, String(q.limit));
+  url.searchParams.set(PARAM.page, String(q.page));
+  if (q.yearFrom !== void 0 || q.yearTo !== void 0) {
+    const from = q.yearFrom ?? YEAR_BOUND.earliest;
+    const to = q.yearTo ?? YEAR_BOUND.latest;
+    url.searchParams.set(PARAM.dates, `${from}/${to}`);
+  }
+  const facets = facetString(q.facets ?? {});
+  if (facets !== "") url.searchParams.set(PARAM.facets, facets);
+  const sort = q.sort ? SORT[q.sort] : "";
+  if (sort !== "") url.searchParams.set(PARAM.sort, sort);
+  if (!q.onlineOnly) url.searchParams.set(PARAM.all, "true");
+  return url.toString();
+}
+function newspaperPagesUrl(query, limit, page, filters = {}) {
+  const url = base(NEWSPAPER_PAGES_ROUTE);
+  url.searchParams.set(PARAM.query, query);
+  url.searchParams.set(PARAM.perPage, String(limit));
+  url.searchParams.set(PARAM.page, String(page));
+  if (filters.yearFrom !== void 0 || filters.yearTo !== void 0) {
+    const from = filters.yearFrom ?? YEAR_BOUND.earliest;
+    const to = filters.yearTo ?? YEAR_BOUND.latest;
+    url.searchParams.set(PARAM.dates, `${from}/${to}`);
+  }
+  const facets = facetString(filters.facets ?? {});
+  if (facets !== "") url.searchParams.set(PARAM.facets, facets);
+  return url.toString();
+}
+function collectionsUrl(limit, page) {
+  const url = base(COLLECTIONS_ROUTE);
+  url.searchParams.set(PARAM.perPage, String(limit));
+  url.searchParams.set(PARAM.page, String(page));
+  return url.toString();
+}
+function itemDocumentUrl(identifier) {
+  const segments = identifier.trim().replace(/^\/+|\/+$/g, "").split("/").filter((segment) => segment !== "");
+  if (segments.some((segment) => /^\.+$/.test(segment))) {
+    throw invalidInput(
+      `"${identifier}" is not an identifier: it carries a relative path segment.`,
+      "Take the identifier from a search result rather than building one."
+    );
+  }
+  const path = segments.map(encodeURIComponent).join("/");
+  const url = new URL(`${HOST}${ITEM_ROUTE}${path}/`);
+  url.searchParams.set(PARAM.format, "json");
+  return url.toString();
+}
+function identifierFrom(address) {
+  if (!address) return null;
+  const trimmed = address.trim();
+  if (trimmed === "") return null;
+  const absolute = trimmed.startsWith("//") ? `https:${trimmed}` : trimmed;
+  let parsed;
+  try {
+    parsed = new URL(absolute);
+  } catch {
+    return null;
+  }
+  const path = parsed.pathname.replace(/^\/+|\/+$/g, "");
+  if (path === "") return null;
+  const segments = path.split("/");
+  if (parsed.hostname === "lccn.loc.gov") return segments[0] ?? null;
+  const first = segments[0];
+  if (first === "item" || first === "resource") {
+    const rest = segments.slice(1);
+    return rest.length > 0 ? rest.join("/") : null;
+  }
+  if (first === "collections") return segments[1] ?? null;
+  return null;
+}
+
+// src/loc/parse.ts
+var asObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+function asStrings(value) {
+  if (typeof value === "string") return value.trim() === "" ? [] : [value];
+  if (Array.isArray(value))
+    return value.filter((v) => typeof v === "string" && v.trim() !== "");
+  return [];
+}
+var asString = (value) => asStrings(value)[0] ?? null;
+function asLabels(value) {
+  const entries = Array.isArray(value) ? value : [value];
+  const labels = [];
+  for (const entry of entries) {
+    if (typeof entry === "string") {
+      if (entry.trim() !== "") labels.push(entry);
+      continue;
+    }
+    const object = asObject(entry);
+    if (!object) continue;
+    const titled = asString(object.title);
+    if (titled !== null) {
+      labels.push(titled);
+      continue;
+    }
+    for (const key of Object.keys(object)) {
+      if (key.trim() !== "") labels.push(key);
+    }
+  }
+  return labels;
+}
+function asNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+  }
+  if (Array.isArray(value)) return asNumber(value[0]);
+  return null;
+}
+function asPageNumber(value) {
+  const text = asString(value);
+  if (text === null) return null;
+  const digits = text.trim();
+  if (!/^\d+$/.test(digits)) return null;
+  const n = Number(digits);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+var PLAUSIBLE_YEAR = { first: 1e3, last: 2200 };
+function asYear(value) {
+  const plausible = (year) => Number.isFinite(year) && year >= PLAUSIBLE_YEAR.first && year <= PLAUSIBLE_YEAR.last ? Math.trunc(year) : null;
+  const text = asString(value);
+  if (text !== null) {
+    const m = /(\d{4})/.exec(text);
+    if (m) return plausible(Number(m[1]));
+  }
+  const direct = asNumber(value);
+  return direct === null ? null : plausible(direct);
+}
+function plainText(value) {
+  return value.replace(/<[^>]*>/g, "").replace(/&amp;/g, "&").replace(/&quot;/g, '"').replace(/&#0?39;|&apos;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
+}
+function toPaging(payload, url) {
+  const root = asObject(payload);
+  const pagination = root ? asObject(root.pagination) : null;
+  if (!pagination) {
+    throw parseFailure(
+      "The answer carried no pagination block, so nothing states how many results match.",
+      {
+        url
+      }
+    );
+  }
+  const resultCount = asNumber(pagination.of);
+  if (resultCount === null) {
+    throw parseFailure("The answer carried no readable count of results.", { url });
+  }
+  return {
+    resultCount,
+    pageCount: asNumber(pagination.total),
+    currentPage: asNumber(pagination.current),
+    perPage: asNumber(pagination.perpage)
+  };
+}
+function rowsOf(payload, url) {
+  const root = asObject(payload);
+  if (!root || !Array.isArray(root.results)) {
+    throw parseFailure("The answer carried its rows in a shape this server cannot read.", { url });
+  }
+  return root.results.map(asObject).filter((r) => r !== null);
+}
+var creatorOf = (row) => asStrings(row[ROW_FIELD.contributor]).map(plainText).join(", ") || null;
+function sourceUrlOf(row, identifier) {
+  const raw = asString(row[ROW_FIELD.url]) ?? asString(row[ROW_FIELD.id]);
+  if (raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith("//")) return `https:${trimmed}`;
+    if (trimmed.startsWith("http://")) return `https://${trimmed.slice("http://".length)}`;
+    if (trimmed.startsWith("https://")) return trimmed;
+  }
+  return identifier === null ? "" : itemUrl(identifier);
+}
+function toSearchResults(payload, url, onSkip) {
+  const rows = rowsOf(payload, url);
+  const records = [];
+  let skipped = 0;
+  for (const row of rows) {
+    const title = asString(row[ROW_FIELD.title]);
+    const identifier = identifierFrom(asString(row[ROW_FIELD.url]) ?? asString(row[ROW_FIELD.id]));
+    const source = sourceUrlOf(row, identifier);
+    if (title === null && source === "") {
+      skipped += 1;
+      continue;
+    }
+    records.push({
+      identifier,
+      title: title === null ? null : plainText(title),
+      creator: creatorOf(row),
+      year: asYear(row[ROW_FIELD.date]),
+      date: asString(row[ROW_FIELD.date]),
+      format: asString(row[ROW_FIELD.originalFormat]),
+      location: asStrings(row[ROW_FIELD.location]),
+      subjects: asStrings(row[ROW_FIELD.subject]).slice(0, MOST_SUBJECTS),
+      online: row[ROW_FIELD.digitized] === true,
+      sourceUrl: source
+    });
+  }
+  if (skipped > 0) onSkip(skipped);
+  if (rows.length > 0 && records.length === 0) {
+    throw parseFailure(`${rows.length} rows came back and none could be read.`, { url });
+  }
+  return { paging: toPaging(payload, url), records };
+}
+var JOINING_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "that",
+  "this",
+  "from",
+  "was",
+  "were",
+  "are",
+  "his",
+  "her",
+  "its",
+  "not",
+  "but",
+  "had",
+  "has",
+  "you",
+  "all",
+  "any",
+  "who"
+]);
+function queryTerms(query) {
+  const terms = [];
+  const phrases = query.match(/"([^"]+)"/g) ?? [];
+  for (const phrase of phrases) {
+    const inner = phrase.slice(1, -1).trim().toLowerCase();
+    if (inner !== "") terms.push(inner);
+  }
+  const rest = query.replace(/"[^"]*"/g, " ");
+  for (const word of rest.split(/[^\p{L}\p{N}'-]+/u)) {
+    const lower = word.trim().toLowerCase();
+    if (lower.length < 3 || JOINING_WORDS.has(lower)) continue;
+    terms.push(lower);
+  }
+  return [...new Set(terms)];
+}
+function toWordBoundary(text, index, direction) {
+  const limit = direction === -1 ? 0 : text.length;
+  let at = index;
+  for (let step = 0; step < 30 && at !== limit; step += 1) {
+    if (text[at] === " ") return at;
+    at += direction;
+  }
+  return index;
+}
+function excerptsFor(text, terms, budget) {
+  const clean = text.replace(/\s+/g, " ").trim();
+  if (clean === "") return { passages: [], located: false };
+  const haystack = clean.toLowerCase();
+  const found = [];
+  for (const term of terms) {
+    let from = 0;
+    while (from <= haystack.length - term.length) {
+      const at = haystack.indexOf(term, from);
+      if (at === -1) break;
+      found.push({ at, length: term.length });
+      from = at + term.length;
+    }
+  }
+  if (found.length === 0) {
+    const opening = clean.slice(0, budget.maxChars);
+    const cut = opening.length < clean.length;
+    return {
+      passages: [cut ? `${opening.trimEnd()}\u2026` : opening],
+      located: false
+    };
+  }
+  found.sort((a, b) => a.at - b.at);
+  const windows = [];
+  for (const hit of found) {
+    const half = Math.max(0, Math.floor((budget.maxChars - hit.length) / 2));
+    const start = toWordBoundary(clean, Math.max(0, hit.at - half), -1);
+    const end = toWordBoundary(clean, Math.min(clean.length, hit.at + hit.length + half), 1);
+    const previous = windows[windows.length - 1];
+    if (previous && start <= previous.end) {
+      previous.end = Math.max(previous.end, end);
+      continue;
+    }
+    windows.push({ start, end });
+  }
+  const passages = windows.slice(0, budget.maxCount).map(({ start, end }) => {
+    const body = clean.slice(start, Math.min(end, start + budget.maxChars)).trim();
+    const opensMidway = start > 0;
+    const closesEarly = Math.min(end, start + budget.maxChars) < clean.length;
+    return `${opensMidway ? "\u2026" : ""}${body}${closesEarly ? "\u2026" : ""}`;
+  });
+  return { passages, located: true };
+}
+function toNewspaperResults(payload, url, query, budget, onSkip) {
+  const rows = rowsOf(payload, url);
+  const terms = queryTerms(query);
+  const hits = [];
+  let skipped = 0;
+  for (const row of rows) {
+    const address = asString(row[ROW_FIELD.url]) ?? asString(row[ROW_FIELD.id]);
+    const source = sourceUrlOf(row, identifierFrom(address));
+    if (source === "") {
+      skipped += 1;
+      continue;
+    }
+    const pageText = asStrings(row[ROW_FIELD.description]).join(" ");
+    const { passages, located } = excerptsFor(pageText, terms, budget);
+    const publication = asString(row[ROW_FIELD.publicationTitle]);
+    const title = asString(row[ROW_FIELD.title]);
+    hits.push({
+      identifier: identifierFrom(address),
+      title: title === null ? null : plainText(title),
+      // A newspaper page is credited to whoever contributed the scan, which is
+      // a library rather than a writer.
+      creator: creatorOf(row),
+      year: asYear(row[ROW_FIELD.date]),
+      pageNumber: asPageNumber(row[ROW_FIELD.pageNumber]),
+      publishedOn: asString(row[ROW_FIELD.date]),
+      publication,
+      state: asString(row[ROW_FIELD.state]),
+      wordsLocated: located,
+      excerpts: passages,
+      sourceUrl: source
+    });
+  }
+  if (skipped > 0) onSkip(skipped);
+  if (rows.length > 0 && hits.length === 0) {
+    throw parseFailure(`${rows.length} matches came back and none could be read.`, { url });
+  }
+  return { paging: toPaging(payload, url), hits };
+}
+function toResources(value) {
+  if (!Array.isArray(value)) return [];
+  const resources = [];
+  for (const entry of value) {
+    const resource = asObject(entry);
+    if (!resource) continue;
+    const files = resource.files;
+    const fileCount = Array.isArray(files) ? files.reduce((sum, group) => sum + (Array.isArray(group) ? group.length : 1), 0) : asNumber(files);
+    resources.push({
+      caption: asString(resource.caption),
+      fileCount,
+      url: asString(resource.url),
+      imageUrl: asString(resource.image)
+    });
+  }
+  return resources;
+}
+function toCitations(value) {
+  const block = asObject(value);
+  if (!block) return {};
+  const citations = {};
+  for (const [style, text] of Object.entries(block)) {
+    if (typeof text !== "string" || text.trim() === "") continue;
+    citations[style] = plainText(text);
+  }
+  return citations;
+}
+function toItemDetail(payload, identifier, url) {
+  const root = asObject(payload);
+  if (!root) throw parseFailure("The item answer was not an object.", { url });
+  if (asNumber(root.status) === 404) {
+    throw notFound(`The Library of Congress has no record called "${identifier}".`, { url });
+  }
+  const item = asObject(root.item);
+  if (!item) {
+    throw parseFailure(
+      `The record for "${identifier}" came back without the item block this server reads.`,
+      { url }
+    );
+  }
+  if (Object.keys(item).length === 0) {
+    throw notFound(`The Library of Congress has no record called "${identifier}".`, { url });
+  }
+  const description = asStrings(item[ITEM_FIELD.description]).map(plainText).join("\n\n");
+  const title = asString(item[ITEM_FIELD.title]);
+  const source = asString(item[ITEM_FIELD.url]) ?? itemUrl(identifier);
+  return {
+    identifier,
+    title: title === null ? null : plainText(title),
+    creator: asStrings(item[ITEM_FIELD.contributorNames]).map(plainText).join(", ") || null,
+    year: asYear(item[ITEM_FIELD.date]),
+    date: asString(item[ITEM_FIELD.date]),
+    format: asString(item[ITEM_FIELD.originalFormat]),
+    description: description === "" ? null : description,
+    notes: asStrings(item[ITEM_FIELD.notes]).map(plainText),
+    subjects: asLabels(item[ITEM_FIELD.subjects]).slice(0, MOST_SUBJECTS),
+    location: asLabels(item[ITEM_FIELD.location]),
+    language: asLabels(item[ITEM_FIELD.language]),
+    partOf: asLabels(item[ITEM_FIELD.partOf]),
+    repository: asStrings(item[ITEM_FIELD.repository]).map(plainText).join(" ") || null,
+    callNumber: asString(item[ITEM_FIELD.callNumber]),
+    rights: asString(item[ITEM_FIELD.rights]) ?? asString(item[ITEM_FIELD.rightsFallback]),
+    citations: toCitations(root.cite_this),
+    resources: toResources(root.resources),
+    sourceUrl: source.startsWith("//") ? `https:${source}` : source,
+    raw: item
+  };
+}
+function toCollections(payload, url, onSkip) {
+  const rows = rowsOf(payload, url);
+  const collections = [];
+  let skipped = 0;
+  for (const row of rows) {
+    const title = asString(row[ROW_FIELD.title]);
+    if (title === null) {
+      skipped += 1;
+      continue;
+    }
+    const address = asString(row[ROW_FIELD.url]) ?? asString(row[ROW_FIELD.id]);
+    const inner = asObject(row.item);
+    const description = asStrings(row[ROW_FIELD.description]).map(plainText).join("\n\n");
+    collections.push({
+      identifier: identifierFrom(address),
+      title: plainText(title),
+      description: description === "" ? null : description,
+      itemCount: asNumber(row[ROW_FIELD.count]),
+      subjects: asStrings(row[ROW_FIELD.subject]).slice(0, MOST_SUBJECTS),
+      formats: inner ? asStrings(inner.formats) : [],
+      sourceUrl: sourceUrlOf(row, null),
+      itemsUrl: asString(row[ROW_FIELD.items])
+    });
+  }
+  if (skipped > 0) onSkip(skipped);
+  if (rows.length > 0 && collections.length === 0) {
+    throw parseFailure(`${rows.length} collections came back and none could be read.`, { url });
+  }
+  return { paging: toPaging(payload, url), collections };
+}
+
+// src/loc/rateLimiter.ts
+var RateLimiter = class {
+  baseIntervalMs;
+  maxIntervalMs;
+  intervalMs;
+  lastStartedAt = 0;
+  queue = Promise.resolve();
+  calmStreak = 0;
+  constructor(options) {
+    this.baseIntervalMs = options.intervalMs;
+    this.maxIntervalMs = options.maxIntervalMs ?? options.intervalMs * 8;
+    this.intervalMs = options.intervalMs;
+  }
+  /** The spacing in force, which callers report rather than guess. */
+  get currentIntervalMs() {
+    return this.intervalMs;
+  }
+  /**
+   * Run `task` with nothing else in flight.
+   *
+   * This only serialises. Spacing is claimed per attempt through
+   * `beforeRequest`, because a task that retries makes several requests and
+   * each of them owes the site the same gap.
+   */
+  schedule(task) {
+    const result = this.queue.then(task, task);
+    this.queue = result.then(
+      () => void 0,
+      () => void 0
+    );
+    return result;
+  }
+  /** Wait until enough time has passed since the previous request began. */
+  async beforeRequest() {
+    const elapsed = Date.now() - this.lastStartedAt;
+    const wait = Math.min(this.intervalMs, this.intervalMs - elapsed);
+    if (wait > 0) await sleep(wait);
+    this.lastStartedAt = Date.now();
+  }
+  /** Called when the site asks for room: double the gap, up to the ceiling. */
+  pushBack() {
+    this.calmStreak = 0;
+    this.intervalMs = Math.min(this.maxIntervalMs, this.intervalMs * 2);
+  }
+  /**
+   * Called on a clean answer. Recovery takes several in a row, so one lucky
+   * response after a rough patch does not undo the caution that earned it.
+   */
+  succeeded() {
+    if (this.intervalMs === this.baseIntervalMs) return;
+    this.calmStreak += 1;
+    if (this.calmStreak < 3) return;
+    this.calmStreak = 0;
+    this.intervalMs = Math.max(this.baseIntervalMs, Math.round(this.intervalMs / 2));
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/loc/client.ts
+function withGuarantees(config) {
+  const defaults = loadConfig({});
+  const number = (value, fallback) => {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+  };
+  const claimed = typeof config.userAgent === "string" ? config.userAgent.trim() : "";
+  const identifier = defaults.userAgent;
+  return {
+    ...config,
+    // A caller may say who they are. Appending rather than replacing means the
+    // Library can always tell which software is calling, and reach someone.
+    userAgent: claimed === "" || claimed.includes(REPO_URL) ? identifier : `${claimed} ${identifier}`,
+    minIntervalMs: Math.max(
+      MIN_ALLOWED_INTERVAL_MS,
+      number(config.minIntervalMs, defaults.minIntervalMs)
+    ),
+    timeoutMs: number(config.timeoutMs, defaults.timeoutMs),
+    newspaperTimeoutMs: number(config.newspaperTimeoutMs, defaults.newspaperTimeoutMs),
+    maxRetries: number(config.maxRetries, defaults.maxRetries),
+    cacheTtlMs: number(config.cacheTtlMs, defaults.cacheTtlMs),
+    cacheMaxEntries: number(config.cacheMaxEntries, defaults.cacheMaxEntries)
+  };
+}
+var LocClient = class {
+  config;
+  logger;
+  limiter;
+  cache;
+  fetchImpl;
+  constructor(options = {}) {
+    const base2 = { ...loadConfig(), ...options.config };
+    this.config = withGuarantees(base2);
+    this.logger = options.logger ?? createLogger(this.config.logLevel);
+    this.limiter = new RateLimiter({ intervalMs: this.config.minIntervalMs });
+    this.cache = new Cache(this.config.cacheTtlMs, this.config.cacheMaxEntries);
+    this.fetchImpl = options.fetchImpl;
+  }
+  /** The pacing in force, which widens when the Library pushes back. */
+  get intervalMs() {
+    return this.limiter.currentIntervalMs;
+  }
+  /** What the Library sees this client call itself. */
+  get userAgent() {
+    return this.config.userAgent;
+  }
+  /**
+   * `cacheKey` is stated rather than taken from the address, because two reads
+   * of one address can produce different values: a passage cut to three hundred
+   * characters is not the same value as the same passage cut to a thousand, and
+   * serving one for the other would answer a budget the caller never set.
+   */
+  async read(cacheKey, url, parse, timeoutMs = this.config.timeoutMs) {
+    const cached = this.cache.get(cacheKey);
+    if (cached !== void 0) {
+      this.logger.debug(`cache hit ${cacheKey}`);
+      return { data: cached, cached: true };
+    }
+    let skipped = 0;
+    const payload = await this.limiter.schedule(
+      () => fetchJson({
+        url,
+        userAgent: this.config.userAgent,
+        timeoutMs,
+        maxRetries: this.config.maxRetries,
+        limiter: this.limiter,
+        logger: this.logger,
+        ...this.fetchImpl ? { fetchImpl: this.fetchImpl } : {}
+      })
+    );
+    const data = parse(payload, (n) => {
+      skipped += n;
+      this.logger.warn(`skipped ${n} unreadable row(s) from ${url}`);
+    });
+    this.cache.set(cacheKey, data);
+    return skipped > 0 ? { data, cached: false, skipped } : { data, cached: false };
+  }
+  searchItems(query) {
+    const url = catalogueUrl(query);
+    return this.read(url, url, (payload, onSkip) => toSearchResults(payload, url, onSkip));
+  }
+  searchNewspapers(query, limit, page, budget, filters = {}) {
+    const trimmed = query.trim();
+    if (trimmed === "") {
+      return Promise.reject(invalidInput("Words to look for are required."));
+    }
+    const url = newspaperPagesUrl(trimmed, limit, page, filters);
+    const key = `${url}#${budget.maxChars}x${budget.maxCount}`;
+    return this.read(
+      key,
+      url,
+      (payload, onSkip) => toNewspaperResults(payload, url, trimmed, budget, onSkip),
+      // Reading the text of millions of pages takes the site far longer than
+      // answering from the catalogue, so this route carries a budget of its own.
+      this.config.newspaperTimeoutMs
+    );
+  }
+  getItem(identifier) {
+    const trimmed = identifier.trim();
+    if (trimmed === "") {
+      return Promise.reject(invalidInput("A record identifier is required."));
+    }
+    const url = itemDocumentUrl(trimmed);
+    return this.read(url, url, (payload) => toItemDetail(payload, trimmed, url));
+  }
+  listCollections(limit, page) {
+    const url = collectionsUrl(limit, page);
+    return this.read(url, url, (payload, onSkip) => toCollections(payload, url, onSkip));
+  }
+};
+export {
+  LocClient
+};
+//# sourceMappingURL=client.js.map