Migrating to 3.0

3.0 is the first stable poolse SDK. The five packages share a version number and are released together; the current release is 3.1. Upgrade them together:

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

Install only the ones you use. Web apps need sdk and react, plus react-ui for the prebuilt UI. React Native apps add react-native, and native for calls and notifications on phones. See SDK reference for which is which.

Coming from 1.x? Upgrade to 2.x first: 2.0 switched every user reference in the SDK (userResolver, useUser, labelFor, member operations) to your external_id. The 2.0 notes are in each package's CHANGELOG.md.

1. `@poolse/react-native-calls` is now `@poolse/native`

The package carries calls and chat notifications, so it was renamed. The API and the native module are the same.

- import * as calls from '@poolse/react-native-calls';
+ import * as calls from '@poolse/native';

In app.json:

  "plugins": [
    "expo-notifications",
-   ["@poolse/react-native-calls", { "ringback": "./assets/sounds/ringback.mp3" }]
+   ["@poolse/native", { "ringback": "./assets/sounds/ringback.mp3" }]
  ]

Then run npx expo prebuild --clean (with Node 20.19 or newer).

If your app still has copies of the old per-app config plugins (withNativeCallMedia, withCallDelegate, withLockscreenCalls, withPictureInPicture, withRingback), delete them; the one @poolse/native plugin does their work. Its options are listed under Config plugin.

2. The JavaScript calling path is gone

These were removed during 2.x and don't exist in 3.x:

Removed	Use instead
`poolse.realtime.calls`, `useCalls`, `useVoipCalls`, `<CallScreen>`	On phones, `@poolse/native`: `place`, `answer`, `onCallState`, …
`poolse.realtime.voice`, `useVoiceRoom`, `<VoiceRoomBar>`	Rooms: `startRoom` from `@poolse/native` on phones; on the web, `useRoom` with `<RoomJoinBar>` and `<RoomStage>`, or `poolse.rooms` and `poolse.call` without React
`poolse.iceServers`, `GET /v1/ice-servers`	Nothing. Media goes through the SFU, which handles connectivity when you join.
`<CallProvider>`, `useCallInvite` (react-ui)	The web joins rooms rather than receiving rings. To ring members' phones from the web, use `poolse.rooms.ring` or `useRoom().join(media, { ring: true })`.
`react-native-webrtc`, `react-native-callkeep`, `react-native-voip-push-notification`, `react-native-incall-manager`	Remove them from your app; `@poolse/native` does their work natively.

Web rooms need livekit-client in your app, passed to useRoom or poolse.call as { livekit }.

3. New licence

From 3.0.0 the packages are under the poolse SDK License. Each package also includes it as LICENSE. Versions before 3.0.0 remain under MIT.

4. Changes in 3.1

No code changes are needed, but behaviour improves:

realtime.pause() and realtime.resume() are new in @poolse/sdk. They close and reopen the socket while keeping every channel and listener. See Realtime.
useMessages and useConversations reload from REST after a reconnect, so messages sent while the socket was down appear without a manual refetch(). See Reconnects.
useAppStateLifecycle (React Native) now pauses the socket when the app goes to the background and resumes it when it returns. In 3.0 it called disconnect(), which destroyed every channel, so mounted hooks stopped receiving events until they remounted. It also no longer reacts to the iOS inactive state. Make sure you call it inside <PoolseProvider>.
@poolse/native declares react as a peer dependency.
UserChannel.onRingEnded and UserChannel.onCallFinished let an app pass call:ring_ended and call:finished to @poolse/native. If you reached them through the internal _channel(), switch to these. See UserChannel.
ConversationChannel.onClosed fires when the server removes you from a conversation. The closed handle is dropped, so realtime.conversation(id) joins afresh afterwards.
Token refresh after a refused handshake. When the server refuses the socket (for example because its token was revoked), the SDK fetches a new token from getToken, at most every 30 seconds.
useMessages, useConversations and useLiveCall no longer reload a second time on the socket's first connect.
@poolse/react-native's AttachmentPicker declares the size of the bytes it uploads, which the server now checks at send time.

5. Server features you can use

Call webhooks: call.started, call.answered, call.finished. See Webhook events.
Call history: GET /v1/calls (your backend), GET /v1/me/calls (the signed-in user's) and GET /v1/conversations/:id/calls. See Call history.
Per-workspace call limits on the dashboard's Calls page. A live call carries video_allowed and max_participants; hide your camera button when video isn't allowed.

Older versions

Every version before 3.0.0 is deprecated on npm and gets no fixes.