@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-world-state.d.ts

@@ -0,0 +1,592 @@
+/**
+ * Refill V3 world-state PUBLIC MCP projection (Phase 146.5 Plan 08, RV3MCP-001).
+ *
+ * This is a THIN projection and nothing else:
+ *
+ *  1. it mirrors Plan 02's DECLARATIVE request vocabulary so a protocol-level
+ *     validator refuses closed-vocabulary drift before the handler runs;
+ *  2. it applies the ONE shared explicit-workspace guard, because a
+ *     request-scoped automation must never switch the shared active workspace;
+ *  3. it posts the caller body once to the authenticated aggregate route, whose
+ *     `parseRefillWorldStateInput` is the SOLE runtime authority for duplicate
+ *     scope identities, invalid dates, unknown/cross-form keys, and canonical
+ *     sorting; and
+ *  4. it returns only what Plan 02's SOLE unknown-value decoder produced.
+ *
+ * It holds no result-field rules, no second decoder, no business policy, and no
+ * hand-built MCP envelope — the central `toMcpToolResult` owns the wire result.
+ *
+ * `isError` is a TRANSPORT concern only (error law 6). A typed business blocker
+ * inside a well-formed decoded result is a successful response VALUE and passes
+ * through VERBATIM; this module therefore contains no branch that reads a
+ * decoded business field to decide failure.
+ *
+ * The declarative input schema is mirrored here rather than imported because the
+ * published package must never import app `src/**`. The mirror is not trusted:
+ * `tests/mcp/refill-v3/world-state-tool.test.ts` asserts it deep-equals the
+ * owner's `REFILL_V3_WORLD_STATE_INPUT_SCHEMA`, so drift is a failing pin.
+ */
+import { type RefillWorldStateResult } from "./refill-v3-world-state-contract.js";
+/** The one authenticated backend boundary this projection may reach. */
+export declare const REFILL_V3_WORLD_STATE_ROUTE = "/api/v3/mcp/refill-v3/world-state";
+export declare const REFILL_V3_WORLD_STATE_TOOL_NAME: "refill_v3_world_state";
+export declare const refillV3WorldStateToolDefinitions: {
+    name: "refill_v3_world_state";
+    description: string;
+    inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["workspaceId", "scope"];
+        readonly properties: {
+            readonly workspaceId: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+            readonly scope: {
+                readonly oneOf: readonly [{
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["kind", "days"];
+                    readonly properties: {
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly enum: readonly ["sender_local_horizon"];
+                        };
+                        readonly days: {
+                            readonly type: "integer";
+                            readonly minimum: 1;
+                            readonly maximum: 3;
+                            readonly description: "sender-local intent; 3 means each sender's local today plus the next two local days";
+                        };
+                        readonly senderIds: {
+                            readonly type: "array";
+                            readonly minItems: 1;
+                            readonly items: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly description: "omit for every active workspace sender";
+                        };
+                    };
+                }, {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["kind", "senderDates"];
+                    readonly properties: {
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly enum: readonly ["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}$";
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                }];
+            };
+        };
+    };
+    outputSchema: Readonly<{
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["rows", "durationMs", "observationSideEffects"];
+        readonly properties: {
+            readonly rows: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["date", "sender", "lane", "targetSlots", "takenSlots", "availableSlots", "reason", "activeCampaigns", "inactiveCampaigns"];
+                    readonly properties: {
+                        readonly date: {
+                            readonly type: "string";
+                            readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                        };
+                        readonly sender: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["id", "name", "timezone"];
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly name: {
+                                    readonly type: "string";
+                                };
+                                readonly timezone: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                            };
+                        };
+                        readonly lane: {
+                            readonly type: "string";
+                            readonly enum: readonly ["connection_invite", "paid_inmail"];
+                        };
+                        readonly targetSlots: {
+                            readonly type: "integer";
+                            readonly minimum: 0;
+                        };
+                        readonly takenSlots: {
+                            readonly type: "integer";
+                            readonly minimum: 0;
+                        };
+                        readonly availableSlots: {
+                            readonly type: "integer";
+                            readonly minimum: 0;
+                        };
+                        readonly reason: {
+                            readonly type: readonly ["object", "null"];
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["kind", "codes", "message"];
+                            readonly properties: {
+                                readonly kind: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["unavailable", "retry_required", "invalid_campaign_configuration"];
+                                };
+                                readonly codes: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        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"];
+                                    };
+                                };
+                                readonly message: {
+                                    readonly type: "string";
+                                };
+                                readonly resumeAt: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                        readonly activeCampaigns: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["id", "name", "status", "lanes", "eligible", "reason", "startEligible", "activeJob", "supply", "leadSourceFamily", "evidence"];
+                                readonly properties: {
+                                    readonly id: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                    readonly name: {
+                                        readonly type: "string";
+                                    };
+                                    readonly status: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["ACTIVE", "PAUSED"];
+                                    };
+                                    readonly lanes: {
+                                        readonly type: "array";
+                                        readonly minItems: 1;
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["connection_invite", "paid_inmail"];
+                                        };
+                                    };
+                                    readonly eligible: {
+                                        readonly type: "boolean";
+                                    };
+                                    readonly reason: {
+                                        readonly type: readonly ["object", "null"];
+                                        readonly additionalProperties: false;
+                                        readonly required: readonly ["kind", "codes", "message"];
+                                        readonly properties: {
+                                            readonly kind: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["unavailable", "retry_required", "invalid_campaign_configuration"];
+                                            };
+                                            readonly codes: {
+                                                readonly type: "array";
+                                                readonly items: {
+                                                    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"];
+                                                };
+                                            };
+                                            readonly message: {
+                                                readonly type: "string";
+                                            };
+                                            readonly resumeAt: {
+                                                readonly type: "string";
+                                            };
+                                        };
+                                    };
+                                    readonly startEligible: {
+                                        readonly type: "boolean";
+                                    };
+                                    readonly activeJob: {
+                                        readonly type: readonly ["object", "null"];
+                                        readonly additionalProperties: false;
+                                        readonly required: readonly ["id", "kind", "status"];
+                                        readonly properties: {
+                                            readonly id: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                            readonly kind: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["enrichment", "message_generation", "source_expansion", "scheduling"];
+                                            };
+                                            readonly status: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["queued", "running"];
+                                            };
+                                        };
+                                    };
+                                    readonly supply: {
+                                        readonly type: "object";
+                                        readonly additionalProperties: false;
+                                        readonly required: readonly ["readyToSchedule", "readyForApproval", "readyForMessageGeneration", "needsEnrichment"];
+                                        readonly properties: {
+                                            readonly readyToSchedule: {
+                                                readonly type: "integer";
+                                                readonly minimum: 0;
+                                            };
+                                            readonly readyForApproval: {
+                                                readonly type: "integer";
+                                                readonly minimum: 0;
+                                            };
+                                            readonly readyForMessageGeneration: {
+                                                readonly type: "integer";
+                                                readonly minimum: 0;
+                                            };
+                                            readonly needsEnrichment: {
+                                                readonly type: "integer";
+                                                readonly minimum: 0;
+                                            };
+                                        };
+                                    };
+                                    readonly leadSourceFamily: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["post_engager", "signal_discovery", "cold"];
+                                    };
+                                    readonly evidence: {
+                                        readonly type: "object";
+                                        readonly additionalProperties: false;
+                                        readonly required: readonly ["evergreen", "lastActualUseAt", "lastScheduledUseAt", "effectiveness", "supplyHealth"];
+                                        readonly properties: {
+                                            readonly evergreen: {
+                                                readonly type: "boolean";
+                                            };
+                                            readonly lastActualUseAt: {
+                                                readonly type: readonly ["string", "null"];
+                                            };
+                                            readonly lastScheduledUseAt: {
+                                                readonly type: readonly ["string", "null"];
+                                            };
+                                            readonly effectiveness: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["unknown", "low", "medium", "high"];
+                                            };
+                                            readonly supplyHealth: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["unknown", "healthy", "thin", "dry"];
+                                            };
+                                            readonly engagement: {
+                                                readonly type: "object";
+                                                readonly additionalProperties: false;
+                                                readonly required: readonly ["sends", "accepted", "replied", "acceptRate", "replyRate"];
+                                                readonly properties: {
+                                                    readonly sends: {
+                                                        readonly type: "number";
+                                                        readonly minimum: 0;
+                                                    };
+                                                    readonly accepted: {
+                                                        readonly type: "number";
+                                                        readonly minimum: 0;
+                                                    };
+                                                    readonly replied: {
+                                                        readonly type: "number";
+                                                        readonly minimum: 0;
+                                                    };
+                                                    readonly acceptRate: {
+                                                        readonly type: "number";
+                                                        readonly minimum: 0;
+                                                        readonly maximum: 100;
+                                                    };
+                                                    readonly replyRate: {
+                                                        readonly type: "number";
+                                                        readonly minimum: 0;
+                                                        readonly maximum: 100;
+                                                    };
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                        readonly inactiveCampaigns: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["id", "name", "status", "lanes", "eligible", "reason", "startEligible", "activeJob", "supply", "leadSourceFamily", "evidence"];
+                                readonly properties: {
+                                    readonly id: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                    readonly name: {
+                                        readonly type: "string";
+                                    };
+                                    readonly status: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["ACTIVE", "PAUSED"];
+                                    };
+                                    readonly lanes: {
+                                        readonly type: "array";
+                                        readonly minItems: 1;
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly enum: readonly ["connection_invite", "paid_inmail"];
+                                        };
+                                    };
+                                    readonly eligible: {
+                                        readonly type: "boolean";
+                                    };
+                                    readonly reason: {
+                                        readonly type: readonly ["object", "null"];
+                                        readonly additionalProperties: false;
+                                        readonly required: readonly ["kind", "codes", "message"];
+                                        readonly properties: {
+                                            readonly kind: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["unavailable", "retry_required", "invalid_campaign_configuration"];
+                                            };
+                                            readonly codes: {
+                                                readonly type: "array";
+                                                readonly items: {
+                                                    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"];
+                                                };
+                                            };
+                                            readonly message: {
+                                                readonly type: "string";
+                                            };
+                                            readonly resumeAt: {
+                                                readonly type: "string";
+                                            };
+                                        };
+                                    };
+                                    readonly startEligible: {
+                                        readonly type: "boolean";
+                                    };
+                                    readonly activeJob: {
+                                        readonly type: readonly ["object", "null"];
+                                        readonly additionalProperties: false;
+                                        readonly required: readonly ["id", "kind", "status"];
+                                        readonly properties: {
+                                            readonly id: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                            readonly kind: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["enrichment", "message_generation", "source_expansion", "scheduling"];
+                                            };
+                                            readonly status: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["queued", "running"];
+                                            };
+                                        };
+                                    };
+                                    readonly supply: {
+                                        readonly type: "object";
+                                        readonly additionalProperties: false;
+                                        readonly required: readonly ["readyToSchedule", "readyForApproval", "readyForMessageGeneration", "needsEnrichment"];
+                                        readonly properties: {
+                                            readonly readyToSchedule: {
+                                                readonly type: "integer";
+                                                readonly minimum: 0;
+                                            };
+                                            readonly readyForApproval: {
+                                                readonly type: "integer";
+                                                readonly minimum: 0;
+                                            };
+                                            readonly readyForMessageGeneration: {
+                                                readonly type: "integer";
+                                                readonly minimum: 0;
+                                            };
+                                            readonly needsEnrichment: {
+                                                readonly type: "integer";
+                                                readonly minimum: 0;
+                                            };
+                                        };
+                                    };
+                                    readonly leadSourceFamily: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["post_engager", "signal_discovery", "cold"];
+                                    };
+                                    readonly evidence: {
+                                        readonly type: "object";
+                                        readonly additionalProperties: false;
+                                        readonly required: readonly ["evergreen", "lastActualUseAt", "lastScheduledUseAt", "effectiveness", "supplyHealth"];
+                                        readonly properties: {
+                                            readonly evergreen: {
+                                                readonly type: "boolean";
+                                            };
+                                            readonly lastActualUseAt: {
+                                                readonly type: readonly ["string", "null"];
+                                            };
+                                            readonly lastScheduledUseAt: {
+                                                readonly type: readonly ["string", "null"];
+                                            };
+                                            readonly effectiveness: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["unknown", "low", "medium", "high"];
+                                            };
+                                            readonly supplyHealth: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["unknown", "healthy", "thin", "dry"];
+                                            };
+                                            readonly engagement: {
+                                                readonly type: "object";
+                                                readonly additionalProperties: false;
+                                                readonly required: readonly ["sends", "accepted", "replied", "acceptRate", "replyRate"];
+                                                readonly properties: {
+                                                    readonly sends: {
+                                                        readonly type: "number";
+                                                        readonly minimum: 0;
+                                                    };
+                                                    readonly accepted: {
+                                                        readonly type: "number";
+                                                        readonly minimum: 0;
+                                                    };
+                                                    readonly replied: {
+                                                        readonly type: "number";
+                                                        readonly minimum: 0;
+                                                    };
+                                                    readonly acceptRate: {
+                                                        readonly type: "number";
+                                                        readonly minimum: 0;
+                                                        readonly maximum: 100;
+                                                    };
+                                                    readonly replyRate: {
+                                                        readonly type: "number";
+                                                        readonly minimum: 0;
+                                                        readonly maximum: 100;
+                                                    };
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                        readonly paidCreditEvidence: {
+                            readonly type: readonly ["object", "null"];
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["availableCredits", "minimumRequired", "checkedAt", "fresh"];
+                            readonly properties: {
+                                readonly availableCredits: {
+                                    readonly type: readonly ["integer", "null"];
+                                    readonly minimum: 0;
+                                };
+                                readonly minimumRequired: {
+                                    readonly type: readonly ["integer", "null"];
+                                    readonly minimum: 0;
+                                };
+                                readonly checkedAt: {
+                                    readonly type: readonly ["string", "null"];
+                                };
+                                readonly fresh: {
+                                    readonly type: "boolean";
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+            readonly durationMs: {
+                readonly type: "number";
+                readonly minimum: 0;
+            };
+            readonly observationSideEffects: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["scheduled", "placed", "sent", "campaignMutated", "approved", "enriched", "generated", "salesNavigatorActioned", "paidCreditCache"];
+                readonly properties: {
+                    readonly scheduled: {
+                        readonly type: "boolean";
+                        readonly enum: readonly [false];
+                    };
+                    readonly placed: {
+                        readonly type: "boolean";
+                        readonly enum: readonly [false];
+                    };
+                    readonly sent: {
+                        readonly type: "boolean";
+                        readonly enum: readonly [false];
+                    };
+                    readonly campaignMutated: {
+                        readonly type: "boolean";
+                        readonly enum: readonly [false];
+                    };
+                    readonly approved: {
+                        readonly type: "boolean";
+                        readonly enum: readonly [false];
+                    };
+                    readonly enriched: {
+                        readonly type: "boolean";
+                        readonly enum: readonly [false];
+                    };
+                    readonly generated: {
+                        readonly type: "boolean";
+                        readonly enum: readonly [false];
+                    };
+                    readonly salesNavigatorActioned: {
+                        readonly type: "boolean";
+                        readonly enum: readonly [false];
+                    };
+                    readonly paidCreditCache: {
+                        readonly type: "string";
+                        readonly enum: readonly ["not_checked", "not_eligible", "fresh_cache_used", "refresh_started", "refreshed", "refresh_in_progress", "refresh_failed", "uncertain"];
+                    };
+                };
+            };
+        };
+    }>;
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+}[];
+export type RefillV3WorldStateToolInput = {
+    workspaceId?: string;
+    scope?: unknown;
+};
+/**
+ * Observe the canonical world state for ONE explicit workspace.
+ *
+ * The returned value is the plain canonical business object. 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 empty
+ * observation.
+ */
+export declare function getRefillV3WorldStateTool(input: RefillV3WorldStateToolInput): Promise<RefillWorldStateResult>;