@hexabot-ai/api 3.0.0-alpha.3 → 3.1.1-alpha.0

package/src/extensions/channels/web/types.ts

@@ -4,6 +4,8 @@
  * Full terms: see LICENSE.md.
  */
 
+import { z } from 'zod';
+
 import { SubscriberFull } from '@/chat/dto/subscriber.dto';
 import { FileType } from '@/chat/types/attachment';
 import { Button, WebUrlButton } from '@/chat/types/button';
@@ -13,9 +15,7 @@ export namespace Web {
   export type RequestSession = {
     web?: {
       profile: SubscriberFull;
-      isSocket: boolean;
-      messageQueue: any[];
-      polling: boolean;
+      threadId?: string;
     };
   };
 
@@ -25,7 +25,7 @@ export namespace Web {
     typing = 'typing',
   }
 
-  export enum IncomingMessageType {
+  export enum InboundMessageType {
     text = 'text',
     quick_reply = 'quick_reply',
     postback = 'postback',
@@ -33,9 +33,9 @@ export namespace Web {
     file = 'file',
   }
 
-  export type EventType = Web.StatusEventType | Web.IncomingMessageType;
+  export type EventType = Web.StatusEventType | Web.InboundMessageType;
 
-  export enum OutgoingMessageType {
+  export enum OutboundMessageType {
     text = 'text',
     buttons = 'buttons',
     quick_replies = 'quick_replies',
@@ -44,102 +44,180 @@ export namespace Web {
     carousel = 'carousel',
   }
 
-  export type IncomingTextMessageData = { text: string };
-
-  export type IncomingPayloadMessageData = IncomingTextMessageData & {
-    payload: string; // Quick reply and button payload are the same
-  };
-
-  export type IncomingLocationMessageData = {
-    coordinates: {
-      lat: number;
-      lng: number;
-    };
-  };
-
-  export type IncomingAttachmentMessageData =
-    // When it's a incoming history message
-    | {
-        type: FileType;
-        url: string; // file download url
-      }
-    // When it's a file upload message
-    | {
-        type: string; // mime type
-        size: number; // file size
-        name: string;
-        file: Buffer;
-      };
-
-  export type IncomingMessageData =
-    | IncomingTextMessageData
-    | IncomingPayloadMessageData
-    | IncomingLocationMessageData
-    | IncomingAttachmentMessageData;
-
-  export type StatusDeliveryEvent = {
-    type: StatusEventType.delivery;
-    mid: string;
-  };
-
-  export type StatusReadEvent = {
-    type: StatusEventType.read;
-    watermark: number;
-  };
-
-  export type StatusTypingEvent = {
-    type: StatusEventType.typing;
-  };
-
-  export type StatusEvent =
-    | StatusDeliveryEvent
-    | StatusReadEvent
-    | StatusTypingEvent;
-
-  export type IncomingTextMessage = {
-    type: IncomingMessageType.text;
-    data: IncomingTextMessageData;
-  };
-
-  export type IncomingPayloadMessage = {
-    type: IncomingMessageType.postback | IncomingMessageType.quick_reply;
-    data: IncomingPayloadMessageData;
-  };
-
-  export type IncomingLocationMessage = {
-    type: IncomingMessageType.location;
-    data: IncomingLocationMessageData;
-  };
-
-  export type IncomingAttachmentMessage = {
-    type: IncomingMessageType.file;
-    data: IncomingAttachmentMessageData;
-  };
-
-  export type IncomingMessageBase =
-    | IncomingTextMessage
-    | IncomingPayloadMessage
-    | IncomingLocationMessage
-    | IncomingAttachmentMessage;
-
-  export type IncomingMessage<
-    T =
-      | IncomingTextMessage
-      | IncomingPayloadMessage
-      | IncomingLocationMessage
-      | IncomingAttachmentMessage,
-  > = T & {
-    mid?: string;
-    author?: string;
-    read?: boolean;
-    delivery?: boolean;
+  export const inboundEventMetadataSchema = z.strictObject({
+    mid: z.string().optional(),
+    author: z.string().optional(),
+    thread_id: z.string().optional(),
+    read: z.boolean().optional(),
+    delivery: z.boolean().optional(),
     // Whether it's a synchronization
     // This is used when message sent by the chatbot from the client side
-    sync?: boolean;
-    createdAt?: Date;
-  };
-
-  export type Event = IncomingMessage | StatusEvent;
+    sync: z.boolean().optional(),
+    createdAt: z.date().optional(),
+  });
+
+  export type InboundEventMetadata = z.infer<typeof inboundEventMetadataSchema>;
+
+  export const inboundTextMessageDataSchema = z.strictObject({
+    text: z.string(),
+  });
+
+  export type InboundTextMessageData = z.infer<
+    typeof inboundTextMessageDataSchema
+  >;
+
+  export const inboundPayloadMessageDataSchema = z.strictObject({
+    text: z.string(),
+    payload: z.string(), // Quick reply and button payload are the same
+  });
+
+  export type InboundPayloadMessageData = z.infer<
+    typeof inboundPayloadMessageDataSchema
+  >;
+
+  export const inboundLocationMessageDataSchema = z.strictObject({
+    coordinates: z.strictObject({
+      lat: z.number(),
+      lng: z.number(),
+    }),
+  });
+
+  export type InboundLocationMessageData = z.infer<
+    typeof inboundLocationMessageDataSchema
+  >;
+
+  export const inboundAttachmentHistoryMessageDataSchema = z.strictObject({
+    type: z.enum(FileType),
+    url: z.string(), // file download url
+  });
+
+  export const inboundAttachmentUploadMessageDataSchema = z.strictObject({
+    type: z.string(), // mime type
+    size: z.number(), // file size
+    name: z.string(),
+    file: z.instanceof(Buffer).optional(),
+  });
+
+  export const inboundAttachmentMessageDataSchema = z.union([
+    inboundAttachmentHistoryMessageDataSchema,
+    inboundAttachmentUploadMessageDataSchema,
+  ]);
+
+  export type InboundAttachmentMessageData = z.infer<
+    typeof inboundAttachmentMessageDataSchema
+  >;
+
+  export const inboundMessageDataSchema = z.union([
+    inboundTextMessageDataSchema,
+    inboundPayloadMessageDataSchema,
+    inboundLocationMessageDataSchema,
+    inboundAttachmentMessageDataSchema,
+  ]);
+
+  export type InboundMessageData = z.infer<typeof inboundMessageDataSchema>;
+
+  export const statusDeliveryEventSchema = z.strictObject({
+    type: z.literal(StatusEventType.delivery),
+    mid: z.string(),
+  });
+
+  export type StatusDeliveryEvent = z.infer<typeof statusDeliveryEventSchema>;
+
+  export const statusReadEventSchema = z.strictObject({
+    type: z.literal(StatusEventType.read),
+    watermark: z.number(),
+  });
+
+  export type StatusReadEvent = z.infer<typeof statusReadEventSchema>;
+
+  export const statusTypingEventSchema = z.strictObject({
+    type: z.literal(StatusEventType.typing),
+  });
+
+  export type StatusTypingEvent = z.infer<typeof statusTypingEventSchema>;
+
+  export const statusEventSchema = z.union([
+    statusDeliveryEventSchema,
+    statusReadEventSchema,
+    statusTypingEventSchema,
+  ]);
+
+  export type StatusEvent = z.infer<typeof statusEventSchema>;
+
+  export const inboundTextMessageSchema = z.strictObject({
+    type: z.literal(InboundMessageType.text),
+    data: inboundTextMessageDataSchema,
+    ...inboundEventMetadataSchema.shape,
+  });
+
+  export type InboundTextMessage = z.infer<typeof inboundTextMessageSchema>;
+
+  export const inboundPostbackMessageSchema = z.strictObject({
+    type: z.literal(InboundMessageType.postback),
+    data: inboundPayloadMessageDataSchema,
+    ...inboundEventMetadataSchema.shape,
+  });
+
+  export const inboundQuickReplyMessageSchema = z.strictObject({
+    type: z.literal(InboundMessageType.quick_reply),
+    data: inboundPayloadMessageDataSchema,
+    ...inboundEventMetadataSchema.shape,
+  });
+
+  export const inboundPayloadMessageSchema = z.union([
+    inboundPostbackMessageSchema,
+    inboundQuickReplyMessageSchema,
+  ]);
+
+  export type IncomingPayloadMessage = z.infer<
+    typeof inboundPayloadMessageSchema
+  >;
+
+  export const inboundLocationMessageSchema = z.strictObject({
+    type: z.literal(InboundMessageType.location),
+    data: inboundLocationMessageDataSchema,
+    ...inboundEventMetadataSchema.shape,
+  });
+
+  export type IncomingLocationMessage = z.infer<
+    typeof inboundLocationMessageSchema
+  >;
+
+  export const inboundAttachmentMessageSchema = z.strictObject({
+    type: z.literal(InboundMessageType.file),
+    data: inboundAttachmentMessageDataSchema,
+    ...inboundEventMetadataSchema.shape,
+  });
+
+  export type InboundAttachmentMessage = z.infer<
+    typeof inboundAttachmentMessageSchema
+  >;
+
+  export const inboundMessageBaseSchema = z.union([
+    inboundTextMessageSchema,
+    inboundPayloadMessageSchema,
+    inboundLocationMessageSchema,
+    inboundAttachmentMessageSchema,
+  ]);
+
+  export type InboundMessageBase = z.infer<typeof inboundMessageBaseSchema>;
+
+  export type InboundMessage<
+    T extends InboundMessageBase = InboundMessageBase,
+  > = T;
+
+  export const eventSchema = z.discriminatedUnion('type', [
+    statusDeliveryEventSchema,
+    statusReadEventSchema,
+    statusTypingEventSchema,
+    inboundTextMessageSchema,
+    inboundPostbackMessageSchema,
+    inboundQuickReplyMessageSchema,
+    inboundLocationMessageSchema,
+    inboundAttachmentMessageSchema,
+  ]);
+
+  export type Event = z.infer<typeof eventSchema>;
 
   export interface MessageElement {
     title: string;
@@ -149,72 +227,73 @@ export namespace Web {
     buttons?: Button[];
   }
 
-  export type OutgoingTextMessageData = { text: string };
+  export type OutboundTextMessageData = { text: string };
 
-  export type OutgoingQuickRepliesMessageData = OutgoingTextMessageData & {
+  export type OutboundQuickRepliesMessageData = OutboundTextMessageData & {
     quick_replies: StdQuickReply[];
   };
 
-  export type OutgoingButtonsMessageData = OutgoingTextMessageData & {
+  export type OutboundButtonsMessageData = OutboundTextMessageData & {
     buttons: Button[];
   };
 
-  export type OutgoingFileMessageData = {
+  export type OutboundFileMessageData = {
     quick_replies?: StdQuickReply[];
     type: FileType;
     url: string;
   };
 
-  export type OutgoingCarouselMessageData = {
+  export type OutboundCarouselMessageData = {
     elements: MessageElement[];
   };
 
-  export type OutgoingListMessageData = OutgoingCarouselMessageData & {
+  export type OutboundListMessageData = OutboundCarouselMessageData & {
     top_element_style?: 'large' | 'compact';
     buttons: Button[];
   };
 
-  export type OutgoingMessageData =
-    | OutgoingTextMessageData
-    | OutgoingQuickRepliesMessageData
-    | OutgoingButtonsMessageData
-    | OutgoingFileMessageData
-    | OutgoingCarouselMessageData
-    | OutgoingListMessageData;
+  export type OutboundMessageData =
+    | OutboundTextMessageData
+    | OutboundQuickRepliesMessageData
+    | OutboundButtonsMessageData
+    | OutboundFileMessageData
+    | OutboundCarouselMessageData
+    | OutboundListMessageData;
 
-  export type OutgoingMessageBase =
+  export type OutboundMessageBase =
     | {
-        type: OutgoingMessageType.text;
-        data: OutgoingTextMessageData;
+        type: OutboundMessageType.text;
+        data: OutboundTextMessageData;
       }
     | {
-        type: OutgoingMessageType.quick_replies;
-        data: OutgoingQuickRepliesMessageData;
+        type: OutboundMessageType.quick_replies;
+        data: OutboundQuickRepliesMessageData;
       }
     | {
-        type: OutgoingMessageType.buttons;
-        data: OutgoingButtonsMessageData;
+        type: OutboundMessageType.buttons;
+        data: OutboundButtonsMessageData;
       }
     | {
-        type: OutgoingMessageType.file;
-        data: OutgoingFileMessageData;
+        type: OutboundMessageType.file;
+        data: OutboundFileMessageData;
       }
     | {
-        type: OutgoingMessageType.carousel;
-        data: OutgoingCarouselMessageData;
+        type: OutboundMessageType.carousel;
+        data: OutboundCarouselMessageData;
       }
     | {
-        type: OutgoingMessageType.list;
-        data: OutgoingListMessageData;
+        type: OutboundMessageType.list;
+        data: OutboundListMessageData;
       };
 
-  export type OutgoingMessage = OutgoingMessageBase & {
+  export type OutboundMessage = OutboundMessageBase & {
     mid: string;
     author: string;
+    thread_id?: string;
     read?: boolean;
     createdAt: Date;
     handover: boolean;
   };
 
-  export type Message = OutgoingMessage | IncomingMessage;
+  export type Message = OutboundMessage | InboundMessage;
 }

package/src/extensions/channels/web/web-channel.settings.ts

@@ -0,0 +1,105 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import z from 'zod';
+
+import { ChannelSetting } from '@/channel/types';
+import { config } from '@/config';
+import { createSettingGroup } from '@/setting/create-setting-group';
+import { buildSettingSeedsFromSchema } from '@/setting/runtime-settings.seed';
+
+export const WEB_CHANNEL_NAME = 'web' as const;
+
+const WEB_ALLOWED_UPLOAD_TYPES =
+  'audio/mpeg,audio/x-ms-wma,audio/vnd.rn-realaudio,audio/x-wav,image/gif,image/jpeg,image/png,image/tiff,image/vnd.microsoft.icon,image/vnd.djvu,image/svg+xml,text/css,text/csv,text/html,text/plain,text/xml,video/mpeg,video/mp4,video/quicktime,video/x-ms-wmv,video/x-msvideo,video/x-flv,video/web,application/msword,application/vnd.ms-powerpoint,application/pdf,application/vnd.ms-excel,application/vnd.oasis.opendocument.presentation,application/vnd.oasis.opendocument.tex,application/vnd.oasis.opendocument.spreadsheet,application/vnd.oasis.opendocument.graphics,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,application/vnd.openxmlformats-officedocument.presentationml.presentation,application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+
+export const WEB_CHANNEL_SETTINGS_SCHEMA = z
+  .strictObject({
+    allowed_domains: z
+      .string()
+      .default(config.security.cors.allowOrigins.join(','))
+      .meta({
+        title: 'Allowed domains',
+        description: 'Comma-separated list of allowed CORS origins.',
+      }),
+    start_button: z.boolean().default(true).meta({
+      title: 'Show start button',
+      description: 'Display the start button before chat begins.',
+    }),
+    input_disabled: z.boolean().default(false).meta({
+      title: 'Disable input',
+      description: 'Disable the user input field in the chat widget.',
+    }),
+    persistent_menu: z.boolean().default(true).meta({
+      title: 'Persistent menu',
+      description: 'Keep the menu visible in the chat interface.',
+    }),
+    greeting_message: z
+      .string()
+      .default('Welcome! Ready to start chatting with our chatbot?')
+      .meta({
+        title: 'Greeting message',
+        description: 'Greeting shown to users when the conversation starts.',
+        'ui:widget': 'textarea',
+      }),
+    window_title: z.string().default('Widget Title').meta({
+      title: 'Window title',
+      description: 'Title displayed in the web widget header.',
+    }),
+    avatar_url: z.url().default('').optional().meta({
+      title: 'Avatar URL',
+      description: 'URL of the chatbot avatar image.',
+    }),
+    show_emoji: z.boolean().default(true).meta({
+      title: 'Show emoji',
+      description: 'Enable emoji picker in the chat interface.',
+    }),
+    show_file: z.boolean().default(true).meta({
+      title: 'Show file upload',
+      description: 'Enable file upload action in the chat interface.',
+    }),
+    show_location: z.boolean().default(true).meta({
+      title: 'Show location',
+      description: 'Enable location sharing action in the chat interface.',
+    }),
+    allowed_upload_types: z.string().default(WEB_ALLOWED_UPLOAD_TYPES).meta({
+      title: 'Allowed upload types',
+      description: 'Comma-separated MIME types accepted by the upload input.',
+      'ui:widget': 'textarea',
+    }),
+    thread_inactivity_hours: z.int().nonnegative().default(24).meta({
+      title: 'Thread inactivity (hours)',
+      description:
+        'Automatically start a new thread when the last message is older than this threshold.',
+    }),
+  })
+  .meta({
+    title: 'Web Channel',
+  });
+
+declare global {
+  interface RuntimeSettingRegistry {
+    [WEB_CHANNEL_NAME]: typeof WEB_CHANNEL_SETTINGS_SCHEMA;
+  }
+}
+
+export const WebChannelSettingsGroup = createSettingGroup({
+  group: WEB_CHANNEL_NAME,
+  schema: WEB_CHANNEL_SETTINGS_SCHEMA,
+  scope: 'extension',
+  extensionType: 'channel',
+  extensionName: WEB_CHANNEL_NAME,
+});
+
+export const WEB_CHANNEL_SETTINGS = buildSettingSeedsFromSchema(
+  WEB_CHANNEL_NAME,
+  WEB_CHANNEL_SETTINGS_SCHEMA,
+  {
+    subgroup: 'channel',
+  },
+) as ChannelSetting<typeof WEB_CHANNEL_NAME>[];
+
+export default WebChannelSettingsGroup;

package/src/extensions/helpers/local-storage/i18n/en.translations.json

@@ -0,0 +1,6 @@
+{
+  "local-storage": {
+    "Local Storage": "Local Storage",
+    "Local storage helper": "Local storage helper"
+  }
+}

package/src/extensions/helpers/local-storage/i18n/fr.translations.json

@@ -0,0 +1,6 @@
+{
+  "local-storage": {
+    "Local Storage": "Stockage local",
+    "Local storage helper": "Helper de stockage local"
+  }
+}

package/src/extensions/helpers/local-storage/index.helper.ts

@@ -6,7 +6,7 @@
 
 import fs from 'fs';
 import os from 'os';
-import { join, normalize, resolve } from 'path';
+import { isAbsolute, join, relative, resolve } from 'path';
 import { Readable, Stream } from 'stream';
 
 import {
@@ -18,10 +18,10 @@ import {
 import sanitizeFilename from 'sanitize-filename';
 
 import {
+  Attachment,
   AttachmentCreateDto,
   AttachmentMetadataDto,
 } from '@/attachment/dto/attachment.dto';
-import { AttachmentOrmEntity } from '@/attachment/entities/attachment.entity';
 import { AttachmentResourceRef } from '@/attachment/types';
 import {
   fileExists,
@@ -29,28 +29,17 @@ import {
   getStreamableFile,
 } from '@/attachment/utilities';
 import { config } from '@/config';
-import { HelperService } from '@/helper/helper.service';
 import { BaseStorageHelper } from '@/helper/lib/base-storage-helper';
-import { LoggerService } from '@/logger/logger.service';
-import { SettingService } from '@/setting/services/setting.service';
 
-import { LOCAL_STORAGE_HELPER_NAME } from './settings';
+export const LOCAL_STORAGE_HELPER_NAME = 'local-storage' as const;
 
 @Injectable()
 export default class LocalStorageHelper
   extends BaseStorageHelper<typeof LOCAL_STORAGE_HELPER_NAME>
   implements OnModuleInit
 {
-  constructor(
-    settingService: SettingService,
-    helperService: HelperService,
-    logger: LoggerService,
-  ) {
-    super(LOCAL_STORAGE_HELPER_NAME, settingService, helperService, logger);
-  }
-
-  getPath() {
-    return __dirname;
+  constructor() {
+    super(LOCAL_STORAGE_HELPER_NAME);
   }
 
   /**
@@ -98,11 +87,11 @@ export default class LocalStorageHelper
       if (file.path) {
         // For example, if the file is an instance of `Express.Multer.File` (diskStorage case)
         const srcFilePath = fs.realpathSync(resolve(file.path));
-        // Get the system's temporary directory in a cross-platform way
-        const tempDir = os.tmpdir();
-        const normalizedTempDir = normalize(tempDir);
+        // Resolve symlinks (e.g. /tmp -> /private/tmp on macOS) before validating boundaries.
+        const canonicalTempDir = fs.realpathSync(resolve(os.tmpdir()));
+        const relativePath = relative(canonicalTempDir, srcFilePath);
 
-        if (!srcFilePath.startsWith(normalizedTempDir)) {
+        if (relativePath.startsWith('..') || isAbsolute(relativePath)) {
           throw new Error('Invalid file path');
         }
 
@@ -130,7 +119,7 @@ export default class LocalStorageHelper
    * @param attachment - The attachment to download.
    * @returns A promise that resolves to a StreamableFile representing the downloaded attachment.
    */
-  async download(attachment: AttachmentOrmEntity): Promise<StreamableFile> {
+  async download(attachment: Attachment): Promise<StreamableFile> {
     const rootDir = this.getRootDirByResourceRef(attachment.resourceRef);
     const path = resolve(join(rootDir, attachment.location));
 
@@ -157,9 +146,7 @@ export default class LocalStorageHelper
    * @param attachment - The attachment to download.
    * @returns A promise that resolves to a Buffer representing the attachment file.
    */
-  async readAsBuffer(
-    attachment: AttachmentOrmEntity,
-  ): Promise<Buffer | undefined> {
+  async readAsBuffer(attachment: Attachment): Promise<Buffer | undefined> {
     const path = resolve(
       join(
         this.getRootDirByResourceRef(attachment.resourceRef),
@@ -180,9 +167,7 @@ export default class LocalStorageHelper
    * @param attachment - The attachment to download.
    * @returns A promise that resolves to a Stream representing the attachment file.
    */
-  async readAsStream(
-    attachment: AttachmentOrmEntity,
-  ): Promise<Stream | undefined> {
+  async readAsStream(attachment: Attachment): Promise<Stream | undefined> {
     const path = resolve(
       join(
         this.getRootDirByResourceRef(attachment.resourceRef),

package/src/extensions/index.ts

@@ -6,22 +6,38 @@
 
 export * from './channels/console/index.channel';
 
-export * from './channels/console/settings';
+export * from './channels/console/console-channel.settings';
 
 export * from './channels/web/base-web-channel';
 
 export * from './channels/web/index.channel';
 
-export * from './channels/web/settings';
+export * from './channels/web/web-channel.settings';
 
 export * from './channels/web/types';
 
-export * from './channels/web/wrapper';
+export * from './channels/web/inbound';
 
-export * from './helpers/llm-nlu/index.helper';
+export * from './helpers/local-storage/index.helper';
 
-export * from './helpers/llm-nlu/settings';
+export * from './actions/ai/model.binding';
 
-export * from './helpers/local-storage/index.helper';
+export * from './actions/ai/tools.binding';
+
+export * from './actions/ai/generate-text.action';
+
+export * from './actions/ai/generate-reply.action';
+
+export * from './actions/ai/generate-object.action';
+
+export * from './actions/ai/infer-object.action';
+
+export * from './actions/messaging/text-message.action';
+
+export * from './actions/messaging/quick-replies.action';
+
+export * from './actions/messaging/buttons.action';
+
+export * from './actions/messaging/attachment.action';
 
-export * from './helpers/local-storage/settings';
+export * from './actions/messaging/list.action';

package/src/global.d.ts

@@ -6,6 +6,7 @@
 
 import '../types/event-emitter';
 import '../types/express-session';
+import './types/ai-sdk-mcp-stdio';
 
 declare global {
   type HyphenToUnderscore<S extends string> = S extends `${infer P}-${infer Q}`