@digitalculture/ochre-sdk 0.13.9 → 0.14.0

package/dist/index.d.mts

@@ -14,11 +14,11 @@ type Data<T extends DataCategory = DataCategory, U extends DataCategory = (T ext
 /**
  * Represents the category of the data
  */
-type DataCategory = "tree" | "set" | "resource" | "spatialUnit" | "concept" | "period" | "bibliography" | "person" | "propertyValue";
+type DataCategory = "resource" | "spatialUnit" | "concept" | "period" | "bibliography" | "person" | "propertyValue" | "text" | "tree" | "set";
 /**
  * Represents the item of the data, with proper type narrowing based on category
  */
-type Item<T extends DataCategory = DataCategory, U extends DataCategory = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? DataCategory : never)> = T extends "resource" ? Resource : T extends "spatialUnit" ? SpatialUnit : T extends "concept" ? Concept : T extends "period" ? Period : T extends "bibliography" ? Bibliography : T extends "person" ? Person : T extends "propertyValue" ? PropertyValue : T extends "tree" ? Tree<Exclude<U, "tree">> : T extends "set" ? Set<U> : Resource | SpatialUnit | Concept | Period | Bibliography | Person | PropertyValue | Tree<Exclude<U, "tree">> | Set<U>;
+type Item<T extends DataCategory = DataCategory, U extends DataCategory = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? DataCategory : never)> = T extends "resource" ? Resource : T extends "spatialUnit" ? SpatialUnit : T extends "concept" ? Concept : T extends "period" ? Period : T extends "bibliography" ? Bibliography : T extends "person" ? Person : T extends "propertyValue" ? PropertyValue : T extends "text" ? Text : T extends "tree" ? Tree<Exclude<U, "tree">> : T extends "set" ? Set<U> : Resource | SpatialUnit | Concept | Period | Bibliography | Person | PropertyValue | Tree<Exclude<U, "tree">> | Set<U>;
 /**
  * Basic identification information used across multiple types
  */
@@ -394,10 +394,7 @@ type Bibliography = {
     startIssue: string;
     startVolume: string;
   } | null;
-  source: {
-    resource: Pick<Resource, "uuid" | "publicationDateTime" | "type" | "identification"> | null;
-    documentUrl: string | null;
-  };
+  sourceResources: Array<Pick<Resource, "uuid" | "category" | "publicationDateTime" | "type" | "identification" | "href">>;
   periods: Array<Period>;
   authors: Array<Person>;
   properties: Array<Property>;
@@ -460,6 +457,45 @@ type Property<T extends PropertyValueContentType = PropertyValueContentType> = {
   comment: string | null;
   properties: Array<Property>;
 };
+/**
+ * Represents a resource item with associated metadata, content and relationships
+ */
+type Text = {
+  uuid: string;
+  category: "text";
+  metadata: Metadata | null;
+  publicationDateTime: Date | null;
+  type: string | null;
+  language: string | null;
+  number: number;
+  context: Context | null;
+  license: License | null;
+  copyright: string | null;
+  watermark: string | null;
+  identification: Identification;
+  creators: Array<Person>;
+  editors: Array<Person>;
+  notes: Array<Note>;
+  description: string;
+  periods: Array<Period>;
+  links: Array<Link>;
+  reverseLinks: Array<Link>;
+  properties: Array<Property>;
+  bibliographies: Array<Bibliography>;
+  sections: Array<Section>;
+};
+/**
+ * Represents a section of a text
+ */
+type Section = {
+  uuid: string;
+  variant: "translation" | "phonemic";
+  type: string;
+  identification: Identification;
+  project: {
+    identification: Identification;
+  };
+};
 /**
  * Represents a tree structure containing resources, spatial units and concepts
  */
@@ -475,7 +511,7 @@ type Tree<U extends Exclude<DataCategory, "tree"> = Exclude<DataCategory, "tree"
   identification: Identification;
   creators: Array<Person>;
   properties: Array<Property>;
-  items: [Exclude<DataCategory, "tree">] extends [U] ? Array<Item> : U extends "resource" ? Array<Resource> : U extends "spatialUnit" ? Array<SpatialUnit> : U extends "concept" ? Array<Concept> : U extends "period" ? Array<Period> : U extends "bibliography" ? Array<Bibliography> : U extends "person" ? Array<Person> : U extends "propertyValue" ? Array<PropertyValue> : U extends "set" ? Array<Set<DataCategory>> : Array<Item>;
+  items: [Exclude<DataCategory, "tree">] extends [U] ? Array<Item> : U extends "resource" ? Array<Resource> : U extends "spatialUnit" ? Array<SpatialUnit> : U extends "concept" ? Array<Concept> : U extends "period" ? Array<Period> : U extends "bibliography" ? Array<Bibliography> : U extends "person" ? Array<Person> : U extends "propertyValue" ? Array<PropertyValue> : U extends "text" ? Array<Text> : U extends "set" ? Array<Set<DataCategory>> : Array<Item>;
 };
 /**
  * Represents a gallery with its identification, project identification, resources and max length
@@ -654,7 +690,6 @@ type WebElementComponent = {
   fileSize: number | null;
   isInteractive: boolean;
   isControlsDisplayed: boolean;
-  isLightingDisplayed: boolean;
 } | {
   component: "advanced-search";
   boundElementUuid: string | null;
@@ -1238,4 +1273,4 @@ declare function filterProperties(property: Property, filter: {
   value: string | number | boolean | Date;
 }, options?: PropertyOptions): boolean;
 //#endregion
-export { Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, Data, DataCategory, Event, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, LevelContext, LevelContextItem, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyContexts, PropertyQueryItem, PropertyValue, PropertyValueContent, PropertyValueContentType, Resource, Set, SpatialUnit, Style, Tree, UuidMetadata, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebTitle, Webpage, Website, fetchByUuidMetadata, fetchGallery, fetchItem, fetchPropertyQuery, fetchWebsite, filterProperties, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };
+export { Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, Data, DataCategory, Event, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, LevelContext, LevelContextItem, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyContexts, PropertyQueryItem, PropertyValue, PropertyValueContent, PropertyValueContentType, Resource, Section, Set, SpatialUnit, Style, Text, Tree, UuidMetadata, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebTitle, Webpage, Website, fetchByUuidMetadata, fetchGallery, fetchItem, fetchPropertyQuery, fetchWebsite, filterProperties, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/dist/index.mjs

@@ -2,10 +2,37 @@ import * as z from "zod";
 
 //#region src/schemas.ts
 /**
+* Validates a pseudo-UUID string
+* @param value - The string to validate
+* @returns True if the string is a valid pseudo-UUID, false otherwise
+* @internal
+*/
+function isPseudoUuid(value) {
+	return /^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i.test(value);
+}
+/**
 * Schema for validating UUIDs
 * @internal
 */
-const uuidSchema = z.uuid({ error: "Invalid UUID provided" });
+const uuidSchema = z.string().refine(isPseudoUuid, { error: "Invalid UUID" });
+/**
+* Schema for validating filters
+* @internal
+*/
+const filterSchema = z.string().optional();
+/**
+* Schema for validating data options
+* @internal
+*/
+const dataOptionsSchema = z.object({
+	filter: z.string().optional().default(""),
+	start: z.number().positive({ error: "Start must be positive" }).optional().default(1),
+	limit: z.number().positive({ error: "Limit must be positive" }).optional().default(40)
+}).optional().default({
+	filter: "",
+	start: 1,
+	limit: 40
+});
 /**
 * Schema for validating website properties
 * @internal
@@ -72,8 +99,9 @@ const categorySchema = z.enum([
 	"bibliography",
 	"person",
 	"propertyValue",
-	"set",
-	"tree"
+	"text",
+	"tree",
+	"set"
 ]);
 /**
 * Schema for validating property value content types
@@ -95,7 +123,7 @@ const propertyValueContentTypeSchema = z.enum([
 * @internal
 */
 const gallerySchema = z.object({
-	uuid: z.uuid({ error: "Invalid UUID" }),
+	uuid: z.string().refine(isPseudoUuid, { error: "Invalid UUID" }),
 	filter: z.string().optional(),
 	page: z.number().positive({ error: "Page must be positive" }),
 	perPage: z.number().positive({ error: "Per page must be positive" })
@@ -1305,13 +1333,18 @@ function parsePeriods(periods) {
 * @returns Parsed Bibliography object
 */
 function parseBibliography(bibliography, metadata) {
-	let resource = null;
-	if (bibliography.source?.resource) resource = {
-		uuid: bibliography.source.resource.uuid,
-		publicationDateTime: bibliography.source.resource.publicationDateTime ? new Date(bibliography.source.resource.publicationDateTime) : null,
-		type: bibliography.source.resource.type,
-		identification: parseIdentification(bibliography.source.resource.identification)
-	};
+	const sourceResources = [];
+	if (bibliography.source?.resource) {
+		const resourcesToParse = Array.isArray(bibliography.source.resource) ? bibliography.source.resource : [bibliography.source.resource];
+		for (const resource of resourcesToParse) sourceResources.push({
+			uuid: resource.uuid,
+			category: "resource",
+			publicationDateTime: new Date(resource.publicationDateTime),
+			type: resource.type,
+			identification: parseIdentification(resource.identification),
+			href: resource.href ?? null
+		});
+	}
 	let shortCitation = null;
 	let longCitation = null;
 	if (bibliography.citationFormatSpan) try {
@@ -1349,10 +1382,7 @@ function parseBibliography(bibliography, metadata) {
 			startIssue: parseFakeString(bibliography.entryInfo.startIssue),
 			startVolume: parseFakeString(bibliography.entryInfo.startVolume)
 		} : null,
-		source: {
-			resource,
-			documentUrl: bibliography.sourceDocument ? `https://ochre.lib.uchicago.edu/ochre?uuid=${bibliography.sourceDocument.uuid}&load` : null
-		},
+		sourceResources,
 		periods: bibliography.periods ? parsePeriods(Array.isArray(bibliography.periods.period) ? bibliography.periods.period : [bibliography.periods.period]) : [],
 		authors: bibliography.authors ? parsePersons(Array.isArray(bibliography.authors.person) ? bibliography.authors.person : [bibliography.authors.person]) : [],
 		properties: bibliography.properties ? parseProperties(Array.isArray(bibliography.properties.property) ? bibliography.properties.property : [bibliography.properties.property]) : []
@@ -1404,6 +1434,82 @@ function parsePropertyValues(propertyValues) {
 	return returnPropertyValues;
 }
 /**
+* Parses raw text data into a standardized Text object
+*
+* @param text - Raw text data in OCHRE format
+* @returns Parsed Text object
+*/
+function parseText(text, metadata) {
+	return {
+		uuid: text.uuid,
+		category: "text",
+		metadata: metadata ?? null,
+		publicationDateTime: text.publicationDateTime ? new Date(text.publicationDateTime) : null,
+		type: text.type ?? null,
+		language: text.language ?? null,
+		number: text.n ?? 0,
+		context: text.context ? parseContext(text.context) : null,
+		license: "availability" in text && text.availability ? parseLicense(text.availability) : null,
+		copyright: "copyright" in text && text.copyright != null ? parseStringContent(text.copyright) : null,
+		watermark: "watermark" in text && text.watermark != null ? parseStringContent(text.watermark) : null,
+		identification: parseIdentification(text.identification),
+		creators: text.creators ? parsePersons(Array.isArray(text.creators.creator) ? text.creators.creator : [text.creators.creator]) : [],
+		editors: text.editions ? parsePersons(Array.isArray(text.editions.editor) ? text.editions.editor : [text.editions.editor]) : [],
+		notes: text.notes ? parseNotes(Array.isArray(text.notes.note) ? text.notes.note : [text.notes.note]) : [],
+		description: text.description ? parseStringContent(text.description) : "",
+		periods: text.periods ? parsePeriods(Array.isArray(text.periods.period) ? text.periods.period : [text.periods.period]) : [],
+		links: text.links ? parseLinks(Array.isArray(text.links) ? text.links : [text.links]) : [],
+		reverseLinks: text.reverseLinks ? parseLinks(Array.isArray(text.reverseLinks) ? text.reverseLinks : [text.reverseLinks]) : [],
+		properties: text.properties ? parseProperties(Array.isArray(text.properties.property) ? text.properties.property : [text.properties.property]) : [],
+		bibliographies: text.bibliographies ? parseBibliographies(Array.isArray(text.bibliographies.bibliography) ? text.bibliographies.bibliography : [text.bibliographies.bibliography]) : [],
+		sections: text.sections ? parseSections(text.sections) : []
+	};
+}
+/**
+* Parses an array of raw texts into standardized Text objects
+*
+* @param texts - Array of raw texts in OCHRE format
+* @returns Array of parsed Text objects
+*/
+function parseTexts(texts) {
+	const returnTexts = [];
+	for (const text of texts) returnTexts.push(parseText(text));
+	return returnTexts;
+}
+/**
+* Parses a raw section data into a standardized Section object
+*
+* @param section - Raw section data in OCHRE format
+* @returns Parsed Section object
+*/
+function parseSection(section, variant) {
+	return {
+		uuid: section.uuid,
+		variant,
+		type: section.type,
+		identification: parseIdentification(section.identification),
+		project: { identification: parseIdentification(section.project.identification) }
+	};
+}
+/**
+* Parses raw sections data into a standardized Section object
+*
+* @param sections - Raw sections data in OCHRE format
+* @param sections.translation - Translation sections
+* @param sections.phonemic - Phonemic sections
+* @param sections.translation.section - Translation sections
+* @param sections.phonemic.section - Phonemic sections
+* @returns Parsed Section object
+*/
+function parseSections(sections) {
+	const returnSections = [];
+	const translationSections = sections.translation ? Array.isArray(sections.translation.section) ? sections.translation.section : [sections.translation.section] : [];
+	const phonemicSections = sections.phonemic ? Array.isArray(sections.phonemic.section) ? sections.phonemic.section : [sections.phonemic.section] : [];
+	for (const section of translationSections) returnSections.push(parseSection(section, "translation"));
+	for (const section of phonemicSections) returnSections.push(parseSection(section, "phonemic"));
+	return returnSections;
+}
+/**
 * Parses a raw tree structure into a standardized Tree object
 *
 * @param tree - Raw tree data in OCHRE format
@@ -1446,6 +1552,10 @@ function parseTree(tree, itemCategory, metadata) {
 			if (!("propertyValue" in tree.items)) throw new Error("Invalid OCHRE data: Tree has no property values");
 			items = parsePropertyValues(Array.isArray(tree.items.propertyValue) ? tree.items.propertyValue : [tree.items.propertyValue]);
 			break;
+		case "text":
+			if (!("text" in tree.items)) throw new Error("Invalid OCHRE data: Tree has no texts");
+			items = parseTexts(Array.isArray(tree.items.text) ? tree.items.text : [tree.items.text]);
+			break;
 		case "set": {
 			if (!("set" in tree.items)) throw new Error("Invalid OCHRE data: Tree has no sets");
 			const setItems = [];
@@ -1509,6 +1619,10 @@ function parseSet(set, itemCategory, metadata) {
 			if (!("propertyValue" in set.items)) throw new Error("Invalid OCHRE data: Set has no property values");
 			items = parsePropertyValues(Array.isArray(set.items.propertyValue) ? set.items.propertyValue : [set.items.propertyValue]);
 			break;
+		case "text":
+			if (!("text" in set.items)) throw new Error("Invalid OCHRE data: Set has no texts");
+			items = parseTexts(Array.isArray(set.items.text) ? set.items.text : [set.items.text]);
+			break;
 		default: throw new Error("Invalid OCHRE data: Set has no items or is malformed");
 	}
 	return {
@@ -1716,14 +1830,10 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			let isControlsDisplayed = true;
 			const isControlsDisplayedProperty = getPropertyValueByLabel(componentProperty.properties, "controls-displayed");
 			if (isControlsDisplayedProperty !== null) isControlsDisplayed = isControlsDisplayedProperty === true;
-			let isLightingDisplayed = true;
-			const isLightingDisplayedProperty = getPropertyValueByLabel(componentProperty.properties, "lighting-displayed");
-			if (isLightingDisplayedProperty !== null) isLightingDisplayed = isLightingDisplayedProperty === true;
 			properties.resourceId = resourceLink.uuid;
 			properties.fileSize = resourceLink.fileSize;
 			properties.isInteractive = isInteractive;
 			properties.isControlsDisplayed = isControlsDisplayed;
-			properties.isLightingDisplayed = isLightingDisplayed;
 			break;
 		}
 		case "advanced-search": {
@@ -2984,6 +3094,10 @@ async function fetchItem(uuid, category, itemCategory, options) {
 				if (!("propertyValue" in data.ochre)) throw new Error("Invalid OCHRE data: API response missing 'propertyValue' key");
 				item = parsePropertyValue(data.ochre.propertyValue, metadata);
 				break;
+			case "text":
+				if (!("text" in data.ochre)) throw new Error("Invalid OCHRE data: API response missing 'text' key");
+				item = parseText(data.ochre.text, metadata);
+				break;
 			case "set":
 				if (!("set" in data.ochre)) throw new Error("Invalid OCHRE data: API response missing 'set' key");
 				item = parseSet(data.ochre.set, itemCategory, metadata);
@@ -3199,7 +3313,6 @@ const KNOWN_ABBREVIATIONS = {
 	ssmc: "8ff977dd-d440-40f5-ad93-8ad7e2d39e74",
 	"sosc-core-at-smart": "db26c953-9b2a-4691-a909-5e8726b531d7"
 };
-const V2_ABBREVIATIONS = /* @__PURE__ */ new Set();
 /**
 * Fetches and parses a website configuration from the OCHRE API
 *
@@ -3233,7 +3346,7 @@ async function fetchWebsite(abbreviation, options) {
 	try {
 		const cleanAbbreviation = abbreviation.trim().toLocaleLowerCase("en-US");
 		const customFetch = options?.customFetch;
-		const isVersion2 = V2_ABBREVIATIONS.has(cleanAbbreviation) ? true : options?.isVersion2 ?? false;
+		const isVersion2 = cleanAbbreviation.endsWith("-v2") ? true : options?.isVersion2 ?? false;
 		let metadata = null;
 		let tree = null;
 		if (isVersion2) {

package/package.json

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