@cueframe/api-contract
The sanitized, versioned OpenAPI contract for CueFrame's public API. It is the only supported input for generated SDK, CLI, and MCP clients, and the only copy of the contract any consumer should read.
The package contains the public OpenAPI document, its reviewed operation inventory, the scene-shot JSON Schema with its examples, and two manifests. It intentionally excludes backend source provenance, storage identifiers, provider names, and internal cost data.
import { contractVersion, openApiSha256, operationCount } from "@cueframe/api-contract";
import openApi from "@cueframe/api-contract/openapi.json" with { type: "json" };
Use the contract
npm install @cueframe/api-contract
Requires Node.js 24 or newer for the JavaScript exports. Other languages and generators can read the public OpenAPI JSON directly. Use the versioned npm package when you need reproducible generation.
The contract describes the hosted API at https://api.cueframe.ai; installing it does not run a server. Start with the API reference, API walkthrough, or TypeScript SDK.
One contract chain
private CueFrame API ──sync──▶ cueframe-ai/cueframe-mcp: api/*.json ──build──▶ @cueframe/[email protected] ──▶ consumers
- The private API projects its public surface and writes
api/openapi.json,api/scene-schema.json,api/scene-examples.jsonandapi/contract-manifest.jsoninto this repository, from one kernel build. The manifest records the kernel version, the private commit and the sha256 of each file as written. openapi.jsoncarries the kernel's own OpenAPI components (Composition,CompositionOp,SceneShotSpecV2and its recursive parts, ...) verbatim. This repository regenerates the SDK from it and commits both.api/public-surface.json, the reviewed operation inventory, is maintained here.pnpm --filter @cueframe/api-contract buildcopies the fiveapi/*.jsonfiles intodist/as they are committed and writesmanifest.json,index.jsandindex.d.ts.- Everything else reads the npm package: the application repository's MCP
tool, composition-op and scene-contract generators and their tests, and any
third party. Nothing reads
api/out of a second checkout.
Contents and exports
| Subpath | File | What it is |
|---|---|---|
. | dist/index.js, dist/index.d.ts | Literal exports: contractVersion, openApiSha256, operationCount, pathCount, componentCount, kernelVersion, privateCommit, syncedFiles. |
./openapi.json | dist/openapi.json | The public OpenAPI 3.1 document, scene schema vendored. |
./public-surface.json | dist/public-surface.json | The reviewed operation inventory; the build fails when the document adds or removes an operation the inventory does not list. |
./scene-schema.json | dist/scene-schema.json | The canonical scene-shot JSON Schema (SceneShotSpecV2), as the kernel generates it. |
./scene-examples.json | dist/scene-examples.json | Worked scene-shot examples that validate against the schema. |
./contract-manifest.json | dist/contract-manifest.json | The sync manifest as the private API wrote it (kernelVersion, privateCommit, per-file sha256 of the un-vendored inputs) plus contractVersion. |
./manifest.json | dist/manifest.json | The build's manifest: contractVersion, the sha256 of the shipped openapi.json, operation/path/component counts, and the sync's fields. |
./package.json | package.json | The package manifest; resolve it (require.resolve("@cueframe/api-contract/package.json")) to locate the installed package and read its version. |
contractVersion is the package version. Two installs that report the same
contractVersion carry the same bytes; a consumer that records it alongside
privateCommit in the headers of what it generates (the application
repository's MCP generators will, once they read this package instead of a
local copy) can tell a bumped pin from a regenerated tree.
Version policy
- The version moves with the contract. Any byte change to one of the five
shipped
api/*.jsonfiles is a new version of this package, because every consumer reads the contract from npm and an npm version is immutable.pnpm check:contract-version(part ofpnpm checkand CI) fails a commit, pull request or working tree whereapi/*.jsonchanged against the baseline andpackages/api-contract/package.jsondid not: onmainthe baseline is the previous commit (HEAD, when the change is still uncommitted); on a branch it is the merge-base withorigin/main; CI passes the pull request's base or the push'sbeforecommit. - Semver by consumer impact. Patch: descriptions, examples, the inventory,
additive non-breaking schema detail. Minor: new operations, new optional
fields, new schema components. Major: an operation or field removed or
renamed, a type narrowed, a required field added, or the scene schema changed
incompatibly. The reviewed inventory (
public-surface.json) is the checklist: an operation added or removed there is at least a minor. - A resync with unchanged content does not move the version.
contract-manifest.jsoncarriesprivateCommit, but the private sync compares the three content files, their hashes,kernelVersionandcontractVersionagainst the committed target and writes nothing when they are equal, so a sync run from a new private commit with identical content leaves the manifest (and itsprivateCommit) untouched. Only a contract change moves the version; when it does, the sync rewrites the manifest with the new stamp and the rule above applies. - The private sync may stamp the version. When
api/contract-manifest.jsoncarriescontractVersion, it names the package version the sync was run against; the check and the build both fail when it differs frompackage.json, so a stale sync cannot publish. - Changes are recorded in the repository's
CHANGELOG.mdunder@cueframe/api-contract <version>.
License
Apache-2.0. The document is what the hosted API already serves to every caller.