@poolse/sdk 2.12.1 → 2.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,159 +1,180 @@
1
- # Changelog
2
-
3
- All notable changes to `@poolse/sdk` are documented here. Format follows
4
- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
5
- [semver](https://semver.org).
6
-
7
- ## [2.0.0] — 2026-06-03
8
-
9
- Lockstep release with `@poolse/react@2.0.0` and `@poolse/react-ui@2.0.0`.
10
- Single load-bearing change: the SDK no longer surfaces poolse-internal
11
- user uuids in identity-shaped APIs — everything is keyed by the
12
- tenant's own `external_id` instead.
13
-
14
- ### Breaking
15
-
16
- - **`PoolseConfig.userResolver` signature changes.** Was
17
- `(userId: string) => UserProfile | null`; now
18
- `(externalId: string) => UserProfile | null`. Your resolver receives
19
- YOUR user id (the same string you pass when minting JWTs and as
20
- `member_external_ids`), so no `poolse_user_id` column is needed.
21
- - **`Message.sender_external_id`** added (string | null, required on
22
- every wire payload that carries a sender).
23
- - **`Membership.external_id`** added (string, required).
24
- - **`QuotedMessagePreview.sender_external_id`** added.
25
- - **`TypingEvent.external_id`** added — `useTyping` returns
26
- `Set<externalId>` instead of `Set<userId>`.
27
- - **`UsersResource.{peek, get, subscribe, invalidate}`** all keyed by
28
- `externalId` (was `userId`). Same semantics; same caching.
29
-
30
- ### Migration
31
-
32
- See `MIGRATING.md` at the repo root. For most apps it's a rename of
33
- the resolver argument plus deleting the `poolse_user_id` column if
34
- you stored one.
35
-
36
- ### Backend coupling
37
-
38
- Pairs with the `poolse-server` change that:
39
-
40
- - lazy-provisions unknown `external_id`s referenced in
41
- `POST /v1/conversations` (`member_external_ids`) and
42
- `POST /v1/conversations/:id/members` (`external_ids`), abuse-capped
43
- at 50/hour per JWT,
44
- - emits `sender_external_id` / `external_id` on every user-shaped
45
- wire payload (REST, webhook, realtime).
46
-
47
- Self-hosted `@poolse/sdk@2.0.0` against an older backend will get
48
- `sender_external_id: null` everywhere — degraded display, but no crash.
49
-
50
- ## [1.1.0] — 2026-06-02
51
-
52
- Lockstep release with `@poolse/react@1.1.0` and `@poolse/react-ui@1.1.0`.
53
- No API changes in `@poolse/sdk` itself — version bumped to keep the
54
- three packages in sync, so customers can pin one version across the
55
- whole client surface.
56
-
57
- ### Changed
58
-
59
- - README rewritten as a full reference: authentication model, every
60
- resource and method with its HTTP path, the realtime channel event
61
- catalogue with payload shapes, token caching semantics, idempotency
62
- conventions, retry behaviour, and the typed error hierarchy.
63
- - Repo-wide prettier formatting fixes (whitespace only).
64
-
65
- ## [1.0.0-beta.0] — 2026-06-01
66
-
67
- First beta of the stable API surface. Consolidates everything from
68
- the 0.2.x line (realtime read receipts, per-conv unread counts,
69
- thread + reply_count, quote replies, MemberReadEvent, attachment
70
- preloads, the AbortError preservation fix). No breaking API changes
71
- relative to `0.2.0-alpha.7` — only a version promotion + diagnostic
72
- log cleanup.
73
-
74
- ## [0.2.0] — 2026-06-01
75
-
76
- ### Added — quote replies (WhatsApp-style)
77
-
78
- - `Message.quoted_message_id?: Uuid | null` + `Message.quoted_message?:
79
- QuotedMessagePreview` — server preloads on REST list + realtime
80
- broadcast so the SDK can render the inline quote card without a
81
- per-message lookup. Body truncated to ~200 chars server-side.
82
- - `MessageCreateRequest.quoted_message_id?: Uuid` — quote a message
83
- on send. Stays in the main feed (independent of `reply_to_id`,
84
- which still drives thread promotion).
85
- - New `QuotedMessagePreview` type exported from the package root.
86
-
87
- ### Added
88
-
89
- - `Message.reply_count?: number` — number of replies in the thread
90
- rooted at this message. Populated by REST list; defaults to 0 over
91
- realtime (a brand-new message can't have replies yet). Drives the
92
- thread pill in `<MessageRow>` and increments locally in
93
- `useMessages` when a reply lands.
94
-
95
- ### Fixed
96
-
97
- - `RestClient.request` no longer wraps `AbortError` as a `NetworkError`
98
- — it now re-throws the `DOMException` as-is. The previous wrapping
99
- defeated abort detection in `useMembers` / `useConversation` /
100
- `useAttachmentUrl`, so a StrictMode-induced re-mount or a fast
101
- conversation switch surfaced "Failed to load …" UI even though the
102
- underlying request was cancelled, not failed.
103
-
104
- ### Added
105
-
106
- - `MemberReadEvent` — wire shape for the server's `member:read` push,
107
- emitted on the conversation channel whenever any member advances
108
- their read cursor.
109
- - `ConversationChannel.onMemberRead(fn)` — subscribe to read-cursor
110
- advances. The companion `useMembers` hook wires this so the sender's
111
- read-receipt glyph flips from "sent" to "read" without a refetch.
112
- - `Conversation.unread_count?: number` — populated by
113
- `chat.conversations.list()`. Diff between `last_sequence` and the
114
- caller's `last_read_message_id`'s sequence; powers sidebar badges.
115
-
116
- ### Changed
117
-
118
- - `PoolseConfig.apiUrl` is now optional. Defaults to the hosted
119
- endpoint at `https://api.poolse.dev`. Self-hosted / staging
120
- deployments still override via the field.
121
- - Exports new `POOLSE_API_URL` constant for callers who want to
122
- reference the default explicitly.
123
-
124
- ### Added
125
-
126
- - `Message.attachments?: Attachment[]` — server populates on send +
127
- realtime broadcast for messages with linked attachments.
128
- - `MessageCreateRequest.attachment_ids?: Uuid[]` — send a message
129
- with one or more previously-uploaded attachments.
130
- - `MessageCreateRequest.body` is now optional (was required) — a
131
- message with attachments and no body is valid.
132
-
133
- ## [0.1.0] — 2026-06-01
134
-
135
- First publishable release.
136
-
137
- ### Added
138
-
139
- - `Poolse` client class with REST resources: `me`, `conversations`
140
- (list/create/get/update + members), `messages` (send/list/mark-read +
141
- edit/delete/replies/reactions on per-id handle), `attachments`
142
- (presigned upload + download + delete).
143
- - `RestClient` low-level wrapper:
144
- - Bearer JWT via `config.getToken` (async or sync; nullable for
145
- deliberate unauthenticated calls).
146
- - Auto-generated `Idempotency-Key` for non-GET requests
147
- (`crypto.randomUUID()` by default; overrideable).
148
- - Exponential backoff with full jitter for transient failures.
149
- - `Retry-After` header honoured on 429.
150
- - Network errors retried (except `AbortError`).
151
- - 401 → `AuthError`, 429 → `RateLimitedError`, other 4xx/5xx → `ApiError`,
152
- network failures → `NetworkError`. All `instanceof`-checkable.
153
- - Initial scaffold: TypeScript, dual ESM+CJS build via tsup, vitest,
154
- eslint, prettier, Node 22 Docker dev environment.
155
-
156
- ## [0.0.1] — scaffolding only
157
-
158
- Placeholder release. The real `Poolse` client class (REST + Channels +
159
- offline queue) lands in subsequent SDK tasks under Phase 1F.
1
+ # Changelog
2
+
3
+ All notable changes to `@poolse/sdk` are documented here. Format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
5
+ [semver](https://semver.org).
6
+
7
+ ## [2.13.0] — 2026-08-23
8
+
9
+ ### Added
10
+
11
+ - **`CallRoom.onAlone`** — fires when everyone else has left a connected
12
+ call and is not coming back. A peer who hangs up cleanly sends
13
+ `call:hangup`; this covers the case where no signal is ever sent
14
+ because the app was killed, the phone lost signal or the tab was
15
+ closed, and the only evidence is an empty SFU roster. Guarded twice:
16
+ it never fires before somebody else has actually joined (so a caller
17
+ waiting for an answer is safe), and the verdict waits out
18
+ `CallRoomOptions.aloneGraceMs` (default 1500ms) so a simultaneous
19
+ hang-up or a brief reconnect does not read as abandonment.
20
+ - **`CallRoom.switchCamera` / `getFacingMode`** — flips between the front
21
+ and rear cameras by restarting the track under the existing
22
+ publication, so the far side's tile never blanks.
23
+ - **`CallRoomOptions.facing`** — which camera a call opens on. Defaults
24
+ to `'user'`; previously the platform chose, and Android routinely
25
+ chose the rear camera.
26
+ - **`CameraFacing`** and **`LiveKitLocalVideoTrack`** types.
27
+
28
+ ## [2.0.0] — 2026-06-03
29
+
30
+ Lockstep release with `@poolse/react@2.0.0` and `@poolse/react-ui@2.0.0`.
31
+ Single load-bearing change: the SDK no longer surfaces poolse-internal
32
+ user uuids in identity-shaped APIs — everything is keyed by the
33
+ tenant's own `external_id` instead.
34
+
35
+ ### Breaking
36
+
37
+ - **`PoolseConfig.userResolver` signature changes.** Was
38
+ `(userId: string) => UserProfile | null`; now
39
+ `(externalId: string) => UserProfile | null`. Your resolver receives
40
+ YOUR user id (the same string you pass when minting JWTs and as
41
+ `member_external_ids`), so no `poolse_user_id` column is needed.
42
+ - **`Message.sender_external_id`** added (string | null, required on
43
+ every wire payload that carries a sender).
44
+ - **`Membership.external_id`** added (string, required).
45
+ - **`QuotedMessagePreview.sender_external_id`** added.
46
+ - **`TypingEvent.external_id`** added — `useTyping` returns
47
+ `Set<externalId>` instead of `Set<userId>`.
48
+ - **`UsersResource.{peek, get, subscribe, invalidate}`** all keyed by
49
+ `externalId` (was `userId`). Same semantics; same caching.
50
+
51
+ ### Migration
52
+
53
+ See `MIGRATING.md` at the repo root. For most apps it's a rename of
54
+ the resolver argument plus deleting the `poolse_user_id` column if
55
+ you stored one.
56
+
57
+ ### Backend coupling
58
+
59
+ Pairs with the `poolse-server` change that:
60
+
61
+ - lazy-provisions unknown `external_id`s referenced in
62
+ `POST /v1/conversations` (`member_external_ids`) and
63
+ `POST /v1/conversations/:id/members` (`external_ids`), abuse-capped
64
+ at 50/hour per JWT,
65
+ - emits `sender_external_id` / `external_id` on every user-shaped
66
+ wire payload (REST, webhook, realtime).
67
+
68
+ Self-hosted `@poolse/sdk@2.0.0` against an older backend will get
69
+ `sender_external_id: null` everywhere — degraded display, but no crash.
70
+
71
+ ## [1.1.0] — 2026-06-02
72
+
73
+ Lockstep release with `@poolse/react@1.1.0` and `@poolse/react-ui@1.1.0`.
74
+ No API changes in `@poolse/sdk` itself — version bumped to keep the
75
+ three packages in sync, so customers can pin one version across the
76
+ whole client surface.
77
+
78
+ ### Changed
79
+
80
+ - README rewritten as a full reference: authentication model, every
81
+ resource and method with its HTTP path, the realtime channel event
82
+ catalogue with payload shapes, token caching semantics, idempotency
83
+ conventions, retry behaviour, and the typed error hierarchy.
84
+ - Repo-wide prettier formatting fixes (whitespace only).
85
+
86
+ ## [1.0.0-beta.0] — 2026-06-01
87
+
88
+ First beta of the stable API surface. Consolidates everything from
89
+ the 0.2.x line (realtime read receipts, per-conv unread counts,
90
+ thread + reply_count, quote replies, MemberReadEvent, attachment
91
+ preloads, the AbortError preservation fix). No breaking API changes
92
+ relative to `0.2.0-alpha.7` — only a version promotion + diagnostic
93
+ log cleanup.
94
+
95
+ ## [0.2.0] — 2026-06-01
96
+
97
+ ### Added — quote replies (WhatsApp-style)
98
+
99
+ - `Message.quoted_message_id?: Uuid | null` + `Message.quoted_message?:
100
+ QuotedMessagePreview` — server preloads on REST list + realtime
101
+ broadcast so the SDK can render the inline quote card without a
102
+ per-message lookup. Body truncated to ~200 chars server-side.
103
+ - `MessageCreateRequest.quoted_message_id?: Uuid` — quote a message
104
+ on send. Stays in the main feed (independent of `reply_to_id`,
105
+ which still drives thread promotion).
106
+ - New `QuotedMessagePreview` type exported from the package root.
107
+
108
+ ### Added
109
+
110
+ - `Message.reply_count?: number` — number of replies in the thread
111
+ rooted at this message. Populated by REST list; defaults to 0 over
112
+ realtime (a brand-new message can't have replies yet). Drives the
113
+ thread pill in `<MessageRow>` and increments locally in
114
+ `useMessages` when a reply lands.
115
+
116
+ ### Fixed
117
+
118
+ - `RestClient.request` no longer wraps `AbortError` as a `NetworkError`
119
+ — it now re-throws the `DOMException` as-is. The previous wrapping
120
+ defeated abort detection in `useMembers` / `useConversation` /
121
+ `useAttachmentUrl`, so a StrictMode-induced re-mount or a fast
122
+ conversation switch surfaced "Failed to load …" UI even though the
123
+ underlying request was cancelled, not failed.
124
+
125
+ ### Added
126
+
127
+ - `MemberReadEvent` — wire shape for the server's `member:read` push,
128
+ emitted on the conversation channel whenever any member advances
129
+ their read cursor.
130
+ - `ConversationChannel.onMemberRead(fn)` — subscribe to read-cursor
131
+ advances. The companion `useMembers` hook wires this so the sender's
132
+ read-receipt glyph flips from "sent" to "read" without a refetch.
133
+ - `Conversation.unread_count?: number` — populated by
134
+ `chat.conversations.list()`. Diff between `last_sequence` and the
135
+ caller's `last_read_message_id`'s sequence; powers sidebar badges.
136
+
137
+ ### Changed
138
+
139
+ - `PoolseConfig.apiUrl` is now optional. Defaults to the hosted
140
+ endpoint at `https://api.poolse.dev`. Self-hosted / staging
141
+ deployments still override via the field.
142
+ - Exports new `POOLSE_API_URL` constant for callers who want to
143
+ reference the default explicitly.
144
+
145
+ ### Added
146
+
147
+ - `Message.attachments?: Attachment[]` — server populates on send +
148
+ realtime broadcast for messages with linked attachments.
149
+ - `MessageCreateRequest.attachment_ids?: Uuid[]` — send a message
150
+ with one or more previously-uploaded attachments.
151
+ - `MessageCreateRequest.body` is now optional (was required) — a
152
+ message with attachments and no body is valid.
153
+
154
+ ## [0.1.0] — 2026-06-01
155
+
156
+ First publishable release.
157
+
158
+ ### Added
159
+
160
+ - `Poolse` client class with REST resources: `me`, `conversations`
161
+ (list/create/get/update + members), `messages` (send/list/mark-read +
162
+ edit/delete/replies/reactions on per-id handle), `attachments`
163
+ (presigned upload + download + delete).
164
+ - `RestClient` low-level wrapper:
165
+ - Bearer JWT via `config.getToken` (async or sync; nullable for
166
+ deliberate unauthenticated calls).
167
+ - Auto-generated `Idempotency-Key` for non-GET requests
168
+ (`crypto.randomUUID()` by default; overrideable).
169
+ - Exponential backoff with full jitter for transient failures.
170
+ - `Retry-After` header honoured on 429.
171
+ - Network errors retried (except `AbortError`).
172
+ - 401 → `AuthError`, 429 → `RateLimitedError`, other 4xx/5xx → `ApiError`,
173
+ network failures → `NetworkError`. All `instanceof`-checkable.
174
+ - Initial scaffold: TypeScript, dual ESM+CJS build via tsup, vitest,
175
+ eslint, prettier, Node 22 Docker dev environment.
176
+
177
+ ## [0.0.1] — scaffolding only
178
+
179
+ Placeholder release. The real `Poolse` client class (REST + Channels +
180
+ offline queue) lands in subsequent SDK tasks under Phase 1F.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Poolse
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Poolse
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.