@digitalculture/ochre-sdk 0.5.19 → 0.6.0

package/dist/index.d.cts

@@ -3,7 +3,7 @@ import { Language } from 'iso-639-3';
 /**
  * Represents the core data structure containing item information and metadata
  */
-type Data = {
+type Data<T extends DataCategory> = {
     uuid: string;
     belongsTo: {
         uuid: string;
@@ -11,8 +11,9 @@ type Data = {
     };
     publicationDateTime: Date;
     metadata: Metadata;
-    item: Tree | Set | Resource | SpatialUnit | Concept | Period | Bibliography | Person | PropertyValue;
+    item: Tree | Set<T> | Resource | SpatialUnit | Concept | Period | Bibliography | Person | PropertyValue;
 };
+type DataCategory = "tree" | "set" | "resource" | "spatialUnit" | "concept" | "period" | "bibliography" | "person" | "propertyValue";
 /**
  * Basic identification information used across multiple types
  */
@@ -226,12 +227,8 @@ type Resource = {
     reverseLinks: Array<Link>;
     properties: Array<Property>;
     citedBibliographies: Array<Bibliography>;
-    resources: Array<NestedResource>;
+    resources: Array<Resource>;
 };
-/**
- * A nested version of Resource type without certain metadata fields
- */
-type NestedResource = Omit<Resource, "publicationDateTime" | "license" | "copyright">;
 /**
  * Represents a spatial unit with geographic coordinates and observations
  */
@@ -249,11 +246,6 @@ type SpatialUnit = {
     coordinates: Coordinates | null;
     observations: Array<Observation>;
     events: Array<Event>;
-};
-/**
- * A nested version of SpatialUnit type without certain metadata fields
- */
-type NestedSpatialUnit = Omit<SpatialUnit, "publicationDateTime" | "license" | "observations" | "events"> & {
     properties: Array<Property>;
 };
 /**
@@ -269,16 +261,13 @@ type Concept = {
     identification: Identification;
     interpretations: Array<Interpretation>;
 };
-/**
- * A nested version of Concept type without certain metadata fields
- */
-type NestedConcept = Omit<Concept, "publicationDateTime" | "license">;
 /**
  * Represents a set that can contain resources, spatial units and concepts
  */
-type Set = {
+type Set<T extends DataCategory> = {
     uuid: string;
     category: "set";
+    itemCategory: T;
     publicationDateTime: Date | null;
     type: string;
     number: number;
@@ -288,15 +277,7 @@ type Set = {
     isSuppressingBlanks: boolean;
     description: string;
     creators: Array<Person>;
-    items: {
-        resources: Array<NestedResource>;
-        spatialUnits: Array<NestedSpatialUnit>;
-        concepts: Array<NestedConcept>;
-        periods: Array<Period>;
-        bibliographies: Array<Bibliography>;
-        persons: Array<Person>;
-        propertyValues: Array<PropertyValue>;
-    };
+    items: T extends "resource" ? Array<Resource> : T extends "spatialUnit" ? Array<SpatialUnit> : T extends "concept" ? Array<Concept> : T extends "period" ? Array<Period> : T extends "bibliography" ? Array<Bibliography> : T extends "person" ? Array<Person> : T extends "propertyValue" ? Array<PropertyValue> : never;
 };
 /**
  * Represents a bibliography entry with citation and publication information
@@ -639,92 +620,54 @@ type WebBlock = {
 };
 
 /**
- * Fetches and parses a bibliography from the OCHRE API
+ * Fetches and parses an OCHRE item from the OCHRE API
  *
- * @param uuid - The UUID of the bibliography to fetch
- * @returns Object containing the parsed bibliography and its metadata, or null if the fetch/parse fails
+ * @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 fetchBibliography("123e4567-e89b-12d3-a456-426614174000");
+ * const result = await fetchItem("123e4567-e89b-12d3-a456-426614174000");
  * if (result === null) {
- *   console.error("Failed to fetch bibliography");
+ *   console.error("Failed to fetch OCHRE item");
  *   return;
  * }
- * const { metadata, item } = result;
- * console.log(`Fetched bibliography: ${item.identification.label}`);
+ * const { metadata, belongsTo, item, category } = result;
+ * console.log(`Fetched OCHRE item: ${item.identification.label} with category ${category}`);
  * ```
  *
- * @remarks
- * The returned bibliography includes:
- * - Full bibliography metadata
- * - Citation and reference information
- * - Publication information
- * - Source information
- * - Author information
- * - Properties
- */
-declare function fetchBibliography(uuid: string): Promise<{
-    metadata: Metadata;
-    bibliography: Bibliography;
-} | null>;
-
-/**
- * Fetches and parses a concept from the OCHRE API
- *
- * @param uuid - The UUID of the concept to fetch
- * @returns Object containing the parsed concept and its metadata, or null if the fetch/parse fails
- *
- * @example
+ * Or, if you want to fetch a specific category, you can do so by passing the category as an argument:
  * ```ts
- * const result = await fetchConcept("123e4567-e89b-12d3-a456-426614174000");
- * if (result === null) {
- *   console.error("Failed to fetch concept");
- *   return;
- * }
- * const { metadata, item } = result;
- * console.log(`Fetched concept: ${item.identification.label}`);
+ * const result = await fetchItem("123e4567-e89b-12d3-a456-426614174000", "resource");
+ * const { metadata, belongsTo, item, category } = result;
+ * console.log(item.category); // "resource"
  * ```
  *
  * @remarks
- * The returned concept includes:
- * - Full concept metadata
- * - Interpretations and their properties
- * - Context information
- * - License details
- */
-declare function fetchConcept(uuid: string): Promise<{
-    metadata: Metadata;
-    concept: Concept;
-} | null>;
-
-/**
- * Fetches and parses a gallery from the OCHRE API
- *
- * @param uuid - The UUID of the gallery
- * @param filter - The filter to apply to the gallery
- * @param page - The page number to fetch
- * @param perPage - The number of items per page
- * @returns The parsed gallery or null if the fetch/parse fails
+ * The returned OCHRE item includes:
+ * - Item metadata
+ * - Item belongsTo information
+ * - Item content
+ * - Item category
  *
- * @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)
+ * If the fetch/parse fails, the returned object will have an `error` property.
  */
-declare function fetchGallery(uuid: string, filter: string, page: number, perPage: number): Promise<Gallery | null>;
+declare function fetchItem<T extends DataCategory, U extends DataCategory>(uuid: string, category?: T): Promise<{
+    error: null;
+    metadata: Metadata;
+    belongsTo: {
+        uuid: string;
+        abbreviation: string;
+    };
+    item: 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 "set" ? Set<U> : T extends "tree" ? Tree : never;
+    category: T;
+} | {
+    error: string;
+    metadata: never;
+    belongsTo: never;
+    item: never;
+    category: never;
+}>;
 
 /**
  * Raw string value that can be a string, number, or boolean
@@ -931,17 +874,9 @@ type OchreResource = {
   citedBibliography?: {
     reference: OchreBibliography | Array<OchreBibliography>;
   };
-  resource?: OchreNestedResource | Array<OchreNestedResource>;
+  resource?: OchreResource | Array<OchreResource>;
 };
 
-/**
- * Raw nested resource structure corresponding to the parsed NestedResource type
- */
-type OchreNestedResource = Omit<
-  OchreResource,
-  "context" | "availability" | "copyright"
->;
-
 /**
  * Raw spatial unit structure corresponding to the parsed SpatialUnit type
  */
@@ -959,15 +894,6 @@ type OchreSpatialUnit = {
   events?: { event: OchreEvent | Array<OchreEvent> };
   observations?: { observation: OchreObservation | Array<OchreObservation> };
   observation?: OchreObservation;
-};
-
-/**
- * Raw nested spatial unit structure corresponding to the parsed NestedSpatialUnit type
- */
-type OchreNestedSpatialUnit = Omit<
-  OchreSpatialUnit,
-  "context" | "availability" | "observations" | "events"
-> & {
   properties?: { property: OchreProperty | Array<OchreProperty> };
 };
 
@@ -986,11 +912,6 @@ type OchreConcept = {
   };
 };
 
-/**
- * Raw nested concept structure corresponding to the parsed NestedConcept type
- */
-type OchreNestedConcept = Omit<OchreConcept, "context" | "availability">;
-
 /**
  * Raw property value structure corresponding to the parsed PropertyValue type
  */
@@ -1335,222 +1256,6 @@ type OchrePropertyValue = {
  */
 declare function fetchByUuid(uuid: string): Promise<[null, OchreData] | [string, null]>;
 
-/**
- * Fetches and parses a period from the OCHRE API
- *
- * @param uuid - The UUID of the period to fetch
- * @returns Object containing the parsed period and its metadata, or null if the fetch/parse fails
- *
- * @example
- * ```ts
- * const result = await fetchPeriod("123e4567-e89b-12d3-a456-426614174000");
- * if (result === null) {
- *   console.error("Failed to fetch period");
- *   return;
- * }
- * const { metadata, item } = result;
- * console.log(`Fetched period: ${item.identification.label}`);
- * ```
- *
- * @remarks
- * The returned period includes:
- * - Full period metadata
- * - Identification information
- * - Description
- * - Properties
- */
-declare function fetchPeriod(uuid: string): Promise<{
-    metadata: Metadata;
-    period: Period;
-} | null>;
-
-/**
- * Fetches and parses a property value from the OCHRE API
- *
- * @param uuid - The UUID of the property value to fetch
- * @returns Object containing the parsed property value and its metadata, or null if the fetch/parse fails
- *
- * @example
- * ```ts
- * const result = await fetchPropertyValue("123e4567-e89b-12d3-a456-426614174000");
- * if (result === null) {
- *   console.error("Failed to fetch property value");
- *   return;
- * }
- * const { metadata, item } = result;
- * console.log(`Fetched property value: ${item.identification.label}`);
- * ```
- *
- * @remarks
- * The returned property value includes:
- * - Identification
- * - Description
- * - Notes
- * - Links
- */
-declare function fetchPropertyValue(uuid: string): Promise<{
-    metadata: Metadata;
-    propertyValue: PropertyValue;
-} | null>;
-
-/**
- * Fetches and parses a resource from the OCHRE API
- *
- * @param uuid - The UUID of the resource to fetch
- * @returns Object containing the parsed resource and its metadata, or null if the fetch/parse fails
- *
- * @example
- * ```ts
- * const result = await fetchResource("123e4567-e89b-12d3-a456-426614174000");
- * if (result === null) {
- *   console.error("Failed to fetch resource");
- *   return;
- * }
- * const { metadata, item } = result;
- * console.log(`Fetched resource: ${item.identification.label}`);
- * ```
- *
- * @remarks
- * The returned resource includes:
- * - Full resource metadata
- * - Associated documents and images
- * - Links and reverse links
- * - Creator information
- * - Notes and bibliographic references
- * - Properties and nested resources
- */
-declare function fetchResource(uuid: string): Promise<{
-    metadata: Metadata;
-    resource: Resource;
-} | null>;
-
-/**
- * Fetches and parses a set from the OCHRE API
- *
- * @param uuid - The UUID of the set to fetch
- * @returns Object containing the parsed set and its metadata, or null if the fetch/parse fails
- *
- * @example
- * ```ts
- * const result = await fetchSet("123e4567-e89b-12d3-a456-426614174000");
- * if (result === null) {
- *   console.error("Failed to fetch set");
- *   return;
- * }
- * const { metadata, item } = result;
- * console.log(`Fetched set: ${item.identification.label}`);
- * console.log(`Contains ${item.items.resources.length.toLocaleString()} resources`);
- * ```
- *
- * @remarks
- * The returned set includes:
- * - Full set metadata
- * - Nested resources, spatial units, and concepts
- * - Creator information
- * - Description and type information
- * - License details
- */
-declare function fetchSet(uuid: string): Promise<{
-    metadata: Metadata;
-    set: Set;
-} | null>;
-
-/**
- * Fetches and parses a spatial unit from the OCHRE API
- *
- * @param uuid - The UUID of the spatial unit to fetch
- * @returns Object containing the parsed spatial unit and its metadata, or null if the fetch/parse fails
- *
- * @example
- * ```ts
- * const result = await fetchSpatialUnit("123e4567-e89b-12d3-a456-426614174000");
- * if (result === null) {
- *   console.error("Failed to fetch spatial unit");
- *   return;
- * }
- * const { metadata, item } = result;
- * console.log(`Fetched spatial unit: ${item.identification.label}`);
- * if (item.coordinates) {
- *   console.log(`Location: ${item.coordinates.latitude}, ${item.coordinates.longitude}`);
- * }
- * ```
- *
- * @remarks
- * The returned spatial unit includes:
- * - Full spatial unit metadata
- * - Geographic coordinates
- * - Observations and events
- * - Associated images
- * - Context information
- * - License details
- */
-declare function fetchSpatialUnit(uuid: string): Promise<{
-    metadata: Metadata;
-    spatialUnit: SpatialUnit;
-} | null>;
-
-/**
- * Fetches and parses a tree from the OCHRE API
- *
- * @param uuid - The UUID of the tree to fetch
- * @returns Object containing the parsed tree and its metadata, or null if the fetch/parse fails
- *
- * @example
- * ```ts
- * const result = await fetchTree("123e4567-e89b-12d3-a456-426614174000");
- * if (result === null) {
- *   console.error("Failed to fetch tree");
- *   return;
- * }
- * const { metadata, item } = result;
- * console.log(`Fetched tree: ${item.identification.label}`);
- * console.log(`Contains ${item.items.resources.length} resources`);
- * ```
- *
- * @remarks
- * The returned tree includes:
- * - Full tree metadata
- * - Hierarchical structure of resources, spatial units, and concepts
- * - Creator information
- * - Properties and type information
- * - License details
- */
-declare function fetchTree(uuid: string): Promise<{
-    metadata: Metadata;
-    tree: Tree;
-} | null>;
-
-/**
- * Fetches and parses a website configuration from the OCHRE API
- *
- * @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): Promise<Website | null>;
-
 /**
  * Options for property search operations
  */
@@ -1836,60 +1541,56 @@ declare function parsePropertyValues(propertyValues: Array<OchrePropertyValue>):
  * @param tree - Raw tree data in OCHRE format
  * @returns Parsed Tree object or null if invalid
  */
-declare function parseTree(tree: OchreTree): Tree | null;
+declare function parseTree(tree: OchreTree): Tree;
 /**
  * Parses raw set data into a standardized Set structure
  *
  * @param set - Raw set data in OCHRE format
  * @returns Parsed Set object
  */
-declare function parseSet(set: OchreSet): Set;
+declare function parseSet<T extends DataCategory>(set: OchreSet): Set<T>;
 /**
  * Parses raw resource data into a standardized Resource structure
  *
  * @param resource - Raw resource data in OCHRE format
  * @returns Parsed Resource object
  */
-declare function parseResource(resource: OchreResource | OchreNestedResource, isNested?: boolean): Resource | NestedResource;
+declare function parseResource(resource: OchreResource): Resource;
 /**
  * Parses raw resource data into a standardized Resource structure
  *
  * @param resources - Raw resource data in OCHRE format
  * @returns Parsed Resource object
  */
-declare function parseResources(resources: Array<OchreResource> | Array<OchreNestedResource>, isNested?: boolean): Array<Resource> | Array<NestedResource>;
+declare function parseResources(resources: Array<OchreResource>): Array<Resource>;
 /**
- * Parses raw spatial units into standardized SpatialUnit or NestedSpatialUnit objects
+ * Parses raw spatial units into standardized SpatialUnit objects
  *
  * @param spatialUnit - Raw spatial unit in OCHRE format
- * @param isNested - Whether to parse as nested spatial units
- * @returns Parsed SpatialUnit or NestedSpatialUnit object
+ * @returns Parsed SpatialUnit object
  */
-declare function parseSpatialUnit(spatialUnit: OchreSpatialUnit | OchreNestedSpatialUnit, isNested?: boolean): SpatialUnit | NestedSpatialUnit;
+declare function parseSpatialUnit(spatialUnit: OchreSpatialUnit): SpatialUnit;
 /**
- * Parses an array of raw spatial units into standardized SpatialUnit or NestedSpatialUnit objects
+ * Parses an array of raw spatial units into standardized SpatialUnit objects
  *
  * @param spatialUnits - Array of raw spatial units in OCHRE format
- * @param isNested - Whether to parse as nested spatial units
- * @returns Array of parsed SpatialUnit or NestedSpatialUnit objects
+ * @returns Array of parsed SpatialUnit objects
  */
-declare function parseSpatialUnits<T extends boolean>(spatialUnits: Array<T extends true ? OchreNestedSpatialUnit : OchreSpatialUnit>, isNested?: T): Array<T extends true ? NestedSpatialUnit : SpatialUnit>;
+declare function parseSpatialUnits(spatialUnits: Array<OchreSpatialUnit>): Array<SpatialUnit>;
 /**
- * Parses a raw concept into a standardized Concept or NestedConcept object
+ * Parses a raw concept into a standardized Concept object
  *
  * @param concept - Raw concept data in OCHRE format
- * @param isNested - Whether to parse as a nested concept
- * @returns Parsed Concept or NestedConcept object
+ * @returns Parsed Concept object
  */
-declare function parseConcept(concept: OchreConcept | OchreNestedConcept, isNested?: boolean): Concept | NestedConcept;
+declare function parseConcept(concept: OchreConcept): Concept;
 /**
- * Parses raw concept data into standardized Concept or NestedConcept objects
+ * Parses raw concept data into standardized Concept objects
  *
  * @param concepts - Array of raw concept data in OCHRE format
- * @param isNested - Whether to parse as nested concepts
- * @returns Array of parsed Concept or NestedConcept objects
+ * @returns Array of parsed Concept objects
  */
-declare function parseConcepts(concepts: Array<OchreConcept> | Array<OchreNestedConcept>, isNested?: boolean): Array<Concept> | Array<NestedConcept>;
+declare function parseConcepts(concepts: Array<OchreConcept>): Array<Concept>;
 declare function parseWebsite(websiteTree: OchreTree, projectName: FakeString, website: FakeString | null): Promise<Website>;
 
 /**
@@ -1943,4 +1644,4 @@ declare function parseStringDocumentItem(item: OchreStringRichTextItem, footnote
  */
 declare function parseStringContent(content: OchreStringContent, language?: string): string;
 
-export { type Bibliography, type Concept, type Context, type ContextItem, type ContextNode, type Coordinates, type Data, type Document, type Event, type Footnote, type Gallery, type Identification, type Image, type ImageMap, type ImageMapArea, type Interpretation, type License, type Link, type Metadata, type NestedConcept, type NestedResource, type NestedSpatialUnit, type Note, type Observation, type Period, type Person, type Property, type PropertyValue, type PropertyValueContent, type PropertyValueContentType, type Resource, type Set, type SpatialUnit, type Style, type Tree, type WebBlock, type WebElement, type WebElementComponent, type WebImage, type Webpage, type WebpageProperties, type Website, type WebsiteProperties, fetchBibliography, fetchByUuid, fetchConcept, fetchGallery, fetchPeriod, fetchPropertyValue, fetchResource, fetchSet, fetchSpatialUnit, fetchTree, fetchWebsite, filterProperties, getAllPropertyLabels, getPropertyByLabel, getPropertyValueByLabel, getPropertyValuesByLabel, parseBibliographies, parseBibliography, parseConcept, parseConcepts, parseContext, parseCoordinates, parseDocument, parseEmail, parseEvents, parseFakeString, parseIdentification, parseImage, parseImageMap, parseInterpretations, parseLanguages, parseLicense, parseLink, parseLinks, parseMetadata, parseNotes, parseObservation, parseObservations, parsePeriod, parsePeriods, parsePerson, parsePersons, parseProperties, parseProperty, parsePropertyValue, parsePropertyValues, parseResource, parseResources, parseSet, parseSpatialUnit, parseSpatialUnits, parseStringContent, parseStringDocumentItem, parseStringItem, parseTree, parseWebsite };
+export { type Bibliography, type Concept, type Context, type ContextItem, type ContextNode, type Coordinates, type Data, type DataCategory, type Document, type Event, type Footnote, type Gallery, type Identification, type Image, type ImageMap, type ImageMapArea, type Interpretation, type License, type Link, type Metadata, type Note, type Observation, type Period, type Person, type Property, type PropertyValue, type PropertyValueContent, type PropertyValueContentType, type Resource, type Set, type SpatialUnit, type Style, type Tree, type WebBlock, type WebElement, type WebElementComponent, type WebImage, type Webpage, type WebpageProperties, type Website, type WebsiteProperties, fetchByUuid, fetchItem, filterProperties, getAllPropertyLabels, getPropertyByLabel, getPropertyValueByLabel, getPropertyValuesByLabel, parseBibliographies, parseBibliography, parseConcept, parseConcepts, parseContext, parseCoordinates, parseDocument, parseEmail, parseEvents, parseFakeString, parseIdentification, parseImage, parseImageMap, parseInterpretations, parseLanguages, parseLicense, parseLink, parseLinks, parseMetadata, parseNotes, parseObservation, parseObservations, parsePeriod, parsePeriods, parsePerson, parsePersons, parseProperties, parseProperty, parsePropertyValue, parsePropertyValues, parseResource, parseResources, parseSet, parseSpatialUnit, parseSpatialUnits, parseStringContent, parseStringDocumentItem, parseStringItem, parseTree, parseWebsite };