@carrierllc/mcp 0.13.0 → 0.13.4

package/dist/index.js

@@ -34,18 +34,22 @@ import {
   lastNDaysPeriod,
   loadStorefrontBrand,
   locationParams,
+  locationZoneCreateParams,
   mccToIso,
   mergeEnvLocal,
   networkEventRows,
   networkEventsOverPeriodParams,
-  normalizePackageTemplate,
-  normalizePackageTemplateChanges,
+  ocsHlrBitrate,
+  ocsHlrBitrateFromBps,
   ocsLocalDateTime,
+  ocsSimStatus,
   packageActivePeriodParams,
   packageDataLimit,
   packageDataUsed,
   packageExpiry,
   packageName,
+  packageTemplateCreateFromToolJson,
+  packageTemplateModifyFromToolJson,
   prepaidPackageLimits,
   prepaidPackageRows,
   probeAll,
@@ -65,7 +69,7 @@ import {
   usageOverPeriodParams,
   verifyStorefront,
   withOcsListSummary
-} from "./chunk-ZUUC3J4J.js";
+} from "./chunk-DUAXD7GD.js";
 import "./chunk-SHKKVIIA.js";
 
 // src/index.ts
@@ -1565,10 +1569,10 @@ function registerAllTools(server2, ctx) {
     "change_sim_status",
     {
       title: "Change SIM Status",
-      description: "Use this to change the physical SIM/eSIM card status at the SIM provider level, independent of the OCS subscriber lifecycle status. Statuses: ENABLED (normal operation), DISABLED (blocked at network level, subscriber cannot connect), DELETED (irrecoverably removes the SIM profile \u2014 use only to decommission). WARNING: DELETED is irreversible. Always use `dry_run=true` first. Internally resolves ICCID \u2192 numeric simId via a getSingleSubscriber call before forwarding to OCS. Params: `iccid` (subscriber identifier), `simStatus` ('ENABLED' | 'DISABLED' | 'DELETED'). Returns: updated SIM record with new status. Do NOT use this to change the subscriber's OCS lifecycle status \u2014 use `modify_subscriber_status`. Do NOT confuse DISABLED (reversible) with DELETED (irreversible).",
+      description: "Use this to change the physical SIM/eSIM card status at the SIM provider level, independent of the OCS subscriber lifecycle status. Statuses: ENABLED maps to OCS Affected (normal operation) and DISABLED maps to OCS Free (blocked at the network). DELETED is not a changeSimStatus value. Always use `dry_run=true` first. Internally resolves ICCID \u2192 numeric simId via a getSingleSubscriber call before forwarding to OCS. Params: `iccid` (subscriber identifier), `simStatus` ('ENABLED' | 'DISABLED'). Returns: updated SIM record with new status. Do NOT use this to change the subscriber's OCS lifecycle status \u2014 use `modify_subscriber_status`. Do NOT send DELETED.",
       inputSchema: {
         iccid: z.string().describe("The subscriber ICCID"),
-        simStatus: z.string().describe("New SIM status (e.g. ENABLED, DISABLED, DELETED)"),
+        simStatus: z.string().describe("New SIM status: ENABLED (OCS Affected) or DISABLED (OCS Free)"),
         ...DRY_RUN_FIELD
       },
       annotations: { destructiveHint: true }
@@ -1579,9 +1583,16 @@ function registerAllTools(server2, ctx) {
       TOOL_SCOPES["change_sim_status"],
       ctx,
       async ({ iccid, simStatus }, token2) => {
+        const newStatus = ocsSimStatus(simStatus);
+        if (typeof newStatus !== "string") {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `Error: ${newStatus.error}` }]
+          };
+        }
         const cache = /* @__PURE__ */ new Map();
         const sub = await resolveSubscriberByIccid(ctx.env, token2, iccid, cache);
-        const simId = Number(sub.simId ?? sub.sim_id ?? sub.id);
+        const simId = subscriberSimId(sub);
         if (simId === void 0) {
           return {
             isError: true,
@@ -1589,8 +1600,8 @@ function registerAllTools(server2, ctx) {
           };
         }
         return ocsCall(ctx.env, token2, "changeSimStatus", {
-          simId: Number(simId),
-          newStatus: simStatus
+          simId,
+          newStatus
         });
       }
     )
@@ -1613,14 +1624,14 @@ function registerAllTools(server2, ctx) {
       async ({ iccid }, token2) => {
         const cache = /* @__PURE__ */ new Map();
         const sub = await resolveSubscriberByIccid(ctx.env, token2, iccid, cache);
-        const simId = Number(sub.simId ?? sub.sim_id ?? sub.id);
+        const simId = subscriberSimId(sub);
         if (simId === void 0) {
           return {
             isError: true,
             content: [{ type: "text", text: `Error: Could not resolve simId for ICCID ${iccid}` }]
           };
         }
-        return ocsCall(ctx.env, token2, "getSimProviderStatus", Number(simId));
+        return ocsCall(ctx.env, token2, "getSimProviderStatus", simId);
       }
     )
   );
@@ -1758,10 +1769,10 @@ function registerAllTools(server2, ctx) {
     "hlr_set_bitrate",
     {
       title: "Set HLR Bitrate",
-      description: "Use this to set a hard bandwidth cap for a subscriber at the HLR (Home Location Register) level. This is a network-level throttle applied regardless of package allowance \u2014 use it to enforce fair-use speed limits or to throttle heavy users without suspending service. Provide at least one of `bitrate` (numeric bps) or `bitrate_string` (OCS string enum); when both are provided, `bitrate_string` is used. String enum values: KB_32, KB_64, KB_128, KB_256, KB_384, KB_512, KB_1024, KB_2048, KB_3072, KB_5120, KB_7680, KB_10240, KB_20480, KB_51200, KB_102400, UNLIMITED. Numeric equivalents: 256000 (256 kbps throttle), 1000000 (1 Mbps), 0 (remove limit). Internally resolves ICCID \u2192 IMSI via a getSingleSubscriber lookup. Params: `iccid` (subscriber identifier), `bitrate` (integer, bits-per-second) OR `bitrate_string` (string enum from the list above). Returns: HLR confirmation with the applied bitrate. Do NOT use this to block data entirely \u2014 use `set_subscriber_traffic_restrictions` with `dataAllowed=false`. Do NOT use this to change throttling thresholds on a package template \u2014 use `modify_template_throttling`.",
+      description: "Use this to set a hard bandwidth cap for a subscriber at the HLR (Home Location Register) level. This is a network-level throttle applied regardless of package allowance \u2014 use it to enforce fair-use speed limits or to throttle heavy users without suspending service. Provide at least one of `bitrate` (bits per second) or `bitrate_string` (OCS string enum); when both are provided, `bitrate_string` is used. The wire value is only the string enum: KB_32, KB_64, KB_128, KB_256, KB_384, KB_512, KB_1024, KB_2048, KB_3072, KB_5120, KB_7680, KB_10240, KB_20480, KB_51200, KB_102400, UNLIMITED. A bits-per-second number is mapped onto that enum (256000 is KB_256, 1024000 is KB_1024). 0 is UNLIMITED. Any other number is refused before OCS. Internally resolves ICCID \u2192 IMSI via a getSingleSubscriber lookup. Params: `iccid` (subscriber identifier), `bitrate` (integer bits per second) OR `bitrate_string` (string enum from the list above). Returns: HLR confirmation with the applied bitrate. Do NOT use this to block data entirely \u2014 use `set_subscriber_traffic_restrictions` with `dataAllowed=false`. Do NOT use this to change throttling thresholds on a package template \u2014 use `modify_template_throttling`.",
       inputSchema: z.object({
         iccid: z.string().describe("The subscriber ICCID"),
-        bitrate: z.number().optional().describe("Max bitrate in bps (numeric form; use 0 to remove limit)"),
+        bitrate: z.number().optional().describe("Max bitrate in bits per second. 256000 is KB_256. 0 is UNLIMITED."),
         bitrate_string: z.enum([
           "KB_32",
           "KB_64",
@@ -1793,6 +1804,13 @@ function registerAllTools(server2, ctx) {
       TOOL_SCOPES["hlr_set_bitrate"],
       ctx,
       async ({ iccid, bitrate, bitrate_string }, token2) => {
+        const limit = bitrate_string !== void 0 ? ocsHlrBitrate(bitrate_string) : ocsHlrBitrateFromBps(bitrate ?? Number.NaN);
+        if (typeof limit !== "string") {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `Error: ${limit.error}` }]
+          };
+        }
         const cache = /* @__PURE__ */ new Map();
         const sub = await resolveSubscriberByIccid(ctx.env, token2, iccid, cache);
         const imsi = imsiFromSubscriberRecord(sub);
@@ -1802,7 +1820,6 @@ function registerAllTools(server2, ctx) {
             content: [{ type: "text", text: `Error: Could not resolve IMSI for ICCID ${iccid}` }]
           };
         }
-        const limit = bitrate_string !== void 0 ? bitrate_string : bitrate;
         return ocsCall(ctx.env, token2, "hlrSetBitrate", { imsi, limit });
       }
     )
@@ -2138,7 +2155,7 @@ function registerAllTools(server2, ctx) {
     "create_package_template",
     {
       title: "Create Package Template",
-      description: 'Use this to create a new prepaid package template in the product catalog. Templates define allowances, pricing, location zones, validity, and throttling thresholds that are reused each time the template is assigned to a subscriber. Params: `template` (full template configuration as a JSON string \u2014 fields include `name`, `dataLimit` in bytes, `price`, `validityDays`, `locationZoneId`, `recurring`, `throttlingActive`). NEVER express an unlimited plan as a zero data allowance: OCS reads 0 as a literal zero, and because `throttlingThreshold1Perc` is a percentage OF THE BUNDLE, a zero bundle leaves the throttle trigger uncomputable and every storefront renders "0 MB". Describe the plan as it is sold and the OCS fields are derived for you: `unlimited: true`, `throttleAfterMb` (the full-speed window, e.g. 500 for "500 MB/day"), `throttleKbps` (the speed AFTER that window) and `perioddays` (1 for a daily bucket). The bundle ceiling is sized so the window is a whole trigger percentage and the bundle cannot be drained even at the throttled rate for the whole period, because a plan sold as unlimited must not run out. `throttleKbps` is a SPEED and must be an OCS bitrate (128, 256, 384, 512, 1024, 3072, 5120, 7680, 10240, 20480, 51200, 102400); passing megabytes here is rejected. Returns: created template record with the new `templateId`. Do NOT use this to modify an existing template \u2014 use `modify_template_core`. After creation, call `list_package_templates` to confirm the template is visible.',
+      description: 'Use this to create a new prepaid package template in the product catalog. Templates define allowances, cost, location zones, validity, and throttling thresholds that are reused each time the template is assigned to a subscriber. Params: `template` (full template configuration as a JSON string). OCS accepts `prepaidpackagetemplatename`, `databyte`, `perioddays`, `locationzoneid`, `cost`, `recurring`, and `throttlingActive`. `name` maps to prepaidpackagetemplatename, `dataLimit` maps to databyte, `validityDays` maps to perioddays, and `locationZoneId` maps to locationzoneid. There is no `price` field and no `description` field. NEVER express an unlimited plan as a zero data allowance: OCS reads 0 as a literal zero, and because `throttlingThreshold1Perc` is a percentage OF THE BUNDLE, a zero bundle leaves the throttle trigger uncomputable and every storefront renders "0 MB". Describe the plan as it is sold and the OCS fields are derived for you: `unlimited: true`, `throttleAfterMb` (the full-speed window, e.g. 500 for "500 MB/day"), `throttleKbps` (the speed AFTER that window) and `perioddays` (1 for a daily bucket). The bundle ceiling is sized so the window is a whole trigger percentage and the bundle cannot be drained even at the throttled rate for the whole period, because a plan sold as unlimited must not run out. `throttleKbps` is a SPEED and must be an OCS bitrate (128, 256, 384, 512, 1024, 3072, 5120, 7680, 10240, 20480, 51200, 102400); passing megabytes here is rejected. Returns: created template record with the new `templateId`. Do NOT use this to modify an existing template \u2014 use `modify_template_core`. After creation, call `list_package_templates` to confirm the template is visible.',
       inputSchema: {
         template: z.string().describe("Full template configuration as JSON string"),
         ...DRY_RUN_FIELD
@@ -2150,19 +2167,23 @@ function registerAllTools(server2, ctx) {
       "createPrepaidPackageTemplate",
       TOOL_SCOPES["create_package_template"],
       ctx,
-      async ({ template }, token2) => ocsCall(
-        ctx.env,
-        token2,
-        "createPrepaidPackageTemplate",
-        normalizePackageTemplate(JSON.parse(template))
-      )
+      async ({ template }, token2) => {
+        const params = packageTemplateCreateFromToolJson(template);
+        if ("error" in params) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `Error: ${params.error}` }]
+          };
+        }
+        return ocsCall(ctx.env, token2, "createPrepaidPackageTemplate", params);
+      }
     )
   );
   server2.registerTool(
     "modify_template_core",
     {
       title: "Modify Template Core Settings",
-      description: 'Use this to change the core fields of an existing package template: name, data/voice/SMS limits, pricing, validity period, and location zone. Changes affect future package assignments from this template but do NOT retroactively change packages already assigned to subscribers. Params: `templateId` (integer from `list_package_templates`), `changes` (JSON string with fields to modify, e.g. {"name": "Europe 5GB", "dataLimit": 5368709120}). Returns: updated template record. Do NOT use this to modify throttling thresholds \u2014 use `modify_template_throttling`. Do NOT use this to modify recurring/renewal settings \u2014 use `modify_template_recurring`.',
+      description: 'Use this to change the core fields of an existing package template: name, data/voice/SMS limits, pricing, validity period, and location zone. Changes affect future package assignments from this template but do NOT retroactively change packages already assigned to subscribers. Params: `templateId` (integer from `list_package_templates`), `changes` (JSON string with fields to modify, e.g. {"name": "Europe 5GB", "dataLimit": 5368709120}). `name` maps to prepaidpackagetemplatename and `dataLimit` maps to databyte. A template id inside `changes` is ignored so the `templateId` argument wins. There is no `price` field and no `description` field. Returns: updated template record. Do NOT use this to modify throttling thresholds \u2014 use `modify_template_throttling`. Do NOT use this to modify recurring/renewal settings \u2014 use `modify_template_recurring`.',
       inputSchema: {
         templateId: z.number().describe("The template ID"),
         changes: z.string().describe("Core fields to modify as JSON string"),
@@ -2175,17 +2196,25 @@ function registerAllTools(server2, ctx) {
       "modifyPPTCore",
       TOOL_SCOPES["modify_template_core"],
       ctx,
-      async ({ templateId, changes }, token2) => ocsCall(ctx.env, token2, "modifyPPTCore", {
-        templateId,
-        ...normalizePackageTemplateChanges(JSON.parse(changes))
-      })
+      async ({ templateId, changes }, token2) => {
+        const mapped = packageTemplateModifyFromToolJson(changes, "modifyPPTCore");
+        if ("error" in mapped) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `Error: ${mapped.error}` }]
+          };
+        }
+        const wire = mapped;
+        wire.templateId = templateId;
+        return ocsCall(ctx.env, token2, "modifyPPTCore", wire);
+      }
     )
   );
   server2.registerTool(
     "modify_template_recurring",
     {
       title: "Modify Template Recurring Settings",
-      description: 'Use this to change the auto-renewal configuration of a package template: periodicity (daily/weekly/monthly), occurrence count, and renewal trigger conditions. Changes affect future assignments and existing recurring packages assigned from this template. Params: `templateId` (integer from `list_package_templates`), `changes` (JSON string with recurring fields, e.g. {"periodicity": "monthly", "occurrences": 12}). Returns: updated template record with new recurring settings. Do NOT use this to stop an individual subscriber\'s recurring renewal \u2014 use `stop_resume_recurring_package`. Do NOT use this to change core template fields like data limits \u2014 use `modify_template_core`.',
+      description: 'Use this to change the auto-renewal configuration of a package template: periodicity (daily/weekly/monthly), occurrence count, and renewal trigger conditions. Changes affect future assignments and existing recurring packages assigned from this template. Params: `templateId` (integer from `list_package_templates`), `changes` (JSON string with recurring fields, e.g. {"periodicity": "monthly", "occurrences": 12}). `periodicity` maps to recurringPeriodicityType (0 daily, 1 weekly, 2 monthly) and `occurrences` maps to nbOccurrence. Returns: updated template record with new recurring settings. Do NOT use this to stop an individual subscriber\'s recurring renewal \u2014 use `stop_resume_recurring_package`. Do NOT use this to change core template fields like data limits \u2014 use `modify_template_core`.',
       inputSchema: {
         templateId: z.number().describe("The template ID"),
         changes: z.string().describe("Recurring fields to modify as JSON string"),
@@ -2198,17 +2227,25 @@ function registerAllTools(server2, ctx) {
       "modifyPPTRecurring",
       TOOL_SCOPES["modify_template_recurring"],
       ctx,
-      async ({ templateId, changes }, token2) => ocsCall(ctx.env, token2, "modifyPPTRecurring", {
-        templateId,
-        ...JSON.parse(changes)
-      })
+      async ({ templateId, changes }, token2) => {
+        const mapped = packageTemplateModifyFromToolJson(changes, "modifyPPTRecurring");
+        if ("error" in mapped) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `Error: ${mapped.error}` }]
+          };
+        }
+        const wire = mapped;
+        wire.templateId = templateId;
+        return ocsCall(ctx.env, token2, "modifyPPTRecurring", wire);
+      }
     )
   );
   server2.registerTool(
     "modify_template_throttling",
     {
       title: "Modify Template Throttling",
-      description: 'Use this to change the bandwidth throttling thresholds on a package template. WARNING: changes apply immediately to ALL existing subscriber packages created from this template, not just future ones. Setting a lower threshold will NOT retroactively throttle subscribers already below the new threshold (the system does not re-check existing usage). Params: `templateId` (integer), `changes` (JSON string with throttling fields, e.g. {"throttlingActive": true, "firstThresholdPercent": 80, "firstThresholdLimitKbps": 1024, "errorAction": "continue_unthrottled"}). Returns: updated template record with new throttling configuration. Do NOT use this to throttle a single subscriber \u2014 use `hlr_set_bitrate` instead. Do NOT use this to change core package limits \u2014 use `modify_template_core`.',
+      description: 'Use this to change the bandwidth throttling thresholds on a package template. WARNING: changes apply immediately to ALL existing subscriber packages created from this template, not just future ones. Setting a lower threshold will NOT retroactively throttle subscribers already below the new threshold (the system does not re-check existing usage). Params: `templateId` (integer), `changes` (JSON string with throttling fields, e.g. {"throttlingActive": true, "throttlingThreshold1Perc": 80, "throttlingThreshold1Limit": 1024}). `firstThresholdPercent` maps to throttlingThreshold1Perc and `firstThresholdLimitKbps` maps to throttlingThreshold1Limit. `throttlingErrorAction` is an integer; continue_unthrottled is refused. Returns: updated template record with new throttling configuration. Do NOT use this to throttle a single subscriber \u2014 use `hlr_set_bitrate` instead. Do NOT use this to change core package limits \u2014 use `modify_template_core`.',
       inputSchema: {
         templateId: z.number().describe("The template ID"),
         changes: z.string().describe("Throttling fields to modify as JSON string"),
@@ -2221,10 +2258,18 @@ function registerAllTools(server2, ctx) {
       "modifyPPTThrottling",
       TOOL_SCOPES["modify_template_throttling"],
       ctx,
-      async ({ templateId, changes }, token2) => ocsCall(ctx.env, token2, "modifyPPTThrottling", {
-        templateId,
-        ...JSON.parse(changes)
-      })
+      async ({ templateId, changes }, token2) => {
+        const mapped = packageTemplateModifyFromToolJson(changes, "modifyPPTThrottling");
+        if ("error" in mapped) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `Error: ${mapped.error}` }]
+          };
+        }
+        const wire = mapped;
+        wire.templateId = templateId;
+        return ocsCall(ctx.env, token2, "modifyPPTThrottling", wire);
+      }
     )
   );
   server2.registerTool(
@@ -2302,7 +2347,7 @@ function registerAllTools(server2, ctx) {
     "create_location_zone",
     {
       title: "Create Location Zone",
-      description: "Use this to create a new location zone \u2014 a named collection of countries and operators that defines where a package can be used. Location zones are required when creating package templates. Use `list_network_profiles` to find valid operator identifiers to include. Params: `zone` (full zone configuration as a JSON string \u2014 fields include `name`, `countries` (array of ISO country codes), `operators` (array of MCC-MNC strings)). Returns: created zone record with the new `locationZoneId`. Do NOT use this to modify an existing zone \u2014 no edit tool exists yet (gap G-19, pending eSIMVault). After creation, verify with `list_detailed_location_zones`.",
+      description: "Use this to create a new location zone \u2014 a named collection of countries and operators that defines where a package can be used. Location zones are required when creating package templates. OCS accepts locationZoneName, tadigList (TADIG codes), and networkProfileId. Params: `zone` (JSON string). `name` is an alias of locationZoneName and `tadigs` is an alias of tadigList. ISO country codes and MCC-MNC operator ids are not TADIG codes and are refused. Use `list_network_profiles` for a networkProfileId. Returns: created zone record with the new `locationZoneId`. Do NOT use this to modify an existing zone \u2014 no edit tool exists yet (gap G-19, pending eSIMVault). After creation, verify with `list_detailed_location_zones`.",
       inputSchema: {
         zone: z.string().describe("Zone configuration as JSON string"),
         ...DRY_RUN_FIELD
@@ -2314,12 +2359,16 @@ function registerAllTools(server2, ctx) {
       "createLocationZone",
       TOOL_SCOPES["create_location_zone"],
       ctx,
-      async ({ zone }, token2) => ocsCall(
-        ctx.env,
-        token2,
-        "createLocationZone",
-        JSON.parse(zone)
-      )
+      async ({ zone }, token2) => {
+        const params = locationZoneCreateParams(zone);
+        if ("error" in params) {
+          return {
+            isError: true,
+            content: [{ type: "text", text: `Error: ${params.error}` }]
+          };
+        }
+        return ocsCall(ctx.env, token2, "createLocationZone", params);
+      }
     )
   );
   server2.registerTool(
@@ -12124,11 +12173,9 @@ if (!token) {
 }
 var stdioEnv = {
   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.
   CARRIER_TOKEN_ENCRYPTION_KEY: "",
-  SENTRY_DSN: "",
-  CLERK_PUBLISHABLE_KEY: "",
-  CLERK_SECRET_KEY: "",
-  CLERK_WEBHOOK_SECRET: "",
   AUDIT_LOG: { writeDataPoint: (_) => void 0 },
   OAUTH_KV: null,
   OCS_EVENT_ROUTING: null,
@@ -12168,7 +12215,8 @@ var stdioEnv = {
   // has already opted in, and making them set a second variable they have never
   // heard of is just the same dead gate one step further along. Setting it to
   // anything other than "true" still turns the router off.
-  CARRIER_ASK_ENABLED: process.env.CARRIER_ASK_ENABLED ?? "true"
+  CARRIER_ASK_ENABLED: process.env.CARRIER_ASK_ENABLED ?? "true",
+  BILLING_PRIMARY: process.env.BILLING_PRIMARY
 };
 var props = {
   sub: "stdio@local",