@acorex-platform/module-conversation-client 0.0.21

package/types/acorex-platform-module-conversation-client-contracts.d.ts

@@ -0,0 +1,497 @@
+import { AXPEntityModel } from '@acorex-platform/framework-shared/entity';
+import { AXMConversationMessage as AXMConversationMessage$1, AXMConversationRoom as AXMConversationRoom$1 } from '@acorex-platform/module-conversation-contracts';
+
+interface AXMCommentEntityData {
+    entityId: string;
+    entityTypeId: string;
+    moduleName?: string;
+    entityName?: string;
+}
+
+declare const AXPConversationMenuKeys: {
+    readonly Conversations: "Conversation:Menu:Conversations";
+};
+
+/**
+ * Collaboration capabilities used by this module.
+ * Domain capability keys for this module. Root groups live in `AXPCommonPermissionGroupKeys` (common contracts).
+ */
+declare const AXPCollaborationPermissionKeys: {
+    readonly Access: "Collaboration:Permission:Access";
+    readonly MaintainConversations: "Collaboration:Permission:MaintainConversations";
+    readonly MaintainMeetings: "Collaboration:Permission:MaintainMeetings";
+    readonly MaintainCalendars: "Collaboration:Permission:MaintainCalendars";
+    readonly MaintainCommunications: "Collaboration:Permission:MaintainCommunications";
+    readonly MaintainReservations: "Collaboration:Permission:MaintainReservations";
+    readonly MaintainHelpDesk: "Collaboration:Permission:MaintainHelpDesk";
+    readonly Setup: "Collaboration:Permission:Setup";
+};
+/**
+ * @deprecated Prefer {@link AXPCollaborationPermissionKeys}.
+ * Legacy nested shape kept so existing imports compile during migration.
+ */
+declare const AXMPermissionsKeys: {
+    readonly Conversation: {
+        readonly Management: "Collaboration:Permission:MaintainConversations";
+    };
+};
+
+declare const RootConfig: {
+    readonly config: {
+        i18n: string;
+        module: string;
+        route: string;
+    };
+    readonly module: {
+        readonly route: "conversation";
+        readonly name: string;
+        readonly title: `@${string}:module.title`;
+        readonly icon: "fa-light fa-comments";
+    };
+    readonly entities: {
+        readonly room: {
+            readonly name: "Room";
+            readonly title: `t("room.plural-title", { scope: "${string}" })`;
+            readonly source: `${string}.Room`;
+            readonly icon: "fa-light fa-comments";
+        };
+        readonly message: {
+            readonly name: "Message";
+            readonly title: `t("message.plural-title", { scope: "${string}" })`;
+            readonly source: `${string}.Message`;
+            readonly icon: "fa-light fa-message";
+        };
+    };
+};
+
+/** Fields for one uploaded or remote media item. */
+interface AXMediaItemFields {
+    /** HTTP(S) or other persistable URL; omit when only {@link mediaId} is stored. */
+    url?: string;
+    mediaId?: string;
+    mimeType?: string;
+    size?: number;
+    metadata?: Record<string, unknown>;
+}
+interface AXTextFormat {
+    start: number;
+    end: number;
+    type: 'bold' | 'italic' | 'code' | 'strikethrough' | 'underline' | 'spoiler';
+}
+interface AXMention {
+    start: number;
+    end: number;
+    userId: string;
+    userName: string;
+}
+interface AXLink {
+    start: number;
+    end: number;
+    url: string;
+    preview?: AXLinkPreview;
+}
+interface AXLinkPreview {
+    title?: string;
+    description?: string;
+    image?: string;
+    siteName?: string;
+}
+interface AXTextPayload {
+    type: 'text';
+    text: string;
+    formatting?: AXTextFormat[];
+    mentions?: AXMention[];
+    links?: AXLink[];
+}
+interface AXImageMediaItem extends AXMediaItemFields {
+    thumbnailUrl?: string;
+    width: number;
+    height: number;
+    blurhash?: string;
+}
+interface AXImagePayload {
+    type: 'image';
+    images: AXImageMediaItem[];
+    caption?: string;
+}
+interface AXVideoMediaItem extends AXMediaItemFields {
+    thumbnailUrl?: string;
+    duration: number;
+    width: number;
+    height: number;
+}
+interface AXVideoPayload {
+    type: 'video';
+    videos: AXVideoMediaItem[];
+    caption?: string;
+}
+interface AXAudioMediaItem extends AXMediaItemFields {
+    duration: number;
+    title?: string;
+    artist?: string;
+    coverUrl?: string;
+    waveform?: number[];
+}
+interface AXAudioPayload {
+    type: 'audio';
+    audios: AXAudioMediaItem[];
+    caption?: string;
+}
+interface AXVoicePayload extends AXMediaItemFields {
+    type: 'voice';
+    duration: number;
+    waveform?: number[];
+    played?: boolean;
+}
+interface AXFileMediaItem extends AXMediaItemFields {
+    name: string;
+    mimeType: string;
+    thumbnailUrl?: string;
+    extension?: string;
+}
+interface AXFilePayload {
+    type: 'file';
+    files: AXFileMediaItem[];
+    caption?: string;
+}
+interface AXLocationPayload {
+    type: 'location';
+    latitude: number;
+    longitude: number;
+    name?: string;
+    address?: string;
+    mapImageUrl?: string;
+    accuracy?: number;
+}
+interface AXStickerPayload extends AXMediaItemFields {
+    type: 'sticker';
+    id: string;
+    packId: string;
+    animated: boolean;
+    width?: number;
+    height?: number;
+    emoji?: string;
+}
+interface AXPollOption {
+    id: string;
+    text: string;
+    votes: number;
+    voters?: string[];
+}
+interface AXPollPayload {
+    type: 'poll';
+    question: string;
+    options: AXPollOption[];
+    multipleChoice: boolean;
+    anonymous: boolean;
+    expiresAt?: Date;
+    totalVotes?: number;
+}
+type AXSystemEventType = 'user_joined' | 'user_left' | 'title_changed' | 'avatar_changed' | 'call_declined' | 'call_missed' | 'call_cancelled' | 'custom';
+interface AXSystemPayload {
+    type: 'system';
+    eventType: AXSystemEventType;
+    text: string;
+    userIds?: string[];
+    data?: Record<string, unknown>;
+}
+/** Layout/node payload used by assist transcripts and dynamic UI messages. */
+interface AXNodePayload {
+    type: 'node';
+    content: unknown;
+}
+/** Aligned with `@acorex/components/conversation` — node payloads use {@link AXNodePayload} at runtime with an explicit cast. */
+type AXMessagePayload = AXTextPayload | AXImagePayload | AXVideoPayload | AXAudioPayload | AXVoicePayload | AXFilePayload | AXLocationPayload | AXStickerPayload | AXPollPayload | AXSystemPayload;
+type AXMessageStatus = 'sending' | 'sent' | 'delivered' | 'read' | 'failed';
+type AXMessageType = 'text' | 'image' | 'video' | 'audio' | 'voice' | 'file' | 'location' | 'sticker' | 'poll' | 'system' | 'node' | 'assist-response' | string;
+/** Reaction on a message. */
+interface AXReaction {
+    /** Emoji character */
+    emoji: string;
+    /** User ID who reacted */
+    userId: string;
+    /** Reaction timestamp */
+    timestamp: Date;
+}
+
+/** Emoji used for comment "like" reactions (maps to {@link AXReaction.emoji}). */
+declare const AXM_COMMENT_LIKE_EMOJI = "\uD83D\uDC4D";
+/** @deprecated Use emoji string with AXReaction instead. */
+type AXMReactionType = string;
+/** @deprecated Use AXReaction instead. */
+type AXMConversationReaction = AXReaction;
+/**
+ * Persisted message entity — conversation message shape plus platform entity base.
+ */
+interface AXMConversationMessage extends AXPEntityModel<string> {
+    /** Conversation (room) this message belongs to */
+    conversationId: string;
+    /** Sender user id */
+    senderId: string;
+    /** Message type */
+    type: AXMessageType;
+    /** File-type catalog name when this message uses a composer file type */
+    fileType?: string;
+    /** Message creation timestamp */
+    timestamp: Date;
+    /** Type-specific message payload */
+    payload: AXMessagePayload;
+    /** Message delivery/read status */
+    status: AXMessageStatus;
+    /** Replied message reference (for quote replies) */
+    replyTo?: AXMConversationMessage;
+    /** Whether this message was forwarded */
+    forwarded?: boolean;
+    /** Original sender information (if forwarded) */
+    forwardedFrom?: {
+        messageId: string;
+        senderId: string;
+        senderName?: string;
+        conversationId: string;
+        conversationTitle?: string;
+    };
+    /** Message reactions */
+    reactions: AXReaction[];
+    /** Whether message is pinned */
+    pinned?: boolean;
+    /** Edit timestamp (if edited) */
+    editedAt?: Date;
+    /** Whether message is deleted */
+    deleted?: boolean;
+    /** Deleted timestamp */
+    deletedAt?: Date;
+    /** Local-only flag (not synced to server yet) */
+    isLocal?: boolean;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** Plain-text snippet for entity admin list column */
+    title?: string;
+    /** Programmatic name for entity admin */
+    name?: string;
+}
+
+type AXParticipantRole = 'admin' | 'moderator' | 'member';
+type AXParticipantStatus = 'online' | 'offline' | 'away';
+/** Extended profile fields shown in private-chat info panels. */
+interface AXUserProfile {
+    bio?: string;
+    phone?: string;
+    email?: string;
+    username?: string;
+    location?: string;
+    company?: string;
+    title?: string;
+}
+/** Represents a user/member in a conversation. */
+interface AXParticipant {
+    /** Unique identifier for the participant */
+    id: string;
+    /** Display name of the participant */
+    name: string;
+    /**
+     * Short line shown under the name in lists (e.g. job title, status line).
+     * Distinct from long-form bio in optional `profile.bio`.
+     */
+    description?: string;
+    /** Optional extended profile details for private chats. */
+    profile?: AXUserProfile;
+    /** Avatar/profile image URL */
+    avatar?: string;
+    /**
+     * Font Awesome icon class(es) used when `avatar` is not set (e.g. `'fa-light fa-user'`).
+     */
+    icon?: string;
+    /** Role in the conversation (for groups/channels) */
+    role?: AXParticipantRole;
+    /** Current online status */
+    status?: AXParticipantStatus;
+    /** Last seen timestamp (when offline/away) */
+    lastSeen?: Date;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+type AXConversationType = 'private' | 'group' | 'channel' | 'bot';
+/** Conversation status information. */
+interface AXConversationStatus {
+    /** Whether someone is typing */
+    isTyping: boolean;
+    /** User IDs currently typing */
+    typingUsers: string[];
+    /** Online presence (for private chats) */
+    presence?: 'online' | 'offline' | 'away';
+    /** Last seen timestamp (for private chats when offline) */
+    lastSeen?: Date;
+}
+/** Conversation settings. */
+interface AXConversationSettings {
+    /** Muted until timestamp */
+    mutedUntil?: Date;
+    /** Show notifications */
+    notifications: boolean;
+    /** Custom notification sound */
+    notificationSound?: string;
+    /** Show message preview in notifications */
+    showPreview: boolean;
+    /** Custom settings */
+    custom?: Record<string, unknown>;
+}
+/** Theme-specific CSS `background` values for the message list area. */
+interface AXConversationMessageListThemeBackground {
+    light: string;
+    dark: string;
+}
+/** Single CSS value (both themes) or per-theme `{ light, dark }` backgrounds. */
+type AXConversationMessageListBackground = string | AXConversationMessageListThemeBackground;
+/**
+ * Extensible map for app-specific conversation data.
+ * Aligned with `@acorex/components/conversation` — UI-only keys such as
+ * `messageListEmptyComponent` are stored as opaque values when persisted.
+ */
+interface AXConversationMetadata extends Record<string, unknown> {
+    /** Optional custom background CSS for message list (per light/dark theme). */
+    messageListBackground?: AXConversationMessageListBackground;
+    /**
+     * When `false`, hides reaction UI for this conversation.
+     * Defaults to `true` when omitted.
+     */
+    reactionsEnabled?: boolean;
+}
+
+/** Distinguishes chat inbox rooms from entity comment threads in the unified store. */
+type AXMConversationRoomKind = 'chat' | 'comment';
+/**
+ * Persisted room entity — conversation shape plus platform entity base.
+ */
+interface AXMConversationRoom extends AXPEntityModel<string> {
+    /** Chat vs comment thread discriminator */
+    kind: AXMConversationRoomKind;
+    /** Conversation type (private, group, channel, bot) */
+    type: AXConversationType;
+    /** User who created this conversation */
+    creatorId?: string;
+    /** Conversation title/name */
+    title: string;
+    /** Conversation avatar/image URL */
+    avatar?: string;
+    /** Font Awesome icon class(es) when no image avatar is used */
+    icon?: string;
+    /** Conversation description (for groups/channels) */
+    description?: string;
+    /** List of participants */
+    participants: AXParticipant[];
+    /** Last message in the conversation */
+    lastMessage?: AXMConversationMessage;
+    /** Timestamp of last message */
+    lastMessageAt: Date;
+    /** Number of unread messages */
+    unreadCount: number;
+    /** Number of unread mentions */
+    unreadMentions?: number;
+    /** Current status (typing, presence, etc.) */
+    status: AXConversationStatus;
+    /** User-specific settings */
+    settings: AXConversationSettings;
+    /** Pinned messages IDs */
+    pinnedMessageIds?: string[];
+    /** Conversation creation timestamp */
+    createdAt: Date;
+    /** Last update timestamp */
+    updatedAt: Date;
+    /** Whether conversation is blocked */
+    blocked?: boolean;
+    /** Whether conversation is pinned */
+    pinned?: boolean;
+    /** Whether conversation is archived */
+    archived?: boolean;
+    /** Draft message text */
+    draft?: string;
+    /** Custom metadata */
+    metadata?: AXConversationMetadata;
+    /** Programmatic name for entity admin */
+    name?: string;
+    /** Entity reference for comment threads */
+    entityRef?: AXMCommentEntityData;
+    /** Comment thread topic/subject */
+    topic?: string;
+}
+
+/** Minimal tool-call shape for assist-stream frontend broker round-trips (mirrors AXPAiToolCall). */
+interface ConversationAssistFrontendToolCall {
+    id: string;
+    name: string;
+    arguments?: unknown;
+}
+type ConversationAssistWireEvent = {
+    type: 'assist_started';
+    conversationId: string;
+    messageId: string;
+    userMessageId: string;
+    message: AXMConversationMessage$1;
+} | {
+    type: 'message_patch';
+    message: AXMConversationMessage$1;
+} | {
+    type: 'conversation_patch';
+    room: AXMConversationRoom$1;
+} | {
+    type: 'assist_completed';
+    conversationId: string;
+    messageId: string;
+    message: AXMConversationMessage$1;
+    /** Present when an auto-generated title was applied at finalize time. */
+    room?: AXMConversationRoom$1;
+} | {
+    type: 'assist_failed';
+    conversationId: string;
+    messageId: string;
+    error: string;
+    message: AXMConversationMessage$1;
+} | {
+    type: 'frontend_tool_call';
+    runId: string;
+    call: ConversationAssistFrontendToolCall;
+};
+
+declare function axmExtractAssistIdFromMetadata(metadata: Record<string, unknown> | undefined): string | undefined;
+declare function axmExtractDirectAgentIdFromMetadata(metadata: Record<string, unknown> | undefined): string | undefined;
+declare function axmConversationHasAiChat(metadata: Record<string, unknown> | undefined): boolean;
+declare function axmChatAiPeerParticipantId(catalogId: string): string;
+declare function axmReadAssistResponseStatus(metadata: Record<string, unknown> | undefined): string | undefined;
+declare function axmReadReplyToUserMessageId(metadata: Record<string, unknown> | undefined): string | undefined;
+declare function extractMessageTextFromPayload(payload: unknown): string;
+declare function axmNormalizeConversationTitle(raw: string): string;
+/** System prompt for a lightweight title-only model call (first user message → sidebar title). */
+declare const AXM_ASSIST_CONVERSATION_TITLE_SYSTEM_PROMPT = "You generate short conversation titles for chat sidebars.\n\nGiven the user's first message, reply with ONLY a concise title (3\u20138 words, max 90 characters).\nUse the same language as the user's message (for example Persian if they wrote in Persian).\nDo not use quotes, colons, hashtags, or explanation. Output the title text only.";
+declare function axmSanitizeAiGeneratedConversationTitle(raw: string): string | null;
+/** Fallback when the title model is unavailable (max 6 words, 90 chars). */
+declare function axmBuildHeuristicConversationTitleFallback(raw: string): string | null;
+declare function axmCoerceMessageTimestampMs(value: unknown): number;
+/** Assist rows must sort after the user turn they reply to (client/server clocks may differ). */
+declare function axmResolveAssistMessageTimestamp(options: {
+    replyToUserMessageTimestamp?: unknown;
+    serverNow?: Date;
+}): Date;
+declare function axmEnsureAssistMessageSortsAfterReplyTarget<T extends {
+    timestamp: unknown;
+}>(message: T, replyTargetTimestamp: unknown): T;
+/** Chronological sort with assist→user reply linkage when timestamps disagree across clocks. */
+declare function axmCompareMessagesChronologically(a: {
+    id: string;
+    timestamp: unknown;
+    metadata?: Record<string, unknown>;
+}, b: {
+    id: string;
+    timestamp: unknown;
+    metadata?: Record<string, unknown>;
+}): number;
+
+interface AXMConversationAssistMessageHandler {
+    maybeStartAfterUserMessage(userMessage: AXMConversationMessage): Promise<void>;
+    retryAssistResponse(conversationId: string, messageId: string, options?: {
+        replyToUserMessageId?: string;
+    }): Promise<AXMConversationMessage>;
+}
+declare const AXM_CONVERSATION_ASSIST_MESSAGE_HANDLER: unique symbol;
+
+export { AXMPermissionsKeys, AXM_ASSIST_CONVERSATION_TITLE_SYSTEM_PROMPT, AXM_COMMENT_LIKE_EMOJI, AXM_CONVERSATION_ASSIST_MESSAGE_HANDLER, AXPCollaborationPermissionKeys, AXPConversationMenuKeys, RootConfig, axmBuildHeuristicConversationTitleFallback, axmChatAiPeerParticipantId, axmCoerceMessageTimestampMs, axmCompareMessagesChronologically, axmConversationHasAiChat, axmEnsureAssistMessageSortsAfterReplyTarget, axmExtractAssistIdFromMetadata, axmExtractDirectAgentIdFromMetadata, axmNormalizeConversationTitle, axmReadAssistResponseStatus, axmReadReplyToUserMessageId, axmResolveAssistMessageTimestamp, axmSanitizeAiGeneratedConversationTitle, extractMessageTextFromPayload };
+export type { AXAudioMediaItem, AXAudioPayload, AXConversationMessageListBackground, AXConversationMessageListThemeBackground, AXConversationMetadata, AXConversationSettings, AXConversationStatus, AXConversationType, AXFileMediaItem, AXFilePayload, AXImageMediaItem, AXImagePayload, AXLink, AXLinkPreview, AXLocationPayload, AXMCommentEntityData, AXMConversationAssistMessageHandler, AXMConversationMessage, AXMConversationReaction, AXMConversationRoom, AXMConversationRoomKind, AXMReactionType, AXMediaItemFields, AXMention, AXMessagePayload, AXMessageStatus, AXMessageType, AXNodePayload, AXParticipant, AXParticipantRole, AXParticipantStatus, AXPollOption, AXPollPayload, AXReaction, AXStickerPayload, AXSystemEventType, AXSystemPayload, AXTextFormat, AXTextPayload, AXUserProfile, AXVideoMediaItem, AXVideoPayload, AXVoicePayload, ConversationAssistFrontendToolCall, ConversationAssistWireEvent };