@poolse/sdk 2.21.0 → 2.23.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/dist/index.d.cts CHANGED
@@ -11,6 +11,23 @@ interface Me {
11
11
  is_blocked: boolean;
12
12
  inserted_at: IsoDateTime;
13
13
  updated_at: IsoDateTime;
14
+ /** Where read receipts stand for this user. Absent on older servers (treat as on). */
15
+ read_receipts?: ReadReceiptsState;
16
+ }
17
+ /**
18
+ * The workspace's read-receipt setting, as it applies to one user.
19
+ * `visible: false` means the app shows no check marks at all — the
20
+ * server withholds other members' read state anyway.
21
+ */
22
+ interface ReadReceiptsState {
23
+ /** `on`: everyone sees them; `off`: nobody; `user`: each user decides (reciprocal). */
24
+ mode: 'on' | 'off' | 'user';
25
+ /** Whether others see when this user reads. */
26
+ shared: boolean;
27
+ /** True only in `user` mode — the app may offer a switch (`me.update`). */
28
+ can_change: boolean;
29
+ /** Whether this user sees other people's read state. */
30
+ visible: boolean;
14
31
  }
15
32
  type ConversationType = 'direct' | 'group';
16
33
  interface Conversation {
@@ -828,6 +845,75 @@ declare class TokenCache {
828
845
  private fetchAndStore;
829
846
  }
830
847
 
848
+ type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
849
+ interface RequestOptions {
850
+ method: HttpMethod;
851
+ path: string;
852
+ /** JSON-serialisable body for non-GETs. Omit for GET/DELETE. */
853
+ body?: unknown;
854
+ /** Query string params; values are stringified, nullish entries dropped. */
855
+ query?: Record<string, string | number | boolean | null | undefined>;
856
+ /**
857
+ * Idempotency-Key override. Defaults to a fresh UUID for non-GETs.
858
+ * Pass `null` to deliberately omit the header (e.g. when the caller's
859
+ * own retry logic supplies a deterministic one).
860
+ */
861
+ idempotencyKey?: string | null;
862
+ /**
863
+ * Per-request override for total retry budget. Defaults to
864
+ * `config.maxRetries`.
865
+ */
866
+ maxRetries?: number;
867
+ /** AbortSignal for caller-driven cancellation. */
868
+ signal?: AbortSignal;
869
+ }
870
+ declare class RestClient {
871
+ private readonly config;
872
+ private readonly tokenCache;
873
+ constructor(config: ResolvedConfig, tokenCache: TokenCache);
874
+ request<T>(opts: RequestOptions): Promise<T>;
875
+ private buildUrl;
876
+ private buildHeaders;
877
+ private resolveIdempotencyKey;
878
+ private backoffDelay;
879
+ }
880
+
881
+ /** A member as a live call names them. */
882
+ interface LiveCallMember {
883
+ user_id: string;
884
+ external_id: string | null;
885
+ display_name: string | null;
886
+ }
887
+ /**
888
+ * The call running on a conversation right now (CONTRACT.md §4.2's
889
+ * CallSummary). `participants` is who is in the room at this moment.
890
+ */
891
+ interface LiveCall {
892
+ id: string;
893
+ conversation_id: string;
894
+ conversation_name: string | null;
895
+ media: 'audio' | 'video';
896
+ state: 'live' | 'finished';
897
+ started_by: LiveCallMember;
898
+ started_at: string | null;
899
+ ended_at: string | null;
900
+ participants: LiveCallMember[];
901
+ /** Callee user id → `ringing` | `answered` | `declined`. */
902
+ ring_states: Record<string, 'ringing' | 'answered' | 'declined'>;
903
+ }
904
+ /**
905
+ * `/v1/conversations/:id/call` — whether a call is running on a
906
+ * conversation, for a "Call in progress · Join" banner. Live changes
907
+ * arrive on the conversation channel (`onCallStarted`,
908
+ * `onCallParticipants`, `onCallFinished`); this is the read on open.
909
+ */
910
+ declare class LiveCallsResource {
911
+ private readonly client;
912
+ constructor(client: RestClient);
913
+ /** GET /v1/conversations/:conversationId/call — `null` when no call is live. */
914
+ get(conversationId: string, signal?: AbortSignal): Promise<LiveCall | null>;
915
+ }
916
+
831
917
  /** `message:new` / `message:updated` push payloads. */
832
918
  type MessageNewEvent = Message;
833
919
  type MessageUpdatedEvent = Message;
@@ -863,6 +949,27 @@ interface MemberReadEvent {
863
949
  last_read_message_id: Uuid;
864
950
  last_read_at: string;
865
951
  }
952
+ /** `call:started` — a call went live on the conversation. */
953
+ interface CallStartedEvent {
954
+ cv: number;
955
+ call: LiveCall;
956
+ }
957
+ /** `call:participants` — who is in the live call's room right now (user ids). */
958
+ interface CallParticipantsEvent {
959
+ cv: number;
960
+ call_id: string;
961
+ participants: Uuid[];
962
+ }
963
+ /** `call:finished` — the call is over for everyone. */
964
+ interface CallFinishedEvent {
965
+ cv: number;
966
+ call_id: string;
967
+ ended_at?: string;
968
+ duration_ms?: number;
969
+ joined_user_ids?: Uuid[];
970
+ /** `finished` | `declined_all` | `no_answer` | `cancelled`. */
971
+ reason?: string;
972
+ }
866
973
  /** Per-user mention push on the `user:<id>` channel. */
867
974
  interface MentionEvent {
868
975
  message_id: Uuid;
@@ -1030,6 +1137,12 @@ declare class ConversationChannel {
1030
1137
  * sender's read-receipt glyph from "sent" to "read" in real time.
1031
1138
  */
1032
1139
  onMemberRead(fn: (evt: MemberReadEvent) => void): Unsubscribe$1;
1140
+ /** A call went live on this conversation (`call:started`). */
1141
+ onCallStarted(fn: (evt: CallStartedEvent) => void): Unsubscribe$1;
1142
+ /** Someone joined or left the live call (`call:participants`): user ids in the room now. */
1143
+ onCallParticipants(fn: (evt: CallParticipantsEvent) => void): Unsubscribe$1;
1144
+ /** The call is over for everyone (`call:finished`). */
1145
+ onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
1033
1146
  onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe$1;
1034
1147
  onPresenceDiff(fn: (diff: PresenceSnapshot) => void): Unsubscribe$1;
1035
1148
  /** Current presence snapshot for sync access — usually used in tests. */
@@ -1086,39 +1199,6 @@ declare class UserChannel {
1086
1199
  _destroy(): void;
1087
1200
  }
1088
1201
 
1089
- type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
1090
- interface RequestOptions {
1091
- method: HttpMethod;
1092
- path: string;
1093
- /** JSON-serialisable body for non-GETs. Omit for GET/DELETE. */
1094
- body?: unknown;
1095
- /** Query string params; values are stringified, nullish entries dropped. */
1096
- query?: Record<string, string | number | boolean | null | undefined>;
1097
- /**
1098
- * Idempotency-Key override. Defaults to a fresh UUID for non-GETs.
1099
- * Pass `null` to deliberately omit the header (e.g. when the caller's
1100
- * own retry logic supplies a deterministic one).
1101
- */
1102
- idempotencyKey?: string | null;
1103
- /**
1104
- * Per-request override for total retry budget. Defaults to
1105
- * `config.maxRetries`.
1106
- */
1107
- maxRetries?: number;
1108
- /** AbortSignal for caller-driven cancellation. */
1109
- signal?: AbortSignal;
1110
- }
1111
- declare class RestClient {
1112
- private readonly config;
1113
- private readonly tokenCache;
1114
- constructor(config: ResolvedConfig, tokenCache: TokenCache);
1115
- request<T>(opts: RequestOptions): Promise<T>;
1116
- private buildUrl;
1117
- private buildHeaders;
1118
- private resolveIdempotencyKey;
1119
- private backoffDelay;
1120
- }
1121
-
1122
1202
  /** Input accepted by {@link AttachmentsResource.upload}. */
1123
1203
  interface AttachmentUploadInput {
1124
1204
  /**
@@ -1341,16 +1421,25 @@ type DevicePlatform = 'ios' | 'android';
1341
1421
  * versa — so a debug build must say `sandbox` or its pushes vanish.
1342
1422
  */
1343
1423
  type DeviceEnvironment = 'production' | 'sandbox';
1424
+ /**
1425
+ * iOS only — which of a phone's two tokens this is. `voip`: the PushKit
1426
+ * token, which only ever carries an incoming call. `alert`: the regular
1427
+ * APNs token, for notifications such as a missed call. Register both.
1428
+ * Android's one FCM token carries everything; leave `kind` out there.
1429
+ */
1430
+ type DeviceKind = 'voip' | 'alert';
1344
1431
  interface RegisterDeviceRequest {
1345
1432
  /**
1346
- * On iOS this MUST be the **PushKit VoIP token**, not the regular
1347
- * APNs token. Apple issues them separately and a VoIP push aimed at a
1348
- * normal token is discarded without an error.
1433
+ * On iOS, the PushKit VoIP token (`kind: 'voip'`, the default) or the
1434
+ * regular APNs token (`kind: 'alert'`). Apple issues them separately
1435
+ * and a push aimed at the wrong one is discarded without an error.
1349
1436
  */
1350
1437
  token: string;
1351
1438
  platform: DevicePlatform;
1352
1439
  /** Defaults to `production` server-side. */
1353
1440
  environment?: DeviceEnvironment;
1441
+ /** iOS: defaults to `voip`. */
1442
+ kind?: DeviceKind;
1354
1443
  }
1355
1444
  /** A registered device, minus the token itself. */
1356
1445
  interface Device {
@@ -1359,6 +1448,7 @@ interface Device {
1359
1448
  user_id: string;
1360
1449
  platform: DevicePlatform;
1361
1450
  environment: DeviceEnvironment;
1451
+ kind: DeviceKind;
1362
1452
  last_registered_at: string | null;
1363
1453
  inserted_at: string;
1364
1454
  updated_at: string;
@@ -1390,12 +1480,36 @@ declare class DevicesResource {
1390
1480
  unregister(token: string, signal?: AbortSignal): Promise<void>;
1391
1481
  }
1392
1482
 
1393
- /** `/v1/me` — the End-User identity behind the presented JWT. */
1483
+ interface UpdateMeRequest {
1484
+ /**
1485
+ * Whether others see when this user reads their messages. Accepted
1486
+ * only while the workspace lets users decide (`read_receipts.can_change`);
1487
+ * otherwise the server answers 409 `read_receipts_fixed`. Reciprocal:
1488
+ * turning it off also hides other people's.
1489
+ */
1490
+ read_receipts?: boolean;
1491
+ }
1492
+ /**
1493
+ * `/v1/me` — the End-User identity behind the presented JWT.
1494
+ *
1495
+ * Keeps the last-known user so every screen agrees: a change made
1496
+ * through `update` (say, turning read receipts off) reaches every
1497
+ * `onChange` subscriber at once instead of waiting for a remount.
1498
+ */
1394
1499
  declare class MeResource {
1395
1500
  private readonly client;
1501
+ private current;
1502
+ private readonly listeners;
1396
1503
  constructor(client: RestClient);
1397
1504
  /** GET /v1/me */
1398
1505
  show(signal?: AbortSignal): Promise<Me>;
1506
+ /** PATCH /v1/me — the user's own preferences. */
1507
+ update(body: UpdateMeRequest, signal?: AbortSignal): Promise<Me>;
1508
+ /** The last user `show` / `update` returned, or null before the first. */
1509
+ peek(): Me | null;
1510
+ /** Called with the user whenever `show` or `update` returns a new one. */
1511
+ onChange(fn: (me: Me) => void): () => void;
1512
+ private set;
1399
1513
  }
1400
1514
 
1401
1515
  type Listener = () => void;
@@ -1944,6 +2058,8 @@ declare class Poolse {
1944
2058
  readonly iceServers: IceServersResource;
1945
2059
  /** SFU credentials for a call's media — see `CallTokensResource`. */
1946
2060
  readonly callTokens: CallTokensResource;
2061
+ /** Whether a call is running on a conversation — for a Join banner. */
2062
+ readonly liveCalls: LiveCallsResource;
1947
2063
  private readonly resolved;
1948
2064
  private readonly tokenCache;
1949
2065
  constructor(config: PoolseConfig);
@@ -2025,9 +2141,13 @@ declare class AuthError extends ApiError {
2025
2141
  declare function isWebRtcAvailable(): boolean;
2026
2142
  declare function createBrowserWebRtcAdapter(): WebRtcAdapter;
2027
2143
 
2028
- declare const version = "2.20.0";
2144
+ declare const version = "2.23.0";
2029
2145
 
2030
2146
  type CallLogMedia = 'audio' | 'video';
2147
+ /** What became of one person a call involved (the caller excluded). */
2148
+ type CallParticipantStatus = 'joined' | 'declined' | 'busy' | 'missed';
2149
+ /** Why a call ended, as the server recorded it. */
2150
+ type CallEndReason = 'finished' | 'declined_all' | 'no_answer' | 'cancelled';
2031
2151
  /** A completed (answered or unanswered) call. */
2032
2152
  interface CallLogEntry {
2033
2153
  kind: 'call';
@@ -2036,6 +2156,19 @@ interface CallLogEntry {
2036
2156
  /** Talk time in ms; `null` when nobody answered. */
2037
2157
  durationMs: number | null;
2038
2158
  joinedUserIds: Uuid[];
2159
+ /** `2` for the one-record-per-call shape; `1` for older history. */
2160
+ version: 1 | 2;
2161
+ /** Who placed the call. `null` on v1 records. */
2162
+ callerUserId: Uuid | null;
2163
+ /** Everyone else the call involved, with their outcome. Empty on v1. */
2164
+ participants: Array<{
2165
+ userId: Uuid;
2166
+ status: CallParticipantStatus;
2167
+ }>;
2168
+ endReason: CallEndReason | null;
2169
+ /** Epoch ms; `null` on v1 records. */
2170
+ startedAt: number | null;
2171
+ endedAt: number | null;
2039
2172
  }
2040
2173
  /** Per-callee "you missed this call" marker. */
2041
2174
  interface CallMissedEntry {
@@ -2069,18 +2202,25 @@ declare function formatCallDuration(ms: number): string;
2069
2202
  /** Render-ready description of a call log for one viewer. */
2070
2203
  interface CallLogDisplay {
2071
2204
  media: CallLogMedia;
2072
- /** "Voice call" / "Video call" / "Missed call". */
2205
+ /** "Outgoing voice call", "Missed video call", "Group voice call"… */
2073
2206
  title: string;
2074
- /** "3:12" when answered, "No answer" when not, null for missed markers. */
2207
+ /** "3:12" when answered; "No answer", "Declined", "You declined"…; null when the title says it all. */
2075
2208
  detail: string | null;
2076
- /** True for the viewer's own missed-call marker — render in the error tone. */
2209
+ /** The viewer missed this call — render in the error tone. */
2077
2210
  missed: boolean;
2078
2211
  /** Short one-line form for list previews ("Video call · 3:12"). */
2079
2212
  summary: string;
2213
+ /** `outgoing` when the viewer placed the call, `incoming` when someone called them, else null. */
2214
+ direction: 'outgoing' | 'incoming' | null;
2215
+ /**
2216
+ * Worth offering "Call back": the viewer missed or declined it, or
2217
+ * placed it and nobody picked up.
2218
+ */
2219
+ callBack: boolean;
2080
2220
  }
2081
2221
  /**
2082
2222
  * Turn a call log into display copy for `currentUserId`. Returns null
2083
- * when the entry should be hidden for this viewer (a `call_missed`
2223
+ * when the entry should be hidden for this viewer (a v1 `call_missed`
2084
2224
  * marker addressed to someone else).
2085
2225
  */
2086
2226
  declare function describeCallLog(log: CallLog, currentUserId: string | null): CallLogDisplay | null;
@@ -2111,4 +2251,4 @@ declare function formatCallLogPreview(preview: string | null | undefined, curren
2111
2251
 
2112
2252
  declare function safeUuid(): string;
2113
2253
 
2114
- export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, type AttachmentProgressEvent, type AttachmentStatus, type AttachmentUploadInput, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsResource, AuthError, type CallAccepted, type CallBusy, type CallCancelled, type CallConnection, type CallDeclined, type CallDevice, type CallDeviceKind, type CallEnded, type CallLog, type CallLogDisplay, type CallLogEntry, type CallLogMedia, type CallMedia, type CallMissedEntry, type CallParticipant, CallRoom, type CallRoomOptions, type CallRoomStatus, CallTokensResource, CallsResource, type CameraFacing, type CheckedLiveKitModule, type Conversation, ConversationChannel, type ConversationCreateRequest, type ConversationCreatedEvent, ConversationHandle, type ConversationList, ConversationMessages, type ConversationType, type ConversationUpdateRequest, type ConversationUpdatedEvent, ConversationsResource, type Device, type DeviceEnvironment, type DevicePlatform, DevicesResource, type ErrorEnvelope, type IceServerResponse, IceServersResource, type IncomingCall, type IsoDateTime, type LiveKitLocalVideoTrack, type LiveKitModule, type LiveKitParticipant, type LiveKitPublication, type LiveKitRoomHandle, type LiveKitTrack, type LiveKitTrackReference, type Me, MeResource, type MemberReadEvent, type MemberRole, type Membership, type MembershipCreateRequest, type MembershipList, type MentionEvent, type Message, type MessageCreateRequest, type MessageDeletedEvent, MessageHandle, type MessageList, type MessageNewEvent, type MessageType, type MessageUpdateRequest, type MessageUpdatedEvent, MessagesResource, NetworkError, type OutgoingCall, POOLSE_API_URL, Poolse, type PoolseConfig, PoolseError, PoolseRealtime, type PoolseUserProfile, type PresenceSnapshot, type QuotedMessagePreview, RateLimitedError, type ReactionEvent, type ReactionRequest, type ReadRequest, type RealtimeStatus, type RegisterDeviceRequest, type TypingEvent, type Unsubscribe$1 as Unsubscribe, UserChannel, UsersResource, type Uuid, type VoiceCandidate, type VoiceDescription, type VoiceIceServer, type VoiceParticipant, type VoicePeerConnection, VoiceRoom, type VoiceRoomOptions, type VoiceStatus, type VoiceStream, type VoiceTrack, type WebRtcAdapter, callLogDisplayFor, createBrowserWebRtcAdapter, describeCallLog, formatCallDuration, formatCallLogPreview, isCallLogMessage, isMessageVisibleTo, isWebRtcAvailable, parseCallLog, parseCallLogBody, safeUuid, version };
2254
+ export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, type AttachmentProgressEvent, type AttachmentStatus, type AttachmentUploadInput, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsResource, AuthError, type CallAccepted, type CallBusy, type CallCancelled, type CallConnection, type CallDeclined, type CallDevice, type CallDeviceKind, type CallEndReason, type CallEnded, type CallFinishedEvent, type CallLog, type CallLogDisplay, type CallLogEntry, type CallLogMedia, type CallMedia, type CallMissedEntry, type CallParticipant, type CallParticipantStatus, type CallParticipantsEvent, CallRoom, type CallRoomOptions, type CallRoomStatus, type CallStartedEvent, CallTokensResource, CallsResource, type CameraFacing, type CheckedLiveKitModule, type Conversation, ConversationChannel, type ConversationCreateRequest, type ConversationCreatedEvent, ConversationHandle, type ConversationList, ConversationMessages, type ConversationType, type ConversationUpdateRequest, type ConversationUpdatedEvent, ConversationsResource, type Device, type DeviceEnvironment, type DeviceKind, type DevicePlatform, DevicesResource, type ErrorEnvelope, type IceServerResponse, IceServersResource, type IncomingCall, type IsoDateTime, type LiveCall, type LiveCallMember, LiveCallsResource, type LiveKitLocalVideoTrack, type LiveKitModule, type LiveKitParticipant, type LiveKitPublication, type LiveKitRoomHandle, type LiveKitTrack, type LiveKitTrackReference, type Me, MeResource, type MemberReadEvent, type MemberRole, type Membership, type MembershipCreateRequest, type MembershipList, type MentionEvent, type Message, type MessageCreateRequest, type MessageDeletedEvent, MessageHandle, type MessageList, type MessageNewEvent, type MessageType, type MessageUpdateRequest, type MessageUpdatedEvent, MessagesResource, NetworkError, type OutgoingCall, POOLSE_API_URL, Poolse, type PoolseConfig, PoolseError, PoolseRealtime, type PoolseUserProfile, type PresenceSnapshot, type QuotedMessagePreview, RateLimitedError, type ReactionEvent, type ReactionRequest, type ReadReceiptsState, type ReadRequest, type RealtimeStatus, type RegisterDeviceRequest, type TypingEvent, type Unsubscribe$1 as Unsubscribe, type UpdateMeRequest, UserChannel, UsersResource, type Uuid, type VoiceCandidate, type VoiceDescription, type VoiceIceServer, type VoiceParticipant, type VoicePeerConnection, VoiceRoom, type VoiceRoomOptions, type VoiceStatus, type VoiceStream, type VoiceTrack, type WebRtcAdapter, callLogDisplayFor, createBrowserWebRtcAdapter, describeCallLog, formatCallDuration, formatCallLogPreview, isCallLogMessage, isMessageVisibleTo, isWebRtcAvailable, parseCallLog, parseCallLogBody, safeUuid, version };
package/dist/index.d.ts CHANGED
@@ -11,6 +11,23 @@ interface Me {
11
11
  is_blocked: boolean;
12
12
  inserted_at: IsoDateTime;
13
13
  updated_at: IsoDateTime;
14
+ /** Where read receipts stand for this user. Absent on older servers (treat as on). */
15
+ read_receipts?: ReadReceiptsState;
16
+ }
17
+ /**
18
+ * The workspace's read-receipt setting, as it applies to one user.
19
+ * `visible: false` means the app shows no check marks at all — the
20
+ * server withholds other members' read state anyway.
21
+ */
22
+ interface ReadReceiptsState {
23
+ /** `on`: everyone sees them; `off`: nobody; `user`: each user decides (reciprocal). */
24
+ mode: 'on' | 'off' | 'user';
25
+ /** Whether others see when this user reads. */
26
+ shared: boolean;
27
+ /** True only in `user` mode — the app may offer a switch (`me.update`). */
28
+ can_change: boolean;
29
+ /** Whether this user sees other people's read state. */
30
+ visible: boolean;
14
31
  }
15
32
  type ConversationType = 'direct' | 'group';
16
33
  interface Conversation {
@@ -828,6 +845,75 @@ declare class TokenCache {
828
845
  private fetchAndStore;
829
846
  }
830
847
 
848
+ type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
849
+ interface RequestOptions {
850
+ method: HttpMethod;
851
+ path: string;
852
+ /** JSON-serialisable body for non-GETs. Omit for GET/DELETE. */
853
+ body?: unknown;
854
+ /** Query string params; values are stringified, nullish entries dropped. */
855
+ query?: Record<string, string | number | boolean | null | undefined>;
856
+ /**
857
+ * Idempotency-Key override. Defaults to a fresh UUID for non-GETs.
858
+ * Pass `null` to deliberately omit the header (e.g. when the caller's
859
+ * own retry logic supplies a deterministic one).
860
+ */
861
+ idempotencyKey?: string | null;
862
+ /**
863
+ * Per-request override for total retry budget. Defaults to
864
+ * `config.maxRetries`.
865
+ */
866
+ maxRetries?: number;
867
+ /** AbortSignal for caller-driven cancellation. */
868
+ signal?: AbortSignal;
869
+ }
870
+ declare class RestClient {
871
+ private readonly config;
872
+ private readonly tokenCache;
873
+ constructor(config: ResolvedConfig, tokenCache: TokenCache);
874
+ request<T>(opts: RequestOptions): Promise<T>;
875
+ private buildUrl;
876
+ private buildHeaders;
877
+ private resolveIdempotencyKey;
878
+ private backoffDelay;
879
+ }
880
+
881
+ /** A member as a live call names them. */
882
+ interface LiveCallMember {
883
+ user_id: string;
884
+ external_id: string | null;
885
+ display_name: string | null;
886
+ }
887
+ /**
888
+ * The call running on a conversation right now (CONTRACT.md §4.2's
889
+ * CallSummary). `participants` is who is in the room at this moment.
890
+ */
891
+ interface LiveCall {
892
+ id: string;
893
+ conversation_id: string;
894
+ conversation_name: string | null;
895
+ media: 'audio' | 'video';
896
+ state: 'live' | 'finished';
897
+ started_by: LiveCallMember;
898
+ started_at: string | null;
899
+ ended_at: string | null;
900
+ participants: LiveCallMember[];
901
+ /** Callee user id → `ringing` | `answered` | `declined`. */
902
+ ring_states: Record<string, 'ringing' | 'answered' | 'declined'>;
903
+ }
904
+ /**
905
+ * `/v1/conversations/:id/call` — whether a call is running on a
906
+ * conversation, for a "Call in progress · Join" banner. Live changes
907
+ * arrive on the conversation channel (`onCallStarted`,
908
+ * `onCallParticipants`, `onCallFinished`); this is the read on open.
909
+ */
910
+ declare class LiveCallsResource {
911
+ private readonly client;
912
+ constructor(client: RestClient);
913
+ /** GET /v1/conversations/:conversationId/call — `null` when no call is live. */
914
+ get(conversationId: string, signal?: AbortSignal): Promise<LiveCall | null>;
915
+ }
916
+
831
917
  /** `message:new` / `message:updated` push payloads. */
832
918
  type MessageNewEvent = Message;
833
919
  type MessageUpdatedEvent = Message;
@@ -863,6 +949,27 @@ interface MemberReadEvent {
863
949
  last_read_message_id: Uuid;
864
950
  last_read_at: string;
865
951
  }
952
+ /** `call:started` — a call went live on the conversation. */
953
+ interface CallStartedEvent {
954
+ cv: number;
955
+ call: LiveCall;
956
+ }
957
+ /** `call:participants` — who is in the live call's room right now (user ids). */
958
+ interface CallParticipantsEvent {
959
+ cv: number;
960
+ call_id: string;
961
+ participants: Uuid[];
962
+ }
963
+ /** `call:finished` — the call is over for everyone. */
964
+ interface CallFinishedEvent {
965
+ cv: number;
966
+ call_id: string;
967
+ ended_at?: string;
968
+ duration_ms?: number;
969
+ joined_user_ids?: Uuid[];
970
+ /** `finished` | `declined_all` | `no_answer` | `cancelled`. */
971
+ reason?: string;
972
+ }
866
973
  /** Per-user mention push on the `user:<id>` channel. */
867
974
  interface MentionEvent {
868
975
  message_id: Uuid;
@@ -1030,6 +1137,12 @@ declare class ConversationChannel {
1030
1137
  * sender's read-receipt glyph from "sent" to "read" in real time.
1031
1138
  */
1032
1139
  onMemberRead(fn: (evt: MemberReadEvent) => void): Unsubscribe$1;
1140
+ /** A call went live on this conversation (`call:started`). */
1141
+ onCallStarted(fn: (evt: CallStartedEvent) => void): Unsubscribe$1;
1142
+ /** Someone joined or left the live call (`call:participants`): user ids in the room now. */
1143
+ onCallParticipants(fn: (evt: CallParticipantsEvent) => void): Unsubscribe$1;
1144
+ /** The call is over for everyone (`call:finished`). */
1145
+ onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
1033
1146
  onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe$1;
1034
1147
  onPresenceDiff(fn: (diff: PresenceSnapshot) => void): Unsubscribe$1;
1035
1148
  /** Current presence snapshot for sync access — usually used in tests. */
@@ -1086,39 +1199,6 @@ declare class UserChannel {
1086
1199
  _destroy(): void;
1087
1200
  }
1088
1201
 
1089
- type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
1090
- interface RequestOptions {
1091
- method: HttpMethod;
1092
- path: string;
1093
- /** JSON-serialisable body for non-GETs. Omit for GET/DELETE. */
1094
- body?: unknown;
1095
- /** Query string params; values are stringified, nullish entries dropped. */
1096
- query?: Record<string, string | number | boolean | null | undefined>;
1097
- /**
1098
- * Idempotency-Key override. Defaults to a fresh UUID for non-GETs.
1099
- * Pass `null` to deliberately omit the header (e.g. when the caller's
1100
- * own retry logic supplies a deterministic one).
1101
- */
1102
- idempotencyKey?: string | null;
1103
- /**
1104
- * Per-request override for total retry budget. Defaults to
1105
- * `config.maxRetries`.
1106
- */
1107
- maxRetries?: number;
1108
- /** AbortSignal for caller-driven cancellation. */
1109
- signal?: AbortSignal;
1110
- }
1111
- declare class RestClient {
1112
- private readonly config;
1113
- private readonly tokenCache;
1114
- constructor(config: ResolvedConfig, tokenCache: TokenCache);
1115
- request<T>(opts: RequestOptions): Promise<T>;
1116
- private buildUrl;
1117
- private buildHeaders;
1118
- private resolveIdempotencyKey;
1119
- private backoffDelay;
1120
- }
1121
-
1122
1202
  /** Input accepted by {@link AttachmentsResource.upload}. */
1123
1203
  interface AttachmentUploadInput {
1124
1204
  /**
@@ -1341,16 +1421,25 @@ type DevicePlatform = 'ios' | 'android';
1341
1421
  * versa — so a debug build must say `sandbox` or its pushes vanish.
1342
1422
  */
1343
1423
  type DeviceEnvironment = 'production' | 'sandbox';
1424
+ /**
1425
+ * iOS only — which of a phone's two tokens this is. `voip`: the PushKit
1426
+ * token, which only ever carries an incoming call. `alert`: the regular
1427
+ * APNs token, for notifications such as a missed call. Register both.
1428
+ * Android's one FCM token carries everything; leave `kind` out there.
1429
+ */
1430
+ type DeviceKind = 'voip' | 'alert';
1344
1431
  interface RegisterDeviceRequest {
1345
1432
  /**
1346
- * On iOS this MUST be the **PushKit VoIP token**, not the regular
1347
- * APNs token. Apple issues them separately and a VoIP push aimed at a
1348
- * normal token is discarded without an error.
1433
+ * On iOS, the PushKit VoIP token (`kind: 'voip'`, the default) or the
1434
+ * regular APNs token (`kind: 'alert'`). Apple issues them separately
1435
+ * and a push aimed at the wrong one is discarded without an error.
1349
1436
  */
1350
1437
  token: string;
1351
1438
  platform: DevicePlatform;
1352
1439
  /** Defaults to `production` server-side. */
1353
1440
  environment?: DeviceEnvironment;
1441
+ /** iOS: defaults to `voip`. */
1442
+ kind?: DeviceKind;
1354
1443
  }
1355
1444
  /** A registered device, minus the token itself. */
1356
1445
  interface Device {
@@ -1359,6 +1448,7 @@ interface Device {
1359
1448
  user_id: string;
1360
1449
  platform: DevicePlatform;
1361
1450
  environment: DeviceEnvironment;
1451
+ kind: DeviceKind;
1362
1452
  last_registered_at: string | null;
1363
1453
  inserted_at: string;
1364
1454
  updated_at: string;
@@ -1390,12 +1480,36 @@ declare class DevicesResource {
1390
1480
  unregister(token: string, signal?: AbortSignal): Promise<void>;
1391
1481
  }
1392
1482
 
1393
- /** `/v1/me` — the End-User identity behind the presented JWT. */
1483
+ interface UpdateMeRequest {
1484
+ /**
1485
+ * Whether others see when this user reads their messages. Accepted
1486
+ * only while the workspace lets users decide (`read_receipts.can_change`);
1487
+ * otherwise the server answers 409 `read_receipts_fixed`. Reciprocal:
1488
+ * turning it off also hides other people's.
1489
+ */
1490
+ read_receipts?: boolean;
1491
+ }
1492
+ /**
1493
+ * `/v1/me` — the End-User identity behind the presented JWT.
1494
+ *
1495
+ * Keeps the last-known user so every screen agrees: a change made
1496
+ * through `update` (say, turning read receipts off) reaches every
1497
+ * `onChange` subscriber at once instead of waiting for a remount.
1498
+ */
1394
1499
  declare class MeResource {
1395
1500
  private readonly client;
1501
+ private current;
1502
+ private readonly listeners;
1396
1503
  constructor(client: RestClient);
1397
1504
  /** GET /v1/me */
1398
1505
  show(signal?: AbortSignal): Promise<Me>;
1506
+ /** PATCH /v1/me — the user's own preferences. */
1507
+ update(body: UpdateMeRequest, signal?: AbortSignal): Promise<Me>;
1508
+ /** The last user `show` / `update` returned, or null before the first. */
1509
+ peek(): Me | null;
1510
+ /** Called with the user whenever `show` or `update` returns a new one. */
1511
+ onChange(fn: (me: Me) => void): () => void;
1512
+ private set;
1399
1513
  }
1400
1514
 
1401
1515
  type Listener = () => void;
@@ -1944,6 +2058,8 @@ declare class Poolse {
1944
2058
  readonly iceServers: IceServersResource;
1945
2059
  /** SFU credentials for a call's media — see `CallTokensResource`. */
1946
2060
  readonly callTokens: CallTokensResource;
2061
+ /** Whether a call is running on a conversation — for a Join banner. */
2062
+ readonly liveCalls: LiveCallsResource;
1947
2063
  private readonly resolved;
1948
2064
  private readonly tokenCache;
1949
2065
  constructor(config: PoolseConfig);
@@ -2025,9 +2141,13 @@ declare class AuthError extends ApiError {
2025
2141
  declare function isWebRtcAvailable(): boolean;
2026
2142
  declare function createBrowserWebRtcAdapter(): WebRtcAdapter;
2027
2143
 
2028
- declare const version = "2.20.0";
2144
+ declare const version = "2.23.0";
2029
2145
 
2030
2146
  type CallLogMedia = 'audio' | 'video';
2147
+ /** What became of one person a call involved (the caller excluded). */
2148
+ type CallParticipantStatus = 'joined' | 'declined' | 'busy' | 'missed';
2149
+ /** Why a call ended, as the server recorded it. */
2150
+ type CallEndReason = 'finished' | 'declined_all' | 'no_answer' | 'cancelled';
2031
2151
  /** A completed (answered or unanswered) call. */
2032
2152
  interface CallLogEntry {
2033
2153
  kind: 'call';
@@ -2036,6 +2156,19 @@ interface CallLogEntry {
2036
2156
  /** Talk time in ms; `null` when nobody answered. */
2037
2157
  durationMs: number | null;
2038
2158
  joinedUserIds: Uuid[];
2159
+ /** `2` for the one-record-per-call shape; `1` for older history. */
2160
+ version: 1 | 2;
2161
+ /** Who placed the call. `null` on v1 records. */
2162
+ callerUserId: Uuid | null;
2163
+ /** Everyone else the call involved, with their outcome. Empty on v1. */
2164
+ participants: Array<{
2165
+ userId: Uuid;
2166
+ status: CallParticipantStatus;
2167
+ }>;
2168
+ endReason: CallEndReason | null;
2169
+ /** Epoch ms; `null` on v1 records. */
2170
+ startedAt: number | null;
2171
+ endedAt: number | null;
2039
2172
  }
2040
2173
  /** Per-callee "you missed this call" marker. */
2041
2174
  interface CallMissedEntry {
@@ -2069,18 +2202,25 @@ declare function formatCallDuration(ms: number): string;
2069
2202
  /** Render-ready description of a call log for one viewer. */
2070
2203
  interface CallLogDisplay {
2071
2204
  media: CallLogMedia;
2072
- /** "Voice call" / "Video call" / "Missed call". */
2205
+ /** "Outgoing voice call", "Missed video call", "Group voice call"… */
2073
2206
  title: string;
2074
- /** "3:12" when answered, "No answer" when not, null for missed markers. */
2207
+ /** "3:12" when answered; "No answer", "Declined", "You declined"…; null when the title says it all. */
2075
2208
  detail: string | null;
2076
- /** True for the viewer's own missed-call marker — render in the error tone. */
2209
+ /** The viewer missed this call — render in the error tone. */
2077
2210
  missed: boolean;
2078
2211
  /** Short one-line form for list previews ("Video call · 3:12"). */
2079
2212
  summary: string;
2213
+ /** `outgoing` when the viewer placed the call, `incoming` when someone called them, else null. */
2214
+ direction: 'outgoing' | 'incoming' | null;
2215
+ /**
2216
+ * Worth offering "Call back": the viewer missed or declined it, or
2217
+ * placed it and nobody picked up.
2218
+ */
2219
+ callBack: boolean;
2080
2220
  }
2081
2221
  /**
2082
2222
  * Turn a call log into display copy for `currentUserId`. Returns null
2083
- * when the entry should be hidden for this viewer (a `call_missed`
2223
+ * when the entry should be hidden for this viewer (a v1 `call_missed`
2084
2224
  * marker addressed to someone else).
2085
2225
  */
2086
2226
  declare function describeCallLog(log: CallLog, currentUserId: string | null): CallLogDisplay | null;
@@ -2111,4 +2251,4 @@ declare function formatCallLogPreview(preview: string | null | undefined, curren
2111
2251
 
2112
2252
  declare function safeUuid(): string;
2113
2253
 
2114
- export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, type AttachmentProgressEvent, type AttachmentStatus, type AttachmentUploadInput, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsResource, AuthError, type CallAccepted, type CallBusy, type CallCancelled, type CallConnection, type CallDeclined, type CallDevice, type CallDeviceKind, type CallEnded, type CallLog, type CallLogDisplay, type CallLogEntry, type CallLogMedia, type CallMedia, type CallMissedEntry, type CallParticipant, CallRoom, type CallRoomOptions, type CallRoomStatus, CallTokensResource, CallsResource, type CameraFacing, type CheckedLiveKitModule, type Conversation, ConversationChannel, type ConversationCreateRequest, type ConversationCreatedEvent, ConversationHandle, type ConversationList, ConversationMessages, type ConversationType, type ConversationUpdateRequest, type ConversationUpdatedEvent, ConversationsResource, type Device, type DeviceEnvironment, type DevicePlatform, DevicesResource, type ErrorEnvelope, type IceServerResponse, IceServersResource, type IncomingCall, type IsoDateTime, type LiveKitLocalVideoTrack, type LiveKitModule, type LiveKitParticipant, type LiveKitPublication, type LiveKitRoomHandle, type LiveKitTrack, type LiveKitTrackReference, type Me, MeResource, type MemberReadEvent, type MemberRole, type Membership, type MembershipCreateRequest, type MembershipList, type MentionEvent, type Message, type MessageCreateRequest, type MessageDeletedEvent, MessageHandle, type MessageList, type MessageNewEvent, type MessageType, type MessageUpdateRequest, type MessageUpdatedEvent, MessagesResource, NetworkError, type OutgoingCall, POOLSE_API_URL, Poolse, type PoolseConfig, PoolseError, PoolseRealtime, type PoolseUserProfile, type PresenceSnapshot, type QuotedMessagePreview, RateLimitedError, type ReactionEvent, type ReactionRequest, type ReadRequest, type RealtimeStatus, type RegisterDeviceRequest, type TypingEvent, type Unsubscribe$1 as Unsubscribe, UserChannel, UsersResource, type Uuid, type VoiceCandidate, type VoiceDescription, type VoiceIceServer, type VoiceParticipant, type VoicePeerConnection, VoiceRoom, type VoiceRoomOptions, type VoiceStatus, type VoiceStream, type VoiceTrack, type WebRtcAdapter, callLogDisplayFor, createBrowserWebRtcAdapter, describeCallLog, formatCallDuration, formatCallLogPreview, isCallLogMessage, isMessageVisibleTo, isWebRtcAvailable, parseCallLog, parseCallLogBody, safeUuid, version };
2254
+ export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, type AttachmentProgressEvent, type AttachmentStatus, type AttachmentUploadInput, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsResource, AuthError, type CallAccepted, type CallBusy, type CallCancelled, type CallConnection, type CallDeclined, type CallDevice, type CallDeviceKind, type CallEndReason, type CallEnded, type CallFinishedEvent, type CallLog, type CallLogDisplay, type CallLogEntry, type CallLogMedia, type CallMedia, type CallMissedEntry, type CallParticipant, type CallParticipantStatus, type CallParticipantsEvent, CallRoom, type CallRoomOptions, type CallRoomStatus, type CallStartedEvent, CallTokensResource, CallsResource, type CameraFacing, type CheckedLiveKitModule, type Conversation, ConversationChannel, type ConversationCreateRequest, type ConversationCreatedEvent, ConversationHandle, type ConversationList, ConversationMessages, type ConversationType, type ConversationUpdateRequest, type ConversationUpdatedEvent, ConversationsResource, type Device, type DeviceEnvironment, type DeviceKind, type DevicePlatform, DevicesResource, type ErrorEnvelope, type IceServerResponse, IceServersResource, type IncomingCall, type IsoDateTime, type LiveCall, type LiveCallMember, LiveCallsResource, type LiveKitLocalVideoTrack, type LiveKitModule, type LiveKitParticipant, type LiveKitPublication, type LiveKitRoomHandle, type LiveKitTrack, type LiveKitTrackReference, type Me, MeResource, type MemberReadEvent, type MemberRole, type Membership, type MembershipCreateRequest, type MembershipList, type MentionEvent, type Message, type MessageCreateRequest, type MessageDeletedEvent, MessageHandle, type MessageList, type MessageNewEvent, type MessageType, type MessageUpdateRequest, type MessageUpdatedEvent, MessagesResource, NetworkError, type OutgoingCall, POOLSE_API_URL, Poolse, type PoolseConfig, PoolseError, PoolseRealtime, type PoolseUserProfile, type PresenceSnapshot, type QuotedMessagePreview, RateLimitedError, type ReactionEvent, type ReactionRequest, type ReadReceiptsState, type ReadRequest, type RealtimeStatus, type RegisterDeviceRequest, type TypingEvent, type Unsubscribe$1 as Unsubscribe, type UpdateMeRequest, UserChannel, UsersResource, type Uuid, type VoiceCandidate, type VoiceDescription, type VoiceIceServer, type VoiceParticipant, type VoicePeerConnection, VoiceRoom, type VoiceRoomOptions, type VoiceStatus, type VoiceStream, type VoiceTrack, type WebRtcAdapter, callLogDisplayFor, createBrowserWebRtcAdapter, describeCallLog, formatCallDuration, formatCallLogPreview, isCallLogMessage, isMessageVisibleTo, isWebRtcAvailable, parseCallLog, parseCallLogBody, safeUuid, version };