@sellable/mcp 0.1.318 → 0.1.320

package/dist/tools/inbox.js

@@ -0,0 +1,576 @@
+import { createHash } from "node:crypto";
+import { getApi, SellableApiError } from "../api.js";
+const snapshotSchema = {
+    type: "object",
+    properties: {
+        latestMessageTimestamp: { type: ["string", "null"] },
+        lastInboundMessageAt: { type: ["string", "null"] },
+        updatedAt: { type: ["string", "null"] },
+        reasonCodes: { type: "array", items: { type: "string" } },
+    },
+    additionalProperties: false,
+};
+const resultOutputSchema = {
+    type: "object",
+    additionalProperties: true,
+};
+export const inboxToolDefinitions = [
+    {
+        name: "search_inbox_threads",
+        description: "Search LinkedIn inbox threads using the existing Sellable product inbox route. This calls GET /api/v3/inbox and returns thread summaries for the active workspace.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", minimum: 1, maximum: 50 },
+                cursor: { type: "string" },
+                filter: { type: "string", enum: ["all", "drafts"] },
+                status: {
+                    type: "string",
+                    enum: ["all", "unread", "replied", "awaiting"],
+                },
+                senderId: { type: "string" },
+                classification: { type: "string" },
+                search: { type: "string" },
+                includeEnrichment: { type: "boolean" },
+                includeReplyEligibility: { type: "boolean" },
+            },
+            required: [],
+            additionalProperties: false,
+        },
+        outputSchema: resultOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "get_inbox_thread",
+        description: "Fetch one LinkedIn inbox thread using the existing Sellable product route GET /api/v3/inbox/[threadId]. Returns the product payload plus a chronological transcript for MCP review.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                threadId: { type: "string" },
+            },
+            required: ["threadId"],
+            additionalProperties: false,
+        },
+        outputSchema: resultOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "check_inbox_reply_eligibility",
+        description: "Load one inbox thread with includeReplyEligibility=true through GET /api/v3/inbox/[threadId] and return the product-computed reply eligibility snapshot.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                threadId: { type: "string" },
+            },
+            required: ["threadId"],
+            additionalProperties: false,
+        },
+        outputSchema: resultOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "update_inbox_draft",
+        description: "Edit an existing inbox draft through PATCH /api/v3/inbox/[threadId]/draft, then re-fetch the thread and return an approval-required persisted draft snapshot. This does not create a new draft.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                threadId: { type: "string" },
+                versionId: { type: "string" },
+                body: { type: "string" },
+            },
+            required: ["threadId", "versionId", "body"],
+            additionalProperties: false,
+        },
+        outputSchema: resultOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: false,
+            idempotentHint: false,
+        },
+    },
+    {
+        name: "send_inbox_draft",
+        description: "Send the currently approved existing inbox draft through POST /api/v3/inbox/[threadId]/send after validating the exact approved body hash, draft version, idempotency key, and thread snapshot. No inline body is sent.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                threadId: { type: "string" },
+                versionId: { type: "string" },
+                approvedBody: { type: "string" },
+                approvedBodyHash: { type: "string" },
+                approvedThreadSnapshot: snapshotSchema,
+                idempotencyKey: { type: "string" },
+                approval: { type: "string", enum: ["approved"] },
+            },
+            required: [
+                "threadId",
+                "versionId",
+                "approvedBody",
+                "approvedBodyHash",
+                "approvedThreadSnapshot",
+                "idempotencyKey",
+                "approval",
+            ],
+            additionalProperties: false,
+        },
+        outputSchema: resultOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+            idempotentHint: false,
+        },
+    },
+    {
+        name: "send_inbox_manual_reply",
+        description: "Send one exact operator-approved manual reply through POST /api/v3/inbox/[threadId]/reply after validating the message hash, idempotency key, and thread snapshot. Batch sends are not supported.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                threadId: { type: "string" },
+                message: { type: "string" },
+                approvedMessageHash: { type: "string" },
+                approvedThreadSnapshot: snapshotSchema,
+                idempotencyKey: { type: "string" },
+                approval: { type: "string", enum: ["approved"] },
+            },
+            required: [
+                "threadId",
+                "message",
+                "approvedMessageHash",
+                "approvedThreadSnapshot",
+                "idempotencyKey",
+                "approval",
+            ],
+            additionalProperties: false,
+        },
+        outputSchema: resultOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+            idempotentHint: false,
+        },
+    },
+];
+function hashText(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function textResult(structuredContent, text, isError = false) {
+    return {
+        structuredContent,
+        content: [{ type: "text", text }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+function errorResult(error, message, extra = {}) {
+    return textResult({ ok: false, error, message, ...extra }, message, true);
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        return errorResult("invalid_arguments", `${field} is required.`);
+    }
+    return value.trim();
+}
+function requireStrings(input, fields) {
+    const values = {};
+    for (const field of fields) {
+        const value = requireString(input[field], field);
+        if (typeof value !== "string") {
+            return { ok: false, result: value };
+        }
+        values[field] = value;
+    }
+    return { ok: true, values };
+}
+function normalizeTimestamp(value) {
+    if (value == null)
+        return null;
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === "string")
+        return value;
+    return String(value);
+}
+function getThread(response) {
+    return response.thread ?? null;
+}
+function getDraft(thread) {
+    return thread?.draft ?? null;
+}
+function getDraftVersionId(draft) {
+    return typeof draft?.id === "string"
+        ? draft.id
+        : typeof draft?.versionId === "string"
+            ? draft.versionId
+            : null;
+}
+function buildThreadSnapshot(thread) {
+    const reasonCodes = Array.isArray(thread?.replyEligibility?.reasonCodes)
+        ? thread.replyEligibility.reasonCodes
+        : [];
+    return {
+        latestMessageTimestamp: normalizeTimestamp(thread?.latestMessageTimestamp),
+        lastInboundMessageAt: normalizeTimestamp(thread?.lastInboundMessageAt),
+        updatedAt: normalizeTimestamp(thread?.updatedAt),
+        reasonCodes,
+    };
+}
+function snapshotsMatch(current, approved) {
+    if (!approved || typeof approved !== "object")
+        return false;
+    const snapshot = approved;
+    return (current.latestMessageTimestamp ===
+        (snapshot.latestMessageTimestamp ?? null) &&
+        current.lastInboundMessageAt === (snapshot.lastInboundMessageAt ?? null));
+}
+function chronologicalTranscript(thread) {
+    const messages = Array.isArray(thread?.messages) ? thread.messages : [];
+    return [...messages].sort((a, b) => {
+        const aTime = new Date(normalizeTimestamp(a.timestamp) ?? 0).getTime();
+        const bTime = new Date(normalizeTimestamp(b.timestamp) ?? 0).getTime();
+        return aTime - bTime;
+    });
+}
+function routeError(error, fallback) {
+    if (error instanceof SellableApiError) {
+        let parsed = null;
+        try {
+            parsed = JSON.parse(error.body);
+        }
+        catch {
+            parsed = error.body;
+        }
+        return errorResult(fallback, error.message, {
+            status: error.status,
+            productError: parsed,
+        });
+    }
+    const message = error instanceof Error ? error.message : fallback;
+    return errorResult(fallback, message);
+}
+function appendParam(params, key, value) {
+    if (value === undefined || value === null || value === "")
+        return;
+    params.set(key, String(value));
+}
+export async function searchInboxThreads(input) {
+    const params = new URLSearchParams();
+    const limit = typeof input.limit === "number" && Number.isFinite(input.limit)
+        ? Math.max(1, Math.min(Math.trunc(input.limit), 50))
+        : undefined;
+    appendParam(params, "limit", limit);
+    appendParam(params, "cursor", input.cursor);
+    appendParam(params, "filter", input.filter);
+    appendParam(params, "status", input.status);
+    appendParam(params, "senderId", input.senderId);
+    appendParam(params, "classification", input.classification);
+    appendParam(params, "search", input.search);
+    if (typeof input.includeEnrichment === "boolean") {
+        params.set("includeEnrichment", String(input.includeEnrichment));
+    }
+    if (typeof input.includeReplyEligibility === "boolean") {
+        params.set("includeReplyEligibility", String(input.includeReplyEligibility));
+    }
+    const query = params.toString();
+    const routeCalled = `/api/v3/inbox${query ? `?${query}` : ""}`;
+    const response = await getApi().get(routeCalled);
+    const threads = Array.isArray(response.threads) ? response.threads : [];
+    return textResult({
+        routeCalled,
+        ...response,
+    }, `${threads.length} inbox thread${threads.length === 1 ? "" : "s"} returned.`);
+}
+export async function getInboxThread(input) {
+    const required = requireStrings(input, ["threadId"]);
+    if (!required.ok)
+        return required.result;
+    const { threadId } = required.values;
+    const routeCalled = `/api/v3/inbox/${encodeURIComponent(threadId)}`;
+    const response = await getApi().get(routeCalled);
+    const thread = getThread(response);
+    return textResult({
+        routeCalled,
+        thread,
+        messageOrder: thread?.messageOrder ?? "route_order",
+        chronologicalTranscript: chronologicalTranscript(thread),
+    }, thread
+        ? `Loaded inbox thread ${thread.id ?? threadId}.`
+        : `Loaded inbox thread ${threadId}.`);
+}
+export async function checkInboxReplyEligibility(input) {
+    const required = requireStrings(input, ["threadId"]);
+    if (!required.ok)
+        return required.result;
+    const { threadId } = required.values;
+    const routeCalled = `/api/v3/inbox/${encodeURIComponent(threadId)}?includeReplyEligibility=true`;
+    const response = await getApi().get(routeCalled);
+    const thread = getThread(response);
+    if (!thread?.replyEligibility) {
+        return errorResult("reply_eligibility_missing", "Product inbox detail response did not include replyEligibility.", { routeCalled, threadId });
+    }
+    return textResult({
+        routeCalled,
+        threadId,
+        replyEligibility: thread.replyEligibility,
+        draftSnapshot: thread.draft
+            ? {
+                threadId,
+                versionId: getDraftVersionId(thread.draft),
+                body: thread.draft.body,
+                bodyHash: typeof thread.draft.body === "string"
+                    ? hashText(thread.draft.body)
+                    : null,
+                versionNumber: thread.draft.versionNumber ?? null,
+            }
+            : null,
+        threadSnapshot: buildThreadSnapshot(thread),
+    }, `Eligibility loaded for inbox thread ${threadId}.`);
+}
+export async function updateInboxDraft(input) {
+    const required = requireStrings(input, ["threadId", "versionId", "body"]);
+    if (!required.ok)
+        return required.result;
+    const { threadId, versionId, body } = required.values;
+    const bodyHash = hashText(body);
+    const routeCalled = `/api/v3/inbox/${encodeURIComponent(threadId)}/draft`;
+    try {
+        const patchResponse = await getApi().patch(routeCalled, {
+            versionId,
+            body,
+            mcpApproval: {
+                toolName: "update_inbox_draft",
+                threadId,
+                versionId,
+                bodyHash,
+            },
+        });
+        const detail = await getApi().get(`/api/v3/inbox/${encodeURIComponent(threadId)}`);
+        const thread = getThread(detail);
+        const draft = getDraft(thread);
+        const currentVersionId = getDraftVersionId(draft);
+        const returnedVersionId = typeof patchResponse.versionId === "string"
+            ? patchResponse.versionId
+            : currentVersionId;
+        const returnedBody = typeof patchResponse.body === "string" ? patchResponse.body : null;
+        const currentBody = typeof draft?.body === "string" ? draft.body : null;
+        if (!returnedVersionId || !returnedBody) {
+            return errorResult("persisted_draft_snapshot_missing", "Could not verify the persisted edited draft after PATCH.", { routeCalled, threadId, versionId: returnedVersionId ?? null });
+        }
+        if (!draft || returnedVersionId !== currentVersionId) {
+            return textResult({
+                routeCalled,
+                approvalRequired: false,
+                status: "applied_but_superseded",
+                threadId,
+                versionId: returnedVersionId,
+                appliedDraftSnapshot: {
+                    threadId,
+                    versionId: returnedVersionId,
+                    versionNumber: patchResponse.versionNumber ?? null,
+                    body: returnedBody,
+                    bodyHash: hashText(returnedBody),
+                    bodyLength: returnedBody.length,
+                    routeCalled,
+                    snapshotAt: new Date().toISOString(),
+                },
+                currentDraftSnapshot: draft && currentVersionId && currentBody
+                    ? {
+                        threadId,
+                        versionId: currentVersionId,
+                        versionNumber: draft.versionNumber ?? null,
+                        body: currentBody,
+                        bodyHash: hashText(currentBody),
+                        bodyLength: currentBody.length,
+                    }
+                    : null,
+                threadSnapshot: buildThreadSnapshot(thread),
+            }, `Edited inbox draft ${returnedVersionId}, but a newer draft is now current. Re-load before approving send.`);
+        }
+        if (!currentBody ||
+            currentBody !== body ||
+            hashText(currentBody) !== bodyHash) {
+            return errorResult("persisted_draft_body_mismatch", "Persisted edited draft did not match the requested body.", { routeCalled, threadId, versionId: currentVersionId });
+        }
+        return textResult({
+            routeCalled,
+            approvalRequired: true,
+            threadId,
+            versionId: currentVersionId,
+            versionNumber: draft.versionNumber ?? patchResponse.versionNumber ?? null,
+            draftSnapshot: {
+                threadId,
+                versionId: currentVersionId,
+                versionNumber: draft.versionNumber ?? patchResponse.versionNumber ?? null,
+                body: currentBody,
+                bodyHash,
+                bodyLength: currentBody.length,
+                routeCalled,
+                snapshotAt: new Date().toISOString(),
+            },
+            threadSnapshot: buildThreadSnapshot(thread),
+        }, `Edited inbox draft ${currentVersionId}; approval is required before send.`);
+    }
+    catch (error) {
+        return routeError(error, "update_inbox_draft_failed");
+    }
+}
+function hasAnyKey(input, keys) {
+    return keys.some((key) => Object.prototype.hasOwnProperty.call(input, key));
+}
+function validateApproval(value) {
+    return value === "approved";
+}
+export async function sendInboxDraft(input) {
+    const required = requireStrings(input, [
+        "threadId",
+        "versionId",
+        "approvedBody",
+        "approvedBodyHash",
+        "idempotencyKey",
+    ]);
+    if (!required.ok)
+        return required.result;
+    const { threadId, versionId, approvedBody, approvedBodyHash, idempotencyKey, } = required.values;
+    if (!validateApproval(input.approval)) {
+        return errorResult("approval_required", "approval must be approved.");
+    }
+    if (hashText(approvedBody) !== approvedBodyHash) {
+        return errorResult("approved_body_hash_mismatch", "approvedBodyHash does not match approvedBody.");
+    }
+    const detailRoute = `/api/v3/inbox/${encodeURIComponent(threadId)}?includeReplyEligibility=true`;
+    const detail = await getApi().get(detailRoute);
+    const thread = getThread(detail);
+    const draft = getDraft(thread);
+    const currentVersionId = getDraftVersionId(draft);
+    if (!thread?.replyEligibility) {
+        return errorResult("reply_eligibility_missing", "Product inbox detail response did not include replyEligibility.", { routeCalled: detailRoute, threadId });
+    }
+    if (!snapshotsMatch(buildThreadSnapshot(thread), input.approvedThreadSnapshot)) {
+        return errorResult("stale_thread_snapshot", "Thread changed after approval; re-check eligibility before sending.", { routeCalled: detailRoute, threadId });
+    }
+    if (currentVersionId !== versionId) {
+        return errorResult("stale_draft_snapshot", "Current draft version does not match the approved version.", { threadId, versionId, currentVersionId });
+    }
+    if (typeof draft?.body !== "string" ||
+        hashText(draft.body) !== approvedBodyHash) {
+        return errorResult("approved_body_mismatch", "Current draft body does not match the approved body hash.", { threadId, versionId });
+    }
+    if (thread.replyEligibility.canSendDraft !== true) {
+        return errorResult("send_not_eligible", "Product eligibility blocks draft send.", {
+            threadId,
+            reasonCodes: thread.replyEligibility.reasonCodes ?? [],
+            replyEligibility: thread.replyEligibility,
+        });
+    }
+    const routeCalled = `/api/v3/inbox/${encodeURIComponent(threadId)}/send`;
+    try {
+        const response = await getApi().post(routeCalled, {
+            idempotencyKey,
+            mcpApproval: {
+                toolName: "send_inbox_draft",
+                threadId,
+                versionId,
+                approvedBodyHash,
+                approvedThreadSnapshot: input.approvedThreadSnapshot,
+                approval: "approved",
+            },
+        });
+        return textResult({
+            routeCalled,
+            threadId,
+            versionId,
+            idempotencyKey,
+            approvedBodyHash,
+            ...response,
+        }, response.success === false
+            ? `Draft send did not complete for thread ${threadId}.`
+            : `Draft send submitted for thread ${threadId}.`, response.success === false);
+    }
+    catch (error) {
+        return routeError(error, "send_inbox_draft_failed");
+    }
+}
+export async function sendInboxManualReply(input) {
+    if (hasAnyKey(input, [
+        "mode",
+        "filter",
+        "filters",
+        "search",
+        "limit",
+        "threadIds",
+        "messages",
+    ])) {
+        return errorResult("batch_manual_reply_not_supported", "send_inbox_manual_reply supports one exact approved message for one thread.");
+    }
+    const required = requireStrings(input, [
+        "threadId",
+        "message",
+        "approvedMessageHash",
+        "idempotencyKey",
+    ]);
+    if (!required.ok)
+        return required.result;
+    const { threadId, message, approvedMessageHash, idempotencyKey } = required.values;
+    if (!validateApproval(input.approval)) {
+        return errorResult("approval_required", "approval must be approved.");
+    }
+    if (hashText(message) !== approvedMessageHash) {
+        return errorResult("approved_message_hash_mismatch", "approvedMessageHash does not match message.");
+    }
+    const detailRoute = `/api/v3/inbox/${encodeURIComponent(threadId)}?includeReplyEligibility=true`;
+    const detail = await getApi().get(detailRoute);
+    const thread = getThread(detail);
+    if (!thread?.replyEligibility) {
+        return errorResult("reply_eligibility_missing", "Product inbox detail response did not include replyEligibility.", { routeCalled: detailRoute, threadId });
+    }
+    if (!snapshotsMatch(buildThreadSnapshot(thread), input.approvedThreadSnapshot)) {
+        return errorResult("stale_thread_snapshot", "Thread changed after approval; re-check eligibility before sending.", { routeCalled: detailRoute, threadId });
+    }
+    if (thread.replyEligibility.canSendManual !== true) {
+        return errorResult("send_not_eligible", "Product eligibility blocks manual reply.", {
+            threadId,
+            reasonCodes: thread.replyEligibility.reasonCodes ?? [],
+            replyEligibility: thread.replyEligibility,
+        });
+    }
+    const routeCalled = `/api/v3/inbox/${encodeURIComponent(threadId)}/reply`;
+    try {
+        const response = await getApi().post(routeCalled, {
+            message,
+            idempotencyKey,
+            mcpApproval: {
+                toolName: "send_inbox_manual_reply",
+                threadId,
+                messageHash: approvedMessageHash,
+                approvedThreadSnapshot: input.approvedThreadSnapshot,
+                approval: "approved",
+            },
+        });
+        return textResult({
+            routeCalled,
+            threadId,
+            idempotencyKey,
+            messageHash: approvedMessageHash,
+            ...response,
+        }, response.success === false
+            ? `Manual reply did not complete for thread ${threadId}.`
+            : `Manual reply submitted for thread ${threadId}.`, response.success === false);
+    }
+    catch (error) {
+        return routeError(error, "send_inbox_manual_reply_failed");
+    }
+}