@poolse/sdk 3.0.0 → 3.2.0-dev.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
@@ -574,6 +574,25 @@ interface MessageDeletedEvent {
574
574
  conversation_id: Uuid;
575
575
  deleted_at: string | null;
576
576
  }
577
+ /**
578
+ * `message:stream` — an AI agent's reply as it's being written.
579
+ *
580
+ * * `started`: the agent began writing (carries `sender_external_id`).
581
+ * * `delta`: the next piece of text; append it.
582
+ * * `failed`: the agent couldn't answer; nothing will be posted.
583
+ *
584
+ * The finished reply arrives as a normal `message:new` whose `id`
585
+ * equals the stream's `id`, so swap the streaming bubble for it.
586
+ */
587
+ interface MessageStreamEvent {
588
+ id: Uuid;
589
+ conversation_id: Uuid;
590
+ sender_id: Uuid;
591
+ status: 'started' | 'delta' | 'failed';
592
+ sender_external_id?: string | null;
593
+ delta?: string;
594
+ error?: string;
595
+ }
577
596
  /** `typing:start` / `typing:stop`. */
578
597
  interface TypingEvent {
579
598
  /** Internal poolse user id. Most consumer code uses `external_id` instead. */
@@ -618,8 +637,23 @@ interface CallFinishedEvent {
618
637
  ended_at?: string;
619
638
  duration_ms?: number;
620
639
  joined_user_ids?: Uuid[];
621
- /** `finished` | `declined_all` | `no_answer` | `cancelled`. */
640
+ /** `finished` | `declined_all` | `busy_all` | `no_answer` | `cancelled`. */
622
641
  reason?: string;
642
+ /** Present on the `user:<id>` copy (`UserChannel.onCallFinished`). */
643
+ conversation_id?: Uuid;
644
+ }
645
+ /**
646
+ * Your ring for a call is over (`call:ring_ended` on `user:<id>`): stop
647
+ * ringing on this device.
648
+ */
649
+ interface RingEndedEvent {
650
+ cv: number;
651
+ call_id: string;
652
+ conversation_id: Uuid;
653
+ /** `answered_elsewhere` | `declined` | `cancelled` | `timeout` | `finished`. */
654
+ reason: string;
655
+ /** The device that resolved the ring (e.g. the one that answered), so it can ignore this. */
656
+ device_id?: string;
623
657
  }
624
658
  /** Per-user mention push on the `user:<id>` channel. */
625
659
  interface MentionEvent {
@@ -689,6 +723,8 @@ declare class PoolseRealtime {
689
723
  private readonly conversations;
690
724
  private userChannel;
691
725
  private status;
726
+ private paused;
727
+ private lastTokenRefreshMs;
692
728
  private readonly statusListeners;
693
729
  constructor(config: ResolvedConfig, tokenCache: TokenCache, opts?: RealtimeOptions);
694
730
  /** Current connection status. */
@@ -721,6 +757,15 @@ declare class PoolseRealtime {
721
757
  * the cache can re-fill on the next iteration.
722
758
  */
723
759
  connect(): void;
760
+ /**
761
+ * Close the socket but keep every channel handle and its listeners
762
+ * (for an app going to the background). `resume()` reopens it and
763
+ * Phoenix rejoins the channels. Events sent in between are not
764
+ * replayed; the React hooks reload from REST on reconnect.
765
+ */
766
+ pause(): void;
767
+ /** Reopen a socket closed by `pause()`, with a fresh token. */
768
+ resume(): void;
724
769
  /** Close the socket and tear down every joined channel. */
725
770
  disconnect(): void;
726
771
  /**
@@ -744,13 +789,16 @@ declare class ConversationChannel {
744
789
  private readonly listeners;
745
790
  private presenceState;
746
791
  private presenceStateSeen;
747
- constructor(conversationId: string, channel: Channel);
792
+ private readonly closedListeners;
793
+ constructor(conversationId: string, channel: Channel, onGone?: () => void);
748
794
  /** New message pushed to the conversation. */
749
795
  onMessage(fn: (msg: MessageNewEvent) => void): Unsubscribe$1;
750
796
  /** Existing message edited by its sender. */
751
797
  onMessageUpdated(fn: (msg: MessageUpdatedEvent) => void): Unsubscribe$1;
752
798
  /** Tombstone for a soft-deleted message. */
753
799
  onMessageDeleted(fn: (evt: MessageDeletedEvent) => void): Unsubscribe$1;
800
+ /** An AI agent's reply as it's written (`message:stream`); see `MessageStreamEvent`. */
801
+ onMessageStream(fn: (evt: MessageStreamEvent) => void): Unsubscribe$1;
754
802
  onTypingStart(fn: (evt: TypingEvent) => void): Unsubscribe$1;
755
803
  onTypingStop(fn: (evt: TypingEvent) => void): Unsubscribe$1;
756
804
  onReactionAdded(fn: (evt: ReactionEvent) => void): Unsubscribe$1;
@@ -768,6 +816,13 @@ declare class ConversationChannel {
768
816
  onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
769
817
  onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe$1;
770
818
  onPresenceDiff(fn: (diff: PresenceSnapshot) => void): Unsubscribe$1;
819
+ /**
820
+ * The channel closed for good: the server removed you from the
821
+ * conversation, or `leave()` / `disconnect()` was called. No more
822
+ * events arrive on this handle; `realtime.conversation(id)` returns a
823
+ * fresh one.
824
+ */
825
+ onClosed(fn: () => void): Unsubscribe$1;
771
826
  /** Current presence snapshot for sync access — usually used in tests. */
772
827
  getPresenceState(): PresenceSnapshot;
773
828
  /** Send a typing ping to the server. Debounced server-side. */
@@ -787,6 +842,7 @@ declare class UserChannel {
787
842
  private mentionBound;
788
843
  private conversationCreatedBound;
789
844
  private conversationUpdatedBound;
845
+ private readonly listeners;
790
846
  constructor(userId: string, channel: Channel);
791
847
  /**
792
848
  * The underlying Phoenix channel, for hosts that listen to events the
@@ -817,10 +873,22 @@ declare class UserChannel {
817
873
  * your own outbound messages out of your unread count.
818
874
  */
819
875
  onConversationUpdated(fn: (evt: ConversationUpdatedEvent) => void): Unsubscribe$1;
876
+ /**
877
+ * Your ring for a call ended — answered on another device, declined,
878
+ * cancelled by the caller or timed out. Stop ringing on this device.
879
+ */
880
+ onRingEnded(fn: (evt: RingEndedEvent) => void): Unsubscribe$1;
881
+ /**
882
+ * A call you were part of (rung or joined) is over. Arrives on the
883
+ * user channel, which the app stays joined to even after leaving the
884
+ * conversation's channel mid-call.
885
+ */
886
+ onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
820
887
  /** @internal */
821
888
  _join(): void;
822
889
  /** @internal */
823
890
  _destroy(): void;
891
+ private subscribe;
824
892
  }
825
893
 
826
894
  /** Input accepted by {@link AttachmentsResource.upload}. */
@@ -900,7 +968,7 @@ declare class AttachmentsResource {
900
968
  * });
901
969
  * await chat.conversations.one(convId).messages.send({
902
970
  * body: 'Look at this!',
903
- * custom_data: { attachment_id: att.id },
971
+ * attachment_ids: [att.id],
904
972
  * });
905
973
  * ```
906
974
  *
@@ -1407,8 +1475,8 @@ interface CallRoomOptions {
1407
1475
  * Resolves SFU credentials for this conversation.
1408
1476
  *
1409
1477
  * 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.
1478
+ * answers 503): calls are unavailable, which callers show as such
1479
+ * rather than as an error.
1412
1480
  */
1413
1481
  tokenProvider: () => Promise<CallConnection | null>;
1414
1482
  /** Publish the camera on join. Audio calls start with it off. */
@@ -1447,10 +1515,10 @@ declare class CallTokensResource {
1447
1515
  /**
1448
1516
  * POST /v1/conversations/:conversationId/call-token
1449
1517
  *
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.
1518
+ * Resolves `null` when the deployment has no SFU configured (503):
1519
+ * calls are unavailable there, which the caller shows as such rather
1520
+ * than as a failed call. A 403 still throws: that one really is a
1521
+ * refusal.
1454
1522
  */
1455
1523
  create(conversationId: string, signal?: AbortSignal): Promise<CallConnection | null>;
1456
1524
  }
@@ -1567,8 +1635,8 @@ declare class CallRoom {
1567
1635
  * Connect to the SFU.
1568
1636
  *
1569
1637
  * 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.
1638
+ * has no SFU — calls are unavailable there; show that rather than a
1639
+ * failed call.
1572
1640
  */
1573
1641
  join(): Promise<boolean>;
1574
1642
  /** Release one holder; disconnects once none are left. */
@@ -1725,7 +1793,7 @@ declare class Poolse {
1725
1793
  *
1726
1794
  * import * as livekit from 'livekit-client';
1727
1795
  * const call = poolse.call(conversationId, { livekit, video: true });
1728
- * const usingSfu = await call.join(); // false = no SFU, use the mesh
1796
+ * const joined = await call.join(); // false = calls aren't available on this deployment
1729
1797
  */
1730
1798
  call(conversationId: string, opts: Omit<CallRoomOptions, 'tokenProvider'> & Partial<Pick<CallRoomOptions, 'tokenProvider'>>): CallRoom;
1731
1799
  /**
@@ -1791,7 +1859,7 @@ declare class AuthError extends ApiError {
1791
1859
  */
1792
1860
  type CallMedia = 'audio' | 'video';
1793
1861
 
1794
- declare const version = "3.0.0";
1862
+ declare const version = "3.2.0-dev.0";
1795
1863
 
1796
1864
  type CallLogMedia = 'audio' | 'video';
1797
1865
  /** What became of one person a call involved (the caller excluded). */
@@ -1903,4 +1971,4 @@ declare function formatCallLogPreview(preview: string | null | undefined, curren
1903
1971
 
1904
1972
  declare function safeUuid(): string;
1905
1973
 
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 };
1974
+ 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 MessageStreamEvent, 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
@@ -574,6 +574,25 @@ interface MessageDeletedEvent {
574
574
  conversation_id: Uuid;
575
575
  deleted_at: string | null;
576
576
  }
577
+ /**
578
+ * `message:stream` — an AI agent's reply as it's being written.
579
+ *
580
+ * * `started`: the agent began writing (carries `sender_external_id`).
581
+ * * `delta`: the next piece of text; append it.
582
+ * * `failed`: the agent couldn't answer; nothing will be posted.
583
+ *
584
+ * The finished reply arrives as a normal `message:new` whose `id`
585
+ * equals the stream's `id`, so swap the streaming bubble for it.
586
+ */
587
+ interface MessageStreamEvent {
588
+ id: Uuid;
589
+ conversation_id: Uuid;
590
+ sender_id: Uuid;
591
+ status: 'started' | 'delta' | 'failed';
592
+ sender_external_id?: string | null;
593
+ delta?: string;
594
+ error?: string;
595
+ }
577
596
  /** `typing:start` / `typing:stop`. */
578
597
  interface TypingEvent {
579
598
  /** Internal poolse user id. Most consumer code uses `external_id` instead. */
@@ -618,8 +637,23 @@ interface CallFinishedEvent {
618
637
  ended_at?: string;
619
638
  duration_ms?: number;
620
639
  joined_user_ids?: Uuid[];
621
- /** `finished` | `declined_all` | `no_answer` | `cancelled`. */
640
+ /** `finished` | `declined_all` | `busy_all` | `no_answer` | `cancelled`. */
622
641
  reason?: string;
642
+ /** Present on the `user:<id>` copy (`UserChannel.onCallFinished`). */
643
+ conversation_id?: Uuid;
644
+ }
645
+ /**
646
+ * Your ring for a call is over (`call:ring_ended` on `user:<id>`): stop
647
+ * ringing on this device.
648
+ */
649
+ interface RingEndedEvent {
650
+ cv: number;
651
+ call_id: string;
652
+ conversation_id: Uuid;
653
+ /** `answered_elsewhere` | `declined` | `cancelled` | `timeout` | `finished`. */
654
+ reason: string;
655
+ /** The device that resolved the ring (e.g. the one that answered), so it can ignore this. */
656
+ device_id?: string;
623
657
  }
624
658
  /** Per-user mention push on the `user:<id>` channel. */
625
659
  interface MentionEvent {
@@ -689,6 +723,8 @@ declare class PoolseRealtime {
689
723
  private readonly conversations;
690
724
  private userChannel;
691
725
  private status;
726
+ private paused;
727
+ private lastTokenRefreshMs;
692
728
  private readonly statusListeners;
693
729
  constructor(config: ResolvedConfig, tokenCache: TokenCache, opts?: RealtimeOptions);
694
730
  /** Current connection status. */
@@ -721,6 +757,15 @@ declare class PoolseRealtime {
721
757
  * the cache can re-fill on the next iteration.
722
758
  */
723
759
  connect(): void;
760
+ /**
761
+ * Close the socket but keep every channel handle and its listeners
762
+ * (for an app going to the background). `resume()` reopens it and
763
+ * Phoenix rejoins the channels. Events sent in between are not
764
+ * replayed; the React hooks reload from REST on reconnect.
765
+ */
766
+ pause(): void;
767
+ /** Reopen a socket closed by `pause()`, with a fresh token. */
768
+ resume(): void;
724
769
  /** Close the socket and tear down every joined channel. */
725
770
  disconnect(): void;
726
771
  /**
@@ -744,13 +789,16 @@ declare class ConversationChannel {
744
789
  private readonly listeners;
745
790
  private presenceState;
746
791
  private presenceStateSeen;
747
- constructor(conversationId: string, channel: Channel);
792
+ private readonly closedListeners;
793
+ constructor(conversationId: string, channel: Channel, onGone?: () => void);
748
794
  /** New message pushed to the conversation. */
749
795
  onMessage(fn: (msg: MessageNewEvent) => void): Unsubscribe$1;
750
796
  /** Existing message edited by its sender. */
751
797
  onMessageUpdated(fn: (msg: MessageUpdatedEvent) => void): Unsubscribe$1;
752
798
  /** Tombstone for a soft-deleted message. */
753
799
  onMessageDeleted(fn: (evt: MessageDeletedEvent) => void): Unsubscribe$1;
800
+ /** An AI agent's reply as it's written (`message:stream`); see `MessageStreamEvent`. */
801
+ onMessageStream(fn: (evt: MessageStreamEvent) => void): Unsubscribe$1;
754
802
  onTypingStart(fn: (evt: TypingEvent) => void): Unsubscribe$1;
755
803
  onTypingStop(fn: (evt: TypingEvent) => void): Unsubscribe$1;
756
804
  onReactionAdded(fn: (evt: ReactionEvent) => void): Unsubscribe$1;
@@ -768,6 +816,13 @@ declare class ConversationChannel {
768
816
  onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
769
817
  onPresenceState(fn: (state: PresenceSnapshot) => void): Unsubscribe$1;
770
818
  onPresenceDiff(fn: (diff: PresenceSnapshot) => void): Unsubscribe$1;
819
+ /**
820
+ * The channel closed for good: the server removed you from the
821
+ * conversation, or `leave()` / `disconnect()` was called. No more
822
+ * events arrive on this handle; `realtime.conversation(id)` returns a
823
+ * fresh one.
824
+ */
825
+ onClosed(fn: () => void): Unsubscribe$1;
771
826
  /** Current presence snapshot for sync access — usually used in tests. */
772
827
  getPresenceState(): PresenceSnapshot;
773
828
  /** Send a typing ping to the server. Debounced server-side. */
@@ -787,6 +842,7 @@ declare class UserChannel {
787
842
  private mentionBound;
788
843
  private conversationCreatedBound;
789
844
  private conversationUpdatedBound;
845
+ private readonly listeners;
790
846
  constructor(userId: string, channel: Channel);
791
847
  /**
792
848
  * The underlying Phoenix channel, for hosts that listen to events the
@@ -817,10 +873,22 @@ declare class UserChannel {
817
873
  * your own outbound messages out of your unread count.
818
874
  */
819
875
  onConversationUpdated(fn: (evt: ConversationUpdatedEvent) => void): Unsubscribe$1;
876
+ /**
877
+ * Your ring for a call ended — answered on another device, declined,
878
+ * cancelled by the caller or timed out. Stop ringing on this device.
879
+ */
880
+ onRingEnded(fn: (evt: RingEndedEvent) => void): Unsubscribe$1;
881
+ /**
882
+ * A call you were part of (rung or joined) is over. Arrives on the
883
+ * user channel, which the app stays joined to even after leaving the
884
+ * conversation's channel mid-call.
885
+ */
886
+ onCallFinished(fn: (evt: CallFinishedEvent) => void): Unsubscribe$1;
820
887
  /** @internal */
821
888
  _join(): void;
822
889
  /** @internal */
823
890
  _destroy(): void;
891
+ private subscribe;
824
892
  }
825
893
 
826
894
  /** Input accepted by {@link AttachmentsResource.upload}. */
@@ -900,7 +968,7 @@ declare class AttachmentsResource {
900
968
  * });
901
969
  * await chat.conversations.one(convId).messages.send({
902
970
  * body: 'Look at this!',
903
- * custom_data: { attachment_id: att.id },
971
+ * attachment_ids: [att.id],
904
972
  * });
905
973
  * ```
906
974
  *
@@ -1407,8 +1475,8 @@ interface CallRoomOptions {
1407
1475
  * Resolves SFU credentials for this conversation.
1408
1476
  *
1409
1477
  * 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.
1478
+ * answers 503): calls are unavailable, which callers show as such
1479
+ * rather than as an error.
1412
1480
  */
1413
1481
  tokenProvider: () => Promise<CallConnection | null>;
1414
1482
  /** Publish the camera on join. Audio calls start with it off. */
@@ -1447,10 +1515,10 @@ declare class CallTokensResource {
1447
1515
  /**
1448
1516
  * POST /v1/conversations/:conversationId/call-token
1449
1517
  *
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.
1518
+ * Resolves `null` when the deployment has no SFU configured (503):
1519
+ * calls are unavailable there, which the caller shows as such rather
1520
+ * than as a failed call. A 403 still throws: that one really is a
1521
+ * refusal.
1454
1522
  */
1455
1523
  create(conversationId: string, signal?: AbortSignal): Promise<CallConnection | null>;
1456
1524
  }
@@ -1567,8 +1635,8 @@ declare class CallRoom {
1567
1635
  * Connect to the SFU.
1568
1636
  *
1569
1637
  * 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.
1638
+ * has no SFU — calls are unavailable there; show that rather than a
1639
+ * failed call.
1572
1640
  */
1573
1641
  join(): Promise<boolean>;
1574
1642
  /** Release one holder; disconnects once none are left. */
@@ -1725,7 +1793,7 @@ declare class Poolse {
1725
1793
  *
1726
1794
  * import * as livekit from 'livekit-client';
1727
1795
  * const call = poolse.call(conversationId, { livekit, video: true });
1728
- * const usingSfu = await call.join(); // false = no SFU, use the mesh
1796
+ * const joined = await call.join(); // false = calls aren't available on this deployment
1729
1797
  */
1730
1798
  call(conversationId: string, opts: Omit<CallRoomOptions, 'tokenProvider'> & Partial<Pick<CallRoomOptions, 'tokenProvider'>>): CallRoom;
1731
1799
  /**
@@ -1791,7 +1859,7 @@ declare class AuthError extends ApiError {
1791
1859
  */
1792
1860
  type CallMedia = 'audio' | 'video';
1793
1861
 
1794
- declare const version = "3.0.0";
1862
+ declare const version = "3.2.0-dev.0";
1795
1863
 
1796
1864
  type CallLogMedia = 'audio' | 'video';
1797
1865
  /** What became of one person a call involved (the caller excluded). */
@@ -1903,4 +1971,4 @@ declare function formatCallLogPreview(preview: string | null | undefined, curren
1903
1971
 
1904
1972
  declare function safeUuid(): string;
1905
1973
 
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 };
1974
+ 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 MessageStreamEvent, 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;
@@ -284,6 +329,10 @@ var ConversationChannel = class {
284
329
  onMessageDeleted(fn) {
285
330
  return this.subscribe("message:deleted", fn);
286
331
  }
332
+ /** An AI agent's reply as it's written (`message:stream`); see `MessageStreamEvent`. */
333
+ onMessageStream(fn) {
334
+ return this.subscribe("message:stream", fn);
335
+ }
287
336
  onTypingStart(fn) {
288
337
  return this.subscribe("typing:start", fn);
289
338
  }
@@ -330,6 +379,18 @@ var ConversationChannel = class {
330
379
  onPresenceDiff(fn) {
331
380
  return this.subscribe("presence_diff", fn);
332
381
  }
382
+ /**
383
+ * The channel closed for good: the server removed you from the
384
+ * conversation, or `leave()` / `disconnect()` was called. No more
385
+ * events arrive on this handle; `realtime.conversation(id)` returns a
386
+ * fresh one.
387
+ */
388
+ onClosed(fn) {
389
+ this.closedListeners.add(fn);
390
+ return () => {
391
+ this.closedListeners.delete(fn);
392
+ };
393
+ }
333
394
  /** Current presence snapshot for sync access — usually used in tests. */
334
395
  getPresenceState() {
335
396
  return this.presenceState;
@@ -372,6 +433,8 @@ var UserChannel = class {
372
433
  mentionBound = false;
373
434
  conversationCreatedBound = false;
374
435
  conversationUpdatedBound = false;
436
+ // One Phoenix binding per event, fanned out — as in ConversationChannel.
437
+ listeners = /* @__PURE__ */ new Map();
375
438
  constructor(userId, channel) {
376
439
  this.userId = userId;
377
440
  this.channel = channel;
@@ -440,17 +503,47 @@ var UserChannel = class {
440
503
  this.conversationUpdatedListeners.delete(fn);
441
504
  };
442
505
  }
506
+ /**
507
+ * Your ring for a call ended — answered on another device, declined,
508
+ * cancelled by the caller or timed out. Stop ringing on this device.
509
+ */
510
+ onRingEnded(fn) {
511
+ return this.subscribe("call:ring_ended", fn);
512
+ }
513
+ /**
514
+ * A call you were part of (rung or joined) is over. Arrives on the
515
+ * user channel, which the app stays joined to even after leaving the
516
+ * conversation's channel mid-call.
517
+ */
518
+ onCallFinished(fn) {
519
+ return this.subscribe("call:finished", fn);
520
+ }
443
521
  /** @internal */
444
522
  _join() {
445
523
  this.channel.join();
446
524
  }
447
525
  /** @internal */
448
526
  _destroy() {
527
+ this.listeners.clear();
449
528
  this.mentionListeners.clear();
450
529
  this.conversationCreatedListeners.clear();
451
530
  this.conversationUpdatedListeners.clear();
452
531
  this.channel.leave();
453
532
  }
533
+ subscribe(event, fn) {
534
+ let set = this.listeners.get(event);
535
+ if (!set) {
536
+ set = /* @__PURE__ */ new Set();
537
+ this.listeners.set(event, set);
538
+ this.channel.on(event, (payload) => {
539
+ this.listeners.get(event)?.forEach((l) => l(payload));
540
+ });
541
+ }
542
+ set.add(fn);
543
+ return () => {
544
+ set.delete(fn);
545
+ };
546
+ }
454
547
  };
455
548
  function deriveWsUrl(apiUrl) {
456
549
  return apiUrl.replace(/^http/, "ws");
@@ -502,7 +595,7 @@ var AttachmentsResource = class {
502
595
  * });
503
596
  * await chat.conversations.one(convId).messages.send({
504
597
  * body: 'Look at this!',
505
- * custom_data: { attachment_id: att.id },
598
+ * attachment_ids: [att.id],
506
599
  * });
507
600
  * ```
508
601
  *
@@ -1024,10 +1117,10 @@ var CallTokensResource = class {
1024
1117
  /**
1025
1118
  * POST /v1/conversations/:conversationId/call-token
1026
1119
  *
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.
1120
+ * Resolves `null` when the deployment has no SFU configured (503):
1121
+ * calls are unavailable there, which the caller shows as such rather
1122
+ * than as a failed call. A 403 still throws: that one really is a
1123
+ * refusal.
1031
1124
  */
1032
1125
  async create(conversationId, signal) {
1033
1126
  try {
@@ -1129,7 +1222,7 @@ var CallRoom = class {
1129
1222
  room = null;
1130
1223
  status = "idle";
1131
1224
  selfId = null;
1132
- // Reference counted like VoiceRoom: a call screen and a roster can
1225
+ // Reference counted: a call screen and a roster can
1133
1226
  // both hold the same call, and the second holder must not open a
1134
1227
  // second SFU connection or tear the first one down on leaving.
1135
1228
  holders = 0;
@@ -1218,8 +1311,8 @@ var CallRoom = class {
1218
1311
  * Connect to the SFU.
1219
1312
  *
1220
1313
  * 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.
1314
+ * has no SFU — calls are unavailable there; show that rather than a
1315
+ * failed call.
1223
1316
  */
1224
1317
  async join() {
1225
1318
  if (this.room) {
@@ -1871,7 +1964,7 @@ var Poolse = class {
1871
1964
  *
1872
1965
  * import * as livekit from 'livekit-client';
1873
1966
  * const call = poolse.call(conversationId, { livekit, video: true });
1874
- * const usingSfu = await call.join(); // false = no SFU, use the mesh
1967
+ * const joined = await call.join(); // false = calls aren't available on this deployment
1875
1968
  */
1876
1969
  call(conversationId, opts) {
1877
1970
  return new CallRoom({
@@ -1891,7 +1984,7 @@ var Poolse = class {
1891
1984
  };
1892
1985
 
1893
1986
  // src/version.ts
1894
- var version = "3.0.0";
1987
+ var version = "3.2.0-dev.0";
1895
1988
 
1896
1989
  // src/call-log.ts
1897
1990
  function parseCallLogBody(body) {