Feat: refactor stdout envelopes

api/src/app.module.ts

@@ -45,6 +45,7 @@ import { PluginsModule } from './plugins/plugins.module';
 import { SettingModule } from './setting/setting.module';
 import { Ability } from './user/guards/ability.guard';
 import { UserModule } from './user/user.module';
+import { StdOutgoingEnvelopeModule } from './utils/envelopes/StdOutgoingEnvelope.module';
 import idPlugin from './utils/schema-plugin/id.plugin';
 import { WebsocketModule } from './websocket/websocket.module';
 
@@ -144,6 +145,7 @@ const i18nOptions: I18nOptions = {
           max: config.cache.max,
         }),
     MigrationModule,
+    StdOutgoingEnvelopeModule,
     ...extraModules,
   ],
   controllers: [AppController],

api/src/utils/envelopes/StdOutgoingEnvelope.module.ts

@@ -0,0 +1,18 @@
+/*
+ * 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 { Global, Module } from '@nestjs/common';
+
+import { StdOutgoingEnvelopeFactory } from './envelopeFactory';
+
+@Global()
+@Module({
+  providers: [StdOutgoingEnvelopeFactory],
+  exports: [StdOutgoingEnvelopeFactory],
+})
+export class StdOutgoingEnvelopeModule {}

api/src/utils/envelopes/envelope-builders/StdOutgoingAttachmentEnvelopeBuilder.ts

@@ -0,0 +1,102 @@
+/*
+ * 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 { FileType } from '@/chat/schemas/types/attachment';
+import {
+  OutgoingMessageFormat,
+  stdOutgoingAttachmentEnvelopeSchema,
+} from '@/chat/schemas/types/message';
+import { StdQuickReply } from '@/chat/schemas/types/quick-reply';
+
+export class StdOutgoingAttachmentEnvelopeBuilder {
+  private fileType: FileType;
+
+  private attachmentId: string;
+
+  private attachmentUrl: string;
+
+  private quickReplies: StdQuickReply[] = [];
+
+  constructor() {}
+
+  setFileType(fileType: FileType) {
+    this.fileType = fileType;
+    return this;
+  }
+
+  setAttachmentId(id: string) {
+    this.attachmentId = id;
+    return this;
+  }
+
+  setAttachmentUrl(url: string) {
+    this.attachmentUrl = url;
+    return this;
+  }
+
+  buildAndAppendQuickReply(quickReply: StdQuickReply) {
+    this.quickReplies.push(quickReply);
+    return this;
+  }
+
+  build() {
+    //todo: verify why id can be null
+    let payload: { id: string } | { url: string };
+    if (this.attachmentUrl) {
+      payload = { url: this.attachmentUrl };
+    } else {
+      payload = { id: this.attachmentId };
+    }
+    const stdOutgoingAttachmentEnvelope = new StdOutgoingAttachmentEnvelope(
+      this.fileType,
+      payload,
+      this.quickReplies,
+    );
+    if (this.isValid(stdOutgoingAttachmentEnvelope)) {
+      return stdOutgoingAttachmentEnvelope;
+    }
+
+    throw new Error('Invalid stdOutgoingAttachmentEnvelope shape');
+  }
+
+  private isValid(data: unknown) {
+    return stdOutgoingAttachmentEnvelopeSchema.safeParse(data).success;
+  }
+}
+
+export class StdOutgoingAttachmentEnvelope {
+  format: OutgoingMessageFormat.attachment;
+
+  message: {
+    attachment: {
+      //todo: verify why id can be null
+      payload: { id: string } | { url: string };
+      type: FileType;
+    };
+    quickReplies?: StdQuickReply[];
+  };
+
+  constructor(
+    fileType: FileType,
+    //todo: verify why id can be null
+    payload: { id: string } | { url: string },
+    quickReplies?: StdQuickReply[],
+  ) {
+    this.format = OutgoingMessageFormat.attachment;
+    this.message = {
+      attachment: {
+        payload,
+        type: fileType,
+      },
+    };
+
+    if (quickReplies?.length) {
+      this.message.quickReplies = quickReplies;
+    }
+  }
+}

api/src/utils/envelopes/envelope-builders/StdOutgoingButtonsEnvelopeBuilder.ts

@@ -0,0 +1,64 @@
+/*
+ * 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 { Button } from '@/chat/schemas/types/button';
+import { OutgoingMessageFormat } from '@/chat/schemas/types/message';
+
+import { stdOutgoingButtonsEnvelopeSchema } from './../../../chat/schemas/types/message';
+
+export class StdOutgoingButtonsEnvelopeBuilder {
+  private text: string;
+
+  private buttons: Button[] = [];
+
+  constructor() {}
+
+  setText(text: string) {
+    this.text = text;
+    return this;
+  }
+
+  addButton(button: Button) {
+    this.buttons.push(button);
+    return this;
+  }
+
+  setButtons(buttons: Button[]) {
+    this.buttons = buttons;
+    return this;
+  }
+
+  build() {
+    const stdOutgoingButton = new StdOutgoingButton(this.text, this.buttons);
+    if (this.isValid(stdOutgoingButton)) {
+      return stdOutgoingButton;
+    }
+    throw new Error('Invalid StdOutgoingButton shape');
+  }
+
+  private isValid(data: unknown) {
+    return stdOutgoingButtonsEnvelopeSchema.safeParse(data).success;
+  }
+}
+
+export class StdOutgoingButton {
+  format: OutgoingMessageFormat.buttons;
+
+  message: {
+    text: string;
+    buttons: Button[];
+  };
+
+  constructor(text: string, buttons: Button[]) {
+    this.format = OutgoingMessageFormat.buttons;
+    this.message = {
+      text,
+      buttons,
+    };
+  }
+}

api/src/utils/envelopes/envelope-builders/StdOutgoingListEnvelope.ts

@@ -0,0 +1,107 @@
+/*
+ * 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 {
+  ContentElement,
+  OutgoingMessageFormat,
+  stdOutgoingListEnvelopeSchema,
+} from '@/chat/schemas/types/message';
+import { ContentOptions } from '@/chat/schemas/types/options';
+
+export class StdOutgoingListEnvelopeBuilder {
+  private format: OutgoingMessageFormat.list | OutgoingMessageFormat.carousel;
+
+  private options: ContentOptions;
+
+  private elements: ContentElement[] = [];
+
+  private pagination: { total: number; skip: number; limit: number } = {
+    total: 0,
+    skip: 0,
+    limit: 10,
+  };
+
+  constructor() {}
+
+  setOptions(options: ContentOptions) {
+    this.options = options;
+    return this;
+  }
+
+  addElement(element: ContentElement) {
+    this.elements.push(element);
+    return this;
+  }
+
+  setElements(elements: ContentElement[]) {
+    this.elements = elements;
+    return this;
+  }
+
+  setFormat(
+    format: OutgoingMessageFormat.list | OutgoingMessageFormat.carousel,
+  ) {
+    this.format = format;
+    return this;
+  }
+
+  setPagination({
+    total,
+    skip,
+    limit,
+  }: {
+    total: number;
+    skip: number;
+    limit: number;
+  }) {
+    this.pagination = { total, skip, limit };
+    return this;
+  }
+
+  build() {
+    const stdOutgoingList = new StdOutgoingList(
+      this.format,
+      this.options,
+      this.elements,
+      this.pagination,
+    );
+    if (this.isValid(stdOutgoingList)) {
+      return stdOutgoingList;
+    }
+
+    throw new Error('Invalid stdOutgoingList shape');
+  }
+
+  private isValid(data: unknown) {
+    return stdOutgoingListEnvelopeSchema.safeParse(data).success;
+  }
+}
+
+export class StdOutgoingList {
+  format: OutgoingMessageFormat.list | OutgoingMessageFormat.carousel;
+
+  message: {
+    options: ContentOptions;
+    elements: ContentElement[];
+    pagination: { total: number; skip: number; limit: number };
+  };
+
+  constructor(
+    format: OutgoingMessageFormat.list | OutgoingMessageFormat.carousel,
+    options: ContentOptions,
+    elements: ContentElement[],
+    pagination: { total: number; skip: number; limit: number },
+  ) {
+    this.format = format;
+    this.message = {
+      options,
+      elements,
+      pagination,
+    };
+  }
+}

api/src/utils/envelopes/envelope-builders/StdOutgoingQuickRepliesEnvelope.ts

@@ -0,0 +1,67 @@
+/*
+ * 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 { OutgoingMessageFormat } from '@/chat/schemas/types/message';
+import { StdQuickReply } from '@/chat/schemas/types/quick-reply';
+
+import { stdOutgoingQuickRepliesEnvelopeSchema } from './../../../chat/schemas/types/message';
+
+export class StdOutgoingQuickReplyEnvelopeBuilder {
+  private quickReplies: StdQuickReply[] = [];
+
+  private text: string;
+
+  constructor() {}
+
+  setText(text: string) {
+    this.text = text;
+    return this;
+  }
+
+  buildAndAppendQuickReply(stdQuickReply: StdQuickReply) {
+    this.quickReplies.push(stdQuickReply);
+    return this;
+  }
+
+  setQuickReplies(stdQuickReplies: StdQuickReply[]) {
+    this.quickReplies = stdQuickReplies;
+  }
+
+  build() {
+    const stdOutgoingQuickReply = new StdOutgoingQuickReply(
+      this.text,
+      this.quickReplies,
+    );
+    if (this.isValid(stdOutgoingQuickReply)) {
+      return stdOutgoingQuickReply;
+    }
+
+    throw new Error('stdOutgoingQuickReply invalid shape');
+  }
+
+  private isValid(data: unknown) {
+    return stdOutgoingQuickRepliesEnvelopeSchema.safeParse(data).success;
+  }
+}
+
+export class StdOutgoingQuickReply {
+  format: OutgoingMessageFormat.quickReplies;
+
+  message: {
+    text: string;
+    quickReplies: StdQuickReply[];
+  };
+
+  constructor(text: string, quickReplies: StdQuickReply[]) {
+    this.format = OutgoingMessageFormat.quickReplies;
+    this.message = {
+      text,
+      quickReplies,
+    };
+  }
+}