@convokitapp/vue-ui 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Conversation as Conversation$1, MessageListOptions, Message, SendMessageInput, MarkConversationReadOptions, RealtimeConnectionHandlers, RealtimeSubscription, MessageEvent, MessageDeletedEvent, ReadEvent, TypingEvent, ReadPosition, MessageMedia, ConvoKitClient } from '@convokitapp/sdk';
+import { Conversation as Conversation$1, InboxPage, MessageListOptions, Message, SendMessageInput, MarkConversationReadOptions, ConversationPrivateState, ClearConversationUnreadOptions, ClearUnreadResult, RealtimeConnectionHandlers, RealtimeSubscription, MessageEvent, MessageDeletedEvent, ReadEvent, TypingEvent, ReadPosition, InboxSummary, MessageMedia, ConvoKitClient, InboxEntry } from '@convokitapp/sdk';
 import * as vue from 'vue';
 import { CSSProperties, HTMLAttributes, Ref, VNodeChild, PropType, MaybeRefOrGetter, TextareaHTMLAttributes } from 'vue';
 
@@ -11,17 +11,39 @@ interface ConvoKitUiClient {
         offset: number;
         archived: boolean;
     }): Promise<Conversation$1[]>;
+    /** Activity-ordered inbox pages with a preview, unread count and read state per row (core 0.6). Pass the previous
+     * `nextCursor` back as `cursor` (null for the head). Adapters without it, and custom page loaders, use the legacy
+     * `getConversations` path without summaries; a 404 from this endpoint falls back to that path for the store's life.
+     */
+    listInbox?(options: {
+        limit: number;
+        cursor: string | null;
+        archived: boolean;
+    }): Promise<InboxPage>;
+    /** The room and, from a 0.7 core and backend, the caller's own `membership`; the room store captures
+     * `membership.privateStateVersion` once per open for that open's acknowledgements.
+     */
     getConversation(conversationId: string): Promise<Conversation$1>;
     /** Newest first, with a paired value cursor; never derive an offset from rendered rows. */
     getMessages(options: MessageListOptions): Promise<Message[]>;
     /** Complete authorized message, including related media absent from raw row events. */
     getMessage(id: string): Promise<Message>;
     sendMessage(input: SendMessageInput): Promise<Message>;
-    /** Acknowledge through `options.throughMessageId` (the newest rendered row). Custom adapters must forward it
-     * and reject a missing target with `code: 'MESSAGE_NOT_FOUND'` (or a 404 without a code); the UI never sends a
-     * request without a target. Membership failures keep their error code, if any, so they surface as errors.
+    /** Acknowledge through `options.throughMessageId` (the newest rendered row). Custom adapters must forward the
+     * options unchanged (0.7 adds `privateStateVersion`, the version captured when the room opened; an adapter that
+     * drops it acknowledges the position but never clears the caller's unread marker) and reject a missing target
+     * with `code: 'MESSAGE_NOT_FOUND'` (or a 404 without a code); the UI never sends a request without a target.
+     * Membership failures keep their error code, if any, so they surface as errors.
      */
     markConversationRead(conversationId: string, options?: MarkConversationReadOptions): Promise<void>;
+    /** Mark the room unread for the caller only (0.7.0). Optional: `markUnread` rejects without it. */
+    markConversationUnread?(conversationId: string): Promise<ConversationPrivateState>;
+    /** Remove the caller's unread marker, only while it still has `options.ifVersion` when given (0.7.0); a mismatch or
+     * an unmarked room answers `cleared: false`, never an error. Optional: `clearUnread` rejects without it, and a room
+     * opened with a marker that renders nothing leaves the marker in place (the room store clears it through this
+     * member, never through an untargeted acknowledgement).
+     */
+    clearConversationUnread?(conversationId: string, options?: ClearConversationUnreadOptions): Promise<ClearUnreadResult>;
     sendTyping(input: {
         conversationId: string;
         isTyping: boolean;
@@ -29,6 +51,11 @@ interface ConvoKitUiClient {
     onConnectionEvent(handlers: RealtimeConnectionHandlers): RealtimeSubscription;
     /** Notify on inbox mutations AND on initial subscription/reconnect. No room data in the signal. */
     onInboxChanged(handler: () => void, onError?: (error: Error) => void): RealtimeSubscription;
+    /** Message inserts/edits, read-position advances and the caller's own unread-marker changes in the caller's
+     * rooms; never fires on join/rejoin. The list store throttles these (`activityRefreshWindowMs`); room stores
+     * ignore them.
+     */
+    onInboxActivity?(handler: () => void, onError?: (error: Error) => void): RealtimeSubscription;
     onMessage(conversationId: string, handler: (event: MessageEvent) => void, onError?: (error: Error) => void): RealtimeSubscription;
     onMessageDeleted(conversationId: string, handler: (event: MessageDeletedEvent) => void, onError?: (error: Error) => void): RealtimeSubscription;
     onReadReceipt(conversationId: string, handler: (event: ReadEvent) => void, onError?: (error: Error) => void): RealtimeSubscription;
@@ -51,6 +78,12 @@ interface ConversationPageRequest {
 type ConversationPageLoader = (request: ConversationPageRequest) => Promise<Conversation$1[]>;
 interface ConversationListState {
     conversations: Readonly<Ref<Conversation$1[]>>;
+    /** Per-room preview, unread count, read state and private unread marker (`isUnread`, `unreadMarkedAt`,
+     * `privateStateVersion`, 0.7.0) by conversation ID; empty on the legacy `getConversations` path.
+     */
+    summaries: Readonly<Ref<ReadonlyMap<string, InboxSummary>>>;
+    /** The bound session's user; `''` without a session, on the legacy path and after disposal. */
+    currentUserId: Readonly<Ref<string>>;
     filter: Readonly<Ref<ConversationFilter>>;
     isInitialLoading: Readonly<Ref<boolean>>;
     isLoadingMore: Readonly<Ref<boolean>>;
@@ -89,6 +122,12 @@ interface ConversationItemSlotProps {
     index: number;
     selected: boolean;
     select: () => void;
+    /** Present when the list carries an inbox summary for this row (0.6.0); `summary.isUnread` (0.7.0) is the row's
+     * unread state including the viewer's private marker.
+     */
+    summary?: InboxSummary;
+    /** Present when the list knows the viewer (0.6.0); compare with `summary.latestMessage.senderId`. */
+    currentUserId?: string;
 }
 interface MessageSlotProps {
     message: Message;
@@ -979,6 +1018,8 @@ interface UseConversationListOptions {
     initialFilter?: ConversationFilter;
     pageSize?: number;
     autoLoad?: boolean;
+    /** Max-wait window (ms) that coalesces `inbox_activity` signals into one refresh; default 500, 0 = immediate. */
+    activityRefreshWindowMs?: number;
 }
 interface ConversationListController extends ConversationListState {
     loadInitial(): Promise<void>;
@@ -986,12 +1027,26 @@ interface ConversationListController extends ConversationListState {
     loadMore(): Promise<void>;
     setFilter(filter: ConversationFilter): Promise<void>;
     setQuery(query: string): Promise<void>;
+    /** Mark a room unread for the viewer only (0.7.0); its summary shows the marker at once. Rejects when the adapter
+     * lacks `markConversationUnread`.
+     */
+    markUnread(conversationId: string): Promise<void>;
+    /** Remove the viewer's marker, only while it still has `options.ifVersion` when given; resolves to whether this
+     * request removed it. Rejects when the adapter lacks `clearConversationUnread`.
+     */
+    clearUnread(conversationId: string, options?: ClearConversationUnreadOptions): Promise<boolean>;
     dispose(): Promise<void>;
 }
 declare function useConversationList(options: UseConversationListOptions): ConversationListController;
 
 interface ConversationListViewProps extends ConvoKitAppearanceProps {
     conversations: readonly Conversation$1[];
+    /** Inbox summaries by conversation ID (0.6.0). Rows with one show a preview, time and unread badge: the count, or
+     * a numberless dot when `isUnread` is set without one (0.7.0).
+     */
+    summaries?: ReadonlyMap<string, InboxSummary>;
+    /** The viewer; a preview from them reads `You: …`. Absent → no prefix. */
+    currentUserId?: string;
     selectedConversationId?: string;
     onConversationSelect?: (conversation: Conversation$1) => void;
     onRefresh?: () => void | Promise<void>;
@@ -1012,6 +1067,14 @@ declare const ConversationListView: vue.DefineComponent<vue.ExtractPropTypes<{
         readonly type: PropType<readonly Conversation$1[]>;
         readonly required: true;
     };
+    readonly summaries: {
+        readonly type: PropType<ReadonlyMap<string, InboxSummary>>;
+        readonly default: undefined;
+    };
+    readonly currentUserId: {
+        readonly type: StringConstructor;
+        readonly default: undefined;
+    };
     readonly selectedConversationId: {
         readonly type: StringConstructor;
         readonly default: undefined;
@@ -1083,6 +1146,14 @@ declare const ConversationListView: vue.DefineComponent<vue.ExtractPropTypes<{
         readonly type: PropType<readonly Conversation$1[]>;
         readonly required: true;
     };
+    readonly summaries: {
+        readonly type: PropType<ReadonlyMap<string, InboxSummary>>;
+        readonly default: undefined;
+    };
+    readonly currentUserId: {
+        readonly type: StringConstructor;
+        readonly default: undefined;
+    };
     readonly selectedConversationId: {
         readonly type: StringConstructor;
         readonly default: undefined;
@@ -1149,6 +1220,7 @@ declare const ConversationListView: vue.DefineComponent<vue.ExtractPropTypes<{
     "onLoad-more"?: () => any;
 }>, {
     readonly isInitialLoading: boolean;
+    readonly currentUserId: string;
     readonly scrollElement: Ref<HTMLElement | null, HTMLElement | null>;
     readonly paginationThreshold: number;
     readonly classNames: Partial<Record<ConvoKitUiPart, string>>;
@@ -1156,6 +1228,7 @@ declare const ConversationListView: vue.DefineComponent<vue.ExtractPropTypes<{
     readonly density: ConvoKitUiDensity;
     readonly unstyled: boolean;
     readonly onRefresh: () => void | Promise<void>;
+    readonly summaries: ReadonlyMap<string, InboxSummary>;
     readonly isLoadingMore: boolean;
     readonly hasMore: boolean;
     readonly selectedConversationId: string;
@@ -1193,10 +1266,22 @@ declare const ConversationList: vue.DefineComponent<vue.ExtractPropTypes<{
         type: BooleanConstructor;
         default: boolean;
     };
+    activityRefreshWindowMs: {
+        type: NumberConstructor;
+        default: undefined;
+    };
     onControllerChange: {
         type: PropType<(controller: ConversationListController) => void>;
         default: undefined;
     };
+    summaries: {
+        readonly type: PropType<ReadonlyMap<string, InboxSummary>>;
+        readonly default: undefined;
+    };
+    currentUserId: {
+        readonly type: StringConstructor;
+        readonly default: undefined;
+    };
     selectedConversationId: {
         readonly type: StringConstructor;
         readonly default: undefined;
@@ -1284,10 +1369,22 @@ declare const ConversationList: vue.DefineComponent<vue.ExtractPropTypes<{
         type: BooleanConstructor;
         default: boolean;
     };
+    activityRefreshWindowMs: {
+        type: NumberConstructor;
+        default: undefined;
+    };
     onControllerChange: {
         type: PropType<(controller: ConversationListController) => void>;
         default: undefined;
     };
+    summaries: {
+        readonly type: PropType<ReadonlyMap<string, InboxSummary>>;
+        readonly default: undefined;
+    };
+    currentUserId: {
+        readonly type: StringConstructor;
+        readonly default: undefined;
+    };
     selectedConversationId: {
         readonly type: StringConstructor;
         readonly default: undefined;
@@ -1353,6 +1450,7 @@ declare const ConversationList: vue.DefineComponent<vue.ExtractPropTypes<{
     "onConversation-select"?: (...args: any[]) => any;
 }>, {
     isInitialLoading: boolean;
+    currentUserId: string;
     scrollElement: Ref<HTMLElement | null, HTMLElement | null>;
     paginationThreshold: number;
     classNames: Partial<Record<ConvoKitUiPart, string>>;
@@ -1363,6 +1461,7 @@ declare const ConversationList: vue.DefineComponent<vue.ExtractPropTypes<{
     autoLoad: boolean;
     onControllerChange: (controller: ConversationListController) => void;
     conversations: readonly Conversation$1[];
+    summaries: ReadonlyMap<string, InboxSummary>;
     isLoadingMore: boolean;
     hasMore: boolean;
     selectedConversationId: string;
@@ -1372,8 +1471,29 @@ declare const ConversationList: vue.DefineComponent<vue.ExtractPropTypes<{
     pageLoader: ConversationPageLoader;
     initialFilter: ConversationFilter;
     pageSize: number;
+    activityRefreshWindowMs: number;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
+/** Whether a message is an optimistic row awaiting server acknowledgement. */
+declare function isConvoKitPendingMessage(message: Message): boolean;
+declare function matchesConversation(conversation: Conversation$1, filter: ConversationFilter): boolean;
+declare function applyConversationFilter(conversations: readonly Conversation$1[], filter: ConversationFilter): Conversation$1[];
+declare function mergeConversations(current: readonly Conversation$1[], incoming: readonly Conversation$1[]): Conversation$1[];
+/** Merge inbox pages by conversation ID: a later entry replaces an earlier one (its room moved), and the result is
+ * re-ordered by `(activityAt desc, id desc)`. Server order is authoritative within a page; this is the rule applied
+ * whenever pages are combined (load more, refresh).
+ */
+declare function mergeInboxEntries(current: readonly InboxEntry[], incoming: readonly InboxEntry[]): InboxEntry[];
+/** Device-zone clock time, shared by message rows and inbox rows. */
+declare function formatMessageTime(date: Date): string;
+declare function mergeMessages(current: readonly Message[], incoming: readonly Message[]): Message[];
+/** Readers of a message under the unified rule: a user's read position (createdAt, id) wins when present,
+ * otherwise the acknowledgement time is compared with createdAt (legacy participants, empty-room acknowledgements).
+ * The sender and pending rows never have readers.
+ */
+declare function readerIdsFor(message: Message, readAtByUserId: ReadonlyMap<string, Date>, readPositionByUserId?: ReadonlyMap<string, ReadPosition>): ReadonlySet<string>;
+declare function formatFileSize(size: number | undefined): string | null;
+
 interface MessageListViewProps extends ConvoKitAppearanceProps {
     conversation: Conversation$1;
     messages: readonly Message[];
@@ -1397,7 +1517,6 @@ interface MessageListViewProps extends ConvoKitAppearanceProps {
     class?: unknown;
     style?: unknown;
 }
-declare function defaultFormatTime(date: Date): string;
 /** Controlled message history with read receipts, structured media, and older-page loading. */
 declare const MessageListView: vue.DefineComponent<vue.ExtractPropTypes<{
     conversation: {
@@ -1462,7 +1581,7 @@ declare const MessageListView: vue.DefineComponent<vue.ExtractPropTypes<{
     };
     formatTime: {
         type: PropType<(date: Date) => string>;
-        default: typeof defaultFormatTime;
+        default: typeof formatMessageTime;
     };
     imageLoading: {
         type: PropType<"eager" | "lazy">;
@@ -1549,7 +1668,7 @@ declare const MessageListView: vue.DefineComponent<vue.ExtractPropTypes<{
     };
     formatTime: {
         type: PropType<(date: Date) => string>;
-        default: typeof defaultFormatTime;
+        default: typeof formatMessageTime;
     };
     imageLoading: {
         type: PropType<"eager" | "lazy">;
@@ -1606,6 +1725,8 @@ interface ConvoKitTheme {
     incomingBubble: string;
     outgoingBubble: string;
     outgoingText: string;
+    /** Unread badge and dot background (0.6.0); the badge label uses `outgoingText`. Defaults to the primary color. */
+    badge: string;
     radius: string;
     avatarSize: string;
     fontFamily: string;
@@ -1646,17 +1767,4 @@ declare const ConvoKitThemeProvider: vue.DefineComponent<vue.ExtractPropTypes<{
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 declare function useConvoKitTheme(): Readonly<Ref<ConvoKitTheme>>;
 
-/** Whether a message is an optimistic row awaiting server acknowledgement. */
-declare function isConvoKitPendingMessage(message: Message): boolean;
-declare function matchesConversation(conversation: Conversation$1, filter: ConversationFilter): boolean;
-declare function applyConversationFilter(conversations: readonly Conversation$1[], filter: ConversationFilter): Conversation$1[];
-declare function mergeConversations(current: readonly Conversation$1[], incoming: readonly Conversation$1[]): Conversation$1[];
-declare function mergeMessages(current: readonly Message[], incoming: readonly Message[]): Message[];
-/** Readers of a message under the unified rule: a user's read position (createdAt, id) wins when present,
- * otherwise the acknowledgement time is compared with createdAt (legacy participants, empty-room acknowledgements).
- * The sender and pending rows never have readers.
- */
-declare function readerIdsFor(message: Message, readAtByUserId: ReadonlyMap<string, Date>, readPositionByUserId?: ReadonlyMap<string, ReadPosition>): ReadonlySet<string>;
-declare function formatFileSize(size: number | undefined): string | null;
-
-export { type BaseViewProps, type ComposerSlotProps, Conversation, type ConversationController, type ConversationFilter, type ConversationItemSlotProps, ConversationList, type ConversationListController, type ConversationListProps, type ConversationListState, ConversationListView, type ConversationListViewProps, type ConversationPageLoader, type ConversationPageRequest, type ConversationProps, type ConversationState, ConversationView, type ConversationViewProps, type ConvoKitAppearanceProps, ConvoKitAvatar, type ConvoKitTheme, ConvoKitThemeProvider, type ConvoKitUiClient, type ConvoKitUiDensity, type ConvoKitUiPart, type ErrorSlot, type ErrorSlotProps, type MediaSlotProps, MessageListView, type MessageListViewProps, type MessageSlotProps, type ReadReceiptSlotProps, type ScrollOptions, type StateSlot, type TypingSlotProps, type UseConversationListOptions, type UseConversationOptions, applyConversationFilter, createConvoKitUiClient, defaultConvoKitTheme, defaultReadersResolver, formatFileSize, isConvoKitPendingMessage, matchesConversation, mergeConversations, mergeMessages, readerIdsFor, useConversation, useConversationList, useConvoKitTheme };
+export { type BaseViewProps, type ComposerSlotProps, Conversation, type ConversationController, type ConversationFilter, type ConversationItemSlotProps, ConversationList, type ConversationListController, type ConversationListProps, type ConversationListState, ConversationListView, type ConversationListViewProps, type ConversationPageLoader, type ConversationPageRequest, type ConversationProps, type ConversationState, ConversationView, type ConversationViewProps, type ConvoKitAppearanceProps, ConvoKitAvatar, type ConvoKitTheme, ConvoKitThemeProvider, type ConvoKitUiClient, type ConvoKitUiDensity, type ConvoKitUiPart, type ErrorSlot, type ErrorSlotProps, type MediaSlotProps, MessageListView, type MessageListViewProps, type MessageSlotProps, type ReadReceiptSlotProps, type ScrollOptions, type StateSlot, type TypingSlotProps, type UseConversationListOptions, type UseConversationOptions, applyConversationFilter, createConvoKitUiClient, defaultConvoKitTheme, defaultReadersResolver, formatFileSize, isConvoKitPendingMessage, matchesConversation, mergeConversations, mergeInboxEntries, mergeMessages, readerIdsFor, useConversation, useConversationList, useConvoKitTheme };