@carrierllc/mcp 0.13.38 → 0.13.40

package/dist/index.js

@@ -80,7 +80,7 @@ import {
   verifyStorefront,
   withOcsListSummary,
   withTemplateResellerId
-} from "./chunk-D37X6FBD.js";
+} from "./chunk-WVXII7ZR.js";
 import "./chunk-SHKKVIIA.js";
 
 // src/index.ts
@@ -89,8 +89,95 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/tools.ts
 import { z } from "zod";
+
+// src/durable-issuance.ts
+async function issueInventory(ctx, args, extra) {
+  const key = args.request_key;
+  const error = (code, message, detail = {}) => ({ isError: true, content: [{ type: "text", text: JSON.stringify({ ...detail, code, message, request_key: key }) }] });
+  const token2 = await ctx.getApiToken?.(extra);
+  if (!token2) return error("CARRIER_API_AUTH_REQUIRED", "An authenticated Carrier API credential is required. No dispatch made.");
+  const body2 = {
+    packageTemplateId: args.packageTemplateId,
+    ...args.account_for_subs !== void 0 ? { accountId: args.account_for_subs } : {},
+    ...Object.fromEntries(["startDate", "endDate", "validityPeriod"].filter((k) => args[k] !== void 0).map((k) => [k, args[k]])),
+    ...args.business_reference !== void 0 ? { businessReference: args.business_reference } : {}
+  };
+  try {
+    const response = await fetch(`${ctx.env.CARRIER_API_BASE_URL ?? "https://api.carrier.llc"}/v1/subscribers/issue-from-inventory`, {
+      method: "POST",
+      redirect: "error",
+      headers: { "Authorization": `Bearer ${token2}`, "Content-Type": "application/json", "X-Idempotency-Key": String(key) },
+      body: JSON.stringify(body2)
+    });
+    const payload = await response.json();
+    if (!payload || typeof payload !== "object" || Array.isArray(payload) || response.ok && !payload.data) throw new Error("Malformed API response");
+    if (response.status >= 500 && payload.code !== "OUTCOME_UNKNOWN" && payload.upstream_dispatched !== false) {
+      return error("OUTCOME_UNKNOWN", "Issuance outcome is unknown. Preserve this request_key for reconciliation; do not issue with a new key.", { api_error: payload });
+    }
+    return { ...!response.ok ? { isError: true } : {}, content: [{ type: "text", text: JSON.stringify({ ...payload, request_key: key }) }] };
+  } catch {
+    return error("OUTCOME_UNKNOWN", "Issuance outcome is unknown. Preserve this request_key for reconciliation; do not issue with a new key.");
+  }
+}
+
+// src/tools.ts
 import * as Sentry from "@sentry/cloudflare";
 
+// src/ocs-scoping.ts
+function positiveAccountId(raw) {
+  if (typeof raw !== "number" && (typeof raw !== "string" || !/^[1-9]\d*$/.test(raw))) return void 0;
+  const id = Number(raw);
+  return Number.isSafeInteger(id) && id > 0 ? id : void 0;
+}
+function tenantAccountIds(auth) {
+  if (auth.managed) {
+    const id = positiveAccountId(auth.accountId);
+    return id === void 0 ? [] : [id];
+  }
+  if (auth.restricted) return (auth.allowedAccountIds ?? []).filter((id) => positiveAccountId(id) !== void 0);
+  if (auth.preferredAccountId !== void 0) {
+    const id = positiveAccountId(auth.preferredAccountId);
+    return id === void 0 ? [] : [id];
+  }
+  return void 0;
+}
+function managedOwnAccountId(auth) {
+  const ids = tenantAccountIds(auth);
+  return ids === void 0 ? void 0 : ids[0] ?? -1;
+}
+function subscriberAccountId(data) {
+  if (!data || typeof data !== "object") return void 0;
+  const root = data;
+  const sub = root.subscriber && typeof root.subscriber === "object" ? root.subscriber : root;
+  const raw = sub.accountId ?? sub.account_id ?? sub.account;
+  if (raw === void 0 || raw === null) return void 0;
+  return positiveAccountId(raw);
+}
+function isManagedSubscriberDenied(auth, subscriberData) {
+  const ids = tenantAccountIds(auth);
+  if (ids === void 0) return false;
+  const subAccountId = subscriberAccountId(subscriberData);
+  return subAccountId === void 0 || !ids.includes(subAccountId);
+}
+async function assertManagedIccidAccess(baseUrl2, auth, iccid) {
+  const ids = tenantAccountIds(auth);
+  if (ids === void 0) return { ok: true };
+  if (ids.length === 0) return { ok: false, error: "Subscriber not found" };
+  try {
+    const client2 = new OcsClient(baseUrl2, auth.token);
+    const data = await client2.call("getSingleSubscriber", { iccid });
+    if (isManagedSubscriberDenied(auth, data)) {
+      return { ok: false, error: "Subscriber not found" };
+    }
+    return { ok: true };
+  } catch (err9) {
+    return {
+      ok: false,
+      error: err9 instanceof Error ? err9.message : String(err9)
+    };
+  }
+}
+
 // ../../packages/carrier-ai/dist/index.js
 import { AwsClient } from "aws4fetch";
 var AI_TIER_POLICY = {
@@ -1211,8 +1298,19 @@ var DESTRUCTIVE_TOOLS = /* @__PURE__ */ new Set([
   // S6 live-smoke gap fill (CAR-105)
   "change_network_profile_of_location_zone"
 ]);
+function assignPackageRefusal(args) {
+  const hasIccid = typeof args.iccid === "string" && args.iccid.trim().length > 0;
+  const conflict = hasIccid && (args.account_for_subs !== void 0 || args.business_reference !== void 0);
+  const invalidKey = !hasIccid && (typeof args.request_key !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/.test(args.request_key));
+  if (conflict || invalidKey) return { isError: true, content: [{ type: "text", text: JSON.stringify({
+    code: conflict ? "INVALID_ASSIGN_PACKAGE_INPUT" : "IDEMPOTENCY_KEY_REQUIRED",
+    message: conflict ? "iccid and inventory/business reference are mutually exclusive. No changes made." : "Inventory requires a stable request_key (1\u2013200 characters: letters, digits, underscore, dot, colon, hyphen). No changes made.",
+    request_key: args.request_key
+  }) }] };
+  return void 0;
+}
 function wrapHandler(toolName, ocsMethod, requiredScope, ctx, handler, options) {
-  return async (args) => {
+  return async (args, extra) => {
     const start = Date.now();
     const isDryRun = args.dry_run === true;
     if (!ctx.props.scope.includes(requiredScope)) {
@@ -1256,6 +1354,11 @@ function wrapHandler(toolName, ocsMethod, requiredScope, ctx, handler, options)
         ]
       };
     }
+    const refusal = options?.validateArgs?.(args);
+    if (refusal) {
+      ctx.audit({ tool_name: toolName, ocs_method: ocsMethod, status: "error", dry_run: isDryRun, duration_ms: 0 });
+      return refusal;
+    }
     if (isDryRun && DESTRUCTIVE_TOOLS.has(toolName)) {
       ctx.audit({
         tool_name: toolName,
@@ -1276,8 +1379,9 @@ function wrapHandler(toolName, ocsMethod, requiredScope, ctx, handler, options)
     }
     let result2;
     try {
-      const token2 = await ctx.getUserToken(ctx.props.sub);
-      result2 = await handler(args, token2);
+      const skipToken = typeof options?.skipUserToken === "function" ? options.skipUserToken(args) : options?.skipUserToken;
+      const token2 = skipToken ? "" : await ctx.getUserToken(ctx.props.sub);
+      result2 = extra === void 0 ? await handler(args, token2) : await handler(args, token2, extra);
     } catch (err9) {
       try {
         Sentry.captureException(err9, {
@@ -1792,7 +1896,7 @@ function registerAllTools(server2, ctx) {
       TOOL_SCOPES["modify_subscriber_steering_list"],
       ctx,
       async ({ iccid, steeringListId }, token2) => ocsCall(ctx.env, token2, "modifySubscriberSteeringList", {
-        subscriber: iccid,
+        subscriber: { iccid },
         steeringListId
       })
     )
@@ -1931,16 +2035,21 @@ function registerAllTools(server2, ctx) {
   server2.registerTool(
     "assign_package",
     {
-      title: "Assign Package to Subscriber",
-      description: "Use this to assign a one-time prepaid data/voice package to a subscriber from an existing template. The package is active immediately (or at first usage, depending on template settings). Params: `iccid` (subscriber identifier), `packageTemplateId` (integer from `list_package_templates`), `account_for_subs` (integer, optional \u2014 when provided instead of resolving a subscriber, OCS auto-selects a free eSIM from that account and assigns the package; this is the bulk auto-provisioning path). Returns: created package record with `packageId`, `startDate`, `endDate`, and allowances. Do NOT use this for packages that should auto-renew \u2014 use `assign_recurring_package` instead. Do NOT use this to provision a new subscriber end-to-end \u2014 consider `provision_esim_wizard` for a guided flow with dry-run preview.",
-      inputSchema: {
-        iccid: z.string().describe("The subscriber ICCID"),
-        packageTemplateId: z.number().describe("The package template ID to assign"),
-        account_for_subs: z.number().optional().describe(
-          "Account ID \u2014 when provided, OCS auto-selects a free eSIM from this account for bulk provisioning"
-        ),
+      title: "Assign Package or Issue From Inventory",
+      description: "Assign a one-time prepaid package to an existing subscriber using iccid + packageTemplateId. Inventory issuance uses authenticated Carrier API POST /v1/subscribers/issue-from-inventory with request_key as X-Idempotency-Key. API authorization and its durable ledger are authoritative. Keep the same key after unknown outcomes; never automatically issue with a new key. Do not send both iccid and account_for_subs. Use assign_recurring_package for auto-renew.",
+      inputSchema: z.object({
+        iccid: z.string().optional().describe("Existing subscriber ICCID"),
+        packageTemplateId: z.number().int().positive().describe("The package template ID to assign"),
+        account_for_subs: z.number().int().positive().optional().describe("Inventory account sent as API accountId"),
+        request_key: z.string().max(200).regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]*$/).optional().describe("Required stable inventory key; preserve after unknown outcomes"),
+        startDate: z.string().optional(),
+        endDate: z.string().optional(),
+        validityPeriod: z.number().int().positive().optional(),
+        business_reference: z.object({ kind: z.literal("storefront_order"), id: z.string().min(1), line: z.literal("esim"), verb: z.literal("issue") }).strict().optional().describe("API-authorized existing order reference; not proof of ownership"),
         ...DRY_RUN_FIELD
-      },
+      }).refine((d) => !((d.account_for_subs !== void 0 || d.business_reference !== void 0) && typeof d.iccid === "string" && d.iccid.trim().length > 0), {
+        message: "iccid and account_for_subs are mutually exclusive \u2014 choose one path"
+      }),
       annotations: { destructiveHint: true }
     },
     wrapHandler(
@@ -1948,17 +2057,34 @@ function registerAllTools(server2, ctx) {
       "affectPackageToSubscriber",
       TOOL_SCOPES["assign_package"],
       ctx,
-      async ({ iccid, packageTemplateId, account_for_subs }, token2) => {
-        if (account_for_subs !== void 0) {
-          return ocsCall(ctx.env, token2, "affectPackageToSubscriber", {
-            packageTemplateId,
-            accountForSubs: account_for_subs
-          });
-        }
+      async (args, token2, extra) => {
+        const { iccid, packageTemplateId } = args;
+        if (typeof iccid !== "string" || !iccid.trim()) return issueInventory(ctx, args, extra);
+        const access = await assertManagedIccidAccess(
+          ctx.env.CARRIER_OCS_BASE_URL,
+          { ...ctx.managedAuth, token: token2 },
+          iccid
+        );
+        if (!access.ok) throw new Error(access.error);
         return ocsCall(ctx.env, token2, "affectPackageToSubscriber", {
           subscriber: { iccid },
           packageTemplateId
         });
+      },
+      {
+        validateArgs: assignPackageRefusal,
+        skipUserToken: (args) => typeof args.iccid !== "string" || !args.iccid.trim(),
+        dryRunPayload: (args) => typeof args.iccid === "string" && args.iccid.trim() ? { subscriber: { iccid: args.iccid }, packageTemplateId: args.packageTemplateId } : {
+          method: "POST",
+          path: "/v1/subscribers/issue-from-inventory",
+          headers: { "X-Idempotency-Key": args.request_key },
+          body: {
+            packageTemplateId: args.packageTemplateId,
+            ...args.account_for_subs !== void 0 ? { accountId: args.account_for_subs } : {},
+            ...Object.fromEntries(["startDate", "endDate", "validityPeriod"].filter((k) => args[k] !== void 0).map((k) => [k, args[k]])),
+            ...args.business_reference !== void 0 ? { businessReference: args.business_reference } : {}
+          }
+        }
       }
     )
   );
@@ -10586,45 +10712,6 @@ function buildExamples(toolName) {
 // src/list-recent-ocs-events.ts
 import { z as z16 } from "zod";
 
-// src/ocs-scoping.ts
-function managedOwnAccountId(auth) {
-  if (!auth.managed || auth.accountId === void 0) return void 0;
-  const n = Number(auth.accountId);
-  return Number.isFinite(n) ? n : void 0;
-}
-function subscriberAccountId(data) {
-  if (!data || typeof data !== "object") return void 0;
-  const root = data;
-  const sub = root.subscriber && typeof root.subscriber === "object" ? root.subscriber : root;
-  const raw = sub.accountId ?? sub.account_id ?? sub.account;
-  if (raw === void 0 || raw === null) return void 0;
-  const n = Number(raw);
-  return Number.isFinite(n) ? n : void 0;
-}
-function isManagedSubscriberDenied(auth, subscriberData) {
-  const ownId = managedOwnAccountId(auth);
-  if (ownId === void 0) return false;
-  const subAccountId = subscriberAccountId(subscriberData);
-  if (subAccountId === void 0) return true;
-  return subAccountId !== ownId;
-}
-async function assertManagedIccidAccess(baseUrl2, auth, iccid) {
-  if (managedOwnAccountId(auth) === void 0) return { ok: true };
-  try {
-    const client2 = new OcsClient(baseUrl2, auth.token);
-    const data = await client2.call("getSingleSubscriber", { iccid });
-    if (isManagedSubscriberDenied(auth, data)) {
-      return { ok: false, error: "Subscriber not found" };
-    }
-    return { ok: true };
-  } catch (err9) {
-    return {
-      ok: false,
-      error: err9 instanceof Error ? err9.message : String(err9)
-    };
-  }
-}
-
 // ../../packages/ocs-spec/src/ocs-event-buffer-read.ts
 var LIFECYCLE_RESELLER_ID2 = 1170;
 function ocsEventRingBufferIccidFromDigitsReference(raw) {
@@ -12857,13 +12944,14 @@ function registerUiAgentGenericTools(server2, ctx, runtime) {
 // src/index.ts
 var baseUrl = process.env.CARRIER_OCS_BASE_URL ?? process.env.ESIMVAULT_BASE_URL ?? "https://ocs.esimvault.cloud";
 var token = process.env.CARRIER_OCS_API_TOKEN ?? process.env.ESIMVAULT_API_TOKEN;
-if (!token) {
+if (!token && !process.env.CARRIER_API_TOKEN) {
   console.error(
-    "ERROR: CARRIER_OCS_API_TOKEN (or legacy ESIMVAULT_API_TOKEN) must be set."
+    "ERROR: Set CARRIER_API_TOKEN for durable inventory or CARRIER_OCS_API_TOKEN for explicit OCS tools."
   );
   process.exit(1);
 }
 var stdioEnv = {
+  CARRIER_API_BASE_URL: process.env.CARRIER_API_BASE_URL ?? "https://api.carrier.llc",
   CARRIER_OCS_BASE_URL: baseUrl,
   // Empty on purpose. rotate_credentials reads this and throws a clear
   // message rather than pretending a local install can rotate the vault.
@@ -12931,13 +13019,17 @@ var props = {
 };
 var audit = (_row) => {
 };
-var getUserToken = async (_sub) => token;
+var getUserToken = async (_sub) => {
+  if (!token) throw new Error("CARRIER_OCS_API_TOKEN is required for explicit OCS tools");
+  return token;
+};
 var toolCtx = {
   env: stdioEnv,
   props,
   managedAuth: {},
   audit,
-  getUserToken
+  getUserToken,
+  getApiToken: async () => process.env.CARRIER_API_TOKEN || void 0
 };
 var server = new McpServer(
   { name: "carrier-mcp", version: CARRIER_VERSION },