@sellable/mcp 0.1.0

package/dist/tools/readiness.js

@@ -0,0 +1,510 @@
+import { getApi } from "../api.js";
+import { hydrateCampaignContextFromNavigation } from "./context.js";
+import { getCampaignNavigationState } from "./navigation.js";
+const DEFAULT_TIMEOUT_MS = 90000;
+const DEFAULT_INTERVAL_MS = 2000;
+const TOOL_CALL_TIMEOUT_GUARD_MS = 55000;
+const SIGNAL_PENDING_STALL_MS = 20000;
+function normalizeLeadSourceProvider(provider) {
+    if (!provider)
+        return undefined;
+    if (provider === "apollo-ai" || provider === "apollo")
+        return "apollo";
+    if (provider === "sales-nav")
+        return "sales-nav";
+    if (provider === "prospeo")
+        return "prospeo";
+    if (provider === "signal-discovery")
+        return "signal-discovery";
+    if (provider === "csv-linkedin")
+        return "csv-linkedin";
+    return undefined;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function resolveWaitTimeout(timeoutMs) {
+    const requestedTimeoutMs = Math.max(5000, timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const effectiveTimeoutMs = Math.min(requestedTimeoutMs, TOOL_CALL_TIMEOUT_GUARD_MS);
+    return {
+        requestedTimeoutMs,
+        effectiveTimeoutMs,
+        guardApplied: requestedTimeoutMs > effectiveTimeoutMs,
+    };
+}
+function hasNonWaitableMissing(missing) {
+    const nonWaitable = new Set([
+        "clientProspectId",
+        "campaignBrief.content",
+        "leadSourceType",
+        'leadSourceType="new"',
+        "leadSourceProvider",
+    ]);
+    return missing.some((m) => nonWaitable.has(m));
+}
+export const readinessToolDefinitions = [
+    {
+        name: "wait_for_campaign_table_ready",
+        description: "Poll backend state until the campaign workflow table exists and (by default) has rows. Use after confirm_lead_list before advancing steps.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                campaignId: {
+                    type: "string",
+                    description: "Campaign offer ID",
+                },
+                timeoutMs: {
+                    type: "number",
+                    description: `Maximum time to wait in ms (default ${DEFAULT_TIMEOUT_MS})`,
+                },
+                intervalMs: {
+                    type: "number",
+                    description: `Polling interval in ms (default ${DEFAULT_INTERVAL_MS})`,
+                },
+                requireRows: {
+                    type: "boolean",
+                    description: "When true (default), wait for at least one row to appear.",
+                },
+            },
+            required: ["campaignId"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "wait_for_lead_list_ready",
+        description: "Poll the lead list table until the import completes (default) and rows appear. Use right after import_leads before asking the user to confirm the list.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                leadListId: {
+                    type: "string",
+                    description: "Lead list table ID. If omitted, uses campaignOfferId to read selectedLeadListId.",
+                },
+                campaignOfferId: {
+                    type: "string",
+                    description: "Campaign offer ID (used to resolve selectedLeadListId if leadListId is missing).",
+                },
+                provider: {
+                    type: "string",
+                    description: "Lead provider (apollo, sales-nav, prospeo, signal-discovery). If omitted, derived from campaignOfferId when possible.",
+                },
+                jobId: {
+                    type: "string",
+                    description: "Import job ID for providers that require it (sales-nav, prospeo).",
+                },
+                targetLeadCount: {
+                    type: "number",
+                    description: "Target number of leads requested. Used as a fallback completion check when status is unavailable.",
+                },
+                timeoutMs: {
+                    type: "number",
+                    description: `Maximum time to wait in ms (default ${DEFAULT_TIMEOUT_MS})`,
+                },
+                intervalMs: {
+                    type: "number",
+                    description: `Polling interval in ms (default ${DEFAULT_INTERVAL_MS})`,
+                },
+                requireRows: {
+                    type: "boolean",
+                    description: "When true (default), wait for at least one row to appear.",
+                },
+                requireComplete: {
+                    type: "boolean",
+                    description: "When true (default), wait until the import job completes (or hits targetLeadCount when status is unavailable).",
+                },
+            },
+            required: [],
+            additionalProperties: false,
+        },
+    },
+];
+export async function waitForCampaignTableReady(input) {
+    const { effectiveTimeoutMs, guardApplied, requestedTimeoutMs } = resolveWaitTimeout(input.timeoutMs);
+    const intervalMs = Math.max(500, input.intervalMs ?? DEFAULT_INTERVAL_MS);
+    const requireRows = input.requireRows !== false;
+    const start = Date.now();
+    let attempts = 0;
+    let lastState = null;
+    while (Date.now() - start <= effectiveTimeoutMs) {
+        attempts += 1;
+        const navState = await getCampaignNavigationState({
+            campaignId: input.campaignId,
+            includeTableCheck: true,
+        });
+        lastState = navState;
+        if (hasNonWaitableMissing(navState.missing)) {
+            return {
+                ready: false,
+                reason: "blocked_by_prerequisites",
+                attempts,
+                elapsedMs: Date.now() - start,
+                navigation: navState,
+            };
+        }
+        const hasTable = Boolean(navState.table.workflowTableId);
+        const hasRows = navState.table.hasRows === true;
+        const rowsSatisfied = requireRows ? hasRows : hasTable;
+        const missingTableBits = navState.missing.filter((m) => m === "workflowTableId" || m === "workflowTableRows");
+        if (hasTable && rowsSatisfied && missingTableBits.length === 0) {
+            const entry = hydrateCampaignContextFromNavigation(navState, "wait_for_campaign_table_ready");
+            return {
+                ready: true,
+                attempts,
+                elapsedMs: Date.now() - start,
+                navigation: entry.navState,
+            };
+        }
+        await sleep(intervalMs);
+    }
+    return {
+        ready: false,
+        reason: guardApplied ? "tool_timeout_guard" : "timeout",
+        attempts,
+        elapsedMs: Date.now() - start,
+        navigation: lastState,
+        warning: guardApplied
+            ? `Stopped after ${effectiveTimeoutMs}ms to avoid host tool timeout (requested ${requestedTimeoutMs}ms).`
+            : undefined,
+    };
+}
+export async function waitForLeadListReady(input) {
+    const api = getApi();
+    const { effectiveTimeoutMs, guardApplied, requestedTimeoutMs } = resolveWaitTimeout(input.timeoutMs);
+    const intervalMs = Math.max(500, input.intervalMs ?? DEFAULT_INTERVAL_MS);
+    const requireRows = input.requireRows !== false;
+    const requireComplete = input.requireComplete !== false;
+    let leadListId = input.leadListId;
+    let provider = input.provider;
+    let targetLeadCount = input.targetLeadCount;
+    if (input.campaignOfferId && (!leadListId || !provider)) {
+        const campaign = await api.get(`/api/v2/campaign-offers/${input.campaignOfferId}`);
+        if (!leadListId) {
+            leadListId = campaign.selectedLeadListId ?? undefined;
+        }
+        if (!provider) {
+            provider = normalizeLeadSourceProvider(campaign.leadSourceProvider);
+        }
+    }
+    if (!leadListId) {
+        return {
+            ready: false,
+            reason: "missing_lead_list_id",
+            attempts: 0,
+            elapsedMs: 0,
+            leadListId: null,
+        };
+    }
+    const start = Date.now();
+    let attempts = 0;
+    let lastRowCount = null;
+    let lastError = null;
+    let lastStatus = null;
+    let missingJobId = false;
+    let signalPendingSince = null;
+    let signalPendingFingerprint = null;
+    while (Date.now() - start <= effectiveTimeoutMs) {
+        attempts += 1;
+        try {
+            const meta = await api.get(`/api/v3/workflow-tables/${leadListId}?mode=meta`);
+            const rowCount = meta?.rowCount ?? 0;
+            lastRowCount = rowCount;
+            const config = meta?.table?.config ?? null;
+            const configStatus = config?.importStatus ?? null;
+            const configError = config?.importError ?? null;
+            const importProgress = config?.importProgress ?? null;
+            const configTarget = typeof config?.targetLeadCount === "number"
+                ? config.targetLeadCount
+                : typeof importProgress?.total === "number"
+                    ? (importProgress?.total ?? null)
+                    : null;
+            if (!provider && config?.importProvider) {
+                provider =
+                    normalizeLeadSourceProvider(config.importProvider) ?? provider;
+            }
+            if (typeof configTarget === "number" && !targetLeadCount) {
+                targetLeadCount = configTarget;
+            }
+            let jobId = input.jobId;
+            if (!jobId && typeof config?.importJobId === "string") {
+                jobId = config.importJobId;
+            }
+            let importComplete = !requireComplete;
+            let statusTarget = null;
+            if (requireComplete) {
+                if (configStatus === "error" && configError === "Import cancelled.") {
+                    return {
+                        ready: false,
+                        reason: "cancelled",
+                        leadListId,
+                        provider: provider ?? null,
+                        attempts,
+                        elapsedMs: Date.now() - start,
+                        rowCount,
+                        status: "CANCELLED",
+                        targetLeadCount,
+                    };
+                }
+                if (configError && configStatus !== "complete") {
+                    return {
+                        ready: false,
+                        reason: "import_failed",
+                        leadListId,
+                        provider: provider ?? null,
+                        attempts,
+                        elapsedMs: Date.now() - start,
+                        rowCount,
+                        status: configStatus,
+                        targetLeadCount,
+                        error: configError,
+                    };
+                }
+                if (configStatus) {
+                    lastStatus = configStatus;
+                    if (configStatus === "error") {
+                        return {
+                            ready: false,
+                            reason: "import_failed",
+                            leadListId,
+                            provider: provider ?? null,
+                            attempts,
+                            elapsedMs: Date.now() - start,
+                            rowCount,
+                            status: configStatus,
+                            targetLeadCount,
+                            error: configError,
+                        };
+                    }
+                    if (configStatus === "complete") {
+                        importComplete = true;
+                    }
+                }
+                // If config didn't provide a status, fall back to provider-specific checks.
+                if (!configStatus) {
+                    if (provider === "apollo") {
+                        const statusResponse = await api.get(`/api/v3/lead-lists/${leadListId}/apollo-import/status`);
+                        const status = statusResponse?.status ?? null;
+                        lastStatus = status;
+                        statusTarget = statusResponse?.progress?.targetLeadCount ?? null;
+                        if (typeof statusTarget === "number" && !targetLeadCount) {
+                            targetLeadCount = statusTarget;
+                        }
+                        if (status === "FAILED") {
+                            return {
+                                ready: false,
+                                reason: "import_failed",
+                                leadListId,
+                                provider: provider ?? null,
+                                attempts,
+                                elapsedMs: Date.now() - start,
+                                rowCount,
+                                status,
+                                targetLeadCount,
+                                error: statusResponse?.lastError ?? null,
+                            };
+                        }
+                        if (status === "CANCELLED") {
+                            return {
+                                ready: false,
+                                reason: "cancelled",
+                                leadListId,
+                                provider: provider ?? null,
+                                attempts,
+                                elapsedMs: Date.now() - start,
+                                rowCount,
+                                status,
+                                targetLeadCount,
+                            };
+                        }
+                        if (status === "COMPLETED") {
+                            importComplete = true;
+                        }
+                        else if (status === "NO_JOB" && rowCount > 0) {
+                            importComplete = true;
+                        }
+                    }
+                    else if (provider === "sales-nav") {
+                        if (jobId) {
+                            const statusResponse = await api.get(`/api/v3/sales-nav/export?jobId=${jobId}`);
+                            const status = statusResponse?.job?.status ?? null;
+                            lastStatus = status;
+                            statusTarget = statusResponse?.job?.targetLeadCount ?? null;
+                            if (typeof statusTarget === "number" && !targetLeadCount) {
+                                targetLeadCount = statusTarget;
+                            }
+                            if (status === "FAILED") {
+                                return {
+                                    ready: false,
+                                    reason: "import_failed",
+                                    leadListId,
+                                    provider: provider ?? null,
+                                    attempts,
+                                    elapsedMs: Date.now() - start,
+                                    rowCount,
+                                    status,
+                                    targetLeadCount,
+                                };
+                            }
+                            if (status === "CANCELLED") {
+                                return {
+                                    ready: false,
+                                    reason: "cancelled",
+                                    leadListId,
+                                    provider: provider ?? null,
+                                    attempts,
+                                    elapsedMs: Date.now() - start,
+                                    rowCount,
+                                    status,
+                                    targetLeadCount,
+                                };
+                            }
+                            if (status === "COMPLETED") {
+                                importComplete = true;
+                            }
+                        }
+                        else if (typeof targetLeadCount === "number") {
+                            importComplete = rowCount >= targetLeadCount;
+                        }
+                        else {
+                            missingJobId = true;
+                        }
+                    }
+                    else if (provider === "prospeo") {
+                        if (jobId) {
+                            const statusResponse = await api.get(`/api/v3/lead-lists/${leadListId}/prospeo-import/status?jobId=${jobId}`);
+                            const status = statusResponse?.job?.status ?? null;
+                            lastStatus = status;
+                            statusTarget = statusResponse?.job?.targetLeadCount ?? null;
+                            if (typeof statusTarget === "number" && !targetLeadCount) {
+                                targetLeadCount = statusTarget;
+                            }
+                            if (status === "FAILED") {
+                                return {
+                                    ready: false,
+                                    reason: "import_failed",
+                                    leadListId,
+                                    provider: provider ?? null,
+                                    attempts,
+                                    elapsedMs: Date.now() - start,
+                                    rowCount,
+                                    status,
+                                    targetLeadCount,
+                                };
+                            }
+                            if (status === "CANCELLED") {
+                                return {
+                                    ready: false,
+                                    reason: "cancelled",
+                                    leadListId,
+                                    provider: provider ?? null,
+                                    attempts,
+                                    elapsedMs: Date.now() - start,
+                                    rowCount,
+                                    status,
+                                    targetLeadCount,
+                                };
+                            }
+                            if (status === "COMPLETED") {
+                                importComplete = true;
+                            }
+                        }
+                        else if (typeof targetLeadCount === "number") {
+                            importComplete = rowCount >= targetLeadCount;
+                        }
+                        else {
+                            missingJobId = true;
+                        }
+                    }
+                    else if (provider === "signal-discovery") {
+                        // Config-based check already handled above.
+                    }
+                    else if (typeof targetLeadCount === "number") {
+                        importComplete = rowCount >= targetLeadCount;
+                    }
+                }
+            }
+            if (provider === "signal-discovery" && requireComplete) {
+                const noRows = rowCount === 0;
+                const hasProgress = typeof importProgress?.processed === "number"
+                    ? importProgress.processed > 0
+                    : typeof importProgress?.leadsImported === "number"
+                        ? importProgress.leadsImported > 0
+                        : false;
+                const pendingNoProgress = configStatus === "pending" && noRows && !hasProgress && !configError;
+                if (pendingNoProgress) {
+                    const nextFingerprint = JSON.stringify({
+                        status: configStatus,
+                        phase: importProgress?.phase ?? null,
+                        processed: importProgress?.processed ?? null,
+                        leadsImported: importProgress?.leadsImported ?? null,
+                        rowCount,
+                    });
+                    if (signalPendingSince === null ||
+                        signalPendingFingerprint !== nextFingerprint) {
+                        signalPendingSince = Date.now();
+                        signalPendingFingerprint = nextFingerprint;
+                    }
+                    else if (Date.now() - signalPendingSince >=
+                        SIGNAL_PENDING_STALL_MS) {
+                        return {
+                            ready: false,
+                            reason: "stalled_import",
+                            leadListId,
+                            provider: provider ?? null,
+                            attempts,
+                            elapsedMs: Date.now() - start,
+                            rowCount,
+                            status: configStatus,
+                            targetLeadCount,
+                            error: "Import stayed in pending state with no rows or progress. The job may not have started.",
+                        };
+                    }
+                }
+                else {
+                    signalPendingSince = null;
+                    signalPendingFingerprint = null;
+                }
+            }
+            if ((!requireRows || rowCount > 0) && importComplete) {
+                return {
+                    ready: true,
+                    leadListId,
+                    provider: provider ?? null,
+                    attempts,
+                    elapsedMs: Date.now() - start,
+                    rowCount,
+                    status: lastStatus,
+                    targetLeadCount: targetLeadCount ?? null,
+                };
+            }
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        await sleep(intervalMs);
+    }
+    const timedOutWithRows = (lastRowCount ?? 0) > 0;
+    const timeoutReason = missingJobId
+        ? "missing_job_id"
+        : timedOutWithRows
+            ? "timeout_with_rows"
+            : guardApplied
+                ? "tool_timeout_guard"
+                : "timeout";
+    return {
+        ready: !missingJobId && timedOutWithRows,
+        reason: timeoutReason,
+        leadListId,
+        provider: provider ?? null,
+        attempts,
+        elapsedMs: Date.now() - start,
+        rowCount: lastRowCount,
+        status: lastStatus ?? undefined,
+        targetLeadCount: targetLeadCount ?? undefined,
+        warning: !missingJobId && timedOutWithRows
+            ? "Timed out waiting for import status, but rows exist."
+            : guardApplied
+                ? `Stopped after ${effectiveTimeoutMs}ms to avoid host tool timeout (requested ${requestedTimeoutMs}ms). Re-run wait_for_lead_list_ready to keep polling.`
+                : undefined,
+        error: lastError ?? undefined,
+    };
+}

package/dist/tools/rows.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Lightweight row for listing - minimal fields for lead selection.
+ */
+export interface LightweightRow {
+    id: string;
+    name: string;
+    company: string;
+    title: string;
+    linkedinUrl: string | null;
+    message: string | null;
+    messageCellId: string | null;
+    subject?: string | null;
+    subjectCellId?: string | null;
+    enrichCellId?: string | null;
+    enrichStatus?: string | null;
+    icpCellId?: string | null;
+    icpStatus?: string | null;
+    icpPassed?: boolean | null;
+    carryData?: Record<string, string>;
+}
+/**
+ * Full row for crafting - includes enrichment essentials.
+ */
+export interface FullRow {
+    id: string;
+    name: string;
+    company: string;
+    title: string;
+    linkedinUrl: string | null;
+    currentMessage: string | null;
+    messageCellId: string | null;
+    currentSubject?: string | null;
+    subjectCellId?: string | null;
+    messageSequenceCellId?: string | null;
+    isApproved: boolean;
+    approveCellId?: string | null;
+    exampleCellId?: string | null;
+    isExample?: boolean;
+    carryData?: Record<string, string>;
+    enrichment: {
+        summary: string | null;
+        location: string | null;
+        experience: Array<{
+            title: string;
+            company: string;
+            duration: string;
+            description: string;
+        }>;
+        education: Array<{
+            degree: string;
+            school: string;
+        }>;
+        skills: string[];
+    } | null;
+}
+export interface RowsResponse {
+    rows: LightweightRow[];
+    pagination: {
+        page: number;
+        totalPages: number;
+        totalCount: number;
+    };
+}
+export declare const rowToolDefinitions: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            tableId: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            page: {
+                type: string;
+                description: string;
+                default: number;
+            };
+            rowIds?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            tableId: {
+                type: string;
+                description: string;
+            };
+            rowIds: {
+                oneOf: ({
+                    type: string;
+                    items?: undefined;
+                } | {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                })[];
+                description: string;
+            };
+            limit?: undefined;
+            page?: undefined;
+        };
+        required: string[];
+    };
+})[];
+export declare function getTableRows(tableId: string, options?: {
+    limit?: number;
+    page?: number;
+}): Promise<RowsResponse>;
+export declare function getTableRowsMinimal(tableId: string, options?: {
+    limit?: number;
+    page?: number;
+}): Promise<RowsResponse>;
+export declare function getRows(tableId: string, rowIds: string | string[]): Promise<{
+    rows: FullRow[];
+}>;