@sellable/mcp 0.1.0

package/dist/tools/auth.js

@@ -0,0 +1,124 @@
+import { getApi, SellableApiError } from "../api.js";
+import { getConfig, getConfigPath } from "../auth.js";
+function maskToken(token) {
+    if (token.length <= 10)
+        return `${token.slice(0, 4)}...`;
+    return `${token.slice(0, 8)}...${token.slice(-2)}`;
+}
+export const authToolDefinitions = [
+    {
+        name: "get_auth_status",
+        description: "Verify Sellable authentication early. Call this before any campaign work. Returns ok=false with clear guidance when the token is missing, revoked, or the active workspace is not set. IMPORTANT: When auth succeeds, ALWAYS tell the user the _userNotice message so they know which workspace is active.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+            additionalProperties: false,
+        },
+    },
+];
+export async function getAuthStatus() {
+    const configPath = getConfigPath();
+    const checkedAt = new Date().toISOString();
+    const base = {
+        ok: false,
+        configPath,
+        activeEnvName: null,
+        apiUrl: null,
+        activeWorkspaceId: null,
+        activeWorkspaceName: null,
+        tokenPrefix: null,
+        workspacesCount: null,
+        _userNotice: null,
+        checkedAt,
+    };
+    try {
+        const config = getConfig();
+        base.activeEnvName = config.activeEnvName || null;
+        const api = getApi();
+        const { workspaces } = await api.get("/api/v3/workspaces");
+        const activeWorkspaceId = config.activeWorkspaceId || config.workspaceId || null;
+        const activeWorkspace = activeWorkspaceId
+            ? workspaces.find((ws) => ws.id === activeWorkspaceId)
+            : null;
+        if (!activeWorkspaceId) {
+            return {
+                ...base,
+                apiUrl: config.apiUrl || null,
+                tokenPrefix: maskToken(config.token),
+                workspacesCount: workspaces.length,
+                error: {
+                    type: "workspace",
+                    message: "No active workspace selected.",
+                    guidance: "Run list_workspaces then set_active_workspace to choose a workspace.",
+                },
+            };
+        }
+        if (!activeWorkspace) {
+            const available = workspaces
+                .map((ws) => `${ws.name} (${ws.id})`)
+                .join(", ");
+            return {
+                ...base,
+                apiUrl: config.apiUrl || null,
+                tokenPrefix: maskToken(config.token),
+                workspacesCount: workspaces.length,
+                error: {
+                    type: "workspace",
+                    message: `Active workspace ${activeWorkspaceId} not found in access list.`,
+                    guidance: available
+                        ? `Available: ${available}. Run set_active_workspace with a valid ID.`
+                        : "Run list_workspaces to view available workspaces, then set_active_workspace.",
+                },
+            };
+        }
+        const workspaceName = activeWorkspace.name || config.activeWorkspaceName || null;
+        const envLabel = config.activeEnvName || null;
+        const wsLabel = workspaceName || activeWorkspaceId;
+        const notice = envLabel
+            ? `Workspace: ${wsLabel} (${envLabel})`
+            : `Workspace: ${wsLabel}`;
+        return {
+            ok: true,
+            configPath,
+            activeEnvName: envLabel,
+            apiUrl: config.apiUrl || null,
+            activeWorkspaceId,
+            activeWorkspaceName: workspaceName,
+            tokenPrefix: maskToken(config.token),
+            workspacesCount: workspaces.length,
+            _userNotice: notice,
+            checkedAt,
+            error: null,
+        };
+    }
+    catch (error) {
+        if (error instanceof SellableApiError && error.isAuthError) {
+            return {
+                ...base,
+                error: {
+                    type: "auth",
+                    status: error.status,
+                    message: error.body || error.message,
+                    guidance: error.guidance ||
+                        `Update ${configPath} with a valid token, then retry get_auth_status.`,
+                },
+            };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        const isConfigError = message.includes("Sellable not configured") ||
+            message.includes("Invalid JSON") ||
+            message.includes("Missing 'token'");
+        const guidance = isConfigError
+            ? `Create ${configPath} with your token, then run list_workspaces + set_active_workspace.`
+            : `Fix the configuration in ${configPath}, then retry get_auth_status.`;
+        return {
+            ...base,
+            error: {
+                type: isConfigError ? "config" : "api",
+                message,
+                guidance,
+            },
+        };
+    }
+}

package/dist/tools/blueprint-commit.d.ts

@@ -0,0 +1,174 @@
+type BlueprintColumn = {
+    id: string;
+    type: string;
+    name: string;
+    config: Record<string, unknown>;
+    inputMapping?: Record<string, string>;
+    runCondition?: string;
+};
+type Blueprint = {
+    columns: BlueprintColumn[];
+    edges: Array<{
+        from: string;
+        to: string;
+        via: string;
+    }>;
+};
+export type CommitBlueprintInput = {
+    tableId: string;
+    blueprint: Blueprint | string;
+};
+export type AddColumnInput = {
+    tableId: string;
+    column: BlueprintColumn | string;
+    validateOnly?: boolean;
+};
+/**
+ * Phase 98 MCP surface (3 new tools — prompt-level tool allowlist must stay ≤ 15):
+ *
+ * 1. sellable:commit_blueprint
+ *    validateBlueprint -> commitBlueprint(topo walk) -> TableManagementService.addColumn per node.
+ *    Input: { tableId: string, blueprint: Blueprint }
+ *    Output:
+ *      { ok: true, columnIds: string[] }
+ *      | { ok: false, errors: BlueprintError[] }
+ *      | { ok: false, createdColumnIds: string[], failedAt: { columnId, reason }, rolledBack: string[], rollbackFailures: { columnId, reason }[] }
+ *      | { ok: false, error: "concurrent_commit" }
+ *
+ * 2. sellable:add_column
+ *    Validate and optionally add one column outside the blueprint flow.
+ *
+ * 3. sellable:verify_table_row
+ *    Run one row end-to-end. Per-column status: success | error | skipped | deferred_to_sweeper | condition_not_met.
+ *    Skips honor caller-supplied skipColumnIds[]; never heuristics.
+ *    Forces re-execution via forceRerun:true executor param (does not mutate isOverridden).
+ *    Honors AbortSignal from the request; aborted mid-run rows are reset to prior terminal state in try/finally.
+ *
+ * Not included (intentionally):
+ * - configure_column: merged into add_column/commit_blueprint.
+ * - update_column_run_condition: verify supplies skipColumnIds directly (no runtime runCondition override).
+ */
+export declare const blueprintCommitToolDefinitions: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            tableId: {
+                type: string;
+                description: string;
+            };
+            blueprint: {
+                description: string;
+                type: string;
+                properties: {
+                    columns: {
+                        type: string;
+                        items: {
+                            type: string;
+                            properties: {
+                                id: {
+                                    type: string;
+                                };
+                                type: {
+                                    type: string;
+                                };
+                                name: {
+                                    type: string;
+                                };
+                                config: {
+                                    type: string;
+                                };
+                                inputMapping: {
+                                    type: string;
+                                    additionalProperties: {
+                                        type: string;
+                                    };
+                                };
+                                runCondition: {
+                                    type: string;
+                                };
+                            };
+                            required: string[];
+                            additionalProperties: boolean;
+                        };
+                    };
+                    edges: {
+                        type: string;
+                        items: {
+                            type: string;
+                            properties: {
+                                from: {
+                                    type: string;
+                                };
+                                to: {
+                                    type: string;
+                                };
+                                via: {
+                                    type: string;
+                                };
+                            };
+                            required: string[];
+                            additionalProperties: boolean;
+                        };
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+            column?: undefined;
+            validateOnly?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            tableId: {
+                type: string;
+                description: string;
+            };
+            column: {
+                description: string;
+                type: string;
+                properties: {
+                    id: {
+                        type: string;
+                    };
+                    type: {
+                        type: string;
+                    };
+                    name: {
+                        type: string;
+                    };
+                    config: {
+                        type: string;
+                    };
+                    inputMapping: {
+                        type: string;
+                        additionalProperties: {
+                            type: string;
+                        };
+                    };
+                    runCondition: {
+                        type: string;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+            validateOnly: {
+                type: string;
+                description: string;
+            };
+            blueprint?: undefined;
+        };
+        required: string[];
+    };
+})[];
+export declare function handleCommitBlueprint(input: CommitBlueprintInput): Promise<unknown>;
+export declare function handleAddColumn(input: AddColumnInput): Promise<unknown>;
+export {};

package/dist/tools/blueprint-commit.js

@@ -0,0 +1,286 @@
+import { getApi } from "../api.js";
+const knownBlueprintColumnTypes = new Set([
+    "ai_column",
+    "checkbox",
+    "formula",
+    "generate_message",
+    "http_request",
+    "inbound_webhook",
+    "score_icp_mcp",
+    "send_dm",
+    "send_inmail_closed",
+    "send_inmail_open",
+    "send_invite",
+    "text",
+    "view_profile",
+    "wait",
+    "is_open_profile",
+]);
+const blueprintColumnInputSchema = {
+    type: "object",
+    properties: {
+        id: { type: "string" },
+        type: { type: "string" },
+        name: { type: "string" },
+        config: { type: "object" },
+        inputMapping: {
+            type: "object",
+            additionalProperties: { type: "string" },
+        },
+        runCondition: { type: "string" },
+    },
+    required: ["id", "type", "name", "config"],
+    additionalProperties: true,
+};
+const blueprintInputSchema = {
+    type: "object",
+    properties: {
+        columns: {
+            type: "array",
+            items: blueprintColumnInputSchema,
+        },
+        edges: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    from: { type: "string" },
+                    to: { type: "string" },
+                    via: { type: "string" },
+                },
+                required: ["from", "to", "via"],
+                additionalProperties: false,
+            },
+        },
+    },
+    required: ["columns", "edges"],
+    additionalProperties: false,
+};
+/**
+ * Phase 98 MCP surface (3 new tools — prompt-level tool allowlist must stay ≤ 15):
+ *
+ * 1. sellable:commit_blueprint
+ *    validateBlueprint -> commitBlueprint(topo walk) -> TableManagementService.addColumn per node.
+ *    Input: { tableId: string, blueprint: Blueprint }
+ *    Output:
+ *      { ok: true, columnIds: string[] }
+ *      | { ok: false, errors: BlueprintError[] }
+ *      | { ok: false, createdColumnIds: string[], failedAt: { columnId, reason }, rolledBack: string[], rollbackFailures: { columnId, reason }[] }
+ *      | { ok: false, error: "concurrent_commit" }
+ *
+ * 2. sellable:add_column
+ *    Validate and optionally add one column outside the blueprint flow.
+ *
+ * 3. sellable:verify_table_row
+ *    Run one row end-to-end. Per-column status: success | error | skipped | deferred_to_sweeper | condition_not_met.
+ *    Skips honor caller-supplied skipColumnIds[]; never heuristics.
+ *    Forces re-execution via forceRerun:true executor param (does not mutate isOverridden).
+ *    Honors AbortSignal from the request; aborted mid-run rows are reset to prior terminal state in try/finally.
+ *
+ * Not included (intentionally):
+ * - configure_column: merged into add_column/commit_blueprint.
+ * - update_column_run_condition: verify supplies skipColumnIds directly (no runtime runCondition override).
+ */
+export const blueprintCommitToolDefinitions = [
+    {
+        name: "commit_blueprint",
+        description: "Validate and commit a full workflow-table blueprint (multiple columns + wiring) in one call. Use when you have designed every column up-front. NOT for incremental additions — use add_column for that.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tableId: {
+                    type: "string",
+                    description: "Workflow table ID",
+                },
+                blueprint: {
+                    ...blueprintInputSchema,
+                    description: "Blueprint with columns [{id,type,name,config,inputMapping?,runCondition?}] and edges [{from,to,via}]",
+                },
+            },
+            required: ["tableId", "blueprint"],
+        },
+    },
+    {
+        name: "add_column",
+        description: 'Validate and add a single column to an existing workflow table. Use validateOnly:true to dry-run. Use http_request named "Enrich Prospect" for enrichment, score_icp_mcp for ICP scoring, and generate_message for Sellable message generation. NOT for batch additions — use commit_blueprint.',
+        inputSchema: {
+            type: "object",
+            properties: {
+                tableId: {
+                    type: "string",
+                    description: "Workflow table ID",
+                },
+                column: {
+                    ...blueprintColumnInputSchema,
+                    description: "Column draft {id,type,name,config,inputMapping?,runCondition?}",
+                },
+                validateOnly: {
+                    type: "boolean",
+                    description: "When true, validate and normalize the column without creating it.",
+                },
+            },
+            required: ["tableId", "column"],
+        },
+    },
+];
+function parseJsonObject(value, label) {
+    try {
+        const parsed = JSON.parse(value);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {
+                ok: false,
+                error: `${label} JSON must parse to an object`,
+            };
+        }
+        return { ok: true, value: parsed };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: `${label} must be an object or valid JSON object string: ${error instanceof Error ? error.message : "invalid JSON"}`,
+        };
+    }
+}
+function coerceBlueprint(value) {
+    if (typeof value === "string") {
+        const parsed = parseJsonObject(value, "blueprint");
+        if (!parsed.ok) {
+            return {
+                ok: false,
+                errors: [
+                    {
+                        kind: "shape",
+                        message: parsed.error,
+                        zodIssues: [],
+                    },
+                ],
+            };
+        }
+        return { ok: true, blueprint: parsed.value };
+    }
+    return { ok: true, blueprint: value };
+}
+function coerceColumn(value) {
+    if (typeof value === "string") {
+        const parsed = parseJsonObject(value, "column");
+        if (!parsed.ok) {
+            return {
+                ok: false,
+                errors: [
+                    {
+                        kind: "shape",
+                        message: parsed.error,
+                        zodIssues: [],
+                    },
+                ],
+            };
+        }
+        return { ok: true, column: parsed.value };
+    }
+    return { ok: true, column: value };
+}
+function validateLocalBlueprint(blueprint) {
+    const errors = [];
+    if (!blueprint || !Array.isArray(blueprint.columns)) {
+        return {
+            ok: false,
+            errors: [
+                {
+                    kind: "shape",
+                    message: "Blueprint must include a columns array",
+                    zodIssues: [],
+                },
+            ],
+        };
+    }
+    for (const column of blueprint.columns) {
+        if (!knownBlueprintColumnTypes.has(column.type)) {
+            errors.push({
+                kind: "phantom_type",
+                columnId: column.id,
+                attemptedType: column.type,
+                availableTypes: Array.from(knownBlueprintColumnTypes).sort(),
+            });
+        }
+    }
+    return errors.length > 0
+        ? { ok: false, errors }
+        : { ok: true };
+}
+function topoSortBlueprint(blueprint) {
+    const columnsById = new Map(blueprint.columns.map((column) => [column.id, column]));
+    const depsById = new Map();
+    for (const column of blueprint.columns) {
+        depsById.set(column.id, new Set());
+    }
+    for (const edge of blueprint.edges || []) {
+        if (depsById.has(edge.to) && columnsById.has(edge.from)) {
+            depsById.get(edge.to)?.add(edge.from);
+        }
+    }
+    for (const column of blueprint.columns) {
+        for (const producerId of Object.values(column.inputMapping || {})) {
+            if (columnsById.has(producerId)) {
+                depsById.get(column.id)?.add(producerId);
+            }
+        }
+    }
+    const sorted = [];
+    const visiting = new Set();
+    const visited = new Set();
+    function visit(columnId) {
+        if (visited.has(columnId))
+            return;
+        if (visiting.has(columnId))
+            return;
+        visiting.add(columnId);
+        for (const depId of depsById.get(columnId) || []) {
+            visit(depId);
+        }
+        visiting.delete(columnId);
+        visited.add(columnId);
+        const column = columnsById.get(columnId);
+        if (column)
+            sorted.push(column);
+    }
+    for (const column of blueprint.columns) {
+        visit(column.id);
+    }
+    return { ...blueprint, columns: sorted };
+}
+export async function handleCommitBlueprint(input) {
+    const api = getApi();
+    const coerced = coerceBlueprint(input.blueprint);
+    if (!coerced.ok) {
+        return { ok: false, errors: coerced.errors };
+    }
+    const validation = validateLocalBlueprint(coerced.blueprint);
+    if (!validation.ok) {
+        return validation;
+    }
+    const blueprint = topoSortBlueprint(coerced.blueprint);
+    return api.post(`/api/v3/workflow-tables/${input.tableId}/columns/bulk`, {
+        blueprint,
+    });
+}
+export async function handleAddColumn(input) {
+    const api = getApi();
+    const coerced = coerceColumn(input.column);
+    if (!coerced.ok) {
+        return { ok: false, errors: coerced.errors };
+    }
+    const blueprint = { columns: [coerced.column], edges: [] };
+    const validation = validateLocalBlueprint(blueprint);
+    if (!validation.ok) {
+        return validation;
+    }
+    return api.post(`/api/v3/workflow-tables/${input.tableId}/columns`, {
+        id: coerced.column.id,
+        name: coerced.column.name,
+        columnType: coerced.column.type,
+        config: coerced.column.config,
+        inputMapping: coerced.column.inputMapping,
+        runCondition: coerced.column.runCondition,
+        validateOnly: input.validateOnly ?? false,
+    });
+}

package/dist/tools/bootstrap.d.ts

@@ -0,0 +1,64 @@
+import { type AuthStatus } from "./auth.js";
+import { getCampaignContext } from "./context.js";
+import { getCampaignFramework } from "./framework.js";
+import { type ListSubskillPromptsResponse, type SubskillPromptResponse } from "./prompts.js";
+type BootstrapCreateCampaignInput = {
+    campaignId?: string;
+    flowVersion?: "v1" | "v2";
+    includeTableCheck?: boolean;
+    refreshContext?: boolean;
+};
+type BootstrapCheck = {
+    key: "auth" | "framework" | "resume_context" | "subskill_catalog" | "create_campaign_subskill";
+    ok: boolean;
+    blocking: boolean;
+    detail: string;
+};
+type BootstrapBlockingError = {
+    check: BootstrapCheck["key"];
+    message: string;
+    guidance: string;
+};
+type BootstrapCreateCampaignResult = {
+    requiredChecks: BootstrapCheck[];
+    blockingErrors: BootstrapBlockingError[];
+    resumeDetected: boolean;
+    nextStep: string;
+    safeToProceed: boolean;
+    flowVersion: "v1" | "v2";
+    campaignId: string | null;
+    auth: AuthStatus | null;
+    framework: ReturnType<typeof getCampaignFramework> | null;
+    campaignContext: Awaited<ReturnType<typeof getCampaignContext>> | null;
+    subskillCatalog: ListSubskillPromptsResponse | null;
+    createCampaignSubskill: Omit<SubskillPromptResponse, "prompt"> | null;
+};
+export declare const bootstrapToolDefinitions: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            campaignId: {
+                type: string;
+                description: string;
+            };
+            flowVersion: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            includeTableCheck: {
+                type: string;
+                description: string;
+            };
+            refreshContext: {
+                type: string;
+                description: string;
+            };
+        };
+        additionalProperties: boolean;
+    };
+}[];
+export declare function bootstrapCreateCampaign(input?: BootstrapCreateCampaignInput): Promise<BootstrapCreateCampaignResult>;
+export {};