@dev.smartpricing/message-composer-utils 3.1.2

package/src/types/language.ts

@@ -0,0 +1,9 @@
+import type { DbEntity, WithDbTimestamps } from "./utils.js";
+
+export interface Language extends DbEntity {
+  id: string;
+  name: string;
+  flag: string;
+}
+
+export type LanguageFromDb = WithDbTimestamps<Language>;

package/src/types/media.ts

@@ -0,0 +1,26 @@
+import type { DbEntity, WithDbTimestamps } from "./utils.js";
+
+export type MediaType = "image" | "video" | "document";
+
+export const MEDIA_LIMITS = {
+  image: { maxSize: 5 * 1024 * 1024, accept: ["image/jpeg", "image/png"] },
+  video: { maxSize: 16 * 1024 * 1024, accept: ["video/mp4", "video/3gpp"] },
+  document: { maxSize: 20 * 1024 * 1024, accept: ["application/pdf"] },
+} as const satisfies Record<
+  MediaType,
+  { maxSize: number; accept: readonly string[] }
+>;
+
+export interface Media extends DbEntity {
+  id: string;
+  remote_url: string;
+  remote_name: string; // Sanitized filename stored in GCS (includes UUID prefix)
+  file_name: string; // Original filename from user
+  file_type: string;
+  meta_handle_id?: string;
+  smartchat_media_id?: string;
+  owner?: string;
+  user_id: string;
+}
+
+export type MediaFromDb = WithDbTimestamps<Media>;

package/src/types/message.ts

@@ -0,0 +1,635 @@
+import { z } from "zod";
+import type { MetaTemplate } from "./meta-template.js";
+import type { DbEntity, PostEntity, WithDbTimestamps } from "./utils.js";
+import type {
+  BodyBlockV1,
+  FooterBlockV1,
+  HeaderBlockV1,
+  ButtonBlockV1,
+} from "./whatsappblocks.v1.js";
+import type { EmailBlock, EmailGlobalSettings } from "./emailblocks.v1.js";
+import {
+  brandDefaultEmailSettingsSchema,
+  brandDefaultButtonSettingsSchema,
+} from "./brand.js";
+
+export const MESSAGE_RENDER_TYPES = ["whatsapp_v1", "email_v1"] as const;
+export type RenderType = (typeof MESSAGE_RENDER_TYPES)[number];
+export const MESSAGE_STATUS = [
+  "pending",
+  "draft",
+  "rejected",
+  "approved",
+] as const;
+export type MessageStatus = (typeof MESSAGE_STATUS)[number];
+
+interface BaseMessage extends DbEntity {
+  id: string;
+  message_group_id: string;
+  language_id: string;
+  status: MessageStatus;
+  render_type: RenderType;
+  owner?: string;
+  user_id: string;
+}
+export interface WhatsappMessage extends BaseMessage {
+  render_type: "whatsapp_v1";
+  body: {
+    header: HeaderBlockV1;
+    body: BodyBlockV1;
+    footer: FooterBlockV1;
+    buttons: ButtonBlockV1;
+  };
+  metadata: {
+    meta?: {
+      template_id: string;
+      template_name: string;
+      submission_date: string;
+      approval_date?: string;
+      rejection_reason?: string;
+      translated_template: MetaTemplate;
+    };
+  };
+}
+export interface EmailMessage extends BaseMessage {
+  render_type: "email_v1";
+  body: {
+    subject: string;
+    blocks: EmailBlock[];
+    settings: EmailGlobalSettings;
+  };
+  metadata: {
+    preheader?: string;
+    email?: {
+      mjml: string;
+      compilation_date: string;
+    };
+  };
+}
+
+export type Message = WhatsappMessage | EmailMessage;
+
+export type MessageFromDb = WithDbTimestamps<Message>;
+
+export const MESSAGE_GROUP_CATEGORIES = ["marketing", "utility"] as const;
+export type MessageGroupCategory = (typeof MESSAGE_GROUP_CATEGORIES)[number];
+
+export const MESSAGE_GROUP_VISIBILITY = ["public", "internal"] as const;
+export type MessageGroupVisibility = (typeof MESSAGE_GROUP_VISIBILITY)[number];
+
+export interface MessageGroup extends DbEntity {
+  id: string;
+  name: string;
+  category: MessageGroupCategory;
+  visibility?: MessageGroupVisibility;
+  brand_id?: string | null;
+  owner?: string;
+  user_id: string;
+}
+
+export type MessageGroupFromDb = WithDbTimestamps<MessageGroup>;
+
+/**
+ * Message Group Validation Types
+ */
+
+export interface MessageContentValidationEntry {
+  type: RenderType;
+  errors: string[];
+}
+
+export interface MessageGroupValidationErrors {
+  status: string[];
+  languages: string[];
+  content: Record<string, MessageContentValidationEntry>;
+}
+
+export interface MessageGroupValidationResponse {
+  valid: boolean;
+  errors: MessageGroupValidationErrors;
+}
+
+/**
+ * Message Compilation Types
+ */
+
+/**
+ * Request body for compiling a message template
+ */
+export interface CompileMessageRequest {
+  /** Language code to compile (e.g., 'en', 'it', 'es') */
+  language: string;
+
+  /** Optional fallback language if primary language not found */
+  fallbackLanguage?: string;
+
+  /** Key-value pairs for parameter injection into template placeholders */
+  parameters: Record<string, unknown>;
+
+  /** When true, throws on missing parameters. When false (default), replaces missing params with empty string */
+  strict?: boolean;
+
+  /** Optional brand ID override — uses this brand instead of the message_group's brand */
+  brand_id?: string;
+}
+
+/**
+ * Brand cascade data schema for preview validation.
+ * Subset of BrandFromDb used at compile time.
+ */
+export const brandCascadeDataSchema = z.object({
+  default_email_settings: brandDefaultEmailSettingsSchema,
+  default_button_settings: brandDefaultButtonSettingsSchema,
+  default_socials: z.record(z.string(), z.string()).nullable(),
+  logo_url: z.string().nullable(),
+});
+
+/**
+ * Request body for previewing a message with inline data (no DB lookups).
+ */
+export const previewMessageRequestSchema = z.object({
+  message: z
+    .object({
+      render_type: z.literal("email_v1"),
+      language_id: z.string(),
+      body: z.object({
+        subject: z.string(),
+        blocks: z.array(z.record(z.string(), z.unknown())),
+        settings: z.record(z.string(), z.unknown()),
+      }),
+      metadata: z.record(z.string(), z.unknown()).optional(),
+    })
+    .passthrough(),
+  parameters: z.record(z.string(), z.unknown()).optional().default({}),
+  brand: brandCascadeDataSchema.nullable().optional().default(null),
+});
+
+export type PreviewMessageRequest = z.infer<typeof previewMessageRequestSchema>;
+
+export type EmailProvider = "SendGrid" | "AmazonSES";
+
+/**
+ * Request body for compiling and preparing message for sending
+ */
+export interface CompileAndSendRequest extends CompileMessageRequest {
+  /** Sender identifier (WhatsApp: phone number ID, Email: from address) */
+  from: string;
+
+  /** Recipient identifier (WhatsApp: phone number, Email: email address) */
+  to: string;
+
+  /**
+   * Message ID to be used for context
+   * @deprecated Use additionalInfo instead
+   */
+  automationEngineMessageId?: string;
+
+  /** Additional parameters to be sent with the message */
+  additionalInfo?: Record<string, unknown>;
+
+  /** Email provider override (default: "SendGrid") */
+  provider?: EmailProvider;
+
+  /** Message kind — when "newsletter", sends via Queen queue instead of messageAPI */
+  kind?: string;
+}
+
+/**
+ * Request body for testing email rendering
+ */
+export interface TestEmailRequest {
+  /** Email message configuration */
+  message: PostEntity<EmailMessage>;
+
+  /** Recipient email address for testing */
+  to: string;
+}
+
+/**
+ * WhatsApp Cloud API send message payloads
+ * Reference: https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages
+ */
+
+// Base properties common to all message types
+interface WhatsAppMessageBase {
+  messaging_product: "whatsapp";
+  recipient_type?: "individual";
+  to: string;
+  biz_opaque_callback_data?: string;
+  context?: {
+    message_id: string;
+  };
+}
+
+// Template message type
+
+type WhatsappHeaderParamText = {
+  type: "text";
+  text: string;
+  parameter_name: string;
+};
+type WhatsappHeaderParamImage = {
+  type: "image";
+  image: { link: string } | { id: string };
+};
+type WhatsappHeaderParamVideo = {
+  type: "video";
+  video: { link: string } | { id: string };
+};
+type WhatsappHeaderParamDocument = {
+  type: "document";
+  document:
+    | { link: string; filename?: string }
+    | { id: string; filename?: string };
+};
+
+export type WhatsappHeaderParam =
+  | WhatsappHeaderParamText
+  | WhatsappHeaderParamImage
+  | WhatsappHeaderParamVideo
+  | WhatsappHeaderParamDocument;
+
+interface WhatsAppTemplateMessage extends WhatsAppMessageBase {
+  type: "template";
+  template: {
+    name: string;
+    language: {
+      code: string;
+      policy?: "deterministic";
+    };
+    components?: Array<
+      | {
+          type: "HEADER";
+          parameters: WhatsappHeaderParam[];
+        }
+      | {
+          type: "BODY";
+          parameters: Array<
+            | { type: "text"; text: string; parameter_name: string }
+            | {
+                type: "currency";
+                currency: {
+                  fallback_value: string;
+                  code: string;
+                  amount_1000: number;
+                };
+              }
+            | { type: "date_time"; date_time: { fallback_value: string } }
+          >;
+        }
+      | {
+          type: "BUTTON";
+          sub_type: "url";
+          index: string; // "0", "1", "2" - string representation of button position
+          parameters: Array<{
+            type: "text";
+            parameter_name: string;
+            text: string; // Dynamic URL suffix for URL buttons
+          }>;
+        }
+    >;
+  };
+}
+
+/**
+ * Union type for all WhatsApp message payloads
+ * NOTE: Only template messages implemented in v1
+ */
+export type WhatsAppSendPayload = WhatsAppTemplateMessage;
+
+/**
+ * Response for compile endpoint (WhatsApp)
+ */
+export interface CompileWhatsAppResponse {
+  render_type: "whatsapp_v1";
+  language: string;
+  template_name: string;
+  payload: Omit<WhatsAppTemplateMessage, "to">;
+  parameters_used: string[];
+  missingParameters?: string[];
+}
+
+/**
+ * Response for compile endpoint (Email)
+ */
+export interface CompileEmailResponse {
+  render_type: "email_v1";
+  language: string;
+  subject: string;
+  html: string;
+  parameters_used: string[];
+  missingParameters?: string[];
+}
+
+export type CompileMessageResponse =
+  | CompileWhatsAppResponse
+  | CompileEmailResponse;
+
+/**
+ * Response for compile-and-send endpoint
+ * Simple status response - actual sending happens via smartchat-sender service
+ */
+export interface CompileAndSendResponse {
+  sent: boolean;
+  template_id: string;
+  language: string;
+  missingParameters?: string[];
+}
+
+/**
+ * Parameter validation result
+ * Keep it simple - just valid/invalid with list of required parameters
+ */
+export interface ParameterValidationResult {
+  valid: boolean;
+  required: string[];
+  missing: string[];
+}
+
+/**
+ * Response for get-parameters endpoint
+ */
+export interface GetMessageParametersResponse {
+  render_type: RenderType;
+  language: string;
+  parameters: string[];
+}
+
+// Text message type (for future use, not in compile endpoints)
+export interface WhatsAppTextMessage extends WhatsAppMessageBase {
+  type: "text";
+  text: {
+    body: string;
+    preview_url?: boolean;
+  };
+}
+
+// Media message types
+export interface WhatsAppImageMessage extends WhatsAppMessageBase {
+  type: "image";
+  image: {
+    link?: string;
+    id?: string;
+    caption?: string;
+  };
+}
+
+export interface WhatsAppVideoMessage extends WhatsAppMessageBase {
+  type: "video";
+  video: {
+    link?: string;
+    id?: string;
+    caption?: string;
+  };
+}
+
+export interface WhatsAppAudioMessage extends WhatsAppMessageBase {
+  type: "audio";
+  audio: {
+    link?: string;
+    id?: string;
+  };
+}
+
+export interface WhatsAppDocumentMessage extends WhatsAppMessageBase {
+  type: "document";
+  document: {
+    link?: string;
+    id?: string;
+    caption?: string;
+    filename?: string;
+  };
+}
+
+// Location message type
+export interface WhatsAppLocationMessage extends WhatsAppMessageBase {
+  type: "location";
+  location: {
+    latitude: string;
+    longitude: string;
+    name?: string;
+    address?: string;
+  };
+}
+
+// Contacts message type
+export interface WhatsAppContactsMessage extends WhatsAppMessageBase {
+  type: "contacts";
+  contacts: Array<{
+    addresses?: Array<{
+      street?: string;
+      city?: string;
+      state?: string;
+      zip?: string;
+      country?: string;
+      country_code?: string;
+      type?: "HOME" | "WORK";
+    }>;
+    birthday?: string;
+    emails?: Array<{
+      email?: string;
+      type?: "HOME" | "WORK";
+    }>;
+    name: {
+      formatted_name: string;
+      first_name?: string;
+      last_name?: string;
+      middle_name?: string;
+      suffix?: string;
+      prefix?: string;
+    };
+    org?: {
+      company?: string;
+      department?: string;
+      title?: string;
+    };
+    phones?: Array<{
+      phone?: string;
+      type?: "HOME" | "WORK" | "CELL";
+      wa_id?: string;
+    }>;
+    urls?: Array<{
+      url?: string;
+      type?: "HOME" | "WORK";
+    }>;
+  }>;
+}
+
+// Interactive message types
+export interface WhatsAppInteractiveButtonMessage extends WhatsAppMessageBase {
+  type: "interactive";
+  interactive: {
+    type: "button";
+    header?: {
+      type: "text" | "image" | "video" | "document";
+      text?: string;
+      image?: { link: string };
+      video?: { link: string };
+      document?: { link: string; filename?: string };
+    };
+    body: {
+      text: string;
+    };
+    footer?: {
+      text: string;
+    };
+    action: {
+      buttons: Array<{
+        type: "reply";
+        reply: {
+          id: string;
+          title: string;
+        };
+      }>;
+    };
+  };
+}
+
+export interface WhatsAppInteractiveListMessage extends WhatsAppMessageBase {
+  type: "interactive";
+  interactive: {
+    type: "list";
+    header?: {
+      type: "text";
+      text: string;
+    };
+    body: {
+      text: string;
+    };
+    footer?: {
+      text: string;
+    };
+    action: {
+      button: string;
+      sections: Array<{
+        title?: string;
+        rows: Array<{
+          id: string;
+          title: string;
+          description?: string;
+        }>;
+      }>;
+    };
+  };
+}
+
+export interface WhatsAppInteractiveProductMessage extends WhatsAppMessageBase {
+  type: "interactive";
+  interactive: {
+    type: "product";
+    body?: {
+      text: string;
+    };
+    footer?: {
+      text: string;
+    };
+    action: {
+      catalog_id: string;
+      product_retailer_id: string;
+    };
+  };
+}
+
+export interface WhatsAppInteractiveProductListMessage extends WhatsAppMessageBase {
+  type: "interactive";
+  interactive: {
+    type: "product_list";
+    header: {
+      type: "text";
+      text: string;
+    };
+    body: {
+      text: string;
+    };
+    footer?: {
+      text: string;
+    };
+    action: {
+      catalog_id: string;
+      sections: Array<{
+        title: string;
+        product_items: Array<{
+          product_retailer_id: string;
+        }>;
+      }>;
+    };
+  };
+}
+
+export interface WhatsAppInteractiveCatalogMessage extends WhatsAppMessageBase {
+  type: "interactive";
+  interactive: {
+    type: "catalog_message";
+    body: {
+      text: string;
+    };
+    action: {
+      name: "catalog_message";
+      parameters: {
+        thumbnail_product_retailer_id: string;
+      };
+    };
+    footer?: {
+      text: string;
+    };
+  };
+}
+
+export interface WhatsAppInteractiveFlowMessage extends WhatsAppMessageBase {
+  type: "interactive";
+  interactive: {
+    type: "flow";
+    header?: {
+      type: "text";
+      text: string;
+    };
+    body: {
+      text: string;
+    };
+    footer?: {
+      text: string;
+    };
+    action: {
+      name: "flow";
+      parameters: {
+        flow_message_version: "3";
+        flow_id?: string;
+        flow_name?: string;
+        flow_cta: string;
+        flow_action?: "navigate" | "data_exchange";
+        flow_action_payload?: Record<string, unknown>;
+      };
+    };
+  };
+}
+
+export interface WhatsAppCallPermissionRequestMessage extends WhatsAppMessageBase {
+  type: "interactive";
+  interactive: {
+    type: "call_permission_request";
+    body: {
+      text: string;
+    };
+    action: {
+      name: "call_permission_request";
+    };
+  };
+}
+
+// Union type for all WhatsApp message payloads (extended types for future)
+export type WhatsAppSendPayloadExtended =
+  | WhatsAppTemplateMessage
+  | WhatsAppTextMessage
+  | WhatsAppImageMessage
+  | WhatsAppVideoMessage
+  | WhatsAppAudioMessage
+  | WhatsAppDocumentMessage
+  | WhatsAppLocationMessage
+  | WhatsAppContactsMessage
+  | WhatsAppInteractiveButtonMessage
+  | WhatsAppInteractiveListMessage
+  | WhatsAppInteractiveProductMessage
+  | WhatsAppInteractiveProductListMessage
+  | WhatsAppInteractiveCatalogMessage
+  | WhatsAppInteractiveFlowMessage
+  | WhatsAppCallPermissionRequestMessage;

package/src/types/meta-template.ts

@@ -0,0 +1,50 @@
+export interface NamedParam {
+  param_name: string;
+  example: string;
+}
+
+// Meta template types
+export interface MetaHeaderComponent {
+  type: "HEADER";
+  format: "TEXT" | "IMAGE" | "VIDEO" | "DOCUMENT";
+  text?: string;
+  example?:
+    | { header_text_named_params: NamedParam[] }
+    | { header_handle: string[] };
+}
+
+export interface MetaBodyComponent {
+  type: "BODY";
+  text: string;
+  example?: { body_text_named_params: NamedParam[] };
+}
+
+export interface MetaFooterComponent {
+  type: "FOOTER";
+  text: string;
+}
+
+export interface MetaButtonComponent {
+  type: "BUTTONS";
+  buttons: Array<{
+    type: "QUICK_REPLY" | "PHONE_NUMBER" | "URL";
+    text: string;
+    url?: string;
+    phone_number?: string;
+    example?: string[];
+  }>;
+}
+
+export interface MetaTemplate {
+  name: string;
+  language: string;
+  category: "MARKETING" | "UTILITY";
+  parameter_format: "NAMED";
+  allow_category_change: boolean;
+  components: Array<
+    | MetaHeaderComponent
+    | MetaBodyComponent
+    | MetaFooterComponent
+    | MetaButtonComponent
+  >;
+}