@hexabot-ai/api 3.0.0-alpha.3

package/src/chat/types/message.ts

@@ -0,0 +1,393 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { PluginName } from '@/plugins/types';
+
+import { Message } from '../dto/message.dto';
+
+import { attachmentPayloadSchema, FileType } from './attachment';
+import { buttonSchema, PayloadType } from './button';
+import { contentOptionsSchema } from './options';
+import { QuickReplyType, stdQuickReplySchema } from './quick-reply';
+
+/**
+ * StdEventType enum is declared, and currently not used
+ **/
+
+export enum StdEventType {
+  message = 'message',
+  delivery = 'delivery',
+  read = 'read',
+  typing = 'typing',
+  follow = 'follow',
+  echo = 'echo',
+  error = 'error',
+  unknown = '',
+}
+
+/**
+ * IncomingMessageType enum is declared, and currently not used
+ **/
+export enum IncomingMessageType {
+  message = 'message',
+  postback = 'postback',
+  quick_reply = 'quick_reply',
+  location = 'location',
+  attachments = 'attachments',
+  unknown = '',
+}
+
+export const incomingMessageType = z.nativeEnum(IncomingMessageType);
+
+export type IncomingMessageTypeLiteral = z.infer<typeof incomingMessageType>;
+
+export enum OutgoingMessageFormat {
+  text = 'text',
+  quickReplies = 'quickReplies',
+  buttons = 'buttons',
+  attachment = 'attachment',
+  list = 'list',
+  carousel = 'carousel',
+  system = 'system',
+}
+
+export const outgoingMessageFormatSchema = z.nativeEnum(OutgoingMessageFormat);
+
+export type OutgoingMessageFormatLiteral = z.infer<
+  typeof outgoingMessageFormatSchema
+>;
+
+export const payloadTypeSchema = z.nativeEnum(PayloadType);
+
+export type PayloadTypeLiteral = z.infer<typeof payloadTypeSchema>;
+
+export const stdOutgoingTextMessageSchema = z.object({
+  text: z.string(),
+});
+
+export type StdOutgoingTextMessage = z.infer<
+  typeof stdOutgoingTextMessageSchema
+>;
+
+export const stdOutgoingQuickRepliesMessageSchema = z.object({
+  text: z.string(),
+  quickReplies: z.array(stdQuickReplySchema),
+});
+
+export type StdOutgoingQuickRepliesMessage = z.infer<
+  typeof stdOutgoingQuickRepliesMessageSchema
+>;
+
+export const stdOutgoingButtonsMessageSchema = z.object({
+  text: z.string(),
+  buttons: z.array(buttonSchema),
+});
+
+export type StdOutgoingButtonsMessage = z.infer<
+  typeof stdOutgoingButtonsMessageSchema
+>;
+
+export const contentElementSchema = z
+  .object({
+    id: z.string(),
+    title: z.string(),
+  })
+  .catchall(z.any());
+
+export type ContentElement = z.infer<typeof contentElementSchema>;
+
+export const contentPaginationSchema = z.object({
+  total: z.number(),
+  skip: z.number(),
+  limit: z.number(),
+});
+
+export type ContentPagination = z.infer<typeof contentPaginationSchema>;
+
+export const stdOutgoingListMessageSchema = z.object({
+  options: contentOptionsSchema,
+  elements: z.array(contentElementSchema),
+  pagination: contentPaginationSchema,
+});
+
+export type StdOutgoingListMessage = z.infer<
+  typeof stdOutgoingListMessageSchema
+>;
+
+export const stdOutgoingAttachmentMessageSchema = z.object({
+  attachment: attachmentPayloadSchema,
+  quickReplies: z.array(stdQuickReplySchema).optional(),
+});
+
+export type StdOutgoingAttachmentMessage = z.infer<
+  typeof stdOutgoingAttachmentMessageSchema
+>;
+
+export const stdOutgoingSystemMessageSchema = z.object({
+  outcome: z.string().optional(), // "any" or any other string (in snake case)
+  data: z.any().optional(),
+});
+
+export type StdOutgoingSystemMessage = z.infer<
+  typeof stdOutgoingSystemMessageSchema
+>;
+
+export const pluginNameSchema = z
+  .string()
+  .regex(/-plugin$/) as z.ZodType<PluginName>;
+
+export const stdPluginMessageSchema = z.object({
+  plugin: pluginNameSchema,
+  args: z.record(z.any()),
+});
+
+export type StdPluginMessage = z.infer<typeof stdPluginMessageSchema>;
+
+export const blockMessageSchema = z.union([
+  z.array(z.string()),
+  stdOutgoingTextMessageSchema,
+  stdOutgoingQuickRepliesMessageSchema,
+  stdOutgoingButtonsMessageSchema,
+  stdOutgoingListMessageSchema,
+  stdOutgoingAttachmentMessageSchema,
+  stdPluginMessageSchema,
+]);
+
+export type BlockMessage = z.infer<typeof blockMessageSchema>;
+
+export const StdOutgoingMessageSchema = z.union([
+  stdOutgoingTextMessageSchema,
+  stdOutgoingQuickRepliesMessageSchema,
+  stdOutgoingButtonsMessageSchema,
+  stdOutgoingListMessageSchema,
+  stdOutgoingAttachmentMessageSchema,
+]);
+
+export type StdOutgoingMessage = z.infer<typeof StdOutgoingMessageSchema>;
+
+export const stdIncomingTextMessageSchema = z.object({
+  text: z.string(),
+});
+
+export type StdIncomingTextMessage = z.infer<
+  typeof stdIncomingTextMessageSchema
+>;
+
+export const stdIncomingPostBackMessageSchema =
+  stdIncomingTextMessageSchema.extend({
+    postback: z.string(),
+  });
+
+export type StdIncomingPostBackMessage = z.infer<
+  typeof stdIncomingPostBackMessageSchema
+>;
+
+export const stdIncomingLocationMessageSchema = z.object({
+  type: z.literal(PayloadType.location),
+  coordinates: z.object({
+    lat: z.number(),
+    lon: z.number(),
+  }),
+});
+
+export type StdIncomingLocationMessage = z.infer<
+  typeof stdIncomingLocationMessageSchema
+>;
+
+export const stdIncomingAttachmentMessageSchema = z.object({
+  type: z.literal(PayloadType.attachments),
+  serialized_text: z.string(),
+  attachment: z.union([
+    attachmentPayloadSchema,
+    z.array(attachmentPayloadSchema),
+  ]),
+});
+
+export type StdIncomingAttachmentMessage = z.infer<
+  typeof stdIncomingAttachmentMessageSchema
+>;
+
+export const stdIncomingMessageSchema = z.union([
+  stdIncomingTextMessageSchema,
+  stdIncomingPostBackMessageSchema,
+  stdIncomingLocationMessageSchema,
+  stdIncomingAttachmentMessageSchema,
+]);
+
+export type StdIncomingMessage = z.infer<typeof stdIncomingMessageSchema>;
+
+export interface IncomingMessage extends Omit<Message, 'recipient' | 'sentBy'> {
+  message: StdIncomingMessage;
+  sender: string;
+}
+
+export interface OutgoingMessage extends Omit<Message, 'sender'> {
+  message: StdOutgoingMessage;
+  recipient: string;
+  sentBy?: string;
+  handover: boolean;
+}
+
+export type AnyMessage = IncomingMessage | OutgoingMessage;
+
+export const stdOutgoingTextEnvelopeSchema = z.object({
+  format: z.literal(OutgoingMessageFormat.text),
+  message: stdOutgoingTextMessageSchema,
+});
+
+export type StdOutgoingTextEnvelope = z.infer<
+  typeof stdOutgoingTextEnvelopeSchema
+>;
+
+export const stdOutgoingQuickRepliesEnvelopeSchema = z.object({
+  format: z.literal(OutgoingMessageFormat.quickReplies),
+  message: stdOutgoingQuickRepliesMessageSchema,
+});
+
+export type StdOutgoingQuickRepliesEnvelope = z.infer<
+  typeof stdOutgoingQuickRepliesEnvelopeSchema
+>;
+
+export const stdOutgoingButtonsEnvelopeSchema = z.object({
+  format: z.literal(OutgoingMessageFormat.buttons),
+  message: stdOutgoingButtonsMessageSchema,
+});
+
+export type StdOutgoingButtonsEnvelope = z.infer<
+  typeof stdOutgoingButtonsEnvelopeSchema
+>;
+
+export const stdOutgoingListEnvelopeSchema = z.object({
+  format: z.enum(['list', 'carousel']),
+  message: stdOutgoingListMessageSchema,
+});
+
+export type StdOutgoingListEnvelope = z.infer<
+  typeof stdOutgoingListEnvelopeSchema
+>;
+
+export const stdOutgoingAttachmentEnvelopeSchema = z.object({
+  format: z.literal(OutgoingMessageFormat.attachment),
+  message: stdOutgoingAttachmentMessageSchema,
+});
+
+export type StdOutgoingAttachmentEnvelope = z.infer<
+  typeof stdOutgoingAttachmentEnvelopeSchema
+>;
+
+export const stdOutgoingSystemEnvelopeSchema = z.object({
+  format: z.literal(OutgoingMessageFormat.system),
+  message: stdOutgoingSystemMessageSchema,
+});
+
+export type StdOutgoingSystemEnvelope = z.infer<
+  typeof stdOutgoingSystemEnvelopeSchema
+>;
+
+export const stdOutgoingMessageEnvelopeSchema = z.union([
+  stdOutgoingTextEnvelopeSchema,
+  stdOutgoingQuickRepliesEnvelopeSchema,
+  stdOutgoingButtonsEnvelopeSchema,
+  stdOutgoingListEnvelopeSchema,
+  stdOutgoingAttachmentEnvelopeSchema,
+]);
+
+export type StdOutgoingMessageEnvelope = z.infer<
+  typeof stdOutgoingMessageEnvelopeSchema
+>;
+
+export const stdOutgoingEnvelopeSchema = z.union([
+  stdOutgoingMessageEnvelopeSchema,
+  stdOutgoingSystemEnvelopeSchema,
+]);
+
+export type StdOutgoingEnvelope = z.infer<typeof stdOutgoingEnvelopeSchema>;
+
+// is-valid-message-text validation
+export const validMessageTextSchema = z.object({
+  text: z.string(),
+});
+
+export const textSchema = z.array(z.string().max(1000));
+
+const quickReplySchema = z
+  .object({
+    content_type: z.nativeEnum(QuickReplyType),
+    title: z.string().max(20).optional(),
+    payload: z.string().max(1000).optional(),
+  })
+  .superRefine((data, ctx) => {
+    // When content_type is 'text', title and payload are required.
+    if (data.content_type === QuickReplyType.text) {
+      if (data.title == null) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Title is required when content_type is 'text'",
+          path: ['title'],
+        });
+      }
+      if (data.payload == null) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "Payload is required when content_type is 'text'",
+          path: ['payload'],
+        });
+      }
+    }
+  });
+
+// pluginBlockMessageSchema in case of Plugin Block
+export const pluginBlockMessageSchema = z
+  .record(z.any())
+  .superRefine((data, ctx) => {
+    if (!('plugin' in data)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "The object must contain the 'plugin' attribute",
+        path: ['plugin'],
+      });
+    }
+  });
+
+// textBlockMessageSchema in case of Text Block
+const textBlockMessageSchema = z.string().max(1000);
+const buttonMessageSchema = z.object({
+  text: z.string(),
+  buttons: z.array(buttonSchema).max(3),
+});
+// quickReplyMessageSchema in case of QuickReply Block
+const quickReplyMessageSchema = z.object({
+  text: z.string(),
+  quickReplies: z.array(quickReplySchema).max(11).optional(),
+});
+// listBlockMessageSchema in case of List Block
+const listBlockMessageSchema = z.object({
+  elements: z.boolean(),
+});
+// attachmentBlockMessageSchema in case of Attachment Block
+const attachmentBlockMessageSchema = z.object({
+  text: z.string().max(1000).optional(),
+  attachment: z.object({
+    type: z.nativeEnum(FileType),
+    payload: z.union([
+      z.object({ url: z.string().url() }),
+      z.object({ id: z.string().nullable() }),
+    ]),
+  }),
+});
+
+// BlockMessage Schema
+export const blockMessageObjectSchema = z.union([
+  textSchema,
+  textBlockMessageSchema,
+  buttonMessageSchema,
+  quickReplyMessageSchema,
+  listBlockMessageSchema,
+  attachmentBlockMessageSchema,
+  pluginBlockMessageSchema,
+]);

package/src/chat/types/options.ts

@@ -0,0 +1,46 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { buttonSchema } from './button';
+
+export const contentOptionsSchema = z.object({
+  display: z.enum(['list', 'carousel']),
+  fields: z.object({
+    title: z.string(),
+    subtitle: z.string().nullable(),
+    image_url: z.string().nullable(),
+    url: z.string().optional(),
+    action_title: z.string().optional(),
+    action_payload: z.string().optional(),
+  }),
+  buttons: z.array(buttonSchema),
+  limit: z.number().finite(),
+  query: z.any().optional(),
+  entity: z.string().optional(),
+  top_element_style: z.enum(['large', 'compact']).optional(),
+});
+
+export type ContentOptions = z.infer<typeof contentOptionsSchema>;
+
+export const fallbackOptionsSchema = z.object({
+  active: z.boolean(),
+  message: z.array(z.string()),
+  max_attempts: z.number().finite(),
+});
+
+export type FallbackOptions = z.infer<typeof fallbackOptionsSchema>;
+
+export const BlockOptionsSchema = z.object({
+  typing: z.number().optional(),
+  content: contentOptionsSchema.optional(),
+  fallback: fallbackOptionsSchema.optional(),
+  assignTo: z.string().optional(),
+  effects: z.array(z.string()).optional(),
+});
+
+export type BlockOptions = z.infer<typeof BlockOptionsSchema>;

package/src/chat/types/pattern.ts

@@ -0,0 +1,77 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { PayloadType } from './button';
+
+export const payloadPatternSchema = z.object({
+  label: z.string(),
+  value: z.string(),
+  type: z.nativeEnum(PayloadType).optional(),
+});
+
+export type PayloadPattern = z.infer<typeof payloadPatternSchema>;
+
+export const nlpEntityMatchPatternSchema = z.object({
+  entity: z.string(),
+  match: z.literal('entity'),
+});
+
+export type NlpEntityMatchPattern = z.infer<typeof nlpEntityMatchPatternSchema>;
+
+export const nlpValueMatchPatternSchema = z.object({
+  entity: z.string(),
+  match: z.literal('value'),
+  value: z.string(),
+});
+
+export type NlpValueMatchPattern = z.infer<typeof nlpValueMatchPatternSchema>;
+
+export const nlpPatternSchema = z.discriminatedUnion('match', [
+  nlpEntityMatchPatternSchema,
+  nlpValueMatchPatternSchema,
+]);
+
+export type NlpPattern = NlpEntityMatchPattern | NlpValueMatchPattern;
+
+export const stringRegexPatternSchema = z.string().refine(
+  (value) => {
+    if (value.startsWith('/') && value.endsWith('/')) {
+      if (value.length === 2) return false;
+      try {
+        new RegExp(value.slice(1, -1), 'gi');
+
+        return true;
+      } catch (_err) {
+        return false;
+      }
+    }
+
+    return value !== '';
+  },
+  (value) => {
+    if (value.startsWith('/') && value.endsWith('/')) {
+      if (value.length === 2) {
+        return { message: 'Empty regex' };
+      }
+
+      return { message: 'Invalid regex' };
+    } else if (value.length === 0) {
+      return { message: 'Empty string' };
+    } else {
+      return {};
+    }
+  },
+);
+
+export const patternSchema = z.union([
+  stringRegexPatternSchema,
+  payloadPatternSchema,
+  z.array(nlpPatternSchema),
+]);
+
+export type Pattern = z.infer<typeof patternSchema>;

package/src/chat/types/position.ts

@@ -0,0 +1,14 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+export const positionSchema = z.object({
+  x: z.number(),
+  y: z.number(),
+});
+
+export type Position = z.infer<typeof positionSchema>;

package/src/chat/types/quick-reply.ts

@@ -0,0 +1,43 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { attachmentPayloadSchema } from './attachment';
+import { PayloadType } from './button';
+
+export enum QuickReplyType {
+  text = 'text',
+  location = 'location',
+  user_phone_number = 'user_phone_number',
+  user_email = 'user_email',
+}
+
+export const cordinatesSchema = z.object({
+  lat: z.number(),
+  lon: z.number(),
+});
+
+export const payloadSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal(PayloadType.location),
+    coordinates: cordinatesSchema,
+  }),
+  z.object({
+    type: z.literal(PayloadType.attachments),
+    attachment: attachmentPayloadSchema,
+  }),
+]);
+
+export const stdQuickReplySchema = z.object({
+  content_type: z.nativeEnum(QuickReplyType),
+  title: z.string(),
+  payload: z.string(),
+});
+
+export type Payload = z.infer<typeof payloadSchema>;
+
+export type StdQuickReply = z.infer<typeof stdQuickReplySchema>;

package/src/chat/types/subscriberContext.ts

@@ -0,0 +1,13 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+export const subscriberContextSchema = z.object({
+  vars: z.record(z.any()).optional(),
+});
+
+export type SubscriberContext = z.infer<typeof subscriberContextSchema>;

package/src/cli.ts

@@ -0,0 +1,28 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import 'dotenv/config';
+
+import moduleAlias from 'module-alias';
+import { CommandFactory } from 'nest-commander';
+
+moduleAlias.addAliases({
+  '@': __dirname,
+});
+
+import { HexabotApplicationModule } from './app.module';
+
+const isCliContext =
+  `${process.env.HEXABOT_CLI ?? ''}`.toLowerCase() === 'true' ||
+  process.env.HEXABOT_CLI === '1';
+
+async function bootstrap() {
+  await CommandFactory.run(HexabotApplicationModule);
+}
+
+if (isCliContext) {
+  bootstrap();
+}

package/src/cms/cms.module.ts

@@ -0,0 +1,45 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { forwardRef, Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { ChatModule } from '@/chat/chat.module';
+
+import { ContentTypeController } from './controllers/content-type.controller';
+import { ContentController } from './controllers/content.controller';
+import { MenuController } from './controllers/menu.controller';
+import { ContentTypeOrmEntity } from './entities/content-type.entity';
+import { ContentOrmEntity } from './entities/content.entity';
+import { MenuOrmEntity } from './entities/menu.entity';
+import { ContentTypeRepository } from './repositories/content-type.repository';
+import { ContentRepository } from './repositories/content.repository';
+import { MenuRepository } from './repositories/menu.repository';
+import { ContentTypeService } from './services/content-type.service';
+import { ContentService } from './services/content.service';
+import { MenuService } from './services/menu.service';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([
+      ContentOrmEntity,
+      ContentTypeOrmEntity,
+      MenuOrmEntity,
+    ]),
+    forwardRef(() => ChatModule),
+  ],
+  controllers: [ContentController, ContentTypeController, MenuController],
+  providers: [
+    ContentTypeService,
+    ContentService,
+    ContentTypeRepository,
+    ContentRepository,
+    MenuRepository,
+    MenuService,
+  ],
+  exports: [MenuService, ContentService, ContentTypeService],
+})
+export class CmsModule {}