wexa-chat 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,529 @@
+import mongoose, { Document, Model } from 'mongoose';
+import { Server } from 'http';
+import { Socket, Server as Server$1 } from 'socket.io';
+
+type Actor = {
+    organizationId: string;
+    participantModel: string;
+    participantId: string;
+};
+
+type MessageCreatedEvent = {
+    type: "message:created";
+    message: any;
+};
+type ConversationReadEvent = {
+    type: "conversation:read";
+    conversationId: string;
+    messageId: string;
+    participantModel: string;
+    participantId: string;
+    at: string;
+};
+type TypingEvent = {
+    type: "typing";
+    conversationId: string;
+    participantModel: string;
+    participantId: string;
+    state: "start" | "stop";
+};
+type PresenceEvent = {
+    type: "presence:join" | "presence:leave";
+    organizationId: string;
+    participantModel: string;
+    participantId: string;
+    at: string;
+};
+
+/**
+ * Redis configuration type
+ */
+type RedisConfig = {
+    url?: string;
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    socketConnectTimeout?: number;
+    keepAlive?: number;
+};
+/**
+ * Environment configuration
+ */
+interface EnvironmentConfig {
+    /** MongoDB connection URI */
+    mongoUri: string;
+    /** Redis configuration (optional) */
+    redis?: RedisConfig;
+}
+/**
+ * Get Redis configuration from provided options
+ */
+declare function getRedisConfig(config: {
+    redis?: RedisConfig;
+}): RedisConfig | null;
+
+type SocketConfig$1 = {
+    path?: string;
+    cors?: {
+        origin?: string | string[];
+        methods?: string[];
+    };
+};
+type InitOptions = {
+    /**
+     * Models that can participate in conversations
+     */
+    participantModels: string[];
+    /**
+     * Valid roles for conversation participants
+     */
+    memberRoles: string[];
+    /**
+     * MongoDB connection URI
+     */
+    mongoUri: string;
+    /**
+     * Enable text search for messages
+     */
+    enableTextSearch?: boolean;
+    /**
+     * Redis configuration
+     */
+    redis?: RedisConfig;
+    /**
+     * Socket.IO configuration
+     */
+    socket?: SocketConfig$1;
+    /**
+     * Presence tracking configuration
+     */
+    presence?: {
+        enabled?: boolean;
+        heartbeatSec?: number;
+    };
+    /**
+     * Rate limiting configuration
+     */
+    rateLimit?: {
+        sendPerMin?: number;
+        typingPerMin?: number;
+    };
+};
+
+type CreateConversationArgs = {
+    organizationId: string;
+    a: {
+        model: string;
+        id: string;
+    };
+    b: {
+        model: string;
+        id: string;
+    };
+};
+type SendMessageArgs = {
+    organizationId: string;
+    conversationId: string;
+    senderModel: string;
+    senderId: string;
+    text: string;
+    kind?: "text" | "system";
+    parentMessageId?: string;
+    rootThreadId?: string;
+};
+type ListMessagesArgs = {
+    organizationId: string;
+    conversationId: string;
+    limit?: number;
+    cursor?: string;
+};
+type MarkReadArgs = {
+    organizationId: string;
+    conversationId: string;
+    participantModel: string;
+    participantId: string;
+    messageId: string;
+};
+type SearchMessagesArgs = {
+    organizationId: string;
+    query?: string;
+    conversationId?: string;
+    senderModel?: string;
+    senderId?: string;
+    kind?: "text" | "system";
+    dateFrom?: string;
+    dateTo?: string;
+    threadRootId?: string;
+    limit?: number;
+    cursor?: string;
+};
+type SearchConversationsArgs = {
+    organizationId: string;
+    participantModel?: string;
+    participantId?: string;
+    limit?: number;
+    cursor?: string;
+};
+
+interface IParticipant {
+    entityModel: string;
+    entityId: string;
+    role: string;
+}
+interface IConversation extends Document {
+    organizationId: string;
+    participants: IParticipant[];
+    lastMessageAt: Date;
+    lastMessagePreview?: string;
+    lastMessageSenderId?: string;
+    lastMessageSenderModel?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Create Conversation model
+ */
+declare function createConversationModel(options: InitOptions): Model<IConversation>;
+
+/**
+ * Message document interface
+ */
+interface IMessage extends Document {
+    organizationId: mongoose.Types.ObjectId;
+    conversationId: mongoose.Types.ObjectId;
+    senderModel: string;
+    senderId: mongoose.Types.ObjectId;
+    kind: 'text' | 'system';
+    text: string;
+    parentMessageId?: mongoose.Types.ObjectId;
+    rootThreadId?: mongoose.Types.ObjectId;
+    editedAt?: Date;
+    deletedAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Create Message model
+ */
+declare function createMessageModel(options: InitOptions): Model<IMessage>;
+
+/**
+ * Pagination result interface
+ */
+interface PaginatedResult<T> {
+    items: T[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/**
+ * Creates a pagination cursor from a timestamp and ID
+ * @param timestamp Timestamp to encode in the cursor
+ * @param id ID to encode in the cursor
+ * @returns An encoded cursor string
+ */
+declare function createCursor(timestamp: number, id: string): string;
+/**
+ * Parses a pagination cursor into its timestamp and ID components
+ * @param cursor The cursor string to parse
+ * @returns An object containing the timestamp and ID, or null if invalid
+ */
+declare function parseCursor(cursor: string): {
+    timestamp: number;
+    id: string;
+} | null;
+/**
+ * Creates a paginated response
+ * @param items The items for the current page
+ * @param limit The requested page size
+ * @param getNextCursor Function to get the next cursor from the last item
+ * @returns A paginated result object
+ */
+declare function createPaginatedResponse<T>(items: T[], limit: number, getNextCursor: (lastItem: T) => string): PaginatedResult<T>;
+
+/**
+ * Service for managing conversations
+ */
+interface ConversationsService {
+    createOrFindConversation(args: CreateConversationArgs): Promise<IConversation>;
+    getConversation(organizationId: string, conversationId: string): Promise<IConversation | null>;
+    searchConversations(args: SearchConversationsArgs): Promise<PaginatedResult<IConversation>>;
+    searchByParticipantPair(args: {
+        organizationId: string;
+        a: {
+            model: string;
+            id: string;
+        };
+        b: {
+            model: string;
+            id: string;
+        };
+    }): Promise<IConversation | null>;
+}
+/**
+ * Create conversations service
+ * @param models MongoDB models
+ * @returns Conversations service instance
+ */
+declare function createConversationsService(models: {
+    Conversation: Model<IConversation>;
+    Message: Model<IMessage>;
+}): ConversationsService;
+
+/**
+ * Message service hooks interface
+ */
+interface MessageServiceHooks {
+    onMessageCreated?: (message: IMessage) => void;
+    onMessageRead?: (args: MarkReadArgs & {
+        at: Date;
+    }) => void;
+}
+/**
+ * Service for managing messages
+ */
+interface MessagesService {
+    sendMessage(args: SendMessageArgs): Promise<IMessage>;
+    listMessages(args: ListMessagesArgs): Promise<PaginatedResult<IMessage>>;
+    markRead(args: MarkReadArgs): Promise<void>;
+}
+/**
+ * Create messages service
+ * @param models MongoDB models
+ * @param hooks Service hooks
+ * @returns Messages service instance
+ */
+declare function createMessagesService(models: {
+    Conversation: Model<IConversation>;
+    Message: Model<IMessage>;
+}, hooks?: MessageServiceHooks): MessagesService;
+
+/**
+ * In-memory subscription maps for conversations and sockets
+ */
+/**
+ * Subscribe a socket to a conversation
+ * @param conversationId The conversation ID to subscribe to
+ * @param socketId The socket ID to subscribe
+ */
+declare function subscribeLocal(conversationId: string, socketId: string): void;
+/**
+ * Unsubscribe a socket from a conversation
+ * @param conversationId The conversation ID to unsubscribe from
+ * @param socketId The socket ID to unsubscribe
+ */
+declare function unsubscribeLocal(conversationId: string, socketId: string): void;
+/**
+ * Clean up all subscriptions for a socket
+ * @param socketId The socket ID to clean up
+ */
+declare function cleanupLocal(socketId: string): void;
+/**
+ * Fan out a message to all local subscribers of a conversation
+ * @param conversationId The conversation ID to fan out to
+ * @param payload The payload to send
+ * @param emitter Function to emit events to socket IDs
+ */
+declare function fanoutLocal(conversationId: string, payload: any, emitter: (toSocketId: string, event: any) => void): void;
+
+interface SocketConfig {
+    path?: string;
+    cors?: {
+        origin?: string | string[];
+        methods?: string[];
+    };
+}
+interface SocketUser {
+    id: string;
+    model: string;
+}
+declare class SocketTransport {
+    private io;
+    private transport;
+    constructor(server: Server, transport: Transport, config?: SocketConfig);
+    /**
+     * Handle socket authentication
+     */
+    handleAuth(authenticate: (socket: Socket) => Promise<SocketUser | null>): void;
+    /**
+     * Initialize socket event handlers
+     */
+    initialize(): void;
+    /**
+     * Get Socket.IO server instance
+     */
+    getIO(): Server$1;
+    /**
+     * Close Socket.IO server
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Transport configuration type
+ */
+interface TransportConfig {
+    redis?: InitOptions['redis'];
+    socket?: SocketConfig;
+}
+/**
+ * Transport instance type
+ */
+interface Transport {
+    subscribeLocal: typeof subscribeLocal;
+    unsubscribeLocal: typeof unsubscribeLocal;
+    cleanupLocal: typeof cleanupLocal;
+    fanoutLocal: typeof fanoutLocal;
+    publishToConversation: (conversationId: string, payload: any) => Promise<number>;
+    startRedisListener: (onEvent: (conversationId: string, payload: any) => void) => (() => void) | null;
+}
+/**
+ * Create transport system with optional Redis and Socket.IO support
+ */
+declare function createTransport(config?: TransportConfig, server?: Server): Transport & {
+    socket?: SocketTransport;
+};
+
+/**
+ * Generates a random string ID with the specified length
+ * @param length The length of the ID to generate (default: 24)
+ * @returns A random string ID
+ */
+declare function generateId(length?: number): string;
+/**
+ * Creates a conversation ID from two participant identifiers
+ * @param a First participant (model:id)
+ * @param b Second participant (model:id)
+ * @returns A deterministic conversation ID
+ */
+declare function createConversationId(a: {
+    model: string;
+    id: string;
+}, b: {
+    model: string;
+    id: string;
+}): string;
+/**
+ * Creates a thread ID
+ * @returns A unique thread ID
+ */
+declare function createThreadId(): string;
+/**
+ * Creates a message ID
+ * @returns A unique message ID
+ */
+declare function createMessageId(): string;
+
+/**
+ * Validates initialization options
+ * @param options Options to validate
+ * @returns Validation error message or null if valid
+ */
+declare function validateInitOptions(options: InitOptions): string | null;
+/**
+ * Validates message sending arguments
+ * @param args Message sending arguments to validate
+ * @returns Validation error message or null if valid
+ */
+declare function validateSendMessageArgs(args: SendMessageArgs): string | null;
+/**
+ * Validates conversation creation arguments
+ * @param args Conversation creation arguments to validate
+ * @returns Validation error message or null if valid
+ */
+declare function validateCreateConversationArgs(args: CreateConversationArgs): string | null;
+/**
+ * Validates mark read arguments
+ * @param args Mark read arguments to validate
+ * @returns Validation error message or null if valid
+ */
+declare function validateMarkReadArgs(args: MarkReadArgs): string | null;
+/**
+ * Validates pagination parameters
+ * @param limit Pagination limit
+ * @param cursor Pagination cursor
+ * @returns Validated limit and cursor
+ */
+declare function validatePagination(limit?: number, cursor?: string): {
+    limit: number;
+    cursor: string | undefined;
+};
+
+/**
+ * Create Mongoose models with applied configuration
+ * @param mongooseInstance Mongoose instance
+ * @param options Initialization options
+ * @returns Object containing Conversation and Message models
+ */
+declare function createModels(mongooseInstance: typeof mongoose, options: InitOptions): {
+    Conversation: mongoose.Model<IConversation, {}, {}, {}, mongoose.Document<unknown, {}, IConversation> & IConversation & {
+        _id: mongoose.Types.ObjectId;
+    }, any>;
+    Message: mongoose.Model<IMessage, {}, {}, {}, mongoose.Document<unknown, {}, IMessage> & IMessage & {
+        _id: mongoose.Types.ObjectId;
+    }, any>;
+};
+
+/**
+ * Ensure all indexes are created on models
+ * @param models Object containing Mongoose models
+ */
+declare function ensureIndexes(models: {
+    Conversation: Model<IConversation>;
+    Message: Model<IMessage>;
+}): Promise<void>;
+
+/**
+ * Search messages based on various criteria
+ * @param model Message model
+ * @param params Search parameters
+ * @returns Paginated messages with optional text search results
+ */
+declare function searchMessages(model: Model<IMessage>, params: SearchMessagesArgs): Promise<PaginatedResult<IMessage>>;
+
+/**
+ * Search conversations with pagination
+ */
+declare function searchConversations(model: Model<IConversation>, params: SearchConversationsArgs): Promise<PaginatedResult<IConversation>>;
+/**
+ * Find a conversation between two specific participants
+ */
+declare function searchByParticipantPair(model: Model<IConversation>, params: {
+    organizationId: string;
+    a: {
+        model: string;
+        id: string;
+    };
+    b: {
+        model: string;
+        id: string;
+    };
+}): Promise<IConversation | null>;
+
+/**
+ * Chat services container
+ */
+interface ChatServices {
+    models: {
+        Conversation: mongoose.Model<any>;
+        Message: mongoose.Model<any>;
+    };
+    services: {
+        conversations: ConversationsService;
+        messages: MessagesService;
+    };
+    transport: Transport & {
+        socket?: SocketTransport;
+    };
+}
+/**
+ * Initialize the chat system
+ * @param mongooseInstance Mongoose instance
+ * @param options Initialization options
+ * @param server Optional HTTP server for Socket.IO integration
+ * @returns Chat services
+ */
+declare function initChat(mongooseInstance: typeof mongoose, options: InitOptions, server?: Server): Promise<ChatServices>;
+
+export { type Actor, type ChatServices, type ConversationReadEvent, type ConversationsService, type CreateConversationArgs, type EnvironmentConfig, type IConversation, type IMessage, type IParticipant, type InitOptions, type ListMessagesArgs, type MarkReadArgs, type MessageCreatedEvent, type MessageServiceHooks, type MessagesService, type PaginatedResult, type PresenceEvent, type RedisConfig, type SearchConversationsArgs, type SearchMessagesArgs, type SendMessageArgs, type SocketConfig$1 as SocketConfig, type Transport, type TransportConfig, type TypingEvent, createConversationId, createConversationModel, createConversationsService, createCursor, createMessageId, createMessageModel, createMessagesService, createModels, createPaginatedResponse, createThreadId, createTransport, ensureIndexes, generateId, getRedisConfig, initChat, parseCursor, searchByParticipantPair, searchConversations, searchMessages, validateCreateConversationArgs, validateInitOptions, validateMarkReadArgs, validatePagination, validateSendMessageArgs };