@digitalculture/ochre-sdk/dist/index.d.cts

Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data

import { Language } from 'iso-639-3';

/**
 * Represents the core data structure containing item information and metadata
 */
type Data = {
    uuid: string;
    belongsTo: {
        uuid: string;
        abbreviation: string;
    };
    publicationDateTime: Date;
    metadata: Metadata;
    item: Tree | Set | Resource | SpatialUnit | Concept | Period | Bibliography | Person | PropertyValue;
};
/**
 * Basic identification information used across multiple types
 */
type Identification = {
    label: string;
    abbreviation: string;
};
/**
 * Metadata information for items including project, publisher and language details
 */
type Metadata = {
    project: {
        identification: Identification & {
            website: string | null;
        };
    } | null;
    item: {
        identification: Identification;
        category: string;
        type: string;
        maxLength: number | null;
    } | null;
    dataset: string;
    publisher: string;
    languages: Array<Language["iso6393"]>;
    identifier: string;
    description: string;
};
/**
 * Represents a single item in a context hierarchy with its metadata
 */
type ContextItem = {
    uuid: string;
    publicationDateTime: Date | null;
    number: number;
    content: string;
};
/**
 * Represents a node in the context tree containing tree, project and spatial unit information
 */
type ContextNode = {
    tree: ContextItem;
    project: ContextItem;
    spatialUnit: Array<ContextItem>;
};
/**
 * Contains the full context information including nodes and display path
 */
type Context = {
    nodes: Array<ContextNode>;
    displayPath: string;
};
/**
 * License information for content items
 */
type License = {
    content: string;
    url: string;
};
/**
 * Represents a person (author, creator, etc.) with their identification and metadata
 */
type Person = {
    uuid: string;
    publicationDateTime: Date | null;
    type: string | null;
    date: Date | null;
    identification: Identification | null;
    content: string | null;
};
/**
 * Represents a note with number, title and content
 */
type Note = {
    number: number;
    title: string | null;
    content: string;
};
/**
 * Represents an image with its metadata and content
 */
type Image = {
    publicationDateTime: Date | null;
    identification: Identification | null;
    url: string | null;
    htmlPrefix: string | null;
    content: string | null;
    widthPreview: number | null;
    heightPreview: number | null;
    width: number | null;
    height: number | null;
};
/**
 * Represents a link to another item with optional image and bibliographic references
 */
type Link = {
    uuid: string;
    publicationDateTime: Date | null;
    type: string | null;
    category: "resource" | "spatialUnit" | "concept" | "set" | "tree" | "person" | "bibliography" | "epigraphicUnit" | "propertyValue" | null;
    identification: Identification | null;
    content: string | null;
    href: string | null;
    image: {
        isInline: boolean;
        isPrimary: boolean;
        heightPreview: number;
        widthPreview: number;
        height: number;
        width: number;
    } | null;
    bibliographies: Array<Bibliography> | null;
};
/**
 * Represents a clickable/interactive area on an image map
 */
type ImageMapArea = {
    uuid: string;
    publicationDateTime: Date | null;
    type: string;
    title: string;
    shape: "rectangle" | "polygon";
    coords: Array<number>;
};
/**
 * Contains image map areas and dimensions
 */
type ImageMap = {
    area: Array<ImageMapArea>;
    width: number;
    height: number;
};
/**
 * Geographic coordinates with optional type and label
 */
type Coordinates = {
    latitude: number;
    longitude: number;
    type: string | null;
    label: string | null;
};
/**
 * Represents an observation with notes, links and properties
 */
type Observation = {
    number: number;
    date: Date | null;
    observers: Array<string>;
    notes: Array<Note>;
    links: Array<Link>;
    properties: Array<Property>;
};
/**
 * Represents an event with date, label and optional agent
 */
type Event = {
    date: Date | null;
    label: string;
    agent: {
        uuid: string;
        content: string;
    } | null;
};
/**
 * Represents an interpretation with date and properties
 */
type Interpretation = {
    date: Date | null;
    number: number;
    properties: Array<Property>;
};
/**
 * Represents a document with content and footnotes
 */
type Document = {
    content: string;
    footnotes: Array<Footnote>;
};
/**
 * Represents a footnote in a document
 */
type Footnote = {
    uuid: string;
    label: string;
    content: string;
};
/**
 * Represents a resource item with associated metadata, content and relationships
 */
type Resource = {
    uuid: string;
    category: "resource";
    publicationDateTime: Date | null;
    type: string;
    number: number;
    context: Context | null;
    license: License | null;
    copyright: string | null;
    identification: Identification;
    date: Date | null;
    image: Image | null;
    creators: Array<Person>;
    notes: Array<Note>;
    description: string;
    document: Document | null;
    href: string | null;
    imageMap: ImageMap | null;
    periods: Array<Period>;
    format: string | null;
    links: Array<Link>;
    reverseLinks: Array<Link>;
    properties: Array<Property>;
    citedBibliographies: Array<Bibliography>;
    resources: Array<NestedResource>;
};
/**
 * 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
 */
type SpatialUnit = {
    uuid: string;
    category: "spatialUnit";
    publicationDateTime: Date | null;
    type: string;
    number: number;
    context: Context | null;
    license: License | null;
    identification: Identification;
    image: Image | null;
    description: string | null;
    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>;
};
/**
 * Represents a concept with associated interpretations
 */
type Concept = {
    uuid: string;
    category: "concept";
    publicationDateTime: Date | null;
    number: number;
    license: License | null;
    context: Context | null;
    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 = {
    uuid: string;
    category: "set";
    publicationDateTime: Date | null;
    type: string;
    number: number;
    date: Date | null;
    license: License | null;
    identification: Identification;
    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>;
    };
};
/**
 * Represents a bibliography entry with citation and publication information
 */
type Bibliography = {
    uuid: string;
    category: "bibliography";
    publicationDateTime: Date | null;
    type: string | null;
    number: number | null;
    identification: Identification | null;
    projectIdentification: Identification | null;
    context: Context | null;
    citation: {
        format: string | null;
        short: string | null;
        long: string | null;
    };
    publicationInfo: {
        publishers: Array<Person>;
        startDate: Date | null;
    };
    entryInfo: {
        startIssue: string;
        startVolume: string;
    } | null;
    source: {
        resource: Pick<Resource, "uuid" | "publicationDateTime" | "type" | "identification"> | null;
        documentUrl: string | null;
    };
    periods: Array<Period>;
    authors: Array<Person>;
    properties: Array<Property>;
};
/**
 * Represents a time period with identification
 */
type Period = {
    uuid: string;
    category: "period";
    publicationDateTime: Date | null;
    type: string | null;
    number: number | null;
    identification: Identification;
    description: string | null;
};
/**
 * Represents a property value with type information
 */
type PropertyValue = {
    uuid: string;
    category: "propertyValue";
    n: number;
    publicationDateTime: Date | null;
    context: Context | null;
    availability: License | null;
    identification: Identification;
    date: Date | null;
    creators: Array<Person>;
    description: string;
    notes: Array<Note>;
    links: Array<Link>;
};
/**
 * Represents a property value with type information
 */
type PropertyValueContent = {
    content: string;
    type: "string" | "number" | "integer" | "boolean" | "date" | "dateTime" | "time" | "IDREF";
    category: string | null;
    uuid: string | null;
    publicationDateTime: Date | null;
};
/**
 * Represents a property with label, values and nested properties
 */
type Property = {
    label: string;
    values: Array<PropertyValueContent>;
    comment: string | null;
    properties: Array<Property>;
};
/**
 * Represents a tree structure containing resources, spatial units and concepts
 */
type Tree = {
    uuid: string;
    category: "tree";
    publicationDateTime: Date | null;
    type: string;
    number: number;
    date: Date | null;
    license: License | null;
    identification: Identification;
    creators: Array<Person>;
    items: {
        resources: Array<Resource>;
        spatialUnits: Array<SpatialUnit>;
        concepts: Array<Concept>;
        periods: Array<Period>;
        bibliographies: Array<Bibliography>;
        persons: Array<Person>;
        propertyValues: Array<PropertyValue>;
    };
    properties: Array<Property>;
};
/**
 * Represents a gallery with its identification, project identification, resources and max length
 */
type Gallery = {
    identification: Identification;
    projectIdentification: Identification;
    resources: Array<Resource>;
    maxLength: number;
};
/**
 * Represents a website with its properties and elements
 */
type Website = {
    uuid: string;
    publicationDateTime: Date | null;
    identification: Identification;
    project: {
        name: string;
        website: string | null;
    };
    creators: Array<Person>;
    license: License | null;
    pages: Array<Webpage>;
    sidebar: {
        elements: Array<WebElement>;
        title: WebElement["title"];
        layout: "start" | "end";
        mobileLayout: "default" | "inline";
        cssStyles: Array<Style>;
        cssStylesMobile: Array<Style>;
    } | null;
    properties: WebsiteProperties;
};
/**
 * Properties for configuring website display and styling
 */
type WebsiteProperties = {
    type: "traditional" | "digital-collection" | "plum" | "cedar" | "elm" | "maple" | "oak" | "palm";
    privacy: "public" | "password" | "private";
    status: "development" | "preview" | "production";
    isHeaderDisplayed: boolean;
    headerVariant: "default" | "floating" | "inline";
    headerAlignment: "start" | "center" | "end";
    isHeaderProjectDisplayed: boolean;
    isFooterDisplayed: boolean;
    isSidebarDisplayed: boolean;
    supportsThemeToggle: boolean;
    searchCollectionUuid: string | null;
    logoUrl: string | null;
};
type Webpage = {
    title: string;
    slug: string;
    properties: WebpageProperties;
    items: Array<WebElement | WebBlock>;
    webpages: Array<Webpage>;
};
/**
 * Properties for configuring webpage display and styling
 */
type WebpageProperties = {
    displayedInHeader: boolean;
    width: "full" | "large" | "narrow" | "default";
    variant: "default" | "no-background";
    backgroundImageUrl: string | null;
    isSidebarDisplayed: boolean;
    cssStyles: Array<Style>;
    cssStylesMobile: Array<Style>;
};
/**
 * Base properties for web elements
 */
type WebElement = {
    uuid: string;
    type: "element";
    title: {
        label: string;
        variant: "default" | "simple";
        properties: {
            isNameDisplayed: boolean;
            isDescriptionDisplayed: boolean;
            isDateDisplayed: boolean;
            isCreatorsDisplayed: boolean;
        };
    };
    cssStyles: Array<Style>;
    cssStylesMobile: Array<Style>;
} & WebElementComponent;
/**
 * Union type of all possible web element components
 */
type WebElementComponent = {
    component: "annotated-document";
    document: Document;
} | {
    component: "annotated-image";
    imageUuid: string;
    isSearchable: boolean;
} | {
    component: "bibliography";
    bibliographies: Array<Bibliography>;
    layout: "long" | "short";
} | {
    component: "blog";
    blogId: string;
} | {
    component: "button";
    variant: "default" | "transparent";
    href: string;
    isExternal: boolean;
    label: string;
    icon: string | null;
} | {
    component: "collection";
    collectionId: string;
    variant: "full" | "highlights";
    itemVariant: "default" | "card";
    isSearchable: boolean;
    showCount: boolean;
    layout: "image-top" | "image-bottom" | "image-start" | "image-end";
} | {
    component: "empty-space";
    height: string | null;
    width: string | null;
} | {
    component: "filter-categories";
    filterId: string;
} | {
    component: "iframe";
    href: string;
    height: string | null;
    width: string | null;
} | {
    component: "iiif-viewer";
    IIIFId: string;
} | {
    component: "image";
    images: Array<WebImage>;
    variant: "default" | "carousel";
    width: number | null;
    height: number | null;
    isFullWidth: boolean;
    isFullHeight: boolean;
    imageQuality: "high" | "low";
    captionSource: "name" | "abbreviation" | "description";
    captionLayout: "top" | "bottom" | "inset" | "suppress";
    altTextSource: "name" | "abbreviation" | "description";
    isTransparentBackground: boolean;
    isCover: boolean;
    carouselOptions: {
        secondsPerImage: number;
    } | null;
} | {
    component: "image-gallery";
    galleryId: string;
    isSearchable: boolean;
} | {
    component: "n-columns";
    columns: Array<WebElement>;
} | {
    component: "n-rows";
    rows: Array<WebElement>;
} | {
    component: "network-graph";
} | {
    component: "search-bar";
    variant: "default" | "full";
} | {
    component: "table";
    tableId: string;
} | {
    component: "text";
    variant: "title" | "block" | "banner";
    heading: "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | null;
    content: string;
} | {
    component: "timeline";
    timelineId: string;
} | {
    component: "video";
    isChaptersDislayed: boolean;
};
/**
 * Represents an image used in web elements
 */
type WebImage = {
    url: string;
    label: string | null;
    width: number;
    height: number;
};
/**
 * Represents a CSS style with label and value
 */
type Style = {
    label: string;
    value: string;
};
/**
 * Represents a block of vertical or horizontal content alignment
 */
type WebBlock = {
    uuid: string;
    type: "block";
    layout: "vertical" | "horizontal" | "grid";
    items: Array<WebElement | WebBlock>;
    properties: {
        /**
         * valid `gridTemplateColumns` or `gridTemplateRows` CSS property value
         */
        spacing: string | undefined;
        /**
         * `gap` CSS property value
         */
        gap: string | undefined;
        /**
         * `align-items` CSS property value
         */
        alignItems: "stretch" | "start" | "center" | "end" | "space-between";
        /**
         * `justify-content` CSS property value
         */
        justifyContent: "stretch" | "start" | "center" | "end" | "space-between";
    };
    propertiesMobile: Record<string, string> | null;
    cssStyles: Array<Style>;
    cssStylesMobile: Array<Style>;
};

/**
 * Fetches and parses a bibliography 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
 *
 * @example
 * ```ts
 * const result = await fetchBibliography("123e4567-e89b-12d3-a456-426614174000");
 * if (result === null) {
 *   console.error("Failed to fetch bibliography");
 *   return;
 * }
 * const { metadata, item } = result;
 * console.log(`Fetched bibliography: ${item.identification.label}`);
 * ```
 *
 * @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
 * ```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}`);
 * ```
 *
 * @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
 *
 * @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)
 */
declare function fetchGallery(uuid: string, filter: string, page: number, perPage: number): Promise<Gallery | null>;

/**
 * Raw string value that can be a string, number, or boolean
 */
type FakeString = string | number | boolean;

/**
 * Raw content item with rendering and whitespace options
 */
type OchreStringItemContent = {
  rend?: string; // "bold" | "italic" | "underline" (space separated)
  whitespace?: string; // "newline" | "trailing" | "leading" (space separated)
  content: FakeString;
};

/**
 * Raw string item with language metadata
 */
type OchreStringItem = {
  string:
    | FakeString
    | OchreStringItemContent
    | Array<FakeString | OchreStringItemContent>;
  lang?: Language["iso6393"]; // 3 character code (zxx = "a.k.a.")
  languages?: string; // 3 character codes, semicolon separated
};

/**
 * Container for raw string content
 */
type OchreStringContent = {
  content: FakeString | OchreStringItem | Array<OchreStringItem>;
};

/**
 * Rich text content item with formatting and language metadata
 */
type OchreStringRichTextItemContent = {
  content: FakeString;
  title?: FakeString;
  lang?: Language["iso6393"]; // 3 character code (zxx = "a.k.a.")
  whitespace?: string; // "newline" | "trailing" | "leading" (space separated)
  rend?: string; // "bold" | "italic" | "underline"  (space separated)
};

/**
 * Annotated rich text item with links
 */
type OchreStringRichTextItemAnnotation = {
  annotation: string; // UUID
  string: FakeString | OchreStringRichTextItemContent;
  links: OchreLink | Array<OchreLink>;
};

/**
 * Union type for different rich text item formats
 */
type OchreStringRichTextItem =
  | FakeString
  | OchreStringRichTextItemContent
  | {
      string:
        | OchreStringRichTextItemAnnotation
        | Array<OchreStringRichTextItemAnnotation>;
      whitespace?: string; // "newline" | "trailing" | "leading" (space separated)
    }
  | {
      whitespace: string; // "newline" | "trailing" | "leading" (space separated)
    }
  | OchreStringRichTextItemAnnotation;

/**
 * Container for rich text content with language metadata
 */
type OchreStringRichText = {
  string: FakeString | OchreStringRichTextItem | Array<OchreStringRichTextItem>;
  title?: FakeString;
  lang?: Language["iso6393"]; // 3 character code (zxx = "a.k.a.")
};

/**
 * Raw data structure corresponding to the parsed Data type
 */
type OchreData = {
  ochre: {
    uuid: string;
    uuidBelongsTo: string;
    belongsTo: FakeString;
    publicationDateTime: string; // YYYY-MM-DDThh:mm:ssZ
    metadata: OchreMetadata;
    languages?: string; // 3 character codes, semicolon separated
  } & (
    | { tree: OchreTree }
    | { set: OchreSet }
    | { resource: OchreResource }
    | { spatialUnit: OchreSpatialUnit }
    | { concept: OchreConcept }
    | { period: OchrePeriod }
    | { bibliography: OchreBibliography }
    | { person: OchrePerson }
    | { propertyValue: OchrePropertyValue }
  );
};

/**
 * Raw metadata structure corresponding to the parsed Metadata type
 */
type OchreMetadata = {
  identifier: OchreStringContent;
  item?: {
    label?: OchreStringContent; // Faulty, only exists in old items that have not been republished
    abbreviation?: OchreStringContent; // Faulty, only exists in old items that have not been republished
    identification: OchreIdentification;
    category: string;
    type: string;
    maxLength?: number;
  };
  publisher: OchreStringContent;
  dataset: OchreStringContent;
  project?: { identification: OchreIdentification };
  language?: OchreLanguage | Array<OchreLanguage>;
  description: OchreStringContent;
};

/**
 * Raw tree structure corresponding to the parsed Tree type
 */
type OchreTree = {
  uuid: string;
  publicationDateTime: string; // YYYY-MM-DDThh:mm:ssZ
  type: string;
  n: number;
  availability: OchreLicense;
  identification: OchreIdentification;
  date?: string; // YYYY-MM-DD
  creators?: { creator: OchrePerson | Array<OchrePerson> };
  items:
    | string
    | {
        resource: OchreResource | Array<OchreResource>;
      }
    | { spatialUnit: OchreSpatialUnit | Array<OchreSpatialUnit> }
    | { concept: OchreConcept | Array<OchreConcept> }
    | { period: OchrePeriod | Array<OchrePeriod> }
    | { bibliography: OchreBibliography | Array<OchreBibliography> }
    | { person: OchrePerson | Array<OchrePerson> }
    | { propertyValue: OchrePropertyValue | Array<OchrePropertyValue> };
  properties?: { property: OchreProperty | Array<OchreProperty> };
};

/**
 * Raw set structure corresponding to the parsed Set type
 */
type OchreSet = {
  uuid: string;
  publicationDateTime: string; // YYYY-MM-DDThh:mm:ssZ
  type: string;
  n: number;
  availability: OchreLicense;
  identification: OchreIdentification;
  date?: string; // YYYY-MM-DD
  suppressBlanks?: boolean;
  description?: OchreStringContent | FakeString;
  creators?: { creator: OchrePerson | Array<OchrePerson> };
  items:
    | string
    | { resource: OchreResource | Array<OchreResource> }
    | { spatialUnit: OchreSpatialUnit | Array<OchreSpatialUnit> }
    | { concept: OchreConcept | Array<OchreConcept> }
    | { period: OchrePeriod | Array<OchrePeriod> }
    | { bibliography: OchreBibliography | Array<OchreBibliography> }
    | { person: OchrePerson | Array<OchrePerson> }
    | { propertyValue: OchrePropertyValue | Array<OchrePropertyValue> };
};

/**
 * Raw resource structure corresponding to the parsed Resource type
 */
type OchreResource = {
  uuid: string;
  publicationDateTime: string; // YYYY-MM-DDThh:mm:ssZ
  type: string;
  n: number;
  slug?: string;
  format?: string;
  context?: OchreContext;
  availability?: OchreLicense;
  copyright?: FakeString;
  identification: OchreIdentification;
  href?: string;
  description?: OchreStringContent | FakeString;
  date?: string; // YYYY-MM-DD
  image?: OchreImage;
  creators?: { creator: OchrePerson | Array<OchrePerson> };
  notes?: { note: OchreNote | Array<OchreNote> };
  document?: {
    content: OchreStringRichText | Array<OchreStringRichText>;
  };
  imagemap?: OchreImageMap;
  periods?: { period: OchrePeriod | Array<OchrePeriod> };
  links?: OchreLink | Array<OchreLink>;
  reverseLinks?: OchreLink | Array<OchreLink>;
  properties?: { property: OchreProperty | Array<OchreProperty> };
  citedBibliography?: {
    reference: OchreBibliography | Array<OchreBibliography>;
  };
  resource?: OchreNestedResource | Array<OchreNestedResource>;
};

/**
 * 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
 */
type OchreSpatialUnit = {
  uuid: string;
  publicationDateTime?: string; // YYYY-MM-DDThh:mm:ssZ
  type: string;
  n: number;
  availability?: OchreLicense;
  context?: OchreContext;
  identification: OchreIdentification;
  image?: OchreImage;
  description?: OchreStringContent | FakeString;
  coordinates?: OchreCoordinates;
  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> };
};

/**
 * Raw concept structure corresponding to the parsed Concept type
 */
type OchreConcept = {
  uuid: string;
  publicationDateTime: string; // YYYY-MM-DDThh:mm:ssZ
  n: number;
  availability?: OchreLicense;
  context?: OchreContext;
  identification: OchreIdentification;
  interpretations: {
    interpretation: OchreInterpretation | Array<OchreInterpretation>;
  };
};

/**
 * 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
 */
type OchrePropertyValueContent = OchreStringContent & {
  uuid?: string;
  publicationDateTime?: string; // YYYY-MM-DDThh:mm:ssZ
  type: string;
  category?: string;
  slug?: FakeString;
};

/**
 * Raw property structure corresponding to the parsed Property type
 */
type OchreProperty = {
  label: OchreStringContent & { uuid: string };
  value?:
    | OchrePropertyValueContent
    | Array<OchrePropertyValueContent>
    | FakeString;
  comment?: FakeString;
  property?: OchreProperty | Array<OchreProperty>;
};

/**
 * Raw identification structure corresponding to the parsed Identification type
 */
type OchreIdentification = {
  label: OchreStringContent | FakeString;
  abbreviation?: OchreStringContent | FakeString;
  MIMEType?: string;
  widthPreview?: number;
  heightPreview?: number;
  height?: number;
  width?: number;
  website?: string;
};

/**
 * Raw license structure corresponding to the parsed License type
 */
type OchreLicense = {
  license: { content: string; target: string } | string;
};

/**
 * Raw language structure for specifying content languages
 */
type OchreLanguage = {
  default?: boolean;
  content: string; // 3 character code
};

/**
 * Raw link item structure for various linked content types
 */
type OchreLinkItem = {
  uuid: string;
  publicationDateTime?: string; // YYYY-MM-DDThh:mm:ssZ
  type?: string;
  identification?: OchreIdentification;
  rend?: "inline";
  content?: FakeString;
  heightPreview?: number;
  widthPreview?: number;
  height?: number;
  width?: number;
  href?: string;
  isPrimary?: boolean;
};

/**
 * Raw link structure corresponding to the parsed Link type
 */
type OchreLink =
  | { resource: OchreLinkItem | Array<OchreLinkItem> }
  | { spatialUnit: OchreLinkItem | Array<OchreLinkItem> }
  | { concept: OchreLinkItem | Array<OchreLinkItem> }
  | { set: OchreLinkItem | Array<OchreLinkItem> }
  | { tree: OchreLinkItem | Array<OchreLinkItem> }
  | { person: OchreLinkItem | Array<OchreLinkItem> }
  | { epigraphicUnit: OchreLinkItem | Array<OchreLinkItem> }
  | { bibliography: OchreBibliography | Array<OchreBibliography> }
  | { propertyValue: OchreLinkItem | Array<OchreLinkItem> };

/**
 * Raw image structure corresponding to the parsed Image type
 */
type OchreImage = {
  publicationDateTime?: string; // YYYY-MM-DDThh:mm:ssZ
  identification?: OchreIdentification;
  href?: string;
  htmlImgSrcPrefix?: string;
  content?: FakeString;
  widthPreview?: number;
  heightPreview?: number;
  width?: number;
  height?: number;
};

/**
 * Raw bibliography structure corresponding to the parsed Bibliography type
 */
type OchreBibliography = {
  uuid: string;
  publicationDateTime?: string; // YYYY-MM-DDThh:mm:ssZ
  type?: string;
  n?: number;
  identification?: OchreIdentification;
  project?: { identification: OchreIdentification };
  context?: OchreContext;
  sourceDocument?: {
    uuid: string;
    content: FakeString;
  };
  publicationInfo?: {
    publishers?: { publishers: { person: OchrePerson | Array<OchrePerson> } };
    startDate?: {
      month: number;
      year: number;
      day: number;
    };
  };
  entryInfo?: {
    startIssue: FakeString;
    startVolume: FakeString;
  };
  citationFormat?: string;
  citationFormatSpan?:
    | {
        span: {
          content: FakeString;
        };
      }
    | {
        "default:span": {
          content: FakeString;
        };
      };
  referenceFormatDiv?:
    | {
        div: {
          div: {
            class: string;
            content: FakeString;
          };
          style: string;
          class: string;
        };
      }
    | {
        "default:div": {
          "default:div": {
            class: string;
            content: FakeString;
          };
          style: string;
          class: string;
        };
      };
  source?: {
    resource: Pick<
      OchreResource,
      "uuid" | "type" | "publicationDateTime" | "identification"
    >;
  };
  periods?: { period: OchrePeriod | Array<OchrePeriod> };
  authors?: { person: OchrePerson | Array<OchrePerson> };
  properties?: { property: OchreProperty | Array<OchreProperty> };
};

/**
 * Raw note structure corresponding to the parsed Note type
 */
type OchreNote =
  | string
  | {
      noteNo: number;
      content: OchreStringRichText | Array<OchreStringRichText>;
    };

/**
 * Raw period structure corresponding to the parsed Period type
 */
type OchrePeriod = {
  uuid: string;
  publicationDateTime?: string; // YYYY-MM-DDThh:mm:ssZ
  type?: string;
  n?: number;
  identification: OchreIdentification;
  description?: OchreStringContent;
};

/**
 * Raw image map area structure corresponding to the parsed ImageMapArea type
 */
type OchreImageMapArea = {
  uuid: string;
  publicationDateTime?: string; // YYYY-MM-DDThh:mm:ssZ
  type: string;
  title: FakeString;
  shape: "rect" | "poly";
  coords: string; // comma separated list of numbers
};

/**
 * Raw image map structure corresponding to the parsed ImageMap type
 */
type OchreImageMap = {
  area: OchreImageMapArea | Array<OchreImageMapArea>;
  width: number;
  height: number;
};

/**
 * Raw context structure corresponding to the parsed Context type
 */
type OchreContext = {
  context: OchreContextValue | Array<OchreContextValue>;
  displayPath: string;
};

/**
 * Raw context value structure containing tree, project and spatial unit information
 */
type OchreContextValue = {
  tree: OchreContextItem;
  project: OchreContextItem;
  spatialUnit?: OchreContextItem | Array<OchreContextItem>;
  displayPath: string;
};

/**
 * Raw context item structure corresponding to the parsed ContextItem type
 */
type OchreContextItem = {
  uuid: string;
  publicationDateTime?: string; // YYYY-MM-DDThh:mm:ssZ
  n: number; // negative number
  content: FakeString;
};

/**
 * Raw person structure corresponding to the parsed Person type
 */
type OchrePerson = {
  uuid: string;
  publicationDateTime?: string; // YYYY-MM-DDThh:mm:ssZ
  type?: string;
  date?: string; // YYYY-MM-DD
  identification?: OchreIdentification;
  content?: FakeString | null;
};

/**
 * Raw observation structure corresponding to the parsed Observation type
 */
type OchreObservation = {
  observationNo: number;
  date?: string; // YYYY-MM-DD
  observers?: FakeString;
  notes?: { note: OchreNote | Array<OchreNote> };
  links?: OchreLink | Array<OchreLink>;
  properties?: { property: OchreProperty | Array<OchreProperty> };
};

/**
 * Raw coordinates structure corresponding to the parsed Coordinates type
 */
type OchreCoordinates = {
  latitude: number;
  longitude: number;
  coordinatesArray?: string;
  coord?: {
    coordLatitude: number;
    coordLongitude: number;
    coordType: string;
    coordLabel: FakeString;
    arrayString: string;
    uuid: string;
  };
};

/**
 * Raw event structure corresponding to the parsed Event type
 */
type OchreEvent = {
  dateTime?: string; // YYYY-MM-DD
  agent?: {
    uuid: string;
    content: FakeString;
  };
  label: OchreStringContent;
};

/**
 * Raw interpretation structure corresponding to the parsed Interpretation type
 */
type OchreInterpretation = {
  date: string; // YYYY-MM-DD
  interpretationNo: number;
  properties?: { property: OchreProperty | Array<OchreProperty> };
};

/**
 * Raw property value structure corresponding to the parsed PropertyValue type
 */
type OchrePropertyValue = {
  uuid: string;
  publicationDateTime?: string; // YYYY-MM-DDThh:mm:ssZ
  n: number;
  context?: OchreContext;
  availability?: OchreLicense;
  identification: OchreIdentification;
  date?: string; // YYYY-MM-DD
  creators?: { creator: OchrePerson | Array<OchrePerson> };
  description?: OchreStringContent | FakeString;
  notes?: { note: OchreNote | Array<OchreNote> };
  links?: OchreLink | Array<OchreLink>;
};

/**
 * Fetches raw OCHRE data by UUID from the OCHRE API
 *
 * @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
 */
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
 */
type PropertyOptions = {
    /** Whether to recursively search through nested properties */
    searchNestedProperties: boolean;
};
/**
 * Finds a property by its label in an array of properties
 *
 * @param properties - Array of properties to search through
 * @param label - The label to search for
 * @param options - Search options, including whether to search nested properties
 * @returns The matching Property object, or null if not found
 *
 * @example
 * ```ts
 * const property = getPropertyByLabel(properties, "author", { searchNestedProperties: true });
 * if (property) {
 *   console.log(property.values);
 * }
 * ```
 */
declare function getPropertyByLabel(properties: Array<Property>, label: string, options?: PropertyOptions): Property | null;
/**
 * Retrieves all values for a property with the given label
 *
 * @param properties - Array of properties to search through
 * @param label - The label to search for
 * @param options - Search options, including whether to search 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> | null;
/**
 * Gets the first value of a property with the given label
 *
 * @param properties - Array of properties to search through
 * @param label - The label to search for
 * @param options - Search options, including whether to search 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 | null;
/**
 * Gets all unique property labels from an array of properties
 *
 * @param properties - Array of properties to get labels from
 * @param options - Search options, including whether to include nested property labels
 * @returns Array of unique property labels
 *
 * @example
 * ```ts
 * const labels = getAllPropertyLabels(properties, { searchNestedProperties: true });
 * console.log(`Available properties: ${labels.join(", ")}`);
 * ```
 */
declare function getAllPropertyLabels(properties: Array<Property>, options?: PropertyOptions): Array<string>;
/**
 * Filters a property based on a label and value criteria
 *
 * @param property - The property to filter
 * @param filter - Filter criteria containing label and value to match
 * @param filter.label - The label to filter by
 * @param filter.value - The value to filter by
 * @param options - Search options, including whether to search 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;
    value: string;
}, options?: PropertyOptions): boolean;

/**
 * Parses raw identification data into the standardized Identification type
 *
 * @param identification - Raw identification data from OCHRE format
 * @returns Parsed Identification object with label and abbreviation
 */
declare function parseIdentification(identification: OchreIdentification): Identification;
/**
 * Parses raw language data into an array of language codes
 *
 * @param language - Raw language data, either single or array
 * @returns Array of language codes as strings
 */
declare function parseLanguages(language: OchreLanguage | Array<OchreLanguage> | undefined): Array<string>;
/**
 * Parses raw metadata into the standardized Metadata type
 *
 * @param metadata - Raw metadata from OCHRE format
 * @returns Parsed Metadata object
 */
declare function parseMetadata(metadata: OchreMetadata): Metadata;
/**
 * Parses raw context data into the standardized Context type
 *
 * @param context - Raw context data from OCHRE format
 * @returns Parsed Context object
 */
declare function parseContext(context: OchreContext): Context;
/**
 * Parses raw license data into the standardized License type
 *
 * @param license - Raw license data from OCHRE format
 * @returns Parsed License object or null if invalid
 */
declare function parseLicense(license: OchreLicense): License | null;
/**
 * Parses raw person data into the standardized Person type
 *
 * @param person - Raw person data from OCHRE format
 * @returns Parsed Person object
 */
declare function parsePerson(person: OchrePerson): Person;
/**
 * Parses raw person data into the standardized Person type
 *
 * @param persons - Array of raw person data from OCHRE format
 * @returns Array of parsed Person objects
 */
declare function parsePersons(persons: Array<OchrePerson>): Array<Person>;
/**
 * Parses an array of raw links into standardized Link objects
 *
 * @param linkRaw - Raw OCHRE link
 * @returns Parsed Link object
 */
declare function parseLink(linkRaw: OchreLink): Array<Link>;
/**
 * Parses an array of raw links into standardized Link objects
 *
 * @param links - Array of raw OCHRE links
 * @returns Array of parsed Link objects
 */
declare function parseLinks(links: Array<OchreLink>): Array<Link>;
/**
 * Parses raw document content into a standardized Document structure
 *
 * @param document - Raw document content in OCHRE format
 * @param language - Language code to use for content selection (defaults to "eng")
 * @returns Parsed Document object with content and footnotes
 */
declare function parseDocument(document: OchreStringRichText | Array<OchreStringRichText>, language?: string): Document;
/**
 * Parses raw image data into a standardized Image structure
 *
 * @param image - Raw image data in OCHRE format
 * @returns Parsed Image object or null if invalid
 */
declare function parseImage(image: OchreImage): Image | null;
/**
 * Parses raw notes into standardized Note objects
 *
 * @param notes - Array of raw notes in OCHRE format
 * @param language - Language code for content selection (defaults to "eng")
 * @returns Array of parsed Note objects
 */
declare function parseNotes(notes: Array<OchreNote>, language?: string): Array<Note>;
/**
 * Parses raw coordinates data into a standardized Coordinates structure
 *
 * @param coordinates - Raw coordinates data in OCHRE format
 * @returns Parsed Coordinates object
 */
declare function parseCoordinates(coordinates: OchreCoordinates): Coordinates;
/**
 * Parses a raw observation into a standardized Observation structure
 *
 * @param observation - Raw observation data in OCHRE format
 * @returns Parsed Observation object
 */
declare function parseObservation(observation: OchreObservation): Observation;
/**
 * Parses an array of raw observations into standardized Observation objects
 *
 * @param observations - Array of raw observations in OCHRE format
 * @returns Array of parsed Observation objects
 */
declare function parseObservations(observations: Array<OchreObservation>): Array<Observation>;
/**
 * Parses an array of raw events into standardized Event objects
 *
 * @param events - Array of raw events in OCHRE format
 * @returns Array of parsed Event objects
 */
declare function parseEvents(events: Array<OchreEvent>): Array<Event>;
/**
 * Parses raw properties into standardized Property objects
 *
 * @param properties - Array of raw properties in OCHRE format
 * @param language - Language code for content selection (defaults to "eng")
 * @returns Array of parsed Property objects
 */
declare function parseProperties(properties: Array<OchreProperty>, language?: string): Array<Property>;
/**
 * Parses raw interpretations into standardized Interpretation objects
 *
 * @param interpretations - Array of raw interpretations in OCHRE format
 * @returns Array of parsed Interpretation objects
 */
declare function parseInterpretations(interpretations: Array<OchreInterpretation>): Array<Interpretation>;
/**
 * Parses raw image map data into a standardized ImageMap structure
 *
 * @param imageMap - Raw image map data in OCHRE format
 * @returns Parsed ImageMap object
 */
declare function parseImageMap(imageMap: OchreImageMap): ImageMap;
/**
 * Parses raw period