Changelog¶

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]¶

Consolidates the 0.3.0-beta.1 … 0.3.0-beta.5 prereleases.

Offline recovery — on reconnect the SDK replays the messages missed while disconnected from Centrifugo's channel history, in order, before CONNECTED fires
RECONNECTED_STALE event — fires when the history window no longer covers the offline gap and messages are unrecoverable. Carries channels, missedPerChannel, totalMissed, offlineDurationMs. The SDK disconnects after emitting it; re-fetch application state, then call reconnect()
reconnect() on JaduSpine and useJaduSpine() — clears offset tracking so no history recovery runs after a post-stale state re-fetch
AUTH_RETRYING event — fires on each auth retry attempt with attemptNumber, retryInMs, elapsedMs
onError() on JaduSpine and the onError prop on JaduSpineProvider centralise ERROR/AUTH_ERROR handling; ERROR events carry a kind field ("transport" | "connect" | "subscription" | "unknown")
GCP Cloud Run deployment path for Centrifugo — cloudbuild.yaml, infra/docker/Dockerfile, entrypoint, and a deployment guide in infra/DEPLOYMENT.md

Requires Centrifugo history and recovery to be enabled on the frontend and custom namespaces (allow_history_for_client, history_size, history_ttl, force_positioning, force_recovery). See centrifugo.config.example.json — offline recovery is inert without it
Playground gained an offline simulator and recovery status panel demonstrating the gap-detection flow

recovered: true is no longer trusted as proof of a complete replay. The flag only means the requested stream position was still valid — if older publications had been evicted, Centrifugo replays what it still has and still reports success. The SDK now counts the replayed publications and compares them against the offset delta, emitting RECONNECTED_STALE when they don't match. Previously a rude transport drop (as opposed to a clean disconnect()) silently lost events.
Gap detection no longer depends on the server's history_size. It uses the offset delta from the history reply rather than inferring loss from buffer fullness, which also removes a false positive that fired RECONNECTED_STALE whenever the buffer happened to be exactly full. History is requested with limit: -1, so there is no SDK-side cap to keep in sync with server config.
Auth retry attempts are counted per auth failure rather than accumulating across reconnects, and stream epoch changes are tracked so an epoch rotation is treated as a gap.

subscribeToChannel() cleanup now uses client.removeSubscription(), which unsubscribes when needed and fully deregisters the channel from the underlying Centrifuge client. Previously, resubscribing to the same channel after all consumers unmounted (e.g. a useProjectChannel-style hook navigating away from and back to the same project) threw "Subscription to the channel X already exists", since unsubscribe() alone left the channel registered in the client's internal map.

CustomChannel class for broadcasting to any named group (project rooms, shared feeds) without user-scoping
useChannel React hook for subscribing to a CustomChannel from frontend components — multiple components share one underlying WebSocket subscription, cleaned up when the last unmounts
custom Centrifugo namespace support — the SDK now emits channels under the custom: prefix and documents the required Centrifugo namespace config

JaduSpineBackend singleton for server-side usage — initialize once at startup and call JaduSpineBackend.publish() / broadcast() from anywhere
JaduSpineProvider React context and useJaduSpine hook for sharing a single WebSocket connection across the app
JWT authentication support with playground auth flow
FrontendChannel, BackendChannel typed channel classes with FrontendChannels / BackendChannels enums
Restructured playground (backend + frontend) for local development

Initial release of @scenarix/jaduspine-sdk
JaduSpine class for WebSocket-based realtime messaging (frontend/bidirectional)
Connection management with automatic reconnection
Channel subscription/unsubscription
Message publishing and receiving
Event-driven architecture with typed events
JaduSpineHttp class for HTTP-based message publishing (backend/server-side)
Publish to single channel
Broadcast to multiple channels
Configurable retry logic with exponential backoff
SpineError custom error class with error codes
SpineErrorCode enum for programmatic error handling
SpineUtils utility class for message creation and validation
Emitter generic event emitter with type safety
VERSION and SDK_NAME exports for version tracking
Full TypeScript type definitions included
Comprehensive JSDoc documentation