@agifyai/leadify-mcp 8.5.1 → 8.5.2

package/README.md

@@ -102,6 +102,14 @@ Mode watch :
 npm run dev
 ```
 
+Canari de vérité commerciale en lecture seule :
+
+```bash
+LEADIFY_CANARY_ORGANIZATION_ID=org-id npm run canary:commercial
+```
+
+Le canari sélectionne une organisation et un groupe accessibles, relit la même source deux fois, ne publie aucun message et n'ajoute aucune activité. Les variables `LEADIFY_CANARY_LEAD_GROUP_ID`, `LEADIFY_CANARY_EMAIL`, `LEADIFY_CANARY_LINKEDIN_URL` et `LEADIFY_CANARY_LEAD_ID` permettent de fixer une cible déjà autorisée ; la clé et le contenu des conversations ne sont jamais affichés.
+
 ### Architecture
 
 ```
@@ -211,7 +219,7 @@ 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 nouvelle campagne rattachée à un groupe de leads (statut DRAFT). |
+| `create_campaign` | Créer une campagne DRAFT mono-canal rattachée à un groupe de leads. `channel` (`LINKEDIN` ou `EMAIL`) est obligatoire : aucun défaut LinkedIn implicite. La fenêtre de campagne (`startAt`/`endAt`) et le contrat de clôture ne sont pas encore supportés par l'API Leadify ; ne pas utiliser cet outil pour une campagne bornée dans le temps avant cette livraison. |
 | `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). |
@@ -221,6 +229,12 @@ Leadify et ne doit jamais être envoyée par un agent MCP.
 | `signal_disable` | Désactiver un signal (faux positif / écarté manuellement). Flip de `state` uniquement. |
 | `signal_delete` | Supprimer définitivement un signal (cas rare : donnée erronée, doublon). |
 | `add_activity` | Journaliser une interaction prospect (LinkedIn, email, call) dans le feed du lead. |
+| `crm_lookup_person` | Lire la personne, les deals et le stage CRM d'une cible explicite, sans écrire dans le CRM. |
+| `email_read_thread` | Lire un thread email borné et ses réponses, exclusions de délivrabilité et ambiguïtés. |
+| `linkedin_read_conversation` | Lire la conversation LinkedIn bornée d'un profil explicitement sélectionné. |
+| `unipile_read_messages` | Lire les messages LinkedIn Unipile bornés d'un profil explicitement sélectionné. |
+| `leadify_read_activity_feed` | Lire l'audit borné d'un lead ; le feed ne constitue jamais une preuve de réponse. |
+| `get_commercial_truth` | Réconcilier CRM, email, LinkedIn, Unipile et activité avec un statut, une fraîcheur et une action recommandée ; aucune écriture ni envoi. |
 | `compile_context_pack` | Compiler en lecture seule un Context Pack canonique depuis une cible explicite (`organization`, `lead_group`, `campaign`, `account`, `person`) ou un couple lead + campagne pour `WRITE_OUTREACH`. Retourne publications courantes, sources, freshness, contradictions et provenance. N’utilise jamais la Data Room legacy ni ne choisit de cible implicite. |
 | `get_context_workspace` | Lire le Context Workspace canonique versionné (`company_brain` ou `gtm_playbook`) d'une organisation explicitement sélectionnée. Retourne le brouillon et la dernière version publiée. |
 | `list_canonical_relationships` | Lire les liens canoniques typés d'une organisation, dans les deux directions. |

package/dist/server.js

@@ -15,6 +15,7 @@ import { registerFineTuningTools } from "./tools/fine_tuning.js";
 import { registerContextWorkspaceTools } from "./tools/context_workspace.js";
 import { registerLeadViewTools } from "./tools/views.js";
 import { registerRelationshipTools } from "./tools/relationships.js";
+import { registerCommercialTruthTools } from "./tools/commercial_truth.js";
 import { MCP_SERVER_NAME, MCP_VERSION } from "./version.js";
 export function createServer() {
     const server = new McpServer({
@@ -27,6 +28,7 @@ export function createServer() {
     registerLeadViewTools(server);
     registerLeadTools(server);
     registerRelationshipTools(server);
+    registerCommercialTruthTools(server);
     registerSchemaTools(server);
     registerLogTools(server);
     registerCampaignTools(server);

package/dist/tools/campaigns.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type LeadifyClient } from "../client.js";
 type CampaignReadClient = Pick<LeadifyClient, "get">;
-export declare function registerCampaignTools(server: McpServer, readClient?: CampaignReadClient): void;
+type CampaignWriteClient = Pick<LeadifyClient, "post">;
+export declare function registerCampaignTools(server: McpServer, readClient?: CampaignReadClient, writeClient?: CampaignWriteClient): void;
 export {};

package/dist/tools/campaigns.js

@@ -19,7 +19,7 @@ function assertCampaignBelongsToOrganization(data, organizationId) {
     }
     return campaign;
 }
-export function registerCampaignTools(server, readClient) {
+export function registerCampaignTools(server, readClient, writeClient) {
     // ── update_campaign_stats ──────────────────────────────────────────────
     server.tool("update_campaign_stats", "Update email campaign statistics for a lead group. If the given campaignSlug " +
         "doesn't exist in the group's stats yet, it is created; otherwise provided fields " +
@@ -88,27 +88,31 @@ export function registerCampaignTools(server, readClient) {
         }
     });
     // ── create_campaign ────────────────────────────────────────────────────
-    server.tool("create_campaign", "Create a new campaign linked to an existing lead group. The campaign is initialized " +
-        "in DRAFT status and can be configured with a persona. Returns the new campaign ID. " +
-        "Use update_campaign_status afterwards to move it to ACTIVE when ready.", {
+    server.tool("create_campaign", "Create a mono-channel DRAFT campaign linked to an existing lead group. channel is required " +
+        "so no campaign silently defaults to LinkedIn. The current Leadify API does not yet persist " +
+        "a campaign start/end window or closure contract: do not use this tool for a time-bounded " +
+        "campaign until that API support is released. Returns the new campaign ID; use " +
+        "update_campaign_status only after the campaign is fully configured and explicitly approved.", {
         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."),
         description: z.string().optional().describe("Optional description."),
         persona_id: z
             .string()
             .optional()
             .describe("ID of the persona to assign (optional)."),
-    }, async ({ name, lead_group_id, description, persona_id }) => {
+    }, async ({ name, lead_group_id, channel, description, persona_id }) => {
         try {
             const body = {
                 name,
                 leadGroupId: lead_group_id,
+                channel,
             };
             if (description !== undefined)
                 body.description = description;
             if (persona_id !== undefined)
                 body.personaId = persona_id;
-            const data = await getClient().post("/api/campaign", body);
+            const data = await (writeClient ?? getClient()).post("/api/campaign", body);
             return toolResult(data);
         }
         catch (error) {

package/dist/tools/commercial_truth.d.ts

@@ -0,0 +1,48 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type LeadifyClient } from "../client.js";
+type CommercialReadClient = Pick<LeadifyClient, "get">;
+type RecordValue = Record<string, unknown>;
+export type CommercialSource = "crm" | "email" | "linkedin" | "unipile" | "leadify_activity";
+export type CommercialDirection = "inbound" | "outbound" | "system" | "mixed" | "unknown";
+export type CommercialStatus = "client" | "prospect" | "in_crm" | "not_in_crm" | "replied" | "contacted" | "excluded" | "audit_only" | "no_observed_activity" | "no_action" | "review_required" | "handoff_required" | "unknown";
+export interface CommercialFreshness {
+    observedAt: string | null;
+    state: "fresh" | "stale" | "unknown";
+    ageMs?: number;
+}
+export interface CommercialProjection {
+    source: CommercialSource | "reconciled";
+    date: string | null;
+    direction: CommercialDirection;
+    status: CommercialStatus;
+    optOut: boolean;
+    bounce: boolean;
+    suppression: boolean;
+    handoff: boolean;
+    freshness: CommercialFreshness;
+    ambiguities: string[];
+}
+export interface CommercialSourceSnapshot {
+    source: CommercialSource;
+    configured: boolean;
+    projection: CommercialProjection;
+    pagination: RecordValue;
+    evidence: RecordValue;
+    payload: RecordValue;
+}
+export interface CommercialReconciliation {
+    status: CommercialStatus;
+    recommendedAction: string;
+    responded: boolean;
+    inCrm: boolean;
+    crmStage: "client" | "prospect" | "none" | "unknown";
+    optOut: boolean;
+    bounce: boolean;
+    suppression: boolean;
+    handoff: boolean;
+    freshness: CommercialFreshness;
+    ambiguities: string[];
+}
+export declare function reconcileCommercialSources(sources: CommercialSourceSnapshot[]): CommercialReconciliation;
+export declare function registerCommercialTruthTools(server: McpServer, client?: CommercialReadClient): void;
+export {};

package/dist/tools/commercial_truth.js

@@ -0,0 +1,1141 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { handleToolError, toolError, toolResult } from "../types.js";
+const DEFAULT_LIMIT = 25;
+const MAX_LIMIT = 50;
+const DEFAULT_CONTENT_LIMIT = 1_000;
+const MAX_CONTENT_LIMIT = 5_000;
+const DEFAULT_FRESHNESS_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
+const MAX_FRESHNESS_MAX_AGE_MS = 90 * 24 * 60 * 60 * 1_000;
+const MAX_TO_ADDRESSES = 10;
+const MAX_CONTACTS = 10;
+const MAX_AMBIGUITIES = 20;
+class IntegrationNotConfiguredError extends Error {
+    source;
+    organizationId;
+    constructor(source, organizationId) {
+        super(`${source} integration is not configured for organization "${organizationId}"`);
+        this.name = "IntegrationNotConfiguredError";
+        this.source = source;
+        this.organizationId = organizationId;
+    }
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function stringValue(value, max = 500) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const marker = "… [truncated]";
+    return trimmed.length > max
+        ? `${trimmed.slice(0, Math.max(0, max - marker.length))}${marker}`
+        : trimmed;
+}
+function firstString(source, keys, max = 500) {
+    return keys.map((key) => stringValue(source[key], max)).find((value) => value !== null) ?? null;
+}
+function booleanValue(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes", "y", "oui"].includes(normalized))
+        return true;
+    if (["false", "0", "no", "n", "non", "null", "none"].includes(normalized))
+        return false;
+    return undefined;
+}
+function safeUrl(value, max = 500) {
+    const raw = stringValue(value, max);
+    if (!raw)
+        return null;
+    try {
+        const url = new URL(raw);
+        url.search = "";
+        url.hash = "";
+        return url.toString().slice(0, max);
+    }
+    catch {
+        return null;
+    }
+}
+const SECRET_KEY = /(api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|authorization|cookie|password|secret|private[_-]?key)/i;
+function safeValue(value, contentLimit, depth = 0) {
+    if (value === null || typeof value === "boolean" || typeof value === "number")
+        return value;
+    if (typeof value === "string")
+        return stringValue(value, contentLimit);
+    if (depth >= 2)
+        return "[omitted]";
+    if (Array.isArray(value))
+        return value.slice(0, 10).map((item) => safeValue(item, contentLimit, depth + 1));
+    if (typeof value !== "object")
+        return undefined;
+    return Object.entries(value)
+        .slice(0, 20)
+        .reduce((result, [key, item]) => {
+        if (!SECRET_KEY.test(key))
+            result[key] = safeValue(item, contentLimit, depth + 1);
+        return result;
+    }, {});
+}
+function boundedArray(value, limit) {
+    return Array.isArray(value) ? value.slice(0, limit) : [];
+}
+function arrayAt(source, keys) {
+    return keys.map((key) => source[key]).find((value) => Array.isArray(value)) ?? [];
+}
+function nestedArrayAt(source, parentKeys, keys) {
+    return parentKeys
+        .map((parentKey) => record(source[parentKey]))
+        .map((parent) => arrayAt(parent, keys))
+        .find((items) => items.length > 0) ?? [];
+}
+function normalizeDirection(value) {
+    const normalized = String(value ?? "").trim().toLowerCase();
+    if (["inbound", "incoming", "received", "replied"].includes(normalized))
+        return "inbound";
+    if (["outbound", "outgoing", "sent", "from_us"].includes(normalized))
+        return "outbound";
+    if (["system", "internal"].includes(normalized))
+        return "system";
+    return "unknown";
+}
+function normalizeStatus(value) {
+    return String(value ?? "").trim().toLowerCase().replace(/[\s-]+/g, "_");
+}
+function looksLikeDate(value) {
+    return typeof value === "string" && !Number.isNaN(Date.parse(value));
+}
+function observedDate(values) {
+    return values.filter(looksLikeDate).sort().at(-1) ?? null;
+}
+function dateFrom(source) {
+    return firstString(source, [
+        "date",
+        "occurredAt",
+        "createdAt",
+        "updatedAt",
+        "timestamp",
+        "sentAt",
+        "receivedAt",
+        "lastActivity",
+    ], 100);
+}
+function limitFor(target) {
+    return Math.min(Math.max(1, Math.floor(target.limit ?? DEFAULT_LIMIT)), MAX_LIMIT);
+}
+function contentLimitFor(target) {
+    return Math.min(Math.max(100, Math.floor(target.max_content_chars ?? DEFAULT_CONTENT_LIMIT)), MAX_CONTENT_LIMIT);
+}
+function freshnessMaxAgeFor(target) {
+    return Math.min(Math.max(1, Math.floor(target.freshness_max_age_ms ?? DEFAULT_FRESHNESS_MAX_AGE_MS)), MAX_FRESHNESS_MAX_AGE_MS);
+}
+function makeFreshness(date, target) {
+    if (!date || !looksLikeDate(date))
+        return { observedAt: date, state: "unknown" };
+    const ageMs = Math.max(0, Date.now() - Date.parse(date));
+    return {
+        observedAt: date,
+        ageMs,
+        state: ageMs <= freshnessMaxAgeFor(target) ? "fresh" : "stale",
+    };
+}
+function uniqueAmbiguities(values) {
+    return [...new Set(values.filter(Boolean))].slice(0, MAX_AMBIGUITIES);
+}
+function makeProjection(source, target, values) {
+    return {
+        source,
+        date: values.date ?? null,
+        direction: values.direction ?? "unknown",
+        status: values.status ?? "unknown",
+        optOut: values.optOut === true,
+        bounce: values.bounce === true,
+        suppression: values.suppression === true,
+        handoff: values.handoff === true,
+        freshness: makeFreshness(values.date ?? null, target),
+        ambiguities: uniqueAmbiguities(values.ambiguities ?? []),
+    };
+}
+function addPagination(query, target) {
+    query.set("limit", String(limitFor(target)));
+    if (target.cursor)
+        query.set("cursor", target.cursor);
+}
+function scopedQuery(target) {
+    const query = new URLSearchParams({
+        organizationId: target.organization_id,
+        leadGroupId: target.lead_group_id,
+    });
+    if (target.campaign_id)
+        query.set("campaignId", target.campaign_id);
+    if (target.page !== undefined)
+        query.set("page", String(Math.max(1, Math.floor(target.page))));
+    addPagination(query, target);
+    return query;
+}
+function pagination(data, target, returned, rawCount) {
+    const source = record(data.pagination ?? data.pageInfo ?? data.meta);
+    const keys = ["page", "limit", "total", "totalPages", "hasMore", "nextCursor", "next_cursor", "previousCursor", "previous_cursor"];
+    const result = keys.reduce((output, key) => {
+        if (source[key] !== undefined)
+            output[key] = safeValue(source[key], 200);
+        return output;
+    }, {});
+    const next = firstString(data, ["nextCursor", "next_cursor"], 500)
+        ?? firstString(source, ["nextCursor", "next_cursor"], 500);
+    if (next && result.nextCursor === undefined && result.next_cursor === undefined)
+        result.nextCursor = next;
+    if (result.hasMore === undefined && next)
+        result.hasMore = true;
+    result.returned = returned;
+    if ((rawCount ?? returned) > returned)
+        result.truncated = true;
+    return result;
+}
+function responseOrganizationId(data) {
+    const organization = record(data.organization);
+    const leadGroup = record(data.leadGroup);
+    const campaign = record(data.campaign);
+    const nestedData = record(data.data);
+    const response = record(data.response);
+    return firstString(data, ["organizationId", "organization_id"], 200)
+        ?? firstString(organization, ["id", "organizationId"], 200)
+        ?? firstString(leadGroup, ["organizationId", "organization_id"], 200)
+        ?? firstString(campaign, ["organizationId", "organization_id"], 200)
+        ?? firstString(nestedData, ["organizationId", "organization_id"], 200)
+        ?? firstString(response, ["organizationId", "organization_id"], 200);
+}
+function responseGroupId(data) {
+    const leadGroup = record(data.leadGroup);
+    const nestedData = record(data.data);
+    const response = record(data.response);
+    return firstString(data, ["leadGroupId", "lead_group_id", "groupId", "group_id"], 200)
+        ?? firstString(leadGroup, ["id", "leadGroupId", "groupId"], 200)
+        ?? firstString(nestedData, ["leadGroupId", "lead_group_id", "groupId", "group_id"], 200)
+        ?? firstString(response, ["leadGroupId", "lead_group_id", "groupId", "group_id"], 200);
+}
+function responseLeadId(data) {
+    const nestedData = record(data.data);
+    return firstString(data, ["leadId", "lead_id"], 200)
+        ?? firstString(nestedData, ["leadId", "lead_id"], 200);
+}
+function responseCampaignId(data) {
+    const campaign = record(data.campaign);
+    const nestedData = record(data.data);
+    return firstString(data, ["campaignId", "campaign_id"], 200)
+        ?? firstString(campaign, ["id", "campaignId"], 200)
+        ?? firstString(nestedData, ["campaignId", "campaign_id"], 200);
+}
+function assertScopedResponse(data, target, source) {
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        throw new Error(`Leadify returned an invalid ${source} read response`);
+    }
+    const value = data;
+    const actualOrganizationId = responseOrganizationId(value);
+    if (actualOrganizationId !== null && actualOrganizationId !== target.organization_id) {
+        throw new Error(`${source} response belongs to organization "${actualOrganizationId}", not the explicitly selected organization "${target.organization_id}"`);
+    }
+    const actualGroupId = responseGroupId(value);
+    if (actualGroupId !== null && actualGroupId !== target.lead_group_id) {
+        throw new Error(`${source} response belongs to lead group "${actualGroupId}", not the explicitly selected group "${target.lead_group_id}"`);
+    }
+    const actualLeadId = responseLeadId(value);
+    if (target.lead_id && actualLeadId !== null && actualLeadId !== target.lead_id) {
+        throw new Error(`${source} response belongs to lead "${actualLeadId}", not the explicitly selected lead "${target.lead_id}"`);
+    }
+    const actualCampaignId = responseCampaignId(value);
+    if (target.campaign_id && actualCampaignId !== null && actualCampaignId !== target.campaign_id) {
+        throw new Error(`${source} response belongs to campaign "${actualCampaignId}", not the explicitly selected campaign "${target.campaign_id}"`);
+    }
+    const nestedItems = ["messages", "entries", "activities", "items", "data", "deals", "domainContacts", "conversations"]
+        .flatMap((key) => Array.isArray(value[key]) ? value[key].slice(0, MAX_LIMIT) : []);
+    nestedItems.forEach((itemValue) => {
+        const item = record(itemValue);
+        const itemOrganizationId = responseOrganizationId(item);
+        if (itemOrganizationId !== null && itemOrganizationId !== target.organization_id) {
+            throw new Error(`${source} response contains a record from organization "${itemOrganizationId}" outside the explicitly selected organization`);
+        }
+        const itemGroupId = responseGroupId(item);
+        if (itemGroupId !== null && itemGroupId !== target.lead_group_id) {
+            throw new Error(`${source} response contains a record from lead group "${itemGroupId}" outside the explicitly selected group`);
+        }
+        const itemLeadId = responseLeadId(item);
+        if (target.lead_id && itemLeadId !== null && itemLeadId !== target.lead_id) {
+            throw new Error(`${source} response contains a record from lead "${itemLeadId}" outside the explicitly selected lead`);
+        }
+    });
+    return value;
+}
+function configuredFlag(data, source) {
+    const key = {
+        crm: "crmConfigured",
+        email: "emailConfigured",
+        linkedin: "linkedinConfigured",
+        unipile: "unipileConfigured",
+        leadify_activity: "activityConfigured",
+    }[source];
+    if (data[key] === false || booleanValue(data[key]) === false)
+        return false;
+    if (data.configured === false || booleanValue(data.configured) === false || data.integrationConfigured === false || booleanValue(data.integrationConfigured) === false)
+        return false;
+    return true;
+}
+function requireConfigured(data, target, source) {
+    if (!configuredFlag(data, source))
+        throw new IntegrationNotConfiguredError(source, target.organization_id);
+}
+function explicitFlag(value, keys) {
+    const wanted = new Set(keys.map((key) => key.toLowerCase().replace(/[^a-z]/g, "")));
+    const visit = (candidate, depth) => {
+        if (depth > 4 || !candidate || typeof candidate !== "object")
+            return false;
+        if (Array.isArray(candidate))
+            return candidate.some((item) => visit(item, depth + 1));
+        return Object.entries(candidate).some(([key, item]) => {
+            const normalizedKey = key.toLowerCase().replace(/[^a-z]/g, "");
+            if (wanted.has(normalizedKey)) {
+                if (booleanValue(item) === true)
+                    return true;
+                if (normalizedKey.includes("handoff") && item && typeof item === "object")
+                    return true;
+                if (typeof item === "string" && item.trim() && (normalizedKey.endsWith("at") || normalizedKey.includes("handoff")))
+                    return true;
+            }
+            if (["status", "deliverystatus", "event"].includes(normalizedKey)) {
+                const normalizedValue = normalizeStatus(item);
+                if (keys.includes("bounce") && ["bounce", "bounced", "hard_bounce", "soft_bounce", "undeliverable"].includes(normalizedValue))
+                    return true;
+                if (keys.includes("optOut") && ["opted_out", "unsubscribed", "do_not_contact"].includes(normalizedValue))
+                    return true;
+                if (keys.includes("suppression") && ["suppressed", "suppression", "do_not_contact"].includes(normalizedValue))
+                    return true;
+                if (keys.includes("handoff") && ["handoff", "handed_off", "crm_handoff"].includes(normalizedValue))
+                    return true;
+            }
+            return visit(item, depth + 1);
+        });
+    };
+    return visit(value, 0);
+}
+function commercialFlags(value) {
+    return {
+        optOut: explicitFlag(value, ["optOut", "optedOut", "unsubscribed", "unsubscribe", "unsubscribedAt", "optOutAt", "doNotContact", "excluded"]),
+        bounce: explicitFlag(value, ["bounce", "bounced", "hardBounce", "softBounce", "bouncedAt", "bounceAt", "undeliverable"]),
+        suppression: explicitFlag(value, ["suppression", "suppressed", "suppressionStatus", "suppressedAt"]),
+        handoff: explicitFlag(value, ["handoff", "crmHandoff", "handedOff", "handoffAt"]),
+    };
+}
+function safePerson(value) {
+    const source = record(value);
+    if (Object.keys(source).length === 0)
+        return null;
+    return {
+        id: firstString(source, ["id", "personId"], 200),
+        name: firstString(source, ["name", "fullName"], 300),
+        email: firstString(source, ["email"], 320),
+        jobTitle: firstString(source, ["jobTitle", "title"], 300),
+        companyId: firstString(source, ["companyId"], 200),
+        companyName: firstString(source, ["companyName", "company"], 300),
+    };
+}
+function safeDeal(value, contentLimit) {
+    const source = record(value);
+    const contacts = boundedArray(source.contacts, MAX_CONTACTS).map((contact) => {
+        const item = record(contact);
+        return {
+            id: firstString(item, ["id"], 200),
+            name: firstString(item, ["name", "fullName"], 300),
+            email: firstString(item, ["email"], 320),
+        };
+    });
+    const result = {
+        id: firstString(source, ["id", "dealId"], 200),
+        name: firstString(source, ["name", "title"], 300),
+        status: normalizeStatus(source.status),
+        nativeStage: firstString(source, ["nativeStage", "stage"], 300),
+        amount: typeof source.amount === "number" ? source.amount : null,
+        currency: firstString(source, ["currency"], 50),
+        contacts,
+    };
+    const date = dateFrom(source);
+    if (date)
+        result.date = date;
+    if (source.description !== undefined)
+        result.description = stringValue(source.description, contentLimit);
+    return result;
+}
+function safeDomainContact(value) {
+    return safePerson(value) ?? { id: null, name: null, email: null };
+}
+function safeMailboxes(value) {
+    return boundedArray(value, MAX_LIMIT).map((mailbox) => {
+        const source = record(mailbox);
+        return {
+            provider: firstString(source, ["provider"], 100),
+            email: firstString(source, ["email", "mailboxEmail"], 320),
+            readable: booleanValue(source.readable) ?? false,
+            status: firstString(source, ["status"], 200),
+            reason: firstString(source, ["reason", "error"], 500),
+        };
+    });
+}
+function safeAddresses(value) {
+    return boundedArray(value, MAX_TO_ADDRESSES)
+        .map((item) => stringValue(item, 320))
+        .filter((item) => item !== null);
+}
+function safeEmailMessage(value, contentLimit) {
+    const source = record(value);
+    const result = {
+        id: firstString(source, ["id", "messageId"], 200),
+        threadId: firstString(source, ["threadId", "thread_id"], 200),
+        conversationId: firstString(source, ["conversationId", "conversation_id"], 200),
+        direction: normalizeDirection(source.direction),
+        counterpartyEmail: firstString(source, ["counterpartyEmail", "counterparty_email"], 320),
+        from: firstString(source, ["from", "sender", "senderEmail"], 320),
+        to: safeAddresses(source.to),
+        date: dateFrom(source),
+        subject: stringValue(source.subject, contentLimit),
+        snippet: stringValue(source.snippet, contentLimit),
+        bodyText: stringValue(source.bodyText ?? source.body ?? source.text, contentLimit),
+    };
+    const mailboxProvider = firstString(source, ["mailboxProvider", "provider"], 100);
+    const mailboxEmail = firstString(source, ["mailboxEmail"], 320);
+    if (mailboxProvider)
+        result.mailboxProvider = mailboxProvider;
+    if (mailboxEmail)
+        result.mailboxEmail = mailboxEmail;
+    const status = firstString(source, ["status", "deliveryStatus"], 100);
+    if (status)
+        result.status = status;
+    const flags = commercialFlags(source);
+    if (flags.optOut)
+        result.optOut = true;
+    if (flags.bounce)
+        result.bounced = true;
+    if (flags.suppression)
+        result.suppressed = true;
+    return result;
+}
+function safeSocialMessage(value, contentLimit) {
+    const source = record(value);
+    const result = {
+        id: firstString(source, ["id", "messageId"], 200),
+        conversationId: firstString(source, ["conversationId", "conversation_id", "threadId"], 200),
+        direction: normalizeDirection(source.direction),
+        from: firstString(source, ["from", "sender", "senderName"], 320),
+        date: dateFrom(source),
+        text: stringValue(source.text ?? source.bodyText ?? source.body ?? source.content, contentLimit),
+    };
+    const profileUrl = safeUrl(source.profileUrl ?? source.linkedinUrl ?? source.participantLinkedinUrl);
+    if (profileUrl)
+        result.profileUrl = profileUrl;
+    const attachments = boundedArray(source.attachments, MAX_TO_ADDRESSES).map((attachment) => {
+        const item = record(attachment);
+        return { name: stringValue(item.name, 300), url: safeUrl(item.url) };
+    });
+    if (attachments.length > 0)
+        result.attachments = attachments;
+    const flags = commercialFlags(source);
+    if (flags.optOut)
+        result.optOut = true;
+    if (flags.bounce)
+        result.bounced = true;
+    if (flags.suppression)
+        result.suppressed = true;
+    return result;
+}
+function dedupeEmailMessages(messages) {
+    const seen = new Set();
+    return messages.filter((message) => {
+        const source = record(message);
+        const key = `${dateFrom(source) ?? ""}|${(firstString(source, ["from", "sender", "senderEmail"], 320) ?? "").toLowerCase()}|${(firstString(source, ["subject"], 500) ?? "").toLowerCase()}`;
+        if (seen.has(key) && key !== "||")
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function latestDirection(messages) {
+    const directions = messages
+        .map((message) => normalizeDirection(message.direction))
+        .filter((direction) => direction !== "unknown");
+    if (directions.length === 0)
+        return "unknown";
+    if (new Set(directions).size > 1)
+        return "mixed";
+    return directions[0];
+}
+function statusForMessages(messages, flags) {
+    if (flags.optOut || flags.bounce || flags.suppression)
+        return "excluded";
+    if (messages.some((message) => normalizeDirection(message.direction) === "inbound"))
+        return "replied";
+    if (messages.some((message) => normalizeDirection(message.direction) === "outbound"))
+        return "contacted";
+    return "no_observed_activity";
+}
+function crmProjection(data, target) {
+    requireConfigured(data, target, "crm");
+    const contentLimit = contentLimitFor(target);
+    const rawDeals = arrayAt(data, ["deals"]);
+    const deals = boundedArray(rawDeals, limitFor(target)).map((deal) => safeDeal(deal, contentLimit));
+    const domainContacts = boundedArray(data.domainContacts, limitFor(target)).map(safeDomainContact);
+    const person = safePerson(data.person);
+    const statuses = rawDeals.map((deal) => normalizeStatus(record(deal).status));
+    const found = booleanValue(data.found) ?? person !== null;
+    const stage = statuses.some((status) => ["won", "closed_won"].includes(status))
+        ? "client"
+        : statuses.some((status) => ["open", "in_progress", "qualified"].includes(status))
+            ? "prospect"
+            : found
+                ? "in_crm"
+                : "not_in_crm";
+    const flags = commercialFlags(data);
+    const dates = [dateFrom(data), ...rawDeals.map((deal) => dateFrom(record(deal))), dateFrom(record(data.person))];
+    const ambiguities = [];
+    if (rawDeals.length > deals.length)
+        ambiguities.push(`CRM deals truncated to ${limitFor(target)} records`);
+    if (booleanValue(data.domainSearched) === true && domainContacts.length >= limitFor(target))
+        ambiguities.push("CRM domain contacts may be truncated");
+    const projectionValue = makeProjection("crm", target, {
+        date: observedDate(dates),
+        direction: "system",
+        status: flags.optOut || flags.bounce || flags.suppression ? "excluded" : stage,
+        ...flags,
+        ambiguities,
+    });
+    const payload = {
+        source: "crm",
+        target: targetDescription(target),
+        organizationId: target.organization_id,
+        leadGroupId: target.lead_group_id,
+        ...(target.campaign_id ? { campaignId: target.campaign_id } : {}),
+        crmConfigured: true,
+        provider: firstString(data, ["provider"], 100),
+        found,
+        person,
+        deals,
+        companyDomain: firstString(data, ["domain", "companyDomain"], 300),
+        domainSearched: booleanValue(data.domainSearched) ?? false,
+        domainContacts,
+        pagination: pagination(data, target, deals.length, rawDeals.length),
+        stage,
+        optOut: projectionValue.optOut,
+        bounce: projectionValue.bounce,
+        suppression: projectionValue.suppression,
+        handoff: projectionValue.handoff,
+        freshness: projectionValue.freshness,
+        ambiguities: projectionValue.ambiguities,
+        projection: projectionValue,
+        commercialTruth: projectionValue,
+        redactions: { secretsOmitted: true, maxContentChars: contentLimit },
+    };
+    return { source: "crm", configured: true, projection: projectionValue, pagination: payload.pagination, evidence: { found, dealCount: deals.length, stage }, payload };
+}
+function emailProjection(data, target) {
+    requireConfigured(data, target, "email");
+    const contentLimit = contentLimitFor(target);
+    const rawMessages = arrayAt(data, ["messages"]);
+    const uniqueMessages = dedupeEmailMessages(rawMessages);
+    const selectedMessages = boundedArray(uniqueMessages, limitFor(target));
+    const messages = selectedMessages.map((message) => safeEmailMessage(message, contentLimit));
+    const messageRecords = messages.map(record);
+    const flags = commercialFlags({ ...data, messages: rawMessages });
+    const reportedMessageCount = typeof data.messageCount === "number" ? data.messageCount : rawMessages.length;
+    const mailboxes = safeMailboxes(data.mailboxesSearched);
+    const problematicMailboxes = mailboxes.filter((mailbox) => mailbox.readable !== true || mailbox.reason !== null);
+    const ambiguities = [];
+    if (rawMessages.length !== uniqueMessages.length)
+        ambiguities.push("Duplicate mailbox copies were collapsed before reconciliation");
+    if (Math.max(rawMessages.length, reportedMessageCount) > selectedMessages.length)
+        ambiguities.push(`Email messages truncated to ${limitFor(target)} records`);
+    if (problematicMailboxes.length > 0)
+        ambiguities.push(`${problematicMailboxes.length} mailbox(es) could not be fully read`);
+    const status = statusForMessages(messageRecords, flags);
+    const projectionValue = makeProjection("email", target, {
+        date: observedDate([dateFrom(data), ...messageRecords.map(dateFrom)]),
+        direction: latestDirection(messageRecords),
+        status,
+        ...flags,
+        ambiguities,
+    });
+    const payload = {
+        source: "email",
+        target: targetDescription(target),
+        organizationId: target.organization_id,
+        leadGroupId: target.lead_group_id,
+        ...(target.campaign_id ? { campaignId: target.campaign_id } : {}),
+        emailConfigured: true,
+        counterparty: firstString(data, ["counterparty"], 320),
+        companyDomain: firstString(data, ["domain", "companyDomain"], 300),
+        domainSearched: booleanValue(data.domainSearched) ?? false,
+        mailboxesSearched: mailboxes,
+        messageCount: messages.length,
+        rawMessageCount: reportedMessageCount,
+        messages,
+        pagination: pagination(data, target, messages.length, Math.max(rawMessages.length, reportedMessageCount)),
+        responded: status === "replied",
+        optOut: projectionValue.optOut,
+        bounce: projectionValue.bounce,
+        suppression: projectionValue.suppression,
+        handoff: projectionValue.handoff,
+        freshness: projectionValue.freshness,
+        ambiguities: projectionValue.ambiguities,
+        projection: projectionValue,
+        commercialTruth: projectionValue,
+        redactions: { secretsOmitted: true, maxContentChars: contentLimit },
+    };
+    return {
+        source: "email",
+        configured: true,
+        projection: projectionValue,
+        pagination: payload.pagination,
+        evidence: {
+            messageCount: messages.length,
+            inboundCount: messageRecords.filter((message) => normalizeDirection(message.direction) === "inbound").length,
+            outboundCount: messageRecords.filter((message) => normalizeDirection(message.direction) === "outbound").length,
+            responseObserved: status === "replied",
+        },
+        payload,
+    };
+}
+function socialProjection(data, target, source) {
+    requireConfigured(data, target, source);
+    const contentLimit = contentLimitFor(target);
+    const nestedMessages = nestedArrayAt(data, ["conversation", "thread", "data"], ["messages"]);
+    const rawMessages = arrayAt(data, ["messages"]);
+    const allMessages = rawMessages.length > 0 ? rawMessages : nestedMessages;
+    const selectedMessages = boundedArray(allMessages, limitFor(target));
+    const messages = selectedMessages.map((message) => safeSocialMessage(message, contentLimit));
+    const messageRecords = messages.map(record);
+    const flags = commercialFlags({ ...data, messages: allMessages });
+    const reportedMessageCount = typeof data.totalMessageCount === "number" ? data.totalMessageCount : allMessages.length;
+    const ambiguities = [];
+    if (Math.max(allMessages.length, reportedMessageCount) > selectedMessages.length)
+        ambiguities.push(`${source} messages truncated to ${limitFor(target)} records`);
+    const status = statusForMessages(messageRecords, flags);
+    const configuredKey = source === "linkedin" ? "linkedinConfigured" : "unipileConfigured";
+    const conversations = arrayAt(data, ["conversations"]);
+    const conversation = record(data.conversation);
+    const safeConversations = boundedArray(conversations, limitFor(target)).map((value) => {
+        const item = record(value);
+        return {
+            id: firstString(item, ["id", "conversationId"], 200),
+            participantName: firstString(item, ["participantName", "name"], 300),
+            participantLinkedinUrl: safeUrl(item.participantLinkedinUrl ?? item.linkedinUrl),
+            lastActivity: dateFrom(item),
+            messageCount: typeof item.messageCount === "number" ? item.messageCount : null,
+        };
+    });
+    if (Object.keys(conversation).length > 0 && safeConversations.length === 0) {
+        safeConversations.push({
+            id: firstString(conversation, ["id", "conversationId"], 200),
+            participantName: firstString(conversation, ["participantName", "name"], 300),
+            participantLinkedinUrl: safeUrl(conversation.participantLinkedinUrl ?? conversation.linkedinUrl),
+            lastActivity: dateFrom(conversation),
+            messageCount: typeof conversation.messageCount === "number" ? conversation.messageCount : messages.length,
+        });
+    }
+    const projectionValue = makeProjection(source, target, {
+        date: observedDate([dateFrom(data), ...messageRecords.map(dateFrom), ...safeConversations.map(dateFrom)]),
+        direction: latestDirection(messageRecords),
+        status,
+        ...flags,
+        ambiguities,
+    });
+    const payload = {
+        source,
+        target: targetDescription(target),
+        organizationId: target.organization_id,
+        leadGroupId: target.lead_group_id,
+        ...(target.campaign_id ? { campaignId: target.campaign_id } : {}),
+        [configuredKey]: true,
+        counterparty: firstString(data, ["counterparty"], 320),
+        conversations: safeConversations,
+        messages,
+        totalMessageCount: reportedMessageCount,
+        pagination: pagination(data, target, messages.length, Math.max(allMessages.length, reportedMessageCount)),
+        responded: status === "replied",
+        optOut: projectionValue.optOut,
+        bounce: projectionValue.bounce,
+        suppression: projectionValue.suppression,
+        handoff: projectionValue.handoff,
+        freshness: projectionValue.freshness,
+        ambiguities: projectionValue.ambiguities,
+        projection: projectionValue,
+        commercialTruth: projectionValue,
+        redactions: { secretsOmitted: true, maxContentChars: contentLimit },
+    };
+    return {
+        source,
+        configured: true,
+        projection: projectionValue,
+        pagination: payload.pagination,
+        evidence: {
+            messageCount: messages.length,
+            inboundCount: messageRecords.filter((message) => normalizeDirection(message.direction) === "inbound").length,
+            outboundCount: messageRecords.filter((message) => normalizeDirection(message.direction) === "outbound").length,
+            responseObserved: status === "replied",
+        },
+        payload,
+    };
+}
+function activityProjection(data, target) {
+    requireConfigured(data, target, "leadify_activity");
+    const contentLimit = contentLimitFor(target);
+    const rawEntries = arrayAt(data, ["entries", "activities", "items", "data"]);
+    const selectedEntries = boundedArray(rawEntries, limitFor(target));
+    const entries = selectedEntries.map((entry) => {
+        const item = record(entry);
+        return {
+            id: firstString(item, ["id"], 200),
+            leadId: firstString(item, ["leadId", "lead_id"], 200),
+            action: firstString(item, ["action"], 200),
+            target: firstString(item, ["target"], 200),
+            before: safeValue(item.before, contentLimit),
+            after: safeValue(item.after, contentLimit),
+            reason: stringValue(item.reason, contentLimit),
+            date: dateFrom(item),
+            createdAt: firstString(item, ["createdAt"], 100),
+        };
+    });
+    const ambiguities = ["Activity feed is an audit trail; it never proves that a person replied."];
+    if (rawEntries.length > selectedEntries.length)
+        ambiguities.push(`Activity entries truncated to ${limitFor(target)} records`);
+    const projectionValue = makeProjection("leadify_activity", target, {
+        date: observedDate([dateFrom(data), ...entries.map((entry) => entry.date)]),
+        direction: "system",
+        status: "audit_only",
+        // Activity rows are a mutation audit trail and cannot become commercial truth.
+        optOut: false,
+        bounce: false,
+        suppression: false,
+        handoff: false,
+        ambiguities,
+    });
+    const payload = {
+        source: "leadify_activity",
+        target: targetDescription(target),
+        organizationId: target.organization_id,
+        leadGroupId: target.lead_group_id,
+        ...(target.campaign_id ? { campaignId: target.campaign_id } : {}),
+        entries,
+        pagination: pagination(data, target, entries.length, rawEntries.length),
+        optOut: false,
+        bounce: false,
+        suppression: false,
+        handoff: false,
+        freshness: projectionValue.freshness,
+        ambiguities: projectionValue.ambiguities,
+        projection: projectionValue,
+        commercialTruth: projectionValue,
+        redactions: { secretsOmitted: true, maxContentChars: contentLimit, runIdentityOmitted: true },
+    };
+    return {
+        source: "leadify_activity",
+        configured: true,
+        projection: projectionValue,
+        pagination: payload.pagination,
+        evidence: { entryCount: entries.length, responseObserved: false, auditOnly: true },
+        payload,
+    };
+}
+function emailQuery(target) {
+    const query = scopedQuery(target);
+    query.set("email", target.email);
+    return query;
+}
+function linkedinQuery(target) {
+    const query = scopedQuery(target);
+    query.set("linkedinUrl", target.linkedin_url);
+    return query;
+}
+function activityQuery(target) {
+    const query = scopedQuery(target);
+    query.set("leadId", target.lead_id);
+    if (target.target)
+        query.set("target", target.target);
+    return query;
+}
+async function readCrm(client, target) {
+    const data = await client.get("/api/crm/lookup-person", emailQuery(target));
+    return crmProjection(assertScopedResponse(data, target, "crm"), target);
+}
+async function readEmail(client, target) {
+    const data = await client.get("/api/email/read-thread", emailQuery(target));
+    return emailProjection(assertScopedResponse(data, target, "email"), target);
+}
+async function readLinkedin(client, target) {
+    const data = await client.get("/api/linkedin/conversation", linkedinQuery(target));
+    return socialProjection(assertScopedResponse(data, target, "linkedin"), target, "linkedin");
+}
+async function readUnipile(client, target) {
+    const data = await client.get("/api/unipile/read-messages", linkedinQuery(target));
+    return socialProjection(assertScopedResponse(data, target, "unipile"), target, "unipile");
+}
+async function readActivity(client, target) {
+    const data = await client.get("/activity-feed", activityQuery(target));
+    return activityProjection(assertScopedResponse(data, target, "leadify_activity"), target);
+}
+function readTargetFromInput(input) {
+    return {
+        ...input,
+        organization_id: input.organization_id.trim(),
+        lead_group_id: input.lead_group_id.trim(),
+        email: input.email?.trim().toLowerCase(),
+        linkedin_url: input.linkedin_url?.trim(),
+        lead_id: input.lead_id?.trim(),
+        page: input.page,
+        campaign_id: input.campaign_id?.trim(),
+        cursor: input.cursor?.trim(),
+        target: input.target?.trim(),
+    };
+}
+function targetDescription(target) {
+    return {
+        organizationId: target.organization_id,
+        leadGroupId: target.lead_group_id,
+        ...(target.campaign_id ? { campaignId: target.campaign_id } : {}),
+        ...(target.email ? { email: target.email } : {}),
+        ...(target.linkedin_url ? { linkedinUrl: safeUrl(target.linkedin_url) ?? "[invalid-url]" } : {}),
+        ...(target.lead_id ? { leadId: target.lead_id } : {}),
+    };
+}
+export function reconcileCommercialSources(sources) {
+    const crm = sources.find((source) => source.source === "crm");
+    const conversationSources = sources.filter((source) => ["email", "linkedin", "unipile"].includes(source.source));
+    const responded = conversationSources.some((source) => source.projection.status === "replied" || source.evidence.responseObserved === true);
+    const optOut = sources.some((source) => source.projection.optOut);
+    const bounce = sources.some((source) => source.projection.bounce);
+    const suppression = sources.some((source) => source.projection.suppression);
+    const handoff = sources.some((source) => source.projection.handoff);
+    const crmStage = crm?.projection.status === "client"
+        ? "client"
+        : crm?.projection.status === "prospect"
+            ? "prospect"
+            : crm?.projection.status === "in_crm"
+                ? "none"
+                : "unknown";
+    const inCrm = crm?.projection.status === "client" || crm?.projection.status === "prospect" || crm?.projection.status === "in_crm";
+    const ambiguities = sources.flatMap((source) => source.projection.ambiguities);
+    if (crm?.projection.status === "not_in_crm" && conversationSources.some((source) => source.evidence.responseObserved === true || Number(source.evidence.messageCount ?? 0) > 0)) {
+        ambiguities.push("CRM found no matching person and a conversation source has observed messages");
+    }
+    const email = sources.find((source) => source.source === "email");
+    const unipile = sources.find((source) => source.source === "unipile");
+    if (email && unipile && Number(email.evidence.messageCount ?? 0) === 0 && Number(unipile.evidence.inboundCount ?? 0) > 0) {
+        ambiguities.push("Email has no observed messages and Unipile has an inbound message");
+    }
+    if (sources.some((source) => source.projection.freshness.state === "stale")) {
+        ambiguities.push("At least one commercial source is older than the requested freshness window");
+    }
+    const unique = uniqueAmbiguities(ambiguities);
+    let status;
+    let recommendedAction;
+    if (optOut || bounce || suppression) {
+        status = "excluded";
+        recommendedAction = "Do not contact, send, or create a follow-up activity; preserve the observed exclusion evidence.";
+    }
+    else if (unique.some((ambiguity) => /CRM found no|Email has no observed/i.test(ambiguity))) {
+        status = "review_required";
+        recommendedAction = "Pause outreach and review the divergent source evidence ahead of any qualification or CRM handoff.";
+    }
+    else if (crmStage === "client") {
+        status = "client";
+        recommendedAction = "Do not cold-prospect this company; review the existing client relationship instead.";
+    }
+    else if (handoff) {
+        status = "handoff_required";
+        recommendedAction = "Review the existing CRM handoff evidence; do not create a duplicate handoff or activity.";
+    }
+    else if (responded) {
+        status = "replied";
+        recommendedAction = "Stop cold outreach and review the observed reply before deciding on a human follow-up.";
+    }
+    else if (crmStage === "prospect") {
+        status = "prospect";
+        recommendedAction = "Treat as warm only; the CRM has an open sales process.";
+    }
+    else if (inCrm) {
+        status = "in_crm";
+        recommendedAction = "Use the existing CRM record and avoid creating a duplicate person or handoff.";
+    }
+    else if (conversationSources.some((source) => source.projection.status === "contacted")) {
+        status = "contacted";
+        recommendedAction = "Do not duplicate the observed outbound contact; inspect the source ahead of another touch.";
+    }
+    else if (sources.length === 0 || !sources.some((source) => !["no_observed_activity", "not_in_crm", "audit_only"].includes(source.projection.status))) {
+        status = "no_observed_activity";
+        recommendedAction = "Leave without action when no configured source provides new evidence.";
+    }
+    else {
+        status = "no_action";
+        recommendedAction = "No action is justified by the observed commercial sources.";
+    }
+    const dates = sources.map((source) => source.projection.date).filter((date) => date !== null);
+    const freshnessDate = observedDate(dates);
+    const freshness = freshnessDate
+        ? {
+            observedAt: freshnessDate,
+            state: sources.some((source) => source.projection.freshness.state === "stale") ? "stale" : "fresh",
+            ageMs: Math.max(...sources.map((source) => source.projection.freshness.ageMs ?? 0)),
+        }
+        : { observedAt: null, state: "unknown" };
+    return {
+        status,
+        recommendedAction,
+        responded,
+        inCrm,
+        crmStage,
+        optOut,
+        bounce,
+        suppression,
+        handoff,
+        freshness,
+        ambiguities: unique,
+    };
+}
+function integrationAction(source) {
+    if (source === "crm")
+        return "Connect a CRM integration in this organization, then retry the read.";
+    if (source === "email")
+        return "Connect a readable Gmail or Outlook mailbox in this organization, then retry the read.";
+    if (source === "unipile")
+        return "Connect an Unipile account in this organization, then retry the read.";
+    if (source === "linkedin")
+        return "Configure the LinkedIn conversation integration in this organization, then retry the read.";
+    return "Enable the Leadify activity feed in this organization, then retry the read.";
+}
+function missingIntegrationResult(error) {
+    const action = integrationAction(error.source);
+    return toolError(`${error.message}. ${action}`, {
+        code: "INTEGRATION_NOT_CONFIGURED",
+        source: error.source,
+        organizationId: error.organizationId,
+        readOnly: true,
+        action,
+    });
+}
+function safeErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.replace(/Bearer\s+[^\s]+/gi, "Bearer [redacted]").slice(0, 500);
+}
+function handleCommercialError(error) {
+    const result = handleToolError(error);
+    try {
+        const body = JSON.parse(result.content[0].text);
+        if (body.error !== undefined)
+            body.error = safeErrorMessage(body.error);
+        const details = record(body.details);
+        if (Object.hasOwn(details, "response"))
+            details.response = safeValue(details.response, DEFAULT_CONTENT_LIMIT);
+        if (Object.keys(details).length > 0)
+            body.details = details;
+        return {
+            ...result,
+            content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+        };
+    }
+    catch {
+        return result;
+    }
+}
+async function readSelectedSources(client, target) {
+    const requests = [
+        { source: "crm", enabled: Boolean(target.email), read: () => readCrm(client, target) },
+        { source: "email", enabled: Boolean(target.email), read: () => readEmail(client, target) },
+        { source: "linkedin", enabled: Boolean(target.linkedin_url), read: () => readLinkedin(client, target) },
+        { source: "unipile", enabled: Boolean(target.linkedin_url), read: () => readUnipile(client, target) },
+        { source: "leadify_activity", enabled: Boolean(target.lead_id), read: () => readActivity(client, target) },
+    ];
+    const snapshots = [];
+    const errors = [];
+    const skipped = [];
+    const processRequest = async (request) => {
+        if (!request.enabled) {
+            skipped.push(request.source);
+            return;
+        }
+        try {
+            snapshots.push(await request.read());
+        }
+        catch (error) {
+            if (error instanceof IntegrationNotConfiguredError) {
+                errors.push({ source: request.source, code: "INTEGRATION_NOT_CONFIGURED", message: safeErrorMessage(error), action: integrationAction(request.source) });
+            }
+            else {
+                errors.push({ source: request.source, code: "READ_FAILED", message: safeErrorMessage(error) });
+            }
+        }
+    };
+    await requests.reduce((chain, request) => chain.then(() => processRequest(request)), Promise.resolve());
+    return { snapshots, errors, skipped };
+}
+function aggregatePayload(target, result) {
+    const baseReconciliation = reconcileCommercialSources(result.snapshots);
+    const reconciliation = result.errors.length === 0 || baseReconciliation.status === "excluded"
+        ? baseReconciliation
+        : {
+            ...baseReconciliation,
+            status: "review_required",
+            recommendedAction: "Pause action and configure or retry every source reported in errors before relying on this read.",
+            ambiguities: uniqueAmbiguities([
+                ...baseReconciliation.ambiguities,
+                ...result.errors.map((error) => `${String(error.source)} could not be read`),
+            ]),
+        };
+    const sourcePayloads = result.snapshots.map((snapshot) => ({
+        source: snapshot.source,
+        configured: snapshot.configured,
+        projection: snapshot.projection,
+        evidence: snapshot.evidence,
+        pagination: snapshot.pagination,
+        data: snapshot.payload,
+    }));
+    const directionSet = new Set(result.snapshots.map((snapshot) => snapshot.projection.direction));
+    const projectionValue = {
+        source: "reconciled",
+        date: reconciliation.freshness.observedAt,
+        direction: result.snapshots.length === 0 ? "unknown" : directionSet.size === 1 ? result.snapshots[0].projection.direction : "mixed",
+        status: reconciliation.status,
+        optOut: reconciliation.optOut,
+        bounce: reconciliation.bounce,
+        suppression: reconciliation.suppression,
+        handoff: reconciliation.handoff,
+        freshness: reconciliation.freshness,
+        ambiguities: reconciliation.ambiguities,
+    };
+    return {
+        target: targetDescription(target),
+        readOnly: true,
+        noWrites: true,
+        sources: sourcePayloads,
+        skippedSources: result.skipped,
+        errors: result.errors,
+        projection: projectionValue,
+        commercialTruth: projectionValue,
+        reconciliation,
+        recommendedAction: reconciliation.recommendedAction,
+        sourceCount: sourcePayloads.length,
+    };
+}
+function readSchema() {
+    return {
+        organization_id: z.string().trim().min(1).max(200).describe("Organization selected explicitly from list_organizations or discover_leadify_context."),
+        lead_group_id: z.string().trim().min(1).max(200).describe("Lead group selected explicitly inside that organization; no implicit group is allowed."),
+        campaign_id: z.string().trim().min(1).max(200).optional().describe("Optional campaign selected explicitly to narrow the read."),
+        page: z.number().int().positive().max(10_000).optional().describe("One-based page number when the source uses page pagination."),
+        limit: z.number().int().min(1).max(MAX_LIMIT).optional().default(DEFAULT_LIMIT).describe(`Maximum records returned; hard-bounded to ${MAX_LIMIT}.`),
+        cursor: z.string().trim().min(1).max(500).optional().describe("Opaque cursor returned by the previous page."),
+        max_content_chars: z.number().int().min(100).max(MAX_CONTENT_LIMIT).optional().default(DEFAULT_CONTENT_LIMIT).describe(`Maximum characters kept in each content field; hard-bounded to ${MAX_CONTENT_LIMIT}.`),
+        freshness_max_age_ms: z.number().int().positive().max(MAX_FRESHNESS_MAX_AGE_MS).optional().default(DEFAULT_FRESHNESS_MAX_AGE_MS).describe("Maximum source age used by the common freshness projection; at most 90 days."),
+    };
+}
+const commonDescription = "The organization, group, person and optional campaign are explicit. This read-only result is tenant-checked, paginated and redacted; it never sends a message or writes an activity.";
+function registerReadOnlyTool(server, name, description, schema, handler) {
+    const candidate = server;
+    if (typeof candidate.registerTool === "function") {
+        candidate.registerTool(name, {
+            title: name,
+            description,
+            inputSchema: schema,
+            annotations: { readOnlyHint: true },
+        }, handler);
+        return;
+    }
+    server.tool(name, description, schema, handler);
+}
+export function registerCommercialTruthTools(server, client = getClient()) {
+    registerReadOnlyTool(server, "crm_lookup_person", `Read normalized CRM person and sales-stage evidence for one explicit person. ${commonDescription} A won deal is exposed as client, an open deal as prospect, and a missing person is distinct from a missing company deal. If no CRM is configured, the response explains the configuration action.`, {
+        ...readSchema(),
+        email: z.string().trim().email().max(320).describe("Exact email of the person to look up."),
+    }, async (params) => {
+        try {
+            const target = readTargetFromInput(params);
+            return toolResult((await readCrm(client, target)).payload);
+        }
+        catch (error) {
+            return error instanceof IntegrationNotConfiguredError ? missingIntegrationResult(error) : handleCommercialError(error);
+        }
+    });
+    registerReadOnlyTool(server, "email_read_thread", `Read the normalized email thread for one explicit person. ${commonDescription} Inbound messages are observed replies, delivery exclusions are preserved, and unreadable mailboxes are reported as ambiguity rather than a false empty thread.`, {
+        ...readSchema(),
+        email: z.string().trim().email().max(320).describe("Exact email whose thread must be read."),
+    }, async (params) => {
+        try {
+            const target = readTargetFromInput(params);
+            return toolResult((await readEmail(client, target)).payload);
+        }
+        catch (error) {
+            return error instanceof IntegrationNotConfiguredError ? missingIntegrationResult(error) : handleCommercialError(error);
+        }
+    });
+    registerReadOnlyTool(server, "linkedin_read_conversation", `Read the normalized LinkedIn conversation of one explicit profile. ${commonDescription} Only bounded message content and conversation metadata are returned; enrichment, send and activity endpoints are never called.`, {
+        ...readSchema(),
+        linkedin_url: z.string().trim().url().max(500).describe("Explicit LinkedIn profile URL whose conversation must be read."),
+    }, async (params) => {
+        try {
+            const target = readTargetFromInput(params);
+            return toolResult((await readLinkedin(client, target)).payload);
+        }
+        catch (error) {
+            return error instanceof IntegrationNotConfiguredError ? missingIntegrationResult(error) : handleCommercialError(error);
+        }
+    });
+    registerReadOnlyTool(server, "unipile_read_messages", `Read normalized Unipile LinkedIn messages of one explicit profile. ${commonDescription} Attachment URLs are reduced to a safe path and message text is bounded.`, {
+        ...readSchema(),
+        linkedin_url: z.string().trim().url().max(500).describe("Explicit LinkedIn profile URL whose Unipile messages must be read."),
+    }, async (params) => {
+        try {
+            const target = readTargetFromInput(params);
+            return toolResult((await readUnipile(client, target)).payload);
+        }
+        catch (error) {
+            return error instanceof IntegrationNotConfiguredError ? missingIntegrationResult(error) : handleCommercialError(error);
+        }
+    });
+    registerReadOnlyTool(server, "leadify_read_activity_feed", `Read the bounded Leadify activity feed of one explicit lead. ${commonDescription} This is an audit source only: agent logs and synthetic entries never prove that a person replied.`, {
+        ...readSchema(),
+        lead_id: z.string().trim().min(1).max(200).describe("Explicit Leadify lead whose activity feed must be read."),
+        target: z.string().trim().min(1).max(200).optional().describe("Optional exact activity target filter, such as a signal ID."),
+    }, async (params) => {
+        try {
+            const target = readTargetFromInput(params);
+            return toolResult((await readActivity(client, target)).payload);
+        }
+        catch (error) {
+            return error instanceof IntegrationNotConfiguredError ? missingIntegrationResult(error) : handleCommercialError(error);
+        }
+    });
+    registerReadOnlyTool(server, "get_commercial_truth", `Reconcile observed CRM, email, LinkedIn, Unipile and Leadify activity evidence of one explicit target. ${commonDescription} Provide an email, a LinkedIn URL and/or a lead ID to select person-level sources; omitted sources are listed as skipped. Exclusions win, divergent CRM/conversation evidence becomes review_required, and activity feed rows never prove a reply.`, {
+        ...readSchema(),
+        email: z.string().trim().email().max(320).optional().describe("Exact person email; enables CRM and email reads."),
+        linkedin_url: z.string().trim().url().max(500).optional().describe("Explicit LinkedIn profile URL; enables LinkedIn and Unipile reads."),
+        lead_id: z.string().trim().min(1).max(200).optional().describe("Explicit Leadify lead ID; enables the bounded activity read."),
+    }, async (params) => {
+        try {
+            const target = readTargetFromInput(params);
+            if (!target.email && !target.linkedin_url && !target.lead_id) {
+                return toolError("Provide at least one explicit person selector: email, linkedin_url, or lead_id. The MCP never reads a whole group or organization implicitly.", {
+                    code: "EXPLICIT_PERSON_SELECTOR_REQUIRED",
+                    organizationId: target.organization_id,
+                    leadGroupId: target.lead_group_id,
+                });
+            }
+            const result = await readSelectedSources(client, target);
+            return toolResult(aggregatePayload(target, result));
+        }
+        catch (error) {
+            return handleCommercialError(error);
+        }
+    });
+}

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.1";
+export declare const MCP_VERSION = "8.5.2";

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.1";
+export const MCP_VERSION = "8.5.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agifyai/leadify-mcp",
-  "version": "8.5.1",
+  "version": "8.5.2",
   "description": "MCP server for Leadify lead management API",
   "type": "module",
   "main": "dist/index.js",
@@ -15,8 +15,9 @@
     "build": "rm -rf dist && tsc && chmod +x dist/index.js",
     "start": "node dist/index.js",
     "dev": "tsc --watch",
+    "canary:commercial": "npm run build && zsh scripts/run-commercial-truth-read-canary.sh",
     "prepublishOnly": "npm run build",
-    "test": "npm run build && node --test test/**/*.test.mjs"
+    "test": "npm run build && node --test test/*.test.mjs"
   },
   "repository": {
     "type": "git",