ochre-sdk 1.0.20 → 1.0.22

package/README.md

@@ -46,10 +46,12 @@ present and `error` is `null`; on failure, the parsed value is `null` and
 ## Core API
 
 - `fetchItem(uuid, options)` fetches and parses a single OCHRE item. Passing
-  `category` narrows the returned TypeScript type, and `containedItemCategory`
-  controls how nested Tree or Set contents are parsed. For large Trees or Sets,
-  pass `shouldOmitEmbeddedItems: true` to fetch the top-level item without its
-  embedded `<items>` payload.
+  `category` as a single category narrows the returned TypeScript type to that
+  category; passing an array narrows it to any category in that list and lets the
+  parser resolve the actual category from the payload. `containedItemCategory`
+  controls how nested Tree or Set contents are parsed. For large recursive item
+  categories, pass `shouldOmitEmbeddedItems: true` to fetch the top-level item
+  without its embedded item hierarchy.
 - `fetchItemLinks(uuid, options)` fetches items linked from a source item and
   parses them as embedded OCHRE items.
 - `fetchGallery(params, options)` fetches paginated resource galleries with an

package/dist/fetchers/item.d.mts

@@ -1,4 +1,4 @@
-import { ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Item, ItemCategory, ItemContainerCategory, ItemWithoutEmbeddedItems } from "../types/index.mjs";
+import { ContainedItemCategoryFromOption, ContainedItemCategoryOption, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemCategoryWithEmbeddedItems, ItemContainerCategory, ItemWithoutEmbeddedItems } from "../types/index.mjs";
 import { FetchBaseOptions, FetchLanguages } from "../parsers/helpers.mjs";
 
 //#region src/fetchers/item.d.ts
@@ -31,9 +31,11 @@ declare function withLanguages<const TLanguages extends ReadonlyArray<string>>(l
  *
  * @param uuid - The UUID of the OCHRE item to fetch
  * @param options - Required options object
- * @param options.category - The category of the OCHRE item to fetch
+ * @param options.category - The category of the OCHRE item to fetch. Pass a
+ * single category when it is known, or an array when the item may be any
+ * category in that list.
  * @param options.containedItemCategory - The category of items inside the OCHRE item to fetch. Only valid for Trees and Sets. Tree accepts one category; Set accepts one category or an array.
- * @param options.shouldOmitEmbeddedItems - Whether to omit the embedded `<items>` node when fetching a Tree or Set.
+ * @param options.shouldOmitEmbeddedItems - Whether to omit the embedded item hierarchy when fetching a recursive item category.
  * @param options.languages - Language codes to parse. Inline arrays preserve literal types automatically.
  * @param options.fetch - Custom fetch function to use instead of the default fetch
  * @returns An object containing the parsed item
@@ -47,21 +49,16 @@ declare function fetchItem<const TContainedItemCategory extends ContainedItemCat
   category?: undefined;
   containedItemCategory?: TContainedItemCategory;
   shouldOmitEmbeddedItems?: true;
-}): FetchItemResult<ItemWithoutEmbeddedItems<ItemContainerCategory, ContainedItemCategoryFromOption<ItemContainerCategory, TContainedItemCategory>, FetchLanguages<TLanguages>>>;
-declare function fetchItem<const TCategory extends ItemContainerCategory, const TContainedItemCategory extends ContainedItemCategoryOption<TCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchBaseOptions<TLanguages> & {
+}): FetchItemResult<ItemWithoutEmbeddedItems<ItemCategoryWithEmbeddedItems, ContainedItemCategoryFromOption<ItemContainerCategory, TContainedItemCategory>, FetchLanguages<TLanguages>>>;
+declare function fetchItem<const TCategory extends ItemCategoryOption, const TContainedItemCategory extends ContainedItemCategoryOption<ItemCategoryFromOption<TCategory>> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchBaseOptions<TLanguages> & {
   category: TCategory;
   containedItemCategory?: TContainedItemCategory;
   shouldOmitEmbeddedItems?: false;
-}): FetchItemResult<Item<TCategory, ContainedItemCategoryFromOption<TCategory, TContainedItemCategory>, FetchLanguages<TLanguages>>>;
-declare function fetchItem<const TCategory extends ItemContainerCategory, const TContainedItemCategory extends ContainedItemCategoryOption<TCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchBaseOptions<TLanguages> & {
+}): FetchItemResult<Item<ItemCategoryFromOption<TCategory>, ContainedItemCategoryFromOption<ItemCategoryFromOption<TCategory>, TContainedItemCategory>, FetchLanguages<TLanguages>>>;
+declare function fetchItem<const TCategory extends ItemCategoryOption, const TContainedItemCategory extends ContainedItemCategoryOption<Extract<ItemCategoryFromOption<TCategory>, ItemCategoryWithEmbeddedItems>> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchBaseOptions<TLanguages> & {
   category: TCategory;
   containedItemCategory?: TContainedItemCategory;
-  shouldOmitEmbeddedItems: true;
-}): FetchItemResult<ItemWithoutEmbeddedItems<TCategory, ContainedItemCategoryFromOption<TCategory, TContainedItemCategory>, FetchLanguages<TLanguages>>>;
-declare function fetchItem<const TCategory extends ItemCategory, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchBaseOptions<TLanguages> & {
-  category: TCategory;
-  containedItemCategory?: never;
-  shouldOmitEmbeddedItems?: false;
-}): FetchItemResult<Item<TCategory, ContainedItemCategory<TCategory>, FetchLanguages<TLanguages>>>;
+  shouldOmitEmbeddedItems: ItemCategoryFromOption<TCategory> extends ItemCategoryWithEmbeddedItems ? true : never;
+}): FetchItemResult<ItemWithoutEmbeddedItems<Extract<ItemCategoryFromOption<TCategory>, ItemCategoryWithEmbeddedItems>, ContainedItemCategoryFromOption<Extract<ItemCategoryFromOption<TCategory>, ItemCategoryWithEmbeddedItems>, TContainedItemCategory>, FetchLanguages<TLanguages>>>;
 //#endregion
 export { defineLanguages, fetchItem, withLanguages };

package/dist/fetchers/item.mjs

@@ -11,63 +11,62 @@ import { XMLParser } from "fast-xml-parser";
 function isItemContainerCategory(category) {
 	return category === "tree" || category === "set";
 }
-function isItemContainer(item) {
-	return isItemContainerCategory(item.category);
+function isItemCategoryWithEmbeddedItems(category) {
+	return category === "tree" || category === "bibliography" || category === "concept" || category === "spatialUnit" || category === "period" || category === "resource" || category === "set";
+}
+function isItemWithEmbeddedItems(item) {
+	return isItemCategoryWithEmbeddedItems(item.category);
 }
 function assertItemCategoryAllowed(category, containedItemCategory) {
-	if (category == null || containedItemCategory == null || isItemContainerCategory(category)) return;
-	throw new Error(`containedItemCategory can only be used when category is "tree" or "set"; received category "${category}"`);
+	if (category == null || containedItemCategory == null) return;
+	const categories = typeof category === "string" ? [category] : category;
+	for (const possibleCategory of categories) if (isItemContainerCategory(possibleCategory)) return;
+	throw new Error(`containedItemCategory can only be used when category is "tree" or "set"; received category "${categories.join(", ")}"`);
 }
 function assertShouldOmitEmbeddedItemsAllowed(category, shouldOmitEmbeddedItems) {
-	if (!shouldOmitEmbeddedItems || category == null || isItemContainerCategory(category)) return;
-	throw new Error(`shouldOmitEmbeddedItems can only be used when category is "tree" or "set"; received category "${category}"`);
-}
-function normalizeFetchedCategory(category) {
-	switch (category) {
-		case "tree":
-		case "bibliography":
-		case "concept":
-		case "spatialUnit":
-		case "period":
-		case "person":
-		case "propertyVariable":
-		case "propertyValue":
-		case "resource":
-		case "text":
-		case "set": return category;
-		case "variable": return "propertyVariable";
-		case "value": return "propertyValue";
-		default: return null;
-	}
-}
-function inferFetchItemCategory(rawOchre) {
-	const metadataCategory = normalizeFetchedCategory(rawOchre.metadata.item?.category);
-	if (metadataCategory != null) return metadataCategory;
-	if ("tree" in rawOchre) return "tree";
-	if ("bibliography" in rawOchre) return "bibliography";
-	if ("concept" in rawOchre) return "concept";
-	if ("spatialUnit" in rawOchre) return "spatialUnit";
-	if ("period" in rawOchre) return "period";
-	if ("person" in rawOchre) return "person";
-	if ("propertyVariable" in rawOchre || "variable" in rawOchre) return "propertyVariable";
-	if ("propertyValue" in rawOchre || "value" in rawOchre) return "propertyValue";
-	if ("resource" in rawOchre) return "resource";
-	if ("text" in rawOchre) return "text";
-	if ("set" in rawOchre) return "set";
-	throw new Error("Could not infer OCHRE item category", { cause: rawOchre });
+	if (!shouldOmitEmbeddedItems || category == null) return;
+	const categories = typeof category === "string" ? [category] : category;
+	for (const possibleCategory of categories) if (!isItemCategoryWithEmbeddedItems(possibleCategory)) throw new Error(`shouldOmitEmbeddedItems can only be used when the item category contains embedded items; received category "${possibleCategory}"`);
 }
-function buildOmitEmbeddedItemsXQuery(uuid) {
+function buildOmitEmbeddedItemsXQuery(uuid, category) {
+	const collectionCategories = [];
+	const categories = category == null ? [
+		"tree",
+		"bibliography",
+		"concept",
+		"spatialUnit",
+		"period",
+		"resource",
+		"set"
+	] : typeof category === "string" ? [category] : category;
+	for (const possibleCategory of categories) if (!collectionCategories.includes(possibleCategory)) collectionCategories.push(possibleCategory);
+	const collectionQueries = [];
+	for (const collectionCategory of collectionCategories) collectionQueries.push(`cts:search(fn:collection("ochre/${collectionCategory}")/ochre, $uuid-query)`);
 	return `xquery version "1.0-ml";
 
-let $ochre := doc()/ochre[@uuid=${stringLiteral(uuid)}][1]
+let $uuid := ${stringLiteral(uuid)}
+let $uuid-query := cts:element-attribute-value-query(xs:QName("ochre"), xs:QName("uuid"), $uuid, "exact")
+let $ochre := (
+  ${collectionQueries.join(",\n  ")}
+)[1]
+let $item := (
+  $ochre/tree,
+  $ochre/bibliography,
+  $ochre/concept,
+  $ochre/spatialUnit,
+  $ochre/period,
+  $ochre/resource,
+  $ochre/set
+)[1]
+let $embedded-child-name := if (local-name($item) = ("tree", "set")) then "items" else local-name($item)
 return
-  if (empty($ochre)) then ()
+  if (empty($ochre) or empty($item)) then ()
   else element ochre {
     $ochre/@*,
     for $node in $ochre/node()
     return
-      if (local-name($node) = ("tree", "set"))
-      then element { node-name($node) } { $node/@*, $node/node()[not(self::items)] }
+      if ($node is $item)
+      then element { node-name($item) } { $item/@*, $item/node()[not(self::*[local-name() = $embedded-child-name])] }
       else $node
   }`;
 }
@@ -108,11 +107,19 @@ async function fetchItem(uuid, options) {
 		assertItemCategoryAllowed(options?.category, options?.containedItemCategory);
 		const shouldOmitEmbeddedItems = options?.shouldOmitEmbeddedItems === true;
 		assertShouldOmitEmbeddedItemsAllowed(options?.category, shouldOmitEmbeddedItems);
+		let omitEmbeddedItemsCategory;
+		if (options?.category != null) if (typeof options.category === "string") {
+			if (isItemCategoryWithEmbeddedItems(options.category)) omitEmbeddedItemsCategory = options.category;
+		} else {
+			const categories = [];
+			for (const possibleCategory of options.category) if (isItemCategoryWithEmbeddedItems(possibleCategory)) categories.push(possibleCategory);
+			omitEmbeddedItemsCategory = categories;
+		}
 		const languages = options?.languages == null ? [] : parseLanguages(options.languages);
 		const fetcher = options?.fetch ?? fetch;
 		const response = shouldOmitEmbeddedItems ? await fetcher("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
 			method: "POST",
-			body: buildOmitEmbeddedItemsXQuery(parsedUuid),
+			body: buildOmitEmbeddedItemsXQuery(parsedUuid, omitEmbeddedItemsCategory),
 			headers: { "Content-Type": "application/xquery" }
 		}) : await fetcher(`https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?uuid=${parsedUuid}&xsl=none&lang="*"`);
 		if (!response.ok) throw new Error("Failed to fetch OCHRE data", { cause: response.statusText });
@@ -121,17 +128,16 @@ async function fetchItem(uuid, options) {
 		const { success, issues, output } = v.safeParse(XMLData, data);
 		if (!success) throw createSchemaValidationError("Failed to parse OCHRE data", issues);
 		restoreXMLMetadata(output, data);
-		const category = options?.category ?? inferFetchItemCategory(output.result.ochre);
-		assertItemCategoryAllowed(category, options?.containedItemCategory);
-		assertShouldOmitEmbeddedItemsAllowed(category, shouldOmitEmbeddedItems);
 		const parsedItem = parseItem(output, {
-			category,
+			category: options?.category,
 			containedItemCategory: options?.containedItemCategory,
 			languages,
 			parseResourceView: (view, context) => parseWebpageView(view, { languages: context.metadata.languages }, context)
 		});
+		assertItemCategoryAllowed(parsedItem.category, options?.containedItemCategory);
+		assertShouldOmitEmbeddedItemsAllowed(parsedItem.category, shouldOmitEmbeddedItems);
 		return {
-			item: shouldOmitEmbeddedItems && isItemContainer(parsedItem) ? omitEmbeddedItems(parsedItem) : parsedItem,
+			item: shouldOmitEmbeddedItems && isItemWithEmbeddedItems(parsedItem) ? omitEmbeddedItems(parsedItem) : parsedItem,
 			error: null,
 			detailedError: null
 		};

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { MultilingualOptions, MultilingualString, MultilingualStringEntries, MultilingualStringEntry, MultilingualStringInput, MultilingualStringJSON, MultilingualStringObject, MultilingualStringText } from "./parsers/multilingual.mjs";
 import { AccordionWebBlock, ContextTree, ContextTreeFilterLevel, ContextTreeLevel, ContextTreeLevelItem, Scope, Style, StylesheetCategory, StylesheetItem, WebAccordionItem, WebBlock, WebBlockByLayout, WebBlockItem, WebBlockLayout, WebElement, WebElementComponent, WebElementComponentName, WebElementComponentOf, WebElementOf, WebImage, WebTitle, Webpage, Website, WebsiteMetadata, WebsitePropertyQuery, WebsitePropertyQueryNode, WebsiteSegment, WebsiteType } from "./types/website.mjs";
-import { AnyBibliography, AnyConcept, AnyItem, AnyPeriod, AnyPerson, AnyPropertyValue, AnyPropertyVariable, AnyResource, AnySet, AnySpatialUnit, AnyText, AnyTree, BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, Coordinates, CoordinatesSource, DictionaryUnitItemLink, EmbeddedBibliography, EmbeddedConcept, EmbeddedItem, EmbeddedPeriod, EmbeddedPerson, EmbeddedPropertyValue, EmbeddedPropertyVariable, EmbeddedResource, EmbeddedSet, EmbeddedSpatialUnit, EmbeddedText, EmbeddedTree, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, ItemProperty, ItemWithoutEmbeddedItems, LanguageCodes, License, Metadata, Note, Observation, Period, PeriodItemLink, Person, PersonItemLink, Property, PropertyLike, PropertyValue, PropertyValueContent, PropertyValueDataType, PropertyValueItemLink, PropertyValueQueryItem, PropertyVariable, PropertyVariableItemLink, Query, QueryGroup, QueryLeaf, QueryablePropertyValueDataType, RecursiveItemCategory, Resource, ResourceItemLink, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Text, TextItemLink, TopLevelItem, Tree, TreeItemCategory, TreeItemLink } from "./types/index.mjs";
+import { AnyBibliography, AnyConcept, AnyItem, AnyPeriod, AnyPerson, AnyPropertyValue, AnyPropertyVariable, AnyResource, AnySet, AnySpatialUnit, AnyText, AnyTree, BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, Coordinates, CoordinatesSource, DictionaryUnitItemLink, EmbeddedBibliography, EmbeddedConcept, EmbeddedItem, EmbeddedPeriod, EmbeddedPerson, EmbeddedPropertyValue, EmbeddedPropertyVariable, EmbeddedResource, EmbeddedSet, EmbeddedSpatialUnit, EmbeddedText, EmbeddedTree, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemCategoryWithEmbeddedItems, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, ItemProperty, ItemWithoutEmbeddedItems, LanguageCodes, License, Metadata, Note, Observation, Period, PeriodItemLink, Person, PersonItemLink, Property, PropertyLike, PropertyValue, PropertyValueContent, PropertyValueDataType, PropertyValueItemLink, PropertyValueQueryItem, PropertyVariable, PropertyVariableItemLink, Query, QueryGroup, QueryLeaf, QueryablePropertyValueDataType, RecursiveItemCategory, Resource, ResourceItemLink, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Text, TextItemLink, TopLevelItem, Tree, TreeItemCategory, TreeItemLink } from "./types/index.mjs";
 import { fetchGallery } from "./fetchers/gallery.mjs";
 import { fetchItemLinks } from "./fetchers/item-links.mjs";
 import { defineLanguages, fetchItem, withLanguages } from "./fetchers/item.mjs";
@@ -10,4 +10,4 @@ import { fetchWebsiteMetadata } from "./fetchers/website-metadata.mjs";
 import { fetchWebsite } from "./fetchers/website.mjs";
 import { PropertyOptions, filterProperties, getLeafPropertyValues, getPropertyByVariableLabel, getPropertyByVariableLabelAndValue, getPropertyByVariableLabelAndValueContent, getPropertyByVariableLabelAndValueContents, getPropertyByVariableLabelAndValues, getPropertyByVariableUuid, getPropertyValueByVariableLabel, getPropertyValueByVariableUuid, getPropertyValueContentByVariableLabel, getPropertyValueContentByVariableUuid, getPropertyValueContentsByVariableUuid, getPropertyValuesByVariableLabel, getPropertyValuesByVariableUuid, getUniqueProperties, getUniquePropertyVariableLabels } from "./getters.mjs";
 import { DEFAULT_PAGE_SIZE, flattenItemProperties } from "./helpers.mjs";
-export { type AccordionWebBlock, type AnyBibliography, type AnyConcept, type AnyItem, type AnyPeriod, type AnyPerson, type AnyPropertyValue, type AnyPropertyVariable, type AnyResource, type AnySet, type AnySpatialUnit, type AnyText, type AnyTree, type BaseItem, type BaseItemLink, type BelongsTo, type Bibliography, type BibliographyEntryInfo, type BibliographyItemLink, type BibliographySourceDocument, type Concept, type ConceptItemLink, type ContainedItemCategory, type ContainedItemCategoryFromOption, type ContainedItemCategoryOption, type Context, type ContextItem, type ContextItemCategory, type ContextNode, type ContextTree, type ContextTreeFilterLevel, type ContextTreeLevel, type ContextTreeLevelItem, type Coordinates, type CoordinatesSource, DEFAULT_PAGE_SIZE, type DictionaryUnitItemLink, type EmbeddedBibliography, type EmbeddedConcept, type EmbeddedItem, type EmbeddedPeriod, type EmbeddedPerson, type EmbeddedPropertyValue, type EmbeddedPropertyVariable, type EmbeddedResource, type EmbeddedSet, type EmbeddedSpatialUnit, type EmbeddedText, type EmbeddedTree, type Event, type Gallery, type Heading, type HeadingItemCategory, type Identification, type Image, type ImageMap, type ImageMapArea, type Interpretation, type Item, type ItemCategory, type ItemContainerCategory, type ItemLink, type ItemLinkCategory, type ItemLinks, type ItemPayloadKind, type ItemProperty, type ItemWithoutEmbeddedItems, type LanguageCodes, type License, type Metadata, type MultilingualOptions, MultilingualString, type MultilingualStringEntries, type MultilingualStringEntry, type MultilingualStringInput, type MultilingualStringJSON, type MultilingualStringObject, type MultilingualStringText, type Note, type Observation, type Period, type PeriodItemLink, type Person, type PersonItemLink, type Property, type PropertyLike, PropertyOptions, type PropertyValue, type PropertyValueContent, type PropertyValueDataType, type PropertyValueItemLink, type PropertyValueQueryItem, type PropertyVariable, type PropertyVariableItemLink, type Query, type QueryGroup, type QueryLeaf, type QueryablePropertyValueDataType, type RecursiveItemCategory, type Resource, type ResourceItemLink, type Scope, type Section, type Set, type SetAttributeValueQueryItem, type SetBibliography, type SetConcept, type SetItem, type SetItemCategory, type SetItemLink, type SetItemProperty, type SetItemSimplifiedProperty, type SetItemsSort, type SetItemsSortDirection, type SetPeriod, type SetResource, type SetSpatialUnit, type SetTree, type SimplifiedProperty, type SpatialUnit, type SpatialUnitItemLink, type Style, type StylesheetCategory, type StylesheetItem, type Text, type TextItemLink, type TopLevelItem, type Tree, type TreeItemCategory, type TreeItemLink, type WebAccordionItem, type WebBlock, type WebBlockByLayout, type WebBlockItem, type WebBlockLayout, type WebElement, type WebElementComponent, type WebElementComponentName, type WebElementComponentOf, type WebElementOf, type WebImage, type WebTitle, type Webpage, type Website, type WebsiteMetadata, type WebsitePropertyQuery, type WebsitePropertyQueryNode, type WebsiteSegment, type WebsiteType, defineLanguages, fetchGallery, fetchItem, fetchItemLinks, fetchSetItems, fetchSetPropertyValues, fetchWebsite, fetchWebsiteMetadata, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByVariableLabel, getPropertyByVariableLabelAndValue, getPropertyByVariableLabelAndValueContent, getPropertyByVariableLabelAndValueContents, getPropertyByVariableLabelAndValues, getPropertyByVariableUuid, getPropertyValueByVariableLabel, getPropertyValueByVariableUuid, getPropertyValueContentByVariableLabel, getPropertyValueContentByVariableUuid, getPropertyValueContentsByVariableUuid, getPropertyValuesByVariableLabel, getPropertyValuesByVariableUuid, getUniqueProperties, getUniquePropertyVariableLabels, withLanguages };
+export { type AccordionWebBlock, type AnyBibliography, type AnyConcept, type AnyItem, type AnyPeriod, type AnyPerson, type AnyPropertyValue, type AnyPropertyVariable, type AnyResource, type AnySet, type AnySpatialUnit, type AnyText, type AnyTree, type BaseItem, type BaseItemLink, type BelongsTo, type Bibliography, type BibliographyEntryInfo, type BibliographyItemLink, type BibliographySourceDocument, type Concept, type ConceptItemLink, type ContainedItemCategory, type ContainedItemCategoryFromOption, type ContainedItemCategoryOption, type Context, type ContextItem, type ContextItemCategory, type ContextNode, type ContextTree, type ContextTreeFilterLevel, type ContextTreeLevel, type ContextTreeLevelItem, type Coordinates, type CoordinatesSource, DEFAULT_PAGE_SIZE, type DictionaryUnitItemLink, type EmbeddedBibliography, type EmbeddedConcept, type EmbeddedItem, type EmbeddedPeriod, type EmbeddedPerson, type EmbeddedPropertyValue, type EmbeddedPropertyVariable, type EmbeddedResource, type EmbeddedSet, type EmbeddedSpatialUnit, type EmbeddedText, type EmbeddedTree, type Event, type Gallery, type Heading, type HeadingItemCategory, type Identification, type Image, type ImageMap, type ImageMapArea, type Interpretation, type Item, type ItemCategory, type ItemCategoryFromOption, type ItemCategoryOption, type ItemCategoryWithEmbeddedItems, type ItemContainerCategory, type ItemLink, type ItemLinkCategory, type ItemLinks, type ItemPayloadKind, type ItemProperty, type ItemWithoutEmbeddedItems, type LanguageCodes, type License, type Metadata, type MultilingualOptions, MultilingualString, type MultilingualStringEntries, type MultilingualStringEntry, type MultilingualStringInput, type MultilingualStringJSON, type MultilingualStringObject, type MultilingualStringText, type Note, type Observation, type Period, type PeriodItemLink, type Person, type PersonItemLink, type Property, type PropertyLike, PropertyOptions, type PropertyValue, type PropertyValueContent, type PropertyValueDataType, type PropertyValueItemLink, type PropertyValueQueryItem, type PropertyVariable, type PropertyVariableItemLink, type Query, type QueryGroup, type QueryLeaf, type QueryablePropertyValueDataType, type RecursiveItemCategory, type Resource, type ResourceItemLink, type Scope, type Section, type Set, type SetAttributeValueQueryItem, type SetBibliography, type SetConcept, type SetItem, type SetItemCategory, type SetItemLink, type SetItemProperty, type SetItemSimplifiedProperty, type SetItemsSort, type SetItemsSortDirection, type SetPeriod, type SetResource, type SetSpatialUnit, type SetTree, type SimplifiedProperty, type SpatialUnit, type SpatialUnitItemLink, type Style, type StylesheetCategory, type StylesheetItem, type Text, type TextItemLink, type TopLevelItem, type Tree, type TreeItemCategory, type TreeItemLink, type WebAccordionItem, type WebBlock, type WebBlockByLayout, type WebBlockItem, type WebBlockLayout, type WebElement, type WebElementComponent, type WebElementComponentName, type WebElementComponentOf, type WebElementOf, type WebImage, type WebTitle, type Webpage, type Website, type WebsiteMetadata, type WebsitePropertyQuery, type WebsitePropertyQueryNode, type WebsiteSegment, type WebsiteType, defineLanguages, fetchGallery, fetchItem, fetchItemLinks, fetchSetItems, fetchSetPropertyValues, fetchWebsite, fetchWebsiteMetadata, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByVariableLabel, getPropertyByVariableLabelAndValue, getPropertyByVariableLabelAndValueContent, getPropertyByVariableLabelAndValueContents, getPropertyByVariableLabelAndValues, getPropertyByVariableUuid, getPropertyValueByVariableLabel, getPropertyValueByVariableUuid, getPropertyValueContentByVariableLabel, getPropertyValueContentByVariableUuid, getPropertyValueContentsByVariableUuid, getPropertyValuesByVariableLabel, getPropertyValuesByVariableUuid, getUniqueProperties, getUniquePropertyVariableLabels, withLanguages };

package/dist/parsers/index.d.mts

@@ -1,5 +1,5 @@
 import { Webpage } from "../types/website.mjs";
-import { Bibliography, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Gallery, Identification, Item, ItemCategory, ItemLinks, Metadata, Note, Person, Property, Resource, SetItem, SetItemCategory, SimplifiedProperty } from "../types/index.mjs";
+import { Bibliography, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Gallery, Identification, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemContainerCategory, ItemLinks, Metadata, Note, Person, Property, Resource, SetItem, SetItemCategory, SimplifiedProperty } from "../types/index.mjs";
 import { XMLBibliography, XMLData, XMLDataItem, XMLGalleryData, XMLIdentification, XMLItemLinks, XMLLink, XMLMetadata, XMLNote, XMLPerson, XMLProperty, XMLResource, XMLSetItems, XMLSimplifiedProperty } from "../xml/types.mjs";
 import { ParserOptions, getParserOptions, parseStringLike } from "./helpers.mjs";
 
@@ -49,14 +49,14 @@ declare function parseItem<const TContainedItemCategory extends ContainedItemCat
   languages: T;
   parseResourceView?: ResourceViewParser<T>;
 }): Item<ItemCategory, ContainedItemCategoryFromOption<ItemCategory, TContainedItemCategory>, T>;
-declare function parseItem<const TCategory extends ItemCategory, const TContainedItemCategory extends ContainedItemCategoryOption<TCategory> | undefined = undefined, T extends ReadonlyArray<string> = ReadonlyArray<string>>(rawData: XMLData, options: {
+declare function parseItem<const TCategory extends ItemCategoryOption, const TContainedItemCategory extends ContainedItemCategoryOption<Extract<ItemCategoryFromOption<TCategory>, ItemContainerCategory>> | undefined = undefined, T extends ReadonlyArray<string> = ReadonlyArray<string>>(rawData: XMLData, options: {
   category: TCategory;
   containedItemCategory?: TContainedItemCategory;
   languages: T;
   parseResourceView?: ResourceViewParser<T>;
-}): Item<TCategory, ContainedItemCategoryFromOption<TCategory, TContainedItemCategory>, T>;
+}): Item<ItemCategoryFromOption<TCategory>, ContainedItemCategoryFromOption<ItemCategoryFromOption<TCategory>, TContainedItemCategory>, T>;
 declare function parseItem(rawData: XMLData, options: {
-  category?: ItemCategory;
+  category?: ItemCategoryOption;
   containedItemCategory?: ContainedItemCategoryOption<ItemCategory>;
   languages: ReadonlyArray<string>;
   parseResourceView?: ResourceViewParser<ReadonlyArray<string>>;

package/dist/parsers/index.mjs

@@ -1305,7 +1305,15 @@ function parseItem(rawData, options) {
 		languages: languagesToUse,
 		containedItemCategory: options.containedItemCategory
 	};
-	const category = options.category ?? normalizeCategory(rawOchre.metadata.item?.category) ?? inferTopLevelCategory(rawOchre);
+	const inferredCategory = normalizeCategory(rawOchre.metadata.item?.category) ?? inferTopLevelCategory(rawOchre);
+	let category = inferredCategory;
+	if (options.category != null) {
+		if (typeof options.category === "string") category = options.category;
+		else if (!options.category.includes(inferredCategory)) throw new Error(`OCHRE item category "${inferredCategory}" is not one of the expected categories: ${options.category.join(", ")}`, { cause: {
+			category: inferredCategory,
+			categories: options.category
+		} });
+	}
 	const defaultLanguage = resolveDefaultLanguage(rawOchre, languagesToUse);
 	const belongsTo = {
 		uuid: rawOchre.uuidBelongsTo,

package/dist/parsers/website/index.mjs

@@ -36,11 +36,45 @@ function normalizeWebsiteResources(resources) {
 	return normalized;
 }
 const SEGMENT_UNIQUE_SLUG_PREFIX_REGEX = /^\$[^-]*-/;
+function cleanWebsitePageSlug(slug) {
+	return slug?.replace(SEGMENT_UNIQUE_SLUG_PREFIX_REGEX, "") ?? null;
+}
 function prefixSlug(slug, slugPrefix) {
 	if (slugPrefix == null || slugPrefix === "") return slug;
 	if (slug === "") return slugPrefix;
 	return `${slugPrefix}/${slug}`;
 }
+function collectWebsitePageSlugs(resources, options, slugPrefix, pageSlugsByUuid = /* @__PURE__ */ new Map(), segmentSlugPrefix = slugPrefix) {
+	for (const resource of resources ?? []) {
+		if ("segments" in resource) {
+			for (const tree of resource.segments.tree) {
+				const segmentSlug = tree.identification.abbreviation == null ? null : parseStringContent(tree.identification.abbreviation, options);
+				if (segmentSlug == null) throw new Error(`Slug not found for segment website (website uuid “${tree.uuid}”)`, { cause: tree });
+				collectWebsitePageSlugs(tree.items?.resource, options, prefixSlug(segmentSlug, segmentSlugPrefix), pageSlugsByUuid);
+			}
+			continue;
+		}
+		if (!("identification" in resource)) {
+			collectWebsitePageSlugs(resource.resource, options, slugPrefix, pageSlugsByUuid, segmentSlugPrefix);
+			continue;
+		}
+		if (websitePresentationReader(resource.properties != null ? parseSimplifiedProperties(resource.properties, options) : []).value("presentation") === "page") {
+			const slug = cleanWebsitePageSlug(resource.slug);
+			if (slug == null) throw new Error(`Slug not found for page (${formatXMLWebsiteResourceMetadata(resource)})`, { cause: resource });
+			const pageSlug = prefixSlug(slug, slugPrefix);
+			pageSlugsByUuid.set(resource.uuid, pageSlug);
+			collectWebsitePageSlugs(resource.resource, options, slugPrefix == null ? void 0 : pageSlug, pageSlugsByUuid, pageSlug);
+			continue;
+		}
+		collectWebsitePageSlugs(resource.resource, options, slugPrefix, pageSlugsByUuid, segmentSlugPrefix);
+	}
+	return pageSlugsByUuid;
+}
+function parseWebsiteLinkTarget(value, context) {
+	if (value == null) return null;
+	if (value.href != null) return transformPermanentIdentificationUrlToItemLink(value.href);
+	return (value.uuid == null ? void 0 : context.pageSlugsByUuid?.get(value.uuid)) ?? value.slug;
+}
 function formatXMLWebsiteResourceMetadata(resource) {
 	const metadata = [`label “${parseStringContent(resource.identification.label)}”`, `uuid “${resource.uuid}”`];
 	if (resource.slug != null) metadata.push(`slug “${resource.slug}”`);
@@ -205,7 +239,7 @@ function parseStylesheets(styles) {
 * @param elementResource - Raw element resource data in OCHRE format
 * @returns Parsed WebElementComponent object
 */
-function parseWebElementProperties(componentProperty, elementResource, options) {
+function parseWebElementProperties(componentProperty, elementResource, options, context) {
 	const unparsedComponentName = componentProperty.values[0].content;
 	const componentNameResult = v.safeParse(componentSchema, unparsedComponentName);
 	const componentName = componentNameResult.success ? componentNameResult.output : void 0;
@@ -229,7 +263,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		}
 		case "advanced-search": {
 			const boundElementPropertyUuid = componentReader.uuid("bound-element");
-			const href = componentReader.linkTarget("link-to", transformPermanentIdentificationUrlToItemLink);
+			const href = parseWebsiteLinkTarget(componentReader.valueNode("link-to"), context);
 			if (boundElementPropertyUuid == null && href == null) throw new Error(formatComponentError("Bound element or href not found", componentName, elementResource), { cause: componentProperty });
 			properties = {
 				component: "advanced-search",
@@ -297,9 +331,9 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		case "button": {
 			const variant = componentReader.valueOr("variant", "default");
 			let isExternal = false;
-			let href = componentReader.linkTarget("navigate-to", transformPermanentIdentificationUrlToItemLink);
+			let href = parseWebsiteLinkTarget(componentReader.valueNode("navigate-to"), context);
 			if (href === null) {
-				href = componentReader.linkTarget("link-to", transformPermanentIdentificationUrlToItemLink);
+				href = parseWebsiteLinkTarget(componentReader.valueNode("link-to"), context);
 				if (href === null) throw new Error(formatComponentError("Properties “navigate-to” or “link-to” not found", componentName, elementResource), { cause: componentProperty });
 				else isExternal = true;
 			}
@@ -594,7 +628,7 @@ function parseWebElementProperties(componentProperty, elementResource, options)
 		case "search-bar": {
 			const queryVariant = componentReader.valueOr("query-variant", "submit");
 			const boundElementUuid = componentReader.uuid("bound-element");
-			const href = componentReader.linkTarget("link-to", transformPermanentIdentificationUrlToItemLink);
+			const href = parseWebsiteLinkTarget(componentReader.valueNode("link-to"), context);
 			if (!boundElementUuid && !href) throw new Error(formatComponentError("Bound element or href not found", componentName, elementResource), { cause: componentProperty });
 			properties = {
 				component: "search-bar",
@@ -705,10 +739,10 @@ function parseWebTitle(properties, identification, overrides) {
 * @param elementResource - Raw element resource data in OCHRE format
 * @returns Parsed WebElement object
 */
-function parseWebElement(elementResource, options) {
+function parseWebElement(elementResource, options, context) {
 	const identification = parseIdentification(elementResource.identification, options);
 	const elementProperties = elementResource.properties?.property ? parseSimplifiedProperties(elementResource.properties, options) : [];
-	const properties = parseWebElementProperties(websitePresentationReader(websitePresentationReader(elementProperties).requiredProperty("presentation", `Presentation property not found for element (${formatXMLWebsiteResourceMetadata(elementResource)})`).properties).requiredProperty("component", `Component property not found for element (${formatXMLWebsiteResourceMetadata(elementResource)})`), elementResource, options);
+	const properties = parseWebElementProperties(websitePresentationReader(websitePresentationReader(elementProperties).requiredProperty("presentation", `Presentation property not found for element (${formatXMLWebsiteResourceMetadata(elementResource)})`).properties).requiredProperty("component", `Component property not found for element (${formatXMLWebsiteResourceMetadata(elementResource)})`), elementResource, options, context);
 	const cssStyles = parseResponsiveCssStyles(elementProperties);
 	const title = parseWebTitle(elementProperties, identification, {
 		isNameDisplayed: properties.component === "annotated-image" || properties.component === "annotated-document" || properties.component === "collection",
@@ -733,7 +767,7 @@ function parseWebpage(webpageResource, options, context, slugPrefix) {
 	const webpageReader = websitePresentationReader(webpageProperties);
 	if (webpageReader.value("presentation") !== "page") return null;
 	const identification = parseIdentification(webpageResource.identification, options);
-	const slug = webpageResource.slug?.replace(SEGMENT_UNIQUE_SLUG_PREFIX_REGEX, "") ?? null;
+	const slug = cleanWebsitePageSlug(webpageResource.slug);
 	if (slug == null) throw new Error(`Slug not found for page (${formatXMLWebsiteResourceMetadata(webpageResource)})`, { cause: webpageResource });
 	const returnWebpage = {
 		uuid: webpageResource.uuid,
@@ -767,12 +801,12 @@ function parseWebpage(webpageResource, options, context, slugPrefix) {
 		if (resourceType === null) continue;
 		switch (resourceType) {
 			case "element": {
-				const element = parseWebElement(resource, options);
+				const element = parseWebElement(resource, options, context);
 				items.push(element);
 				break;
 			}
 			case "block": {
-				const block = parseWebBlock(resource, options);
+				const block = parseWebBlock(resource, options, context);
 				if (block) items.push(block);
 				break;
 			}
@@ -836,7 +870,7 @@ function parseWebsiteSegments(resources, context, options, slugPrefix) {
 * @param resources - Array of raw sidebar resources in OCHRE format
 * @returns Parsed Sidebar object
 */
-function parseSidebar(resources, options) {
+function parseSidebar(resources, options, context) {
 	let returnSidebar = null;
 	const items = [];
 	let title = null;
@@ -867,12 +901,12 @@ function parseSidebar(resources, options) {
 			if (resourceType === null) continue;
 			switch (resourceType) {
 				case "element": {
-					const element = parseWebElement(resource, options);
+					const element = parseWebElement(resource, options, context);
 					items.push(element);
 					break;
 				}
 				case "block": {
-					const block = parseWebBlock(resource, options);
+					const block = parseWebBlock(resource, options, context);
 					if (block) items.push(block);
 					break;
 				}
@@ -889,20 +923,20 @@ function parseSidebar(resources, options) {
 	};
 	return returnSidebar;
 }
-function parseWebAccordionItem(elementResource, childResources, options) {
-	const trigger = parseWebElement(elementResource, options);
+function parseWebAccordionItem(elementResource, childResources, options, context) {
+	const trigger = parseWebElement(elementResource, options, context);
 	const items = [];
 	for (const resource of childResources) {
 		const resourceType = websitePresentationReader(resource.properties ? parseSimplifiedProperties(resource.properties, options) : []).value("presentation");
 		if (resourceType === null) continue;
 		switch (resourceType) {
 			case "element": {
-				const element = parseWebElement(resource, options);
+				const element = parseWebElement(resource, options, context);
 				items.push(element);
 				break;
 			}
 			case "block": {
-				const block = parseWebBlock(resource, options);
+				const block = parseWebBlock(resource, options, context);
 				if (block) items.push(block);
 				break;
 			}
@@ -921,7 +955,7 @@ function parseWebAccordionItem(elementResource, childResources, options) {
 * @param blockResource - Raw block resource data in OCHRE format
 * @returns Parsed WebBlock object
 */
-function parseWebBlock(blockResource, options) {
+function parseWebBlock(blockResource, options, context) {
 	const blockProperties = blockResource.properties ? parseSimplifiedProperties(blockResource.properties, options) : [];
 	const returnBlock = {
 		uuid: blockResource.uuid,
@@ -1006,16 +1040,16 @@ function parseWebBlock(blockResource, options) {
 				const childResources = resource.resource ? normalizeWebsiteResources(resource.resource) : [];
 				const componentType = resourceReader.nestedByValue("presentation", "element").value("component");
 				if (supportsAccordionItems && componentType === "text" && childResources.length > 0) {
-					const item = parseWebAccordionItem(resource, childResources, options);
+					const item = parseWebAccordionItem(resource, childResources, options, context);
 					blockItems.push(item);
 					break;
 				}
-				const element = parseWebElement(resource, options);
+				const element = parseWebElement(resource, options, context);
 				blockItems.push(element);
 				break;
 			}
 			case "block": {
-				const block = parseWebBlock(resource, options);
+				const block = parseWebBlock(resource, options, context);
 				if (block) blockItems.push(block);
 				break;
 			}
@@ -1200,7 +1234,12 @@ function parseWebsiteTree(websiteTree, context, type, options, slugPrefix) {
 	if (!websiteTree.properties) throw new Error(`Website properties not found (website uuid “${websiteTree.uuid}”)`, { cause: websiteTree });
 	if (type === "website" && websiteTree.items?.resource == null) throw new Error(`Website pages not found (website uuid “${websiteTree.uuid}”)`, { cause: websiteTree });
 	const resources = normalizeWebsiteResources(websiteTree.items?.resource);
-	const sidebar = parseSidebar(resources, options);
+	const pageSlugsByUuid = context.pageSlugsByUuid ?? collectWebsitePageSlugs(websiteTree.items?.resource, options, slugPrefix);
+	const treeContext = {
+		...context,
+		pageSlugsByUuid
+	};
+	const sidebar = parseSidebar(resources, options, treeContext);
 	const properties = parseWebsiteProperties(websiteTree.properties.property, websiteTree, sidebar, options);
 	return {
 		uuid: websiteTree.uuid,
@@ -1211,7 +1250,7 @@ function parseWebsiteTree(websiteTree, context, type, options, slugPrefix) {
 		identification: parseIdentification(websiteTree.identification, options),
 		creators: websiteTree.creators ? parsePersonList(websiteTree.creators.creator, options) : [],
 		license: parseLicense(websiteTree.availability),
-		items: parseWebpages(resources, options, context, slugPrefix),
+		items: parseWebpages(resources, options, treeContext, slugPrefix),
 		properties
 	};
 }

package/dist/parsers/website/reader.d.mts

@@ -17,7 +17,6 @@ declare class WebsitePresentationReader<T extends LanguageCodes> {
   stringValue(label: string): string | null;
   numberValue(label: string): number | null;
   uuid(label: string): string | null;
-  linkTarget(label: string, transformHref: (href: string) => string): string | null;
   multilingualValue(label: string, options: ParserOptions<T>): MultilingualString<T> | null;
   nested(label: string): WebsitePresentationReader<T>;
   nestedByValue(label: string, value: WebsitePropertyContent<T>): WebsitePresentationReader<T>;

package/dist/parsers/website/reader.mjs

@@ -44,11 +44,6 @@ var WebsitePresentationReader = class WebsitePresentationReader {
 	uuid(label) {
 		return this.valueNode(label)?.uuid ?? null;
 	}
-	linkTarget(label, transformHref) {
-		const value = this.valueNode(label);
-		if (value?.href != null) return transformHref(value.href);
-		return value?.slug ?? null;
-	}
 	multilingualValue(label, options) {
 		const value = this.valueNode(label);
 		if (value == null) return null;

package/dist/types/index.d.mts

@@ -18,6 +18,10 @@ type ItemCategory = "tree" | "bibliography" | "concept" | "spatialUnit" | "perio
  * OCHRE item categories that can contain other items in API payloads.
  */
 type ItemContainerCategory = Extract<ItemCategory, "tree" | "set">;
+/**
+ * OCHRE item categories that expose recursive embedded item payloads.
+ */
+type ItemCategoryWithEmbeddedItems = Extract<ItemCategory, "tree" | "bibliography" | "concept" | "spatialUnit" | "period" | "resource" | "set">;
 /**
  * The category of items in a Tree
  */
@@ -26,6 +30,8 @@ type TreeItemCategory = Exclude<ItemCategory, "tree">;
  * The category of items in a Set
  */
 type SetItemCategory = ItemCategory;
+type ItemCategoryOption<U extends ItemCategory = ItemCategory> = U | ReadonlyArray<U>;
+type ItemCategoryFromOption<U extends ItemCategoryOption | undefined = undefined> = U extends ReadonlyArray<infer V> ? Extract<V, ItemCategory> : U extends ItemCategory ? U : ItemCategory;
 type ContainedItemCategory<U extends ItemCategory = ItemCategory> = U extends "tree" ? TreeItemCategory : U extends "set" ? SetItemCategory : never;
 type ContainedItemCategoryOption<U extends ItemCategory = ItemCategory> = U extends "tree" ? TreeItemCategory : U extends "set" ? SetItemCategory | ReadonlyArray<SetItemCategory> : never;
 type ContainedItemCategoryFromOption<U extends ItemCategory = ItemCategory, V extends ContainedItemCategoryOption<U> | undefined = undefined> = V extends ReadonlyArray<infer W> ? Extract<W, ContainedItemCategory<U>> : V extends ContainedItemCategory<U> ? V : ContainedItemCategory<U>;
@@ -448,9 +454,9 @@ type ItemLink<U extends ItemLinkCategory = ItemLinkCategory, T extends LanguageC
  */
 type Item<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes, W extends ItemPayloadKind = "topLevel"> = U extends ItemCategory ? U extends "tree" ? Tree<Extract<V, TreeItemCategory>, T, W> : U extends "set" ? Set<Extract<V, SetItemCategory>, T, W> : U extends "bibliography" ? Bibliography<T, W> : U extends "concept" ? Concept<T, W> : U extends "spatialUnit" ? SpatialUnit<T, W> : U extends "period" ? Period<T, W> : U extends "person" ? Person<T, W> : U extends "propertyVariable" ? PropertyVariable<T, W> : U extends "propertyValue" ? PropertyValue<T, W> : U extends "resource" ? Resource<T, W> : U extends "text" ? Text<T, W> : never : never;
 /**
- * A Tree or Set fetched without its embedded item hierarchy.
+ * An item fetched without its embedded item hierarchy.
  */
-type ItemWithoutEmbeddedItems<U extends ItemContainerCategory = ItemContainerCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes, W extends ItemPayloadKind = "topLevel"> = U extends ItemContainerCategory ? U extends "tree" ? Prettify<Omit<Tree<Extract<V, TreeItemCategory>, T, W>, "items">> : U extends "set" ? Prettify<Omit<Set<Extract<V, SetItemCategory>, T, W>, "items">> : never : never;
+type ItemWithoutEmbeddedItems<U extends ItemCategoryWithEmbeddedItems = ItemCategoryWithEmbeddedItems, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes, W extends ItemPayloadKind = "topLevel"> = U extends ItemCategoryWithEmbeddedItems ? U extends "tree" ? Prettify<Omit<Tree<Extract<V, TreeItemCategory>, T, W>, "items">> : U extends "set" ? Prettify<Omit<Set<Extract<V, SetItemCategory>, T, W>, "items">> : U extends "bibliography" ? Prettify<Omit<Bibliography<T, W>, "items">> : U extends "concept" ? Prettify<Omit<Concept<T, W>, "items">> : U extends "spatialUnit" ? Prettify<Omit<SpatialUnit<T, W>, "items">> : U extends "period" ? Prettify<Omit<Period<T, W>, "items">> : U extends "resource" ? Prettify<Omit<Resource<T, W>, "items">> : never : never;
 type TopLevelItem<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes> = Item<U, V, T, "topLevel">;
 type EmbeddedItem<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes> = Item<U, V, T, "embedded">;
 type AnyItem<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes> = Item<U, V, T, ItemPayloadKind>;
@@ -837,4 +843,4 @@ type QueryGroup = {
  */
 type Query = QueryLeaf | QueryGroup;
 //#endregion
-export { AnyBibliography, AnyConcept, AnyItem, AnyPeriod, AnyPerson, AnyPropertyValue, AnyPropertyVariable, AnyResource, AnySet, AnySpatialUnit, AnyText, AnyTree, BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, Coordinates, CoordinatesSource, DictionaryUnitItemLink, EmbeddedBibliography, EmbeddedConcept, EmbeddedItem, EmbeddedPeriod, EmbeddedPerson, EmbeddedPropertyValue, EmbeddedPropertyVariable, EmbeddedResource, EmbeddedSet, EmbeddedSpatialUnit, EmbeddedText, EmbeddedTree, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, ItemProperty, ItemWithoutEmbeddedItems, LanguageCodes, License, Metadata, Note, Observation, Period, PeriodItemLink, Person, PersonItemLink, Property, PropertyLike, PropertyValue, PropertyValueContent, PropertyValueDataType, PropertyValueItemLink, PropertyValueQueryItem, PropertyVariable, PropertyVariableItemLink, Query, QueryGroup, QueryLeaf, QueryablePropertyValueDataType, RecursiveItemCategory, Resource, ResourceItemLink, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Text, TextItemLink, TopLevelItem, Tree, TreeItemCategory, TreeItemLink };
+export { AnyBibliography, AnyConcept, AnyItem, AnyPeriod, AnyPerson, AnyPropertyValue, AnyPropertyVariable, AnyResource, AnySet, AnySpatialUnit, AnyText, AnyTree, BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, Coordinates, CoordinatesSource, DictionaryUnitItemLink, EmbeddedBibliography, EmbeddedConcept, EmbeddedItem, EmbeddedPeriod, EmbeddedPerson, EmbeddedPropertyValue, EmbeddedPropertyVariable, EmbeddedResource, EmbeddedSet, EmbeddedSpatialUnit, EmbeddedText, EmbeddedTree, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemCategoryWithEmbeddedItems, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, ItemProperty, ItemWithoutEmbeddedItems, LanguageCodes, License, Metadata, Note, Observation, Period, PeriodItemLink, Person, PersonItemLink, Property, PropertyLike, PropertyValue, PropertyValueContent, PropertyValueDataType, PropertyValueItemLink, PropertyValueQueryItem, PropertyVariable, PropertyVariableItemLink, Query, QueryGroup, QueryLeaf, QueryablePropertyValueDataType, RecursiveItemCategory, Resource, ResourceItemLink, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Text, TextItemLink, TopLevelItem, Tree, TreeItemCategory, TreeItemLink };

package/package.json

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