@instruments/taxonomy-client

The generated, server-only TypeScript client for the public Taxonomy API. It contains transport code and OpenAPI-derived types only: it does not ship the Taxonomy corpus or depend on @instruments/taxonomy at runtime.

import { createTaxonomyClient } from "@instruments/taxonomy-client";

const taxonomy = createTaxonomyClient();
const result = await taxonomy.resolveTerm({
  path: { term: "walnut" },
  query: { context: "material" },
});

if (result.status === 200) {
  console.log(result.body);
}

The client exposes one method per canonical OpenAPI operationId: listAxes, getAxis, getConcept, getFacetedConcept, traverseGraph, getSnapshot, resolveTerm, and listTerms. Every method has generated request and status-discriminated response types. Problem responses use the generated TaxonomyProblemDetails type.

If the server returns a status that the operation does not document, the method rejects with TaxonomyUnexpectedResponseError instead of presenting that response as a member of the generated response union. The error exposes the operationId, numeric status, and original Response.

createTaxonomyClient is the only hand-written configuration seam. It accepts an optional baseUrl, fetch, and default headers. The package has a null browser export and refuses browser-like runtime evaluation; call it only from Node server code, server actions, route handlers, or other server-only modules.

Contract regeneration

The canonical contract remains packages/http-api/src/openapi.ts. After changing it, run:

pnpm --filter @instruments/taxonomy-client generate
pnpm --filter @instruments/taxonomy-client check:generated

The repository release gate checks exact generated output and runs a packed-tarball fresh-consumer smoke test before publication.