@poolse/sdk 2.1.5 → 2.2.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,159 @@
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.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.
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.