@hexabot-ai/api 3.1.4-alpha.0 → 3.2.0-alpha.0

package/src/channel/lib/inbound-events/synthetic-message-inbound-event.ts

@@ -4,9 +4,12 @@
  * Full terms: see LICENSE.md.
  */
 
-import { PayloadType } from '@/chat/types/button';
-import { IncomingMessageType, StdIncomingMessage } from '@/chat/types/message';
-import { Payload } from '@/chat/types/quick-reply';
+import {
+  IncomingMessageType,
+  Payload,
+  PayloadType,
+  StdIncomingMessage,
+} from '@hexabot-ai/types';
 
 import { ChannelName } from '../../types';
 import type ChannelHandler from '../Handler';
@@ -33,35 +36,36 @@ export class SyntheticMessageInboundEvent<
   }
 
   override getPayload(): Payload | string | undefined {
-    if ('postback' in this.message) {
-      return this.message.postback;
+    if (
+      this.message.type === IncomingMessageType.postback ||
+      this.message.type === IncomingMessageType.quickReply
+    ) {
+      return this.message.data.payload;
     }
 
-    if ('type' in this.message) {
-      if (this.message.type === PayloadType.location) {
-        return {
-          type: PayloadType.location,
-          coordinates: {
-            lat: this.message.coordinates.lat,
-            lon: this.message.coordinates.lon,
-          },
-        };
-      }
-
-      if (this.message.type === PayloadType.attachments) {
-        const attachment = Array.isArray(this.message.attachment)
-          ? this.message.attachment[0]
-          : this.message.attachment;
+    if (this.message.type === IncomingMessageType.location) {
+      return {
+        type: PayloadType.location,
+        coordinates: {
+          lat: this.message.data.coordinates.lat,
+          lon: this.message.data.coordinates.lon,
+        },
+      };
+    }
 
-        if (!attachment) {
-          return undefined;
-        }
+    if (this.message.type === IncomingMessageType.attachment) {
+      const attachment = Array.isArray(this.message.data.attachment)
+        ? this.message.data.attachment[0]
+        : this.message.data.attachment;
 
-        return {
-          type: PayloadType.attachments,
-          attachment,
-        };
+      if (!attachment) {
+        return undefined;
       }
+
+      return {
+        type: PayloadType.attachment,
+        attachment,
+      };
     }
 
     return undefined;

package/src/channel/lib/outbound/channel-outbound-encoder.ts

@@ -5,20 +5,14 @@
  */
 
 import {
-  OutgoingMessageFormat,
-  StdOutgoingAttachmentEnvelope,
-  StdOutgoingButtonsEnvelope,
-  StdOutgoingListEnvelope,
-  StdOutgoingMessage,
+  OutgoingMessageType,
   StdOutgoingMessageEnvelope,
-  StdOutgoingQuickRepliesEnvelope,
-  StdOutgoingTextEnvelope,
-} from '@/chat/types/message';
+} from '@hexabot-ai/types';
 
 export class UnsupportedOutgoingFormatError extends Error {
   constructor(
-    public readonly format: string,
-    message = `Unsupported outgoing message format "${format}".`,
+    public readonly type: string,
+    message = `Unsupported outgoing message type "${type}".`,
   ) {
     super(message);
     this.name = 'UnsupportedOutgoingFormatError';
@@ -27,28 +21,46 @@ export class UnsupportedOutgoingFormatError extends Error {
 }
 
 export type EnvelopeHandlers<Out, Opt = unknown> = {
-  [OutgoingMessageFormat.text]: (
-    envelope: StdOutgoingTextEnvelope,
+  [OutgoingMessageType.text]: (
+    envelope: Extract<
+      StdOutgoingMessageEnvelope,
+      { type: OutgoingMessageType.text }
+    >,
     options: Opt,
   ) => Promise<Out> | Out;
-  [OutgoingMessageFormat.quickReplies]: (
-    envelope: StdOutgoingQuickRepliesEnvelope,
+  [OutgoingMessageType.quickReply]: (
+    envelope: Extract<
+      StdOutgoingMessageEnvelope,
+      { type: OutgoingMessageType.quickReply }
+    >,
     options: Opt,
   ) => Promise<Out> | Out;
-  [OutgoingMessageFormat.buttons]: (
-    envelope: StdOutgoingButtonsEnvelope,
+  [OutgoingMessageType.buttons]: (
+    envelope: Extract<
+      StdOutgoingMessageEnvelope,
+      { type: OutgoingMessageType.buttons }
+    >,
     options: Opt,
   ) => Promise<Out> | Out;
-  [OutgoingMessageFormat.attachment]: (
-    envelope: StdOutgoingAttachmentEnvelope,
+  [OutgoingMessageType.attachment]: (
+    envelope: Extract<
+      StdOutgoingMessageEnvelope,
+      { type: OutgoingMessageType.attachment }
+    >,
     options: Opt,
   ) => Promise<Out> | Out;
-  [OutgoingMessageFormat.list]: (
-    envelope: StdOutgoingListEnvelope,
+  [OutgoingMessageType.list]: (
+    envelope: Extract<
+      StdOutgoingMessageEnvelope,
+      { type: OutgoingMessageType.list }
+    >,
     options: Opt,
   ) => Promise<Out> | Out;
-  [OutgoingMessageFormat.carousel]: (
-    envelope: StdOutgoingListEnvelope,
+  [OutgoingMessageType.carousel]: (
+    envelope: Extract<
+      StdOutgoingMessageEnvelope,
+      { type: OutgoingMessageType.carousel }
+    >,
     options: Opt,
   ) => Promise<Out> | Out;
 };
@@ -64,77 +76,30 @@ export abstract class ChannelOutboundMessageEncoder<Out, Opt = unknown> {
     options: Opt,
     handlers: EnvelopeHandlers<Out, Opt>,
   ): Promise<Out> | Out {
-    switch (envelope.format) {
-      case OutgoingMessageFormat.text:
-        return handlers[OutgoingMessageFormat.text](envelope, options);
-      case OutgoingMessageFormat.quickReplies:
-        return handlers[OutgoingMessageFormat.quickReplies](envelope, options);
-      case OutgoingMessageFormat.buttons:
-        return handlers[OutgoingMessageFormat.buttons](envelope, options);
-      case OutgoingMessageFormat.attachment:
-        return handlers[OutgoingMessageFormat.attachment](envelope, options);
-      case OutgoingMessageFormat.list:
-        return handlers[OutgoingMessageFormat.list](envelope, options);
-      case OutgoingMessageFormat.carousel:
-        return handlers[OutgoingMessageFormat.carousel](envelope, options);
+    switch (envelope.type) {
+      case OutgoingMessageType.text:
+        return handlers[OutgoingMessageType.text](envelope, options);
+      case OutgoingMessageType.quickReply:
+        return handlers[OutgoingMessageType.quickReply](envelope, options);
+      case OutgoingMessageType.buttons:
+        return handlers[OutgoingMessageType.buttons](envelope, options);
+      case OutgoingMessageType.attachment:
+        return handlers[OutgoingMessageType.attachment](envelope, options);
+      case OutgoingMessageType.list:
+        return handlers[OutgoingMessageType.list](envelope, options);
+      case OutgoingMessageType.carousel:
+        return handlers[OutgoingMessageType.carousel](envelope, options);
       default:
         return this.assertNeverOutgoingEnvelope(envelope);
     }
   }
 
   protected assertNeverOutgoingEnvelope(value: never): never {
-    const unknownFormat =
-      typeof value === 'object' && value && 'format' in value
-        ? String((value as { format: unknown }).format)
+    const unknownType =
+      typeof value === 'object' && value && 'type' in value
+        ? String((value as { type: unknown }).type)
         : 'unknown';
 
-    throw new UnsupportedOutgoingFormatError(unknownFormat);
+    throw new UnsupportedOutgoingFormatError(unknownType);
   }
 }
-
-export function inferOutgoingMessageEnvelope(
-  message: StdOutgoingMessage,
-): StdOutgoingMessageEnvelope {
-  if ('buttons' in message) {
-    return {
-      format: OutgoingMessageFormat.buttons,
-      message,
-    };
-  }
-
-  if ('attachment' in message) {
-    return {
-      format: OutgoingMessageFormat.attachment,
-      message,
-    };
-  }
-
-  if ('quickReplies' in message) {
-    return {
-      format: OutgoingMessageFormat.quickReplies,
-      message,
-    };
-  }
-
-  if ('options' in message) {
-    return {
-      format:
-        message.options.display === OutgoingMessageFormat.carousel
-          ? OutgoingMessageFormat.carousel
-          : OutgoingMessageFormat.list,
-      message,
-    };
-  }
-
-  if ('text' in message) {
-    return {
-      format: OutgoingMessageFormat.text,
-      message,
-    };
-  }
-
-  throw new UnsupportedOutgoingFormatError(
-    'unknown',
-    'Unable to infer outgoing message format from message payload.',
-  );
-}

package/src/channel/lib/transports/http-channel-handler.ts

@@ -0,0 +1,187 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Source, StdEventType, Subscriber } from '@hexabot-ai/types';
+import { Inject, Injectable } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+import { SocketRequest } from '@/websocket/utils/socket-request';
+import { SocketResponse } from '@/websocket/utils/socket-response';
+
+import {
+  SubscriberResolution,
+  SubscriberResolver,
+} from '../../services/subscriber-resolver.service';
+import { ChannelName } from '../../types';
+import ChannelHandler from '../Handler';
+import type ChannelInboundEvent from '../inbound-events/channel-inbound-event';
+import type MessageInboundEvent from '../inbound-events/message-inbound-event';
+
+/**
+ * Abstract base for channels that receive events over plain HTTP webhooks
+ * (Facebook Messenger, WhatsApp Business, Slack, Discord, …).
+ *
+ * Provides the shared webhook dispatch loop so implementors only need to
+ * supply:
+ *  - `decode(req)` — parse the raw request body into typed inbound events
+ *  - `sendMessage(event, envelope, options)` — deliver outbound messages via
+ *    the platform's own HTTP API
+ *  - `getSubscriberData(event)` — map the platform's user object to a
+ *    Hexabot SubscriberCreateDto
+ *
+ * Optional overrides for common HTTP webhook concerns:
+ *  - `verifyWebhook(req, res, source)` — respond to the platform's subscription
+ *    handshake (e.g. Facebook hub.verify challenge)
+ *  - `verifySignature(req, res, source)` — authenticate the incoming payload (e.g.
+ *    HMAC-SHA256 as used by Meta, Slack, Discord)
+ *  - `resolveSubscriber(event)` — find or create a Hexabot subscriber from
+ *    the event's sender identity (default: SubscriberResolver.resolve())
+ *  - `normalizeSenderId(rawId)` — transform the platform's sender identifier
+ *    before it is used as a Hexabot foreignId
+ */
+@Injectable()
+export abstract class HttpChannelHandler<N extends ChannelName>
+  extends ChannelHandler<N>
+  implements SubscriberResolution<N>
+{
+  @Inject(SubscriberResolver)
+  private readonly subscriberResolver: SubscriberResolver;
+
+  /**
+   * Entry point called by ChannelService / WebhookController.
+   *
+   * - GET  → `verifyWebhook()` (subscription handshake)
+   * - POST → `verifySignature()` → acknowledge 200 immediately → decode +
+   *          dispatch events asynchronously
+   *
+   * Sending 200 before event processing is intentional: most messaging
+   * platforms retry if they don't receive a fast acknowledgement, leading to
+   * duplicate events.
+   */
+  async handle(
+    req: Request | SocketRequest,
+    res: Response | SocketResponse,
+    source: Source,
+    workflowId?: string,
+  ): Promise<void> {
+    if ((req as Request).method === 'GET') {
+      return this.verifyWebhook(req as Request, res as Response, source);
+    }
+
+    try {
+      await this.verifySignature(req as Request, res as Response, source);
+    } catch (err) {
+      this.logger.warn('Webhook signature verification failed', err);
+      (res as Response).status(401).json({ error: 'Unauthorized' });
+
+      return;
+    }
+
+    let events: ChannelInboundEvent<N>[];
+    try {
+      events = await this.decode(req as Request, source);
+    } catch (err) {
+      this.logger.warn('Failed to decode webhook payload', err);
+      (res as Response).status(400).json({ error: 'Bad Request' });
+
+      return;
+    }
+
+    // Acknowledge the platform before processing — prevents retries.
+    (res as Response).status(200).json({ success: true });
+
+    for (const event of events) {
+      event.setHandler(
+        this as unknown as Parameters<typeof event.setHandler>[0],
+      );
+      event.setSourceContext(source.id, source.settings);
+      if (workflowId) {
+        event.setWorkflowId(workflowId);
+      }
+
+      try {
+        const subscriber = await this.resolveSubscriber(event);
+        event.setInitiator(subscriber);
+
+        if (event.getEventType() === StdEventType.message) {
+          const messageEvent = event as unknown as MessageInboundEvent<N>;
+          await messageEvent.preprocess();
+          await this.channelEventBus.emitMessage(messageEvent);
+        } else {
+          this.channelEventBus.emitStatusEvent(event);
+        }
+      } catch (err) {
+        this.logger.error('Failed to process webhook event', err);
+      }
+    }
+  }
+
+  /**
+   * Respond to the platform's webhook subscription handshake (GET request).
+   *
+   * Default implementation returns HTTP 200 OK. Override to handle
+   * challenge-response flows (e.g. Facebook's `hub.challenge` parameter).
+   */
+  protected async verifyWebhook(
+    _req: Request,
+    res: Response,
+    _source: Source,
+  ): Promise<void> {
+    res.sendStatus(200);
+  }
+
+  /**
+   * Verify the authenticity of an incoming POST webhook payload.
+   *
+   * Default is a no-op (accepts all requests). Override to validate
+   * HMAC-SHA256 signatures or other platform-specific auth schemes.
+   * Throw any error to reject the request with HTTP 401.
+   */
+  protected async verifySignature(
+    _req: Request,
+    _res: Response,
+    _source: Source,
+  ): Promise<void> {}
+
+  /**
+   * Parse the raw HTTP request body into an array of typed inbound events.
+   *
+   * Return multiple events when the platform batches several interactions in
+   * one webhook call (e.g. Facebook's `entry[].messaging[]` structure).
+   */
+  protected abstract decode(
+    req: Request,
+    source: Source,
+  ): Promise<ChannelInboundEvent<N>[]>;
+
+  /**
+   * Find the Hexabot subscriber that corresponds to the event's sender, or
+   * create one if they are new.
+   *
+   * Delegates to SubscriberResolver using this handler as the SubscriberResolution
+   * delegate (provides `getSubscriberData` and optionally `normalizeSenderId`).
+   *
+   * Override when the platform requires a different identity resolution strategy
+   * (e.g. recipient-based lookup for delivery receipts, token exchange, etc.).
+   */
+  protected async resolveSubscriber(
+    event: ChannelInboundEvent<N>,
+  ): Promise<Subscriber> {
+    return this.subscriberResolver.resolve(event, this);
+  }
+
+  /**
+   * Transform a raw sender identifier from the platform before it is stored
+   * as a Hexabot foreignId.
+   *
+   * Default: return the identifier unchanged.
+   * Override to apply prefixes, case normalisation, or other channel-specific
+   * transformations.
+   */
+  normalizeSenderId(rawSenderId: string): string {
+    return rawSenderId;
+  }
+}

package/src/channel/lib/transports/index.ts

@@ -0,0 +1,9 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './http-channel-handler';
+
+export * from './websocket-channel-handler';

package/src/channel/lib/transports/websocket-channel-handler.ts

@@ -0,0 +1,142 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Source, StdEventType, Subscriber } from '@hexabot-ai/types';
+import { Inject, Injectable } from '@nestjs/common';
+import { Request, Response } from 'express';
+
+import { SocketRequest } from '@/websocket/utils/socket-request';
+import { SocketResponse } from '@/websocket/utils/socket-response';
+import { WebsocketGateway } from '@/websocket/websocket.gateway';
+
+import { ChannelName } from '../../types';
+import ChannelHandler from '../Handler';
+
+/**
+ * Abstract base for channels that communicate over Socket.IO (WebSocket transport).
+ *
+ * Provides transport-level plumbing:
+ *  - HTTP-request guard (rejects plain HTTP with 403)
+ *  - GET / POST routing to protected abstract hook methods
+ *  - `broadcast()` via the shared WebsocketGateway
+ *  - `sendTypingIndicator()` helper
+ *  - `isSocketRequest()` type-guard utility
+ *  - `getIpAddress()` utility
+ *
+ * Concrete channel implementations should extend this class (directly or via
+ * an intermediate base like BaseWebChannelHandler) and implement:
+ *  - `processSocketGet(req, res)` — subscription / disconnect flows
+ *  - `processSocketPost(req, res, workflowId?)` — incoming message flows
+ *  - `sendMessage(event, envelope, options)` — outbound delivery
+ *  - `getSubscriberData(event)` — subscriber profile extraction
+ */
+@Injectable()
+export abstract class WebSocketChannelHandler<
+  N extends ChannelName,
+> extends ChannelHandler<N> {
+  @Inject(WebsocketGateway)
+  protected readonly websocketGateway: WebsocketGateway;
+
+  /**
+   * Type-guard: returns true when `req` is a synthetic SocketRequest
+   * (created by the Socket.IO dispatcher) rather than a plain Express request.
+   */
+  isSocketRequest(req: Request | SocketRequest): req is SocketRequest {
+    return 'isSocket' in req && req.isSocket;
+  }
+
+  /**
+   * Returns the remote IP address of the connected socket client.
+   */
+  protected getIpAddress(req: SocketRequest): string {
+    return req.socket.handshake.address;
+  }
+
+  /**
+   * Broadcasts a typed event to all Socket.IO rooms belonging to a subscriber.
+   *
+   * @param excludedRooms - Socket IDs to skip (e.g. the originating socket).
+   */
+  protected broadcast(
+    subscriber: Subscriber,
+    type: StdEventType,
+    content: unknown,
+    excludedRooms: string[] = [],
+  ): void {
+    this.websocketGateway.broadcast(subscriber, type, content, excludedRooms);
+  }
+
+  /**
+   * Emits a typing indicator to the subscriber, then clears it after
+   * `timeout` milliseconds.
+   */
+  async sendTypingIndicator(
+    recipient: Subscriber,
+    timeout: number,
+  ): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        this.broadcast(recipient, StdEventType.typing, true);
+        setTimeout(() => {
+          this.broadcast(recipient, StdEventType.typing, false);
+          resolve();
+        }, timeout);
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * Handle an incoming GET request that arrived over the WebSocket transport.
+   * Typically used for subscription / disconnect flows.
+   */
+  protected abstract processSocketGet(
+    req: SocketRequest,
+    res: Response | SocketResponse,
+    source: Source,
+  ): Promise<void>;
+
+  /**
+   * Handle an incoming POST request that arrived over the WebSocket transport.
+   * Typically used for inbound message processing.
+   */
+  protected abstract processSocketPost(
+    req: SocketRequest,
+    res: Response | SocketResponse,
+    source: Source,
+    workflowId?: string,
+  ): Promise<void>;
+
+  /**
+   * Entry point called by ChannelService / WebhookController for every request.
+   *
+   * Rejects plain HTTP with 403 (web channels require the Socket.IO transport),
+   * then routes GET / POST to the concrete hook methods.
+   */
+  async handle(
+    req: Request | SocketRequest,
+    res: Response | SocketResponse,
+    source: Source,
+    workflowId?: string,
+  ): Promise<void> {
+    if (!this.isSocketRequest(req)) {
+      this.logger.warn(
+        'Web channel over HTTP is no longer supported. Use Socket.IO transport.',
+      );
+
+      return void res
+        .status(403)
+        .json({ err: 'Web Channel Handler : Unauthorized!' });
+    }
+
+    if (req.method === 'GET') {
+      return this.processSocketGet(req, res, source);
+    }
+
+    return this.processSocketPost(req, res, source, workflowId);
+  }
+}

package/src/channel/repositories/source.repository.ts

@@ -0,0 +1,23 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+import { BaseOrmRepository } from '@/utils/generics/base-orm.repository';
+
+import { SourceOrmEntity } from '../entities/source.entity';
+
+@Injectable()
+export class SourceRepository extends BaseOrmRepository<SourceOrmEntity> {
+  constructor(
+    @InjectRepository(SourceOrmEntity)
+    repository: Repository<SourceOrmEntity>,
+  ) {
+    super(repository, ['defaultWorkflow']);
+  }
+}