@sendinel/mcp-server 1.0.134 → 1.0.136

package/build/lib/action-approvals.js

@@ -192,6 +192,12 @@ export function buildApprovalSummary(action, params, display = {}) {
             const emails = typeof display.email_count === 'number' ? ` (${display.email_count} email${display.email_count === 1 ? '' : 's'})` : '';
             const names = display.campaign_names ? `: ${display.campaign_names}` : '';
             const warnings = display.content_warnings ? ` — Check before approving: ${display.content_warnings}` : '';
+            const broadcasts = (p.__approval_snapshot?.campaigns ?? [])
+                .filter(c => c.type === 'broadcast');
+            if (broadcasts.length) {
+                const audiences = broadcasts.map(c => `${c.name ?? c.id}: ${typeof c.recipient_count === 'number' ? c.recipient_count : 'unknown'} eligible recipients${c.audience ? ` (matched ${c.audience.matched}, not signed up for sender ${c.audience.not_signed_up_for_sender}, held back by consent ${JSON.stringify(c.audience.held_back_by_consent)})` : ''}`).join('; ');
+                return `Activate ${count} campaign${count === 1 ? '' : 's'}${emails}${names} — broadcasts enroll nobody by design; total_enrolled stays unchanged (0 until enrollment). Use send_broadcast or broadcast_to_segment to create, enroll and activate a broadcast for sending. Triggered campaigns send when their triggers fire. ${audiences}${warnings}`;
+            }
             return `Activate ${count} campaign${count === 1 ? '' : 's'}${emails}${names} — each emails contacts when its trigger fires${warnings}`;
         },
         set_campaign_trigger: (p) => `Change what starts campaign \"${display.campaign_name ?? p.campaign_id}\" from ${display.from_trigger ?? 'its current trigger'} to ${display.to_trigger ?? 'the requested trigger'}; ${typeof display.recipient_count === 'number' ? `up to ${display.recipient_count.toLocaleString('en-US')} people` : 'an unknown number of people'} may start receiving it`,

package/build/lib/approval-snapshot.d.ts

@@ -1,4 +1,20 @@
 type Params = Record<string, any>;
+/** The same segment scope, sender subscriptions and consent gate used by the send tools. */
+export declare function captureBroadcastAudience(projectId: string, campaign: Params): Promise<{
+    recipient_count: null;
+    audience: null;
+    segment?: undefined;
+    contact_ids?: undefined;
+} | {
+    segment: any;
+    contact_ids: string[];
+    recipient_count: number;
+    audience: {
+        matched: number;
+        not_signed_up_for_sender: number;
+        held_back_by_consent: Record<string, number>;
+    };
+}>;
 /** Optional display facts only. Failures must never prevent requesting or using an approval. */
 export declare function captureApprovalDisplay(action: string, params: Params, projectId: string): Promise<{
     target_name: string;

package/build/lib/approval-snapshot.js

@@ -4,6 +4,28 @@ import { readAllRows, chunkIds, scopeSegmentRulesToSite, approvalDisplayFact, pa
 import { callSendinelV1 } from './v1-client.js';
 import { adminDb, db } from '../db.js';
 import { resolveSendAudience, resolveSegmentContactIds } from './send-audience.js';
+/** The same segment scope, sender subscriptions and consent gate used by the send tools. */
+export async function captureBroadcastAudience(projectId, campaign) {
+    if (!campaign.segment_id || !campaign.site_id)
+        return { recipient_count: null, audience: null };
+    const source = db();
+    const client = typeof source.schema === 'function' ? source.schema('email') : source;
+    const { data: segment, error } = await client.from('segments').select('id, name, rules, site_id')
+        .eq('id', campaign.segment_id).eq('project_id', projectId).maybeSingle();
+    if (error || !segment)
+        throw new Error('Approval segment unavailable');
+    const resolved = await resolveSendAudience(projectId, campaign.site_id, scopeSegmentRulesToSite(segment.rules, segment.site_id), campaign.send_class === 'product' ? 'product' : 'broadcast');
+    return {
+        segment,
+        contact_ids: [...resolved.contactIds].sort(),
+        recipient_count: resolved.contactIds.length,
+        audience: {
+            matched: resolved.matched,
+            not_signed_up_for_sender: resolved.notOnSender,
+            held_back_by_consent: resolved.heldBack,
+        },
+    };
+}
 const TARGET_ACTIONS = new Set(['send_broadcast', 'broadcast_to_segment', 'launch_campaign', 'activate_campaigns',
     'update_campaign_status', 'set_campaign_trigger', 'create_campaign_with_content', 'enroll_segment',
     'send_transactional', 'send_awaiting_reply', 'send_test_email', 'send_newsletter_issue', 'schedule_newsletter_issue']);
@@ -159,7 +181,7 @@ export async function captureApprovalSnapshot(action, params, projectId) {
             typeof params.campaign_id === 'string' ? [params.campaign_id] : []).map(String))].sort();
     if (ids.length) {
         snapshot.campaigns = await readAllRows(client.from('campaigns')
-            .select('id, name, site_id, type, status, trigger_event_name, trigger_tag, trigger_type, trigger_config, send_class, total_enrolled')
+            .select('id, name, site_id, type, segment_id, status, trigger_event_name, trigger_tag, trigger_type, trigger_config, send_class, total_enrolled')
             .eq('project_id', projectId).in('id', ids));
         if (snapshot.campaigns.length !== ids.length)
             throw new Error('Approval target not found');
@@ -167,11 +189,17 @@ export async function captureApprovalSnapshot(action, params, projectId) {
             .select('id, campaign_id, step_order, variant_label, subject, body_html, body_text, delay_days, delay_hours, blocks')
             .in('campaign_id', ids));
         let count = 0;
-        for (const id of ids) {
-            const result = await client.from('campaign_enrollments').select('id', { count: 'exact', head: true }).eq('campaign_id', id);
+        for (const campaign of snapshot.campaigns) {
+            if (campaign.type === 'broadcast') {
+                Object.assign(campaign, await captureBroadcastAudience(projectId, campaign));
+                count = count == null || campaign.recipient_count == null ? null : count + campaign.recipient_count;
+                continue;
+            }
+            const result = await client.from('campaign_enrollments').select('id', { count: 'exact', head: true }).eq('campaign_id', campaign.id);
             if (result.error || result.count == null)
                 throw new Error('Approval audience count unavailable');
-            count += result.count;
+            if (count != null)
+                count += result.count;
         }
         snapshot.recipient_count = count;
     }

package/build/lib/campaign-engagement.d.ts

@@ -10,12 +10,12 @@ export declare function countUniqueEngagementByCampaign(sb: {
     delivered: Map<string, number>;
     error?: undefined;
 } | {
-    ok: false;
-    error: {
-        message: string;
-    };
     opened?: undefined;
     clicked?: undefined;
     sent?: undefined;
     delivered?: undefined;
+    ok: false;
+    error: {
+        message: string;
+    };
 }>;

package/build/plan-limits.d.ts

@@ -3,6 +3,9 @@ interface LimitCheck {
     current: number;
     limit: number;
     resource: string;
+    upgrade_url?: string | null;
 }
+/** Shared cap copy for single adds and bulk imports, without assuming a plan tier. */
+export declare function contactLimitMessage(limit: LimitCheck, newCount?: number): string;
 export declare function checkPlanLimit(resource: 'contacts' | 'monthly_sends' | 'active_campaigns' | 'sites' | 'ai_drafts'): Promise<LimitCheck>;
 export {};

package/build/plan-limits.js

@@ -1,5 +1,13 @@
 import { adminDb } from './db.js';
 import { getProjectId } from './project.js';
+/** Shared cap copy for single adds and bulk imports, without assuming a plan tier. */
+export function contactLimitMessage(limit, newCount) {
+    const usage = `(${limit.current}/${limit.limit})`;
+    const message = newCount === undefined
+        ? `Contact limit reached ${usage}.`
+        : `Import would add ${newCount} new contacts but only ${Math.max(0, limit.limit - limit.current)} slots remaining ${usage}.`;
+    return `${message} Raise your contact limit${limit.upgrade_url ? `: ${limit.upgrade_url}` : '.'}`;
+}
 export async function checkPlanLimit(resource) {
     const { data, error } = await adminDb()
         .rpc('check_plan_limit', { p_project_id: getProjectId(), p_resource: resource });

package/build/tools/campaign-sets.d.ts

@@ -8,6 +8,11 @@ type CampaignSetRow = {
     trigger_config?: unknown;
     send_class: string | null;
     site_id: string;
+    type?: string;
+    segment_id?: string | null;
+    recipient_count?: number | null;
+    audience?: Record<string, unknown> | null;
+    audience_error?: string;
 };
 type StepRow = {
     campaign_id: string;
@@ -33,6 +38,10 @@ export declare function previewOf(campaigns: CampaignSetRow[], steps: StepRow[])
         tag: string;
     } | null;
     send_class: string | null;
+    recipient_count?: number | null | undefined;
+    audience?: Record<string, unknown> | null | undefined;
+    audience_error?: string | undefined;
+    activation?: string | undefined;
     emails: {
         step_order: number;
         wait: string;

package/build/tools/campaign-sets.js

@@ -11,6 +11,7 @@ import { fireWebhookEvent } from '../lib/webhook-events.js';
 import { logAudit } from '../audit.js';
 import { applyCampaignTargetingFields } from './campaigns.js';
 import { checkCampaignContent, contentNotReadyResponse, contentWarningView, summarizeContentWarnings } from '../lib/content-sources.js';
+import { captureBroadcastAudience } from '../lib/approval-snapshot.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
@@ -38,6 +39,7 @@ const CampaignInput = z.object({
     description: z.string().max(1000).optional(),
     emails: z.array(EmailInput).min(1).max(10),
 });
+const BROADCAST_ACTIVATION = 'Activating a broadcast enrolls nobody by design; total_enrolled stays unchanged (0 until enrollment). Use send_broadcast or broadcast_to_segment to create, enroll and activate a broadcast for sending.';
 /** The event-data filter a campaign starts on, if any (#3689). */
 function triggerWhere(config) {
     if (!config || typeof config !== 'object' || Array.isArray(config))
@@ -71,6 +73,12 @@ export function previewOf(campaigns, steps) {
             ? { event: c.trigger_event_name, ...(triggerWhere(c.trigger_config) ? { only_when: triggerWhere(c.trigger_config) } : {}) }
             : c.trigger_tag ? { tag: c.trigger_tag } : null,
         send_class: c.send_class,
+        ...(c.type === 'broadcast' ? {
+            recipient_count: c.recipient_count ?? null,
+            audience: c.audience ?? null,
+            ...(c.audience_error ? { audience_error: c.audience_error } : {}),
+            activation: BROADCAST_ACTIVATION,
+        } : {}),
         emails: steps
             .filter((s) => s.campaign_id === c.id)
             .sort((a, b) => a.step_order - b.step_order)
@@ -85,7 +93,7 @@ export function previewOf(campaigns, steps) {
 export async function loadSet(projectId, campaignIds) {
     const { data: campaigns, error } = await db()
         .from('campaigns')
-        .select('id, name, status, trigger_event_name, trigger_tag, trigger_config, send_class, site_id')
+        .select('id, name, type, segment_id, status, trigger_event_name, trigger_tag, trigger_config, send_class, site_id')
         .eq('project_id', projectId)
         .in('id', campaignIds);
     if (error)
@@ -96,7 +104,20 @@ export async function loadSet(projectId, campaignIds) {
         .in('campaign_id', campaignIds);
     if (stepsError)
         throw stepsError;
-    return { campaigns: (campaigns ?? []), steps: (steps ?? []) };
+    const loaded = (campaigns ?? []).map((campaign) => ({ ...campaign }));
+    for (const campaign of loaded) {
+        if (campaign.type !== 'broadcast')
+            continue;
+        try {
+            const { recipient_count, audience } = await captureBroadcastAudience(projectId, campaign);
+            Object.assign(campaign, { recipient_count, audience });
+        }
+        catch (error) {
+            Object.assign(campaign, { recipient_count: null, audience: null,
+                audience_error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return { campaigns: loaded, steps: (steps ?? []) };
 }
 /**
  * Writes checked drafts as one campaign set. Shared by create_campaign_set and
@@ -256,7 +277,7 @@ export function registerCampaignSetTools(server) {
     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.',
+        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. Activating a broadcast enrolls nobody; use send_broadcast or broadcast_to_segment to create, enroll and activate a broadcast for sending.',
         inputSchema: {
             campaign_set_id: z.string().uuid().optional(),
             campaign_ids: z.array(z.string().uuid()).min(1).max(50).optional(),
@@ -273,7 +294,7 @@ export function registerCampaignSetTools(server) {
             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.`);
+                return j({ error: `Approval ${approval_id} is not_found. Request a new approval.`, code: 'not_found' });
             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.
@@ -293,7 +314,7 @@ export function registerCampaignSetTools(server) {
                 return j(contentNotReadyResponse(readiness.blocking));
             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.'}`);
+                return j({ error: `Approval ${approval_id} is ${check.status}. ${check.status === 'pending' ? 'Waiting for human approval via dashboard.' : 'Request a new approval.'}`, code: 'validation_failed', approval_status: check.status });
             const activated = [];
             const failed = [];
             for (const c of current.campaigns) {
@@ -314,9 +335,15 @@ export function registerCampaignSetTools(server) {
             return j({
                 activated,
                 failed,
+                ...(current.campaigns.some(c => c.type === 'broadcast') ? {
+                    campaigns: previewOf(current.campaigns.filter(c => activated.includes(c.id)).map(c => ({ ...c, status: 'active' })), current.steps),
+                    broadcast_activation: BROADCAST_ACTIVATION,
+                } : {}),
                 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.`,
+                    : current.campaigns.some(c => c.type === 'broadcast')
+                        ? `Activated ${activated.length} campaign${activated.length === 1 ? '' : 's'}. ${BROADCAST_ACTIVATION} Triggered campaigns send when their triggers fire.`
+                        : `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.
@@ -363,7 +390,7 @@ export function registerCampaignSetTools(server) {
         const channelContext = currentChannelContext();
         const decision = assertChannelCanExecute('activate_campaigns', approvalParams, channelContext);
         if (!decision.allowed)
-            return txt(decision.reason ?? 'This channel cannot request this action.');
+            return j({ error: decision.reason ?? 'This channel cannot request this action.', code: 'forbidden' });
         const names = set.campaigns.map((c) => c.name);
         const approval = await requestApproval('activate_campaigns', approvalParams, undefined, channelContext, {
             campaign_count: set.campaigns.length,

package/build/tools/contacts.js

@@ -6,7 +6,7 @@ import { z } from 'zod';
 import { callSendinelV1 } from '../lib/v1-client.js';
 import { db, projectClientForWriteback } from '../db.js';
 import { getProjectId } from '../project.js';
-import { checkPlanLimit } from '../plan-limits.js';
+import { checkPlanLimit, contactLimitMessage } from '../plan-limits.js';
 import { logConsent, logAudit } from '../audit.js';
 import { assertChannelCanExecute, currentChannelContext, requestApproval, checkApproval, withApproval } from '../lib/action-approvals.js';
 import { decrypt } from '../crypto.js';
@@ -18,6 +18,7 @@ import { AI_MAX_TOKENS, outputConfig, anthropicCheckedText } from '@sendinel/dom
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const err = (text) => ({ ...txt(text), isError: true });
 const j = (data) => txt(JSON.stringify(data, null, 2));
+const contactInputError = (code, message) => err(JSON.stringify({ code, error: message }));
 const CUSTOM_FIELD_TYPES = [
     'email', 'text', 'textarea', 'select', 'checkbox', 'number', 'tel', 'url', 'date',
     'multi_select', 'contact_reference',
@@ -1220,22 +1221,27 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
     }, async ({ email, site_id, first_name, last_name, company_id, company_name, company_domain, source, utm_source, utm_medium, utm_campaign, utm_content, utm_term }) => {
         email = email.trim().toLowerCase();
         const projectId = getProjectId();
-        const embedOk = await hasCompaniesEmbed(projectId);
-        const resolvedCompanyId = await resolveCompanyId(projectId, { company_id, company_name, company_domain });
         // Block distribution list / system addresses
         const DISTRO_LOCAL_PARTS = new Set(['all', 'everyone', 'distro', 'broadcast', 'announce', 'postmaster', 'abuse', 'mailer-daemon', 'bounce', 'bounces', 'noreply', 'no-reply', 'nobody', 'null', 'void']);
         const DISTRO_PATTERNS = [/^all[-+.]/, /[-+.]all$/, /^list[-+.]/, /[-+.]list$/, /[-+.]announce$/, /^announce[-+.]/, /[-+.]distro$/, /^distro[-+.]/, /[-+.]broadcast$/, /^broadcast[-+.]/];
         const local = email.trim().toLowerCase().split('@')[0] ?? '';
         if (DISTRO_LOCAL_PARTS.has(local) || DISTRO_PATTERNS.some(p => p.test(local))) {
-            return { content: [{ type: 'text', text: `Blocked: "${email}" looks like a group or distribution list address. Sendinel sends to individual people only.` }] };
-        }
+            return contactInputError('validation_failed', `Blocked: "${email}" looks like a group or distribution list address. Sendinel sends to individual people only.`);
+        }
+        // Validate project ownership before the cap, and reuse the double opt-in lookup.
+        const { data: siteInfo, error: siteError } = await db().from('sites')
+            .select('double_opt_in').eq('id', site_id).eq('project_id', projectId).maybeSingle();
+        if (siteError)
+            throw new Error(`Site lookup failed: ${siteError.message}`);
+        if (!siteInfo)
+            return contactInputError('not_found', 'Site not found for this project.');
+        const needsConfirm = siteInfo.double_opt_in === true;
         const limit = await checkPlanLimit('contacts');
         if (!limit.allowed) {
-            return { content: [{ type: 'text', text: `Contact limit reached (${limit.current}/${limit.limit}). Upgrade to Pro for more contacts.` }] };
+            return contactInputError('plan_limit', contactLimitMessage(limit));
         }
-        // Check if site requires double opt-in
-        const { data: siteInfo } = await db().from('sites').select('double_opt_in').eq('id', site_id).maybeSingle();
-        const needsConfirm = siteInfo?.double_opt_in === true;
+        const embedOk = await hasCompaniesEmbed(projectId);
+        const resolvedCompanyId = await resolveCompanyId(projectId, { company_id, company_name, company_domain });
         let { data: existingContact, error: lookupError } = await db()
             .from('subscribers')
             .select('id, source, first_name, last_name, company_id, custom_properties, opted_in_at')
@@ -1395,7 +1401,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             const msg = skippedDistro.length
                 ? `No valid contacts to import. ${skippedDistro.length} address(es) blocked as distribution lists: ${skippedDistro.slice(0, 5).join(', ')}`
                 : 'No valid contacts to import.';
-            return { content: [{ type: 'text', text: msg }] };
+            return contactInputError('validation_failed', msg);
         }
         // Check which already exist
         const { data: existing } = await db()
@@ -1407,9 +1413,9 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         const newCount = valid.filter(c => !existingEmails.has(c.email)).length;
         if (newCount > 0) {
             const limit = await checkPlanLimit('contacts');
-            const remaining = limit.limit - limit.current;
+            const remaining = Math.max(0, limit.limit - limit.current);
             if (newCount > remaining) {
-                return { content: [{ type: 'text', text: `Import would add ${newCount} new contacts but only ${remaining} slots remaining (${limit.current}/${limit.limit}). Upgrade to import more.` }] };
+                return contactInputError('plan_limit', contactLimitMessage(limit, newCount));
             }
         }
         const rows = valid.map(c => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.134",
+  "version": "1.0.136",
   "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",