@sellable/mcp 0.1.521 → 0.1.522

package/dist/tools/refill-executors.d.ts

@@ -5,6 +5,15 @@ export type PaidInmailRefreshAction = {
     actionKey?: string | null;
     action?: Record<string, unknown>;
 };
+export type PaidInmailCreditRefreshOptions = {
+    actionType?: string | null;
+    campaignId?: string | null;
+    tableId?: string | null;
+    columnId?: string | null;
+    threshold?: number | null;
+    maxStalenessSeconds?: number | null;
+    paidInmailCreditsMaxStalenessSeconds?: number | null;
+};
 export type YoloPrimitiveExecution = {
     enabled: true;
     status: "no_action" | "read_only_reread" | "executed_and_reread" | "refused" | "skipped_after_paid_refresh";
@@ -161,7 +170,7 @@ export declare function approveGeneratedMessagesBatch(action: Record<string, unk
     refusalReason?: undefined;
 }>;
 export declare function continueSignalDiscoverySource(action: Record<string, unknown>, workspaceId?: string): Promise<YoloPrimitiveAttempt>;
-export declare function refreshPaidInmailCreditsWithRetry(senderId: string, workspaceId: string): Promise<{
+export declare function refreshPaidInmailCreditsWithRetry(senderId: string, workspaceId: string, options?: PaidInmailCreditRefreshOptions): Promise<{
     receipt: import("./senders.js").RefreshPaidInmailCreditsResponse;
     attempts: number;
     errors: string[];

package/dist/tools/refill-executors.js

@@ -618,13 +618,14 @@ export async function continueSignalDiscoverySource(action, workspaceId) {
         },
     };
 }
-export async function refreshPaidInmailCreditsWithRetry(senderId, workspaceId) {
+export async function refreshPaidInmailCreditsWithRetry(senderId, workspaceId, options = {}) {
     const errors = [];
     for (let attempt = 1; attempt <= PAID_INMAIL_REFRESH_MAX_ATTEMPTS; attempt += 1) {
         try {
             const receipt = await refreshPaidInmailCredits({
                 senderId,
                 workspaceId,
+                ...options,
             });
             return { receipt, attempts: attempt, errors };
         }

package/dist/tools/refill-sends.js

@@ -2,6 +2,7 @@ import { actionIds, collectPaidInmailRefreshActions, executeOneYoloPrimitive, fi
 import { getRefillTargetPlan } from "./refill-target-plan.js";
 import { createWorkspaceContext, normalizeExplicitWorkspaceId, } from "./workspace-context.js";
 const DEFAULT_SCHEDULER_FORWARD_HOURS = 48;
+const MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS = 4 * 60 * 60;
 function normalizeHorizonSendDays(value) {
     if (value === undefined || value === null)
         return null;
@@ -329,6 +330,9 @@ function paidRefreshApprovalPacket(params) {
     const action = params.action.action ?? {};
     const ids = actionIds(action);
     const threshold = numberValue(action.oldThreshold) ?? numberValue(action.threshold);
+    const maxStalenessSeconds = Math.max(numberValue(action.maxStalenessSeconds) ??
+        numberValue(action.paidInmailCreditsMaxStalenessSeconds) ??
+        MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS, MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS);
     return {
         approvalSource: "explicit_yolo_flag",
         workspaceId: params.workspaceId ?? null,
@@ -339,12 +343,22 @@ function paidRefreshApprovalPacket(params) {
         tableId: stringValue(ids.tableId) ?? stringValue(action.tableId) ?? null,
         columnId: stringValue(ids.columnId) ?? stringValue(action.columnId) ?? null,
         threshold: threshold ?? null,
-        maxStalenessSeconds: numberValue(action.maxStalenessSeconds) ??
-            numberValue(action.paidInmailCreditsMaxStalenessSeconds) ??
-            null,
+        maxStalenessSeconds,
         targetPlanFingerprint: targetPlanFingerprint(params.targetPlan),
     };
 }
+function paidRefreshOptionsFromApprovalPacket(packet) {
+    return {
+        ...(packet.actionType ? { actionType: packet.actionType } : {}),
+        ...(packet.campaignId ? { campaignId: packet.campaignId } : {}),
+        ...(packet.tableId ? { tableId: packet.tableId } : {}),
+        ...(packet.columnId ? { columnId: packet.columnId } : {}),
+        ...(typeof packet.threshold === "number"
+            ? { threshold: packet.threshold }
+            : {}),
+        maxStalenessSeconds: packet.maxStalenessSeconds,
+    };
+}
 export async function executeRefillSendsCommand(input = {}) {
     const yolo = input.yolo === true;
     const executionMode = input.executionMode ?? (yolo ? "yolo" : "manual");
@@ -407,7 +421,7 @@ export async function executeRefillSendsCommand(input = {}) {
             });
             continue;
         }
-        const refreshResult = await refreshPaidInmailCreditsWithRetry(action.senderId, workspaceId);
+        const refreshResult = await refreshPaidInmailCreditsWithRetry(action.senderId, workspaceId, paidRefreshOptionsFromApprovalPacket(approvalPacket));
         if (refreshResult.receipt) {
             refreshedPaidInmailSenderIds.push(action.senderId);
             refreshReceipts.push({

package/dist/tools/refill-target-plan.js

@@ -36,6 +36,11 @@ const TERMINAL_NO_ACTION_BLOCKER_CODES = new Set([
     "paid_inmail_credit_missing",
     "paid_inmail_credit_stale",
 ]);
+const MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS = 4 * 60 * 60;
+const PAID_INMAIL_REFRESH_STATUSES = new Set([
+    "missing_credit_facts",
+    "stale_credit_facts",
+]);
 const SOURCE_PLAN_STATES = new Set([
     "not_needed",
     "use_existing_rows",
@@ -73,6 +78,9 @@ function actionTypesFrom(value) {
 function numberValue(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
+function optionalNumberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
 function stringValue(value) {
     return typeof value === "string" ? value : undefined;
 }
@@ -87,6 +95,20 @@ function numericRecord(value) {
 function campaignClassificationValue(value) {
     return value === "sales_nav_cascade" ? "sales_nav_cascade" : undefined;
 }
+function normalizePaidInmailMaxStalenessSeconds(value) {
+    const numeric = optionalNumberValue(value);
+    return numeric !== null && numeric > 0
+        ? Math.max(Math.trunc(numeric), MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS)
+        : MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS;
+}
+function isFreshWithinMcpPaidInmailWindow(checkedAt, maxStalenessSeconds) {
+    if (!checkedAt)
+        return false;
+    const checkedAtMs = new Date(checkedAt).getTime();
+    if (!Number.isFinite(checkedAtMs))
+        return false;
+    return Date.now() - checkedAtMs <= maxStalenessSeconds * 1000;
+}
 function stringArray(value) {
     if (!Array.isArray(value))
         return [];
@@ -138,7 +160,7 @@ function sanitizeCounts(counts, selectedKeys) {
         return Boolean(key && selectedKeys.has(key));
     });
 }
-function sanitizeActionCandidates(candidates, selectedKeys, status, remainingReadyOrProjectedGap, remainingProjectedGap) {
+function sanitizeActionCandidates(candidates, selectedKeys, paidRefreshNeededSenderIds, status, remainingReadyOrProjectedGap, remainingProjectedGap) {
     const filtered = Array.isArray(candidates)
         ? candidates
             .filter((item) => {
@@ -149,6 +171,13 @@ function sanitizeActionCandidates(candidates, selectedKeys, status, remainingRea
                 return false;
             }
             const actionType = item.actionType;
+            if (item.type === "refresh_paid_inmail_credits") {
+                const ids = isRecord(item.ids) ? item.ids : {};
+                const senderId = stringValue(item.senderId) ?? stringValue(ids.senderId);
+                return Boolean(senderId &&
+                    paidRefreshNeededSenderIds.has(senderId) &&
+                    selectedKeys.has(`${senderId}:send_inmail_closed`));
+            }
             if (actionType === undefined)
                 return item.type === "wait_for_scheduler";
             const allowed = allowedActionType(actionType);
@@ -532,20 +561,41 @@ function sanitizeSourcePlan(value) {
 function sanitizePaidInmail(value) {
     if (!isRecord(value))
         return null;
+    const originalMaxStalenessSeconds = optionalNumberValue(value.maxStalenessSeconds);
+    const maxStalenessSeconds = normalizePaidInmailMaxStalenessSeconds(value.maxStalenessSeconds);
+    const checkedAt = stringValue(value.checkedAt) ?? null;
+    const availableCredits = numberValue(value.availableCredits);
+    const threshold = numberValue(value.threshold);
+    let status = stringValue(value.status) ?? "missing_credit_facts";
+    let reason = stringValue(value.reason) ?? "";
+    let freshnessPolicy;
+    if (status === "stale_credit_facts" &&
+        isFreshWithinMcpPaidInmailWindow(checkedAt, maxStalenessSeconds)) {
+        status = availableCredits < threshold ? "below_threshold" : "ok";
+        reason =
+            status === "below_threshold"
+                ? "MCP normalized paid InMail freshness to 4h; cached credits are fresh enough but below threshold."
+                : "MCP normalized paid InMail freshness to 4h; cached credits are fresh enough.";
+        freshnessPolicy = {
+            normalizedBy: "mcp",
+            minMaxStalenessSeconds: MCP_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS,
+            originalMaxStalenessSeconds,
+        };
+    }
     return {
-        status: stringValue(value.status) ?? "missing_credit_facts",
-        reason: stringValue(value.reason) ?? "",
-        checkedAt: stringValue(value.checkedAt) ?? null,
+        status,
+        reason,
+        checkedAt,
         balance: typeof value.balance === "number" ? value.balance : null,
         sentSince: numberValue(value.sentSince),
-        availableCredits: numberValue(value.availableCredits),
-        threshold: numberValue(value.threshold),
+        availableCredits,
+        threshold,
         campaignId: stringValue(value.campaignId) ?? null,
         campaignName: stringValue(value.campaignName) ?? null,
         tableId: stringValue(value.tableId) ?? null,
         tableName: stringValue(value.tableName) ?? null,
         columnId: stringValue(value.columnId) ?? null,
-        maxStalenessSeconds: numberValue(value.maxStalenessSeconds),
+        maxStalenessSeconds,
         campaignClassification: campaignClassificationValue(value.campaignClassification) ?? null,
         connectionFallbackAvailable: booleanValue(value.connectionFallbackAvailable) ?? false,
         connectionFallbackCampaignId: stringValue(value.connectionFallbackCampaignId) ?? null,
@@ -553,8 +603,19 @@ function sanitizePaidInmail(value) {
         suggestedThreshold: typeof value.suggestedThreshold === "number"
             ? value.suggestedThreshold
             : null,
+        ...(freshnessPolicy ? { freshnessPolicy } : {}),
     };
 }
+function paidInmailNeedsRefresh(value) {
+    if (!isRecord(value))
+        return false;
+    const status = stringValue(value.status);
+    return Boolean(status && PAID_INMAIL_REFRESH_STATUSES.has(status));
+}
+function filterFreshPaidInmailRefreshAction(action, paidInmail) {
+    return (action.type !== "refresh_paid_inmail_credits" ||
+        paidInmailNeedsRefresh(paidInmail));
+}
 function sanitizeStructuredSenderPlans(value, selectedBySender) {
     if (!Array.isArray(value))
         return [];
@@ -566,10 +627,12 @@ function sanitizeStructuredSenderPlans(value, selectedBySender) {
         return Boolean(selectedLane && selectedBySender.get(plan.senderId) === selectedLane);
     })
         .map((plan) => {
+        const paidInmail = sanitizePaidInmail(plan.paidInmail);
         const nextActions = Array.isArray(plan.nextActions)
             ? plan.nextActions
                 .map((action, index) => sanitizeStructuredAction(action, selectedBySender, "next", index + 1))
                 .filter((action) => Boolean(action))
+                .filter((action) => filterFreshPaidInmailRefreshAction(action, paidInmail))
             : [];
         const manualAlternates = Array.isArray(plan.manualAlternates)
             ? plan.manualAlternates
@@ -614,7 +677,7 @@ function sanitizeStructuredSenderPlans(value, selectedBySender) {
                 : {},
             coverageDisplay: stringArray(plan.coverageDisplay),
             campaignRanking: sanitizeCampaignRanking(plan.campaignRanking),
-            paidInmail: sanitizePaidInmail(plan.paidInmail),
+            paidInmail,
             sourcePlan: sanitizeSourcePlan(plan.sourcePlan),
             refillReceipt: sanitizeRefillReceipt(plan.refillReceipt),
             nextActions,
@@ -640,6 +703,17 @@ function buildSanitizedGlobalActionQueue(senderRefillPlans) {
         rank: index + 1,
     }));
 }
+function paidRefreshNeededSenderIds(senderRefillPlans) {
+    const senderIds = new Set();
+    for (const plan of senderRefillPlans) {
+        if (!paidInmailNeedsRefresh(plan.paidInmail))
+            continue;
+        const senderId = stringValue(plan.senderId);
+        if (senderId)
+            senderIds.add(senderId);
+    }
+    return senderIds;
+}
 function emptyUnsupportedResult(result) {
     if (!isRecord(result) || !isRecord(result.target))
         return result;
@@ -682,7 +756,7 @@ function emptyUnsupportedResult(result) {
         mcpSanitizedRefillLanes: true,
     };
 }
-function sanitizeBlockers(blockers, selectedKeys) {
+function sanitizeBlockers(blockers, selectedKeys, paidRefreshNeededSenderIds) {
     if (!Array.isArray(blockers))
         return [];
     return blockers.filter((item) => {
@@ -694,6 +768,10 @@ function sanitizeBlockers(blockers, selectedKeys) {
             return true;
         const detailSenderId = detail.split(":")[0];
         if (code.startsWith("paid_inmail_")) {
+            if (code === "paid_inmail_credit_stale" &&
+                !paidRefreshNeededSenderIds.has(detailSenderId)) {
+                return false;
+            }
             return selectedKeys.has(`${detailSenderId}:send_inmail_closed`);
         }
         if (detail.includes(":send_dm") || detail.includes(":send_inmail_open")) {
@@ -782,9 +860,10 @@ function sanitizeRefillTargetPlanResult(result) {
     const remainingScheduledGap = senderPlans.reduce((sum, plan) => sum + numberValue(plan.remainingScheduledGap), 0);
     const remainingProjectedGap = senderPlans.reduce((sum, plan) => sum + numberValue(plan.remainingProjectedGap), 0);
     const remainingReadyOrProjectedGap = senderPlans.reduce((sum, plan) => sum + numberValue(plan.remainingReadyOrProjectedGap), 0);
-    const blockers = sanitizeBlockers(result.blockers, selectedKeys);
     const eligibleSenderLedger = sanitizeEligibleSenderLedger(target.eligibleSenderLedger, selectedBySender);
     const senderRefillPlans = sanitizeStructuredSenderPlans(target.senderRefillPlans, selectedBySender);
+    const paidRefreshNeededSenderIdSet = paidRefreshNeededSenderIds(senderRefillPlans);
+    const blockers = sanitizeBlockers(result.blockers, selectedKeys, paidRefreshNeededSenderIdSet);
     const globalActionQueue = buildSanitizedGlobalActionQueue(senderRefillPlans);
     const hasTerminalNoActionBlocker = globalActionQueue.length === 0 &&
         blockers.some((blocker) => TERMINAL_NO_ACTION_BLOCKER_CODES.has(String(blocker.code)));
@@ -831,7 +910,7 @@ function sanitizeRefillTargetPlanResult(result) {
                 readyCounts: sanitizeCounts(result.coverage.readyCounts, selectedKeys),
             }
             : result.coverage,
-        actionCandidates: sanitizeActionCandidates(result.actionCandidates, selectedKeys, status, remainingReadyOrProjectedGap, remainingProjectedGap),
+        actionCandidates: sanitizeActionCandidates(result.actionCandidates, selectedKeys, paidRefreshNeededSenderIdSet, status, remainingReadyOrProjectedGap, remainingProjectedGap),
         blockers,
         mcpSanitizedRefillLanes: true,
     };

package/dist/tools/registry.d.ts

@@ -584,6 +584,97 @@ export declare const allTools: ({
         required: string[];
         additionalProperties: boolean;
     };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            campaignId: {
+                type: string;
+                description: string;
+            };
+            tableId: {
+                type: string;
+            };
+            targetPreparedMessages: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            maxRowsToCheck: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+            batchSize: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+            maxBatchRows: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+            approvalMode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            rowSelector: {
+                type: string;
+                description: string;
+                properties: {
+                    type: {
+                        type: string;
+                        enum: string[];
+                    };
+                    limit: {
+                        type: string;
+                        minimum: number;
+                        maximum: number;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+            excludeRowIds: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                maxItems: number;
+                description: string;
+            };
+            autoContinue: {
+                type: string;
+            };
+            senderId: {
+                type: string;
+                description: string;
+            };
+            actionType: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            disableLowPassRateStop: {
+                type: string;
+                description: string;
+            };
+            workspaceId: {
+                type: string;
+                description: string;
+            };
+            jobId?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
 } | {
     name: string;
     description: string;
@@ -2343,6 +2434,13 @@ export declare const allTools: ({
                 type: string;
                 description: string;
             };
+            actionType?: undefined;
+            campaignId?: undefined;
+            tableId?: undefined;
+            columnId?: undefined;
+            threshold?: undefined;
+            maxStalenessSeconds?: undefined;
+            paidInmailCreditsMaxStalenessSeconds?: undefined;
         };
         required: string[];
         additionalProperties: boolean;

package/dist/tools/senders.d.ts

@@ -35,6 +35,13 @@ export type SenderDetailResponse = {
 export type RefreshPaidInmailCreditsInput = {
     senderId: string;
     workspaceId: string;
+    actionType?: string | null;
+    campaignId?: string | null;
+    tableId?: string | null;
+    columnId?: string | null;
+    threshold?: number | null;
+    maxStalenessSeconds?: number | null;
+    paidInmailCreditsMaxStalenessSeconds?: number | null;
 };
 export type PaidInmailCreditStatus = {
     available: number;
@@ -68,6 +75,13 @@ export declare const senderToolDefinitions: ({
                 description: string;
             };
             senderId?: undefined;
+            actionType?: undefined;
+            campaignId?: undefined;
+            tableId?: undefined;
+            columnId?: undefined;
+            threshold?: undefined;
+            maxStalenessSeconds?: undefined;
+            paidInmailCreditsMaxStalenessSeconds?: undefined;
         };
         required: never[];
         additionalProperties: boolean;
@@ -86,6 +100,59 @@ export declare const senderToolDefinitions: ({
                 type: string;
                 description: string;
             };
+            actionType?: undefined;
+            campaignId?: undefined;
+            tableId?: undefined;
+            columnId?: undefined;
+            threshold?: undefined;
+            maxStalenessSeconds?: undefined;
+            paidInmailCreditsMaxStalenessSeconds?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            senderId: {
+                type: string;
+                description: string;
+            };
+            workspaceId: {
+                type: string;
+                description: string;
+            };
+            actionType: {
+                type: string;
+                description: string;
+            };
+            campaignId: {
+                type: string;
+                description: string;
+            };
+            tableId: {
+                type: string;
+                description: string;
+            };
+            columnId: {
+                type: string;
+                description: string;
+            };
+            threshold: {
+                type: string;
+                description: string;
+            };
+            maxStalenessSeconds: {
+                type: string;
+                description: string;
+            };
+            paidInmailCreditsMaxStalenessSeconds: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
         additionalProperties: boolean;

package/dist/tools/senders.js

@@ -11,6 +11,19 @@ function pickString(...values) {
     }
     return null;
 }
+const DEFAULT_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS = 4 * 60 * 60;
+function numberOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function normalizePaidInmailCreditsMaxStalenessSeconds(...values) {
+    for (const value of values) {
+        const numeric = numberOrNull(value);
+        if (numeric === null || numeric <= 0)
+            continue;
+        return Math.max(Math.trunc(numeric), DEFAULT_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS);
+    }
+    return DEFAULT_PAID_INMAIL_CREDITS_MAX_STALENESS_SECONDS;
+}
 function computeDisplayName(sender) {
     const profile = sender?.unipileAccount?.profileData;
     const name = pickString(profile?.name);
@@ -148,6 +161,34 @@ export const senderToolDefinitions = [
                     type: "string",
                     description: "Explicit request-scoped workspace id for scheduled/yolo refill automation. Pass this instead of switching the shared active workspace.",
                 },
+                actionType: {
+                    type: "string",
+                    description: "Optional action type context for the credit freshness check. Defaults to send_inmail_closed.",
+                },
+                campaignId: {
+                    type: "string",
+                    description: "Optional campaign context for the refresh receipt.",
+                },
+                tableId: {
+                    type: "string",
+                    description: "Optional workflow table context for the refresh receipt.",
+                },
+                columnId: {
+                    type: "string",
+                    description: "Optional workflow column context for the refresh receipt.",
+                },
+                threshold: {
+                    type: "number",
+                    description: "Optional paid InMail threshold used by the planner for this sender.",
+                },
+                maxStalenessSeconds: {
+                    type: "number",
+                    description: "Optional cache freshness window in seconds. Values below 4h are clamped to 4h.",
+                },
+                paidInmailCreditsMaxStalenessSeconds: {
+                    type: "number",
+                    description: "Optional legacy alias for maxStalenessSeconds. Values below 4h are clamped to 4h.",
+                },
             },
             required: ["senderId", "workspaceId"],
             additionalProperties: false,
@@ -213,7 +254,25 @@ export async function refreshPaidInmailCredits(input) {
         throw new Error("workspaceId is required.");
     }
     const requestOptions = workspaceRequestOptions(workspaceId);
-    const body = { workspaceId };
+    const threshold = numberOrNull(input.threshold);
+    const body = {
+        workspaceId,
+        maxStalenessSeconds: normalizePaidInmailCreditsMaxStalenessSeconds(input.maxStalenessSeconds, input.paidInmailCreditsMaxStalenessSeconds),
+    };
+    const actionType = pickString(input.actionType);
+    const campaignId = pickString(input.campaignId);
+    const tableId = pickString(input.tableId);
+    const columnId = pickString(input.columnId);
+    if (actionType)
+        body.actionType = actionType;
+    if (campaignId)
+        body.campaignId = campaignId;
+    if (tableId)
+        body.tableId = tableId;
+    if (columnId)
+        body.columnId = columnId;
+    if (threshold !== null)
+        body.threshold = threshold;
     const result = await api.post(`/api/v3/mcp/senders/${encodeURIComponent(senderId)}/refresh-inmail-credits`, body, requestOptions);
     return {
         senderId,

package/package.json

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