@carrierllc/mcp 0.10.7 → 0.11.4

package/dist/index.js

@@ -27,12 +27,14 @@ import {
   generateStorefrontLogo,
   getLimitForEndpoint,
   getRateLimitWindowCounts,
+  gyCountryHistoryFromResponse,
   imsiFromSubscriberRecord,
   isActivePackage,
   isTargetId,
   lastNDaysPeriod,
   loadStorefrontBrand,
   locationParams,
+  mccToIso,
   mergeEnvLocal,
   networkEventRows,
   networkEventsOverPeriodParams,
@@ -54,6 +56,7 @@ import {
   recurringPackageParams,
   renderHtml,
   repairPlanFor,
+  staleActivePackages,
   storefrontClerkUrls,
   subscriberIdParams,
   subscriberRows,
@@ -62,7 +65,7 @@ import {
   usageOverPeriodParams,
   verifyStorefront,
   withOcsListSummary
-} from "./chunk-KYS5GHJV.js";
+} from "./chunk-625SBKRG.js";
 import "./chunk-SHKKVIIA.js";
 
 // src/index.ts
@@ -3507,506 +3510,44 @@ var ocs_methods_default = {
       ui_resource_uri: "ui://balance-topup-form",
       verified_against_server: false,
       verified_against_live_docs: false
+    },
+    {
+      name: "subscriber_investigator_app",
+      category: "apps",
+      scope: "read",
+      description: "MCP App: Subscriber Investigator \u2014 single-subscriber drill-down panel (identity, packages, usage, network events). Read-only, no destructive ops.",
+      min_tier: "free",
+      destructive: false,
+      ui_resource_uri: "ui://apps/subscriber-investigator",
+      verified_against_server: false,
+      verified_against_live_docs: false
+    },
+    {
+      name: "template_zone_builder_app",
+      category: "apps",
+      scope: "write",
+      description: "MCP App: Template & Zone Builder \u2014 multi-step builder for a package template or location zone, with a preview step before the confirm write. Pro tier minimum; refused for managed sessions at the OCS scope layer.",
+      min_tier: "pro",
+      destructive: true,
+      destructive_step: 4,
+      ui_resource_uri: "ui://apps/template-builder",
+      verified_against_server: false,
+      verified_against_live_docs: false
+    },
+    {
+      name: "action_receipt_app",
+      category: "apps",
+      scope: "write",
+      description: "MCP App: Action Receipt & Rollback Viewer \u2014 ledger of recorded write actions with verification evidence and rollback where a rollback method was recorded. Viewing/recording needs no OCS write; rollback requires write scope.",
+      min_tier: "free",
+      destructive: true,
+      ui_resource_uri: "ui://apps/action-receipt",
+      verified_against_server: false,
+      verified_against_live_docs: false
     }
   ]
 };
 
-// ../../packages/ocs-spec/src/mcc-iso.ts
-var MCC_TO_ISO = {
-  // Europe
-  202: "GR",
-  // Greece
-  204: "NL",
-  // Netherlands
-  206: "BE",
-  // Belgium
-  208: "FR",
-  // France
-  212: "MC",
-  // Monaco
-  213: "AD",
-  // Andorra
-  214: "ES",
-  // Spain
-  216: "HU",
-  // Hungary
-  218: "BA",
-  // Bosnia and Herzegovina
-  219: "HR",
-  // Croatia
-  220: "RS",
-  // Serbia
-  221: "XK",
-  // Kosovo
-  222: "IT",
-  // Italy
-  225: "VA",
-  // Vatican City
-  226: "RO",
-  // Romania
-  228: "CH",
-  // Switzerland
-  230: "CZ",
-  // Czech Republic
-  231: "SK",
-  // Slovakia
-  232: "AT",
-  // Austria
-  234: "GB",
-  // United Kingdom
-  235: "GB",
-  // United Kingdom
-  238: "DK",
-  // Denmark
-  240: "SE",
-  // Sweden
-  242: "NO",
-  // Norway
-  244: "FI",
-  // Finland
-  246: "LT",
-  // Lithuania
-  247: "LV",
-  // Latvia
-  248: "EE",
-  // Estonia
-  250: "RU",
-  // Russia
-  255: "UA",
-  // Ukraine
-  257: "BY",
-  // Belarus
-  259: "MD",
-  // Moldova
-  260: "PL",
-  // Poland
-  262: "DE",
-  // Germany
-  266: "GI",
-  // Gibraltar
-  268: "PT",
-  // Portugal
-  270: "LU",
-  // Luxembourg
-  272: "IE",
-  // Ireland
-  274: "IS",
-  // Iceland
-  276: "AL",
-  // Albania
-  278: "MT",
-  // Malta
-  280: "CY",
-  // Cyprus
-  282: "GE",
-  // Georgia
-  283: "AM",
-  // Armenia
-  284: "BG",
-  // Bulgaria
-  286: "TR",
-  // Turkey
-  288: "FO",
-  // Faroe Islands
-  289: "GE",
-  // Abkhazia (Georgia)
-  290: "GL",
-  // Greenland
-  292: "SM",
-  // San Marino
-  293: "SI",
-  // Slovenia
-  294: "MK",
-  // North Macedonia
-  295: "LI",
-  // Liechtenstein
-  297: "ME",
-  // Montenegro
-  // Commonwealth of Independent States / Former USSR
-  401: "KZ",
-  // Kazakhstan
-  402: "BT",
-  // Bhutan
-  404: "IN",
-  // India
-  405: "IN",
-  // India
-  406: "IN",
-  // India
-  410: "PK",
-  // Pakistan
-  412: "AF",
-  // Afghanistan
-  413: "LK",
-  // Sri Lanka
-  414: "MM",
-  // Myanmar
-  415: "LB",
-  // Lebanon
-  416: "JO",
-  // Jordan
-  417: "SY",
-  // Syria
-  418: "IQ",
-  // Iraq
-  419: "KW",
-  // Kuwait
-  420: "SA",
-  // Saudi Arabia
-  421: "YE",
-  // Yemen
-  422: "OM",
-  // Oman
-  424: "AE",
-  // United Arab Emirates
-  425: "IL",
-  // Israel
-  426: "BH",
-  // Bahrain
-  427: "QA",
-  // Qatar
-  428: "MN",
-  // Mongolia
-  429: "NP",
-  // Nepal
-  430: "AE",
-  // United Arab Emirates
-  431: "AE",
-  // United Arab Emirates
-  432: "IR",
-  // Iran
-  434: "UZ",
-  // Uzbekistan
-  436: "TJ",
-  // Tajikistan
-  437: "KG",
-  // Kyrgyzstan
-  438: "TM",
-  // Turkmenistan
-  440: "JP",
-  // Japan
-  441: "JP",
-  // Japan
-  450: "KR",
-  // South Korea
-  452: "VN",
-  // Vietnam
-  454: "HK",
-  // Hong Kong
-  455: "MO",
-  // Macau
-  456: "KH",
-  // Cambodia
-  457: "LA",
-  // Laos
-  460: "CN",
-  // China
-  461: "CN",
-  // China
-  466: "TW",
-  // Taiwan
-  467: "KP",
-  // North Korea
-  470: "BD",
-  // Bangladesh
-  472: "MV",
-  // Maldives
-  502: "MY",
-  // Malaysia
-  505: "AU",
-  // Australia
-  510: "ID",
-  // Indonesia
-  514: "TL",
-  // East Timor
-  515: "PH",
-  // Philippines
-  520: "TH",
-  // Thailand
-  525: "SG",
-  // Singapore
-  528: "BN",
-  // Brunei
-  530: "NZ",
-  // New Zealand
-  536: "NR",
-  // Nauru
-  537: "PG",
-  // Papua New Guinea
-  539: "TO",
-  // Tonga
-  540: "SB",
-  // Solomon Islands
-  541: "VU",
-  // Vanuatu
-  542: "FJ",
-  // Fiji
-  544: "AS",
-  // American Samoa
-  545: "KI",
-  // Kiribati
-  546: "NC",
-  // New Caledonia
-  547: "PF",
-  // French Polynesia
-  548: "CK",
-  // Cook Islands
-  549: "WS",
-  // Samoa
-  550: "FM",
-  // Micronesia
-  551: "MH",
-  // Marshall Islands
-  552: "PW",
-  // Palau
-  553: "TV",
-  // Tuvalu
-  555: "NU",
-  // Niue
-  // Africa (ITU-T E.212)
-  602: "EG",
-  // Egypt
-  603: "DZ",
-  // Algeria
-  604: "MA",
-  // Morocco
-  605: "TN",
-  // Tunisia
-  606: "LY",
-  // Libya
-  607: "GM",
-  // Gambia
-  608: "SN",
-  // Senegal
-  609: "MR",
-  // Mauritania
-  610: "ML",
-  // Mali
-  611: "GN",
-  // Guinea
-  612: "CI",
-  // Côte d'Ivoire
-  613: "BF",
-  // Burkina Faso
-  614: "NE",
-  // Niger
-  615: "TG",
-  // Togo
-  616: "BJ",
-  // Benin
-  617: "MU",
-  // Mauritius
-  618: "LR",
-  // Liberia
-  619: "SL",
-  // Sierra Leone
-  620: "GH",
-  // Ghana
-  621: "NG",
-  // Nigeria
-  622: "TD",
-  // Chad
-  623: "CF",
-  // Central African Republic
-  624: "CM",
-  // Cameroon
-  625: "CV",
-  // Cape Verde
-  626: "ST",
-  // São Tomé and Príncipe
-  627: "GQ",
-  // Equatorial Guinea
-  628: "GA",
-  // Gabon
-  629: "CG",
-  // Republic of the Congo
-  630: "CD",
-  // Democratic Republic of the Congo
-  631: "AO",
-  // Angola
-  632: "GW",
-  // Guinea-Bissau
-  633: "SC",
-  // Seychelles
-  634: "SD",
-  // Sudan
-  635: "RW",
-  // Rwanda
-  636: "ET",
-  // Ethiopia
-  637: "SO",
-  // Somalia
-  638: "DJ",
-  // Djibouti
-  639: "KE",
-  // Kenya
-  640: "TZ",
-  // Tanzania
-  641: "UG",
-  // Uganda
-  642: "BI",
-  // Burundi
-  643: "MZ",
-  // Mozambique
-  645: "ZM",
-  // Zambia
-  646: "MG",
-  // Madagascar
-  647: "RE",
-  // Réunion / French Indian Ocean
-  648: "ZW",
-  // Zimbabwe
-  649: "NA",
-  // Namibia
-  650: "MW",
-  // Malawi
-  651: "LS",
-  // Lesotho
-  652: "BW",
-  // Botswana
-  653: "SZ",
-  // Eswatini
-  654: "KM",
-  // Comoros
-  655: "ZA",
-  // South Africa
-  657: "ER",
-  // Eritrea
-  658: "SH",
-  // Saint Helena
-  659: "SS",
-  // South Sudan
-  702: "BZ",
-  // Belize
-  704: "GT",
-  // Guatemala
-  706: "SV",
-  // El Salvador
-  708: "HN",
-  // Honduras
-  710: "NI",
-  // Nicaragua
-  712: "CR",
-  // Costa Rica
-  714: "PA",
-  // Panama
-  716: "PE",
-  // Peru
-  722: "AR",
-  // Argentina
-  724: "BR",
-  // Brazil
-  730: "CL",
-  // Chile
-  732: "CO",
-  // Colombia
-  734: "VE",
-  // Venezuela
-  736: "BO",
-  // Bolivia
-  738: "GY",
-  // Guyana
-  740: "EC",
-  // Ecuador
-  742: "GF",
-  // French Guiana
-  744: "PY",
-  // Paraguay
-  746: "SR",
-  // Suriname
-  748: "UY",
-  // Uruguay
-  750: "FK",
-  // Falkland Islands
-  // North America, Caribbean
-  302: "CA",
-  // Canada
-  308: "PM",
-  // Saint Pierre and Miquelon
-  310: "US",
-  // United States
-  311: "US",
-  // United States
-  312: "US",
-  // United States
-  313: "US",
-  // United States
-  314: "US",
-  // United States
-  315: "US",
-  // United States
-  316: "US",
-  // United States
-  330: "PR",
-  // Puerto Rico
-  332: "VI",
-  // U.S. Virgin Islands
-  334: "MX",
-  // Mexico
-  338: "JM",
-  // Jamaica
-  340: "GP",
-  // Guadeloupe
-  342: "BB",
-  // Barbados
-  344: "AG",
-  // Antigua and Barbuda
-  346: "KY",
-  // Cayman Islands
-  348: "VG",
-  // British Virgin Islands
-  350: "BM",
-  // Bermuda
-  352: "GD",
-  // Grenada
-  354: "MS",
-  // Montserrat
-  356: "KN",
-  // Saint Kitts and Nevis
-  358: "LC",
-  // Saint Lucia
-  360: "VC",
-  // Saint Vincent and the Grenadines
-  362: "CW",
-  // Curaçao / Netherlands Antilles
-  363: "AW",
-  // Aruba
-  364: "BS",
-  // Bahamas
-  365: "AI",
-  // Anguilla
-  366: "DM",
-  // Dominica
-  368: "CU",
-  // Cuba
-  370: "DO",
-  // Dominican Republic
-  372: "HT",
-  // Haiti
-  374: "TT",
-  // Trinidad and Tobago
-  376: "TC",
-  // Turks and Caicos Islands
-  // Special / Test MCCs
-  999: "XX",
-  // Test network
-  901: "XX"
-  // International / satellite
-};
-function mccToIso(mcc) {
-  if (mcc == null) return null;
-  let n;
-  if (typeof mcc === "string") {
-    const trimmed = mcc.trim();
-    if (trimmed === "" || !/^\d+$/.test(trimmed)) return null;
-    n = parseInt(trimmed, 10);
-  } else {
-    n = mcc;
-  }
-  if (!Number.isFinite(n)) return null;
-  return MCC_TO_ISO[n] ?? null;
-}
-
 // ../../packages/ocs-spec/src/index.ts
 var ocsSpec = ocs_methods_default;
 var ocsMethods = ocsSpec.v1_methods;
@@ -4083,8 +3624,19 @@ function registerIntelligenceTools(server2, ctx) {
       severity = "critical";
     }
     const pkgs = await safeCall(ctx.env, token2, "listSubscriberPrepaidPackages", { iccid });
-    const activePkgs = prepaidPackageRows(pkgs.data).filter(isActivePackage);
+    const allPkgs = prepaidPackageRows(pkgs.data);
+    const activePkgs = allPkgs.filter((p) => isActivePackage(p));
+    const stalePkgs = staleActivePackages(allPkgs);
     if (!pkgs.error) {
+      for (const pkg of stalePkgs) {
+        const label = packageName(pkg);
+        const days = Math.abs(daysUntil(packageExpiry(pkg)));
+        findings.push(
+          `Package "${label}" is flagged active but expired ${days} days ago \u2014 it grants nothing`
+        );
+        actions.push("Deactivate the stale row via modify_package_status (status INACTIVE)");
+        if (severity !== "critical") severity = "warning";
+      }
       if (activePkgs.length === 0) {
         findings.push("No active packages \u2014 subscriber has no data/voice/SMS allowance");
         actions.push("Assign a package via assign_package");
@@ -9673,11 +9225,13 @@ var CURATED_ROUTER_TOOLS = [
   },
   {
     name: "subscriber_country_history",
-    description: "Return cross-border movement history for a subscriber from Relay LU events. Intent: 'where has subscriber X traveled', 'country history for ICCID', 'border crossings', 'which countries did this SIM visit', 'travel history'.",
+    description: "Return cross-border movement history for a subscriber, reconstructed from OCS Gy charging events. Intent: 'where has subscriber X traveled', 'country history for ICCID', 'border crossings', 'which countries did this SIM visit', 'travel history'.",
     input_schema: {
       type: "object",
       properties: {
         subscriberId: { type: "string" },
+        startDate: { type: "string" },
+        endDate: { type: "string" },
         limit: { type: "number" }
       },
       required: ["subscriberId"]
@@ -10749,15 +10303,32 @@ function registerDepletionEventsTool(server2, ctx) {
 
 // src/tools-country-history.ts
 import { z as z15 } from "zod";
+function isoDate(now, daysAgo = 0) {
+  const d = new Date(now.getTime() - daysAgo * 864e5);
+  return d.toISOString().slice(0, 10);
+}
+function staysAsCountryEvents(stays) {
+  return stays.map((stay, idx) => ({
+    event_id: `gy-${stay.country}-${stay.first_seen}`,
+    new_country: stay.country,
+    previous_country: idx === 0 ? null : stays[idx - 1].country,
+    mcc: stay.mccs[0] ?? null,
+    mnc: null,
+    timestamp: stay.first_seen,
+    source: "ocs-gy"
+  })).reverse();
+}
 function registerCountryHistoryTool(server2, ctx) {
   server2.registerTool(
     "subscriber_country_history",
     {
       title: "Subscriber Country History",
-      description: "Return cross-border movement history for a subscriber from Relay LU events. Reads country.entered events from the OCS ring-buffer (24h window, up to `limit` entries per request) written by the Bridge4IP Relay LU webhook. Each entry includes the new country, previous country, MCC/MNC, and timestamp. Use this to answer: 'where has subscriber X traveled', 'show country history for ICCID', 'border crossings for this SIM'. Params: `subscriberId` (ICCID, 19\u201320 digits), `limit` (1\u201350, default 20, newest first). Returns: ordered list of country.entered events with { new_country, previous_country, mcc, mnc, timestamp, source }. Empty list when no cross-border events recorded. Do NOT use this for raw location events \u2014 use `list_recent_ocs_events` with event_types=['location.changed'] for finer-grained location data.",
+      description: "Return cross-border movement history for a subscriber, reconstructed from OCS Gy charging events. Reads `gyAnswer.events` from `subscriberNetworkEventsOverPeriod` \u2014 every Gy record carries its own country, operator and MCC \u2014 and collapses consecutive same-country records into stays with first-seen and last-seen timestamps. This needs no webhook: it works with Relay LU and Relay Gy off. Relay `country.entered` events from the 24h ring-buffer are merged in as a supplement when present. Use this to answer: 'where has subscriber X traveled', 'show country history for ICCID', 'border crossings for this SIM'. Params: `subscriberId` (ICCID, 19\u201320 digits), `startDate`/`endDate` (YYYY-MM-DD, max 7 days apart, default the last 7 days), `limit` (1\u201350, default 20, newest first). Returns: `stays` ({ country, country_name, first_seen, last_seen, operators, mccs, event_count, used_bytes }), `transitions` ({ from, to, at }), and `country_events` in the legacy flat shape. `used_bytes` already handles the string-typed `usedUnits` and its 'N/A' values. Do NOT use this for raw per-session records \u2014 use `subscriber_network_events` for those.",
       inputSchema: {
         subscriberId: z15.string().regex(/^\d{19,20}$/, "subscriberId must be a 19\u201320 digit ICCID").describe("Subscriber ICCID (19\u201320 digits, ITU-T E.118)"),
-        limit: z15.number().int().min(1).max(50).default(20).optional().describe("Maximum number of events to return, newest first (default 20, max 50)")
+        startDate: z15.string().regex(/^\d{4}-\d{2}-\d{2}$/, "startDate must be YYYY-MM-DD").optional().describe("Start of the period, YYYY-MM-DD inclusive (default: 7 days ago)"),
+        endDate: z15.string().regex(/^\d{4}-\d{2}-\d{2}$/, "endDate must be YYYY-MM-DD").optional().describe("End of the period, YYYY-MM-DD inclusive, max 7 days from start (default: today)"),
+        limit: z15.number().int().min(1).max(50).default(20).optional().describe("Maximum number of country_events to return, newest first (default 20, max 50)")
       },
       annotations: { readOnlyHint: true, idempotentHint: true }
     },
@@ -10766,12 +10337,31 @@ function registerCountryHistoryTool(server2, ctx) {
       "getSingleSubscriber",
       "read",
       ctx,
-      async ({ subscriberId, limit }, token2) => {
+      async ({
+        subscriberId,
+        startDate,
+        endDate,
+        limit
+      }, token2) => {
         const effectiveLimit = limit ?? 20;
+        const now = /* @__PURE__ */ new Date();
+        const end = endDate ?? isoDate(now);
+        const start = startDate ?? isoDate(now, 7);
         const client2 = new OcsClient(ctx.env.CARRIER_OCS_BASE_URL, token2);
         const subscriberPayload = await client2.call("getSingleSubscriber", {
           iccid: subscriberId
         });
+        let gy = gyCountryHistoryFromResponse(void 0);
+        let gyError = null;
+        try {
+          const events = await client2.call(
+            "subscriberNetworkEventsOverPeriod",
+            networkEventsOverPeriodParams(subscriberId, start, end)
+          );
+          gy = gyCountryHistoryFromResponse(events);
+        } catch (err7) {
+          gyError = err7 instanceof Error ? err7.message : String(err7);
+        }
         let syntheticRingIccid = null;
         const msisdnRaw = msisdnFieldFromSubscriberPayload(subscriberPayload);
         if (msisdnRaw) {
@@ -10789,7 +10379,7 @@ function registerCountryHistoryTool(server2, ctx) {
           void 0,
           ctx.env.OCS_EVENT_ROUTING
         );
-        let countryEvents = primary.events;
+        let relayEvents = primary.events;
         if (syntheticRingIccid) {
           const secondary = await listRecentOcsEvents(
             syntheticRingIccid,
@@ -10798,11 +10388,23 @@ function registerCountryHistoryTool(server2, ctx) {
             void 0,
             ctx.env.OCS_EVENT_ROUTING
           );
-          countryEvents = mergeOcsEventOutputsNewestFirst(
+          relayEvents = mergeOcsEventOutputsNewestFirst(
             [primary.events, secondary.events],
             effectiveLimit
           );
         }
+        const countryEvents = [
+          ...relayEvents.map((e) => ({
+            event_id: e.event_id,
+            new_country: e.data["new_country"] ?? null,
+            previous_country: e.data["previous_country"] ?? null,
+            mcc: e.data["mcc"] ?? null,
+            mnc: e.data["mnc"] ?? null,
+            timestamp: e.timestamp,
+            source: e.data["source"] ?? "relay-lu"
+          })),
+          ...staysAsCountryEvents(gy.stays)
+        ].slice(0, effectiveLimit);
         return {
           content: [
             {
@@ -10810,18 +10412,17 @@ function registerCountryHistoryTool(server2, ctx) {
               text: JSON.stringify(
                 {
                   subscriber_id: subscriberId,
-                  country_events: countryEvents.map((e) => ({
-                    event_id: e.event_id,
-                    new_country: e.data["new_country"] ?? null,
-                    previous_country: e.data["previous_country"] ?? null,
-                    mcc: e.data["mcc"] ?? null,
-                    mnc: e.data["mnc"] ?? null,
-                    timestamp: e.timestamp,
-                    source: e.data["source"] ?? "relay-lu"
-                  })),
+                  period: { start, end },
+                  stays: gy.stays,
+                  transitions: gy.transitions,
+                  gy_events_considered: gy.events_considered,
+                  gy_events_skipped: gy.events_skipped,
+                  gy_teardown_artifacts_dropped: gy.teardown_artifacts_dropped,
+                  gy_error: gyError ?? void 0,
+                  country_events: countryEvents,
                   total_country_events: countryEvents.length,
                   total_in_buffer: primary.total_in_buffer,
-                  note: countryEvents.length === 0 ? "No cross-border events recorded in the 24h ring-buffer for this subscriber." : void 0
+                  note: countryEvents.length === 0 ? `No Gy charging records with a country between ${start} and ${end}, and no relay country events in the 24h ring-buffer. Widen the period, or check the subscriber has attached at all.` : void 0
                 },
                 null,
                 2