@poolse/sdk 3.0.0 → 3.1.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
@@ -618,8 +618,23 @@ interface CallFinishedEvent {
618
618
  ended_at?: string;
619
619
  duration_ms?: number;
620
620
  joined_user_ids?: Uuid[];
621
- /** `finished` | `declined_all` | `no_answer` | `cancelled`. */
621
+ /** `finished` | `declined_all` | `busy_all` | `no_answer` | `cancelled`. */
622
622
  reason?: string;
623
+ /** Present on the `user:<id>` copy (`UserChannel.onCallFinished`). */
624
+ conversation_id?: Uuid;
625
+ }
626
+ /**
627
+ * Your ring for a call is over (`call:ring_ended` on `user:<id>`): stop
628
+ * ringing on this device.
629
+ */
630
+ interface RingEndedEvent {
631
+ cv: number;
632
+ call_id: string;
633
+ conversation_id: Uuid;
634
+ /** `answered_elsewhere` | `declined` | `cancelled` | `timeout` | `finished`. */
635
+ reason: string;
636
+ /** The device that resolved the ring (e.g. the one that answered), so it can ignore this. */
637
+ device_id?: string;
623
638
  }
624
639
  /** Per-user mention push on the `user:<id>` channel. */
625
640
  interface MentionEvent {
@@ -689,6 +704,8 @@ declare class PoolseRealtime {
689
704
  private readonly conversations;
690
705
  private userChannel;
691
706
  private status;
707
+ private paused;
708
+ private lastTokenRefreshMs;
692
709
  private readonly statusListeners;
693
710
  constructor(config: ResolvedConfig, tokenCache: TokenCache, opts?: RealtimeOptions);
694
711
  /** Current connection status. */
@@ -721,6 +738,15 @@ declare class PoolseRealtime {
721
738
  * the cache can re-fill on the next iteration.
722
739
  */
723
740
  connect(): void;
741
+ /**
742
+ * Close the socket but keep every channel handle and its listeners
743
+ * (for an app going to the background). `resume()` reopens it and
744
+ * Phoenix rejoins the channels. Events sent in between are not
745
+ * replayed; the React hooks reload from REST on reconnect.
746
+ */
747
+ pause(): void;
748
+ /** Reopen a socket closed by `pause()`, with a fresh token. */
749
+ resume(): void;
724
750
  /** Close the socket and tear down every joined channel. */
725
751
  disconnect(): void;
726
752
  /**
@@ -744,7 +770,8 @@ declare class ConversationChannel {
744
770
  private readonly listeners;
745
771
  private presenceState;
746
772
  private presenceStateSeen;
747
- constructor(conversationId: string, channel: Channel);
773
+ private readonly closedListeners;
774
+ constructor(conversationId: string, channel: Channel, onGone?: () => void);
748
775
  /** New message pushed to the conversation. */
749
776
  onMessage(fn: (msg: MessageNewEvent) => void): Unsubscribe$1;
750
777
  /** Existing message edited by its sender. */
@@ -768,6 +795,13 @@ declare class ConversationChannel {
768
795
  onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
769
796
  onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe$1;
770
797
  onPresenceDiff(fn: (diff: PresenceSnapshot) => void): Unsubscribe$1;
798
+ /**
799
+ * The channel closed for good: the server removed you from the
800
+ * conversation, or `leave()` / `disconnect()` was called. No more
801
+ * events arrive on this handle; `realtime.conversation(id)` returns a
802
+ * fresh one.
803
+ */
804
+ onClosed(fn: () => void): Unsubscribe$1;
771
805
  /** Current presence snapshot for sync access — usually used in tests. */
772
806
  getPresenceState(): PresenceSnapshot;
773
807
  /** Send a typing ping to the server. Debounced server-side. */
@@ -787,6 +821,7 @@ declare class UserChannel {
787
821
  private mentionBound;
788
822
  private conversationCreatedBound;
789
823
  private conversationUpdatedBound;
824
+ private readonly listeners;
790
825
  constructor(userId: string, channel: Channel);
791
826
  /**
792
827
  * The underlying Phoenix channel, for hosts that listen to events the
@@ -817,10 +852,22 @@ declare class UserChannel {
817
852
  * your own outbound messages out of your unread count.
818
853
  */
819
854
  onConversationUpdated(fn: (evt: ConversationUpdatedEvent) => void): Unsubscribe$1;
855
+ /**
856
+ * Your ring for a call ended — answered on another device, declined,
857
+ * cancelled by the caller or timed out. Stop ringing on this device.
858
+ */
859
+ onRingEnded(fn: (evt: RingEndedEvent) => void): Unsubscribe$1;
860
+ /**
861
+ * A call you were part of (rung or joined) is over. Arrives on the
862
+ * user channel, which the app stays joined to even after leaving the
863
+ * conversation's channel mid-call.
864
+ */
865
+ onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
820
866
  /** @internal */
821
867
  _join(): void;
822
868
  /** @internal */
823
869
  _destroy(): void;
870
+ private subscribe;
824
871
  }
825
872
 
826
873
  /** Input accepted by {@link AttachmentsResource.upload}. */
@@ -900,7 +947,7 @@ declare class AttachmentsResource {
900
947
  * });
901
948
  * await chat.conversations.one(convId).messages.send({
902
949
  * body: 'Look at this!',
903
- * custom_data: { attachment_id: att.id },
950
+ * attachment_ids: [att.id],
904
951
  * });
905
952
  * ```
906
953
  *
@@ -1407,8 +1454,8 @@ interface CallRoomOptions {
1407
1454
  * Resolves SFU credentials for this conversation.
1408
1455
  *
1409
1456
  * Returning `null` means the deployment has no SFU configured (the API
1410
- * answers 503), which callers treat as "fall back to the mesh" rather
1411
- * than as an error.
1457
+ * answers 503): calls are unavailable, which callers show as such
1458
+ * rather than as an error.
1412
1459
  */
1413
1460
  tokenProvider: () => Promise<CallConnection | null>;
1414
1461
  /** Publish the camera on join. Audio calls start with it off. */
@@ -1447,10 +1494,10 @@ declare class CallTokensResource {
1447
1494
  /**
1448
1495
  * POST /v1/conversations/:conversationId/call-token
1449
1496
  *
1450
- * Resolves `null` when the deployment has no SFU configured (503).
1451
- * That is deliberately not an error — the caller falls back to the
1452
- * peer-to-peer mesh, which is how every call worked before the SFU
1453
- * existed. A 403 still throws: that one really is a refusal.
1497
+ * Resolves `null` when the deployment has no SFU configured (503):
1498
+ * calls are unavailable there, which the caller shows as such rather
1499
+ * than as a failed call. A 403 still throws: that one really is a
1500
+ * refusal.
1454
1501
  */
1455
1502
  create(conversationId: string, signal?: AbortSignal): Promise<CallConnection | null>;
1456
1503
  }
@@ -1567,8 +1614,8 @@ declare class CallRoom {
1567
1614
  * Connect to the SFU.
1568
1615
  *
1569
1616
  * Resolves `true` once media is flowing, `false` when the deployment
1570
- * has no SFU — the caller should fall back to the mesh rather than
1571
- * treat that as a failed call.
1617
+ * has no SFU — calls are unavailable there; show that rather than a
1618
+ * failed call.
1572
1619
  */
1573
1620
  join(): Promise<boolean>;
1574
1621
  /** Release one holder; disconnects once none are left. */
@@ -1725,7 +1772,7 @@ declare class Poolse {
1725
1772
  *
1726
1773
  * import * as livekit from 'livekit-client';
1727
1774
  * const call = poolse.call(conversationId, { livekit, video: true });
1728
- * const usingSfu = await call.join(); // false = no SFU, use the mesh
1775
+ * const joined = await call.join(); // false = calls aren't available on this deployment
1729
1776
  */
1730
1777
  call(conversationId: string, opts: Omit<CallRoomOptions, 'tokenProvider'> & Partial<Pick<CallRoomOptions, 'tokenProvider'>>): CallRoom;
1731
1778
  /**
@@ -1791,7 +1838,7 @@ declare class AuthError extends ApiError {
1791
1838
  */
1792
1839
  type CallMedia = 'audio' | 'video';
1793
1840
 
1794
- declare const version = "3.0.0";
1841
+ declare const version = "3.1.0";
1795
1842
 
1796
1843
  type CallLogMedia = 'audio' | 'video';
1797
1844
  /** What became of one person a call involved (the caller excluded). */
@@ -1903,4 +1950,4 @@ declare function formatCallLogPreview(preview: string | null | undefined, curren
1903
1950
 
1904
1951
  declare function safeUuid(): string;
1905
1952
 
1906
- export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, type AttachmentProgressEvent, type AttachmentStatus, type AttachmentUploadInput, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsResource, AuthError, type CallConnection, type CallDevice, type CallDeviceKind, type CallEndReason, 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, 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 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, 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 RoomSession, RoomsResource, type TypingEvent, type Unsubscribe$1 as Unsubscribe, type UpdateMeRequest, UserChannel, UsersResource, type Uuid, callLogDisplayFor, describeCallLog, formatCallDuration, formatCallLogPreview, isCallLogMessage, isMessageVisibleTo, parseCallLog, parseCallLogBody, safeUuid, version };
1953
+ export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, type AttachmentProgressEvent, type AttachmentStatus, type AttachmentUploadInput, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsResource, AuthError, type CallConnection, type CallDevice, type CallDeviceKind, type CallEndReason, 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, 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 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, 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 RingEndedEvent, type RoomSession, RoomsResource, type TypingEvent, type Unsubscribe$1 as Unsubscribe, type UpdateMeRequest, UserChannel, UsersResource, type Uuid, callLogDisplayFor, describeCallLog, formatCallDuration, formatCallLogPreview, isCallLogMessage, isMessageVisibleTo, parseCallLog, parseCallLogBody, safeUuid, version };
package/dist/index.d.ts CHANGED
@@ -618,8 +618,23 @@ interface CallFinishedEvent {
618
618
  ended_at?: string;
619
619
  duration_ms?: number;
620
620
  joined_user_ids?: Uuid[];
621
- /** `finished` | `declined_all` | `no_answer` | `cancelled`. */
621
+ /** `finished` | `declined_all` | `busy_all` | `no_answer` | `cancelled`. */
622
622
  reason?: string;
623
+ /** Present on the `user:<id>` copy (`UserChannel.onCallFinished`). */
624
+ conversation_id?: Uuid;
625
+ }
626
+ /**
627
+ * Your ring for a call is over (`call:ring_ended` on `user:<id>`): stop
628
+ * ringing on this device.
629
+ */
630
+ interface RingEndedEvent {
631
+ cv: number;
632
+ call_id: string;
633
+ conversation_id: Uuid;
634
+ /** `answered_elsewhere` | `declined` | `cancelled` | `timeout` | `finished`. */
635
+ reason: string;
636
+ /** The device that resolved the ring (e.g. the one that answered), so it can ignore this. */
637
+ device_id?: string;
623
638
  }
624
639
  /** Per-user mention push on the `user:<id>` channel. */
625
640
  interface MentionEvent {
@@ -689,6 +704,8 @@ declare class PoolseRealtime {
689
704
  private readonly conversations;
690
705
  private userChannel;
691
706
  private status;
707
+ private paused;
708
+ private lastTokenRefreshMs;
692
709
  private readonly statusListeners;
693
710
  constructor(config: ResolvedConfig, tokenCache: TokenCache, opts?: RealtimeOptions);
694
711
  /** Current connection status. */
@@ -721,6 +738,15 @@ declare class PoolseRealtime {
721
738
  * the cache can re-fill on the next iteration.
722
739
  */
723
740
  connect(): void;
741
+ /**
742
+ * Close the socket but keep every channel handle and its listeners
743
+ * (for an app going to the background). `resume()` reopens it and
744
+ * Phoenix rejoins the channels. Events sent in between are not
745
+ * replayed; the React hooks reload from REST on reconnect.
746
+ */
747
+ pause(): void;
748
+ /** Reopen a socket closed by `pause()`, with a fresh token. */
749
+ resume(): void;
724
750
  /** Close the socket and tear down every joined channel. */
725
751
  disconnect(): void;
726
752
  /**
@@ -744,7 +770,8 @@ declare class ConversationChannel {
744
770
  private readonly listeners;
745
771
  private presenceState;
746
772
  private presenceStateSeen;
747
- constructor(conversationId: string, channel: Channel);
773
+ private readonly closedListeners;
774
+ constructor(conversationId: string, channel: Channel, onGone?: () => void);
748
775
  /** New message pushed to the conversation. */
749
776
  onMessage(fn: (msg: MessageNewEvent) => void): Unsubscribe$1;
750
777
  /** Existing message edited by its sender. */
@@ -768,6 +795,13 @@ declare class ConversationChannel {
768
795
  onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
769
796
  onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe$1;
770
797
  onPresenceDiff(fn: (diff: PresenceSnapshot) => void): Unsubscribe$1;
798
+ /**
799
+ * The channel closed for good: the server removed you from the
800
+ * conversation, or `leave()` / `disconnect()` was called. No more
801
+ * events arrive on this handle; `realtime.conversation(id)` returns a
802
+ * fresh one.
803
+ */
804
+ onClosed(fn: () => void): Unsubscribe$1;
771
805
  /** Current presence snapshot for sync access — usually used in tests. */
772
806
  getPresenceState(): PresenceSnapshot;
773
807
  /** Send a typing ping to the server. Debounced server-side. */
@@ -787,6 +821,7 @@ declare class UserChannel {
787
821
  private mentionBound;
788
822
  private conversationCreatedBound;
789
823
  private conversationUpdatedBound;
824
+ private readonly listeners;
790
825
  constructor(userId: string, channel: Channel);
791
826
  /**
792
827
  * The underlying Phoenix channel, for hosts that listen to events the
@@ -817,10 +852,22 @@ declare class UserChannel {
817
852
  * your own outbound messages out of your unread count.
818
853
  */
819
854
  onConversationUpdated(fn: (evt: ConversationUpdatedEvent) => void): Unsubscribe$1;
855
+ /**
856
+ * Your ring for a call ended — answered on another device, declined,
857
+ * cancelled by the caller or timed out. Stop ringing on this device.
858
+ */
859
+ onRingEnded(fn: (evt: RingEndedEvent) => void): Unsubscribe$1;
860
+ /**
861
+ * A call you were part of (rung or joined) is over. Arrives on the
862
+ * user channel, which the app stays joined to even after leaving the
863
+ * conversation's channel mid-call.
864
+ */
865
+ onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
820
866
  /** @internal */
821
867
  _join(): void;
822
868
  /** @internal */
823
869
  _destroy(): void;
870
+ private subscribe;
824
871
  }
825
872
 
826
873
  /** Input accepted by {@link AttachmentsResource.upload}. */
@@ -900,7 +947,7 @@ declare class AttachmentsResource {
900
947
  * });
901
948
  * await chat.conversations.one(convId).messages.send({
902
949
  * body: 'Look at this!',
903
- * custom_data: { attachment_id: att.id },
950
+ * attachment_ids: [att.id],
904
951
  * });
905
952
  * ```
906
953
  *
@@ -1407,8 +1454,8 @@ interface CallRoomOptions {
1407
1454
  * Resolves SFU credentials for this conversation.
1408
1455
  *
1409
1456
  * Returning `null` means the deployment has no SFU configured (the API
1410
- * answers 503), which callers treat as "fall back to the mesh" rather
1411
- * than as an error.
1457
+ * answers 503): calls are unavailable, which callers show as such
1458
+ * rather than as an error.
1412
1459
  */
1413
1460
  tokenProvider: () => Promise<CallConnection | null>;
1414
1461
  /** Publish the camera on join. Audio calls start with it off. */
@@ -1447,10 +1494,10 @@ declare class CallTokensResource {
1447
1494
  /**
1448
1495
  * POST /v1/conversations/:conversationId/call-token
1449
1496
  *
1450
- * Resolves `null` when the deployment has no SFU configured (503).
1451
- * That is deliberately not an error — the caller falls back to the
1452
- * peer-to-peer mesh, which is how every call worked before the SFU
1453
- * existed. A 403 still throws: that one really is a refusal.
1497
+ * Resolves `null` when the deployment has no SFU configured (503):
1498
+ * calls are unavailable there, which the caller shows as such rather
1499
+ * than as a failed call. A 403 still throws: that one really is a
1500
+ * refusal.
1454
1501
  */
1455
1502
  create(conversationId: string, signal?: AbortSignal): Promise<CallConnection | null>;
1456
1503
  }
@@ -1567,8 +1614,8 @@ declare class CallRoom {
1567
1614
  * Connect to the SFU.
1568
1615
  *
1569
1616
  * Resolves `true` once media is flowing, `false` when the deployment
1570
- * has no SFU — the caller should fall back to the mesh rather than
1571
- * treat that as a failed call.
1617
+ * has no SFU — calls are unavailable there; show that rather than a
1618
+ * failed call.
1572
1619
  */
1573
1620
  join(): Promise<boolean>;
1574
1621
  /** Release one holder; disconnects once none are left. */
@@ -1725,7 +1772,7 @@ declare class Poolse {
1725
1772
  *
1726
1773
  * import * as livekit from 'livekit-client';
1727
1774
  * const call = poolse.call(conversationId, { livekit, video: true });
1728
- * const usingSfu = await call.join(); // false = no SFU, use the mesh
1775
+ * const joined = await call.join(); // false = calls aren't available on this deployment
1729
1776
  */
1730
1777
  call(conversationId: string, opts: Omit<CallRoomOptions, 'tokenProvider'> & Partial<Pick<CallRoomOptions, 'tokenProvider'>>): CallRoom;
1731
1778
  /**
@@ -1791,7 +1838,7 @@ declare class AuthError extends ApiError {
1791
1838
  */
1792
1839
  type CallMedia = 'audio' | 'video';
1793
1840
 
1794
- declare const version = "3.0.0";
1841
+ declare const version = "3.1.0";
1795
1842
 
1796
1843
  type CallLogMedia = 'audio' | 'video';
1797
1844
  /** What became of one person a call involved (the caller excluded). */
@@ -1903,4 +1950,4 @@ declare function formatCallLogPreview(preview: string | null | undefined, curren
1903
1950
 
1904
1951
  declare function safeUuid(): string;
1905
1952
 
1906
- export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, type AttachmentProgressEvent, type AttachmentStatus, type AttachmentUploadInput, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsResource, AuthError, type CallConnection, type CallDevice, type CallDeviceKind, type CallEndReason, 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, 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 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, 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 RoomSession, RoomsResource, type TypingEvent, type Unsubscribe$1 as Unsubscribe, type UpdateMeRequest, UserChannel, UsersResource, type Uuid, callLogDisplayFor, describeCallLog, formatCallDuration, formatCallLogPreview, isCallLogMessage, isMessageVisibleTo, parseCallLog, parseCallLogBody, safeUuid, version };
1953
+ export { type AddMemberOptions, ApiError, type Attachment, type AttachmentDownloadResponse, AttachmentHandle, type AttachmentOptions, type AttachmentProgressEvent, type AttachmentStatus, type AttachmentUploadInput, type AttachmentUploadRequest, type AttachmentUploadResponse, AttachmentsResource, AuthError, type CallConnection, type CallDevice, type CallDeviceKind, type CallEndReason, 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, 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 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, 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 RingEndedEvent, type RoomSession, RoomsResource, type TypingEvent, type Unsubscribe$1 as Unsubscribe, type UpdateMeRequest, UserChannel, UsersResource, type Uuid, callLogDisplayFor, describeCallLog, formatCallDuration, formatCallLogPreview, isCallLogMessage, isMessageVisibleTo, parseCallLog, parseCallLogBody, safeUuid, version };
package/dist/index.js CHANGED
@@ -104,6 +104,7 @@ var AuthError = class extends ApiError {
104
104
  };
105
105
 
106
106
  // src/realtime/realtime.ts
107
+ var TOKEN_REFRESH_ON_ERROR_MS = 3e4;
107
108
  var PoolseRealtime = class {
108
109
  config;
109
110
  tokenCache;
@@ -113,6 +114,8 @@ var PoolseRealtime = class {
113
114
  conversations = /* @__PURE__ */ new Map();
114
115
  userChannel = null;
115
116
  status = "idle";
117
+ paused = false;
118
+ lastTokenRefreshMs = 0;
116
119
  statusListeners = /* @__PURE__ */ new Set();
117
120
  constructor(config, tokenCache, opts = {}) {
118
121
  this.config = config;
@@ -168,9 +171,15 @@ var PoolseRealtime = class {
168
171
  });
169
172
  socket.onError((err) => {
170
173
  this.setStatus("reconnecting");
174
+ if (Date.now() - this.lastTokenRefreshMs > TOKEN_REFRESH_ON_ERROR_MS) {
175
+ this.lastTokenRefreshMs = Date.now();
176
+ void this.tokenCache.getToken({ forceRefresh: true }).catch(() => {
177
+ });
178
+ }
171
179
  this.config.onSocketError?.(new PoolseError(`socket error: ${String(err)}`));
172
180
  });
173
181
  this.socket = socket;
182
+ this.lastTokenRefreshMs = Date.now();
174
183
  void this.tokenCache.getToken().catch((err) => {
175
184
  this.config.onSocketError?.(
176
185
  new PoolseError(`token fetch failed before socket open: ${String(err)}`)
@@ -179,8 +188,35 @@ var PoolseRealtime = class {
179
188
  socket.connect();
180
189
  });
181
190
  }
191
+ /**
192
+ * Close the socket but keep every channel handle and its listeners
193
+ * (for an app going to the background). `resume()` reopens it and
194
+ * Phoenix rejoins the channels. Events sent in between are not
195
+ * replayed; the React hooks reload from REST on reconnect.
196
+ */
197
+ pause() {
198
+ if (!this.socket || this.paused) return;
199
+ this.paused = true;
200
+ this.setStatus("closed");
201
+ this.socket.disconnect();
202
+ }
203
+ /** Reopen a socket closed by `pause()`, with a fresh token. */
204
+ resume() {
205
+ const socket = this.socket;
206
+ if (!socket || !this.paused) return;
207
+ this.paused = false;
208
+ this.setStatus("connecting");
209
+ void this.tokenCache.getToken().catch((err) => {
210
+ this.config.onSocketError?.(
211
+ new PoolseError(`token fetch failed before socket open: ${String(err)}`)
212
+ );
213
+ }).finally(() => {
214
+ if (this.socket === socket && !this.paused) socket.connect();
215
+ });
216
+ }
182
217
  /** Close the socket and tear down every joined channel. */
183
218
  disconnect() {
219
+ this.paused = false;
184
220
  this.setStatus("closed");
185
221
  this.conversations.forEach((c) => c._destroy());
186
222
  this.conversations.clear();
@@ -204,7 +240,10 @@ var PoolseRealtime = class {
204
240
  throw new PoolseError("socket not initialised \u2014 call connect() first");
205
241
  }
206
242
  const channel = this.socket.channel(`conversation:${conversationId}`, {});
207
- const handle = new ConversationChannel(conversationId, channel);
243
+ const handle = new ConversationChannel(conversationId, channel, () => {
244
+ if (this.conversations.get(conversationId) === handle)
245
+ this.conversations.delete(conversationId);
246
+ });
208
247
  this.conversations.set(conversationId, handle);
209
248
  handle._join();
210
249
  return handle;
@@ -253,9 +292,15 @@ var ConversationChannel = class {
253
292
  // state here and replay it on subscribe.
254
293
  presenceState = {};
255
294
  presenceStateSeen = false;
256
- constructor(conversationId, channel) {
295
+ closedListeners = /* @__PURE__ */ new Set();
296
+ constructor(conversationId, channel, onGone) {
257
297
  this.conversationId = conversationId;
258
298
  this.channel = channel;
299
+ channel.onClose(() => {
300
+ onGone?.();
301
+ this.closedListeners.forEach((l) => l());
302
+ this.closedListeners.clear();
303
+ });
259
304
  channel.on("presence_state", (payload) => {
260
305
  this.presenceState = payload ?? {};
261
306
  this.presenceStateSeen = true;
@@ -330,6 +375,18 @@ var ConversationChannel = class {
330
375
  onPresenceDiff(fn) {
331
376
  return this.subscribe("presence_diff", fn);
332
377
  }
378
+ /**
379
+ * The channel closed for good: the server removed you from the
380
+ * conversation, or `leave()` / `disconnect()` was called. No more
381
+ * events arrive on this handle; `realtime.conversation(id)` returns a
382
+ * fresh one.
383
+ */
384
+ onClosed(fn) {
385
+ this.closedListeners.add(fn);
386
+ return () => {
387
+ this.closedListeners.delete(fn);
388
+ };
389
+ }
333
390
  /** Current presence snapshot for sync access — usually used in tests. */
334
391
  getPresenceState() {
335
392
  return this.presenceState;
@@ -372,6 +429,8 @@ var UserChannel = class {
372
429
  mentionBound = false;
373
430
  conversationCreatedBound = false;
374
431
  conversationUpdatedBound = false;
432
+ // One Phoenix binding per event, fanned out — as in ConversationChannel.
433
+ listeners = /* @__PURE__ */ new Map();
375
434
  constructor(userId, channel) {
376
435
  this.userId = userId;
377
436
  this.channel = channel;
@@ -440,17 +499,47 @@ var UserChannel = class {
440
499
  this.conversationUpdatedListeners.delete(fn);
441
500
  };
442
501
  }
502
+ /**
503
+ * Your ring for a call ended — answered on another device, declined,
504
+ * cancelled by the caller or timed out. Stop ringing on this device.
505
+ */
506
+ onRingEnded(fn) {
507
+ return this.subscribe("call:ring_ended", fn);
508
+ }
509
+ /**
510
+ * A call you were part of (rung or joined) is over. Arrives on the
511
+ * user channel, which the app stays joined to even after leaving the
512
+ * conversation's channel mid-call.
513
+ */
514
+ onCallFinished(fn) {
515
+ return this.subscribe("call:finished", fn);
516
+ }
443
517
  /** @internal */
444
518
  _join() {
445
519
  this.channel.join();
446
520
  }
447
521
  /** @internal */
448
522
  _destroy() {
523
+ this.listeners.clear();
449
524
  this.mentionListeners.clear();
450
525
  this.conversationCreatedListeners.clear();
451
526
  this.conversationUpdatedListeners.clear();
452
527
  this.channel.leave();
453
528
  }
529
+ subscribe(event, fn) {
530
+ let set = this.listeners.get(event);
531
+ if (!set) {
532
+ set = /* @__PURE__ */ new Set();
533
+ this.listeners.set(event, set);
534
+ this.channel.on(event, (payload) => {
535
+ this.listeners.get(event)?.forEach((l) => l(payload));
536
+ });
537
+ }
538
+ set.add(fn);
539
+ return () => {
540
+ set.delete(fn);
541
+ };
542
+ }
454
543
  };
455
544
  function deriveWsUrl(apiUrl) {
456
545
  return apiUrl.replace(/^http/, "ws");
@@ -502,7 +591,7 @@ var AttachmentsResource = class {
502
591
  * });
503
592
  * await chat.conversations.one(convId).messages.send({
504
593
  * body: 'Look at this!',
505
- * custom_data: { attachment_id: att.id },
594
+ * attachment_ids: [att.id],
506
595
  * });
507
596
  * ```
508
597
  *
@@ -1024,10 +1113,10 @@ var CallTokensResource = class {
1024
1113
  /**
1025
1114
  * POST /v1/conversations/:conversationId/call-token
1026
1115
  *
1027
- * Resolves `null` when the deployment has no SFU configured (503).
1028
- * That is deliberately not an error — the caller falls back to the
1029
- * peer-to-peer mesh, which is how every call worked before the SFU
1030
- * existed. A 403 still throws: that one really is a refusal.
1116
+ * Resolves `null` when the deployment has no SFU configured (503):
1117
+ * calls are unavailable there, which the caller shows as such rather
1118
+ * than as a failed call. A 403 still throws: that one really is a
1119
+ * refusal.
1031
1120
  */
1032
1121
  async create(conversationId, signal) {
1033
1122
  try {
@@ -1129,7 +1218,7 @@ var CallRoom = class {
1129
1218
  room = null;
1130
1219
  status = "idle";
1131
1220
  selfId = null;
1132
- // Reference counted like VoiceRoom: a call screen and a roster can
1221
+ // Reference counted: a call screen and a roster can
1133
1222
  // both hold the same call, and the second holder must not open a
1134
1223
  // second SFU connection or tear the first one down on leaving.
1135
1224
  holders = 0;
@@ -1218,8 +1307,8 @@ var CallRoom = class {
1218
1307
  * Connect to the SFU.
1219
1308
  *
1220
1309
  * Resolves `true` once media is flowing, `false` when the deployment
1221
- * has no SFU — the caller should fall back to the mesh rather than
1222
- * treat that as a failed call.
1310
+ * has no SFU — calls are unavailable there; show that rather than a
1311
+ * failed call.
1223
1312
  */
1224
1313
  async join() {
1225
1314
  if (this.room) {
@@ -1871,7 +1960,7 @@ var Poolse = class {
1871
1960
  *
1872
1961
  * import * as livekit from 'livekit-client';
1873
1962
  * const call = poolse.call(conversationId, { livekit, video: true });
1874
- * const usingSfu = await call.join(); // false = no SFU, use the mesh
1963
+ * const joined = await call.join(); // false = calls aren't available on this deployment
1875
1964
  */
1876
1965
  call(conversationId, opts) {
1877
1966
  return new CallRoom({
@@ -1891,7 +1980,7 @@ var Poolse = class {
1891
1980
  };
1892
1981
 
1893
1982
  // src/version.ts
1894
- var version = "3.0.0";
1983
+ var version = "3.1.0";
1895
1984
 
1896
1985
  // src/call-log.ts
1897
1986
  function parseCallLogBody(body) {