Versioning

The SeatBuilder platform versions its REST surface and its JavaScript SDK independently. Both follow semver and both promise that backwards- compatible additions never bump a major version.

REST API

Every public endpoint lives under the api/v1 global prefix:

POST /api/v1/charts
GET  /api/v1/events/{eventKey}
POST /api/v1/events/{eventKey}/seats/hold
...

Inside v1, the platform only ships additive changes:

• New endpoints, new request fields (always optional), new response fields, new webhook event types.
• Bug fixes that bring runtime behaviour in line with the documented contract.

Any change that would break an existing v1 integration ships at a new prefix — api/v2 — alongside api/v1. Both prefixes run side by side during the deprecation window. There is no auto-upgrade and no implicit prefix rewriting; integrators opt in by changing the URL.

SDK semver

The current published version is @seats/[email protected]. Pin to the major:

npm install @seats/sdk@^2

The v1 → v2 break was a single field rename on the event payload:

The semantic change matters: under v1 each event froze the chart layout at event-creation time; under v2 events follow the chart's current published version live. Re-publishing a chart now propagates the new layout to every existing event on next read. Booked-seat consistency across chart changes is the chart owner's responsibility — see Integration for the implications.

Future breaking changes (if any) will ship as @seats/sdk@3 with the same migration-table style; v2 remains supported during the deprecation window.

CDN caching

If you load the SDK from a CDN, pin to a major (@2), never @latest:

<!-- ✅ recommended -->
<script src="https://cdn.jsdelivr.net/npm/@seats/sdk@2/dist/index.iife.min.js"></script>

<!-- ❌ unsafe — jsdelivr can serve a stale build for up to 7 days -->
<script src="https://cdn.jsdelivr.net/npm/@seats/sdk@latest/dist/index.iife.min.js"></script>

Why this matters. jsdelivr caches version-tag resolutions for up to seven days. A new @2.x.y patch publish is not visible to every edge immediately — most clients get the new build within minutes, but a tail of edges can serve the previous resolution for the full TTL. Pinning to @2 lets jsdelivr cache the resolution aggressively without freezing you on an old build, because the bytes behind @2 change when you publish — only the redirect from @latest to a specific version is what gets stuck.

If you need to force a refresh after an urgent patch, you can call the jsdelivr purge API: https://purge.jsdelivr.net/npm/@seats/sdk@2/dist/index.iife.min.js. A standard purge is asynchronous and propagates within minutes.

Hardening with a user-controlled SDK build

For integrators who need a stronger supply-chain story — for example, to defend against an upstream CDN compromise or against jsdelivr's cache lag — host the SDK yourself. Either:

1. Install @seats/sdk from npm and serve dist/index.iife.min.js from your own static origin (CDN or otherwise), or
2. Build a slim wrapper bundle that re-exports SeatsIO.render and serve that.

Both options put the SDK build under your CI's release control. You opt out of jsdelivr's CDN convenience in exchange for deterministic versioning and the ability to apply Subresource Integrity hashes.