@sendinel/mcp-server 1.0.129 → 1.0.130

package/build/lib/campaign-trigger-approval.d.ts

@@ -1,5 +1,5 @@
 type Row = Record<string, any>;
-export declare const TRIGGER_EDIT_SELECT = "id, name, type, status, trigger_type, trigger_event_name, trigger_tag, trigger_config, updated_at";
+export declare const TRIGGER_EDIT_SELECT = "id, name, type, status, trigger_type, trigger_event_name, trigger_tag, trigger_config, period_key, updated_at";
 export declare const campaignEditError: (error: string, code: string) => {
     error: string;
     code: string;

package/build/lib/campaign-trigger-approval.js

@@ -5,7 +5,7 @@ import { db } from '../db.js';
 import { getProjectId } from '../project.js';
 import { logAudit } from '../audit.js';
 import { assertChannelCanExecute, currentChannelContext, checkApproval } from './action-approvals.js';
-export const TRIGGER_EDIT_SELECT = 'id, name, type, status, trigger_type, trigger_event_name, trigger_tag, trigger_config, updated_at';
+export const TRIGGER_EDIT_SELECT = 'id, name, type, status, trigger_type, trigger_event_name, trigger_tag, trigger_config, period_key, updated_at';
 export const campaignEditError = (error, code) => ({ error, code });
 /** All writes include the revision used for the approval decision, including ungated drafts. */
 async function writeEdit(campaignId, previous, updates) {

package/build/tools/campaigns.js

@@ -1,4 +1,4 @@
-import { readCampaignPeriods, campaignPeriodFields } from "@sendinel/domain";
+import { resolveCampaignReentry, readCampaignPeriods, campaignPeriodFields } from "@sendinel/domain";
 import { CAMPAIGN_BRANCH_CONDITIONS, campaignBranchConditionValue, isContactPropertyConditionList, STEP_PROPERTY_CONDITIONS_ERROR, validateStepPropertyRules } from "@sendinel/domain";
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
@@ -32,6 +32,11 @@ 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 REENTRY_DESCRIPTION = 'Re-entry defaults to once ever. per_event_period uses a flat event-data period_key on event-triggered campaigns only. Changing a live campaign returns an approval request. Existing enrollments without a period cannot re-enter; sends wait for campaign-cycle approval.';
+const reentryFields = {
+    reentry_mode: z.enum(['once_ever', 'per_event_period']).optional().describe(REENTRY_DESCRIPTION),
+    period_key: z.string().min(1).max(64).nullable().optional().describe('Flat event-data key naming the period (starts with a letter; letters, digits and underscores only). Key alone selects per_event_period; null clears to once ever. ' + REENTRY_DESCRIPTION),
+};
 const SENT_EMAIL_STATUSES = ['sent', 'delivered', 'opened', 'clicked', 'bounced', 'complained', 'unsubscribed'];
 function stripHtml(value) {
     return value
@@ -670,9 +675,9 @@ export function registerCampaignTools(server) {
         const engagement = await countUniqueEngagementByCampaign(db(), getProjectId(), rows.map((row) => row.id));
         const withPeople = await Promise.all(rows.map(async (row) => {
             const periods = await readCampaignPeriods(db(), getProjectId(), row);
-            const { period_key: _periodKey, ...legacy } = row;
             return {
-                ...legacy,
+                ...row,
+                reentry_mode: row.period_key ? "per_event_period" : "once_ever",
                 requires_approval_description: ACTIVATION_APPROVAL_DESCRIPTION,
                 fires_on: buildCampaignFiresOn(row),
                 trigger_diagnostics: buildCampaignTriggerDiagnostics(row),
@@ -732,6 +737,7 @@ export function registerCampaignTools(server) {
         },
         description: 'Create a new email campaign. For triggered campaigns, provide one trigger shape: trigger_event_name, trigger_tag, trigger_type=date_field with trigger_config, or segment_id for ongoing audience targeting. For type=broadcast, send_at schedules the send for a future instant; the campaign must still be activated via update_campaign_status.',
         inputSchema: {
+            ...reentryFields,
             site_id: z.string().uuid(),
             name: z.string().min(1).max(200),
             type: z.enum(['sequence', 'broadcast', 'triggered']),
@@ -746,7 +752,7 @@ export function registerCampaignTools(server) {
             send_at: z.string().datetime().nullable().optional().describe('For type=broadcast only: ISO 8601 instant to schedule the send. Must be in the future. Set null for no schedule. The campaign must still be activated via update_campaign_status.'),
             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 ({ site_id, name, type, description, sends_per_hour, requires_approval, trigger_event_name, trigger_tag, trigger_type, trigger_config, segment_id, send_at, send_class }) => {
+    }, async ({ site_id, name, type, description, sends_per_hour, requires_approval, trigger_event_name, trigger_tag, trigger_type, trigger_config, segment_id, send_at, send_class, reentry_mode, period_key }) => {
         const limit = await checkPlanLimit('active_campaigns');
         if (!limit.allowed) {
             return { content: [{ type: 'text', text: `Active campaign limit reached (${limit.current}/${limit.limit}). Upgrade to Pro for unlimited campaigns.` }] };
@@ -762,6 +768,11 @@ export function registerCampaignTools(server) {
             requires_approval,
             ...(send_class ? { send_class } : {}),
         };
+        const reentry = resolveCampaignReentry({ reentry_mode, period_key }, { type, trigger_type });
+        if (!reentry.ok)
+            return j({ error: reentry.error, code: 'INVALID_FIELD' });
+        if (reentry.period_key !== undefined)
+            insertPayload.period_key = reentry.period_key;
         const scheduleError = applyCampaignSendAtField(insertPayload, send_at, type);
         if (scheduleError)
             return j({ error: scheduleError, code: 'INVALID_FIELD' });
@@ -2955,6 +2966,7 @@ Return ONLY valid JSON with this exact shape:
         },
         description: 'Create billing, dunning, trial ending or transactional mail with send_class=product (broadcast is the marketing default). Build a sequence, broadcast or triggered campaign with pre-built steps. Override unsubscribe text with unsub_footer_template. Set trigger_event_name for dunning (invoice_payment_failed, trial_ending), trigger_tag, or date_field/contact_event trigger_config; events/tags and where filters are supported. Triggered campaigns need no segment. Returns fires_on and trigger_diagnostics. Adds email steps, optionally enrolls a segment, and activates behind standard approval. Ideal for orchestrators that draft their own content — skips AI generation. Uses two-call confirmation: first call returns a preview, second call with confirmed=true executes.',
         inputSchema: {
+            ...reentryFields,
             site_id: z.string().uuid().describe('Site to send from'),
             name: z.string().min(1).max(200).describe('Campaign name'),
             type: z.enum(['sequence', 'broadcast', 'triggered']).describe('Campaign type'),
@@ -2978,7 +2990,7 @@ Return ONLY valid JSON with this exact shape:
             confirmed: z.boolean().optional().default(false).describe('Two-call confirmation. First call previews, second call with confirmed=true executes.'),
             approval_id: z.string().uuid().optional().describe('Approval token from a previous call. Required when activate=true — get this by calling once without it, then have a human approve via the dashboard.'),
         },
-    }, async ({ site_id, name, type, steps, segment_id, sends_per_hour, activate, confirmed, approval_id, trigger_event_name, trigger_tag, trigger_type, trigger_config, send_class, unsub_footer_template }) => {
+    }, async ({ site_id, name, type, steps, segment_id, sends_per_hour, activate, confirmed, approval_id, trigger_event_name, trigger_tag, trigger_type, trigger_config, send_class, unsub_footer_template, reentry_mode, period_key }) => {
         const footerTemplate = unsub_footer_template?.trim() ?? null;
         if (footerTemplate !== null) {
             const footerError = validateUnsubFooterTemplate(footerTemplate);
@@ -2994,10 +3006,15 @@ Return ONLY valid JSON with this exact shape:
         const triggerConfig = normalizeTriggerConfig(targeting.trigger_config);
         const hasEventOrTag = Boolean(targeting.trigger_event_name || targeting.trigger_tag || triggerConfig.events.length || triggerConfig.tags.length);
         const campaignType = type === 'sequence' && hasEventOrTag ? 'triggered' : type;
+        const reentry = resolveCampaignReentry({ reentry_mode, period_key }, { type: campaignType, trigger_type: targeting.trigger_type });
+        if (!reentry.ok)
+            return j({ error: reentry.error, code: 'INVALID_FIELD' });
+        if (reentry.period_key !== undefined)
+            targeting.period_key = reentry.period_key;
         const canActivateOnTrigger = campaignType === 'triggered' && (hasEventOrTag || targeting.trigger_type === 'date_field' || targeting.trigger_type === 'contact_event');
         // Human-in-the-loop gate for activation
         if (activate && confirmed) {
-            const approvalParams = { site_id, name, type, steps, segment_id, sends_per_hour, activate, send_class, unsub_footer_template, ...triggerInput };
+            const approvalParams = { site_id, name, type, steps, segment_id, sends_per_hour, activate, send_class, unsub_footer_template, reentry_mode, period_key, ...triggerInput };
             const channelContext = currentChannelContext();
             const decision = assertChannelCanExecute('create_campaign_with_content', { activate }, channelContext);
             if (!decision.allowed)
@@ -3351,6 +3368,7 @@ Return ONLY valid JSON with this exact shape:
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         description: 'Set or clear what a campaign fires on: trigger event name, tag, date_field, contact_event, or trigger_config events/tags and where event-data filter. Bind billing, payment failed, dunning or trial ending mail to an event trigger such as invoice_payment_failed or trial_ending. Drafts save directly; active/paused campaigns require standard human approval. Archived/completed campaigns cannot change. Returns saved trigger fields, fires_on and trigger_diagnostics.',
         inputSchema: {
+            ...reentryFields,
             campaign_id: z.string().uuid().optional(),
             trigger_event_name: z.string().nullable().optional(),
             trigger_tag: z.string().nullable().optional(),
@@ -3377,7 +3395,7 @@ Return ONLY valid JSON with this exact shape:
         if (!['draft', 'active', 'paused'].includes(existing.status)) {
             return j({ error: `Cannot change a ${existing.status} campaign trigger`, code: 'INVALID_STATUS' });
         }
-        const hasFields = ['trigger_event_name', 'trigger_tag', 'trigger_type', 'trigger_config']
+        const hasFields = ['trigger_event_name', 'trigger_tag', 'trigger_type', 'trigger_config', 'reentry_mode', 'period_key']
             .some((key) => args[key] !== undefined);
         if ((!args.clear && !hasFields) || (args.clear && hasFields)) {
             return j({ error: 'Provide trigger fields or clear=true, exclusively', code: 'INVALID_FIELD' });
@@ -3393,6 +3411,14 @@ Return ONLY valid JSON with this exact shape:
             && (updates.trigger_event_name || updates.trigger_tag || normalized.events.length || normalized.tags.length)) {
             updates.type = 'triggered';
         }
+        const reentry = resolveCampaignReentry(args, {
+            type: (updates.type ?? existing.type),
+            trigger_type: (updates.trigger_type ?? existing.trigger_type),
+        });
+        if (!reentry.ok)
+            return j({ error: reentry.error, code: 'INVALID_FIELD' });
+        if (reentry.period_key !== undefined)
+            updates.period_key = reentry.period_key;
         const result = await finishCampaignEdit('set_campaign_trigger', args, existing, updates, params => requestApproval('set_campaign_trigger', params));
         return j(result.error || result.requires_approval ? result : { ...result, fires_on: buildCampaignFiresOn(result), trigger_diagnostics: buildCampaignTriggerDiagnostics(result) });
     });
@@ -3406,6 +3432,7 @@ Return ONLY valid JSON with this exact shape:
         },
         description: 'Update a campaign name, site, segment, send time, topic, trigger event name/tag/config (including where filters for dunning), or send class (broadcast vs product). trigger_type null (or manual) clears a date_field or contact_event trigger; type switches a draft between sequence and triggered. The response includes fires_on, a plain summary of what the saved campaign fires on, and trigger_diagnostics naming any trigger problems. 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. Changed triggers on active/paused campaigns return an approval request; retry with only approval_id to apply the frozen edit.',
         inputSchema: {
+            ...reentryFields,
             campaign_id: z.string().uuid().optional(),
             approval_id: z.string().uuid().optional(),
             name: z.string().min(1).max(200).optional(),
@@ -3428,7 +3455,7 @@ Return ONLY valid JSON with this exact shape:
             const result = await resumeCampaignEdit('update_campaign', approval_id, input);
             return j(result.error ? result : { ...result, fires_on: buildCampaignFiresOn(result), trigger_diagnostics: buildCampaignTriggerDiagnostics(result) });
         }
-        const { 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, unsub_footer_template } = input;
+        const { 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, unsub_footer_template, reentry_mode, period_key } = input;
         if (!campaign_id)
             return j({ error: 'campaign_id is required', code: 'INVALID_FIELD' });
         if (unsub_footer_template !== undefined && unsub_footer_template !== null) {
@@ -3474,7 +3501,7 @@ Return ONLY valid JSON with this exact shape:
                     return j({ error: `a ${existing.type} campaign cannot become ${type}`, code: 'INVALID_FIELD' });
             }
         }
-        const hasTriggerUpdate = trigger_event_name !== undefined || trigger_tag !== undefined || trigger_type !== undefined || trigger_config !== undefined;
+        const hasTriggerUpdate = reentry_mode !== undefined || period_key !== undefined || trigger_event_name !== undefined || trigger_tag !== undefined || trigger_type !== undefined || trigger_config !== undefined;
         let existingCampaignForTargeting = null;
         if (hasTriggerUpdate) {
             const { data: existing, error: fetchError } = await getExisting();
@@ -3517,6 +3544,14 @@ Return ONLY valid JSON with this exact shape:
                 updates.type = 'triggered';
             }
         }
+        const reentry = resolveCampaignReentry({ reentry_mode, period_key }, {
+            type: (updates.type ?? existingCampaignForTargeting?.type),
+            trigger_type: (updates.trigger_type ?? existingCampaignForTargeting?.trigger_type),
+        });
+        if (!reentry.ok)
+            return j({ error: reentry.error, code: 'INVALID_FIELD' });
+        if (reentry.period_key !== undefined)
+            updates.period_key = reentry.period_key;
         let data;
         if (existingCampaignForTargeting) {
             data = await finishCampaignEdit('update_campaign', input, existingCampaignForTargeting, updates, params => requestApproval('update_campaign', params));
@@ -3620,6 +3655,7 @@ Return ONLY valid JSON with this exact shape:
         const unresolvedCount = dlqUnresolvedCount ?? 0;
         return j({
             ...campaign,
+            reentry_mode: campaign.period_key ? "per_event_period" : "once_ever",
             requires_approval_description: ACTIVATION_APPROVAL_DESCRIPTION,
             fires_on: buildCampaignFiresOn(campaign),
             trigger_diagnostics: buildCampaignTriggerDiagnostics(campaign),

package/package.json

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