ochre-sdk 1.0.5 → 1.0.7

package/README.md

@@ -33,7 +33,7 @@ const result = await fetchItem("<item-uuid>", {
 });
 
 if (result.error != null) {
-  throw new Error(result.error);
+  throw new Error("Failed to fetch item", { cause: result.error });
 }
 
 console.log(result.item.identification.label.getText("eng"));

package/dist/index.mjs

@@ -487,7 +487,45 @@ var MultilingualString = class MultilingualString {
 };
 //#endregion
 //#region src/utils.ts
+const MAX_SCHEMA_VALIDATION_ISSUES = 3;
 const PSEUDO_UUID_REGEX = /^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i;
+function getSchemaValidationLeafIssues(issues, leaves = []) {
+	for (const issue of issues) {
+		if (issue.issues != null && issue.issues.length > 0) {
+			getSchemaValidationLeafIssues(issue.issues, leaves);
+			continue;
+		}
+		leaves.push(issue);
+	}
+	return leaves;
+}
+function formatSchemaValidationIssue(issue) {
+	const path = v.getDotPath(issue);
+	return `${path != null && path.length > 0 ? path : "(root)"}: ${issue.message}`;
+}
+/**
+* Formats Valibot validation issues for compact error messages.
+* @param issues - The validation issues to format
+* @internal
+*/
+function formatSchemaValidationIssues(issues) {
+	const leafIssues = getSchemaValidationLeafIssues(issues);
+	const issuesToFormat = leafIssues.length > 0 ? leafIssues : issues;
+	const formattedIssues = [];
+	for (const issue of issuesToFormat.slice(0, MAX_SCHEMA_VALIDATION_ISSUES)) formattedIssues.push(formatSchemaValidationIssue(issue));
+	const hiddenIssueCount = issuesToFormat.length - formattedIssues.length;
+	if (hiddenIssueCount > 0) formattedIssues.push(`+${hiddenIssueCount.toLocaleString("en-US")} more`);
+	return `Schema validation failed: ${formattedIssues.join("; ")}`;
+}
+/**
+* Creates an Error whose message includes compact schema-validation details.
+* @param message - The base error message
+* @param issues - The validation issues to include
+* @internal
+*/
+function createSchemaValidationError(message, issues) {
+	return new Error(`${message}. ${formatSchemaValidationIssues(issues)}`, { cause: issues });
+}
 /**
 * Logs Valibot validation issues to the console with detailed formatting
 * @param issues - The validation issues to log
@@ -1409,6 +1447,12 @@ function parseStringContent(value, options = FALLBACK_PARSER_OPTIONS) {
 }
 //#endregion
 //#region src/parsers/index.ts
+function isXMLContextGroup(context) {
+	return "context" in context;
+}
+function isXMLContextItem(context) {
+	return "project" in context;
+}
 const SET_ITEM_CATEGORIES = ["tree", ...[
 	"bibliography",
 	"concept",
@@ -1521,27 +1565,33 @@ function emptyContextItem() {
 }
 function parseContext(rawContext) {
 	const nodes = [];
-	for (const rawContextOuterItem of rawContext) for (const rawContextItem of rawContextOuterItem.context) {
-		const node = {
-			tree: rawContextItem.tree[0] == null ? emptyContextItem() : parseContextItem$1(rawContextItem.tree[0]),
-			project: parseContextItem$1(rawContextItem.project),
-			heading: []
-		};
-		const rawContextValues = rawContextItem;
-		for (const heading of rawContextValues.heading ?? []) node.heading.push(parseContextItem$1(heading));
-		for (const { raw, parsed } of CONTEXT_CATEGORY_MAPPINGS) {
-			const contextValues = rawContextValues[raw] ?? [];
-			for (const contextValue of contextValues) {
-				const parsedItems = node[parsed] ?? [];
-				parsedItems.push(parseContextItem$1(contextValue));
-				node[parsed] = parsedItems;
+	let displayPath = "";
+	for (const rawContextOuterItem of rawContext) {
+		if (!isXMLContextGroup(rawContextOuterItem)) continue;
+		displayPath = displayPath || rawContextOuterItem.displayPath;
+		for (const rawContextItem of rawContextOuterItem.context) {
+			if (!isXMLContextItem(rawContextItem)) continue;
+			const node = {
+				tree: rawContextItem.tree[0] == null ? emptyContextItem() : parseContextItem$1(rawContextItem.tree[0]),
+				project: parseContextItem$1(rawContextItem.project),
+				heading: []
+			};
+			const rawContextValues = rawContextItem;
+			for (const heading of rawContextValues.heading ?? []) node.heading.push(parseContextItem$1(heading));
+			for (const { raw, parsed } of CONTEXT_CATEGORY_MAPPINGS) {
+				const contextValues = rawContextValues[raw] ?? [];
+				for (const contextValue of contextValues) {
+					const parsedItems = node[parsed] ?? [];
+					parsedItems.push(parseContextItem$1(contextValue));
+					node[parsed] = parsedItems;
+				}
 			}
+			nodes.push(node);
 		}
-		nodes.push(node);
 	}
 	return {
 		nodes,
-		displayPath: rawContext[0]?.displayPath ?? ""
+		displayPath
 	};
 }
 function parseEventReference(rawReference, options) {
@@ -1692,16 +1742,19 @@ function normalizeSetItemCategories(containedItemCategory) {
 	return uniqueCategories;
 }
 function normalizeTreeItemCategory(containedItemCategory) {
-	if (containedItemCategory != null && typeof containedItemCategory !== "string") throw new Error("Tree containedItemCategory must be a single category");
-	if (containedItemCategory === "tree") throw new Error("Tree containedItemCategory cannot be \"tree\"");
+	if (containedItemCategory != null && typeof containedItemCategory !== "string") throw new Error("Tree containedItemCategory must be a single category", { cause: containedItemCategory });
+	if (containedItemCategory === "tree") throw new Error("Tree containedItemCategory cannot be \"tree\"", { cause: containedItemCategory });
 	return containedItemCategory;
 }
 function resolveTreeItemCategory(rawTree, containedItemCategory) {
 	const inferredCategories = inferItemCategories(rawTree.items);
-	if (inferredCategories.length > 1) throw new Error(`Expected Tree items to contain one category, received ${inferredCategories.join(", ")}`);
+	if (inferredCategories.length > 1) throw new Error(`Expected Tree items to contain one category, received ${inferredCategories.join(", ")}`, { cause: inferredCategories });
 	const inferredCategory = inferredCategories[0] ?? null;
-	if (inferredCategory === "tree") throw new Error("Tree items cannot contain category \"tree\"");
-	if (containedItemCategory != null && inferredCategory != null && containedItemCategory !== inferredCategory) throw new Error(`Tree containedItemCategory "${containedItemCategory}" does not match XML items category "${inferredCategory}"`);
+	if (inferredCategory === "tree") throw new Error("Tree items cannot contain category \"tree\"", { cause: inferredCategory });
+	if (containedItemCategory != null && inferredCategory != null && containedItemCategory !== inferredCategory) throw new Error(`Tree containedItemCategory "${containedItemCategory}" does not match XML items category "${inferredCategory}"`, { cause: {
+		containedItemCategory,
+		inferredCategory
+	} });
 	return containedItemCategory ?? inferredCategory;
 }
 function parseImage(rawImage, options) {
@@ -1849,12 +1902,13 @@ function parseNotes(rawNotes, options) {
 }
 function parsePropertyDataType(dataType) {
 	if (dataType == null || dataType === "") return "string";
-	for (const propertyDataType of PROPERTY_DATA_TYPES) if (dataType === propertyDataType) return propertyDataType;
-	throw new Error(`Invalid property value data type: ${dataType}`);
+	const normalizedDataType = dataType.startsWith("xs:") ? dataType.slice(3) : dataType;
+	for (const propertyDataType of PROPERTY_DATA_TYPES) if (normalizedDataType === propertyDataType) return propertyDataType;
+	throw new Error(`Invalid property value data type: ${dataType}`, { cause: dataType });
 }
 function parsePropertyValueContent(value, options) {
 	const dataType = parsePropertyDataType(value.dataType);
-	const rawLabel = value.content == null ? null : parseRequiredContentLike(value, options);
+	const rawLabel = value.content != null ? parseRequiredContentLike(value, options) : value.payload != null && value.payload !== "" ? multilingualFromText(value.payload, options) : null;
 	const displayText = rawLabel?.getText() ?? value.payload ?? value.slug ?? "";
 	const contentText = value.rawValue ?? value.payload ?? displayText;
 	const common = {
@@ -2580,7 +2634,7 @@ function resolveLanguages(requestedLanguages, metadataLanguages) {
 	if (requestedLanguages.length === 0) return metadataLanguages;
 	const unsupportedLanguages = [];
 	for (const requestedLanguage of requestedLanguages) if (!metadataLanguages.some((metadataLanguage) => metadataLanguage.toLocaleLowerCase("en-US") === requestedLanguage.toLocaleLowerCase("en-US"))) unsupportedLanguages.push(requestedLanguage);
-	if (unsupportedLanguages.length > 0) throw new Error(`The following language(s) are not supported by the dataset: ${unsupportedLanguages.toSorted((a, b) => a.localeCompare(b, "en-US")).join(", ")}. Available languages: ${metadataLanguages.toSorted((a, b) => a.localeCompare(b, "en-US")).join(", ")}`);
+	if (unsupportedLanguages.length > 0) throw new Error(`The following language(s) are not supported by the dataset: ${unsupportedLanguages.toSorted((a, b) => a.localeCompare(b, "en-US")).join(", ")}. Available languages: ${metadataLanguages.toSorted((a, b) => a.localeCompare(b, "en-US")).join(", ")}`, { cause: unsupportedLanguages });
 	return requestedLanguages;
 }
 function resolveDefaultLanguage(rawOchre, languages) {
@@ -2590,7 +2644,7 @@ function resolveDefaultLanguage(rawOchre, languages) {
 	}
 	for (const language of languages) if (language === DEFAULT_LANGUAGES[0]) return language;
 	const firstLanguage = languages[0];
-	if (firstLanguage == null) throw new Error("Default language not found");
+	if (firstLanguage == null) throw new Error("Default language not found", { cause: languages });
 	return firstLanguage;
 }
 function parseMetadataPublisher(rawPublisher) {
@@ -2635,11 +2689,11 @@ function inferTopLevelCategory(rawOchre) {
 	for (const category of SET_ITEM_CATEGORIES) if (category in rawOchre) return category;
 	if ("variable" in rawOchre) return "propertyVariable";
 	if ("value" in rawOchre) return "propertyValue";
-	throw new Error("Could not infer OCHRE item category");
+	throw new Error("Could not infer OCHRE item category", { cause: rawOchre });
 }
 function getSingleTopLevelRawItem(items, category) {
-	if (items == null || items.length === 0) throw new Error(`${category} not found`);
-	if (items.length > 1) throw new Error(`Expected one ${category}, received ${items.length}`);
+	if (items == null || items.length === 0) throw new Error(`${category} not found`, { cause: items });
+	if (items.length > 1) throw new Error(`Expected one ${category}, received ${items.length}`, { cause: items });
 	return items[0];
 }
 function parseTopLevelItem(rawOchre, category, options) {
@@ -2826,10 +2880,12 @@ const XMLContextItem = v.objectWithRest({
 	tree: v.array(XMLContextValue),
 	displayPath: v.string("XMLContextItem: displayPath is string and required")
 }, v.array(XMLContextValue), "XMLContextItem: Shape error");
-const XMLContext = v.array(v.object({
-	context: v.array(XMLContextItem, "XMLContext: context is array of XMLContextItem"),
-	displayPath: v.string("XMLContext: displayPath is string and required")
-}, "XMLContext: Shape error"));
+const XMLEmptyContext = v.object({ payload: v.string("XMLEmptyContext: payload is string and required") }, "XMLEmptyContext: Shape error");
+const XMLContextGroup = v.object({
+	context: v.array(v.union([XMLContextItem, XMLEmptyContext]), "XMLContextGroup: context is array of XMLContextItem or XMLEmptyContext"),
+	displayPath: v.string("XMLContextGroup: displayPath is string and required")
+}, "XMLContextGroup: Shape error");
+const XMLContext = v.array(v.union([XMLContextGroup, XMLEmptyContext], "XMLContext: item is XMLContextGroup or XMLEmptyContext"));
 const XMLEvent = v.object({
 	dateTime: v.optional(customDateTime("XMLEvent: dateTime is not a valid datetime")),
 	endDateTime: v.optional(customDateTime("XMLEvent: endDateTime is not a valid datetime")),
@@ -3612,13 +3668,13 @@ async function fetchGallery(params, options) {
 			}),
 			headers: { "Content-Type": "application/xquery" }
 		});
-		if (!response.ok) throw new Error("Error fetching gallery items, please try again later.");
+		if (!response.ok) throw new Error("Error fetching gallery items, please try again later.", { cause: response.statusText });
 		const dataRaw = await response.text();
 		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
 		const { success, issues, output } = v.safeParse(XMLGalleryData, data);
 		if (!success) {
 			logIssues(issues);
-			throw new Error("Failed to parse gallery XML");
+			throw createSchemaValidationError("Failed to parse gallery XML", issues);
 		}
 		restoreXMLMetadata(output, data);
 		return {
@@ -3722,13 +3778,13 @@ async function fetchItemLinks(uuid, options) {
 			body: buildXQuery$2(parsedUuid),
 			headers: { "Content-Type": "application/xquery" }
 		});
-		if (!response.ok) throw new Error("Failed to fetch OCHRE item links");
+		if (!response.ok) throw new Error("Failed to fetch OCHRE item links", { cause: response.statusText });
 		const dataRaw = await response.text();
 		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
 		const { success, issues, output } = v.safeParse(XMLItemLinksData, data);
 		if (!success) {
 			logIssues(issues);
-			throw new Error("Failed to parse OCHRE item links");
+			throw createSchemaValidationError("Failed to parse OCHRE item links", issues);
 		}
 		restoreXMLMetadata(output, data);
 		const languages = resolveItemLinksLanguages(output, requestedLanguages);
@@ -3788,7 +3844,7 @@ function inferFetchItemCategory(rawOchre) {
 	if ("resource" in rawOchre) return "resource";
 	if ("text" in rawOchre) return "text";
 	if ("set" in rawOchre) return "set";
-	throw new Error("Could not infer OCHRE item category");
+	throw new Error("Could not infer OCHRE item category", { cause: rawOchre });
 }
 /**
 * Validate language codes while preserving literal tuple inference.
@@ -3823,13 +3879,13 @@ async function fetchItem(uuid, options) {
 		assertItemCategoryAllowed(options?.category, options?.containedItemCategory);
 		const languages = options?.languages == null ? [] : parseLanguages$1(options.languages);
 		const response = await (options?.fetch ?? fetch)(`https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?uuid=${parsedUuid}&xsl=none&lang="*"`);
-		if (!response.ok) throw new Error("Failed to fetch OCHRE data");
+		if (!response.ok) throw new Error("Failed to fetch OCHRE data", { cause: response.statusText });
 		const dataRaw = await response.text();
 		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
 		const { success, issues, output } = v.safeParse(XMLData, data);
 		if (!success) {
 			logIssues(issues);
-			throw new Error("Failed to parse OCHRE data");
+			throw createSchemaValidationError("Failed to parse OCHRE data", issues);
 		}
 		restoreXMLMetadata(output, data);
 		const category = options?.category ?? inferFetchItemCategory(output.result.ochre);
@@ -4514,7 +4570,7 @@ function buildLeafQueryExpression(context, query) {
 	if (query.target === "property" && query.dataType !== "date" && query.dataType !== "dateTime" && !("value" in query) && query.propertyVariable != null) return buildPropertyPresenceQueryExpression({ propertyVariable: query.propertyVariable });
 	if (query.target === "property" && (query.dataType === "date" || query.dataType === "dateTime") && query.value == null) return buildPropertyDateRangeQueryExpression(query);
 	const searchValue = getLeafSearchValue(query);
-	if (searchValue == null) throw new Error("Missing searchable value for query leaf");
+	if (searchValue == null) throw new Error("Missing searchable value for query leaf", { cause: query });
 	const exactHelper = registerLeafHelper({
 		context,
 		query,
@@ -4589,9 +4645,9 @@ function getCompatibleIncludesGroupLeaves(query) {
 }
 function buildIncludesGroupQueryExpression(context, queries) {
 	const firstQuery = queries[0];
-	if (firstQuery == null) throw new Error("Cannot build an includes group without queries");
+	if (firstQuery == null) throw new Error("Cannot build an includes group without queries", { cause: queries });
 	const groupValue = getGroupableIncludesValue(firstQuery);
-	if (groupValue == null) throw new Error("Cannot build an includes group without a search value");
+	if (groupValue == null) throw new Error("Cannot build an includes group without a search value", { cause: firstQuery });
 	const terms = tokenizeIncludesSearchValue({
 		value: groupValue,
 		isCaseSensitive: firstQuery.isCaseSensitive
@@ -4897,18 +4953,18 @@ async function fetchSetItems(params, containedItemCategories, options) {
 			body: xquery,
 			headers: { "Content-Type": "application/xquery" }
 		});
-		if (!response.ok) throw new Error(`OCHRE API responded with status: ${response.status}`);
+		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(XMLSetItemsData, data);
 		if (!success) {
 			logIssues(issues);
-			throw new Error("Failed to parse OCHRE Set items");
+			throw createSchemaValidationError("Failed to parse OCHRE Set items", issues);
 		}
 		restoreXMLMetadata(output, data);
 		if (containedItemCategories != null) {
 			const missingCategories = containedItemCategories.filter((category) => !hasSetItemsCategory(output.result.ochre.items, category));
-			if (missingCategories.length > 0) throw new Error(`No Set items found for item categories: ${missingCategories.join(", ")}`);
+			if (missingCategories.length > 0) throw new Error(`No Set items found for item categories: ${missingCategories.join(", ")}`, { cause: missingCategories });
 		}
 		const languages = resolveSetItemsLanguages(output, requestedLanguages);
 		const items = parseSetItems(output.result.ochre.items, {
@@ -5374,13 +5430,13 @@ async function fetchSetPropertyValues(params, options) {
 			body: xquery,
 			headers: { "Content-Type": "application/xquery" }
 		});
-		if (!response.ok) throw new Error(`OCHRE API responded with status: ${response.status}`);
+		if (!response.ok) throw new Error(`OCHRE API responded with status: ${response.status}`, { cause: response.statusText });
 		const dataRaw = await response.text();
 		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
 		const { success, issues, output } = v.safeParse(responseSchema, data);
 		if (!success) {
 			logIssues(issues);
-			throw new Error("Failed to parse OCHRE Set property values");
+			throw createSchemaValidationError("Failed to parse OCHRE Set property values", issues);
 		}
 		const parsedPropertyValues = [];
 		const parsedAttributeValues = [];
@@ -5794,7 +5850,7 @@ var WebsitePresentationReader = class WebsitePresentationReader {
 	}
 	requiredProperty(label, message) {
 		const property = this.property(label);
-		if (property === null) throw new Error(message);
+		if (property === null) throw new Error(message, { cause: this.sourceProperties });
 		return property;
 	}
 	propertyByValue(label, value) {
@@ -5942,7 +5998,7 @@ function parseResponsiveCssStyles(properties) {
 */
 function parseBounds(bounds) {
 	const [southWest, northEast] = bounds.trim().startsWith("[") ? parseJsonBounds(bounds) : bounds.split(";").map((pair) => pair.split(",").map((coordinate) => Number.parseFloat(coordinate.trim())));
-	if (southWest?.length !== 2 || northEast?.length !== 2 || southWest.some((coordinate) => Number.isNaN(coordinate)) || northEast.some((coordinate) => Number.isNaN(coordinate))) throw new Error(`Invalid bounds: ${bounds}`);
+	if (southWest?.length !== 2 || northEast?.length !== 2 || southWest.some((coordinate) => Number.isNaN(coordinate)) || northEast.some((coordinate) => Number.isNaN(coordinate))) throw new Error(`Invalid bounds: ${bounds}`, { cause: bounds });
 	return [[southWest[0], southWest[1]], [northEast[0], northEast[1]]];
 }
 function parseJsonBounds(bounds) {
@@ -5950,9 +6006,9 @@ function parseJsonBounds(bounds) {
 	try {
 		parsed = JSON.parse(bounds);
 	} catch {
-		throw new Error(`Invalid bounds: ${bounds}`);
+		throw new Error(`Invalid bounds: ${bounds}`, { cause: bounds });
 	}
-	if (!isNumberPairArray(parsed)) throw new Error(`Invalid bounds: ${bounds}`);
+	if (!isNumberPairArray(parsed)) throw new Error(`Invalid bounds: ${bounds}`, { cause: bounds });
 	return parsed;
 }
 function isNumberPairArray(value) {
@@ -6030,7 +6086,7 @@ function parseStylesheets(styles) {
 			mobile: []
 		};
 		if (style.category === "propertyValue" || style.valueUuid != null) {
-			if (style.valueUuid == null) throw new Error(`Stylesheet property value "${style.variableUuid}" is missing a value UUID`);
+			if (style.valueUuid == null) throw new Error(`Stylesheet property value "${style.variableUuid}" is missing a value UUID`, { cause: style });
 			parsedStyles.push({
 				uuid: style.valueUuid,
 				category: "propertyValue",
@@ -6066,7 +6122,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 	switch (componentName) {
 		case "3d-viewer": {
 			const resourceLink = findWebsiteLink(websiteLinks, "resource", (link) => link.fileFormat === "model/obj");
-			if (resourceLink == null) throw new Error(formatComponentError("Resource link not found", componentName, elementResource));
+			if (resourceLink == null) throw new Error(formatComponentError("Resource link not found", componentName, elementResource), { cause: componentProperty });
 			const isInteractive = componentReader.valueOr("is-interactive", true);
 			const isControlsDisplayed = componentReader.valueOr("controls-displayed", true);
 			properties = {
@@ -6081,7 +6137,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		case "advanced-search": {
 			const boundElementPropertyUuid = componentReader.uuid("bound-element");
 			const href = componentReader.linkTarget("link-to", transformPermanentIdentificationUrlToItemLink);
-			if (boundElementPropertyUuid == null && href == null) throw new Error(formatComponentError("Bound element or href not found", componentName, elementResource));
+			if (boundElementPropertyUuid == null && href == null) throw new Error(formatComponentError("Bound element or href not found", componentName, elementResource), { cause: componentProperty });
 			properties = {
 				component: "advanced-search",
 				boundElementUuid: boundElementPropertyUuid,
@@ -6091,7 +6147,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "annotated-document": {
 			const documentLink = findWebsiteLink(websiteLinks, "resource", (link) => link.type === "internalDocument");
-			if (documentLink == null) throw new Error(formatComponentError("Document link not found", componentName, elementResource));
+			if (documentLink == null) throw new Error(formatComponentError("Document link not found", componentName, elementResource), { cause: componentProperty });
 			properties = {
 				component: "annotated-document",
 				linkUuid: documentLink.uuid
@@ -6100,7 +6156,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "annotated-image": {
 			const imageLinks = getWebsiteLinks(websiteLinks, "resource").filter((link) => link.type === "image" || link.type === "IIIF");
-			if (imageLinks.length === 0) throw new Error(formatComponentError("Image link not found", componentName, elementResource));
+			if (imageLinks.length === 0) throw new Error(formatComponentError("Image link not found", componentName, elementResource), { cause: componentProperty });
 			const isFilterInputDisplayed = componentReader.valueOr("filter-input-displayed", true);
 			const isOptionsDisplayed = componentReader.valueOr("options-displayed", true);
 			const isAnnotationHighlightsDisplayed = componentReader.valueOr("annotation-highlights-displayed", true);
@@ -6117,7 +6173,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "audio-player": {
 			const audioLink = findWebsiteLink(websiteLinks, "resource", (link) => link.type === "audio");
-			if (audioLink == null) throw new Error(formatComponentError("Audio link not found", componentName, elementResource));
+			if (audioLink == null) throw new Error(formatComponentError("Audio link not found", componentName, elementResource), { cause: componentProperty });
 			const isSpeedControlsDisplayed = componentReader.valueOr("speed-controls-displayed", true);
 			const isVolumeControlsDisplayed = componentReader.valueOr("volume-controls-displayed", true);
 			const isSeekBarDisplayed = componentReader.valueOr("seek-bar-displayed", true);
@@ -6133,7 +6189,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		case "bibliography": {
 			const itemLinks = websiteLinks.filter((link) => link.category !== "bibliography");
 			const bibliographies = parseBibliographyList(elementResource.bibliographies, options);
-			if (itemLinks.length === 0 && bibliographies.length === 0) throw new Error(formatComponentError("No links found", componentName, elementResource));
+			if (itemLinks.length === 0 && bibliographies.length === 0) throw new Error(formatComponentError("No links found", componentName, elementResource), { cause: componentProperty });
 			const layout = componentReader.valueOr("layout", "long");
 			const isSourceDocumentDisplayed = componentReader.valueOr("source-document-displayed", true);
 			properties = {
@@ -6151,7 +6207,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 			let href = componentReader.linkTarget("navigate-to", transformPermanentIdentificationUrlToItemLink);
 			if (href === null) {
 				href = componentReader.linkTarget("link-to", transformPermanentIdentificationUrlToItemLink);
-				if (href === null) throw new Error(formatComponentError("Properties “navigate-to” or “link-to” not found", componentName, elementResource));
+				if (href === null) throw new Error(formatComponentError("Properties “navigate-to” or “link-to” not found", componentName, elementResource), { cause: componentProperty });
 				else isExternal = true;
 			}
 			const startIcon = componentReader.value("start-icon");
@@ -6180,7 +6236,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "collection": {
 			const setLinks = getWebsiteLinks(websiteLinks, "set");
-			if (setLinks.length === 0) throw new Error(formatComponentError("Set links not found", componentName, elementResource));
+			if (setLinks.length === 0) throw new Error(formatComponentError("Set links not found", componentName, elementResource), { cause: componentProperty });
 			const displayedProperties = componentReader.property("use-property");
 			const variant = componentReader.valueOr("variant", "slide");
 			const paginationVariant = componentReader.valueOr("pagination-variant", "default");
@@ -6229,7 +6285,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 			break;
 		case "entries": {
 			const entriesLink = findWebsiteLinkByCategories(websiteLinks, ["set", "tree"]);
-			if (entriesLink == null) throw new Error(formatComponentError("Entries link not found", componentName, elementResource));
+			if (entriesLink == null) throw new Error(formatComponentError("Entries link not found", componentName, elementResource), { cause: componentProperty });
 			const variant = componentReader.valueOr("variant", "entry");
 			const isFilterInputDisplayed = componentReader.valueOr("filter-input-displayed", false);
 			properties = {
@@ -6242,7 +6298,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "iframe": {
 			const webpageLink = findWebsiteLink(websiteLinks, "resource", (link) => link.type === "webpage");
-			if (webpageLink?.href == null) throw new Error(formatComponentError("URL not found", componentName, elementResource));
+			if (webpageLink?.href == null) throw new Error(formatComponentError("URL not found", componentName, elementResource), { cause: componentProperty });
 			properties = {
 				component: "iframe",
 				href: transformPermanentIdentificationUrlToItemLink(webpageLink.href),
@@ -6253,7 +6309,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "iiif-viewer": {
 			const manifestLink = findWebsiteLink(websiteLinks, "resource", (link) => link.type === "IIIF");
-			if (manifestLink == null) throw new Error(formatComponentError("Manifest link not found", componentName, elementResource));
+			if (manifestLink == null) throw new Error(formatComponentError("Manifest link not found", componentName, elementResource), { cause: componentProperty });
 			const variant = componentReader.valueOr("variant", "universal-viewer");
 			properties = {
 				component: "iiif-viewer",
@@ -6263,7 +6319,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 			break;
 		}
 		case "image": {
-			if (websiteLinks.length === 0) throw new Error(formatComponentError("No links found", componentName, elementResource));
+			if (websiteLinks.length === 0) throw new Error(formatComponentError("No links found", componentName, elementResource), { cause: componentProperty });
 			const imageQuality = componentReader.valueOr("image-quality", "high");
 			const images = [];
 			for (const link of websiteLinks) images.push({
@@ -6333,7 +6389,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "image-gallery": {
 			const galleryLink = findWebsiteLinkByCategories(websiteLinks, ["set", "tree"]);
-			if (galleryLink == null) throw new Error(formatComponentError("Image gallery link not found", componentName, elementResource));
+			if (galleryLink == null) throw new Error(formatComponentError("Image gallery link not found", componentName, elementResource), { cause: componentProperty });
 			const isFilterInputDisplayed = componentReader.valueOr("filter-input-displayed", true);
 			properties = {
 				component: "image-gallery",
@@ -6344,7 +6400,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "map": {
 			const mapLink = findWebsiteLinkByCategories(websiteLinks, ["set", "tree"]);
-			if (mapLink == null) throw new Error(formatComponentError("Map link not found", componentName, elementResource));
+			if (mapLink == null) throw new Error(formatComponentError("Map link not found", componentName, elementResource), { cause: componentProperty });
 			const isInteractive = componentReader.valueOr("is-interactive", true);
 			const isClustered = componentReader.valueOr("is-clustered", false);
 			const isUsingPins = componentReader.valueOr("is-using-pins", false);
@@ -6373,9 +6429,9 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "query": {
 			const setLinks = getWebsiteLinks(websiteLinks, "set");
-			if (setLinks.length === 0) throw new Error(formatComponentError("Set links not found", componentName, elementResource));
+			if (setLinks.length === 0) throw new Error(formatComponentError("Set links not found", componentName, elementResource), { cause: componentProperty });
 			const items = [];
-			if (componentProperty.properties.length === 0) throw new Error(formatComponentError("Query properties not found", componentName, elementResource));
+			if (componentProperty.properties.length === 0) throw new Error(formatComponentError("Query properties not found", componentName, elementResource), { cause: componentProperty });
 			for (const queryItem of componentProperty.properties) {
 				const queryReader = websitePresentationReader(queryItem.properties);
 				const label = queryReader.multilingualValue("query-prompt", options);
@@ -6385,9 +6441,9 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 				if (queryLanguage == null) throw new Error(formatComponentError("Query language not found", componentName, elementResource));
 				const queries = [];
 				for (const propertyVariable of propertyVariables) {
-					if (propertyVariable.uuid === null) throw new Error(formatComponentError("Property variable UUID not found", componentName, elementResource));
+					if (propertyVariable.uuid === null) throw new Error(formatComponentError("Property variable UUID not found", componentName, elementResource), { cause: propertyVariable });
 					const dataType = propertyVariable.dataType;
-					if (dataType === "coordinate") throw new Error(formatComponentError("Query prompts with data type \"coordinate\" are not supported", componentName, elementResource));
+					if (dataType === "coordinate") throw new Error(formatComponentError("Query prompts with data type \"coordinate\" are not supported", componentName, elementResource), { cause: propertyVariable });
 					queries.push({
 						target: "property",
 						propertyVariable: propertyVariable.uuid,
@@ -6406,7 +6462,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 					endIcon
 				});
 			}
-			if (items.length === 0) throw new Error(formatComponentError("No queries found", componentName, elementResource));
+			if (items.length === 0) throw new Error(formatComponentError("No queries found", componentName, elementResource), { cause: componentProperty });
 			const componentOptions = parseWebsiteOptions(elementResource.options, options);
 			const displayedProperties = componentReader.property("use-property");
 			const variant = componentReader.valueOr("variant", "slide");
@@ -6433,7 +6489,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "table": {
 			const tableLink = findWebsiteLink(websiteLinks, "set");
-			if (tableLink == null) throw new Error(formatComponentError("Table link not found", componentName, elementResource));
+			if (tableLink == null) throw new Error(formatComponentError("Table link not found", componentName, elementResource), { cause: componentProperty });
 			properties = {
 				component: "table",
 				linkUuid: tableLink.uuid
@@ -6444,7 +6500,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 			const queryVariant = componentReader.valueOr("query-variant", "submit");
 			const boundElementUuid = componentReader.uuid("bound-element");
 			const href = componentReader.linkTarget("link-to", transformPermanentIdentificationUrlToItemLink);
-			if (!boundElementUuid && !href) throw new Error(formatComponentError("Bound element or href not found", componentName, elementResource));
+			if (!boundElementUuid && !href) throw new Error(formatComponentError("Bound element or href not found", componentName, elementResource), { cause: componentProperty });
 			properties = {
 				component: "search-bar",
 				queryVariant,
@@ -6457,7 +6513,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "text": {
 			const content = elementResource.document && "content" in elementResource.document ? parseXMLContent(elementResource.document, options) : null;
-			if (content == null) throw new Error(formatComponentError("Content not found", componentName, elementResource));
+			if (content == null) throw new Error(formatComponentError("Content not found", componentName, elementResource), { cause: componentProperty });
 			let variantName = "block";
 			let variant;
 			const variantProperty = componentReader.property("variant");
@@ -6503,7 +6559,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "timeline": {
 			const timelineLink = findWebsiteLink(websiteLinks, "tree");
-			if (timelineLink == null) throw new Error(formatComponentError("Timeline link not found", componentName, elementResource));
+			if (timelineLink == null) throw new Error(formatComponentError("Timeline link not found", componentName, elementResource), { cause: componentProperty });
 			properties = {
 				component: "timeline",
 				linkUuid: timelineLink.uuid
@@ -6512,7 +6568,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "video": {
 			const videoLink = findWebsiteLink(websiteLinks, "resource", (link) => link.type === "video");
-			if (videoLink == null) throw new Error(formatComponentError("Video link not found", componentName, elementResource));
+			if (videoLink == null) throw new Error(formatComponentError("Video link not found", componentName, elementResource), { cause: componentProperty });
 			const isChaptersDisplayed = componentReader.valueOr("chapters-displayed", true);
 			properties = {
 				component: "video",
@@ -6525,7 +6581,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 			console.warn(`Invalid or non-implemented component name “${unparsedComponentName.toString()}” for the following element: “${parseStringContent(elementResource.identification.label, options)}”`);
 			break;
 	}
-	if (properties === null) throw new Error(formatComponentError("Properties not found", componentName, elementResource));
+	if (properties === null) throw new Error(formatComponentError("Properties not found", componentName, elementResource), { cause: componentProperty });
 	return properties;
 }
 function parseWebTitle(properties, identification, overrides) {
@@ -6586,7 +6642,7 @@ function parseWebpage(webpageResource, options, context, slugPrefix) {
 	if (webpageReader.value("presentation") !== "page") return null;
 	const identification = parseIdentification(webpageResource.identification, options);
 	const slug = webpageResource.slug?.replace(SEGMENT_UNIQUE_SLUG_PREFIX_REGEX, "") ?? null;
-	if (slug == null) throw new Error(`Slug not found for page (${formatXMLWebsiteResourceMetadata(webpageResource)})`);
+	if (slug == null) throw new Error(`Slug not found for page (${formatXMLWebsiteResourceMetadata(webpageResource)})`, { cause: webpageResource });
 	const returnWebpage = {
 		uuid: webpageResource.uuid,
 		type: "page",
@@ -6673,7 +6729,7 @@ function parseWebsiteSegments(resources, context, options, slugPrefix) {
 		if (!("segments" in resource)) continue;
 		for (const tree of resource.segments.tree) {
 			const segmentSlug = tree.identification.abbreviation == null ? null : parseStringContent(tree.identification.abbreviation, options);
-			if (segmentSlug == null) throw new Error(`Slug not found for segment website (website uuid “${tree.uuid}”)`);
+			if (segmentSlug == null) throw new Error(`Slug not found for segment website (website uuid “${tree.uuid}”)`, { cause: tree });
 			segments.push(parseWebsiteTree(tree, context, "segment", options, prefixSlug(segmentSlug, slugPrefix)));
 		}
 	}
@@ -6854,9 +6910,9 @@ function parseWebBlock(blockResource, options) {
 		for (const resource of blockResources) {
 			const resourceReader = websitePresentationReader(resource.properties ? parseSimplifiedProperties(resource.properties, options) : []);
 			const resourceType = resourceReader.value("presentation");
-			if (resourceType !== "element") throw new Error(`Accordion only accepts elements, but got “${resourceType}” (${formatXMLWebsiteResourceMetadata(resource)})`);
+			if (resourceType !== "element") throw new Error(`Accordion only accepts elements, but got “${resourceType}” (${formatXMLWebsiteResourceMetadata(resource)})`, { cause: resource });
 			const componentType = resourceReader.nestedByValue("presentation", "element").value("component");
-			if (componentType !== "text") throw new Error(`Accordion only accepts text components, but got “${componentType}” (${formatXMLWebsiteResourceMetadata(resource)})`);
+			if (componentType !== "text") throw new Error(`Accordion only accepts text components, but got “${componentType}” (${formatXMLWebsiteResourceMetadata(resource)})`, { cause: resource });
 			const element = parseWebElementForAccordion(resource, options);
 			accordionItems.push(element);
 		}
@@ -6950,7 +7006,7 @@ function parseWebsiteProperties(properties, websiteTree, sidebar, options) {
 			name: contactContent[0],
 			email: contactContent[1] ?? null
 		};
-		else throw new Error(`Contact property must use “name;email”, got “${contactProperty.values[0]?.content}” (website uuid “${websiteTree.uuid}”)`);
+		else throw new Error(`Contact property must use “name;email”, got “${contactProperty.values[0]?.content}” (website uuid “${websiteTree.uuid}”)`, { cause: websiteTree });
 	}
 	returnProperties.loadingVariant = websiteReader.valueOr("loading-variant", "spinner");
 	returnProperties.theme.isThemeToggleDisplayed = websiteReader.valueOr("supports-theme-toggle", true);
@@ -7056,8 +7112,8 @@ function parseFilterContexts(filterContextLevels, options) {
 	return filterContextTreeLevels;
 }
 function parseWebsiteTree(websiteTree, context, type, options, slugPrefix) {
-	if (!websiteTree.properties) throw new Error(`Website properties not found (website uuid “${websiteTree.uuid}”)`);
-	if (type === "website" && websiteTree.items?.resource == null) throw new Error(`Website pages not found (website uuid “${websiteTree.uuid}”)`);
+	if (!websiteTree.properties) throw new Error(`Website properties not found (website uuid “${websiteTree.uuid}”)`, { cause: websiteTree });
+	if (type === "website" && websiteTree.items?.resource == null) throw new Error(`Website pages not found (website uuid “${websiteTree.uuid}”)`, { cause: websiteTree });
 	const resources = normalizeWebsiteResources(websiteTree.items?.resource);
 	const sidebar = parseSidebar(resources, options);
 	const properties = parseWebsiteProperties(websiteTree.properties.property, websiteTree, sidebar, options);
@@ -7081,7 +7137,7 @@ function parseWebsite(data, options) {
 	const parserOptions = { languages };
 	const defaultLanguage = resolveDefaultLanguage(rawOchre, languages);
 	const websiteTree = rawOchre.tree[0];
-	if (websiteTree == null) throw new Error("Website tree not found");
+	if (websiteTree == null) throw new Error("Website tree not found", { cause: data });
 	return parseWebsiteTree(websiteTree, {
 		belongsTo: {
 			uuid: rawOchre.uuidBelongsTo,
@@ -7102,13 +7158,13 @@ async function fetchWebsite(abbreviation, options) {
 	try {
 		const cleanAbbreviation = abbreviation.trim().toLocaleLowerCase("en-US");
 		const response = await (options?.fetch ?? fetch)(`https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery=${encodeURIComponent(`collection('ochre/tree')/ochre[tree/identification/abbreviation/content/string='${cleanAbbreviation}']`)}&xsl=none&lang="*"`);
-		if (!response.ok) throw new Error("Failed to fetch website");
+		if (!response.ok) throw new Error("Failed to fetch website", { cause: response.statusText });
 		const dataRaw = await response.text();
 		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
 		const { success, issues, output } = v.safeParse(XMLWebsiteData, data);
 		if (!success) {
 			logIssues(issues);
-			throw new Error("Failed to parse website XML");
+			throw createSchemaValidationError("Failed to parse website XML", issues);
 		}
 		restoreXMLMetadata(output, data);
 		return {

package/package.json

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