@only-chat/types 0.2.0-beta.9 → 1.0.1

package/index.d.ts

@@ -1,4 +1,5 @@
 export type * as Log from './log.d.ts'
-export type * as Queue from './queue.js'
-export type * as Store from './store.js'
-export type * as Transport from './transport.ts'
+export type * as Queue from './queue.d.ts'
+export type * as Store from './store.d.ts'
+export type * as Transport from './transport.d.ts'
+export type * as UserStore from './userStore.d.ts'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@only-chat/types",
-  "version": "0.2.0-beta.9",
+  "version": "1.0.1",
   "description": "TypeScript definitions for only-chat",
   "homepage": "https://github.com/only-chat/node-backend/packages/types",
   "main": "",
@@ -13,11 +13,11 @@
   "scripts": {},
   "author": "only-chat",
   "license": "MIT",
-  "dependencies": {
-    "@types/node": "^22.7.4"
-  },
   "keywords": [
     "only-chat",
     "type"
-  ]
-}
+  ],
+  "devDependencies": {
+    "@types/node": "^25.2.3"
+  }
+}

package/queue.d.ts

@@ -20,6 +20,7 @@ export interface TextMessage {
 
 export interface MessageDelete {
     messageId: string
+    deletedAt: Date
 }
 
 export interface MessageUpdate extends Partial<FileMessage>, Partial<TextMessage> {
@@ -31,6 +32,12 @@ export type MessageType = 'connected' | 'disconnected' | 'joined' | 'left' | 'cl
 
 export type MessageData = ConversationUpdate | FileMessage | MessageDelete | MessageUpdate | TextMessage | null
 
+export type MessageMetadataValue = string | number | boolean | null
+
+export type MessageMetadata = {
+  [name: string]: MessageMetadataValue | MessageMetadataValue[]
+}
+
 export interface Message {
     type: MessageType
     id?: string
@@ -41,14 +48,38 @@ export interface Message {
     connectionId: string
     fromId: string
     data: MessageData
+    metadata?: MessageMetadata
     createdAt: Date
     updatedAt?: Date
     deletedAt?: Date
 }
 
 export interface MessageQueue {
-    acceptTypes?: MessageType[]
+     // Provide list of accepted message types
+    readonly acceptTypes?: MessageType[]
+    /**
+     * Publishes a message to the queue if its type is accepted
+     * 
+     * @param msg - The message object to publish
+     * @returns Promise<boolean> - true if message was published, false if message type is not accepted
+     */
     publish: (msg: Message) => Promise<boolean>
+     /**
+     * Subscribes a callback function to receive messages from the queue
+     * 
+     * @param callback - Async function that processes incoming messages
+     * @returns Promise<boolean> - Always returns true when subscription is added
+     * 
+     * Note: Multiple subscribers can be registered, and all will be called for each message
+     */
     subscribe: (callback: (msg: Message) => Promise<void>) => Promise<boolean>
+    /**
+     * Unsubscribes a previously registered callback function
+     * 
+     * @param callback - The callback function to remove
+     * @returns Promise<boolean> - true if callback was found and removed, false otherwise
+     * 
+     * Note: Only removes the last occurrence if the same callback was added multiple times
+     */
     unsubscribe?: (callback: (msg: Message) => Promise<void>) => Promise<boolean>
 }

package/store.d.ts

@@ -38,10 +38,12 @@ export interface TextMessage {
 
 export interface MessageDelete {
     messageId: string
+    deletedAt: Date
 }
 
 export interface MessageUpdate extends Partial<FileMessage>, Partial<TextMessage> {
     messageId: string
+    updatedAt: Date
 }
 
 export interface FindRequest {
@@ -71,6 +73,12 @@ export type MessageType = 'joined' | 'left' | 'closed' | 'deleted' | 'updated' |
 
 export type MessageData = ConversationUpdate | FileMessage | MessageDelete | MessageUpdate | TextMessage | null
 
+export type MessageMetadataValue = string | number | boolean | null
+
+export type MessageMetadata = {
+  [name: string]: MessageMetadataValue | MessageMetadataValue[]
+}
+
 export interface Message {
     type: MessageType
     id?: string
@@ -80,6 +88,7 @@ export interface Message {
     connectionId: string
     fromId: string
     data: MessageData
+    metadata?: MessageMetadata
     createdAt: Date
     updatedAt?: Date
     deletedAt?: Date
@@ -92,6 +101,11 @@ export interface SaveResponse {
 
 export type ConversationLastMessages = Record<string, { latest?: Message, left?: Date }>
 
+export interface ConversationIdResult {
+    id?: string
+    result?: string
+}
+
 export interface ConversationsResult {
     conversations: Conversation[]
     from: number
@@ -100,14 +114,119 @@ export interface ConversationsResult {
 }
 
 export interface MessageStore {
+    /**
+     * Searches for messages based on filter criteria with pagination and sorting support
+     * 
+     * @param r - FindRequest object containing search parameters including:
+     *   - ids: Message IDs to retrieve
+     *   - conversationIds: Messages from specific conversations
+     *   - text: Text content filter (searches within text messages)
+     *   - fromIds: Sender IDs
+     *   - types: Message types (e.g., 'text', 'file')
+     *   - clientMessageIds: Client-provided message IDs
+     *   - excludeIds: Message IDs to exclude from results
+     *   - createdFrom/createdTo: Date range filters
+     *   - sort: Field to sort by (e.g., 'createdAt')
+     *   - sortDesc: Whether to sort in descending order
+     *   - from: Pagination starting index
+     *   - size: Maximum number of results to return
+     * 
+     * @returns Promise<FindResult> containing filtered, sorted, and paginated messages
+     */
     findMessages: (r: FindRequest) => Promise<FindResult>
-    getConversationById: (id: string) => Promise<Conversation | undefined>
+    /**
+     * Retrieves the latest message and last participant message for each specified conversation
+     * 
+     * @param participant - The user ID of the participant requesting the information
+     * @param conversationId - Array of conversation IDs to fetch last message info for
+     * 
+     * @returns Promise<ConversationLastMessages> - Object mapping conversation IDs to:
+     *   - latest: The most recent non-deleted message of type 'text' or 'file'
+     *   - left: Timestamp of the last message sent by the specified participant
+     */
     getLastMessagesTimestamps: (fromId: string, conversationId: string[]) => Promise<ConversationLastMessages>
+    /**
+     * Retrieves a single conversation by ID for a specific participant
+     *  
+     * @param participant - Optional participant ID; if provided, verifies the participant is part of the conversation
+     * @param id - The unique identifier of the conversation to retrieve
+     * 
+     * @returns Promise<Conversation | undefined> - The conversation object if found and accessible,
+     *          undefined if conversation doesn't exist, is deleted, or doesn't have specified participant
+     */
     getParticipantConversationById: (participant: string | undefined, id: string) => Promise<Conversation | undefined>
-    getParticipantConversations: (participant: string, excludeIds: string[], from: number, size: number) => Promise<ConversationsResult>
+    /**
+     * Retrieves a paginated list of conversations for a specific participant with optional filtering
+     * 
+     * @param participant - The user ID of the participant whose conversations to retrieve
+     * @param ids - Optional array of conversation IDs to filter by (if undefined, returns all conversations)
+     * @param excludeIds - Optional array of conversation IDs to exclude from results
+     * @param from - Pagination starting index (default: 0)
+     * @param size - Maximum number of conversations to return (default: 100)
+     * 
+     * @returns Promise<ConversationsResult> - Paginated result containing:
+     *   - conversations: Array of conversations sorted by creation date (newest first)
+     *   - from: The starting index used for pagination
+     *   - size: The number of conversations returned
+     *   - total: The total number of conversations for the participant
+     */
+    getParticipantConversations: (participant: string, ids?: string[], excludeIds?: string[], from?: number, size?: number) => Promise<ConversationsResult>
+    /**
+     * Retrieves the last non-deleted message sent by a specific participant in a conversation
+     * 
+     * @param participant - The user ID of the participant whose last message to find
+     * @param conversationId - The unique identifier of the conversation
+     * 
+     * @returns Promise<Message | undefined> - The last message sent by the participant in the conversation,
+     *          undefined if conversation doesn't exist, is deleted, participant is not in conversation,
+     *          or participant has no messages
+     */
     getParticipantLastMessage: (participant: string, conversationId: string) => Promise<Message | undefined>
-    getPeerToPeerConversationId(peer1: string, peer2: string): Promise<string | undefined>
+    /**
+     * Gets or creates a peer-to-peer conversation ID between two users
+     * 
+     * @param peer1 - First user ID
+     * @param peer2 - Second user ID
+     * 
+     * @returns Promise<ConversationIdResult | undefined> - Object containing:
+     *   - id: The conversation ID (existing or newly created)
+     *   - result: 'created' if a new conversation was created, undefined if existing conversation was found
+     * 
+     * Note: The conversation ID is deterministic - same two users will always get the same ID
+     *       regardless of parameter order (peer1 and peer2 are sorted internally)
+     */
+    getPeerToPeerConversationId(peer1: string, peer2: string): Promise<ConversationIdResult | undefined>
+    /**
+     * Saves a connection record for a user instance (e.g., WebSocket connection)
+     * 
+     * @param userId - The ID of the user establishing the connection
+     * @param instanceId - The instance identifier for this connection
+     * 
+     * @returns Promise<SaveResponse> - Object containing:
+     *   - _id: The auto-generated unique connection ID
+     *   - result: Always 'created' since connections are always new entries
+     */
     saveConnection: (userId: string, instanceId: string) => Promise<SaveResponse>
+    /**
+     * Saves or updates a conversation in the store
+     * 
+     * @param c - Conversation to save. If the conversation has an ID,
+     *            it updates the existing conversation; otherwise creates a new one
+     * 
+     * @returns Promise<SaveResponse> - Object containing:
+     *   - _id: The conversation ID (preserved if provided, auto-generated if new)
+     *   - result: 'created' for new conversations, 'updated' for existing ones
+     */
     saveConversation: (c: Conversation) => Promise<SaveResponse>
+    /**
+     * Saves or updates a message in the store and associates it with a conversation
+     * 
+     * @param m - Message to save. If the message has an ID,
+     *            it updates the existing message; otherwise creates a new one
+     * 
+     * @returns Promise<SaveResponse> - Object containing:
+     *   - _id: The message ID (preserved if provided, auto-generated if new)
+     *   - result: 'created' for new messages, 'updated' for existing ones
+     */
     saveMessage: (m: Message) => Promise<SaveResponse>
 }

package/transport.d.ts

@@ -16,7 +16,7 @@ export interface Transport extends EventEmitter {
 
     close(code?: number, data?: string | Buffer): void
     send(data: string, options: {
-        binary?: boolean | undefined
-        fin?: boolean | undefined
-    },): void
+        binary?: boolean
+        fin?: boolean
+    }): void
 }

package/userStore.d.ts

@@ -2,10 +2,15 @@ export interface AuthenticationInfo {}
 
 export interface UserStore {
     /**
-     * Verifies provided user credentials
+     * Authenticates a user
      * 
-     * @param authInfo User credentials
-     * @returns User identifier
+     * @param info - Authentication information containing name and password
+     * 
+     * @returns Promise<string | undefined> - User ID if authentication successful
+     *          or new user created, undefined if no name provided
+     * 
+     * Security Consideration: In production, passwords should be hashed
+     *       before storage.
      */
     authenticate(authInfo: AuthenticationInfo): Promise<string | undefined>
 }