@hexabot-ai/api 3.0.0-alpha.3

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

@@ -0,0 +1,212 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import {
+  OutgoingMessageFormat,
+  StdOutgoingAttachmentEnvelope,
+  stdOutgoingAttachmentEnvelopeSchema,
+  StdOutgoingButtonsEnvelope,
+  stdOutgoingButtonsEnvelopeSchema,
+  StdOutgoingEnvelope,
+  StdOutgoingListEnvelope,
+  stdOutgoingListEnvelopeSchema,
+  StdOutgoingMessageEnvelope,
+  StdOutgoingQuickRepliesEnvelope,
+  stdOutgoingQuickRepliesEnvelopeSchema,
+  StdOutgoingSystemEnvelope,
+  stdOutgoingSystemEnvelopeSchema,
+  StdOutgoingTextEnvelope,
+  stdOutgoingTextEnvelopeSchema,
+} from '../types/message';
+
+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],
+  ) => IEnvelopeBuilder<T>;
+} & {
+  [K in keyof T['message'] as `get${Capitalize<string & K>}`]-?: () => T['message'][K];
+} & {
+  [K in ArrayKeys<T['message']> as `appendTo${Capitalize<string & K>}`]: (
+    item: NonNullable<T['message'][K]> extends (infer U)[] ? U : never,
+  ) => IEnvelopeBuilder<T>;
+} & {
+  build(): T;
+};
+
+/**
+ * Extracts and transforms a property name into a standardized attribute name.
+ *
+ * @param prop - The property name from which to derive the attribute name.
+ * @param prefix - A regular expression that matches the prefix to remove from the property.
+ * @returns The transformed attribute name with its first character in lowercase.
+ */
+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);
+
+  return messageKey;
+}
+
+/**
+ * Builds an envelope object (containing a `format` and a `message` 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 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.
+ * @param factory - Envelope Factory which provides methods common methods.
+ *
+ * @returns A proxy-based builder object implementing `IEnvelopeBuilder<T>`. It provides
+ * chainable setter methods for all message fields, an `appendToX` pattern for
+ * array fields, and a `build()` method to finalize and validate the envelope.
+ *
+ * @example
+ * // Build a simple text envelope:
+ * const env1 = EnvelopeBuilder(OutgoingMessageFormat.text)
+ *   .setText('Hello')
+ *   .build();
+ *
+ * @example
+ * // Build a text envelope with quick replies:
+ * const env2 = EnvelopeBuilder(OutgoingMessageFormat.quickReplies)
+ *   .setText('Hello')
+ *   .setQuickReplies([])
+ *   .build();
+ *
+ * @example
+ * // Append multiple quickReplies items:
+ * const env3 = EnvelopeBuilder(OutgoingMessageFormat.quickReplies)
+ *   .setText('Are you interested?')
+ *   .appendToQuickReplies({
+ *     content_type: QuickReplyType.text,
+ *     title: 'Yes',
+ *     payload: 'yes',
+ *   })
+ *   .appendToQuickReplies({
+ *     content_type: QuickReplyType.text,
+ *     title: 'No',
+ *     payload: 'no',
+ *   })
+ *   .build();
+ *
+ * @example
+ * // Build a system envelope with an outcome:
+ * const env4 = EnvelopeBuilder(OutgoingMessageFormat.system)
+ *   .setOutcome('success')
+ *   .build();
+ */
+export function EnvelopeBuilder<T extends StdOutgoingEnvelope>(
+  format: T['format'],
+  template: Partial<T['message']> = {},
+  schema: z.ZodSchema,
+): IEnvelopeBuilder<T> {
+  let built: { format: T['format']; message: Partial<T['message']> } = {
+    format,
+    message: template,
+  };
+
+  const builder = new Proxy(
+    {},
+    {
+      get(target, prop) {
+        if ('build' === prop) {
+          // No type information - just return the object.
+          return () => {
+            const result = schema.parse(built);
+            built = {
+              format,
+              message: template,
+            };
+
+            return result;
+          };
+        }
+
+        if (typeof prop === 'string' && prop.startsWith('appendTo')) {
+          const messageKey = getAttributeNameFromProp(prop, /^appendTo/);
+
+          return (item: unknown) => {
+            // Initialize the array if needed
+            if (!Array.isArray(built.message[messageKey])) {
+              built.message[messageKey] = [];
+            }
+            (built.message[messageKey] as unknown[]).push(item);
+
+            return builder;
+          };
+        }
+
+        return (...args: unknown[]): unknown => {
+          // If no arguments passed return current value.
+          if (0 === args.length) {
+            const messageKey = getAttributeNameFromProp(
+              prop.toString(),
+              /^get/,
+            );
+
+            return built.message[messageKey];
+          }
+
+          const value = args[0];
+          const messageKey = getAttributeNameFromProp(prop.toString(), /^set/);
+          built.message[messageKey] = value;
+
+          return builder;
+        };
+      },
+    },
+  );
+
+  return builder as IEnvelopeBuilder<T>;
+}
+
+type EnvelopeTypeByFormat<F extends OutgoingMessageFormat> =
+  F extends OutgoingMessageFormat.text
+    ? StdOutgoingTextEnvelope
+    : F extends OutgoingMessageFormat.quickReplies
+      ? StdOutgoingQuickRepliesEnvelope
+      : F extends OutgoingMessageFormat.buttons
+        ? StdOutgoingButtonsEnvelope
+        : F extends OutgoingMessageFormat.attachment
+          ? StdOutgoingAttachmentEnvelope
+          : F extends OutgoingMessageFormat.carousel
+            ? StdOutgoingListEnvelope
+            : F extends OutgoingMessageFormat.list
+              ? StdOutgoingListEnvelope
+              : F extends OutgoingMessageFormat.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,
+};
+
+export const getEnvelopeBuilder = <F extends OutgoingMessageFormat>(
+  format: F,
+) => {
+  return EnvelopeBuilder<EnvelopeTypeByFormat<F>>(
+    format,
+    {},
+    ENVELOP_SCHEMAS_BY_FORMAT[format],
+  );
+};

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

@@ -0,0 +1,275 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import Handlebars from 'handlebars';
+
+import { I18nService } from '@/i18n/services/i18n.service';
+import { getRandomElement } from '@/utils/helpers/safeRandom';
+
+import { AttachmentPayload } from '../types/attachment';
+import { Button, ButtonType } from '../types/button';
+import { Context, TemplateContext } from '../types/context';
+import {
+  ContentElement,
+  ContentPagination,
+  OutgoingMessageFormat,
+  StdOutgoingAttachmentEnvelope,
+  StdOutgoingButtonsEnvelope,
+  StdOutgoingListEnvelope,
+  StdOutgoingQuickRepliesEnvelope,
+  StdOutgoingSystemEnvelope,
+  StdOutgoingTextEnvelope,
+} from '../types/message';
+import { ContentOptions } from '../types/options';
+import { StdQuickReply } from '../types/quick-reply';
+
+import { getEnvelopeBuilder } from './envelope-builder';
+
+export class EnvelopeFactory {
+  constructor(
+    protected readonly context: Context,
+    protected readonly settings: Settings,
+    protected readonly i18n: I18nService,
+  ) {}
+
+  /**
+   * Converts an old text template with single-curly placeholders, e.g. `{context.user.name}`,
+   * into a Handlebars-style template, e.g. `{{context.user.name}}`.
+   *
+   * @param str - The template string you want to convert.
+   * @returns The converted template string with Handlebars-style placeholders.
+   */
+  static toHandlebars(str: string) {
+    // If the string already contains {{ }}, assume it's already a handlebars template.
+    if (/\{\{.*\}\}/.test(str)) {
+      return str;
+    }
+
+    // Otherwise, replace single curly braces { } with double curly braces {{ }}.
+    return str.replaceAll(/{([^}]+)}/g, '{{$1}}');
+  }
+
+  /**
+   * Compiles a handlebars template to replace tokens with their associated values in the provided text message
+   *
+   * `You phone number is {{context.vars.phone}}`
+   * Becomes
+   * `You phone number is 6354-543-534`
+   *
+   * @param text - Text message
+   * @param context - Object holding context variables relative to the conversation (temporary)
+   * @param subscriberContext - Object holding context values relative to the subscriber (permanent)
+   * @param settings - Settings Object
+   *
+   * @returns Text message with the tokens being replaced
+   */
+  static compileHandlebarsTemplate(
+    text: string,
+    context: Context,
+    settings: Settings,
+  ): string {
+    // Build the template context for Handlebars to match our token paths
+    const templateContext: TemplateContext = {
+      context: { ...context },
+      contact: { ...settings.contact },
+    };
+    // Compile and run the Handlebars template
+    const compileTemplate = Handlebars.compile(
+      EnvelopeFactory.toHandlebars(text),
+    );
+
+    return compileTemplate(templateContext);
+  }
+
+  /**
+   * Processes the provided text or array of texts, localizes it based on the user's language settings,
+   * and then compiles it with the current context and settings using Handlebars templates.
+   *
+   * @param text - The text or an array of text strings to be processed.
+   * @returns - The processed and localized text.
+   */
+  public processText(text: string | string[]): string {
+    let result = Array.isArray(text) ? getRandomElement(text) : text;
+    result = this.i18n.t(result, {
+      lang: this.context.user.language || undefined,
+      defaultValue: result,
+    });
+    result = EnvelopeFactory.compileHandlebarsTemplate(
+      result,
+      this.context,
+      this.settings,
+    );
+
+    return result;
+  }
+
+  /**
+   * Returns an envelope builder instance for the specified message format.
+   *
+   * @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.
+   */
+  getBuilder<F extends OutgoingMessageFormat>(format: F) {
+    return getEnvelopeBuilder<F>(format);
+  }
+
+  /**
+   * Builds a text envelope by processing the provided text.
+   *
+   * This method processes the input text for localization and template compilation,
+   * then builds a text envelope using the envelope builder.
+   *
+   * @param text - The text content or an array of text variants.
+   * @returns A finalized text envelope object.
+   */
+  buildTextEnvelope(text: string | string[]): StdOutgoingTextEnvelope {
+    const builder = this.getBuilder(OutgoingMessageFormat.text);
+    const processedText = this.processText(text);
+
+    return builder.setText(processedText).build();
+  }
+
+  /**
+   * Builds a quick replies envelope by processing the text and quick reply items.
+   *
+   * Processes the input text for localization and template compilation, then appends each
+   * processed quick reply (with localized title and payload) to the envelope before finalizing it.
+   *
+   * @param text - The text content or an array of text variants.
+   * @param quickReplies - An array of quick reply objects.
+   * @returns A finalized quick replies envelope object.
+   */
+  buildQuickRepliesEnvelope(
+    text: string | string[],
+    quickReplies: StdQuickReply[],
+  ): StdOutgoingQuickRepliesEnvelope {
+    const builder = this.getBuilder(OutgoingMessageFormat.quickReplies);
+    const processedText = this.processText(text);
+    const envelope = builder.setText(processedText);
+
+    quickReplies.forEach((qr) => {
+      envelope.appendToQuickReplies({
+        ...qr,
+        title: this.processText(qr.title),
+        payload: this.processText(qr.payload),
+      });
+    });
+
+    return envelope.build();
+  }
+
+  /**
+   * Builds a buttons envelope by processing the text and button items.
+   *
+   * Processes the input text and iterates over the provided buttons.
+   * For postback buttons, both the title and payload are processed; for other button types,
+   * only the title is processed. Each processed button is then appended to the envelope.
+   *
+   * @param text - The text content or an array of text variants.
+   * @param buttons - An array of button objects.
+   * @returns A finalized buttons envelope object.
+   */
+  buildButtonsEnvelope(
+    text: string | string[],
+    buttons: Button[],
+  ): StdOutgoingButtonsEnvelope {
+    const builder = this.getBuilder(OutgoingMessageFormat.buttons);
+    const processedText = this.processText(text);
+    const envelope = builder.setText(processedText);
+
+    buttons.forEach((btn) => {
+      if (btn.type === ButtonType.postback) {
+        envelope.appendToButtons({
+          ...btn,
+          title: this.processText(btn.title),
+          payload: this.processText(btn.payload),
+        });
+      } else {
+        envelope.appendToButtons({
+          ...btn,
+          title: this.processText(btn.title),
+        });
+      }
+    });
+
+    return envelope.build();
+  }
+
+  /**
+   * Builds an attachment envelope with the provided attachment payload.
+   *
+   * Sets the attachment on the envelope and appends any quick replies after processing
+   * them for localization and template compilation.
+   *
+   * @param attachment - The attachment payload object.
+   * @param quickReplies - Optional array of quick reply objects.
+   * @returns A finalized attachment envelope object.
+   */
+  buildAttachmentEnvelope(
+    attachment: AttachmentPayload,
+    quickReplies: StdQuickReply[] = [],
+  ): StdOutgoingAttachmentEnvelope {
+    const builder = this.getBuilder(OutgoingMessageFormat.attachment);
+    const envelope = builder.setAttachment(attachment);
+
+    quickReplies.forEach((qr) => {
+      envelope.appendToQuickReplies({
+        ...qr,
+        title: this.processText(qr.title),
+        payload: this.processText(qr.payload),
+      });
+    });
+
+    return envelope.build();
+  }
+
+  /**
+   * Builds a list or carousel envelope using the provided content options.
+   *
+   * 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 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,
+    options: ContentOptions,
+    elements: ContentElement[],
+    pagination: ContentPagination,
+  ): StdOutgoingListEnvelope {
+    const builder = this.getBuilder(format);
+
+    return builder
+      .setOptions(options)
+      .setElements(elements)
+      .setPagination(pagination)
+      .build();
+  }
+
+  /**
+   * Builds a system envelope with the specified outcome and optional data.
+   *
+   * Processes the provided outcome and additional data (if any) to create a system envelope.
+   * This envelope type is used for system-level messaging.
+   *
+   * @param outcome - The outcome message or status.
+   * @param data - Optional additional data to include in the envelope.
+   * @returns A finalized system envelope object.
+   */
+  buildSystemEnvelope(
+    outcome: string | undefined,
+    data?: unknown,
+  ): StdOutgoingSystemEnvelope {
+    const builder = this.getBuilder(OutgoingMessageFormat.system);
+
+    return builder.setOutcome(outcome).setData(data).build();
+  }
+}

package/src/chat/index.ts

@@ -0,0 +1,129 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export * from './chat.module';
+
+export * from './constants/block';
+
+export * from './constants/conversation';
+
+export * from './controllers/block.controller';
+
+export * from './controllers/category.controller';
+
+export * from './controllers/context-var.controller';
+
+export * from './controllers/label-group.controller';
+
+export * from './controllers/label.controller';
+
+export * from './controllers/message.controller';
+
+export * from './controllers/subscriber.controller';
+
+export * from './dto/block.dto';
+
+export * from './dto/category.dto';
+
+export * from './dto/context-var.dto';
+
+export * from './dto/conversation.dto';
+
+export * from './dto/label-group.dto';
+
+export * from './dto/label.dto';
+
+export * from './dto/message.dto';
+
+export * from './dto/subscriber.dto';
+
+export * from './entities/block.entity';
+
+export * from './entities/category.entity';
+
+export * from './entities/context-var.entity';
+
+export * from './entities/conversation.entity';
+
+export * from './entities/label-group.entity';
+
+export * from './entities/label.entity';
+
+export * from './entities/message.entity';
+
+export * from './entities/subscriber.entity';
+
+export * from './helpers/constants';
+
+export * from './helpers/envelope-builder';
+
+export * from './helpers/envelope-factory';
+
+export * from './repositories/block.repository';
+
+export * from './repositories/category.repository';
+
+export * from './repositories/context-var.repository';
+
+export * from './repositories/conversation.repository';
+
+export * from './repositories/label-group.repository';
+
+export * from './repositories/label.repository';
+
+export * from './repositories/message.repository';
+
+export * from './repositories/subscriber.repository';
+
+export * from './seeds/category.seed-model';
+
+export * from './seeds/category.seed';
+
+export * from './seeds/context-var.seed-model';
+
+export * from './seeds/context-var.seed';
+
+export * from './services/block.service';
+
+export * from './services/bot.service';
+
+export * from './services/category.service';
+
+export * from './services/chat.service';
+
+export * from './services/context-var.service';
+
+export * from './services/conversation.service';
+
+export * from './services/label-group.service';
+
+export * from './services/label.service';
+
+export * from './services/message.service';
+
+export * from './services/subscriber.service';
+
+export * from './types/attachment';
+
+export * from './types/button';
+
+export * from './types/capture-var';
+
+export * from './types/channel';
+
+export * from './types/context';
+
+export * from './types/message';
+
+export * from './types/options';
+
+export * from './types/pattern';
+
+export * from './types/position';
+
+export * from './types/quick-reply';
+
+export * from './types/subscriberContext';