@funnelsgrove/cli 0.1.75 → 0.1.78

package/dist/emailFiles.js

@@ -0,0 +1,517 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createValidationDiagnostic, } from './diagnosticOutput.js';
+const EMAIL_EVENTS = new Set([
+    'email_captured',
+    'purchase_completed',
+    'registration_completed',
+]);
+const VARIABLE_TYPES = new Set(['string', 'number', 'boolean']);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const RESERVED_VARIABLE_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
+const STEP_KEY = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const TEMPLATE_METADATA_KEYS = new Set([
+    'id',
+    'slug',
+    'name',
+    'subject',
+    'previewText',
+    'variables',
+]);
+const SEQUENCE_KEYS = new Set([
+    'id',
+    'slug',
+    'name',
+    'triggerEventType',
+    'funnelIds',
+    'steps',
+    'exitEventTypes',
+]);
+const SEQUENCE_STEP_KEYS = new Set(['key', 'delaySeconds', 'templateVersionId']);
+const isRecord = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value));
+const assertNoSymlinkPath = async (root, relativePath = '') => {
+    const parts = relativePath ? relativePath.split('/') : [];
+    let current = path.resolve(root);
+    for (const part of ['', ...parts]) {
+        if (part)
+            current = path.join(current, part);
+        try {
+            const metadata = await lstat(current);
+            if (metadata.isSymbolicLink()) {
+                throw new Error(`Managed email path cannot be a symlink: ${current}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+};
+const assertWriterSlug = (slug) => {
+    if (slug.length > 80 || !SLUG.test(slug)) {
+        throw new Error(`Invalid email file slug: ${slug}`);
+    }
+};
+const writeAtomic = async (filePath, content) => {
+    const temporaryPath = `${filePath}.tmp-${randomUUID()}`;
+    try {
+        await writeFile(temporaryPath, content, { flag: 'wx' });
+        await rename(temporaryPath, filePath);
+    }
+    finally {
+        await rm(temporaryPath, { force: true });
+    }
+};
+const diagnostic = (input) => createValidationDiagnostic({
+    ...input,
+    stepId: null,
+    guide: 'Run `fgrove email validate` after repairing the file.',
+});
+const schemaDiagnostic = (file, field, expected, received) => diagnostic({
+    code: 'FG-EMAIL-002',
+    file,
+    reason: `Invalid email field: ${field}`,
+    expected,
+    received,
+    repair: `Set ${field} to the documented email file value.`,
+});
+const missingFileDiagnostic = (file) => diagnostic({
+    code: 'FG-EMAIL-001',
+    file,
+    reason: `Missing required email file: ${file}`,
+    expected: 'file',
+    received: null,
+    repair: `Create ${file}.`,
+});
+const readUtf8 = async (absolutePath, relativePath, diagnostics) => {
+    try {
+        return await readFile(absolutePath, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            diagnostics.push(missingFileDiagnostic(relativePath));
+            return null;
+        }
+        throw error;
+    }
+};
+const readJson = async (absolutePath, relativePath, diagnostics) => {
+    const source = await readUtf8(absolutePath, relativePath, diagnostics);
+    if (source === null)
+        return null;
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        diagnostics.push(diagnostic({
+            code: 'FG-EMAIL-001',
+            file: relativePath,
+            reason: 'Invalid JSON in email file',
+            expected: 'valid JSON',
+            received: source,
+            repair: `Repair the JSON syntax in ${relativePath}.`,
+        }));
+        return null;
+    }
+};
+const validateExactKeys = (value, allowed, file, diagnostics) => {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            diagnostics.push(schemaDiagnostic(file, key, 'no unknown fields', value[key]));
+        }
+    }
+};
+const validateIdentity = (value, pathSlug, file, diagnostics) => {
+    let valid = true;
+    if (value.id !== null && (typeof value.id !== 'string' || !UUID.test(value.id))) {
+        diagnostics.push(schemaDiagnostic(file, 'id', 'UUID or null', value.id));
+        valid = false;
+    }
+    if (typeof value.slug !== 'string' || value.slug.length > 80 || !SLUG.test(value.slug)) {
+        diagnostics.push(schemaDiagnostic(file, 'slug', 'lowercase kebab-case slug', value.slug));
+        valid = false;
+    }
+    else if (value.slug !== pathSlug) {
+        diagnostics.push(diagnostic({
+            code: 'FG-EMAIL-003',
+            file,
+            reason: `Email slug ${value.slug} does not match path slug ${pathSlug}`,
+            expected: pathSlug,
+            received: value.slug,
+            repair: `Restore the path to ${value.slug} or restore slug to ${pathSlug}.`,
+        }));
+        valid = false;
+    }
+    if (typeof value.name !== 'string' || !value.name.trim() || value.name.length > 120) {
+        diagnostics.push(schemaDiagnostic(file, 'name', 'non-empty string up to 120 characters', value.name));
+        valid = false;
+    }
+    else if (value.name !== value.name.trim()) {
+        diagnostics.push(diagnostic({
+            code: 'FG-EMAIL-002',
+            file,
+            reason: 'Email name contains surrounding whitespace',
+            expected: value.name.trim(),
+            received: value.name,
+            repair: 'Remove surrounding whitespace from name.',
+        }));
+        valid = false;
+    }
+    return valid;
+};
+const validateTemplateMetadata = (value, pathSlug, file, diagnostics) => {
+    if (!isRecord(value)) {
+        diagnostics.push(schemaDiagnostic(file, 'root', 'object', value));
+        return null;
+    }
+    const initialCount = diagnostics.length;
+    validateExactKeys(value, TEMPLATE_METADATA_KEYS, file, diagnostics);
+    validateIdentity(value, pathSlug, file, diagnostics);
+    if (typeof value.subject !== 'string' || Buffer.byteLength(value.subject, 'utf8') > 998) {
+        diagnostics.push(schemaDiagnostic(file, 'subject', 'string up to 998 UTF-8 bytes', value.subject));
+    }
+    else if ([...value.subject].some((character) => {
+        const code = character.codePointAt(0);
+        return code <= 0x1f || (code >= 0x7f && code <= 0x9f);
+    })) {
+        diagnostics.push(diagnostic({
+            code: 'FG-EMAIL-002',
+            file,
+            reason: 'Email subject contains invalid control characters',
+            expected: 'subject without control characters',
+            received: value.subject,
+            repair: 'Remove control characters from subject.',
+        }));
+    }
+    if (value.previewText !== null
+        && (typeof value.previewText !== 'string' || Buffer.byteLength(value.previewText, 'utf8') > 500)) {
+        diagnostics.push(schemaDiagnostic(file, 'previewText', 'string up to 500 UTF-8 bytes or null', value.previewText));
+    }
+    if (!isRecord(value.variables)) {
+        diagnostics.push(schemaDiagnostic(file, 'variables', 'object', value.variables));
+    }
+    else {
+        const names = Object.keys(value.variables);
+        if (names.length > 50) {
+            diagnostics.push(schemaDiagnostic(file, 'variables', 'at most 50 variables', names.length));
+        }
+        for (const name of names) {
+            if (!VARIABLE_NAME.test(name) || Buffer.byteLength(name, 'utf8') > 64) {
+                diagnostics.push(schemaDiagnostic(file, `variables.${name}`, 'safe variable name', name));
+            }
+            if (RESERVED_VARIABLE_NAMES.has(name)) {
+                diagnostics.push(schemaDiagnostic(file, `variables.${name}`, 'non-reserved variable name', name));
+            }
+            if (!VARIABLE_TYPES.has(value.variables[name])) {
+                diagnostics.push(schemaDiagnostic(file, `variables.${name}`, 'string, number, or boolean', value.variables[name]));
+            }
+        }
+    }
+    if (diagnostics.length !== initialCount)
+        return null;
+    return value;
+};
+const validateSequence = (value, pathSlug, file, diagnostics) => {
+    if (!isRecord(value)) {
+        diagnostics.push(schemaDiagnostic(file, 'root', 'object', value));
+        return null;
+    }
+    const initialCount = diagnostics.length;
+    validateExactKeys(value, SEQUENCE_KEYS, file, diagnostics);
+    validateIdentity(value, pathSlug, file, diagnostics);
+    if (!EMAIL_EVENTS.has(value.triggerEventType)) {
+        diagnostics.push(schemaDiagnostic(file, 'triggerEventType', [...EMAIL_EVENTS], value.triggerEventType));
+    }
+    if (!Array.isArray(value.funnelIds) || value.funnelIds.length < 1 || value.funnelIds.length > 50) {
+        diagnostics.push(schemaDiagnostic(file, 'funnelIds', '1 to 50 UUIDs', value.funnelIds));
+    }
+    else {
+        value.funnelIds.forEach((id, index) => {
+            if (typeof id !== 'string' || !UUID.test(id)) {
+                diagnostics.push(schemaDiagnostic(file, `funnelIds[${index}]`, 'UUID', id));
+            }
+        });
+    }
+    if (!Array.isArray(value.steps) || value.steps.length < 1 || value.steps.length > 50) {
+        diagnostics.push(schemaDiagnostic(file, 'steps', '1 to 50 steps', value.steps));
+    }
+    else {
+        const seenKeys = new Set();
+        value.steps.forEach((step, index) => {
+            if (!isRecord(step)) {
+                diagnostics.push(schemaDiagnostic(file, `steps[${index}]`, 'object', step));
+                return;
+            }
+            validateExactKeys(step, SEQUENCE_STEP_KEYS, file, diagnostics);
+            if (typeof step.key !== 'string' || !STEP_KEY.test(step.key) || step.key.length > 64) {
+                diagnostics.push(schemaDiagnostic(file, `steps[${index}].key`, 'lowercase kebab-case key', step.key));
+            }
+            else if (seenKeys.has(step.key)) {
+                diagnostics.push(schemaDiagnostic(file, `steps[${index}].key`, 'unique step key', step.key));
+            }
+            else {
+                seenKeys.add(step.key);
+            }
+            if (!Number.isInteger(step.delaySeconds) || Number(step.delaySeconds) < 0 || Number(step.delaySeconds) > 7_776_000) {
+                diagnostics.push(schemaDiagnostic(file, `steps[${index}].delaySeconds`, 'integer from 0 to 7776000', step.delaySeconds));
+            }
+            if (typeof step.templateVersionId !== 'string' || !UUID.test(step.templateVersionId)) {
+                diagnostics.push(schemaDiagnostic(file, `steps[${index}].templateVersionId`, 'UUID', step.templateVersionId));
+            }
+        });
+    }
+    if (!Array.isArray(value.exitEventTypes) || value.exitEventTypes.length > EMAIL_EVENTS.size) {
+        diagnostics.push(schemaDiagnostic(file, 'exitEventTypes', 'up to 3 event types', value.exitEventTypes));
+    }
+    else {
+        value.exitEventTypes.forEach((event, index) => {
+            if (!EMAIL_EVENTS.has(event)) {
+                diagnostics.push(schemaDiagnostic(file, `exitEventTypes[${index}]`, [...EMAIL_EVENTS], event));
+            }
+        });
+        if (value.exitEventTypes.includes(value.triggerEventType)) {
+            diagnostics.push(schemaDiagnostic(file, 'exitEventTypes', 'events excluding triggerEventType', value.exitEventTypes));
+        }
+    }
+    if (diagnostics.length !== initialCount)
+        return null;
+    return {
+        id: value.id,
+        slug: value.slug,
+        name: value.name,
+        draft: {
+            triggerEventType: value.triggerEventType,
+            funnelIds: value.funnelIds,
+            steps: value.steps,
+            exitEventTypes: value.exitEventTypes,
+        },
+    };
+};
+const listDirectories = async (directory) => {
+    try {
+        const entries = await readdir(directory, { withFileTypes: true });
+        const symlink = entries.find((entry) => entry.isSymbolicLink());
+        if (symlink)
+            throw new Error(`Managed email path cannot be a symlink: ${path.join(directory, symlink.name)}`);
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+};
+const listJsonFiles = async (directory) => {
+    try {
+        const entries = await readdir(directory, { withFileTypes: true });
+        const symlink = entries.find((entry) => entry.isSymbolicLink());
+        if (symlink)
+            throw new Error(`Managed email path cannot be a symlink: ${path.join(directory, symlink.name)}`);
+        return entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+};
+export async function readEmailFiles(sourceDir) {
+    const diagnostics = [];
+    const templates = [];
+    const sequences = [];
+    const templateRoot = path.join(sourceDir, 'emails', 'templates');
+    const sequenceRoot = path.join(sourceDir, 'emails', 'sequences');
+    await Promise.all([
+        assertNoSymlinkPath(sourceDir),
+        assertNoSymlinkPath(sourceDir, 'emails'),
+        assertNoSymlinkPath(sourceDir, 'emails/templates'),
+        assertNoSymlinkPath(sourceDir, 'emails/sequences'),
+    ]);
+    for (const slug of await listDirectories(templateRoot)) {
+        const relativeRoot = path.posix.join('emails', 'templates', slug);
+        const metadataFile = path.posix.join(relativeRoot, 'template.json');
+        const htmlFile = path.posix.join(relativeRoot, 'body.html');
+        const textFile = path.posix.join(relativeRoot, 'body.txt');
+        await Promise.all([
+            assertNoSymlinkPath(sourceDir, relativeRoot),
+            assertNoSymlinkPath(sourceDir, metadataFile),
+            assertNoSymlinkPath(sourceDir, htmlFile),
+            assertNoSymlinkPath(sourceDir, textFile),
+        ]);
+        const metadataValue = await readJson(path.join(templateRoot, slug, 'template.json'), metadataFile, diagnostics);
+        const html = await readUtf8(path.join(templateRoot, slug, 'body.html'), htmlFile, diagnostics);
+        const text = await readUtf8(path.join(templateRoot, slug, 'body.txt'), textFile, diagnostics);
+        const metadata = metadataValue === null
+            ? null
+            : validateTemplateMetadata(metadataValue, slug, metadataFile, diagnostics);
+        if (metadata && html !== null && text !== null) {
+            if (Buffer.byteLength(html, 'utf8') > 256_000) {
+                diagnostics.push(schemaDiagnostic(htmlFile, 'body', 'up to 256000 UTF-8 bytes', html.length));
+            }
+            else if (Buffer.byteLength(text, 'utf8') > 100_000) {
+                diagnostics.push(schemaDiagnostic(textFile, 'body', 'up to 100000 UTF-8 bytes', text.length));
+            }
+            else {
+                templates.push({
+                    id: metadata.id,
+                    slug: metadata.slug,
+                    name: metadata.name,
+                    draft: {
+                        subject: metadata.subject,
+                        previewText: metadata.previewText,
+                        html,
+                        text,
+                        variables: metadata.variables,
+                    },
+                });
+            }
+        }
+    }
+    for (const filename of await listJsonFiles(sequenceRoot)) {
+        const slug = filename.slice(0, -'.json'.length);
+        const relativeFile = path.posix.join('emails', 'sequences', filename);
+        const value = await readJson(path.join(sequenceRoot, filename), relativeFile, diagnostics);
+        const sequence = value === null ? null : validateSequence(value, slug, relativeFile, diagnostics);
+        if (sequence)
+            sequences.push(sequence);
+    }
+    return {
+        valid: diagnostics.length === 0,
+        diagnostics,
+        templates,
+        sequences,
+    };
+}
+const sortedVariables = (variables) => Object.fromEntries(Object.entries(variables).sort(([left], [right]) => (Buffer.compare(Buffer.from(left), Buffer.from(right)))));
+const compareUtf8 = (left, right) => (Buffer.compare(Buffer.from(left), Buffer.from(right)));
+const sortedUnique = (values) => [...new Set(values)].sort(compareUtf8);
+export async function writeEmailTemplateFile(sourceDir, template) {
+    assertWriterSlug(template.slug);
+    const relativeDirectory = path.posix.join('emails', 'templates', template.slug);
+    const directory = path.join(sourceDir, relativeDirectory);
+    await Promise.all([
+        assertNoSymlinkPath(sourceDir),
+        assertNoSymlinkPath(sourceDir, 'emails'),
+        assertNoSymlinkPath(sourceDir, 'emails/templates'),
+        assertNoSymlinkPath(sourceDir, relativeDirectory),
+        assertNoSymlinkPath(sourceDir, path.posix.join(relativeDirectory, 'template.json')),
+        assertNoSymlinkPath(sourceDir, path.posix.join(relativeDirectory, 'body.html')),
+        assertNoSymlinkPath(sourceDir, path.posix.join(relativeDirectory, 'body.txt')),
+    ]);
+    await mkdir(directory, { recursive: true });
+    const metadata = {
+        id: template.id,
+        slug: template.slug,
+        name: template.name,
+        subject: template.draft.subject,
+        previewText: template.draft.previewText,
+        variables: sortedVariables(template.draft.variables),
+    };
+    await writeAtomic(path.join(directory, 'template.json'), `${JSON.stringify(metadata, null, 2)}\n`);
+    await Promise.all([
+        writeAtomic(path.join(directory, 'body.html'), template.draft.html),
+        writeAtomic(path.join(directory, 'body.txt'), template.draft.text),
+    ]);
+}
+export async function writeEmailSequenceFile(sourceDir, sequence) {
+    assertWriterSlug(sequence.slug);
+    const relativeRoot = path.posix.join('emails', 'sequences');
+    const relativeFile = path.posix.join(relativeRoot, `${sequence.slug}.json`);
+    await Promise.all([
+        assertNoSymlinkPath(sourceDir),
+        assertNoSymlinkPath(sourceDir, 'emails'),
+        assertNoSymlinkPath(sourceDir, relativeRoot),
+        assertNoSymlinkPath(sourceDir, relativeFile),
+    ]);
+    const sequenceRoot = path.join(sourceDir, relativeRoot);
+    await mkdir(sequenceRoot, { recursive: true });
+    const serialized = {
+        id: sequence.id,
+        slug: sequence.slug,
+        name: sequence.name,
+        triggerEventType: sequence.draft.triggerEventType,
+        funnelIds: sortedUnique(sequence.draft.funnelIds),
+        steps: sequence.draft.steps.map((step) => ({
+            key: step.key,
+            delaySeconds: step.delaySeconds,
+            templateVersionId: step.templateVersionId,
+        })),
+        exitEventTypes: sortedUnique(sequence.draft.exitEventTypes),
+    };
+    await writeAtomic(path.join(sequenceRoot, `${sequence.slug}.json`), `${JSON.stringify(serialized, null, 2)}\n`);
+}
+export async function writeEmailFiles(input) {
+    await Promise.all([
+        assertNoSymlinkPath(input.sourceDir),
+        assertNoSymlinkPath(input.sourceDir, 'emails'),
+        assertNoSymlinkPath(input.sourceDir, 'emails/templates'),
+        assertNoSymlinkPath(input.sourceDir, 'emails/sequences'),
+    ]);
+    await Promise.all([
+        mkdir(path.join(input.sourceDir, 'emails', 'templates'), { recursive: true }),
+        mkdir(path.join(input.sourceDir, 'emails', 'sequences'), { recursive: true }),
+    ]);
+    for (const template of [...input.templates].sort((left, right) => compareUtf8(left.slug, right.slug))) {
+        await writeEmailTemplateFile(input.sourceDir, template);
+    }
+    for (const sequence of [...input.sequences].sort((left, right) => compareUtf8(left.slug, right.slug))) {
+        await writeEmailSequenceFile(input.sourceDir, sequence);
+    }
+}
+const pathExists = async (value) => {
+    try {
+        await lstat(value);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+};
+export async function replaceEmailFiles(input) {
+    await mkdir(input.sourceDir, { recursive: true });
+    await Promise.all([
+        assertNoSymlinkPath(input.sourceDir),
+        assertNoSymlinkPath(input.sourceDir, 'emails'),
+    ]);
+    const stagingRoot = await mkdtemp(path.join(input.sourceDir, '.fgrove-email-pull-'));
+    const target = path.join(input.sourceDir, 'emails');
+    const staged = path.join(stagingRoot, 'emails');
+    const backup = path.join(input.sourceDir, `.fgrove-email-backup-${randomUUID()}`);
+    let backedUp = false;
+    try {
+        await writeEmailFiles({ ...input, sourceDir: stagingRoot });
+        const validation = await readEmailFiles(stagingRoot);
+        if (!validation.valid)
+            throw new Error('Invalid remote email resources');
+        if (await pathExists(target)) {
+            await rename(target, backup);
+            backedUp = true;
+        }
+        try {
+            await rename(staged, target);
+        }
+        catch (error) {
+            if (backedUp)
+                await rename(backup, target);
+            backedUp = false;
+            throw error;
+        }
+        if (backedUp)
+            await rm(backup, { recursive: true, force: true });
+    }
+    finally {
+        await rm(stagingRoot, { recursive: true, force: true });
+    }
+}