mcp-databnf 1.0.0 → 1.1.0

package/dist/bnf/client.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var PKG_VERSION = "1.0.0";
+var PKG_VERSION = "1.1.0";
 var REPO_URL = "https://github.com/smeet666/mcp-databnf";
 
 // src/config.ts
@@ -387,8 +387,36 @@ 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)}"`;
+var INVISIBLE = /[\u0000-\u0008\u000e-\u001f\u007f-\u009f\u00ad\u061c\u180e\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/gu;
+function withoutInvisibles(input) {
+  return input.replace(INVISIBLE, "");
+}
+function invisibleCharacters(input) {
+  const found = [];
+  for (const character of input.match(INVISIBLE) ?? []) {
+    if (!found.includes(character)) found.push(character);
+  }
+  return found;
+}
+function charactersSetAside(input) {
+  const found = [];
+  for (const character of withoutInvisibles(input).normalize("NFC")) {
+    if (/[\p{L}\p{N}'\-\s]/u.test(character) || /[‘’ʼ]/u.test(character)) continue;
+    if (!found.includes(character)) found.push(character);
+  }
+  return found;
+}
+function readSearchText(input) {
+  const words = toSearchWords(input);
+  return {
+    words,
+    terms: toIndexTerms(words),
+    invisible: invisibleCharacters(input),
+    setAside: charactersSetAside(input)
+  };
+}
 function toSearchWords(input) {
-  const cleaned = input.normalize("NFC").replace(/[‘’ʼ]/gu, "'").replace(/[^\p{L}\p{N}'-]+/gu, " ");
+  const cleaned = withoutInvisibles(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, "");
@@ -398,6 +426,15 @@ function toSearchWords(input) {
   }
   return words;
 }
+function toIndexTerms(words) {
+  const terms = [];
+  for (const word of words) {
+    for (const piece of word.split(/['-]+/u)) {
+      if (piece !== "" && !terms.includes(piece)) terms.push(piece);
+    }
+  }
+  return terms;
+}
 function containsAllWords(words) {
   if (words.length === 0) {
     throw invalidInput(
@@ -469,31 +506,47 @@ var TEXT_WINDOW = 400;
 var prefixed = (body) => `${PREFIX_BLOCK}
 ${body.trim()}
 `;
+function windowOccupancy(predicate, words) {
+  return `
+  {
+    SELECT (COUNT(*) AS ?windowRows) WHERE {
+      SELECT DISTINCT ?windowEntity ?windowText WHERE {
+        ?windowEntity ${predicate} ?windowText .
+        ?windowText bif:contains ${containsAllWords(words)} .
+      }
+      LIMIT ${TEXT_WINDOW}
+    }
+  }`;
+}
 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 ?person ?name ?label ?birthYear ?deathYear ?role ?windowRows WHERE {
   {
-    SELECT DISTINCT ?person WHERE {
-      {
-        SELECT DISTINCT ?person ?name WHERE {
-          ?person foaf:name ?name .
-          ?name bif:contains ${containsAllWords(words)} .
+    {
+      SELECT DISTINCT ?person WHERE {
+        {
+          SELECT DISTINCT ?person ?name WHERE {
+            ?person foaf:name ?name .
+            ?name bif:contains ${containsAllWords(words)} .
+          }
+          LIMIT ${TEXT_WINDOW}
         }
-        LIMIT ${TEXT_WINDOW}
+        ?person a foaf:Person .
       }
-      ?person a foaf:Person .
+      ORDER BY ?person
+      LIMIT ${take} OFFSET ${skip}
     }
-    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 }
   }
-  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 }
-}`);
+  UNION${windowOccupancy("foaf:name", words)}
+}
+ORDER BY ?person`);
 }
 var MOST_TRIPLES = 2e3;
 function authorQuery(id) {
@@ -516,29 +569,54 @@ 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 ?work ?title ?date ?status ?creator ?creatorName ?windowRows WHERE {
   {
-    SELECT DISTINCT ?work WHERE {
-      {
-        SELECT DISTINCT ?work ?title WHERE {
-          ?work dcterms:title ?title .
-          ?title bif:contains ${containsAllWords(words)} .
+    {
+      SELECT DISTINCT ?work WHERE {
+        {
+          SELECT DISTINCT ?work ?title WHERE {
+            ?work dcterms:title ?title .
+            ?title bif:contains ${containsAllWords(words)} .
+          }
+          LIMIT ${TEXT_WINDOW}
         }
-        LIMIT ${TEXT_WINDOW}
+        ?work a rdafrbr:Work .
       }
-      ?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 }
+    }
+  }
+  UNION${windowOccupancy("dcterms:title", words)}
+}
+ORDER BY ?work`);
+}
+function worksByCreatorQuery(id, limit, offset) {
+  const person = iriOf(id);
+  const take = boundedInteger(limit, 1, 50, "limit") + 1;
+  const skip = boundedInteger(offset, 0, 5e3, "offset");
+  return prefixed(`
+SELECT ?work ?title ?date ?year ?status ?form WHERE {
+  {
+    SELECT DISTINCT ?work WHERE {
+      ?work dcterms:creator ${person} .
     }
     ORDER BY ?work
     LIMIT ${take} OFFSET ${skip}
   }
   OPTIONAL { ?work dcterms:title ?title }
   OPTIONAL { ?work dcterms:date ?date }
+  OPTIONAL { ?work bnf:firstYear ?year }
   OPTIONAL { ?work rdae:statusOfIdentification ?status }
-  OPTIONAL {
-    ?work dcterms:creator ?creator .
-    OPTIONAL { ?creator foaf:name ?creatorName }
-  }
-}`);
+  OPTIONAL { ?work rdae:formOfWork ?form }
+}
+ORDER BY ?work`);
 }
 function workQuery(id) {
   const work = iriOf(id);
@@ -576,7 +654,8 @@ SELECT ?edition ?title ?date ?year ?publisher ?place ?editionStatement
   OPTIONAL { ?edition rdfs:seeAlso ?catalogue }
   OPTIONAL { ?edition rdarel:electronicReproduction ?reproduction }
   OPTIONAL { ?edition bnf:OCR ?ocr }
-}`);
+}
+ORDER BY ?edition`);
 }
 function digitisedForWorkQuery(id, limit) {
   const work = iriOf(id);
@@ -713,12 +792,28 @@ function toDigitisedLink(address, role, fromId, fromTitle) {
   if (!segment) return null;
   const ark = segment.split(".")[0] ?? segment;
   if (ark === "") return null;
-  return { ark, url: address, role, fromId, fromTitle };
+  return { ark, url: address, rendering: renderingOf(address, ark), role, fromId, fromTitle };
+}
+function renderingOf(address, ark) {
+  const path = address.split(/[?#]/)[0] ?? address;
+  const after = path.slice(path.indexOf(`ark:/12148/${ark}`) + `ark:/12148/${ark}`.length);
+  const rendering = after.replace(/^[./]+/, "").replace(/\/+$/, "");
+  return rendering === "" ? null : rendering;
 }
 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 readWindowOccupancy(results) {
+  for (const row of results.results.bindings) {
+    const raw = text(row.windowRows);
+    if (raw === null) continue;
+    const count = Number(raw);
+    if (Number.isInteger(count)) return count >= TEXT_WINDOW;
+  }
+  return null;
+}
+var isOccupancyRow = (row, entity) => row.windowRows !== void 0 && row[entity] === void 0;
 function byPredicate(results) {
   const index = /* @__PURE__ */ new Map();
   for (const row of results.results.bindings) {
@@ -773,6 +868,7 @@ function toAuthorSummaries(results, limit) {
   const seen = /* @__PURE__ */ new Set();
   let skipped = 0;
   for (const row of results.results.bindings) {
+    if (isOccupancyRow(row, "person")) continue;
     const iri = text(row.person);
     const id = iri === null ? null : idFromIri(iri);
     if (iri === null || id === null) {
@@ -791,7 +887,7 @@ function toAuthorSummaries(results, limit) {
       sourceUrl: publicPageFor(iri)
     });
   }
-  return page(rows, limit, skipped);
+  return { ...page(rows, limit, skipped), indexWindowFull: readWindowOccupancy(results) };
 }
 function toAuthorDetail(results, id, pageUrl) {
   const index = byPredicate(results);
@@ -855,6 +951,7 @@ function toWorkSummaries(results, limit) {
   const byId = /* @__PURE__ */ new Map();
   let skipped = 0;
   for (const row of results.results.bindings) {
+    if (isOccupancyRow(row, "work")) continue;
     const iri = text(row.work);
     const id = iri === null ? null : idFromIri(iri);
     if (iri === null || id === null) {
@@ -880,6 +977,46 @@ function toWorkSummaries(results, limit) {
       work.creators.push({ id: creatorId, name: text(row.creatorName) });
     }
   }
+  return {
+    ...page(
+      order.map((id) => byId.get(id)),
+      limit,
+      skipped
+    ),
+    indexWindowFull: readWindowOccupancy(results)
+  };
+}
+function toAuthoredWorks(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),
+        year: integer(row.year),
+        forms: [],
+        status: readStatus(text(row.status), iri),
+        sourceUrl: publicPageFor(iri)
+      };
+      byId.set(id, work);
+      order.push(id);
+    }
+    const form = text(row.form);
+    if (form !== null && form.startsWith("http")) {
+      const term = vocabularyTerm(form);
+      if (!work.forms.includes(term)) work.forms.push(term);
+    }
+  }
   return page(
     order.map((id) => byId.get(id)),
     limit,
@@ -1179,6 +1316,25 @@ var BnfClient = class {
   words(input) {
     return toSearchWords(input);
   }
+  /**
+   * The terms the index requires, which is what a row's presence rests on.
+   *
+   * The index splits inside a word at an apostrophe and at a hyphen, so a word
+   * a caller wrote as one can reach it as two, each required on its own.
+   */
+  indexTerms(words) {
+    return toIndexTerms(words);
+  }
+  /**
+   * How a piece of caller text became the terms the search was run with.
+   *
+   * A tool reports the reading back, so the same reading has to be the one the
+   * query was built from: the words, the terms the index makes of them, and
+   * the characters that reached neither.
+   */
+  searchReading(input) {
+    return readSearchText(input);
+  }
   searchAuthors(name, limit, offset) {
     const words = toSearchWords(name);
     const query = searchAuthorsQuery(words, limit, offset);
@@ -1195,7 +1351,7 @@ var BnfClient = class {
       (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.");
+      await this.refuse(id, "a person", "get_work reads a work.");
     }
     return result;
   }
@@ -1206,8 +1362,8 @@ var BnfClient = class {
    * 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;
+  async refuse(id, wanted, hint) {
+    const known = (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.",
@@ -1237,13 +1393,26 @@ var BnfClient = class {
     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;
   }
+  /**
+   * The works one person is named the creator of.
+   *
+   * The record is not checked here. A person the catalogue credits with nothing
+   * and an address that names no person both answer with no rows, and telling
+   * them apart costs a second query that only an empty answer needs.
+   */
+  worksByAuthor(id, limit, offset) {
+    return this.read(
+      `author-works:${id.id}:${limit}:${offset}`,
+      worksByCreatorQuery(id, limit, offset),
+      (results) => toAuthoredWorks(results, limit)
+    );
+  }
   listEditions(id, limit, offset) {
     const query = editionsQuery(id, limit, offset);
     return this.read(