@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 +159 -159
- package/LICENSE +21 -21
- package/README.md +397 -395
- package/dist/index.cjs +590 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +337 -3
- package/dist/index.d.ts +337 -3
- package/dist/index.js +587 -2
- package/dist/index.js.map +1 -1
- package/package.json +28 -16
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.
|