@hexabot-ai/api 3.0.0-alpha.3

package/src/channel/channel.service.ts

@@ -0,0 +1,209 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable, UnauthorizedException } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+import { SubscriberService } from '@/chat/services/subscriber.service';
+import { CONSOLE_CHANNEL_NAME } from '@/extensions/channels/console/settings';
+import { WEB_CHANNEL_NAME } from '@/extensions/channels/web/settings';
+import { LoggerService } from '@/logger/logger.service';
+import { getSessionStore } from '@/utils/constants/session-store';
+import {
+  SocketGet,
+  SocketPost,
+} from '@/websocket/decorators/socket-method.decorator';
+import { SocketReq } from '@/websocket/decorators/socket-req.decorator';
+import { SocketRes } from '@/websocket/decorators/socket-res.decorator';
+import { SocketRequest } from '@/websocket/utils/socket-request';
+import { SocketResponse } from '@/websocket/utils/socket-response';
+
+import ChannelHandler from './lib/Handler';
+import { ChannelName } from './types';
+
+@Injectable()
+export class ChannelService {
+  private registry: Map<string, ChannelHandler<ChannelName>> = new Map();
+
+  constructor(
+    private readonly logger: LoggerService,
+    private readonly subscriberService: SubscriberService,
+  ) {}
+
+  /**
+   * Registers a channel with a specific handler.
+   *
+   * @param name - The name of the channel to be registered.
+   * @param channel - The channel handler associated with the channel name.
+   * @typeParam C The channel handler's type that extends `ChannelHandler`.
+   */
+  public setChannel<T extends ChannelName, C extends ChannelHandler<T>>(
+    name: T,
+    channel: C,
+  ) {
+    this.registry.set(name, channel);
+  }
+
+  /**
+   * Retrieves all registered channel handlers.
+   *
+   * @returns An array of all channel handlers currently registered.
+   */
+  public getAll() {
+    return Array.from(this.registry.values());
+  }
+
+  /**
+   * Finds and returns the channel handler associated with the specified channel name.
+   *
+   * @param name - The name of the channel to find.
+   * @returns The channel handler associated with the specified name, or undefined if the channel is not found.
+   */
+  public findChannel(name: ChannelName) {
+    return this.getAll().find((c) => {
+      return c.getName() === name;
+    });
+  }
+
+  /**
+   * Retrieves the appropriate channel handler based on the channel name.
+   *
+   * @param channelName - The name of the channel (messenger, web, ...).
+   * @returns The handler for the specified channel.
+   */
+  public getChannelHandler<T extends ChannelName, C extends ChannelHandler<T>>(
+    name: T,
+  ): C {
+    const handler = this.registry.get(name);
+    if (!handler) {
+      throw new Error(`Channel ${name} not found`);
+    }
+
+    return handler as C;
+  }
+
+  /**
+   * Handles a request for a specific channel.
+   *
+   * @param channel - The channel for which the request is being handled.
+   * @param req - The HTTP request object.
+   * @param res - The HTTP response object.
+   * @returns A promise that resolves when the handler has processed the request.
+   */
+  async handle(channel: string, req: Request, res: Response): Promise<void> {
+    const handler = this.getChannelHandler(`${channel}-channel`);
+    handler.handle(req, res);
+  }
+
+  /**
+   * Handles a download request for a specific channel.
+   *
+   * @param channel - The channel for which the request is being handled.
+   * @param token - The file JWT token.
+   * @param req - The HTTP express request object.
+   * @returns A promise that resolves a streamable if the signed url is valid.
+   */
+  async download(channel: string, token: string, req: Request) {
+    const handler = this.getChannelHandler(`${channel}-channel`);
+
+    return await handler.download(token, req);
+  }
+
+  /**
+   * Handles a websocket request for the web channel.
+   *
+   * @param req - The websocket request object.
+   * @param res - The websocket response object.
+   */
+  @SocketGet(`/webhook/${WEB_CHANNEL_NAME}/`)
+  @SocketPost(`/webhook/${WEB_CHANNEL_NAME}/`)
+  async handleWebsocketForWebChannel(
+    @SocketReq() req: SocketRequest,
+    @SocketRes() res: SocketResponse,
+  ) {
+    this.logger.log('Channel notification (Web Socket) : ', req.method);
+    const handler = this.getChannelHandler(WEB_CHANNEL_NAME);
+
+    return await handler.handle(req, res);
+  }
+
+  /**
+   * Handles a websocket request for the admin chat console channel.
+   * It considers the user as a subscriber.
+   *
+   * @param req - The websocket request object.
+   * @param res - The websocket response object.
+   */
+  @SocketGet(`/webhook/${CONSOLE_CHANNEL_NAME}/`)
+  @SocketPost(`/webhook/${CONSOLE_CHANNEL_NAME}/`)
+  async handleWebsocketForAdminChatConsole(
+    @SocketReq() req: SocketRequest,
+    @SocketRes() res: SocketResponse,
+  ) {
+    this.logger.log(
+      'Channel notification (Admin Chat Console Socket) : ',
+      req.method,
+    );
+
+    if (!req.session.passport?.user?.id) {
+      setTimeout(() => {
+        req.socket.client.conn.close();
+      }, 300);
+      throw new UnauthorizedException(
+        'Only authenticated users are allowed to use this channel',
+      );
+    }
+
+    if (!req.session.web?.profile?.id) {
+      // Create test subscriber for the current user
+      const testSubscriber = await this.subscriberService.findOneOrCreate(
+        {
+          where: { foreign_id: req.session.passport.user.id },
+        },
+        {
+          foreign_id: req.session.passport.user.id,
+          first_name: req.session.passport.user.first_name || 'Anonymous',
+          last_name: req.session.passport.user.last_name || 'Anonymous',
+          locale: null,
+          language: null,
+          gender: null,
+          country: null,
+          labels: [],
+          assignedTo: null,
+          assignedAt: null,
+          lastvisit: new Date(),
+          retainedFrom: new Date(),
+          timezone: 0,
+          avatar: null,
+          channel: {
+            name: CONSOLE_CHANNEL_NAME,
+            data: { isSocket: true },
+          },
+          context: { vars: {} },
+        },
+      );
+
+      // Update session (end user is both a user + subscriber)
+      req.session.web = {
+        profile: testSubscriber,
+        isSocket: true,
+        messageQueue: [],
+        polling: false,
+      };
+
+      // @TODO: temporary fix until it's fixed properly: https://github.com/Hexastack/Hexabot/issues/578
+      getSessionStore().set(req.session.id, req.session, (err) => {
+        if (err) {
+          this.logger.warn('Unable to store WS Console session', err);
+        }
+      });
+    }
+
+    const handler = this.getChannelHandler(CONSOLE_CHANNEL_NAME);
+
+    return await handler.handle(req, res);
+  }
+}

package/src/channel/index.ts

@@ -0,0 +1,21 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './channel.controller';
+
+export * from './channel.middleware';
+
+export * from './channel.module';
+
+export * from './channel.service';
+
+export * from './lib/EventWrapper';
+
+export * from './lib/Handler';
+
+export * from './types';
+
+export * from './webhook.controller';

package/src/channel/lib/EventWrapper.ts

@@ -0,0 +1,410 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { AttachmentOrmEntity } from '@/attachment/entities/attachment.entity';
+import { Subscriber } from '@/chat/dto/subscriber.dto';
+import { SubscriberChannelData } from '@/chat/types/channel';
+import {
+  IncomingMessageType,
+  StdEventType,
+  StdIncomingMessage,
+} from '@/chat/types/message';
+import { Payload } from '@/chat/types/quick-reply';
+import { NLU } from '@/helper/types';
+
+import { ChannelName } from '../types';
+
+import ChannelHandler from './Handler';
+
+export interface ChannelEvent {}
+
+export default abstract class EventWrapper<
+  A extends {
+    eventType: StdEventType;
+    messageType?: IncomingMessageType;
+    raw: E;
+    attachments?: AttachmentOrmEntity[];
+  },
+  E,
+  N extends ChannelName = ChannelName,
+  C extends ChannelHandler = ChannelHandler<N>,
+  S = SubscriberChannelDict[N],
+> {
+  _adapter: A = {
+    raw: {},
+    eventType: StdEventType.unknown,
+    attachments: undefined,
+  } as A;
+
+  _handler: C;
+
+  channelAttrs: S;
+
+  subscriber!: Subscriber;
+
+  _nlp!: NLU.ParseEntities;
+
+  /**
+   * Constructor : Class used to wrap any channel's event in order
+   * to provide a unified interface for accessing data by the chatbot.
+   *
+   * Any method declared in this class should be extended and overridden in any given channel's
+   * event wrapper if needed.
+   * @param handler - The channel's handler
+   * @param event - The message event received
+   * @param channelAttrs - Channel's specific data
+   */
+  constructor(handler: C, event: A['raw'], channelAttrs: S = {} as S) {
+    this._handler = handler;
+    this._init(event);
+    this.channelAttrs = channelAttrs;
+  }
+
+  toString() {
+    return JSON.stringify(
+      {
+        handler: this._handler.getName(),
+        channelData: this.getChannelData(),
+        sender: this.getSender(),
+        // recipient: this.getRecipientForeignId(),
+        eventType: this.getEventType(),
+        messageType: this.getMessageType(),
+        payload: this.getPayload(),
+        message: this.getMessage(),
+        deliveredMessages: this.getDeliveredMessages(),
+        watermark: this.getWatermark(),
+      },
+      null,
+      4,
+    );
+  }
+
+  /**
+   * Called by the parent constructor, it defines `_adapter` which should store :
+   *
+   * - `_adapter.eventType` : The type of event received
+   *
+   *- `_adapter.messageType` : The type of message when the event is a message.
+   *
+   *- `_adapter.raw` : Sets a typed object of the event raw data
+   * @param event - The message event received from a given channel
+   */
+  abstract _init(event: A['raw']): void;
+
+  /**
+   * Retrieves the current channel handler.
+   *
+   * @returns The current instance of the channel handler.
+   */
+  getHandler(): C {
+    return this._handler;
+  }
+
+  /**
+   * Retrieves channel data.
+   *
+   * @returns Returns any channel related data.
+   */
+  getChannelData(): SubscriberChannelData<N> {
+    return {
+      name: this._handler.getName(),
+      ...this.channelAttrs,
+    } as SubscriberChannelData<N>;
+  }
+
+  /**
+   * Returns the message id.
+   * @returns the message id.
+   */
+  abstract getId(): string;
+
+  /**
+   * Sets an event attribute value
+   *
+   * @deprecated
+   * @param attr - Event attribute name
+   * @param value - The value to set for the specified attribute.
+   */
+  set(attr: string, value: any) {
+    (this._adapter as any).raw[attr] = value;
+  }
+
+  /**
+   * Returns an event attribute value, default value if it does exist
+   *
+   * @deprecated
+   * @param  attr - Event attribute name
+   * @param  otherwise - Default value if attribute does not exist
+   *
+   * @returns The value of the specified attribute or the default value.
+   */
+  get(attr: string, otherwise: any): any {
+    return attr in (this._adapter as any).raw
+      ? ((this._adapter as any).raw as any)[attr]
+      : otherwise || {};
+  }
+
+  /**
+   * Returns attached NLP parse results
+   *
+   * @returns The parsed NLP entities, or null if not available.
+   */
+  getNLP(): NLU.ParseEntities | null {
+    return this._nlp;
+  }
+
+  /**
+   * Attaches the NLP object to the event
+   *
+   * @param nlp - NLP parse results
+   */
+  setNLP(nlp: NLU.ParseEntities) {
+    this._nlp = nlp;
+  }
+
+  /**
+   * Returns event sender/profile id (channel's id)
+   *
+   * @returns sender/profile id
+   */
+  abstract getSenderForeignId(): string;
+
+  /**
+   * Returns event sender data
+   *
+   * @returns event sender data
+   */
+  getSender(): Subscriber {
+    return this.subscriber;
+  }
+
+  /**
+   * Sets event sender data
+   *
+   * @param profile - Sender data
+   */
+  setSender(profile: Subscriber) {
+    this.subscriber = profile;
+  }
+
+  /**
+   * Pre-Process the message event
+   *
+   * Child class can perform operations such as storing files as attachments.
+   */
+  async preprocess() {
+    if (
+      this._adapter.eventType === StdEventType.message &&
+      this._adapter.messageType === IncomingMessageType.attachments
+    ) {
+      await this._handler.persistMessageAttachments(
+        this as EventWrapper<
+          any,
+          any,
+          ChannelName,
+          ChannelHandler<ChannelName>,
+          Record<string, any>
+        >,
+      );
+    }
+  }
+
+  /**
+   * Returns event recipient id
+   *
+   * @returns event recipient id
+   */
+  abstract getRecipientForeignId(): string;
+
+  /**
+   * Returns the type of event received (message, delivery, read, ...)
+   *
+   * @returns The type of event received (message, delivery, read, ...)
+   */
+  getEventType(): StdEventType {
+    return this._adapter.eventType;
+  }
+
+  /**
+   * Identifies the type of the message received
+   *
+   * @return The type of message
+   */
+  getMessageType(): IncomingMessageType | undefined {
+    return this._adapter.messageType;
+  }
+
+  /**
+   * Return payload whenever user clicks on a button/quick_reply or sends an attachment, false otherwise
+   *
+   * @returns The payload content
+   */
+  abstract getPayload(): Payload | string | undefined;
+
+  /**
+   * Returns the message in a standardized format
+   *
+   * @returns The received message
+   */
+  abstract getMessage(): StdIncomingMessage;
+
+  /**
+   * Return the text message received
+   *
+   * @returns Received text message
+   */
+  getText(): string {
+    const message = this.getMessage();
+    if ('text' in message) {
+      return message.text;
+    } else if ('serialized_text' in message) {
+      return message.serialized_text;
+    }
+
+    return '';
+  }
+
+  /**
+   * Returns the list of delivered messages
+   *
+   * @returns Array of message ids
+   */
+  abstract getDeliveredMessages(): string[];
+
+  /**
+   * Returns the message's watermark
+   *
+   * @returns The message's watermark
+   */
+  abstract getWatermark(): number;
+}
+
+type GenericEvent = { senderId: string; messageId: string };
+type GenericEventAdapter = {
+  eventType: StdEventType.unknown;
+  messageType: IncomingMessageType.unknown;
+  raw: GenericEvent;
+};
+
+export class GenericEventWrapper extends EventWrapper<
+  GenericEventAdapter,
+  GenericEvent,
+  ChannelName
+> {
+  /**
+   * Constructor : channel's event wrapper
+   *
+   * @param  handler - The channel's handler
+   * @param event - The message event received
+   */
+  constructor(handler: ChannelHandler, event: GenericEvent) {
+    super(handler, event);
+  }
+
+  /**
+   * Called by the parent constructor, it defines :
+   * 
+   *     - The type of event received
+   * 
+   *     - The type of message when the event is a message.
+   * 
+   *     - Sets a typed raw object of the event data
+   * @param event - The message event received
+
+   */
+  _init(event: GenericEvent): void {
+    this._adapter.eventType = StdEventType.unknown;
+    this._adapter.messageType = IncomingMessageType.unknown;
+    this._adapter.raw = event;
+  }
+
+  /**
+   * Returns the message id
+   *
+   * @returns The message id
+   */
+  getId(): string {
+    if (this._adapter.raw.messageId) {
+      return this._adapter.raw.messageId;
+    }
+    throw new Error('The message id `mid` is missing');
+  }
+
+  /**
+   * Returns event sender id
+   *
+   * @returns event sender id
+   */
+  getSenderForeignId(): string {
+    if (this._adapter.raw.senderId) {
+      return this._adapter.raw.senderId;
+    }
+    throw new Error('The sender id is missing');
+  }
+
+  /**
+   * Returns event recipient id (channel's id)
+   *
+   * @returns Returns event recipient id
+   */
+  getRecipientForeignId(): string {
+    throw new Error('The recipient id is missing');
+  }
+
+  /**
+   * Returns the type of event received
+   *
+   * @returns The type of event received
+   */
+  getEventType(): StdEventType {
+    return this._adapter.eventType;
+  }
+
+  /**
+   * Finds out and returns the type of the event received from the channel
+   *
+   * @returns The type of message
+   */
+  getMessageType(): IncomingMessageType {
+    return this._adapter.messageType;
+  }
+
+  /**
+   * Returns payload whenever user clicks on a button/quick_reply or sends an attachment
+   *
+   * @returns The payload content
+   */
+  getPayload(): Payload | string | undefined {
+    return undefined;
+  }
+
+  /**
+   * Returns a standard message format that can be stored in DB
+   *
+   * @returns Received message in standard format
+   */
+  getMessage(): StdIncomingMessage {
+    throw new Error('Unknown incoming message type');
+  }
+
+  /**
+   * Returns the delivered messages ids
+   *
+   * @returns return delivered messages ids
+   */
+  getDeliveredMessages(): string[] {
+    return [];
+  }
+
+  /**
+   * Returns the message's watermark (timestamp or equivalent).
+   *
+   * @returns The message's watermark
+   */
+  getWatermark() {
+    return 0;
+  }
+}