{"_id":"@allem-sdk/realtime","name":"@allem-sdk/realtime","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.1":{"name":"@allem-sdk/realtime","version":"0.1.1","description":"Provider-agnostic realtime hooks for React. WebSocket and SSE abstractions with useChannel, usePresence, RealtimeProvider. Works with any backend.","license":"MIT","author":{"name":"Ahmed Allem"},"main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"sideEffects":false,"devDependencies":{"@testing-library/react":"^16.0.0","@types/react":"^19.0.0","jsdom":"^25.0.0","react":"^19.0.0","react-dom":"^19.0.0","tsup":"^8.4.0","typescript":"^5.8.0","vitest":"^3.0.0"},"peerDependencies":{"react":">=18.0.0"},"repository":{"type":"git","url":"git+https://github.com/kingofmit/allem-sdk.git","directory":"packages/realtime"},"keywords":["allem-sdk","react","react-hooks","realtime","websocket","sse","server-sent-events","pubsub","channels","presence","typescript","nextjs"],"publishConfig":{"access":"public"},"scripts":{"build":"tsup","dev":"tsup --watch","clean":"rm -rf dist","test":"vitest run"},"_id":"@allem-sdk/realtime@0.1.1","bugs":{"url":"https://github.com/kingofmit/allem-sdk/issues"},"homepage":"https://github.com/kingofmit/allem-sdk#readme","_integrity":"sha512-lom86bhEZmaV7Actvi65uDRUYWdeLsue0z9pzZroSctknCGI0ZqOElYc8UG4c5yDaJWhyNB4iBXoNazF31GR2w==","_resolved":"/private/var/folders/4v/rph2hgm54rqf12vzbjxpn5kc0000gn/T/14dddfb76ee0aa7d00ffa95e0bfb3921/allem-sdk-realtime-0.1.1.tgz","_from":"file:allem-sdk-realtime-0.1.1.tgz","_nodeVersion":"26.0.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-lom86bhEZmaV7Actvi65uDRUYWdeLsue0z9pzZroSctknCGI0ZqOElYc8UG4c5yDaJWhyNB4iBXoNazF31GR2w==","shasum":"3c2b5bd82132b6d8ba61a1734053d93e9a42ee8a","tarball":"https://registry.npmjs.org/@allem-sdk/realtime/-/realtime-0.1.1.tgz","fileCount":8,"unpackedSize":21418,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEc2iy+BicR+pIkuYJyLTTWGuRhKkJiCeeEFvoV8g8oBAiA+7tk7hg0cG3qXC0YFYwsa5MC92JaP5qsebL6rZHSxew=="}]},"_npmUser":{"name":"kingofmit","email":"allem.ahmed@gmail.com"},"directories":{},"maintainers":[{"name":"kingofmit","email":"allem.ahmed@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/realtime_0.1.1_1779571359793_0.8760582754442741"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-23T21:22:39.603Z","0.1.1":"2026-05-23T21:22:39.938Z","modified":"2026-05-23T21:22:40.190Z"},"maintainers":[{"name":"kingofmit","email":"allem.ahmed@gmail.com"}],"description":"Provider-agnostic realtime hooks for React. WebSocket and SSE abstractions with useChannel, usePresence, RealtimeProvider. Works with any backend.","homepage":"https://github.com/kingofmit/allem-sdk#readme","keywords":["allem-sdk","react","react-hooks","realtime","websocket","sse","server-sent-events","pubsub","channels","presence","typescript","nextjs"],"repository":{"type":"git","url":"git+https://github.com/kingofmit/allem-sdk.git","directory":"packages/realtime"},"author":{"name":"Ahmed Allem"},"bugs":{"url":"https://github.com/kingofmit/allem-sdk/issues"},"license":"MIT","readme":"

\n \"Allem\n

\n\n

\n \"npm\n \"License\"\n \"React\n \"TypeScript\"\n

\n\n# @allem-sdk/realtime\n\nWebSocket and SSE abstraction for React. Subscribe to channels, track presence, and monitor connection status with a provider-agnostic adapter interface.\n\n## Installation\n\n```bash\nnpm install @allem-sdk/realtime\n```\n\n## Usage\n\n```tsx\nimport { RealtimeProvider, useChannel, usePresence, useConnectionStatus } from \"@allem-sdk/realtime\";\n\nfunction App() {\n return (\n \n \n \n );\n}\n\nfunction ChatRoom() {\n const [messages, setMessages] = useState([]);\n const status = useConnectionStatus();\n const members = usePresence(\"room-1\", { name: \"Ahmed\" });\n\n const { publish } = useChannel(\"room-1\", (data) => {\n setMessages((prev) => [...prev, data]);\n });\n\n return (\n
\n

Status: {status}

\n

{members.length} online

\n {messages.map((m, i) =>
{m.text}
)}\n \n
\n );\n}\n```\n\n## RealtimeAdapter Interface\n\nImplement this interface for your WebSocket/SSE provider:\n\n```tsx\nimport type { RealtimeAdapter } from \"@allem-sdk/realtime\";\n\nconst myRealtimeAdapter: RealtimeAdapter = {\n // Required\n subscribe: (channel, callback) => {\n const ws = new WebSocket(`wss://example.com/${channel}`);\n ws.onmessage = (e) => callback(JSON.parse(e.data));\n return () => ws.close();\n },\n publish: (channel, data) => { /* send to server */ },\n getStatus: () => \"connected\",\n\n // Optional — for presence support\n subscribePresence: (channel, callback) => { /* ... */ return () => {}; },\n enterPresence: (channel, info) => { /* ... */ },\n leavePresence: (channel) => { /* ... */ },\n disconnect: () => { /* ... */ },\n};\n```\n\n## useChannel\n\nSubscribe to a channel and get a `publish` function.\n\n```tsx\nconst { publish } = useChannel(channel: string, onMessage: (data: unknown) => void)\n```\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `channel` | `string` | Channel name to subscribe to |\n| `onMessage` | `(data: unknown) => void` | Callback for incoming messages |\n\nReturns `{ publish }` — sends data to the same channel. Automatically unsubscribes on unmount.\n\n## usePresence\n\nTrack who is present on a channel. Joins on mount, leaves on unmount.\n\n```tsx\nconst members = usePresence(channel: string, info?: Record)\n```\n\n| Param | Type | Description |\n|-------|------|-------------|\n| `channel` | `string` | Channel name |\n| `info` | `Record` | Your presence info (name, avatar, etc.) |\n\nReturns `PresenceMember[]`:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `id` | `string` | Member identifier |\n| `info` | `Record` | Presence info |\n| `joinedAt` | `number` | Join timestamp (ms since epoch) |\n\nRequires `subscribePresence` and `enterPresence` on the adapter. No-ops if not provided.\n\n## useConnectionStatus\n\nReturns the current connection status of the adapter.\n\n```tsx\nconst status = useConnectionStatus()\n// \"connecting\" | \"connected\" | \"disconnected\" | \"error\"\n```\n\nUses `useSyncExternalStore` with 1-second polling. Returns `\"disconnected\"` during SSR.\n\n## Exports\n\n| Export | Type | Description |\n|--------|------|-------------|\n| `RealtimeProvider` | Component | Context provider accepting a realtime adapter |\n| `useChannel` | Hook | Subscribe to a channel, returns `{ publish }` |\n| `usePresence` | Hook | Track and join presence on a channel |\n| `useConnectionStatus` | Hook | Current connection status string |\n| `useRealtimeAdapter` | Hook | Access the raw adapter directly |\n\n## Part of [Allem SDK](https://github.com/kingofmit/allem-sdk)\n\nThis package can be used standalone or as part of the full SDK. Install `allem-sdk` to get all packages in one install.\n\n## Support\n\nIf you find Allem SDK useful, consider supporting its development:\n\n\"Buy\n\n## License\n\n[MIT](https://github.com/kingofmit/allem-sdk/blob/main/LICENSE) - [Ahmed Allem](https://kingallem.com)\n","readmeFilename":"README.md","_rev":"1-cfbba7701ef1f0c736dd67a6fc3423e8"}