SDK reference

poolse ships five npm packages. Each one builds on the one below it, so install the highest layer that fits your app and you get the rest with it.

Package	What it is	Runs on
`@poolse/sdk`	Headless TypeScript client: REST, the realtime socket, rooms and call media on the web. No UI, no framework.	Browsers, React Native, Node, Deno, Bun
`@poolse/react`	`<PoolseProvider>` and hooks (`useMessages`, `useConversations`, `useTyping`, `useRoom`, …). No UI.	React on the web and React Native
`@poolse/react-ui`	Prebuilt web components (`<PoolseInbox>`, `<ConversationView>`, room UI) and a stylesheet.	React on the web
`@poolse/react-native`	Prebuilt React Native chat components, a JS theme, the app-lifecycle hook and call-screen building blocks.	React Native / Expo
`@poolse/native`	The native call core for phones (CallKit and PushKit on iOS, a call service on Android), plus chat-notification helpers and an Expo config plugin.	React Native with a development build (not Expo Go)

Which one do I install?

You want	Install
A ready-made chat UI in a web app	`@poolse/sdk` `@poolse/react` `@poolse/react-ui`
Your own web UI on top of poolse's state and realtime	`@poolse/sdk` `@poolse/react`
Vue, Svelte, plain JS, or a Node script	`@poolse/sdk`
A ready-made chat UI in a React Native / Expo app	`@poolse/sdk` `@poolse/react` `@poolse/react-native` plus its peers (see install)
Phone calls that ring a locked or closed phone, or poolse's chat notifications on a phone	add `@poolse/native` to the React Native set

Web apps:

npm install @poolse/sdk @poolse/react @poolse/react-ui

React Native / Expo apps:

npx expo install \
  @poolse/sdk @poolse/react @poolse/react-native \
  react-native-svg react-native-markdown-display react-native-safe-area-context \
  expo-clipboard expo-image-picker expo-document-picker expo-image-manipulator

Add calls and notifications on phones:

npx expo install @poolse/native expo-notifications

How the packages depend on each other

@poolse/sdk                      (depends on: phoenix)
   ▲
@poolse/react                    (depends on: @poolse/sdk · peer: react ≥ 18)
   ▲                 ▲
@poolse/react-ui     @poolse/react-native
(web components)     (RN components · peers: react-native ≥ 0.73 and the libraries listed on its page)

@poolse/native                   (no poolse dependency · peers: expo, expo-notifications, react, react-native)

@poolse/react lists @poolse/sdk as a regular dependency, so installing @poolse/react alone also brings the SDK. Installing it yourself as well is fine; keep the major version the same.
@poolse/react-ui and @poolse/react-native depend on both @poolse/react and @poolse/sdk.
@poolse/native doesn't import any other poolse package. It talks to the poolse API itself with the end-user JWT you hand it. Your app wires it to @poolse/sdk (for example, it registers the push token the native core receives with poolse.devices.register).
Web rooms and calls (poolse.call, useCallRoom, useRoom, <RoomStage>) need livekit-client, which no poolse package installs. Add it to your app and pass the module in. See Rooms on the web.

Versions

All five packages share one version number and are released together. The current release is 3.1. Use the same major version for every @poolse/* package in your app.

3.0 was the first stable release. Upgrading from 2.x is covered in Migrating to 3.0.
Every version before 3.0.0 is deprecated on npm.
3.1 adds realtime.pause() / realtime.resume() and makes useMessages and useConversations catch up from REST after a reconnect. It also changes useAppStateLifecycle to pause the socket instead of closing every channel. @poolse/native now declares react as a peer dependency. The user channel gains onRingEnded and onCallFinished, conversation channels gain onClosed, and the socket fetches a fresh token after a refused handshake.

Licence

From 3.0.0 every package is under the poolse SDK License. Versions before 3.0.0 remain MIT. Each package also ships the licence text in its LICENSE file.