@sendinel/mcp-server 1.0.154 → 1.0.156

package/build/lib/action-approvals.d.ts

@@ -97,14 +97,9 @@ type ToolResult = {
         text: string;
     }>;
 };
-/**
- * Wrap a tool handler in the standard approval flow (#4005). In standard mode the first call
- * (no approval_id) records the exact arguments and returns the approval request without running
- * the handler; the follow-up call with an approved approval_id runs the handler on those same
- * arguments. getApprovalTier() decides when no approval is needed (autonomous mode, special
- * cases), so autonomous mode and send_broadcast's never-self-approves rule live in one place.
- * Add `approval_id: z.string().uuid().optional()` to the tool's inputSchema.
- */
+export declare function markNotExecuted<R extends object>(result: R): R;
+/** HTTP statuses that mean the request was refused before it changed anything. */
+export declare function isPreExecutionStatus(status: number | undefined): boolean;
 export declare function withApproval<A extends object, R extends ToolResult>(action: string, handler: (args: A, extra?: unknown) => Promise<R> | R, options?: {
     display?: (args: A) => Promise<ApprovalDisplay> | ApprovalDisplay;
     registeredRequestOnly?: boolean;

package/build/lib/action-approvals.js

@@ -472,7 +472,7 @@ export async function checkApproval(approvalId, options = {}) {
         approved: true,
         status: 'approved',
         decided_by: claimed.decided_by,
-        ...(options.action === 'send_test_email' ? { consumed_at: consumedAt } : {}),
+        ...(options.action && ['send_test_email', 'identify_subscriber', 'emit_contact_event'].includes(options.action) ? { consumed_at: consumedAt } : {}),
         ...(sandboxDecision ? { decision_channel: 'sandbox' } : {}),
     };
 }
@@ -487,6 +487,19 @@ function toolText(value) {
  * cases), so autonomous mode and send_broadcast's never-self-approves rule live in one place.
  * Add `approval_id: z.string().uuid().optional()` to the tool's inputSchema.
  */
+/**
+ * Results a handler marks as "definitively did nothing" (refused or failed before any write or send).
+ * withApproval releases the consumed approval for these, so a failed call does not use up the pass.
+ */
+const notExecutedResults = new WeakSet();
+export function markNotExecuted(result) {
+    notExecutedResults.add(result);
+    return result;
+}
+/** HTTP statuses that mean the request was refused before it changed anything. */
+export function isPreExecutionStatus(status) {
+    return status !== undefined && [0, 400, 401, 403, 404, 422, 429, 501].includes(status);
+}
 export function withApproval(action, handler, options = {}) {
     return async (args, extra) => {
         const { approval_id, ...params } = args;
@@ -516,14 +529,17 @@ export function withApproval(action, handler, options = {}) {
         const result = await handler(params, extra);
         // Keep the atomic claim across the outbound hop. Only a definitive pre-acceptance
         // failure may release it; transport errors and unknown outcomes can already have sent.
-        if (action === 'send_test_email' && approval_id && consumedAt && testSendNotAccepted(result)) {
+        const releasable = action === 'send_test_email' ? testSendNotAccepted(result) : notExecutedResults.has(result);
+        if (approval_id && consumedAt && releasable) {
             const { data: restored, error } = await approvalStore().from('action_approvals')
                 .update({ status: 'approved', used_at: null })
-                .eq('id', approval_id).eq('project_id', getProjectId()).eq('action', 'send_test_email')
+                .eq('id', approval_id).eq('project_id', getProjectId()).eq('action', action)
                 .eq('status', 'used').eq('used_at', consumedAt)
                 .select('id').maybeSingle();
             if (error || !restored) {
-                console.error('Test-send approval could not be restored after a pre-acceptance failure.');
+                console.error(action === 'send_test_email'
+                    ? 'Test-send approval could not be restored after a pre-acceptance failure.'
+                    : `Approval for ${action} could not be restored after a pre-execution failure.`);
             }
         }
         return result;

package/build/lib/tester-requests.js

@@ -10,9 +10,9 @@ import { TESTER_SITE_FIELDS } from './tester-policy.js';
 const text = (message) => ({ content: [{ type: 'text', text: message }] });
 /** Only installed for an authenticated tester connection, never selected by tool arguments. */
 export function testerRequestTool(action, config, handler) {
-    const original = z.object(config.inputSchema);
+    const original = config.inputSchema instanceof z.ZodObject ? config.inputSchema : z.object(config.inputSchema);
     // Wrapping before optional prevents Zod defaults from populating an approval-id-only retry.
-    const inputSchema = Object.fromEntries(Object.entries(config.inputSchema).map(([key, schema]) => [key, z.preprocess(value => value, schema).optional()]));
+    const inputSchema = Object.fromEntries(Object.entries(original.shape).map(([key, schema]) => [key, z.preprocess(value => value, schema).optional()]));
     inputSchema.approval_id = z.string().uuid().optional();
     return {
         config: { ...config, inputSchema },

package/build/tools/campaigns.js

@@ -1,4 +1,4 @@
-import { validateStepMultiEventRules, stepMultiEventRulesView } from "@sendinel/domain";
+import { validateStepMultiEventRules, stepMultiEventRulesView, validateStepAbsenceRule, stepAbsenceRuleView } from "@sendinel/domain";
 import { readCampaignMetricGroups, SENT_STATUSES } from "@sendinel/domain";
 import { resolveCampaignReentry, readCampaignPeriods, campaignPeriodFields } from "@sendinel/domain";
 import { CAMPAIGN_BRANCH_CONDITIONS, campaignBranchConditionValue, isContactPropertyConditionList, STEP_PROPERTY_CONDITIONS_ERROR, validateStepPropertyRules } from "@sendinel/domain";
@@ -47,6 +47,12 @@ const multiEventFields = {
     send_only_if_events: z.array(z.string().trim().min(1)).min(1).max(10).nullable().optional().describe('Required events at send time, ALL by default; null clears. ANDed with legacy gates.'),
     send_only_if_events_mode: z.enum(['all', 'any']).nullable().optional().describe('Required-event list mode; omitted/null defaults to all on new steps. Omission preserves the mode on updates.'),
 };
+const absenceFields = {
+    send_only_if_no_event: z.string().trim().min(1).nullable().optional().describe('Send only if this event has NOT occurred in the last send_only_if_no_event_days days at send time. Supply both fields together; two nulls clear.'),
+    send_only_if_no_event_days: z.number().int().min(1).max(365).nullable().optional().describe('Rolling lookback in days (1–365), independent of enrollment/cycle bounds. Supply with send_only_if_no_event; two nulls clear.'),
+};
+const absencePairValid = (input) => validateStepAbsenceRule(input).ok;
+const absencePairError = 'send_only_if_no_event and send_only_if_no_event_days must both be set or both null';
 function stripHtml(value) {
     return value
         .replace(/<style[\s\S]*?<\/style>/gi, ' ')
@@ -884,7 +890,7 @@ export function registerCampaignTools(server) {
             openWorldHint: false,
         },
         description: 'Add an email step to a campaign. Requires a non-blank subject and body_html, body_text, or blocks that render to content. For A/B testing, add multiple steps with the same step_order but different variant_label values.',
-        inputSchema: {
+        inputSchema: z.object({
             campaign_id: z.string().uuid(),
             step_order: z.number().int().min(0).describe('Position in sequence (0 = first)'),
             subject: z.string().min(1),
@@ -899,11 +905,15 @@ export function registerCampaignTools(server) {
             skip_if_property: propertyConditions.describe('Skip when ALL 1–10 conditions match current custom_properties. Missing/null keys never match. null clears.'),
             send_only_if_property: propertyConditions.describe('Send only when ALL 1–10 conditions match current custom_properties. Unknown/non-match skips. null clears.'),
             ...multiEventFields,
+            ...absenceFields,
             skip_if_event: z.string().trim().min(1).optional().describe('Skip this step at send time if the contact already has an event with this name; the journey continues.'),
             send_only_if_event: z.string().trim().min(1).optional().describe('Send this step only if the contact has an event with this name by send time; otherwise skip it and continue the journey.'),
-        },
-    }, async ({ campaign_id, step_order, subject, body_html, body_text, blocks, delay_days, delay_hours, variant_label, survey_id, brand_asset_ids, skip_if_event, send_only_if_event, skip_if_events, send_only_if_events, send_only_if_events_mode, skip_if_property, send_only_if_property }) => {
+        }).refine(absencePairValid, { message: absencePairError }),
+    }, async ({ campaign_id, step_order, subject, body_html, body_text, blocks, delay_days, delay_hours, variant_label, survey_id, brand_asset_ids, skip_if_event, send_only_if_event, skip_if_events, send_only_if_events, send_only_if_events_mode, send_only_if_no_event, send_only_if_no_event_days, skip_if_property, send_only_if_property }) => {
         try {
+            const absence = validateStepAbsenceRule({ send_only_if_no_event, send_only_if_no_event_days });
+            if (!absence.ok)
+                return j({ error: absence.error, code: 'INVALID_INPUT' });
             const events = validateStepMultiEventRules({ skip_if_events, send_only_if_events, send_only_if_events_mode });
             if (!events.ok)
                 return j({ error: events.error, code: 'INVALID_INPUT' });
@@ -943,7 +953,7 @@ export function registerCampaignTools(server) {
             const renderedText = body_text !== undefined && survey_id ? renderTemplateVars(body_text, renderVars) : body_text;
             const { data, error } = await db()
                 .from('campaign_steps')
-                .insert({ campaign_id, step_order, subject: renderedSubject, body_html: renderedHtml, body_text: renderedText ?? (normalizedBlocks?.length ? blocksToText(normalizedBlocks) : undefined), blocks: normalizedBlocks ?? null, delay_days, delay_hours, variant_label: variant_label ?? 'A', skip_if_event: skip_if_event ?? null, send_only_if_event: send_only_if_event ?? null, ...events.rules, ...properties.rules })
+                .insert({ campaign_id, step_order, subject: renderedSubject, body_html: renderedHtml, body_text: renderedText ?? (normalizedBlocks?.length ? blocksToText(normalizedBlocks) : undefined), blocks: normalizedBlocks ?? null, delay_days, delay_hours, variant_label: variant_label ?? 'A', skip_if_event: skip_if_event ?? null, send_only_if_event: send_only_if_event ?? null, ...events.rules, ...absence.rules, ...properties.rules })
                 .select()
                 .single();
             if (error)
@@ -3125,6 +3135,7 @@ Return ONLY valid JSON with this exact shape:
             trigger_config: z.record(z.string(), z.unknown()).nullable().optional().describe('Event/tag lists with optional where filter, or date_field/contact_event configuration.'),
             steps: z.array(z.object({
                 ...multiEventFields,
+                ...absenceFields,
                 skip_if_event: z.string().trim().min(1).nullable().optional(),
                 send_only_if_event: z.string().trim().min(1).nullable().optional(),
                 subject: z.string().min(1).describe('Email subject line'),
@@ -3133,7 +3144,7 @@ Return ONLY valid JSON with this exact shape:
                 blocks: z.array(z.record(z.string(), z.unknown())).optional().describe('Optional structured Composer blocks that produced body_html.'),
                 delay_days: z.number().int().min(0).optional().default(0),
                 delay_hours: z.number().int().min(0).max(23).optional().default(0),
-            })).min(1).describe('Email steps with pre-built content'),
+            }).refine(absencePairValid, { message: absencePairError })).min(1).describe('Email steps with pre-built content'),
             segment_id: z.string().uuid().optional().describe('Segment to auto-enroll. Optional for triggered campaigns; future trigger matches enroll contacts.'),
             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.'),
             activate: z.boolean().optional().default(false).describe('Set to true to activate immediately after creation. Requires segment_id or a configured triggered campaign.'),
@@ -3142,10 +3153,13 @@ Return ONLY valid JSON with this exact shape:
         },
     }, 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 }) => {
         for (const step of steps) {
+            const absence = validateStepAbsenceRule(step);
+            if (!absence.ok)
+                return j({ error: absence.error, code: 'INVALID_INPUT' });
             const events = validateStepMultiEventRules(step);
             if (!events.ok)
                 return j({ error: events.error, code: 'INVALID_INPUT' });
-            Object.assign(step, events.rules);
+            Object.assign(step, events.rules, absence.rules);
         }
         const footerTemplate = unsub_footer_template?.trim() ?? null;
         if (footerTemplate !== null) {
@@ -3226,6 +3240,7 @@ Return ONLY valid JSON with this exact shape:
                     skip_if_event: s.skip_if_event ?? null,
                     send_only_if_event: s.send_only_if_event ?? null,
                     ...stepMultiEventRulesView(s),
+                    ...stepAbsenceRuleView(s),
                 })),
                 segment_id: segment_id ?? null,
                 sends_per_hour: sends_per_hour ?? null,
@@ -3267,6 +3282,7 @@ Return ONLY valid JSON with this exact shape:
             skip_if_event: s.skip_if_event ?? null,
             send_only_if_event: s.send_only_if_event ?? null,
             ...stepMultiEventRulesView(s),
+            ...stepAbsenceRuleView(s),
         }));
         const { error: stepErr } = await db()
             .from('campaign_steps')
@@ -3364,7 +3380,7 @@ Return ONLY valid JSON with this exact shape:
             return j({ error: (campaignErr ? dbToolError(campaignErr).error : undefined) ?? 'Campaign not found', code: 'NOT_FOUND' });
         const { data, error } = await db()
             .from('campaign_steps')
-            .select('id, step_order, subject, body_html, body_text, blocks, delay_days, delay_hours, skip_if_event, send_only_if_event, skip_if_events, send_only_if_events, send_only_if_events_mode, skip_if_property, send_only_if_property, created_at, updated_at')
+            .select('id, step_order, subject, body_html, body_text, blocks, delay_days, delay_hours, skip_if_event, send_only_if_event, skip_if_events, send_only_if_events, send_only_if_events_mode, send_only_if_no_event, send_only_if_no_event_days, skip_if_property, send_only_if_property, created_at, updated_at')
             .eq('campaign_id', campaign_id)
             .order('step_order', { ascending: true });
         if (error)
@@ -3380,7 +3396,7 @@ Return ONLY valid JSON with this exact shape:
             openWorldHint: false,
         },
         description: 'Update a campaign step — change subject, body, delay, or step_order.',
-        inputSchema: {
+        inputSchema: z.object({
             step_id: z.string().uuid(),
             subject: z.string().optional(),
             body_html: z.string().optional(),
@@ -3393,6 +3409,7 @@ Return ONLY valid JSON with this exact shape:
             skip_if_property: propertyConditions.describe('Skip when ALL 1–10 conditions match current custom_properties. Missing/null keys never match. null clears.'),
             send_only_if_property: propertyConditions.describe('Send only when ALL 1–10 conditions match current custom_properties. Unknown/non-match skips. null clears.'),
             ...multiEventFields,
+            ...absenceFields,
             skip_if_event: z.string().trim().min(1).nullable().optional().describe('Event name that skips this step at send time; null clears the rule.'),
             send_only_if_event: z.string().trim().min(1).nullable().optional().describe('Event required for this step to send; null clears the rule.'),
             link_actions: z.array(z.discriminatedUnion('action', [
@@ -3405,10 +3422,13 @@ Return ONLY valid JSON with this exact shape:
                     continue_url: z.string().url().max(500).optional().describe('Optional http(s) link shown on the thank-you page.'),
                 }),
             ])).max(10).optional().describe('Link actions for this step. set_property links show a Confirm page; only the Confirm click writes the property (last click wins). Replaces the whole list.'),
-        },
+        }).refine(absencePairValid, { message: absencePairError }),
     }, async ({ step_id, ...updates }) => {
         const projectId = getProjectId();
         const { survey_id, ...stepUpdates } = updates;
+        const absence = validateStepAbsenceRule(stepUpdates);
+        if (!absence.ok)
+            return j({ error: absence.error, code: 'INVALID_INPUT' });
         const events = validateStepMultiEventRules(stepUpdates);
         if (!events.ok)
             return j({ error: events.error, code: 'INVALID_INPUT' });
@@ -3441,6 +3461,7 @@ Return ONLY valid JSON with this exact shape:
         const renderedUpdates = {
             ...stepUpdates,
             ...events.rules,
+            ...absence.rules,
             ...(normalizedBlocks !== undefined ? { blocks: normalizedBlocks.length ? normalizedBlocks : null } : {}),
             ...(normalizedBlocks?.length && stepUpdates.body_html === undefined ? { body_html: blocksToHtml(normalizedBlocks) } : {}),
             ...(normalizedBlocks?.length && stepUpdates.body_text === undefined ? { body_text: blocksToText(normalizedBlocks) } : {}),
@@ -3452,7 +3473,7 @@ Return ONLY valid JSON with this exact shape:
             .from('campaign_steps')
             .update({ ...renderedUpdates, updated_at: new Date().toISOString() })
             .eq('id', step_id)
-            .select('id, step_order, subject, delay_days, delay_hours, skip_if_event, send_only_if_event, skip_if_events, send_only_if_events, send_only_if_events_mode, skip_if_property, send_only_if_property, updated_at')
+            .select('id, step_order, subject, delay_days, delay_hours, skip_if_event, send_only_if_event, skip_if_events, send_only_if_events, send_only_if_events_mode, send_only_if_no_event, send_only_if_no_event_days, skip_if_property, send_only_if_property, updated_at')
             .single();
         if (error)
             return j(dbToolError(error));
@@ -3830,7 +3851,7 @@ Return ONLY valid JSON with this exact shape:
             total_sent: periods?.totals?.sent ?? sentCount ?? 0,
             ...(periods?.totals ? { unique_opened: periods.totals.opened, unique_clicked: periods.totals.clicked } : {}),
             ...campaignPeriodFields(periods, period),
-            steps: (steps ?? []).map((step) => ({ ...step, ...stepMultiEventRulesView(step), total_sent: stepMetrics.sent.get(step.id) ?? 0 })),
+            steps: (steps ?? []).map((step) => ({ ...step, ...stepMultiEventRulesView(step), ...stepAbsenceRuleView(step), total_sent: stepMetrics.sent.get(step.id) ?? 0 })),
             active_enrollments: enrollCount ?? 0,
             send_incomplete: queuedCount > 0 || failedCount > 0 || outstandingRows.length > 0 || unresolvedCount > 0,
             queued_email_count: queuedCount,

package/build/tools/contacts.js

@@ -11,7 +11,7 @@ import { dbErrorResult, dbToolError, toolError } from '../lib/db-error.js';
 import { resolveSegmentContactIds } from '../lib/send-audience.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 { assertChannelCanExecute, currentChannelContext, requestApproval, checkApproval, withApproval, markNotExecuted, isPreExecutionStatus } from '../lib/action-approvals.js';
 import { decrypt } from '../crypto.js';
 import { normalizeActiveCampaignAccountUrl } from '../lib/url-validation.js';
 import { diffCustomProperties } from '../lib/custom-properties-diff.js';
@@ -612,8 +612,19 @@ export function registerContactTools(server) {
             event: z.string().trim().min(1),
             data: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
             idempotency_key: z.string().min(1).optional().describe('Sent as Idempotency-Key. Reuse with the same event payload when retrying.'),
+            consent: z.object({
+                site_id: z.string().uuid(),
+                basis: z.enum(['opt_in', 'existing_customer']),
+                source: z.string().trim().min(1).max(100),
+                collected_at: z.string().optional(),
+            }).optional().describe('Optional consent record for an unknown email (see docs/api-events-and-identify.md). Omit for contacts that already exist.'),
+            traits: z.object({
+                first_name: z.string().optional(),
+                last_name: z.string().optional(),
+                properties: z.record(z.string(), z.unknown()).optional(),
+            }).optional().describe('Optional contact traits applied with the event (see docs/api-events-and-identify.md).'),
         },
-    }, withApproval('emit_contact_event', async ({ email, event, data, idempotency_key }) => {
+    }, withApproval('emit_contact_event', async ({ email, event, data, idempotency_key, consent, traits }) => {
         // Never forward raw transport, database or provider errors to the MCP caller.
         // Only known public codes survive; even a returned message may contain internal text.
         const publicCodes = new Set([
@@ -623,7 +634,12 @@ export function registerContactTools(server) {
         try {
             const result = await callSendinelV1('/api/v1/events', {
                 method: 'POST',
-                body: { email, event, ...(data !== undefined ? { data } : {}) },
+                body: {
+                    email, event,
+                    ...(data !== undefined ? { data } : {}),
+                    ...(consent !== undefined ? { consent } : {}),
+                    ...(traits !== undefined ? { traits } : {}),
+                },
                 ...(idempotency_key ? { idempotencyKey: idempotency_key } : {}),
             });
             if (result.ok)
@@ -631,7 +647,8 @@ export function registerContactTools(server) {
             const payload = result.error && typeof result.error === 'object' && 'error' in result.error
                 && result.error.error && typeof result.error.error === 'object' ? result.error.error : result.error;
             const code = payload && typeof payload === 'object' && 'code' in payload ? payload.code : undefined;
-            return { ...j({ code: typeof code === 'string' && publicCodes.has(code) ? code : 'event_intake_failed', error: 'Could not emit contact event' }), isError: true };
+            const failed = { ...j({ code: typeof code === 'string' && publicCodes.has(code) ? code : 'event_intake_failed', error: 'Could not emit contact event' }), isError: true };
+            return isPreExecutionStatus(result.status) ? markNotExecuted(failed) : failed;
         }
         catch {
             return { ...j({ code: 'event_intake_failed', error: 'Could not emit contact event' }), isError: true };
@@ -654,7 +671,10 @@ export function registerContactTools(server) {
         },
     }, withApproval('identify_subscriber', async (params) => {
         const result = await callSendinelV1('/api/v1/identify', { method: 'POST', body: params });
-        return result.ok ? j(result.data) : err(JSON.stringify(result.error));
+        if (result.ok)
+            return j(result.data);
+        const failed = err(JSON.stringify(result.error));
+        return isPreExecutionStatus(result.status) ? markNotExecuted(failed) : failed;
     }));
     server.registerTool('get_subscriber_timeline', {
         title: 'Get Subscriber Timeline',

package/package.json

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