@dialtribe/chat-client 0.3.0 → 0.5.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.ts CHANGED
@@ -104,6 +104,11 @@ interface DmRoomSummary {
104
104
  /** "pending" means this is an incoming request the user hasn't answered. */
105
105
  myStatus: DmMemberStatus;
106
106
  isMuted: boolean;
107
+ /**
108
+ * Archived by the signed-in user: off their rail, kept in their inbox under
109
+ * Archived, unread still counted. Private to them. Absent on older servers.
110
+ */
111
+ isArchived?: boolean;
107
112
  /** Everyone except the signed-in user. */
108
113
  participants: DmParticipant[];
109
114
  lastMessageAt: string | null;
@@ -199,7 +204,40 @@ type UserEvent = {
199
204
  type: "chat-error";
200
205
  code: ChatErrorCode;
201
206
  message?: string;
207
+ }
208
+ /** Dialtribe Notifications: a new item for this user (unread). */
209
+ | {
210
+ type: "notification.created";
211
+ notification: NotificationItem;
212
+ unreadCount?: number;
213
+ }
214
+ /** Items were read elsewhere (another tab or device). `ids` null means all. */
215
+ | {
216
+ type: "notification.read";
217
+ ids: string[] | null;
218
+ unreadCount: number;
202
219
  };
220
+ /** One in-app notification for the signed-in user (Dialtribe Notifications). */
221
+ interface NotificationItem {
222
+ id: string;
223
+ eventType: string;
224
+ title: string;
225
+ body: string | null;
226
+ url: string | null;
227
+ imageUrl: string | null;
228
+ actor: {
229
+ userId: string | null;
230
+ name: string | null;
231
+ avatarUrl: string | null;
232
+ } | null;
233
+ /** Items sharing a groupKey are shown as one row ("and 3 others"). */
234
+ groupKey: string | null;
235
+ data: unknown;
236
+ createdAt: string;
237
+ seenAt: string | null;
238
+ readAt: string | null;
239
+ clickedAt: string | null;
240
+ }
203
241
 
204
242
  /**
205
243
  * A failed chat call: a transport failure, or a chat-ws rejection with the
@@ -305,6 +343,11 @@ declare class InboxStore extends Store<InboxSnapshot> {
305
343
  */
306
344
  hideDM(roomId: string): Promise<void>;
307
345
  setMuted(roomId: string, muted: boolean): Promise<void>;
346
+ /**
347
+ * Archive or unarchive for the signed-in user only (optimistic). The room
348
+ * leaves the rail but stays in the inbox; new messages don't unarchive it.
349
+ */
350
+ setArchived(roomId: string, archived: boolean): Promise<void>;
308
351
  /** Mark a room read now (optimistic). */
309
352
  markRead(roomId: string): Promise<void>;
310
353
  /**
@@ -322,9 +365,56 @@ declare class InboxStore extends Store<InboxSnapshot> {
322
365
  private setRooms;
323
366
  }
324
367
 
368
+ interface NotificationsSnapshot {
369
+ status: "idle" | "loading" | "ready" | "error";
370
+ /** Newest first. */
371
+ items: NotificationItem[];
372
+ unreadCount: number;
373
+ /** More older items exist (call loadMore). */
374
+ hasMore: boolean;
375
+ loadingMore: boolean;
376
+ error: ChatRequestError | null;
377
+ }
378
+ /**
379
+ * The signed-in user's notifications (Dialtribe Notifications service). Live
380
+ * via the personal channel the chat connection already holds; reconciled from
381
+ * the server on every (re)connect, so a missed event never leaves it wrong.
382
+ * Started on first `acquire()`, so apps that don't show notifications pay nothing.
383
+ */
384
+ declare class NotificationsStore extends Store<NotificationsSnapshot> {
385
+ private readonly client;
386
+ private refs;
387
+ private unlisten;
388
+ private refreshTimer;
389
+ private nextCursor;
390
+ constructor(client: ChatClient);
391
+ acquire(): void;
392
+ release(): void;
393
+ /** Reload the first page and the unread count. */
394
+ refresh(): Promise<void>;
395
+ /** Append the next (older) page. */
396
+ loadMore(): Promise<void>;
397
+ /** Mark items read (optimistic). */
398
+ markRead(ids: string[]): Promise<void>;
399
+ /** Mark everything read (optimistic). */
400
+ markAllRead(): Promise<void>;
401
+ /** Record that the list was shown (for stats; doesn't change unread). */
402
+ markSeen(): Promise<void>;
403
+ /** Record a click (also marks read). Pass every id in a grouped row. */
404
+ click(ids: string[]): Promise<void>;
405
+ private onUserEvent;
406
+ private applyRead;
407
+ private scheduleRefresh;
408
+ }
409
+
325
410
  interface ChatClientOptions {
326
411
  /** chat-ws base URL, e.g. "https://chatws.dialtribe.com". */
327
412
  serverUrl: string;
413
+ /**
414
+ * Dialtribe API base URL for services outside chat-ws (notifications).
415
+ * Defaults to "https://dialtribe.com". Uses the same session token.
416
+ */
417
+ apiUrl?: string;
328
418
  /**
329
419
  * Returns a current `sess_` token minted by the host backend for the signed-in
330
420
  * user. Called on start, and again whenever chat-ws rejects the token, so
@@ -373,6 +463,7 @@ declare class ChatClient {
373
463
  readonly connection: ConnectionStore;
374
464
  private readonly events;
375
465
  private readonly serverUrl;
466
+ private readonly apiUrl;
376
467
  private centrifuge;
377
468
  private userChannel;
378
469
  private sessionToken;
@@ -381,6 +472,7 @@ declare class ChatClient {
381
472
  private generation;
382
473
  private rooms;
383
474
  private inboxStore;
475
+ private notificationsStore;
384
476
  constructor(options: ChatClientOptions);
385
477
  /** Connect. Idempotent; resolves once the connection has been initiated. */
386
478
  start(): Promise<void>;
@@ -391,6 +483,8 @@ declare class ChatClient {
391
483
  room(roomId: string): RoomStore;
392
484
  /** The signed-in user's DM inbox (created on first use). */
393
485
  get inbox(): InboxStore;
486
+ /** The signed-in user's notifications (created on first use). */
487
+ get notifications(): NotificationsStore;
394
488
  get self(): ChatSelf | null;
395
489
  private open;
396
490
  private fetchGrant;
@@ -415,6 +509,14 @@ declare class ChatClient {
415
509
  }[];
416
510
  userCount: number;
417
511
  }>;
512
+ /**
513
+ * Authenticated JSON request to the Dialtribe API (apiUrl), with the same
514
+ * session token and 401 retry as chat-ws requests. `path` is under /api/public/v1.
515
+ */
516
+ api<T>(path: string, init?: {
517
+ method?: "GET" | "POST";
518
+ body?: unknown;
519
+ }): Promise<T>;
418
520
  /** A DM action on POST /dm (see DMS.md). */
419
521
  dm<T = Record<string, unknown>>(action: string, fields?: Record<string, unknown>): Promise<T>;
420
522
  /**
@@ -432,6 +534,10 @@ type MessagesView = {
432
534
  kind: "room";
433
535
  roomId: string;
434
536
  }
537
+ /** The built-in notifications panel (DialtribeMessages `notifications`). */
538
+ | {
539
+ kind: "notifications";
540
+ }
435
541
  /** A host-defined rail item (DialtribeMessages `items`). */
436
542
  | {
437
543
  kind: "item";
@@ -472,7 +578,7 @@ interface DialtribeChatProviderProps extends Omit<ChatClientOptions, "getSession
472
578
  * )}
473
579
  * ```
474
580
  */
475
- declare function DialtribeChatProvider({ children, getSessionToken, serverUrl, websocketUrl, websocket }: DialtribeChatProviderProps): react.JSX.Element;
581
+ declare function DialtribeChatProvider({ children, getSessionToken, serverUrl, apiUrl, websocketUrl, websocket }: DialtribeChatProviderProps): react.JSX.Element;
476
582
  /** The shared ChatClient. Must be under a <DialtribeChatProvider>. */
477
583
  declare function useChatClient(): ChatClient;
478
584
 
@@ -525,7 +631,7 @@ declare function ChatRoomProvider({ roomId, children }: ChatRoomProviderProps):
525
631
  /** The room from the nearest <ChatRoomProvider>. */
526
632
  declare function useChatRoomContext(): UseDialtribeChatReturn;
527
633
 
528
- type UseChatRoomsReturn = InboxSnapshot & Pick<InboxStore, "requestDM" | "acceptDM" | "ignoreDM" | "closeDM" | "reopenDM" | "hideDM" | "addParticipant" | "setMuted" | "markRead" | "setVisible" | "refresh">;
634
+ type UseChatRoomsReturn = InboxSnapshot & Pick<InboxStore, "requestDM" | "acceptDM" | "ignoreDM" | "closeDM" | "reopenDM" | "hideDM" | "addParticipant" | "setMuted" | "setArchived" | "markRead" | "setVisible" | "refresh">;
529
635
  /**
530
636
  * The signed-in user's DMs: inbox (newest first), incoming requests, unread
531
637
  * totals, and every DM action. Live via the personal channel; reconciled with
@@ -553,6 +659,8 @@ interface UseDialtribeMessagesReturn {
553
659
  openRoom: (roomId: string) => void;
554
660
  /** Show one of the host's own rail items (DialtribeMessages `items`) by id. */
555
661
  openItem: (itemId: string) => void;
662
+ /** Open the notifications panel (when the rail shows notifications). */
663
+ openNotifications: () => void;
556
664
  /**
557
665
  * Start (or reopen) a DM with one of your users and show it. `hint` is only a
558
666
  * display name for someone Dialtribe hasn't seen yet. Rejects with
@@ -575,6 +683,19 @@ interface UseDialtribeMessagesReturn {
575
683
  */
576
684
  declare function useDialtribeMessages(): UseDialtribeMessagesReturn;
577
685
 
686
+ type UseDialtribeNotificationsReturn = NotificationsSnapshot & Pick<NotificationsStore, "refresh" | "loadMore" | "markRead" | "markAllRead" | "markSeen" | "click">;
687
+ /**
688
+ * The signed-in user's in-app notifications (Dialtribe Notifications): newest
689
+ * first, the unread count, and the read/click actions. Live over the existing
690
+ * chat connection. Must be under a <DialtribeChatProvider>.
691
+ *
692
+ * @example
693
+ * ```tsx
694
+ * const { items, unreadCount, markAllRead } = useDialtribeNotifications();
695
+ * ```
696
+ */
697
+ declare function useDialtribeNotifications(): UseDialtribeNotificationsReturn;
698
+
578
699
  /** User-facing strings for <DialtribeMessages>. Override any via the `labels` prop. */
579
700
  interface MessagesLabels {
580
701
  messages: string;
@@ -589,16 +710,51 @@ interface MessagesLabels {
589
710
  waitingForReply: string;
590
711
  conversationClosed: string;
591
712
  reopen: string;
713
+ /** @deprecated No longer shown. Conversations are archived instead of closed. */
592
714
  closeConversation: string;
593
715
  /** Inbox row X: remove from the inbox (comes back on a new message). */
594
716
  removeConversation: string;
717
+ /** Conversation menu: mute / unmute notifications. */
595
718
  mute: string;
596
719
  unmute: string;
720
+ /** Conversation menu: archive / unarchive (private to the user). */
721
+ archive: string;
722
+ unarchive: string;
723
+ /** Inbox section for archived conversations. */
724
+ archived: string;
725
+ /** Accessible name for the conversation's kebab menu button. */
726
+ moreOptions: string;
727
+ muteConfirmTitle: (name: string) => string;
728
+ muteConfirmBody: string;
729
+ muteConfirm: string;
730
+ archiveConfirmTitle: (name: string) => string;
731
+ archiveConfirmBody: string;
732
+ archiveConfirm: string;
733
+ cancel: string;
597
734
  messagePlaceholder: string;
598
735
  openMessages: string;
736
+ /** Notifications panel and rail button. */
737
+ notifications: string;
738
+ noNotifications: string;
739
+ markAllRead: string;
740
+ loadMore: string;
741
+ /** Extra line on a grouped row: "and 3 more". */
742
+ groupMore: (count: number) => string;
743
+ /** Relative times: "now", "5m", "3h", "2d". */
744
+ timeAgo: (date: Date) => string;
599
745
  }
600
746
  declare const DEFAULT_LABELS: MessagesLabels;
601
747
 
748
+ /** What a confirmation asks. Hosts render it in their own modal via the `confirm` prop. */
749
+ interface ConfirmOptions {
750
+ title: string;
751
+ body?: string;
752
+ confirmLabel: string;
753
+ cancelLabel: string;
754
+ }
755
+ /** Resolves true when the user confirms. */
756
+ type ConfirmFn = (options: ConfirmOptions) => Promise<boolean>;
757
+
602
758
  /** A host-provided rail entry (e.g. a live show the user is watching). */
603
759
  interface MessagesContext {
604
760
  roomId: string;
@@ -664,6 +820,19 @@ interface DialtribeMessagesProps {
664
820
  railDmLimit?: number;
665
821
  /** Below this width (px) the rail collapses to a floating button + drawer. */
666
822
  mobileBreakpoint?: number;
823
+ /**
824
+ * Show confirmations (mute, archive) in your app's own modal. Resolve true to
825
+ * proceed. Without it, a built-in dialog inside the panel is used.
826
+ */
827
+ confirm?: ConfirmFn;
828
+ /**
829
+ * Show the Dialtribe Notifications inbox: a bell on the rail (above Messages)
830
+ * with an unread badge, opening the notifications panel. Pass an object to
831
+ * handle opening a notification yourself (return true when you navigated).
832
+ */
833
+ notifications?: boolean | {
834
+ onOpen?: (item: NotificationItem) => boolean | void;
835
+ };
667
836
  }
668
837
  /**
669
838
  * Drop-in messages rail: inbox, DM requests, conversations, and any host
@@ -680,7 +849,22 @@ interface DialtribeMessagesProps {
680
849
  * </DialtribeChatProvider>
681
850
  * ```
682
851
  */
683
- declare function DialtribeMessages({ side, placement, openPlacement, items, inboxRowClose, contexts, theme, labels: labelOverrides, panelWidth, railDmLimit, mobileBreakpoint, }: DialtribeMessagesProps): react.JSX.Element;
852
+ declare function DialtribeMessages({ side, placement, openPlacement, items, inboxRowClose, contexts, theme, labels: labelOverrides, panelWidth, railDmLimit, mobileBreakpoint, confirm: hostConfirm, notifications, }: DialtribeMessagesProps): react.JSX.Element;
853
+
854
+ interface NotificationsPanelProps {
855
+ labels: MessagesLabels;
856
+ onClose?: () => void;
857
+ /**
858
+ * Called when a notification is opened. Return true if you handled the
859
+ * navigation (e.g. client-side routing); otherwise the browser goes to its url.
860
+ */
861
+ onOpen?: (item: NotificationItem) => boolean | void;
862
+ }
863
+ /**
864
+ * The notifications list shown in the messages rail. Usable on its own too
865
+ * (any host panel) as long as it's under a <DialtribeChatProvider>.
866
+ */
867
+ declare function NotificationsPanel({ labels, onClose, onOpen }: NotificationsPanelProps): react.JSX.Element;
684
868
 
685
869
  interface AvatarProps {
686
870
  name: string;
@@ -759,4 +943,4 @@ interface ChatInputProps {
759
943
  */
760
944
  declare function ChatInput({ onSendMessage, onSendTyping, replyTo, onClearReply, disabled, placeholder, maxLength, }: ChatInputProps): react.JSX.Element;
761
945
 
762
- export { Avatar, type AvatarProps, ChatClient, type ChatClientOptions, type ChatErrorCode, ChatInput, type ChatInputProps, type ChatMessage, ChatMessageItem, type ChatMessageItemProps, ChatPanel, type ChatPanelProps, ChatRequestError, type ChatRoomConfig, ChatRoomProvider, type ChatRoomProviderProps, type ChatSelf, type ConnectionSnapshot, type ConnectionState, DEFAULT_LABELS, DialtribeChatProvider, type DialtribeChatProviderProps, DialtribeMessages, type DialtribeMessagesProps, type DmMemberStatus, type DmParticipant, type DmRequestResult, type DmRoomSummary, type Flair, type InboxSnapshot, type MessagesContext, type MessagesLabels, type MessagesTheme, type MessagesUiSnapshot, type MessagesView, type ParsedReactions, type RailItem, type RichMediaConfig, type RoomEvent, type RoomInit, type RoomSnapshot, type RoomState, type TypingUser, type UseChatRoomsReturn, type UseDialtribeChatOptions, type UseDialtribeChatReturn, type UseDialtribeMessagesReturn, type UserEvent, parseReactions, useChatClient, useChatConnection, useChatRoomContext, useChatRooms, useDialtribeChat, useDialtribeMessages };
946
+ export { Avatar, type AvatarProps, ChatClient, type ChatClientOptions, type ChatErrorCode, ChatInput, type ChatInputProps, type ChatMessage, ChatMessageItem, type ChatMessageItemProps, ChatPanel, type ChatPanelProps, ChatRequestError, type ChatRoomConfig, ChatRoomProvider, type ChatRoomProviderProps, type ChatSelf, type ConfirmFn, type ConfirmOptions, type ConnectionSnapshot, type ConnectionState, DEFAULT_LABELS, DialtribeChatProvider, type DialtribeChatProviderProps, DialtribeMessages, type DialtribeMessagesProps, type DmMemberStatus, type DmParticipant, type DmRequestResult, type DmRoomSummary, type Flair, type InboxSnapshot, type MessagesContext, type MessagesLabels, type MessagesTheme, type MessagesUiSnapshot, type MessagesView, type NotificationItem, NotificationsPanel, type NotificationsPanelProps, type NotificationsSnapshot, type ParsedReactions, type RailItem, type RichMediaConfig, type RoomEvent, type RoomInit, type RoomSnapshot, type RoomState, type TypingUser, type UseChatRoomsReturn, type UseDialtribeChatOptions, type UseDialtribeChatReturn, type UseDialtribeMessagesReturn, type UseDialtribeNotificationsReturn, type UserEvent, parseReactions, useChatClient, useChatConnection, useChatRoomContext, useChatRooms, useDialtribeChat, useDialtribeMessages, useDialtribeNotifications };