Merge pull request #546 from Hexastack/refactor/attachment-payload

feat: Refactor attachment payload + use public signed urls in web channel

api/src/chat/dto/subscriber.dto.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -112,6 +112,16 @@ export class SubscriberCreateDto {
   @IsNotEmpty()
   @IsChannelData()
   channel: SubscriberChannelData<ChannelName>;
+
+  @ApiPropertyOptional({
+    description: 'Subscriber Avatar',
+    type: String,
+    default: null,
+  })
+  @IsOptional()
+  @IsString()
+  @IsObjectId({ message: 'Avatar Attachment ID must be a valid ObjectId' })
+  avatar?: string | null = null;
 }
 
 export class SubscriberUpdateDto extends PartialType(SubscriberCreateDto) {}

api/src/chat/repositories/block.repository.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -58,7 +58,7 @@ export class BlockRepository extends BaseRepository<
       'url' in block.message.attachment.payload
     ) {
       this.logger?.error(
-        'NOTE: `url` payload has been deprecated in favor of `attachment_id`',
+        'NOTE: `url` payload has been deprecated in favor of `id`',
         block.name,
       );
     }

api/src/chat/schemas/types/attachment.ts

@@ -6,8 +6,6 @@
  * 2. All derivative works must include clear attribution to the original creator and software, Hexastack and Hexabot, in a prominent location (e.g., in the software's "About" section, documentation, and README file).
  */
 
-import { Attachment } from '@/attachment/schemas/attachment.schema';
-
 export enum FileType {
   image = 'image',
   video = 'video',
@@ -16,21 +14,24 @@ export enum FileType {
   unknown = 'unknown',
 }
 
-export type AttachmentForeignKey = {
-  url?: string;
-  attachment_id: string;
-};
+/**
+ * The `AttachmentRef` type defines two possible ways to reference an attachment:
+ * 1. By `id`: This is used when the attachment is uploaded and stored in the Hexabot system.
+ * The `id` field represents the unique identifier of the uploaded attachment in the system.
+ * 2. By `url`: This is used when the attachment is externally hosted, especially when
+ * the content is generated or retrieved by a plugin that consumes a third-party API.
+ * In this case, the `url` field contains the direct link to the external resource.
+ */
+export type AttachmentRef =
+  | {
+      id: string | null;
+    }
+  | {
+      /** @deprecated To be used only for external URLs (plugins), for stored attachments use "id" instead */
+      url: string;
+    };
 
-export interface AttachmentPayload<
-  A extends Attachment | AttachmentForeignKey,
-> {
+export interface AttachmentPayload {
   type: FileType;
-  payload: A;
-}
-
-export interface IncomingAttachmentPayload {
-  type: FileType;
-  payload: {
-    url: string;
-  };
+  payload: AttachmentRef;
 }

api/src/chat/schemas/types/message.ts

@@ -6,16 +6,11 @@
  * 2. All derivative works must include clear attribution to the original creator and software, Hexastack and Hexabot, in a prominent location (e.g., in the software's "About" section, documentation, and README file).
  */
 
-import { Attachment } from '@/attachment/schemas/attachment.schema';
 import { PluginName } from '@/plugins/types';
 
 import { Message } from '../message.schema';
 
-import {
-  AttachmentForeignKey,
-  AttachmentPayload,
-  IncomingAttachmentPayload,
-} from './attachment';
+import { AttachmentPayload } from './attachment';
 import { Button } from './button';
 import { ContentOptions } from './options';
 import { StdQuickReply } from './quick-reply';
@@ -100,11 +95,9 @@ export type StdOutgoingListMessage = {
   };
 };
 
-export type StdOutgoingAttachmentMessage<
-  A extends Attachment | AttachmentForeignKey,
-> = {
+export type StdOutgoingAttachmentMessage = {
   // Stored in DB as `AttachmentPayload`, `Attachment` when populated for channels relaying
-  attachment: AttachmentPayload<A>;
+  attachment: AttachmentPayload;
   quickReplies?: StdQuickReply[];
 };
 
@@ -119,7 +112,7 @@ export type BlockMessage =
   | StdOutgoingQuickRepliesMessage
   | StdOutgoingButtonsMessage
   | StdOutgoingListMessage
-  | StdOutgoingAttachmentMessage<AttachmentForeignKey>
+  | StdOutgoingAttachmentMessage
   | StdPluginMessage;
 
 export type StdOutgoingMessage =
@@ -127,7 +120,7 @@ export type StdOutgoingMessage =
   | StdOutgoingQuickRepliesMessage
   | StdOutgoingButtonsMessage
   | StdOutgoingListMessage
-  | StdOutgoingAttachmentMessage<Attachment>;
+  | StdOutgoingAttachmentMessage;
 
 type StdIncomingTextMessage = { text: string };
 
@@ -146,7 +139,7 @@ export type StdIncomingLocationMessage = {
 export type StdIncomingAttachmentMessage = {
   type: PayloadType.attachments;
   serialized_text: string;
-  attachment: IncomingAttachmentPayload | IncomingAttachmentPayload[];
+  attachment: AttachmentPayload | AttachmentPayload[];
 };
 
 export type StdIncomingMessage =
@@ -191,7 +184,7 @@ export interface StdOutgoingListEnvelope {
 
 export interface StdOutgoingAttachmentEnvelope {
   format: OutgoingMessageFormat.attachment;
-  message: StdOutgoingAttachmentMessage<Attachment>;
+  message: StdOutgoingAttachmentMessage;
 }
 
 export type StdOutgoingEnvelope =

api/src/chat/schemas/types/quick-reply.ts

@@ -1,12 +1,12 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
  * 2. All derivative works must include clear attribution to the original creator and software, Hexastack and Hexabot, in a prominent location (e.g., in the software's "About" section, documentation, and README file).
  */
 
-import { IncomingAttachmentPayload } from './attachment';
+import { AttachmentPayload } from './attachment';
 import { PayloadType } from './message';
 
 export type Payload =
@@ -19,7 +19,7 @@ export type Payload =
     }
   | {
       type: PayloadType.attachments;
-      attachments: IncomingAttachmentPayload;
+      attachments: AttachmentPayload;
     };
 
 export enum QuickReplyType {

api/src/chat/services/block.service.spec.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -390,6 +390,7 @@ describe('BlockService', () => {
           attachments: {
             type: FileType.file,
             payload: {
+              id: '9'.repeat(24),
               url: 'http://link.to/the/file',
             },
           },

api/src/chat/services/block.service.ts

@@ -417,7 +417,7 @@ export class BlockService extends BaseService<
       'url' in block.message.attachment.payload
     ) {
       this.logger.error(
-        'Attachment Model : `url` payload has been deprecated in favor of `attachment_id`',
+        'Attachment Block : `url` payload has been deprecated in favor of `id`',
         block.id,
         block.message,
       );
@@ -527,21 +527,11 @@ export class BlockService extends BaseService<
       }
     } else if (blockMessage && 'attachment' in blockMessage) {
       const attachmentPayload = blockMessage.attachment.payload;
-      if (!attachmentPayload.attachment_id) {
+      if (!('id' in attachmentPayload)) {
         this.checkDeprecatedAttachmentUrl(block);
-        throw new Error('Remote attachments are no longer supported!');
-      }
-
-      const attachment = await this.attachmentService.findOne(
-        attachmentPayload.attachment_id,
-      );
-
-      if (!attachment) {
-        this.logger.debug(
-          'Unable to locate the attachment for the given block',
-          block,
+        throw new Error(
+          'Remote attachments in blocks are no longer supported!',
         );
-        throw new Error('Unable to find attachment.');
       }
 
       const envelope: StdOutgoingEnvelope = {
@@ -549,7 +539,7 @@ export class BlockService extends BaseService<
         message: {
           attachment: {
             type: blockMessage.attachment.type,
-            payload: attachment,
+            payload: blockMessage.attachment.payload,
           },
           quickReplies: blockMessage.quickReplies
             ? [...blockMessage.quickReplies]

api/src/chat/services/chat.service.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -231,7 +231,7 @@ export class ChatService {
    */
   @OnEvent('hook:chatbot:message')
   async handleNewMessage(event: EventWrapper<any, any>) {
-    this.logger.debug('New message received', event);
+    this.logger.debug('New message received', event._adapter.raw);
 
     const foreignId = event.getSenderForeignId();
     const handler = event.getHandler();
@@ -256,6 +256,8 @@ export class ChatService {
 
       event.setSender(subscriber);
 
+      await event.preprocess();
+
       // Trigger message received event
       this.eventEmitter.emit('hook:chatbot:received', event);
 

api/src/chat/validation-rules/is-message.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Hexastack. All rights reserved.
+ * Copyright © 2025 Hexastack. All rights reserved.
  *
  * Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
  * 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
@@ -71,7 +71,7 @@ export function isValidMessage(msg: any) {
             .required(),
           payload: Joi.object().keys({
             url: Joi.string().uri(),
-            attachment_id: Joi.string().allow(null),
+            id: Joi.string().allow(null),
           }),
         }),
         elements: Joi.boolean(),