@digitalculture/ochre-sdk 0.11.28 → 0.12.1

package/dist/index.d.mts

@@ -524,6 +524,7 @@ type LevelContext = {
  */
 type Website = {
   uuid: string;
+  version: 1 | 2;
   publicationDateTime: Date | null;
   identification: Identification;
   project: {
@@ -545,33 +546,6 @@ type Website = {
     };
   } | null;
   properties: WebsiteProperties;
-  searchOptions: {
-    filters: Array<{
-      uuid: string;
-      type: string;
-    }>;
-    attributeFilters: {
-      bibliographies: boolean;
-      periods: boolean;
-    };
-    scopes: Array<{
-      uuid: string;
-      type: string;
-      identification: Identification;
-    }>;
-  };
-  globalOptions: {
-    contexts: {
-      flatten: Array<LevelContext>;
-      suppress: Array<LevelContext>;
-      filter: Array<LevelContext>;
-      sort: Array<LevelContext>;
-      detail: Array<LevelContext>;
-      download: Array<LevelContext>;
-      label: Array<LevelContext>;
-      prominent: Array<LevelContext>;
-    };
-  };
 };
 /**
  * Properties for configuring website display and styling
@@ -691,6 +665,27 @@ type WebElementComponent = {
   isFilterDisplayed: boolean;
   filterSort: "default" | "alphabetical";
   layout: "image-top" | "image-bottom" | "image-start" | "image-end";
+  options: {
+    attributeFilters: {
+      bibliographies: boolean;
+      periods: boolean;
+    };
+    scopes: Array<{
+      uuid: string;
+      type: string;
+      identification: Identification;
+    }>;
+    contexts: {
+      flatten: Array<LevelContext>;
+      suppress: Array<LevelContext>;
+      filter: Array<LevelContext>;
+      sort: Array<LevelContext>;
+      detail: Array<LevelContext>;
+      download: Array<LevelContext>;
+      label: Array<LevelContext>;
+      prominent: Array<LevelContext>;
+    };
+  };
 } | {
   component: "empty-space";
   height: string | null;
@@ -786,6 +781,7 @@ type WebElementComponent = {
  * Represents an image used in web elements
  */
 type WebImage = {
+  uuid: string | null;
   url: string;
   label: string | null;
   description: string | null;
@@ -914,7 +910,10 @@ declare function fetchGallery(uuid: string, filter: string, page: number, perPag
  *
  * If the fetch/parse fails, the returned object will have an `error` property.
  */
-declare function fetchItem<T extends DataCategory, U extends DataCategory>(uuid: string, category?: T, setCategory?: T extends "set" ? U : never, customFetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>): Promise<{
+declare function fetchItem<T extends DataCategory, U extends DataCategory>(uuid: string, category?: T, setCategory?: T extends "set" ? U : never, options?: {
+  customFetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
+  isVersion2: boolean;
+}): Promise<{
   error: null;
   metadata: Metadata;
   belongsTo: {
@@ -937,7 +936,9 @@ declare function fetchItem<T extends DataCategory, U extends DataCategory>(uuid:
  *
  * @param scopeUuids - The scope UUIDs to filter by
  * @param propertyUuids - The property UUIDs to query by
- * @param customFetch - A custom fetch function to use instead of the default fetch
+ * @param options - Options for the fetch
+ * @param options.customFetch - A custom fetch function to use instead of the default fetch
+ * @param options.isVersion2 - Whether to use the v2 API
  * @returns The parsed property query or null if the fetch/parse fails
  *
  * @example
@@ -954,7 +955,10 @@ declare function fetchItem<T extends DataCategory, U extends DataCategory>(uuid:
  * The returned property query includes:
  * - Property items
  */
-declare function fetchPropertyQuery(scopeUuids: Array<string>, propertyUuids: Array<string>, customFetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>): Promise<{
+declare function fetchPropertyQuery(scopeUuids: Array<string>, propertyUuids: Array<string>, options?: {
+  customFetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
+  isVersion2?: boolean;
+}): Promise<{
   items: Array<PropertyQueryItem> | null;
   error: null;
 } | {
@@ -1014,7 +1018,10 @@ declare function fetchByUuidMetadata(uuid: string, customFetch?: (input: string
  *
  * The abbreviation is case-insensitive and should match the website's configured abbreviation in OCHRE.
  */
-declare function fetchWebsite(abbreviation: string, customFetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>): Promise<[null, Website] | [string, null]>;
+declare function fetchWebsite(abbreviation: string, options?: {
+  customFetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
+  isVersion2?: boolean;
+}): Promise<[null, Website] | [string, null]>;
 //#endregion
 //#region src/utils/getters.d.ts
 /**

package/dist/index.mjs

@@ -1,4 +1,5 @@
-import { z } from "zod";
+import * as z from "zod";
+import { writeFileSync } from "node:fs";
 
 //#region src/schemas.ts
 /**
@@ -1766,6 +1767,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			let image = null;
 			const imageLink = links.find((link) => link.type === "image" || link.type === "IIIF");
 			if (imageLink != null) image = {
+				uuid: imageLink.uuid,
 				url: `https://ochre.lib.uchicago.edu/ochre?uuid=${imageLink.uuid}&load`,
 				label: imageLink.identification?.label ?? null,
 				width: imageLink.image?.width ?? 0,
@@ -1800,6 +1802,47 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			filterSort ??= "default";
 			let layout = getPropertyValueByLabel(componentProperty.properties, "layout");
 			layout ??= "image-start";
+			const options = {
+				attributeFilters: {
+					bibliographies: elementResource.options?.filterBibliography ?? false,
+					periods: elementResource.options?.filterPeriods ?? false
+				},
+				scopes: elementResource.options?.scopes != null ? (Array.isArray(elementResource.options.scopes.scope) ? elementResource.options.scopes.scope : [elementResource.options.scopes.scope]).map((scope) => ({
+					uuid: scope.uuid.content,
+					type: scope.uuid.type,
+					identification: parseIdentification(scope.identification)
+				})) : [],
+				contexts: {
+					flatten: [],
+					filter: [],
+					sort: [],
+					detail: [],
+					download: [],
+					label: [],
+					suppress: [],
+					prominent: []
+				}
+			};
+			if ("options" in elementResource && elementResource.options) {
+				const flattenContextsRaw = elementResource.options.flattenContexts != null ? Array.isArray(elementResource.options.flattenContexts) ? elementResource.options.flattenContexts : [elementResource.options.flattenContexts] : [];
+				const suppressContextsRaw = elementResource.options.suppressContexts != null ? Array.isArray(elementResource.options.suppressContexts) ? elementResource.options.suppressContexts : [elementResource.options.suppressContexts] : [];
+				const filterContextsRaw = elementResource.options.filterContexts != null ? Array.isArray(elementResource.options.filterContexts) ? elementResource.options.filterContexts : [elementResource.options.filterContexts] : [];
+				const sortContextsRaw = elementResource.options.sortContexts != null ? Array.isArray(elementResource.options.sortContexts) ? elementResource.options.sortContexts : [elementResource.options.sortContexts] : [];
+				const detailContextsRaw = elementResource.options.detailContexts != null ? Array.isArray(elementResource.options.detailContexts) ? elementResource.options.detailContexts : [elementResource.options.detailContexts] : [];
+				const downloadContextsRaw = elementResource.options.downloadContexts != null ? Array.isArray(elementResource.options.downloadContexts) ? elementResource.options.downloadContexts : [elementResource.options.downloadContexts] : [];
+				const labelContextsRaw = elementResource.options.labelContexts != null ? Array.isArray(elementResource.options.labelContexts) ? elementResource.options.labelContexts : [elementResource.options.labelContexts] : [];
+				const prominentContextsRaw = elementResource.options.prominentContexts != null ? Array.isArray(elementResource.options.prominentContexts) ? elementResource.options.prominentContexts : [elementResource.options.prominentContexts] : [];
+				options.contexts = {
+					flatten: parseContexts(flattenContextsRaw),
+					filter: parseContexts(filterContextsRaw),
+					sort: parseContexts(sortContextsRaw),
+					detail: parseContexts(detailContextsRaw),
+					download: parseContexts(downloadContextsRaw),
+					label: parseContexts(labelContextsRaw),
+					suppress: parseContexts(suppressContextsRaw),
+					prominent: parseContexts(prominentContextsRaw)
+				};
+			}
 			properties.collectionId = collectionLink.uuid;
 			properties.variant = variant;
 			properties.itemVariant = itemVariant;
@@ -1808,6 +1851,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			properties.isFilterDisplayed = isFilterDisplayed;
 			properties.filterSort = filterSort;
 			properties.layout = layout;
+			properties.options = options;
 			break;
 		}
 		case "empty-space": {
@@ -1855,6 +1899,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			imageQuality ??= "high";
 			const images = [];
 			for (const link of links) images.push({
+				uuid: link.uuid,
 				url: `https://ochre.lib.uchicago.edu/ochre?uuid=${link.uuid}${imageQuality === "high" && (link.type === "image" || link.type === "IIIF") ? "&load" : "&preview"}`,
 				label: link.identification?.label ?? null,
 				width: link.image?.width ?? 0,
@@ -2625,72 +2670,27 @@ function parseContexts(contexts) {
 	}
 	return contextsParsed;
 }
-function parseWebsite(websiteTree, projectName, website) {
+function parseWebsite(websiteTree, projectName, website$1, { isVersion2 = false } = {}) {
 	if (!websiteTree.properties) throw new Error("Website properties not found");
 	const properties = parseWebsiteProperties(Array.isArray(websiteTree.properties.property) ? websiteTree.properties.property : [websiteTree.properties.property]);
 	if (typeof websiteTree.items === "string" || !("resource" in websiteTree.items)) throw new Error("Website pages not found");
 	const resources = Array.isArray(websiteTree.items.resource) ? websiteTree.items.resource : [websiteTree.items.resource];
 	const pages = parseWebpages(resources);
 	const sidebar = parseSidebar(resources);
-	let globalOptions = { contexts: {
-		flatten: [],
-		filter: [],
-		sort: [],
-		detail: [],
-		download: [],
-		label: [],
-		suppress: [],
-		prominent: []
-	} };
-	if (websiteTree.websiteOptions) {
-		const flattenContextsRaw = websiteTree.websiteOptions.flattenContexts != null ? Array.isArray(websiteTree.websiteOptions.flattenContexts) ? websiteTree.websiteOptions.flattenContexts : [websiteTree.websiteOptions.flattenContexts] : [];
-		const suppressContextsRaw = websiteTree.websiteOptions.suppressContexts != null ? Array.isArray(websiteTree.websiteOptions.suppressContexts) ? websiteTree.websiteOptions.suppressContexts : [websiteTree.websiteOptions.suppressContexts] : [];
-		const filterContextsRaw = websiteTree.websiteOptions.filterContexts != null ? Array.isArray(websiteTree.websiteOptions.filterContexts) ? websiteTree.websiteOptions.filterContexts : [websiteTree.websiteOptions.filterContexts] : [];
-		const sortContextsRaw = websiteTree.websiteOptions.sortContexts != null ? Array.isArray(websiteTree.websiteOptions.sortContexts) ? websiteTree.websiteOptions.sortContexts : [websiteTree.websiteOptions.sortContexts] : [];
-		const detailContextsRaw = websiteTree.websiteOptions.detailContexts != null ? Array.isArray(websiteTree.websiteOptions.detailContexts) ? websiteTree.websiteOptions.detailContexts : [websiteTree.websiteOptions.detailContexts] : [];
-		const downloadContextsRaw = websiteTree.websiteOptions.downloadContexts != null ? Array.isArray(websiteTree.websiteOptions.downloadContexts) ? websiteTree.websiteOptions.downloadContexts : [websiteTree.websiteOptions.downloadContexts] : [];
-		const labelContextsRaw = websiteTree.websiteOptions.labelContexts != null ? Array.isArray(websiteTree.websiteOptions.labelContexts) ? websiteTree.websiteOptions.labelContexts : [websiteTree.websiteOptions.labelContexts] : [];
-		const prominentContextsRaw = websiteTree.websiteOptions.prominentContexts != null ? Array.isArray(websiteTree.websiteOptions.prominentContexts) ? websiteTree.websiteOptions.prominentContexts : [websiteTree.websiteOptions.prominentContexts] : [];
-		globalOptions = { contexts: {
-			flatten: parseContexts(flattenContextsRaw),
-			filter: parseContexts(filterContextsRaw),
-			sort: parseContexts(sortContextsRaw),
-			detail: parseContexts(detailContextsRaw),
-			download: parseContexts(downloadContextsRaw),
-			label: parseContexts(labelContextsRaw),
-			suppress: parseContexts(suppressContextsRaw),
-			prominent: parseContexts(prominentContextsRaw)
-		} };
-	}
 	return {
 		uuid: websiteTree.uuid,
+		version: isVersion2 ? 2 : 1,
 		publicationDateTime: websiteTree.publicationDateTime ? new Date(websiteTree.publicationDateTime) : null,
 		identification: parseIdentification(websiteTree.identification),
 		project: {
 			name: parseFakeString(projectName),
-			website: website !== null ? parseFakeString(website) : null
+			website: website$1 !== null ? parseFakeString(website$1) : null
 		},
 		creators: websiteTree.creators ? parsePersons(Array.isArray(websiteTree.creators.creator) ? websiteTree.creators.creator : [websiteTree.creators.creator]) : [],
 		license: parseLicense(websiteTree.availability),
 		sidebar,
 		pages,
-		properties,
-		searchOptions: {
-			filters: websiteTree.searchOptions?.filterUuids != null ? (Array.isArray(websiteTree.searchOptions.filterUuids.uuid) ? websiteTree.searchOptions.filterUuids.uuid : [websiteTree.searchOptions.filterUuids.uuid]).map((uuid) => ({
-				uuid: uuid.content,
-				type: uuid.type
-			})) : [],
-			attributeFilters: {
-				bibliographies: websiteTree.searchOptions?.filterUuids?.filterBibliography ?? false,
-				periods: websiteTree.searchOptions?.filterUuids?.filterPeriods ?? false
-			},
-			scopes: websiteTree.searchOptions?.scopes != null ? (Array.isArray(websiteTree.searchOptions.scopes.scope) ? websiteTree.searchOptions.scopes.scope : [websiteTree.searchOptions.scopes.scope]).map((scope) => ({
-				uuid: scope.uuid.content,
-				type: scope.uuid.type,
-				identification: parseIdentification(scope.identification)
-			})) : []
-		},
-		globalOptions
+		properties
 	};
 }
 
@@ -2781,10 +2781,12 @@ async function fetchGallery(uuid, filter, page, perPage, customFetch) {
 *
 * @internal
 */
-async function fetchByUuid(uuid, customFetch) {
+async function fetchByUuid(uuid, options) {
 	try {
+		const customFetch = options?.customFetch;
+		const isVersion2 = options?.isVersion2 ?? false;
 		const parsedUuid = uuidSchema.parse(uuid);
-		const response = await (customFetch ?? fetch)(`https://ochre.lib.uchicago.edu/ochre?uuid=${parsedUuid}&format=json&lang="*"`);
+		const response = await (customFetch ?? fetch)(isVersion2 ? `https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?uuid=${parsedUuid}&format=json&lang="*"` : `https://ochre.lib.uchicago.edu/ochre?uuid=${parsedUuid}&format=json&lang="*"`);
 		if (!response.ok) throw new Error("Failed to fetch OCHRE data");
 		const dataRaw = await response.json();
 		if (!("ochre" in dataRaw)) throw new Error("Invalid OCHRE data: API response missing 'ochre' key");
@@ -2829,9 +2831,13 @@ async function fetchByUuid(uuid, customFetch) {
 *
 * If the fetch/parse fails, the returned object will have an `error` property.
 */
-async function fetchItem(uuid, category, setCategory, customFetch) {
+async function fetchItem(uuid, category, setCategory, options) {
 	try {
-		const [error, data] = await fetchByUuid(uuid, customFetch);
+		const customFetch = options?.customFetch;
+		const [error, data] = await fetchByUuid(uuid, {
+			customFetch,
+			isVersion2: options?.isVersion2 ?? false
+		});
 		if (error !== null) throw new Error(error);
 		const categoryKey = getItemCategory(Object.keys(data.ochre));
 		let item;
@@ -2895,11 +2901,17 @@ async function fetchItem(uuid, category, setCategory, customFetch) {
 	}
 }
 
+//#endregion
+//#region src/constants.ts
+/**
+* The UUID of the `<unassigned>` property value in OCHRE
+*/
+const UNASSIGNED_UUID = "e28e29af-b663-c0ac-ceb6-11a688fca0dd";
+
 //#endregion
 //#region src/utils/fetchers/property-query.ts
 const PROJECT_SCOPE = "0c0aae37-7246-495b-9547-e25dbf5b99a3";
 const BELONG_TO_COLLECTION_UUID = "30054cb2-909a-4f34-8db9-8fe7369d691d";
-const UNASSIGNED_UUID = "e28e29af-b663-c0ac-ceb6-11a688fca0dd";
 /**
 * Check if a string is a valid UUID
 * @param value - The string to check
@@ -2953,7 +2965,9 @@ return <item>
 *
 * @param scopeUuids - The scope UUIDs to filter by
 * @param propertyUuids - The property UUIDs to query by
-* @param customFetch - A custom fetch function to use instead of the default fetch
+* @param options - Options for the fetch
+* @param options.customFetch - A custom fetch function to use instead of the default fetch
+* @param options.isVersion2 - Whether to use the v2 API
 * @returns The parsed property query or null if the fetch/parse fails
 *
 * @example
@@ -2970,10 +2984,12 @@ return <item>
 * The returned property query includes:
 * - Property items
 */
-async function fetchPropertyQuery(scopeUuids, propertyUuids, customFetch) {
+async function fetchPropertyQuery(scopeUuids, propertyUuids, options) {
 	try {
+		const customFetch = options?.customFetch;
+		const isVersion2 = options?.isVersion2 ?? false;
 		const xquery = buildXQuery(scopeUuids, propertyUuids);
-		const response = await (customFetch ?? fetch)(`https://ochre.lib.uchicago.edu/ochre?xquery=${encodeURIComponent(xquery)}&format=json`);
+		const response = await (customFetch ?? fetch)(isVersion2 ? `https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery=${encodeURIComponent(xquery)}&format=json&lang="*"` : `https://ochre.lib.uchicago.edu/ochre?xquery=${encodeURIComponent(xquery)}&format=json&lang="*"`);
 		if (!response.ok) throw new Error(`OCHRE API responded with status: ${response.status}`);
 		const data = await response.json();
 		const parsedResultRaw = responseSchema.parse(data);
@@ -3076,6 +3092,7 @@ const KNOWN_ABBREVIATIONS = {
 	ssmc: "8ff977dd-d440-40f5-ad93-8ad7e2d39e74",
 	"sosc-core-at-smart": "db26c953-9b2a-4691-a909-5e8726b531d7"
 };
+const V2_ABBREVIATIONS = new Set(["bengali-song"]);
 /**
 * Fetches and parses a website configuration from the OCHRE API
 *
@@ -3105,21 +3122,39 @@ const KNOWN_ABBREVIATIONS = {
 *
 * The abbreviation is case-insensitive and should match the website's configured abbreviation in OCHRE.
 */
-async function fetchWebsite(abbreviation, customFetch) {
+async function fetchWebsite(abbreviation, options) {
 	try {
-		const uuid = KNOWN_ABBREVIATIONS[abbreviation.toLocaleLowerCase("en-US")];
-		const response = await (customFetch ?? fetch)(uuid != null ? `https://ochre.lib.uchicago.edu/ochre?uuid=${uuid}&format=json` : `https://ochre.lib.uchicago.edu/ochre?xquery=for $q in input()/ochre[tree[@type='lesson'][identification/abbreviation='${abbreviation.toLocaleLowerCase("en-US")}']] return $q&format=json`);
-		if (!response.ok) throw new Error("Failed to fetch website");
-		const data = await response.json();
-		const result = "result" in data && !Array.isArray(data.result) ? data.result : !("result" in data) ? data : null;
-		if (result == null || !("tree" in result.ochre)) throw new Error("Failed to fetch website");
-		const projectIdentification = result.ochre.metadata.project?.identification ? parseIdentification(result.ochre.metadata.project.identification) : null;
-		return [null, parseWebsite(result.ochre.tree, projectIdentification?.label ?? "", result.ochre.metadata.project?.identification.website ?? null)];
+		const customFetch = options?.customFetch;
+		const isVersion2 = options?.isVersion2 ?? false;
+		const cleanAbbreviation = abbreviation.trim().toLocaleLowerCase("en-US");
+		let metadata = null;
+		let tree = null;
+		if (V2_ABBREVIATIONS.has(cleanAbbreviation) || isVersion2) {
+			const response = await (customFetch ?? fetch)(`https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery=${encodeURIComponent(`collection('ochre/tree')/ochre[tree/identification/abbreviation/content/string='${cleanAbbreviation}']`)}&format=json&lang="*"`);
+			if (!response.ok) throw new Error("Failed to fetch website");
+			const data = await response.json();
+			if (Array.isArray(data.result) || !("tree" in data.result.ochre)) throw new Error("Failed to fetch website");
+			metadata = data.result.ochre.metadata;
+			tree = data.result.ochre.tree;
+		} else {
+			const uuid = KNOWN_ABBREVIATIONS[cleanAbbreviation];
+			const response = await (customFetch ?? fetch)(uuid != null ? `https://ochre.lib.uchicago.edu/ochre?uuid=${uuid}&format=json` : `https://ochre.lib.uchicago.edu/ochre?xquery=${encodeURIComponent(`for $q in input()/ochre[tree[@type='lesson'][identification/abbreviation='${cleanAbbreviation}']] return $q`)}&format=json`);
+			if (!response.ok) throw new Error("Failed to fetch website");
+			const data = await response.json();
+			const result = "result" in data && !Array.isArray(data.result) ? data.result : !("result" in data) ? data : null;
+			if (result == null || !("tree" in result.ochre)) throw new Error("Failed to fetch website");
+			metadata = result.ochre.metadata;
+			tree = result.ochre.tree;
+		}
+		const projectIdentification = metadata.project?.identification ? parseIdentification(metadata.project.identification) : null;
+		return [null, parseWebsite(tree, projectIdentification?.label ?? "", metadata.project?.identification.website ?? null, { isVersion2: true })];
 	} catch (error) {
 		console.error(error);
 		return [error instanceof Error ? error.message : "Unknown error", null];
 	}
 }
+const [_, website] = await fetchWebsite("bengali-song");
+writeFileSync("website.json", JSON.stringify(website, null, 2));
 
 //#endregion
 export { fetchByUuidMetadata, fetchGallery, fetchItem, fetchPropertyQuery, fetchWebsite, filterProperties, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalculture/ochre-sdk",
-  "version": "0.11.28",
+  "version": "0.12.1",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -49,9 +49,9 @@
     "eslint": "^9.39.1",
     "prettier": "^3.6.2",
     "terser": "^5.44.1",
-    "tsdown": "^0.16.0",
+    "tsdown": "^0.16.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.7"
+    "vitest": "^4.0.8"
   },
   "scripts": {
     "dev": "tsdown src/index.ts --watch",