\n\n---\n\n## What is `@arkosjs/websockets-client`?\n\nThis is the **core WebSocket client** that powers all Arkos real-time features. It wraps socket.io and adds:\n\n- **Automatic `_meta` injection** — every emit gets a unique ID and timestamp for dedup/maxAge\n- **Client-side deduplication** — guards against reconnect replay and server retry storms\n- **Ack + retry + timeout** — request-response patterns with exponential backoff\n- **Observable connection state** — drive framework reactivity without framework coupling\n- **Zero framework dependencies** — works standalone or with React, Vue, Svelte, Solid, Angular\n\n## Installation\n\n```bash\nnpm install @arkosjs/websockets-client socket.io-client\n```\n\nYou'll also need `socket.io-client` as a peer dependency.\n\n## Quick Start\n\n### Create a Manager and Client\n\n```ts\nimport { Manager } from \"socket.io-client\";\nimport { createWebsocketClient } from \"@arkosjs/websockets-client\";\n\nconst manager = new Manager(\"http://localhost:3000\", {\n auth: { token: \"your-auth-token\" },\n reconnection: true,\n});\n\nconst client = createWebsocketClient(manager);\n```\n\n### Get a Gateway for a Namespace\n\n```ts\nconst chat = client.gateway(\"/chat\");\nconst orders = client.gateway(\"/orders\");\n```\n\nCalling `.gateway()` with the same namespace twice returns the same instance — no duplicate connections. Socket.io multiplexes all namespaces over a single TCP connection.\n\n### Listen to Events\n\n```ts\nconst off = chat.on(\"receive_message\", (data) => {\n console.log(data);\n});\n\n// Cleanup when done\noff();\n```\n\nClient-side deduplication is applied automatically when `_meta.mid` is present — guards against reconnect replay or server retry storms.\n\n### Emit Events\n\n**Fire and forget:**\n\n```ts\nchat.emit(\"send_message\", { room: \"general\", content: \"hello\" });\n```\n\n**With acknowledgement:**\n\n```ts\nconst result = await chat.emit(\"send_message\", data, {\n ack: true,\n timeout: 5000,\n retries: 3,\n});\n\nif (result.success) {\n console.log(result.data);\n} else {\n console.error(result.error);\n}\n```\n\nRetries with exponential backoff on timeout, capped at 5s per attempt.\n\n### Track Connection State\n\n```ts\nconst unsub = chat.subscribe({\n onStatus: (status) => {\n console.log(status); // \"connected\" | \"disconnected\" | \"reconnecting\" | \"connecting\"\n },\n onUser: (user) => {\n console.log(user); // Populated when server emits \"authenticated\"\n },\n});\n\n// Cleanup\nunsub();\n```\n\nOr read the current state synchronously:\n\n```ts\nchat.status; // \"connected\" | \"disconnected\" | \"reconnecting\" | \"connecting\"\nchat.user; // { id, email, ... } | null\n```\n\n---\n\n## API Reference\n\n### `createWebsocketClient(manager)`\n\nCreates a `WebsocketClient` from a socket.io `Manager`.\n\n```ts\nconst client = createWebsocketClient(manager);\n```\n\n### `client.gateway(namespace)`\n\nReturns (or lazily creates) a `GatewayClient` for the given namespace.\n\n```ts\nconst chat = client.gateway(\"/chat\");\nconst orders = client.gateway(\"/orders\");\n```\n\nSubsequent calls with the same namespace return the cached instance.\n\n### `client.destroy()`\n\nDisconnects all namespace sockets and clears the gateway map.\n\n```ts\nclient.destroy();\n```\n\n---\n\n## GatewayClient API\n\nThe object returned by `client.gateway()`. All interaction with a namespace goes through here.\n\n### `.on(event, handler)` → `() => void`\n\nListen to a server event. Returns an unsubscribe function.\n\n```ts\nconst off = chat.on(\"receive_message\", (data) => {\n console.log(data);\n});\n\n// Cleanup\noff();\n```\n\n**Deduplication:** Client-side dedup is applied automatically when `_meta.mid` is present in the payload — it's stripped before the handler is called.\n\n### `.emit(event, data)` → `void`\n\nFire-and-forget emit. Automatically injects `_meta.mid` and `_meta.timestamp`.\n\n```ts\nchat.emit(\"send_message\", { room: \"general\", content: \"hello\" });\n```\n\n### `.emit(event, data, { ack: true, timeout?, retries? })` → `Promise`\n\nEmit with acknowledgement. Returns a promise resolving to the server's ack response.\n\n```ts\nconst result = await chat.emit(\"send_message\", data, {\n ack: true,\n timeout: 5000, // Wait 5s before retrying (default: 5000)\n retries: 3, // Retry up to 3 times (default: 0)\n});\n\nif (result.success) {\n console.log(\"Data:\", result.data);\n} else {\n console.error(\"Error:\", result.error);\n}\n```\n\nRetries use exponential backoff: 1s, 2s, 4s, capped at 5s.\n\n### `.subscribe(subscriber)` → `() => void`\n\nSubscribe to connection state changes. Used by framework adapters to drive reactivity.\n\n```ts\nconst unsub = chat.subscribe({\n onStatus: (status) => {\n // \"connected\" | \"disconnected\" | \"reconnecting\" | \"connecting\"\n },\n onUser: (user) => {\n // Populated when server emits \"authenticated\"\n },\n});\n\n// Cleanup\nunsub();\n```\n\n### `.status`\n\nCurrent connection status (non-reactive sync read).\n\n```ts\nif (chat.status === \"connected\") {\n chat.emit(\"send_message\", data);\n}\n```\n\n### `.user`\n\nCurrent user object (non-reactive sync read). Populated when the server emits `\"authenticated\"` after authentication.\n\n```ts\nif (chat.user) {\n console.log(`Connected as ${chat.user.id}`);\n}\n```\n\n### `.rawSocket`\n\nEscape hatch to the underlying socket.io `Socket` instance for advanced use cases.\n\n```ts\nchat.rawSocket.id; // Socket ID\n```\n\n### `.destroy()`\n\nRemoves all listeners and cleans up internal state. Called automatically by `client.destroy()`.\n\n```ts\nchat.destroy();\n```\n\n---\n\n## How `_meta` Works\n\nEvery `.emit()` call automatically wraps your payload with a `_meta` envelope:\n\n```ts\n// You call this\nchat.emit(\"send_message\", { room: \"general\", content: \"hello\" });\n\n// Server receives this\n{\n room: \"general\",\n content: \"hello\",\n _meta: {\n mid: \"550e8400-e29b-41d4-a716-446655440000\", // Auto-generated UUID\n timestamp: \"2026-01-01T00:00:00.000Z\" // Auto-generated ISO timestamp\n }\n}\n```\n\nThis `_meta` envelope is what [ArkosGateway](https://www.arkosjs.com/docs/core-concepts/components/gateways)'s `dedup` and `maxAge` options consume for server-side deduplication and time-based validation.\n\n**You never need to construct it manually.** On the receive side, `_meta` is stripped before your handler is called — it's internal plumbing, not your data.\n\n---\n\n## Framework Adapters\n\nThis package is the **core** used by all official Arkos framework bindings. If you're using a framework, use one of these instead:\n\n| Framework | Package | Status |\n| --------- | ----------------------------- | --------------------------- |\n| React | `@arkosjs/react-websockets` | ✅ Available |\n| Svelte | `@arkosjs/svelte-websockets` | 🚧 Looking for contributors |\n| Vue | `@arkosjs/vue-websockets` | 🚧 Looking for contributors |\n| Solid | `@arkosjs/solid-websockets` | 🚧 Looking for contributors |\n| Angular | `@arkosjs/angular-websockets` | 🚧 Looking for contributors |\n\nEach adapter wraps this core in your framework's reactivity primitives (hooks, stores, services, etc.).\n\n**Want to contribute a binding?** See [CONTRIBUTING_FRAMEWORK_BINDINGS.md](../../CONTRIBUTING_FRAMEWORK_BINDINGS.md).\n\n---\n\n## Peer Dependencies\n\n| Package | Version |\n| ------------------ | -------- |\n| `socket.io-client` | `^4.7.0` |\n\n---\n\n## Related\n\n- [ArkosGateway Documentation](https://www.arkosjs.com/docs/core-concepts/components/gateways)\n- [Contributing Framework Bindings](../../CONTRIBUTING_FRAMEWORK_BINDINGS.md)\n- [`@arkosjs/react-websockets`](../react-websockets)\n\n---\n\n## License\n\nMIT\n\n
\n\n**[Installation](#installation)** •\n**[Quick Start](#quick-start)** •\n**[API Reference](#api-reference)** •\n**[How \\_meta Works](#how-_meta-works)** •\n**[Framework Adapters](#framework-adapters)** •\n**[Documentation](https://www.arkosjs.com/docs/core-concepts/components/gateways)** •\n**[GitHub](https://github.com/uanela/arkos)**\n\nBuilt with ❤️ as part of [Arkos.js](https://arkosjs.com)\n\n_Real-time WebSocket communication, simplified._\n\n