@poolse/sdk 2.20.0 → 2.22.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
@@ -828,6 +828,75 @@ declare class TokenCache {
828
828
  private fetchAndStore;
829
829
  }
830
830
 
831
+ type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
832
+ interface RequestOptions {
833
+ method: HttpMethod;
834
+ path: string;
835
+ /** JSON-serialisable body for non-GETs. Omit for GET/DELETE. */
836
+ body?: unknown;
837
+ /** Query string params; values are stringified, nullish entries dropped. */
838
+ query?: Record<string, string | number | boolean | null | undefined>;
839
+ /**
840
+ * Idempotency-Key override. Defaults to a fresh UUID for non-GETs.
841
+ * Pass `null` to deliberately omit the header (e.g. when the caller's
842
+ * own retry logic supplies a deterministic one).
843
+ */
844
+ idempotencyKey?: string | null;
845
+ /**
846
+ * Per-request override for total retry budget. Defaults to
847
+ * `config.maxRetries`.
848
+ */
849
+ maxRetries?: number;
850
+ /** AbortSignal for caller-driven cancellation. */
851
+ signal?: AbortSignal;
852
+ }
853
+ declare class RestClient {
854
+ private readonly config;
855
+ private readonly tokenCache;
856
+ constructor(config: ResolvedConfig, tokenCache: TokenCache);
857
+ request<T>(opts: RequestOptions): Promise<T>;
858
+ private buildUrl;
859
+ private buildHeaders;
860
+ private resolveIdempotencyKey;
861
+ private backoffDelay;
862
+ }
863
+
864
+ /** A member as a live call names them. */
865
+ interface LiveCallMember {
866
+ user_id: string;
867
+ external_id: string | null;
868
+ display_name: string | null;
869
+ }
870
+ /**
871
+ * The call running on a conversation right now (CONTRACT.md §4.2's
872
+ * CallSummary). `participants` is who is in the room at this moment.
873
+ */
874
+ interface LiveCall {
875
+ id: string;
876
+ conversation_id: string;
877
+ conversation_name: string | null;
878
+ media: 'audio' | 'video';
879
+ state: 'live' | 'finished';
880
+ started_by: LiveCallMember;
881
+ started_at: string | null;
882
+ ended_at: string | null;
883
+ participants: LiveCallMember[];
884
+ /** Callee user id → `ringing` | `answered` | `declined`. */
885
+ ring_states: Record<string, 'ringing' | 'answered' | 'declined'>;
886
+ }
887
+ /**
888
+ * `/v1/conversations/:id/call` — whether a call is running on a
889
+ * conversation, for a "Call in progress · Join" banner. Live changes
890
+ * arrive on the conversation channel (`onCallStarted`,
891
+ * `onCallParticipants`, `onCallFinished`); this is the read on open.
892
+ */
893
+ declare class LiveCallsResource {
894
+ private readonly client;
895
+ constructor(client: RestClient);
896
+ /** GET /v1/conversations/:conversationId/call — `null` when no call is live. */
897
+ get(conversationId: string, signal?: AbortSignal): Promise<LiveCall | null>;
898
+ }
899
+
831
900
  /** `message:new` / `message:updated` push payloads. */
832
901
  type MessageNewEvent = Message;
833
902
  type MessageUpdatedEvent = Message;
@@ -863,6 +932,27 @@ interface MemberReadEvent {
863
932
  last_read_message_id: Uuid;
864
933
  last_read_at: string;
865
934
  }
935
+ /** `call:started` — a call went live on the conversation. */
936
+ interface CallStartedEvent {
937
+ cv: number;
938
+ call: LiveCall;
939
+ }
940
+ /** `call:participants` — who is in the live call's room right now (user ids). */
941
+ interface CallParticipantsEvent {
942
+ cv: number;
943
+ call_id: string;
944
+ participants: Uuid[];
945
+ }
946
+ /** `call:finished` — the call is over for everyone. */
947
+ interface CallFinishedEvent {
948
+ cv: number;
949
+ call_id: string;
950
+ ended_at?: string;
951
+ duration_ms?: number;
952
+ joined_user_ids?: Uuid[];
953
+ /** `finished` | `declined_all` | `no_answer` | `cancelled`. */
954
+ reason?: string;
955
+ }
866
956
  /** Per-user mention push on the `user:<id>` channel. */
867
957
  interface MentionEvent {
868
958
  message_id: Uuid;
@@ -1030,6 +1120,12 @@ declare class ConversationChannel {
1030
1120
  * sender's read-receipt glyph from "sent" to "read" in real time.
1031
1121
  */
1032
1122
  onMemberRead(fn: (evt: MemberReadEvent) => void): Unsubscribe$1;
1123
+ /** A call went live on this conversation (`call:started`). */
1124
+ onCallStarted(fn: (evt: CallStartedEvent) => void): Unsubscribe$1;
1125
+ /** Someone joined or left the live call (`call:participants`): user ids in the room now. */
1126
+ onCallParticipants(fn: (evt: CallParticipantsEvent) => void): Unsubscribe$1;
1127
+ /** The call is over for everyone (`call:finished`). */
1128
+ onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
1033
1129
  onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe$1;
1034
1130
  onPresenceDiff(fn: (diff: PresenceSnapshot) => void): Unsubscribe$1;
1035
1131
  /** Current presence snapshot for sync access — usually used in tests. */
@@ -1086,39 +1182,6 @@ declare class UserChannel {
1086
1182
  _destroy(): void;
1087
1183
  }
1088
1184
 
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
1185
  /** Input accepted by {@link AttachmentsResource.upload}. */
1123
1186
  interface AttachmentUploadInput {
1124
1187
  /**
@@ -1341,16 +1404,25 @@ type DevicePlatform = 'ios' | 'android';
1341
1404
  * versa — so a debug build must say `sandbox` or its pushes vanish.
1342
1405
  */
1343
1406
  type DeviceEnvironment = 'production' | 'sandbox';
1407
+ /**
1408
+ * iOS only — which of a phone's two tokens this is. `voip`: the PushKit
1409
+ * token, which only ever carries an incoming call. `alert`: the regular
1410
+ * APNs token, for notifications such as a missed call. Register both.
1411
+ * Android's one FCM token carries everything; leave `kind` out there.
1412
+ */
1413
+ type DeviceKind = 'voip' | 'alert';
1344
1414
  interface RegisterDeviceRequest {
1345
1415
  /**
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.
1416
+ * On iOS, the PushKit VoIP token (`kind: 'voip'`, the default) or the
1417
+ * regular APNs token (`kind: 'alert'`). Apple issues them separately
1418
+ * and a push aimed at the wrong one is discarded without an error.
1349
1419
  */
1350
1420
  token: string;
1351
1421
  platform: DevicePlatform;
1352
1422
  /** Defaults to `production` server-side. */
1353
1423
  environment?: DeviceEnvironment;
1424
+ /** iOS: defaults to `voip`. */
1425
+ kind?: DeviceKind;
1354
1426
  }
1355
1427
  /** A registered device, minus the token itself. */
1356
1428
  interface Device {
@@ -1359,6 +1431,7 @@ interface Device {
1359
1431
  user_id: string;
1360
1432
  platform: DevicePlatform;
1361
1433
  environment: DeviceEnvironment;
1434
+ kind: DeviceKind;
1362
1435
  last_registered_at: string | null;
1363
1436
  inserted_at: string;
1364
1437
  updated_at: string;
@@ -1944,6 +2017,8 @@ declare class Poolse {
1944
2017
  readonly iceServers: IceServersResource;
1945
2018
  /** SFU credentials for a call's media — see `CallTokensResource`. */
1946
2019
  readonly callTokens: CallTokensResource;
2020
+ /** Whether a call is running on a conversation — for a Join banner. */
2021
+ readonly liveCalls: LiveCallsResource;
1947
2022
  private readonly resolved;
1948
2023
  private readonly tokenCache;
1949
2024
  constructor(config: PoolseConfig);
@@ -2025,8 +2100,114 @@ declare class AuthError extends ApiError {
2025
2100
  declare function isWebRtcAvailable(): boolean;
2026
2101
  declare function createBrowserWebRtcAdapter(): WebRtcAdapter;
2027
2102
 
2028
- declare const version = "2.20.0";
2103
+ declare const version = "2.22.0";
2104
+
2105
+ type CallLogMedia = 'audio' | 'video';
2106
+ /** What became of one person a call involved (the caller excluded). */
2107
+ type CallParticipantStatus = 'joined' | 'declined' | 'busy' | 'missed';
2108
+ /** Why a call ended, as the server recorded it. */
2109
+ type CallEndReason = 'finished' | 'declined_all' | 'no_answer' | 'cancelled';
2110
+ /** A completed (answered or unanswered) call. */
2111
+ interface CallLogEntry {
2112
+ kind: 'call';
2113
+ callId: string;
2114
+ media: CallLogMedia;
2115
+ /** Talk time in ms; `null` when nobody answered. */
2116
+ durationMs: number | null;
2117
+ joinedUserIds: Uuid[];
2118
+ /** `2` for the one-record-per-call shape; `1` for older history. */
2119
+ version: 1 | 2;
2120
+ /** Who placed the call. `null` on v1 records. */
2121
+ callerUserId: Uuid | null;
2122
+ /** Everyone else the call involved, with their outcome. Empty on v1. */
2123
+ participants: Array<{
2124
+ userId: Uuid;
2125
+ status: CallParticipantStatus;
2126
+ }>;
2127
+ endReason: CallEndReason | null;
2128
+ /** Epoch ms; `null` on v1 records. */
2129
+ startedAt: number | null;
2130
+ endedAt: number | null;
2131
+ }
2132
+ /** Per-callee "you missed this call" marker. */
2133
+ interface CallMissedEntry {
2134
+ kind: 'call_missed';
2135
+ callId: string;
2136
+ /** The callee who missed the call — the only user who should see it. */
2137
+ userId: Uuid;
2138
+ /** Present when the server includes it; defaults to `'audio'` for display. */
2139
+ media: CallLogMedia | null;
2140
+ }
2141
+ type CallLog = CallLogEntry | CallMissedEntry;
2142
+ /**
2143
+ * Parse a raw message body (or a conversation's `last_message_preview`)
2144
+ * into a call log. Returns null for non-JSON or unknown shapes.
2145
+ */
2146
+ declare function parseCallLogBody(body: string | null | undefined): CallLog | null;
2147
+ /**
2148
+ * Parse a message into a call log. Only `system` / `custom` messages
2149
+ * are considered; text messages that happen to contain JSON are
2150
+ * never treated as call logs. Deleted messages return null.
2151
+ */
2152
+ declare function parseCallLog(message: Pick<Message, 'type' | 'body'> & {
2153
+ deleted_at?: string | null;
2154
+ }): CallLog | null;
2155
+ /** True when the message is a call log of either kind. */
2156
+ declare function isCallLogMessage(message: Pick<Message, 'type' | 'body'> & {
2157
+ deleted_at?: string | null;
2158
+ }): boolean;
2159
+ /** `3:12`, `0:05`, `1:02:03`. Rounds to the nearest second. */
2160
+ declare function formatCallDuration(ms: number): string;
2161
+ /** Render-ready description of a call log for one viewer. */
2162
+ interface CallLogDisplay {
2163
+ media: CallLogMedia;
2164
+ /** "Outgoing voice call", "Missed video call", "Group voice call"… */
2165
+ title: string;
2166
+ /** "3:12" when answered; "No answer", "Declined", "You declined"…; null when the title says it all. */
2167
+ detail: string | null;
2168
+ /** The viewer missed this call — render in the error tone. */
2169
+ missed: boolean;
2170
+ /** Short one-line form for list previews ("Video call · 3:12"). */
2171
+ summary: string;
2172
+ /** `outgoing` when the viewer placed the call, `incoming` when someone called them, else null. */
2173
+ direction: 'outgoing' | 'incoming' | null;
2174
+ /**
2175
+ * Worth offering "Call back": the viewer missed or declined it, or
2176
+ * placed it and nobody picked up.
2177
+ */
2178
+ callBack: boolean;
2179
+ }
2180
+ /**
2181
+ * Turn a call log into display copy for `currentUserId`. Returns null
2182
+ * when the entry should be hidden for this viewer (a v1 `call_missed`
2183
+ * marker addressed to someone else).
2184
+ */
2185
+ declare function describeCallLog(log: CallLog, currentUserId: string | null): CallLogDisplay | null;
2186
+ /**
2187
+ * Convenience: parse + describe a message in one go. Returns
2188
+ * `undefined` when the message isn't a call log at all, `null` when
2189
+ * it IS one but is hidden for this viewer, otherwise the display.
2190
+ */
2191
+ declare function callLogDisplayFor(message: Pick<Message, 'type' | 'body'> & {
2192
+ deleted_at?: string | null;
2193
+ }, currentUserId: string | null): CallLogDisplay | null | undefined;
2194
+ /**
2195
+ * Message filter for list rendering: drops call-log markers that are
2196
+ * hidden for this viewer so they don't affect grouping or day
2197
+ * separators. Every other message passes through untouched.
2198
+ */
2199
+ declare function isMessageVisibleTo(message: Pick<Message, 'type' | 'body'> & {
2200
+ deleted_at?: string | null;
2201
+ }, currentUserId: string | null): boolean;
2202
+ /**
2203
+ * Conversation-list preview text for a raw body / `last_message_preview`
2204
+ * string. Returns null when the string isn't a call log (show it as-is).
2205
+ * A missed-call marker addressed to someone else reads as a neutral
2206
+ * "Voice call" / "Video call" / "Call" instead of being hidden, since
2207
+ * the list row still needs some text.
2208
+ */
2209
+ declare function formatCallLogPreview(preview: string | null | undefined, currentUserId: string | null): string | null;
2029
2210
 
2030
2211
  declare function safeUuid(): string;
2031
2212
 
2032
- 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 CallMedia, 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, createBrowserWebRtcAdapter, isWebRtcAvailable, safeUuid, version };
2213
+ 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 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 };
package/dist/index.d.ts CHANGED
@@ -828,6 +828,75 @@ declare class TokenCache {
828
828
  private fetchAndStore;
829
829
  }
830
830
 
831
+ type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
832
+ interface RequestOptions {
833
+ method: HttpMethod;
834
+ path: string;
835
+ /** JSON-serialisable body for non-GETs. Omit for GET/DELETE. */
836
+ body?: unknown;
837
+ /** Query string params; values are stringified, nullish entries dropped. */
838
+ query?: Record<string, string | number | boolean | null | undefined>;
839
+ /**
840
+ * Idempotency-Key override. Defaults to a fresh UUID for non-GETs.
841
+ * Pass `null` to deliberately omit the header (e.g. when the caller's
842
+ * own retry logic supplies a deterministic one).
843
+ */
844
+ idempotencyKey?: string | null;
845
+ /**
846
+ * Per-request override for total retry budget. Defaults to
847
+ * `config.maxRetries`.
848
+ */
849
+ maxRetries?: number;
850
+ /** AbortSignal for caller-driven cancellation. */
851
+ signal?: AbortSignal;
852
+ }
853
+ declare class RestClient {
854
+ private readonly config;
855
+ private readonly tokenCache;
856
+ constructor(config: ResolvedConfig, tokenCache: TokenCache);
857
+ request<T>(opts: RequestOptions): Promise<T>;
858
+ private buildUrl;
859
+ private buildHeaders;
860
+ private resolveIdempotencyKey;
861
+ private backoffDelay;
862
+ }
863
+
864
+ /** A member as a live call names them. */
865
+ interface LiveCallMember {
866
+ user_id: string;
867
+ external_id: string | null;
868
+ display_name: string | null;
869
+ }
870
+ /**
871
+ * The call running on a conversation right now (CONTRACT.md §4.2's
872
+ * CallSummary). `participants` is who is in the room at this moment.
873
+ */
874
+ interface LiveCall {
875
+ id: string;
876
+ conversation_id: string;
877
+ conversation_name: string | null;
878
+ media: 'audio' | 'video';
879
+ state: 'live' | 'finished';
880
+ started_by: LiveCallMember;
881
+ started_at: string | null;
882
+ ended_at: string | null;
883
+ participants: LiveCallMember[];
884
+ /** Callee user id → `ringing` | `answered` | `declined`. */
885
+ ring_states: Record<string, 'ringing' | 'answered' | 'declined'>;
886
+ }
887
+ /**
888
+ * `/v1/conversations/:id/call` — whether a call is running on a
889
+ * conversation, for a "Call in progress · Join" banner. Live changes
890
+ * arrive on the conversation channel (`onCallStarted`,
891
+ * `onCallParticipants`, `onCallFinished`); this is the read on open.
892
+ */
893
+ declare class LiveCallsResource {
894
+ private readonly client;
895
+ constructor(client: RestClient);
896
+ /** GET /v1/conversations/:conversationId/call — `null` when no call is live. */
897
+ get(conversationId: string, signal?: AbortSignal): Promise<LiveCall | null>;
898
+ }
899
+
831
900
  /** `message:new` / `message:updated` push payloads. */
832
901
  type MessageNewEvent = Message;
833
902
  type MessageUpdatedEvent = Message;
@@ -863,6 +932,27 @@ interface MemberReadEvent {
863
932
  last_read_message_id: Uuid;
864
933
  last_read_at: string;
865
934
  }
935
+ /** `call:started` — a call went live on the conversation. */
936
+ interface CallStartedEvent {
937
+ cv: number;
938
+ call: LiveCall;
939
+ }
940
+ /** `call:participants` — who is in the live call's room right now (user ids). */
941
+ interface CallParticipantsEvent {
942
+ cv: number;
943
+ call_id: string;
944
+ participants: Uuid[];
945
+ }
946
+ /** `call:finished` — the call is over for everyone. */
947
+ interface CallFinishedEvent {
948
+ cv: number;
949
+ call_id: string;
950
+ ended_at?: string;
951
+ duration_ms?: number;
952
+ joined_user_ids?: Uuid[];
953
+ /** `finished` | `declined_all` | `no_answer` | `cancelled`. */
954
+ reason?: string;
955
+ }
866
956
  /** Per-user mention push on the `user:<id>` channel. */
867
957
  interface MentionEvent {
868
958
  message_id: Uuid;
@@ -1030,6 +1120,12 @@ declare class ConversationChannel {
1030
1120
  * sender's read-receipt glyph from "sent" to "read" in real time.
1031
1121
  */
1032
1122
  onMemberRead(fn: (evt: MemberReadEvent) => void): Unsubscribe$1;
1123
+ /** A call went live on this conversation (`call:started`). */
1124
+ onCallStarted(fn: (evt: CallStartedEvent) => void): Unsubscribe$1;
1125
+ /** Someone joined or left the live call (`call:participants`): user ids in the room now. */
1126
+ onCallParticipants(fn: (evt: CallParticipantsEvent) => void): Unsubscribe$1;
1127
+ /** The call is over for everyone (`call:finished`). */
1128
+ onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
1033
1129
  onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe$1;
1034
1130
  onPresenceDiff(fn: (diff: PresenceSnapshot) => void): Unsubscribe$1;
1035
1131
  /** Current presence snapshot for sync access — usually used in tests. */
@@ -1086,39 +1182,6 @@ declare class UserChannel {
1086
1182
  _destroy(): void;
1087
1183
  }
1088
1184
 
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
1185
  /** Input accepted by {@link AttachmentsResource.upload}. */
1123
1186
  interface AttachmentUploadInput {
1124
1187
  /**
@@ -1341,16 +1404,25 @@ type DevicePlatform = 'ios' | 'android';
1341
1404
  * versa — so a debug build must say `sandbox` or its pushes vanish.
1342
1405
  */
1343
1406
  type DeviceEnvironment = 'production' | 'sandbox';
1407
+ /**
1408
+ * iOS only — which of a phone's two tokens this is. `voip`: the PushKit
1409
+ * token, which only ever carries an incoming call. `alert`: the regular
1410
+ * APNs token, for notifications such as a missed call. Register both.
1411
+ * Android's one FCM token carries everything; leave `kind` out there.
1412
+ */
1413
+ type DeviceKind = 'voip' | 'alert';
1344
1414
  interface RegisterDeviceRequest {
1345
1415
  /**
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.
1416
+ * On iOS, the PushKit VoIP token (`kind: 'voip'`, the default) or the
1417
+ * regular APNs token (`kind: 'alert'`). Apple issues them separately
1418
+ * and a push aimed at the wrong one is discarded without an error.
1349
1419
  */
1350
1420
  token: string;
1351
1421
  platform: DevicePlatform;
1352
1422
  /** Defaults to `production` server-side. */
1353
1423
  environment?: DeviceEnvironment;
1424
+ /** iOS: defaults to `voip`. */
1425
+ kind?: DeviceKind;
1354
1426
  }
1355
1427
  /** A registered device, minus the token itself. */
1356
1428
  interface Device {
@@ -1359,6 +1431,7 @@ interface Device {
1359
1431
  user_id: string;
1360
1432
  platform: DevicePlatform;
1361
1433
  environment: DeviceEnvironment;
1434
+ kind: DeviceKind;
1362
1435
  last_registered_at: string | null;
1363
1436
  inserted_at: string;
1364
1437
  updated_at: string;
@@ -1944,6 +2017,8 @@ declare class Poolse {
1944
2017
  readonly iceServers: IceServersResource;
1945
2018
  /** SFU credentials for a call's media — see `CallTokensResource`. */
1946
2019
  readonly callTokens: CallTokensResource;
2020
+ /** Whether a call is running on a conversation — for a Join banner. */
2021
+ readonly liveCalls: LiveCallsResource;
1947
2022
  private readonly resolved;
1948
2023
  private readonly tokenCache;
1949
2024
  constructor(config: PoolseConfig);
@@ -2025,8 +2100,114 @@ declare class AuthError extends ApiError {
2025
2100
  declare function isWebRtcAvailable(): boolean;
2026
2101
  declare function createBrowserWebRtcAdapter(): WebRtcAdapter;
2027
2102
 
2028
- declare const version = "2.20.0";
2103
+ declare const version = "2.22.0";
2104
+
2105
+ type CallLogMedia = 'audio' | 'video';
2106
+ /** What became of one person a call involved (the caller excluded). */
2107
+ type CallParticipantStatus = 'joined' | 'declined' | 'busy' | 'missed';
2108
+ /** Why a call ended, as the server recorded it. */
2109
+ type CallEndReason = 'finished' | 'declined_all' | 'no_answer' | 'cancelled';
2110
+ /** A completed (answered or unanswered) call. */
2111
+ interface CallLogEntry {
2112
+ kind: 'call';
2113
+ callId: string;
2114
+ media: CallLogMedia;
2115
+ /** Talk time in ms; `null` when nobody answered. */
2116
+ durationMs: number | null;
2117
+ joinedUserIds: Uuid[];
2118
+ /** `2` for the one-record-per-call shape; `1` for older history. */
2119
+ version: 1 | 2;
2120
+ /** Who placed the call. `null` on v1 records. */
2121
+ callerUserId: Uuid | null;
2122
+ /** Everyone else the call involved, with their outcome. Empty on v1. */
2123
+ participants: Array<{
2124
+ userId: Uuid;
2125
+ status: CallParticipantStatus;
2126
+ }>;
2127
+ endReason: CallEndReason | null;
2128
+ /** Epoch ms; `null` on v1 records. */
2129
+ startedAt: number | null;
2130
+ endedAt: number | null;
2131
+ }
2132
+ /** Per-callee "you missed this call" marker. */
2133
+ interface CallMissedEntry {
2134
+ kind: 'call_missed';
2135
+ callId: string;
2136
+ /** The callee who missed the call — the only user who should see it. */
2137
+ userId: Uuid;
2138
+ /** Present when the server includes it; defaults to `'audio'` for display. */
2139
+ media: CallLogMedia | null;
2140
+ }
2141
+ type CallLog = CallLogEntry | CallMissedEntry;
2142
+ /**
2143
+ * Parse a raw message body (or a conversation's `last_message_preview`)
2144
+ * into a call log. Returns null for non-JSON or unknown shapes.
2145
+ */
2146
+ declare function parseCallLogBody(body: string | null | undefined): CallLog | null;
2147
+ /**
2148
+ * Parse a message into a call log. Only `system` / `custom` messages
2149
+ * are considered; text messages that happen to contain JSON are
2150
+ * never treated as call logs. Deleted messages return null.
2151
+ */
2152
+ declare function parseCallLog(message: Pick<Message, 'type' | 'body'> & {
2153
+ deleted_at?: string | null;
2154
+ }): CallLog | null;
2155
+ /** True when the message is a call log of either kind. */
2156
+ declare function isCallLogMessage(message: Pick<Message, 'type' | 'body'> & {
2157
+ deleted_at?: string | null;
2158
+ }): boolean;
2159
+ /** `3:12`, `0:05`, `1:02:03`. Rounds to the nearest second. */
2160
+ declare function formatCallDuration(ms: number): string;
2161
+ /** Render-ready description of a call log for one viewer. */
2162
+ interface CallLogDisplay {
2163
+ media: CallLogMedia;
2164
+ /** "Outgoing voice call", "Missed video call", "Group voice call"… */
2165
+ title: string;
2166
+ /** "3:12" when answered; "No answer", "Declined", "You declined"…; null when the title says it all. */
2167
+ detail: string | null;
2168
+ /** The viewer missed this call — render in the error tone. */
2169
+ missed: boolean;
2170
+ /** Short one-line form for list previews ("Video call · 3:12"). */
2171
+ summary: string;
2172
+ /** `outgoing` when the viewer placed the call, `incoming` when someone called them, else null. */
2173
+ direction: 'outgoing' | 'incoming' | null;
2174
+ /**
2175
+ * Worth offering "Call back": the viewer missed or declined it, or
2176
+ * placed it and nobody picked up.
2177
+ */
2178
+ callBack: boolean;
2179
+ }
2180
+ /**
2181
+ * Turn a call log into display copy for `currentUserId`. Returns null
2182
+ * when the entry should be hidden for this viewer (a v1 `call_missed`
2183
+ * marker addressed to someone else).
2184
+ */
2185
+ declare function describeCallLog(log: CallLog, currentUserId: string | null): CallLogDisplay | null;
2186
+ /**
2187
+ * Convenience: parse + describe a message in one go. Returns
2188
+ * `undefined` when the message isn't a call log at all, `null` when
2189
+ * it IS one but is hidden for this viewer, otherwise the display.
2190
+ */
2191
+ declare function callLogDisplayFor(message: Pick<Message, 'type' | 'body'> & {
2192
+ deleted_at?: string | null;
2193
+ }, currentUserId: string | null): CallLogDisplay | null | undefined;
2194
+ /**
2195
+ * Message filter for list rendering: drops call-log markers that are
2196
+ * hidden for this viewer so they don't affect grouping or day
2197
+ * separators. Every other message passes through untouched.
2198
+ */
2199
+ declare function isMessageVisibleTo(message: Pick<Message, 'type' | 'body'> & {
2200
+ deleted_at?: string | null;
2201
+ }, currentUserId: string | null): boolean;
2202
+ /**
2203
+ * Conversation-list preview text for a raw body / `last_message_preview`
2204
+ * string. Returns null when the string isn't a call log (show it as-is).
2205
+ * A missed-call marker addressed to someone else reads as a neutral
2206
+ * "Voice call" / "Video call" / "Call" instead of being hidden, since
2207
+ * the list row still needs some text.
2208
+ */
2209
+ declare function formatCallLogPreview(preview: string | null | undefined, currentUserId: string | null): string | null;
2029
2210
 
2030
2211
  declare function safeUuid(): string;
2031
2212
 
2032
- 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 CallMedia, 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, createBrowserWebRtcAdapter, isWebRtcAvailable, safeUuid, version };
2213
+ 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 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 };