@ariaflowagents/messaging-meta 0.8.1

package/dist/whatsapp/split.js

@@ -0,0 +1,76 @@
+/**
+ * @module whatsapp/split
+ *
+ * Smart message splitting for WhatsApp's 4096-character limit.
+ *
+ * Splits long messages at natural boundaries (paragraph breaks, line breaks)
+ * to maintain readability. Falls back to hard splitting only when no natural
+ * boundary exists within the allowed range.
+ */
+/** Maximum character length for a single WhatsApp text message. */
+const MAX_LENGTH = 4096;
+/**
+ * Split a text message into chunks that fit within WhatsApp's character limit.
+ *
+ * The splitting strategy prioritises readability:
+ * 1. Paragraph boundaries (`\n\n`) within the first `maxLength` characters.
+ * 2. Line boundaries (`\n`) if no paragraph break is available.
+ * 3. Word boundaries (last space character) as a third preference.
+ * 4. Hard split at `maxLength` as a last resort.
+ *
+ * A split point is only used if it falls in the latter half of the chunk
+ * to avoid producing very short fragments.
+ *
+ * @param text      - The full message text.
+ * @param maxLength - Maximum characters per chunk. Default `4096`.
+ * @returns An array of text chunks, each within `maxLength`.
+ *
+ * @example
+ * ```ts
+ * const chunks = splitMessage(longReport);
+ * for (const chunk of chunks) {
+ *   await client.sendText(to, chunk);
+ * }
+ * ```
+ */
+export function splitMessage(text, maxLength = MAX_LENGTH) {
+    if (text.length <= maxLength) {
+        return [text];
+    }
+    const chunks = [];
+    let remaining = text;
+    const minSplit = Math.floor(maxLength / 2);
+    while (remaining.length > maxLength) {
+        let splitIndex = -1;
+        // 1. Try paragraph boundary (\n\n)
+        splitIndex = remaining.lastIndexOf('\n\n', maxLength);
+        if (splitIndex > 0 && splitIndex >= minSplit) {
+            // Include the first newline as part of the chunk
+            chunks.push(remaining.slice(0, splitIndex).trimEnd());
+            remaining = remaining.slice(splitIndex + 2).trimStart();
+            continue;
+        }
+        // 2. Try line boundary (\n)
+        splitIndex = remaining.lastIndexOf('\n', maxLength);
+        if (splitIndex > 0 && splitIndex >= minSplit) {
+            chunks.push(remaining.slice(0, splitIndex).trimEnd());
+            remaining = remaining.slice(splitIndex + 1).trimStart();
+            continue;
+        }
+        // 3. Try word boundary (space)
+        splitIndex = remaining.lastIndexOf(' ', maxLength);
+        if (splitIndex > 0 && splitIndex >= minSplit) {
+            chunks.push(remaining.slice(0, splitIndex).trimEnd());
+            remaining = remaining.slice(splitIndex + 1).trimStart();
+            continue;
+        }
+        // 4. Hard split at max length
+        chunks.push(remaining.slice(0, maxLength));
+        remaining = remaining.slice(maxLength);
+    }
+    if (remaining.length > 0) {
+        chunks.push(remaining);
+    }
+    return chunks;
+}
+//# sourceMappingURL=split.js.map

package/dist/whatsapp/split.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"split.js","sourceRoot":"","sources":["../../src/whatsapp/split.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,mEAAmE;AACnE,MAAM,UAAU,GAAG,IAAI,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,YAAoB,UAAU;IACvE,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS,EAAE,CAAC;QAC7B,OAAO,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,SAAS,GAAG,IAAI,CAAC;IACrB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAE3C,OAAO,SAAS,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QACpC,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC;QAEpB,mCAAmC;QACnC,UAAU,GAAG,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACtD,IAAI,UAAU,GAAG,CAAC,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;YAC7C,iDAAiD;YACjD,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YACtD,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;YACxD,SAAS;QACX,CAAC;QAED,4BAA4B;QAC5B,UAAU,GAAG,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACpD,IAAI,UAAU,GAAG,CAAC,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;YAC7C,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YACtD,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;YACxD,SAAS;QACX,CAAC;QAED,+BAA+B;QAC/B,UAAU,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACnD,IAAI,UAAU,GAAG,CAAC,IAAI,UAAU,IAAI,QAAQ,EAAE,CAAC;YAC7C,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;YACtD,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;YACxD,SAAS;QACX,CAAC;QAED,8BAA8B;QAC9B,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;QAC3C,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/whatsapp/templates.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @module whatsapp/templates
+ *
+ * Builder utilities for constructing WhatsApp template message payloads.
+ *
+ * Provides both a **typed builder** (structured config with type-safe
+ * header/body/button definitions) and a **raw builder** (passthrough with
+ * minimal normalization) for maximum flexibility.
+ *
+ * @example
+ * ```ts
+ * // Typed builder
+ * const payload = buildTemplateSendPayload({
+ *   name: 'order_confirmation',
+ *   language: 'en_US',
+ *   body: [
+ *     { type: 'text', text: 'John' },
+ *     { type: 'text', text: 'ORD-12345' },
+ *   ],
+ * });
+ *
+ * await client.sendTemplate(to, payload);
+ * ```
+ */
+import type { TemplateMessage, TemplateComponent, TemplateParameter, MediaObject } from './types.js';
+/**
+ * Typed configuration for building a template send payload.
+ *
+ * Provides a structured way to specify header, body, and button parameters
+ * without manually constructing the `components` array.
+ */
+export interface TypedTemplateConfig {
+    /** Template name (must match an approved template). */
+    name: string;
+    /** BCP 47 language code (e.g. `"en_US"`). */
+    language: string;
+    /** Header parameter — text or media. */
+    header?: {
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image';
+        image: MediaObject;
+    } | {
+        type: 'video';
+        video: MediaObject;
+    } | {
+        type: 'document';
+        document: MediaObject;
+    };
+    /** Body parameters (positional, matching `{{1}}`, `{{2}}`, etc.). */
+    body?: TemplateParameter[];
+    /** Button parameters (for dynamic URL suffixes or quick-reply payloads). */
+    buttons?: Array<{
+        /** Must be `"button"`. */
+        type: 'button';
+        /** Button sub-type (e.g. `"url"`, `"quick_reply"`). */
+        subType: string;
+        /** Zero-based button index. */
+        index: number;
+        /** Parameters for this button. */
+        parameters: TemplateParameter[];
+    }>;
+}
+/**
+ * Build a template message payload from a typed configuration.
+ *
+ * Converts the structured {@link TypedTemplateConfig} into Meta's
+ * `components` array format for the WhatsApp Cloud API.
+ *
+ * @param config - The typed template configuration.
+ * @returns A {@link TemplateMessage} ready to send via the API.
+ *
+ * @example
+ * ```ts
+ * const payload = buildTemplateSendPayload({
+ *   name: 'hello_world',
+ *   language: 'en_US',
+ *   header: { type: 'text', text: 'Welcome!' },
+ *   body: [
+ *     { type: 'text', text: 'John Doe' },
+ *   ],
+ *   buttons: [
+ *     { type: 'button', subType: 'url', index: 0, parameters: [{ type: 'text', text: '/track/123' }] },
+ *   ],
+ * });
+ * ```
+ */
+export declare function buildTemplateSendPayload(config: TypedTemplateConfig): TemplateMessage;
+/**
+ * Raw template components configuration.
+ *
+ * A minimal wrapper around Meta's native `components` format for cases
+ * where the caller wants full control over the payload structure.
+ */
+export interface RawTemplateComponents {
+    /** Template name. */
+    name: string;
+    /** Language specification. */
+    language: {
+        code: string;
+        policy?: string;
+    };
+    /** Raw components array in Meta's format. */
+    components: TemplateComponent[];
+}
+/**
+ * Build a template message payload from raw components.
+ *
+ * This is a passthrough builder that accepts Meta's native format directly,
+ * performing only minimal validation. Use this when you need full control
+ * over the payload or when the typed builder does not cover a specific case.
+ *
+ * @param config - The raw template configuration.
+ * @returns A {@link TemplateMessage} ready to send via the API.
+ *
+ * @example
+ * ```ts
+ * const payload = buildTemplatePayload({
+ *   name: 'custom_template',
+ *   language: { code: 'en' },
+ *   components: [
+ *     { type: 'body', parameters: [{ type: 'text', text: 'Hello' }] },
+ *   ],
+ * });
+ * ```
+ */
+export declare function buildTemplatePayload(config: RawTemplateComponents): TemplateMessage;
+//# sourceMappingURL=templates.d.ts.map

package/dist/whatsapp/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/whatsapp/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACZ,MAAM,YAAY,CAAC;AAMpB;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,MAAM,CAAC,EACH;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC9B;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,WAAW,CAAA;KAAE,GACrC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,WAAW,CAAA;KAAE,GACrC;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,CAAC;IAChD,qEAAqE;IACrE,IAAI,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,0BAA0B;QAC1B,IAAI,EAAE,QAAQ,CAAC;QACf,uDAAuD;QACvD,OAAO,EAAE,MAAM,CAAC;QAChB,+BAA+B;QAC/B,KAAK,EAAE,MAAM,CAAC;QACd,kCAAkC;QAClC,UAAU,EAAE,iBAAiB,EAAE,CAAC;KACjC,CAAC,CAAC;CACJ;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,mBAAmB,GAAG,eAAe,CAqDrF;AAMD;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,6CAA6C;IAC7C,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAMnF"}

package/dist/whatsapp/templates.js

@@ -0,0 +1,125 @@
+/**
+ * @module whatsapp/templates
+ *
+ * Builder utilities for constructing WhatsApp template message payloads.
+ *
+ * Provides both a **typed builder** (structured config with type-safe
+ * header/body/button definitions) and a **raw builder** (passthrough with
+ * minimal normalization) for maximum flexibility.
+ *
+ * @example
+ * ```ts
+ * // Typed builder
+ * const payload = buildTemplateSendPayload({
+ *   name: 'order_confirmation',
+ *   language: 'en_US',
+ *   body: [
+ *     { type: 'text', text: 'John' },
+ *     { type: 'text', text: 'ORD-12345' },
+ *   ],
+ * });
+ *
+ * await client.sendTemplate(to, payload);
+ * ```
+ */
+/**
+ * Build a template message payload from a typed configuration.
+ *
+ * Converts the structured {@link TypedTemplateConfig} into Meta's
+ * `components` array format for the WhatsApp Cloud API.
+ *
+ * @param config - The typed template configuration.
+ * @returns A {@link TemplateMessage} ready to send via the API.
+ *
+ * @example
+ * ```ts
+ * const payload = buildTemplateSendPayload({
+ *   name: 'hello_world',
+ *   language: 'en_US',
+ *   header: { type: 'text', text: 'Welcome!' },
+ *   body: [
+ *     { type: 'text', text: 'John Doe' },
+ *   ],
+ *   buttons: [
+ *     { type: 'button', subType: 'url', index: 0, parameters: [{ type: 'text', text: '/track/123' }] },
+ *   ],
+ * });
+ * ```
+ */
+export function buildTemplateSendPayload(config) {
+    const components = [];
+    // Header component
+    if (config.header) {
+        const headerComponent = {
+            type: 'header',
+            parameters: [],
+        };
+        switch (config.header.type) {
+            case 'text':
+                headerComponent.parameters = [{ type: 'text', text: config.header.text }];
+                break;
+            case 'image':
+                headerComponent.parameters = [{ type: 'image', image: config.header.image }];
+                break;
+            case 'video':
+                headerComponent.parameters = [{ type: 'video', video: config.header.video }];
+                break;
+            case 'document':
+                headerComponent.parameters = [{ type: 'document', document: config.header.document }];
+                break;
+        }
+        components.push(headerComponent);
+    }
+    // Body component
+    if (config.body && config.body.length > 0) {
+        components.push({
+            type: 'body',
+            parameters: config.body,
+        });
+    }
+    // Button components
+    if (config.buttons) {
+        for (const button of config.buttons) {
+            components.push({
+                type: 'button',
+                sub_type: button.subType,
+                index: button.index,
+                parameters: button.parameters,
+            });
+        }
+    }
+    return {
+        name: config.name,
+        language: { code: config.language },
+        components: components.length > 0 ? components : undefined,
+    };
+}
+/**
+ * Build a template message payload from raw components.
+ *
+ * This is a passthrough builder that accepts Meta's native format directly,
+ * performing only minimal validation. Use this when you need full control
+ * over the payload or when the typed builder does not cover a specific case.
+ *
+ * @param config - The raw template configuration.
+ * @returns A {@link TemplateMessage} ready to send via the API.
+ *
+ * @example
+ * ```ts
+ * const payload = buildTemplatePayload({
+ *   name: 'custom_template',
+ *   language: { code: 'en' },
+ *   components: [
+ *     { type: 'body', parameters: [{ type: 'text', text: 'Hello' }] },
+ *   ],
+ * });
+ * ```
+ */
+export function buildTemplatePayload(config) {
+    return {
+        name: config.name,
+        language: config.language,
+        components: config.components,
+    };
+}
+//# sourceMappingURL=templates.js.map

package/dist/whatsapp/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/whatsapp/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA6CH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAA2B;IAClE,MAAM,UAAU,GAAwB,EAAE,CAAC;IAE3C,mBAAmB;IACnB,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,eAAe,GAAsB;YACzC,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE;SACf,CAAC;QAEF,QAAQ,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YAC3B,KAAK,MAAM;gBACT,eAAe,CAAC,UAAU,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC1E,MAAM;YACR,KAAK,OAAO;gBACV,eAAe,CAAC,UAAU,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;gBAC7E,MAAM;YACR,KAAK,OAAO;gBACV,eAAe,CAAC,UAAU,GAAG,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;gBAC7E,MAAM;YACR,KAAK,UAAU;gBACb,eAAe,CAAC,UAAU,GAAG,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACtF,MAAM;QACV,CAAC;QAED,UAAU,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACnC,CAAC;IAED,iBAAiB;IACjB,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,MAAM;YACZ,UAAU,EAAE,MAAM,CAAC,IAAI;SACxB,CAAC,CAAC;IACL,CAAC;IAED,oBAAoB;IACpB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACpC,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,MAAM,CAAC,OAAO;gBACxB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,UAAU,EAAE,MAAM,CAAC,UAAU;aAC9B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE;QACnC,UAAU,EAAE,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;KAC3D,CAAC;AACJ,CAAC;AAqBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAA6B;IAChE,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,MAAM,CAAC,UAAU;KAC9B,CAAC;AACJ,CAAC"}