@webbula/mcp 1.0.0

package/dist/tools/persona-append.js

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { WEBBULA_PERSONA_DEFAULT_SCOPE } from "../config.js";
+import { toToolError } from "./errors.js";
+/** The PII attributes that can serve as a match key (at least one required). */
+export const APPEND_MATCH_KEYS = [
+    "first_name",
+    "last_name",
+    "email",
+    "address",
+    "city",
+    "state",
+    "zip5",
+    "phone",
+];
+/** Zod raw shape shared by all four append tools (validated before any call). */
+export const appendInputShape = {
+    first_name: z.string().optional().describe("Contact's given name."),
+    last_name: z.string().optional().describe("Contact's family name."),
+    email: z.string().email().optional().describe("Known email address, if any."),
+    address: z.string().optional().describe("Street address line."),
+    city: z.string().optional().describe("City."),
+    state: z.string().optional().describe("State (2-letter or full)."),
+    zip5: z.string().optional().describe("5-digit ZIP code."),
+    phone: z.string().optional().describe("Known phone number, if any."),
+    scope: z
+        .enum(["individual", "household", "both"])
+        .optional()
+        .describe("Identity-resolution scope: 'individual', 'household', or 'both'. " +
+        "Defaults to the server's configured scope ('both')."),
+};
+/** Reshape a persona response into the agent-facing result (no fabrication). */
+export function toAppendResult(filter, scope, response) {
+    const data = response.data;
+    const matched = response.status === "success" &&
+        data !== undefined &&
+        Object.keys(data).length > 0;
+    const result = { filter, scope, matched };
+    if (matched && data !== undefined)
+        result.data = data;
+    return result;
+}
+/** The four append tools (CSV rows 22–25). */
+export const APPEND_TOOLS = [
+    {
+        name: "append_email",
+        title: "Append an email address",
+        filter: "Email",
+        description: "Append an email address to a contact using Webbula's identity resolution. " +
+            "Use when the record has a name and/or postal address but no email and you " +
+            "want to find one. Do not use if an email is already present — use verify_email " +
+            "instead. Provide at least one identifying attribute (name, address, or phone).",
+    },
+    {
+        name: "append_telephone",
+        title: "Append a phone number",
+        filter: "Telephone",
+        description: "Append a phone number (and line type) to a contact using identity resolution. " +
+            "Use when the record has a name and/or address but no phone number. Provide at " +
+            "least one identifying attribute (name, address, or email).",
+    },
+    {
+        name: "append_postal",
+        title: "Append a postal address",
+        filter: "Postal",
+        description: "Append a full postal address (address, city, state, ZIP) to a contact using " +
+            "identity resolution. Use when the record has a name and/or email but no mailing " +
+            "address. Provide at least one identifying attribute (name, email, or phone).",
+    },
+    {
+        name: "append_automotive",
+        title: "Append automotive data",
+        filter: "Automotive",
+        description: "Append automotive data (year, make, model) associated with a contact using " +
+            "identity resolution. Use when you want vehicle information for a known person. " +
+            "Provide at least one identifying attribute (name, address, email, or phone).",
+    },
+];
+/** Split validated input into the persona PII `record` and the resolved scope. */
+function toRequest(input) {
+    const { scope, ...record } = input;
+    const pii = {};
+    for (const key of APPEND_MATCH_KEYS) {
+        const value = record[key];
+        if (value !== undefined)
+            pii[key] = value;
+    }
+    return { scope: scope ?? WEBBULA_PERSONA_DEFAULT_SCOPE, record: pii };
+}
+/** Register all four persona append tools against the MCP server. */
+export function registerPersonaAppend(server, client) {
+    for (const spec of APPEND_TOOLS) {
+        server.registerTool(spec.name, {
+            title: spec.title,
+            description: spec.description,
+            inputSchema: appendInputShape,
+        }, async (input) => {
+            // At least one PII attribute must be present to resolve an identity
+            // (pre-flight, principle V — never call upstream with an empty key).
+            const hasKey = APPEND_MATCH_KEYS.some((key) => input[key] !== undefined);
+            if (!hasKey) {
+                return toToolError(new Error("At least one identifying attribute is required " +
+                    "(name, email, postal address, or phone)."));
+            }
+            try {
+                const { scope, record } = toRequest(input);
+                const response = await client.personaAppend({
+                    filter: spec.filter,
+                    scope,
+                    record,
+                });
+                const result = toAppendResult(spec.filter, scope, response);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                    structuredContent: result,
+                };
+            }
+            catch (error) {
+                return toToolError(error);
+            }
+        });
+    }
+}
+//# sourceMappingURL=persona-append.js.map

package/dist/tools/persona-append.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persona-append.js","sourceRoot":"","sources":["../../src/tools/persona-append.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,gFAAgF;AAChF,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,YAAY;IACZ,WAAW;IACX,OAAO;IACP,SAAS;IACT,MAAM;IACN,OAAO;IACP,MAAM;IACN,OAAO;CACC,CAAC;AAEX,iFAAiF;AACjF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;IACnE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IACnE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IAC7E,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sBAAsB,CAAC;IAC/D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC;IAC7C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IAClE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IACzD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IACpE,KAAK,EAAE,CAAC;SACL,IAAI,CAAC,CAAC,YAAY,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;SACzC,QAAQ,EAAE;SACV,QAAQ,CACP,mEAAmE;QACjE,qDAAqD,CACxD;CACK,CAAC;AAmBX,gFAAgF;AAChF,MAAM,UAAU,cAAc,CAC5B,MAAqB,EACrB,KAAmB,EACnB,QAA+B;IAE/B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC3B,MAAM,OAAO,GACX,QAAQ,CAAC,MAAM,KAAK,SAAS;QAC7B,IAAI,KAAK,SAAS;QAClB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAiB,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IACxD,IAAI,OAAO,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;IACtD,OAAO,MAAM,CAAC;AAChB,CAAC;AAUD,8CAA8C;AAC9C,MAAM,CAAC,MAAM,YAAY,GAA8B;IACrD;QACE,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,yBAAyB;QAChC,MAAM,EAAE,OAAO;QACf,WAAW,EACT,4EAA4E;YAC5E,4EAA4E;YAC5E,iFAAiF;YACjF,gFAAgF;KACnF;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,KAAK,EAAE,uBAAuB;QAC9B,MAAM,EAAE,WAAW;QACnB,WAAW,EACT,gFAAgF;YAChF,gFAAgF;YAChF,4DAA4D;KAC/D;IACD;QACE,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,yBAAyB;QAChC,MAAM,EAAE,QAAQ;QAChB,WAAW,EACT,8EAA8E;YAC9E,kFAAkF;YAClF,8EAA8E;KACjF;IACD;QACE,IAAI,EAAE,mBAAmB;QACzB,KAAK,EAAE,wBAAwB;QAC/B,MAAM,EAAE,YAAY;QACpB,WAAW,EACT,6EAA6E;YAC7E,iFAAiF;YACjF,8EAA8E;KACjF;CACO,CAAC;AAEX,kFAAkF;AAClF,SAAS,SAAS,CAAC,KAAkB;IAInC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,EAAE,GAAG,KAAK,CAAC;IACnC,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,KAAK,KAAK,SAAS;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC5C,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,IAAI,6BAA6B,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AACxE,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,qBAAqB,CACnC,MAAiB,EACjB,MAAqB;IAErB,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;YACE,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,gBAAgB;SAC9B,EACD,KAAK,EAAE,KAAK,EAAE,EAAE;YACd,oEAAoE;YACpE,qEAAqE;YACrE,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CACnC,CAAC,GAAG,EAAE,EAAE,CAAE,KAAqB,CAAC,GAAG,CAAC,KAAK,SAAS,CACnD,CAAC;YACF,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,OAAO,WAAW,CAChB,IAAI,KAAK,CACP,iDAAiD;oBAC/C,0CAA0C,CAC7C,CACF,CAAC;YACJ,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC,KAAoB,CAAC,CAAC;gBAC1D,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC;oBAC1C,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,KAAK;oBACL,MAAM;iBACP,CAAC,CAAC;gBACH,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;gBAC5D,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;oBAClE,iBAAiB,EAAE,MAA4C;iBAChE,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/tools/register.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Transport-agnostic tool registration (constitution principle IV).
+ *
+ * Both `server/stdio.ts` and `server/http.ts` call `registerTools()` with a
+ * freshly-built `McpServer` and a shared `WebbulaClient`, so the exposed tool set
+ * is identical across transports. Each tool lives in its own module and is wired
+ * in below.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { WebbulaClient } from "../api/webbula-client.js";
+/**
+ * Register every Webbula MCP tool against `server`, using `client` as the single
+ * HTTP boundary to the Webbula API.
+ */
+export declare function registerTools(server: McpServer, client: WebbulaClient): void;

package/dist/tools/register.js

@@ -0,0 +1,23 @@
+import { registerDownloadResults } from "./download-results.js";
+import { registerFileStatus } from "./file-status.js";
+import { registerGetCredits } from "./get-credits.js";
+import { registerHygieneCheck } from "./hygiene-check.js";
+import { registerPersonaAppend } from "./persona-append.js";
+import { registerUploadFile } from "./upload-file.js";
+import { registerValidateLead } from "./validate-lead.js";
+import { registerVerifyEmail } from "./verify-email.js";
+/**
+ * Register every Webbula MCP tool against `server`, using `client` as the single
+ * HTTP boundary to the Webbula API.
+ */
+export function registerTools(server, client) {
+    registerVerifyEmail(server, client); // 001 US1
+    registerHygieneCheck(server, client); // 001 US2
+    registerGetCredits(server, client); // 001 US3
+    registerValidateLead(server, client); // 002 lead validation
+    registerUploadFile(server, client); // 003 US1 batch submit
+    registerFileStatus(server, client); // 003 US2 batch status
+    registerDownloadResults(server, client); // 003 US3 batch download
+    registerPersonaAppend(server, client); // 006 persona data append (4 tools)
+}
+//# sourceMappingURL=register.js.map

package/dist/tools/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/tools/register.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAiB,EAAE,MAAqB;IACpE,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU;IAC/C,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU;IAChD,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU;IAC9C,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,sBAAsB;IAC5D,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,uBAAuB;IAC3D,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,uBAAuB;IAC3D,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,yBAAyB;IAClE,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,oCAAoC;AAC7E,CAAC"}

package/dist/tools/upload-file.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `upload_file` — submit a file for asynchronous batch hygiene (spec 003 US1).
+ * Maps to `POST /api/v5/task/run` and returns a `package_name` to track the task
+ * (contracts/upload_file.md).
+ *
+ * The file is supplied EITHER inline (base64 + filename, JSON `file_base64` mode)
+ * OR as a remote `data_source` (web/ftp/ssh) — never a local filesystem path, so
+ * both transports behave identically (FR-002, constitution IV). The extension and
+ * the inline-size limit are validated before any upstream call (FR-003).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { BatchRunResponse } from "../api/types.js";
+import { type BatchRunParams, type WebbulaClient } from "../api/webbula-client.js";
+export declare const UPLOAD_FILE_NAME = "upload_file";
+export declare const UPLOAD_FILE_DESCRIPTION: string;
+/** Accepted upload file extensions (FR-003). */
+export declare const ALLOWED_UPLOAD_EXTENSIONS: readonly [".csv", ".txt", ".xlsx", ".xls"];
+export declare const uploadFileInputShape: {
+    readonly profile: z.ZodOptional<z.ZodString>;
+    readonly content_base64: z.ZodOptional<z.ZodString>;
+    readonly filename: z.ZodOptional<z.ZodString>;
+    readonly data_source: z.ZodOptional<z.ZodEnum<["web", "ftp", "ssh"]>>;
+    readonly url: z.ZodOptional<z.ZodString>;
+    readonly host: z.ZodOptional<z.ZodString>;
+    readonly port: z.ZodOptional<z.ZodNumber>;
+    readonly username: z.ZodOptional<z.ZodString>;
+    readonly password: z.ZodOptional<z.ZodString>;
+    readonly path: z.ZodOptional<z.ZodString>;
+    readonly secure: z.ZodOptional<z.ZodBoolean>;
+};
+export type UploadFileInput = {
+    profile?: string;
+    content_base64?: string;
+    filename?: string;
+    data_source?: "web" | "ftp" | "ssh";
+    url?: string;
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    path?: string;
+    secure?: boolean;
+};
+export interface BatchSubmissionResult {
+    package_name: string;
+    transaction?: string;
+}
+/**
+ * Validate the one-of input rule + the extension/size limits, and build the
+ * client params. Throws a structured `validation` error before any upstream call
+ * (FR-001/FR-003). Exported for contract testing.
+ */
+export declare function buildBatchRunParams(input: UploadFileInput): BatchRunParams;
+/** Reshape the upstream `BatchRunResponse` into the agent-facing handle. */
+export declare function toBatchSubmissionResult(response: BatchRunResponse): BatchSubmissionResult;
+/** Register `upload_file` against the MCP server. */
+export declare function registerUploadFile(server: McpServer, client: WebbulaClient): void;

package/dist/tools/upload-file.js

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import { WebbulaApiError, } from "../api/webbula-client.js";
+import { WEBBULA_BATCH_PROFILE, WEBBULA_MAX_INLINE_BYTES } from "../config.js";
+import { toToolError } from "./errors.js";
+export const UPLOAD_FILE_NAME = "upload_file";
+export const UPLOAD_FILE_DESCRIPTION = "Submit a file of emails for asynchronous batch hygiene when the list is too " +
+    "large for the real-time tools. Provide the file inline (base64 + filename) or " +
+    "point at a remote source (web URL, FTP, or SSH). Returns a package_name to " +
+    "track with file_status and fetch with download_results. Accepts .csv, .txt, " +
+    ".xlsx, .xls. Local filesystem paths are not supported.";
+/** Accepted upload file extensions (FR-003). */
+export const ALLOWED_UPLOAD_EXTENSIONS = [".csv", ".txt", ".xlsx", ".xls"];
+export const uploadFileInputShape = {
+    profile: z
+        .string()
+        .optional()
+        .describe("Optional Webbula profile name. Defaults to the server's configured profile."),
+    content_base64: z
+        .string()
+        .optional()
+        .describe("Base64-encoded file content (≤ ~1 MiB). Use with `filename`."),
+    filename: z
+        .string()
+        .optional()
+        .describe("File name (with a .csv/.txt/.xlsx/.xls extension). Required with `content_base64`."),
+    data_source: z
+        .enum(["web", "ftp", "ssh"])
+        .optional()
+        .describe("Remote source type, as an alternative to inline content."),
+    url: z.string().url().optional().describe("Source URL (when `data_source` is `web`)."),
+    host: z.string().optional().describe("FTP/SSH host."),
+    port: z.number().int().optional().describe("FTP/SSH port."),
+    username: z.string().optional().describe("FTP/SSH username."),
+    password: z.string().optional().describe("FTP/SSH password."),
+    path: z.string().optional().describe("FTP/SSH remote file path."),
+    secure: z.boolean().optional().describe("Use TLS (SFTP) for the FTP source."),
+};
+function hasAllowedExtension(filename) {
+    const lower = filename.toLowerCase();
+    return ALLOWED_UPLOAD_EXTENSIONS.some((ext) => lower.endsWith(ext));
+}
+/**
+ * Validate the one-of input rule + the extension/size limits, and build the
+ * client params. Throws a structured `validation` error before any upstream call
+ * (FR-001/FR-003). Exported for contract testing.
+ */
+export function buildBatchRunParams(input) {
+    const hasInline = input.content_base64 !== undefined || input.filename !== undefined;
+    const hasSource = input.data_source !== undefined;
+    if (hasInline && hasSource) {
+        throw new WebbulaApiError("validation", "Provide either content_base64+filename or a data_source, not both");
+    }
+    if (!hasInline && !hasSource) {
+        throw new WebbulaApiError("validation", "Provide either content_base64+filename or a data_source");
+    }
+    const profile = input.profile ?? WEBBULA_BATCH_PROFILE;
+    if (hasInline) {
+        if (input.content_base64 === undefined || input.filename === undefined) {
+            throw new WebbulaApiError("validation", "Inline upload requires both content_base64 and filename");
+        }
+        if (!hasAllowedExtension(input.filename)) {
+            throw new WebbulaApiError("validation", "Unsupported file type — use .csv, .txt, .xlsx, or .xls");
+        }
+        const decodedBytes = Buffer.from(input.content_base64, "base64").length;
+        if (decodedBytes > WEBBULA_MAX_INLINE_BYTES) {
+            throw new WebbulaApiError("validation", `Inline file exceeds the ~${Math.round(WEBBULA_MAX_INLINE_BYTES / 1_048_576)} MiB limit — use a data_source`);
+        }
+        return {
+            profile,
+            inline: { filename: input.filename, content_base64: input.content_base64 },
+        };
+    }
+    // Remote data source.
+    return {
+        profile,
+        dataSource: {
+            data_source: input.data_source,
+            url: input.url,
+            host: input.host,
+            port: input.port,
+            username: input.username,
+            password: input.password,
+            path: input.path,
+            secure: input.secure,
+        },
+    };
+}
+/** Reshape the upstream `BatchRunResponse` into the agent-facing handle. */
+export function toBatchSubmissionResult(response) {
+    if (typeof response.package_name !== "string" || response.package_name === "") {
+        throw new WebbulaApiError("upstream", "Webbula accepted the task but returned no package_name");
+    }
+    const out = { package_name: response.package_name };
+    if (typeof response.transaction === "string")
+        out.transaction = response.transaction;
+    return out;
+}
+/** Register `upload_file` against the MCP server. */
+export function registerUploadFile(server, client) {
+    server.registerTool(UPLOAD_FILE_NAME, {
+        title: "Submit a batch file",
+        description: UPLOAD_FILE_DESCRIPTION,
+        inputSchema: uploadFileInputShape,
+    }, async (input) => {
+        try {
+            const params = buildBatchRunParams(input);
+            const response = await client.runBatch(params);
+            const result = toBatchSubmissionResult(response);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+}
+//# sourceMappingURL=upload-file.js.map

package/dist/tools/upload-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-file.js","sourceRoot":"","sources":["../../src/tools/upload-file.ts"],"names":[],"mappings":"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"}

package/dist/tools/validate-lead.d.ts

@@ -0,0 +1,102 @@
+/**
+ * `validate_lead` — assess a full lead/contact record (spec 002 US1/US2). Maps to
+ * `POST /api/v5/task/lead` and reshapes the `ExpressCompoundResponse` into one
+ * agent-facing `LeadValidationResult` (contracts/validate_lead.md).
+ *
+ * Each supplied attribute is returned as its own sub-result; any sub-result the
+ * upstream omits is absent, never fabricated (FR-003). Documented coded fields
+ * (`name.gender`, name/phone `status`, `phone.service_type`) carry the verbatim
+ * upstream code AND a human-readable label/description from the STATIC tables in
+ * `api/enums.ts` — unknown codes omit the friendly field (FR-004, principle I).
+ * `address.accuracy_score` is passed through verbatim (FR-006). When `emails` are
+ * supplied, each reuses `verify_email`'s verdict + trust shape exactly (FR-005).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { ExpressCompoundResponse } from "../api/types.js";
+import { type WebbulaClient } from "../api/webbula-client.js";
+import { type EmailVerificationResult } from "./verify-email.js";
+export declare const VALIDATE_LEAD_NAME = "validate_lead";
+export declare const VALIDATE_LEAD_DESCRIPTION: string;
+/** The lead attributes that satisfy the "at least one attribute" rule (FR-002). */
+export declare const LEAD_ATTRIBUTE_KEYS: readonly ["first_name", "last_name", "full_address", "phone", "emails"];
+/**
+ * Zod raw shape for the tool input (validated before any upstream call). The
+ * v4 `task/lead` endpoint accepts only firstname/lastname/address/phone/emails,
+ * so the complete street+city+state+ZIP goes in `full_address`.
+ */
+export declare const validateLeadInputShape: {
+    readonly profile: z.ZodOptional<z.ZodString>;
+    readonly first_name: z.ZodOptional<z.ZodString>;
+    readonly last_name: z.ZodOptional<z.ZodString>;
+    readonly full_address: z.ZodOptional<z.ZodString>;
+    readonly phone: z.ZodOptional<z.ZodString>;
+    readonly emails: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+};
+export type ValidateLeadInput = {
+    profile?: string;
+    first_name?: string;
+    last_name?: string;
+    full_address?: string;
+    phone?: string;
+    emails?: string[];
+};
+export interface NameAssessment {
+    prefix?: string;
+    first?: string;
+    middle?: string;
+    last?: string;
+    suffix?: string;
+    gender?: string;
+    gender_label?: string;
+    status?: string;
+    status_description?: string;
+}
+export interface AddressAssessment {
+    address?: string;
+    address2?: string;
+    city?: string;
+    state?: string;
+    zip5?: string;
+    lat?: number;
+    lon?: number;
+    /** Continuous percent, verbatim (FR-006 — no bucketing/rounding). */
+    accuracy_score?: string;
+}
+export interface PhoneAssessment {
+    number?: string;
+    area_code?: string;
+    prefix?: string;
+    suffix?: string;
+    service_type?: string;
+    service_type_description?: string;
+    status?: string;
+    status_description?: string;
+}
+export interface CreditScenario {
+    scenario?: string;
+    records?: string;
+}
+export interface LeadValidationResult {
+    name?: NameAssessment;
+    address?: AddressAssessment;
+    phone?: PhoneAssessment;
+    emails?: EmailVerificationResult[];
+    profile?: string;
+    transaction?: string;
+    credits_remaining?: CreditScenario[];
+}
+/**
+ * Throw a structured `validation` error when no lead attribute is supplied
+ * (FR-002). Enforced before any upstream call. Exported for contract testing.
+ */
+export declare function assertAtLeastOneAttribute(input: ValidateLeadInput): void;
+/**
+ * Reshape the upstream `ExpressCompoundResponse` into a `LeadValidationResult`.
+ * Any sub-result the upstream omits is left absent (FR-003); the email sub-result
+ * reuses `verify_email`'s verdict + trust mapping exactly (FR-005). Exported for
+ * contract testing.
+ */
+export declare function toLeadValidationResult(response: ExpressCompoundResponse): LeadValidationResult;
+/** Register `validate_lead` against the MCP server. */
+export declare function registerValidateLead(server: McpServer, client: WebbulaClient): void;

package/dist/tools/validate-lead.js

@@ -0,0 +1,192 @@
+import { z } from "zod";
+import { NAME_GENDER, NAME_STATUS, PHONE_SERVICE_TYPE, PHONE_STATUS, } from "../api/enums.js";
+import { WebbulaApiError, } from "../api/webbula-client.js";
+import { WEBBULA_LEAD_PROFILE, WEBBULA_MAX_EMAILS } from "../config.js";
+import { toVerificationResult } from "./verify-email.js";
+import { toToolError } from "./errors.js";
+export const VALIDATE_LEAD_NAME = "validate_lead";
+export const VALIDATE_LEAD_DESCRIPTION = "Validate a full lead/contact record with Webbula's leadHygiene. Parses and " +
+    "assesses any combination of name, postal address, and phone number — modeled " +
+    "gender, address accuracy and geocode, phone line type — and, when an email is " +
+    "supplied, runs the same email hygiene verdict as verify_email in the same call. " +
+    "Use this for cleaning CRM/lead records, not just an email address. At least one " +
+    "of first_name, last_name, full_address, phone, or emails is required. " +
+    "Real-time, single tool call.";
+/** The lead attributes that satisfy the "at least one attribute" rule (FR-002). */
+export const LEAD_ATTRIBUTE_KEYS = [
+    "first_name",
+    "last_name",
+    "full_address",
+    "phone",
+    "emails",
+];
+/**
+ * Zod raw shape for the tool input (validated before any upstream call). The
+ * v4 `task/lead` endpoint accepts only firstname/lastname/address/phone/emails,
+ * so the complete street+city+state+ZIP goes in `full_address`.
+ */
+export const validateLeadInputShape = {
+    profile: z
+        .string()
+        .optional()
+        .describe("Optional lead-enabled Webbula profile name. Defaults to the server's configured lead profile."),
+    first_name: z.string().optional().describe("Given name."),
+    last_name: z.string().optional().describe("Family name."),
+    full_address: z
+        .string()
+        .optional()
+        .describe("The complete address: street, city, state, and ZIP."),
+    phone: z.string().optional().describe("Phone number."),
+    emails: z
+        .array(z.string().email())
+        .max(WEBBULA_MAX_EMAILS)
+        .optional()
+        .describe(`Optional email addresses to additionally run hygiene on (max ${WEBBULA_MAX_EMAILS}).`),
+};
+/** Copy a defined string field from src→dst under the same key. */
+function copyString(src, dst, key) {
+    const value = src[key];
+    if (typeof value === "string")
+        dst[key] = value;
+}
+/**
+ * Throw a structured `validation` error when no lead attribute is supplied
+ * (FR-002). Enforced before any upstream call. Exported for contract testing.
+ */
+export function assertAtLeastOneAttribute(input) {
+    const hasAttribute = LEAD_ATTRIBUTE_KEYS.some((key) => {
+        const value = input[key];
+        return key === "emails"
+            ? Array.isArray(value) && value.length > 0
+            : value !== undefined && value !== "";
+    });
+    if (!hasAttribute) {
+        throw new WebbulaApiError("validation", "Supply at least one of: first_name, last_name, full_address, phone, ip, emails");
+    }
+}
+/** Reshape the upstream `name` sub-result, enriching coded fields (FR-004). */
+function toNameAssessment(name) {
+    const out = {};
+    const src = name;
+    const dst = out;
+    copyString(src, dst, "prefix");
+    copyString(src, dst, "first");
+    copyString(src, dst, "middle");
+    copyString(src, dst, "last");
+    copyString(src, dst, "suffix");
+    if (typeof name.gender === "string") {
+        out.gender = name.gender;
+        const info = Object.prototype.hasOwnProperty.call(NAME_GENDER, name.gender)
+            ? NAME_GENDER[name.gender]
+            : undefined;
+        if (info !== undefined)
+            out.gender_label = info.label;
+    }
+    if (typeof name.status === "string") {
+        out.status = name.status;
+        if (Object.prototype.hasOwnProperty.call(NAME_STATUS, name.status)) {
+            out.status_description = NAME_STATUS[name.status];
+        }
+    }
+    return out;
+}
+/** Reshape the upstream `address` sub-result (accuracy_score verbatim, FR-006). */
+function toAddressAssessment(address) {
+    const out = {};
+    const src = address;
+    const dst = out;
+    copyString(src, dst, "address");
+    copyString(src, dst, "address2");
+    copyString(src, dst, "city");
+    copyString(src, dst, "state");
+    copyString(src, dst, "zip5");
+    copyString(src, dst, "accuracy_score");
+    if (typeof address.lat === "number")
+        out.lat = address.lat;
+    if (typeof address.lon === "number")
+        out.lon = address.lon;
+    return out;
+}
+/** Reshape the upstream `phone` sub-result, enriching coded fields (FR-004). */
+function toPhoneAssessment(phone) {
+    const out = {};
+    const src = phone;
+    const dst = out;
+    copyString(src, dst, "number");
+    copyString(src, dst, "area_code");
+    copyString(src, dst, "prefix");
+    copyString(src, dst, "suffix");
+    if (typeof phone.service_type === "string") {
+        out.service_type = phone.service_type;
+        if (Object.prototype.hasOwnProperty.call(PHONE_SERVICE_TYPE, phone.service_type)) {
+            out.service_type_description = PHONE_SERVICE_TYPE[phone.service_type];
+        }
+    }
+    if (typeof phone.status === "string") {
+        out.status = phone.status;
+        if (Object.prototype.hasOwnProperty.call(PHONE_STATUS, phone.status)) {
+            out.status_description = PHONE_STATUS[phone.status];
+        }
+    }
+    return out;
+}
+/**
+ * Reshape the upstream `ExpressCompoundResponse` into a `LeadValidationResult`.
+ * Any sub-result the upstream omits is left absent (FR-003); the email sub-result
+ * reuses `verify_email`'s verdict + trust mapping exactly (FR-005). Exported for
+ * contract testing.
+ */
+export function toLeadValidationResult(response) {
+    const out = {};
+    if (response.name !== undefined)
+        out.name = toNameAssessment(response.name);
+    if (response.address !== undefined)
+        out.address = toAddressAssessment(response.address);
+    if (response.phone !== undefined)
+        out.phone = toPhoneAssessment(response.phone);
+    if (response.emails !== undefined && response.emails.length > 0) {
+        out.emails = response.emails.map(toVerificationResult);
+    }
+    if (typeof response.profile === "string")
+        out.profile = response.profile;
+    if (typeof response.transaction === "string")
+        out.transaction = response.transaction;
+    if (Array.isArray(response.credits_remaining)) {
+        out.credits_remaining = response.credits_remaining.map((entry) => {
+            const scenario = {};
+            if (typeof entry.scenario === "string")
+                scenario.scenario = entry.scenario;
+            if (typeof entry.records === "string")
+                scenario.records = entry.records;
+            return scenario;
+        });
+    }
+    return out;
+}
+/** Register `validate_lead` against the MCP server. */
+export function registerValidateLead(server, client) {
+    server.registerTool(VALIDATE_LEAD_NAME, {
+        title: "Validate a lead record",
+        description: VALIDATE_LEAD_DESCRIPTION,
+        inputSchema: validateLeadInputShape,
+    }, async (input) => {
+        try {
+            assertAtLeastOneAttribute(input);
+            const { profile, ...attributes } = input;
+            const params = {
+                profile: profile ?? WEBBULA_LEAD_PROFILE,
+                ...attributes,
+            };
+            const response = await client.leadValidate(params);
+            const result = toLeadValidationResult(response);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+}
+//# sourceMappingURL=validate-lead.js.map