ochre-sdk 1.0.72 → 1.0.73

package/dist/schemas.d.mts

@@ -38,7 +38,7 @@ declare const renderOptionsSchema: v.SchemaWithPipe<readonly [v.StringSchema<und
 declare const setPropertyValuesParametersSchema: v.ObjectSchema<{
   readonly setScopeUuids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, v.MinLengthAction<string[], 1, "At least one set scope UUID is required">]>;
   readonly belongsToCollectionScopeUuids: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, readonly []>;
-  readonly queries: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.GenericSchema<unknown, Query>, v.CheckAction<Query, "OCR queries cannot be nested inside an OR group because they are resolved by a document join instead of a CTS query">]>, undefined>, null>;
+  readonly queries: v.OptionalSchema<v.NullableSchema<v.GenericSchema<unknown, Query>, undefined>, null>;
   readonly attributes: v.OptionalSchema<v.ObjectSchema<{
     readonly bibliographies: v.GenericSchema<unknown, boolean>;
     readonly periods: v.GenericSchema<unknown, boolean>;
@@ -49,15 +49,14 @@ declare const setPropertyValuesParametersSchema: v.ObjectSchema<{
   readonly isLimitedToLeafPropertyValues: v.GenericSchema<unknown, boolean>;
 }, undefined>;
 /**
- * Schema for validating OCR matches parameters
+ * Schema for validating the parameters for the item OCR data fetching function
  * @internal
  */
-declare const ocrMatchesParametersSchema: v.ObjectSchema<{
-  readonly uuids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, v.MinLengthAction<string[], 1, "At least one UUID is required">]>;
-  readonly value: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "A search value is required">]>;
+declare const itemOcrDataParametersSchema: v.ObjectSchema<{
+  readonly uuid: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>;
+  readonly value: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "A search value is required">]>;
   readonly matchMode: v.OptionalSchema<v.PicklistSchema<["includes", "exact"], undefined>, "includes">;
   readonly isCaseSensitive: v.GenericSchema<unknown, boolean>;
-  readonly maxMatchesPerItem: v.OptionalSchema<v.GenericSchema<unknown, number>, 50>;
 }, undefined>;
 /**
  * Schema for validating Set items parameters
@@ -66,7 +65,7 @@ declare const ocrMatchesParametersSchema: v.ObjectSchema<{
 declare const setItemsParametersSchema: v.ObjectSchema<{
   readonly setScopeUuids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, v.MinLengthAction<string[], 1, "At least one set scope UUID is required">]>;
   readonly belongsToCollectionScopeUuids: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, readonly []>;
-  readonly queries: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.GenericSchema<unknown, Query>, v.CheckAction<Query, "OCR queries cannot be nested inside an OR group because they are resolved by a document join instead of a CTS query">]>, undefined>, null>;
+  readonly queries: v.OptionalSchema<v.NullableSchema<v.GenericSchema<unknown, Query>, undefined>, null>;
   readonly sort: v.OptionalSchema<v.VariantSchema<"target", [v.StrictObjectSchema<{
     readonly target: v.LiteralSchema<"none", undefined>;
   }, undefined>, v.StrictObjectSchema<{
@@ -86,4 +85,4 @@ declare const setItemsParametersSchema: v.ObjectSchema<{
   readonly pageSize: v.OptionalSchema<v.GenericSchema<unknown, number>, 48>;
 }, undefined>;
 //#endregion
-export { componentSchema, gallerySchema, iso639_3Schema, ocrMatchesParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };
+export { componentSchema, gallerySchema, iso639_3Schema, itemOcrDataParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };

package/dist/schemas.mjs

@@ -1,6 +1,5 @@
 import { isPseudoUuid } from "./utilities.mjs";
 import "./helpers.mjs";
-import { OCR_DISJUNCTION_ERROR_MESSAGE, hasOcrQueryInDisjunction } from "./query.mjs";
 import * as v from "valibot";
 //#region src/schemas.ts
 const positiveNumber = (message) => v.pipe(v.number(), v.minValue(1, message));
@@ -143,7 +142,7 @@ const setQueryLeafSchema = v.union([
 		...standardQueryFields
 	}),
 	v.strictObject({
-		target: v.literal("ocr"),
+		target: v.literal("ocrText"),
 		value: v.string(),
 		matchMode: standardQueryFields.matchMode,
 		isCaseSensitive: standardQueryFields.isCaseSensitive,
@@ -175,7 +174,7 @@ const setQuerySchema = v.lazy(() => v.union([
 * Schema for validating Set queries
 * @internal
 */
-const setQueriesSchema = v.optional(v.nullable(v.pipe(setQuerySchema, v.check((query) => !hasOcrQueryInDisjunction(query), OCR_DISJUNCTION_ERROR_MESSAGE))), null);
+const setQueriesSchema = v.optional(v.nullable(setQuerySchema), null);
 /**
 * Schema for validating Set items sort
 * @internal
@@ -222,15 +221,14 @@ const setPropertyValuesParametersSchema = v.object({
 	isLimitedToLeafPropertyValues: defaultBoolean(false)
 });
 /**
-* Schema for validating OCR matches parameters
+* Schema for validating the parameters for the item OCR data fetching function
 * @internal
 */
-const ocrMatchesParametersSchema = v.object({
-	uuids: v.pipe(v.array(uuidSchema), v.minLength(1, "At least one UUID is required")),
-	value: v.pipe(v.string(), v.minLength(1, "A search value is required")),
+const itemOcrDataParametersSchema = v.object({
+	uuid: uuidSchema,
+	value: v.pipe(v.string(), v.check((value) => value.trim() !== "", "A search value is required")),
 	matchMode: v.optional(v.picklist(["includes", "exact"]), "includes"),
-	isCaseSensitive: defaultBoolean(false),
-	maxMatchesPerItem: v.optional(positiveNumber("Max matches per item must be positive"), 50)
+	isCaseSensitive: defaultBoolean(false)
 });
 /**
 * Schema for validating Set items parameters
@@ -245,4 +243,4 @@ const setItemsParametersSchema = v.object({
 	pageSize: v.optional(positiveNumber("Page size must be positive"), 48)
 });
 //#endregion
-export { componentSchema, gallerySchema, iso639_3Schema, ocrMatchesParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };
+export { componentSchema, gallerySchema, iso639_3Schema, itemOcrDataParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };

package/dist/types/index.d.mts

@@ -263,58 +263,29 @@ type ImageMap = {
   height: number;
 };
 /**
- *  Vertex of an OCR word's bounding polygon in OCHRE
- */
-type OcrPoint = {
-  x: number;
-  y: number;
-};
-/**
- *  Word recognized within an OCR text line in OCHRE
- */
-type OcrWord = {
-  content: string;
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-  vertices: Array<OcrPoint>;
-};
-/**
- *  Text line of an OCR text block in OCHRE
- */
-type OcrTextLine = {
-  content: string;
-  words: Array<OcrWord>;
-};
-/**
- *  Text block of an OCR page in OCHRE
- */
-type OcrTextBlock = {
-  lines: Array<OcrTextLine>;
-};
-/**
- *  OCR page of a resource in OCHRE
- */
-type OcrPage = {
-  number: number | null;
-  fileName: string | null;
-  width: number | null;
-  height: number | null;
-  blocks: Array<OcrTextBlock>;
-};
-/**
- *  A run of adjacent OCR words matching a search value in OCHRE
+ *  Positioned OCR string in OCHRE
+ *
+ *  OCHRE gives no guarantee about the node hierarchy inside a Resource's
+ *  `<ocr>` layer, so only `<string>` nodes are parsed, at whatever depth they
+ *  occur. `x` and `y` come from `HPOS` and `VPOS` and locate the top-left
+ *  corner of the string's box, while `vertices` is its full bounding polygon,
+ *  which is not necessarily rectangular. Every geometry attribute is optional
+ *  in the source, so each one is null when absent or unparseable.
  *
- *  `uuid` is the requested resource, while `resourceUuid` is the resource that
- *  owns the OCR page — they differ when the OCR lives on a child page resource.
+ *  `resourceUuid` is the Resource that owns the OCR layer, which differs from
+ *  the requested item when the OCR lives on a child Resource.
  */
-type OcrMatch = {
-  uuid: string;
+type OcrString = {
   resourceUuid: string | null;
-  page: Omit<OcrPage, "blocks">;
   content: string;
-  words: Array<OcrWord>;
+  x: number | null;
+  y: number | null;
+  width: number | null;
+  height: number | null;
+  vertices: Array<{
+    x: number;
+    y: number;
+  }>;
 };
 /**
  *  Note in OCHRE
@@ -734,7 +705,6 @@ type Resource<T extends LanguageCodes = LanguageCodes, U extends ItemPayloadKind
   image: Image<T> | null;
   document: MultilingualString<T> | null;
   imageMap: ImageMap | null;
-  ocr: Array<OcrPage>;
   coordinates: Array<Coordinates<T>>;
   periods: Array<Period<T, "embedded">>;
   links: ItemLinks<T>;
@@ -845,12 +815,12 @@ type SetItemsSort = {
 /**
  * Represents a leaf query for Set items
  *
- * The `ocr` target matches the OCR text layer of resources. Because OCR is not
- * carried by Set item projections, it is resolved by a document join rather
- * than a CTS term, which means `ocr` leaves compose with `and` and `isNegated`
- * but cannot be nested inside an `or` group. Both match modes are adjacency
- * based: `includes` allows stemming and wildcards, `exact` requires whole OCR
- * words. OCR carries no language, so `ocr` leaves take no `language`.
+ * The `ocrText` target matches the OCR text layer of Resource items. Because
+ * Set item projections do not carry `<ocrText>`, it is resolved by a document
+ * join rather than a CTS term, so it composes with `and`, `or`, and `isNegated`
+ * at the cost of one extra search branch per distinct OCR text value in a
+ * disjunction. OCR text carries no language, so `ocrText` leaves take no
+ * `language`.
  */
 type QueryLeaf = {
   target: "property";
@@ -918,7 +888,7 @@ type QueryLeaf = {
   language: string;
   isNegated?: boolean;
 } | {
-  target: "ocr";
+  target: "ocrText";
   value: string;
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
@@ -944,4 +914,4 @@ type QueryGroup = {
  */
 type Query = QueryLeaf | QueryGroup;
 //#endregion
-export { AnyBibliography, AnyConcept, AnyItem, AnyPeriod, AnyPerson, AnyPropertyValue, AnyPropertyVariable, AnyResource, AnySet, AnySpatialUnit, AnyText, AnyTree, BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, Coordinates, CoordinatesSource, DictionaryUnitItemLink, EmbeddedBibliography, EmbeddedConcept, EmbeddedItem, EmbeddedPeriod, EmbeddedPerson, EmbeddedPropertyValue, EmbeddedPropertyVariable, EmbeddedResource, EmbeddedSet, EmbeddedSpatialUnit, EmbeddedText, EmbeddedTree, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemCategoryWithEmbeddedItems, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, ItemProperty, ItemWithoutEmbeddedItems, LanguageCodes, License, Metadata, Note, Observation, OcrMatch, OcrPage, OcrPoint, OcrTextBlock, OcrTextLine, OcrWord, Period, PeriodItemLink, Person, PersonItemLink, Prettify, Property, PropertyLike, PropertyRelation, PropertyValue, PropertyValueContent, PropertyValueDataType, PropertyValueItemLink, PropertyValueQueryItem, PropertyVariable, PropertyVariableItemLink, Query, QueryGroup, QueryLeaf, QueryablePropertyValueDataType, RecursiveItemCategory, Resource, ResourceItemLink, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Text, TextItemLink, TopLevelItem, Tree, TreeItemCategory, TreeItemLink };
+export { AnyBibliography, AnyConcept, AnyItem, AnyPeriod, AnyPerson, AnyPropertyValue, AnyPropertyVariable, AnyResource, AnySet, AnySpatialUnit, AnyText, AnyTree, BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, Coordinates, CoordinatesSource, DictionaryUnitItemLink, EmbeddedBibliography, EmbeddedConcept, EmbeddedItem, EmbeddedPeriod, EmbeddedPerson, EmbeddedPropertyValue, EmbeddedPropertyVariable, EmbeddedResource, EmbeddedSet, EmbeddedSpatialUnit, EmbeddedText, EmbeddedTree, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemCategoryWithEmbeddedItems, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, ItemProperty, ItemWithoutEmbeddedItems, LanguageCodes, License, Metadata, Note, Observation, OcrString, Period, PeriodItemLink, Person, PersonItemLink, Prettify, Property, PropertyLike, PropertyRelation, PropertyValue, PropertyValueContent, PropertyValueDataType, PropertyValueItemLink, PropertyValueQueryItem, PropertyVariable, PropertyVariableItemLink, Query, QueryGroup, QueryLeaf, QueryablePropertyValueDataType, RecursiveItemCategory, Resource, ResourceItemLink, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Text, TextItemLink, TopLevelItem, Tree, TreeItemCategory, TreeItemLink };

package/dist/utilities.d.mts

@@ -20,6 +20,30 @@ declare function isPseudoUuid(value: string): boolean;
  * @returns The escaped string literal
  */
 declare function stringLiteral(value: string): string;
+/**
+ * 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}.
+ */
+declare const SUPPLEMENTAL_XQUERY_PROLOG = "declare function local:omit-supplemental($nodes as node()*) as node()* {\n  for $node in $nodes\n  return\n    if ($node instance of element())\n    then\n      if ($node/@supplemental = \"true\")\n      then ()\n      else if (empty($node//@supplemental[. = \"true\"]))\n      then $node\n      else element { node-name($node) } {\n        $node/@*,\n        local:omit-supplemental($node/node())\n      }\n    else $node\n};";
+/**
+ * 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
+ */
+declare function omitSupplemental(expression: string): string;
+/**
+ * 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.
+ */
+declare const NOT_SUPPLEMENTAL_PREDICATE = "[not(ancestor-or-self::*[@supplemental = \"true\"])]";
 /**
  * Flatten a properties array
  * @param properties - The properties to flatten
@@ -28,4 +52,4 @@ declare function stringLiteral(value: string): string;
  */
 declare function flattenProperties<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T> | SetItemProperty<T>>): Array<SetItemProperty<T>>;
 //#endregion
-export { createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, stringLiteral };
+export { NOT_SUPPLEMENTAL_PREDICATE, SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, omitSupplemental, stringLiteral };

package/dist/utilities.mjs

@@ -151,6 +151,46 @@ 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
@@ -169,4 +209,4 @@ function flattenProperties(properties) {
 	return result;
 }
 //#endregion
-export { createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, stringLiteral };
+export { NOT_SUPPLEMENTAL_PREDICATE, SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, flattenProperties, getErrorOutput, isPseudoUuid, omitSupplemental, stringLiteral };

package/dist/xml/schemas.d.mts

@@ -1,11 +1,6 @@
-import { XMLData as XMLData$1, XMLDataItem as XMLDataItem$1, XMLGalleryData as XMLGalleryData$1, XMLItemLinksData as XMLItemLinksData$1, XMLLink as XMLLink$1, XMLOcrMatchesData as XMLOcrMatchesData$1, XMLSetItemsData as XMLSetItemsData$1, XMLWebsiteData as XMLWebsiteData$1 } from "./types.mjs";
+import { XMLData as XMLData$1, XMLDataItem as XMLDataItem$1, XMLGalleryData as XMLGalleryData$1, XMLItemLinksData as XMLItemLinksData$1, XMLLink as XMLLink$1, XMLSetItemsData as XMLSetItemsData$1, XMLWebsiteData as XMLWebsiteData$1 } from "./types.mjs";
 import * as v from "valibot";
 //#region src/xml/schemas.d.ts
-/**
- * Schema for validating OCR matches fetched from the OCHRE API
- * @internal
- */
-declare const XMLOcrMatchesData: v.GenericSchema<unknown, XMLOcrMatchesData$1>;
 declare const XMLLink: v.GenericSchema<unknown, XMLLink$1>;
 declare const XMLDataItem: v.GenericSchema<unknown, XMLDataItem$1>;
 declare const XMLItemLinksData: v.GenericSchema<unknown, XMLItemLinksData$1>;
@@ -14,4 +9,4 @@ declare const XMLSetItemsData: v.GenericSchema<unknown, XMLSetItemsData$1>;
 declare const XMLData: v.GenericSchema<unknown, XMLData$1>;
 declare const XMLWebsiteData: v.GenericSchema<unknown, XMLWebsiteData$1>;
 //#endregion
-export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLOcrMatchesData, XMLSetItemsData, XMLWebsiteData };
+export { XMLData, XMLDataItem, XMLGalleryData, XMLItemLinksData, XMLLink, XMLSetItemsData, XMLWebsiteData };

package/dist/xml/schemas.mjs

@@ -224,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")),
@@ -680,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) })),
@@ -832,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) })),
@@ -966,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

@@ -182,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;
@@ -605,7 +563,6 @@ type XMLResource = XMLBaseItem & {
   width?: XMLNumber;
   image?: XMLImage;
   imagemap?: XMLImageMap;
-  ocr?: XMLOcr;
   document?: XMLContent;
   coordinates?: XMLCoordinates;
   periods?: {
@@ -963,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, 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 };
+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.72",
+  "version": "1.0.73",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -53,7 +53,7 @@
   "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.62.0",

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 };