ochre-sdk 1.0.71 → 1.0.73

package/dist/xml/schemas.mjs

@@ -42,19 +42,23 @@ const ITEM_CATEGORIES = [
 	"set"
 ];
 const XMLItemCategory = v.picklist(ITEM_CATEGORIES);
+const XMLRichTextEnvelope = {
+	links: v.optional(v.lazy(() => XMLLink)),
+	properties: v.optional(v.object({ property: v.array(v.lazy(() => XMLProperty), "XMLRichTextEnvelope: properties is array of XMLProperty") })),
+	annotation: v.optional(v.string("XMLRichTextEnvelope: annotation is string and optional"))
+};
 const XMLString = v.lazy(() => v.object({
 	payload: v.optional(v.string("XMLString: payload is string and optional")),
 	rend: v.optional(v.string("XMLString: rend is string and optional")),
 	whitespace: v.optional(v.string("XMLString: whitespace is string and optional")),
-	links: v.optional(v.lazy(() => XMLLink)),
-	properties: v.optional(v.object({ property: v.array(v.lazy(() => XMLProperty), "XMLString: properties is array of XMLProperty") })),
-	annotation: v.optional(v.string("XMLString: annotation is string and optional")),
+	...XMLRichTextEnvelope,
 	string: v.optional(v.array(XMLString, "XMLString: string is array of XMLString"))
 }, "XMLString: Shape error"));
 const XMLContent = v.object({ content: v.array(v.object({
 	string: v.array(XMLString),
 	title: v.optional(v.string("XMLContent: title is string and optional")),
-	lang: v.string("XMLContent: lang is string and required")
+	lang: v.string("XMLContent: lang is string and required"),
+	...XMLRichTextEnvelope
 }), "XMLContent: content is array of object with string, title, and lang") }, "XMLContent: Shape error");
 const XMLNumber = v.pipe(v.union([v.string("XMLNumber: string is string and required"), XMLString]), v.check(isXMLNumber, "XMLNumber: string is not a number"), v.transform(parseXMLNumber));
 const XMLOptionalNumber = v.optional(v.pipe(v.union([v.string("XMLNumber: string is string and required"), XMLString]), v.check(isOptionalXMLNumber, "XMLNumber: string is not a number"), v.transform(parseOptionalXMLNumber)));
@@ -220,42 +224,6 @@ const XMLImageMap = v.object({
 	width: XMLNumber,
 	height: XMLNumber
 }, "XMLImageMap: Shape error");
-const XMLOcrString = v.object({
-	HPOS: XMLNumber,
-	VPOS: XMLNumber,
-	WIDTH: XMLNumber,
-	HEIGHT: XMLNumber,
-	CONTENT: v.string("XMLOcrString: CONTENT is string and required"),
-	VERTICES: v.optional(v.string("XMLOcrString: VERTICES is string and optional"))
-}, "XMLOcrString: Shape error");
-const XMLOcrTextLine = v.object({ string: v.optional(v.array(XMLOcrString, "XMLOcrTextLine: string is array of XMLOcrString")) }, "XMLOcrTextLine: Shape error");
-const XMLOcrTextBlock = v.object({ TextLine: v.optional(v.array(XMLOcrTextLine, "XMLOcrTextBlock: TextLine is array of XMLOcrTextLine")) }, "XMLOcrTextBlock: Shape error");
-const XMLOcrPage = v.object({
-	n: XMLOptionalNumber,
-	fileName: v.optional(v.string("XMLOcrPage: fileName is string and optional")),
-	WIDTH: XMLOptionalNumber,
-	HEIGHT: XMLOptionalNumber,
-	TextBlock: v.optional(v.array(XMLOcrTextBlock, "XMLOcrPage: TextBlock is array of XMLOcrTextBlock"))
-}, "XMLOcrPage: Shape error");
-const XMLOcr = v.object({ Page: v.optional(v.array(XMLOcrPage, "XMLOcr: Page is array of XMLOcrPage")) }, "XMLOcr: Shape error");
-const XMLOcrMatch = v.object({
-	resourceUuid: v.optional(v.string("XMLOcrMatch: resourceUuid is string and optional")),
-	n: XMLOptionalNumber,
-	fileName: v.optional(v.string("XMLOcrMatch: fileName is string and optional")),
-	WIDTH: XMLOptionalNumber,
-	HEIGHT: XMLOptionalNumber,
-	string: v.optional(v.array(XMLOcrString, "XMLOcrMatch: string is array of XMLOcrString"))
-}, "XMLOcrMatch: Shape error");
-const XMLOcrMatchItem = v.object({
-	uuid: v.pipe(v.string("XMLOcrMatchItem: uuid is string and required"), v.check(isPseudoUuid, "XMLOcrMatchItem: uuid is not a valid pseudo-UUID")),
-	matchCount: XMLNumber,
-	ocrMatch: v.optional(v.array(XMLOcrMatch, "XMLOcrMatchItem: ocrMatch is array of XMLOcrMatch"))
-}, "XMLOcrMatchItem: Shape error");
-/**
-* Schema for validating OCR matches fetched from the OCHRE API
-* @internal
-*/
-const XMLOcrMatchesData = v.object({ result: v.object({ ochre: v.object({ ocrMatches: v.optional(v.object({ ocrItem: v.optional(v.array(XMLOcrMatchItem, "XMLOcrMatchesData: ocrItem is array of XMLOcrMatchItem")) })) }) }) }, "XMLOcrMatchesData: Shape error");
 const XMLNote = v.object({
 	content: v.optional(XMLContent.entries.content),
 	payload: v.optional(v.string("XMLNote: payload is string and optional")),
@@ -676,7 +644,6 @@ const XMLResource = v.object({
 	width: XMLOptionalNumber,
 	image: v.optional(XMLImage),
 	imagemap: v.optional(XMLImageMap),
-	ocr: v.optional(XMLOcr),
 	document: v.optional(XMLContent),
 	coordinates: v.optional(XMLCoordinates),
 	periods: v.optional(v.object({ period: v.array(XMLPeriod) })),
@@ -828,7 +795,6 @@ const XMLWebsiteResource = v.lazy(() => v.object({
 	width: XMLOptionalNumber,
 	image: v.optional(XMLImage),
 	imagemap: v.optional(XMLImageMap),
-	ocr: v.optional(XMLOcr),
 	document: v.optional(XMLContent),
 	coordinates: v.optional(XMLCoordinates),
 	periods: v.optional(v.object({ period: v.array(XMLPeriod) })),
@@ -962,4 +928,4 @@ const XMLWebsiteData = v.object({ result: v.object({ ochre: v.object({
 	tree: v.array(XMLWebsiteTree)
 }, "XMLWebsiteData: ochre is object with website tree") }, "XMLWebsiteData: result is object with ochre") }, "XMLWebsiteData: Shape error");
 //#endregion
-export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLOcrMatchesData, XMLSetItemsData, XMLWebsiteData };
+export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLSetItemsData, XMLWebsiteData };

package/dist/xml/types.d.mts

@@ -2,19 +2,26 @@
 type XMLItemCategory = "tree" | "bibliography" | "spatialUnit" | "concept" | "period" | "person" | "propertyVariable" | "variable" | "propertyValue" | "value" | "text" | "resource" | "set";
 type XMLHeadingItemCategory = Exclude<XMLItemCategory, "tree" | "bibliography" | "spatialUnit" | "concept" | "period">;
 type XMLRecursiveItemCategory = Exclude<XMLItemCategory, "tree" | "person" | "propertyVariable" | "propertyValue" | "set">;
-type XMLString = {
-  payload?: string;
-  rend?: string;
-  whitespace?: string;
+/**
+ * Rich text envelope shared by `<string>` and `<content>` nodes, carrying the
+ * inline links, presentation properties and annotation identifier that turn a
+ * span of text into an annotation.
+ */
+type XMLRichTextEnvelope = {
   links?: XMLLink;
   properties?: {
     property: Array<XMLProperty>;
   };
   annotation?: string;
+};
+type XMLString = XMLRichTextEnvelope & {
+  payload?: string;
+  rend?: string;
+  whitespace?: string;
   string?: Array<XMLString>;
 };
 type XMLContent = {
-  content: Array<{
+  content: Array<XMLRichTextEnvelope & {
     string: Array<XMLString>;
     lang: string;
     title?: string;
@@ -175,48 +182,6 @@ type XMLImageMap = {
   width: XMLNumber;
   height: XMLNumber;
 };
-type XMLOcrString = {
-  HPOS: XMLNumber;
-  VPOS: XMLNumber;
-  WIDTH: XMLNumber;
-  HEIGHT: XMLNumber;
-  CONTENT: string;
-  VERTICES?: string;
-};
-type XMLOcrTextLine = {
-  string?: Array<XMLOcrString>;
-};
-type XMLOcrTextBlock = {
-  TextLine?: Array<XMLOcrTextLine>;
-};
-type XMLOcrPage = {
-  n?: XMLNumber;
-  fileName?: string;
-  WIDTH?: XMLNumber;
-  HEIGHT?: XMLNumber;
-  TextBlock?: Array<XMLOcrTextBlock>;
-};
-type XMLOcr = {
-  Page?: Array<XMLOcrPage>;
-};
-type XMLOcrMatch = Omit<XMLOcrPage, "TextBlock"> & {
-  resourceUuid?: string;
-  string?: Array<XMLOcrString>;
-};
-type XMLOcrMatchItem = {
-  uuid: string;
-  matchCount: XMLNumber;
-  ocrMatch?: Array<XMLOcrMatch>;
-};
-type XMLOcrMatchesData = {
-  result: {
-    ochre: {
-      ocrMatches?: {
-        ocrItem?: Array<XMLOcrMatchItem>;
-      };
-    };
-  };
-};
 type XMLNote = Partial<XMLContent> & XMLString & {
   noteNo?: XMLNumber;
   title?: string;
@@ -598,7 +563,6 @@ type XMLResource = XMLBaseItem & {
   width?: XMLNumber;
   image?: XMLImage;
   imagemap?: XMLImageMap;
-  ocr?: XMLOcr;
   document?: XMLContent;
   coordinates?: XMLCoordinates;
   periods?: {
@@ -956,4 +920,4 @@ type XMLWebsiteData = {
   };
 };
 //#endregion
-export { XMLBaseItem, XMLBibliography, XMLBoolean, XMLConcept, XMLContent, XMLContext, XMLContextGroup, XMLContextItem, XMLContextValue, XMLCoordinate, XMLCoordinates, XMLCoordinatesSource, XMLData, XMLDataItem, XMLDictionaryUnit, XMLEmptyContext, XMLEvent, XMLGallery, XMLGalleryData, XMLHeading, XMLHeadingItemCategory, XMLIdentification, XMLImage, XMLImageMap, XMLImageMapArea, XMLInterpretation, XMLItemCategory, XMLItemLinks, XMLItemLinksData, XMLLicense, XMLLink, XMLLinkedBaseItem, XMLLinkedBibliography, XMLLinkedConcept, XMLLinkedPeriod, XMLLinkedPerson, XMLLinkedPropertyValue, XMLLinkedPropertyVariable, XMLLinkedResource, XMLLinkedSet, XMLLinkedSpatialUnit, XMLLinkedText, XMLLinkedTree, XMLMetadata, XMLNote, XMLNumber, XMLObservation, XMLOcr, XMLOcrMatch, XMLOcrMatchItem, XMLOcrMatchesData, XMLOcrPage, XMLOcrString, XMLOcrTextBlock, XMLOcrTextLine, XMLPeriod, XMLPerson, XMLProperty, XMLPropertyRelation, XMLPropertyValue, XMLPropertyVariable, XMLRecursiveItemCategory, XMLResource, XMLSection, XMLSet, XMLSetItems, XMLSetItemsData, XMLSimplifiedProperty, XMLSpatialUnit, XMLString, XMLText, XMLTree, XMLWebsiteContext, XMLWebsiteContextItem, XMLWebsiteContextLevel, XMLWebsiteData, XMLWebsiteFilterContext, XMLWebsiteFilterContextItem, XMLWebsiteOptions, XMLWebsiteProperties, XMLWebsiteResource, XMLWebsiteResourceGroup, XMLWebsiteResourceItem, XMLWebsiteScope, XMLWebsiteSegment, XMLWebsiteStyle, XMLWebsiteTree };
+export { XMLBaseItem, XMLBibliography, XMLBoolean, XMLConcept, XMLContent, XMLContext, XMLContextGroup, XMLContextItem, XMLContextValue, XMLCoordinate, XMLCoordinates, XMLCoordinatesSource, XMLData, XMLDataItem, XMLDictionaryUnit, XMLEmptyContext, XMLEvent, XMLGallery, XMLGalleryData, XMLHeading, XMLHeadingItemCategory, XMLIdentification, XMLImage, XMLImageMap, XMLImageMapArea, XMLInterpretation, XMLItemCategory, XMLItemLinks, XMLItemLinksData, XMLLicense, XMLLink, XMLLinkedBaseItem, XMLLinkedBibliography, XMLLinkedConcept, XMLLinkedPeriod, XMLLinkedPerson, XMLLinkedPropertyValue, XMLLinkedPropertyVariable, XMLLinkedResource, XMLLinkedSet, XMLLinkedSpatialUnit, XMLLinkedText, XMLLinkedTree, XMLMetadata, XMLNote, XMLNumber, XMLObservation, XMLPeriod, XMLPerson, XMLProperty, XMLPropertyRelation, XMLPropertyValue, XMLPropertyVariable, XMLRecursiveItemCategory, XMLResource, XMLRichTextEnvelope, XMLSection, XMLSet, XMLSetItems, XMLSetItemsData, XMLSimplifiedProperty, XMLSpatialUnit, XMLString, XMLText, XMLTree, XMLWebsiteContext, XMLWebsiteContextItem, XMLWebsiteContextLevel, XMLWebsiteData, XMLWebsiteFilterContext, XMLWebsiteFilterContextItem, XMLWebsiteOptions, XMLWebsiteProperties, XMLWebsiteResource, XMLWebsiteResourceGroup, XMLWebsiteResourceItem, XMLWebsiteScope, XMLWebsiteSegment, XMLWebsiteStyle, XMLWebsiteTree };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.0.71",
+  "version": "1.0.73",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -53,10 +53,10 @@
   "devDependencies": {
     "@antfu/eslint-config": "^9.2.0",
     "@types/node": "^24.13.3",
-    "bumpp": "^12.1.1",
+    "bumpp": "^12.2.0",
     "eslint": "^10.8.0",
     "knip": "^6.31.0",
-    "oxfmt": "^0.61.0",
+    "oxfmt": "^0.62.0",
     "tsdown": "^0.22.14",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"

package/dist/fetchers/ocr-matches.d.mts

@@ -1,44 +0,0 @@
-import { OcrMatch } from "../types/index.mjs";
-import { FetchFunction } from "../parsers/helpers.mjs";
-//#region src/fetchers/ocr-matches.d.ts
-/**
- * Fetches the locations of OCR text matches within OCHRE resources
- *
- * Matching mirrors the `ocr` Set item query target, so the same value and match
- * mode that selected an item will locate its hits. `matchCountsByUuid` reports
- * the untruncated count, which can exceed the returned matches when
- * `maxMatchesPerItem` caps them.
- *
- * @param parameters - The parameters for the fetch
- * @param parameters.uuids - The resource UUIDs to search, typically from a filtered Set item fetch
- * @param parameters.value - The search value
- * @param parameters.matchMode - Whether to match loosely (stemming and wildcards) or on whole OCR words, defaults to "includes"
- * @param parameters.isCaseSensitive - Whether matching is case sensitive, defaults to false
- * @param parameters.maxMatchesPerItem - The cap on returned matches per requested UUID, defaults to 50
- * @param options - Options for the fetch
- * @param options.fetch - The fetch function to use
- * @returns The OCR matches, or null if the fetch/parse fails
- */
-declare function fetchOcrMatches(parameters: {
-  uuids: Array<string>;
-  value: string;
-  matchMode?: "includes" | "exact";
-  isCaseSensitive?: boolean;
-  maxMatchesPerItem?: number;
-}, options?: {
-  fetch?: FetchFunction;
-}): Promise<{
-  matches: Array<OcrMatch>;
-  matchesByUuid: Record<string, Array<OcrMatch>>;
-  matchCountsByUuid: Record<string, number>;
-  error: null;
-  detailedError: null;
-} | {
-  matches: null;
-  matchesByUuid: null;
-  matchCountsByUuid: null;
-  error: string;
-  detailedError: string;
-}>;
-//#endregion
-export { fetchOcrMatches };

package/dist/fetchers/ocr-matches.mjs

@@ -1,134 +0,0 @@
-import { XML_PARSER_OPTIONS } from "../constants.mjs";
-import { createSchemaValidationError, getErrorOutput, stringLiteral } from "../utilities.mjs";
-import { buildOcrTermQueryExpressions } from "../query.mjs";
-import { ocrMatchesParametersSchema } from "../schemas.mjs";
-import { restoreXMLMetadata } from "../xml/metadata.mjs";
-import { parseOcrMatches } from "../parsers/index.mjs";
-import { XMLOcrMatchesData } from "../xml/schemas.mjs";
-import * as v from "valibot";
-import { XMLParser } from "fast-xml-parser";
-//#region src/fetchers/ocr-matches.ts
-/**
-* Build an XQuery string to fetch OCR match locations from the OCHRE API
-*
-* Each OCR word is matched with `cts:contains` against the same per-term CTS
-* queries the Set item filter compiles, so hit locations always agree with what
-* the filter matched — including stemming and wildcards, which cannot be
-* reproduced outside MarkLogic.
-*
-* @param parameters - The parameters for the fetch
-* @param parameters.uuids - The resource UUIDs to search
-* @param parameters.termQueryExpressions - One CTS query expression per search term, in word order
-* @param parameters.maxMatchesPerItem - The cap on returned matches per requested UUID
-* @returns An XQuery string
-*/
-function buildXQuery(parameters) {
-	const { uuids, termQueryExpressions, maxMatchesPerItem } = parameters;
-	return `xquery version "1.0-ml";
-
-declare variable $uuids := (${Array.from(uuids, (uuid) => stringLiteral(uuid)).join(", ")});
-
-declare variable $termQueries := (
-  ${termQueryExpressions.join(",\n  ")}
-);
-
-declare variable $termCount := ${termQueryExpressions.length};
-
-<ochre>{
-  <ocrMatches>{
-    for $uuid in $uuids
-    let $matches :=
-      for $page in doc($uuid)//ocr/Page
-      let $words := $page//TextLine/string
-      let $wordCount := count($words)
-      let $resourceUuid := string($page/ancestor::resource[1]/@uuid)
-      for $word at $index in $words
-      where $index + $termCount - 1 le $wordCount
-        and (every $offset in (1 to $termCount)
-             satisfies cts:contains($words[$index + $offset - 1], $termQueries[$offset]))
-      return <ocrMatch resourceUuid="{$resourceUuid}">{
-        $page/@n, $page/@fileName, $page/@WIDTH, $page/@HEIGHT,
-        subsequence($words, $index, $termCount)
-      }</ocrMatch>
-    return <ocrItem uuid="{$uuid}" matchCount="{count($matches)}">{
-      subsequence($matches, 1, ${maxMatchesPerItem})
-    }</ocrItem>
-  }</ocrMatches>
-}</ochre>`;
-}
-/**
-* Fetches the locations of OCR text matches within OCHRE resources
-*
-* Matching mirrors the `ocr` Set item query target, so the same value and match
-* mode that selected an item will locate its hits. `matchCountsByUuid` reports
-* the untruncated count, which can exceed the returned matches when
-* `maxMatchesPerItem` caps them.
-*
-* @param parameters - The parameters for the fetch
-* @param parameters.uuids - The resource UUIDs to search, typically from a filtered Set item fetch
-* @param parameters.value - The search value
-* @param parameters.matchMode - Whether to match loosely (stemming and wildcards) or on whole OCR words, defaults to "includes"
-* @param parameters.isCaseSensitive - Whether matching is case sensitive, defaults to false
-* @param parameters.maxMatchesPerItem - The cap on returned matches per requested UUID, defaults to 50
-* @param options - Options for the fetch
-* @param options.fetch - The fetch function to use
-* @returns The OCR matches, or null if the fetch/parse fails
-*/
-async function fetchOcrMatches(parameters, options) {
-	try {
-		const { uuids, value, matchMode, isCaseSensitive, maxMatchesPerItem } = v.parse(ocrMatchesParametersSchema, parameters);
-		const termQueryExpressions = buildOcrTermQueryExpressions({
-			value,
-			matchMode,
-			isCaseSensitive
-		});
-		if (termQueryExpressions.length === 0) return {
-			matches: [],
-			matchesByUuid: {},
-			matchCountsByUuid: {},
-			error: null,
-			detailedError: null
-		};
-		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
-			method: "POST",
-			body: buildXQuery({
-				uuids,
-				termQueryExpressions,
-				maxMatchesPerItem
-			}),
-			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(XMLOcrMatchesData, data);
-		if (!success) throw createSchemaValidationError("Failed to parse OCHRE OCR matches", issues);
-		restoreXMLMetadata(output, data);
-		const rawOcrItems = output.result.ochre.ocrMatches?.ocrItem ?? [];
-		const matches = parseOcrMatches(rawOcrItems);
-		const matchesByUuid = {};
-		const matchCountsByUuid = {};
-		for (const uuid of uuids) {
-			matchesByUuid[uuid] = [];
-			matchCountsByUuid[uuid] = 0;
-		}
-		for (const rawOcrItem of rawOcrItems) matchCountsByUuid[rawOcrItem.uuid] = rawOcrItem.matchCount;
-		for (const match of matches) matchesByUuid[match.uuid]?.push(match);
-		return {
-			matches,
-			matchesByUuid,
-			matchCountsByUuid,
-			error: null,
-			detailedError: null
-		};
-	} catch (error) {
-		return {
-			matches: null,
-			matchesByUuid: null,
-			matchCountsByUuid: null,
-			...getErrorOutput(error, "Unknown error")
-		};
-	}
-}
-//#endregion
-export { fetchOcrMatches };