API versioning
The version in your lockfile pins the client, not the hosted API it calls. What that means, what protects you today, and what we do not guarantee yet.
Two versions matter when you build on cmssy, and only one of them is in your lockfile. "@cmssy/core": "16.9.0" pins the client. The delivery API it calls is a hosted service that deploys on its own schedule, and there is no version segment you can pin instead.
This page says plainly what that means, including the parts we do not guarantee yet.
What the package version covers
Normal semver, over this package alone: its exports, their signatures, its behaviour. A major means your code may need changing. It says nothing about the schema on the other end - a field removed from the delivery schema is gone for @cmssy/core@16.9.0 exactly as it is for the next release.
What protects you today
- The delivery surface is an allow-list. The endpoint under
/public/{org}/{workspace}/graphqlserves a deliberately chosen subset of the schema, not everything the admin API can see. A field is there because somebody put it there. - A breaking change cannot merge silently. Every schema change is diffed against the previous one in CI. A removal or a narrowing fails the gate, and shipping one anyway takes an explicit, recorded approval.
- Published operations are validated. The SDK's own queries, the MCP server's, and the reference storefront's all run against the proposed schema before it can merge.
- Removals are marked first. A field we intend to drop is marked
@deprecatedin the schema, which shows up in your codegen output and in your editor.
What does not exist yet
Stated rather than implied:
- There is no dated API version to pin. The delivery endpoint has no version segment.
- There is no guaranteed deprecation window.
@deprecatedmarks intent; it does not promise the field survives for a set number of days. - There is no minimum notice period, and no announcement list you can subscribe to.
We would rather write that down than let a version number imply a promise the server does not keep.
What to do about it
Generate your types from the delivery endpoint, not the admin schema. It is narrower, and typing against it means your build fails on a field you were never allowed to read:
// codegen.ts
schema: `${process.env.CMSSY_API_URL}/public/${org}/${workspace}/graphql`,
documents: ["app/**/*.tsx", "lib/**/*.ts"],Run codegen in your own CI, not only on your machine. If a field you select disappears, codegen fails there - and that is the earliest anyone outside cmssy can find out.
Pin the SDK and upgrade deliberately. It does not protect you from schema changes, but it keeps the client's own behaviour from moving underneath you at the same time.