https://github.com/uchicago-digitalculture-webdev/ochre-sdk
Node.js SDK for OCHRE
https://github.com/uchicago-digitalculture-webdev/ochre-sdk
cultural-heritage digital-culture digital-humanities ochre parser research sdk typescript uchicago
Last synced: 15 days ago
JSON representation
Node.js SDK for OCHRE
- Host: GitHub
- URL: https://github.com/uchicago-digitalculture-webdev/ochre-sdk
- Owner: uchicago-digitalculture-webdev
- License: mit
- Created: 2025-01-25T22:50:14.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-06-08T20:10:55.000Z (16 days ago)
- Last Synced: 2026-06-08T20:17:43.725Z (16 days ago)
- Topics: cultural-heritage, digital-culture, digital-humanities, ochre, parser, research, sdk, typescript, uchicago
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/ochre-sdk
- Size: 2.59 MB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# OCHRE SDK
`ochre-sdk` is a TypeScript package for reading data from
[OCHRE](https://ochre.uchicago.edu/) (Online Cultural and Historical Research
Environment). It fetches OCHRE XML/XQuery responses, validates the payloads, and
parses them into typed objects that are easier to use in web applications,
digital collections, and research tools.
The package focuses on the public OCHRE v2 API and exposes higher-level helpers
for items, linked items, galleries, Set search results, Set facets, website
presentation records, multilingual text, and property access.
## Installation
```sh
npm install ochre-sdk
```
Use the equivalent command for your package manager if you do not use npm.
`ochre-sdk` is published as an ESM package. The runtime must provide `fetch`, or
you can pass a custom fetch implementation through each fetcher's `options.fetch`
field.
## Quick Start
```ts
import { fetchItem } from "ochre-sdk";
const result = await fetchItem("", {
category: "resource",
languages: ["eng"],
});
if (result.error != null) {
throw new Error("Failed to fetch item", { cause: result.error });
}
console.log(result.item.identification.label.getText("eng"));
```
Every fetcher returns a success/error object. On success, the parsed value is
present and `error` is `null`; on failure, the parsed value is `null` and
`error` contains the message.
## Core API
- `fetchItem(uuid, options)` fetches and parses a single OCHRE item. Passing
`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
optional label filter.
- `fetchWebsite(abbreviation, options)` fetches an OCHRE website presentation
record, including pages, segments, components, navigation, footer, sidebar,
style, collection, and item-page configuration.
- `fetchSetItems(params, containedItemCategories, options)` fetches paginated
Set search results with typed query and sort support.
- `fetchSetPropertyValues(params, options)` fetches Set property-value facets
and optional bibliography/period attribute facets for the same query model.
## Multilingual Text
OCHRE text fields are represented with `MultilingualString`. It preserves plain
text and rich text renderings, supports language fallback, and exposes helpers
for exact-language access when consumers need stricter behavior.
```ts
const title = result.item.identification.label;
title.getText("eng");
title.getRichText("eng");
title.getExactText("tur");
title.getAvailableLanguages();
```
For reusable language tuples, use `defineLanguages` to keep runtime validation
and literal TypeScript inference together.
```ts
import { defineLanguages, fetchWebsite } from "ochre-sdk";
const languages = defineLanguages("eng", "tur");
const result = await fetchWebsite("uchicago-node", { languages });
```
## Set Queries
Set fetchers accept a recursive `Query` tree. Leaf queries can target full text,
specific fields, property values, bibliographies, periods, notes, images, and
other supported OCHRE search surfaces.
```ts
import { fetchSetItems, type Query } from "ochre-sdk";
const queries: Query = {
target: "string",
value: "Chicago",
matchMode: "includes",
isCaseSensitive: false,
language: "eng",
};
const result = await fetchSetItems(
{ setScopeUuids: [""], queries, page: 1, pageSize: 48 },
["resource", "bibliography"],
{ languages: ["eng"] },
);
```
Use `fetchSetPropertyValues` with the same query shape when you need facet data
for a filtered result set.
## Helpers And Types
The root export includes the SDK's public TypeScript model, website component
types, query types, property getters, and small data helpers:
- `Item`, `SetItem`, `ItemLink`, `Website`, `WebElementOf`,
`WebElementComponentOf`, `WebBlockByLayout`, `Query`, and related types.
- `getPropertyByVariableUuid`, `getPropertyValueContentByVariableUuid`,
`getPropertyByVariableLabel`, `getUniqueProperties`, `filterProperties`, and
related property helpers.
- `flattenItemProperties` and `DEFAULT_PAGE_SIZE` for common collection UI
workflows.
## Development
The package source lives in `src/`, and `src/index.ts` is the public entrypoint.
Published files are generated into `dist/`. See `package.json` for the
available repository scripts.
## License
[MIT](LICENSE)