@sellable/mcp 0.1.793 → 0.1.794

package/dist/tools/refill-v3-world-state.js

@@ -0,0 +1,137 @@
+/**
+ * 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 { getApi } from "../api.js";
+import { REFILL_V3_SCHEMA_VERSION_UNSUPPORTED } from "./refill-v3-attention-packet-contract.js";
+import { decodeRefillWorldStateResult, REFILL_V3_WORLD_STATE_OUTPUT_SCHEMA, } from "./refill-v3-world-state-contract.js";
+import { normalizeExplicitWorkspaceId, workspaceRequestOptions, } from "./workspace-context.js";
+/** The one authenticated backend boundary this projection may reach. */
+export const REFILL_V3_WORLD_STATE_ROUTE = "/api/v3/mcp/refill-v3/world-state";
+export const REFILL_V3_WORLD_STATE_TOOL_NAME = "refill_v3_world_state";
+/** Declarative mirror of Plan 02's closed request vocabulary. */
+const REFILL_V3_WORLD_STATE_TOOL_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["workspaceId", "scope"],
+    properties: {
+        workspaceId: { type: "string", minLength: 1 },
+        scope: {
+            oneOf: [
+                {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["kind", "days"],
+                    properties: {
+                        kind: { type: "string", enum: ["sender_local_horizon"] },
+                        days: {
+                            type: "integer",
+                            minimum: 1,
+                            maximum: 3,
+                            description: "sender-local intent; 3 means each sender's local today plus the next two local days",
+                        },
+                        senderIds: {
+                            type: "array",
+                            minItems: 1,
+                            items: { type: "string", minLength: 1 },
+                            description: "omit for every active workspace sender",
+                        },
+                    },
+                },
+                {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["kind", "senderDates"],
+                    properties: {
+                        kind: { type: "string", enum: ["exact_sender_dates"] },
+                        senderDates: {
+                            type: "array",
+                            minItems: 1,
+                            items: {
+                                type: "object",
+                                additionalProperties: false,
+                                required: ["senderId", "dates"],
+                                properties: {
+                                    senderId: { type: "string", minLength: 1 },
+                                    dates: {
+                                        type: "array",
+                                        minItems: 1,
+                                        items: {
+                                            type: "string",
+                                            pattern: "^\\d{4}-\\d{2}-\\d{2}$",
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            ],
+        },
+    },
+};
+export const refillV3WorldStateToolDefinitions = [
+    {
+        name: REFILL_V3_WORLD_STATE_TOOL_NAME,
+        description: "One factual observation of Refill V3 send capacity. It returns one row per scoped sender, per scoped local date, per lane, where the two lanes connection_invite and paid_inmail are independent: each carries its own slots, its own typed blocker, and its own eligible and ineligible campaign options. A scoped sender/date request refreshes both lanes of that sender and date atomically, so the two lanes are never read from different instants. It states facts and never chooses: it schedules nothing, places nothing, sends nothing, approves nothing, enriches nothing, generates nothing, and mutates no campaign, and it reports each of those explicitly as false. The one bookkeeping effect it may perform is a paid-InMail credit cache read or refresh, reported as its own outcome.",
+        inputSchema: REFILL_V3_WORLD_STATE_TOOL_INPUT_SCHEMA,
+        outputSchema: REFILL_V3_WORLD_STATE_OUTPUT_SCHEMA,
+        annotations: {
+            title: "Refill V3 World State",
+            // NOT literal read-only: the observation is allowed to perform paid-credit
+            // cache bookkeeping, so claiming `readOnlyHint: true` would be false.
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
+];
+/**
+ * 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 async function getRefillV3WorldStateTool(input) {
+    const workspaceId = normalizeExplicitWorkspaceId(input.workspaceId);
+    if (!workspaceId) {
+        throw new Error("Explicit workspaceId is required for refill_v3_world_state. Pass workspaceId on the tool call instead of switching the shared active workspace.");
+    }
+    const raw = await getApi().post(REFILL_V3_WORLD_STATE_ROUTE, { workspaceId, scope: input.scope }, workspaceRequestOptions(workspaceId));
+    const decoded = decodeRefillWorldStateResult(raw);
+    if (decoded === null) {
+        throw new Error("The Refill V3 world-state response failed the published result contract.");
+    }
+    if (decoded === REFILL_V3_SCHEMA_VERSION_UNSUPPORTED) {
+        throw new Error("The Refill V3 world-state response uses a schema major this build cannot read. Update @sellable/mcp.");
+    }
+    return decoded;
+}