@ganju/utils 0.0.18 → 0.0.21

package/dist/whatsappTemplates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsappTemplates.d.ts","sourceRoot":"","sources":["../src/whatsappTemplates.ts"],"names":[],"mappings":"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"}

package/dist/whatsappTemplates.js

@@ -0,0 +1,402 @@
+"use strict";
+// WhatsApp message templates: the shape Meta's Graph API takes and returns,
+// and the rules it rejects templates for most often, checked before one is
+// sent for review. Imports nothing, so the dashboard runs the same checks.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.whatsappSendError = exports.cleanWhatsappTemplateParam = exports.fillWhatsappTemplate = exports.whatsappTemplateSendable = exports.whatsappTemplateContent = exports.whatsappTemplateComponents = exports.whatsappTemplateIssueText = exports.checkWhatsappTemplate = exports.whatsappTemplateVariableCount = exports.whatsappTemplateVariables = exports.WHATSAPP_TEMPLATE_LANGUAGES = exports.WHATSAPP_TEMPLATE_EXAMPLE_MAX = exports.WHATSAPP_TEMPLATE_LABEL_MAX = exports.WHATSAPP_TEMPLATE_VARIABLES_MAX = exports.WHATSAPP_TEMPLATE_BUTTONS_MAX = exports.WHATSAPP_TEMPLATE_BUTTON_MAX = exports.WHATSAPP_TEMPLATE_FOOTER_MAX = exports.WHATSAPP_TEMPLATE_HEADER_MAX = exports.WHATSAPP_TEMPLATE_BODY_MAX = exports.WHATSAPP_TEMPLATE_NAME_MAX = exports.WHATSAPP_TEMPLATE_STATUSES_STOPPED = exports.WHATSAPP_TEMPLATE_STATUSES_WAITING = exports.WHATSAPP_TEMPLATE_STATUS_APPROVED = exports.WHATSAPP_TEMPLATE_CATEGORIES = void 0;
+exports.WHATSAPP_TEMPLATE_CATEGORIES = ['UTILITY', 'MARKETING'];
+// What Meta reports. Only APPROVED templates can be sent.
+exports.WHATSAPP_TEMPLATE_STATUS_APPROVED = 'APPROVED';
+// Still in Meta's hands: the hourly sync looks at these again.
+exports.WHATSAPP_TEMPLATE_STATUSES_WAITING = [
+    'PENDING',
+    'IN_APPEAL',
+    'PENDING_DELETION'
+];
+// An approved template Meta stopped: its owners are told.
+exports.WHATSAPP_TEMPLATE_STATUSES_STOPPED = ['PAUSED', 'DISABLED'];
+exports.WHATSAPP_TEMPLATE_NAME_MAX = 512;
+exports.WHATSAPP_TEMPLATE_BODY_MAX = 1024;
+exports.WHATSAPP_TEMPLATE_HEADER_MAX = 60;
+exports.WHATSAPP_TEMPLATE_FOOTER_MAX = 60;
+exports.WHATSAPP_TEMPLATE_BUTTON_MAX = 25;
+exports.WHATSAPP_TEMPLATE_BUTTONS_MAX = 10;
+exports.WHATSAPP_TEMPLATE_VARIABLES_MAX = 20;
+exports.WHATSAPP_TEMPLATE_LABEL_MAX = 40;
+exports.WHATSAPP_TEMPLATE_EXAMPLE_MAX = 200;
+const NAME_PATTERN = /^[a-z0-9_]+$/;
+// Meta's template languages. The first ones are the ones most owners use.
+exports.WHATSAPP_TEMPLATE_LANGUAGES = [
+    { code: 'es', name: 'Spanish' },
+    { code: 'es_MX', name: 'Spanish (Mexico)' },
+    { code: 'es_AR', name: 'Spanish (Argentina)' },
+    { code: 'es_ES', name: 'Spanish (Spain)' },
+    { code: 'en', name: 'English' },
+    { code: 'en_US', name: 'English (US)' },
+    { code: 'en_GB', name: 'English (UK)' },
+    { code: 'pt_BR', name: 'Portuguese (Brazil)' },
+    { code: 'pt_PT', name: 'Portuguese (Portugal)' },
+    { code: 'af', name: 'Afrikaans' },
+    { code: 'sq', name: 'Albanian' },
+    { code: 'ar', name: 'Arabic' },
+    { code: 'az', name: 'Azerbaijani' },
+    { code: 'bn', name: 'Bengali' },
+    { code: 'bg', name: 'Bulgarian' },
+    { code: 'ca', name: 'Catalan' },
+    { code: 'zh_CN', name: 'Chinese (China)' },
+    { code: 'zh_HK', name: 'Chinese (Hong Kong)' },
+    { code: 'zh_TW', name: 'Chinese (Taiwan)' },
+    { code: 'hr', name: 'Croatian' },
+    { code: 'cs', name: 'Czech' },
+    { code: 'da', name: 'Danish' },
+    { code: 'nl', name: 'Dutch' },
+    { code: 'et', name: 'Estonian' },
+    { code: 'fil', name: 'Filipino' },
+    { code: 'fi', name: 'Finnish' },
+    { code: 'fr', name: 'French' },
+    { code: 'ka', name: 'Georgian' },
+    { code: 'de', name: 'German' },
+    { code: 'el', name: 'Greek' },
+    { code: 'gu', name: 'Gujarati' },
+    { code: 'ha', name: 'Hausa' },
+    { code: 'he', name: 'Hebrew' },
+    { code: 'hi', name: 'Hindi' },
+    { code: 'hu', name: 'Hungarian' },
+    { code: 'id', name: 'Indonesian' },
+    { code: 'ga', name: 'Irish' },
+    { code: 'it', name: 'Italian' },
+    { code: 'ja', name: 'Japanese' },
+    { code: 'kn', name: 'Kannada' },
+    { code: 'kk', name: 'Kazakh' },
+    { code: 'rw_RW', name: 'Kinyarwanda' },
+    { code: 'ko', name: 'Korean' },
+    { code: 'ky_KG', name: 'Kyrgyz' },
+    { code: 'lo', name: 'Lao' },
+    { code: 'lv', name: 'Latvian' },
+    { code: 'lt', name: 'Lithuanian' },
+    { code: 'mk', name: 'Macedonian' },
+    { code: 'ms', name: 'Malay' },
+    { code: 'ml', name: 'Malayalam' },
+    { code: 'mr', name: 'Marathi' },
+    { code: 'nb', name: 'Norwegian' },
+    { code: 'fa', name: 'Persian' },
+    { code: 'pl', name: 'Polish' },
+    { code: 'pa', name: 'Punjabi' },
+    { code: 'ro', name: 'Romanian' },
+    { code: 'ru', name: 'Russian' },
+    { code: 'sr', name: 'Serbian' },
+    { code: 'sk', name: 'Slovak' },
+    { code: 'sl', name: 'Slovenian' },
+    { code: 'sw', name: 'Swahili' },
+    { code: 'sv', name: 'Swedish' },
+    { code: 'ta', name: 'Tamil' },
+    { code: 'te', name: 'Telugu' },
+    { code: 'th', name: 'Thai' },
+    { code: 'tr', name: 'Turkish' },
+    { code: 'uk', name: 'Ukrainian' },
+    { code: 'ur', name: 'Urdu' },
+    { code: 'uz', name: 'Uzbek' },
+    { code: 'vi', name: 'Vietnamese' },
+    { code: 'zu', name: 'Zulu' }
+];
+const VARIABLE = /\{\{\s*(\d+)\s*\}\}/g;
+/** Each {{n}} in the text, in the order they appear. */
+const whatsappTemplateVariables = (text) => Array.from(text.matchAll(VARIABLE), match => Number(match[1]));
+exports.whatsappTemplateVariables = whatsappTemplateVariables;
+/** How many variables the body has: its highest {{n}}. */
+const whatsappTemplateVariableCount = (body) => Math.max(0, ...(0, exports.whatsappTemplateVariables)(body));
+exports.whatsappTemplateVariableCount = whatsappTemplateVariableCount;
+const words = (text) => text
+    .replace(VARIABLE, ' ')
+    .split(/\s+/)
+    .filter(word => /[\p{L}\p{N}]/u.test(word)).length;
+/**
+ * The rules Meta rejects templates for most often, checked before sending
+ * one for review. Meta's review has the last word; this only catches the
+ * common mistakes early.
+ */
+const checkWhatsappTemplate = (draft) => {
+    const issues = [];
+    const add = (code, n) => issues.push(n === undefined ? { code } : { code, n });
+    if (!NAME_PATTERN.test(draft.name))
+        add('name_format');
+    if (draft.name.length > exports.WHATSAPP_TEMPLATE_NAME_MAX)
+        add('name_long');
+    if (!exports.WHATSAPP_TEMPLATE_LANGUAGES.some(l => l.code === draft.language)) {
+        add('language');
+    }
+    if (!exports.WHATSAPP_TEMPLATE_CATEGORIES.includes(draft.category))
+        add('category');
+    const header = draft.header?.trim() ?? '';
+    if (header.length > exports.WHATSAPP_TEMPLATE_HEADER_MAX)
+        add('header_long');
+    if ((0, exports.whatsappTemplateVariables)(header).length > 0)
+        add('header_variables');
+    if (/[\n\r]/.test(header))
+        add('header_lines');
+    const footer = draft.footer?.trim() ?? '';
+    if (footer.length > exports.WHATSAPP_TEMPLATE_FOOTER_MAX)
+        add('footer_long');
+    if ((0, exports.whatsappTemplateVariables)(footer).length > 0)
+        add('footer_variables');
+    const buttons = draft.buttons ?? [];
+    if (buttons.length > exports.WHATSAPP_TEMPLATE_BUTTONS_MAX)
+        add('buttons_many');
+    if (buttons.some(button => !button.trim()))
+        add('button_empty');
+    if (buttons.some(button => button.trim().length > exports.WHATSAPP_TEMPLATE_BUTTON_MAX)) {
+        add('button_long');
+    }
+    if (buttons.some(button => (0, exports.whatsappTemplateVariables)(button).length > 0)) {
+        add('button_variables');
+    }
+    const unique = new Set(buttons.map(button => button.trim().toLowerCase()));
+    if (unique.size < buttons.length)
+        add('buttons_repeated');
+    const body = draft.body.trim();
+    if (!body) {
+        add('body_empty');
+        return issues;
+    }
+    if (body.length > exports.WHATSAPP_TEMPLATE_BODY_MAX)
+        add('body_long');
+    const found = (0, exports.whatsappTemplateVariables)(body);
+    if (found.length === 0)
+        return issues;
+    const count = Math.max(...found);
+    if (count > exports.WHATSAPP_TEMPLATE_VARIABLES_MAX)
+        add('variables_many');
+    // {{1}}, {{2}}, … with no gaps, each first used after the one before.
+    const firsts = [...new Set(found)];
+    if (firsts.some((n, i) => n !== i + 1))
+        add('variables_order');
+    if (/^\{\{\s*\d+\s*\}\}/.test(body))
+        add('variable_at_start');
+    if (/\{\{\s*\d+\s*\}\}[\s.!?…]*$/.test(body))
+        add('variable_at_end');
+    if (/\}\}\s*\{\{/.test(body))
+        add('variables_adjacent');
+    // Meta wants more words than variables; this is about the ratio it accepts.
+    if (words(body) < 2 * firsts.length + 1)
+        add('variables_dense');
+    const examples = draft.examples ?? [];
+    for (let n = 1; n <= count; n++) {
+        if (!examples[n - 1]?.trim())
+            add('example_missing', n);
+    }
+    return issues;
+};
+exports.checkWhatsappTemplate = checkWhatsappTemplate;
+const ISSUE_TEXT = {
+    name_format: 'The name takes lowercase letters, digits and underscores only.',
+    name_long: `The name is at most ${exports.WHATSAPP_TEMPLATE_NAME_MAX} characters.`,
+    language: "The language isn't one Meta supports.",
+    category: 'The category is Utility or Marketing.',
+    body_empty: 'The message needs a body.',
+    body_long: `The body is at most ${exports.WHATSAPP_TEMPLATE_BODY_MAX} characters.`,
+    header_long: `The header is at most ${exports.WHATSAPP_TEMPLATE_HEADER_MAX} characters.`,
+    header_variables: "The header can't have variables.",
+    header_lines: 'The header is one line.',
+    footer_long: `The footer is at most ${exports.WHATSAPP_TEMPLATE_FOOTER_MAX} characters.`,
+    footer_variables: "The footer can't have variables.",
+    button_empty: 'A quick reply needs a text.',
+    button_long: `A quick reply is at most ${exports.WHATSAPP_TEMPLATE_BUTTON_MAX} characters.`,
+    button_variables: "A quick reply can't have variables.",
+    buttons_many: `At most ${exports.WHATSAPP_TEMPLATE_BUTTONS_MAX} quick replies.`,
+    buttons_repeated: 'Two quick replies say the same.',
+    variables_many: `At most ${exports.WHATSAPP_TEMPLATE_VARIABLES_MAX} variables.`,
+    variables_order: 'Variables are numbered {{1}}, {{2}}, … in the order they first appear, with no gaps.',
+    variable_at_start: 'Meta rejects a body that starts with a variable.',
+    variable_at_end: 'Meta rejects a body that ends with a variable.',
+    variables_adjacent: 'Meta rejects two variables side by side; put words between them.',
+    variables_dense: 'Too many variables for the length of the text; add words or remove variables.',
+    example_missing: 'Each variable needs an example value for Meta to review.'
+};
+const whatsappTemplateIssueText = (issue) => issue.n === undefined
+    ? ISSUE_TEXT[issue.code]
+    : `{{${issue.n}}}: ${ISSUE_TEXT[issue.code]}`;
+exports.whatsappTemplateIssueText = whatsappTemplateIssueText;
+/** The components Meta's create and edit calls take. */
+const whatsappTemplateComponents = (draft) => {
+    const components = [];
+    const header = draft.header?.trim();
+    if (header)
+        components.push({ type: 'HEADER', format: 'TEXT', text: header });
+    const body = draft.body.trim();
+    const count = (0, exports.whatsappTemplateVariableCount)(body);
+    components.push({
+        type: 'BODY',
+        text: body,
+        ...(count > 0
+            ? {
+                example: {
+                    body_text: [
+                        Array.from({ length: count }, (_, i) => (draft.examples?.[i] ?? '').trim())
+                    ]
+                }
+            }
+            : {})
+    });
+    const footer = draft.footer?.trim();
+    if (footer)
+        components.push({ type: 'FOOTER', text: footer });
+    const buttons = (draft.buttons ?? []).map(b => b.trim()).filter(Boolean);
+    if (buttons.length > 0) {
+        components.push({
+            type: 'BUTTONS',
+            buttons: buttons.map(text => ({ type: 'QUICK_REPLY', text }))
+        });
+    }
+    return components;
+};
+exports.whatsappTemplateComponents = whatsappTemplateComponents;
+/** A template's text, from the components Meta returns. */
+const whatsappTemplateContent = (components) => {
+    const content = {
+        header: null,
+        body: '',
+        footer: null,
+        buttons: [],
+        examples: []
+    };
+    if (!Array.isArray(components))
+        return content;
+    for (const component of components) {
+        const type = String(component?.type ?? '').toUpperCase();
+        const text = typeof component?.text === 'string' ? component.text : null;
+        if (type === 'HEADER' && component.format === 'TEXT')
+            content.header = text;
+        if (type === 'BODY') {
+            content.body = text ?? '';
+            const example = component.example;
+            const first = example?.body_text?.[0];
+            if (Array.isArray(first))
+                content.examples = first.map(v => String(v));
+        }
+        if (type === 'FOOTER')
+            content.footer = text;
+        if (type === 'BUTTONS' && Array.isArray(component.buttons)) {
+            content.buttons = component.buttons
+                .filter(b => b?.type === 'QUICK_REPLY' && typeof b.text === 'string')
+                .map(b => b.text);
+        }
+    }
+    return content;
+};
+exports.whatsappTemplateContent = whatsappTemplateContent;
+/**
+ * Whether Ganju can send it: it fills the body's variables only. A media
+ * header, a header variable, or a button that takes a value (a URL with a
+ * variable, a code, a flow) needs more, and Meta refuses the send.
+ */
+const whatsappTemplateSendable = (components) => {
+    if (!Array.isArray(components))
+        return false;
+    return components.every(component => {
+        const type = String(component?.type ?? '').toUpperCase();
+        if (type === 'BODY' || type === 'FOOTER')
+            return true;
+        if (type === 'HEADER') {
+            return (component.format === 'TEXT' &&
+                (0, exports.whatsappTemplateVariables)(String(component.text ?? '')).length === 0);
+        }
+        if (type === 'BUTTONS') {
+            const buttons = Array.isArray(component.buttons)
+                ? component.buttons
+                : [];
+            return buttons.every(button => {
+                const kind = String(button?.type ?? '').toUpperCase();
+                if (kind === 'QUICK_REPLY' || kind === 'PHONE_NUMBER')
+                    return true;
+                if (kind === 'URL') {
+                    return ((0, exports.whatsappTemplateVariables)(String(button.url ?? '')).length === 0);
+                }
+                return false;
+            });
+        }
+        return false;
+    });
+};
+exports.whatsappTemplateSendable = whatsappTemplateSendable;
+/** The body with each {{n}} replaced, for previews and the message record. */
+const fillWhatsappTemplate = (body, values) => body.replace(VARIABLE, (whole, n) => values[Number(n) - 1] ?? whole);
+exports.fillWhatsappTemplate = fillWhatsappTemplate;
+/**
+ * A value for a {{n}} as Meta accepts it: no line breaks or tabs, no long
+ * runs of spaces, and never empty.
+ */
+const cleanWhatsappTemplateParam = (value) => {
+    const text = String(value ?? '')
+        .replace(/[\r\n\t]+/g, ' ')
+        .replace(/ {2,}/g, ' ')
+        .trim()
+        .slice(0, 1024);
+    return text || '-';
+};
+exports.cleanWhatsappTemplateParam = cleanWhatsappTemplateParam;
+// Meta's error codes for a message that didn't go out, in words an owner can
+// act on. `retry`: the same message may go through later.
+const SEND_ERRORS = {
+    1: { text: 'WhatsApp had a temporary problem.', retry: true },
+    2: { text: 'WhatsApp had a temporary problem.', retry: true },
+    10: { text: "The channel's access token isn't allowed to send messages." },
+    190: {
+        text: "The channel's access token expired or was revoked; connect a new one in the channel's settings."
+    },
+    200: { text: "The channel's access token isn't allowed to send messages." },
+    368: {
+        text: 'Meta has temporarily blocked this WhatsApp Business account for policy violations.'
+    },
+    130429: {
+        text: "The number's sending rate was reached; it will be tried again.",
+        retry: true
+    },
+    131000: { text: 'WhatsApp had a temporary problem.', retry: true },
+    131016: { text: 'WhatsApp is temporarily unavailable.', retry: true },
+    131026: {
+        text: "WhatsApp couldn't deliver it: the customer may have blocked the business, left WhatsApp, or not accepted its latest terms."
+    },
+    131031: { text: 'Meta locked this WhatsApp Business account.' },
+    131042: {
+        text: "Meta refused it over a payment problem on the WhatsApp Business account; check its payment method in Meta's Business settings."
+    },
+    131047: {
+        text: "Outside WhatsApp's 24-hour window: the customer last wrote more than 24 hours ago, so only an approved template reaches them."
+    },
+    131048: {
+        text: "Meta limited this number's sending because of its quality: too many customers blocked or reported its messages."
+    },
+    131049: {
+        text: 'Meta chose not to deliver this marketing message, to limit how many each customer gets.'
+    },
+    131050: {
+        text: 'The customer turned off marketing messages from this business.'
+    },
+    131056: {
+        text: 'Too many messages to this customer in a short time; it will be tried again.',
+        retry: true
+    },
+    132000: {
+        text: "The number of values doesn't match the template's variables."
+    },
+    132001: {
+        text: 'Meta has no approved template with that name in that language.'
+    },
+    132005: { text: "The template's text is too long with the values put in." },
+    132007: { text: "The template's text breaks WhatsApp's commerce policy." },
+    132012: { text: "A value doesn't match what the template expects." },
+    132015: { text: 'Meta paused this template because of its quality.' },
+    132016: { text: 'Meta disabled this template because of its quality.' },
+    132018: { text: 'A value has line breaks, tabs or too many spaces.' }
+};
+/** A Meta send error as an owner reads it, and whether a retry may help. */
+const whatsappSendError = (code, detail) => {
+    const known = code !== undefined ? SEND_ERRORS[code] : undefined;
+    if (known)
+        return { text: known.text, retry: !!known.retry };
+    return {
+        text: detail ? detail.slice(0, 300) : 'WhatsApp refused the message.',
+        retry: true
+    };
+};
+exports.whatsappSendError = whatsappSendError;

package/dist/whatsappWebhook.d.ts

@@ -0,0 +1,28 @@
+export interface WhatsappWebhookChange<V> {
+    field?: string;
+    value?: V;
+}
+export interface WhatsappWebhookEnvelope<V> {
+    entry?: Array<{
+        id?: string;
+        changes?: Array<WhatsappWebhookChange<V>>;
+    }>;
+}
+export interface WhatsappAddressedValue {
+    metadata?: {
+        phone_number_id?: string;
+    };
+    messages?: unknown[];
+}
+/**
+ * The change carrying a message for this channel's number, wherever Meta put
+ * it in the batch. A change that doesn't say which number it's for is kept.
+ */
+export declare const whatsappMessageChange: <V extends WhatsappAddressedValue>(payload: WhatsappWebhookEnvelope<V>, phoneNumberId: string) => V | undefined;
+/**
+ * The changes with one of `fields` from this channel's business account. An
+ * entry without an id, or a channel that hasn't saved its account, keeps
+ * them: template events only touch the channel's own stored templates.
+ */
+export declare const whatsappAccountChanges: <V>(payload: WhatsappWebhookEnvelope<V>, businessAccountId: string | undefined, fields: readonly string[]) => WhatsappWebhookChange<V>[];
+//# sourceMappingURL=whatsappWebhook.d.ts.map

package/dist/whatsappWebhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whatsappWebhook.d.ts","sourceRoot":"","sources":["../src/whatsappWebhook.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,CAAC,CAAC;CACX;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,KAAK,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAA;KAAE,CAAC,CAAC;CAC3E;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,CAAC,SAAS,sBAAsB,EACpE,SAAS,uBAAuB,CAAC,CAAC,CAAC,EACnC,eAAe,MAAM,KACpB,CAAC,GAAG,SAQM,CAAC;AAEd;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,CAAC,EACtC,SAAS,uBAAuB,CAAC,CAAC,CAAC,EACnC,mBAAmB,MAAM,GAAG,SAAS,EACrC,QAAQ,SAAS,MAAM,EAAE,KACxB,qBAAqB,CAAC,CAAC,CAAC,EAStB,CAAC"}

package/dist/whatsappWebhook.js

@@ -0,0 +1,30 @@
+"use strict";
+// What one WhatsApp channel takes from a webhook. A Meta app sends every
+// number's events to each of its callbacks, signed with the same app secret,
+// so a channel keeps only what was addressed to its own number and business
+// account; otherwise another channel's bot answers its messages.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.whatsappAccountChanges = exports.whatsappMessageChange = void 0;
+/**
+ * The change carrying a message for this channel's number, wherever Meta put
+ * it in the batch. A change that doesn't say which number it's for is kept.
+ */
+const whatsappMessageChange = (payload, phoneNumberId) => (payload.entry ?? [])
+    .flatMap(entry => entry.changes ?? [])
+    .find(change => {
+    const value = change.value;
+    if (!value?.messages?.length)
+        return false;
+    const to = value.metadata?.phone_number_id;
+    return !to || to === phoneNumberId;
+})?.value;
+exports.whatsappMessageChange = whatsappMessageChange;
+/**
+ * The changes with one of `fields` from this channel's business account. An
+ * entry without an id, or a channel that hasn't saved its account, keeps
+ * them: template events only touch the channel's own stored templates.
+ */
+const whatsappAccountChanges = (payload, businessAccountId, fields) => (payload.entry ?? [])
+    .filter(entry => !entry.id || !businessAccountId || entry.id === businessAccountId)
+    .flatMap(entry => (entry.changes ?? []).filter(change => !!change.field && fields.includes(change.field)));
+exports.whatsappAccountChanges = whatsappAccountChanges;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ganju/utils",
-  "version": "0.0.18",
+  "version": "0.0.21",
   "description": "Shared constants, schemas and helpers for Ganju",
   "license": "Apache-2.0",
   "author": "MontoyaAndres <andresmontoyafcb@gmail.com>",

package/src/constants.ts

@@ -25,6 +25,7 @@ import {
   CUSTOM_CODE_BROKER_PATH_DATA,
   CUSTOM_CODE_BROKER_PATH_CHANNELS_SEND,
   CUSTOM_CODE_BROKER_PATH_CHANNELS_POST,
+  CUSTOM_CODE_BROKER_PATH_CHANNELS_TEMPLATES,
   CUSTOM_CODE_HEALTH_TOOL,
   CUSTOM_CODE_MAX_LOGS,
   CUSTOM_CODE_MAX_LOG_LENGTH
@@ -2196,6 +2197,36 @@ const DATA_PURGE_BATCH = 20;
 // Postgres write per query.
 const DATA_ACTIVITY_THROTTLE_MS = 60 * 60 * 1000;
 
+// Index advice. A column is worth an index when, over a week, at least 50
+// queries filtered or sorted on it and they read on average 1,000 rows and
+// 20 rows for every row returned. An index no query used in 30 days on a
+// table written at least 1,000 rows (and more rows written than queries) is
+// flagged as unused. Never dropped automatically.
+const DATA_INDEX_ADVICE_WINDOW_DAYS = 7;
+const DATA_INDEX_ADVICE_MIN_QUERIES = 50;
+const DATA_INDEX_ADVICE_MIN_ROWS_READ = 1_000;
+const DATA_INDEX_ADVICE_MIN_READ_RATIO = 20;
+const DATA_INDEX_UNUSED_WINDOW_DAYS = 30;
+const DATA_INDEX_UNUSED_MIN_ROWS_WRITTEN = 1_000;
+// Daily stats are kept past the longest window, then removed.
+const DATA_QUERY_STAT_KEEP_DAYS = 35;
+const DATA_INDEX_ADVICE_ADD = 'add' as 'add';
+const DATA_INDEX_ADVICE_UNUSED = 'unused' as 'unused';
+const DATA_INDEX_ADVICE_OPEN = 'open' as 'open';
+const DATA_INDEX_ADVICE_DISMISSED = 'dismissed' as 'dismissed';
+
+// The daily jobs (index advice and the abandoned-database flow) run on the
+// hourly cron at this UTC hour.
+const DATA_DAILY_JOB_HOUR_UTC = 13;
+
+// Days on Free before a database is warned about, reminded about, and listed
+// for Ganju to delete by hand.
+const DATA_ABANDON_WARN_DAYS = 30;
+const DATA_ABANDON_REMIND_DAYS = 41;
+const DATA_ABANDON_DELETE_DAYS = 44;
+// How long the export taken before a database is deleted is kept.
+const DATA_ABANDON_EXPORT_KEEP_DAYS = 90;
+
 interface PlanLimits {
   // null on any field means "no hard limit" for that plan.
   maxProjects: number | null;
@@ -2271,6 +2302,9 @@ interface PlanLimits {
   maxDataTablesPerDatabase: number | null;
   // Abuse backstop on data trigger runs a month. `null` = no backstop.
   triggerRunHardCap: number | null;
+  // Email trigger runs a day per organization, each to at most 10 addresses.
+  // They go out from Ganju's own domain. `null` = no cap.
+  dailyTriggerEmailCap: number | null;
 }
 
 const PLAN_LIMITS: Record<
@@ -2315,7 +2349,8 @@ const PLAN_LIMITS: Record<
     canUseData: false,
     maxDataBytes: null,
     maxDataTablesPerDatabase: null,
-    triggerRunHardCap: 0
+    triggerRunHardCap: 0,
+    dailyTriggerEmailCap: 0
   },
   PRO: {
     maxProjects: null,
@@ -2346,7 +2381,8 @@ const PLAN_LIMITS: Record<
     canUseData: true,
     maxDataBytes: DATA_MAX_DATABASE_BYTES,
     maxDataTablesPerDatabase: DATA_MAX_TABLES_PER_DATABASE,
-    triggerRunHardCap: DATA_TRIGGER_RUN_HARD_CAP
+    triggerRunHardCap: DATA_TRIGGER_RUN_HARD_CAP,
+    dailyTriggerEmailCap: 500
   },
   ENTERPRISE: {
     maxProjects: null,
@@ -2377,7 +2413,8 @@ const PLAN_LIMITS: Record<
     canUseData: true,
     maxDataBytes: DATA_MAX_DATABASE_BYTES,
     maxDataTablesPerDatabase: DATA_MAX_TABLES_PER_DATABASE,
-    triggerRunHardCap: null
+    triggerRunHardCap: null,
+    dailyTriggerEmailCap: 5000
   }
 };
 
@@ -2581,6 +2618,22 @@ export const constants = {
   DATA_DELETE_GRACE_DAYS,
   DATA_PURGE_BATCH,
   DATA_ACTIVITY_THROTTLE_MS,
+  DATA_INDEX_ADVICE_WINDOW_DAYS,
+  DATA_INDEX_ADVICE_MIN_QUERIES,
+  DATA_INDEX_ADVICE_MIN_ROWS_READ,
+  DATA_INDEX_ADVICE_MIN_READ_RATIO,
+  DATA_INDEX_UNUSED_WINDOW_DAYS,
+  DATA_INDEX_UNUSED_MIN_ROWS_WRITTEN,
+  DATA_QUERY_STAT_KEEP_DAYS,
+  DATA_INDEX_ADVICE_ADD,
+  DATA_INDEX_ADVICE_UNUSED,
+  DATA_INDEX_ADVICE_OPEN,
+  DATA_INDEX_ADVICE_DISMISSED,
+  DATA_DAILY_JOB_HOUR_UTC,
+  DATA_ABANDON_WARN_DAYS,
+  DATA_ABANDON_REMIND_DAYS,
+  DATA_ABANDON_DELETE_DAYS,
+  DATA_ABANDON_EXPORT_KEEP_DAYS,
   ARTIFACT_DATABASE_STATUS_CREATING,
   ARTIFACT_DATABASE_STATUS_READY,
   ARTIFACT_DATABASE_STATUS_FAILED,
@@ -3113,6 +3166,7 @@ export const constants = {
   CUSTOM_CODE_BROKER_PATH_DATA,
   CUSTOM_CODE_BROKER_PATH_CHANNELS_SEND,
   CUSTOM_CODE_BROKER_PATH_CHANNELS_POST,
+  CUSTOM_CODE_BROKER_PATH_CHANNELS_TEMPLATES,
   CUSTOM_CODE_OUTBOUND_PARAM_ARTIFACT_ID,
   CUSTOM_CODE_OUTBOUND_PARAM_ALLOWED_HOSTS,
   CUSTOM_CODE_PLATFORM_HOSTS,

package/src/crypto.ts

@@ -1,6 +1,6 @@
-import { Context } from 'hono';
 import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';
 import { getEnv } from './getEnv';
+import type { EnvSource } from './getEnv';
 import { base64ToBytes, bytesToBase64 } from './base64';
 
 const PREFIX = 'enc:v1:';
@@ -8,7 +8,8 @@ const NONCE_BYTES = 24;
 const KEY_BYTES = 32;
 const KEY_ENV = 'CRYPTO_SECRET';
 
-export const getCredentialEncryptionKey = (c: Context) => {
+// A request's context, or anything with the worker's env (a cron, a queue).
+export const getCredentialEncryptionKey = (c: EnvSource) => {
   const rawKey = getEnv(c, KEY_ENV);
   if (!rawKey) {
     throw new Error(`Missing env: ${KEY_ENV}`);

package/src/data.ts

@@ -26,6 +26,8 @@ export {
   encodeCursor,
   decodeCursor,
   isSensitiveWrite,
+  fileUriOf,
+  unknownFileUris,
   tidyArgs,
   zoned
 } from './dataCompiler';
@@ -47,6 +49,8 @@ export {
   rowHistory,
   pruneHistory,
   deleteImpact,
+  fileLinks,
+  replaceFileLinks,
   createTable,
   updateTable,
   dropTable,
@@ -64,6 +68,12 @@ export {
   exportRows
 } from './dataEngine';
 export type { SqlRow, SqlRunner } from './dataEngine';
+export { adviseIndexes, adviceDoubled } from './dataIndexAdvice';
+export type {
+  IndexAdviceCandidate,
+  IndexAdviceInput,
+  IndexAdviceStat
+} from './dataIndexAdvice';
 export {
   DATA_QUERY_PARAM_TYPES,
   DATA_MAX_QUERIES,
@@ -118,7 +128,10 @@ export {
   utf8Bytes,
   conditionMatches,
   renderTriggerText,
+  renderCustomerMessage,
+  readEventRow,
   normaliseTrigger,
+  normaliseCustomerAction,
   listTriggers,
   getTrigger,
   saveTrigger,
@@ -138,6 +151,7 @@ export type {
   DataTriggerAction,
   DataTriggerActionType,
   DataTriggerCondition,
+  DataTriggerCustomerMessage,
   DataTriggerEvent,
   DataTriggerEventMessage,
   DataTriggerInput,