ochre-sdk 0.22.21 → 0.22.22

package/dist/index.d.mts

@@ -1288,6 +1288,29 @@ 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
@@ -1601,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
@@ -5495,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.21",
+  "version": "0.22.22",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",