Compatibility

Builds of your app live on users' devices for years, and a web app open in a tab for weeks. This page is what Talkline promises about them.

Three things with versions

What	Version	Where you see it
The wire protocol between an SDK and the signaling server	talkline.v1, released as MAJOR.MINOR.PATCH	client.protocol in @talkline/core
The SDKs — @talkline/core, @talkline/react, @talkline/server-sdk	Each its own semantic version	package.json; SDK_VERSION in @talkline/core
The control API	In its path: /v1	Every route

The support window below is stated in protocol versions, because an SDK's version says nothing about what it speaks: each SDK release records the protocol release it was built against.

The support window

• A deployment accepts clients speaking the current and the previous minor release of talkline.v1, for at least twelve months after the newer minor ships.
• Nothing is removed from talkline.v1. A field the server no longer acts on is kept, and ignored.
• A client asking for something a deployment does not serve is answered unsupported_message, and the SDK stops asking: a newer client works, with less, against an older deployment.
• A change that cannot be made compatibly is a new protocol, talkline.v2, served alongside v1 for at least twelve months.

Being told in time

A build of your app moves through three stages as deployments move on, and the SDK tells you at each:

1. Current. Nothing to do.
2. Due an update — more than one minor release behind the deployment, and still served. The client raises updateDue on connect, with client.protocol describing both sides. Use it to prompt users to update, in your own words.
3. Outdated — below the oldest release the deployment accepts. The connect is refused with client_outdated, whose info.minProtocolVersion names that release. The SDK does not retry: only an update fixes it. Tell the user so.

Every minor release stays accepted until at least twelve months after the next minor release ships.

What your code should tolerate

Additions arrive in minor releases and need no change from you, provided your code does not break on what it does not know:

• An error code you do not know — treat it as a failure you cannot act on, never as a crash.
• An enum value you do not know — an end reason, a status, a webhook event — handle it as "other".
• A field you do not know in an API response or a webhook payload — ignore it.
• A webhook event you did not ask for — an endpoint subscribed to * receives events added later. Answer 2xx and ignore it.

The control API

The control API keeps the same promise as the protocol:

• Within /v1, every change is an addition. No route, field, enum value, error code or webhook event is removed, and none changes meaning. Additions need no change from you, provided your code tolerates them (above).
• A change that cannot be made that way is a new version, /v2, served alongside /v1 for at least twelve months after it ships. Your backend moves route by route, in its own time.

The SDKs

@talkline/core and @talkline/react are released together, at one version. Each follows semantic versioning: a patch fixes, a minor adds, a major changes something you call. A minor release of an SDK may move to a newer protocol minor, which every deployment in the support window serves.