SDK versioning policy

@dlbr/eid-sdk follows Semantic Versioning 2.0.0. The published package version is the source of truth and lives in packages/sdk/package.json.

See the SDK changelog for the release history.

What counts as public API

The following are public and versioned:

• exported classes, functions, types, interfaces, and enum-like unions;
• resource methods and their request/response shapes;
• documented error classes, fields, and helper methods;
• supported runtime and module entry points.

Internal source paths, generated declaration implementation details, and undocumented object properties are not compatibility promises.

Version increments

Change	Version increment	Example
Backwards-compatible bug or security fix	patch	0.1.0 → 0.1.1
Backwards-compatible feature or API addition	minor	0.1.1 → 0.2.0
Breaking public API change	major after 1.0.0	1.2.0 → 2.0.0

While the package is below 1.0.0, SemVer permits breaking changes in a minor release. We will use that rule explicitly: a breaking change before 1.0.0 increments the minor version (0.1.x → 0.2.0) and never ships as a patch release. Once 1.0.0 is published, breaking changes require a major version.

Compatibility guarantees

• Patch releases do not intentionally change the public TypeScript surface or documented runtime behavior.
• Minor releases preserve existing calls and add opt-in behavior, except for the explicitly documented pre-1.0.0 breaking changes described above.
• A deprecation must be documented before removal and include the replacement path. Removal is a breaking change under the rules above.
• Gateway API-version headers and SDK package versions are independent. An API version change is documented in the migration guide even when the SDK major version does not change.

Deprecation policy

Deprecations are intentional compatibility work, not silent removals:

1. announce the deprecated API in the changelog and migration guide;
2. add a TypeScript @deprecated annotation with the supported replacement;
3. keep the old API working for at least two minor releases or 90 days, whichever is longer;
4. remove it only in the SemVer release allowed by the versioning rules above.

Deprecations do not emit runtime warnings by default because SDK consumers may run in request paths where logging is costly or sensitive. Applications should use TypeScript diagnostics and CI deprecation checks. A security or legal issue may require an accelerated removal; that exception must include a changelog entry, migration instructions, and a clear security advisory.

Release checklist

Before publishing a version:

1. classify the change against the table above;
2. update packages/sdk/package.json and the changelog in the same release commit;
3. run SDK typecheck, tests, build, and generated API-reference validation;
4. document migration or deprecation notes for any changed behavior;
5. publish only from a clean, reviewed sdk-vX.Y.Z tag matching the package version;
6. verify the npm Trusted Publisher configuration before pushing the release tag.

The release workflow validates the tag, runs the SDK checks, verifies the generated API reference, and publishes @dlbr/eid-sdk with npm provenance and public access. A prerelease is started by pushing a tag such as sdk-v0.1.0-beta.1 and is published under the next dist-tag. A stable tag such as sdk-v0.1.0 uses latest. The workflow never changes package versions itself.

npm Trusted Publishing

SDK and CLI release workflows use npm Trusted Publishing through GitHub Actions OIDC. No long-lived NPM_TOKEN is required by the publish jobs. Before the first release, configure these trusted publishers in each npm package's Settings → Trusted publishing:

Package	Workflow filename
@dlbr/eid-sdk	release-sdk.yml
@dlbr/eid-sdk	canary-sdk.yml
@dlbr/eid-cli	release-cli.yml
@dlbr/eid-cli	canary-cli.yml

Use GitHub organization/user dlbr, repository eid, and the exact workflow filename. The workflows run on GitHub-hosted runners with Node 24/npm 11+ and OIDC id-token: write permission. Keep npm token publishing disabled after the trusted publishers have been verified.

For branch-level smoke testing, run the manual Canary JavaScript SDK or Canary DLBR EID CLI workflow from GitHub Actions. These workflows intentionally use workflow_dispatch only: pushing to main does not publish a canary automatically. This keeps every npm prerelease publish explicit and reviewable. The SDK canary derives a unique 0.x.y-canary.<run>.<attempt> version and both canary workflows publish only under the canary dist-tag:

gh workflow run canary-sdk.yml --repo dlbr/eid --ref main
gh workflow run canary-cli.yml --repo dlbr/eid --ref main

Install the SDK canary with:

npm install @dlbr/eid-sdk@canary

Canary releases do not move either next or latest.