@sendinel/mcp-server 1.0.31 → 1.0.33

package/build/tools/campaign-sets.js

@@ -0,0 +1,327 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import Anthropic from '@anthropic-ai/sdk';
+import { db } from '../db.js';
+import { getProjectId } from '../project.js';
+import { checkPlanLimit } from '../plan-limits.js';
+import { validateTemplate } from '../lib/voice.js';
+import { approvalExcerpt, assertChannelCanExecute, checkApproval, currentChannelContext, requestApproval } from '../lib/action-approvals.js';
+import { generateEmailFromBrief } from '../lib/email-generation.js';
+import { fireWebhookEvent } from '../lib/webhook-events.js';
+import { logAudit } from '../audit.js';
+import { applyCampaignTargetingFields } from './campaigns.js';
+/**
+ * Campaign sets (#3669): build a whole set of triggered campaigns as drafts in one call, then
+ * activate the set behind one human approval. Built for Cyber Wingman's lifecycle emails
+ * (trial and onboarding events), generic for any project.
+ *
+ * - create_campaign_set writes drafts only. Drafts send nothing, so it needs no approval.
+ * - activate_campaigns asks for one approval covering every campaign's exact content, and the
+ *   approval_id-only call refuses if anything changed after approval.
+ */
+const txt = (text) => ({ content: [{ type: 'text', text }] });
+const j = (data) => txt(JSON.stringify(data, null, 2));
+const EmailInput = z.object({
+    subject: z.string().min(1).max(300).optional().describe('Subject line. Required with body_html; overrides the drafted subject with brief.'),
+    body_html: z.string().min(1).optional().describe('Finished HTML. Use this or brief.'),
+    brief: z.string().min(10).max(4000).optional().describe('What this email should say; drafted in the brand voice. Use this or body_html.'),
+    body_text: z.string().optional(),
+    delay_days: z.number().int().min(0).max(365).optional().default(0).describe('Wait after the previous email (or after the trigger, for the first).'),
+    delay_hours: z.number().int().min(0).max(23).optional().default(0),
+});
+const CampaignInput = z.object({
+    name: z.string().min(1).max(200),
+    trigger_event_name: z.string().min(1).max(120).optional().describe('Event name sent to POST /v1/events that starts this campaign for a contact.'),
+    trigger_tag: z.string().min(1).max(120).optional().describe('Or: a tag that starts it when added to a contact.'),
+    send_class: z.enum(['broadcast', 'product']).optional().describe('product for account, trial and onboarding email; broadcast for marketing.'),
+    description: z.string().max(1000).optional(),
+    emails: z.array(EmailInput).min(1).max(10),
+});
+/** Fingerprint of everything an approver saw: triggers and every email's exact content. */
+export function campaignSetContentHash(campaigns, steps) {
+    const ordered = [...campaigns].sort((a, b) => a.id.localeCompare(b.id)).map((c) => ({
+        id: c.id,
+        trigger_event_name: c.trigger_event_name,
+        trigger_tag: c.trigger_tag,
+        send_class: c.send_class,
+        site_id: c.site_id,
+        steps: steps
+            .filter((s) => s.campaign_id === c.id)
+            .sort((a, b) => a.step_order - b.step_order || String(a.variant_label).localeCompare(String(b.variant_label)))
+            .map((s) => [s.step_order, s.variant_label ?? 'A', s.subject, s.body_html ?? '', s.body_text ?? '', s.delay_days ?? 0, s.delay_hours ?? 0]),
+    }));
+    return createHash('sha256').update(JSON.stringify(ordered)).digest('hex');
+}
+function previewOf(campaigns, steps) {
+    return campaigns.map((c) => ({
+        campaign_id: c.id,
+        name: c.name,
+        status: c.status,
+        trigger: c.trigger_event_name ? { event: c.trigger_event_name } : c.trigger_tag ? { tag: c.trigger_tag } : null,
+        send_class: c.send_class,
+        emails: steps
+            .filter((s) => s.campaign_id === c.id)
+            .sort((a, b) => a.step_order - b.step_order)
+            .map((s) => ({
+            step_order: s.step_order,
+            wait: `${s.delay_days ?? 0}d ${s.delay_hours ?? 0}h`,
+            subject: s.subject,
+            body_text: s.body_text ?? approvalExcerpt(s.body_html, 100000),
+        })),
+    }));
+}
+async function loadSet(projectId, campaignIds) {
+    const { data: campaigns, error } = await db()
+        .from('campaigns')
+        .select('id, name, status, trigger_event_name, trigger_tag, send_class, site_id')
+        .eq('project_id', projectId)
+        .in('id', campaignIds);
+    if (error)
+        throw error;
+    const { data: steps, error: stepsError } = await db()
+        .from('campaign_steps')
+        .select('campaign_id, step_order, variant_label, subject, body_html, body_text, delay_days, delay_hours')
+        .in('campaign_id', campaignIds);
+    if (stepsError)
+        throw stepsError;
+    return { campaigns: (campaigns ?? []), steps: (steps ?? []) };
+}
+export function registerCampaignSetTools(server) {
+    server.registerTool('create_campaign_set', {
+        title: 'Create Campaign Set',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        description: 'Create several triggered campaigns (for example trial and onboarding emails) as drafts in one call, and get back a preview of every campaign: its trigger, and each email\'s subject and text. Drafts send nothing. Show the preview to a person, then use activate_campaigns to turn the set on behind one approval. Emails can use {{first_name}} and event data as {{ctx.field}}.',
+        inputSchema: {
+            campaigns: z.array(CampaignInput).min(1).max(20),
+            site_id: z.string().uuid().optional().describe('Sender. Optional when the project has exactly one sender.'),
+        },
+    }, async ({ campaigns, site_id }) => {
+        const projectId = getProjectId();
+        // Sender: the given one, or the only one. Never guessed between several.
+        const { data: sites, error: sitesErr } = await db().from('sites').select('id, name, from_email, unsub_link_enabled').eq('project_id', projectId);
+        if (sitesErr)
+            return j({ error: sitesErr.message, code: 'SITE_LOOKUP_FAILED' });
+        const site = site_id ? (sites ?? []).find((s) => s.id === site_id) : (sites?.length === 1 ? sites[0] : null);
+        if (!site) {
+            return j({
+                error: site_id ? 'Site not found in this project.' : 'This project has more than one sender. Pass site_id.',
+                code: site_id ? 'SITE_NOT_FOUND' : 'SITE_REQUIRED',
+                sites: (sites ?? []).map((s) => ({ id: s.id, name: s.name, from_email: s.from_email })),
+            });
+        }
+        // Check everything before writing anything: one trigger per campaign, content per email.
+        const problems = [];
+        campaigns.forEach((c, i) => {
+            if (Boolean(c.trigger_event_name) === Boolean(c.trigger_tag))
+                problems.push(`campaigns[${i}] "${c.name}": give exactly one of trigger_event_name or trigger_tag.`);
+            c.emails.forEach((e, k) => {
+                if (Boolean(e.brief) === Boolean(e.body_html))
+                    problems.push(`campaigns[${i}].emails[${k}]: give exactly one of brief or body_html.`);
+                if (e.body_html && !e.subject)
+                    problems.push(`campaigns[${i}].emails[${k}]: subject is required with body_html.`);
+            });
+        });
+        if (problems.length)
+            return j({ error: 'Nothing was created. Fix these first.', code: 'INVALID_SET', problems });
+        const limit = await checkPlanLimit('active_campaigns');
+        if (!limit.allowed) {
+            return j({ error: `Campaign limit reached (${limit.current}/${limit.limit}). Upgrade your plan for more campaigns.`, code: 'PLAN_LIMIT' });
+        }
+        // Draft any briefs, then validate every email.
+        const needsAi = campaigns.some((c) => c.emails.some((e) => e.brief));
+        const apiKey = process.env.ANTHROPIC_API_KEY;
+        if (needsAi && !apiKey)
+            return j({ error: 'ANTHROPIC_API_KEY not configured', code: 'AI_NOT_CONFIGURED' });
+        const anthropic = needsAi ? new Anthropic({ apiKey: apiKey }) : null;
+        const footerAdded = site.unsub_link_enabled !== false;
+        const drafted = [];
+        for (let i = 0; i < campaigns.length; i++) {
+            const out = [];
+            for (let k = 0; k < campaigns[i].emails.length; k++) {
+                const e = campaigns[i].emails[k];
+                let email;
+                if (e.brief) {
+                    try {
+                        const g = await generateEmailFromBrief(anthropic, projectId, site.id, e.brief);
+                        email = { subject: e.subject ?? g.subject, body_html: g.body_html, body_text: g.body_text, blocks: g.blocks, delay_days: e.delay_days ?? 0, delay_hours: e.delay_hours ?? 0 };
+                    }
+                    catch (error) {
+                        return j({ error: `Nothing was created. Drafting campaigns[${i}].emails[${k}] failed: ${error instanceof Error ? error.message : String(error)}`, code: 'DRAFT_FAILED' });
+                    }
+                }
+                else {
+                    email = { subject: e.subject, body_html: e.body_html, body_text: e.body_text ?? null, blocks: null, delay_days: e.delay_days ?? 0, delay_hours: e.delay_hours ?? 0 };
+                }
+                const check = validateTemplate(email.body_html, null, { subject: email.subject, bodyText: email.body_text ?? undefined });
+                // The send step appends the unsubscribe footer for this sender, so a body without a link is fine.
+                const blocking = check.errors.filter((msg) => !(footerAdded && msg.startsWith('Missing unsubscribe link')));
+                if (blocking.length)
+                    problems.push(...blocking.map((msg) => `campaigns[${i}].emails[${k}] "${email.subject}": ${msg}`));
+                out.push(email);
+            }
+            drafted.push(out);
+        }
+        if (problems.length)
+            return j({ error: 'Nothing was created. Fix these first.', code: 'INVALID_SET', problems });
+        // Write the drafts.
+        const setId = randomUUID();
+        const createdIds = [];
+        for (let i = 0; i < campaigns.length; i++) {
+            const c = campaigns[i];
+            const insertPayload = {
+                project_id: projectId,
+                site_id: site.id,
+                name: c.name,
+                type: 'triggered',
+                status: 'draft',
+                description: c.description ?? null,
+                requires_approval: true,
+                ...(c.send_class ? { send_class: c.send_class } : {}),
+                metadata: { source: 'mcp_create_campaign_set', campaign_set_id: setId },
+            };
+            const targetingError = await applyCampaignTargetingFields(insertPayload, { trigger_event_name: c.trigger_event_name ?? null, trigger_tag: c.trigger_tag ?? null }, projectId);
+            if (targetingError)
+                return j({ error: targetingError, code: 'INVALID_FIELD', campaign: c.name, created_before_failure: createdIds });
+            const { data: campaign, error } = await db().from('campaigns').insert(insertPayload).select('id').single();
+            if (error || !campaign)
+                return j({ error: error?.message ?? 'Failed to create campaign', code: 'CAMPAIGN_CREATE_FAILED', campaign: c.name, created_before_failure: createdIds });
+            createdIds.push(campaign.id);
+            const rows = drafted[i].map((e, k) => ({
+                campaign_id: campaign.id,
+                step_order: k,
+                subject: e.subject,
+                body_html: e.body_html,
+                body_text: e.body_text,
+                blocks: e.blocks,
+                delay_days: e.delay_days,
+                delay_hours: e.delay_hours,
+                variant_label: 'A',
+            }));
+            const { error: stepError } = await db().from('campaign_steps').insert(rows);
+            if (stepError)
+                return j({ error: stepError.message, code: 'STEP_CREATE_FAILED', campaign: c.name, created_before_failure: createdIds });
+        }
+        await logAudit({ action: 'campaign.set_created', resourceType: 'campaign_set', resourceId: setId, details: { campaign_ids: createdIds, site_id: site.id, source: 'mcp' } }).catch(() => { });
+        let preview;
+        try {
+            const loaded = await loadSet(projectId, createdIds);
+            preview = previewOf(loaded.campaigns, loaded.steps);
+        }
+        catch (error) {
+            return j({ campaign_set_id: setId, campaign_ids: createdIds, status: 'draft', warning: `Created, but the preview could not be read back: ${error instanceof Error ? error.message : String(error)}` });
+        }
+        return j({
+            campaign_set_id: setId,
+            campaign_ids: createdIds,
+            status: 'draft',
+            site: { id: site.id, name: site.name, from_email: site.from_email },
+            campaigns: preview,
+            next: 'These are drafts and send nothing. Show the person every subject and text exactly as above. To turn them on, call activate_campaigns with campaign_set_id (or campaign_ids); it returns one approval for the whole set.',
+        });
+    });
+    server.registerTool('activate_campaigns', {
+        title: 'Activate Campaigns',
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+        description: 'Turn on a set of draft or paused campaigns behind one human approval. Call 1: give campaign_set_id or campaign_ids; it returns one approval_id with a summary of every campaign, and activates nothing. After a person approves (approve_url works on a phone), call again with only approval_id. It refuses if any campaign or email changed after approval.',
+        inputSchema: {
+            campaign_set_id: z.string().uuid().optional(),
+            campaign_ids: z.array(z.string().uuid()).min(1).max(50).optional(),
+            approval_id: z.string().uuid().optional().describe('Call 2 only: the approved approval_id. Pass nothing else.'),
+        },
+    }, async (args) => {
+        const projectId = getProjectId();
+        const { approval_id } = args;
+        if (approval_id) {
+            const extras = Object.entries(args).filter(([key, value]) => key !== 'approval_id' && value !== undefined).map(([key]) => key);
+            if (extras.length)
+                return j({ error: `Call activate_campaigns with only approval_id. Remove: ${extras.join(', ')}.`, code: 'APPROVAL_CALL_TAKES_ONLY_APPROVAL_ID' });
+            const { data: row, error: rowErr } = await db().from('action_approvals').select('params').eq('id', approval_id).eq('project_id', projectId).eq('action', 'activate_campaigns').maybeSingle();
+            if (rowErr)
+                return j({ error: rowErr.message, code: 'APPROVAL_LOOKUP_FAILED' });
+            if (!row)
+                return txt(`Approval ${approval_id} is not_found. Request a new approval.`);
+            const stored = (row.params ?? {});
+            const ids = Array.isArray(stored.campaign_ids) ? stored.campaign_ids : [];
+            // Check before consuming: what is live now must be exactly what was approved.
+            let current;
+            try {
+                current = await loadSet(projectId, ids);
+            }
+            catch (error) {
+                return j({ error: `Could not load the campaigns: ${error instanceof Error ? error.message : String(error)}`, code: 'SET_LOOKUP_FAILED' });
+            }
+            if (current.campaigns.length !== ids.length || campaignSetContentHash(current.campaigns, current.steps) !== stored.content_hash) {
+                return j({ error: 'A campaign or email changed (or was deleted) after approval. Nothing was activated. Request a new approval.', code: 'CONTENT_CHANGED_SINCE_APPROVAL' });
+            }
+            const check = await checkApproval(approval_id, { consume: true, action: 'activate_campaigns', params: stored });
+            if (!check.approved)
+                return txt(`Approval ${approval_id} is ${check.status}. ${check.status === 'pending' ? 'Waiting for human approval via dashboard.' : 'Request a new approval.'}`);
+            const activated = [];
+            const failed = [];
+            for (const c of current.campaigns) {
+                const { error } = await db()
+                    .from('campaigns')
+                    .update({ status: 'active', updated_at: new Date().toISOString() })
+                    .eq('id', c.id)
+                    .eq('project_id', projectId)
+                    .in('status', ['draft', 'paused']);
+                if (error) {
+                    failed.push({ campaign_id: c.id, error: error.message });
+                    continue;
+                }
+                activated.push(c.id);
+                fireWebhookEvent('campaign.activated', { campaign_id: c.id, campaign_name: c.name, status: 'active' }).catch(() => { });
+            }
+            await logAudit({ action: 'campaign.set_activated', resourceType: 'campaign_set', resourceId: approval_id, details: { approval_id, decided_by: check.decided_by ?? null, activated, failed, source: 'mcp' } }).catch(() => { });
+            return j({
+                activated,
+                failed,
+                message: failed.length
+                    ? `Activated ${activated.length} of ${ids.length}. ${failed.length} could not be activated; see failed.`
+                    : `Activated ${activated.length} campaign${activated.length === 1 ? '' : 's'}. Each sends when its trigger fires for a contact who can get it.`,
+            });
+        }
+        // Call 1: build one approval for the exact set.
+        let ids = args.campaign_ids ?? [];
+        if (args.campaign_set_id) {
+            const { data, error } = await db().from('campaigns').select('id').eq('project_id', projectId).eq('metadata->>campaign_set_id', args.campaign_set_id);
+            if (error)
+                return j({ error: error.message, code: 'SET_LOOKUP_FAILED' });
+            ids = [...new Set([...ids, ...(data ?? []).map((r) => r.id)])];
+        }
+        if (!ids.length)
+            return j({ error: 'Give campaign_set_id or campaign_ids.', code: 'CAMPAIGNS_REQUIRED' });
+        let set;
+        try {
+            set = await loadSet(projectId, ids);
+        }
+        catch (error) {
+            return j({ error: `Could not load the campaigns: ${error instanceof Error ? error.message : String(error)}`, code: 'SET_LOOKUP_FAILED' });
+        }
+        const missing = ids.filter((id) => !set.campaigns.some((c) => c.id === id));
+        if (missing.length)
+            return j({ error: 'Some campaigns were not found in this project.', code: 'NOT_FOUND', missing });
+        const notReady = set.campaigns.filter((c) => !['draft', 'paused'].includes(c.status));
+        if (notReady.length)
+            return j({ error: 'Only draft or paused campaigns can be activated here.', code: 'NOT_ACTIVATABLE', campaigns: notReady.map((c) => ({ id: c.id, name: c.name, status: c.status })) });
+        const empty = set.campaigns.filter((c) => !set.steps.some((s) => s.campaign_id === c.id));
+        if (empty.length)
+            return j({ error: 'Some campaigns have no emails yet.', code: 'NO_EMAILS', campaigns: empty.map((c) => ({ id: c.id, name: c.name })) });
+        const approvalParams = { campaign_ids: [...ids].sort(), content_hash: campaignSetContentHash(set.campaigns, set.steps) };
+        const channelContext = currentChannelContext();
+        const decision = assertChannelCanExecute('activate_campaigns', approvalParams, channelContext);
+        if (!decision.allowed)
+            return txt(decision.reason ?? 'This channel cannot request this action.');
+        const names = set.campaigns.map((c) => c.name);
+        const approval = await requestApproval('activate_campaigns', approvalParams, undefined, channelContext, {
+            campaign_count: set.campaigns.length,
+            email_count: set.steps.length,
+            campaign_names: names.slice(0, 10).join(', ') + (names.length > 10 ? `, and ${names.length - 10} more` : ''),
+        });
+        return j({
+            ...approval,
+            campaigns: previewOf(set.campaigns, set.steps),
+            next: 'Show the person the campaigns above and approve_url. After approval, call activate_campaigns with only approval_id.',
+        });
+    });
+}

package/build/tools/campaigns.d.ts

@@ -1,2 +1,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function applyCampaignTargetingFields(updates: Record<string, unknown>, input: {
+    trigger_event_name?: string | null;
+    trigger_tag?: string | null;
+    trigger_type?: string | null;
+    trigger_config?: Record<string, unknown> | null;
+    segment_id?: string | null;
+}, projectId: string): Promise<string | null>;
 export declare function registerCampaignTools(server: McpServer): void;