{"id":34519696,"url":"https://github.com/uchicago-digitalculture-webdev/ochre-sdk","last_synced_at":"2026-06-09T01:03:26.464Z","repository":{"id":274244279,"uuid":"922328950","full_name":"uchicago-digitalculture-webdev/ochre-sdk","owner":"uchicago-digitalculture-webdev","description":"Node.js SDK for OCHRE","archived":false,"fork":false,"pushed_at":"2026-06-08T20:10:55.000Z","size":2718,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-06-08T20:17:43.725Z","etag":null,"topics":["cultural-heritage","digital-culture","digital-humanities","ochre","parser","research","sdk","typescript","uchicago"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/ochre-sdk","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uchicago-digitalculture-webdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-25T22:50:14.000Z","updated_at":"2026-06-08T20:11:00.000Z","dependencies_parsed_at":"2026-05-16T01:02:16.785Z","dependency_job_id":null,"html_url":"https://github.com/uchicago-digitalculture-webdev/ochre-sdk","commit_stats":null,"previous_names":["forumfordigitalculture/ochre-sdk"],"tags_count":460,"template":false,"template_full_name":null,"purl":"pkg:github/uchicago-digitalculture-webdev/ochre-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uchicago-digitalculture-webdev%2Fochre-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uchicago-digitalculture-webdev%2Fochre-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uchicago-digitalculture-webdev%2Fochre-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uchicago-digitalculture-webdev%2Fochre-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uchicago-digitalculture-webdev","download_url":"https://codeload.github.com/uchicago-digitalculture-webdev/ochre-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uchicago-digitalculture-webdev%2Fochre-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34086664,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cultural-heritage","digital-culture","digital-humanities","ochre","parser","research","sdk","typescript","uchicago"],"created_at":"2025-12-24T04:37:43.244Z","updated_at":"2026-06-09T01:03:26.448Z","avatar_url":"https://github.com/uchicago-digitalculture-webdev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OCHRE SDK\n\n`ochre-sdk` is a TypeScript package for reading data from\n[OCHRE](https://ochre.uchicago.edu/) (Online Cultural and Historical Research\nEnvironment). It fetches OCHRE XML/XQuery responses, validates the payloads, and\nparses them into typed objects that are easier to use in web applications,\ndigital collections, and research tools.\n\nThe package focuses on the public OCHRE v2 API and exposes higher-level helpers\nfor items, linked items, galleries, Set search results, Set facets, website\npresentation records, multilingual text, and property access.\n\n## Installation\n\n```sh\nnpm install ochre-sdk\n```\n\nUse the equivalent command for your package manager if you do not use npm.\n\n`ochre-sdk` is published as an ESM package. The runtime must provide `fetch`, or\nyou can pass a custom fetch implementation through each fetcher's `options.fetch`\nfield.\n\n## Quick Start\n\n```ts\nimport { fetchItem } from \"ochre-sdk\";\n\nconst result = await fetchItem(\"\u003citem-uuid\u003e\", {\n  category: \"resource\",\n  languages: [\"eng\"],\n});\n\nif (result.error != null) {\n  throw new Error(\"Failed to fetch item\", { cause: result.error });\n}\n\nconsole.log(result.item.identification.label.getText(\"eng\"));\n```\n\nEvery fetcher returns a success/error object. On success, the parsed value is\npresent and `error` is `null`; on failure, the parsed value is `null` and\n`error` contains the message.\n\n## Core API\n\n- `fetchItem(uuid, options)` fetches and parses a single OCHRE item. Passing\n  `category` as a single category narrows the returned TypeScript type to that\n  category; passing an array narrows it to any category in that list and lets the\n  parser resolve the actual category from the payload. `containedItemCategory`\n  controls how nested Tree or Set contents are parsed. For large recursive item\n  categories, pass `shouldOmitEmbeddedItems: true` to fetch the top-level item\n  without its embedded item hierarchy.\n- `fetchItemLinks(uuid, options)` fetches items linked from a source item and\n  parses them as embedded OCHRE items.\n- `fetchGallery(params, options)` fetches paginated resource galleries with an\n  optional label filter.\n- `fetchWebsite(abbreviation, options)` fetches an OCHRE website presentation\n  record, including pages, segments, components, navigation, footer, sidebar,\n  style, collection, and item-page configuration.\n- `fetchSetItems(params, containedItemCategories, options)` fetches paginated\n  Set search results with typed query and sort support.\n- `fetchSetPropertyValues(params, options)` fetches Set property-value facets\n  and optional bibliography/period attribute facets for the same query model.\n\n## Multilingual Text\n\nOCHRE text fields are represented with `MultilingualString`. It preserves plain\ntext and rich text renderings, supports language fallback, and exposes helpers\nfor exact-language access when consumers need stricter behavior.\n\n```ts\nconst title = result.item.identification.label;\n\ntitle.getText(\"eng\");\ntitle.getRichText(\"eng\");\ntitle.getExactText(\"tur\");\ntitle.getAvailableLanguages();\n```\n\nFor reusable language tuples, use `defineLanguages` to keep runtime validation\nand literal TypeScript inference together.\n\n```ts\nimport { defineLanguages, fetchWebsite } from \"ochre-sdk\";\n\nconst languages = defineLanguages(\"eng\", \"tur\");\nconst result = await fetchWebsite(\"uchicago-node\", { languages });\n```\n\n## Set Queries\n\nSet fetchers accept a recursive `Query` tree. Leaf queries can target full text,\nspecific fields, property values, bibliographies, periods, notes, images, and\nother supported OCHRE search surfaces.\n\n```ts\nimport { fetchSetItems, type Query } from \"ochre-sdk\";\n\nconst queries: Query = {\n  target: \"string\",\n  value: \"Chicago\",\n  matchMode: \"includes\",\n  isCaseSensitive: false,\n  language: \"eng\",\n};\n\nconst result = await fetchSetItems(\n  { setScopeUuids: [\"\u003cset-uuid\u003e\"], queries, page: 1, pageSize: 48 },\n  [\"resource\", \"bibliography\"],\n  { languages: [\"eng\"] },\n);\n```\n\nUse `fetchSetPropertyValues` with the same query shape when you need facet data\nfor a filtered result set.\n\n## Helpers And Types\n\nThe root export includes the SDK's public TypeScript model, website component\ntypes, query types, property getters, and small data helpers:\n\n- `Item`, `SetItem`, `ItemLink`, `Website`, `WebElementOf`,\n  `WebElementComponentOf`, `WebBlockByLayout`, `Query`, and related types.\n- `getPropertyByVariableUuid`, `getPropertyValueContentByVariableUuid`,\n  `getPropertyByVariableLabel`, `getUniqueProperties`, `filterProperties`, and\n  related property helpers.\n- `flattenItemProperties` and `DEFAULT_PAGE_SIZE` for common collection UI\n  workflows.\n\n## Development\n\nThe package source lives in `src/`, and `src/index.ts` is the public entrypoint.\nPublished files are generated into `dist/`. See `package.json` for the\navailable repository scripts.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuchicago-digitalculture-webdev%2Fochre-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuchicago-digitalculture-webdev%2Fochre-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuchicago-digitalculture-webdev%2Fochre-sdk/lists"}