@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-advance.d.ts

@@ -0,0 +1,397 @@
+/**
+ * Refill V3 advance PUBLIC MCP projection (Phase 146.5 Plan 10, RV3FLOW-001).
+ *
+ * A THIN projection over this plan's package-root contract and nothing else:
+ *
+ *  1. it mirrors the closed three-key request vocabulary so a protocol-level
+ *     validator refuses drift — including every progress-carrying key — before
+ *     the handler runs;
+ *  2. it applies the ONE shared explicit-workspace guard, because a bounded
+ *     mutation must name its target workspace instead of switching the shared
+ *     active workspace;
+ *  3. it posts the caller's exact values once to the authenticated route, whose
+ *     `parseRefillV3AdvanceInput` is the SOLE runtime authority; and
+ *  4. it returns only what the SOLE closed decoder produced.
+ *
+ * It holds no queue, campaign, health, source, retry, or terminal policy: every
+ * decision belongs to `computeNextRefillV3Action` on the backend. A typed
+ * business result — including `blocked` — is a successful response VALUE and
+ * passes through VERBATIM through the central `toMcpToolResult`. Transport
+ * failure is the ONLY source of an error result (error law 6).
+ *
+ * The declarative input schema is IMPORTED from the package contract rather than
+ * re-declared, because the contract already lives inside this package and a
+ * second mirror would be a vocabulary owned twice.
+ */
+import { type RefillV3AdvanceResult } from "./refill-v3-advance-contract.js";
+/** The one authenticated backend boundary this projection may reach. */
+export declare const REFILL_V3_ADVANCE_ROUTE = "/api/v3/mcp/refill-v3/advance";
+export declare const REFILL_V3_ADVANCE_TOOL_NAME: "refill_v3_advance";
+export declare const refillV3AdvanceToolDefinitions: {
+    name: "refill_v3_advance";
+    description: string;
+    inputSchema: Readonly<{
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["workspaceId", "scope"];
+        readonly properties: {
+            readonly workspaceId: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly description: "Explicit request-scoped workspace id. Pass this instead of switching the shared active workspace.";
+            };
+            readonly scope: {
+                readonly description: "Either a 1-3 day sender-local horizon or an exact sender/date set. There is no lane input, no row input, and no mode input.";
+                readonly oneOf: readonly [{
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["kind", "days"];
+                    readonly properties: {
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly const: "sender_local_horizon";
+                        };
+                        readonly days: {
+                            readonly type: "integer";
+                            readonly minimum: 1;
+                            readonly maximum: 3;
+                        };
+                        readonly senderIds: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly minItems: 1;
+                        };
+                    };
+                }, {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["kind", "senderDates"];
+                    readonly properties: {
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly const: "exact_sender_dates";
+                        };
+                        readonly senderDates: {
+                            readonly type: "array";
+                            readonly minItems: 1;
+                            readonly items: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["senderId", "dates"];
+                                readonly properties: {
+                                    readonly senderId: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                    readonly dates: {
+                                        readonly type: "array";
+                                        readonly minItems: 1;
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                }];
+            };
+            readonly yolo: {
+                readonly type: "boolean";
+                readonly description: "The operator's AUTONOMY GRANT, true only when the operator actually asked for --yolo. It is not a mode and selects nothing: WHICH campaign may start is derived from the workspace's own campaigns. It authorizes exactly one thing this call could not otherwise do — starting one already-eligible PAUSED derived-evergreen campaign once every active campaign for a row is exhausted. Omit it, or pass false, for a conservative run that reports that exhaustion instead of acting on it.";
+            };
+        };
+    }>;
+    outputSchema: Readonly<{
+        readonly type: "object";
+        readonly required: readonly ["kind", "scope"];
+        readonly properties: {
+            readonly schemaVersion: {
+                readonly type: "string";
+            };
+            readonly kind: {
+                readonly type: "string";
+                readonly enum: readonly ["advanced", "campaign_attention_required", "awaiting_external_change", "complete", "blocked"];
+            };
+            readonly scope: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["workspaceId", "scopeKind", "scopeFingerprint"];
+                readonly properties: {
+                    readonly workspaceId: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly scopeKind: {
+                        readonly type: "string";
+                        readonly enum: readonly ["sender_local_horizon", "exact_sender_dates"];
+                    };
+                    readonly scopeFingerprint: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                };
+            };
+            readonly action: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["kind", "actionKey", "authority", "senderId", "date", "lane", "campaignId", "evidenceFingerprint"];
+                readonly properties: {
+                    readonly evidenceFingerprint: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly senderId: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly date: {
+                        readonly type: "string";
+                        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                    };
+                    readonly lane: {
+                        readonly type: "string";
+                        readonly enum: readonly ["connection_invite", "paid_inmail"];
+                    };
+                    readonly campaignId: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                    readonly kind: {
+                        readonly type: "string";
+                        readonly enum: readonly ["refresh_paid_credit_fact", "recheck_sender_connection", "fill_ready", "start_evergreen_campaign"];
+                    };
+                    readonly actionKey: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly authority: {
+                        readonly type: "string";
+                        readonly enum: ("getOrRefreshPaidInmailCreditFact" | "recheckRefillV3SenderConnection" | "fillRefillV3Ready" | "startRefillV3EvergreenCampaign")[];
+                    };
+                };
+            };
+            readonly receipt: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["actionKey", "status", "effectFingerprint", "productStateDelta", "reasonCode"];
+                readonly properties: {
+                    readonly actionKey: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly status: {
+                        readonly type: "string";
+                        readonly enum: readonly ["executed", "attached", "failed", "indeterminate"];
+                    };
+                    readonly effectFingerprint: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly productStateDelta: {
+                        readonly type: "boolean";
+                    };
+                    readonly reasonCode: {
+                        readonly type: readonly ["string", "null"];
+                        readonly enum: readonly ["global_cooldown", "connection_cooldown", "paid_inmail_cooldown", "endpoint_temporarily_unavailable", "date_in_past", "no_sending_hours", "sender_disconnected", "sender_limit_reached", "daily_target_met", "no_eligible_campaign", "no_ready_supply", "sales_nav_disconnected", "insufficient_paid_credits", "paid_inmail_connection_health_recheck_required", "paid_inmail_credit_refresh_failed", "invalid_paid_configuration", "campaign_table_missing", "campaign_sequence_invalid", "source_family_unresolved", "campaign_work_in_flight", "zero_requested_count", "idempotency_scope_mismatch", "uncertain_outcome", "placed_under_other_sender", "placed_off_target_date", "paid_inmail_credit_receipt_invalid", "awaiting_external_change", "approval_authority_invalid", "approval_authority_in_flight", "approval_dispatch_incomplete", "ready_cells_unavailable", "sender_affinity_conflict", "scheduler_target_omitted", "scheduler_failed", "receipt_readback_mismatch", "account_identity_missing", "no_progress_refused", "retryable_paid_attempts_exhausted", "unknown_transport_vocabulary", "forged_authority_receipt_facts", "authority_failure_uncertain", "sender_scope_unresolved", "campaign_supply_unclaimed", "lane_campaigns_exhausted", "missing_balance", "blocked", "workspace_membership_revoked", null];
+                    };
+                };
+            };
+            readonly packet: {
+                readonly properties: {
+                    readonly schemaVersion: {
+                        readonly type: "string";
+                    };
+                };
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["scope", "evidence"];
+            };
+            readonly deferral: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["senderId", "date", "lane", "campaignId", "code", "message", "resumeAt", "receiptRef"];
+                readonly properties: {
+                    readonly code: {
+                        readonly type: "string";
+                        readonly enum: readonly ["global_cooldown", "connection_cooldown", "paid_inmail_cooldown", "endpoint_temporarily_unavailable", "date_in_past", "no_sending_hours", "sender_disconnected", "sender_limit_reached", "daily_target_met", "no_eligible_campaign", "no_ready_supply", "sales_nav_disconnected", "insufficient_paid_credits", "paid_inmail_connection_health_recheck_required", "paid_inmail_credit_refresh_failed", "invalid_paid_configuration", "campaign_table_missing", "campaign_sequence_invalid", "source_family_unresolved", "campaign_work_in_flight", "zero_requested_count", "idempotency_scope_mismatch", "uncertain_outcome", "placed_under_other_sender", "placed_off_target_date", "paid_inmail_credit_receipt_invalid", "awaiting_external_change", "approval_authority_invalid", "approval_authority_in_flight", "approval_dispatch_incomplete", "ready_cells_unavailable", "sender_affinity_conflict", "scheduler_target_omitted", "scheduler_failed", "receipt_readback_mismatch", "account_identity_missing", "no_progress_refused", "retryable_paid_attempts_exhausted", "unknown_transport_vocabulary", "forged_authority_receipt_facts", "authority_failure_uncertain", "sender_scope_unresolved", "campaign_supply_unclaimed", "lane_campaigns_exhausted", "missing_balance", "blocked", "workspace_membership_revoked"];
+                    };
+                    readonly message: {
+                        readonly type: "string";
+                    };
+                    readonly resumeAt: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                    readonly receiptRef: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                    readonly senderId: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly date: {
+                        readonly type: "string";
+                        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                    };
+                    readonly lane: {
+                        readonly type: "string";
+                        readonly enum: readonly ["connection_invite", "paid_inmail"];
+                    };
+                    readonly campaignId: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                };
+            };
+            readonly blocker: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["senderId", "date", "lane", "campaignId", "code", "message", "permanent", "field"];
+                readonly properties: {
+                    readonly code: {
+                        readonly type: "string";
+                        readonly enum: readonly ["global_cooldown", "connection_cooldown", "paid_inmail_cooldown", "endpoint_temporarily_unavailable", "date_in_past", "no_sending_hours", "sender_disconnected", "sender_limit_reached", "daily_target_met", "no_eligible_campaign", "no_ready_supply", "sales_nav_disconnected", "insufficient_paid_credits", "paid_inmail_connection_health_recheck_required", "paid_inmail_credit_refresh_failed", "invalid_paid_configuration", "campaign_table_missing", "campaign_sequence_invalid", "source_family_unresolved", "campaign_work_in_flight", "zero_requested_count", "idempotency_scope_mismatch", "uncertain_outcome", "placed_under_other_sender", "placed_off_target_date", "paid_inmail_credit_receipt_invalid", "awaiting_external_change", "approval_authority_invalid", "approval_authority_in_flight", "approval_dispatch_incomplete", "ready_cells_unavailable", "sender_affinity_conflict", "scheduler_target_omitted", "scheduler_failed", "receipt_readback_mismatch", "account_identity_missing", "no_progress_refused", "retryable_paid_attempts_exhausted", "unknown_transport_vocabulary", "forged_authority_receipt_facts", "authority_failure_uncertain", "sender_scope_unresolved", "campaign_supply_unclaimed", "lane_campaigns_exhausted", "missing_balance", "blocked", "workspace_membership_revoked"];
+                    };
+                    readonly message: {
+                        readonly type: "string";
+                    };
+                    readonly permanent: {
+                        readonly type: "boolean";
+                    };
+                    readonly field: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                    readonly senderId: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly date: {
+                        readonly type: "string";
+                        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                    };
+                    readonly lane: {
+                        readonly type: "string";
+                        readonly enum: readonly ["connection_invite", "paid_inmail"];
+                    };
+                    readonly campaignId: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                };
+            };
+            readonly terminal: {
+                readonly type: "string";
+                readonly enum: readonly ["active_campaigns_exhausted", "no_eligible_campaigns", "campaign_supply_unclaimed_defect", "daily_targets_met", "scope_unresolved"];
+            };
+            readonly observation: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["observationFingerprint", "senderCount", "rowCount", "dates", "availableSlots", "supply"];
+                readonly properties: {
+                    readonly observationFingerprint: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly senderCount: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly rowCount: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly dates: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                            readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                        };
+                    };
+                    readonly availableSlots: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly supply: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["readyToSchedule", "readyForApproval", "readyForMessageGeneration", "needsEnrichment"];
+                        readonly properties: {
+                            [k: string]: {
+                                type: string;
+                                minimum: number;
+                            };
+                        };
+                    };
+                };
+            };
+            readonly replacementObservation: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["observationFingerprint", "senderCount", "rowCount", "dates", "availableSlots", "supply"];
+                readonly properties: {
+                    readonly observationFingerprint: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly senderCount: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly rowCount: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly dates: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                            readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                        };
+                    };
+                    readonly availableSlots: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                    };
+                    readonly supply: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["readyToSchedule", "readyForApproval", "readyForMessageGeneration", "needsEnrichment"];
+                        readonly properties: {
+                            [k: string]: {
+                                type: string;
+                                minimum: number;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    }>;
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}[];
+export type RefillV3AdvanceToolInput = {
+    workspaceId?: string;
+    scope?: unknown;
+    /**
+     * The operator's autonomy grant, forwarded verbatim. It is NOT defaulted here
+     * — an omitted grant stays omitted so the backend parser, which is the single
+     * owner of the conservative default, is the only place that decides.
+     */
+    yolo?: boolean;
+};
+/**
+ * Advance one explicit workspace scope by exactly one step.
+ *
+ * The returned value is the plain canonical business result. Every failure that
+ * is NOT a decoded business fact — a refused request, an authorization refusal,
+ * an infrastructure failure, or a response the sole decoder rejects — propagates
+ * as a thrown transport error and can never become a plausible receipt.
+ */
+export declare function advanceRefillV3Tool(input: RefillV3AdvanceToolInput): Promise<RefillV3AdvanceResult>;

package/dist/tools/refill-v3-advance.js

@@ -0,0 +1,75 @@
+/**
+ * Refill V3 advance PUBLIC MCP projection (Phase 146.5 Plan 10, RV3FLOW-001).
+ *
+ * A THIN projection over this plan's package-root contract and nothing else:
+ *
+ *  1. it mirrors the closed three-key request vocabulary so a protocol-level
+ *     validator refuses drift — including every progress-carrying key — before
+ *     the handler runs;
+ *  2. it applies the ONE shared explicit-workspace guard, because a bounded
+ *     mutation must name its target workspace instead of switching the shared
+ *     active workspace;
+ *  3. it posts the caller's exact values once to the authenticated route, whose
+ *     `parseRefillV3AdvanceInput` is the SOLE runtime authority; and
+ *  4. it returns only what the SOLE closed decoder produced.
+ *
+ * It holds no queue, campaign, health, source, retry, or terminal policy: every
+ * decision belongs to `computeNextRefillV3Action` on the backend. A typed
+ * business result — including `blocked` — is a successful response VALUE and
+ * passes through VERBATIM through the central `toMcpToolResult`. Transport
+ * failure is the ONLY source of an error result (error law 6).
+ *
+ * The declarative input schema is IMPORTED from the package contract rather than
+ * re-declared, because the contract already lives inside this package and a
+ * second mirror would be a vocabulary owned twice.
+ */
+import { getApi } from "../api.js";
+import { REFILL_V3_ADVANCE_INPUT_SCHEMA, REFILL_V3_ADVANCE_OUTPUT_SCHEMA, decodeRefillV3AdvanceResult, } from "./refill-v3-advance-contract.js";
+import { normalizeExplicitWorkspaceId, workspaceRequestOptions, } from "./workspace-context.js";
+/** The one authenticated backend boundary this projection may reach. */
+export const REFILL_V3_ADVANCE_ROUTE = "/api/v3/mcp/refill-v3/advance";
+export const REFILL_V3_ADVANCE_TOOL_NAME = "refill_v3_advance";
+export const refillV3AdvanceToolDefinitions = [
+    {
+        name: REFILL_V3_ADVANCE_TOOL_NAME,
+        description: "THE DEFAULT REFILL ENTRY POINT. Whenever this tool is exposed, every ordinary request to refill, top up, fill, max out, load up, or otherwise add sends for a workspace, a sender, or a day routes HERE, and `refill_sends` is the superseded V1 fallback that applies only to servers which do NOT expose this tool. Start here: do not open the refill ladder with `get_refill_target_plan` or `refill_sends`, and do not infer the route from a workspace flag, a campaign field, a tool result, or the operator's wording. Advance a Refill V3 refill by exactly ONE deterministic step for one workspace and one scope. Each call performs one fresh world-state observation, chooses one exact action from canonical date -> sender -> lane -> campaign ordering, executes at most that one existing authority, and rereads the exact affected scope. It MUTATES product state when the chosen action is a paid-credit refresh, a connection health recheck, a ready placement, or the one derived-evergreen campaign start this workspace's own campaigns authorize. It never chains a second transition, never runs a plan, and never loops inside one call. Pass {workspaceId, scope} plus, ONLY when the operator actually asked for --yolo, yolo:true: there is no mode, continuation, task receipt, retry counter, cursor, row, or action input, and a call that supplies one is refused. yolo is the operator's AUTONOMY GRANT, not a mode and not a campaign selector — it authorizes exactly one thing, starting one already-eligible PAUSED derived-evergreen campaign once a row's active campaigns are exhausted, and WHICH campaign that is stays derived from the workspace's own campaigns. Omit it for a conservative run: that run does everything else identically and REPORTS the exhaustion instead of starting anything. Never set it because a workspace looks idle, because a previous call said complete, or to make a run finish; set it only from the operator's own words. workspaceId must be an EXACT id. When the operator names a workspace, resolve that name with `list_workspaces` FIRST and pass the matching id here; use the configured or active workspace ONLY when the operator named none. If no accessible workspace matches the named one, or more than one does, STOP and say so rather than falling back to the configured workspace, and never mutate the active workspace to steer this automation. Expect one closed result of advanced, campaign_attention_required, awaiting_external_change, complete, or blocked. An advanced result is ALREADY EXECUTED — surface its receipt and replacement observation and do not call its authority again. Only campaign_attention_required needs a caller: route its ONE selected campaign to the refill-sends-work-campaign subskill and return its chosen closed action to refill_v3_edit_selected_campaign. Call this repeatedly until it answers complete, awaiting_external_change, or blocked.",
+        inputSchema: REFILL_V3_ADVANCE_INPUT_SCHEMA,
+        outputSchema: REFILL_V3_ADVANCE_OUTPUT_SCHEMA,
+        annotations: {
+            title: "Refill V3 Advance",
+            readOnlyHint: false,
+            // Destructive in the PRODUCT-STATE sense: approval, scheduling, credit
+            // bookkeeping, and campaign activation change durable customer state a
+            // caller cannot undo from this tool.
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
+];
+/**
+ * Advance one explicit workspace scope by exactly one step.
+ *
+ * The returned value is the plain canonical business result. Every failure that
+ * is NOT a decoded business fact — a refused request, an authorization refusal,
+ * an infrastructure failure, or a response the sole decoder rejects — propagates
+ * as a thrown transport error and can never become a plausible receipt.
+ */
+export async function advanceRefillV3Tool(input) {
+    const workspaceId = normalizeExplicitWorkspaceId(input.workspaceId);
+    if (!workspaceId) {
+        throw new Error("Explicit workspaceId is required for refill_v3_advance. Name the target workspace instead of switching the shared active workspace.");
+    }
+    const raw = await getApi().post(REFILL_V3_ADVANCE_ROUTE, {
+        workspaceId,
+        scope: input.scope,
+        // Forwarded only when the caller actually supplied it, so an absent grant
+        // is absent on the wire rather than an explicit `false` this layer made up.
+        ...(input.yolo === undefined ? {} : { yolo: input.yolo }),
+    }, workspaceRequestOptions(workspaceId));
+    const decoded = decodeRefillV3AdvanceResult(raw);
+    if (decoded === null) {
+        throw new Error("The Refill V3 advance response failed the published result contract.");
+    }
+    return decoded;
+}