@agifyai/leadify-mcp 8.5.4 → 8.5.5

package/README.md

@@ -245,12 +245,12 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `get_campaign_logs` | Récupérer les logs de campagne avec filtres et pagination. |
 | `delete_campaign_log` | Supprimer une entrée de log de campagne. |
 | `update_campaign_stats` | Mettre à jour les statistiques d'email d'une campagne pour un groupe de leads. |
-| `create_campaign` | Créer une campagne DRAFT mono-canal rattachée à un groupe de leads. `channel` (`LINKEDIN` ou `EMAIL`) est obligatoire ; `start_at`, `end_at` et `timezone` configurent la fenêtre métier. À `end_at`, Leadify ferme la campagne idempotemment, annule uniquement les jobs prouvablement pré-fournisseur et préserve les autres pour réconciliation. |
-| `update_campaign_configuration` | Corriger le canal ou la fenêtre d'une campagne DRAFT encore ouverte, sans activation ni enrôlement. |
-| `list_campaigns` | Lister compactement les campagnes d'une organisation explicitement sélectionnée et leur statut courant. |
-| `get_campaign` | Récupérer les détails d'une campagne et ses KPIs temps réel. |
-| `update_campaign_status` | Changer le statut d'une campagne (DRAFT, ACTIVE, PAUSED, COMPLETED). |
-| `export_campaign` | Exporter les statistiques complètes d'une campagne en CSV. |
+| `create_campaign` | Créer une campagne DRAFT mono-canal rattachée à un groupe de leads. `channel` (`LINKEDIN` ou `EMAIL`) est obligatoire ; `start_at` inclusif, `end_at` exclusif et `timezone` IANA configurent la fenêtre métier. À `end_at`, Leadify met la campagne en pause réversible (`WINDOW_END`) sans la clôturer. |
+| `update_campaign_configuration` | Modifier la fenêtre de toute campagne encore `OPEN`; le canal reste modifiable uniquement en DRAFT. Prolonger `end_at` dans le futur ou le supprimer relance automatiquement une pause `WINDOW_END` après validation du fournisseur, mais jamais une pause manuelle. La fenêtre demandée reste enregistrée si cette validation échoue. |
+| `list_campaigns` | Lister compactement les campagnes d'une organisation explicitement sélectionnée, avec état effectif, fenêtre, motif de pause et clôture. |
+| `get_campaign` | Récupérer les détails d'une campagne, son état effectif, sa clôture et son éventuel rapport final figé, ainsi que ses KPIs temps réel. |
+| `update_campaign_status` | Changer le statut d'une campagne. `PAUSED` est une pause manuelle réversible ; `COMPLETED` déclenche la clôture définitive terminale et son rapport final immuable. |
+| `export_campaign` | Exporter les statistiques en CSV ; après clôture définitive, l'export provient du rapport final figé. |
 | `signal_upsert` | Créer ou mettre à jour un signal de business intelligence (INFO, CRITICAL, GOLDEN). Remet le state à `active`. |
 | `signal_expire` | Expirer un signal (événement périmé). Flip de `state` uniquement. |
 | `signal_disable` | Désactiver un signal (faux positif / écarté manuellement). Flip de `state` uniquement. |

package/dist/tools/campaigns.js

@@ -2,6 +2,14 @@ import { z } from "zod";
 import { getClient } from "../client.js";
 import { toolResult, handleToolError } from "../types.js";
 const CAMPAIGN_STATUSES = ["DRAFT", "ACTIVE", "PAUSED", "COMPLETED"];
+const CAMPAIGN_EFFECTIVE_STATES = [
+    "DRAFT",
+    "SCHEDULED",
+    "ACTIVE",
+    "PAUSED_MANUAL",
+    "PAUSED_WINDOW_END",
+    "CLOSED",
+];
 function assertCampaignBelongsToOrganization(data, organizationId) {
     if (!data || typeof data !== "object") {
         throw new Error("Leadify returned an invalid campaign response");
@@ -89,13 +97,14 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
     });
     // ── create_campaign ────────────────────────────────────────────────────
     server.tool("create_campaign", "Create a mono-channel DRAFT campaign with an explicit channel, optional ISO-8601 start/end " +
-        "window, and IANA timezone. At endAt Leadify closes the campaign idempotently, cancels only " +
-        "pre-provider jobs, and preserves any provider-barrier job for reconciliation.", {
+        "window, and IANA timezone. startAt is inclusive and endAt is exclusive. Reaching endAt " +
+        "reversibly pauses the campaign with reason WINDOW_END while closure remains OPEN; it never " +
+        "creates the permanent closure report.", {
         name: z.string().describe("Campaign name."),
         lead_group_id: z.string().describe("ID of the lead group to associate."),
         channel: z.enum(["LINKEDIN", "EMAIL"]).describe("Required effective delivery channel. Create separate campaigns for LinkedIn and email."),
         start_at: z.string().datetime().optional().describe("Optional inclusive campaign start timestamp in ISO-8601 UTC."),
-        end_at: z.string().datetime().optional().describe("Optional exclusive campaign end timestamp in ISO-8601 UTC; must be after start_at."),
+        end_at: z.string().datetime().optional().describe("Optional exclusive campaign end timestamp in ISO-8601 UTC; must be after start_at. Reaching it pauses, but does not close, the campaign."),
         timezone: z.string().min(1).optional().describe("IANA timezone used for the campaign business window, for example Europe/Paris."),
         description: z.string().optional().describe("Optional description."),
         persona_id: z
@@ -126,12 +135,16 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
             return handleToolError(error);
         }
     });
-    server.tool("update_campaign_configuration", "Correct an open DRAFT campaign's channel or lifecycle window before activation. This tool refuses ACTIVE, PAUSED, COMPLETED, or closed campaigns and never activates or enrolls prospects.", {
+    server.tool("update_campaign_configuration", "Edit the lifecycle window of any OPEN campaign; changing channel remains limited to DRAFT. " +
+        "Extending endAt into the future or removing it automatically resumes only a campaign paused " +
+        "because WINDOW_END, after provider validation and immediate replanning. A MANUAL pause never " +
+        "auto-resumes. The requested window remains saved when provider validation fails, and a CLOSED " +
+        "campaign is terminal.", {
         id: z.string().describe("Campaign ID."),
-        channel: z.enum(["LINKEDIN", "EMAIL"]).optional(),
-        start_at: z.string().datetime().nullable().optional(),
-        end_at: z.string().datetime().nullable().optional(),
-        timezone: z.string().min(1).optional(),
+        channel: z.enum(["LINKEDIN", "EMAIL"]).optional().describe("Delivery channel; mutable only while status is DRAFT."),
+        start_at: z.string().datetime().nullable().optional().describe("Inclusive UTC start timestamp, or null to remove the lower bound."),
+        end_at: z.string().datetime().nullable().optional().describe("Exclusive UTC end timestamp, or null to remove the upper bound. A future value or null can auto-resume only a WINDOW_END pause."),
+        timezone: z.string().min(1).optional().describe("IANA timezone used for the business window, for example Europe/Paris."),
     }, async ({ id, channel, start_at, end_at, timezone }) => {
         try {
             const body = {};
@@ -151,8 +164,9 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
     });
     // ── get_campaign ───────────────────────────────────────────────────────
     server.tool("get_campaign", "Retrieve a campaign chosen from list_campaigns, scoped to the explicitly selected " +
-        "organization. Includes its normalized current status (DRAFT, ACTIVE, PAUSED, or COMPLETED) " +
-        "and real-time KPIs. Never use campaign logs as the source of status.", {
+        "organization. Includes status, effectiveState, pauseReason, pausedAt, window, terminal " +
+        "closure metadata, immutable final report when present, and real-time KPIs. Never use " +
+        "campaign logs as the source of lifecycle state.", {
         id: z.string().describe("Campaign ID."),
         organization_id: z.string().describe("Organization selected explicitly via discover_leadify_context or list_organizations."),
     }, async ({ id, organization_id }) => {
@@ -165,9 +179,10 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
         }
     });
     // ── list_campaigns ─────────────────────────────────────────────────────
-    server.tool("list_campaigns", "List campaigns in one explicitly selected organization with compact current status metadata. " +
-        "Use this after discover_leadify_context to identify ACTIVE, DRAFT, PAUSED, or COMPLETED " +
-        "campaigns without reading historical logs.", {
+    server.tool("list_campaigns", "List campaigns in one explicitly selected organization with compact persisted and effective " +
+        "lifecycle metadata. Use effectiveState to distinguish SCHEDULED, ACTIVE, a manual pause, an " +
+        "end-of-window pause, and permanent closure without reading historical logs. Fetch get_campaign " +
+        "for the immutable final report.", {
         organization_id: z.string().describe("Organization selected explicitly via discover_leadify_context or list_organizations."),
         status: z.enum(CAMPAIGN_STATUSES).optional().describe("Optional current-status filter."),
         limit: z.number().int().min(1).max(100).optional().default(50).describe("Maximum campaigns returned, bounded to 100."),
@@ -188,24 +203,46 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
                 if (!CAMPAIGN_STATUSES.includes(campaign.status)) {
                     throw new Error("Leadify returned a campaign with an invalid current status");
                 }
+                if (!CAMPAIGN_EFFECTIVE_STATES.includes(campaign.effectiveState)) {
+                    throw new Error("Leadify returned a campaign with an invalid effective state");
+                }
+                const closure = campaign.closure;
+                if (!closure || typeof closure !== "object") {
+                    throw new Error("Leadify returned a campaign without closure metadata");
+                }
+                const closureRecord = closure;
                 return {
                     id: campaign.id,
                     name: campaign.name,
                     status: campaign.status,
+                    effectiveState: campaign.effectiveState,
                     channel: campaign.channel,
                     leadGroupId: campaign.leadGroupId,
+                    startAt: campaign.startAt,
+                    endAt: campaign.endAt,
+                    timezone: campaign.timezone,
+                    pauseReason: campaign.pauseReason,
+                    pausedAt: campaign.pausedAt,
+                    closure: {
+                        state: closureRecord.state,
+                        closedAt: closureRecord.closedAt,
+                        terminal: closureRecord.terminal,
+                        reportAvailable: closureRecord.report !== null && closureRecord.report !== undefined,
+                    },
                     createdAt: campaign.createdAt,
                     updatedAt: campaign.updatedAt,
                 };
             });
             const filtered = status ? campaigns.filter((campaign) => campaign.status === status) : campaigns;
             const statusCounts = Object.fromEntries(CAMPAIGN_STATUSES.map((value) => [value, campaigns.filter((campaign) => campaign.status === value).length]));
+            const effectiveStateCounts = Object.fromEntries(CAMPAIGN_EFFECTIVE_STATES.map((value) => [value, campaigns.filter((campaign) => campaign.effectiveState === value).length]));
             return toolResult({
                 organizationId: organization_id,
                 campaigns: filtered.slice(0, limit),
                 total: filtered.length,
                 truncated: filtered.length > limit,
                 statusCounts,
+                effectiveStateCounts,
             });
         }
         catch (error) {
@@ -214,8 +251,9 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
     });
     // ── update_campaign_status ─────────────────────────────────────────────
     server.tool("update_campaign_status", "Change a campaign's workflow status. Allowed values: DRAFT, ACTIVE, PAUSED, COMPLETED. " +
-        "Moving to ACTIVE starts outbound execution; PAUSED halts it; COMPLETED marks the " +
-        "campaign as finished. Always confirm with the user before calling this tool.", {
+        "Moving to ACTIVE starts outbound execution; PAUSED is a reversible manual pause; COMPLETED " +
+        "means explicit permanent closure and creates the immutable final report. Permanent closure is " +
+        "terminal and cannot be reopened. Always confirm with the user before calling this tool.", {
         id: z.string().describe("Campaign ID."),
         status: z
             .enum(["DRAFT", "ACTIVE", "PAUSED", "COMPLETED"])
@@ -230,8 +268,9 @@ export function registerCampaignTools(server, readClient, writeClient, mutationC
         }
     });
     // ── export_campaign ────────────────────────────────────────────────────
-    server.tool("export_campaign", "Export a campaign's full statistics and metrics as CSV. Returns the raw CSV text. " +
-        "Use this for external analysis or reporting.", {
+    server.tool("export_campaign", "Export a campaign's statistics and metrics as CSV. A permanently closed campaign is exported " +
+        "from its immutable final report, so late replies remain visible in current activity without " +
+        "rewriting the export. Returns the raw CSV text.", {
         id: z.string().describe("Campaign ID."),
     }, async ({ id }) => {
         try {

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const MCP_PACKAGE_NAME = "@agifyai/leadify-mcp";
 export declare const MCP_SERVER_NAME = "leadify";
-export declare const MCP_VERSION = "8.5.4";
+export declare const MCP_VERSION = "8.5.5";

package/dist/version.js

@@ -1,3 +1,3 @@
 export const MCP_PACKAGE_NAME = "@agifyai/leadify-mcp";
 export const MCP_SERVER_NAME = "leadify";
-export const MCP_VERSION = "8.5.4";
+export const MCP_VERSION = "8.5.5";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agifyai/leadify-mcp",
-  "version": "8.5.4",
+  "version": "8.5.5",
   "description": "MCP server for Leadify lead management API",
   "type": "module",
   "main": "dist/index.js",