@agifyai/leadify-mcp 8.5.5 → 8.6.2

package/dist/tools/context_entities.js

@@ -0,0 +1,528 @@
+import { z } from "zod";
+import { getClient } from "../client.js";
+import { handleToolError, toolResult } from "../types.js";
+const statusSchema = z.enum(["DRAFT", "ACTIVE", "ARCHIVED"]);
+const shortText = z.string().trim().max(500);
+const longText = z.string().trim().max(20_000);
+const itemId = z.string().trim().min(1).max(100);
+const textList = z.array(shortText).max(50);
+const linkedIds = z.array(itemId).max(50);
+const idealCustomerSchema = z.object({
+    summary: longText.optional(),
+    industries: textList.optional(),
+    companySizes: textList.optional(),
+    geographies: textList.optional(),
+    characteristics: textList.optional(),
+}).strict();
+const marketMetricSchema = z.object({
+    id: itemId,
+    label: shortText,
+    value: shortText,
+    explanation: longText.optional(),
+}).strict();
+const verticalUseCaseSchema = z.object({
+    id: itemId,
+    title: shortText,
+    description: longText.optional(),
+    customerCaseIds: linkedIds.optional(),
+}).strict();
+const verticalPainPointSchema = z.object({
+    id: itemId,
+    title: shortText,
+    description: longText.optional(),
+    useCaseIds: linkedIds.optional(),
+    customerCaseIds: linkedIds.optional(),
+}).strict();
+const qualificationSignalSchema = z.object({
+    id: itemId,
+    title: shortText,
+    example: longText.optional(),
+    meaning: longText.optional(),
+}).strict();
+const titledDetailSchema = z.object({
+    id: itemId,
+    title: shortText,
+    description: longText.optional(),
+}).strict();
+const objectionSchema = z.object({
+    id: itemId,
+    objection: longText,
+    response: longText.optional(),
+}).strict();
+const commercialLearningSchema = z.object({
+    id: itemId,
+    observation: longText,
+    implication: longText.optional(),
+}).strict();
+const offerClaimSchema = z.object({
+    id: itemId,
+    statement: longText,
+    details: longText.optional(),
+}).strict();
+const demonstratedResultSchema = z.object({
+    id: itemId,
+    label: shortText,
+    value: shortText,
+    details: longText.optional(),
+}).strict();
+const customerCaseSchema = z.object({
+    id: itemId,
+    companyName: shortText,
+    industry: shortText.optional(),
+    companyDescription: longText.optional(),
+    resultDetails: longText.optional(),
+    testimonial: longText.optional(),
+}).strict();
+function duplicates(values) {
+    const seen = new Set();
+    const duplicateValues = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            duplicateValues.add(value);
+        seen.add(value);
+    }
+    return [...duplicateValues];
+}
+const verticalContextContentObjectSchema = z.object({
+    sector: shortText.optional(),
+    sectorPositioning: longText.optional(),
+    commercialPitch: longText.optional(),
+    idealCustomer: idealCustomerSchema.optional(),
+    marketMetrics: z.array(marketMetricSchema).max(10).optional(),
+    customerCaseIds: z.array(itemId).max(7).optional(),
+    useCases: z.array(verticalUseCaseSchema).max(50).optional(),
+    painPoints: z.array(verticalPainPointSchema).max(50).optional(),
+    qualificationSignals: z.array(qualificationSignalSchema).max(50).optional(),
+    competitiveAdvantages: z.array(titledDetailSchema).max(50).optional(),
+    competitors: z.array(titledDetailSchema).max(50).optional(),
+    objections: z.array(objectionSchema).max(50).optional(),
+    allowedVocabulary: textList.optional(),
+    prohibitedVocabulary: textList.optional(),
+    legalConstraints: z.array(titledDetailSchema).max(50).optional(),
+    regulatoryInformation: longText.optional(),
+    commercialExperience: z.array(commercialLearningSchema).max(50).optional(),
+}).strict();
+export const verticalContextContentSchema = verticalContextContentObjectSchema.superRefine((content, context) => {
+    const itemCollections = [
+        ["marketMetrics", content.marketMetrics],
+        ["useCases", content.useCases],
+        ["painPoints", content.painPoints],
+        ["qualificationSignals", content.qualificationSignals],
+        ["competitiveAdvantages", content.competitiveAdvantages],
+        ["competitors", content.competitors],
+        ["objections", content.objections],
+        ["legalConstraints", content.legalConstraints],
+        ["commercialExperience", content.commercialExperience],
+    ];
+    for (const [field, items] of itemCollections) {
+        for (const duplicate of duplicates((items ?? []).map(item => item.id))) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: [field], message: `Duplicate item id: ${duplicate}` });
+        }
+    }
+    for (const duplicate of duplicates(content.customerCaseIds ?? [])) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["customerCaseIds"], message: `Duplicate customer case id: ${duplicate}` });
+    }
+    const selectedCustomerCases = new Set(content.customerCaseIds ?? []);
+    const useCaseIds = new Set((content.useCases ?? []).map(item => item.id));
+    for (const [index, useCase] of (content.useCases ?? []).entries()) {
+        for (const customerCaseId of useCase.customerCaseIds ?? []) {
+            if (!selectedCustomerCases.has(customerCaseId)) {
+                context.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["useCases", index, "customerCaseIds"],
+                    message: `Customer case ${customerCaseId} must first be selected on the Vertical`,
+                });
+            }
+        }
+    }
+    for (const [index, painPoint] of (content.painPoints ?? []).entries()) {
+        for (const useCaseId of painPoint.useCaseIds ?? []) {
+            if (!useCaseIds.has(useCaseId)) {
+                context.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["painPoints", index, "useCaseIds"],
+                    message: `Unknown Vertical use case id: ${useCaseId}`,
+                });
+            }
+        }
+        for (const customerCaseId of painPoint.customerCaseIds ?? []) {
+            if (!selectedCustomerCases.has(customerCaseId)) {
+                context.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["painPoints", index, "customerCaseIds"],
+                    message: `Customer case ${customerCaseId} must first be selected on the Vertical`,
+                });
+            }
+        }
+    }
+});
+export const offerContextContentSchema = z.object({
+    description: longText.optional(),
+    promise: longText.optional(),
+    capabilities: z.array(titledDetailSchema).max(50).optional(),
+    activationConditions: z.array(titledDetailSchema).max(50).optional(),
+    claims: z.array(offerClaimSchema).max(50).optional(),
+    demonstratedResults: z.array(demonstratedResultSchema).max(50).optional(),
+    customerCases: z.array(customerCaseSchema).max(50).optional(),
+    constraints: z.array(titledDetailSchema).max(50).optional(),
+}).strict().superRefine((content, context) => {
+    const itemCollections = [
+        ["capabilities", content.capabilities],
+        ["activationConditions", content.activationConditions],
+        ["claims", content.claims],
+        ["demonstratedResults", content.demonstratedResults],
+        ["customerCases", content.customerCases],
+        ["constraints", content.constraints],
+    ];
+    for (const [field, items] of itemCollections) {
+        for (const duplicate of duplicates((items ?? []).map(item => item.id))) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: [field], message: `Duplicate item id: ${duplicate}` });
+        }
+    }
+});
+const expectedUpdatedAtSchema = z.string().datetime({ offset: true }).describe("Exact updatedAt from the read this mutation is based on. A stale value is rejected with 409.");
+const previewScopeSchema = z.enum(["explicit", "lead_group", "campaign"]);
+function previewBody(input) {
+    if (input.scope === "explicit") {
+        if (!input.vertical_id || !input.offer_id || !input.persona_id) {
+            throw new Error("explicit preview requires vertical_id, offer_id, and persona_id");
+        }
+        return {
+            scope: input.scope,
+            verticalId: input.vertical_id,
+            offerId: input.offer_id,
+            personaId: input.persona_id,
+        };
+    }
+    if (input.scope === "lead_group") {
+        if (!input.lead_group_id)
+            throw new Error("lead_group preview requires lead_group_id");
+        return { scope: input.scope, leadGroupId: input.lead_group_id };
+    }
+    if (!input.campaign_id)
+        throw new Error("campaign preview requires campaign_id");
+    return { scope: input.scope, campaignId: input.campaign_id };
+}
+function params(organizationId, status) {
+    return new URLSearchParams({
+        organizationId,
+        ...(status ? { status } : {}),
+    });
+}
+function path(resource, organizationId) {
+    return `/api/context-entities/${resource}?${new URLSearchParams({ organizationId }).toString()}`;
+}
+function entityPath(resource, id, organizationId, suffix = "") {
+    return `/api/context-entities/${resource}/${encodeURIComponent(id)}${suffix}?${new URLSearchParams({ organizationId }).toString()}`;
+}
+function object(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+async function patchEntity(client, input) {
+    if (input.name === undefined &&
+        Object.keys(input.contentPatch ?? {}).length === 0 &&
+        (input.removeContentKeys?.length ?? 0) === 0) {
+        throw new Error("Provide a name, a non-empty content_patch, or remove_content_keys.");
+    }
+    const read = object(await client.get(entityPath(input.resource, input.id, input.organizationId)));
+    const entity = object(read[input.wrapper]);
+    const actualUpdatedAt = entity.updatedAt;
+    if (typeof actualUpdatedAt !== "string" ||
+        new Date(actualUpdatedAt).toISOString() !== new Date(input.expectedUpdatedAt).toISOString()) {
+        throw new Error(`CONTEXT_ENTITY_UPDATE_CONFLICT: expected ${input.expectedUpdatedAt}, current ${String(actualUpdatedAt)}. Re-read before retrying.`);
+    }
+    const parsedCurrent = input.resource === "verticals"
+        ? verticalContextContentSchema.safeParse(entity.content)
+        : offerContextContentSchema.safeParse(entity.content);
+    const content = {
+        // During the strict cutover, an invalid legacy object has no active keys to
+        // preserve. The first valid patch replaces it instead of smuggling old,
+        // now-forbidden JSON back through the MCP.
+        ...(parsedCurrent.success ? parsedCurrent.data : {}),
+        ...(input.contentPatch ?? {}),
+    };
+    for (const key of input.removeContentKeys ?? [])
+        delete content[key];
+    return client.patch(entityPath(input.resource, input.id, input.organizationId), {
+        expectedUpdatedAt: input.expectedUpdatedAt,
+        ...(input.name !== undefined ? { name: input.name } : {}),
+        ...(input.contentPatch !== undefined || (input.removeContentKeys?.length ?? 0) > 0
+            ? { content }
+            : {}),
+    });
+}
+export function registerContextEntityTools(server, client = getClient()) {
+    server.registerTool("list_verticals", {
+        title: "List organization Verticals",
+        description: "List compact tenant-scoped Verticals. Historical global/orphaned Personas are never returned. " +
+            "Always provide the organization explicitly; no tenant or Vertical is inferred.",
+        inputSchema: {
+            organization_id: z.string().trim().min(1),
+            status: statusSchema.optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ organization_id, status }) => {
+        try {
+            return toolResult(await client.get("/api/context-entities/verticals", params(organization_id, status)));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.registerTool("get_vertical", {
+        title: "Read one Vertical",
+        description: "Read one exact tenant-scoped Vertical, including its authoritative JSON, linked Personas, and linked Offers. " +
+            "The organization and Vertical IDs are both mandatory.",
+        inputSchema: {
+            organization_id: z.string().trim().min(1),
+            vertical_id: z.string().trim().min(1),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ organization_id, vertical_id }) => {
+        try {
+            return toolResult(await client.get(`/api/context-entities/verticals/${encodeURIComponent(vertical_id)}`, params(organization_id)));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.registerTool("create_vertical", {
+        title: "Create a Vertical draft",
+        description: "Create one tenant-scoped Vertical in DRAFT. Content is simple authoritative JSON and must not contain " +
+            "formal evidence/source/proof/provenance fields. Its closed schema covers sector positioning, vocabulary, legal constraints and " +
+            "commercialExperience belong here; global counterparts remain in Company Brain with no fallback or override. " +
+            "This never publishes, activates, or selects a default Vertical.",
+        inputSchema: {
+            organization_id: z.string().trim().min(1),
+            name: z.string().trim().min(1).max(200),
+            content: verticalContextContentSchema.optional(),
+        },
+    }, async ({ organization_id, name, content }) => {
+        try {
+            return toolResult(await client.post(path("verticals", organization_id), {
+                name,
+                content: content ?? {},
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.registerTool("list_offers", {
+        title: "List organization Offers",
+        description: "List compact tenant-scoped Offers with relation counts. Always provide the organization explicitly; " +
+            "no Offer or tenant is inferred.",
+        inputSchema: {
+            organization_id: z.string().trim().min(1),
+            status: statusSchema.optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ organization_id, status }) => {
+        try {
+            return toolResult(await client.get("/api/context-entities/offers", params(organization_id, status)));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.registerTool("update_vertical", {
+        title: "Update one Vertical safely",
+        description: "Optimistically patch one Vertical name and/or top-level JSON keys. The tool re-reads, shallow-merges only the named keys, " +
+            "and sends the exact expected_updated_at. A concurrent change returns 409; no silent overwrite is allowed. " +
+            "Editing an ACTIVE Vertical returns it to DRAFT.",
+        inputSchema: {
+            organization_id: z.string().trim().min(1),
+            vertical_id: z.string().trim().min(1),
+            expected_updated_at: expectedUpdatedAtSchema,
+            name: z.string().trim().min(1).max(200).optional(),
+            // References may target untouched top-level collections. Structural
+            // validation happens here; the server validates the fully merged JSON.
+            content_patch: verticalContextContentObjectSchema.optional(),
+            remove_content_keys: z.array(z.string().min(1)).max(100).optional(),
+        },
+    }, async ({ organization_id, vertical_id, expected_updated_at, name, content_patch, remove_content_keys }) => {
+        try {
+            return toolResult(await patchEntity(client, {
+                resource: "verticals",
+                wrapper: "vertical",
+                organizationId: organization_id,
+                id: vertical_id,
+                expectedUpdatedAt: expected_updated_at,
+                name,
+                contentPatch: content_patch,
+                removeContentKeys: remove_content_keys,
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.registerTool("change_vertical_status", {
+        title: "Change one Vertical status",
+        description: "Change a Vertical between DRAFT, ACTIVE, and ARCHIVED using mandatory optimistic concurrency. " +
+            "Activation checks readiness; archive is blocked while references remain; ARCHIVED can only return to DRAFT.",
+        inputSchema: {
+            organization_id: z.string().trim().min(1),
+            vertical_id: z.string().trim().min(1),
+            expected_updated_at: expectedUpdatedAtSchema,
+            status: statusSchema,
+        },
+    }, async ({ organization_id, vertical_id, expected_updated_at, status }) => {
+        try {
+            return toolResult(await client.post(entityPath("verticals", vertical_id, organization_id, "/status"), { expectedUpdatedAt: expected_updated_at, status }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.registerTool("get_offer", {
+        title: "Read one Offer",
+        description: "Read one exact tenant-scoped Offer, including its authoritative JSON, linked Verticals, and Lead Groups. " +
+            "The organization and Offer IDs are both mandatory.",
+        inputSchema: {
+            organization_id: z.string().trim().min(1),
+            offer_id: z.string().trim().min(1),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ organization_id, offer_id }) => {
+        try {
+            return toolResult(await client.get(`/api/context-entities/offers/${encodeURIComponent(offer_id)}`, params(organization_id)));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.registerTool("create_offer", {
+        title: "Create an Offer draft",
+        description: "Create one tenant-scoped Offer in DRAFT. Content is simple authoritative JSON and must not contain " +
+            "formal evidence/source/proof/provenance fields. Its closed schema owns claims, demonstratedResults and customerCases; " +
+            "sector context and commercialExperience do not. This never publishes, activates, links, or selects an Offer.",
+        inputSchema: {
+            organization_id: z.string().trim().min(1),
+            name: z.string().trim().min(1).max(200),
+            content: offerContextContentSchema.optional(),
+        },
+    }, async ({ organization_id, name, content }) => {
+        try {
+            return toolResult(await client.post(path("offers", organization_id), {
+                name,
+                content: content ?? {},
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.registerTool("update_offer", {
+        title: "Update one Offer safely",
+        description: "Optimistically patch one Offer name and/or top-level JSON keys. The tool re-reads and shallow-merges only the named keys. " +
+            "A stale expected_updated_at returns 409, and editing an ACTIVE Offer returns it to DRAFT.",
+        inputSchema: {
+            organization_id: z.string().trim().min(1),
+            offer_id: z.string().trim().min(1),
+            expected_updated_at: expectedUpdatedAtSchema,
+            name: z.string().trim().min(1).max(200).optional(),
+            content_patch: offerContextContentSchema.optional(),
+            remove_content_keys: z.array(z.string().min(1)).max(100).optional(),
+        },
+    }, async ({ organization_id, offer_id, expected_updated_at, name, content_patch, remove_content_keys }) => {
+        try {
+            return toolResult(await patchEntity(client, {
+                resource: "offers",
+                wrapper: "offer",
+                organizationId: organization_id,
+                id: offer_id,
+                expectedUpdatedAt: expected_updated_at,
+                name,
+                contentPatch: content_patch,
+                removeContentKeys: remove_content_keys,
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.registerTool("change_offer_status", {
+        title: "Change one Offer status",
+        description: "Change an Offer between DRAFT, ACTIVE, and ARCHIVED using mandatory optimistic concurrency. " +
+            "Activation checks readiness; archive is blocked while references remain; ARCHIVED can only return to DRAFT.",
+        inputSchema: {
+            organization_id: z.string().trim().min(1),
+            offer_id: z.string().trim().min(1),
+            expected_updated_at: expectedUpdatedAtSchema,
+            status: statusSchema,
+        },
+    }, async ({ organization_id, offer_id, expected_updated_at, status }) => {
+        try {
+            return toolResult(await client.post(entityPath("offers", offer_id, organization_id, "/status"), { expectedUpdatedAt: expected_updated_at, status }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    const verticalOfferMutationInput = {
+        organization_id: z.string().trim().min(1),
+        vertical_id: z.string().trim().min(1),
+        offer_id: z.string().trim().min(1),
+        expected_vertical_updated_at: expectedUpdatedAtSchema,
+        expected_offer_updated_at: expectedUpdatedAtSchema,
+    };
+    server.registerTool("link_vertical_offer", {
+        title: "Link one Offer to one Vertical",
+        description: "Create one exact tenant-scoped Vertical-Offer relation. Both objects must be ACTIVE and both timestamps must be current. " +
+            "The relation edit returns both objects to DRAFT for explicit revalidation.",
+        inputSchema: verticalOfferMutationInput,
+    }, async ({ organization_id, vertical_id, offer_id, expected_vertical_updated_at, expected_offer_updated_at }) => {
+        try {
+            return toolResult(await client.put(`${entityPath("verticals", vertical_id, organization_id, `/offers/${encodeURIComponent(offer_id)}`)}`, {
+                expectedVerticalUpdatedAt: expected_vertical_updated_at,
+                expectedOfferUpdatedAt: expected_offer_updated_at,
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.registerTool("unlink_vertical_offer", {
+        title: "Unlink one Offer from one Vertical",
+        description: "Remove one exact tenant-scoped Vertical-Offer relation with both current timestamps. " +
+            "The server refuses removal while a Lead Group depends on that pair and returns changed:false when already absent.",
+        inputSchema: verticalOfferMutationInput,
+    }, async ({ organization_id, vertical_id, offer_id, expected_vertical_updated_at, expected_offer_updated_at }) => {
+        try {
+            return toolResult(await client.delete(`${entityPath("verticals", vertical_id, organization_id, `/offers/${encodeURIComponent(offer_id)}`)}`, {
+                expectedVerticalUpdatedAt: expected_vertical_updated_at,
+                expectedOfferUpdatedAt: expected_offer_updated_at,
+            }));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+    server.registerTool("preview_resolved_context", {
+        title: "Preview the exact resolved context",
+        description: "Resolve Company Brain, one ACTIVE Vertical, one linked ACTIVE Offer, one ACTIVE Persona, and Lead Group sender/CTA when the scope provides them. " +
+            "Use explicit for a free writer, lead_group for qualification, or campaign for inherited campaign context. " +
+            "The tool is read-only and returns a deterministic digest with dryRun:true, persisted:false, noSend:true, " +
+            "runtimeApplied:false, and externalActivation:0. No organization or resource is inferred.",
+        inputSchema: {
+            organization_id: z.string().trim().min(1),
+            scope: previewScopeSchema,
+            vertical_id: z.string().trim().min(1).optional(),
+            offer_id: z.string().trim().min(1).optional(),
+            persona_id: z.string().trim().min(1).optional(),
+            lead_group_id: z.string().trim().min(1).optional(),
+            campaign_id: z.string().trim().min(1).optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ organization_id, ...input }) => {
+        try {
+            return toolResult(await client.post(`/api/context-entities/preview?${new URLSearchParams({ organizationId: organization_id }).toString()}`, previewBody(input)));
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    });
+}