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

package/src/chat/helpers/envelope-builder.ts

@@ -4,10 +4,8 @@
  * Full terms: see LICENSE.md.
  */
 
-import { z } from 'zod';
-
 import {
-  OutgoingMessageFormat,
+  OutgoingMessageType,
   StdOutgoingAttachmentEnvelope,
   stdOutgoingAttachmentEnvelopeSchema,
   StdOutgoingButtonsEnvelope,
@@ -22,21 +20,22 @@ import {
   stdOutgoingSystemEnvelopeSchema,
   StdOutgoingTextEnvelope,
   stdOutgoingTextEnvelopeSchema,
-} from '../types/message';
+} from '@hexabot-ai/types';
+import { z } from 'zod';
 
 type ArrayKeys<T> = {
   [K in keyof T]: NonNullable<T[K]> extends Array<any> ? K : never;
 }[keyof T];
 
 export type IEnvelopeBuilder<T extends StdOutgoingEnvelope> = {
-  [K in keyof T['message'] as `set${Capitalize<string & K>}`]-?: (
-    arg: T['message'][K],
+  [K in keyof T['data'] as `set${Capitalize<string & K>}`]-?: (
+    arg: T['data'][K],
   ) => IEnvelopeBuilder<T>;
 } & {
-  [K in keyof T['message'] as `get${Capitalize<string & K>}`]-?: () => T['message'][K];
+  [K in keyof T['data'] as `get${Capitalize<string & K>}`]-?: () => T['data'][K];
 } & {
-  [K in ArrayKeys<T['message']> as `appendTo${Capitalize<string & K>}`]: (
-    item: NonNullable<T['message'][K]> extends (infer U)[] ? U : never,
+  [K in ArrayKeys<T['data']> as `appendTo${Capitalize<string & K>}`]: (
+    item: NonNullable<T['data'][K]> extends (infer U)[] ? U : never,
   ) => IEnvelopeBuilder<T>;
 } & {
   build(): T;
@@ -53,18 +52,18 @@ function getAttributeNameFromProp(prop: string, prefix: RegExp) {
   // e.g. "appendToButtons" => "Buttons"
   const rawKey = prop.toString().replace(prefix, '');
   // e.g. "Buttons" -> "buttons"
-  const messageKey = rawKey.charAt(0).toLowerCase() + rawKey.slice(1);
+  const dataKey = rawKey.charAt(0).toLowerCase() + rawKey.slice(1);
 
-  return messageKey;
+  return dataKey;
 }
 
 /**
- * Builds an envelope object (containing a `format` and a `message` property)
+ * Builds an envelope object (containing a `type` and a `data` property)
  * and returns a proxy-based builder interface with chainable setter methods.
  * It also validates the final envelope against the provided `z.ZodSchema`.
  *
- * @param format - The format of the outgoing envelope.
- * Corresponds to `format` on the generic type `T`.
+ * @param type - The type of the outgoing envelope.
+ * Corresponds to `type` on the generic type `T`.
  * @param template - An optional initial message template.
  * It will be merged as you set or append properties through the returned builder.
  * @param schema - A Zod schema used to validate the final envelope object.
@@ -76,20 +75,20 @@ function getAttributeNameFromProp(prop: string, prefix: RegExp) {
  *
  * @example
  * // Build a simple text envelope:
- * const env1 = EnvelopeBuilder(OutgoingMessageFormat.text)
+ * const env1 = EnvelopeBuilder(OutgoingMessageType.text)
  *   .setText('Hello')
  *   .build();
  *
  * @example
  * // Build a text envelope with quick replies:
- * const env2 = EnvelopeBuilder(OutgoingMessageFormat.quickReplies)
+ * const env2 = EnvelopeBuilder(OutgoingMessageType.quickReply)
  *   .setText('Hello')
  *   .setQuickReplies([])
  *   .build();
  *
  * @example
  * // Append multiple quickReplies items:
- * const env3 = EnvelopeBuilder(OutgoingMessageFormat.quickReplies)
+ * const env3 = EnvelopeBuilder(OutgoingMessageType.quickReply)
  *   .setText('Are you interested?')
  *   .appendToQuickReplies({
  *     title: 'Yes',
@@ -103,18 +102,18 @@ function getAttributeNameFromProp(prop: string, prefix: RegExp) {
  *
  * @example
  * // Build a system envelope with an outcome:
- * const env4 = EnvelopeBuilder(OutgoingMessageFormat.system)
+ * const env4 = EnvelopeBuilder(OutgoingMessageType.system)
  *   .setOutcome('success')
  *   .build();
  */
 export function EnvelopeBuilder<T extends StdOutgoingEnvelope>(
-  format: T['format'],
-  template: Partial<T['message']> = {},
+  type: T['type'],
+  template: Partial<T['data']> = {},
   schema: z.ZodType,
 ): IEnvelopeBuilder<T> {
-  let built: { format: T['format']; message: Partial<T['message']> } = {
-    format,
-    message: template,
+  let built: { type: T['type']; data: Partial<T['data']> } = {
+    type,
+    data: template,
   };
 
   const builder = new Proxy(
@@ -126,8 +125,8 @@ export function EnvelopeBuilder<T extends StdOutgoingEnvelope>(
           return () => {
             const result = schema.parse(built);
             built = {
-              format,
-              message: template,
+              type,
+              data: template,
             };
 
             return result;
@@ -135,14 +134,14 @@ export function EnvelopeBuilder<T extends StdOutgoingEnvelope>(
         }
 
         if (typeof prop === 'string' && prop.startsWith('appendTo')) {
-          const messageKey = getAttributeNameFromProp(prop, /^appendTo/);
+          const dataKey = getAttributeNameFromProp(prop, /^appendTo/);
 
           return (item: unknown) => {
             // Initialize the array if needed
-            if (!Array.isArray(built.message[messageKey])) {
-              built.message[messageKey] = [];
+            if (!Array.isArray(built.data[dataKey])) {
+              built.data[dataKey] = [];
             }
-            (built.message[messageKey] as unknown[]).push(item);
+            (built.data[dataKey] as unknown[]).push(item);
 
             return builder;
           };
@@ -151,17 +150,14 @@ export function EnvelopeBuilder<T extends StdOutgoingEnvelope>(
         return (...args: unknown[]): unknown => {
           // If no arguments passed return current value.
           if (0 === args.length) {
-            const messageKey = getAttributeNameFromProp(
-              prop.toString(),
-              /^get/,
-            );
+            const dataKey = getAttributeNameFromProp(prop.toString(), /^get/);
 
-            return built.message[messageKey];
+            return built.data[dataKey];
           }
 
           const value = args[0];
-          const messageKey = getAttributeNameFromProp(prop.toString(), /^set/);
-          built.message[messageKey] = value;
+          const dataKey = getAttributeNameFromProp(prop.toString(), /^set/);
+          built.data[dataKey] = value;
 
           return builder;
         };
@@ -172,39 +168,37 @@ export function EnvelopeBuilder<T extends StdOutgoingEnvelope>(
   return builder as IEnvelopeBuilder<T>;
 }
 
-type EnvelopeTypeByFormat<F extends OutgoingMessageFormat> =
-  F extends OutgoingMessageFormat.text
+type EnvelopeTypeByType<T extends OutgoingMessageType> =
+  T extends OutgoingMessageType.text
     ? StdOutgoingTextEnvelope
-    : F extends OutgoingMessageFormat.quickReplies
+    : T extends OutgoingMessageType.quickReply
       ? StdOutgoingQuickRepliesEnvelope
-      : F extends OutgoingMessageFormat.buttons
+      : T extends OutgoingMessageType.buttons
         ? StdOutgoingButtonsEnvelope
-        : F extends OutgoingMessageFormat.attachment
+        : T extends OutgoingMessageType.attachment
           ? StdOutgoingAttachmentEnvelope
-          : F extends OutgoingMessageFormat.carousel
+          : T extends OutgoingMessageType.carousel
             ? StdOutgoingListEnvelope
-            : F extends OutgoingMessageFormat.list
+            : T extends OutgoingMessageType.list
               ? StdOutgoingListEnvelope
-              : F extends OutgoingMessageFormat.system
+              : T extends OutgoingMessageType.system
                 ? StdOutgoingSystemEnvelope
                 : StdOutgoingMessageEnvelope;
 
-const ENVELOP_SCHEMAS_BY_FORMAT = {
-  [OutgoingMessageFormat.text]: stdOutgoingTextEnvelopeSchema,
-  [OutgoingMessageFormat.quickReplies]: stdOutgoingQuickRepliesEnvelopeSchema,
-  [OutgoingMessageFormat.buttons]: stdOutgoingButtonsEnvelopeSchema,
-  [OutgoingMessageFormat.attachment]: stdOutgoingAttachmentEnvelopeSchema,
-  [OutgoingMessageFormat.carousel]: stdOutgoingListEnvelopeSchema,
-  [OutgoingMessageFormat.list]: stdOutgoingListEnvelopeSchema,
-  [OutgoingMessageFormat.system]: stdOutgoingSystemEnvelopeSchema,
+const ENVELOPE_SCHEMAS_BY_TYPE = {
+  [OutgoingMessageType.text]: stdOutgoingTextEnvelopeSchema,
+  [OutgoingMessageType.quickReply]: stdOutgoingQuickRepliesEnvelopeSchema,
+  [OutgoingMessageType.buttons]: stdOutgoingButtonsEnvelopeSchema,
+  [OutgoingMessageType.attachment]: stdOutgoingAttachmentEnvelopeSchema,
+  [OutgoingMessageType.carousel]: stdOutgoingListEnvelopeSchema,
+  [OutgoingMessageType.list]: stdOutgoingListEnvelopeSchema,
+  [OutgoingMessageType.system]: stdOutgoingSystemEnvelopeSchema,
 };
 
-export const getEnvelopeBuilder = <F extends OutgoingMessageFormat>(
-  format: F,
-) => {
-  return EnvelopeBuilder<EnvelopeTypeByFormat<F>>(
-    format,
+export const getEnvelopeBuilder = <F extends OutgoingMessageType>(type: F) => {
+  return EnvelopeBuilder<EnvelopeTypeByType<F>>(
+    type,
     {},
-    ENVELOP_SCHEMAS_BY_FORMAT[format],
+    ENVELOPE_SCHEMAS_BY_TYPE[type],
   );
 };

package/src/chat/helpers/envelope-factory.ts

@@ -4,23 +4,24 @@
  * Full terms: see LICENSE.md.
  */
 
-import { getRandomElement } from '@/utils/helpers/safeRandom';
-
-import { AttachmentPayload } from '../types/attachment';
-import { Button, ButtonType } from '../types/button';
 import {
+  AttachmentPayload,
+  Button,
+  ButtonType,
   ContentElement,
+  ContentOptions,
   ContentPagination,
-  OutgoingMessageFormat,
+  OutgoingMessageType,
   StdOutgoingAttachmentEnvelope,
   StdOutgoingButtonsEnvelope,
   StdOutgoingListEnvelope,
   StdOutgoingQuickRepliesEnvelope,
   StdOutgoingSystemEnvelope,
   StdOutgoingTextEnvelope,
-} from '../types/message';
-import { ContentOptions } from '../types/options';
-import { StdQuickReply } from '../types/quick-reply';
+  StdQuickReply,
+} from '@hexabot-ai/types';
+
+import { getRandomElement } from '@/utils/helpers/safeRandom';
 
 import { getEnvelopeBuilder } from './envelope-builder';
 
@@ -36,14 +37,14 @@ export class EnvelopeFactory {
   }
 
   /**
-   * Returns an envelope builder instance for the specified message format.
+   * Returns an envelope builder instance for the specified message type.
    *
-   * @template F - The envelope message format extending OutgoingMessageFormat.
-   * @param format - The desired envelope message format.
-   * @returns A builder instance for creating envelopes of the specified format.
+   * @template F - The envelope message type extending OutgoingMessageType.
+   * @param type - The desired envelope message type.
+   * @returns A builder instance for creating envelopes of the specified type.
    */
-  getBuilder<F extends OutgoingMessageFormat>(format: F) {
-    return getEnvelopeBuilder<F>(format);
+  getBuilder<F extends OutgoingMessageType>(type: F) {
+    return getEnvelopeBuilder<F>(type);
   }
 
   /**
@@ -56,7 +57,7 @@ export class EnvelopeFactory {
    * @returns A finalized text envelope object.
    */
   buildTextEnvelope(text: string | string[]): StdOutgoingTextEnvelope {
-    const builder = this.getBuilder(OutgoingMessageFormat.text);
+    const builder = this.getBuilder(OutgoingMessageType.text);
     const processedText = this.processText(text);
 
     return builder.setText(processedText).build();
@@ -76,7 +77,7 @@ export class EnvelopeFactory {
     text: string | string[],
     quickReplies: StdQuickReply[],
   ): StdOutgoingQuickRepliesEnvelope {
-    const builder = this.getBuilder(OutgoingMessageFormat.quickReplies);
+    const builder = this.getBuilder(OutgoingMessageType.quickReply);
     const processedText = this.processText(text);
     const envelope = builder.setText(processedText);
 
@@ -106,7 +107,7 @@ export class EnvelopeFactory {
     text: string | string[],
     buttons: Button[],
   ): StdOutgoingButtonsEnvelope {
-    const builder = this.getBuilder(OutgoingMessageFormat.buttons);
+    const builder = this.getBuilder(OutgoingMessageType.buttons);
     const processedText = this.processText(text);
     const envelope = builder.setText(processedText);
 
@@ -141,7 +142,7 @@ export class EnvelopeFactory {
     attachment: AttachmentPayload,
     quickReplies: StdQuickReply[] = [],
   ): StdOutgoingAttachmentEnvelope {
-    const builder = this.getBuilder(OutgoingMessageFormat.attachment);
+    const builder = this.getBuilder(OutgoingMessageType.attachment);
     const envelope = builder.setAttachment(attachment);
 
     quickReplies.forEach((qr) => {
@@ -161,19 +162,19 @@ export class EnvelopeFactory {
    * This method builds a list envelope (applicable for both carousel and list formats)
    * by setting options, elements, and pagination details on the envelope.
    *
-   * @param format - The envelope format (carousel or list).
+   * @param type - The envelope type (carousel or list).
    * @param options - Options for content presentation.
    * @param elements - An array of content elements.
    * @param pagination - Pagination details for the content.
    * @returns A finalized list envelope object.
    */
   buildListEnvelope(
-    format: OutgoingMessageFormat.carousel | OutgoingMessageFormat.list,
+    type: OutgoingMessageType.carousel | OutgoingMessageType.list,
     options: ContentOptions,
     elements: ContentElement[],
     pagination: ContentPagination,
   ): StdOutgoingListEnvelope {
-    const builder = this.getBuilder(format);
+    const builder = this.getBuilder(type);
 
     return builder
       .setOptions(options)
@@ -196,7 +197,7 @@ export class EnvelopeFactory {
     outcome: string | undefined,
     data?: unknown,
   ): StdOutgoingSystemEnvelope {
-    const builder = this.getBuilder(OutgoingMessageFormat.system);
+    const builder = this.getBuilder(OutgoingMessageType.system);
 
     return builder.setOutcome(outcome).setData(data).build();
   }

package/src/chat/index.ts

@@ -64,14 +64,4 @@ export * from './services/subscriber.service';
 
 export * from './services/thread.service';
 
-export * from './types/attachment';
-
-export * from './types/button';
-
 export * from './types/channel';
-
-export * from './types/message';
-
-export * from './types/options';
-
-export * from './types/quick-reply';

package/src/chat/repositories/message.repository.ts

@@ -4,14 +4,13 @@
  * Full terms: see LICENSE.md.
  */
 
+import { ThreadStub, Message } from '@hexabot-ai/types';
 import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
 
 import { BaseOrmRepository } from '@/utils/generics/base-orm.repository';
 
-import { Message } from '../dto/message.dto';
-import { ThreadStub } from '../dto/thread.dto';
 import { MessageOrmEntity } from '../entities/message.entity';
 
 @Injectable()

package/src/chat/repositories/subscriber.repository.ts

@@ -4,6 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
+import { Subscriber, SubscriberFull } from '@hexabot-ai/types';
 import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { FindManyOptions, Repository } from 'typeorm';
@@ -14,11 +15,7 @@ import {
   FindAllOptions,
 } from '@/utils/generics/base-orm.repository';
 
-import {
-  Subscriber,
-  SubscriberFull,
-  SubscriberUpdateDto,
-} from '../dto/subscriber.dto';
+import { SubscriberUpdateDto } from '../dto/subscriber.dto';
 import { SubscriberOrmEntity } from '../entities/subscriber.entity';
 
 @Injectable()
@@ -27,7 +24,14 @@ export class SubscriberRepository extends BaseOrmRepository<SubscriberOrmEntity>
     @InjectRepository(SubscriberOrmEntity)
     repository: Repository<SubscriberOrmEntity>,
   ) {
-    super(repository, ['labels', 'assignedTo', 'avatar']);
+    super(repository, ['labels', 'assignedTo', 'avatar', 'source']);
+  }
+
+  private buildForeignIdWhere(id: string, sourceId?: string) {
+    return {
+      foreignId: id,
+      ...(sourceId ? { source: { id: sourceId } } : {}),
+    };
   }
 
   /**
@@ -37,9 +41,12 @@ export class SubscriberRepository extends BaseOrmRepository<SubscriberOrmEntity>
    *
    * @returns The found subscriber entity, or `null` if no subscriber is found.
    */
-  async findOneByForeignId(id: string): Promise<Subscriber | null> {
+  async findOneByForeignId(
+    id: string,
+    sourceId?: string,
+  ): Promise<Subscriber | null> {
     return await this.findOne({
-      where: { foreignId: id },
+      where: this.buildForeignIdWhere(id, sourceId),
       order: { lastvisit: 'DESC' },
     });
   }
@@ -53,9 +60,10 @@ export class SubscriberRepository extends BaseOrmRepository<SubscriberOrmEntity>
    */
   async findOneByForeignIdAndPopulate(
     id: string,
+    sourceId?: string,
   ): Promise<SubscriberFull | null> {
     const result = await this.findOneAndPopulate({
-      where: { foreignId: id },
+      where: this.buildForeignIdWhere(id, sourceId),
       order: { lastvisit: 'DESC' },
     });
 
@@ -73,10 +81,11 @@ export class SubscriberRepository extends BaseOrmRepository<SubscriberOrmEntity>
   async updateOneByForeignIdQuery(
     id: string,
     updates: SubscriberUpdateDto,
+    sourceId?: string,
   ): Promise<Subscriber> {
     return await this.updateOne(
       {
-        where: { foreignId: id },
+        where: this.buildForeignIdWhere(id, sourceId),
       },
       updates,
     );
@@ -89,13 +98,14 @@ export class SubscriberRepository extends BaseOrmRepository<SubscriberOrmEntity>
    *
    * @returns The updated subscriber entity.
    */
-  async handBackByForeignIdQuery(foreignId: string): Promise<Subscriber> {
-    const previous = await this.findOneByForeignId(foreignId);
+  async handBackByForeignIdQuery(
+    foreignId: string,
+    sourceId?: string,
+  ): Promise<Subscriber> {
+    const previous = await this.findOneByForeignId(foreignId, sourceId);
     const updated = await this.updateOne(
       {
-        where: {
-          foreignId,
-        },
+        where: this.buildForeignIdWhere(foreignId, sourceId),
       },
       {
         assignedTo: null,
@@ -128,12 +138,11 @@ export class SubscriberRepository extends BaseOrmRepository<SubscriberOrmEntity>
   async handOverByForeignIdQuery(
     foreignId: string,
     userId: string,
+    sourceId?: string,
   ): Promise<Subscriber> {
     return await this.updateOne(
       {
-        where: {
-          foreignId,
-        },
+        where: this.buildForeignIdWhere(foreignId, sourceId),
       },
       {
         assignedTo: userId,

package/src/chat/repositories/thread.repository.ts

@@ -4,13 +4,13 @@
  * Full terms: see LICENSE.md.
  */
 
+import { Thread } from '@hexabot-ai/types';
 import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
 
 import { BaseOrmRepository } from '@/utils/generics/base-orm.repository';
 
-import { Thread } from '../dto/thread.dto';
 import { ThreadOrmEntity } from '../entities/thread.entity';
 
 @Injectable()
@@ -19,7 +19,7 @@ export class ThreadRepository extends BaseOrmRepository<ThreadOrmEntity> {
     @InjectRepository(ThreadOrmEntity)
     repository: Repository<ThreadOrmEntity>,
   ) {
-    super(repository, ['subscriber']);
+    super(repository, ['subscriber', 'source']);
   }
 
   async findLatestOpenThreadForSubscriber(

package/src/chat/services/chat.service.ts

@@ -207,12 +207,17 @@ export class ChatService {
   async handleEchoMessage(event: MessageInboundEvent) {
     this.logger.verbose('Message echo received', event.getRaw());
     const foreignId = event.getRecipientForeignId();
+    const sourceId =
+      typeof event.getSourceId === 'function'
+        ? (event.getSourceId() ?? undefined)
+        : undefined;
 
     if (foreignId) {
       try {
-        const recipient = await this.subscriberService.findOne({
-          where: { foreignId },
-        });
+        const recipient = await this.subscriberService.findOneByForeignId(
+          foreignId,
+          sourceId,
+        );
 
         if (!recipient) {
           throw new Error(`Subscriber with foreign ID ${foreignId} not found`);
@@ -225,6 +230,7 @@ export class ChatService {
             await this.threadService.resolveOrCreateThread({
               subscriberId: recipient.id,
               explicitThreadId: event.getThreadId(),
+              sourceId,
             })
           ).id,
           message: event.getMessage(),
@@ -250,16 +256,25 @@ export class ChatService {
     this.logger.debug('New message received', event.getRaw());
 
     const foreignId = event.getSenderForeignId();
+    const sourceId =
+      typeof event.getSourceId === 'function'
+        ? (event.getSourceId() ?? undefined)
+        : undefined;
+    if (!sourceId) {
+      throw new Error('Cannot handle incoming message without source id');
+    }
     const handler = event.getHandler();
 
     try {
-      let subscriber = await this.subscriberService.findOne({
-        where: { foreignId },
-      });
+      let subscriber = await this.subscriberService.findOneByForeignId(
+        foreignId,
+        sourceId,
+      );
 
       if (!subscriber) {
         const subscriberData = await handler.getSubscriberData(event);
         subscriberData.channel = event.getChannelData();
+        subscriberData.source = sourceId;
         subscriber = await this.subscriberService.create(subscriberData);
 
         if (!subscriber) {
@@ -292,13 +307,17 @@ export class ChatService {
       // Set the subscriber object
       event.setInitiator(subscriber!);
 
-      const channelSettings = await handler.getSettings();
+      const channelSettings =
+        typeof event.getSourceSettings === 'function'
+          ? event.getSourceSettings()
+          : {};
       const inactivityHours =
         this.threadService.resolveInactivityHours(channelSettings);
       const thread = await this.threadService.resolveThreadForIncoming({
         subscriberId: subscriber.id,
         explicitThreadId: event.getThreadId(),
         inactivityHours,
+        sourceId,
       });
       event.setThreadId(thread.id);
 

package/src/chat/services/message.service.ts

@@ -4,13 +4,12 @@
  * Full terms: see LICENSE.md.
  */
 
+import { ThreadStub, Message, Thread } from '@hexabot-ai/types';
 import { Injectable } from '@nestjs/common';
 
 import { BaseOrmService } from '@/utils/generics/base-orm.service';
 import { WebsocketGateway } from '@/websocket/websocket.gateway';
 
-import { Message } from '../dto/message.dto';
-import { Thread, ThreadStub } from '../dto/thread.dto';
 import { MessageOrmEntity } from '../entities/message.entity';
 import { MessageRepository } from '../repositories/message.repository';