@funnelsgrove/cli 0.1.73 → 0.1.76

package/dist/cli.js

@@ -15,6 +15,7 @@ import { buildCommittedSyncManifest, buildDownloadedSyncManifest, buildSourceCan
 import { mergeTextSourceWithGit } from './sourceRebase.js';
 import { executeExperimentCreate, formatExperimentCreateSuccess, recoverExperimentCreateTransaction, } from './experimentCreate.js';
 import { pullEnvFile } from './envSync.js';
+import { executeEmailPull, executeEmailPush, executeEmailSequencePublish, executeEmailTemplatePublish, executeEmailValidate, } from './emailCommands.js';
 import { formatGitHubConnectRows, formatGitHubJobRows, formatGitHubStatusRows, } from './githubOutput.js';
 import { GitHubSyncTimeoutError, syncGitHubDraftIfConnected, } from './githubSyncFlow.js';
 import { reskinFunnel } from './reskin.js';
@@ -1440,6 +1441,22 @@ const resolveAnalyticsProject = async (input) => {
     }
     return resolveProject(input.token, input.workspaceId, project);
 };
+const resolveEmailCommandScope = async (options) => {
+    const token = await readAuthToken();
+    const workspaceId = await resolveWorkspaceId(token, options.workspace);
+    const project = await resolveAnalyticsProject({
+        token,
+        workspaceId,
+        project: options.project,
+    });
+    return {
+        callApi,
+        token,
+        workspaceId,
+        projectId: project.id,
+        sourceDir: path.resolve(process.cwd(), options.dir),
+    };
+};
 const resolveAnalyticsFunnel = async (input) => {
     const active = await loadActiveContext(getConfigPath());
     const funnel = input.funnel || (active?.workspaceId === input.workspaceId ? active.funnelId : undefined);
@@ -1682,6 +1699,69 @@ addExamples(program
         console.log(`${legacyDiagnostic.code}\t${legacyDiagnostic.message}`);
     }
 });
+const addEmailScopeOptions = (command) => command
+    .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
+    .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
+    .option('--dir <path>', 'Directory containing the emails folder', '.');
+const emailCommand = addExamples(program.command('email').description('Manage project email drafts'), [
+    'fgrove email pull',
+    'fgrove email validate',
+    'fgrove email push',
+    'fgrove email template publish welcome',
+]);
+addEmailScopeOptions(emailCommand
+    .command('pull')
+    .description('Pull project email drafts into local files'))
+    .action(async (options) => {
+    const result = await executeEmailPull(await resolveEmailCommandScope(options));
+    console.log(`Pulled ${result.templates} templates and ${result.sequences} sequences.`);
+});
+emailCommand
+    .command('validate')
+    .description('Validate local email draft files')
+    .option('--dir <path>', 'Directory containing the emails folder', '.')
+    .action(async (options) => {
+    const result = await executeEmailValidate({
+        sourceDir: path.resolve(process.cwd(), options.dir),
+    });
+    if (result.valid) {
+        console.log('Email files are valid.');
+        return;
+    }
+    for (const item of result.diagnostics) {
+        console.error(`[${item.code}] ${item.file || 'emails'}: ${item.reason}`);
+    }
+    process.exitCode = 1;
+});
+addEmailScopeOptions(emailCommand
+    .command('push')
+    .description('Push local email drafts without publishing'))
+    .action(async (options) => {
+    const result = await executeEmailPush(await resolveEmailCommandScope(options));
+    console.log(`Pushed ${result.templates} templates and ${result.sequences} sequences.`);
+});
+const emailTemplateCommand = emailCommand.command('template').description('Manage email templates');
+addEmailScopeOptions(emailTemplateCommand
+    .command('publish <slug>')
+    .description('Publish one email template explicitly'))
+    .action(async (slug, options) => {
+    await executeEmailTemplatePublish({
+        ...await resolveEmailCommandScope(options),
+        slug,
+    });
+    console.log(`Published email template ${slug}.`);
+});
+const emailSequenceCommand = emailCommand.command('sequence').description('Manage email sequences');
+addEmailScopeOptions(emailSequenceCommand
+    .command('publish <slug>')
+    .description('Publish one email sequence explicitly'))
+    .action(async (slug, options) => {
+    await executeEmailSequencePublish({
+        ...await resolveEmailCommandScope(options),
+        slug,
+    });
+    console.log(`Published email sequence ${slug}.`);
+});
 const projectsCommand = addExamples(program.command('projects').description('Manage projects'), [
     'fgrove projects list',
     'fgrove projects list --workspace acme',

package/dist/emailCommands.d.ts

@@ -0,0 +1,32 @@
+import { type EmailFilesResult } from './emailFiles.js';
+export type EmailCallApi = <T>(input: {
+    path: string;
+    type: 'query' | 'mutation';
+    data?: unknown;
+    token?: string | null;
+}) => Promise<T>;
+type EmailCommandScope = {
+    callApi: EmailCallApi;
+    token: string;
+    workspaceId: string;
+    projectId: string;
+    sourceDir: string;
+};
+export declare function executeEmailPull(scope: EmailCommandScope): Promise<{
+    templates: number;
+    sequences: number;
+}>;
+export declare const executeEmailValidate: (input: {
+    sourceDir: string;
+}) => Promise<EmailFilesResult>;
+export declare function executeEmailPush(scope: EmailCommandScope): Promise<{
+    templates: number;
+    sequences: number;
+}>;
+export declare function executeEmailTemplatePublish(scope: EmailCommandScope & {
+    slug: string;
+}): Promise<unknown>;
+export declare function executeEmailSequencePublish(scope: EmailCommandScope & {
+    slug: string;
+}): Promise<unknown>;
+export {};

package/dist/emailCommands.js

@@ -0,0 +1,269 @@
+import { readEmailFiles, replaceEmailFiles, writeEmailFiles, writeEmailSequenceFile, writeEmailTemplateFile, } from './emailFiles.js';
+const isRecord = (value) => (typeof value === 'object' && value !== null && !Array.isArray(value));
+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 hasDraft = (value) => (isRecord(value) && isRecord(value.draft));
+const assertRemoteResource = (value, resource) => {
+    if (!isRecord(value)
+        || typeof value.id !== 'string'
+        || !UUID.test(value.id)
+        || typeof value.slug !== 'string'
+        || typeof value.name !== 'string'
+        || !hasDraft(value)) {
+        throw new Error(`Invalid remote ${resource} resource`);
+    }
+    return value;
+};
+const assertCreatedId = (value, resource) => {
+    if (!isRecord(value) || typeof value.id !== 'string' || !UUID.test(value.id)) {
+        throw new Error(`Invalid created ${resource} ID`);
+    }
+    return value.id;
+};
+const assertRemoteIdentity = (value, resource) => {
+    if (!isRecord(value)
+        || typeof value.id !== 'string'
+        || !UUID.test(value.id)
+        || typeof value.slug !== 'string') {
+        throw new Error(`Invalid remote ${resource} identity`);
+    }
+    return value;
+};
+const assertValidFiles = (result) => {
+    if (result.valid)
+        return;
+    const summary = result.diagnostics
+        .map((item) => `[${item.code}] ${item.file || 'emails'}: ${item.reason}`)
+        .join('\n');
+    throw new Error(`Email files are invalid. Run \`fgrove email validate\`.\n${summary}`);
+};
+const projectData = (scope) => ({
+    workspaceId: scope.workspaceId,
+    projectId: scope.projectId,
+});
+const assertRemoteIdentities = async (scope, input) => {
+    const localWithIds = input.local.filter((item) => item.id !== null);
+    if (localWithIds.length === 0)
+        return new Map();
+    const remote = await scope.callApi({
+        path: `${input.resource}.list`,
+        type: 'query',
+        token: scope.token,
+        data: projectData(scope),
+    });
+    const parsed = remote.map((item) => assertRemoteIdentity(item, input.resource));
+    const remoteSlugs = new Map(parsed.map((item) => [item.id, item.slug]));
+    for (const local of localWithIds) {
+        const remoteSlug = remoteSlugs.get(local.id);
+        if (remoteSlug !== local.slug) {
+            throw new Error(`Email identity mismatch: ID ${local.id} has local slug "${local.slug}" but remote slug ${remoteSlug ? `"${remoteSlug}"` : 'is missing'}.`);
+        }
+    }
+    return new Map(parsed.map((item) => [item.id, item]));
+};
+const canonicalResource = (kind, value) => {
+    if (kind === 'template') {
+        const variables = isRecord(value.draft.variables) ? value.draft.variables : {};
+        return JSON.stringify({
+            name: value.name,
+            subject: value.draft.subject,
+            previewText: value.draft.previewText,
+            html: value.draft.html,
+            text: value.draft.text,
+            variables: Object.fromEntries(Object.entries(variables).sort(([left], [right]) => left.localeCompare(right))),
+        });
+    }
+    const steps = Array.isArray(value.draft.steps) ? value.draft.steps : [];
+    return JSON.stringify({
+        name: value.name,
+        triggerEventType: value.draft.triggerEventType,
+        funnelIds: Array.isArray(value.draft.funnelIds) ? [...new Set(value.draft.funnelIds)].sort() : [],
+        steps: steps.map((step) => isRecord(step) ? {
+            key: step.key,
+            delaySeconds: step.delaySeconds,
+            templateVersionId: step.templateVersionId,
+        } : step),
+        exitEventTypes: Array.isArray(value.draft.exitEventTypes)
+            ? [...new Set(value.draft.exitEventTypes)].sort()
+            : [],
+    });
+};
+const loadCompleteItems = async (scope, input) => {
+    const listed = await scope.callApi({
+        path: `${input.resource}.list`,
+        type: 'query',
+        token: scope.token,
+        data: projectData(scope),
+    });
+    return Promise.all(listed.map(async (item) => {
+        if (hasDraft(item))
+            return assertRemoteResource(item, input.resource);
+        if (!isRecord(item) || typeof item.id !== 'string') {
+            throw new Error(`Invalid ${input.resource}.list response`);
+        }
+        const detail = await scope.callApi({
+            path: `${input.resource}.get`,
+            type: 'query',
+            token: scope.token,
+            data: {
+                ...projectData(scope),
+                [input.idKey]: item.id,
+            },
+        });
+        return assertRemoteResource(detail[input.detailKey], input.resource);
+    }));
+};
+export async function executeEmailPull(scope) {
+    const [templates, sequences] = await Promise.all([
+        loadCompleteItems(scope, {
+            resource: 'emailTemplates',
+            idKey: 'templateId',
+            detailKey: 'template',
+        }),
+        loadCompleteItems(scope, {
+            resource: 'emailSequences',
+            idKey: 'sequenceId',
+            detailKey: 'sequence',
+        }),
+    ]);
+    await replaceEmailFiles({
+        sourceDir: scope.sourceDir,
+        templates,
+        sequences,
+    });
+    return { templates: templates.length, sequences: sequences.length };
+}
+export const executeEmailValidate = (input) => readEmailFiles(input.sourceDir);
+export async function executeEmailPush(scope) {
+    const files = await readEmailFiles(scope.sourceDir);
+    assertValidFiles(files);
+    await Promise.all([
+        assertRemoteIdentities(scope, {
+            resource: 'emailTemplates',
+            local: files.templates,
+        }),
+        assertRemoteIdentities(scope, {
+            resource: 'emailSequences',
+            local: files.sequences,
+        }),
+    ]);
+    for (const template of files.templates) {
+        if (template.id) {
+            await scope.callApi({
+                path: 'emailTemplates.updateDraft',
+                type: 'mutation',
+                token: scope.token,
+                data: {
+                    ...projectData(scope),
+                    templateId: template.id,
+                    name: template.name,
+                    draft: template.draft,
+                },
+            });
+            continue;
+        }
+        const created = await scope.callApi({
+            path: 'emailTemplates.create',
+            type: 'mutation',
+            token: scope.token,
+            data: {
+                ...projectData(scope),
+                slug: template.slug,
+                name: template.name,
+                draft: template.draft,
+            },
+        });
+        template.id = assertCreatedId(created, 'email template');
+        await writeEmailTemplateFile(scope.sourceDir, template);
+    }
+    for (const sequence of files.sequences) {
+        if (sequence.id) {
+            await scope.callApi({
+                path: 'emailSequences.updateDraft',
+                type: 'mutation',
+                token: scope.token,
+                data: {
+                    ...projectData(scope),
+                    sequenceId: sequence.id,
+                    name: sequence.name,
+                    draft: sequence.draft,
+                },
+            });
+            continue;
+        }
+        const created = await scope.callApi({
+            path: 'emailSequences.create',
+            type: 'mutation',
+            token: scope.token,
+            data: {
+                ...projectData(scope),
+                slug: sequence.slug,
+                name: sequence.name,
+                draft: sequence.draft,
+            },
+        });
+        sequence.id = assertCreatedId(created, 'email sequence');
+        await writeEmailSequenceFile(scope.sourceDir, sequence);
+    }
+    await writeEmailFiles({
+        sourceDir: scope.sourceDir,
+        templates: files.templates,
+        sequences: files.sequences,
+    });
+    return { templates: files.templates.length, sequences: files.sequences.length };
+}
+export async function executeEmailTemplatePublish(scope) {
+    return executeEmailPublish(scope, {
+        kind: 'template',
+        resource: 'emailTemplates',
+        idKey: 'templateId',
+    });
+}
+export async function executeEmailSequencePublish(scope) {
+    return executeEmailPublish(scope, {
+        kind: 'sequence',
+        resource: 'emailSequences',
+        idKey: 'sequenceId',
+    });
+}
+const executeEmailPublish = async (scope, input) => {
+    const files = await readEmailFiles(scope.sourceDir);
+    assertValidFiles(files);
+    const resources = input.kind === 'template' ? files.templates : files.sequences;
+    const resource = resources.find((item) => item.slug === scope.slug);
+    if (!resource)
+        throw new Error(`Email ${input.kind} "${scope.slug}" was not found locally.`);
+    if (!resource.id)
+        throw new Error(`Push email ${input.kind} "${scope.slug}" before publishing it.`);
+    const remote = await assertRemoteIdentities(scope, {
+        resource: input.resource,
+        local: [resource],
+    });
+    let remoteResource = remote.get(resource.id);
+    if (remoteResource && !hasDraft(remoteResource)) {
+        const detailKey = input.kind;
+        const detail = await scope.callApi({
+            path: `${input.resource}.get`,
+            type: 'query',
+            token: scope.token,
+            data: {
+                ...projectData(scope),
+                [input.idKey]: resource.id,
+            },
+        });
+        remoteResource = assertRemoteResource(detail[detailKey], input.resource);
+    }
+    if (!remoteResource
+        || canonicalResource(input.kind, resource)
+            !== canonicalResource(input.kind, remoteResource)) {
+        throw new Error(`Run \`fgrove email push\` before publishing ${input.kind} "${scope.slug}".`);
+    }
+    return scope.callApi({
+        path: `${input.resource}.publish`,
+        type: 'mutation',
+        token: scope.token,
+        data: {
+            ...projectData(scope),
+            [input.idKey]: resource.id,
+        },
+    });
+};

package/dist/emailFiles.d.ts

@@ -0,0 +1,52 @@
+import { type FunnelValidationDiagnostic } from './diagnosticOutput.js';
+export type EmailTemplateVariableType = 'string' | 'number' | 'boolean';
+export type EmailEventType = 'email_captured' | 'purchase_completed' | 'registration_completed';
+export type EmailTemplateDraft = {
+    subject: string;
+    previewText: string | null;
+    html: string;
+    text: string;
+    variables: Record<string, EmailTemplateVariableType>;
+};
+export type EmailTemplateFile = {
+    id: string | null;
+    slug: string;
+    name: string;
+    draft: EmailTemplateDraft;
+};
+export type EmailSequenceStep = {
+    key: string;
+    delaySeconds: number;
+    templateVersionId: string;
+};
+export type EmailSequenceDraft = {
+    triggerEventType: EmailEventType;
+    funnelIds: string[];
+    steps: EmailSequenceStep[];
+    exitEventTypes: EmailEventType[];
+};
+export type EmailSequenceFile = {
+    id: string | null;
+    slug: string;
+    name: string;
+    draft: EmailSequenceDraft;
+};
+export type EmailFilesResult = {
+    valid: boolean;
+    diagnostics: FunnelValidationDiagnostic[];
+    templates: EmailTemplateFile[];
+    sequences: EmailSequenceFile[];
+};
+export declare function readEmailFiles(sourceDir: string): Promise<EmailFilesResult>;
+export declare function writeEmailTemplateFile(sourceDir: string, template: EmailTemplateFile): Promise<void>;
+export declare function writeEmailSequenceFile(sourceDir: string, sequence: EmailSequenceFile): Promise<void>;
+export declare function writeEmailFiles(input: {
+    sourceDir: string;
+    templates: EmailTemplateFile[];
+    sequences: EmailSequenceFile[];
+}): Promise<void>;
+export declare function replaceEmailFiles(input: {
+    sourceDir: string;
+    templates: EmailTemplateFile[];
+    sequences: EmailSequenceFile[];
+}): Promise<void>;