ochre-sdk 1.0.12 → 1.0.14

package/README.md

@@ -47,7 +47,9 @@ present and `error` is `null`; on failure, the parsed value is `null` and
 
 - `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.
+  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.
 - `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/constants.d.mts

@@ -0,0 +1,17 @@
+import { X2jOptions } from "fast-xml-parser";
+
+//#region src/constants.d.ts
+declare const XML_ARRAY_TAGS: ReadonlyArray<string>;
+declare const XML_PARSER_OPTIONS: X2jOptions;
+declare const DEFAULT_LANGUAGES: readonly ["eng"];
+declare const BELONGS_TO_COLLECTION_UUID = "30054cb2-909a-4f34-8db9-8fe7369d691d";
+declare const PRESENTATION_ITEM_UUID = "f1c131b6-1498-48a4-95bf-a9edae9fd518";
+declare const TEXT_ANNOTATION_UUID = "b9ca2732-78f4-416e-b77f-dae7647e68a9";
+declare const TEXT_ANNOTATION_HOVER_CARD_UUID = "c7f6a08a-f07b-49b6-bcb1-af485da3c58f";
+declare const TEXT_ANNOTATION_ITEM_PAGE_VARIANT_UUID = "bf4476ab-6bc8-40d0-a001-1446213c72ce";
+declare const TEXT_ANNOTATION_ENTRY_PAGE_VARIANT_UUID = "9d52db95-a9cf-45f7-a0bf-fc9ba9f0aae0";
+declare const TEXT_ANNOTATION_TEXT_STYLING_UUID = "3e6f86ab-df81-45ae-8257-e2867357df56";
+declare const TEXT_ANNOTATION_TEXT_STYLING_VARIANT_UUID = "e1647bef-d801-4100-bdde-d081c422f763";
+declare const TEXT_ANNOTATION_TEXT_STYLING_HEADING_LEVEL_UUID = "d4266f0b-3f8d-4b32-8c15-4b229c8bb11e";
+//#endregion
+export { BELONGS_TO_COLLECTION_UUID, DEFAULT_LANGUAGES, PRESENTATION_ITEM_UUID, TEXT_ANNOTATION_ENTRY_PAGE_VARIANT_UUID, TEXT_ANNOTATION_HOVER_CARD_UUID, TEXT_ANNOTATION_ITEM_PAGE_VARIANT_UUID, TEXT_ANNOTATION_TEXT_STYLING_HEADING_LEVEL_UUID, TEXT_ANNOTATION_TEXT_STYLING_UUID, TEXT_ANNOTATION_TEXT_STYLING_VARIANT_UUID, TEXT_ANNOTATION_UUID, XML_ARRAY_TAGS, XML_PARSER_OPTIONS };

package/dist/constants.mjs

@@ -0,0 +1,85 @@
+//#region src/constants.ts
+const XML_ARRAY_TAGS = [
+	"string",
+	"content",
+	"tree",
+	"bibliography",
+	"spatialUnit",
+	"concept",
+	"person",
+	"period",
+	"propertyValue",
+	"propertyVariable",
+	"resource",
+	"text",
+	"set",
+	"dictionaryUnit",
+	"variable",
+	"property",
+	"value",
+	"context",
+	"creator",
+	"author",
+	"event",
+	"interpretation",
+	"observation",
+	"observer",
+	"heading",
+	"note",
+	"reference",
+	"coord",
+	"area",
+	"footnote",
+	"language",
+	"section",
+	"translation",
+	"phonemic",
+	"editor",
+	"publisher",
+	"scope",
+	"level",
+	"style",
+	"flattenContexts",
+	"suppressContexts",
+	"filterContexts",
+	"sortContexts",
+	"detailContexts",
+	"downloadContexts",
+	"labelContexts",
+	"prominentContexts"
+];
+const XML_PARSER_OPTIONS = {
+	alwaysCreateTextNode: true,
+	captureMetaData: true,
+	ignoreAttributes: false,
+	removeNSPrefix: true,
+	ignorePiTags: true,
+	trimValues: false,
+	parseTagValue: false,
+	parseAttributeValue: false,
+	attributeNamePrefix: "",
+	textNodeName: "payload",
+	stopNodes: ["*.referenceFormatDiv", "*.citationFormatSpan"],
+	htmlEntities: true,
+	isArray(tagName, jPath, isLeafNode, isAttribute) {
+		if (isAttribute) return false;
+		if (XML_ARRAY_TAGS.includes(tagName)) return true;
+		return false;
+	},
+	attributeValueProcessor: (attrName, attrValue) => {
+		if (attrValue.startsWith("xs:")) return attrValue.replace("xs:", "");
+		return null;
+	}
+};
+const DEFAULT_LANGUAGES = ["eng"];
+const BELONGS_TO_COLLECTION_UUID = "30054cb2-909a-4f34-8db9-8fe7369d691d";
+const PRESENTATION_ITEM_UUID = "f1c131b6-1498-48a4-95bf-a9edae9fd518";
+const TEXT_ANNOTATION_UUID = "b9ca2732-78f4-416e-b77f-dae7647e68a9";
+const TEXT_ANNOTATION_HOVER_CARD_UUID = "c7f6a08a-f07b-49b6-bcb1-af485da3c58f";
+const TEXT_ANNOTATION_ITEM_PAGE_VARIANT_UUID = "bf4476ab-6bc8-40d0-a001-1446213c72ce";
+const TEXT_ANNOTATION_ENTRY_PAGE_VARIANT_UUID = "9d52db95-a9cf-45f7-a0bf-fc9ba9f0aae0";
+const TEXT_ANNOTATION_TEXT_STYLING_UUID = "3e6f86ab-df81-45ae-8257-e2867357df56";
+const TEXT_ANNOTATION_TEXT_STYLING_VARIANT_UUID = "e1647bef-d801-4100-bdde-d081c422f763";
+const TEXT_ANNOTATION_TEXT_STYLING_HEADING_LEVEL_UUID = "d4266f0b-3f8d-4b32-8c15-4b229c8bb11e";
+//#endregion
+export { BELONGS_TO_COLLECTION_UUID, DEFAULT_LANGUAGES, PRESENTATION_ITEM_UUID, TEXT_ANNOTATION_ENTRY_PAGE_VARIANT_UUID, TEXT_ANNOTATION_HOVER_CARD_UUID, TEXT_ANNOTATION_ITEM_PAGE_VARIANT_UUID, TEXT_ANNOTATION_TEXT_STYLING_HEADING_LEVEL_UUID, TEXT_ANNOTATION_TEXT_STYLING_UUID, TEXT_ANNOTATION_TEXT_STYLING_VARIANT_UUID, TEXT_ANNOTATION_UUID, XML_ARRAY_TAGS, XML_PARSER_OPTIONS };

package/dist/fetchers/gallery.d.mts

@@ -0,0 +1,38 @@
+import { Gallery } from "../types/index.mjs";
+
+//#region src/fetchers/gallery.d.ts
+type FetchFunction = (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
+type FetchGalleryBaseOptions<TLanguages extends ReadonlyArray<string> | undefined = undefined> = {
+  languages?: TLanguages;
+  fetch?: FetchFunction;
+};
+type FetchGalleryLanguages<TLanguages extends ReadonlyArray<string> | undefined> = TLanguages extends readonly [] ? ReadonlyArray<string> : TLanguages extends ReadonlyArray<string> ? TLanguages : ReadonlyArray<string>;
+/**
+ * Fetches and parses a gallery from the OCHRE API
+ *
+ * @param params - The parameters for the fetch
+ * @param params.uuid - The UUID of the gallery
+ * @param params.filter - The filter to apply to the gallery
+ * @param params.page - The page number to fetch
+ * @param params.perPage - The number of items per page
+ * @param options - The options for the fetch
+ * @param options.languages - Language codes to parse. Inline arrays preserve literal types automatically.
+ * @param options.fetch - The fetch function to use
+ * @returns The parsed gallery or an error message if the fetch/parse fails
+ */
+declare function fetchGallery<const TLanguages extends ReadonlyArray<string> | undefined = undefined>(params: {
+  uuid: string;
+  filter?: string;
+  page: number;
+  perPage: number;
+}, options?: FetchGalleryBaseOptions<TLanguages>): Promise<{
+  gallery: Gallery<FetchGalleryLanguages<TLanguages>>;
+  error: null;
+  detailedError: null;
+} | {
+  gallery: null;
+  error: string;
+  detailedError: string;
+}>;
+//#endregion
+export { fetchGallery };

package/dist/fetchers/gallery.mjs

@@ -0,0 +1,91 @@
+import { DEFAULT_LANGUAGES, XML_PARSER_OPTIONS } from "../constants.mjs";
+import { createSchemaValidationError, getErrorOutput, stringLiteral } from "../utils.mjs";
+import { gallerySchema, iso639_3Schema } from "../schemas.mjs";
+import { restoreXMLMetadata } from "../xml/metadata.mjs";
+import { parseGallery } from "../parsers/index.mjs";
+import { XMLGalleryData } from "../xml/schemas.mjs";
+import * as v from "valibot";
+import { XMLParser } from "fast-xml-parser";
+//#region src/fetchers/gallery.ts
+function parseLanguages(languages) {
+	const parsedLanguages = [];
+	for (const language of languages) parsedLanguages.push(v.parse(iso639_3Schema, language));
+	return parsedLanguages;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function collectContentLanguages(value, languages) {
+	if (Array.isArray(value)) {
+		for (const item of value) collectContentLanguages(item, languages);
+		return;
+	}
+	if (!isRecord(value)) return;
+	const content = value.content;
+	if (Array.isArray(content)) for (const contentItem of content) {
+		if (!isRecord(contentItem)) continue;
+		const language = contentItem.lang;
+		if (typeof language === "string" && language !== "zxx") languages.add(language);
+	}
+	for (const child of Object.values(value)) collectContentLanguages(child, languages);
+}
+function resolveGalleryLanguages(data, requestedLanguages) {
+	if (requestedLanguages.length > 0) return requestedLanguages;
+	const languages = /* @__PURE__ */ new Set();
+	collectContentLanguages(data.result.ochre.gallery, languages);
+	return languages.size > 0 ? [...languages] : [...DEFAULT_LANGUAGES];
+}
+function buildXQuery(params) {
+	const { uuid, filter, page, perPage } = params;
+	const start = (page - 1) * perPage + 1;
+	const filterLiteral = stringLiteral(filter?.trim() ?? "");
+	return `<ochre>{
+  for $q in doc()/ochre[@uuid=${stringLiteral(uuid)}]
+  let $filter := ${filterLiteral}
+  let $resources := $q//items/resource
+  let $filtered :=
+    if ($filter = "")
+    then $resources
+    else $resources[contains(lower-case(string-join(identification/label//text(), "")), lower-case($filter))]
+  let $maxLength := count($filtered)
+  return <gallery maxLength="{$maxLength}">{
+    $q/metadata/project,
+    $q/metadata/item,
+    subsequence($filtered, ${start}, ${perPage})
+  }</gallery>
+}</ochre>`;
+}
+async function fetchGallery(params, options) {
+	try {
+		const { uuid, filter, page, perPage } = v.parse(gallerySchema, params);
+		const requestedLanguages = options?.languages == null ? [] : parseLanguages(options.languages);
+		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
+			method: "POST",
+			body: buildXQuery({
+				uuid,
+				filter,
+				page,
+				perPage
+			}),
+			headers: { "Content-Type": "application/xquery" }
+		});
+		if (!response.ok) throw new Error("Error fetching gallery items, please try again later.", { cause: response.statusText });
+		const dataRaw = await response.text();
+		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
+		const { success, issues, output } = v.safeParse(XMLGalleryData, data);
+		if (!success) throw createSchemaValidationError("Failed to parse gallery XML", issues);
+		restoreXMLMetadata(output, data);
+		return {
+			gallery: parseGallery(output, { languages: resolveGalleryLanguages(output, requestedLanguages) }),
+			error: null,
+			detailedError: null
+		};
+	} catch (error) {
+		return {
+			gallery: null,
+			...getErrorOutput(error, "Failed to fetch gallery")
+		};
+	}
+}
+//#endregion
+export { fetchGallery };

package/dist/fetchers/item-links.d.mts

@@ -0,0 +1,32 @@
+import { ContainedItemCategoryFromOption, ContainedItemCategoryOption, Item, ItemCategory, ItemContainerCategory } from "../types/index.mjs";
+
+//#region src/fetchers/item-links.d.ts
+type FetchFunction = (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
+type FetchItemLinksBaseOptions<TLanguages extends ReadonlyArray<string> | undefined = undefined> = {
+  languages?: TLanguages;
+  fetch?: FetchFunction;
+};
+type FetchItemLinksLanguages<TLanguages extends ReadonlyArray<string> | undefined> = TLanguages extends readonly [] ? ReadonlyArray<string> : TLanguages extends ReadonlyArray<string> ? TLanguages : ReadonlyArray<string>;
+/**
+ * Fetches linked OCHRE items by source-item UUID.
+ *
+ * @param uuid - The UUID of the OCHRE item whose linked items should be fetched
+ * @param options - Fetch and parser options
+ * @param options.containedItemCategory - The category of items inside linked Trees/Sets to parse. Tree accepts one category; Set accepts one category or an array.
+ * @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 parsed linked items
+ */
+declare function fetchItemLinks<const TContainedItemCategory extends ContainedItemCategoryOption<ItemContainerCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options?: FetchItemLinksBaseOptions<TLanguages> & {
+  containedItemCategory?: TContainedItemCategory;
+}): Promise<{
+  items: Array<Item<ItemCategory, ContainedItemCategoryFromOption<ItemCategory, TContainedItemCategory>, FetchItemLinksLanguages<TLanguages>, "embedded">>;
+  error: null;
+  detailedError: null;
+} | {
+  items: null;
+  error: string;
+  detailedError: string;
+}>;
+//#endregion
+export { fetchItemLinks };

package/dist/fetchers/item-links.mjs

@@ -0,0 +1,120 @@
+import { DEFAULT_LANGUAGES, XML_PARSER_OPTIONS } from "../constants.mjs";
+import { createSchemaValidationError, getErrorOutput } from "../utils.mjs";
+import { iso639_3Schema, uuidSchema } from "../schemas.mjs";
+import { restoreXMLMetadata } from "../xml/metadata.mjs";
+import { parseLinkedItems } from "../parsers/index.mjs";
+import { XMLItemLinksData } from "../xml/schemas.mjs";
+import * as v from "valibot";
+import { XMLParser } from "fast-xml-parser";
+//#region src/fetchers/item-links.ts
+function parseLanguages(languages) {
+	const parsedLanguages = [];
+	for (const language of languages) parsedLanguages.push(v.parse(iso639_3Schema, language));
+	return parsedLanguages;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function collectContentLanguages(value, languages) {
+	if (Array.isArray(value)) {
+		for (const item of value) collectContentLanguages(item, languages);
+		return;
+	}
+	if (!isRecord(value)) return;
+	const content = value.content;
+	if (Array.isArray(content)) for (const contentItem of content) {
+		if (!isRecord(contentItem)) continue;
+		const language = contentItem.lang;
+		if (typeof language === "string" && language !== "zxx") languages.add(language);
+	}
+	for (const child of Object.values(value)) collectContentLanguages(child, languages);
+}
+function resolveItemLinksLanguages(data, requestedLanguages) {
+	if (requestedLanguages.length > 0) return requestedLanguages;
+	const languages = /* @__PURE__ */ new Set();
+	collectContentLanguages(data.result.ochre.items, languages);
+	return languages.size > 0 ? [...languages] : [...DEFAULT_LANGUAGES];
+}
+/**
+* Build an XQuery string to fetch linked items from the OCHRE API.
+*
+* @param uuid - The UUID of the OCHRE item whose links should be fetched
+* @returns An XQuery string
+*/
+function buildXQuery(uuid) {
+	return `<ochre>{${`let $item-uuid := "${uuid}"
+
+let $source-items := (
+  fn:collection("ochre/resource")/ochre[@uuid = $item-uuid]/resource,
+  fn:collection("ochre/bibliography")/ochre[@uuid = $item-uuid]/bibliography,
+  fn:collection("ochre/period")/ochre[@uuid = $item-uuid]/period,
+  fn:collection("ochre/person")/ochre[@uuid = $item-uuid]/person,
+  fn:collection("ochre/propertyVariable")/ochre[@uuid = $item-uuid]/propertyVariable,
+  fn:collection("ochre/propertyValue")/ochre[@uuid = $item-uuid]/propertyValue,
+  fn:collection("ochre/text")/ochre[@uuid = $item-uuid]/text,
+  fn:collection("ochre/tree")/ochre[@uuid = $item-uuid]/tree,
+  fn:collection("ochre/set")/ochre[@uuid = $item-uuid]/set,
+  fn:collection("ochre/spatialUnit")/ochre[@uuid = $item-uuid]/spatialUnit,
+  fn:collection("ochre/concept")/ochre[@uuid = $item-uuid]/concept
+)
+
+let $link-nodes := (
+  $source-items/links/*,
+  $source-items/observations/observation/links/*,
+  $source-items/interpretations/interpretation/links/*
+)
+
+return
+    <items>{
+      for $link at $position in $link-nodes
+      let $uuid := $link/@uuid/string()
+      let $category := name($link)
+      where $uuid ne "" and not($uuid = $link-nodes[position() lt $position]/@uuid/string())
+      return
+        if ($category = "resource") then fn:collection("ochre/resource")/ochre/resource[@uuid = $uuid]
+        else if ($category = "bibliography") then fn:collection("ochre/bibliography")/ochre/bibliography[@uuid = $uuid]
+        else if ($category = "period") then fn:collection("ochre/period")/ochre/period[@uuid = $uuid]
+        else if ($category = "person") then fn:collection("ochre/person")/ochre/person[@uuid = $uuid]
+        else if ($category = "propertyVariable" or $category = "variable") then fn:collection("ochre/propertyVariable")/ochre/propertyVariable[@uuid = $uuid]
+        else if ($category = "propertyValue" or $category = "value") then fn:collection("ochre/propertyValue")/ochre/propertyValue[@uuid = $uuid]
+        else if ($category = "text") then fn:collection("ochre/text")/ochre/text[@uuid = $uuid]
+        else if ($category = "tree") then fn:collection("ochre/tree")/ochre/tree[@uuid = $uuid]
+        else if ($category = "set") then fn:collection("ochre/set")/ochre/set[@uuid = $uuid]
+        else if ($category = "spatialUnit") then fn:collection("ochre/spatialUnit")/ochre/spatialUnit[@uuid = $uuid]
+        else if ($category = "concept") then fn:collection("ochre/concept")/ochre/concept[@uuid = $uuid]
+        else ()
+    }</items>`}}</ochre>`;
+}
+async function fetchItemLinks(uuid, options) {
+	try {
+		const parsedUuid = v.parse(uuidSchema, uuid);
+		const requestedLanguages = options?.languages == null ? [] : parseLanguages(options.languages);
+		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
+			method: "POST",
+			body: buildXQuery(parsedUuid),
+			headers: { "Content-Type": "application/xquery" }
+		});
+		if (!response.ok) throw new Error("Failed to fetch OCHRE item links", { cause: response.statusText });
+		const dataRaw = await response.text();
+		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
+		const { success, issues, output } = v.safeParse(XMLItemLinksData, data);
+		if (!success) throw createSchemaValidationError("Failed to parse OCHRE item links", issues);
+		restoreXMLMetadata(output, data);
+		const languages = resolveItemLinksLanguages(output, requestedLanguages);
+		return {
+			items: parseLinkedItems(output.result.ochre.items, {
+				containedItemCategory: options?.containedItemCategory,
+				languages
+			}),
+			error: null,
+			detailedError: null
+		};
+	} catch (error) {
+		return {
+			items: null,
+			...getErrorOutput(error, "Unknown error")
+		};
+	}
+}
+//#endregion
+export { fetchItemLinks };

package/dist/fetchers/item.d.mts

@@ -0,0 +1,74 @@
+import { ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Item, ItemCategory, ItemContainerCategory, ItemWithoutEmbeddedItems } from "../types/index.mjs";
+
+//#region src/fetchers/item.d.ts
+type FetchFunction = (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
+type FetchItemBaseOptions<TLanguages extends ReadonlyArray<string> | undefined = undefined> = {
+  languages?: TLanguages;
+  fetch?: FetchFunction;
+};
+type FetchItemNoOmitEmbeddedItemsOption = {
+  shouldOmitEmbeddedItems?: false;
+};
+type FetchItemLanguages<TLanguages extends ReadonlyArray<string> | undefined> = TLanguages extends readonly [] ? ReadonlyArray<string> : TLanguages extends ReadonlyArray<string> ? TLanguages : ReadonlyArray<string>;
+type FetchItemSuccess<TItem> = {
+  item: TItem;
+  error: null;
+  detailedError: null;
+};
+type FetchItemError = {
+  item: null;
+  error: string;
+  detailedError: string;
+};
+type FetchItemResult<TItem> = Promise<FetchItemSuccess<TItem> | FetchItemError>;
+/**
+ * Defines a reusable languages tuple with validation and literal type inference.
+ *
+ * Inline arrays can be passed directly to fetchItem:
+ * `fetchItem(uuid, { languages: ["eng", "spa"] })`.
+ *
+ * Use this helper when the language set is stored separately:
+ * `const languages = defineLanguages("eng", "spa")`.
+ */
+declare function defineLanguages<const TLanguages extends ReadonlyArray<string>>(...languages: TLanguages): TLanguages;
+/**
+ * @deprecated Pass inline language arrays directly to fetchItem, or use
+ * defineLanguages("eng", "spa") for reusable language tuples.
+ */
+declare function withLanguages<const TLanguages extends ReadonlyArray<string>>(languages: TLanguages): TLanguages;
+/**
+ * Fetches an OCHRE item by UUID from the OCHRE API
+ *
+ * @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.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.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
+ */
+declare function fetchItem<const TContainedItemCategory extends ContainedItemCategoryOption<ItemContainerCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options?: FetchItemBaseOptions<TLanguages> & FetchItemNoOmitEmbeddedItemsOption & {
+  category?: undefined;
+  containedItemCategory?: TContainedItemCategory;
+}): FetchItemResult<Item<ItemCategory, ContainedItemCategoryFromOption<ItemCategory, TContainedItemCategory>, FetchItemLanguages<TLanguages>>>;
+declare function fetchItem<const TContainedItemCategory extends ContainedItemCategoryOption<ItemContainerCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchItemBaseOptions<TLanguages> & {
+  category?: undefined;
+  containedItemCategory?: TContainedItemCategory;
+  shouldOmitEmbeddedItems: true;
+}): FetchItemResult<ItemWithoutEmbeddedItems<ItemContainerCategory, ContainedItemCategoryFromOption<ItemContainerCategory, TContainedItemCategory>, FetchItemLanguages<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: FetchItemBaseOptions<TLanguages> & FetchItemNoOmitEmbeddedItemsOption & {
+  category: TCategory;
+  containedItemCategory?: TContainedItemCategory;
+}): FetchItemResult<Item<TCategory, ContainedItemCategoryFromOption<TCategory, TContainedItemCategory>, FetchItemLanguages<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: FetchItemBaseOptions<TLanguages> & {
+  category: TCategory;
+  containedItemCategory?: TContainedItemCategory;
+  shouldOmitEmbeddedItems: true;
+}): FetchItemResult<ItemWithoutEmbeddedItems<TCategory, ContainedItemCategoryFromOption<TCategory, TContainedItemCategory>, FetchItemLanguages<TLanguages>>>;
+declare function fetchItem<const TCategory extends ItemCategory, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(uuid: string, options: FetchItemBaseOptions<TLanguages> & FetchItemNoOmitEmbeddedItemsOption & {
+  category: TCategory;
+  containedItemCategory?: never;
+}): FetchItemResult<Item<TCategory, ContainedItemCategory<TCategory>, FetchItemLanguages<TLanguages>>>;
+//#endregion
+export { defineLanguages, fetchItem, withLanguages };

package/dist/fetchers/item.mjs

@@ -0,0 +1,146 @@
+import { XML_PARSER_OPTIONS } from "../constants.mjs";
+import { createSchemaValidationError, getErrorOutput, stringLiteral } from "../utils.mjs";
+import { iso639_3Schema, uuidSchema } from "../schemas.mjs";
+import { restoreXMLMetadata } from "../xml/metadata.mjs";
+import { parseItem } from "../parsers/index.mjs";
+import { XMLData } from "../xml/schemas.mjs";
+import { parseWebpageView } from "../parsers/website/index.mjs";
+import * as v from "valibot";
+import { XMLParser } from "fast-xml-parser";
+//#region src/fetchers/item.ts
+function isItemContainerCategory(category) {
+	return category === "tree" || category === "set";
+}
+function isItemContainer(item) {
+	return isItemContainerCategory(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}"`);
+}
+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 });
+}
+function buildOmitEmbeddedItemsXQuery(uuid) {
+	return `xquery version "1.0-ml";
+
+let $ochre := doc()/ochre[@uuid=${stringLiteral(uuid)}][1]
+return
+  if (empty($ochre)) 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)] }
+      else $node
+  }`;
+}
+function omitEmbeddedItems(item) {
+	const { items: _items, ...itemWithoutEmbeddedItems } = item;
+	return itemWithoutEmbeddedItems;
+}
+/**
+* Validate language codes while preserving literal tuple inference.
+*/
+function parseLanguages(languages) {
+	const parsedLanguages = [];
+	for (const language of languages) parsedLanguages.push(v.parse(iso639_3Schema, language));
+	return parsedLanguages;
+}
+/**
+* Defines a reusable languages tuple with validation and literal type inference.
+*
+* Inline arrays can be passed directly to fetchItem:
+* `fetchItem(uuid, { languages: ["eng", "spa"] })`.
+*
+* Use this helper when the language set is stored separately:
+* `const languages = defineLanguages("eng", "spa")`.
+*/
+function defineLanguages(...languages) {
+	return parseLanguages(languages);
+}
+/**
+* @deprecated Pass inline language arrays directly to fetchItem, or use
+* defineLanguages("eng", "spa") for reusable language tuples.
+*/
+function withLanguages(languages) {
+	return parseLanguages(languages);
+}
+async function fetchItem(uuid, options) {
+	try {
+		const parsedUuid = v.parse(uuidSchema, uuid);
+		assertItemCategoryAllowed(options?.category, options?.containedItemCategory);
+		const shouldOmitEmbeddedItems = options?.shouldOmitEmbeddedItems === true;
+		assertShouldOmitEmbeddedItemsAllowed(options?.category, shouldOmitEmbeddedItems);
+		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),
+			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 });
+		const dataRaw = await response.text();
+		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
+		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,
+			containedItemCategory: options?.containedItemCategory,
+			languages,
+			parseResourceView: (view, context) => parseWebpageView(view, { languages: context.metadata.languages }, context)
+		});
+		return {
+			item: shouldOmitEmbeddedItems && isItemContainer(parsedItem) ? omitEmbeddedItems(parsedItem) : parsedItem,
+			error: null,
+			detailedError: null
+		};
+	} catch (error) {
+		return {
+			item: null,
+			...getErrorOutput(error, "Unknown error")
+		};
+	}
+}
+//#endregion
+export { defineLanguages, fetchItem, withLanguages };