This SDK follows Semantic Versioning and ships release notes through Changesets.
SemVer Policy VaultSaaS SDK uses strict semantic versioning:
MAJOR Breaking API or behavior changes
MINOR Backward-compatible features
PATCH Backward-compatible fixes
Public Contract The following are considered part of the public contract and follow SemVer guarantees:
Exported TypeScript types
VaultClient methods and request/response shapesCanonical error structure (VaultError)
Webhook normalization output (VaultEvent)
Internal implementation details, private methods, and undocumented APIs are not covered by SemVer guarantees and may change in any release.
Deprecation Policy When deprecating a public API, we follow these steps:
Announce deprecation
Add a clear note in README/docs and release notes explaining the deprecation.
Maintain compatibility
Keep the deprecated API working through at least one full minor release.
Provide migration path
Provide a direct migration path with before/after snippets.
Remove in major version
Remove only in the next major release.
Migration Note Template Use this format in changelog/docs:
### Migration: < old API > -> < new API > - Deprecated in: vX.Y.0 - Removal target: v(X+1).0.0 - Why: < reason > - Action required: < specific code change >
Example Migration Here’s an example of how a migration might look:
await vault . charge ({ amount: 1000 , currency: 'USD' , paymentMethod: { type: 'card' , token: 'tok_visa' }, });
Release Process Guidance Do not publish breaking removals without:
A prior deprecation cycle
Migration documentation
Major version bump
Release Checklist
Add changeset
Add a changeset for user-facing changes:
Confirm version bump
Confirm version bump type follows SemVer policy (major/minor/patch).
Write actionable changelog
Keep changelog entries actionable and migration-focused.
Run release gates
Run release gates locally: bun run release:verify bun run release:dry-run
Publish via workflow
Publish only from the release workflow after CI + docs + package gates pass.
Version Support Security patches and critical bug fixes will be applied to the latest release in the supported range. Users are encouraged to stay on the latest version.
See the Security page for information about supported versions and vulnerability reporting.