SDK Semantic Versioning Covenant

This document is the canonical versioning covenant for the official Claimful SDKs. It binds:

  • @claimful/sdk — TypeScript SDK published to npm (packages/sdk-ts)
  • claimful/sdk — PHP SDK published to Packagist (packages/sdk-php)

It does not govern the HTTP API itself — URL versioning, deprecation headers, sunset cadence, and the breaking-change taxonomy for /api/v{'{N}'}/... live in ADR 0028. The covenant below specifies how SDK package releases track, surface, and overlap those API changes for integrators.

Document marker: CLAIMFUL_SDK_SEMVER_SENTINEL

1. Versioning scheme

Both SDKs follow SemVer 2.0.0 — MAJOR.MINOR.PATCH:

  • MAJOR — any change that meets the SDK breaking-change definition in §2. Examples: removing a public export, renaming a public method, changing the type of a method parameter or return value, raising the language floor.
  • MINOR — new public exports, new optional method parameters, new public method overloads, new optional response fields surfaced through typed helpers, new helper functions. Strictly additive. Consumers MUST tolerate.
  • PATCH — bug fixes, internal refactors with no observable surface change, dependency bumps that do not change the public type signature, documentation-only changes shipped to the package.

The pre-1.0 escape hatch from SemVer §4 does not apply — both SDKs are already at 1.x and bound by the full covenant.

2. SDK breaking-change definition

An SDK change is breaking (forces MAJOR) when any one of the following is true:

  1. A public export, public method, or public constructor is removed or renamed.
  2. The type signature of a public method changes in a way that makes previously-valid call sites invalid (parameter added without a default, parameter type narrowed, return type changed).
  3. A previously-optional method parameter becomes required.
  4. The language or runtime floor is raised (Node engines field, PHP require php constraint, minimum TypeScript or PHP language level).
  5. A public exception / error type is removed, renamed, or moved between namespaces.
  6. The shape of a public response DTO (TypeScript interface or PHP value object) changes in a way that breaks consumers reading existing fields.
  7. The SDK starts relying on a server response shape that has not yet shipped in a deployed /api/v{'{N}'}/... major — i.e. SDK and API majors are not allowed to drift.
  8. Default behaviour of a public method changes — same name, same signature, different semantics (e.g. retry policy default flips, default base URL moves).

Additive changes — new exports, new optional parameters with defaults, new fields on response DTOs that existing consumers tolerate, new error subclasses added below an existing public base type — are MINOR.

This taxonomy is the SDK-side mirror of ADR 0028 §2; SDK breaking changes are a superset because language-floor bumps and binding-shape changes are SDK-only concerns.

3. 90-day deprecation-overlap window

When a MAJOR is cut, the previous MAJOR line continues to receive security and severity-1 bug patches for a minimum of 90 days from the day the new MAJOR is published. This mirrors the ADR 0028 §3 API deprecation lifecycle:

When a major bumps, the previous major runs in parallel for a 90-day minimum overlap, signalled via RFC 8594 Sunset + RFC 8288 Deprecation/Link headers and a Postmark notification cadence.

What the SDK overlap window guarantees:

  • The previous MAJOR remains installable from npm / Packagist (no unpublish, no Packagist removal).
  • Security advisories (CVE-grade) and severity-1 correctness bugs are back-ported to the previous MAJOR for the full 90 days.
  • New features (MINOR-grade changesets) do not back-port — the previous MAJOR is frozen at the last patch line plus security/sev-1 fixes.
  • The CHANGELOG entry that introduces a new MAJOR pins the calendar end of the overlap window — e.g. "Previous v1.x line maintained until 2026-08-21".
  • Integrators on the previous MAJOR receive the same Postmark cadence defined in ADR 0028 §5 when the underlying API major is also sunsetting.

The 90-day floor is a minimum, not a maximum. The CTO may extend a specific MAJOR's overlap window per ADR 0028 §3 row 3.

4. LTS posture

The Claimful SDKs ship in a rolling-stable posture, not a long-term support (LTS) posture:

  • There is no dedicated LTS branch beyond the rolling 90-day overlap on the prior MAJOR.
  • Security and severity-1 patches land on main (current MAJOR) first, then on the previous-MAJOR maintenance branch during the 90-day overlap window.
  • The pre-pilot state described in ADR 0028 §9 applies symmetrically: the SDK has no v2.x to maintain until the API takes its first breaking change. Both SDKs are currently at 1.x.
  • Integrators who require a longer support tail than 90 days should contact Claimful through their merchant agreement; bespoke extensions are handled per-account, not by a published LTS schedule.

5. Changeset → version mapping

@claimful/sdk releases are driven by Changesets. The .changeset/ workflow at the repo root binds intent → bump:

  • patch — bug fix; no public-API change → PATCH bump.
  • minor — new public export or new optional parameter; strictly additive → MINOR bump.
  • major — any item in §2 above → MAJOR bump.

Rules enforced by .changeset/README.md:

  1. A major changeset MUST cite which row of ADR 0028 §2 (for an API-binding break) or §2 above (for an SDK-only break) applies. The changeset body is the audit trail.
  2. A major changeset implies the 90-day overlap window starts on the publish date of the new MAJOR. The release PR description carries the calendar end-date.
  3. The Changeset "Version Packages" PR rolls accumulated .changeset/*.md files into packages/sdk-ts/CHANGELOG.md and bumps packages/sdk-ts/package.json#version. Merging the Version Packages PR triggers the npm publish workflow with provenance + SBOM (Phase 16 G1).

claimful/sdk (PHP) does not use Changesets — versions are bumped manually in packages/sdk-php/composer.json and tagged. The same MAJOR / MINOR / PATCH mapping above governs the PHP bump. packages/sdk-php/CHANGELOG.md mirrors the same intent capture as the TS changesets.

6. Cross-references

  • ADR 0028 — API versioning + deprecation window policy
  • ADR 0036 — banned lexicon (governs all SDK strings + comments)
  • .changeset/README.md — local workflow
  • packages/sdk-ts/CHANGELOG.md — TypeScript SDK release log
  • packages/sdk-php/CHANGELOG.md — PHP SDK release log