@sendinel/mcp-server 1.0.48 → 1.0.49

package/build/tools/campaigns.d.ts

@@ -1,4 +1,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Plain-language answer to "what will this campaign actually fire on?", from a saved campaign
+ * row. Includes a warning when the campaign cannot fire yet (#3855).
+ */
+export declare function buildCampaignFiresOn(campaign: Record<string, unknown>): string;
 export declare function applyCampaignTargetingFields(updates: Record<string, unknown>, input: {
     trigger_event_name?: string | null;
     trigger_tag?: string | null;

package/build/tools/campaigns.js

@@ -51,6 +51,45 @@ function buildCampaignTriggerConfig(value) {
         return null;
     return { events, tags, ...(Object.keys(where).length ? { where } : {}) };
 }
+/**
+ * Plain-language answer to "what will this campaign actually fire on?", from a saved campaign
+ * row. Includes a warning when the campaign cannot fire yet (#3855).
+ */
+export function buildCampaignFiresOn(campaign) {
+    const config = (campaign.trigger_config && typeof campaign.trigger_config === 'object' ? campaign.trigger_config : {});
+    const events = normalizeTriggerList([...normalizeTriggerList(config.events), campaign.trigger_event_name]);
+    const tags = normalizeTriggerList([...normalizeTriggerList(config.tags), campaign.trigger_tag]);
+    const parts = [];
+    if (campaign.trigger_type === 'date_field') {
+        const field = typeof config.field === 'string' && config.field ? config.field : null;
+        const days = Number(config.days_before ?? 0) || 0;
+        parts.push(field
+            ? `${days} day(s) before contact field "${field}" (${config.recurring === false ? 'once' : 'recurring'})`
+            : 'a contact date field, but no field is set (it will never fire)');
+    }
+    else if (campaign.trigger_type === 'contact_event') {
+        const name = typeof config.event_type === 'string' ? config.event_type : null;
+        parts.push(name
+            ? `${Number(config.days_after ?? 0) || 0} day(s) after event "${name}"`
+            : 'a contact event, but no event is set (it will never fire)');
+    }
+    if (events.length)
+        parts.push(`event${events.length > 1 ? 's' : ''} ${events.map((e) => `"${e}"`).join(', ')} sent to /v1/events`);
+    if (tags.length)
+        parts.push(`tag${tags.length > 1 ? 's' : ''} ${tags.map((t) => `"${t}"`).join(', ')} added`);
+    if (campaign.segment_id)
+        parts.push('contacts entering its segment');
+    let summary = parts.length ? `Fires on: ${parts.join('; ')}.` : 'Fires on: nothing (no trigger set).';
+    const warnings = [];
+    if ((events.length || tags.length) && campaign.type !== 'triggered') {
+        warnings.push(`event and tag triggers only start campaigns of type "triggered"; this one is "${String(campaign.type)}"`);
+    }
+    if (campaign.status !== 'active')
+        warnings.push(`it is ${String(campaign.status)}, so nothing starts until it is active`);
+    if (warnings.length)
+        summary += ` Warning: ${warnings.join('; ')}.`;
+    return summary;
+}
 function applyCampaignSendAtField(updates, sendAt, campaignType) {
     if (sendAt === undefined)
         return null;
@@ -71,6 +110,13 @@ export async function applyCampaignTargetingFields(updates, input, projectId) {
         updates.trigger_event_name = input.trigger_event_name?.trim() || null;
     if (input.trigger_tag !== undefined)
         updates.trigger_tag = input.trigger_tag?.trim().toLowerCase() || null;
+    if (input.trigger_type === null || input.trigger_type === 'manual') {
+        // campaigns.trigger_type is NOT NULL DEFAULT 'manual', so "clear" means back to 'manual'.
+        // Also drops a stale date_field config unless the caller sent a new trigger_config (#3855).
+        updates.trigger_type = 'manual';
+        if (input.trigger_config === undefined)
+            updates.trigger_config = null;
+    }
     if (input.trigger_type === 'date_field') {
         const config = input.trigger_config ?? {};
         const field = typeof config.field === 'string' ? config.field.trim() : '';
@@ -3143,7 +3189,7 @@ Return ONLY valid JSON with this exact shape:
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Update a campaign name, site, segment, send time, topic, trigger settings, or send class (broadcast vs product). send_at schedules a broadcast send (type=broadcast only) and must be a future ISO 8601 instant; set null to clear a pending schedule. Only provided fields are updated.',
+        description: 'Update a campaign name, site, segment, send time, topic, trigger settings, or send class (broadcast vs product). trigger_type null (or manual) clears a date_field trigger; type switches a draft between sequence and triggered. The response includes fires_on, a plain summary of what the saved campaign fires on. send_at schedules a broadcast send (type=broadcast only) and must be a future ISO 8601 instant; set null to clear a pending schedule. Only provided fields are updated.',
         inputSchema: {
             campaign_id: z.string().uuid(),
             name: z.string().min(1).max(200).optional(),
@@ -3153,33 +3199,50 @@ Return ONLY valid JSON with this exact shape:
             topic: z.string().nullable().optional(),
             trigger_event_name: z.string().nullable().optional(),
             trigger_tag: z.string().nullable().optional(),
-            trigger_type: z.enum(['date_field']).nullable().optional(),
+            trigger_type: z.enum(['date_field', 'manual']).nullable().optional().describe("'date_field' fires relative to a contact date field (needs trigger_config.field). null or 'manual' clears a date_field trigger."),
             trigger_config: z.record(z.string(), z.unknown()).nullable().optional(),
+            type: z.enum(['sequence', 'triggered']).optional().describe("Switch a DRAFT campaign between 'sequence' and 'triggered'. Event and tag triggers only start campaigns of type 'triggered'."),
             sends_per_hour: z.number().int().min(1).nullable().optional().describe('Optional hourly send cap for wave sending. Set null to clear.'),
             send_in_contact_timezone: z.boolean().optional(),
             send_class: z.enum(['broadcast', 'product']).optional().describe("Who may receive it when the project's consent gate is on: 'broadcast' (default) = only contacts who opted in to marketing; 'product' = also the customer's signed-up users (onboarding, trial, account mail)."),
         },
-    }, async ({ campaign_id, name, site_id, segment_id, send_at, topic, trigger_event_name, trigger_tag, trigger_type, trigger_config, sends_per_hour, send_in_contact_timezone, send_class }) => {
+    }, async ({ campaign_id, name, site_id, segment_id, send_at, topic, trigger_event_name, trigger_tag, trigger_type, trigger_config, type, sends_per_hour, send_in_contact_timezone, send_class }) => {
         const projectId = getProjectId();
         let campaignType;
+        const loadExisting = () => db()
+            .from('campaigns')
+            .select('id, type, status')
+            .eq('id', campaign_id)
+            .eq('project_id', projectId)
+            .maybeSingle();
         if (send_at !== undefined && send_at !== null) {
-            const { data: existing, error: fetchError } = await db()
-                .from('campaigns')
-                .select('id, type')
-                .eq('id', campaign_id)
-                .eq('project_id', projectId)
-                .maybeSingle();
+            const { data: existing, error: fetchError } = await loadExisting();
             if (fetchError)
                 return j({ error: fetchError.message });
             if (!existing)
                 return j({ error: 'Campaign not found', code: 'NOT_FOUND' });
             campaignType = existing.type;
         }
+        if (type !== undefined) {
+            const { data: existing, error: fetchError } = await loadExisting();
+            if (fetchError)
+                return j({ error: fetchError.message });
+            if (!existing)
+                return j({ error: 'Campaign not found', code: 'NOT_FOUND' });
+            if (type !== existing.type) {
+                if (existing.status !== 'draft')
+                    return j({ error: `type can only be changed while the campaign is a draft (this one is ${existing.status})`, code: 'INVALID_FIELD' });
+                if (existing.type !== 'sequence' && existing.type !== 'triggered')
+                    return j({ error: `a ${existing.type} campaign cannot become ${type}`, code: 'INVALID_FIELD' });
+            }
+        }
         const updates = { updated_at: new Date().toISOString() };
         if (name !== undefined)
             updates.name = name;
         if (site_id !== undefined)
             updates.site_id = site_id;
+        if (type !== undefined)
+            updates.type = type;
         const scheduleError = applyCampaignSendAtField(updates, send_at, campaignType);
         if (scheduleError)
             return j({ error: scheduleError, code: 'INVALID_FIELD' });
@@ -3203,7 +3266,7 @@ Return ONLY valid JSON with this exact shape:
             .single();
         if (error)
             return j({ error: error.message });
-        return j(data);
+        return j({ ...data, fires_on: buildCampaignFiresOn(data) });
     });
     server.registerTool('get_campaign', {
         title: 'Get Campaign',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.48",
+  "version": "1.0.49",
   "description": "AI-controlled email operations control plane for campaigns, contacts, segments, analytics, and multi-provider sending via MCP.",
   "mcpName": "ai.sendinel/mcp-server",
   "type": "module",