@sellable/mcp 0.1.0

package/dist/tools/campaigns.js

@@ -0,0 +1,892 @@
+import { getApi } from "../api.js";
+import { getConfig } from "../auth.js";
+import { assertCreateCampaignPromptLoaded, assertNetNewCreateCampaignResearchReady, markSenderEnrichmentObserved, } from "./flow-preflight.js";
+import { setCampaignInteractionMode, } from "./interaction-mode.js";
+import { fetchCampaignRubrics } from "./processing.js";
+const LEAD_SOURCE_PROVIDERS = {
+    APOLLO: "apollo-ai",
+    SALES_NAV: "sales-nav",
+    PROSPEO: "prospeo",
+    SIGNAL_DISCOVERY: "signal-discovery",
+};
+function normalizeLeadSourceProvider(input) {
+    if (!input)
+        return null;
+    if (input === "apollo")
+        return LEAD_SOURCE_PROVIDERS.APOLLO;
+    const values = Object.values(LEAD_SOURCE_PROVIDERS);
+    return values.includes(input)
+        ? input
+        : null;
+}
+function buildWatchUrl(config, redirect) {
+    const workspaceId = config.activeWorkspaceId || config.workspaceId;
+    const workspaceParam = workspaceId
+        ? `&workspaceId=${encodeURIComponent(workspaceId)}`
+        : "";
+    return `${config.apiUrl}/auth/continue?token=${config.token}&redirect=${redirect}${workspaceParam}`;
+}
+export const campaignToolDefinitions = [
+    {
+        name: "enrich_sender",
+        description: "Enrich a LinkedIn profile to get the clientProspectId needed for create_campaign. Fast return (~5-8s) with background enrichment. Call this first with the sender's LinkedIn URL before creating a campaign.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                linkedinUrl: {
+                    type: "string",
+                    description: "Full LinkedIn profile URL (e.g., https://linkedin.com/in/username)",
+                },
+                companyDomain: {
+                    type: "string",
+                    description: "Optional company domain to use instead of resolving from profile",
+                },
+                forceRefresh: {
+                    type: "boolean",
+                    description: "Skip cache and fetch fresh LinkedIn data. Use when you need the latest profile info.",
+                },
+            },
+            required: ["linkedinUrl"],
+        },
+    },
+    {
+        name: "get_campaigns",
+        description: "List campaigns for the authenticated user. Returns id, name, createdAt. Ordered by most recent first.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: {
+                    type: "number",
+                    description: "Number of campaigns to return (default 10, max 50)",
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "get_campaign",
+        description: "Get detailed campaign context including brief, positioning, sender info, lead scoring rubrics, and stats. Returns workflowTableId for fetching rows.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignId: {
+                    type: "string",
+                    description: "Campaign ID (e.g., cmp_abc123)",
+                },
+            },
+            required: ["campaignId"],
+        },
+    },
+    {
+        name: "get_campaign_messages_preview",
+        description: "Resolve campaign workflow table and return table meta + lead preview for messaging selection (supports filters + pagination).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignId: {
+                    type: "string",
+                    description: "Campaign ID (e.g., cmp_abc123)",
+                },
+                tableId: {
+                    type: "string",
+                    description: "Optional override table ID (uses campaign workflowTableId if omitted)",
+                },
+                leadLimit: {
+                    type: "number",
+                    description: "Number of leads to preview (default 25, max 25)",
+                },
+                page: {
+                    type: "number",
+                    description: "Page number for pagination (default 1)",
+                },
+                filters: {
+                    type: "array",
+                    description: "Optional column filters (Clay-style). Use column name or id.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            column: {
+                                type: "string",
+                                description: "Column name or column id",
+                            },
+                            op: {
+                                type: "string",
+                                description: "Operator: eq, neq, contains, starts_with, ends_with, gt, gte, lt, lte, is_empty, is_not_empty, in",
+                            },
+                            value: {
+                                oneOf: [
+                                    { type: "string" },
+                                    { type: "number" },
+                                    { type: "boolean" },
+                                    {
+                                        type: "array",
+                                        items: {
+                                            oneOf: [
+                                                { type: "string" },
+                                                { type: "number" },
+                                                { type: "boolean" },
+                                            ],
+                                        },
+                                    },
+                                ],
+                            },
+                            caseSensitive: {
+                                type: "boolean",
+                            },
+                        },
+                        required: ["column", "op"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["campaignId"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "create_campaign",
+        description: 'Create a new campaign offer OR resume an existing one. Low-level write tool: load create-campaign workflow instructions first via get_subskill_prompt({ subskillName: "create-campaign" }) (or bootstrap_create_campaign + nextStep). If campaignId is provided, this tool returns the watchUrl + state for that campaign instead of creating a new campaign.',
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignId: {
+                    type: "string",
+                    description: "Optional campaign ID to resume (e.g., cmp_abc123). When provided, other create fields are ignored.",
+                },
+                name: {
+                    type: "string",
+                    description: "Campaign name",
+                },
+                clientProspectId: {
+                    type: "string",
+                    description: "Enriched client prospect ID",
+                },
+                offerPositioning: {
+                    type: "object",
+                    description: "Offer positioning JSON",
+                },
+                campaignBrief: {
+                    type: "string",
+                    description: "Campaign brief as markdown string. Use actual newline characters (not escaped \\n). Example: '# Campaign\\n\\n## ICP\\n\\nTech founders...'",
+                },
+                messageGenerationMode: {
+                    type: "string",
+                    enum: ["template", "ai-generated"],
+                    description: "Defaults to template for autonomous messaging steps. Use ai-generated only when the user explicitly approves freeform AI-generated messages instead of an approved {{token}} template.",
+                },
+                currentStep: {
+                    type: ["string", "null"],
+                    description: "Workflow step ID (headless or UI step ID such as filter-rules)",
+                },
+                leadSourceType: {
+                    type: ["string", "null"],
+                    description: "Lead source type (existing | new)",
+                },
+                leadSourceProvider: {
+                    type: ["string", "null"],
+                    enum: [
+                        LEAD_SOURCE_PROVIDERS.APOLLO,
+                        LEAD_SOURCE_PROVIDERS.SALES_NAV,
+                        LEAD_SOURCE_PROVIDERS.PROSPEO,
+                        LEAD_SOURCE_PROVIDERS.SIGNAL_DISCOVERY,
+                        null,
+                    ],
+                    description: "Lead source provider (apollo-ai | sales-nav | prospeo | signal-discovery)",
+                },
+                selectedLeadListId: {
+                    type: ["string", "null"],
+                    description: "Lead list ID when using existing list",
+                },
+                senderIds: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Outbound sender IDs to attach to the campaign",
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: "update_campaign",
+        description: "Update an existing campaign offer with positioning, brief, or workflow state fields. Returns currentStep plus navigation diagnostics.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignId: {
+                    type: "string",
+                    description: "Campaign ID to update",
+                },
+                offerPositioning: {
+                    type: "object",
+                    description: "Updated offer positioning JSON",
+                },
+                campaignBrief: {
+                    description: "Updated campaign brief (markdown or JSON)",
+                },
+                leadSourceType: {
+                    type: ["string", "null"],
+                    description: "Lead source type (existing | new)",
+                },
+                leadSourceProvider: {
+                    type: ["string", "null"],
+                    enum: [
+                        LEAD_SOURCE_PROVIDERS.APOLLO,
+                        LEAD_SOURCE_PROVIDERS.SALES_NAV,
+                        LEAD_SOURCE_PROVIDERS.PROSPEO,
+                        LEAD_SOURCE_PROVIDERS.SIGNAL_DISCOVERY,
+                        null,
+                    ],
+                    description: "Lead source provider (apollo-ai | sales-nav | prospeo | signal-discovery)",
+                },
+                selectedLeadListId: {
+                    type: ["string", "null"],
+                    description: "Lead list ID when using existing list",
+                },
+                currentStep: {
+                    type: ["string", "null"],
+                    description: "Headless workflow step ID",
+                },
+                interactionMode: {
+                    type: "string",
+                    enum: ["step-by-step", "autonomous", "ask-when-needed"],
+                    description: "Execution style for lead sourcing steps (step-by-step | autonomous | ask-when-needed).",
+                },
+                enableICPFilters: {
+                    type: ["boolean", "null"],
+                    description: "Whether ICP filtering is enabled (true/false)",
+                },
+                useMessagingTemplate: {
+                    type: ["boolean", "null"],
+                    description: "Whether to use the messaging template step",
+                },
+                senderIds: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Outbound sender IDs to attach to the campaign",
+                },
+                rubric: {
+                    type: "array",
+                    description: "Lead scoring rubric entries",
+                },
+            },
+            required: ["campaignId"],
+        },
+    },
+    {
+        name: "start_campaign",
+        description: "Start a paused campaign, enabling the sweeper to send messages.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignId: {
+                    type: "string",
+                    description: "Campaign ID to start",
+                },
+            },
+            required: ["campaignId"],
+        },
+    },
+    {
+        name: "pause_campaign",
+        description: "Pause an active campaign, stopping the sweeper from sending messages.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignId: {
+                    type: "string",
+                    description: "Campaign ID to pause",
+                },
+            },
+            required: ["campaignId"],
+        },
+    },
+    {
+        name: "update_campaign_brief",
+        description: "Update the campaign brief markdown document. This is a living canvas where you accumulate knowledge during crafting. Use it to: add social proof/case studies discovered during research, note common objections, record successful hooks, or reorganize when user changes direction. You control the full markdown content - read the current brief first, then update it intelligently.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignId: {
+                    type: "string",
+                    description: "Campaign ID to update",
+                },
+                campaignBrief: {
+                    type: "string",
+                    description: "The updated campaign brief as markdown. You should read the current brief first (from get_campaign), then intelligently edit it to add new sections, update existing content, or reorganize as needed.",
+                },
+            },
+            required: ["campaignId", "campaignBrief"],
+        },
+    },
+];
+export async function getCampaigns(limit) {
+    const api = getApi();
+    const params = limit ? `?limit=${limit}` : "";
+    return api.get(`/api/v3/mcp/campaigns${params}`);
+}
+export async function getCampaign(campaignId) {
+    const api = getApi();
+    const config = getConfig();
+    // Fetch campaign context and rubrics in parallel
+    const [result, rubricsResult] = await Promise.all([
+        api.get(`/api/v3/mcp/campaigns/${campaignId}`),
+        fetchCampaignRubrics(campaignId).catch(() => null),
+    ]);
+    // Build watch URL with auto-auth token
+    const redirect = encodeURIComponent(`/campaign-builder/${campaignId}?mode=claude`);
+    const watchUrl = buildWatchUrl(config, redirect);
+    // Merge rubrics into campaignOffer
+    const rubrics = (rubricsResult?.rubrics || []).map((r) => ({
+        id: r.id || "",
+        checkName: r.checkName || "",
+        description: r.description || "",
+        criterion: r.criterion || "",
+        reason: r.reason || "",
+        useCheckForScoring: r.useCheckForScoring !== false,
+        isRequiredCheck: r.isRequiredCheck === true,
+        allowPartialCredit: r.allowPartialCredit !== false,
+        strictMatching: r.strictMatching === true,
+    }));
+    return {
+        ...result,
+        campaignOffer: {
+            ...result.campaignOffer,
+            leadScoringRubrics: rubrics,
+        },
+        watchUrl,
+    };
+}
+function normalizeCellValue(cell) {
+    if (!cell)
+        return null;
+    return cell.isOverridden ? cell.overrideValue : cell.result;
+}
+function toText(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return String(value);
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (Array.isArray(value)) {
+        const parts = value
+            .map((item) => toText(item))
+            .filter((item) => Boolean(item));
+        return parts.length > 0 ? parts.join(", ") : null;
+    }
+    if (typeof value === "object") {
+        const record = value;
+        const preferredKeys = ["display", "value", "label", "name"];
+        for (const key of preferredKeys) {
+            if (key in record) {
+                const resolved = toText(record[key]);
+                if (resolved)
+                    return resolved;
+            }
+        }
+        if ("linkedin_url" in record) {
+            const resolved = toText(record.linkedin_url);
+            if (resolved)
+                return resolved;
+        }
+        const firstValue = Object.values(record)[0];
+        return toText(firstValue);
+    }
+    return null;
+}
+function isTruthyValue(value) {
+    if (value === true)
+        return true;
+    if (value === false || value === null || value === undefined)
+        return false;
+    if (typeof value === "number")
+        return value === 1;
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        return normalized === "true" || normalized === "1" || normalized === "yes";
+    }
+    if (typeof value === "object") {
+        const record = value;
+        if ("value" in record)
+            return isTruthyValue(record.value);
+        if ("checked" in record)
+            return isTruthyValue(record.checked);
+        if ("selected" in record)
+            return isTruthyValue(record.selected);
+    }
+    return false;
+}
+function normalizeColumnName(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function findColumnByName(columns, names) {
+    const normalized = new Set(names.map((name) => normalizeColumnName(name)));
+    return (columns.find((col) => normalized.has(normalizeColumnName(col.name))) || null);
+}
+function findColumnByType(columns, type) {
+    return columns.find((col) => col.columnType === type) || null;
+}
+export async function getCampaignMessagesPreview(input) {
+    const api = getApi();
+    const leadLimitRaw = input.leadLimit ?? 25;
+    const leadLimit = Math.min(25, Math.max(1, leadLimitRaw));
+    const page = Math.max(1, input.page ?? 1);
+    let tableId = input.tableId;
+    if (!tableId) {
+        const offer = await api.get(`/api/v2/campaign-offers/${input.campaignId}`);
+        tableId = offer.workflowTableId || undefined;
+    }
+    if (!tableId) {
+        throw new Error("No workflowTableId found for this campaign. Import leads into the campaign table first.");
+    }
+    let stats = null;
+    try {
+        const statsResponse = await api.get(`/api/v3/workflow-tables/${tableId}/stats`);
+        stats = {
+            totalRows: statsResponse.totalRows ?? 0,
+            enrichedCount: statsResponse.enrichedCount ?? 0,
+            needsEnrichCount: statsResponse.needsEnrichCount ?? 0,
+            messagesCount: statsResponse.messagesCount ?? 0,
+            approvedCount: statsResponse.approvedCount ?? 0,
+            needsApprovalCount: statsResponse.needsApprovalCount ?? 0,
+            processingCount: statsResponse.processingCount ?? 0,
+        };
+    }
+    catch {
+        stats = null;
+    }
+    const metaResponse = await api.get(`/api/v3/workflow-tables/${tableId}?mode=meta`);
+    const columns = (metaResponse.columns || []).map((col) => ({
+        id: col.id,
+        name: col.name,
+        columnType: col.columnType,
+    }));
+    const nameColumn = findColumnByName(columns, [
+        "name",
+        "full name",
+        "full_name",
+        "contact name",
+        "lead name",
+        "person name",
+    ]) || findColumnByType(columns, "text");
+    const titleColumn = findColumnByName(columns, [
+        "title",
+        "job title",
+        "job_title",
+        "position",
+        "role",
+        "headline",
+    ]);
+    const companyColumn = findColumnByName(columns, [
+        "company",
+        "company name",
+        "company_name",
+        "organization",
+        "org",
+        "employer",
+        "current company",
+        "company website",
+        "company site",
+        "website",
+    ]);
+    const linkedinColumn = findColumnByType(columns, "linkedin_url") ||
+        columns.find((col) => col.name.toLowerCase().includes("linkedin")) ||
+        null;
+    const messageColumn = findColumnByName(columns, ["message", "message body"]) ||
+        findColumnByType(columns, "message") ||
+        findColumnByName(columns, ["generate message", "generate_message"]);
+    const approveColumn = findColumnByName(columns, [
+        "approved",
+        "enable scheduling",
+        "enable_scheduling",
+    ]) ||
+        findColumnByType(columns, "approve") ||
+        null;
+    const filtersParam = input.filters && input.filters.length > 0
+        ? `&filters=${encodeURIComponent(JSON.stringify(input.filters))}`
+        : "";
+    const rowsResponse = await api.get(`/api/v3/workflow-tables/${tableId}/rows?page=${page}&limit=${leadLimit}${filtersParam}`);
+    const previewRows = (rowsResponse.rows || []).map((row, index) => {
+        const cells = row.cells || [];
+        const cellByColumnId = new Map(cells
+            .filter((cell) => cell.columnId)
+            .map((cell) => [cell.columnId, cell]));
+        const getCellText = (columnId) => {
+            if (!columnId)
+                return null;
+            const cell = cellByColumnId.get(columnId);
+            return toText(normalizeCellValue(cell || null));
+        };
+        const name = getCellText(nameColumn?.id) || "Unknown";
+        const title = getCellText(titleColumn?.id) || "";
+        const company = getCellText(companyColumn?.id) || "";
+        const linkedinUrl = getCellText(linkedinColumn?.id) || null;
+        const messageCell = messageColumn
+            ? cellByColumnId.get(messageColumn.id) || null
+            : null;
+        const messageValue = toText(normalizeCellValue(messageCell || null)) || "";
+        const messagePreview = messageValue.length > 140
+            ? `${messageValue.slice(0, 140)}...`
+            : messageValue || null;
+        const approveCell = approveColumn
+            ? cellByColumnId.get(approveColumn.id) || null
+            : null;
+        const approveValue = normalizeCellValue(approveCell || null);
+        const isApproved = messageValue.trim().length > 0 && isTruthyValue(approveValue);
+        return {
+            index: index + 1,
+            rowId: row.id,
+            name,
+            title,
+            company,
+            linkedinUrl,
+            messagePreview,
+            messageCellId: messageCell?.id ?? null,
+            hasMessage: messageValue.trim().length > 0,
+            approveCellId: approveCell?.id ?? null,
+            isApproved,
+        };
+    });
+    return {
+        campaignId: input.campaignId,
+        tableId,
+        stats,
+        meta: {
+            columns,
+            keyColumns: {
+                nameColumnId: nameColumn?.id || null,
+                titleColumnId: titleColumn?.id || null,
+                companyColumnId: companyColumn?.id || null,
+                linkedinUrlColumnId: linkedinColumn?.id || null,
+                messageColumnId: messageColumn?.id || null,
+                approveColumnId: approveColumn?.id || null,
+            },
+        },
+        leads: {
+            limit: leadLimit,
+            rows: previewRows,
+        },
+    };
+}
+function deriveOfferValue(name, briefContent) {
+    const lines = briefContent
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    if (lines.length === 0)
+        return name;
+    const headingMatch = lines[0].match(/^#{1,6}\s+(.*)$/);
+    const heading = headingMatch?.[1]?.trim();
+    if (heading)
+        return heading.slice(0, 120);
+    return lines[0].slice(0, 120);
+}
+export async function createCampaign(input) {
+    const api = getApi();
+    const config = getConfig();
+    // Idempotent resume path
+    if (input.campaignId) {
+        const existing = await api.get(`/api/v2/campaign-offers/${input.campaignId}`);
+        const redirect = encodeURIComponent(`/campaign-builder/${existing.id}?mode=claude`);
+        const watchUrl = buildWatchUrl(config, redirect);
+        const hasCreateFields = input.name ||
+            input.clientProspectId ||
+            input.offerPositioning !== undefined ||
+            input.campaignBrief;
+        return {
+            id: existing.id,
+            name: existing.name,
+            createdAt: existing.createdAt,
+            currentStep: existing.currentStep ?? null,
+            watchUrl,
+            resumed: true,
+            warning: hasCreateFields
+                ? "campaignId provided; resume mode ignores create fields."
+                : undefined,
+        };
+    }
+    assertCreateCampaignPromptLoaded();
+    const missing = [];
+    if (!input.name)
+        missing.push("name");
+    if (!input.clientProspectId)
+        missing.push("clientProspectId");
+    if (!input.campaignBrief)
+        missing.push("campaignBrief");
+    if (missing.length > 0) {
+        throw new Error("VALIDATION_ERROR: create_campaign requires either campaignId (resume) " +
+            `or all create fields. Missing: ${missing.join(", ")}.\n\n` +
+            "Remediation:\n" +
+            '- For full workflow, call get_subskill_prompt({ subskillName: "create-campaign" }) and follow it.\n' +
+            '- For net-new campaign creation, call enrich_sender first, then call get_subskill_prompt({ subskillName: "research-sender" }), run sender research, call complete_sender_research(...), and only then call create_campaign.\n' +
+            "- For resume, call create_campaign with campaignId only.");
+    }
+    assertNetNewCreateCampaignResearchReady();
+    const name = input.name;
+    const clientProspectId = input.clientProspectId;
+    const campaignBrief = input.campaignBrief;
+    // Validate required campaignBrief - must be non-empty markdown
+    // Normalize escaped newlines - MCP tool calls pass literal "\n" text (backslash + n)
+    // because JSON serialization escapes the backslash
+    const rawBrief = typeof campaignBrief === "string"
+        ? campaignBrief.trim()
+        : String(campaignBrief);
+    // Replace literal \n (backslash + n) with actual newline characters
+    // In regex: /\\n/ matches literal backslash followed by n
+    const briefContent = rawBrief.replace(/\\n/g, "\n");
+    if (briefContent.length < 50) {
+        throw new Error("VALIDATION_ERROR: campaignBrief is too short (min 50 chars).\n\n" +
+            "Please provide a comprehensive campaign brief with:\n" +
+            "- Target audience description\n" +
+            "- Value proposition\n" +
+            "- Key messages\n" +
+            "- Tone guidelines");
+    }
+    const currentStep = input.currentStep ?? null;
+    const isAutonomousMessageMint = currentStep === "auto-execute-leads" ||
+        currentStep === "validate-sample" ||
+        currentStep === "auto-execute-messaging";
+    const explicitlyAllowsAiGenerated = input.messageGenerationMode === "ai-generated";
+    const hasTemplateToken = /\{\{\s*\S[^}]*\}\}/.test(briefContent);
+    if (isAutonomousMessageMint &&
+        !explicitlyAllowsAiGenerated &&
+        !hasTemplateToken) {
+        throw new Error("VALIDATION_ERROR: campaignBrief must include at least one supported {{token}} before minting into autonomous messaging.\n\n" +
+            "Why this is blocked:\n" +
+            "- Generate Message enters template mode only when campaignBrief.content contains {{...}}.\n" +
+            "- Without a token, the message cascade uses freeform AI generation and may rewrite the approved message.\n\n" +
+            "Remediation:\n" +
+            "- Add an `## Approved Message Template` section to campaignBrief with the exact live template, e.g. `hey {{first_name}},`.\n" +
+            "- Add `### Token Fill Rules` for every prospect-row token.\n" +
+            '- Only pass messageGenerationMode: "ai-generated" if the user explicitly approved freeform AI-generated messages.');
+    }
+    const offerPositioning = input.offerPositioning ??
+        {
+            offer: {
+                value: deriveOfferValue(name, briefContent),
+                isAnchor: true,
+            },
+        };
+    // Format campaignBrief as expected object structure { name, content }
+    // Default currentStep to "create-offer" (Plan step) so watch link shows brief first
+    // Default leadSourceType to "new" to skip choose-source step (most headless users want new leads)
+    const normalizedLeadSourceProvider = input.leadSourceProvider === undefined
+        ? undefined
+        : normalizeLeadSourceProvider(input.leadSourceProvider);
+    const { messageGenerationMode: _messageGenerationMode, ...apiInput } = input;
+    const formattedInput = {
+        ...apiInput,
+        name,
+        clientProspectId,
+        offerPositioning,
+        ...(input.leadSourceProvider !== undefined
+            ? { leadSourceProvider: normalizedLeadSourceProvider }
+            : {}),
+        currentStep: currentStep ?? "create-offer",
+        leadSourceType: input.leadSourceType ?? "new",
+        campaignBrief: {
+            name, // Use campaign name as brief name
+            content: briefContent, // The markdown content
+        },
+    };
+    const result = await api.post(`/api/v2/campaign-offers`, formattedInput);
+    // Build watch URL for Claude Code to share with user
+    const redirect = encodeURIComponent(`/campaign-builder/${result.id}?mode=claude`);
+    const watchUrl = buildWatchUrl(config, redirect);
+    // Serialize to only essential fields for context efficiency
+    return {
+        id: result.id,
+        name: result.name,
+        createdAt: result.createdAt,
+        currentStep: result.currentStep,
+        watchUrl,
+    };
+}
+export async function updateCampaign(campaignId, input) {
+    const api = getApi();
+    const { campaignId: _ignore, interactionMode, ...updates } = input;
+    // Normalize campaignBrief: if a plain string is passed, wrap it in the
+    // { name, content } structure the UI expects.  createCampaign already does
+    // this, but updateCampaign was passing the string straight through.
+    if (typeof updates.campaignBrief === "string") {
+        updates.campaignBrief = {
+            content: updates.campaignBrief,
+        };
+    }
+    if (typeof interactionMode === "string" && interactionMode.trim()) {
+        setCampaignInteractionMode({
+            campaignId,
+            interactionMode,
+        });
+    }
+    if ("leadSourceProvider" in updates) {
+        if (updates.leadSourceProvider === null) {
+            updates.leadSourceProvider = null;
+        }
+        else {
+            const normalizedLeadSourceProvider = normalizeLeadSourceProvider(updates.leadSourceProvider);
+            if (normalizedLeadSourceProvider) {
+                updates.leadSourceProvider = normalizedLeadSourceProvider;
+            }
+            else {
+                delete updates.leadSourceProvider;
+            }
+        }
+    }
+    // Hotfix: when rubrics are saved with enableICPFilters, ensure the UI step
+    // is set to "filter-rules" so the frontend can render the filter state.
+    // Without this, the MCP caller can save rubrics + enableICPFilters on the
+    // backend while the UI currentStep points somewhere else (e.g. "messages"),
+    // causing the UI to be out of sync with the backend filter state.
+    if (updates.enableICPFilters === true &&
+        Array.isArray(updates.rubric) &&
+        updates.rubric.length > 0 &&
+        !updates.currentStep) {
+        updates.currentStep = "filter-rules";
+    }
+    const result = await api.put(`/api/v2/campaign-offers/${campaignId}`, updates);
+    // Serialize to only essential fields for context efficiency
+    return {
+        id: result.id,
+        name: result.name,
+        currentStep: result.currentStep,
+        updatedAt: result.updatedAt,
+        // Provide full campaign snapshot for server-side context hydration.
+        _campaign: result,
+    };
+}
+export async function startCampaign(campaignId) {
+    const api = getApi();
+    return api.post(`/api/v3/campaigns/${campaignId}/start`);
+}
+export async function pauseCampaign(campaignId) {
+    const api = getApi();
+    return api.post(`/api/v3/campaigns/${campaignId}/pause`);
+}
+export async function updateCampaignBrief(campaignId, campaignBrief) {
+    const api = getApi();
+    return api.patch(`/api/v3/mcp/campaigns/${campaignId}`, { campaignBrief });
+}
+export async function enrichSender(linkedinUrl, companyDomain, forceRefresh) {
+    const api = getApi();
+    const result = await api.post(`/api/v4/enrich-prospect`, {
+        linkedinUrl,
+        companyDomain,
+        force: forceRefresh,
+    });
+    markSenderEnrichmentObserved({
+        enrichmentStatus: result.enrichmentStatus,
+        caseStudies: result.caseStudies,
+        proof: result.reviews,
+    });
+    // Serialize to compact digests — strip raw blobs to save context tokens
+    const personData = (result.personData || {});
+    const companyData = (result.companyData || {});
+    const positioning = (result.positioning || {});
+    const caseStudies = result.caseStudies;
+    const reviews = result.reviews;
+    const base = {
+        clientProspectId: result.id,
+        sender: {
+            fullName: personData.fullName || "",
+            headline: personData.headline,
+            title: personData.currentPosition?.title,
+            company: personData.currentPosition?.company?.name,
+        },
+        companyDomain: result.companyDomain,
+        enrichmentStatus: result.enrichmentStatus,
+    };
+    if (result.enrichmentStatus !== "complete")
+        return base;
+    // Build compact companySnapshot
+    base.companySnapshot = {
+        name: companyData.name || "",
+        domain: companyData.domain || result.companyDomain,
+        industry: companyData.industry,
+        employeeRange: companyData.employeeRange,
+        description: companyData.description,
+        linkedinUrl: companyData.linkedinUrl,
+    };
+    // Build compact senderBackground
+    const experience = personData.experience || [];
+    base.senderBackground = {
+        experience: experience.slice(0, 4).map((exp) => ({
+            title: exp.title || "",
+            company: exp.companyName || exp.company || "",
+            duration: exp.duration,
+        })),
+        education: personData.education?.[0]?.schoolName,
+        followerCount: personData.followerCount,
+        connectionCount: personData.connectionCount,
+    };
+    // Build compact proofDigest from caseStudies + reviews + positioning
+    let caseStudyCount = 0;
+    let caseStudySummary = null;
+    if (caseStudies) {
+        try {
+            const parsed = JSON.parse(caseStudies);
+            const studies = parsed.caseStudies || [];
+            caseStudyCount = studies.length;
+            caseStudySummary = parsed.summary || null;
+        }
+        catch {
+            // ignore parse errors
+        }
+    }
+    let reviewHighlight = null;
+    if (reviews) {
+        try {
+            const parsed = JSON.parse(reviews);
+            // Cross-check review sites against confirmed company domain
+            const sites = (parsed.reviewSites || []);
+            const relevantSites = sites.filter((s) => {
+                const url = s.url || "";
+                const domain = result.companyDomain.replace(/^www\./, "");
+                const companyName = (companyData.name || "").toLowerCase();
+                return (url.includes(domain) ||
+                    url.includes(companyName.replace(/\s+/g, "-")) ||
+                    url.includes(companyName.replace(/\s+/g, "")));
+            });
+            if (relevantSites.length > 0) {
+                reviewHighlight = relevantSites
+                    .map((s) => `${s.platform}: ${s.reviewCount || "reviews found"} (${s.url})`)
+                    .join("; ");
+            }
+            // Fall back to summary if no site-level match but summary exists
+            if (!reviewHighlight && parsed.summary) {
+                reviewHighlight = parsed.summary;
+            }
+        }
+        catch {
+            // ignore parse errors
+        }
+    }
+    let positioningOneLiner = null;
+    let keyDifferentiators = [];
+    if (positioning) {
+        try {
+            const desc = typeof positioning === "string" ? JSON.parse(positioning) : positioning;
+            const descObj = typeof desc.description === "string"
+                ? JSON.parse(desc.description)
+                : desc.description || {};
+            positioningOneLiner =
+                descObj.UniqueValueProposition ||
+                    descObj.ExamplePositioningStatement ||
+                    null;
+            keyDifferentiators = descObj.keyDifferentiators || [];
+        }
+        catch {
+            // ignore parse errors
+        }
+    }
+    base.proofDigest = {
+        caseStudyCount,
+        caseStudySummary,
+        reviewHighlight,
+        positioningOneLiner,
+        keyDifferentiators,
+    };
+    return base;
+}