{"id":49423,"library":"stayge-ws-client-sdk","title":"stayge-ws-client-sdk","description":"Stayge WebSocket Client SDK for browser and React Native environments. This SDK provides a unified interface for connecting to Stayge's WebSocket gateway server with built-in heartbeat, reconnection, and event-driven message handling. The current stable version is 0.1.35, and it is released with no fixed cadence. Key differentiators include separate entry points for React (`react`) and React Native (`react-native`), automatic JSON parsing, and built-in heartbeat with customizable intervals and timeouts. It requires token issuance via a REST API for topic subscriptions.","status":"active","version":"0.1.35","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install stayge-ws-client-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add stayge-ws-client-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add stayge-ws-client-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only. Must specify '/react' or '/react-native' subpath. Default import does not exist.","wrong":"import { getWebSocketClient } from 'stayge-ws-client-sdk'","symbol":"getWebSocketClient","correct":"import { getWebSocketClient } from 'stayge-ws-client-sdk/react'"},{"note":"ESM-only. WsError is a class for error handling with code and topic fields.","wrong":"const { WsError } = require('stayge-ws-client-sdk/react')","symbol":"WsError","correct":"import { WsError } from 'stayge-ws-client-sdk/react'"},{"note":"Ensure you import from the correct platform-specific subpath. React and React Native have separate implementations.","wrong":"import { getWebSocketClient } from 'stayge-ws-client-sdk/react'","symbol":"getWebSocketClient (React Native)","correct":"import { getWebSocketClient } from 'stayge-ws-client-sdk/react-native'"}],"quickstart":{"code":"import { getWebSocketClient, WsError } from 'stayge-ws-client-sdk/react';\n\nconst ws = getWebSocketClient();\nconst token = process.env.WS_TOKEN ?? '';\n\nws.connect({ url: 'wss://dev.linc.fan/ws/linc' });\n\nws.onConnect({ callback: () => console.log('connected') });\n\nws.onMessage<{ title: string; body: string }>({\n  topic: 'openchat/12345',\n  callback: (topic, payload) => {\n    console.log(`Received: topic=${topic}, payload=${JSON.stringify(payload)}`);\n  },\n});\n\nws.subscribe({ topic: 'artist:12345:live', token });\n\nws.onError({ callback: (error: WsError) => {\n  if (error.code === 'connectionLost') console.log('Connection lost');\n}});","lang":"typescript","description":"Connects to a Stayge WebSocket server, subscribes to a topic, handles messages and errors."},"warnings":[{"fix":"Use import { getWebSocketClient } from 'stayge-ws-client-sdk/react' for React projects.","message":"Must import from '/react' or '/react-native' subpath; root import does not exist.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Call POST /api/youmeon/v1/websocket/token to get a token, then pass it to ws.subscribe({ topic, token }).","message":"Topic subscriptions require a token obtained from the REST API; connect does not handle auth.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Specify heartbeat.pingIntervalMs in connect() to change interval.","message":"Heartbeat is enabled by default with 20s ping interval; customize via connect options.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Register event handlers before connect() if you need to guarantee they are active from the start.","message":"Event handlers (onConnect, onMessage, etc.) can be registered before or after connect, but message handlers require the topic to be known at registration time.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'0.1.35':47 'api':91 'automat':71 'browser':11 'built':32,76 'built-in':31,75 'cadenc':55 'client':4,8 'connect':23 'current':43 'customiz':80 'differenti':57 'driven':39 'entri':60 'environ':15 'event':38 'event-driven':37 'fix':54 'gateway':28 'handl':41 'heartbeat':34,78 'includ':58 'interfac':21 'interv':81 'issuanc':87 'javascript':95 'json':72 'key':56 'messag':40 'nativ':14,67,70 'pars':73 'point':61 'provid':18 'react':13,63,64,66,69 'react-nat':68 'reconnect':35 'releas':51 'requir':85 'rest':90 'sdk':5,9,17 'separ':59 'server':29 'stabl':44 'stayg':2,6,25 'stayge-ws-client-sdk':1 'subscript':94 'timeout':83 'token':86 'topic':93 'typescript':96 'unifi':20 'version':45 'via':88 'websocket':7,27 'ws':3","created_at":"2026-06-07T17:01:42.496535+00:00","updated_at":"2026-06-07T17:01:42.496535+00:00","problems":[{"fix":"Use import { getWebSocketClient } from 'stayge-ws-client-sdk/react' or '/react-native'.","cause":"Importing from root instead of platform subpath.","error":"Cannot find module 'stayge-ws-client-sdk' or its corresponding type declarations."},{"fix":"Ensure you call ws.connect() first and pass a valid token to subscribe().","cause":"Trying to subscribe before connect or with incorrect token.","error":"Property 'subscribe' does not exist on type 'WebSocketClient'"},{"fix":"Use ES import syntax: import { getWebSocketClient } from 'stayge-ws-client-sdk/react'.","cause":"Attempting to use CJS require() on an ESM-only package.","error":"TypeError: (0 , stayge_ws_client_sdk__WEBPACK_IMPORTED_MODULE_0__.getWebSocketClient) is not a function"},{"fix":"Obtain a fresh token via POST /api/youmeon/v1/websocket/token and call ws.subscribe again.","cause":"Token is expired or invalid for the subscribed topic.","error":"WsError: subscribeError - topic: 'artist:12345:live', message: 'Invalid token'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"stayge-ws-client-sdk","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}