ochre-sdk 0.22.20 → 0.22.22

package/dist/index.d.mts

@@ -1288,11 +1288,39 @@ declare function fetchGallery(params: {
   error: string;
 }>;
 //#endregion
+//#region src/utils/fetchers/item-links.d.ts
+/**
+ * Fetches and parses an OCHRE item links from the OCHRE API
+ *
+ * @param uuid - The UUID of the OCHRE item to fetch
+ * @param category - The category of the OCHRE item to fetch
+ * @param itemCategories - The categories of the OCHRE linked items to fetch
+ * @param options - The options for the fetch
+ * @param options.fetch - The fetch function to use
+ * @param options.version - The version of the OCHRE API to use
+ * @returns Object containing the parsed OCHRE item links, or an error message if the fetch/parse fails
+ */
+declare function fetchItemLinks<T extends DataCategory = DataCategory, U extends DataCategory | Array<DataCategory> = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? Array<DataCategory> : never)>(uuid: string, category?: T, itemCategories?: U, options?: {
+  fetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
+  version?: ApiVersion;
+}): Promise<{
+  error: null;
+  items: Array<Item<T, U>>;
+} | {
+  error: string;
+  items: never;
+}>;
+//#endregion
 //#region src/utils/fetchers/item.d.ts
 /**
  * Fetches and parses an OCHRE item from the OCHRE API
  *
  * @param uuid - The UUID of the OCHRE item to fetch
+ * @param category - The category of the OCHRE item to fetch
+ * @param itemCategories - The categories of the OCHRE items to fetch
+ * @param options - The options for the fetch
+ * @param options.fetch - The fetch function to use
+ * @param options.version - The version of the OCHRE API to use
  * @returns Object containing the parsed OCHRE item, or an error message if the fetch/parse fails
  */
 declare function fetchItem<T extends DataCategory = DataCategory, U extends DataCategory | Array<DataCategory> = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? Array<DataCategory> : never)>(uuid: string, category?: T, itemCategories?: U, options?: {
@@ -1596,4 +1624,4 @@ declare const DEFAULT_PAGE_SIZE = 48;
  */
 declare function flattenItemProperties<T extends DataCategory = DataCategory, U extends DataCategory | Array<DataCategory> = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? Array<DataCategory> : never)>(item: Item<T, U>): Item<T, U>;
 //#endregion
-export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, ContextTree, ContextTreeFilterLevel, ContextTreeLevel, ContextTreeLevelItem, Coordinate, DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, Data, DataCategory, Event, FileFormat, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyValue, PropertyValueContent, PropertyValueContentType, PropertyValueQueryItem, PropertyVariable, Query, QueryGroup, QueryLeaf, Resource, Scope, Section, Set, SetAttributeValueQueryItem, SetItemsSort, SetItemsSortDirection, SpatialUnit, Style, StylesheetCategory, StylesheetItem, Text, Tree, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebSegment, WebSegmentItem, WebTitle, Webpage, Website, WebsitePropertyQuery, WebsitePropertyQueryNode, WebsiteType, fetchGallery, fetchItem, fetchSetItems, fetchSetPropertyValues, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByLabelAndValue, getPropertyByLabelAndValueContent, getPropertyByLabelAndValueContents, getPropertyByLabelAndValues, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValueContentByLabel, getPropertyValueContentByUuid, getPropertyValueContentsByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };
+export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, ContextTree, ContextTreeFilterLevel, ContextTreeLevel, ContextTreeLevelItem, Coordinate, DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, Data, DataCategory, Event, FileFormat, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyValue, PropertyValueContent, PropertyValueContentType, PropertyValueQueryItem, PropertyVariable, Query, QueryGroup, QueryLeaf, Resource, Scope, Section, Set, SetAttributeValueQueryItem, SetItemsSort, SetItemsSortDirection, SpatialUnit, Style, StylesheetCategory, StylesheetItem, Text, Tree, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebSegment, WebSegmentItem, WebTitle, Webpage, Website, WebsitePropertyQuery, WebsitePropertyQueryNode, WebsiteType, fetchGallery, fetchItem, fetchItemLinks, fetchSetItems, fetchSetPropertyValues, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByLabelAndValue, getPropertyByLabelAndValueContent, getPropertyByLabelAndValueContents, getPropertyByLabelAndValues, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValueContentByLabel, getPropertyValueContentByUuid, getPropertyValueContentsByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/dist/index.mjs

@@ -2038,6 +2038,99 @@ async function fetchGallery(params, options) {
 	}
 }
 //#endregion
+//#region src/utils/fetchers/item-links.ts
+/**
+* Build an XQuery string to fetch item links from the OCHRE API
+* @param params - The parameters for the fetch
+* @param params.uuid - The UUID of the OCHRE item to fetch
+* @returns An XQuery string
+*/
+function buildXQuery$2(params) {
+	const { uuid } = params;
+	return `<ochre>{${`let $item-uuid := "${uuid}"
+
+let $uuids :=
+  distinct-values((
+
+    (: Direct links on most item categories :)
+    fn:collection("ochre/resource")/ochre[@uuid = $item-uuid]/resource/links/*/@uuid/string(),
+    fn:collection("ochre/bibliography")/ochre[@uuid = $item-uuid]/bibliography/links/*/@uuid/string(),
+    fn:collection("ochre/period")/ochre[@uuid = $item-uuid]/period/links/*/@uuid/string(),
+    fn:collection("ochre/person")/ochre[@uuid = $item-uuid]/person/links/*/@uuid/string(),
+    fn:collection("ochre/propertyVariable")/ochre[@uuid = $item-uuid]/propertyVariable/links/*/@uuid/string(),
+    fn:collection("ochre/propertyValue")/ochre[@uuid = $item-uuid]/propertyValue/links/*/@uuid/string(),
+    fn:collection("ochre/text")/ochre[@uuid = $item-uuid]/text/links/*/@uuid/string(),
+    fn:collection("ochre/tree")/ochre[@uuid = $item-uuid]/tree/links/*/@uuid/string(),
+    fn:collection("ochre/set")/ochre[@uuid = $item-uuid]/set/links/*/@uuid/string(),
+
+    (: Special category structures :)
+    fn:collection("ochre/spatialUnit")/ochre[@uuid = $item-uuid]/spatialUnit/observations/observation/links/*/@uuid/string(),
+    fn:collection("ochre/concept")/ochre[@uuid = $item-uuid]/concept/interpretations/interpretation/links/*/@uuid/string()
+  ))
+
+return
+    <items>{(
+      fn:collection("ochre/resource")/ochre/resource[@uuid = $uuids],
+      fn:collection("ochre/bibliography")/ochre/bibliography[@uuid = $uuids],
+      fn:collection("ochre/period")/ochre/period[@uuid = $uuids],
+      fn:collection("ochre/person")/ochre/person[@uuid = $uuids],
+      fn:collection("ochre/propertyVariable")/ochre/propertyVariable[@uuid = $uuids],
+      fn:collection("ochre/propertyValue")/ochre/propertyValue[@uuid = $uuids],
+      fn:collection("ochre/text")/ochre/text[@uuid = $uuids],
+      fn:collection("ochre/tree")/ochre/tree[@uuid = $uuids],
+      fn:collection("ochre/set")/ochre/set[@uuid = $uuids],
+      fn:collection("ochre/spatialUnit")/ochre/spatialUnit[@uuid = $uuids],
+      fn:collection("ochre/concept")/ochre/concept[@uuid = $uuids]
+    )}</items>`}}</ochre>`;
+}
+/**
+* Fetches and parses an OCHRE item links from the OCHRE API
+*
+* @param uuid - The UUID of the OCHRE item to fetch
+* @param category - The category of the OCHRE item to fetch
+* @param itemCategories - The categories of the OCHRE linked items to fetch
+* @param options - The options for the fetch
+* @param options.fetch - The fetch function to use
+* @param options.version - The version of the OCHRE API to use
+* @returns Object containing the parsed OCHRE item links, or an error message if the fetch/parse fails
+*/
+async function fetchItemLinks(uuid, category, itemCategories, options) {
+	try {
+		if (options?.version != null && options.version !== 2) throw new Error("Set item queries only support API version 2");
+		const xquery = buildXQuery$2({ uuid });
+		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&format=json", {
+			method: "POST",
+			body: xquery,
+			headers: { "Content-Type": "application/xquery" }
+		});
+		if (!response.ok) throw new Error(`OCHRE API responded with status: ${response.status}`);
+		const data = await response.json();
+		if (Array.isArray(data.result) || Object.keys(data.result).length === 0) throw new Error("Invalid OCHRE API response");
+		const rawItems = data.result.ochre.items;
+		const items = [];
+		if (rawItems.resource != null) items.push(...parseResources(ensureArray(rawItems.resource)));
+		if (rawItems.spatialUnit != null) items.push(...parseSpatialUnits(ensureArray(rawItems.spatialUnit)));
+		if (rawItems.concept != null) items.push(...parseConcepts(ensureArray(rawItems.concept)));
+		if (rawItems.period != null) items.push(...parsePeriods(ensureArray(rawItems.period)));
+		if (rawItems.bibliography != null) items.push(...parseBibliographies(ensureArray(rawItems.bibliography)));
+		if (rawItems.person != null) items.push(...parsePersons(ensureArray(rawItems.person)));
+		if (rawItems.propertyVariable != null) items.push(...parsePropertyVariables(ensureArray(rawItems.propertyVariable)));
+		if (rawItems.propertyValue != null) items.push(...parsePropertyValues(ensureArray(rawItems.propertyValue)));
+		if (rawItems.text != null) items.push(...parseTexts(ensureArray(rawItems.text)));
+		if (rawItems.set != null) for (const linkedSet of ensureArray(rawItems.set)) items.push(parseSet(linkedSet, itemCategories));
+		if (rawItems.tree != null) for (const linkedTree of ensureArray(rawItems.tree)) items.push(parseTree(linkedTree, itemCategories));
+		return {
+			error: null,
+			items
+		};
+	} catch (error) {
+		return {
+			error: error instanceof Error ? error.message : "Unknown error",
+			items: void 0
+		};
+	}
+}
+//#endregion
 //#region src/utils/fetchers/uuid.ts
 /**
 * Fetches raw OCHRE data by UUID from the OCHRE API
@@ -2065,6 +2158,11 @@ async function fetchByUuid(uuid, options) {
 * Fetches and parses an OCHRE item from the OCHRE API
 *
 * @param uuid - The UUID of the OCHRE item to fetch
+* @param category - The category of the OCHRE item to fetch
+* @param itemCategories - The categories of the OCHRE items to fetch
+* @param options - The options for the fetch
+* @param options.fetch - The fetch function to use
+* @param options.version - The version of the OCHRE API to use
 * @returns Object containing the parsed OCHRE item, or an error message if the fetch/parse fails
 */
 async function fetchItem(uuid, category, itemCategories, options) {
@@ -4050,6 +4148,15 @@ function filterProperties(property, filter, options = DEFAULT_OPTIONS) {
 //#region src/utils/parse/website.ts
 const SEGMENT_UNIQUE_SLUG_PREFIX_REGEX = /^\$[^-]*-/;
 const TRAILING_SLASH_REGEX = /\/$/;
+function formatRawResourceMetadata(resource) {
+	const metadata = [`label “${parseStringContent(resource.identification.label)}”`, `uuid “${resource.uuid}”`];
+	if (resource.slug != null) metadata.push(`slug “${resource.slug}”`);
+	if (resource.identification.abbreviation != null) metadata.push(`abbreviation “${parseFakeStringOrContent(resource.identification.abbreviation)}”`);
+	return metadata.join(", ");
+}
+function formatComponentError(message, componentName, elementResource) {
+	return `${message} for component “${componentName ?? "(unknown)"}” (${formatRawResourceMetadata(elementResource)})`;
+}
 /**
 * Extracts CSS style properties for a given presentation variant.
 *
@@ -4173,7 +4280,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 	switch (componentName) {
 		case "3d-viewer": {
 			const resourceLink = links.find((link) => link.category === "resource" && link.fileFormat === "model/obj");
-			if (resourceLink?.uuid == null) throw new Error(`Resource link not found for the following component: “${componentName}”`);
+			if (resourceLink?.uuid == null) throw new Error(formatComponentError("Resource link not found", componentName, elementResource));
 			let isInteractive = getPropertyValueContentByLabel(componentProperty.properties, "is-interactive");
 			isInteractive ??= true;
 			let isControlsDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "controls-displayed");
@@ -4191,7 +4298,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			const boundElementPropertyUuid = getPropertyByLabel(componentProperty.properties, "bound-element")?.values[0]?.uuid ?? null;
 			const linkToProperty = getPropertyByLabel(componentProperty.properties, "link-to");
 			const href = linkToProperty?.values[0]?.href != null ? transformPermanentIdentificationUrl(linkToProperty.values[0].href) : linkToProperty?.values[0]?.slug ?? null;
-			if (boundElementPropertyUuid == null && href == null) throw new Error(`Bound element or href not found for the following component: “${componentName}”`);
+			if (boundElementPropertyUuid == null && href == null) throw new Error(formatComponentError("Bound element or href not found", componentName, elementResource));
 			properties = {
 				component: "advanced-search",
 				boundElementUuid: boundElementPropertyUuid,
@@ -4201,7 +4308,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "annotated-document": {
 			const documentLink = links.find((link) => link.type === "internalDocument");
-			if (documentLink?.uuid == null) throw new Error(`Document link not found for the following component: “${componentName}”`);
+			if (documentLink?.uuid == null) throw new Error(formatComponentError("Document link not found", componentName, elementResource));
 			properties = {
 				component: "annotated-document",
 				linkUuid: documentLink.uuid
@@ -4210,7 +4317,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "annotated-image": {
 			const imageLinks = links.filter((link) => link.type === "image" || link.type === "IIIF");
-			if (imageLinks.length === 0 || imageLinks[0].uuid == null) throw new Error(`Image link not found for the following component: “${componentName}”`);
+			if (imageLinks.length === 0 || imageLinks[0].uuid == null) throw new Error(formatComponentError("Image link not found", componentName, elementResource));
 			let isFilterInputDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "filter-input-displayed");
 			isFilterInputDisplayed ??= true;
 			let isOptionsDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "options-displayed");
@@ -4231,7 +4338,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "audio-player": {
 			const audioLink = links.find((link) => link.type === "audio");
-			if (audioLink?.uuid == null) throw new Error(`Audio link not found for the following component: “${componentName}”`);
+			if (audioLink?.uuid == null) throw new Error(formatComponentError("Audio link not found", componentName, elementResource));
 			let isSpeedControlsDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "speed-controls-displayed");
 			isSpeedControlsDisplayed ??= true;
 			let isVolumeControlsDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "volume-controls-displayed");
@@ -4250,7 +4357,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		case "bibliography": {
 			const itemLinks = links.filter((link) => link.category !== "bibliography");
 			const bibliographyLink = links.find((link) => link.category === "bibliography");
-			if (itemLinks.length === 0 && bibliographyLink?.bibliographies == null) throw new Error(`No links found for the following component: “${componentName}”`);
+			if (itemLinks.length === 0 && bibliographyLink?.bibliographies == null) throw new Error(formatComponentError("No links found", componentName, elementResource));
 			let layout = getPropertyValueContentByLabel(componentProperty.properties, "layout");
 			layout ??= "long";
 			let isSourceDocumentDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "source-document-displayed");
@@ -4273,7 +4380,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			if (href === null) {
 				const linkToProperty = getPropertyByLabel(componentProperty.properties, "link-to");
 				href = linkToProperty?.values[0]?.href != null ? transformPermanentIdentificationUrl(linkToProperty.values[0].href) : linkToProperty?.values[0]?.slug ?? null;
-				if (href === null) throw new Error(`Properties “navigate-to” or “link-to” not found for the following component: “${componentName}”`);
+				if (href === null) throw new Error(formatComponentError("Properties “navigate-to” or “link-to” not found", componentName, elementResource));
 				else isExternal = true;
 			}
 			let startIcon = getPropertyValueContentByLabel(componentProperty.properties, "start-icon");
@@ -4304,7 +4411,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "collection": {
 			const setLinks = links.filter((link) => link.category === "set");
-			if (setLinks.every((link) => link.uuid === null)) throw new Error(`Set links not found for the following component: “${componentName}”`);
+			if (setLinks.every((link) => link.uuid === null)) throw new Error(formatComponentError("Set links not found", componentName, elementResource));
 			const displayedProperties = getPropertyByLabel(componentProperty.properties, "use-property");
 			let variant = getPropertyValueContentByLabel(componentProperty.properties, "variant");
 			variant ??= "slide";
@@ -4383,7 +4490,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "entries": {
 			const entriesLink = links.find((link) => link.category === "tree" || link.category === "set");
-			if (entriesLink?.uuid == null) throw new Error(`Entries link not found for the following component: “${componentName}”`);
+			if (entriesLink?.uuid == null) throw new Error(formatComponentError("Entries link not found", componentName, elementResource));
 			let variant = getPropertyValueContentByLabel(componentProperty.properties, "variant");
 			variant ??= "entry";
 			let isFilterInputDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "filter-input-displayed");
@@ -4398,7 +4505,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "iframe": {
 			const href = links.find((link) => link.type === "webpage")?.href;
-			if (!href) throw new Error(`URL not found for the following component: “${componentName}”`);
+			if (!href) throw new Error(formatComponentError("URL not found", componentName, elementResource));
 			const height = getPropertyValueContentByLabel(componentProperty.properties, "height");
 			const width = getPropertyValueContentByLabel(componentProperty.properties, "width");
 			properties = {
@@ -4411,7 +4518,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "iiif-viewer": {
 			const manifestLink = links.find((link) => link.type === "IIIF");
-			if (manifestLink?.uuid == null) throw new Error(`Manifest link not found for the following component: “${componentName}”`);
+			if (manifestLink?.uuid == null) throw new Error(formatComponentError("Manifest link not found", componentName, elementResource));
 			let variant = getPropertyValueContentByLabel(componentProperty.properties, "variant");
 			variant ??= "universal-viewer";
 			properties = {
@@ -4422,7 +4529,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			break;
 		}
 		case "image": {
-			if (links.length === 0) throw new Error(`No links found for the following component: “${componentName}”`);
+			if (links.length === 0) throw new Error(formatComponentError("No links found", componentName, elementResource));
 			let imageQuality = getPropertyValueContentByLabel(componentProperty.properties, "image-quality");
 			imageQuality ??= "high";
 			const images = [];
@@ -4510,7 +4617,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "image-gallery": {
 			const galleryLink = links.find((link) => link.category === "tree" || link.category === "set");
-			if (galleryLink?.uuid == null) throw new Error(`Image gallery link not found for the following component: “${componentName}”`);
+			if (galleryLink?.uuid == null) throw new Error(formatComponentError("Image gallery link not found", componentName, elementResource));
 			let isFilterInputDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "filter-input-displayed");
 			isFilterInputDisplayed ??= true;
 			properties = {
@@ -4522,7 +4629,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "map": {
 			const mapLink = links.find((link) => link.category === "set" || link.category === "tree");
-			if (mapLink?.uuid == null) throw new Error(`Map link not found for the following component: “${componentName}”`);
+			if (mapLink?.uuid == null) throw new Error(formatComponentError("Map link not found", componentName, elementResource));
 			let isInteractive = getPropertyValueContentByLabel(componentProperty.properties, "is-interactive");
 			isInteractive ??= true;
 			let isClustered = getPropertyValueContentByLabel(componentProperty.properties, "is-clustered");
@@ -4557,17 +4664,17 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "query": {
 			const setLinks = links.filter((link) => link.category === "set");
-			if (setLinks.every((link) => link.uuid === null)) throw new Error(`Set links not found for the following component: “${componentName}”`);
+			if (setLinks.every((link) => link.uuid === null)) throw new Error(formatComponentError("Set links not found", componentName, elementResource));
 			const items = [];
-			if (componentProperty.properties.length === 0) throw new Error(`Query properties not found for the following component: “${componentName}”`);
+			if (componentProperty.properties.length === 0) throw new Error(formatComponentError("Query properties not found", componentName, elementResource));
 			for (const queryItem of componentProperty.properties) {
 				const querySubProperties = queryItem.properties;
 				const label = getPropertyValueContentByLabel(querySubProperties, "query-prompt");
 				if (label === null) continue;
 				const queries = (getPropertyByLabel(querySubProperties, "use-property")?.values.filter((value) => value.uuid !== null) ?? []).map((propertyVariable) => {
-					if (propertyVariable.uuid === null) throw new Error(`Property variable UUID not found for the following component: “${componentName}”`);
+					if (propertyVariable.uuid === null) throw new Error(formatComponentError("Property variable UUID not found", componentName, elementResource));
 					const dataType = propertyVariable.dataType;
-					if (dataType === "coordinate") throw new Error(`Query prompts with data type "coordinate" are not supported for the following component: “${componentName}”`);
+					if (dataType === "coordinate") throw new Error(formatComponentError("Query prompts with data type \"coordinate\" are not supported", componentName, elementResource));
 					return {
 						target: "property",
 						propertyVariable: propertyVariable.uuid,
@@ -4588,7 +4695,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 					endIcon
 				});
 			}
-			if (items.length === 0) throw new Error(`No queries found for the following component: “${componentName}”`);
+			if (items.length === 0) throw new Error(formatComponentError("No queries found", componentName, elementResource));
 			const options = {
 				scopes: elementResource.options?.scopes != null ? ensureArray(elementResource.options.scopes.scope).map((scope) => ({
 					uuid: scope.uuid.content,
@@ -4634,7 +4741,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "table": {
 			const tableLink = links.find((link) => link.category === "set");
-			if (tableLink?.uuid == null) throw new Error(`Table link not found for the following component: “${componentName}”`);
+			if (tableLink?.uuid == null) throw new Error(formatComponentError("Table link not found", componentName, elementResource));
 			properties = {
 				component: "table",
 				linkUuid: tableLink.uuid
@@ -4648,7 +4755,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			const boundElementUuid = getPropertyByLabel(componentProperty.properties, "bound-element")?.values[0]?.uuid ?? null;
 			const linkToProperty = getPropertyByLabel(componentProperty.properties, "link-to");
 			const href = linkToProperty?.values[0]?.href != null ? transformPermanentIdentificationUrl(linkToProperty.values[0].href) : linkToProperty?.values[0]?.slug ?? null;
-			if (!boundElementUuid && !href) throw new Error(`Bound element or href not found for the following component: “${componentName}”`);
+			if (!boundElementUuid && !href) throw new Error(formatComponentError("Bound element or href not found", componentName, elementResource));
 			let placeholder = getPropertyValueContentByLabel(componentProperty.properties, "placeholder-text");
 			placeholder ??= null;
 			let baseFilterQueries = getPropertyValueContentByLabel(componentProperty.properties, "base-filter-queries");
@@ -4665,7 +4772,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "text": {
 			const content = elementResource.document && "content" in elementResource.document ? parseDocument(elementResource.document.content) : null;
-			if (!content) throw new Error(`Content not found for the following component: “${componentName}”`);
+			if (!content) throw new Error(formatComponentError("Content not found", componentName, elementResource));
 			let variantName = "block";
 			let variant;
 			const variantProperty = getPropertyByLabel(componentProperty.properties, "variant");
@@ -4692,7 +4799,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "timeline": {
 			const timelineLink = links.find((link) => link.category === "tree");
-			if (timelineLink?.uuid == null) throw new Error(`Timeline link not found for the following component: “${componentName}”`);
+			if (timelineLink?.uuid == null) throw new Error(formatComponentError("Timeline link not found", componentName, elementResource));
 			properties = {
 				component: "timeline",
 				linkUuid: timelineLink.uuid
@@ -4701,7 +4808,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "video": {
 			const videoLink = links.find((link) => link.type === "video");
-			if (videoLink?.uuid == null) throw new Error(`Video link not found for the following component: “${componentName}”`);
+			if (videoLink?.uuid == null) throw new Error(formatComponentError("Video link not found", componentName, elementResource));
 			let isChaptersDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "chapters-displayed");
 			isChaptersDisplayed ??= true;
 			properties = {
@@ -4715,7 +4822,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			console.warn(`Invalid or non-implemented component name “${unparsedComponentName?.toString() ?? "(unknown)"}” for the following element: “${parseStringContent(elementResource.identification.label)}”`);
 			break;
 	}
-	if (properties === null) throw new Error(`Properties not found for the following component: “${componentName}”`);
+	if (properties === null) throw new Error(formatComponentError("Properties not found", componentName, elementResource));
 	return properties;
 }
 function parseWebTitle(properties, identification, overrides) {
@@ -4751,9 +4858,9 @@ function parseWebElement(elementResource) {
 	const identification = parseIdentification(elementResource.identification);
 	const elementProperties = elementResource.properties?.property ? parseProperties(Array.isArray(elementResource.properties.property) ? elementResource.properties.property : [elementResource.properties.property]) : [];
 	const presentationProperty = getPropertyByLabel(elementProperties, "presentation");
-	if (presentationProperty === null) throw new Error(`Presentation property not found for element “${identification.label}”`);
+	if (presentationProperty === null) throw new Error(`Presentation property not found for element (${formatRawResourceMetadata(elementResource)})`);
 	const componentProperty = getPropertyByLabel(presentationProperty.properties, "component");
-	if (componentProperty === null) throw new Error(`Component for element “${identification.label}” not found`);
+	if (componentProperty === null) throw new Error(`Component property not found for element (${formatRawResourceMetadata(elementResource)})`);
 	const properties = parseWebElementProperties(componentProperty, elementResource);
 	const cssStyles = parseResponsiveCssStyles(elementProperties);
 	const title = parseWebTitle(elementProperties, identification, {
@@ -4810,7 +4917,7 @@ function parseWebpage(webpageResource, slugPrefix) {
 	if (webpageProperties.length === 0 || getPropertyValueContentByLabel(webpageProperties, "presentation") !== "page") return null;
 	const identification = parseIdentification(webpageResource.identification);
 	const slug = webpageResource.slug?.replace(SEGMENT_UNIQUE_SLUG_PREFIX_REGEX, "") ?? null;
-	if (slug == null) throw new Error(`Slug not found for page “${identification.label}”`);
+	if (slug == null) throw new Error(`Slug not found for page (${formatRawResourceMetadata(webpageResource)})`);
 	const returnWebpage = {
 		uuid: webpageResource.uuid,
 		type: "page",
@@ -4905,7 +5012,7 @@ function parseWebSegment(segmentResource, slugPrefix) {
 	if (webpageProperties.length === 0 || getPropertyValueContentByLabel(webpageProperties, "presentation") !== "segment") return null;
 	const identification = parseIdentification(segmentResource.identification);
 	const slug = segmentResource.identification.abbreviation != null ? parseFakeStringOrContent(segmentResource.identification.abbreviation) : null;
-	if (slug == null) throw new Error(`Slug not found for segment “${identification.label}”`);
+	if (slug == null) throw new Error(`Slug not found for segment (${formatRawResourceMetadata(segmentResource)})`);
 	const returnSegment = {
 		uuid: segmentResource.uuid,
 		type: "segment",
@@ -4942,7 +5049,7 @@ function parseWebSegmentItem(segmentItemResource, slugPrefix) {
 	if (webpageProperties.length === 0 || getPropertyValueContentByLabel(webpageProperties, "presentation") !== "segment-item") return null;
 	const identification = parseIdentification(segmentItemResource.identification);
 	const slug = segmentItemResource.identification.abbreviation != null ? parseFakeStringOrContent(segmentItemResource.identification.abbreviation) : null;
-	if (slug == null) throw new Error(`Slug not found for segment item “${identification.label}”`);
+	if (slug == null) throw new Error(`Slug not found for segment item (${formatRawResourceMetadata(segmentItemResource)})`);
 	const returnSegmentItem = {
 		uuid: segmentItemResource.uuid,
 		type: "segment-item",
@@ -5168,9 +5275,9 @@ function parseWebBlock(blockResource) {
 		for (const resource of blockResources) {
 			const resourceProperties = resource.properties ? parseProperties(ensureArray(resource.properties.property)) : [];
 			const resourceType = getPropertyValueContentByLabel(resourceProperties, "presentation");
-			if (resourceType !== "element") throw new Error(`Accordion only accepts elements, but got “${resourceType}” for the following resource: “${parseStringContent(resource.identification.label)}”`);
+			if (resourceType !== "element") throw new Error(`Accordion only accepts elements, but got “${resourceType}” (${formatRawResourceMetadata(resource)})`);
 			const componentType = getPropertyValueContentByLabel(getPropertyByLabel(resourceProperties, "presentation")?.properties ?? [], "component");
-			if (componentType !== "text") throw new Error(`Accordion only accepts text components, but got “${componentType}” for the following resource: “${parseStringContent(resource.identification.label)}”`);
+			if (componentType !== "text") throw new Error(`Accordion only accepts text components, but got “${componentType}” (${formatRawResourceMetadata(resource)})`);
 			const element = parseWebElementForAccordion(resource);
 			accordionItems.push(element);
 		}
@@ -5269,7 +5376,7 @@ function parseWebsiteProperties(properties, websiteTree, sidebar) {
 			name: contactContent[0],
 			email: contactContent[1] ?? null
 		};
-		else throw new Error(`Contact property must be in the format “name;email”, but got “${contactProperty.values[0]?.content}”`);
+		else throw new Error(`Contact property must use “name;email”, got “${contactProperty.values[0]?.content}” (website uuid “${websiteTree.uuid}”)`);
 	}
 	returnProperties.loadingVariant = getPropertyValueContentByLabel(websiteProperties, "loading-variant") ?? "spinner";
 	returnProperties.theme.isThemeToggleDisplayed = getPropertyValueContentByLabel(websiteProperties, "supports-theme-toggle") ?? true;
@@ -5389,8 +5496,8 @@ function parseFilterContexts(filterContextLevels) {
 	return filterContextTreeLevels;
 }
 function parseWebsite(websiteTree, metadata, belongsTo, { version = 2 } = {}) {
-	if (!websiteTree.properties) throw new Error("Website properties not found");
-	if (typeof websiteTree.items === "string" || !("resource" in websiteTree.items)) throw new Error("Website pages not found");
+	if (!websiteTree.properties) throw new Error(`Website properties not found (website uuid “${websiteTree.uuid}”)`);
+	if (typeof websiteTree.items === "string" || !("resource" in websiteTree.items)) throw new Error(`Website pages not found (website uuid “${websiteTree.uuid}”)`);
 	const resources = ensureArray(websiteTree.items.resource);
 	const items = [...parseWebpages(resources), ...parseSegments(resources)];
 	const sidebar = parseSidebar(resources);
@@ -5481,4 +5588,4 @@ async function fetchWebsite(abbreviation, options) {
 	}
 }
 //#endregion
-export { DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, fetchGallery, fetchItem, fetchSetItems, fetchSetPropertyValues, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByLabelAndValue, getPropertyByLabelAndValueContent, getPropertyByLabelAndValueContents, getPropertyByLabelAndValues, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValueContentByLabel, getPropertyValueContentByUuid, getPropertyValueContentsByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };
+export { DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, fetchGallery, fetchItem, fetchItemLinks, fetchSetItems, fetchSetPropertyValues, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByLabelAndValue, getPropertyByLabelAndValueContent, getPropertyByLabelAndValueContents, getPropertyByLabelAndValues, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValueContentByLabel, getPropertyValueContentByUuid, getPropertyValueContentsByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "0.22.20",
+  "version": "0.22.22",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",