mcp-databnf 1.0.0

package/dist/bnf/client.js

@@ -0,0 +1,1279 @@
+// src/version.ts
+var PKG_VERSION = "1.0.0";
+var REPO_URL = "https://github.com/smeet666/mcp-databnf";
+
+// src/config.ts
+var LOG_LEVELS = ["silent", "error", "info", "debug"];
+var MIN_ALLOWED_INTERVAL_MS = 3e3;
+var MAX_ALLOWED_INTERVAL_MS = 12e4;
+var DEFAULT_INTERVAL_MS = 3e3;
+var DEFAULT_TIMEOUT_MS = 6e4;
+var DEFAULT_USER_AGENT = `mcp-databnf/${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-databnf] ${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-databnf] error: ${name}="${raw}" is not a whole number; using ${fallback}.
+`
+    );
+    return fallback;
+  }
+  if (value < min || value > max) {
+    process.stderr.write(
+      `[mcp-databnf] error: ${name}=${value} is outside ${min}..${max}; using ${fallback}.
+`
+    );
+    return fallback;
+  }
+  return value;
+}
+function loadConfig(env = process.env) {
+  const level = env.BNF_LOG_LEVEL;
+  const logLevel = level && LOG_LEVELS.includes(level) ? level : "error";
+  if (level && !LOG_LEVELS.includes(level)) {
+    process.stderr.write(
+      `[mcp-databnf] error: BNF_LOG_LEVEL="${level}" is not one of ${LOG_LEVELS.join(", ")}; using error.
+`
+    );
+  }
+  const custom = env.BNF_USER_AGENT?.trim();
+  return {
+    // A caller who wants to be recognised may say who they are, and the
+    // contact address stays attached: the BnF 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,
+      "BNF_MIN_INTERVAL_MS",
+      DEFAULT_INTERVAL_MS,
+      MIN_ALLOWED_INTERVAL_MS,
+      MAX_ALLOWED_INTERVAL_MS
+    ),
+    timeoutMs: readInteger(env, "BNF_TIMEOUT_MS", DEFAULT_TIMEOUT_MS, 1e3, 3e5),
+    maxRetries: readInteger(env, "BNF_MAX_RETRIES", 3, 0, 8),
+    cacheTtlMs: readInteger(env, "BNF_CACHE_TTL_MS", 9e5, 0, 864e5),
+    cacheMaxEntries: readInteger(env, "BNF_CACHE_MAX_ENTRIES", 200, 1, 5e3),
+    logLevel
+  };
+}
+
+// src/errors.ts
+var BnfError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "BnfError";
+    this.code = code;
+    this.details = details;
+  }
+};
+var notFound = (message, details) => new BnfError("not_found", message, details);
+var invalidInput = (message, hint) => new BnfError("invalid_input", message, hint ? { hint } : {});
+var rateLimited = (message, details) => new BnfError("rate_limited", message, {
+  hint: "Wait a moment and ask again. This says nothing about whether the BnF describes what you asked for.",
+  ...details
+});
+var parseFailure = (message, details) => new BnfError("parse_failure", message, {
+  hint: "data.bnf.fr may have changed how it answers. Please report this at https://github.com/smeet666/mcp-databnf/issues with the arguments you used.",
+  ...details
+});
+var networkError = (message, details) => new BnfError("network_error", message, details);
+var timeout = (message, details) => new BnfError("timeout", message, details);
+
+// src/bnf/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 { value: entry.value, retrievedAt: entry.retrievedAt };
+  }
+  set(key, value, retrievedAt) {
+    if (this.ttlMs <= 0) return;
+    this.entries.delete(key);
+    this.entries.set(key, { value, expiresAt: Date.now() + this.ttlMs, retrievedAt });
+    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/bnf/endpoint.ts
+var SPARQL_ENDPOINT = "https://data.bnf.fr/sparql";
+var ALLOWED_HOST = "data.bnf.fr";
+var GALLICA_HOST = "gallica.bnf.fr";
+function assertRequestable(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw refusal(`mcp-databnf refuses to request "${url}": it is not an address.`);
+  }
+  const host = parsed.hostname.toLowerCase().replace(/\.$/, "");
+  if (host !== ALLOWED_HOST) {
+    throw refusal(
+      `mcp-databnf requests ${ALLOWED_HOST} and nothing else; "${host}" was refused. Gallica in particular is described from the catalogue and never read.`
+    );
+  }
+}
+var refusal = (message) => new BnfError("network_error", message, {
+  hint: "This server reads the BnF catalogue at data.bnf.fr. It holds no licence to read the digitised contents, so it does not follow an address that leaves that host."
+});
+function isGallicaAddress(address) {
+  try {
+    const host = new URL(address).hostname.toLowerCase().replace(/\.$/, "");
+    return host === GALLICA_HOST || host.endsWith(`.${GALLICA_HOST}`);
+  } catch {
+    return false;
+  }
+}
+var PREFIXES = {
+  foaf: "http://xmlns.com/foaf/0.1/",
+  rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+  rdfs: "http://www.w3.org/2000/01/rdf-schema#",
+  owl: "http://www.w3.org/2002/07/owl#",
+  skos: "http://www.w3.org/2004/02/skos/core#",
+  dcterms: "http://purl.org/dc/terms/",
+  bio: "http://vocab.org/bio/0.1/",
+  bnf: "http://data.bnf.fr/ontology/bnf-onto/",
+  bibo: "http://purl.org/ontology/bibo/",
+  isni: "http://isni.org/ontology#",
+  /** RDA group 2 elements, which carry the biographical fields. */
+  rdag2: "http://rdvocab.info/ElementsGr2/",
+  /** RDA elements, which carry the bibliographic fields. */
+  rdae: "http://rdvocab.info/Elements/",
+  /** RDA relationships between work, expression, manifestation and item. */
+  rdarel: "http://rdvocab.info/RDARelationshipsWEMI/",
+  /** The FRBR classes data.bnf.fr types its entities with. */
+  rdafrbr: "http://rdvocab.info/uri/schema/FRBRentitiesRDA/"
+};
+var PREFIX_BLOCK = Object.entries(PREFIXES).map(([name, iri]) => `PREFIX ${name}: <${iri}>`).join("\n");
+var publicPageFor = (entityIri) => entityIri.replace(/#.*$/, "").replace(/^http:/, "https:");
+
+// src/bnf/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;
+var MAX_REDIRECTS = 2;
+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 base = Math.min(16e3, 1e3 * 2 ** attempt);
+  return base + Math.floor(Math.random() * 500);
+}
+function readEngineError(body) {
+  const match = /^Virtuoso\s+(\w+)\s+Error\s+([\s\S]*)$/.exec(body.trim());
+  if (!match) return null;
+  const state = match[1] ?? "";
+  const text2 = (match[2] ?? "").split("\n")[0]?.trim() ?? "";
+  return { kind: state === "37000" ? "compile" : "runtime", text: text2 };
+}
+async function postOnce(options, signal) {
+  assertRequestable(SPARQL_ENDPOINT);
+  const doFetch = options.fetchImpl ?? fetch;
+  const form = new URLSearchParams();
+  form.set("query", options.query);
+  form.set("format", "application/sparql-results+json");
+  let target = SPARQL_ENDPOINT;
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
+    const response = await doFetch(target, {
+      method: "POST",
+      signal,
+      redirect: "manual",
+      headers: {
+        "user-agent": options.userAgent,
+        accept: "application/sparql-results+json",
+        "content-type": "application/x-www-form-urlencoded"
+      },
+      body: form.toString()
+    });
+    const location = response.headers.get("location");
+    if (response.status >= 300 && response.status < 400 && location !== null) {
+      const next = new URL(location, target).toString();
+      assertRequestable(next);
+      target = next;
+      continue;
+    }
+    return {
+      status: response.status,
+      headers: response.headers,
+      body: await response.text(),
+      ok: response.ok
+    };
+  }
+  throw networkError(`data.bnf.fr redirected this request more than ${MAX_REDIRECTS} times.`, {
+    url: SPARQL_ENDPOINT
+  });
+}
+async function runQuery(options) {
+  const { timeoutMs, maxRetries, limiter, logger } = options;
+  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(`POST ${SPARQL_ENDPOINT} (${options.query.length} characters)`);
+      const response = await postOnce(options, controller.signal);
+      if (response.ok) {
+        let parsed;
+        try {
+          parsed = parseResults(response.body);
+        } catch (error) {
+          limiter.pushBack();
+          throw error;
+        }
+        limiter.succeeded();
+        return parsed;
+      }
+      if (RETRYABLE.has(response.status)) limiter.pushBack();
+      if (PUSH_BACK.has(response.status)) {
+        const asked = parseRetryAfter(response.headers.get("retry-after"));
+        if (asked !== null && asked > LONGEST_WAIT_MS) {
+          throw rateLimited(
+            `data.bnf.fr asked this client to wait ${Math.round(asked / 1e3)} seconds (HTTP ${response.status}).`,
+            { url: SPARQL_ENDPOINT, status: response.status }
+          );
+        }
+        if (attempt >= maxRetries) {
+          throw rateLimited(
+            `data.bnf.fr asked this client to slow down (HTTP ${response.status}).`,
+            {
+              url: SPARQL_ENDPOINT,
+              status: response.status
+            }
+          );
+        }
+        askedWaitMs = asked ?? backoffMs(attempt);
+        lastError = new Error(`HTTP ${response.status}`);
+        continue;
+      }
+      if (RETRYABLE.has(response.status) && attempt < maxRetries) {
+        lastError = new Error(`HTTP ${response.status}`);
+        askedWaitMs = backoffMs(attempt);
+        continue;
+      }
+      if (response.status === 400 || response.status === 422) {
+        const engine = readEngineError(response.body);
+        throw invalidInput(
+          `data.bnf.fr would not run this query${engine?.text ? `: ${engine.text}` : "."}`,
+          "Try fewer or plainer words. If this keeps happening with ordinary input, please report it."
+        );
+      }
+      throw networkError(`data.bnf.fr answered HTTP ${response.status}.`, {
+        url: SPARQL_ENDPOINT,
+        status: response.status
+      });
+    } catch (error) {
+      clearTimeout(deadline);
+      if (error instanceof Error && error.name === "BnfError") throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        lastError = error;
+        if (attempt >= Math.min(maxRetries, RETRIES_AFTER_SILENCE)) {
+          throw timeout(
+            `No answer from data.bnf.fr within ${timeoutMs}ms. A query spanning the whole catalogue can take longer than the service will spend on it.`,
+            { url: SPARQL_ENDPOINT }
+          );
+        }
+        askedWaitMs = backoffMs(attempt);
+        continue;
+      }
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (attempt >= maxRetries) {
+        throw networkError(`Could not reach data.bnf.fr: ${lastError.message}`, {
+          url: SPARQL_ENDPOINT
+        });
+      }
+      askedWaitMs = backoffMs(attempt);
+      continue;
+    } finally {
+      clearTimeout(deadline);
+    }
+  }
+  throw networkError(
+    `Could not reach data.bnf.fr: ${lastError?.message ?? "no attempt was made"}`,
+    {
+      url: SPARQL_ENDPOINT
+    }
+  );
+}
+function parseResults(body) {
+  if (body.trim() === "") {
+    throw parseFailure(
+      "data.bnf.fr returned an empty body, which is what it does when it abandons a query part way through.",
+      { url: SPARQL_ENDPOINT }
+    );
+  }
+  const engine = readEngineError(body);
+  if (engine) {
+    if (engine.kind === "compile") {
+      throw invalidInput(
+        `data.bnf.fr could not read this query: ${engine.text}`,
+        "Try fewer or plainer words. If this keeps happening with ordinary input, please report it."
+      );
+    }
+    throw timeout(`data.bnf.fr started this query and gave it up: ${engine.text}`, {
+      url: SPARQL_ENDPOINT
+    });
+  }
+  let payload;
+  try {
+    payload = JSON.parse(body);
+  } catch {
+    throw parseFailure("data.bnf.fr answered with something that is not JSON.", {
+      url: SPARQL_ENDPOINT
+    });
+  }
+  if (typeof payload !== "object" || payload === null || !("results" in payload) || typeof payload.results !== "object" || !Array.isArray(payload.results?.bindings)) {
+    throw parseFailure("data.bnf.fr answered with JSON that is not a SPARQL result set.", {
+      url: SPARQL_ENDPOINT
+    });
+  }
+  return payload;
+}
+
+// src/bnf/sparql.ts
+function escapeLiteral(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/gu, "");
+}
+var literal = (value) => `"${escapeLiteral(value)}"`;
+function toSearchWords(input) {
+  const cleaned = input.normalize("NFC").replace(/[‘’ʼ]/gu, "'").replace(/[^\p{L}\p{N}'-]+/gu, " ");
+  const words = [];
+  for (const raw of cleaned.split(" ")) {
+    const word = raw.replace(/^['-]+/u, "").replace(/['-]+$/u, "");
+    if (word === "") continue;
+    words.push(word.length > 60 ? word.slice(0, 60) : word);
+    if (words.length >= 12) break;
+  }
+  return words;
+}
+function containsAllWords(words) {
+  if (words.length === 0) {
+    throw invalidInput(
+      "No word to search for: the text held no letters or digits.",
+      "Write the words to look for, such as a surname or a title."
+    );
+  }
+  const clause = words.map((word) => `'${word.replace(/'/g, "''")}'`).join(" AND ");
+  return literal(clause);
+}
+var ARK_ID = /^c[bc][0-9a-z]{6,20}$/;
+var TEMP_WORK_ID = /^[0-9a-f]{32}$/;
+function parseEntityId(input) {
+  const trimmed = input.trim();
+  if (trimmed === "") {
+    throw invalidInput("An identifier is required.");
+  }
+  const arkMatch = /(?:^|\/)ark:\/12148\/(c[bc][0-9a-z]+)/i.exec(trimmed);
+  const bare = arkMatch ? arkMatch[1] : trimmed.replace(/^#/, "").split(/[#?]/)[0];
+  const candidate = (bare ?? "").toLowerCase();
+  if (ARK_ID.test(candidate)) {
+    return {
+      kind: "ark",
+      id: candidate,
+      iri: `http://data.bnf.fr/ark:/12148/${candidate}#about`,
+      pageUrl: `https://data.bnf.fr/ark:/12148/${candidate}`
+    };
+  }
+  const tempMatch = /temp-work\/([0-9a-f]{32})/i.exec(trimmed);
+  const digest = (tempMatch?.[1] ?? candidate).toLowerCase();
+  if (TEMP_WORK_ID.test(digest)) {
+    return {
+      kind: "temp-work",
+      id: `temp-work/${digest}`,
+      iri: `http://data.bnf.fr/temp-work/${digest}/#about`,
+      pageUrl: `https://data.bnf.fr/temp-work/${digest}/`
+    };
+  }
+  throw invalidInput(`"${input}" is not a data.bnf.fr identifier.`, hintFor(trimmed));
+}
+var GALLICA_DOCUMENT = /^(?:bpt6k|btv1b|bd6t|cb32|btv1b)[0-9a-z]+$/i;
+var PAGE_ADDRESS = /data\.bnf\.fr\/(?:[a-z]{2}\/)?(\d{6,12})\/([a-z0-9_]+)/i;
+var GENERAL_HINT = "An identifier looks like 'cb119219976' for an established record, or 'temp-work/22d7f68c1a4bdd081ad7ca791fd3b730' for a provisional one. Take it from a search result rather than building one.";
+function hintFor(input) {
+  const page2 = PAGE_ADDRESS.exec(input);
+  if (page2) {
+    const name = (page2[2] ?? "").replace(/_/g, " ");
+    return `That is the readable address of a data.bnf.fr page, and ${page2[1]} in it is the record's FRBNF number rather than the identifier these tools take. Search for "${name}" with search_authors or search_works, and use the identifier the row carries.`;
+  }
+  const gallicaArk = /ark:\/12148\/([0-9a-z]+)/i.exec(input)?.[1] ?? input;
+  if (GALLICA_DOCUMENT.test(gallicaArk)) {
+    return "That is a Gallica identifier: it names a digitised document rather than a record in the catalogue, and these tools read the catalogue. Search for the work with search_works, then list_editions will give you the Gallica link alongside the edition it belongs to.";
+  }
+  return GENERAL_HINT;
+}
+var iriOf = (id) => `<${id.iri}>`;
+function boundedInteger(value, min, max, name) {
+  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+    throw invalidInput(`'${name}' has to be a whole number.`);
+  }
+  if (value < min || value > max) {
+    throw invalidInput(`'${name}' has to be between ${min} and ${max}.`);
+  }
+  return value;
+}
+
+// src/bnf/queries.ts
+var TEXT_WINDOW = 400;
+var prefixed = (body) => `${PREFIX_BLOCK}
+${body.trim()}
+`;
+function searchAuthorsQuery(words, limit, offset) {
+  const take = boundedInteger(limit, 1, 50, "limit") + 1;
+  const skip = boundedInteger(offset, 0, 5e3, "offset");
+  return prefixed(`
+SELECT ?person ?name ?label ?birthYear ?deathYear ?role WHERE {
+  {
+    SELECT DISTINCT ?person WHERE {
+      {
+        SELECT DISTINCT ?person ?name WHERE {
+          ?person foaf:name ?name .
+          ?name bif:contains ${containsAllWords(words)} .
+        }
+        LIMIT ${TEXT_WINDOW}
+      }
+      ?person a foaf:Person .
+    }
+    ORDER BY ?person
+    LIMIT ${take} OFFSET ${skip}
+  }
+  OPTIONAL { ?person foaf:name ?name }
+  OPTIONAL { ?record foaf:focus ?person ; skos:prefLabel ?label }
+  OPTIONAL { ?person bnf:firstYear ?birthYear }
+  OPTIONAL { ?person bnf:lastYear ?deathYear }
+  OPTIONAL { ?person rdag2:biographicalInformation ?role }
+}`);
+}
+var MOST_TRIPLES = 2e3;
+function authorQuery(id) {
+  const person = iriOf(id);
+  return prefixed(`
+SELECT ?p ?o ?lang WHERE {
+  {
+    ${person} ?p ?o .
+    BIND(LANG(?o) AS ?lang)
+  }
+  UNION
+  {
+    ?record foaf:focus ${person} ; ?p ?o .
+    BIND(LANG(?o) AS ?lang)
+  }
+}
+LIMIT ${MOST_TRIPLES}`);
+}
+function searchWorksQuery(words, limit, offset) {
+  const take = boundedInteger(limit, 1, 50, "limit") + 1;
+  const skip = boundedInteger(offset, 0, 5e3, "offset");
+  return prefixed(`
+SELECT ?work ?title ?date ?status ?creator ?creatorName WHERE {
+  {
+    SELECT DISTINCT ?work WHERE {
+      {
+        SELECT DISTINCT ?work ?title WHERE {
+          ?work dcterms:title ?title .
+          ?title bif:contains ${containsAllWords(words)} .
+        }
+        LIMIT ${TEXT_WINDOW}
+      }
+      ?work a rdafrbr:Work .
+    }
+    ORDER BY ?work
+    LIMIT ${take} OFFSET ${skip}
+  }
+  OPTIONAL { ?work dcterms:title ?title }
+  OPTIONAL { ?work dcterms:date ?date }
+  OPTIONAL { ?work rdae:statusOfIdentification ?status }
+  OPTIONAL {
+    ?work dcterms:creator ?creator .
+    OPTIONAL { ?creator foaf:name ?creatorName }
+  }
+}`);
+}
+function workQuery(id) {
+  const work = iriOf(id);
+  return prefixed(`
+SELECT ?p ?o ?lang ?name WHERE {
+  ${work} ?p ?o .
+  BIND(LANG(?o) AS ?lang)
+  OPTIONAL { ?o foaf:name ?name }
+}
+LIMIT ${MOST_TRIPLES}`);
+}
+function editionsQuery(id, limit, offset) {
+  const work = iriOf(id);
+  const take = boundedInteger(limit, 1, 50, "limit") + 1;
+  const skip = boundedInteger(offset, 0, 5e3, "offset");
+  return prefixed(`
+SELECT ?edition ?title ?date ?year ?publisher ?place ?editionStatement
+       ?extent ?isbn ?note ?catalogue ?reproduction ?ocr WHERE {
+  {
+    SELECT DISTINCT ?edition WHERE {
+      ?edition rdarel:workManifested ${work} .
+    }
+    ORDER BY ?edition
+    LIMIT ${take} OFFSET ${skip}
+  }
+  OPTIONAL { ?edition dcterms:title ?title }
+  OPTIONAL { ?edition dcterms:date ?date }
+  OPTIONAL { ?edition bnf:firstYear ?year }
+  OPTIONAL { ?edition rdae:publishersName ?publisher }
+  OPTIONAL { ?edition rdae:placeOfPublication ?place }
+  OPTIONAL { ?edition rdae:editionStatement ?editionStatement }
+  OPTIONAL { ?edition dcterms:description ?extent }
+  OPTIONAL { ?edition bnf:isbn ?isbn }
+  OPTIONAL { ?edition rdae:note ?note }
+  OPTIONAL { ?edition rdfs:seeAlso ?catalogue }
+  OPTIONAL { ?edition rdarel:electronicReproduction ?reproduction }
+  OPTIONAL { ?edition bnf:OCR ?ocr }
+}`);
+}
+function digitisedForWorkQuery(id, limit) {
+  const work = iriOf(id);
+  const take = boundedInteger(limit, 1, 200, "limit") + 1;
+  return prefixed(`
+SELECT DISTINCT ?rank ?edition ?title ?reproduction ?ocr ?depiction WHERE {
+  {
+    ?edition rdarel:workManifested ${work} .
+    OPTIONAL { ?edition dcterms:title ?title }
+    { ?edition rdarel:electronicReproduction ?reproduction }
+    UNION
+    { ?edition bnf:OCR ?ocr }
+    BIND(0 AS ?rank)
+  }
+  UNION
+  {
+    ${work} foaf:depiction ?depiction .
+    BIND(${work} AS ?edition)
+    BIND(1 AS ?rank)
+  }
+}
+ORDER BY ?rank
+LIMIT ${take}`);
+}
+function digitisedForPersonQuery(id, limit) {
+  const person = iriOf(id);
+  const take = boundedInteger(limit, 1, 200, "limit") + 1;
+  return prefixed(`
+SELECT DISTINCT ?rank ?edition ?title ?reproduction ?ocr ?depiction WHERE {
+  {
+    ?work dcterms:creator ${person} .
+    ?edition rdarel:workManifested ?work .
+    OPTIONAL { ?edition dcterms:title ?title }
+    { ?edition rdarel:electronicReproduction ?reproduction }
+    UNION
+    { ?edition bnf:OCR ?ocr }
+    BIND(0 AS ?rank)
+  }
+  UNION
+  {
+    ${person} foaf:depiction ?depiction .
+    BIND(${person} AS ?edition)
+    BIND(1 AS ?rank)
+  }
+}
+ORDER BY ?rank
+LIMIT ${take}`);
+}
+function kindQuery(id) {
+  return prefixed(`
+SELECT DISTINCT ?type WHERE {
+  ${iriOf(id)} a ?type .
+}
+LIMIT 20`);
+}
+
+// src/bnf/parse.ts
+var P = {
+  type: "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
+  label: "http://www.w3.org/2000/01/rdf-schema#label",
+  seeAlso: "http://www.w3.org/2000/01/rdf-schema#seeAlso",
+  sameAs: "http://www.w3.org/2002/07/owl#sameAs",
+  exactMatch: "http://www.w3.org/2004/02/skos/core#exactMatch",
+  closeMatch: "http://www.w3.org/2004/02/skos/core#closeMatch",
+  prefLabel: "http://www.w3.org/2004/02/skos/core#prefLabel",
+  altLabel: "http://www.w3.org/2004/02/skos/core#altLabel",
+  created: "http://purl.org/dc/terms/created",
+  modified: "http://purl.org/dc/terms/modified",
+  title: "http://purl.org/dc/terms/title",
+  date: "http://purl.org/dc/terms/date",
+  creator: "http://purl.org/dc/terms/creator",
+  language: "http://purl.org/dc/terms/language",
+  subject: "http://purl.org/dc/terms/subject",
+  name: "http://xmlns.com/foaf/0.1/name",
+  givenName: "http://xmlns.com/foaf/0.1/givenName",
+  familyName: "http://xmlns.com/foaf/0.1/familyName",
+  depiction: "http://xmlns.com/foaf/0.1/depiction",
+  birth: "http://vocab.org/bio/0.1/birth",
+  death: "http://vocab.org/bio/0.1/death",
+  firstYear: "http://data.bnf.fr/ontology/bnf-onto/firstYear",
+  lastYear: "http://data.bnf.fr/ontology/bnf-onto/lastYear",
+  subjectLabel: "http://data.bnf.fr/ontology/bnf-onto/subject",
+  isni: "http://isni.org/ontology#identifierValid",
+  placeOfBirth: "http://rdvocab.info/ElementsGr2/placeOfBirth",
+  placeOfDeath: "http://rdvocab.info/ElementsGr2/placeOfDeath",
+  biographicalInformation: "http://rdvocab.info/ElementsGr2/biographicalInformation",
+  languageOfThePerson: "http://rdvocab.info/ElementsGr2/languageOfThePerson",
+  countryAssociated: "http://rdvocab.info/ElementsGr2/countryAssociatedWithThePerson",
+  fieldOfActivity: "http://rdvocab.info/ElementsGr2/fieldOfActivityOfThePerson",
+  formOfWork: "http://rdvocab.info/Elements/formOfWork",
+  statusOfIdentification: "http://rdvocab.info/Elements/statusOfIdentification",
+  /** The occupation, which RDA numbers rather than names. */
+  occupation: "http://rdaregistry.info/Elements/a/#P50113",
+  /** Expressions of a work, which are not editions. */
+  expressionOfWork: "http://rdaregistry.info/Elements/w/#P10078"
+};
+var ALIGNMENT_HOSTS = [
+  { host: "viaf.org", name: "viaf" },
+  { host: "idref.fr", name: "idref" },
+  { host: "dbpedia.org", name: "dbpedia" },
+  { host: "wikidata.org", name: "wikidata" },
+  { host: "isni.org", name: "isni" },
+  { host: "d-nb.info", name: "gnd" },
+  { host: "id.loc.gov", name: "loc" },
+  { host: "datos.bne.es", name: "bne" },
+  { host: "wikipedia.org", name: "wikipedia" },
+  { host: "musicbrainz.org", name: "musicbrainz" },
+  { host: "francearchives.gouv.fr", name: "francearchives" },
+  { host: "imslp.org", name: "imslp" },
+  { host: "catalogue.bnf.fr", name: "catalogue" }
+];
+var text = (term) => {
+  if (!term) return null;
+  const value = term.value.trim();
+  return value === "" ? null : value;
+};
+var integer = (term) => {
+  const raw = text(term);
+  if (raw === null) return null;
+  const value = Number(raw);
+  return Number.isInteger(value) ? value : null;
+};
+function idFromIri(iri) {
+  const ark = /ark:\/12148\/(c[bc][0-9a-z]+)/i.exec(iri);
+  if (ark?.[1]) return ark[1].toLowerCase();
+  const temp = /temp-work\/([0-9a-f]{32})/i.exec(iri);
+  if (temp?.[1]) return `temp-work/${temp[1].toLowerCase()}`;
+  return null;
+}
+var vocabularyTerm = (iri) => decodeURIComponent(iri.replace(/[/#]$/, "").split(/[/#]/).pop() ?? iri);
+function toDigitisedLink(address, role, fromId, fromTitle) {
+  if (!address || !isGallicaAddress(address)) return null;
+  const segment = /ark:\/12148\/([^/?#]+)/.exec(address)?.[1] ?? null;
+  if (!segment) return null;
+  const ark = segment.split(".")[0] ?? segment;
+  if (ark === "") return null;
+  return { ark, url: address, role, fromId, fromTitle };
+}
+function page(rows, limit, skipped) {
+  const more = rows.length > limit;
+  return skipped > 0 ? { rows: rows.slice(0, limit), hasMore: more, skipped } : { rows: rows.slice(0, limit), hasMore: more };
+}
+function byPredicate(results) {
+  const index = /* @__PURE__ */ new Map();
+  for (const row of results.results.bindings) {
+    const predicate = text(row.p);
+    if (predicate === null) continue;
+    const bucket = index.get(predicate);
+    if (bucket) bucket.push(row);
+    else index.set(predicate, [row]);
+  }
+  return index;
+}
+var firstValue = (index, predicate) => text(index.get(predicate)?.[0]?.o);
+var allValues = (index, predicate) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const row of index.get(predicate) ?? []) {
+    const value = text(row.o);
+    if (value !== null) seen.add(value);
+  }
+  return [...seen];
+};
+var allTerms = (index, predicate) => allValues(index, predicate).filter((value) => value.startsWith("http")).map(vocabularyTerm);
+var deweyClasses = (index, predicate) => allValues(index, predicate).filter((value) => value.includes("dewey.info/class/")).map(vocabularyTerm);
+var allWords = (index, predicate) => allValues(index, predicate).filter((value) => !value.startsWith("http"));
+function alignments(index, selfId) {
+  const found = {};
+  for (const predicate of [P.sameAs, P.exactMatch, P.closeMatch, P.seeAlso]) {
+    for (const address of allValues(index, predicate)) {
+      if (!address.startsWith("http")) continue;
+      if (selfId && address.includes(selfId)) continue;
+      let host;
+      try {
+        host = new URL(address).hostname.toLowerCase();
+      } catch {
+        continue;
+      }
+      const known = ALIGNMENT_HOSTS.find(
+        (entry) => host === entry.host || host.endsWith(`.${entry.host}`)
+      );
+      if (!known) continue;
+      (found[known.name] ??= /* @__PURE__ */ new Set()).add(address);
+    }
+  }
+  return Object.fromEntries(Object.entries(found).map(([name, set]) => [name, [...set]]));
+}
+function isniAddresses(index) {
+  return allValues(index, P.isni).map(
+    (value) => `https://isni.org/isni/${value.replace(/\s/g, "")}`
+  );
+}
+function toAuthorSummaries(results, limit) {
+  const rows = [];
+  const seen = /* @__PURE__ */ new Set();
+  let skipped = 0;
+  for (const row of results.results.bindings) {
+    const iri = text(row.person);
+    const id = iri === null ? null : idFromIri(iri);
+    if (iri === null || id === null) {
+      skipped += 1;
+      continue;
+    }
+    if (seen.has(id)) continue;
+    seen.add(id);
+    rows.push({
+      id,
+      name: text(row.name),
+      label: text(row.label),
+      birthYear: integer(row.birthYear),
+      deathYear: integer(row.deathYear),
+      role: text(row.role),
+      sourceUrl: publicPageFor(iri)
+    });
+  }
+  return page(rows, limit, skipped);
+}
+function toAuthorDetail(results, id, pageUrl) {
+  const index = byPredicate(results);
+  const types = allValues(index, P.type);
+  const otherNames = [];
+  const seenLabels = /* @__PURE__ */ new Set();
+  for (const row of index.get(P.altLabel) ?? []) {
+    const label = text(row.o);
+    if (label === null || seenLabels.has(label)) continue;
+    seenLabels.add(label);
+    otherNames.push({ label, language: text(row.lang) });
+  }
+  const sameAs = alignments(index, id);
+  const isni = isniAddresses(index);
+  if (isni.length > 0) sameAs.isni = [.../* @__PURE__ */ new Set([...sameAs.isni ?? [], ...isni])];
+  const catalogueUrl = allValues(index, P.seeAlso).find((address) => address.includes("catalogue.bnf.fr")) ?? null;
+  const depictions = [];
+  for (const address of allValues(index, P.depiction)) {
+    const link = toDigitisedLink(address, "depiction", id, null);
+    if (link) depictions.push(link);
+  }
+  return {
+    id,
+    name: firstValue(index, P.name),
+    label: firstValue(index, P.prefLabel),
+    givenName: firstValue(index, P.givenName),
+    familyName: firstValue(index, P.familyName),
+    otherNames,
+    birthDate: firstValue(index, P.birth),
+    deathDate: firstValue(index, P.death),
+    birthYear: integer(index.get(P.firstYear)?.[0]?.o),
+    deathYear: integer(index.get(P.lastYear)?.[0]?.o),
+    birthPlace: firstValue(index, P.placeOfBirth),
+    deathPlace: firstValue(index, P.placeOfDeath),
+    biographicalInformation: firstValue(index, P.biographicalInformation),
+    occupation: firstValue(index, P.occupation),
+    languages: allTerms(index, P.languageOfThePerson),
+    countries: allTerms(index, P.countryAssociated),
+    fields: allWords(index, P.fieldOfActivity),
+    deweyClasses: deweyClasses(index, P.fieldOfActivity),
+    sameAs,
+    catalogueUrl,
+    recordCreated: firstValue(index, P.created),
+    recordModified: firstValue(index, P.modified),
+    depictions,
+    types,
+    truncated: results.results.bindings.length >= MOST_TRIPLES,
+    sourceUrl: pageUrl
+  };
+}
+function readStatus(statement, iri) {
+  if (statement !== null) {
+    const said = statement.toLowerCase();
+    if (said.includes("provisional")) return "provisional";
+    if (said.includes("established")) return "established";
+  }
+  return iri.includes("/temp-work/") ? "provisional" : "established";
+}
+function toWorkSummaries(results, limit) {
+  const order = [];
+  const byId = /* @__PURE__ */ new Map();
+  let skipped = 0;
+  for (const row of results.results.bindings) {
+    const iri = text(row.work);
+    const id = iri === null ? null : idFromIri(iri);
+    if (iri === null || id === null) {
+      skipped += 1;
+      continue;
+    }
+    let work = byId.get(id);
+    if (!work) {
+      work = {
+        id,
+        title: text(row.title),
+        date: text(row.date),
+        creators: [],
+        status: readStatus(text(row.status), iri),
+        sourceUrl: publicPageFor(iri)
+      };
+      byId.set(id, work);
+      order.push(id);
+    }
+    const creatorIri = text(row.creator);
+    const creatorId = creatorIri ? idFromIri(creatorIri) : null;
+    if (creatorId && !work.creators.some((c) => c.id === creatorId)) {
+      work.creators.push({ id: creatorId, name: text(row.creatorName) });
+    }
+  }
+  return page(
+    order.map((id) => byId.get(id)),
+    limit,
+    skipped
+  );
+}
+function toWorkDetail(results, id, iri, pageUrl) {
+  const index = byPredicate(results);
+  const types = allValues(index, P.type);
+  const truncated = results.results.bindings.length >= MOST_TRIPLES;
+  const creators = [];
+  for (const row of index.get(P.creator) ?? []) {
+    const creatorIri = text(row.o);
+    const creatorId = creatorIri ? idFromIri(creatorIri) : null;
+    if (!creatorId || creators.some((c) => c.id === creatorId)) continue;
+    creators.push({ id: creatorId, name: text(row.name) });
+  }
+  const depictions = [];
+  for (const address of allValues(index, P.depiction)) {
+    const link = toDigitisedLink(address, "depiction", id, null);
+    if (link) depictions.push(link);
+  }
+  const statusStatement = firstValue(index, P.statusOfIdentification);
+  const catalogueUrl = allValues(index, P.seeAlso).find((address) => address.includes("catalogue.bnf.fr")) ?? null;
+  return {
+    id,
+    title: firstValue(index, P.title),
+    label: firstValue(index, P.label),
+    date: firstValue(index, P.date),
+    firstYear: integer(index.get(P.firstYear)?.[0]?.o),
+    creators,
+    languages: allTerms(index, P.language),
+    forms: allTerms(index, P.formOfWork),
+    subjects: allWords(index, P.subjectLabel),
+    deweyClasses: deweyClasses(index, P.subject),
+    status: readStatus(statusStatement, iri),
+    statusStatement,
+    // A cut record makes this the ceiling rather than the count, so it is
+    // withheld rather than published as a number the record does not support.
+    expressionCount: truncated ? null : allValues(index, P.expressionOfWork).length,
+    sameAs: alignments(index, id),
+    catalogueUrl,
+    depictions,
+    types,
+    truncated,
+    sourceUrl: pageUrl
+  };
+}
+function toEditions(results, limit) {
+  const order = [];
+  const byId = /* @__PURE__ */ new Map();
+  let skipped = 0;
+  for (const row of results.results.bindings) {
+    const iri = text(row.edition);
+    const id = iri === null ? null : idFromIri(iri);
+    if (iri === null || id === null) {
+      skipped += 1;
+      continue;
+    }
+    let edition = byId.get(id);
+    if (!edition) {
+      edition = {
+        id,
+        title: text(row.title),
+        date: text(row.date),
+        year: integer(row.year),
+        publisher: text(row.publisher),
+        place: text(row.place),
+        editionStatement: text(row.editionStatement),
+        extent: text(row.extent),
+        isbn: text(row.isbn),
+        note: text(row.note),
+        catalogueUrl: text(row.catalogue),
+        digitised: [],
+        sourceUrl: publicPageFor(iri)
+      };
+      byId.set(id, edition);
+      order.push(id);
+    }
+    for (const [column, role] of [
+      ["reproduction", "reproduction"],
+      ["ocr", "ocr"]
+    ]) {
+      const link = toDigitisedLink(text(row[column]), role, id, edition.title);
+      if (link && !edition.digitised.some((existing) => existing.url === link.url)) {
+        edition.digitised.push(link);
+      }
+    }
+  }
+  return page(
+    order.map((id) => byId.get(id)),
+    limit,
+    skipped
+  );
+}
+function toDigitisedLinks(results, limit) {
+  const links = [];
+  const seen = /* @__PURE__ */ new Set();
+  const rowCount = results.results.bindings.length;
+  for (const row of results.results.bindings) {
+    const fromIri = text(row.edition);
+    const fromId = fromIri ? idFromIri(fromIri) ?? fromIri : "";
+    const title = text(row.title);
+    for (const [column, role] of [
+      ["reproduction", "reproduction"],
+      ["ocr", "ocr"],
+      ["depiction", "depiction"]
+    ]) {
+      const link = toDigitisedLink(text(row[column]), role, fromId, title);
+      if (!link || seen.has(link.url)) continue;
+      seen.add(link.url);
+      links.push(link);
+    }
+  }
+  return { rows: links.slice(0, limit), hasMore: links.length > limit || rowCount > limit };
+}
+function toTypes(results) {
+  const types = /* @__PURE__ */ new Set();
+  for (const row of results.results.bindings) {
+    const iri = text(row.type);
+    if (iri !== null) types.add(iri);
+  }
+  return [...types];
+}
+
+// src/bnf/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 service 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 service 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/bnf/client.ts
+var PERSON_CLASS = "http://xmlns.com/foaf/0.1/Person";
+var WORK_CLASSES = /* @__PURE__ */ new Set([
+  "http://rdvocab.info/uri/schema/FRBRentitiesRDA/Work",
+  "http://rdaregistry.info/Elements/c/#C10001"
+]);
+function withGuarantees(config) {
+  const defaults = loadConfig({});
+  const bounded = (value, fallback, min, max) => {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) return fallback;
+    return Math.min(max, Math.max(min, parsed));
+  };
+  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
+    // BnF can always tell which software is calling, and reach someone.
+    userAgent: claimed === "" || claimed.includes(REPO_URL) ? identifier : `${claimed} ${identifier}`,
+    minIntervalMs: bounded(
+      config.minIntervalMs,
+      defaults.minIntervalMs,
+      MIN_ALLOWED_INTERVAL_MS,
+      MAX_ALLOWED_INTERVAL_MS
+    ),
+    timeoutMs: bounded(config.timeoutMs, defaults.timeoutMs, 1e3, 3e5),
+    maxRetries: bounded(config.maxRetries, defaults.maxRetries, 0, 8),
+    cacheTtlMs: bounded(config.cacheTtlMs, defaults.cacheTtlMs, 0, 864e5),
+    cacheMaxEntries: bounded(config.cacheMaxEntries, defaults.cacheMaxEntries, 1, 5e3)
+  };
+}
+var BnfClient = class {
+  config;
+  logger;
+  limiter;
+  cache;
+  /** Questions already on the wire, so an identical one waits instead of asking. */
+  inFlight = /* @__PURE__ */ new Map();
+  fetchImpl;
+  constructor(options = {}) {
+    const base = { ...loadConfig(), ...options.config };
+    this.config = withGuarantees(base);
+    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 endpoint pushes back. */
+  get intervalMs() {
+    return this.limiter.currentIntervalMs;
+  }
+  /** What the BnF sees this client call itself. */
+  get userAgent() {
+    return this.config.userAgent;
+  }
+  /** The deadline one query is given, which callers report rather than guess. */
+  get timeoutMs() {
+    return this.config.timeoutMs;
+  }
+  /** The one address this client sends anything to. */
+  get endpoint() {
+    return SPARQL_ENDPOINT;
+  }
+  /**
+   * `cacheKey` is stated rather than taken from the query, because two reads of
+   * one query can produce different values: a list cut to five rows is not the
+   * same value as the same list cut to twenty, and serving one for the other
+   * would answer a size the caller never asked for.
+   */
+  read(cacheKey, query, parse) {
+    const hit = this.cache.get(cacheKey);
+    if (hit !== void 0) {
+      this.logger.debug(`cache hit ${cacheKey}`);
+      return Promise.resolve({
+        data: hit.value,
+        cached: true,
+        retrievedAt: new Date(hit.retrievedAt).toISOString()
+      });
+    }
+    const flying = this.inFlight.get(cacheKey);
+    if (flying !== void 0) {
+      this.logger.debug(`joining a request already in flight for ${cacheKey}`);
+      return flying;
+    }
+    const flight = this.fetchAndParse(cacheKey, query, parse);
+    this.inFlight.set(cacheKey, flight);
+    return flight.finally(() => this.inFlight.delete(cacheKey));
+  }
+  async fetchAndParse(cacheKey, query, parse) {
+    const results = await this.limiter.schedule(
+      () => runQuery({
+        query,
+        userAgent: this.config.userAgent,
+        timeoutMs: this.config.timeoutMs,
+        maxRetries: this.config.maxRetries,
+        limiter: this.limiter,
+        logger: this.logger,
+        ...this.fetchImpl ? { fetchImpl: this.fetchImpl } : {}
+      })
+    );
+    const retrievedAt = Date.now();
+    const data = parse(results);
+    this.cache.set(cacheKey, data, retrievedAt);
+    return { data, cached: false, retrievedAt: new Date(retrievedAt).toISOString() };
+  }
+  /** Read an identifier a caller wrote, refusing anything this dataset cannot address. */
+  identify(input) {
+    return parseEntityId(input);
+  }
+  /** The words a search will actually look for, which a tool reports back. */
+  words(input) {
+    return toSearchWords(input);
+  }
+  searchAuthors(name, limit, offset) {
+    const words = toSearchWords(name);
+    const query = searchAuthorsQuery(words, limit, offset);
+    return this.read(
+      `authors:${words.join("+")}:${limit}:${offset}`,
+      query,
+      (results) => toAuthorSummaries(results, limit)
+    );
+  }
+  async getAuthor(id) {
+    const result = await this.read(
+      `author:${id.id}`,
+      authorQuery(id),
+      (results) => toAuthorDetail(results, id.id, id.pageUrl)
+    );
+    if (!result.data.types.includes(PERSON_CLASS)) {
+      await this.refuse(id, result.data.types, "a person", "get_work reads a work.");
+    }
+    return result;
+  }
+  /**
+   * Say what an address is, when it is not the kind of thing that was asked for.
+   *
+   * A record the catalogue does not describe at all and a record describing
+   * something else are two different answers, and only one of them means the
+   * caller should go looking elsewhere.
+   */
+  async refuse(id, types, wanted, hint) {
+    const known = types.length > 0 ? types : (await this.read(`types:${id.id}`, kindQuery(id), toTypes)).data;
+    if (known.length === 0) {
+      throw notFound(`data.bnf.fr describes nothing at "${id.id}".`, {
+        hint: "Find the identifier with search_authors or search_works rather than writing one.",
+        url: id.pageUrl
+      });
+    }
+    throw notFound(
+      `"${id.id}" is described by data.bnf.fr, and it is not ${wanted}: it is typed ${known.join(", ")}.`,
+      { hint, url: id.pageUrl }
+    );
+  }
+  searchWorks(title, limit, offset) {
+    const words = toSearchWords(title);
+    const query = searchWorksQuery(words, limit, offset);
+    return this.read(
+      `works:${words.join("+")}:${limit}:${offset}`,
+      query,
+      (results) => toWorkSummaries(results, limit)
+    );
+  }
+  async getWork(id) {
+    const result = await this.read(
+      `work:${id.id}`,
+      workQuery(id),
+      (results) => toWorkDetail(results, id.id, id.iri, id.pageUrl)
+    );
+    if (!result.data.types.some((type) => WORK_CLASSES.has(type))) {
+      await this.refuse(
+        id,
+        result.data.types,
+        "a work",
+        "get_author reads a person, and list_editions reads the editions of a work."
+      );
+    }
+    return result;
+  }
+  listEditions(id, limit, offset) {
+    const query = editionsQuery(id, limit, offset);
+    return this.read(
+      `editions:${id.id}:${limit}:${offset}`,
+      query,
+      (results) => toEditions(results, limit)
+    );
+  }
+  /** Digitised documents attached to a work and to its editions. */
+  digitisedForWork(id, limit) {
+    return this.read(
+      `digitised-work:${id.id}:${limit}`,
+      digitisedForWorkQuery(id, limit),
+      (results) => toDigitisedLinks(results, limit)
+    );
+  }
+  /** Digitised documents attached to a person and to the editions of their works. */
+  digitisedForPerson(id, limit) {
+    return this.read(
+      `digitised-person:${id.id}:${limit}`,
+      digitisedForPersonQuery(id, limit),
+      (results) => toDigitisedLinks(results, limit)
+    );
+  }
+  /** What an address is typed as, which tells a person from a work. */
+  types(id) {
+    return this.read(`types:${id.id}`, kindQuery(id), toTypes);
+  }
+};
+export {
+  BnfClient
+};
+//# sourceMappingURL=client.js.map