Blueprint SDKs

Blueprint SDKs are thin, domain-specific wrappers over @nolag/js-sdk. Each one turns a NoLag connection into a purpose-built API (chat rooms, notification channels, device groups, dashboard panels) and handles the topics, presence and local state for that use case. They are MIT licensed, published to npm, and run against any kraken broker you host.

Every wrapper is client-injection only: your app creates one core client with NoLag(token, { url }), owns its connect() and disconnect(), and passes it to the wrapper. The wrapper attaches its handlers when it is constructed and releases them with detach(); it never opens or closes the socket.

The SDKs

Communication

• Chat, @nolag/chat: multi-room chat with presence, typing indicators, unread counts and user mapping.
• Notify, @nolag/notify: notifications with channels, read and unread tracking, and badge counts.
• Signal, @nolag/signal: WebRTC signalling with peer discovery, offer and answer exchange, and ICE candidate relay.

Engagement

• Stream, @nolag/stream: live stream engagement with comments, reaction bursts and polls.
• Feed, @nolag/feed: activity feeds with posts, likes and comments.

Data

• Dash, @nolag/dash: live dashboards with streaming metrics, rolling aggregation and widgets.
• Track, @nolag/track: vehicle and asset GPS tracking with geofencing.
• Sync, @nolag/sync: shared documents with change tracking, versions and conflict resolution.

Infrastructure

• Queue, @nolag/queue: job queues with lifecycle tracking, progress updates and load-balanced workers.
• IoT, @nolag/iot: device telemetry and command dispatch with acknowledgement tracking.

Collaboration

• Collab, @nolag/collab: real-time collaboration with operations, cursor tracking and idle awareness.

Installation

Each SDK is a separate npm package with @nolag/js-sdk as a peer dependency (^1.12.0):

npm install @nolag/chat @nolag/js-sdk

Injecting the client

One core client can back several wrappers at once, as long as each wrapper uses a different appName:

import { NoLag } from '@nolag/js-sdk'
import { NoLagChat } from '@nolag/chat'
import { NoLagNotify } from '@nolag/notify'

// `token` is an actor token (for example from kraken's auth.json) or a
// TokenProvider that fetches a short-lived client token from your backend.
const client = NoLag(token, { url: 'ws://localhost:8080/ws' })

const chat = new NoLagChat({ client, appName: 'chat', username: 'Alice' })
const notify = new NoLagNotify({ client, appName: 'notify' })

await client.connect()                          // the app owns the connection
await Promise.all([chat.ready(), notify.ready()])

const room = chat.joinRoom('general')
const alerts = notify.subscribe('alerts')

// Teardown: wrappers first, then the socket
chat.detach()
notify.detach()
client.disconnect()

appName is the App Slug the wrapper's topics live under: a wrapper addresses appName/room/topic. Every wrapper has a default ('chat', 'notify' and so on) that works if your app uses exactly that slug.

Shared architecture

Each main class has the same lifecycle: ready() resolves after the first setup completes (and join methods throw before that), the connected event fires at the same moment, reconnected fires after each later setup, and detach() is terminal.

Granting their topics

A wrapper only works if its actor may reach the topics, rooms and lobby it uses. Each SDK page has a Topics to grant section with the exact names and two ready-made excerpts: a kraken static auth token entry, and an app for a @nolag/core project document.

The rules that apply to all of them:

• Grant every topic the wrapper subscribes to, in every room it joins. A refused subscribe arrives on the wrapper's error event, and that room then receives nothing on that topic.
• Grant the online lobby. Every wrapper subscribes to it on each connect. Without it, ready() resolves only after the 10 second lobby subscribe timeout.
• Rooms are never created by the broker. A room a wrapper joins must exist in core, or match a rule in the static file. See Rooms.
• With the static auth file, every token that should talk to the others must use the same appId, presence only works in rooms that have a rule carrying both room_slug and room_id, and lobbies are listed under allowedLobbies with a lobby_slug and lobby_id.
• With @nolag/core, the app's topics, rooms and lobbies go in the project document; accessMode: "open" gives every actor in the project pubSub, and grants narrow it. See Access Control.

Behaviour on kraken v0.9.0

The wrappers were written against the NoLag protocol, and they run on kraken unchanged. A few things work differently from what their source comments assume; the individual SDK pages go into the details:

• Reconnects. After a reconnect every wrapper subscribes to its lobby again and re-sends any presence it had set, but none of them subscribes to its room topics again: they assume the broker restored those. kraken restores subscriptions only from what its auth backend returns, and the static auth file returns none (see Production). The wrappers' message handlers stay registered on the core client, so re-issuing the subscriptions from a connect handler on the core client restores delivery. Use connect, not reconnect, which fires before the socket is back.
• Presence. kraken keeps a connection's presence in one room at a time, and presence is tied to the live socket. Wrappers that set presence in several rooms at once (for example collab, dash and iot) show you as present only in the last one. See Presence.
• Lobbies. A lobby's room list is built from the rooms the subscribing actor can reach and cached per broker node for 5 minutes after the last lobby subscribe; after that, lobby presence events stop until a client subscribes to the lobby again. Wrapper features built on the online lobby (online users, online devices, online viewers) can go stale on long-lived connections. See Lobbies.
• Echo. kraken delivers a message back to the publishing connection unless it was published with echo: false. Most wrappers turn echo off and add your own messages to their local store instead; each page says whether its wrapper does.
• Filters are routing, not privacy. Subscribers without filters receive filtered messages too. Separate audiences that must not see each other with rooms and grants, or with access scopes. See Filters.
• Delivery. The default syn broker ignores the QoS level and delivers each message to the subscribers connected at that moment. There is no offline queue and no message history for clients to read, so a client that was disconnected misses what was published meanwhile, and every wrapper's local store starts empty. See Quality of Service.
• Retained messages. None of the eleven wrappers uses retained messages.