Track API versioning

Pin SDKs, review OpenAPI changes, and treat package/version drift as a release checklist item.

Versioning protects integrations from silent drift. Track the API reference, SDK package versions, generated examples, webhook event contracts, and launch notes as one release surface.

Resolve version mismatches before public release

The audit found SDK version evidence that needs package-owner confirmation before hard public promises. Pin versions in your app and verify docs against the package actually published for your environment.

Release review flow

What to track

Surface	Track
API reference	New, changed, deprecated, or removed operations. 0Gate currently uses the reviewed `gate-v1.yaml` contract with OpenAPI version `2026-05-25`.
SDKs	Package version, runtime version, and changelog. The audited npm package is `@0bit/gate` version `0.1.4`; the Node runtime user agent still reports `gate-node/0.1.0`, so treat this as release drift until package owners resolve it.
Webhooks	Event names, payload shape, headers, retry behavior.
Guides	Code examples, URLs, environment names, and public-safe wording.
Product status	Whether a surface is public, partner-confidential, or review-only.
Security	Credential handling, origin rules, signature verification, rate limits.

Changelog discipline

Change class	Required docs action
OpenAPI operation added	Update the public YAML, add or update endpoint docs, and verify guides do not imply access before product approval.
OpenAPI schema changed	Update examples, SDK snippets, webhook payload docs, and any tables that mention affected fields.
SDK package changed	Run SDK tests, update install/import examples, and note package/runtime version drift if present.
Webhook event changed	Update webhook handlers, event-log guidance, replay guidance, and support checklist fields.
Product status changed	Update publication status and sidebar labels before changing guide copy.
Region/KYC/KYB wording changed	Require Product, Legal, and Compliance review before public docs ship.

Integration-side policy

type DependencyPolicy = {
  gateSdkVersion: string;
  openApiReviewedAt: string;
  webhookContractReviewedAt: string;
  sandboxRegressionPassedAt: string;
  owner: string;
};

Guardrails

Pin SDK major and minor versions in production apps.
Review generated code after API reference changes.
Keep webhook handlers tolerant of unknown event types.
Do not publish package names, install commands, or versions that have not been confirmed.
Treat Base, Link, Pools, and compliance wording as higher-review surfaces.
Link docs releases to the source OpenAPI hash or SDK commit used for examples.
Keep OpenAPI-backed API docs and handwritten guides in the same release branch.