Versioning

The Cosmo Realtime SDK has two independent version axes: the SDK package version and the wire protocol version.

SDK package versions

The three SDKs follow Semantic Versioning independently:

MAJOR — incremented on breaking changes to the public API surface (renamed exports, removed methods, changed required parameters). Requires a migration step.

MINOR — new capabilities added in a backward-compatible way (new methods, new optional fields, new events).

PATCH — backward-compatible bug fixes, documentation updates, internal refactors that don't change behavior.

All three SDKs target the same protocol version and are released together when the wire protocol changes.

PROTOCOL_VERSION

The wire protocol carries a separate version string: PROTOCOL_VERSION = "1.0".

This version is exchanged on session start:

• The client sends version in RealtimeClientInit.
• The server echoes it in RealtimeReady and validates compatibility.

If the server finds the client version incompatible, it replies with RealtimeError(code="version_mismatch") before closing the session. The SDK surfaces this as auth_error in TypeScript and RealtimeErrorCode.VERSION_MISMATCH in Python/Swift.

The protocol version is independent of the SDK package version. A patch release of cosmo-ai that fixes a bug does not change PROTOCOL_VERSION.

When PROTOCOL_VERSION bumps

The protocol version increments on:

• Renamed or removed fields on any wire message.
• Changed discriminator values (type string changed).
• Required fields added to a message that previously made them optional.
• Changed semantics of an existing field that could break a correctly-behaving client.

It does not increment on:

• New optional fields added to a message.
• New message types that older clients silently ignore.
• New server error codes (clients switch on known codes and fall back to server_error for unknowns).

Backward compatibility guarantees

For minor and patch releases:

• Existing optional fields remain optional.
• New fields added to request bodies are optional with backward-compatible defaults.
• New server message types are silently ignored by SDKs that don't handle them.
• New RealtimeErrorCode values fall through to the server_error bucket in the TypeScript SDK.
• New event names on RealtimeEventMap are ignored by handlers that don't subscribe to them.

Upgrade path

When a new major version ships:

1. A migration guide is published in the changelog.
2. The old major remains supported for a deprecation window (announced in the changelog).
3. The PROTOCOL_VERSION bump is accompanied by a new SDK major if it requires client-side changes.

Checking the version at runtime

// TypeScript — the package version is not readable at runtime; `cosmo-ai`
// exports no version constant and its `exports` map does not expose
// package.json. Pin the version in your own build instead.
import { PROTOCOL_VERSION } from 'cosmo-ai';

console.log(`Client speaks protocol ${PROTOCOL_VERSION}`); // "1.0"

# Python
import importlib.metadata
print(importlib.metadata.version("cosmo-ai-sdk"))

// Swift — package version is embedded in the generated client's User-Agent
print("Client speaks protocol \(RealtimeSession.protocolVersion)")