@messenger-box/platform-server 10.0.3-alpha.7 → 10.0.3-alpha.74

package/lib/templates/services/MessengerNotificationService.ts.template

@@ -1,37 +1,45 @@
-import { IPost,IExpoNotificationData } from 'common';
+/**
+ * Messenger Notification Service Interface
+ * --------------------------------------
+ * 
+ * This interface defines the business logic layer for notification management within
+ * the messenger platform. It provides a comprehensive set of operations for
+ * handling various types of notifications including push notifications, message alerts,
+ * and Expo-specific notifications.
+ * 
+ * Key capabilities:
+ * - Unread message notifications
+ * - Post-based notifications
+ * - Alert message handling
+ * - Expo push notification integration
+ * - Service message notifications
+ * - Support service configuration
+ */
+
+import { IPost, IExpoNotificationData, IBaseService, AsDomainType, Disposable } from 'common/server';
+
 export enum NotificationDurationUnitEnum {
     days = 'days',
     hours = 'hours',
     minutes = 'minutes',
     seconds = 'seconds',
 }
+
 export type IExpoNotification = any;
 export type IExpoNotificationTo = string | string[];
-export type IExpoNotificationBodyData = {
+
+export interface IExpoNotificationBodyData {
     url: string;
     params: object;
     title?: string;
     body?: string;
     screen?: string;
     senderId?: string;
-    thread?: { id: string; extraParams?: object };
+    thread?: { 
+        id: string; 
+        extraParams?: object 
+    };
     other?: object;
-};
-// export interface IExpoNotificationData {
-//     to: IExpoNotificationTo;
-//     data?: IExpoNotificationBodyData;
-//     title: string;
-//     body: any;
-//     sound?: any;
-// }
-export interface IMessengerNotificationService {
-    sendNotificationOfUnreadMessages(unit: NotificationDurationUnitEnum, value: number): Promise<void>;
-    sendNotificationOnPost(post: IPost): Promise<Boolean>;
-    sendNotificationOfAlertMessages(unit: NotificationDurationUnitEnum, value: number): Promise<void>;
-    sendPushNotificationsExpo(data: IExpoNotificationData): Promise<IExpoNotification>;
-    sendExpoNotificationOnPost(post: IPost, notificationData?: IExpoNotificationBodyData): Promise<Boolean>;
-    sendNotificationOfUnreadServiceMessages(unit: NotificationDurationUnitEnum, value: number): Promise<void>;
-    setSupportServiceConfig?(config: any): Promise<void>;
 }
 
 export interface ISupportServiceConfig {
@@ -39,3 +47,70 @@ export interface ISupportServiceConfig {
     templateId?: string;
     variables?: object;
 }
+
+export interface IMessengerNotificationService extends IBaseService<IPost>, Disposable {
+    /**
+     * Sends notifications for unread messages based on duration
+     * 
+     * @param {NotificationDurationUnitEnum} unit - Time unit for notification check
+     * @param {number} value - Duration value in specified unit
+     * @returns {Promise<void>}
+     */
+    sendNotificationOfUnreadMessages(unit: NotificationDurationUnitEnum, value: number): Promise<void>;
+
+    /**
+     * Sends a notification when a new post is created
+     * 
+     * @param {AsDomainType<IPost>} post - The post that triggered the notification
+     * @returns {Promise<Boolean>}
+     */
+    sendNotificationOnPost(post: AsDomainType<IPost>): Promise<Boolean>;
+
+    /**
+     * Sends notifications for alert messages based on duration
+     * 
+     * @param {NotificationDurationUnitEnum} unit - Time unit for alert check
+     * @param {number} value - Duration value in specified unit
+     * @returns {Promise<void>}
+     */
+    sendNotificationOfAlertMessages(unit: NotificationDurationUnitEnum, value: number): Promise<void>;
+
+    /**
+     * Sends push notifications through Expo service
+     * 
+     * @param {IExpoNotificationData} data - The notification data to send
+     * @returns {Promise<IExpoNotification>}
+     */
+    sendPushNotificationsExpo(data: IExpoNotificationData): Promise<IExpoNotification>;
+
+    /**
+     * Sends an Expo notification for a specific post
+     * 
+     * @param {AsDomainType<IPost>} post - The post to send notification for
+     * @param {IExpoNotificationBodyData} [notificationData] - Optional custom notification data
+     * @returns {Promise<Boolean>}
+     */
+    sendExpoNotificationOnPost(post: AsDomainType<IPost>, notificationData?: IExpoNotificationBodyData): Promise<Boolean>;
+
+    /**
+     * Sends notifications for unread service messages based on duration
+     * 
+     * @param {NotificationDurationUnitEnum} unit - Time unit for service message check
+     * @param {number} value - Duration value in specified unit
+     * @returns {Promise<void>}
+     */
+    sendNotificationOfUnreadServiceMessages(unit: NotificationDurationUnitEnum, value: number): Promise<void>;
+
+    /**
+     * Configures the support service settings
+     * 
+     * @param {ISupportServiceConfig} config - Support service configuration
+     * @returns {Promise<void>}
+     */
+    setSupportServiceConfig?(config: ISupportServiceConfig): Promise<void>;
+
+    /**
+     * Disposes of resources used by the service
+     */
+    dispose(): void;
+}

package/lib/templates/services/PostService.ts.template

@@ -1,42 +1,287 @@
-import { IBaseService } from '@common-stack/store-mongo';
-import { IFileInfo, IMessageIdentifier, IPost, IPostThread, IThreadMessageInput, IUploadedFileInput } from 'common';
+/**
+ * Post Service Interface
+ * ----------------------
+ * 
+ * This interface defines the business logic layer for post and message management
+ * within the messenger platform. It provides comprehensive operations for handling
+ * messages, file attachments, threading, and message state management across
+ * different channels and communication contexts.
+ * 
+ * Key capabilities:
+ * - Post lifecycle management (creation, updates, deletion)
+ * - File upload and attachment handling (single and batch operations)
+ * - Message threading and conversation management
+ * - Message delivery and read status tracking
+ * - File management and cleanup operations
+ * - Cross-channel message coordination
+ * - Post-thread relationship management
+ * - Message state synchronization
+ * 
+ * The service layer abstracts complex messaging operations and provides a
+ * cohesive API for post-related functionality throughout the messaging platform,
+ * handling file storage, threading logic, and message state consistency.
+ */
 
-export interface IPostServiceInput extends Omit<IPost, 'id' | 'files' | 'isRead' | 'isDelivered'> {
+import { 
+    IFileInfo, 
+    IMessageIdentifier, 
+    IPost, 
+    IPostModel,
+    IPostThread, 
+    IThreadMessageInput, 
+    IUploadedFileInput, 
+    Disposable, 
+    AsDomainType,
+    IBaseService,
+    IFileUpdateResponse
+} from 'common/server';
+
+/**
+ * Code Agent Request Interface
+ * 
+ * @description Input parameters for code agent operations,
+ * containing project details and configuration.
+ */
+export enum AiAgentMessageRole {
+    USER = 'USER',
+    ASSISTANT = 'ASSISTANT',
+}
+
+export enum AiAgentMessageType {
+    RESULT = 'RESULT',
+    ERROR = 'ERROR',
+}
+
+export interface ICodeAgentRequest {
+    /** The input value or prompt for the code agent */
+    value: string;
+    /** The unique identifier of the project */
+    projectId: string;
+    /** Optional message identifier */
+    messageId?: string;
+    /** Owner of the project */
+    owner: string;
+    /** Organization name */
+    orgName: string;
+    /** Optional model configuration */
+    modelConfig?: any;
+}
+
+/**
+ * Post Service Input Interface
+ * 
+ * @description Input parameters for post creation operations,
+ * excluding auto-generated and system-managed fields.
+ */
+export interface IPostServiceInput extends Omit<IPostModel, 'id' | 'files' | 'isRead' | 'isDelivered' | '_id'> {
+    /** Array of file identifiers to attach to the post */
     files: string[];
+    /** Optional MongoDB ObjectId for the post */
     _id?: any;
 }
 
+/**
+ * Post Thread Creation Options
+ * 
+ * @description Configuration parameters for creating posts with associated threads.
+ */
 export type CreatePostThreadOptions = {
+    /** Thread message input data */
     threadMessageInput: IThreadMessageInput;
+    /** Channel identifier where the post will be created */
     channelId: string;
+    /** Optional responder user identifier */
     responderId?: string;
+    /** Optional parent post identifier for threading */
     postParentId?: string;
+    /** Optional existing post identifier */
     postId?: string;
+    /** Account identifier of the post creator */
     accountId: string;
+    /** Optional organization identifier */
     orgId?: string;
+    /** Optional existing post thread identifier */
     postThreadId?: string;
 };
 
-export interface IPostService extends IBaseService<IPost, IPostServiceInput, Partial<IPost>> {
-    createFileUploadLink(postId: string, filename: string, userId: string): Promise<string>;
-    attachUploadedFile(postId: string, file: IUploadedFileInput, createdBy: string): Promise<IFileInfo>;
+/**
+ * Post Service Interface
+ * 
+ * @description Provides comprehensive post and message management capabilities
+ * including file handling, threading, and message state management.
+ */
+export interface IPostService extends IBaseService<IPostModel, IPostServiceInput, Partial<IPostModel>>, Disposable {
+    /**
+     * Creates a file upload link for a specific post
+     * 
+     * @description Generates a secure upload URL for attaching a single file
+     * to an existing post, handling authentication and storage permissions.
+     * 
+     * @param {string} postId - The unique identifier of the post
+     * @param {string} filename - The name of the file to upload
+     * @param {string} userId - The identifier of the user performing the upload
+     * @returns {Promise<string | Error>} - Upload URL or error
+     */
+    createFileUploadLink(postId: string, filename: string, userId: string): Promise<string | Error>;
+
+    /**
+     * Attaches an uploaded file to a post
+     * 
+     * @description Associates a successfully uploaded file with a post,
+     * updating the post's file attachments and metadata.
+     * 
+     * @param {string} postId - The unique identifier of the post
+     * @param {IUploadedFileInput} file - The uploaded file information
+     * @param {string} createdBy - The identifier of the user who uploaded the file
+     * @returns {Promise<IFileInfo | Error>} - File information or error
+     */
+    attachUploadedFile(postId: string, file: IUploadedFileInput, createdBy: string): Promise<IFileInfo | Error>;
+
+    /**
+     * Creates multiple file upload links for a post
+     * 
+     * @description Generates secure upload URLs for attaching multiple files
+     * to an existing post in a single operation.
+     * 
+     * @param {string} postId - The unique identifier of the post
+     * @param {string[]} filenames - Array of file names to upload
+     * @param {string} userId - The identifier of the user performing the upload
+     * @returns {Promise<string[] | Error>} - Array of upload URLs or error
+     */
+    createFilesUploadLink(postId: string, filenames: string[], userId: string): Promise<string[] | Error>;
+
+    /**
+     * Attaches multiple uploaded files to a post
+     * 
+     * @description Associates multiple successfully uploaded files with a post
+     * in a single batch operation, optimizing performance and consistency.
+     * 
+     * @param {string} postId - The unique identifier of the post
+     * @param {IUploadedFileInput[]} files - Array of uploaded file information
+     * @param {string} createdBy - The identifier of the user who uploaded the files
+     * @returns {Promise<IFileInfo[] | Error>} - Array of file information or error
+     */
+    attachUploadedFiles(postId: string, files: IUploadedFileInput[], createdBy: string): Promise<IFileInfo[] | Error>;
+
+    /**
+     * Deletes a file from storage
+     * 
+     * @description Permanently removes a file from the storage system,
+     * typically used for cleanup or when files are no longer needed.
+     * 
+     * @param {string} url - The URL or identifier of the file to delete
+     * @returns {Promise<boolean | Error>} - Success status or error
+     */
+    deleteFile(url: string): Promise<boolean | Error>;
+
+    /**
+     * Marks a message as read by a user
+     * 
+     * @description Updates the read status of a message for a specific user,
+     * affecting unread counts and notification states.
+     * 
+     * @param {IMessageIdentifier} messageId - The message identifier
+     * @param {string} user - The identifier of the user marking the message as read
+     * @returns {Promise<boolean | Error>} - Success status or error
+     */
+    readMessage(messageId: IMessageIdentifier, user: string): Promise<boolean | Error>;
+
+    /**
+     * Marks a message as delivered to a user
+     * 
+     * @description Updates the delivery status of a message, indicating
+     * successful delivery to the target user's device or client.
+     * 
+     * @param {IMessageIdentifier} messageId - The message identifier
+     * @param {string} user - The identifier of the user who received the message
+     * @returns {Promise<boolean | Error>} - Success status or error
+     */
+    deliverMessage(messageId: IMessageIdentifier, user: string): Promise<boolean | Error>;
+
+    /**
+     * Creates a post without triggering subscriptions
+     * 
+     * @description Creates a new post while bypassing real-time subscription
+     * notifications, useful for bulk operations or system-generated content.
+     * 
+     * @param {IPostServiceInput} data - The post creation data
+     * @returns {Promise<AsDomainType<IPostModel> | Error>} - Created post or error
+     */
+    createWithoutSubscription(data: IPostServiceInput): Promise<AsDomainType<IPostModel> | Error>;
+
+    /**
+     * Creates a post with an associated thread
+     * 
+     * @description Creates both a post and its associated thread in a single
+     * transaction, ensuring data consistency and proper relationship setup.
+     * 
+     * @param {CreatePostThreadOptions} options - The post and thread creation options
+     * @returns {Promise<{ post: AsDomainType<IPostModel>; postThread: IPostThread } | Error>} - Created post and thread or error
+     */
+    createPostWithPostThread(options: CreatePostThreadOptions): Promise<{ post: AsDomainType<IPostModel>; postThread: IPostThread } | Error>;
+
+    /**
+     * Retrieves the most recent message from a channel
+     * 
+     * @description Fetches the latest post/message from a specific channel,
+     * useful for displaying channel previews and recent activity.
+     * 
+     * @param {string} channelId - The unique identifier of the channel
+     * @returns {Promise<AsDomainType<IPostModel> | Error>} - Latest message or error
+     */
+    getLastMessage(channelId: string): Promise<AsDomainType<IPostModel> | Error>;
 
-    createFilesUploadLink(postId: string, filenames: string[], userId: string): Promise<string[]>;
-    attachUploadedFiles(postId: string, files: IUploadedFileInput[], createdBy: string): Promise<IFileInfo[]>;
+    /**
+     * Retrieves previous messages from a channel
+     * 
+     * @description Fetches a specified number of recent messages from a channel,
+     * formatted for display with associated file attachments. Returns messages
+     * in reverse chronological order (newest to oldest).
+     * 
+     * @param {string} channelId - The unique identifier of the channel
+     * @param {number} limit - Maximum number of messages to retrieve (default: 5)
+     * @returns {Promise<Array<IPostModel> | Error>} - Array of formatted messages or error
+     */
+    getPreviousMessagesByProjectId(projectId: string, limit?: number): Promise<Array<IPostModel> | Error>;
 
-    deleteFile(url: string): Promise<boolean>;
+    /**
+     * Saves code agent result with comprehensive data
+     * 
+     * @description Saves the result from a code agent operation including message creation,
+     * fragment generation, and project update publishing. Handles both success and error cases
+     * with proper message creation and fragment management.
+     * 
+     * @param {ICodeAgentRequest} request - The code agent request containing project details
+     * @param {string} sandboxUrl - URL of the generated sandbox
+     * @param {string} fragmentTitle - Title for the generated fragment
+     * @param {string} responseContent - Content of the AI response
+     * @param {{ [path: string]: string }} files - Generated files with their paths and content
+     * @param {string} summary - Summary of the generated content
+     * @param {boolean} isError - Whether the operation resulted in an error
+     * @param {any[]} canvasLayers - Optional canvas layers for visual components
+     * @returns {Promise<any>} - Created message document or error
+     */
+    saveCodeAgentResult(
+        request: ICodeAgentRequest,
+        sandboxUrl: string,
+        fragmentTitle: string,
+        responseContent: string,
+        files: { [path: string]: string },
+        summary: string,
+        isError: boolean,
+        canvasLayers?: any[],
+    ): Promise<any>;
 
-    readMessage(messageId: IMessageIdentifier, user: string): Promise<boolean>;
 
-    deliverMessage(messageId: IMessageIdentifier, user: string): Promise<boolean>;
-    createWithoutSubscription(data: IPostServiceInput): Promise<IPost>;
+    updateSandboxFile(
+        projectId: string,
+        messageId: string,
+        filePath: string,
+        content: string,
+    ): Promise<IFileUpdateResponse>;
 
-    createPostWithPostThread({
-        threadMessageInput,
-        channelId,
-        responderId,
-        postParentId,
-        postId,
-        accountId,
-    }: CreatePostThreadOptions): Promise<{ post: IPost; postThread: IPostThread }>;
+    /**
+     * Disposes of resources used by the service
+     */
+    dispose(): void;
 }

package/lib/templates/services/PostThreadService.ts.template

@@ -1,10 +1,155 @@
-import { IPostThread } from 'common';
-import { IBaseService } from '@common-stack/store-mongo';
+/**
+ * Post Thread Service Interface
+ * -----------------------------
+ * 
+ * This interface defines the business logic layer for post thread management
+ * within the messenger platform. It provides comprehensive operations for handling
+ * threaded conversations, reply management, and discussion organization across
+ * different channels and messaging contexts.
+ * 
+ * Key capabilities:
+ * - Thread lifecycle management (creation, updates, deletion)
+ * - Reply and response tracking within threads
+ * - Thread participant management and notifications
+ * - Thread statistics and metrics collection
+ * - Nested conversation organization
+ * - Thread visibility and access control
+ * - Cross-channel thread coordination
+ * - Thread state synchronization
+ * 
+ * The service layer abstracts complex threading operations and provides a
+ * cohesive API for thread-related functionality throughout the messaging platform,
+ * handling conversation hierarchies, participant tracking, and thread state management.
+ */
 
-export interface IPostThreadServiceInput extends Omit<IPostThread, 'id'> {}
+import { IPostThreadModel, Disposable, AsDomainType,IBaseService } from 'common/server';
 
-// export type IPostThreadService = IBaseService<IPostThread>;
 
-export interface IPostThreadService extends IBaseService<IPostThread> {
-    getPostThread(data: any): Promise<IPostThread>;
+/**
+ * Post Thread Service Input Interface
+ * 
+ * @description Input parameters for post thread creation and update operations,
+ * excluding auto-generated fields like ID. Used for operations that modify
+ * thread data before it becomes a domain object.
+ */
+export interface IPostThreadServiceInput extends Omit<IPostThreadModel, 'id'> {
+    // Add any additional input-specific fields here if needed
+}
+
+/**
+ * Post Thread Service Interface
+ * 
+ * @description Provides comprehensive post thread management capabilities
+ * including thread creation, participant tracking, and conversation organization.
+ * All operations return domain objects wrapped with AsDomainType for consistency.
+ */
+export interface IPostThreadService extends IBaseService<IPostThreadModel>, Disposable {
+    /**
+     * Retrieves a specific post thread with its metadata
+     * 
+     * @description Fetches a complete post thread including all replies,
+     * participant information, and thread statistics for display and interaction.
+     * 
+     * @param {string} threadId - The ID of the thread to retrieve
+     * @returns {Promise<AsDomainType<IPostThreadModel> | Error>} - Post thread data or error
+     */
+    getPostThread(threadId: string): Promise<AsDomainType<IPostThreadModel> | Error>;
+
+    /**
+     * Retrieves the total count of posts within a thread
+     * 
+     * @description Calculates and returns the number of posts/replies
+     * within a specific thread for pagination and display purposes.
+     * 
+     * @param {string} threadId - The ID of the thread to count posts for
+     * @returns {Promise<number | Error>} - Thread post count or error
+     */
+    getPostThreadCount(threadId: string): Promise<number | Error>;
+
+    /**
+     * Updates a post thread
+     * 
+     * @description Updates the specified thread with new data while maintaining
+     * thread integrity and participant notifications.
+     * 
+     * @param {string} threadId - The ID of the thread to update
+     * @param {Partial<IPostThreadServiceInput>} updates - The updates to apply
+     * @returns {Promise<AsDomainType<IPostThreadModel> | Error>} - Updated thread or error
+     */
+    updateThread(threadId: string, updates: Partial<IPostThreadServiceInput>): Promise<AsDomainType<IPostThreadModel> | Error>;
+
+    /**
+     * Deletes a post thread
+     * 
+     * @description Soft deletes a thread while maintaining data integrity
+     * and notifying participants.
+     * 
+     * @param {string} threadId - The ID of the thread to delete
+     * @returns {Promise<boolean | Error>} - Success status or error
+     */
+    deleteThread(threadId: string): Promise<boolean | Error>;
+
+    /**
+     * Gets threads by post ID
+     * 
+     * @description Retrieves all threads associated with a specific post,
+     * useful for viewing conversation context.
+     * 
+     * @param {string} postId - The ID of the post
+     * @returns {Promise<Array<AsDomainType<IPostThreadModel>> | Error>} - Array of threads or error
+     */
+    getThreadsByPost(postId: string): Promise<Array<AsDomainType<IPostThreadModel>> | Error>;
+
+    /**
+     * Gets threads by channel with pagination
+     * 
+     * @description Retrieves paginated threads for a specific channel,
+     * ordered by relevance or time.
+     * 
+     * @param {string} channelId - The ID of the channel
+     * @param {number} [limit] - Maximum number of threads to return
+     * @param {number} [offset] - Number of threads to skip
+     * @returns {Promise<Array<AsDomainType<IPostThreadModel>> | Error>} - Array of threads or error
+     */
+    getThreadsByChannel(channelId: string, limit?: number, offset?: number): Promise<Array<AsDomainType<IPostThreadModel>> | Error>;
+
+    /**
+     * Gets thread participants
+     * 
+     * @description Retrieves all participants in a thread, including
+     * their participation status and roles.
+     * 
+     * @param {string} threadId - The ID of the thread
+     * @returns {Promise<Array<string> | Error>} - Array of participant IDs or error
+     */
+    getThreadParticipants(threadId: string): Promise<Array<string> | Error>;
+
+    /**
+     * Adds a participant to a thread
+     * 
+     * @description Adds a user as a participant to a thread,
+     * enabling notifications and access.
+     * 
+     * @param {string} threadId - The ID of the thread
+     * @param {string} userId - The ID of the user to add
+     * @returns {Promise<boolean | Error>} - Success status or error
+     */
+    addParticipant(threadId: string, userId: string): Promise<boolean | Error>;
+
+    /**
+     * Removes a participant from a thread
+     * 
+     * @description Removes a user's participation from a thread,
+     * updating notifications and access accordingly.
+     * 
+     * @param {string} threadId - The ID of the thread
+     * @param {string} userId - The ID of the user to remove
+     * @returns {Promise<boolean | Error>} - Success status or error
+     */
+    removeParticipant(threadId: string, userId: string): Promise<boolean | Error>;
+
+    /**
+     * Disposes of resources used by the service
+     */
+    dispose(): void;
 }