@sendinel/mcp-server 1.0.114 → 1.0.116

package/build/lib/send-audience.js

@@ -1,4 +1,4 @@
-import { applySegmentRules, buildSegmentBaseQuery, chunkIds, evaluateSegmentRules, normalizeSegmentRulesToTree, readAllRows, } from '@sendinel/domain';
+import { applySegmentRules, buildSegmentBaseQuery, chunkIds, evaluateSegmentRules, hydrateEmailSendsContacts, normalizeSegmentRulesToTree, readAllRows, } from '@sendinel/domain';
 import { db } from '../db.js';
 async function loadFieldTypes(projectId) {
     const { data, error } = await db()
@@ -30,7 +30,8 @@ export async function resolveSegmentContactIds(projectId, rules) {
     if (siteContactIds && siteContactIds.length === 0)
         return [];
     const data = await readAllRows(filtered);
-    const contacts = data.filter((contact) => evaluateSegmentRules(contact, tree, fieldTypes));
+    const hydrated = await hydrateEmailSendsContacts(db(), projectId, data, tree);
+    const contacts = hydrated.filter((contact) => evaluateSegmentRules(contact, tree, fieldTypes));
     if (tree.exclude_suppressed === false || contacts.length === 0)
         return contacts.map((c) => String(c.id));
     const suppressed = await readAllRows(db().from('suppressions').select('id, email').eq('project_id', projectId));

package/build/tools/campaigns.js

@@ -31,6 +31,7 @@ import { callSendinelV1 } from '../lib/v1-client.js';
 import { countUniqueEngagementByCampaign } from '../lib/campaign-engagement.js';
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
+const ACTIVATION_APPROVAL_DESCRIPTION = 'Activation-only: requires_approval gates campaign activation. It does not stop sends of an already-active campaign or sends triggered by other paths.';
 const SENT_EMAIL_STATUSES = ['sent', 'delivered', 'opened', 'clicked', 'bounced', 'complained', 'unsubscribed'];
 function stripHtml(value) {
     return value
@@ -642,7 +643,7 @@ export function registerCampaignTools(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'List campaigns with saved trigger fields, fires_on summaries and trigger_diagnostics; optionally filter by site or status.',
+        description: 'List campaigns with saved trigger fields, fires_on summaries and trigger_diagnostics; optionally filter by site or status. ' + ACTIVATION_APPROVAL_DESCRIPTION,
         inputSchema: {
             site_id: z.string().uuid().optional(),
             period: z.string().min(1).optional().describe("Return one enrollment period in by_period; totals remain all-time."),
@@ -652,7 +653,7 @@ export function registerCampaignTools(server) {
     }, async ({ site_id, status, limit, period }) => {
         let q = db()
             .from('campaigns')
-            .select('id, site_id, name, type, status, sends_per_hour, total_enrolled, total_sent, total_opened, total_clicked, created_at, period_key, segment_id, trigger_type, trigger_event_name, trigger_tag, trigger_config, send_class, unsub_footer_template')
+            .select('id, site_id, name, type, status, sends_per_hour, total_enrolled, total_sent, total_opened, total_clicked, created_at, period_key, segment_id, trigger_type, trigger_event_name, trigger_tag, trigger_config, send_class, unsub_footer_template, requires_approval, approved_by, approved_at')
             .eq('project_id', getProjectId())
             .order('created_at', { ascending: false })
             .limit(limit ?? 25);
@@ -672,6 +673,7 @@ export function registerCampaignTools(server) {
             const { period_key: _periodKey, ...legacy } = row;
             return {
                 ...legacy,
+                requires_approval_description: ACTIVATION_APPROVAL_DESCRIPTION,
                 fires_on: buildCampaignFiresOn(row),
                 trigger_diagnostics: buildCampaignTriggerDiagnostics(row),
                 ...campaignPeriodFields(periods, period),
@@ -735,7 +737,7 @@ export function registerCampaignTools(server) {
             type: z.enum(['sequence', 'broadcast', 'triggered']),
             description: z.string().optional(),
             sends_per_hour: z.number().int().min(1).nullable().optional().describe('Optional hourly send cap for wave sending. Null or omitted sends without a campaign-specific cap.'),
-            requires_approval: z.boolean().optional().default(true),
+            requires_approval: z.boolean().optional().default(true).describe(ACTIVATION_APPROVAL_DESCRIPTION),
             trigger_event_name: z.string().optional().describe('For type=triggered: event name that fires this campaign'),
             trigger_tag: z.string().optional().describe('For type=triggered: contact tag that fires this campaign when applied'),
             trigger_type: z.enum(['date_field']).optional().describe('Set for elapsed-time triggers keyed on a contact custom_properties date field'),
@@ -773,7 +775,7 @@ export function registerCampaignTools(server) {
             .single();
         if (error)
             return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        return { content: [{ type: 'text', text: JSON.stringify({ ...data, requires_approval_description: ACTIVATION_APPROVAL_DESCRIPTION }, null, 2) }] };
     });
     const propertyConditions = z.array(z.union([
         z.object({ key: z.string(), op: z.enum(['eq', 'neq']), value: z.string() }).strict(),
@@ -849,7 +851,7 @@ export function registerCampaignTools(server) {
             idempotentHint: true,
             openWorldHint: true,
         },
-        description: 'Activate, pause, or archive a campaign. Activating requires human approval via the dashboard — call without approval_id to request one, then call again with the approved token.',
+        description: 'Activate, pause, or archive a campaign. Activating requires human approval via the dashboard — call without approval_id to request one, then call again with the approved token. ' + ACTIVATION_APPROVAL_DESCRIPTION,
         inputSchema: {
             campaign_id: z.string().uuid(),
             status: z.enum(['draft', 'active', 'paused', 'completed', 'archived']),
@@ -3558,7 +3560,7 @@ Return ONLY valid JSON with this exact shape:
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Get full campaign details including all steps, enrollment counts and saved trigger_type, trigger_event_name, trigger_tag, trigger_config (including where filter), fires_on and trigger_diagnostics. Read what event a dunning campaign fires on; use set_campaign_trigger to change it.',
+        description: 'Get full campaign details including all steps, enrollment counts and saved trigger_type, trigger_event_name, trigger_tag, trigger_config (including where filter), fires_on and trigger_diagnostics. Read what event a dunning campaign fires on; use set_campaign_trigger to change it. ' + ACTIVATION_APPROVAL_DESCRIPTION,
         inputSchema: { campaign_id: z.string().uuid(), period: z.string().min(1).optional().describe("Return results for one enrollment period; totals remain all-time.") },
     }, async ({ campaign_id, period }) => {
         const projectId = getProjectId();
@@ -3629,6 +3631,7 @@ Return ONLY valid JSON with this exact shape:
         const unresolvedCount = dlqUnresolvedCount ?? 0;
         return j({
             ...campaign,
+            requires_approval_description: ACTIVATION_APPROVAL_DESCRIPTION,
             fires_on: buildCampaignFiresOn(campaign),
             trigger_diagnostics: buildCampaignTriggerDiagnostics(campaign),
             total_sent: periods?.totals?.sent ?? sentCount ?? 0,

package/build/tools/lists.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { applySegmentRules, buildSegmentBaseQuery, evaluateSegmentRules, isSegmentRulesError, normalizeSegmentRulesToTree, readAllRows, } from '@sendinel/domain';
+import { applySegmentRules, buildSegmentBaseQuery, evaluateSegmentRules, hydrateEmailSendsContacts, isSegmentRulesError, normalizeSegmentRulesToTree, readAllRows, } from '@sendinel/domain';
 import { db } from '../db.js';
 import { getProjectId } from '../project.js';
 import { logAudit } from '../audit.js';
@@ -39,7 +39,8 @@ async function getSegmentContactIds(rules) {
         return [];
     // Paged and loud (#3674): an unpaged read stopped at 1,000 rows, and an error read as "no one".
     const data = await readAllRows(filtered);
-    const contacts = data.filter((contact) => evaluateSegmentRules(contact, tree, fieldTypes));
+    const hydrated = await hydrateEmailSendsContacts(db(), projectId, data, tree);
+    const contacts = hydrated.filter((contact) => evaluateSegmentRules(contact, tree, fieldTypes));
     let ids = contacts.map((contact) => String(contact.id));
     if (tree.exclude_suppressed !== false && ids.length > 0) {
         const suppressed = await readAllRows(db().from('suppressions').select('id, email').eq('project_id', projectId));

package/build/tools/segments.js

@@ -5,7 +5,7 @@ import { db } from '../db.js';
 import { getProjectId } from '../project.js';
 import { getAnthropicModelId } from '../anthropic-model.js';
 import { assertUsableStopReason } from '@sendinel/domain';
-import { applySegmentRules, buildSegmentBaseQuery, evaluateSegmentRules, isSegmentRulesError, normalizeSegmentRulesToTree, prepareSegmentRulesForStorage, readAllRows, } from '@sendinel/domain';
+import { applySegmentRules, buildSegmentBaseQuery, evaluateSegmentRules, hydrateEmailSendsContacts, isSegmentRulesError, normalizeSegmentRulesToTree, prepareSegmentRulesForStorage, readAllRows, } from '@sendinel/domain';
 async function loadFieldTypes(projectId) {
     const client = db();
     const scoped = typeof client.schema === 'function' ? client.schema('email') : client;
@@ -41,7 +41,8 @@ async function getSegmentContactIds(rules) {
         return [];
     // Paged and loud (#3674): an unpaged read stopped at 1,000 rows, and an error read as "no one".
     const data = await readAllRows(filtered);
-    const contacts = data.filter((contact) => evaluateSegmentRules(contact, tree, fieldTypes));
+    const hydrated = await hydrateEmailSendsContacts(db(), projectId, data, tree);
+    const contacts = hydrated.filter((contact) => evaluateSegmentRules(contact, tree, fieldTypes));
     let ids = contacts.map((c) => String(c.id));
     if (tree.exclude_suppressed !== false && ids.length > 0) {
         const suppressed = await readAllRows(db().from('suppressions').select('id, email').eq('project_id', projectId));
@@ -76,7 +77,7 @@ export function registerSegmentTools(server) {
         inputSchema: {
             name: z.string().min(1).describe('Segment name (unique per project)'),
             description: z.string().optional(),
-            rules: z.record(z.string(), z.unknown()).describe('Segment rule tree: {op:"AND"|"OR", conditions:[{field, operator, value}]} or legacy flat rules. Supported fields include lifecycle_stage, engagement_score, source, created_at, last_opened_at, last_clicked_at, introduced_by_subscriber_id, tags, custom_properties.<key>, payment.<key>. tag may be a plain string (one tag) or {values: string[], mode: "any"|"all"} to match several tags at once.'),
+            rules: z.record(z.string(), z.unknown()).describe('Segment rule tree: {op:"AND"|"OR", conditions:[{field, operator, value}]} or legacy flat rules. Supported fields include lifecycle_stage, engagement_score, source, created_at, last_opened_at, last_clicked_at, introduced_by_subscriber_id, tags, custom_properties.<key>, payment.<key>, email_sends (eq only, value: {min_count: positive integer, within_days: positive number}; at most one per segment). tag may be a plain string (one tag) or {values: string[], mode: "any"|"all"} to match several tags at once.'),
         },
     }, async ({ name, description, rules }) => {
         let storedRules;
@@ -281,7 +282,7 @@ export function registerSegmentTools(server) {
         const resp = await anthropic.messages.create({
             model: getAnthropicModelId(),
             max_tokens: 4096,
-            system: 'You translate natural language audience descriptions into a JSON segment rule tree. Return ONLY valid JSON. Format: {"op":"AND"|"OR","conditions":[conditionOrGroup],"exclude_suppressed":true}. Condition format: {"field": string, "operator":"eq|neq|gt|gte|lt|lte|contains|exists|not_exists|after|before|on_or_after|on_or_before","value": any}. Supported fields: lifecycle_stage, engagement_score, source, created_at, last_opened_at, last_clicked_at, introduced_by_subscriber_id, tags, custom_properties.<key>, payment.plan, payment.mrr_cents, payment.ltv_cents, payment.subscription_status, payment.trial_ends_at, payment.churned_at, payment.paid_at. Example: {"op":"AND","conditions":[{"field":"lifecycle_stage","operator":"eq","value":"trial"},{"field":"payment.trial_ends_at","operator":"on_or_before","value":"' + new Date(Date.now() + 7 * 86400000).toISOString() + '"}]}. Today is ' + new Date().toISOString().slice(0, 10) + '.',
+            system: 'You translate natural language audience descriptions into a JSON segment rule tree. Return ONLY valid JSON. Format: {"op":"AND"|"OR","conditions":[conditionOrGroup],"exclude_suppressed":true}. Condition format: {"field": string, "operator":"eq|neq|gt|gte|lt|lte|contains|exists|not_exists|after|before|on_or_after|on_or_before","value": any}. Supported fields: lifecycle_stage, engagement_score, source, created_at, last_opened_at, last_clicked_at, introduced_by_subscriber_id, tags, custom_properties.<key>, payment.plan, payment.mrr_cents, payment.ltv_cents, payment.subscription_status, payment.trial_ends_at, payment.churned_at, payment.paid_at, email_sends. email_sends uses eq only and value {"min_count":4,"within_days":30}; both required, at most one per segment. It counts email_log rows with non-null sent_at in the inclusive elapsed-day window through now, regardless of current status. No observed sends = zero; failed history reads are errors. Example: {"op":"AND","conditions":[{"field":"lifecycle_stage","operator":"eq","value":"trial"},{"field":"payment.trial_ends_at","operator":"on_or_before","value":"' + new Date(Date.now() + 7 * 86400000).toISOString() + '"}]}. Today is ' + new Date().toISOString().slice(0, 10) + '.',
             messages: [{ role: 'user', content: description }],
         });
         assertUsableStopReason(resp.stop_reason);

package/package.json

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