@instruments/colorscope-client

Server-only TypeScript client for ColorScope’s anonymous deterministic HTTP API. Its request, response, Problem Details, binary snapshot, and HTML documentation types are generated solely from packages/api/src/openapi.json.

Usage

import { createColorScopeClient } from "@instruments/colorscope-client";

const colorscope = createColorScopeClient({
  baseUrl: "https://colorscope.materialinstruments.com",
});

const result = await colorscope.interpretColor({ body: { input: "navy" } });
if (result.error) {
  console.error(result.error.requestId, result.error.detail);
} else {
  console.log(result.data.data);
}

The API is anonymous: the client has no authentication, API-key, tenant, metering, agent, LLM, MCP, or catalogue-mutation methods. Import it only from Node.js or React Server Components. Browser resolution and Next.js Client Component imports fail deliberately.

For the gzip reference snapshot, request binary parsing explicitly:

const snapshot = await colorscope.downloadReferenceSnapshot({ parseAs: "arrayBuffer" });

The documentation operation returns HTML and may be requested with { parseAs: "text" }.

Generated contract and drift

src/generated/ is machine-owned. Regenerate and verify it with:

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

scripts/openapi-emitter.ts emits types and operation bindings directly from the API-owned OpenAPI document, without a JavaScript TypeScript compiler dependency. It supports the schema features used by this API: local references, objects, required and optional properties, nullable values, unions/intersections, literal values, arrays and fixed tuples. Unsupported schema keywords, serialization modes and response shapes fail generation rather than silently widening the contract.

The fetch runtime remains the original Hey API 0.99.0 output, preserved in scripts/runtime-templates/ and copied unchanged during generation. Its MIT attribution is in NOTICE.md and ships with the SDK. Consumers do not install generator tooling or transport peers. Drift checking regenerates into a temporary directory and compares the complete file list and bytes. The compile-contract fixture and emitter tests run under TypeScript 7.

capability-policy.json is the review-owned classification input. It names every callable Core source symbol exactly and assigns either one or more OpenAPI operationIds or a concrete local-only reason. Generation fails when a Core symbol is unclassified or a policy entry has gone stale, so a new export cannot inherit a broad directory fallback silently.

capability-ledger.json is generated from that policy, Core’s canonical entrypoint manifest, and the statically parsed export graph. Its capabilities collection contains one canonical record for every Core source-symbol implementation and every HTTP operation; HTTP records carry the Reference, Deterministic, or System classification derived from the OpenAPI tag. Its separate bindings collection preserves every public entrypoint/export alias and points each alias to its canonical Core identity, so aliases cannot acquire conflicting classifications.

Release acceptance

pnpm --filter @instruments/colorscope-client build
pnpm --filter @instruments/colorscope-client typecheck
pnpm --filter @instruments/colorscope-client test

The pack check installs the tarball into clean temporary pnpm and npm consumers, verifies the runtime bundle has no undeclared package imports, audits the exact current Core version plus SDK candidate, verifies a lightweight Node request, proves a Vite client build is rejected, proves a Next server build succeeds, and proves a Next Client Component build fails with a server-only diagnostic. It therefore requires network access to the public npm registry and npm audit service; the full test command has the same prerequisite because it includes the pack check.

Coordinated release

The GitHub v<semver> release tag must equal the SDK version. The SDK and OpenAPI info.version must have the same major and minor versions, while the SDK patch may equal or exceed the OpenAPI patch for packaging-only releases. The single release workflow verifies the API and SDK, attaches the matching OpenAPI document, immutable reference snapshot, and SDK tarball, then publishes the server-only npm package.