@messenger-box/platform-server 10.0.3-alpha.50 → 10.0.3-alpha.54

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

@@ -1,6 +1,28 @@
-import { IBaseService } from '@common-stack/store-mongo';
-import { IChannel,RoomType, IChannelUnread, IPost, IUserAccount, Maybe, Scalars } from 'common/server';
+/**
+ * Channel Service Interface
+ * -------------------------
+ * 
+ * This interface defines the business logic layer for channel management within
+ * the messenger platform. It provides a comprehensive set of operations for
+ * managing channels, their members, and related messaging workflows.
+ * 
+ * Key capabilities:
+ * - Channel lifecycle management (creation, updates, deletion)
+ * - Member management (adding, removing, role assignment)
+ * - Direct and public channel handling
+ * - Message and post management within channels
+ * - Channel visibility and access control
+ * - Notification and unread message tracking
+ * - Team-based channel organization
+ * - Channel discovery and filtering
+ * 
+ * The service layer abstracts the underlying data access operations and
+ * provides a cohesive API for channel-related functionality throughout
+ * the messaging platform, handling complex business rules and cross-cutting concerns.
+ */
 
+import { IBaseService } from '@common-stack/store-mongo';
+import { IChannel, IChannelModel, RoomType, IChannelUnread, IPost, IUserAccount, Maybe, Scalars, Disposable, AsDomainType } from 'common/server';
 
 export interface INotificationProps {
     desktopNotifyProp: boolean;
@@ -18,32 +40,31 @@ export interface IDirectChannelMemberCreate {
     explicitRoles?: string;
 }
 
-export interface ISaveDirectChannelParams extends Omit<IChannel, 'creator' | 'id' | 'type' | 'members'> {
+export interface ISaveDirectChannelParams extends Omit<IChannelModel, 'creator' | 'id' | 'type' | 'members'> {
     type: RoomType.Direct;
     creator: string;
     displayName: string;
     members: any;
 }
 
-export interface ISaveChannelParams extends Omit<IChannel, 'creator' | 'id' | 'type' | 'team'> {
+export interface ISaveChannelParams extends Omit<IChannelModel, 'creator' | 'id' | 'type' | 'team'> {
     type: RoomType;
     creator: string;
     team: string;
     orgName: string;
 }
 
-export interface IAddMemberParams extends Omit<IChannel, 'channelId' | 'memberId'> {
+export interface IAddMemberParams extends Omit<IChannelModel, 'channelId' | 'memberId'> {
     memberId: string;
     channelId: string;
 }
 
-export interface ISavePublicChannelParams extends Omit<IChannel, 'creator' | 'id' | 'orgName' | 'team'> {
+export interface ISavePublicChannelParams extends Omit<IChannelModel, 'creator' | '_id' | 'orgName' | 'team'> {
     _id?: any;
     type: RoomType.Public;
     title: string;
 }
 
-
 export interface ICreateDirectChannelParams {
     sender: string;
     receiver: string[];
@@ -57,88 +78,306 @@ export interface ISaveMembersToChannelParams {
     channelId: string;
 }
 
-// based on https://github.com/mattermost/mattermost-server/blob/master/store/sqlstore/channel_store.go
-export interface IChannelService extends IBaseService<IChannel, Omit<IChannel, 'id'>> {
+// Based on https://github.com/mattermost/mattermost-server/blob/master/store/sqlstore/channel_store.go
+export interface IChannelService extends IBaseService<IChannelModel>, Disposable {
     /**
-     * @description Direct channel don't need team reference.
-     * @param data
+     * Creates a direct channel between users
+     * 
+     * @description Direct channels don't need team reference and are used for
+     * private conversations between specific users.
+     * 
+     * @param {ICreateDirectChannelParams} data - The direct channel creation parameters
+     * @returns {Promise<AsDomainType<IChannelModel> | Error>} - The created channel or error
      */
-    createDirectChannel(data: ICreateDirectChannelParams): Promise<IChannel | Error>;
+    createDirectChannel(data: ICreateDirectChannelParams): Promise<AsDomainType<IChannelModel> | Error>;
 
+    /**
+     * Checks if a user is a member of a specific channel
+     * 
+     * @param {string} channelId - The ID of the channel to check
+     * @param {string} user - The ID of the user
+     * @returns {Promise<boolean>} - True if the user is a member
+     */
     isMember(channelId: string, user: string): Promise<boolean>;
 
-    addMemberToChannel(channelId: string, memberId: string): Promise<IChannel | Error>;
+    /**
+     * Adds a single member to a channel
+     * 
+     * @param {string} channelId - The ID of the channel
+     * @param {string} memberId - The ID of the member to add
+     * @returns {Promise<AsDomainType<IChannelModel> | Error>} - The updated channel or error
+     */
+    addMemberToChannel(channelId: string, memberId: string): Promise<AsDomainType<IChannelModel> | Error>;
 
-    saveMembersToChannel(data: ISaveMembersToChannelParams): Promise<IChannel | Error>;
+    /**
+     * Adds multiple members to a channel in a single operation
+     * 
+     * @param {ISaveMembersToChannelParams} data - The members and channel data
+     * @returns {Promise<AsDomainType<IChannelModel> | Error>} - The updated channel or error
+     */
+    saveMembersToChannel(data: ISaveMembersToChannelParams): Promise<AsDomainType<IChannelModel> | Error>;
 
-    saveDirectChannel(channel: ISaveDirectChannelParams): Promise<IChannel | Error>;
+    /**
+     * Creates and saves a direct channel
+     * 
+     * @param {ISaveDirectChannelParams} channel - The direct channel parameters
+     * @returns {Promise<AsDomainType<IChannelModel> | Error>} - The created channel or error
+     */
+    saveDirectChannel(channel: ISaveDirectChannelParams): Promise<AsDomainType<IChannelModel> | Error>;
 
-    saveChannel(data: ISaveChannelParams): Promise<IChannel | Error>;
+    /**
+     * Creates and saves a team-based channel
+     * 
+     * @param {ISaveChannelParams} data - The channel creation parameters
+     * @returns {Promise<AsDomainType<IChannelModel> | Error>} - The created channel or error
+     */
+    saveChannel(data: ISaveChannelParams): Promise<AsDomainType<IChannelModel> | Error>;
 
-    savePublicChannel(data: ISavePublicChannelParams): Promise<IChannel | Error>;
+    /**
+     * Creates and saves a public channel
+     * 
+     * @param {ISavePublicChannelParams} data - The public channel parameters
+     * @returns {Promise<AsDomainType<IChannelModel> | Error>} - The created channel or error
+     */
+    savePublicChannel(data: ISavePublicChannelParams): Promise<AsDomainType<IChannelModel> | Error>;
 
+    /**
+     * Retrieves unread message information for a user in a channel
+     * 
+     * @param {string} channelId - The ID of the channel
+     * @param {string} userId - The ID of the user
+     * @returns {Promise<IChannelUnread | Error>} - Unread information or error
+     */
     getChannelUnread(channelId: string, userId: string): Promise<IChannelUnread | Error>;
 
+    /**
+     * Invalidates cached channel data by name
+     * 
+     * @param {string} teamId - The ID of the team
+     * @param {string} name - The name of the channel
+     * @returns {Promise<void>} - Void promise when complete
+     */
     invalidateChannelByName(teamId: string, name: string): Promise<void>;
 
+    /**
+     * Retrieves all pinned posts from a channel
+     * 
+     * @param {string} channelId - The ID of the channel
+     * @returns {Promise<IPost[] | Error>} - Array of pinned posts or error
+     */
     getPinnedPosts(channelId: string): Promise<IPost[] | Error>;
 
-    getFromMaster(id: string): Promise<IChannel | Error>;
+    /**
+     * Retrieves a channel from the master database
+     * 
+     * @param {string} id - The ID of the channel
+     * @returns {Promise<AsDomainType<IChannelModel> | Error>} - The channel or error
+     */
+    getFromMaster(id: string): Promise<AsDomainType<IChannelModel> | Error>;
 
-    restore(channelId: string, time: Date);
+    /**
+     * Restores a previously deleted channel
+     * 
+     * @param {string} channelId - The ID of the channel to restore
+     * @param {Date} time - The restoration timestamp
+     * @returns {Promise<void>} - Void promise when complete
+     */
+    restore(channelId: string, time: Date): Promise<void>;
 
     /**
-     * @description remove all channels for the given team from the database.
-     * @param teamId
+     * Permanently removes all channels for a given team
+     * 
+     * @description Removes all channels associated with a team from the database.
+     * This operation cannot be undone.
+     * 
+     * @param {string} teamId - The ID of the team
+     * @returns {Promise<void | Error>} - Void promise or error
      */
-    permanentDeleteByTeam(teamId: string): void | Error;
+    permanentDeleteByTeam(teamId: string): Promise<void | Error>;
 
     /**
-     * @description removes the given channel
-     * @param channelId
+     * Permanently removes a specific channel
+     * 
+     * @description Completely removes the channel from the database.
+     * This operation cannot be undone.
+     * 
+     * @param {string} channelId - The ID of the channel to delete
+     * @returns {Promise<void | Error>} - Void promise or error
      */
-    permanentDelete(channelId: string): void | Error;
+    permanentDelete(channelId: string): Promise<void | Error>;
 
-    permanentDeleteMembersByChannel(channelId: string): void | Error;
+    /**
+     * Permanently removes all members from a channel
+     * 
+     * @param {string} channelId - The ID of the channel
+     * @returns {Promise<void | Error>} - Void promise or error
+     */
+    permanentDeleteMembersByChannel(channelId: string): Promise<void | Error>;
 
+    /**
+     * Retrieves channels for a team with filtering options
+     * 
+     * @param {string} teamId - The ID of the team
+     * @param {string} userId - The ID of the user
+     * @param {boolean} includeDeleted - Whether to include deleted channels
+     * @param {number} lastDeleteAt - Timestamp filter for deletions
+     * @param {string} orgId - The organization ID
+     * @returns {Promise<Array<AsDomainType<IChannelModel>> | Error>} - Array of channels or error
+     */
     getChannels(
         teamId: string,
         userId: string,
         includeDeleted: boolean,
         lastDeleteAt: number,
         orgId: string,
-    ): Promise<IChannel[] | Error>;
+    ): Promise<Array<AsDomainType<IChannelModel>> | Error>;
 
-    getMoreChannels(teamId: string, userId: string, offset: number, limit: number): Promise<IChannel[] | Error>;
+    /**
+     * Retrieves additional channels with pagination
+     * 
+     * @param {string} teamId - The ID of the team
+     * @param {string} userId - The ID of the user
+     * @param {number} offset - Number of items to skip
+     * @param {number} limit - Maximum number of items to return
+     * @returns {Promise<Array<AsDomainType<IChannelModel>> | Error>} - Array of channels or error
+     */
+    getMoreChannels(teamId: string, userId: string, offset: number, limit: number): Promise<Array<AsDomainType<IChannelModel>> | Error>;
 
-    getPrivateChannelsForTeam(teamId: string, offset: number, limit: number): Promise<IChannel[] | Error>;
+    /**
+     * Retrieves private channels for a team with pagination
+     * 
+     * @param {string} teamId - The ID of the team
+     * @param {number} offset - Number of items to skip
+     * @param {number} limit - Maximum number of items to return
+     * @returns {Promise<Array<AsDomainType<IChannelModel>> | Error>} - Array of private channels or error
+     */
+    getPrivateChannelsForTeam(teamId: string, offset: number, limit: number): Promise<Array<AsDomainType<IChannelModel>> | Error>;
 
-    getPublicChannelsForTeam(teamId: string, offset: number, limit: number): Promise<IChannel[] | Error>;
+    /**
+     * Retrieves public channels for a team with pagination
+     * 
+     * @param {string} teamId - The ID of the team
+     * @param {number} offset - Number of items to skip
+     * @param {number} limit - Maximum number of items to return
+     * @returns {Promise<Array<AsDomainType<IChannelModel>> | Error>} - Array of public channels or error
+     */
+    getPublicChannelsForTeam(teamId: string, offset: number, limit: number): Promise<Array<AsDomainType<IChannelModel>> | Error>;
 
-    getPublicChannelsByIdsForTeam(teamId: string, channelsIds: string[]): Promise<IChannel[] | Error>;
+    /**
+     * Retrieves specific public channels by their IDs
+     * 
+     * @param {string} teamId - The ID of the team
+     * @param {string[]} channelsIds - Array of channel IDs to retrieve
+     * @returns {Promise<Array<AsDomainType<IChannelModel>> | Error>} - Array of channels or error
+     */
+    getPublicChannelsByIdsForTeam(teamId: string, channelsIds: string[]): Promise<Array<AsDomainType<IChannelModel>> | Error>;
 
+    /**
+     * Retrieves channel count statistics for a team
+     * 
+     * @param {string} teamId - The ID of the team
+     * @param {string} userId - The ID of the user
+     * @returns {Promise<any | Error>} - Channel count data or error
+     */
     getChannelCounts(teamId: string, userId: string): Promise<any | Error>;
 
-    getTeamChannels(teamId: string): Promise<IChannel[] | Error>;
+    /**
+     * Retrieves all channels belonging to a team
+     * 
+     * @param {string} teamId - The ID of the team
+     * @returns {Promise<Array<AsDomainType<IChannelModel>> | Error>} - Array of team channels or error
+     */
+    getTeamChannels(teamId: string): Promise<Array<AsDomainType<IChannelModel>> | Error>;
 
-    // getByName(teamId: string, name: string): Promise<IChannel | Error>;
-    getByName(name: string): Promise<IChannel>;
+    /**
+     * Retrieves a channel by its name
+     * 
+     * @param {string} name - The name of the channel
+     * @returns {Promise<IChannelModel>} - The channel
+     */
+    getByName(name: string): Promise<IChannelModel>;
 
-    getByNames(teamId: string, names: string[]): Promise<IChannel[] | Error>;
+    /**
+     * Retrieves multiple channels by their names
+     * 
+     * @param {string} teamId - The ID of the team
+     * @param {string[]} names - Array of channel names
+     * @returns {Promise<Array<AsDomainType<IChannelModel>> | Error>} - Array of channels or error
+     */
+    getByNames(teamId: string, names: string[]): Promise<Array<AsDomainType<IChannelModel>> | Error>;
 
-    getByNameIncludeDeleted(teamId: string, name: string): Promise<IChannel | Error>;
+    /**
+     * Retrieves a channel by name including deleted channels
+     * 
+     * @param {string} teamId - The ID of the team
+     * @param {string} name - The name of the channel
+     * @returns {Promise<AsDomainType<IChannelModel> | Error>} - The channel or error
+     */
+    getByNameIncludeDeleted(teamId: string, name: string): Promise<AsDomainType<IChannelModel> | Error>;
 
-    getDeletedByName(teamId: string, name: string): Promise<IChannel | Error>;
+    /**
+     * Retrieves a deleted channel by name
+     * 
+     * @param {string} teamId - The ID of the team
+     * @param {string} name - The name of the deleted channel
+     * @returns {Promise<AsDomainType<IChannelModel> | Error>} - The deleted channel or error
+     */
+    getDeletedByName(teamId: string, name: string): Promise<AsDomainType<IChannelModel> | Error>;
 
-    getDeleted(teamId: string, offset: number, limit: number, userId: string): Promise<IChannel[] | Error>;
+    /**
+     * Retrieves deleted channels with pagination
+     * 
+     * @param {string} teamId - The ID of the team
+     * @param {number} offset - Number of items to skip
+     * @param {number} limit - Maximum number of items to return
+     * @param {string} userId - The ID of the user
+     * @returns {Promise<Array<AsDomainType<IChannelModel>> | Error>} - Array of deleted channels or error
+     */
+    getDeleted(teamId: string, offset: number, limit: number, userId: string): Promise<Array<AsDomainType<IChannelModel>> | Error>;
 
+    /**
+     * Saves multiple members to the system
+     * 
+     * @param {IUserAccount[]} members - Array of user accounts to save
+     * @returns {Promise<IUserAccount[] | Error>} - Array of saved user accounts or error
+     */
     saveMultipleMembers(members: IUserAccount[]): Promise<IUserAccount[] | Error>;
 
+    /**
+     * Hides a channel from the user's view
+     * 
+     * @param {string} id - The ID of the channel to hide
+     * @returns {Promise<boolean>} - True if successful
+     */
     hideChannel(id: string): Promise<boolean>;
 
+    /**
+     * Removes the current user from a channel
+     * 
+     * @param {string} id - The ID of the channel to leave
+     * @returns {Promise<boolean>} - True if successful
+     */
     leaveChannel(id: string): Promise<boolean>;
 
+    /**
+     * Soft deletes a channel (marks as deleted)
+     * 
+     * @param {string} id - The ID of the channel to delete
+     * @returns {Promise<boolean | Error>} - True if successful or error
+     */
     deleteChannel(id: string): Promise<boolean | Error>;
 
+    /**
+     * Marks a channel as viewed by a user
+     * 
+     * @param {string} id - The ID of the channel
+     * @param {string} user - The ID of the user
+     * @returns {Promise<boolean>} - True if successful
+     */
     viewChannel(id: string, user: string): Promise<boolean>;
+
+    /**
+     * Disposes of resources used by the service
+     */
+    dispose(): void;
 }

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

@@ -1,13 +1,98 @@
-import { IPostThread, IUserAccount,IAccountServiceContext } from 'common/server';
+/**
+ * Extended Token Account Service Interface
+ * ----------------------------------------
+ * 
+ * This interface extends the base account service functionality to provide
+ * enhanced token management capabilities for user accounts within the messenger
+ * platform. It specializes in device token handling, authentication management,
+ * and push notification token operations.
+ * 
+ * Key capabilities:
+ * - Device token lifecycle management (registration, updates, removal)
+ * - Auth0 integration for external authentication providers
+ * - Expo push notification token management
+ * - Account resolution by external authentication IDs
+ * - Cross-platform device token coordination
+ * - Push notification targeting and delivery management
+ * 
+ * The service layer provides a cohesive API for account-related token operations
+ * throughout the messaging platform, handling complex authentication flows and
+ * device management scenarios across multiple platforms and notification providers.
+ */
+
+import { IPostThread, IUserAccount, IAccountServiceContext, IUserAccountModel, Disposable, AsDomainType } from 'common/server';
 import { IBaseService } from '@common-stack/store-mongo';
 
 //export type IExtendedTokenAccountService = IBaseService<IUserAccount>;
 
-export interface IExtendedTokenAccountService extends IBaseService<IUserAccount> {
-    getDeviceToken(accountId: string): Promise<any>;
-    setDeviceToken(deviceToken: string, accountId: string): Promise<any>;
-    removeDeviceToken(deviceToken: string, accountId: string): Promise<any>;
-    getAccountByAuth0Id(auth0Id: string, context?: IAccountServiceContext): Promise<any>;
-    removeUserExpoTokenByAuth0Id(auth0Id: string, context?: IAccountServiceContext): Promise<any>;
-    
+/**
+ * Extended Token Account Service Interface
+ * 
+ * @description Provides enhanced account management with token operations,
+ * authentication integration, and device management capabilities.
+ */
+export interface IExtendedTokenAccountService extends IBaseService<IUserAccountModel>, Disposable {
+    /**
+     * Retrieves device tokens associated with a user account
+     * 
+     * @description Fetches all registered device tokens for push notifications
+     * and real-time messaging delivery for the specified account.
+     * 
+     * @param {string} accountId - The unique identifier of the user account
+     * @returns {Promise<any | Error>} - Device token data or error
+     */
+    getDeviceToken(accountId: string): Promise<any | Error>;
+
+    /**
+     * Registers or updates a device token for an account
+     * 
+     * @description Associates a new device token with the user account for
+     * push notification delivery. Handles token updates and duplicates.
+     * 
+     * @param {string} deviceToken - The device-specific push notification token
+     * @param {string} accountId - The unique identifier of the user account
+     * @returns {Promise<any | Error>} - Operation result or error
+     */
+    setDeviceToken(deviceToken: string, accountId: string): Promise<any | Error>;
+
+    /**
+     * Removes a specific device token from an account
+     * 
+     * @description Unregisters a device token from push notification delivery,
+     * typically when a device is logged out or uninstalled.
+     * 
+     * @param {string} deviceToken - The device token to remove
+     * @param {string} accountId - The unique identifier of the user account
+     * @returns {Promise<any | Error>} - Operation result or error
+     */
+    removeDeviceToken(deviceToken: string, accountId: string): Promise<any | Error>;
+
+    /**
+     * Retrieves a user account by Auth0 authentication ID
+     * 
+     * @description Resolves user account information using external Auth0
+     * authentication provider identifiers for SSO and federated login scenarios.
+     * 
+     * @param {string} auth0Id - The Auth0 user identifier
+     * @param {IAccountServiceContext} [context] - Optional service context for scoped operations
+     * @returns {Promise<AsDomainType<IUserAccountModel> | Error>} - User account or error
+     */
+    getAccountByAuth0Id(auth0Id: string, context?: IAccountServiceContext): Promise<AsDomainType<IUserAccountModel> | Error>;
+
+    /**
+     * Removes Expo push notification tokens by Auth0 ID
+     * 
+     * @description Cleans up all Expo-specific push notification tokens
+     * associated with an Auth0 user, typically during account deletion or logout.
+     * 
+     * @param {string} auth0Id - The Auth0 user identifier
+     * @param {IAccountServiceContext} [context] - Optional service context for scoped operations
+     * @returns {Promise<void | Error>} - Void promise or error
+     */
+    removeUserExpoTokenByAuth0Id(auth0Id: string, context?: IAccountServiceContext): Promise<void | Error>;
+
+    /**
+     * Disposes of resources used by the service
+     */
+    dispose(): void;
 }