ochre-sdk 0.22.20 → 0.22.21

package/dist/index.d.mts

@@ -1293,6 +1293,11 @@ declare function fetchGallery(params: {
  * 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?: {

package/dist/index.mjs

@@ -2065,6 +2065,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 +4055,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 +4187,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 +4205,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 +4215,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 +4224,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 +4245,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 +4264,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 +4287,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 +4318,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 +4397,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 +4412,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 +4425,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 +4436,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 +4524,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 +4536,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 +4571,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 +4602,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 +4648,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 +4662,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 +4679,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 +4706,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 +4715,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 +4729,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 +4765,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 +4824,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 +4919,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 +4956,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 +5182,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 +5283,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 +5403,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);

package/package.json

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