@messenger-box/platform-server 10.0.3-alpha.2 → 10.0.3-alpha.202

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

@@ -0,0 +1,131 @@
+/**
+ * Messenger Stream Service Interface
+ * -----------------------------------
+ *
+ * This interface defines the service layer for real-time AI/LLM response streaming
+ * within the messenger platform. It bridges LLM token output to GraphQL PubSub,
+ * providing delta accumulation, throttling, and optional block chunking.
+ *
+ * Key capabilities:
+ * - Stream lifecycle management (start, push, end, cancel, error)
+ * - Delta accumulation with monotonic sequence numbering
+ * - 150ms delta coalescing (throttled publish)
+ * - Optional block chunking for messaging channels (Telegram, Slack, etc.)
+ * - PubSub integration for GraphQL subscription delivery
+ *
+ * Inspired by openclaw's agent-events + server-chat + BlockChunker orchestration.
+ */
+
+import {
+    IMessengerStreamDelta,
+    IMessengerStreamStatusEvent,
+    IMessengerStreamBlock,
+    IMessengerStartStreamInput,
+    IMessengerPushDeltaInput,
+    IMessengerStreamStartResult,
+    MessengerStreamStatus,
+    Disposable,
+} from 'common/server';
+
+/**
+ * Coalesce configuration for block chunking — controls when buffered text
+ * is flushed to subscribers as a block.
+ */
+export interface IBlockCoalesceConfig {
+    /** Minimum characters before flushing a block */
+    minChars: number;
+    /** Idle time (ms) before flushing whatever is buffered */
+    idleMs: number;
+}
+
+/**
+ * Extended start stream params with server-side fields.
+ */
+export interface IStartStreamParams extends IMessengerStartStreamInput {
+    /** Generated unique run ID for this stream */
+    runId: string;
+    /** Custom coalesce config (from channel dock settings) */
+    coalesceConfig?: Partial<IBlockCoalesceConfig>;
+}
+
+/**
+ * Active stream state snapshot (returned by getStreamState).
+ */
+export interface IStreamState {
+    runId: string;
+    channelId: string;
+    threadId?: string;
+    postId?: string;
+    seq: number;
+    text: string;
+    status: MessengerStreamStatus;
+}
+
+/**
+ * Stream completion event — emitted when endStream() completes successfully.
+ * Bridges ephemeral streaming pipeline to persistent post storage.
+ */
+export interface IStreamCompleteEvent {
+    runId: string;
+    channelId: string;
+    threadId?: string;
+    postId?: string;
+    /** The full accumulated text from the stream */
+    text: string;
+}
+
+/** Handler type for stream completion callbacks. */
+export type StreamCompleteHandler = (event: IStreamCompleteEvent) => Promise<void>;
+
+/**
+ * Service interface for managing AI/LLM response streaming.
+ */
+export interface IMessengerStreamService extends Disposable {
+    /**
+     * Set the PubSub instance. Called during resolver initialization
+     * since PubSub comes from IResolverOptions, not from DI container.
+     */
+    setPubSub(pubsub: any): void;
+
+    /**
+     * Register a handler called when a stream completes.
+     * Used by PostService to finalize streamed content into a Post record.
+     */
+    onStreamComplete(handler: StreamCompleteHandler): void;
+
+    /**
+     * Start a new stream. Call this when an AI/LLM response begins.
+     */
+    startStream(params: IStartStreamParams): Promise<void>;
+
+    /**
+     * Push a text delta into an active stream.
+     * Call for each token/chunk received from the LLM provider.
+     */
+    pushDelta(runId: string, delta: string): Promise<void>;
+
+    /**
+     * End a stream successfully. Flushes any pending data.
+     */
+    endStream(runId: string): Promise<void>;
+
+    /**
+     * Cancel a stream. Discards pending data.
+     */
+    cancelStream(runId: string): Promise<void>;
+
+    /**
+     * Error a stream.
+     */
+    errorStream(runId: string, error: string): Promise<void>;
+
+    /**
+     * Get the current state of an active stream (for reconnection / catch-up).
+     */
+    getStreamState(runId: string): IStreamState | undefined;
+
+    /**
+     * Dispose / cleanup the service.
+     */
+    dispose(): void;
+}

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

@@ -1,42 +1,250 @@
-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',
+// }
+
+
+/**
+ * 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>;
 
-    createFilesUploadLink(postId: string, filenames: string[], userId: string): Promise<string[]>;
-    attachUploadedFiles(postId: string, files: IUploadedFileInput[], createdBy: string): Promise<IFileInfo[]>;
+    /**
+     * 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>;
 
-    deleteFile(url: string): Promise<boolean>;
+    /**
+     * 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>;
 
-    readMessage(messageId: IMessageIdentifier, user: string): Promise<boolean>;
+    /**
+     * 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>;
 
-    deliverMessage(messageId: IMessageIdentifier, user: string): Promise<boolean>;
-    createWithoutSubscription(data: IPostServiceInput): Promise<IPost>;
+    /**
+     * Finalize a streamed post — creates or updates a Post with the accumulated
+     * text from a completed stream. Bridges streaming pipeline to persistent storage.
+     *
+     * @param event - The stream completion event containing final text and routing info
+     * @param authorId - The author (user/agent) who generated the streamed content
+     * @returns The created or updated post, or undefined on error
+     */
+    finalizeStreamedPost(
+        event: { runId: string; channelId: string; threadId?: string; postId?: string; text: string },
+        authorId?: string,
+    ): Promise<AsDomainType<IPostModel> | undefined>;
 
-    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;
 }