@carrierllc/mcp 0.0.1 → 0.1.0

package/dist/intelligence.js

@@ -0,0 +1,732 @@
+/**
+ * Carrier MCP stdio — Intelligence tools (8 composites).
+ *
+ * These tools chain multiple OCS read methods to produce structured insights.
+ * Stdio variant: no scope enforcement, no audit hook, no Sentry.
+ */
+import { z } from "zod";
+async function safeCall(client, method, params = {}) {
+    try {
+        return { data: await client.call(method, params), error: null };
+    }
+    catch (err) {
+        return { data: null, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return "0 B";
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    return `${(bytes / Math.pow(1024, i)).toFixed(2)} ${units[i]}`;
+}
+function daysUntil(dateStr) {
+    return Math.ceil((new Date(dateStr).getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+}
+function toISODate(d) {
+    return d.toISOString().split("T")[0];
+}
+function result(text, isError = false) {
+    return { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) };
+}
+function makeIntelHandler(_client, fn) {
+    return async (args) => {
+        try {
+            return await fn(args);
+        }
+        catch (err) {
+            return result(`Error: ${err instanceof Error ? err.message : String(err)}`, true);
+        }
+    };
+}
+export function registerAllIntelligenceTools(server, client) {
+    // -------------------------------------------------------------------------
+    // 1. DIAGNOSE SUBSCRIBER
+    // -------------------------------------------------------------------------
+    server.registerTool("diagnose_subscriber", {
+        title: "Diagnose Subscriber Issues",
+        description: "Smart diagnostic that chains multiple API calls to analyse why a subscriber may be offline, throttled, or having connectivity issues.",
+        inputSchema: { iccid: z.string().describe("The subscriber ICCID to diagnose") },
+        annotations: { readOnlyHint: true },
+    }, makeIntelHandler(client, async ({ iccid }) => {
+        const findings = [];
+        const actions = [];
+        let severity = "healthy";
+        const sub = await safeCall(client, "getSingleSubscriber", { iccid });
+        if (sub.error)
+            return result(`Failed to fetch subscriber: ${sub.error}`, true);
+        if (!sub.data)
+            return result("Subscriber not found", true);
+        const status = String(sub.data.status ?? "").toUpperCase();
+        const balance = Number(sub.data.balance ?? 0);
+        if (status !== "ACTIVE") {
+            findings.push(`OCS status is ${status} (not ACTIVE)`);
+            actions.push("Reactivate subscriber via modify_subscriber_status");
+            severity = "critical";
+        }
+        if (balance <= 0) {
+            findings.push(`Balance is ${balance} — subscriber may be blocked from usage`);
+            actions.push("Top up balance via modify_subscriber_balance");
+            if (severity !== "critical")
+                severity = "warning";
+        }
+        const simIdForStatus = sub.data.simId ?? sub.data.sim_id ?? sub.data.id;
+        const sim = simIdForStatus !== undefined
+            ? await safeCall(client, "getSimProviderStatus", Number(simIdForStatus))
+            : { data: null, error: null };
+        if (sim.data) {
+            const simStatus = String(sim.data.simStatus ?? sim.data.status ?? "").toUpperCase();
+            if (simStatus && !["ENABLED", "ACTIVE", "ACTIVATED"].includes(simStatus)) {
+                findings.push(`SIM provider status is ${simStatus} — SIM may be disabled at network level`);
+                actions.push("Enable SIM via change_sim_status");
+                severity = "critical";
+            }
+        }
+        const pkgs = await safeCall(client, "listSubscriberPrepaidPackages", { iccid });
+        if (pkgs.data && Array.isArray(pkgs.data)) {
+            const activePkgs = pkgs.data.filter((p) => String(p.status ?? "").toUpperCase() === "ACTIVE");
+            if (activePkgs.length === 0) {
+                findings.push("No active packages — subscriber has no data/voice/SMS allowance");
+                actions.push("Assign a package via assign_package");
+                severity = "critical";
+            }
+            else {
+                for (const pkg of activePkgs) {
+                    const dataUsed = Number(pkg.dataUsed ?? pkg.dataConsumed ?? 0);
+                    const dataLimit = Number(pkg.dataLimit ?? pkg.dataAllowance ?? 0);
+                    if (dataLimit > 0 && dataUsed >= dataLimit) {
+                        findings.push(`Package "${pkg.name ?? pkg.packageTemplateId}" data depleted: ${formatBytes(dataUsed)} / ${formatBytes(dataLimit)}`);
+                        actions.push("Assign additional package or increase limits via modify_package_limits");
+                        if (severity !== "critical")
+                            severity = "warning";
+                    }
+                    const expiry = String(pkg.expirationDate ?? pkg.endDate ?? "");
+                    if (expiry) {
+                        const days = daysUntil(expiry);
+                        if (days < 0) {
+                            findings.push(`Package "${pkg.name ?? pkg.packageTemplateId}" expired ${Math.abs(days)} days ago`);
+                            actions.push("Remove expired package and assign a new one");
+                            if (severity !== "critical")
+                                severity = "warning";
+                        }
+                        else if (days <= 3) {
+                            findings.push(`Package "${pkg.name ?? pkg.packageTemplateId}" expires in ${days} day(s)`);
+                            actions.push("Consider renewing or assigning a recurring package");
+                            if (severity === "healthy")
+                                severity = "info";
+                        }
+                    }
+                }
+            }
+        }
+        const now = new Date();
+        const twoDaysAgo = new Date(now.getTime() - 2 * 24 * 60 * 60 * 1000);
+        const events = await safeCall(client, "subscriberNetworkEventsOverPeriod", { subscriber: { iccid }, period: { start: toISODate(twoDaysAgo), end: toISODate(now) } });
+        if (events.data && Array.isArray(events.data)) {
+            if (events.data.length === 0) {
+                findings.push("No network events in last 48 hours — device may be powered off or out of coverage");
+                if (severity === "healthy")
+                    severity = "warning";
+            }
+            else {
+                const lastEvent = events.data[events.data.length - 1];
+                const lastType = String(lastEvent.eventType ?? lastEvent.type ?? "unknown");
+                findings.push(`Last network event: ${lastType} at ${lastEvent.timestamp ?? lastEvent.date ?? "unknown"}`);
+            }
+        }
+        const imsiForBitrate = typeof sub.data.imsi === "string" ? sub.data.imsi : null;
+        const bitrate = imsiForBitrate
+            ? await safeCall(client, "hlrGetBitrate", { imsi: imsiForBitrate })
+            : { data: null, error: null };
+        if (bitrate.data) {
+            const rate = Number(bitrate.data.bitrate ?? bitrate.data.maxBitrate ?? 0);
+            if (rate > 0 && rate < 1000000) {
+                findings.push(`HLR bitrate throttled to ${(rate / 1000).toFixed(0)} kbps`);
+                actions.push("Increase bitrate via hlr_set_bitrate if throttling is unintended");
+                if (severity === "healthy")
+                    severity = "info";
+            }
+        }
+        if (findings.length === 0)
+            findings.push("No issues detected — subscriber appears healthy");
+        const activeCount = pkgs.data && Array.isArray(pkgs.data)
+            ? pkgs.data.filter((p) => String(p.status ?? "").toUpperCase() === "ACTIVE").length
+            : "unknown";
+        return result([
+            `# Subscriber Diagnosis: ${iccid}`,
+            ``,
+            `## Severity: ${severity.toUpperCase()}`,
+            ``,
+            `## Findings`,
+            ...findings.map((f, i) => `${i + 1}. ${f}`),
+            ``,
+            ...(actions.length > 0 ? [`## Recommended Actions`, ...actions.map((a, i) => `${i + 1}. ${a}`)] : []),
+            ``,
+            `## Raw Status`,
+            `- OCS Status: ${status}`,
+            `- Balance: ${balance}`,
+            `- Active Packages: ${activeCount}`,
+        ].join("\n"));
+    }));
+    // -------------------------------------------------------------------------
+    // 2. FLEET HEALTH
+    // -------------------------------------------------------------------------
+    server.registerTool("fleet_health", {
+        title: "Fleet Health Dashboard",
+        description: "Aggregates eSIM status counts, low-balance accounts, and provides a fleet-wide health summary in a single call.",
+        inputSchema: {
+            accountId: z.number().optional().describe("Filter to a specific account (omit for all)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, makeIntelHandler(client, async ({ accountId }) => {
+        const [statusResult, accountsResult] = await Promise.all([
+            safeCall(client, "esimStatusPerAccount", accountId !== undefined ? { accountId } : {}),
+            safeCall(client, "listResellerAccount", {}),
+        ]);
+        const sections = ["# Fleet Health Dashboard\n"];
+        if (statusResult.data && Array.isArray(statusResult.data)) {
+            let totalActive = 0, totalSuspended = 0, totalInventory = 0, totalOther = 0;
+            for (const account of statusResult.data) {
+                totalActive += Number(account.active ?? 0);
+                totalSuspended += Number(account.suspended ?? 0);
+                totalInventory += Number(account.inventory ?? account.notActivated ?? 0);
+                totalOther += Number(account.other ?? account.terminated ?? 0);
+            }
+            const total = totalActive + totalSuspended + totalInventory + totalOther;
+            const utilization = total > 0 ? ((totalActive / total) * 100).toFixed(1) : "0";
+            sections.push(`## eSIM Fleet Status`);
+            sections.push(`| Metric | Count | % |`);
+            sections.push(`|--------|-------|---|`);
+            sections.push(`| Active | ${totalActive} | ${total > 0 ? ((totalActive / total) * 100).toFixed(1) : 0}% |`);
+            sections.push(`| Suspended | ${totalSuspended} | ${total > 0 ? ((totalSuspended / total) * 100).toFixed(1) : 0}% |`);
+            sections.push(`| Inventory | ${totalInventory} | ${total > 0 ? ((totalInventory / total) * 100).toFixed(1) : 0}% |`);
+            sections.push(`| Other | ${totalOther} | ${total > 0 ? ((totalOther / total) * 100).toFixed(1) : 0}% |`);
+            sections.push(`| **Total** | **${total}** | |`);
+            sections.push(`\n**Fleet Utilization: ${utilization}%**`);
+            if (totalSuspended > totalActive * 0.1) {
+                sections.push(`\nHigh suspension rate (${totalSuspended} suspended vs ${totalActive} active)`);
+            }
+        }
+        if (accountsResult.data && Array.isArray(accountsResult.data)) {
+            const lowBalance = accountsResult.data.filter((a) => Number(a.balance ?? 0) < 10);
+            if (lowBalance.length > 0) {
+                sections.push(`\n## Low Balance Accounts (< 10)`);
+                sections.push(`| Account | Balance |`);
+                sections.push(`|---------|---------|`);
+                for (const a of lowBalance) {
+                    sections.push(`| ${a.name ?? a.accountId ?? "?"} | ${Number(a.balance ?? 0).toFixed(2)} |`);
+                }
+            }
+            sections.push(`\n## Account Summary`);
+            sections.push(`- Total accounts: ${accountsResult.data.length}`);
+            sections.push(`- Low balance (< 10): ${lowBalance.length}`);
+        }
+        return result(sections.join("\n"));
+    }));
+    // -------------------------------------------------------------------------
+    // 3. DETECT USAGE ANOMALIES
+    // -------------------------------------------------------------------------
+    server.registerTool("detect_usage_anomalies", {
+        title: "Detect Usage Anomalies",
+        description: "Analyses recent usage to detect anomalies: spikes, off-hours activity, or consumption exhausting the package before expiry.",
+        inputSchema: { iccid: z.string().describe("The subscriber ICCID to analyse") },
+        annotations: { readOnlyHint: true },
+    }, makeIntelHandler(client, async ({ iccid }) => {
+        const now = new Date();
+        const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+        const [usageResult, pkgResult] = await Promise.all([
+            safeCall(client, "subscriberUsageOverPeriod", { subscriber: { iccid }, period: { start: toISODate(weekAgo), end: toISODate(now) } }),
+            safeCall(client, "listSubscriberPrepaidPackages", { iccid }),
+        ]);
+        if (usageResult.error)
+            return result(`Failed to fetch usage: ${usageResult.error}`, true);
+        const sections = [`# Usage Anomaly Report: ${iccid}\n`];
+        const anomalies = [];
+        if (usageResult.data && Array.isArray(usageResult.data) && usageResult.data.length > 0) {
+            const dailyData = usageResult.data.map((entry) => ({
+                date: String(entry.date ?? entry.day ?? "?"),
+                bytes: Number(entry.dataBytes ?? entry.dataVolume ?? entry.totalData ?? 0),
+            }));
+            if (dailyData.length >= 2) {
+                const volumes = dailyData.map((d) => d.bytes);
+                const mean = volumes.reduce((a, b) => a + b, 0) / volumes.length;
+                const stdDev = Math.sqrt(volumes.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / volumes.length);
+                sections.push(`## Daily Usage (Last 7 Days)`);
+                sections.push(`| Date | Data | vs Average |`);
+                sections.push(`|------|------|-----------|`);
+                for (const d of dailyData) {
+                    const deviation = mean > 0 ? (((d.bytes - mean) / mean) * 100).toFixed(0) : "0";
+                    const flag = d.bytes > mean + 2 * stdDev ? " SPIKE" : d.bytes > mean + stdDev ? " HIGH" : "";
+                    sections.push(`| ${d.date} | ${formatBytes(d.bytes)} | ${deviation}%${flag} |`);
+                    if (d.bytes > mean + 2 * stdDev) {
+                        anomalies.push(`Spike on ${d.date}: ${formatBytes(d.bytes)} (${deviation}% above average)`);
+                    }
+                }
+                sections.push(`\n**Average daily usage: ${formatBytes(mean)}**`);
+                sections.push(`**Std deviation: ${formatBytes(stdDev)}**`);
+                if (pkgResult.data && Array.isArray(pkgResult.data)) {
+                    const activePkgs = pkgResult.data.filter((p) => String(p.status ?? "").toUpperCase() === "ACTIVE");
+                    for (const pkg of activePkgs) {
+                        const dataLimit = Number(pkg.dataLimit ?? pkg.dataAllowance ?? 0);
+                        const dataUsed = Number(pkg.dataUsed ?? pkg.dataConsumed ?? 0);
+                        const remaining = dataLimit - dataUsed;
+                        const expiry = String(pkg.expirationDate ?? pkg.endDate ?? "");
+                        if (remaining > 0 && expiry && mean > 0) {
+                            const daysLeft = daysUntil(expiry);
+                            const daysToExhaust = remaining / mean;
+                            sections.push(`\n## Burn Rate: ${pkg.name ?? pkg.packageTemplateId}`);
+                            sections.push(`- Remaining: ${formatBytes(remaining)} of ${formatBytes(dataLimit)}`);
+                            sections.push(`- Days until expiry: ${daysLeft}`);
+                            sections.push(`- At current rate, data exhausts in: ${daysToExhaust.toFixed(1)} days`);
+                            if (daysToExhaust < daysLeft * 0.5) {
+                                anomalies.push(`Package "${pkg.name ?? pkg.packageTemplateId}" will run out ${(daysLeft - daysToExhaust).toFixed(0)} days before expiry at current consumption`);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        else {
+            sections.push("No usage data available for the last 7 days.");
+        }
+        if (anomalies.length > 0) {
+            sections.push(`\n## Anomalies Detected`);
+            anomalies.forEach((a, i) => sections.push(`${i + 1}. ${a}`));
+        }
+        else {
+            sections.push(`\n## No anomalies detected — usage appears normal.`);
+        }
+        return result(sections.join("\n"));
+    }));
+    // -------------------------------------------------------------------------
+    // 4. OPTIMIZE PACKAGE
+    // -------------------------------------------------------------------------
+    server.registerTool("optimize_package", {
+        title: "Package Optimization Advisor",
+        description: "Compares a subscriber's usage against their current package and all available templates; recommends better-fit packages.",
+        inputSchema: { iccid: z.string().describe("The subscriber ICCID to optimise") },
+        annotations: { readOnlyHint: true },
+    }, makeIntelHandler(client, async ({ iccid }) => {
+        const now = new Date();
+        const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+        const [usageResult, pkgResult, templatesResult] = await Promise.all([
+            safeCall(client, "subscriberUsageOverPeriod", { subscriber: { iccid }, period: { start: toISODate(weekAgo), end: toISODate(now) } }),
+            safeCall(client, "listSubscriberPrepaidPackages", { iccid }),
+            safeCall(client, "listPrepaidPackageTemplate", {}),
+        ]);
+        const sections = [`# Package Optimization: ${iccid}\n`];
+        let avgDailyData = 0;
+        if (usageResult.data && Array.isArray(usageResult.data) && usageResult.data.length > 0) {
+            const totalData = usageResult.data.reduce((sum, e) => sum + Number(e.dataBytes ?? e.dataVolume ?? e.totalData ?? 0), 0);
+            avgDailyData = totalData / usageResult.data.length;
+            sections.push(`## Current Usage Pattern`);
+            sections.push(`- Average daily data: ${formatBytes(avgDailyData)}`);
+            sections.push(`- Projected monthly: ${formatBytes(avgDailyData * 30)}`);
+        }
+        if (pkgResult.data && Array.isArray(pkgResult.data)) {
+            const activePkgs = pkgResult.data.filter((p) => String(p.status ?? "").toUpperCase() === "ACTIVE");
+            if (activePkgs.length > 0) {
+                sections.push(`\n## Current Active Packages`);
+                for (const pkg of activePkgs) {
+                    const dataLimit = Number(pkg.dataLimit ?? pkg.dataAllowance ?? 0);
+                    const dataUsed = Number(pkg.dataUsed ?? pkg.dataConsumed ?? 0);
+                    const utilization = dataLimit > 0 ? ((dataUsed / dataLimit) * 100).toFixed(1) : "N/A";
+                    const price = Number(pkg.price ?? pkg.cost ?? 0);
+                    sections.push(`\n### ${pkg.name ?? pkg.packageTemplateId}`);
+                    sections.push(`- Data: ${formatBytes(dataUsed)} / ${formatBytes(dataLimit)} (${utilization}% used)`);
+                    if (price > 0)
+                        sections.push(`- Price: ${price.toFixed(2)}`);
+                    const expiry = String(pkg.expirationDate ?? pkg.endDate ?? "");
+                    if (expiry)
+                        sections.push(`- Expires: ${expiry} (${daysUntil(expiry)} days)`);
+                    if (dataLimit > 0 && Number(utilization) < 30) {
+                        sections.push(`- LOW UTILIZATION — subscriber is using less than 30% of allowance`);
+                    }
+                    else if (Number(utilization) > 90) {
+                        sections.push(`- NEAR LIMIT — subscriber at risk of running out`);
+                    }
+                }
+            }
+        }
+        if (templatesResult.data && Array.isArray(templatesResult.data) && avgDailyData > 0) {
+            const scored = templatesResult.data
+                .map((t) => {
+                const limit = Number(t.dataLimit ?? t.dataAllowance ?? 0);
+                const validity = Number(t.validityDays ?? t.duration ?? 30);
+                const price = Number(t.price ?? t.cost ?? 0);
+                const projectedUsage = avgDailyData * validity;
+                const ratio = limit > 0 ? projectedUsage / limit : 0;
+                const fitScore = 1 - Math.abs(1 - ratio);
+                return { name: String(t.name ?? t.templateId ?? "?"), limit, validity, price, projectedUsage, fitScore };
+            })
+                .filter((t) => t.fitScore > 0.3 && t.limit > 0)
+                .sort((a, b) => b.fitScore - a.fitScore)
+                .slice(0, 5);
+            if (scored.length > 0) {
+                sections.push(`\n## Recommended Packages (by usage fit)`);
+                sections.push(`| Template | Data | Validity | Price | Fit | Projected Use |`);
+                sections.push(`|----------|------|----------|-------|-----|--------------|`);
+                for (const t of scored) {
+                    const fitLabel = t.fitScore > 0.8 ? "GREAT" : t.fitScore > 0.6 ? "GOOD" : "OK";
+                    sections.push(`| ${t.name} | ${formatBytes(t.limit)} | ${t.validity}d | ${t.price > 0 ? t.price.toFixed(2) : "?"} | ${fitLabel} (${(t.fitScore * 100).toFixed(0)}%) | ${formatBytes(t.projectedUsage)} |`);
+                }
+            }
+        }
+        else if (avgDailyData === 0) {
+            sections.push(`\n*No usage data available — cannot recommend packages without usage history.*`);
+        }
+        return result(sections.join("\n"));
+    }));
+    // -------------------------------------------------------------------------
+    // 5. CHURN RISK
+    // -------------------------------------------------------------------------
+    server.registerTool("churn_risk", {
+        title: "Churn Risk Assessment",
+        description: "Analyses usage trends, package status, balance, and activity to produce a churn risk score (0-100) with retention recommendations.",
+        inputSchema: { iccid: z.string().describe("The subscriber ICCID to assess") },
+        annotations: { readOnlyHint: true },
+    }, makeIntelHandler(client, async ({ iccid }) => {
+        const now = new Date();
+        const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+        const [subResult, usageResult, pkgResult, activeResult] = await Promise.all([
+            safeCall(client, "getSingleSubscriber", { iccid }),
+            safeCall(client, "subscriberUsageOverPeriod", { subscriber: { iccid }, period: { start: toISODate(weekAgo), end: toISODate(now) } }),
+            safeCall(client, "listSubscriberPrepaidPackages", { iccid }),
+            safeCall(client, "getSubscriberActivePeriod", { iccid }),
+        ]);
+        let riskScore = 0;
+        const factors = [];
+        if (usageResult.data && Array.isArray(usageResult.data) && usageResult.data.length >= 3) {
+            const volumes = usageResult.data.map((e) => Number(e.dataBytes ?? e.dataVolume ?? e.totalData ?? 0));
+            const firstHalf = volumes.slice(0, Math.floor(volumes.length / 2));
+            const secondHalf = volumes.slice(Math.floor(volumes.length / 2));
+            const avgFirst = firstHalf.reduce((a, b) => a + b, 0) / firstHalf.length;
+            const avgSecond = secondHalf.reduce((a, b) => a + b, 0) / secondHalf.length;
+            if (avgFirst > 0) {
+                const trend = (avgSecond - avgFirst) / avgFirst;
+                if (trend < -0.5) {
+                    riskScore += 30;
+                    factors.push({ factor: "Declining usage", impact: 30, detail: `Usage dropped ${Math.abs(trend * 100).toFixed(0)}% week-over-week` });
+                }
+                else if (trend < -0.2) {
+                    riskScore += 15;
+                    factors.push({ factor: "Moderately declining usage", impact: 15, detail: `Usage dropped ${Math.abs(trend * 100).toFixed(0)}%` });
+                }
+            }
+        }
+        else if (!usageResult.data || (Array.isArray(usageResult.data) && usageResult.data.length === 0)) {
+            riskScore += 25;
+            factors.push({ factor: "No recent usage", impact: 25, detail: "Zero data activity in last 7 days" });
+        }
+        if (pkgResult.data && Array.isArray(pkgResult.data)) {
+            const activePkgs = pkgResult.data.filter((p) => String(p.status ?? "").toUpperCase() === "ACTIVE");
+            if (activePkgs.length === 0) {
+                riskScore += 20;
+                factors.push({ factor: "No active packages", impact: 20, detail: "Subscriber has no active data packages" });
+            }
+            else {
+                const allExpiringSoon = activePkgs.every((p) => {
+                    const expiry = String(p.expirationDate ?? p.endDate ?? "");
+                    return expiry && daysUntil(expiry) <= 5;
+                });
+                if (allExpiringSoon) {
+                    riskScore += 15;
+                    factors.push({ factor: "All packages expiring soon", impact: 15, detail: "No package renewal in sight" });
+                }
+                const hasRecurring = activePkgs.some((p) => p.recurring === true || p.isRecurring === true);
+                if (!hasRecurring) {
+                    riskScore += 10;
+                    factors.push({ factor: "No recurring packages", impact: 10, detail: "Manual renewal required — higher churn risk" });
+                }
+            }
+        }
+        if (subResult.data) {
+            const balance = Number(subResult.data.balance ?? 0);
+            if (balance <= 0) {
+                riskScore += 15;
+                factors.push({ factor: "Zero balance", impact: 15, detail: "Cannot purchase new packages" });
+            }
+        }
+        if (activeResult.data) {
+            const firstUse = String(activeResult.data.firstUseDate ?? activeResult.data.activationDate ?? "");
+            if (firstUse) {
+                const daysSinceFirst = Math.abs(daysUntil(firstUse));
+                if (daysSinceFirst < 30) {
+                    riskScore += 10;
+                    factors.push({ factor: "New subscriber", impact: 10, detail: `Only ${daysSinceFirst} days since first use` });
+                }
+            }
+        }
+        riskScore = Math.min(riskScore, 100);
+        const level = riskScore >= 70 ? "HIGH" : riskScore >= 40 ? "MEDIUM" : "LOW";
+        const sections = [
+            `# Churn Risk Assessment: ${iccid}`,
+            ``,
+            `## Risk Score: ${riskScore}/100 (${level})`,
+            ``,
+            `${"#".repeat(Math.floor(riskScore / 5))}${"-".repeat(20 - Math.floor(riskScore / 5))}`,
+            ``,
+        ];
+        if (factors.length > 0) {
+            sections.push(`## Contributing Factors`);
+            sections.push(`| Factor | Impact | Detail |`);
+            sections.push(`|--------|--------|--------|`);
+            factors.sort((a, b) => b.impact - a.impact);
+            for (const f of factors) {
+                sections.push(`| ${f.factor} | +${f.impact} | ${f.detail} |`);
+            }
+        }
+        sections.push(`\n## Retention Recommendations`);
+        if (riskScore >= 70) {
+            sections.push("1. Immediate outreach — contact subscriber with special offer");
+            sections.push("2. Assign a complimentary small data package to re-engage");
+            sections.push("3. Set up a recurring package to reduce renewal friction");
+        }
+        else if (riskScore >= 40) {
+            sections.push("1. Monitor usage for next 7 days");
+            sections.push("2. Consider proactive package renewal notification (via send_sms)");
+            sections.push("3. Ensure package fits usage pattern (run optimize_package)");
+        }
+        else {
+            sections.push("1. No immediate action required");
+            sections.push("2. Continue monitoring via regular fleet_health checks");
+        }
+        return result(sections.join("\n"));
+    }));
+    // -------------------------------------------------------------------------
+    // 6. AUDIT NETWORK COVERAGE
+    // -------------------------------------------------------------------------
+    server.registerTool("audit_network_coverage", {
+        title: "Network Coverage Audit",
+        description: "Analyses which networks subscribers connect to vs steering lists; flags expensive/non-preferred network roaming.",
+        inputSchema: {
+            accountId: z.number().optional().describe("Filter to a specific account"),
+            limit: z.number().optional().describe("Max subscribers to sample (default 50)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, makeIntelHandler(client, async ({ accountId, limit: sampleLimit }) => {
+        const maxSample = sampleLimit ?? 50;
+        const subParams = { limit: maxSample, status: "ACTIVE" };
+        if (accountId !== undefined)
+            subParams.accountId = accountId;
+        const [subsResult, steeringResult] = await Promise.all([
+            safeCall(client, "listSubscriber", subParams),
+            safeCall(client, "listSteeringList", {}),
+        ]);
+        if (subsResult.error)
+            return result(`Failed to fetch subscribers: ${subsResult.error}`, true);
+        const sections = [`# Network Coverage Audit\n`];
+        if (steeringResult.data && Array.isArray(steeringResult.data)) {
+            sections.push(`## Steering Lists: ${steeringResult.data.length} configured`);
+        }
+        const countryStats = new Map();
+        if (subsResult.data && Array.isArray(subsResult.data)) {
+            sections.push(`## Sampling ${subsResult.data.length} active subscribers\n`);
+            const subs = subsResult.data.slice(0, maxSample);
+            const batchSize = 10;
+            for (let i = 0; i < subs.length; i += batchSize) {
+                const batch = subs.slice(i, i + batchSize);
+                const locations = await Promise.all(batch.map((s) => safeCall(client, "getSubscriberLocation", { iccid: String(s.iccid ?? "") })));
+                for (let j = 0; j < batch.length; j++) {
+                    const loc = locations[j];
+                    if (loc.data) {
+                        const country = String(loc.data.country ?? loc.data.countryCode ?? "Unknown");
+                        const network = String(loc.data.network ?? loc.data.operator ?? loc.data.mccMnc ?? "Unknown");
+                        if (!countryStats.has(country)) {
+                            countryStats.set(country, { count: 0, networks: new Map() });
+                        }
+                        const stat = countryStats.get(country);
+                        stat.count++;
+                        stat.networks.set(network, (stat.networks.get(network) ?? 0) + 1);
+                    }
+                }
+            }
+        }
+        if (countryStats.size > 0) {
+            sections.push(`## Network Distribution by Country`);
+            const sorted = [...countryStats.entries()].sort((a, b) => b[1].count - a[1].count);
+            for (const [country, stat] of sorted) {
+                sections.push(`\n### ${country} (${stat.count} subscribers)`);
+                sections.push(`| Network | Subscribers | % |`);
+                sections.push(`|---------|------------|---|`);
+                const networksSorted = [...stat.networks.entries()].sort((a, b) => b[1] - a[1]);
+                for (const [network, count] of networksSorted) {
+                    sections.push(`| ${network} | ${count} | ${((count / stat.count) * 100).toFixed(0)}% |`);
+                }
+                if (networksSorted.length > 3) {
+                    sections.push(`\n${networksSorted.length} different networks in ${country} — possible steering fragmentation`);
+                }
+            }
+        }
+        else {
+            sections.push("No location data available for sampled subscribers.");
+        }
+        return result(sections.join("\n"));
+    }));
+    // -------------------------------------------------------------------------
+    // 7. MARKETING INTELLIGENCE
+    // -------------------------------------------------------------------------
+    server.registerTool("marketing_intelligence", {
+        title: "Marketing Intelligence Report",
+        description: "Identifies high-growth markets, underserved regions, and revenue concentration. Answers 'where should I target marketing?'",
+        inputSchema: {
+            accountId: z.number().optional().describe("Filter to a specific account"),
+        },
+        annotations: { readOnlyHint: true },
+    }, makeIntelHandler(client, async ({ accountId }) => {
+        const params = { limit: 200 };
+        if (accountId !== undefined)
+            params.accountId = accountId;
+        const [subsResult, templatesResult] = await Promise.all([
+            safeCall(client, "listSubscriber", params),
+            safeCall(client, "listPrepaidPackageTemplate", {}),
+        ]);
+        const sections = [`# Marketing Intelligence Report\n`];
+        if (subsResult.data && Array.isArray(subsResult.data)) {
+            const total = subsResult.data.length;
+            sections.push(`## Fleet Size: ${total} subscribers sampled\n`);
+            const sample = subsResult.data.slice(0, 100);
+            const countryData = new Map();
+            const batchSize = 10;
+            for (let i = 0; i < sample.length; i += batchSize) {
+                const batch = sample.slice(i, i + batchSize);
+                const locations = await Promise.all(batch.map((s) => safeCall(client, "getSubscriberLocation", { iccid: String(s.iccid ?? "") })));
+                for (let j = 0; j < batch.length; j++) {
+                    const loc = locations[j];
+                    const subItem = batch[j];
+                    const country = loc.data ? String(loc.data.country ?? loc.data.countryCode ?? "Unknown") : "Unknown";
+                    if (!countryData.has(country))
+                        countryData.set(country, { subscribers: 0, totalBalance: 0 });
+                    const cd = countryData.get(country);
+                    cd.subscribers++;
+                    cd.totalBalance += Number(subItem.balance ?? 0);
+                }
+            }
+            if (countryData.size > 0) {
+                const sorted = [...countryData.entries()].sort((a, b) => b[1].subscribers - a[1].subscribers);
+                sections.push(`## Subscriber Concentration by Country`);
+                sections.push(`| Country | Subscribers | % of Fleet | Avg Balance |`);
+                sections.push(`|---------|-----------|------------|-------------|`);
+                for (const [country, data] of sorted) {
+                    const pct = ((data.subscribers / sample.length) * 100).toFixed(1);
+                    const avgBal = (data.totalBalance / data.subscribers).toFixed(2);
+                    sections.push(`| ${country} | ${data.subscribers} | ${pct}% | ${avgBal} |`);
+                }
+                sections.push(`\n## Market Insights`);
+                const topMarket = sorted[0];
+                if (topMarket) {
+                    sections.push(`- Strongest market: ${topMarket[0]} (${topMarket[1].subscribers} subscribers)`);
+                    if (topMarket[1].subscribers / sample.length > 0.5) {
+                        sections.push(`  Revenue concentration risk — >50% of fleet in one market`);
+                    }
+                }
+                const emerging = sorted.filter(([, d]) => d.subscribers >= 1 && d.subscribers <= 3);
+                if (emerging.length > 0) {
+                    sections.push(`\n### Emerging Markets (1-3 subscribers)`);
+                    for (const [country, data] of emerging) {
+                        sections.push(`- ${country}: ${data.subscribers} subscriber(s)`);
+                    }
+                }
+            }
+        }
+        if (templatesResult.data && Array.isArray(templatesResult.data)) {
+            sections.push(`\n## Package Templates Available: ${templatesResult.data.length}`);
+            const prices = templatesResult.data.map((t) => Number(t.price ?? t.cost ?? 0)).filter((p) => p > 0);
+            if (prices.length > 0) {
+                const avgPrice = prices.reduce((a, b) => a + b, 0) / prices.length;
+                sections.push(`- Pricing range: ${Math.min(...prices).toFixed(2)} – ${Math.max(...prices).toFixed(2)} (avg ${avgPrice.toFixed(2)})`);
+            }
+        }
+        sections.push(`\n## Recommended Actions`);
+        sections.push(`1. Run \`audit_network_coverage\` to verify network quality in top markets`);
+        sections.push(`2. Run \`high_cost_subscribers\` to identify margin pressure`);
+        sections.push(`3. Consider creating regional package templates for emerging markets`);
+        return result(sections.join("\n"));
+    }));
+    // -------------------------------------------------------------------------
+    // 8. HIGH COST SUBSCRIBERS
+    // -------------------------------------------------------------------------
+    server.registerTool("high_cost_subscribers", {
+        title: "High Cost Subscriber Report",
+        description: "Identifies subscribers with disproportionately high data consumption relative to package value.",
+        inputSchema: {
+            accountId: z.number().optional().describe("Filter to a specific account"),
+            limit: z.number().optional().describe("Max subscribers to analyse (default 100)"),
+            thresholdPct: z.number().optional().describe("Usage % threshold to flag (default 80)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, makeIntelHandler(client, async ({ accountId, limit: maxLimit, thresholdPct }) => {
+        const sampleSize = maxLimit ?? 100;
+        const threshold = thresholdPct ?? 80;
+        const subParams = { limit: sampleSize, status: "ACTIVE" };
+        if (accountId !== undefined)
+            subParams.accountId = accountId;
+        const subsResult = await safeCall(client, "listSubscriber", subParams);
+        if (subsResult.error)
+            return result(`Failed to fetch subscribers: ${subsResult.error}`, true);
+        if (!subsResult.data || !Array.isArray(subsResult.data))
+            return result("No subscribers found", true);
+        const sections = [`# High Cost Subscriber Report\n`];
+        const now = new Date();
+        const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+        const highCostSubs = [];
+        const batchSize = 5;
+        const subs = subsResult.data.slice(0, sampleSize);
+        for (let i = 0; i < subs.length; i += batchSize) {
+            const batch = subs.slice(i, i + batchSize);
+            await Promise.all(batch.map(async (sub) => {
+                const iccid = String(sub.iccid ?? "");
+                const [usage, pkgs, loc] = await Promise.all([
+                    safeCall(client, "subscriberUsageOverPeriod", { subscriber: { iccid }, period: { start: toISODate(weekAgo), end: toISODate(now) } }),
+                    safeCall(client, "listSubscriberPrepaidPackages", { iccid }),
+                    safeCall(client, "getSubscriberLocation", { iccid }),
+                ]);
+                let dailyAvgBytes = 0;
+                if (usage.data && Array.isArray(usage.data) && usage.data.length > 0) {
+                    const totalBytes = usage.data.reduce((sum, e) => sum + Number(e.dataBytes ?? e.dataVolume ?? e.totalData ?? 0), 0);
+                    dailyAvgBytes = totalBytes / usage.data.length;
+                }
+                if (pkgs.data && Array.isArray(pkgs.data)) {
+                    const activePkg = pkgs.data.find((p) => String(p.status ?? "").toUpperCase() === "ACTIVE");
+                    if (activePkg && dailyAvgBytes > 0) {
+                        const dataLimit = Number(activePkg.dataLimit ?? activePkg.dataAllowance ?? 0);
+                        const dataUsed = Number(activePkg.dataUsed ?? activePkg.dataConsumed ?? 0);
+                        const price = Number(activePkg.price ?? activePkg.cost ?? 0);
+                        const utilizationPct = dataLimit > 0 ? (dataUsed / dataLimit) * 100 : 0;
+                        const remaining = dataLimit - dataUsed;
+                        const daysToExhaust = dailyAvgBytes > 0 ? remaining / dailyAvgBytes : Infinity;
+                        const costPerGB = price > 0 && dataUsed > 0 ? price / (dataUsed / (1024 * 1024 * 1024)) : 0;
+                        const country = loc.data ? String(loc.data.country ?? loc.data.countryCode ?? "?") : "?";
+                        if (utilizationPct >= threshold || daysToExhaust < 3) {
+                            highCostSubs.push({ iccid, dailyAvgBytes, packageDataLimit: dataLimit, packagePrice: price, utilizationPct, costPerGB, daysToExhaust, country });
+                        }
+                    }
+                }
+            }));
+        }
+        highCostSubs.sort((a, b) => b.utilizationPct - a.utilizationPct);
+        sections.push(`Analysed ${subs.length} active subscribers (threshold: ${threshold}% usage)\n`);
+        if (highCostSubs.length === 0) {
+            sections.push(`No subscribers above ${threshold}% package utilization. Fleet margins look healthy.`);
+        }
+        else {
+            sections.push(`## ${highCostSubs.length} High-Cost Subscribers Found\n`);
+            sections.push(`| ICCID | Country | Daily Avg | Usage % | Days Left | Cost/GB |`);
+            sections.push(`|-------|---------|-----------|---------|-----------|---------|`);
+            let totalDailyBytes = 0;
+            for (const s of highCostSubs) {
+                totalDailyBytes += s.dailyAvgBytes;
+                sections.push(`| ${s.iccid.slice(-8)}... | ${s.country} | ${formatBytes(s.dailyAvgBytes)} | ${s.utilizationPct.toFixed(0)}% | ${s.daysToExhaust === Infinity ? "inf" : s.daysToExhaust.toFixed(1)} | ${s.costPerGB > 0 ? s.costPerGB.toFixed(2) : "?"} |`);
+            }
+            sections.push(`\n## Summary`);
+            sections.push(`- High-cost subscribers: ${highCostSubs.length} / ${subs.length} (${((highCostSubs.length / subs.length) * 100).toFixed(1)}%)`);
+            sections.push(`- Combined daily data burn: ${formatBytes(totalDailyBytes)}`);
+            sections.push(`\n## Recommended Actions`);
+            sections.push(`1. Review tariff rates for top countries via \`get_tariff\``);
+            sections.push(`2. Consider throttling heavy users via \`hlr_set_bitrate\``);
+            sections.push(`3. Run \`optimize_package\` on flagged ICCIDs to find better-fit plans`);
+        }
+        return result(sections.join("\n"));
+    }));
+}
+//# sourceMappingURL=intelligence.js.map