ochre-sdk 1.0.78 → 1.1.0

package/dist/{utilities.mjs → errors.mjs}

@@ -1,17 +1,21 @@
+import { isObject, readEntries } from "./reflection.mjs";
 import * as v from "valibot";
-//#region src/utilities.ts
-const PSEUDO_UUID_REGEX = /^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i;
-function isRecord(value) {
-	return typeof value === "object" && value != null;
-}
-function isSchemaValidationIssue(value) {
-	if (!isRecord(value)) return false;
-	return typeof value.kind === "string" && typeof value.type === "string" && typeof value.message === "string";
-}
+//#region src/errors.ts
+/**
+* The shape a valibot issue has to have for this module to render it
+*
+* A schema rather than a hand-written predicate: the fields being checked are
+* exactly a shape, and `v.is` narrows without asserting anything unchecked. An
+* array cannot pass, because it carries none of these fields.
+*/
+const schemaValidationIssueSchema = v.looseObject({
+	kind: v.string(),
+	type: v.string(),
+	message: v.string()
+});
+const schemaValidationIssuesSchema = v.pipe(v.array(schemaValidationIssueSchema), v.minLength(1));
 function isSchemaValidationIssues(value) {
-	if (!Array.isArray(value) || value.length === 0) return false;
-	for (const item of value) if (!isSchemaValidationIssue(item)) return false;
-	return true;
+	return v.is(schemaValidationIssuesSchema, value);
 }
 function getIssuePath(issue) {
 	const path = v.getDotPath(issue);
@@ -54,7 +58,7 @@ function formatCauseArray(value) {
 }
 function formatCauseRecord(value) {
 	const values = [];
-	for (const [key, entryValue] of Object.entries(value)) {
+	for (const [key, entryValue] of readEntries(value)) {
 		const formattedEntryValue = formatPrimitiveValue(entryValue);
 		if (formattedEntryValue != null) values.push(`${key}: ${formattedEntryValue}`);
 	}
@@ -65,7 +69,7 @@ function formatCauseValue(value) {
 	const primitiveValue = formatPrimitiveValue(value);
 	if (primitiveValue != null) return primitiveValue;
 	if (Array.isArray(value)) return formatCauseArray(value);
-	if (isRecord(value)) return formatCauseRecord(value);
+	if (isObject(value)) return formatCauseRecord(value);
 	return null;
 }
 function appendContainedErrors(lines, containedErrors, indent, depth, seenErrors) {
@@ -126,6 +130,13 @@ function getDetailedError(error, fallbackMessage = "Unknown error") {
 	appendDetailedError(lines, error, fallbackMessage, 0, /* @__PURE__ */ new Set());
 	return lines.join("\n");
 }
+/**
+* Render an error as a short message and a fully detailed report
+* @param error - The thrown value
+* @param fallbackMessage - The message to use when the value is not an Error
+* @returns The message and the detailed report
+* @internal
+*/
 function getErrorOutput(error, fallbackMessage) {
 	const message = getErrorMessage(error, fallbackMessage);
 	return {
@@ -133,6 +144,13 @@ function getErrorOutput(error, fallbackMessage) {
 		detailedError: getDetailedError(error, message)
 	};
 }
+/**
+* Wrap schema validation issues in an error {@link getErrorOutput} can render
+* @param message - The failure message
+* @param issues - The validation issues to carry as the cause
+* @returns The error
+* @internal
+*/
 function createSchemaValidationError(message, issues) {
 	return new Error(message, { cause: issues });
 }
@@ -142,74 +160,5 @@ function createSchemaValidationError(message, issues) {
 * @returns True if the string is a valid pseudo-UUID, false otherwise
 * @internal
 */
-function isPseudoUuid(value) {
-	return PSEUDO_UUID_REGEX.test(value);
-}
-/**
-* Build a string literal for an XQuery string
-* @param value - The string value to escape
-* @returns The escaped string literal
-*/
-function stringLiteral(value) {
-	return `"${value.replaceAll("\"", "\"\"")}"`;
-}
-/**
-* XQuery prolog declaring `local:omit-supplemental`, which drops every element
-* carrying `supplemental="true"` from a node sequence, at any depth.
-*
-* Subtrees without a supplemental descendant are returned by reference, so
-* nodes are only copied along the path leading to an omitted element. The
-* lookahead walks the attribute axis (`//@supplemental`) rather than testing
-* every element, which measures around three times faster on large documents.
-*
-* Must be declared before any query body that calls {@link omitSupplemental}.
-*/
-const SUPPLEMENTAL_XQUERY_PROLOG = `declare function local:omit-supplemental($nodes as node()*) as node()* {
-  for $node in $nodes
-  return
-    if ($node instance of element())
-    then
-      if ($node/@supplemental = "true")
-      then ()
-      else if (empty($node//@supplemental[. = "true"]))
-      then $node
-      else element { node-name($node) } {
-        $node/@*,
-        local:omit-supplemental($node/node())
-      }
-    else $node
-};`;
-/**
-* Wrap an XQuery node expression so supplemental nodes are omitted from it
-* @param expression - The XQuery expression returning the nodes to filter
-* @returns The wrapped XQuery expression
-*/
-function omitSupplemental(expression) {
-	return `local:omit-supplemental(${expression})`;
-}
-/**
-* XQuery predicate keeping only nodes that are neither supplemental themselves
-* nor nested inside a supplemental node. Use it when aggregating over nodes
-* instead of returning them.
-*/
-const NOT_SUPPLEMENTAL_PREDICATE = "[not(ancestor-or-self::*[@supplemental = \"true\"])]";
-/**
-* Flatten a properties array
-* @param properties - The properties to flatten
-* @returns The flattened properties
-* @internal
-*/
-function flattenProperties(properties) {
-	const result = [];
-	for (const property of properties) {
-		result.push({
-			variable: property.variable,
-			values: property.values,
-			comment: property.comment
-		});
-		if ("properties" in property) result.push(...flattenProperties(property.properties));
-	}
-	return result;
-}
 //#endregion
-export { NOT_SUPPLEMENTAL_PREDICATE, SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, omitSupplemental, stringLiteral };
+export { createSchemaValidationError, getErrorOutput };

package/dist/fetchers/gallery.mjs

@@ -1,48 +1,17 @@
-import { DEFAULT_LANGUAGES, XML_PARSER_OPTIONS } from "../constants.mjs";
-import { SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, getErrorOutput, omitSupplemental, stringLiteral } from "../utilities.mjs";
-import { gallerySchema, iso639_3Schema } from "../schemas.mjs";
-import { restoreXMLMetadata } from "../xml/metadata.mjs";
+import { getErrorOutput } from "../errors.mjs";
+import { requestOchre } from "./request.mjs";
+import { gallerySchema } from "../schemas.mjs";
+import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
 import { parseGallery } from "../parsers/index.mjs";
 import { XMLGalleryData } from "../xml/schemas.mjs";
+import { compileOchreQuery, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
-import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/gallery.ts
-function parseLanguages(languages) {
-	for (const language of languages) v.parse(iso639_3Schema, language);
-	return languages;
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null;
-}
-function collectContentLanguages(value, languages) {
-	if (Array.isArray(value)) {
-		for (const item of value) collectContentLanguages(item, languages);
-		return;
-	}
-	if (!isRecord(value)) return;
-	const content = value.content;
-	if (Array.isArray(content)) for (const contentItem of content) {
-		if (!isRecord(contentItem)) continue;
-		const language = contentItem.lang;
-		if (typeof language === "string" && language !== "zxx") languages.add(language);
-	}
-	for (const child of Object.values(value)) collectContentLanguages(child, languages);
-}
-function resolveGalleryLanguages(data, requestedLanguages) {
-	if (requestedLanguages.length > 0) return requestedLanguages;
-	const languages = /* @__PURE__ */ new Set();
-	collectContentLanguages(data.result.ochre.gallery, languages);
-	return languages.size > 0 ? [...languages] : [...DEFAULT_LANGUAGES];
-}
 function buildXQuery(parameters) {
 	const { uuid, filter, page, perPage } = parameters;
 	const start = (page - 1) * perPage + 1;
 	const filterLiteral = stringLiteral(filter?.trim() ?? "");
-	return `xquery version "1.0-ml";
-
-${SUPPLEMENTAL_XQUERY_PROLOG}
-
-<ochre>{
+	return compileOchreQuery({ body: ({ omitSupplemental }) => `<ochre>{
   for $q in doc()/ochre[@uuid=${stringLiteral(uuid)}]
   let $filter := ${filterLiteral}
   let $resources := $q//items/resource
@@ -58,29 +27,24 @@ ${SUPPLEMENTAL_XQUERY_PROLOG}
       subsequence($filtered, ${start}, ${perPage})
     )`)}
   }</gallery>
-}</ochre>`;
+}</ochre>` });
 }
 async function fetchGallery(parameters, options) {
 	try {
 		const { uuid, filter, page, perPage } = v.parse(gallerySchema, parameters);
-		const requestedLanguages = options?.languages == null ? [] : parseLanguages(options.languages);
-		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
-			method: "POST",
-			body: buildXQuery({
+		const requestedLanguages = parseRequestedLanguages(options?.languages);
+		const output = await requestOchre({
+			xquery: buildXQuery({
 				uuid,
 				filter,
 				page,
 				perPage
 			}),
-			headers: { "Content-Type": "application/xquery" }
+			schema: XMLGalleryData,
+			label: "OCHRE gallery",
+			options
 		});
-		if (!response.ok) throw new Error("Error fetching gallery items, please try again later.", { cause: response.statusText });
-		const dataRaw = await response.text();
-		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
-		const { success, issues, output } = v.safeParse(XMLGalleryData, data);
-		if (!success) throw createSchemaValidationError("Failed to parse gallery XML", issues);
-		restoreXMLMetadata(output, data);
-		const languages = resolveGalleryLanguages(output, requestedLanguages);
+		const languages = resolveContentLanguages(output.result.ochre.gallery, requestedLanguages);
 		return {
 			gallery: parseGallery(output, { languages }),
 			error: null,
@@ -89,7 +53,7 @@ async function fetchGallery(parameters, options) {
 	} catch (error) {
 		return {
 			gallery: null,
-			...getErrorOutput(error, "Failed to fetch gallery")
+			...getErrorOutput(error, "Failed to fetch OCHRE gallery")
 		};
 	}
 }

package/dist/fetchers/item-children.mjs

@@ -1,67 +1,25 @@
-import { DEFAULT_LANGUAGES, XML_PARSER_OPTIONS } from "../constants.mjs";
-import { SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, getErrorOutput, omitSupplemental, stringLiteral } from "../utilities.mjs";
-import { iso639_3Schema, uuidSchema } from "../schemas.mjs";
-import { restoreXMLMetadata } from "../xml/metadata.mjs";
+import { OCHRE_COLLECTION_CATEGORIES } from "../categories.mjs";
+import { getErrorOutput } from "../errors.mjs";
+import { requestOchre } from "./request.mjs";
+import { uuidSchema } from "../schemas.mjs";
+import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
 import { parseLinkedItems } from "../parsers/index.mjs";
 import { XMLItemLinksData } from "../xml/schemas.mjs";
+import { compileOchreQuery, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
-import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/item-children.ts
-const ITEM_COLLECTION_CATEGORIES = [
-	"tree",
-	"bibliography",
-	"concept",
-	"spatialUnit",
-	"period",
-	"person",
-	"propertyVariable",
-	"propertyValue",
-	"resource",
-	"text",
-	"set"
-];
-function parseLanguages(languages) {
-	for (const language of languages) v.parse(iso639_3Schema, language);
-	return languages;
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null;
-}
-function collectContentLanguages(value, languages) {
-	if (Array.isArray(value)) {
-		for (const item of value) collectContentLanguages(item, languages);
-		return;
-	}
-	if (!isRecord(value)) return;
-	const content = value.content;
-	if (Array.isArray(content)) for (const contentItem of content) {
-		if (!isRecord(contentItem)) continue;
-		const language = contentItem.lang;
-		if (typeof language === "string" && language !== "zxx") languages.add(language);
-	}
-	for (const child of Object.values(value)) collectContentLanguages(child, languages);
-}
-function resolveItemChildrenLanguages(data, requestedLanguages) {
-	if (requestedLanguages.length > 0) return requestedLanguages;
-	const languages = /* @__PURE__ */ new Set();
-	collectContentLanguages(data.result.ochre.items, languages);
-	return languages.size > 0 ? [...languages] : [...DEFAULT_LANGUAGES];
-}
 function buildXQuery(uuid, category) {
-	const categories = category == null ? ITEM_COLLECTION_CATEGORIES : typeof category === "string" ? [category] : category;
+	const categories = category == null ? OCHRE_COLLECTION_CATEGORIES : typeof category === "string" ? [category] : category;
 	const collectionQueries = Array.from(categories, (possibleCategory) => `cts:search(fn:collection("ochre/${possibleCategory}")/ochre, $uuid-query)`);
-	return `xquery version "1.0-ml";
-
-${SUPPLEMENTAL_XQUERY_PROLOG}
-
-declare function local:item-children($nodes as node()*) as node()* {
+	return compileOchreQuery({
+		declarations: [`declare function local:item-children($nodes as node()*) as node()* {
   for $node in $nodes
   return
     if (local-name($node) = "heading")
     then local:item-children($node/*)
     else $node
-};
-
+};`],
+		body: ({ omitSupplemental }) => `
 let $uuid := ${stringLiteral(uuid)}
 let $uuid-query := cts:element-attribute-value-query(xs:QName("ochre"), xs:QName("uuid"), $uuid, "exact")
 let $ochre := (
@@ -93,24 +51,20 @@ let $children :=
 return
   <ochre>
     <items>{${omitSupplemental("$children")}}</items>
-  </ochre>`;
+  </ochre>`
+	});
 }
 async function fetchItemChildren(uuid, options) {
 	try {
 		const parsedUuid = v.parse(uuidSchema, uuid);
-		const requestedLanguages = options?.languages == null ? [] : parseLanguages(options.languages);
-		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
-			method: "POST",
-			body: buildXQuery(parsedUuid, options?.category),
-			headers: { "Content-Type": "application/xquery" }
+		const requestedLanguages = parseRequestedLanguages(options?.languages);
+		const output = await requestOchre({
+			xquery: buildXQuery(parsedUuid, options?.category),
+			schema: XMLItemLinksData,
+			label: "OCHRE item children",
+			options
 		});
-		if (!response.ok) throw new Error("Failed to fetch OCHRE item children", { cause: response.statusText });
-		const dataRaw = await response.text();
-		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
-		const { success, issues, output } = v.safeParse(XMLItemLinksData, data);
-		if (!success) throw createSchemaValidationError("Failed to parse OCHRE item children", issues);
-		restoreXMLMetadata(output, data);
-		const languages = resolveItemChildrenLanguages(output, requestedLanguages);
+		const languages = resolveContentLanguages(output.result.ochre.items, requestedLanguages);
 		return {
 			items: parseLinkedItems(output.result.ochre.items, {
 				containedItemCategory: options?.containedItemCategory,

package/dist/fetchers/item-links.mjs

@@ -1,39 +1,13 @@
-import { DEFAULT_LANGUAGES, XML_PARSER_OPTIONS } from "../constants.mjs";
-import { SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, getErrorOutput, omitSupplemental, stringLiteral } from "../utilities.mjs";
-import { iso639_3Schema, uuidSchema } from "../schemas.mjs";
-import { restoreXMLMetadata } from "../xml/metadata.mjs";
+import { ITEM_CATEGORY_ALIASES, OCHRE_COLLECTION_CATEGORIES } from "../categories.mjs";
+import { getErrorOutput } from "../errors.mjs";
+import { requestOchre } from "./request.mjs";
+import { uuidSchema } from "../schemas.mjs";
+import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
 import { parseLinkedItems } from "../parsers/index.mjs";
 import { XMLItemLinksData } from "../xml/schemas.mjs";
+import { compileOchreQuery, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
-import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/item-links.ts
-function parseLanguages(languages) {
-	for (const language of languages) v.parse(iso639_3Schema, language);
-	return languages;
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null;
-}
-function collectContentLanguages(value, languages) {
-	if (Array.isArray(value)) {
-		for (const item of value) collectContentLanguages(item, languages);
-		return;
-	}
-	if (!isRecord(value)) return;
-	const content = value.content;
-	if (Array.isArray(content)) for (const contentItem of content) {
-		if (!isRecord(contentItem)) continue;
-		const language = contentItem.lang;
-		if (typeof language === "string" && language !== "zxx") languages.add(language);
-	}
-	for (const child of Object.values(value)) collectContentLanguages(child, languages);
-}
-function resolveItemLinksLanguages(data, requestedLanguages) {
-	if (requestedLanguages.length > 0) return requestedLanguages;
-	const languages = /* @__PURE__ */ new Set();
-	collectContentLanguages(data.result.ochre.items, languages);
-	return languages.size > 0 ? [...languages] : [...DEFAULT_LANGUAGES];
-}
 /**
 * Build an XQuery string to fetch linked items from the OCHRE API.
 *
@@ -41,20 +15,19 @@ function resolveItemLinksLanguages(data, requestedLanguages) {
 * @returns An XQuery string
 */
 function buildXQuery(uuid) {
-	const xquery = `let $item-uuid := ${stringLiteral(uuid)}
+	const linkedItems = `for $link at $position in $link-nodes
+      let $uuid := $link/@uuid/string()
+      let $category := name($link)
+      where $uuid ne "" and not($uuid = $link-nodes[position() lt $position]/@uuid/string())
+      return
+        ${OCHRE_COLLECTION_CATEGORIES.map((category) => {
+		return `if (${ITEM_CATEGORY_ALIASES[category].map((alias) => `$category = ${stringLiteral(alias)}`).join(" or ")}) then fn:collection("ochre/${category}")/ochre/${category}[@uuid = $uuid]`;
+	}).join("\n        else ")}
+        else ()`;
+	return compileOchreQuery({ body: ({ omitSupplemental }) => `<ochre>{let $item-uuid := ${stringLiteral(uuid)}
 
 let $source-items := (
-  fn:collection("ochre/resource")/ochre[@uuid = $item-uuid]/resource,
-  fn:collection("ochre/bibliography")/ochre[@uuid = $item-uuid]/bibliography,
-  fn:collection("ochre/period")/ochre[@uuid = $item-uuid]/period,
-  fn:collection("ochre/person")/ochre[@uuid = $item-uuid]/person,
-  fn:collection("ochre/propertyVariable")/ochre[@uuid = $item-uuid]/propertyVariable,
-  fn:collection("ochre/propertyValue")/ochre[@uuid = $item-uuid]/propertyValue,
-  fn:collection("ochre/text")/ochre[@uuid = $item-uuid]/text,
-  fn:collection("ochre/tree")/ochre[@uuid = $item-uuid]/tree,
-  fn:collection("ochre/set")/ochre[@uuid = $item-uuid]/set,
-  fn:collection("ochre/spatialUnit")/ochre[@uuid = $item-uuid]/spatialUnit,
-  fn:collection("ochre/concept")/ochre[@uuid = $item-uuid]/concept
+${OCHRE_COLLECTION_CATEGORIES.map((category) => `  fn:collection("ochre/${category}")/ochre[@uuid = $item-uuid]/${category}`).join(",\n")}
 )
 
 let $link-nodes := (
@@ -65,46 +38,20 @@ let $link-nodes := (
 
 return
     <items>{
-      ${omitSupplemental(`for $link at $position in $link-nodes
-      let $uuid := $link/@uuid/string()
-      let $category := name($link)
-      where $uuid ne "" and not($uuid = $link-nodes[position() lt $position]/@uuid/string())
-      return
-        if ($category = "resource") then fn:collection("ochre/resource")/ochre/resource[@uuid = $uuid]
-        else if ($category = "bibliography") then fn:collection("ochre/bibliography")/ochre/bibliography[@uuid = $uuid]
-        else if ($category = "period") then fn:collection("ochre/period")/ochre/period[@uuid = $uuid]
-        else if ($category = "person") then fn:collection("ochre/person")/ochre/person[@uuid = $uuid]
-        else if ($category = "propertyVariable" or $category = "variable") then fn:collection("ochre/propertyVariable")/ochre/propertyVariable[@uuid = $uuid]
-        else if ($category = "propertyValue" or $category = "value") then fn:collection("ochre/propertyValue")/ochre/propertyValue[@uuid = $uuid]
-        else if ($category = "text") then fn:collection("ochre/text")/ochre/text[@uuid = $uuid]
-        else if ($category = "tree") then fn:collection("ochre/tree")/ochre/tree[@uuid = $uuid]
-        else if ($category = "set") then fn:collection("ochre/set")/ochre/set[@uuid = $uuid]
-        else if ($category = "spatialUnit") then fn:collection("ochre/spatialUnit")/ochre/spatialUnit[@uuid = $uuid]
-        else if ($category = "concept") then fn:collection("ochre/concept")/ochre/concept[@uuid = $uuid]
-        else ()`)}
-    }</items>`;
-	return `xquery version "1.0-ml";
-
-${SUPPLEMENTAL_XQUERY_PROLOG}
-
-<ochre>{${xquery}}</ochre>`;
+      ${omitSupplemental(linkedItems)}
+    }</items>}</ochre>` });
 }
 async function fetchItemLinks(uuid, options) {
 	try {
 		const parsedUuid = v.parse(uuidSchema, uuid);
-		const requestedLanguages = options?.languages == null ? [] : parseLanguages(options.languages);
-		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
-			method: "POST",
-			body: buildXQuery(parsedUuid),
-			headers: { "Content-Type": "application/xquery" }
+		const requestedLanguages = parseRequestedLanguages(options?.languages);
+		const output = await requestOchre({
+			xquery: buildXQuery(parsedUuid),
+			schema: XMLItemLinksData,
+			label: "OCHRE item links",
+			options
 		});
-		if (!response.ok) throw new Error("Failed to fetch OCHRE item links", { cause: response.statusText });
-		const dataRaw = await response.text();
-		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
-		const { success, issues, output } = v.safeParse(XMLItemLinksData, data);
-		if (!success) throw createSchemaValidationError("Failed to parse OCHRE item links", issues);
-		restoreXMLMetadata(output, data);
-		const languages = resolveItemLinksLanguages(output, requestedLanguages);
+		const languages = resolveContentLanguages(output.result.ochre.items, requestedLanguages);
 		return {
 			items: parseLinkedItems(output.result.ochre.items, {
 				containedItemCategory: options?.containedItemCategory,

package/dist/fetchers/item-ocr-data.d.mts

@@ -1,4 +1,5 @@
 import { OcrString } from "../types/index.mjs";
+import { OchreRequestOptions } from "./request.mjs";
 //#region src/fetchers/item-ocr-data.d.ts
 /**
  * Fetches and parses the OCR strings of an OCHRE item that match a search value
@@ -23,10 +24,9 @@ import { OcrString } from "../types/index.mjs";
  * @returns The matching OCR strings, an empty array when the item has no OCR
  * layer or nothing matches, and a null output on fetch/parse errors
  */
-export declare function fetchItemOcrData(uuid: string, value: string, options?: {
+export declare function fetchItemOcrData(uuid: string, value: string, options?: OchreRequestOptions & {
   matchMode?: "includes" | "exact";
   isCaseSensitive?: boolean;
-  fetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
 }): Promise<{
   ocrStrings: Array<OcrString>;
   error: null;

package/dist/fetchers/item-ocr-data.mjs

@@ -1,8 +1,9 @@
-import { XML_PARSER_OPTIONS } from "../constants.mjs";
-import { createSchemaValidationError, getErrorOutput, stringLiteral } from "../utilities.mjs";
+import { getErrorOutput } from "../errors.mjs";
+import { requestOchre } from "./request.mjs";
 import { itemOcrDataParametersSchema } from "../schemas.mjs";
+import { stringLiteral } from "../xquery.mjs";
+import { buildOcrWordPath } from "../ocr.mjs";
 import * as v from "valibot";
-import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/item-ocr-data.ts
 const OCR_STRING_VERTEX_REGEX = /\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\)/g;
 /**
@@ -83,7 +84,7 @@ declare variable $terms := (${termValues.join(", ")});
 
 let $ochre := doc(${stringLiteral(uuid)})/ochre
 let $ocrStrings :=
-  for $string in $ochre//*[lower-case(local-name(.)) = "ocr"]//*[lower-case(local-name(.)) = "string"][@CONTENT]
+  for $string in ${buildOcrWordPath("$ochre")}
   where (some $term in $terms satisfies ${matchExpression})
   return <ocrString
     resourceUuid="{string($string/ancestor::*[local-name(.) = "resource"][1]/@uuid)}"
@@ -137,17 +138,12 @@ async function fetchItemOcrData(uuid, value, options) {
 			matchMode: parameters.matchMode,
 			isCaseSensitive: parameters.isCaseSensitive
 		});
-		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
-			method: "POST",
-			body: xquery,
-			headers: { "Content-Type": "application/xquery" }
-		});
-		if (!response.ok) throw new Error(`OCHRE API responded with status: ${response.status}`, { cause: response.statusText });
-		const dataRaw = await response.text();
-		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
-		const { success, issues, output } = v.safeParse(responseSchema, data);
-		if (!success) throw createSchemaValidationError("Failed to parse OCHRE item OCR data", issues);
-		const { found, ocrString } = output.result.ochre.ocrStrings;
+		const { found, ocrString } = (await requestOchre({
+			xquery,
+			schema: responseSchema,
+			label: "OCHRE item OCR data",
+			options
+		})).result.ochre.ocrStrings;
 		if (found !== "true") throw new Error(`No OCHRE item found for UUID: ${parameters.uuid}`, { cause: parameters.uuid });
 		const parsedOcrStrings = ocrString == null ? [] : Array.isArray(ocrString) ? ocrString : [ocrString];
 		return {

package/dist/fetchers/item.d.mts

@@ -10,21 +10,6 @@ type FetchItemResult<TItem> = Promise<{
   error: string;
   detailedError: string;
 }>;
-/**
- * Defines a reusable languages tuple with validation and literal type inference.
- *
- * Inline arrays can be passed directly to fetchItem:
- * `fetchItem(uuid, { languages: ["eng", "spa"] })`.
- *
- * Use this helper when the language set is stored separately:
- * `const languages = defineLanguages("eng", "spa")`.
- */
-export declare function defineLanguages<const TLanguages extends ReadonlyArray<string>>(...languages: TLanguages): TLanguages;
-/**
- * @deprecated Pass inline language arrays directly to fetchItem, or use
- * defineLanguages("eng", "spa") for reusable language tuples.
- */
-export declare function withLanguages<const TLanguages extends ReadonlyArray<string>>(languages: TLanguages): TLanguages;
 /**
  * Fetches an OCHRE item by UUID from the OCHRE API
  *