@poolse/react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `@poolse/react` are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[semver](https://semver.org).
+
+## [0.1.0] — 2026-06-01
+
+First publishable release.
+
+### Added
+
+- `<PoolseProvider>` — mount-once SDK instance with ref-stable callbacks
+  (safe to pass `config={{getToken: () => ...}}` inline on every render).
+- `usePoolse()` — raw `Poolse` instance escape hatch.
+- Realtime hooks: `useMe`, `useConversations`, `useConversation`,
+  `useMembers`, `useMessages`, `useThread`, `useReactions`, `useTyping`,
+  `usePresence`, `useRealtimeStatus`.
+- Attachments: `useAttachmentUpload`, `useAttachmentUrl`.
+- Real-time conversation list — `useConversations` subscribes to the
+  user's `user:<id>` channel and prepends on `conversation:created`
+  push (no manual refetch needed).
+- Optimistic message send with id-based dedup: `useMessages.send()`
+  inserts under the same id the server will assign, so realtime echo
+  upserts in place.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Poolse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# `@poolse/react`
+
+Headless React hooks for **[poolse](https://poolse.dev)** — realtime chat infrastructure.
+
+Provider + hooks for `useMe`, `useConversations`, `useMessages`, `useTyping`, `usePresence`, `useReactions`, `useThread`, `useAttachmentUpload`, and more. No UI — bring your own, or use the prebuilt components in **[`@poolse/react-ui`](https://www.npmjs.com/package/@poolse/react-ui)**.
+
+## Install
+
+```bash
+npm install @poolse/react @poolse/sdk
+```
+
+## Quick start
+
+```tsx
+import { PoolseProvider, useMessages } from '@poolse/react';
+
+function App() {
+  return (
+    <PoolseProvider
+      config={{
+        apiUrl: 'https://chat.example.com',
+        getToken: async () => {
+          const res = await fetch('/api/chat-token', { method: 'POST' });
+          const { token } = await res.json();
+          return token;
+        },
+      }}
+    >
+      <Chat conversationId="<conversation-id>" />
+    </PoolseProvider>
+  );
+}
+
+function Chat({ conversationId }: { conversationId: string }) {
+  const { messages, send, loading } = useMessages(conversationId);
+
+  if (loading) return <div>Loading…</div>;
+  return (
+    <ul>
+      {messages.map((m) => (
+        <li key={m.id}>{m.body}</li>
+      ))}
+      <button onClick={() => send({ body: 'Hi!' })}>Send hi</button>
+    </ul>
+  );
+}
+```
+
+## Hooks at a glance
+
+| Hook                            | Returns                                                           |
+| ------------------------------- | ----------------------------------------------------------------- |
+| `useMe()`                       | The signed-in End User                                            |
+| `useConversations()`            | List + `create` + realtime new-conversation push                  |
+| `useConversation(id)`           | Single conversation read + refetch                                |
+| `useMembers(convId)`            | Membership list + add/remove helpers                              |
+| `useMessages(convId)`           | Live messages + `send` + pagination + optimistic dedup            |
+| `useThread(convId, rootId)`     | Replies + `sendReply` + pagination                                |
+| `useTyping(convId)`             | Live `typing` set + `signalTyping` (debounced)                    |
+| `usePresence(convId)`           | Live `online` set                                                 |
+| `useReactions(messageId, opts)` | Live reaction map + add/remove                                    |
+| `useAttachmentUpload()`         | Stateful `upload(file)` with `uploading` + `error`                |
+| `useAttachmentUrl(id)`          | Presigned download URL                                            |
+| `useRealtimeStatus()`           | Socket lifecycle (connecting / connected / reconnecting / closed) |
+| `usePoolse()`                   | Raw `Poolse` instance (escape hatch)                              |
+
+## What the provider gives you
+
+- **One `Poolse` instance per mount.** Stable WebSocket and channel subscriptions for the life of the provider. Pass a fresh inline `config={{ getToken: … }}` on every render — `getToken` is read from a ref each call, so the SDK doesn't tear down.
+- **Auto-rejoin** when the socket drops + reconnects.
+- **Optimistic message dedup** by client-generated id — `useMessages.send()` adds the row under the same id the server will assign, so the realtime echo upserts in place rather than appending a duplicate.
+
+## Documentation
+
+- Full hook reference + recipes — <https://poolse.dev/docs/react>
+- Source — <https://github.com/poolse-hq/js-sdk>
+- Issues — <https://github.com/poolse-hq/js-sdk/issues>
+
+## License
+
+MIT