@poolse/sdk 2.26.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
@@ -527,7 +527,7 @@ interface LiveCallMember {
527
527
  display_name: string | null;
528
528
  }
529
529
  /**
530
- * The call running on a conversation right now (CONTRACT.md §4.2's
530
+ * The call running on a conversation right now (CALL_CONTRACT.md §4.2's
531
531
  * CallSummary). `participants` is who is in the room at this moment.
532
532
  */
533
533
  interface LiveCall {
@@ -547,6 +547,10 @@ interface LiveCall {
547
547
  * | `declined` | `missed` (rang out unanswered).
548
548
  */
549
549
  ring_states: Record<string, 'ringing' | 'answered' | 'declined' | 'missed'>;
550
+ /** The workspace's call limits (dashboard → Calls). False: hide the camera button. */
551
+ video_allowed?: boolean;
552
+ /** How many people the call holds; one more joining is refused with `call_full`. */
553
+ max_participants?: number;
550
554
  }
551
555
  /**
552
556
  * `/v1/conversations/:id/call` — whether a call is running on a
@@ -614,8 +618,23 @@ interface CallFinishedEvent {
614
618
  ended_at?: string;
615
619
  duration_ms?: number;
616
620
  joined_user_ids?: Uuid[];
617
- /** `finished` | `declined_all` | `no_answer` | `cancelled`. */
621
+ /** `finished` | `declined_all` | `busy_all` | `no_answer` | `cancelled`. */
618
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;
619
638
  }
620
639
  /** Per-user mention push on the `user:<id>` channel. */
621
640
  interface MentionEvent {
@@ -685,6 +704,8 @@ declare class PoolseRealtime {
685
704
  private readonly conversations;
686
705
  private userChannel;
687
706
  private status;
707
+ private paused;
708
+ private lastTokenRefreshMs;
688
709
  private readonly statusListeners;
689
710
  constructor(config: ResolvedConfig, tokenCache: TokenCache, opts?: RealtimeOptions);
690
711
  /** Current connection status. */
@@ -717,6 +738,15 @@ declare class PoolseRealtime {
717
738
  * the cache can re-fill on the next iteration.
718
739
  */
719
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;
720
750
  /** Close the socket and tear down every joined channel. */
721
751
  disconnect(): void;
722
752
  /**
@@ -740,7 +770,8 @@ declare class ConversationChannel {
740
770
  private readonly listeners;
741
771
  private presenceState;
742
772
  private presenceStateSeen;
743
- constructor(conversationId: string, channel: Channel);
773
+ private readonly closedListeners;
774
+ constructor(conversationId: string, channel: Channel, onGone?: () => void);
744
775
  /** New message pushed to the conversation. */
745
776
  onMessage(fn: (msg: MessageNewEvent) => void): Unsubscribe$1;
746
777
  /** Existing message edited by its sender. */
@@ -764,6 +795,13 @@ declare class ConversationChannel {
764
795
  onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
765
796
  onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe$1;
766
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;
767
805
  /** Current presence snapshot for sync access — usually used in tests. */
768
806
  getPresenceState(): PresenceSnapshot;
769
807
  /** Send a typing ping to the server. Debounced server-side. */
@@ -783,6 +821,7 @@ declare class UserChannel {
783
821
  private mentionBound;
784
822
  private conversationCreatedBound;
785
823
  private conversationUpdatedBound;
824
+ private readonly listeners;
786
825
  constructor(userId: string, channel: Channel);
787
826
  /**
788
827
  * The underlying Phoenix channel, for hosts that listen to events the
@@ -813,10 +852,22 @@ declare class UserChannel {
813
852
  * your own outbound messages out of your unread count.
814
853
  */
815
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;
816
866
  /** @internal */
817
867
  _join(): void;
818
868
  /** @internal */
819
869
  _destroy(): void;
870
+ private subscribe;
820
871
  }
821
872
 
822
873
  /** Input accepted by {@link AttachmentsResource.upload}. */
@@ -896,7 +947,7 @@ declare class AttachmentsResource {
896
947
  * });
897
948
  * await chat.conversations.one(convId).messages.send({
898
949
  * body: 'Look at this!',
899
- * custom_data: { attachment_id: att.id },
950
+ * attachment_ids: [att.id],
900
951
  * });
901
952
  * ```
902
953
  *
@@ -1403,8 +1454,8 @@ interface CallRoomOptions {
1403
1454
  * Resolves SFU credentials for this conversation.
1404
1455
  *
1405
1456
  * Returning `null` means the deployment has no SFU configured (the API
1406
- * answers 503), which callers treat as "fall back to the mesh" rather
1407
- * than as an error.
1457
+ * answers 503): calls are unavailable, which callers show as such
1458
+ * rather than as an error.
1408
1459
  */
1409
1460
  tokenProvider: () => Promise<CallConnection | null>;
1410
1461
  /** Publish the camera on join. Audio calls start with it off. */
@@ -1443,10 +1494,10 @@ declare class CallTokensResource {
1443
1494
  /**
1444
1495
  * POST /v1/conversations/:conversationId/call-token
1445
1496
  *
1446
- * Resolves `null` when the deployment has no SFU configured (503).
1447
- * That is deliberately not an error — the caller falls back to the
1448
- * peer-to-peer mesh, which is how every call worked before the SFU
1449
- * 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.
1450
1501
  */
1451
1502
  create(conversationId: string, signal?: AbortSignal): Promise<CallConnection | null>;
1452
1503
  }
@@ -1563,8 +1614,8 @@ declare class CallRoom {
1563
1614
  * Connect to the SFU.
1564
1615
  *
1565
1616
  * Resolves `true` once media is flowing, `false` when the deployment
1566
- * has no SFU — the caller should fall back to the mesh rather than
1567
- * treat that as a failed call.
1617
+ * has no SFU — calls are unavailable there; show that rather than a
1618
+ * failed call.
1568
1619
  */
1569
1620
  join(): Promise<boolean>;
1570
1621
  /** Release one holder; disconnects once none are left. */
@@ -1721,7 +1772,7 @@ declare class Poolse {
1721
1772
  *
1722
1773
  * import * as livekit from 'livekit-client';
1723
1774
  * const call = poolse.call(conversationId, { livekit, video: true });
1724
- * 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
1725
1776
  */
1726
1777
  call(conversationId: string, opts: Omit<CallRoomOptions, 'tokenProvider'> & Partial<Pick<CallRoomOptions, 'tokenProvider'>>): CallRoom;
1727
1778
  /**
@@ -1787,7 +1838,7 @@ declare class AuthError extends ApiError {
1787
1838
  */
1788
1839
  type CallMedia = 'audio' | 'video';
1789
1840
 
1790
- declare const version = "2.26.0";
1841
+ declare const version = "3.1.0";
1791
1842
 
1792
1843
  type CallLogMedia = 'audio' | 'video';
1793
1844
  /** What became of one person a call involved (the caller excluded). */
@@ -1899,4 +1950,4 @@ declare function formatCallLogPreview(preview: string | null | undefined, curren
1899
1950
 
1900
1951
  declare function safeUuid(): string;
1901
1952
 
1902
- 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
@@ -527,7 +527,7 @@ interface LiveCallMember {
527
527
  display_name: string | null;
528
528
  }
529
529
  /**
530
- * The call running on a conversation right now (CONTRACT.md §4.2's
530
+ * The call running on a conversation right now (CALL_CONTRACT.md §4.2's
531
531
  * CallSummary). `participants` is who is in the room at this moment.
532
532
  */
533
533
  interface LiveCall {
@@ -547,6 +547,10 @@ interface LiveCall {
547
547
  * | `declined` | `missed` (rang out unanswered).
548
548
  */
549
549
  ring_states: Record<string, 'ringing' | 'answered' | 'declined' | 'missed'>;
550
+ /** The workspace's call limits (dashboard → Calls). False: hide the camera button. */
551
+ video_allowed?: boolean;
552
+ /** How many people the call holds; one more joining is refused with `call_full`. */
553
+ max_participants?: number;
550
554
  }
551
555
  /**
552
556
  * `/v1/conversations/:id/call` — whether a call is running on a
@@ -614,8 +618,23 @@ interface CallFinishedEvent {
614
618
  ended_at?: string;
615
619
  duration_ms?: number;
616
620
  joined_user_ids?: Uuid[];
617
- /** `finished` | `declined_all` | `no_answer` | `cancelled`. */
621
+ /** `finished` | `declined_all` | `busy_all` | `no_answer` | `cancelled`. */
618
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;
619
638
  }
620
639
  /** Per-user mention push on the `user:<id>` channel. */
621
640
  interface MentionEvent {
@@ -685,6 +704,8 @@ declare class PoolseRealtime {
685
704
  private readonly conversations;
686
705
  private userChannel;
687
706
  private status;
707
+ private paused;
708
+ private lastTokenRefreshMs;
688
709
  private readonly statusListeners;
689
710
  constructor(config: ResolvedConfig, tokenCache: TokenCache, opts?: RealtimeOptions);
690
711
  /** Current connection status. */
@@ -717,6 +738,15 @@ declare class PoolseRealtime {
717
738
  * the cache can re-fill on the next iteration.
718
739
  */
719
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;
720
750
  /** Close the socket and tear down every joined channel. */
721
751
  disconnect(): void;
722
752
  /**
@@ -740,7 +770,8 @@ declare class ConversationChannel {
740
770
  private readonly listeners;
741
771
  private presenceState;
742
772
  private presenceStateSeen;
743
- constructor(conversationId: string, channel: Channel);
773
+ private readonly closedListeners;
774
+ constructor(conversationId: string, channel: Channel, onGone?: () => void);
744
775
  /** New message pushed to the conversation. */
745
776
  onMessage(fn: (msg: MessageNewEvent) => void): Unsubscribe$1;
746
777
  /** Existing message edited by its sender. */
@@ -764,6 +795,13 @@ declare class ConversationChannel {
764
795
  onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
765
796
  onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe$1;
766
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;
767
805
  /** Current presence snapshot for sync access — usually used in tests. */
768
806
  getPresenceState(): PresenceSnapshot;
769
807
  /** Send a typing ping to the server. Debounced server-side. */
@@ -783,6 +821,7 @@ declare class UserChannel {
783
821
  private mentionBound;
784
822
  private conversationCreatedBound;
785
823
  private conversationUpdatedBound;
824
+ private readonly listeners;
786
825
  constructor(userId: string, channel: Channel);
787
826
  /**
788
827
  * The underlying Phoenix channel, for hosts that listen to events the
@@ -813,10 +852,22 @@ declare class UserChannel {
813
852
  * your own outbound messages out of your unread count.
814
853
  */
815
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;
816
866
  /** @internal */
817
867
  _join(): void;
818
868
  /** @internal */
819
869
  _destroy(): void;
870
+ private subscribe;
820
871
  }
821
872
 
822
873
  /** Input accepted by {@link AttachmentsResource.upload}. */
@@ -896,7 +947,7 @@ declare class AttachmentsResource {
896
947
  * });
897
948
  * await chat.conversations.one(convId).messages.send({
898
949
  * body: 'Look at this!',
899
- * custom_data: { attachment_id: att.id },
950
+ * attachment_ids: [att.id],
900
951
  * });
901
952
  * ```
902
953
  *
@@ -1403,8 +1454,8 @@ interface CallRoomOptions {
1403
1454
  * Resolves SFU credentials for this conversation.
1404
1455
  *
1405
1456
  * Returning `null` means the deployment has no SFU configured (the API
1406
- * answers 503), which callers treat as "fall back to the mesh" rather
1407
- * than as an error.
1457
+ * answers 503): calls are unavailable, which callers show as such
1458
+ * rather than as an error.
1408
1459
  */
1409
1460
  tokenProvider: () => Promise<CallConnection | null>;
1410
1461
  /** Publish the camera on join. Audio calls start with it off. */
@@ -1443,10 +1494,10 @@ declare class CallTokensResource {
1443
1494
  /**
1444
1495
  * POST /v1/conversations/:conversationId/call-token
1445
1496
  *
1446
- * Resolves `null` when the deployment has no SFU configured (503).
1447
- * That is deliberately not an error — the caller falls back to the
1448
- * peer-to-peer mesh, which is how every call worked before the SFU
1449
- * 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.
1450
1501
  */
1451
1502
  create(conversationId: string, signal?: AbortSignal): Promise<CallConnection | null>;
1452
1503
  }
@@ -1563,8 +1614,8 @@ declare class CallRoom {
1563
1614
  * Connect to the SFU.
1564
1615
  *
1565
1616
  * Resolves `true` once media is flowing, `false` when the deployment
1566
- * has no SFU — the caller should fall back to the mesh rather than
1567
- * treat that as a failed call.
1617
+ * has no SFU — calls are unavailable there; show that rather than a
1618
+ * failed call.
1568
1619
  */
1569
1620
  join(): Promise<boolean>;
1570
1621
  /** Release one holder; disconnects once none are left. */
@@ -1721,7 +1772,7 @@ declare class Poolse {
1721
1772
  *
1722
1773
  * import * as livekit from 'livekit-client';
1723
1774
  * const call = poolse.call(conversationId, { livekit, video: true });
1724
- * 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
1725
1776
  */
1726
1777
  call(conversationId: string, opts: Omit<CallRoomOptions, 'tokenProvider'> & Partial<Pick<CallRoomOptions, 'tokenProvider'>>): CallRoom;
1727
1778
  /**
@@ -1787,7 +1838,7 @@ declare class AuthError extends ApiError {
1787
1838
  */
1788
1839
  type CallMedia = 'audio' | 'video';
1789
1840
 
1790
- declare const version = "2.26.0";
1841
+ declare const version = "3.1.0";
1791
1842
 
1792
1843
  type CallLogMedia = 'audio' | 'video';
1793
1844
  /** What became of one person a call involved (the caller excluded). */
@@ -1899,4 +1950,4 @@ declare function formatCallLogPreview(preview: string | null | undefined, curren
1899
1950
 
1900
1951
  declare function safeUuid(): string;
1901
1952
 
1902
- 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 = "2.26.0";
1983
+ var version = "3.1.0";
1895
1984
 
1896
1985
  // src/call-log.ts
1897
1986
  function parseCallLogBody(body) {