{"id":31794526,"url":"https://github.com/hotsock/hotsock-js","last_synced_at":"2026-03-14T00:58:51.417Z","repository":{"id":254798939,"uuid":"725855567","full_name":"hotsock/hotsock-js","owner":"hotsock","description":"JavaScript library for Hotsock WebSocket connections, subscriptions, and messages.","archived":false,"fork":false,"pushed_at":"2026-03-04T22:34:14.000Z","size":19,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T22:41:48.969Z","etag":null,"topics":["browser","channels","javascript","jwt","messaging","react-native","real-time","subscriptions","websockets"],"latest_commit_sha":null,"homepage":"https://www.hotsock.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hotsock.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-01T02:23:28.000Z","updated_at":"2026-03-04T16:25:40.000Z","dependencies_parsed_at":"2024-08-26T07:23:23.303Z","dependency_job_id":"60efed76-b0f0-42c5-8973-f632655e076b","html_url":"https://github.com/hotsock/hotsock-js","commit_stats":null,"previous_names":["hotsock/hotsock-js"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/hotsock/hotsock-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hotsock%2Fhotsock-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hotsock%2Fhotsock-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hotsock%2Fhotsock-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hotsock%2Fhotsock-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hotsock","download_url":"https://codeload.github.com/hotsock/hotsock-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hotsock%2Fhotsock-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30478929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T20:45:58.186Z","status":"ssl_error","status_checked_at":"2026-03-13T20:45:20.133Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","channels","javascript","jwt","messaging","react-native","real-time","subscriptions","websockets"],"created_at":"2025-10-10T19:46:16.490Z","updated_at":"2026-03-14T00:58:51.399Z","avatar_url":"https://github.com/hotsock.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hotsock JavaScript Client\n\nThis JS client allows you to connect and handle Hotsock messages on a WebSocket connection. It's designed for use in the browser, provides a small and stable API with no dependencies, and handles reconnects gracefully. React Native is also supported.\n\n## Installation\n\n### Install and import the library\n\n```\nnpm add @hotsock/hotsock-js\n```\n\nor\n\n```\nyarn add @hotsock/hotsock-js\n```\n\n## Usage\n\n```javascript\nimport { HotsockClient } from \"@hotsock/hotsock-js\"\n```\n\n### Construct a client object\n\nEach client object manages a WebSocket connection to your Hotsock installation. This client can subscribe to any number of channels and fire callback functions when messages are received.\n\nThe `HotsockClient` constructor takes 2 arguments - the WebSocket URL for your installation (`WebSocketsWssUrl` from the installation's CloudFormation stack output) and an object containing a `connectTokenFn` function that returns a valid [connect-scoped JWT](https://www.hotsock.io/docs/connection/claims/#scope) authorizing a connection to the WebSocket.\n\n`connectTokenFn` must return a JWT string or return a `Promise` that resolves to a JWT string (async/await).\n\nHere's an example with a connect function that returns a static JWT string. In a real application, this function would typically be a network call to fetch a token for this user, if they're permitted.\n\n```javascript\nconst client = new HotsockClient(\n  \"wss://996iaxdp6g.execute-api.us-east-1.amazonaws.com/v1\",\n  {\n    connectTokenFn: async () =\u003e {\n      // Implement your token fetching logic here that returns a connect-scoped\n      // JWT accepted by your Hotsock installation.\n      return \"your-jwt-token\"\n    },\n    connectTokenFnMaxAttempts: 3, // Optional, defaults to 2\n    lazyConnection: true, // Optional, prevents connection until needed, defaults to false\n    logLevel: \"debug\", // Optional, default log level is \"warn\"\n  }\n)\n```\n\n### Connection management\n\nYou can control the WebSocket connection by suspending, resuming, or terminating it.\n\n```javascript\nclient.suspend() // Suspend the connection while retaining event bindings\nclient.resume() // Resume the connection and re-subscribe to channels\nclient.terminate() // Terminate the connection and clear all bindings\n```\n\n### Make a callback function\n\nAll message handler functions must accept a single `Object` argument, which is the message pre-parsed from the JSON that came over the WebSocket.\n\n```javascript\nfunction handleMessage(messageObj) {\n  console.log(\"Received Hotsock message\", messageObj)\n}\n```\n\nGiven the previous handler, you'd see something like this upon receiving a message in a browser console.\n\n```javascript\nReceived Hotsock message Object { id: \"01HP8BGSHWY952BXW1PE25DSJA\", event: \"my-event\", channel: \"my-channel\", data: \"👋 Hello from Hotsock! こんにちは\" }\n```\n\n### Subscribe to channel events\n\nBy default, a channel subscribe action will use the permissions granted from the [connect-scoped token](https://www.hotsock.io/docs/connection/claims/#scope) that authorized the connection.\n\nThe initial `connect` token often does not include permissions for all channels that will be subscribed to during the lifetime of a connection or may need modified [`uid`](https://www.hotsock.io/docs/connections/claims/#uid) / [`umd`](https://www.hotsock.io/docs/connections/claims/#umd) claims. In this case, you can pass a `subscribeTokenFn` that will be called, which must return a valid [subscribe-scoped JWT](https://www.hotsock.io/docs/connections/claims/#scope) that authorizes the channel subscription.\n\n```javascript\nconst myChannel = client.channels(\"my-channel\")\nmyChannel.subscribeTokenFn = async ({ channel, connectionId }) =\u003e {\n  // Implement your token fetching logic here that returns a subscribe-scoped\n  // JWT accepted by your Hotsock installation.\n  return \"your-jwt-token\"\n}\nmyChannel.bind(\"my-event\", (message) =\u003e {\n  console.log(\"Received message:\", message)\n})\nmyChannel.bind(\"my-other-event\", myOtherFn)\n```\n\n#### Bind from the client directly\n\nSubscribe to events matching the event name `my-event` on the `my-channel` channel. Each matching message will invoke `handleMessage` with the message object passed as an argument.\n\n```javascript\nconst binding = client.bind(\"my-event\", handleMessage, {\n  channel: \"my-channel\",\n})\n```\n\nOr with an inline function:\n\n```javascript\nconst binding = client.bind(\"my-event\", ({ data }) =\u003e console.log(data), {\n  channel: \"my-channel\",\n})\n```\n\nYou can also subscribe with a regex matcher. The following subscribes to all events on the `my-channel` channel.\n\n```javascript\nconst binding = client.bind(/.+/, handleMessage, { channel: \"my-channel\" })\n```\n\n#### Get info about the channel\n\nFrom a binding, you can access information about the channel as well as how you're represented in the channel.\n\nGet your connection's `uid` as it is represented in this channel.\n\n```javascript\nbinding.channel.uid\n// \"12345\"\n```\n\nGet your connection's `umd` as it is represented in this channel.\n\n```javascript\nbinding.channel.umd\n// {\"name\": \"Jim\"}\n```\n\nGet the channel name.\n\n```javascript\nbinding.channel.name\n// \"my-channel\"\n```\n\nGet info about other members of the channel (only populated for presence channels).\n\n```javascript\nbinding.channel.members\n// [{\"uid\":\"12345\",\"umd\":{\"name\":\"Jim\"},{\"uid\":\"23456\",\"umd\":{\"name\":\"Dwight\"}]\n```\n\n### Publish messages to a channel\n\nIf the channel subscription [permits client-initiated messages](https://www.hotsock.io/docs/connections/claims/#channels.messages.publish), use `sendMessage` to publish messages. `data` can be anything that is valid JSON (Object|Array|string|number|boolean|null) up to 32 KiB.\n\n```javascript\nconst myChannel = client.channels(\"my-channel\")\nmyChannel.sendMessage(\"isTyping\")\nmyChannel.sendMessage(\"chat\", { data: { message: \"Hello!\" } })\n```\n\nYou can also publish from the client directly, specifying the channel.\n\n```javascript\nclient.sendMessage(\"isTyping\", { channel: \"my-channel\" })\nclient.sendMessage(\"chat\", {\n  channel: \"my-channel\",\n  data: { message: \"Hello!\" },\n})\n```\n\n### Send a raw message on the WebSocket\n\nIf you prepared your message and it's already stringified JSON, you can publish it directly.\n\n```javascript\nclient.sendRawMessage(`{\"event\":\"hotsock.ping\"}`)\nclient.sendRawMessage(\n  `{\"event\":\"chat\",\"channel\":\"discussion.123\",\"data\":{\"message\":\"Hello!\"}}`\n)\n```\n\n# Unsubscribe from channel events\n\nYou can unsubscribe from the binding object that was returned when subscribing.\n\n```javascript\nbinding.unbind()\n```\n\nOr, unsubscribe from a channel via the top-level client.\n\n```javascript\nclient.unbind(\"my-event\", { channel: \"my-channel\" })\n```\n\n## Special connection events\n\nYou can subscribe to ALL incoming or outgoing messages at the connection-level, as well as the connection's connect, disconnect, and error events with a special `@@` event prefix for the following events.\n\n```javascript\n// Call a function for any message received on the WebSocket, regardless of\n// event or channel name.\nclient.bind(\"@@message\", (event) =\u003e\n  console.log(\"Received WebSocket data\", event.data)\n)\n\n// Call a function for any message sent on the WebSocket from this client.\nclient.bind(\"@@messageSent\", (rawMessage) =\u003e\n  console.log(\"Sent WebSocket message\", rawMessage)\n)\n\n// Call a function when the WebSocket connection is established.\nclient.bind(\"@@connect\", (event) =\u003e console.log(\"Connected!\"))\n\n// Call a function when the WebSocket connection is terminated.\nclient.bind(\"@@disconnect\", (event) =\u003e console.log(\"Disconnected!\"))\n\n// Call a function when a WebSocket-level error occurs. This is not called for\n// \"hotsock.error\" events.\nclient.bind(\"@@error\", (event) =\u003e console.log(\"An error occurred\", event))\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhotsock%2Fhotsock-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhotsock%2Fhotsock-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhotsock%2Fhotsock-js/lists"}