@rapidmx/crm-plugin 0.1.0

package/dist/lib/templates/Sanitize.js

@@ -0,0 +1,98 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import sanitizeHtml from "sanitize-html";
+/** Merge tags (`{{ contact.first_name }}`) and Liquid tags (`{% if ... %}`) in a piece of HTML or text. */
+const TAGS = /(\{\{[\s\S]*?\}\}|\{%[\s\S]*?%\})/g;
+/** The entities an escaper puts inside a merge tag that Liquid needs back as characters. */
+const ENTITIES = { """: '"', """: '"', "'": "'", "'": "'", "'": "'", "&": "&" };
+/**
+ * `html` with the quote and ampersand entities inside its merge and Liquid tags turned back into characters: `{{ x | default: 'a' }}`
+ * becomes `{{ x | default: 'a' }}`, which Liquid can parse. Nothing outside the tags changes, and `<`/`>` stay escaped everywhere.
+ */
+export function restoreMergeTags(html) {
+    return html.replace(TAGS, (tag) => tag.replace(/&quot;|&#34;|&#39;|&#x27;|&apos;|&amp;/g, (entity) => ENTITIES[entity]));
+}
+/** Escapes text for HTML, except inside merge and Liquid tags (which only lose `<` and `>`, never valid in them). */
+export function escapeKeepingTags(text) {
+    return text
+        .split(TAGS)
+        .map((part, index) => index % 2 === 1
+        ? part.replace(/[<>]/g, "")
+        : part.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;"))
+        .join("");
+}
+/** Keeps a link to the web, mail or a phone, or one that is a merge tag; anything else (`javascript:`, `data:`...) is dropped. */
+function safeHref(href) {
+    const value = (href ?? "").trim();
+    return /^(?:https?:|mailto:|tel:)/i.test(value) || /^\{\{\s*[a-z_][a-z0-9_.]*\s*\}\}/i.test(value);
+}
+/** A link with an unsafe target becomes plain text (a bare `<span>`), keeping what it says. */
+function unlinkUnsafe(tagName, attribs) {
+    return safeHref(attribs.href) ? { tagName, attribs } : { tagName: "span", attribs: {} };
+}
+const TEXT_OPTIONS = {
+    allowedTags: ["p", "br", "strong", "b", "em", "i", "u", "s", "a", "ul", "ol", "li", "span", "blockquote", "h1", "h2", "h3"],
+    allowedAttributes: { a: ["href", "target", "rel"], span: ["style"], p: ["style"] },
+    allowedStyles: {
+        "*": {
+            color: [/^#[0-9a-f]{3,8}$/i, /^rgb\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*\)$/i],
+            "text-align": [/^(?:left|right|center|justify)$/],
+            "font-weight": [/^(?:bold|normal|\d{3})$/],
+        },
+    },
+    // Links are checked by `unlinkUnsafe()`, so merge-tag links (which have no scheme) survive.
+    allowedSchemes: ["http", "https", "mailto", "tel"],
+    allowProtocolRelative: false,
+    transformTags: { a: unlinkUnsafe },
+};
+/**
+ * The formatted text of a text block, made safe: the formatting the editor produces (paragraphs, bold, italics, underline,
+ * strike-through, links, lists, quotes, small headings, colour and alignment) and nothing else - no scripts, no styles beyond
+ * those, and links only to the web, mail, phones or merge tags. Merge tags stay usable (`restoreMergeTags()`).
+ */
+export function sanitizeText(html) {
+    return restoreMergeTags(sanitizeHtml(html, TEXT_OPTIONS));
+}
+const HTML_OPTIONS = {
+    allowedTags: [
+        ...TEXT_OPTIONS.allowedTags,
+        "div",
+        "table",
+        "thead",
+        "tbody",
+        "tfoot",
+        "tr",
+        "td",
+        "th",
+        "img",
+        "hr",
+        "h4",
+        "h5",
+        "h6",
+        "center",
+        "small",
+        "sup",
+        "sub",
+        "code",
+        "pre",
+    ],
+    allowedAttributes: {
+        "*": ["style", "align", "width", "height", "bgcolor", "valign", "border", "cellpadding", "cellspacing", "class", "role"],
+        a: ["href", "target", "rel", "style", "title"],
+        img: ["src", "alt", "width", "height", "style", "title"],
+    },
+    allowedSchemes: ["http", "https", "mailto", "tel"],
+    allowedSchemesByTag: { img: ["https"] },
+    allowProtocolRelative: false,
+    transformTags: { a: unlinkUnsafe },
+};
+/**
+ * A hand-written HTML block's HTML, made safe: layout and formatting HTML (tables, images, inline styles) is kept; scripts, forms,
+ * frames, event handlers and `javascript:` links are removed, and images must be https. Merge tags stay usable.
+ */
+export function sanitizeBlockHtml(html) {
+    return restoreMergeTags(sanitizeHtml(html, HTML_OPTIONS));
+}
+//# sourceMappingURL=Sanitize.js.map

package/dist/lib/templates/Sanitize.js.map

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

package/dist/lib/util/Csv.js

@@ -0,0 +1,128 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/** Thrown for a CSV the parser can't read. */
+export class CsvError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CsvError";
+    }
+}
+/**
+ * Parses RFC 4180 CSV into rows of fields: fields separated by `delimiter` (a comma unless given; `detectDelimiter()` can pick one),
+ * rows by CRLF or LF, a field in double quotes may hold the delimiter, line breaks and `""` for a quote. A leading UTF-8 byte order
+ * mark is dropped, and so are lines that are entirely empty. Throws a `CsvError` for an unterminated quote or when `limits` are
+ * exceeded.
+ */
+export function parseCsv(text, delimiter = ",", limits = {}) {
+    const maxRows = limits.maxRows ?? Infinity;
+    const maxColumns = limits.maxColumns ?? 500;
+    const maxFieldLength = limits.maxFieldLength ?? 100000;
+    const input = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    const rows = [];
+    let row = [];
+    let field = "";
+    let quoted = false;
+    let fieldWasQuoted = false;
+    let i = 0;
+    const endField = () => {
+        if (field.length > maxFieldLength) {
+            throw new CsvError(`Row ${rows.length + 1} has a value longer than ${maxFieldLength} characters.`);
+        }
+        row.push(field);
+        if (row.length > maxColumns) {
+            throw new CsvError(`Row ${rows.length + 1} has more than ${maxColumns} columns.`);
+        }
+        field = "";
+        fieldWasQuoted = false;
+    };
+    const endRow = () => {
+        // A line with one quoted empty value (`""`) is a row; a line with nothing on it isn't.
+        const lastWasQuoted = fieldWasQuoted;
+        endField();
+        if (!(row.length === 1 && row[0] === "" && !lastWasQuoted)) {
+            rows.push(row);
+            if (rows.length > maxRows) {
+                throw new CsvError(`The file has more than ${maxRows} rows.`);
+            }
+        }
+        row = [];
+    };
+    while (i < input.length) {
+        const char = input[i];
+        if (quoted) {
+            if (char === '"') {
+                if (input[i + 1] === '"') {
+                    field += '"';
+                    i += 2;
+                    continue;
+                }
+                quoted = false;
+                i++;
+                continue;
+            }
+            field += char;
+            i++;
+            continue;
+        }
+        if (char === '"' && field.length === 0) {
+            quoted = true;
+            fieldWasQuoted = true;
+            i++;
+        }
+        else if (char === delimiter) {
+            endField();
+            i++;
+        }
+        else if (char === "\r" && input[i + 1] === "\n") {
+            endRow();
+            i += 2;
+        }
+        else if (char === "\n" || char === "\r") {
+            endRow();
+            i++;
+        }
+        else {
+            field += char;
+            i++;
+        }
+    }
+    if (quoted) {
+        throw new CsvError(`Row ${rows.length + 1} has a quoted value that never ends.`);
+    }
+    if (field.length > 0 || row.length > 0 || fieldWasQuoted) {
+        endRow();
+    }
+    return rows;
+}
+/** The delimiter of a CSV file, from its first line: whichever of comma, semicolon or tab appears most outside quotes (comma on a tie). */
+export function detectDelimiter(text) {
+    const firstLine = text.split(/\r?\n/, 1)[0].replace(/"[^"]*"/g, "");
+    let best = ",";
+    let bestCount = 0;
+    for (const candidate of [",", ";", "\t"]) {
+        const count = firstLine.split(candidate).length - 1;
+        if (count > bestCount) {
+            best = candidate;
+            bestCount = count;
+        }
+    }
+    return best;
+}
+/**
+ * One CSV field: quoted when it holds a comma, a quote or a line break. A value starting with `=`, `+`, `-`, `@`, a tab or a carriage
+ * return gets a leading `'`, so a spreadsheet opening the file reads it as text instead of running it as a formula (CSV injection).
+ */
+export function csvField(value) {
+    let text = value === undefined || value === null ? "" : value instanceof Date ? value.toISOString() : String(value);
+    if (/^[=+\-@\t\r]/.test(text)) {
+        text = `'${text}`;
+    }
+    return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+/** One CSV line (CRLF-terminated) of `values`. */
+export function csvLine(values) {
+    return `${values.map(csvField).join(",")}\r\n`;
+}
+//# sourceMappingURL=Csv.js.map

package/dist/lib/util/Csv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Csv.js","sourceRoot":"","sources":["../../../src/util/Csv.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAE/E,8CAA8C;AAC9C,MAAM,OAAO,QAAS,SAAQ,KAAK;IAC/B,YAAmB,OAAe;QAC9B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IAC3B,CAAC;CACJ;AASD;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,YAAoB,GAAG,EAAE,SAAoB,EAAE;IAClF,MAAM,OAAO,GAAW,MAAM,CAAC,OAAO,IAAI,QAAQ,CAAC;IACnD,MAAM,UAAU,GAAW,MAAM,CAAC,UAAU,IAAI,GAAG,CAAC;IACpD,MAAM,cAAc,GAAW,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC;IAC/D,MAAM,KAAK,GAAW,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3E,MAAM,IAAI,GAAe,EAAE,CAAC;IAC5B,IAAI,GAAG,GAAa,EAAE,CAAC;IACvB,IAAI,KAAK,GAAW,EAAE,CAAC;IACvB,IAAI,MAAM,GAAY,KAAK,CAAC;IAC5B,IAAI,cAAc,GAAY,KAAK,CAAC;IACpC,IAAI,CAAC,GAAW,CAAC,CAAC;IAElB,MAAM,QAAQ,GAAG,GAAS,EAAE;QACxB,IAAI,KAAK,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;YAChC,MAAM,IAAI,QAAQ,CAAC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,4BAA4B,cAAc,cAAc,CAAC,CAAC;QACvG,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChB,IAAI,GAAG,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;YAC1B,MAAM,IAAI,QAAQ,CAAC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,kBAAkB,UAAU,WAAW,CAAC,CAAC;QACtF,CAAC;QACD,KAAK,GAAG,EAAE,CAAC;QACX,cAAc,GAAG,KAAK,CAAC;IAC3B,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,GAAS,EAAE;QACtB,uFAAuF;QACvF,MAAM,aAAa,GAAY,cAAc,CAAC;QAC9C,QAAQ,EAAE,CAAC;QACX,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;YACzD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACf,IAAI,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;gBACxB,MAAM,IAAI,QAAQ,CAAC,0BAA0B,OAAO,QAAQ,CAAC,CAAC;YAClE,CAAC;QACL,CAAC;QACD,GAAG,GAAG,EAAE,CAAC;IACb,CAAC,CAAC;IAEF,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QACtB,MAAM,IAAI,GAAW,KAAK,CAAC,CAAC,CAAC,CAAC;QAC9B,IAAI,MAAM,EAAE,CAAC;YACT,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;gBACf,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;oBACvB,KAAK,IAAI,GAAG,CAAC;oBACb,CAAC,IAAI,CAAC,CAAC;oBACP,SAAS;gBACb,CAAC;gBACD,MAAM,GAAG,KAAK,CAAC;gBACf,CAAC,EAAE,CAAC;gBACJ,SAAS;YACb,CAAC;YACD,KAAK,IAAI,IAAI,CAAC;YACd,CAAC,EAAE,CAAC;YACJ,SAAS;QACb,CAAC;QACD,IAAI,IAAI,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrC,MAAM,GAAG,IAAI,CAAC;YACd,cAAc,GAAG,IAAI,CAAC;YACtB,CAAC,EAAE,CAAC;QACR,CAAC;aAAM,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5B,QAAQ,EAAE,CAAC;YACX,CAAC,EAAE,CAAC;QACR,CAAC;aAAM,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YAChD,MAAM,EAAE,CAAC;YACT,CAAC,IAAI,CAAC,CAAC;QACX,CAAC;aAAM,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACxC,MAAM,EAAE,CAAC;YACT,CAAC,EAAE,CAAC;QACR,CAAC;aAAM,CAAC;YACJ,KAAK,IAAI,IAAI,CAAC;YACd,CAAC,EAAE,CAAC;QACR,CAAC;IACL,CAAC;IACD,IAAI,MAAM,EAAE,CAAC;QACT,MAAM,IAAI,QAAQ,CAAC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,sCAAsC,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,cAAc,EAAE,CAAC;QACvD,MAAM,EAAE,CAAC;IACb,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,2IAA2I;AAC3I,MAAM,UAAU,eAAe,CAAC,IAAY;IACxC,MAAM,SAAS,GAAW,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC5E,IAAI,IAAI,GAAW,GAAG,CAAC;IACvB,IAAI,SAAS,GAAW,CAAC,CAAC;IAC1B,KAAK,MAAM,SAAS,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,KAAK,GAAW,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QAC5D,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YACpB,IAAI,GAAG,SAAS,CAAC;YACjB,SAAS,GAAG,KAAK,CAAC;QACtB,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACnC,IAAI,IAAI,GAAW,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5H,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;IACtB,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1E,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,OAAO,CAAC,MAAiB;IACrC,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;AACnD,CAAC"}

package/dist/lib/util/ImportMapping.js

@@ -0,0 +1,206 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { CrmObjectType, PropertyType } from "../models/types.js";
+import { TAGS_KEY } from "./PropertyValues.js";
+import { badRequest, normalizeTag, parseDate } from "./Validation.js";
+/** The import target of a contact column holding its company's name: the company is found by name, or created. */
+export const COMPANY_NAME_TARGET = "company";
+/** The prefix of a custom property target (`properties.<key>`). */
+const PROPERTY_PREFIX = "properties.";
+/** The contact and company fields an import may fill, with how their text is read (`number`: as a number). */
+export const IMPORT_FIELDS = {
+    [CrmObjectType.CONTACT]: {
+        email: "text",
+        firstName: "text",
+        lastName: "text",
+        phone: "text",
+        jobTitle: "text",
+        lifecycleStage: "text",
+        leadStatus: "text",
+        score: "number",
+        source: "text",
+    },
+    [CrmObjectType.COMPANY]: {
+        name: "text",
+        domain: "text",
+        industry: "text",
+        employeeCount: "number",
+        phone: "text",
+        website: "text",
+        city: "text",
+        country: "text",
+    },
+};
+/** Header spellings that mean a field, besides its own name (compared with case, spaces and punctuation removed). */
+const ALIASES = {
+    email: ["emailaddress", "mail", "e-mail"],
+    firstName: ["first", "givenname", "forename"],
+    lastName: ["last", "surname", "familyname"],
+    phone: ["phonenumber", "telephone", "mobile", "tel"],
+    jobTitle: ["title", "position", "role"],
+    [COMPANY_NAME_TARGET]: ["companyname", "organization", "organisation", "account"],
+    name: ["companyname", "organization", "organisation", "account"],
+    domain: ["companydomain", "domainname"],
+    website: ["url", "web", "homepage"],
+    employeeCount: ["employees", "numberofemployees", "size"],
+    tags: ["tag", "labels", "label"],
+};
+/** A header or target name compared loosely: lowercase, letters and digits only. */
+function loose(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+/**
+ * Every target a column of an `objectType` import may map to: the record's `importFields`, `tags`, `properties.<key>` for each of its
+ * custom properties, and for contacts `company` (the company's name).
+ */
+export function importTargets(objectType, importFields, definitions) {
+    return [
+        ...Object.keys(importFields),
+        TAGS_KEY,
+        ...(objectType === CrmObjectType.CONTACT ? [COMPANY_NAME_TARGET] : []),
+        ...definitions.filter((definition) => definition.objectType === objectType).map((definition) => `${PROPERTY_PREFIX}${definition.key}`),
+    ];
+}
+/** A mapping guessed from the header: each column mapped to the target whose name, alias or property label it matches, once. */
+export function suggestMapping(columns, targets, definitions) {
+    const used = new Set();
+    return columns.map((column) => {
+        const header = loose(column);
+        const target = targets.find((candidate) => {
+            if (used.has(candidate)) {
+                return false;
+            }
+            const key = candidate.startsWith(PROPERTY_PREFIX) ? candidate.slice(PROPERTY_PREFIX.length) : candidate;
+            const label = definitions.find((definition) => definition.key === key)?.label;
+            return header === loose(key) || (label !== undefined && header === loose(label)) || (ALIASES[candidate] ?? []).some((alias) => loose(alias) === header);
+        });
+        if (target) {
+            used.add(target);
+        }
+        return { column, target };
+    });
+}
+/**
+ * Checks a mapping from a start request against the CSV's `columns` and the allowed `targets`: one entry per column (a missing one is
+ * skipped), each target used once, and the required one (`email` for contacts, `name` for companies) mapped.
+ */
+export function validateMapping(raw, columns, targets, required) {
+    if (!Array.isArray(raw)) {
+        throw badRequest("'mapping' must be a list of { column, target }.");
+    }
+    const used = new Set();
+    const mapping = columns.map((column) => ({ column }));
+    for (const entry of raw) {
+        const column = entry?.column;
+        const target = entry?.target;
+        const index = typeof column === "string" ? columns.indexOf(column) : -1;
+        if (index < 0) {
+            throw badRequest(`The mapping names a column the file doesn't have: ${JSON.stringify(column)}.`);
+        }
+        if (target === undefined || target === null || target === "") {
+            continue;
+        }
+        if (typeof target !== "string" || !targets.includes(target)) {
+            throw badRequest(`Column '${column}' is mapped to an unknown field: ${JSON.stringify(target)}.`);
+        }
+        if (used.has(target) && target !== TAGS_KEY) {
+            throw badRequest(`More than one column is mapped to '${target}'.`);
+        }
+        used.add(target);
+        mapping[index] = { column: column, target };
+    }
+    if (!used.has(required)) {
+        throw badRequest(`A column must be mapped to '${required}'.`);
+    }
+    return mapping;
+}
+/** Splits a list cell (tags, a multi-select) on `;` or `,`. */
+function splitList(cell) {
+    return cell
+        .split(/[;,]/)
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+/**
+ * One CSV row as a create request: each mapped, non-empty cell read as its target's type (numbers, booleans as true/yes/1 and
+ * false/no/0, dates, `;`- or `,`-separated tags and multi-select values), plus `extraTags`. A cell that isn't a valid value for its
+ * target is a 400 naming the column.
+ */
+export function rowToBody(row, mapping, importFields, definitions, extraTags) {
+    const body = {};
+    const properties = {};
+    const tags = [...extraTags];
+    mapping.forEach((entry, index) => {
+        const cell = (row[index] ?? "").trim();
+        if (!entry.target || cell.length === 0) {
+            return;
+        }
+        if (entry.target === TAGS_KEY) {
+            for (const part of splitList(cell)) {
+                const tag = normalizeTag(part);
+                if (tag && !tags.includes(tag)) {
+                    tags.push(tag);
+                }
+            }
+            return;
+        }
+        if (entry.target.startsWith(PROPERTY_PREFIX)) {
+            const key = entry.target.slice(PROPERTY_PREFIX.length);
+            const definition = definitions.find((candidate) => candidate.key === key);
+            properties[key] = cellValue(definition, cell, entry.column);
+            return;
+        }
+        if (importFields[entry.target] === "number") {
+            const value = Number(cell.replace(/[\s,]/g, ""));
+            if (!Number.isFinite(value)) {
+                throw badRequest(`'${entry.column}' must be a number, not '${cell}'.`);
+            }
+            body[entry.target] = Math.round(value);
+            return;
+        }
+        body[entry.target] = cell;
+    });
+    if (tags.length > 0) {
+        body.tags = tags;
+    }
+    if (Object.keys(properties).length > 0) {
+        body.properties = properties;
+    }
+    return body;
+}
+/** One cell as a custom property's value. */
+function cellValue(definition, cell, column) {
+    switch (definition.type) {
+        case PropertyType.NUMBER: {
+            const value = Number(cell.replace(/[\s,]/g, ""));
+            if (!Number.isFinite(value)) {
+                throw badRequest(`'${column}' must be a number, not '${cell}'.`);
+            }
+            return value;
+        }
+        case PropertyType.BOOLEAN: {
+            const lower = cell.toLowerCase();
+            if (["true", "yes", "y", "1"].includes(lower)) {
+                return true;
+            }
+            if (["false", "no", "n", "0"].includes(lower)) {
+                return false;
+            }
+            throw badRequest(`'${column}' must be yes or no, not '${cell}'.`);
+        }
+        case PropertyType.DATE: {
+            const date = parseDate(cell);
+            if (!date) {
+                throw badRequest(`'${column}' must be a date, not '${cell}'.`);
+            }
+            return date.toISOString();
+        }
+        case PropertyType.MULTI_SELECT:
+            return splitList(cell);
+        default:
+            return cell;
+    }
+}
+//# sourceMappingURL=ImportMapping.js.map

package/dist/lib/util/ImportMapping.js.map

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

package/dist/lib/util/Mailer.js

@@ -0,0 +1,43 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import MailComposer from "nodemailer/lib/mail-composer/index.js";
+/** Escapes text for HTML. */
+export function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+/** A small, complete HTML email: a heading, paragraphs, and an optional button link. Everything given is escaped. */
+export function simpleHtml(heading, paragraphs, button) {
+    const body = [`<h1 style="font-size:20px;margin:0 0 16px">${escapeHtml(heading)}</h1>`];
+    for (const paragraph of paragraphs) {
+        body.push(`<p style="margin:0 0 12px;line-height:1.5">${escapeHtml(paragraph)}</p>`);
+    }
+    if (button) {
+        body.push(`<p style="margin:20px 0"><a href="${escapeHtml(button.href)}" style="background:#2563eb;color:#ffffff;padding:10px 18px;border-radius:4px;text-decoration:none;display:inline-block">${escapeHtml(button.label)}</a></p>`);
+    }
+    return `<!DOCTYPE html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"></head><body style="font-family:Arial,Helvetica,sans-serif;color:#111827;margin:0;padding:24px">${body.join("")}</body></html>`;
+}
+/** Composes `message` as `multipart/alternative` MIME. */
+export async function composeMessage(message) {
+    return await new MailComposer({
+        from: { name: message.sender.fromName, address: message.sender.fromAddress },
+        replyTo: message.sender.replyToAddress || undefined,
+        to: message.to,
+        subject: message.subject,
+        text: message.text,
+        html: message.html,
+        headers: message.headers,
+        messageId: message.messageId,
+    })
+        .compile()
+        .build();
+}
+/** Sends `message` through the server's mail transport, from its sender's address. Throws when the transport accepts no recipient. */
+export async function sendSystemMessage(transport, message) {
+    const result = await transport.send({ raw: await composeMessage(message), envelopeFrom: message.sender.fromAddress, envelopeTo: [message.to] });
+    if (result.accepted.length === 0) {
+        throw new Error(`The mail transport refused the message to ${message.to}.`);
+    }
+}
+//# sourceMappingURL=Mailer.js.map

package/dist/lib/util/Mailer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mailer.js","sourceRoot":"","sources":["../../../src/util/Mailer.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,mEAAmE;AACnE,mCAAmC;AACnC,+EAA+E;AAC/E,OAAO,YAAY,MAAM,uCAAuC,CAAC;AAgBjE,6BAA6B;AAC7B,MAAM,UAAU,UAAU,CAAC,IAAY;IACnC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAClI,CAAC;AAED,qHAAqH;AACrH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,UAAoB,EAAE,MAAwC;IACtG,MAAM,IAAI,GAAa,CAAC,8CAA8C,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClG,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACjC,IAAI,CAAC,IAAI,CAAC,8CAA8C,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,MAAM,EAAE,CAAC;QACT,IAAI,CAAC,IAAI,CACL,qCAAqC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,4HAA4H,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAC7N,CAAC;IACN,CAAC;IACD,OAAO,wNAAwN,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC;AACjQ,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAsB;IACvD,OAAO,MAAM,IAAI,YAAY,CAAC;QAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE;QAC5E,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,IAAI,SAAS;QACnD,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,OAAO,CAAC,SAAS;KAC/B,CAAC;SACG,OAAO,EAAE;SACT,KAAK,EAAE,CAAC;AACjB,CAAC;AAED,sIAAsI;AACtI,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,SAAwB,EAAE,OAAsB;IACpF,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC,OAAO,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,UAAU,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAChJ,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,6CAA6C,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC;IAChF,CAAC;AACL,CAAC"}