@agifyai/leadify-mcp 9.6.0 → 9.7.1

package/dist/tools/events.js

@@ -7,7 +7,10 @@ const dateOnly = z.string()
     const parsed = new Date(`${value}T00:00:00.000Z`);
     return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
 }, "Use a real calendar date in YYYY-MM-DD format.");
-const role = z.enum([
+// Company roles are the nine historical ones. REGISTERED, ATTENDED and
+// INVITED are three distinct facts about a person (PRD-2473 contract):
+// a registration never proves attendance, an invitation proves neither.
+export const COMPANY_EVENT_ROLES = [
     "EXHIBITOR",
     "SPONSOR",
     "SPEAKER",
@@ -17,7 +20,13 @@ const role = z.enum([
     "PARTICIPANT",
     "UNKNOWN",
     "OTHER",
-]);
+];
+export const PERSON_ONLY_EVENT_ROLES = ["REGISTERED", "ATTENDED", "INVITED"];
+export const PERSON_EVENT_ROLES = ["REGISTERED", "ATTENDED", "INVITED", "SPEAKER", "ORGANIZER", "OTHER"];
+export const eventRole = z.enum([...COMPANY_EVENT_ROLES, ...PERSON_ONLY_EVENT_ROLES]);
+const role = eventRole;
+export const eventType = z.enum(["WEBINAR", "CONGRESS", "TRADE_SHOW", "OTHER"]);
+const target = z.enum(["COMPANY", "PERSON"]);
 const status = z.enum(["UNVERIFIED", "VERIFIED", "DISPUTED", "REFUTED"]);
 const nullableLabel = z.string().trim().min(1).max(500).nullable().optional();
 const nullableNarrative = z.string().trim().min(1).max(5_000).nullable().optional();
@@ -35,10 +44,12 @@ const eventFields = {
     official_url: nullableUrl,
     last_verified_on: dateOnly.nullable().optional(),
 };
+const eventTypeDescription = "Event type: WEBINAR, CONGRESS, TRADE_SHOW or OTHER. Omitted means not specified.";
 const createEventShape = {
     organization_id: z.string().trim().min(1),
     slug: z.string().trim().min(1).max(160).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
     ...eventFields,
+    event_type: eventType.optional().describe(eventTypeDescription),
     idempotency_key: idempotencyKey,
 };
 const createEventInput = z.object(createEventShape).strict().superRefine((value, context) => {
@@ -59,12 +70,13 @@ const updateEventShape = {
     venue: eventFields.venue,
     official_url: eventFields.official_url,
     last_verified_on: eventFields.last_verified_on,
+    event_type: eventType.nullable().optional().describe("New event type (WEBINAR, CONGRESS, TRADE_SHOW, OTHER), or null to mark it as not specified."),
     archive: z.boolean().optional().default(false),
     expected_version: z.number().int().positive(),
     idempotency_key: idempotencyKey,
 };
 const updateEventInput = z.object(updateEventShape).strict().superRefine((value, context) => {
-    const mutable = ["name", "edition", "description", "starts_on", "ends_on", "city", "country_code", "venue", "official_url", "last_verified_on"];
+    const mutable = ["name", "edition", "description", "starts_on", "ends_on", "city", "country_code", "venue", "official_url", "last_verified_on", "event_type"];
     const supplied = mutable.filter((key) => value[key] !== undefined);
     if (value.archive && supplied.length > 0) {
         context.addIssue({ code: z.ZodIssueCode.custom, path: ["archive"], message: "Archive and field updates must be separate idempotent operations." });
@@ -76,16 +88,23 @@ const updateEventInput = z.object(updateEventShape).strict().superRefine((value,
         context.addIssue({ code: z.ZodIssueCode.custom, path: ["ends_on"], message: "ends_on must be on or after starts_on." });
     }
 });
+const clientDocument = z.object({
+    file_name: z.string().trim().min(1).max(300).describe("Name of the file the client sent, e.g. the registrants spreadsheet."),
+    received_on: dateOnly.describe("Date the file was received, YYYY-MM-DD."),
+    provided_by: z.string().trim().min(1).max(300).describe("Who provided the file (client organization or contact)."),
+}).strict().describe("Proof by a document provided by the client, without a web address. A client's registrants list is valid proof of registration (role REGISTERED), including for a person who later unsubscribed or registered several times. It is not proof of attendance.");
 const participationItem = z.object({
     event_id: z.string().trim().min(1),
-    account_id: z.string().trim().min(1).optional(),
-    lead_id: z.string().trim().min(1).optional(),
-    roles: z.array(role).min(1).max(20),
+    account_id: z.string().trim().min(1).optional().describe("Company target: canonical account id."),
+    lead_id: z.string().trim().min(1).optional().describe("Company lead (writes on its account) or Person lead (writes a personal participation on its canonical person)."),
+    person_id: z.string().trim().min(1).optional().describe("Person target: canonical person id: canonicalIdentity.id of a Person lead (canonicalIdentity.kind PERSON), as returned by get_lead."),
+    roles: z.array(role).min(1).max(20).describe("Company roles: EXHIBITOR, SPONSOR, SPEAKER, PARTNER, ORGANIZER, CONTRIBUTOR, PARTICIPANT, UNKNOWN, OTHER. Person roles: REGISTERED, ATTENDED, INVITED, SPEAKER, ORGANIZER, OTHER. REGISTERED, ATTENDED and INVITED are reserved to persons and are three distinct facts."),
     role_details: z.array(z.string().trim().min(1).max(500)).max(50).optional().default([]),
     stands: z.array(z.string().trim().min(1).max(200)).max(50).optional().default([]),
     source_urls: z.array(z.string().trim().url().max(2048)).max(50).optional().default([]),
+    client_document: clientDocument.optional(),
     source_provider: nullableLabel,
-    activity_summary: nullableNarrative.describe("Readable summary of what the company does, presents or targets at this event."),
+    activity_summary: nullableNarrative.describe("Readable summary of what the company or person does, presents or targets at this event."),
     proof_excerpt: z.string().trim().min(1).max(20_000),
     observed_on: dateOnly,
     verified_on: dateOnly.nullable().optional(),
@@ -93,11 +112,24 @@ const participationItem = z.object({
     correction_reason: z.string().trim().min(1).max(5_000).optional(),
     idempotency_key: idempotencyKey,
 }).strict().superRefine((value, context) => {
-    if (Number(Boolean(value.account_id)) + Number(Boolean(value.lead_id)) !== 1) {
-        context.addIssue({ code: z.ZodIssueCode.custom, message: "Provide exactly one account_id or lead_id." });
+    const targets = [value.account_id, value.lead_id, value.person_id].filter(Boolean).length;
+    if (targets !== 1) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "Provide exactly one account_id, lead_id or person_id." });
     }
-    if (value.status === "VERIFIED" && value.source_urls.length === 0) {
-        context.addIssue({ code: z.ZodIssueCode.custom, path: ["source_urls"], message: "VERIFIED requires at least one source URL." });
+    if (value.account_id) {
+        const refused = value.roles.filter((item) => PERSON_ONLY_EVENT_ROLES.includes(item));
+        if (refused.length) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["roles"], message: `Roles reserved to a person cannot be recorded on a company: ${refused.join(", ")}.` });
+        }
+    }
+    if (value.person_id) {
+        const refused = value.roles.filter((item) => !PERSON_EVENT_ROLES.includes(item));
+        if (refused.length) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["roles"], message: `Roles not accepted for a person: ${refused.join(", ")}. Use REGISTERED, ATTENDED, INVITED, SPEAKER, ORGANIZER or OTHER.` });
+        }
+    }
+    if (value.status === "VERIFIED" && value.source_urls.length === 0 && !value.client_document) {
+        context.addIssue({ code: z.ZodIssueCode.custom, path: ["source_urls"], message: "VERIFIED requires at least one source URL or a client_document." });
     }
     if (value.status === "VERIFIED" && !value.verified_on) {
         context.addIssue({ code: z.ZodIssueCode.custom, path: ["verified_on"], message: "VERIFIED requires verified_on." });
@@ -118,10 +150,18 @@ function participationPayload(item) {
         eventId: item.event_id,
         accountId: item.account_id,
         leadId: item.lead_id,
+        personId: item.person_id,
         roles: item.roles,
         roleDetails: item.role_details,
         stands: item.stands,
         sourceUrls: item.source_urls,
+        clientDocument: item.client_document
+            ? {
+                fileName: item.client_document.file_name,
+                receivedOn: item.client_document.received_on,
+                providedBy: item.client_document.provided_by,
+            }
+            : undefined,
         sourceProvider: item.source_provider,
         activitySummary: item.activity_summary,
         proofExcerpt: item.proof_excerpt,
@@ -160,16 +200,17 @@ function filterFactHistory(data, acceptedStatuses) {
     return source;
 }
 export function registerEventTools(server, client = getClient()) {
-    server.tool("list_events", "List tenant-scoped events. Archived events are hidden unless include_archived=true. An event alone is not evidence that a company attended; cite participation only from a matching VERIFIED participation.", {
+    server.tool("list_events", "List tenant-scoped events. Archived events are hidden unless include_archived=true. Filter by event_types (WEBINAR, CONGRESS, TRADE_SHOW, OTHER). An event alone is not evidence that a company or a person took part; cite participation only from a matching VERIFIED participation.", {
         organization_id: z.string().trim().min(1),
         include_archived: z.boolean().optional().default(false),
         search: z.string().trim().min(1).max(200).optional(),
         editions: z.array(z.string().trim().min(1).max(200)).max(100).optional(),
+        event_types: z.array(eventType).min(1).max(4).optional(),
         starts_on_from: dateOnly.optional(),
         starts_on_to: dateOnly.optional(),
         limit: z.number().int().min(1).max(100).optional().default(50),
         cursor: z.string().trim().min(1).optional(),
-    }, async ({ organization_id, include_archived, search, editions, starts_on_from, starts_on_to, limit, cursor }) => {
+    }, async ({ organization_id, include_archived, search, editions, event_types, starts_on_from, starts_on_to, limit, cursor }) => {
         try {
             const params = new URLSearchParams({
                 organizationId: organization_id,
@@ -179,6 +220,7 @@ export function registerEventTools(server, client = getClient()) {
             if (search)
                 params.set("search", search);
             setCsv(params, "editions", editions);
+            setCsv(params, "eventTypes", event_types);
             if (starts_on_from)
                 params.set("startsOnFrom", starts_on_from);
             if (starts_on_to)
@@ -191,7 +233,7 @@ export function registerEventTools(server, client = getClient()) {
             return handleToolError(error);
         }
     });
-    server.tool("get_event", "Get one tenant-scoped event, including its archive state and current participation count. This does not establish that any particular company attended.", {
+    server.tool("get_event", "Get one tenant-scoped event, including its type, archive state and participationCounts { companies, persons }: the number of companies and of persons that carry a participation themselves. A count does not establish that any particular company or person attended, and a person is never counted through their employer.", {
         organization_id: z.string().trim().min(1),
         event_id: z.string().trim().min(1),
     }, async ({ organization_id, event_id }) => {
@@ -202,7 +244,7 @@ export function registerEventTools(server, client = getClient()) {
             return handleToolError(error);
         }
     });
-    server.tool("create_event", "Create one reusable tenant-scoped event. The idempotency key makes an identical retry safe; changing the payload under the same key is rejected. Creating an event does not create company participation evidence.", createEventShape, async (params) => {
+    server.tool("create_event", "Create one reusable tenant-scoped event, optionally typed with event_type (WEBINAR, CONGRESS, TRADE_SHOW, OTHER). The idempotency key makes an identical retry safe; changing the payload under the same key is rejected. Creating an event does not create any company or person participation evidence.", createEventShape, async (params) => {
         try {
             const input = createEventInput.parse(params);
             return toolResult(await client.post("/api/events", compact({
@@ -218,6 +260,7 @@ export function registerEventTools(server, client = getClient()) {
                 venue: input.venue,
                 officialUrl: input.official_url,
                 lastVerifiedOn: input.last_verified_on,
+                eventType: input.event_type,
                 idempotencyKey: input.idempotency_key,
             })));
         }
@@ -225,7 +268,7 @@ export function registerEventTools(server, client = getClient()) {
             return handleToolError(error);
         }
     });
-    server.tool("update_event", "Update or archive one shared event with optimistic versioning and idempotency. Set archive=true as a separate operation with no field changes. This affects every company view that references the event; archiving is non-destructive and keeps all participation evidence.", updateEventShape, async (params) => {
+    server.tool("update_event", "Update or archive one shared event with optimistic versioning and idempotency, including its event_type (WEBINAR, CONGRESS, TRADE_SHOW, OTHER, or null for not specified). Set archive=true as a separate operation with no field changes. This affects every company and person view that references the event; archiving is non-destructive and keeps all participation evidence.", updateEventShape, async (params) => {
         try {
             const input = updateEventInput.parse(params);
             const body = input.archive
@@ -247,6 +290,7 @@ export function registerEventTools(server, client = getClient()) {
                     venue: input.venue,
                     officialUrl: input.official_url,
                     lastVerifiedOn: input.last_verified_on,
+                    eventType: input.event_type,
                     expectedVersion: input.expected_version,
                     idempotencyKey: input.idempotency_key,
                 });
@@ -256,11 +300,13 @@ export function registerEventTools(server, client = getClient()) {
             return handleToolError(error);
         }
     });
-    server.tool("list_event_participations", "List current company-event participation snapshots in one tenant. Defaults explicitly to VERIFIED only. To review uncertain evidence or uncertain historical facts, pass statuses containing UNVERIFIED, DISPUTED or REFUTED; unrequested fact statuses are hidden and counted. Never cite uncertain data, or the absence of a record, as proof of attendance or non-attendance.", {
+    server.tool("list_event_participations", "List current event participation snapshots of companies and persons in one tenant. Without target, person_ids or a Person lead_id, only company participations are returned (historical behavior); pass target=PERSON, person_ids or the lead_id of a Person lead to read persons. Each item carries target (COMPANY or PERSON), accountId, personId, clientDocument and, for a person, personLeads. With the lead_id of a Person lead, the result holds the person's own participations (origin PERSON) and those of their employer (origin EMPLOYER): an employer's event is never a participation of the person. REGISTERED (registered), ATTENDED (attended) and INVITED (invited) are distinct facts: a registration never proves attendance. Defaults explicitly to VERIFIED only. To review uncertain evidence or uncertain historical facts, pass statuses containing UNVERIFIED, DISPUTED or REFUTED; unrequested fact statuses are hidden and counted. Never cite uncertain data, or the absence of a record, as proof of attendance or non-attendance.", {
         organization_id: z.string().trim().min(1),
         event_ids: z.array(z.string().trim().min(1)).max(100).optional(),
         account_ids: z.array(z.string().trim().min(1)).max(100).optional(),
-        lead_id: z.string().trim().min(1).optional(),
+        person_ids: z.array(z.string().trim().min(1)).max(100).optional().describe("Canonical person ids: canonicalIdentity.id of Person leads (kind PERSON)."),
+        target: target.optional().describe("COMPANY or PERSON. Omitted: companies only, unless person_ids or a Person lead_id is given."),
+        lead_id: z.string().trim().min(1).optional().describe("Company lead: its account's participations. Person lead: its own participations (origin PERSON) and its employer's (origin EMPLOYER)."),
         editions: z.array(z.string().trim().min(1).max(200)).max(100).optional(),
         roles: z.array(role).max(20).optional(),
         statuses: z.array(status).min(1).max(10).optional().default(["VERIFIED"]),
@@ -268,8 +314,8 @@ export function registerEventTools(server, client = getClient()) {
         starts_on_to: dateOnly.optional(),
         include_facts: z.boolean().optional().default(false),
         limit: z.number().int().min(1).max(100).optional().default(50),
-        cursor: z.string().trim().min(1).optional(),
-    }, async ({ organization_id, event_ids, account_ids, lead_id, editions, roles, statuses, starts_on_from, starts_on_to, include_facts, limit, cursor }) => {
+        cursor: z.string().trim().min(1).optional().describe("Opaque cursor returned by the previous page; pass it back unchanged."),
+    }, async ({ organization_id, event_ids, account_ids, person_ids, target, lead_id, editions, roles, statuses, starts_on_from, starts_on_to, include_facts, limit, cursor }) => {
         try {
             const params = new URLSearchParams({
                 organizationId: organization_id,
@@ -279,6 +325,9 @@ export function registerEventTools(server, client = getClient()) {
             });
             setCsv(params, "eventIds", event_ids);
             setCsv(params, "accountIds", account_ids);
+            setCsv(params, "personIds", person_ids);
+            if (target)
+                params.set("target", target);
             if (lead_id)
                 params.set("leadId", lead_id);
             setCsv(params, "editions", editions);
@@ -296,7 +345,7 @@ export function registerEventTools(server, client = getClient()) {
             return handleToolError(error);
         }
     });
-    server.tool("get_event_participation", "Get one explicitly selected current participation and its immutable fact history. Access defaults to VERIFIED only; pass statuses explicitly to review UNVERIFIED, DISPUTED or REFUTED facts. Uncertain evidence is not verified attendance, and missing data never means non-participation.", {
+    server.tool("get_event_participation", "Get one explicitly selected current participation of a company or a person and its immutable fact history, with target, accountId, personId, clientDocument and, for a person, personLeads. Access defaults to VERIFIED only; pass statuses explicitly to review UNVERIFIED, DISPUTED or REFUTED facts. REGISTERED is not ATTENDED. Uncertain evidence is not verified attendance, and missing data never means non-participation.", {
         organization_id: z.string().trim().min(1),
         participation_id: z.string().trim().min(1),
         statuses: z.array(status).min(1).max(10).optional().default(["VERIFIED"]),
@@ -320,7 +369,7 @@ export function registerEventTools(server, client = getClient()) {
             return handleToolError(error);
         }
     });
-    server.tool("record_event_participations", "Create participation evidence, add a corroborating source, or correct 1-100 company-event observations. Set validate_only=true for a no-write dry-run. activity_summary is the readable account of what the company does at the event; proof_excerpt remains the exact agent/audit evidence. Each item targets exactly one account_id or resolvable lead_id and has its own idempotency key. Corrections append an immutable fact and require correction_reason; there is no delete operation. VERIFIED requires a source URL, proof excerpt and verification date. Uncertain or absent data cannot be cited as attendance.", {
+    server.tool("record_event_participations", "Create participation evidence, add a corroborating source, or correct 1-100 event observations of companies or persons. Set validate_only=true for a no-write dry-run. Each item targets exactly one account_id, lead_id or person_id and has its own idempotency key. A Company lead or account_id writes a company participation, exactly as before. The lead_id of a Person lead, or a person_id, writes a personal participation on the canonical person: it follows that person across every group. Person roles: REGISTERED, ATTENDED, INVITED, SPEAKER, ORGANIZER, OTHER; REGISTERED, ATTENDED and INVITED are refused for a company. Registered, attended and invited are three distinct facts: a registration never proves attendance. A registrants list provided by the client is valid proof of registration: record role REGISTERED with client_document { file_name, received_on, provided_by } and no URL, including for a person who later unsubscribed or registered several times. An employer's event is never a participation of the person: never record a person from their company's participation. activity_summary is the readable account of what the company or person does at the event; proof_excerpt remains the exact agent/audit evidence. Corrections append an immutable fact and require correction_reason; there is no delete operation. VERIFIED requires a source URL or a client_document, a proof excerpt and a verification date. Uncertain or absent data cannot be cited as attendance, and the absence of a record proves nothing.", {
         organization_id: z.string().trim().min(1),
         batch_id: z.string().trim().min(1).max(255),
         validate_only: z.boolean().optional().default(false),