@digitalculture/ochre-sdk 0.18.16 → 0.18.18

package/dist/index.d.mts

@@ -15,11 +15,11 @@ type Data<T extends DataCategory = DataCategory, U extends DataCategory | Array<
 /**
  * Represents the category of the data
  */
-type DataCategory = "resource" | "spatialUnit" | "concept" | "period" | "bibliography" | "person" | "propertyValue" | "text" | "tree" | "set";
+type DataCategory = "resource" | "spatialUnit" | "concept" | "period" | "bibliography" | "person" | "propertyVariable" | "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 | Array<DataCategory> = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? Array<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<U extends Array<DataCategory> ? Exclude<U[number], "tree"> : Exclude<U, "tree">> : T extends "set" ? Set<U extends Array<DataCategory> ? U : Array<U>> : Resource | SpatialUnit | Concept | Period | Bibliography | Person | PropertyValue | Tree<U extends Array<DataCategory> ? Exclude<U[number], "tree"> : Exclude<U, "tree">> | Set<U extends Array<DataCategory> ? U : Array<U>>;
+type Item<T extends DataCategory = DataCategory, U extends DataCategory | Array<DataCategory> = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? Array<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 "propertyVariable" ? PropertyVariable : T extends "propertyValue" ? PropertyValue : T extends "text" ? Text : T extends "tree" ? Tree<U extends Array<DataCategory> ? Exclude<U[number], "tree"> : Exclude<U, "tree">> : T extends "set" ? Set<U extends Array<DataCategory> ? U : Array<U>> : Resource | SpatialUnit | Concept | Period | Bibliography | Person | PropertyVariable | PropertyValue | Tree<U extends Array<DataCategory> ? Exclude<U[number], "tree"> : Exclude<U, "tree">> | Set<U extends Array<DataCategory> ? U : Array<U>>;
 /**
  * Basic identification information used across multiple types
  */
@@ -36,6 +36,7 @@ type Metadata = {
     identification: Identification & {
       website: string | null;
     };
+    dateFormat: string | null;
   } | null;
   collection: {
     identification: Identification;
@@ -260,8 +261,7 @@ type Observation = {
  * Represents an event with date, label and optional agent
  */
 type Event = {
-  dateTime: Date | null;
-  date: string | null;
+  dateTime: string | null;
   label: string;
   agent: {
     uuid: string;
@@ -406,7 +406,7 @@ type Set<U extends Array<DataCategory> = Array<DataCategory>> = {
   isSuppressingBlanks: boolean;
   description: string;
   creators: Array<Person>;
-  items: [DataCategory] 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 "tree" ? Array<Tree<Exclude<DataCategory, "tree">>> : U extends "set" ? Array<Set<Array<DataCategory>>> : Array<Item>;
+  items: [DataCategory] 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 "propertyVariable" ? Array<PropertyVariable> : U extends "propertyValue" ? Array<PropertyValue> : U extends "tree" ? Array<Tree<Exclude<DataCategory, "tree">>> : U extends "set" ? Array<Set<Array<DataCategory>>> : Array<Item>;
 };
 /**
  * Represents a bibliography entry with citation and publication information
@@ -468,6 +468,25 @@ type Period = {
   coordinates: Array<Coordinate>;
   description: string | null;
 };
+/**
+ * Represents a property variable
+ */
+type PropertyVariable = {
+  uuid: string;
+  category: "propertyVariable";
+  belongsTo: {
+    uuid: string;
+    abbreviation: string;
+  } | null;
+  metadata: Metadata | null;
+  persistentUrl: string | null;
+  type: string;
+  number: number;
+  publicationDateTime: Date | null;
+  context: Context | null;
+  availability: License | null;
+  identification: Identification;
+};
 /**
  * Represents a property value with type information
  */
@@ -590,7 +609,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 "text" ? Array<Text> : U extends "set" ? Array<Set<U extends Array<DataCategory> ? U : Array<U>>> : 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 "propertyVariable" ? Array<PropertyVariable> : U extends "propertyValue" ? Array<PropertyValue> : U extends "text" ? Array<Text> : U extends "set" ? Array<Set<U extends Array<DataCategory> ? U : Array<U>>> : Array<Item>;
 };
 /**
  * Represents a gallery with its identification, project identification, resources and max length
@@ -1031,24 +1050,7 @@ type WebBlock<T extends WebBlockLayout = WebBlockLayout> = {
  * @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 The parsed gallery or null if the fetch/parse fails
- *
- * @example
- * ```ts
- * const gallery = await fetchGallery("9c4da06b-f15e-40af-a747-0933eaf3587e", "1978", 1, 12);
- * if (gallery === null) {
- *   console.error("Failed to fetch gallery");
- *   return;
- * }
- * console.log(`Fetched gallery: ${gallery.identification.label}`);
- * console.log(`Contains ${gallery.resources.length.toLocaleString()} resources`);
- * ```
- *
- * @remarks
- * The returned gallery includes:
- * - Gallery metadata and identification
- * - Project identification
- * - Resources (gallery items)
+ * @returns The parsed gallery or an error message if the fetch/parse fails
  */
 declare function fetchGallery(uuid: string, filter: string, page: number, pageSize: number, options?: {
   fetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
@@ -1066,34 +1068,7 @@ declare function fetchGallery(uuid: string, filter: string, page: number, pageSi
  * Fetches and parses an OCHRE item from the OCHRE API
  *
  * @param uuid - The UUID of the OCHRE item to fetch
- * @returns Object containing the parsed OCHRE item and its metadata, or null if the fetch/parse fails
- *
- * @example
- * ```ts
- * const result = await fetchItem("123e4567-e89b-12d3-a456-426614174000");
- * if (result === null) {
- *   console.error("Failed to fetch OCHRE item");
- *   return;
- * }
- * const { metadata, belongsTo, item, category } = result;
- * console.log(`Fetched OCHRE item: ${item.identification.label} with category ${category}`);
- * ```
- *
- * Or, if you want to fetch a specific category, you can do so by passing the category as an argument:
- * ```ts
- * const result = await fetchItem("123e4567-e89b-12d3-a456-426614174000", "resource");
- * const { metadata, belongsTo, item, category } = result;
- * console.log(item.category); // "resource"
- * ```
- *
- * @remarks
- * The returned OCHRE item includes:
- * - Item metadata
- * - Item belongsTo information
- * - Item content
- * - Item category
- *
- * If the fetch/parse fails, the returned object will have an `error` property.
+ * @returns Object containing the parsed OCHRE item, or an error message if the fetch/parse fails
  */
 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?: {
   fetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
@@ -1101,13 +1076,9 @@ declare function fetchItem<T extends DataCategory = DataCategory, U extends Data
 }): Promise<{
   error: null;
   item: Item<T, U>;
-  category: T;
-  itemCategories: U;
 } | {
   error: string;
-  item: never;
-  category: never;
-  itemCategories: never;
+  item: null;
 }>;
 //#endregion
 //#region src/utils/fetchers/items-by-property-values.d.ts
@@ -1235,29 +1206,6 @@ declare function fetchPropertyValuesByPropertyVariables(params: {
  *
  * @param abbreviation - The abbreviation identifier for the website
  * @returns The parsed website configuration or null if the fetch/parse fails
- *
- * @example
- * ```ts
- * const website = await fetchWebsite("guerrilla-television");
- * if (website === null) {
- *   console.error("Failed to fetch website");
- *   return;
- * }
- * console.log(`Fetched website: ${website.identification.label}`);
- * console.log(`Contains ${website.pages.length.toLocaleString()} pages`);
- * ```
- *
- * @remarks
- * The returned website configuration includes:
- * - Website metadata and identification
- * - Page structure and content
- * - Layout and styling properties
- * - Navigation configuration
- * - Sidebar elements
- * - Project information
- * - Creator details
- *
- * The abbreviation is case-insensitive and should match the website's configured abbreviation in OCHRE.
  */
 declare function fetchWebsite(abbreviation: string, options?: {
   fetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
@@ -1278,14 +1226,6 @@ type PropertyOptions = {
  * @param uuid - The UUID to search for
  * @param options - Search options, including whether to include nested properties
  * @returns The matching Property object, or null if not found
- *
- * @example
- * ```ts
- * const property = getPropertyByUuid(properties, "123e4567-e89b-12d3-a456-426614174000", { includeNestedProperties: true });
- * if (property) {
- *   console.log(property.values);
- * }
- * ```
  */
 declare function getPropertyByUuid(properties: Array<Property>, uuid: string, options?: PropertyOptions): Property | null;
 /**
@@ -1295,16 +1235,6 @@ declare function getPropertyByUuid(properties: Array<Property>, uuid: string, op
  * @param uuid - The UUID to search for
  * @param options - Search options, including whether to include nested properties
  * @returns Array of property values as strings, or null if property not found
- *
- * @example
- * ```ts
- * const values = getPropertyValuesByUuid(properties, "123e4567-e89b-12d3-a456-426614174000");
- * if (values) {
- *   for (const value of values) {
- *     console.log(value);
- *   }
- * }
- * ```
  */
 declare function getPropertyValuesByUuid(properties: Array<Property>, uuid: string, options?: PropertyOptions): Array<string | number | boolean | Date | null> | null;
 /**
@@ -1314,14 +1244,6 @@ declare function getPropertyValuesByUuid(properties: Array<Property>, uuid: stri
  * @param uuid - The UUID to search for
  * @param options - Search options, including whether to include nested properties
  * @returns The first property value as string, or null if property not found
- *
- * @example
- * ```ts
- * const title = getPropertyValueByUuid(properties, "123e4567-e89b-12d3-a456-426614174000");
- * if (title) {
- *   console.log(`Document title: ${title}`);
- * }
- * ```
  */
 declare function getPropertyValueByUuid(properties: Array<Property>, uuid: string, options?: PropertyOptions): string | number | boolean | Date | null;
 /**
@@ -1331,14 +1253,6 @@ declare function getPropertyValueByUuid(properties: Array<Property>, uuid: strin
  * @param label - The label to search for
  * @param options - Search options, including whether to include nested properties
  * @returns The matching Property object, or null if not found
- *
- * @example
- * ```ts
- * const property = getPropertyByLabel(properties, "author", { includeNestedProperties: true });
- * if (property) {
- *   console.log(property.values);
- * }
- * ```
  */
 declare function getPropertyByLabel(properties: Array<Property>, label: string, options?: PropertyOptions): Property | null;
 /**
@@ -1348,16 +1262,6 @@ declare function getPropertyByLabel(properties: Array<Property>, label: string,
  * @param label - The label to search for
  * @param options - Search options, including whether to include nested properties
  * @returns Array of property values as strings, or null if property not found
- *
- * @example
- * ```ts
- * const values = getPropertyValuesByLabel(properties, "keywords");
- * if (values) {
- *   for (const value of values) {
- *     console.log(value);
- *   }
- * }
- * ```
  */
 declare function getPropertyValuesByLabel(properties: Array<Property>, label: string, options?: PropertyOptions): Array<string | number | boolean | Date | null> | null;
 /**
@@ -1367,14 +1271,6 @@ declare function getPropertyValuesByLabel(properties: Array<Property>, label: st
  * @param label - The label to search for
  * @param options - Search options, including whether to include nested properties
  * @returns The first property value as string, or null if property not found
- *
- * @example
- * ```ts
- * const title = getPropertyValueByLabel(properties, "title");
- * if (title) {
- *   console.log(`Document title: ${title}`);
- * }
- * ```
  */
 declare function getPropertyValueByLabel(properties: Array<Property>, label: string, options?: PropertyOptions): string | number | boolean | Date | null;
 /**
@@ -1383,12 +1279,6 @@ declare function getPropertyValueByLabel(properties: Array<Property>, label: str
  * @param properties - Array of properties to get unique properties from
  * @param options - Search options, including whether to include nested properties
  * @returns Array of unique properties
- *
- * @example
- * ```ts
- * const properties = getAllUniqueProperties(properties, { includeNestedProperties: true });
- * console.log(`Available properties: ${properties.map((p) => p.label).join(", ")}`);
- * ```
  */
 declare function getUniqueProperties(properties: Array<Property>, options?: PropertyOptions): Array<Property>;
 /**
@@ -1397,12 +1287,6 @@ declare function getUniqueProperties(properties: Array<Property>, options?: Prop
  * @param properties - Array of properties to get unique property labels from
  * @param options - Search options, including whether to include nested properties
  * @returns Array of unique property labels
- *
- * @example
- * ```ts
- * const properties = getAllUniquePropertyLabels(properties, { includeNestedProperties: true });
- * console.log(`Available properties: ${properties.join(", ")}`);
- * ```
  */
 declare function getUniquePropertyLabels(properties: Array<Property>, options?: PropertyOptions): Array<string>;
 /**
@@ -1414,17 +1298,6 @@ declare function getUniquePropertyLabels(properties: Array<Property>, options?:
  * @param filter.value - The value to filter by
  * @param options - Search options, including whether to include nested properties
  * @returns True if the property matches the filter criteria, false otherwise
- *
- * @example
- * ```ts
- * const matches = filterProperties(property, {
- *   label: "category",
- *   value: "book"
- * });
- * if (matches) {
- *   console.log("Property matches filter criteria");
- * }
- * ```
  */
 declare function filterProperties(property: Property, filter: {
   label: string;
@@ -1460,4 +1333,4 @@ declare function flattenItemProperties<T extends DataCategory = DataCategory, U
  */
 declare function getLeafPropertyValues<T extends PropertyValueContentType = PropertyValueContentType>(propertyValues: Array<PropertyValueContent<T>>): Array<PropertyValueContent<T>>;
 //#endregion
-export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, Data, DataCategory, Event, FileFormat, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, LevelContext, LevelContextItem, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyContexts, PropertyValue, PropertyValueContent, PropertyValueContentType, PropertyValueQueryItem, Resource, Scope, Section, Set, SpatialUnit, Style, Text, Tree, UuidMetadata, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebTitle, Webpage, Website, fetchGallery, fetchItem, fetchItemsByPropertyValues, fetchItemsByUuidsAndLinks, fetchPropertyValuesByPropertyVariables, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };
+export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, Data, DataCategory, Event, FileFormat, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, LevelContext, LevelContextItem, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyContexts, PropertyValue, PropertyValueContent, PropertyValueContentType, PropertyValueQueryItem, PropertyVariable, Resource, Scope, Section, Set, SpatialUnit, Style, Text, Tree, UuidMetadata, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebTitle, Webpage, Website, fetchGallery, fetchItem, fetchItemsByPropertyValues, fetchItemsByUuidsAndLinks, fetchPropertyValuesByPropertyVariables, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/dist/index.mjs

@@ -187,6 +187,7 @@ const categorySchema = z.enum([
 	"period",
 	"bibliography",
 	"person",
+	"propertyVariable",
 	"propertyValue",
 	"text",
 	"tree",
@@ -277,14 +278,6 @@ const DEFAULT_OPTIONS = { includeNestedProperties: false };
 * @param uuid - The UUID to search for
 * @param options - Search options, including whether to include nested properties
 * @returns The matching Property object, or null if not found
-*
-* @example
-* ```ts
-* const property = getPropertyByUuid(properties, "123e4567-e89b-12d3-a456-426614174000", { includeNestedProperties: true });
-* if (property) {
-*   console.log(property.values);
-* }
-* ```
 */
 function getPropertyByUuid(properties, uuid, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = options;
@@ -305,16 +298,6 @@ function getPropertyByUuid(properties, uuid, options = DEFAULT_OPTIONS) {
 * @param uuid - The UUID to search for
 * @param options - Search options, including whether to include nested properties
 * @returns Array of property values as strings, or null if property not found
-*
-* @example
-* ```ts
-* const values = getPropertyValuesByUuid(properties, "123e4567-e89b-12d3-a456-426614174000");
-* if (values) {
-*   for (const value of values) {
-*     console.log(value);
-*   }
-* }
-* ```
 */
 function getPropertyValuesByUuid(properties, uuid, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = options;
@@ -335,14 +318,6 @@ function getPropertyValuesByUuid(properties, uuid, options = DEFAULT_OPTIONS) {
 * @param uuid - The UUID to search for
 * @param options - Search options, including whether to include nested properties
 * @returns The first property value as string, or null if property not found
-*
-* @example
-* ```ts
-* const title = getPropertyValueByUuid(properties, "123e4567-e89b-12d3-a456-426614174000");
-* if (title) {
-*   console.log(`Document title: ${title}`);
-* }
-* ```
 */
 function getPropertyValueByUuid(properties, uuid, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = options;
@@ -363,14 +338,6 @@ function getPropertyValueByUuid(properties, uuid, options = DEFAULT_OPTIONS) {
 * @param label - The label to search for
 * @param options - Search options, including whether to include nested properties
 * @returns The matching Property object, or null if not found
-*
-* @example
-* ```ts
-* const property = getPropertyByLabel(properties, "author", { includeNestedProperties: true });
-* if (property) {
-*   console.log(property.values);
-* }
-* ```
 */
 function getPropertyByLabel(properties, label, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = options;
@@ -391,16 +358,6 @@ function getPropertyByLabel(properties, label, options = DEFAULT_OPTIONS) {
 * @param label - The label to search for
 * @param options - Search options, including whether to include nested properties
 * @returns Array of property values as strings, or null if property not found
-*
-* @example
-* ```ts
-* const values = getPropertyValuesByLabel(properties, "keywords");
-* if (values) {
-*   for (const value of values) {
-*     console.log(value);
-*   }
-* }
-* ```
 */
 function getPropertyValuesByLabel(properties, label, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = options;
@@ -421,14 +378,6 @@ function getPropertyValuesByLabel(properties, label, options = DEFAULT_OPTIONS)
 * @param label - The label to search for
 * @param options - Search options, including whether to include nested properties
 * @returns The first property value as string, or null if property not found
-*
-* @example
-* ```ts
-* const title = getPropertyValueByLabel(properties, "title");
-* if (title) {
-*   console.log(`Document title: ${title}`);
-* }
-* ```
 */
 function getPropertyValueByLabel(properties, label, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = options;
@@ -448,12 +397,6 @@ function getPropertyValueByLabel(properties, label, options = DEFAULT_OPTIONS) {
 * @param properties - Array of properties to get unique properties from
 * @param options - Search options, including whether to include nested properties
 * @returns Array of unique properties
-*
-* @example
-* ```ts
-* const properties = getAllUniqueProperties(properties, { includeNestedProperties: true });
-* console.log(`Available properties: ${properties.map((p) => p.label).join(", ")}`);
-* ```
 */
 function getUniqueProperties(properties, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = options;
@@ -477,12 +420,6 @@ function getUniqueProperties(properties, options = DEFAULT_OPTIONS) {
 * @param properties - Array of properties to get unique property labels from
 * @param options - Search options, including whether to include nested properties
 * @returns Array of unique property labels
-*
-* @example
-* ```ts
-* const properties = getAllUniquePropertyLabels(properties, { includeNestedProperties: true });
-* console.log(`Available properties: ${properties.join(", ")}`);
-* ```
 */
 function getUniquePropertyLabels(properties, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = options;
@@ -509,17 +446,6 @@ function getUniquePropertyLabels(properties, options = DEFAULT_OPTIONS) {
 * @param filter.value - The value to filter by
 * @param options - Search options, including whether to include nested properties
 * @returns True if the property matches the filter criteria, false otherwise
-*
-* @example
-* ```ts
-* const matches = filterProperties(property, {
-*   label: "category",
-*   value: "book"
-* });
-* if (matches) {
-*   console.log("Property matches filter criteria");
-* }
-* ```
 */
 function filterProperties(property, filter, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = options;
@@ -548,7 +474,7 @@ function filterProperties(property, filter, options = DEFAULT_OPTIONS) {
 
 //#endregion
 //#region src/constants.ts
-const BELONG_TO_COLLECTION_UUID = "30054cb2-909a-4f34-8db9-8fe7369d691d";
+const BELONGS_TO_COLLECTION_UUID = "30054cb2-909a-4f34-8db9-8fe7369d691d";
 const PRESENTATION_ITEM_UUID = "f1c131b6-1498-48a4-95bf-a9edae9fd518";
 const TEXT_ANNOTATION_UUID = "b9ca2732-78f4-416e-b77f-dae7647e68a9";
 const TEXT_ANNOTATION_HOVER_CARD_UUID = "c7f6a08a-f07b-49b6-bcb1-af485da3c58f";
@@ -576,12 +502,6 @@ function getStringItemByLanguage(content, language) {
 *
 * @param string - Input string to parse
 * @returns String with emails converted to HTML links
-*
-* @example
-* ```ts
-* const parsed = parseEmail("Contact us at info@example.com");
-* // Returns: "Contact us at <ExternalLink href="mailto:info@example.com">info@example.com</ExternalLink>"
-* ```
 */
 function parseEmail(string) {
 	const splitString = string.split(" ");
@@ -661,13 +581,6 @@ function parseWhitespace(contentString, whitespace) {
 *
 * @param string - FakeString value to convert
 * @returns Converted string value
-*
-* @example
-* ```ts
-* parseFakeString(true); // Returns "Yes"
-* parseFakeString(123); // Returns "123"
-* parseFakeString("test"); // Returns "test"
-* ```
 */
 function parseFakeString(string) {
 	return String(string).replaceAll("&#39;", "'").replaceAll("{", String.raw`\{`).replaceAll("}", String.raw`\}`);
@@ -1106,7 +1019,10 @@ function parseMetadata(metadata) {
 	let collectionIdentification = null;
 	if (metadata.collection) collectionIdentification = parseIdentification(metadata.collection.identification);
 	return {
-		project: projectIdentification ? { identification: projectIdentification } : null,
+		project: projectIdentification ? {
+			identification: projectIdentification,
+			dateFormat: metadata.project?.dateFormat ?? null
+		} : null,
 		collection: collectionIdentification ? { identification: collectionIdentification } : null,
 		item: metadata.item ? {
 			identification,
@@ -1225,13 +1141,13 @@ function parsePersons(persons) {
 * @returns Parsed Link object
 */
 function parseLink(linkRaw) {
-	const links = "resource" in linkRaw ? linkRaw.resource : "spatialUnit" in linkRaw ? linkRaw.spatialUnit : "concept" in linkRaw ? linkRaw.concept : "set" in linkRaw ? linkRaw.set : "tree" in linkRaw ? linkRaw.tree : "person" in linkRaw ? linkRaw.person : "bibliography" in linkRaw ? linkRaw.bibliography : "propertyValue" in linkRaw ? linkRaw.propertyValue : null;
+	const links = "resource" in linkRaw ? linkRaw.resource : "spatialUnit" in linkRaw ? linkRaw.spatialUnit : "concept" in linkRaw ? linkRaw.concept : "set" in linkRaw ? linkRaw.set : "tree" in linkRaw ? linkRaw.tree : "person" in linkRaw ? linkRaw.person : "bibliography" in linkRaw ? linkRaw.bibliography : "propertyVariable" in linkRaw ? linkRaw.propertyVariable : "propertyValue" in linkRaw ? linkRaw.propertyValue : null;
 	if (!links) throw new Error(`Invalid link provided: ${JSON.stringify(linkRaw, null, 2)}`);
 	const linksToParse = Array.isArray(links) ? links : [links];
 	const returnLinks = [];
 	for (const link of linksToParse) {
 		const returnLink = {
-			category: "resource" in linkRaw ? "resource" : "spatialUnit" in linkRaw ? "spatialUnit" : "concept" in linkRaw ? "concept" : "set" in linkRaw ? "set" : "person" in linkRaw ? "person" : "tree" in linkRaw ? "tree" : "bibliography" in linkRaw ? "bibliography" : "propertyValue" in linkRaw ? "propertyValue" : null,
+			category: "resource" in linkRaw ? "resource" : "spatialUnit" in linkRaw ? "spatialUnit" : "concept" in linkRaw ? "concept" : "set" in linkRaw ? "set" : "person" in linkRaw ? "person" : "tree" in linkRaw ? "tree" : "bibliography" in linkRaw ? "bibliography" : "propertyVariable" in linkRaw ? "propertyVariable" : "propertyValue" in linkRaw ? "propertyValue" : null,
 			content: "content" in link ? link.content != null ? parseFakeString(link.content) : null : null,
 			href: "href" in link && link.href != null ? link.href : null,
 			fileFormat: "fileFormat" in link && link.fileFormat != null ? link.fileFormat : null,
@@ -1438,8 +1354,7 @@ function parseObservations(observations) {
 function parseEvents(events) {
 	const returnEvents = [];
 	for (const event of events) returnEvents.push({
-		dateTime: event.dateTime != null ? parseISO(event.dateTime) : null,
-		date: event.partialDates?.year != null ? `${event.partialDates.year}-01-01/${event.partialDates.endYear ?? event.partialDates.year}-12-31` : null,
+		dateTime: event.endDateTime != null ? `${event.dateTime}/${event.endDateTime}` : event.dateTime ?? null,
 		label: parseStringContent(event.label),
 		location: event.location ? {
 			uuid: event.location.uuid,
@@ -1577,7 +1492,7 @@ function parseProperties(properties, language = "eng") {
 function parseInterpretations(interpretations) {
 	const returnInterpretations = [];
 	for (const interpretation of interpretations) returnInterpretations.push({
-		date: interpretation.date,
+		date: interpretation.date ?? null,
 		number: interpretation.interpretationNo,
 		links: interpretation.links ? parseLinks(Array.isArray(interpretation.links) ? interpretation.links : [interpretation.links]) : [],
 		properties: interpretation.properties ? parseProperties(Array.isArray(interpretation.properties.property) ? interpretation.properties.property : [interpretation.properties.property]) : [],
@@ -1713,6 +1628,38 @@ function parseBibliography(bibliography, metadata, persistentUrl, belongsTo) {
 	};
 }
 /**
+* Parses raw property variable data into a standardized PropertyVariable structure
+*
+* @param propertyVariable - Raw property variable data in OCHRE format
+* @returns Parsed PropertyVariable object
+*/
+function parsePropertyVariable(propertyVariable, metadata, persistentUrl, belongsTo) {
+	return {
+		uuid: propertyVariable.uuid,
+		category: "propertyVariable",
+		belongsTo: belongsTo ?? null,
+		metadata: metadata ?? null,
+		persistentUrl: persistentUrl ?? null,
+		type: propertyVariable.type,
+		number: propertyVariable.n,
+		publicationDateTime: propertyVariable.publicationDateTime ? parseISO(propertyVariable.publicationDateTime) : null,
+		context: propertyVariable.context ? parseContext(propertyVariable.context) : null,
+		availability: propertyVariable.availability ? parseLicense(propertyVariable.availability) : null,
+		identification: parseIdentification(propertyVariable.identification)
+	};
+}
+/**
+* Parses an array of raw property variables into standardized PropertyVariable objects
+*
+* @param propertyVariables - Array of raw property variables in OCHRE format
+* @returns Array of parsed PropertyVariable objects
+*/
+function parsePropertyVariables(propertyVariables) {
+	const returnPropertyVariables = [];
+	for (const propertyVariable of propertyVariables) returnPropertyVariables.push(parsePropertyVariable(propertyVariable));
+	return returnPropertyVariables;
+}
+/**
 * Parses an array of raw bibliographies into standardized Bibliography objects
 *
 * @param bibliographies - Array of raw bibliographies in OCHRE format
@@ -1879,6 +1826,10 @@ function parseTree(tree, itemCategories, metadata, persistentUrl, belongsTo) {
 			if (!("person" in tree.items)) throw new Error("Invalid OCHRE data: Tree has no persons");
 			items = parsePersons(Array.isArray(tree.items.person) ? tree.items.person : [tree.items.person]);
 			break;
+		case "propertyVariable":
+			if (!("propertyVariable" in tree.items)) throw new Error("Invalid OCHRE data: Tree has no property variables");
+			items = parsePropertyVariables(Array.isArray(tree.items.propertyVariable) ? tree.items.propertyVariable : [tree.items.propertyVariable]);
+			break;
 		case "propertyValue":
 			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]);
@@ -1959,6 +1910,10 @@ function parseSet(set, itemCategories, metadata, persistentUrl, belongsTo) {
 			if (!("person" in set.items) || set.items.person == null) throw new Error("Invalid OCHRE data: Set has no persons");
 			items.push(...parsePersons(Array.isArray(set.items.person) ? set.items.person : [set.items.person]));
 			break;
+		case "propertyVariable":
+			if (!("propertyVariable" in set.items) || set.items.propertyVariable == null) throw new Error("Invalid OCHRE data: Set has no property variables");
+			items.push(...parsePropertyVariables(Array.isArray(set.items.propertyVariable) ? set.items.propertyVariable : [set.items.propertyVariable]));
+			break;
 		case "propertyValue":
 			if (!("propertyValue" in set.items) || set.items.propertyValue == null) throw new Error("Invalid OCHRE data: Set has no property values");
 			items.push(...parsePropertyValues(Array.isArray(set.items.propertyValue) ? set.items.propertyValue : [set.items.propertyValue]));
@@ -3357,24 +3312,7 @@ function parseWebsite(websiteTree, metadata, belongsTo, { version = DEFAULT_API_
 * @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 The parsed gallery or null if the fetch/parse fails
-*
-* @example
-* ```ts
-* const gallery = await fetchGallery("9c4da06b-f15e-40af-a747-0933eaf3587e", "1978", 1, 12);
-* if (gallery === null) {
-*   console.error("Failed to fetch gallery");
-*   return;
-* }
-* console.log(`Fetched gallery: ${gallery.identification.label}`);
-* console.log(`Contains ${gallery.resources.length.toLocaleString()} resources`);
-* ```
-*
-* @remarks
-* The returned gallery includes:
-* - Gallery metadata and identification
-* - Project identification
-* - Resources (gallery items)
+* @returns The parsed gallery or an error message if the fetch/parse fails
 */
 async function fetchGallery(uuid, filter, page, pageSize, options) {
 	try {
@@ -3422,17 +3360,6 @@ async function fetchGallery(uuid, filter, page, pageSize, options) {
 *
 * @param uuid - The UUID of the OCHRE item to fetch
 * @returns A tuple containing either [null, OchreData] on success or [error message, null] on failure
-*
-* @example
-* ```ts
-* const [error, data] = await fetchByUuid("123e4567-e89b-12d3-a456-426614174000");
-* if (error !== null) {
-*   console.error(`Failed to fetch: ${error}`);
-*   return;
-* }
-* // Process data...
-* ```
-*
 * @internal
 */
 async function fetchByUuid(uuid, options) {
@@ -3455,34 +3382,7 @@ async function fetchByUuid(uuid, options) {
 * Fetches and parses an OCHRE item from the OCHRE API
 *
 * @param uuid - The UUID of the OCHRE item to fetch
-* @returns Object containing the parsed OCHRE item and its metadata, or null if the fetch/parse fails
-*
-* @example
-* ```ts
-* const result = await fetchItem("123e4567-e89b-12d3-a456-426614174000");
-* if (result === null) {
-*   console.error("Failed to fetch OCHRE item");
-*   return;
-* }
-* const { metadata, belongsTo, item, category } = result;
-* console.log(`Fetched OCHRE item: ${item.identification.label} with category ${category}`);
-* ```
-*
-* Or, if you want to fetch a specific category, you can do so by passing the category as an argument:
-* ```ts
-* const result = await fetchItem("123e4567-e89b-12d3-a456-426614174000", "resource");
-* const { metadata, belongsTo, item, category } = result;
-* console.log(item.category); // "resource"
-* ```
-*
-* @remarks
-* The returned OCHRE item includes:
-* - Item metadata
-* - Item belongsTo information
-* - Item content
-* - Item category
-*
-* If the fetch/parse fails, the returned object will have an `error` property.
+* @returns Object containing the parsed OCHRE item, or an error message if the fetch/parse fails
 */
 async function fetchItem(uuid, category, itemCategories, options) {
 	try {
@@ -3492,7 +3392,7 @@ async function fetchItem(uuid, category, itemCategories, options) {
 			version
 		});
 		if (error !== null) throw new Error(error);
-		const categoryKey = getItemCategory(Object.keys(data.ochre));
+		const categoryKey = category ?? getItemCategory(Object.keys(data.ochre));
 		const belongsTo = {
 			uuid: data.ochre.uuidBelongsTo,
 			abbreviation: parseFakeString(data.ochre.belongsTo)
@@ -3527,6 +3427,10 @@ async function fetchItem(uuid, category, itemCategories, options) {
 				if (!("person" in data.ochre)) throw new Error("Invalid OCHRE data: API response missing 'person' key");
 				item = parsePerson(data.ochre.person, metadata, data.ochre.persistentUrl, belongsTo);
 				break;
+			case "propertyVariable":
+				if (!("propertyVariable" in data.ochre)) throw new Error("Invalid OCHRE data: API response missing 'propertyVariable' key");
+				item = parsePropertyVariable(data.ochre.propertyVariable, metadata, data.ochre.persistentUrl, belongsTo);
+				break;
 			case "propertyValue":
 				if (!("propertyValue" in data.ochre)) throw new Error("Invalid OCHRE data: API response missing 'propertyValue' key");
 				item = parsePropertyValue(data.ochre.propertyValue, metadata, data.ochre.persistentUrl, belongsTo);
@@ -3547,16 +3451,12 @@ async function fetchItem(uuid, category, itemCategories, options) {
 		}
 		return {
 			error: null,
-			item,
-			category,
-			itemCategories
+			item
 		};
 	} catch (error) {
 		return {
 			error: error instanceof Error ? error.message : "Unknown error",
-			item: void 0,
-			category: void 0,
-			itemCategories: void 0
+			item: null
 		};
 	}
 }
@@ -3584,7 +3484,7 @@ function buildXQuery$2(params, options) {
 	const startPos = (page - 1) * pageSize + 1;
 	const endPos = page * pageSize;
 	let belongsToCollectionScopeFilter = "";
-	if (belongsToCollectionScopeUuids.length > 0) belongsToCollectionScopeFilter = `[.//properties[property[label/@uuid="${BELONG_TO_COLLECTION_UUID}" and value/(${belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]]`;
+	if (belongsToCollectionScopeUuids.length > 0) belongsToCollectionScopeFilter = `[.//properties[property[label/@uuid="${BELONGS_TO_COLLECTION_UUID}" and value/(${belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]]`;
 	const propertyVariables = propertyVariableUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
 	const propertyValuesFilters = propertyValues.map(({ dataType, value }) => {
 		if (dataType === "IDREF") return `value[@uuid="${value}"]`;
@@ -3680,6 +3580,10 @@ async function fetchItemsByPropertyValues(params, categoryParams, options) {
 			const persons = parsePersons(Array.isArray(data.result.ochre.items.person) ? data.result.ochre.items.person : [data.result.ochre.items.person]);
 			items.push(...persons);
 		}
+		if ("propertyVariable" in data.result.ochre.items && data.result.ochre.items.propertyVariable != null) {
+			const propertyVariables = parsePropertyVariables(Array.isArray(data.result.ochre.items.propertyVariable) ? data.result.ochre.items.propertyVariable : [data.result.ochre.items.propertyVariable]);
+			items.push(...propertyVariables);
+		}
 		if ("propertyValue" in data.result.ochre.items && data.result.ochre.items.propertyValue != null) {
 			const propertyValues = parsePropertyValues(Array.isArray(data.result.ochre.items.propertyValue) ? data.result.ochre.items.propertyValue : [data.result.ochre.items.propertyValue]);
 			items.push(...propertyValues);
@@ -3733,7 +3637,7 @@ function buildXQuery$1(params, options) {
 	const version = options?.version ?? DEFAULT_API_VERSION;
 	const { projectScopeUuid, belongsToCollectionScopeUuids, itemCategory, itemUuids, linkUuids } = params;
 	let belongsToCollectionScopeFilter = "";
-	if (belongsToCollectionScopeUuids.length > 0) belongsToCollectionScopeFilter = `properties/property[label/@uuid="${BELONG_TO_COLLECTION_UUID}"][value[${belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")}]]`;
+	if (belongsToCollectionScopeUuids.length > 0) belongsToCollectionScopeFilter = `properties/property[label/@uuid="${BELONGS_TO_COLLECTION_UUID}"][value[${belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")}]]`;
 	let itemCategoryFilter = "";
 	const filterParts = [];
 	if (itemUuids.length > 0) filterParts.push(itemUuids.map((uuid) => `@uuid="${uuid}"`).join(" or "));
@@ -3812,6 +3716,10 @@ async function fetchItemsByUuidsAndLinks(params, categoryParams, options) {
 			const persons = parsePersons(Array.isArray(data.result.ochre.person) ? data.result.ochre.person : [data.result.ochre.person]);
 			items.push(...persons);
 		}
+		if ("propertyVariable" in data.result.ochre && data.result.ochre.propertyVariable != null && itemCategory === null) {
+			const propertyVariables = parsePropertyVariables(Array.isArray(data.result.ochre.propertyVariable) ? data.result.ochre.propertyVariable : [data.result.ochre.propertyVariable]);
+			items.push(...propertyVariables);
+		}
 		if ("propertyValue" in data.result.ochre && data.result.ochre.propertyValue != null && itemCategory === null) {
 			const propertyValues = parsePropertyValues(Array.isArray(data.result.ochre.propertyValue) ? data.result.ochre.propertyValue : [data.result.ochre.propertyValue]);
 			items.push(...propertyValues);
@@ -3848,6 +3756,7 @@ async function fetchItemsByUuidsAndLinks(params, categoryParams, options) {
 */
 const propertyValueQueryItemSchema = z.object({
 	uuid: z.string(),
+	itemUuid: z.string().optional(),
 	dataType: z.string(),
 	rawValue: z.union([
 		z.string(),
@@ -3863,6 +3772,7 @@ const propertyValueQueryItemSchema = z.object({
 	]).optional()
 }).transform((val) => {
 	const returnValue = {
+		itemUuid: val.itemUuid != null && val.itemUuid !== "" ? val.itemUuid : null,
 		dataType: val.dataType,
 		content: null,
 		label: null
@@ -3907,16 +3817,17 @@ function buildXQuery(params, options) {
 	const version = options?.version ?? DEFAULT_API_VERSION;
 	const { projectScopeUuid, belongsToCollectionScopeUuids, propertyVariableUuids } = params;
 	let collectionScopeFilter = "";
-	if (belongsToCollectionScopeUuids.length > 0) collectionScopeFilter = `//properties[property[label/@uuid="${BELONG_TO_COLLECTION_UUID}" and value/(${belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]]`;
+	if (belongsToCollectionScopeUuids.length > 0) collectionScopeFilter = `//properties[property[label/@uuid="${BELONGS_TO_COLLECTION_UUID}" and value/(${belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]]`;
 	const propertyVariableFilters = propertyVariableUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
 	return `<ochre>{${`let $matching-props := ${version === 2 ? "doc()" : "input()"}/ochre[@uuidBelongsTo="${projectScopeUuid}"]
       ${collectionScopeFilter}
       //property[label/(${propertyVariableFilters})]
 
   for $v in $matching-props/value
-  return <propertyValue uuid="{$v/@uuid}" rawValue="{$v/@rawValue}" dataType="{$v/@dataType}">{
-    if ($v/content) then $v/content else $v/text()
-  }</propertyValue>`}}</ochre>`;
+    let $item-uuid := $v/ancestor::*[parent::ochre]/@uuid
+    return <propertyValue uuid="{$v/@uuid}" rawValue="{$v/@rawValue}" dataType="{$v/@dataType}" itemUuid="{$item-uuid}">{
+      if ($v/content) then $v/content else $v/text()
+    }</propertyValue>`}}</ochre>`;
 }
 /**
 * Fetches and parses property values by property variables from the OCHRE API
@@ -3945,15 +3856,24 @@ async function fetchPropertyValuesByPropertyVariables(params, options) {
 		const parsedResultRaw = responseSchema.parse(data);
 		if (Array.isArray(parsedResultRaw.result)) throw new TypeError("No items found");
 		const parsedItems = Array.isArray(parsedResultRaw.result.ochre.propertyValue) ? parsedResultRaw.result.ochre.propertyValue : [parsedResultRaw.result.ochre.propertyValue];
-		const groupedItems = [];
+		const groupedItemsMap = /* @__PURE__ */ new Map();
 		for (const item of parsedItems) {
-			const existingItem = groupedItems.find((i) => i.content === item.content);
-			if (existingItem == null) groupedItems.push({
-				count: 1,
-				...item
+			const existing = groupedItemsMap.get(item.content);
+			if (existing == null) groupedItemsMap.set(item.content, {
+				dataType: item.dataType,
+				content: item.content,
+				label: item.label,
+				itemUuids: new Set([item.itemUuid])
 			});
-			else existingItem.count++;
+			else existing.itemUuids.add(item.itemUuid);
 		}
+		const groupedItems = [];
+		for (const group of groupedItemsMap.values()) groupedItems.push({
+			count: group.itemUuids.size,
+			dataType: group.dataType,
+			content: group.content,
+			label: group.label
+		});
 		return {
 			items: groupedItems.toSorted((a, b) => {
 				if (a.count !== b.count) return b.count - a.count;
@@ -3996,29 +3916,6 @@ function parseApiVersionSuffix(abbreviation) {
 *
 * @param abbreviation - The abbreviation identifier for the website
 * @returns The parsed website configuration or null if the fetch/parse fails
-*
-* @example
-* ```ts
-* const website = await fetchWebsite("guerrilla-television");
-* if (website === null) {
-*   console.error("Failed to fetch website");
-*   return;
-* }
-* console.log(`Fetched website: ${website.identification.label}`);
-* console.log(`Contains ${website.pages.length.toLocaleString()} pages`);
-* ```
-*
-* @remarks
-* The returned website configuration includes:
-* - Website metadata and identification
-* - Page structure and content
-* - Layout and styling properties
-* - Navigation configuration
-* - Sidebar elements
-* - Project information
-* - Creator details
-*
-* The abbreviation is case-insensitive and should match the website's configured abbreviation in OCHRE.
 */
 async function fetchWebsite(abbreviation, options) {
 	try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalculture/ochre-sdk",
-  "version": "0.18.16",
+  "version": "0.18.18",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -46,11 +46,11 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "^7.2.0",
-    "@types/node": "^24.10.10",
-    "bumpp": "^10.4.0",
+    "@types/node": "^24.10.11",
+    "bumpp": "^10.4.1",
     "eslint": "^9.39.2",
     "prettier": "^3.8.1",
-    "tsdown": "^0.20.1",
+    "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },