@digitalculture/ochre-sdk 0.16.10 → 0.16.12

package/dist/index.d.mts

@@ -660,12 +660,13 @@ type Scope = {
   type: string;
   identification: Identification;
 };
+type ApiVersion = 1 | 2;
 /**
  * Represents a website with its properties and elements
  */
 type Website = {
   uuid: string;
-  version: 1 | 2;
+  version: ApiVersion;
   belongsTo: {
     uuid: string;
     abbreviation: string;
@@ -1082,7 +1083,7 @@ declare function fetchGallery(uuid: string, filter: string, page: number, perPag
  */
 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?: {
   customFetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
-  isVersion2: boolean;
+  version: ApiVersion;
 }): Promise<{
   error: null;
   item: Item<T, U>;
@@ -1109,7 +1110,7 @@ declare function fetchItem<T extends DataCategory = DataCategory, U extends Data
  * @param categoryParams.itemCategories - The categories of the items to 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
+ * @param options.version - The version of the OCHRE API to use
  * @returns The parsed items by property value or null if the fetch/parse fails
  */
 declare function fetchItemsByPropertyValue<T extends DataCategory = DataCategory, U extends DataCategory | Array<DataCategory> = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? Array<DataCategory> : never)>(params: {
@@ -1122,7 +1123,7 @@ declare function fetchItemsByPropertyValue<T extends DataCategory = DataCategory
   itemCategories?: U;
 }, options?: {
   customFetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
-  isVersion2?: boolean;
+  version: ApiVersion;
 }): Promise<{
   items: Array<Item<T, U>>;
   error: null;
@@ -1141,7 +1142,7 @@ declare function fetchItemsByPropertyValue<T extends DataCategory = DataCategory
  * @param params.projectScopeUuid - The UUID of the project scope
  * @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
+ * @param options.version - The version of the OCHRE API to use
  * @returns The parsed property query or null if the fetch/parse fails
  *
  * @example
@@ -1164,7 +1165,7 @@ declare function fetchPropertyQuery(params: {
   projectScopeUuid: string;
 }, options?: {
   customFetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
-  isVersion2?: boolean;
+  version: ApiVersion;
 }): Promise<{
   items: Array<PropertyQueryItem> | null;
   error: null;
@@ -1227,7 +1228,7 @@ declare function fetchByUuidMetadata(uuid: string, customFetch?: (input: string
  */
 declare function fetchWebsite(abbreviation: string, options?: {
   customFetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
-  isVersion2?: boolean;
+  version: ApiVersion;
 }): Promise<[null, Website] | [string, null]>;
 //#endregion
 //#region src/utils/getters.d.ts
@@ -1398,6 +1399,7 @@ declare function filterProperties(property: Property, filter: {
 }, options?: PropertyOptions): boolean;
 //#endregion
 //#region src/utils/helpers.d.ts
+declare const DEFAULT_API_VERSION = 1;
 /**
  * Flatten the properties of an item
  * @param item - The item whose properties to flatten
@@ -1405,4 +1407,4 @@ declare function filterProperties(property: Property, filter: {
  */
 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 { Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, Data, DataCategory, Event, FileFormat, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, LevelContext, LevelContextItem, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyContexts, PropertyQueryItem, PropertyValue, PropertyValueContent, PropertyValueContentType, Resource, Scope, Section, Set, SpatialUnit, Style, Text, Tree, UuidMetadata, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebTitle, Webpage, Website, fetchByUuidMetadata, fetchGallery, fetchItem, fetchItemsByPropertyValue, fetchPropertyQuery, fetchWebsite, filterProperties, flattenItemProperties, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };
+export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, DEFAULT_API_VERSION, Data, DataCategory, Event, FileFormat, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, LevelContext, LevelContextItem, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyContexts, PropertyQueryItem, PropertyValue, PropertyValueContent, PropertyValueContentType, Resource, Scope, Section, Set, SpatialUnit, Style, Text, Tree, UuidMetadata, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebTitle, Webpage, Website, fetchByUuidMetadata, fetchGallery, fetchItem, fetchItemsByPropertyValue, fetchPropertyQuery, fetchWebsite, filterProperties, flattenItemProperties, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/dist/index.mjs

@@ -87,6 +87,7 @@ const dataOptionsSchema = z.object({
 	start: 1,
 	limit: 40
 });
+const apiVersionSuffixSchema = z.enum(["-v1", "-v2"]).transform((suffix) => suffix.replace("-v", ""));
 /**
 * Schema for validating website properties
 * @internal
@@ -947,6 +948,41 @@ function parseStringContent(content, language = "eng") {
 	}
 }
 
+//#endregion
+//#region src/utils/helpers.ts
+const DEFAULT_API_VERSION = 1;
+/**
+* Flatten the properties of an item
+* @param item - The item whose properties to flatten
+* @returns The item with the properties flattened
+*/
+function flattenItemProperties(item) {
+	if ("properties" in item) return {
+		...item,
+		properties: flattenProperties(item.properties)
+	};
+	function collectPropertiesFromSubNodes() {
+		const allProperties = [];
+		if ("observations" in item) {
+			const typedItem = item;
+			for (const observation of typedItem.observations) allProperties.push(...observation.properties);
+		}
+		if ("interpretations" in item) {
+			const typedItem = item;
+			for (const interpretation of typedItem.interpretations) allProperties.push(...interpretation.properties);
+		}
+		if ("bibliographies" in item) {
+			const typedItem = item;
+			for (const bibliography of typedItem.bibliographies) allProperties.push(...bibliography.properties);
+		}
+		return flattenProperties(allProperties);
+	}
+	return {
+		...item,
+		properties: collectPropertiesFromSubNodes()
+	};
+}
+
 //#endregion
 //#region src/utils/parse.ts
 /**
@@ -3197,7 +3233,7 @@ function parseContexts(contexts) {
 	}
 	return contextsParsed;
 }
-function parseWebsite(websiteTree, metadata, belongsTo, { isVersion2 = false } = {}) {
+function parseWebsite(websiteTree, metadata, belongsTo, { version = DEFAULT_API_VERSION } = {}) {
 	if (!websiteTree.properties) throw new Error("Website properties not found");
 	const properties = parseWebsiteProperties(Array.isArray(websiteTree.properties.property) ? websiteTree.properties.property : [websiteTree.properties.property], websiteTree);
 	if (typeof websiteTree.items === "string" || !("resource" in websiteTree.items)) throw new Error("Website pages not found");
@@ -3206,7 +3242,7 @@ function parseWebsite(websiteTree, metadata, belongsTo, { isVersion2 = false } =
 	const sidebar = parseSidebar(resources);
 	return {
 		uuid: websiteTree.uuid,
-		version: isVersion2 ? 2 : 1,
+		version,
 		belongsTo: belongsTo ?? null,
 		metadata: parseMetadata(metadata),
 		publicationDateTime: websiteTree.publicationDateTime ? new Date(websiteTree.publicationDateTime) : null,
@@ -3309,12 +3345,12 @@ async function fetchGallery(uuid, filter, page, perPage, customFetch) {
 async function fetchByUuid(uuid, options) {
 	try {
 		const customFetch = options?.customFetch;
-		const isVersion2 = options?.isVersion2 ?? false;
+		const version = options?.version ?? DEFAULT_API_VERSION;
 		const parsedUuid = uuidSchema.parse(uuid);
-		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="*"`);
+		const response = await (customFetch ?? fetch)(version === 2 ? `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 (isVersion2 && (!("result" in dataRaw) || !("ochre" in dataRaw.result)) || !isVersion2 && !("ochre" in dataRaw)) throw new Error("Invalid OCHRE data: API response missing 'ochre' key");
+		if (version === 2 && (!("result" in dataRaw) || !("ochre" in dataRaw.result)) || version !== 2 && !("ochre" in dataRaw)) throw new Error("Invalid OCHRE data: API response missing 'ochre' key");
 		return [null, "result" in dataRaw && !Array.isArray(dataRaw.result) && "ochre" in dataRaw.result ? dataRaw.result : "ochre" in dataRaw ? dataRaw : null];
 	} catch (error) {
 		return [error instanceof Error ? error.message : "Unknown error", null];
@@ -3361,7 +3397,7 @@ async function fetchItem(uuid, category, itemCategories, options) {
 		const customFetch = options?.customFetch;
 		const [error, data] = await fetchByUuid(uuid, {
 			customFetch,
-			isVersion2: options?.isVersion2 ?? false
+			version: options?.version ?? DEFAULT_API_VERSION
 		});
 		if (error !== null) throw new Error(error);
 		const categoryKey = getItemCategory(Object.keys(data.ochre));
@@ -3444,12 +3480,12 @@ async function fetchItem(uuid, category, itemCategories, options) {
 * @returns An XQuery string
 */
 function buildXQuery$1(scopeUuids, propertyVariableUuids, propertyValueUuids, projectScopeUuid, options) {
-	const isVersion2 = options?.isVersion2 ?? false;
+	const version = options?.version ?? DEFAULT_API_VERSION;
 	let collectionScopeFilter = "";
 	if (scopeUuids.length > 0) collectionScopeFilter = `[properties/property[label/@uuid="${BELONG_TO_COLLECTION_UUID}"][value[${scopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")}]]]`;
 	const propertyVariables = propertyVariableUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
 	const propertyValues = propertyValueUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
-	return `<ochre>{${`for $q in ${isVersion2 ? "doc()" : "input()"}/ochre[@uuidBelongsTo="${projectScopeUuid}"]/*${collectionScopeFilter}/properties//property[label[${propertyVariables}]][value[${propertyValues}]]
+	return `<ochre>{${`for $q in ${version === 2 ? "doc()" : "input()"}/ochre[@uuidBelongsTo="${projectScopeUuid}"]/*${collectionScopeFilter}/properties//property[label[${propertyVariables}]][value[${propertyValues}]]
 
 let $item := $q/ancestor::*[parent::ochre]
 let $category := local-name($item)
@@ -3472,17 +3508,17 @@ return element { node-name($item) } {
 * @param categoryParams.itemCategories - The categories of the items to 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
+* @param options.version - The version of the OCHRE API to use
 * @returns The parsed items by property value or null if the fetch/parse fails
 */
 async function fetchItemsByPropertyValue(params, categoryParams, options) {
 	try {
 		const customFetch = options?.customFetch;
-		const isVersion2 = options?.isVersion2 ?? false;
+		const version = options?.version ?? DEFAULT_API_VERSION;
 		const { scopeUuids, propertyVariableUuids, propertyValueUuids, projectScopeUuid } = params;
 		const { category, itemCategories } = categoryParams ?? {};
-		const xquery = buildXQuery$1(scopeUuids, propertyVariableUuids, propertyValueUuids, projectScopeUuid, { isVersion2 });
-		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="*"`);
+		const xquery = buildXQuery$1(scopeUuids, propertyVariableUuids, propertyValueUuids, projectScopeUuid, { version });
+		const response = await (customFetch ?? fetch)(version === 2 ? `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();
 		if (Object.keys(data.result.ochre).length === 0) throw new Error("No items found");
@@ -3594,7 +3630,7 @@ return <item>
 * @param params.projectScopeUuid - The UUID of the project scope
 * @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
+* @param options.version - The version of the OCHRE API to use
 * @returns The parsed property query or null if the fetch/parse fails
 *
 * @example
@@ -3614,10 +3650,10 @@ return <item>
 async function fetchPropertyQuery(params, options) {
 	try {
 		const customFetch = options?.customFetch;
-		const isVersion2 = options?.isVersion2 ?? false;
+		const version = options?.version ?? DEFAULT_API_VERSION;
 		const { scopeUuids, propertyUuids, projectScopeUuid } = params;
 		const xquery = buildXQuery(scopeUuids, propertyUuids, projectScopeUuid);
-		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="*"`);
+		const response = await (customFetch ?? fetch)(version === 2 ? `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);
@@ -3721,6 +3757,24 @@ const KNOWN_ABBREVIATIONS = {
 	"sosc-core-at-smart": "db26c953-9b2a-4691-a909-5e8726b531d7"
 };
 /**
+* Parses the version suffix from an API abbreviation
+*
+* @param abbreviation - The API abbreviation to parse
+* @returns The parsed abbreviation and API version
+*/
+function parseApiVersionSuffix(abbreviation) {
+	if (!/-v\d+$/.test(abbreviation)) return {
+		abbreviation,
+		version: DEFAULT_API_VERSION
+	};
+	const result = apiVersionSuffixSchema.safeParse(abbreviation);
+	if (!result.success) throw new Error("Invalid API version suffix");
+	return {
+		abbreviation: abbreviation.replace(`-v${result.data}`, ""),
+		version: result.data
+	};
+}
+/**
 * Fetches and parses a website configuration from the OCHRE API
 *
 * @param abbreviation - The abbreviation identifier for the website
@@ -3753,12 +3807,14 @@ async function fetchWebsite(abbreviation, options) {
 	try {
 		const cleanAbbreviation = abbreviation.trim().toLocaleLowerCase("en-US");
 		const customFetch = options?.customFetch;
-		const isVersion2 = cleanAbbreviation.endsWith("-v2") ? true : options?.isVersion2 ?? false;
+		const { abbreviation: parsedAbbreviation, version: parsedVersion } = parseApiVersionSuffix(cleanAbbreviation);
+		const abbreviationToUse = options?.version != null ? cleanAbbreviation : parsedAbbreviation;
+		const version = options?.version ?? parsedVersion;
 		let metadata = null;
 		let tree = null;
 		let belongsTo = null;
-		if (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.replace("-v2", "")}']`)}&format=json&lang="*"`);
+		if (version === 2) {
+			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='${abbreviationToUse}']`)}&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");
@@ -3769,8 +3825,8 @@ async function fetchWebsite(abbreviation, options) {
 				abbreviation: parseFakeString(data.result.ochre.belongsTo)
 			};
 		} 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`);
+			const uuid = KNOWN_ABBREVIATIONS[abbreviationToUse];
+			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='${abbreviationToUse}']] 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;
@@ -3782,7 +3838,7 @@ async function fetchWebsite(abbreviation, options) {
 				abbreviation: parseFakeString(result.ochre.belongsTo)
 			};
 		}
-		return [null, parseWebsite(tree, metadata, belongsTo, { isVersion2 })];
+		return [null, parseWebsite(tree, metadata, belongsTo, { version })];
 	} catch (error) {
 		console.error(error);
 		return [error instanceof Error ? error.message : "Unknown error", null];
@@ -3790,38 +3846,4 @@ async function fetchWebsite(abbreviation, options) {
 }
 
 //#endregion
-//#region src/utils/helpers.ts
-/**
-* Flatten the properties of an item
-* @param item - The item whose properties to flatten
-* @returns The item with the properties flattened
-*/
-function flattenItemProperties(item) {
-	if ("properties" in item) return {
-		...item,
-		properties: flattenProperties(item.properties)
-	};
-	function collectPropertiesFromSubNodes() {
-		const allProperties = [];
-		if ("observations" in item) {
-			const typedItem = item;
-			for (const observation of typedItem.observations) allProperties.push(...observation.properties);
-		}
-		if ("interpretations" in item) {
-			const typedItem = item;
-			for (const interpretation of typedItem.interpretations) allProperties.push(...interpretation.properties);
-		}
-		if ("bibliographies" in item) {
-			const typedItem = item;
-			for (const bibliography of typedItem.bibliographies) allProperties.push(...bibliography.properties);
-		}
-		return flattenProperties(allProperties);
-	}
-	return {
-		...item,
-		properties: collectPropertiesFromSubNodes()
-	};
-}
-
-//#endregion
-export { fetchByUuidMetadata, fetchGallery, fetchItem, fetchItemsByPropertyValue, fetchPropertyQuery, fetchWebsite, filterProperties, flattenItemProperties, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };
+export { DEFAULT_API_VERSION, fetchByUuidMetadata, fetchGallery, fetchItem, fetchItemsByPropertyValue, fetchPropertyQuery, fetchWebsite, filterProperties, flattenItemProperties, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/package.json

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