@sellable/mcp 0.1.364 → 0.1.366

package/dist/tools/workspace-export.d.ts

@@ -1,7 +1,11 @@
 export type WorkspaceExportDataset = "people" | "events";
+export type WorkspaceExportIntent = "reached_out_people" | "people_and_events" | "outreach_event_log" | "dashboard_messages" | "connections_sent";
+type WorkspaceExportActionType = "INVITE" | "DM" | "INMAIL_OPEN" | "INMAIL_CLOSED" | "VIEW_PROFILE" | "COMMENT";
 export interface ExportWorkspaceCsvInput {
     exportType?: "outreach";
+    exportIntent?: WorkspaceExportIntent;
     datasets?: WorkspaceExportDataset[];
+    actionTypes?: WorkspaceExportActionType[];
     outputDir?: string;
     fromSentAt?: string;
     toSentAt?: string;
@@ -19,6 +23,11 @@ export declare const workspaceExportToolDefinitions: {
                 enum: string[];
                 description: string;
             };
+            exportIntent: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
             datasets: {
                 type: string;
                 items: {
@@ -27,6 +36,14 @@ export declare const workspaceExportToolDefinitions: {
                 };
                 description: string;
             };
+            actionTypes: {
+                type: string;
+                items: {
+                    type: string;
+                    enum: string[];
+                };
+                description: string;
+            };
             outputDir: {
                 type: string;
                 description: string;
@@ -70,6 +87,16 @@ export declare function exportWorkspaceCsv(input?: ExportWorkspaceCsvInput): Pro
         status: "complete" | "failed";
     }[];
     exportCutoff: string;
+    exportIntent: WorkspaceExportIntent | null;
+    intentDescription: string | null;
+    countDefinitions: {
+        reachedOutPeople: string;
+        outreachEvents: string;
+        dashboardMessagesSent: string;
+        connectionsSent: string;
+        profileViews: string;
+    };
+    counts: Record<string, unknown>;
     workspace: {
         id?: string;
         name?: string | null;
@@ -80,3 +107,4 @@ export declare function exportWorkspaceCsv(input?: ExportWorkspaceCsvInput): Pro
         error: string;
     }[];
 }>;
+export {};

package/dist/tools/workspace-export.js

@@ -11,7 +11,13 @@ export const workspaceExportToolDefinitions = [
     {
         name: "export_workspace_csv",
         description: "Export active-workspace outreach CSVs to local files on the MCP host. " +
-            "Phase 70 supports workflow-table-backed reached-out people and event-level outreach only. " +
+            "Use exportIntent to disambiguate counts before exporting: " +
+            "`reached_out_people` means one deduped row per unique prospect who received an actual contact attempt (invite, DM, open InMail, or paid/closed InMail) and is the right choice for 'everyone we reached out to'; " +
+            "`dashboard_messages` means message events only (DMs + InMails), matching the dashboard Messages Sent card; " +
+            "`connections_sent` means invite events only; " +
+            "`outreach_event_log` means one row per action event for audit/reconciliation; " +
+            "`people_and_events` exports the reached-out people CSV plus matching contact event rows. " +
+            "If the user asks for 'sent', 'reached out', or cites conflicting dashboard/export numbers, ask which intent they want before calling the tool. " +
             "Requires a valid Sellable API key plus active workspace; run list_workspaces and set_active_workspace first if needed. " +
             "The manifest includes file paths, counts, filters, package/runtime metadata, and skipped/deferred scope notes. " +
             "CSV files may contain prospect and outreach metadata, so store them appropriately.",
@@ -23,10 +29,36 @@ export const workspaceExportToolDefinitions = [
                     enum: ["outreach"],
                     description: "Export family. Phase 70 supports outreach only.",
                 },
+                exportIntent: {
+                    type: "string",
+                    enum: [
+                        "reached_out_people",
+                        "people_and_events",
+                        "outreach_event_log",
+                        "dashboard_messages",
+                        "connections_sent",
+                    ],
+                    description: "Recommended semantic export. Use reached_out_people for 'everyone we reached out to'; dashboard_messages for the dashboard Messages Sent card; connections_sent for invites; outreach_event_log for audit rows; people_and_events for both reached people and matching contact events.",
+                },
                 datasets: {
                     type: "array",
                     items: { type: "string", enum: ["people", "events"] },
-                    description: "Datasets to export. Defaults to both people and events.",
+                    description: "Low-level datasets to export. people is one deduped prospect row; events is one action row. Omit this and use exportIntent for clearer behavior.",
+                },
+                actionTypes: {
+                    type: "array",
+                    items: {
+                        type: "string",
+                        enum: [
+                            "INVITE",
+                            "DM",
+                            "INMAIL_OPEN",
+                            "INMAIL_CLOSED",
+                            "VIEW_PROFILE",
+                            "COMMENT",
+                        ],
+                    },
+                    description: "Optional low-level action filter. Usually omit and use exportIntent. Dashboard messages are DM + INMAIL_OPEN + INMAIL_CLOSED; reached-out/contact events are INVITE + DM + INMAIL_OPEN + INMAIL_CLOSED.",
                 },
                 outputDir: {
                     type: "string",
@@ -56,6 +88,52 @@ export const workspaceExportToolDefinitions = [
         },
     },
 ];
+const CONTACT_ACTION_TYPES = [
+    "INVITE",
+    "DM",
+    "INMAIL_OPEN",
+    "INMAIL_CLOSED",
+];
+const DASHBOARD_MESSAGE_ACTION_TYPES = [
+    "DM",
+    "INMAIL_OPEN",
+    "INMAIL_CLOSED",
+];
+const ALL_ACTION_TYPES = [
+    "INVITE",
+    "DM",
+    "INMAIL_OPEN",
+    "INMAIL_CLOSED",
+    "VIEW_PROFILE",
+    "COMMENT",
+];
+const EXPORT_INTENT_CONFIG = {
+    reached_out_people: {
+        datasets: ["people"],
+        actionTypes: CONTACT_ACTION_TYPES,
+        description: "Unique prospects who received at least one actual contact attempt: invite, DM, open InMail, or paid/closed InMail.",
+    },
+    people_and_events: {
+        datasets: ["people", "events"],
+        actionTypes: CONTACT_ACTION_TYPES,
+        description: "Reached-out people plus one matching contact event row per invite, DM, open InMail, or paid/closed InMail.",
+    },
+    outreach_event_log: {
+        datasets: ["events"],
+        actionTypes: ALL_ACTION_TYPES,
+        description: "Raw workflow-table-backed action event log for audit/reconciliation, including profile views and comments when present.",
+    },
+    dashboard_messages: {
+        datasets: ["events"],
+        actionTypes: DASHBOARD_MESSAGE_ACTION_TYPES,
+        description: "Message events only, matching the dashboard Messages Sent card: DMs + open InMails + paid/closed InMails.",
+    },
+    connections_sent: {
+        datasets: ["events"],
+        actionTypes: ["INVITE"],
+        description: "Connection invite events only, matching the dashboard Connections Sent sub-count.",
+    },
+};
 function assertIsoDate(value, field) {
     if (value === undefined || value === null || value === "")
         return undefined;
@@ -97,17 +175,57 @@ function normalizeDatasets(value) {
         return dataset;
     });
 }
+function normalizeExportIntent(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    if (value !== "reached_out_people" &&
+        value !== "people_and_events" &&
+        value !== "outreach_event_log" &&
+        value !== "dashboard_messages" &&
+        value !== "connections_sent") {
+        throw new Error("exportIntent is not supported");
+    }
+    return value;
+}
+function normalizeActionTypes(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("actionTypes must be an array");
+    if (value.length === 0)
+        throw new Error("actionTypes cannot be empty");
+    const unique = Array.from(new Set(value));
+    return unique.map((actionType) => {
+        if (actionType !== "INVITE" &&
+            actionType !== "DM" &&
+            actionType !== "INMAIL_OPEN" &&
+            actionType !== "INMAIL_CLOSED" &&
+            actionType !== "VIEW_PROFILE" &&
+            actionType !== "COMMENT") {
+            throw new Error("actionTypes contains an unsupported action type");
+        }
+        return actionType;
+    });
+}
 function validateInput(input) {
     if (input.exportType && input.exportType !== "outreach") {
         throw new Error("exportType must be outreach");
     }
+    const exportIntent = normalizeExportIntent(input.exportIntent);
+    const intentConfig = exportIntent ? EXPORT_INTENT_CONFIG[exportIntent] : null;
     const fromSentAt = assertIsoDate(input.fromSentAt, "fromSentAt");
     const toSentAt = assertIsoDate(input.toSentAt, "toSentAt");
     if (fromSentAt && toSentAt && new Date(fromSentAt) > new Date(toSentAt)) {
         throw new Error("fromSentAt must be before toSentAt");
     }
+    const actionTypes = normalizeActionTypes(input.actionTypes);
     return {
-        datasets: normalizeDatasets(input.datasets),
+        exportIntent,
+        intentDescription: intentConfig?.description ?? null,
+        datasets: input.datasets === undefined || input.datasets === null
+            ? (intentConfig?.datasets ?? ["people", "events"])
+            : normalizeDatasets(input.datasets),
+        actionTypes: actionTypes.length > 0 ? actionTypes : (intentConfig?.actionTypes ?? []),
         outputDir: input.outputDir,
         fromSentAt,
         toSentAt,
@@ -115,6 +233,15 @@ function validateInput(input) {
         tableIds: assertIdList(input.tableIds, "tableIds"),
     };
 }
+function countDefinitions() {
+    return {
+        reachedOutPeople: "Deduped prospects with at least one actual contact attempt: INVITE, DM, INMAIL_OPEN, or INMAIL_CLOSED. This is what 'everyone we reached out to' should mean.",
+        outreachEvents: "One row per exported LinkedInOutreach action event after workspace, date, campaign/table, and action-type filters.",
+        dashboardMessagesSent: "Dashboard Messages Sent equals DM + INMAIL_OPEN + INMAIL_CLOSED events. It excludes connection invites.",
+        connectionsSent: "Dashboard Connections Sent equals INVITE events. Accepted invites show separately as Connections Made.",
+        profileViews: "VIEW_PROFILE is an action event for audit logs, but it is not a contact attempt and should not define reached-out people.",
+    };
+}
 async function packageVersion() {
     const entryDir = process.argv[1]
         ? path.dirname(path.resolve(process.argv[1]))
@@ -226,6 +353,7 @@ export async function exportWorkspaceCsv(input = {}) {
         toSentAt: validated.toSentAt,
         campaignIds: validated.campaignIds,
         tableIds: validated.tableIds,
+        actionTypes: validated.actionTypes,
     });
     const metadataEndpoint = `/api/v3/mcp/workspace-export/outreach/metadata${metadataQuery}`;
     const backendMetadata = await api.get(metadataEndpoint);
@@ -243,6 +371,7 @@ export async function exportWorkspaceCsv(input = {}) {
             toSentAt: validated.toSentAt,
             campaignIds: validated.campaignIds,
             tableIds: validated.tableIds,
+            actionTypes: validated.actionTypes,
         });
         const endpoint = `/api/v3/mcp/workspace-export/outreach${query}`;
         const filePath = path.join(runDir, `outreach-${dataset}.csv`);
@@ -278,6 +407,9 @@ export async function exportWorkspaceCsv(input = {}) {
         status: failures.length > 0 ? "partial" : "success",
         tool: "export_workspace_csv",
         exportType: "outreach",
+        exportIntent: validated.exportIntent ?? "legacy_datasets",
+        intentDescription: validated.intentDescription,
+        countDefinitions: countDefinitions(),
         startedAt,
         completedAt: new Date().toISOString(),
         package: {
@@ -298,6 +430,7 @@ export async function exportWorkspaceCsv(input = {}) {
             toSentAt: validated.toSentAt ?? null,
             campaignIds: validated.campaignIds,
             tableIds: validated.tableIds,
+            actionTypes: validated.actionTypes,
             exportCutoff,
         },
         outputDir: runDir,
@@ -318,6 +451,10 @@ export async function exportWorkspaceCsv(input = {}) {
             status: file.status,
         })),
         exportCutoff,
+        exportIntent: validated.exportIntent ?? null,
+        intentDescription: validated.intentDescription,
+        countDefinitions: countDefinitions(),
+        counts: backendMetadata.counts ?? {},
         workspace: backendMetadata.workspace ?? {
             id: workspaceId,
             name: config.activeWorkspaceName || config.workspaceName || null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sellable/mcp",
-  "version": "0.1.364",
+  "version": "0.1.366",
   "type": "module",
   "description": "Sellable MCP server for Claude Code and Codex campaign workflows",
   "main": "dist/index.js",