Commerce Layer SDK

Monorepo for Commerce Layer's JavaScript SDKs. Each API surface is published as its own package, and both are generated by one shared generator from that API's own published schema.

Packages

Package	npm	Description
packages/core-sdk	@commercelayer/sdk	SDK for the Core API
packages/provisioning-sdk	@commercelayer/provisioning-sdk	SDK for the Provisioning API
packages/sdk-generator	—	Templates and generation logic. Not published
packages/sdk-runtime	—	Shared runtime the generated code depends on. Not published

Each published package has zero runtime dependencies. For installation and usage, see the package READMEs — the two SDKs have separate documentation because they wrap different APIs.

How the SDKs are generated

Both SDKs are generated from the API's own /api/public/resources payload, which describes every resource, field, relationship and action. The generator turns that into resource classes, model interfaces, query types and specs.

The runtime is hand-written and shared: HTTP client, resource adapter, query building, JSON:API handling, errors and interceptors. The generator is the templates and the logic that drives them. Neither is published.

Everything generated lives under a package's gen/ directory, and nothing hand-written does. Deleting that directory and regenerating reproduces it exactly, which CI enforces on every pull request — so generated and hand-written code can never be confused, and stale output cannot survive review.

Facts a schema cannot express — the API host, client class names, resources to hide, custom actions — live in each package's sdk.config.ts.

Development

Requires Node >= 20 and pnpm 10.

pnpm install

Command	What it does
pnpm generate	Regenerate both SDKs from the live schemas
pnpm build	Build both packages
pnpm test	Run both test suites
pnpm lint	Check formatting and lint rules
pnpm ts:check	Type-check every package

To regenerate from the committed schema snapshot instead of the live API — branch-agnostic, and what the drift check uses:

pnpm -r generate-local

Releasing

Versioning is independent: each package releases on its own cadence, so each owns a tag namespace matching its directory name — core-sdk-v8.0.0, provisioning-sdk-v3.0.0.

1. Choose the versions

pnpm release:version

Prompts for each package's new version, then commits the bumps and creates the tags. Private packages are left at their existing version, and the commit contains nothing but the published packages' manifests. Nothing is pushed.

2. Push the branch and the tags

git push origin HEAD
git push origin core-sdk-v<version> provisioning-sdk-v<version>

The exact tag names are printed by the previous step. Pushing a tag drafts a GitHub release — it does not publish anything.

3. Publish a draft

Review the generated notes on the draft release and publish it. That is the only irreversible step, and it is deliberately a human one.

Publishing a draft runs the build, packaging checks and both test suites, then publishes to npm with OIDC trusted publishing — every version carries provenance, and no long-lived token exists.

Important

Publishing either draft publishes both packages: the publish step releases every package whose version is missing from the registry, not just the one whose draft you published. Publish one draft per batch. If a publish fails part-way it is safe to re-run, because anything already on the registry is skipped — but wait until the first version is visible on npm, since a version still in npm's automated review looks unpublished and will be retried.

Release notes

Notes are generated from pull request titles, grouped by label. Each package has its own notes configuration, and the core-sdk / provisioning-sdk labels are applied automatically from the paths a pull request touches. A change to the runtime or the generator is labelled for both, since it affects both SDKs.

Contributing

1. Fork this repository.

2. Clone your fork and install:

   git clone https://github.com/<your username>/commercelayer-sdk.git && cd commercelayer-sdk
   pnpm install

3. Make your changes. If you touch the generator or a target config, run pnpm generate and commit the regenerated output — CI fails if gen/ is stale or hand-edited.

4. Open a pull request. Lint, types, both test suites and the reproducibility check run automatically.

Need help?

• Join Commerce Layer's Discord community.
• Ping us on Bluesky, X (formerly Twitter), or LinkedIn.
• Is there a bug? Create an issue on this repository.

License

This repository is published under the MIT license.