@carrierllc/mcp 0.0.1 → 0.2.0

package/dist/intelligence.js

@@ -0,0 +1,899 @@
+import { z } from "zod";
+import { OcsClient } from "./client.js";
+import { getDefaultResellerId } from "./tools.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function safeCall(env, token, method, params = {}) {
+    try {
+        const client = new OcsClient(env.CARRIER_OCS_BASE_URL, token);
+        const data = await client.call(method, params);
+        return { data, 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) {
+    const now = new Date();
+    const target = new Date(dateStr);
+    return Math.ceil((target.getTime() - now.getTime()) / (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 } : {}) };
+}
+// ---------------------------------------------------------------------------
+// 1. DIAGNOSE SUBSCRIBER — "why is this subscriber offline?"
+// ---------------------------------------------------------------------------
+export function registerIntelligenceTools(server, ctx) {
+    server.registerTool("diagnose_subscriber", {
+        title: "Diagnose Subscriber Issues",
+        description: "Smart diagnostic that chains multiple API calls to analyze why a subscriber " +
+            "may be offline, throttled, or having connectivity issues. Returns a structured " +
+            "diagnosis with root cause analysis and recommended actions.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID to diagnose"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ iccid }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
+        const findings = [];
+        const actions = [];
+        let severity = "healthy";
+        // 1. Get subscriber details
+        const sub = await safeCall(ctx.env, token, "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);
+        // Check OCS status
+        if (status !== "ACTIVE") {
+            findings.push(`OCS status is ${status} (not ACTIVE)`);
+            actions.push(`Reactivate subscriber via modify_subscriber_status`);
+            severity = "critical";
+        }
+        // Check balance
+        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";
+        }
+        // 2. Check SIM provider status — OCS expects bare simId (Long), resolve from subscriber record
+        const simId = sub.data.simId ?? sub.data.sim_id ?? sub.data.id;
+        const sim = simId !== undefined
+            ? await safeCall(ctx.env, token, "getSimProviderStatus", Number(simId))
+            : { 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";
+            }
+        }
+        // 3. Check packages
+        const pkgs = await safeCall(ctx.env, token, "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 {
+                // Check for depleted packages
+                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";
+                    }
+                    // Check expiry
+                    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";
+                        }
+                    }
+                }
+            }
+        }
+        // 4. Check recent network events (last 2 days)
+        const now = new Date();
+        const twoDaysAgo = new Date(now.getTime() - 2 * 24 * 60 * 60 * 1000);
+        const events = await safeCall(ctx.env, token, "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"}`);
+            }
+        }
+        // 5. Check HLR bitrate — OCS expects { imsi }, resolve from subscriber record
+        const imsiForBitrate = typeof sub.data.imsi === "string" ? sub.data.imsi : null;
+        const bitrate = imsiForBitrate
+            ? await safeCall(ctx.env, token, "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";
+            }
+        }
+        // Build report
+        if (findings.length === 0) {
+            findings.push("No issues detected — subscriber appears healthy");
+        }
+        const report = [
+            `# 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: ${pkgs.data && Array.isArray(pkgs.data) ? pkgs.data.filter((p) => String(p.status ?? "").toUpperCase() === "ACTIVE").length : "unknown"}`,
+        ].join("\n");
+        return result(report);
+    });
+    // ---------------------------------------------------------------------------
+    // 2. FLEET HEALTH — single-call fleet overview
+    // ---------------------------------------------------------------------------
+    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. Identifies accounts that " +
+            "need attention.",
+        inputSchema: {
+            accountId: z.number().optional().describe("Filter to a specific account (omit for all)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ accountId }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
+        // Parallel fetch
+        const [statusResult, accountsResult] = await Promise.all([
+            safeCall(ctx.env, token, "esimStatusPerAccount", accountId !== undefined ? { accountId } : {}),
+            safeCall(ctx.env, token, "listResellerAccount", {}),
+        ]);
+        const sections = ["# Fleet Health Dashboard\n"];
+        // eSIM status breakdown
+        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(`\n⚠ High suspension rate (${totalSuspended} suspended vs ${totalActive} active)`);
+            }
+        }
+        // Account balances
+        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. USAGE ANOMALY DETECTION
+    // ---------------------------------------------------------------------------
+    server.registerTool("detect_usage_anomalies", {
+        title: "Detect Usage Anomalies",
+        description: "Analyzes a subscriber's recent usage patterns over the last 7 days to detect " +
+            "anomalies: sudden spikes, unusual off-hours activity, or consumption rates that " +
+            "would exhaust the package before expiry.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID to analyze"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ iccid }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
+        const now = new Date();
+        const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+        const [usageResult, pkgResult] = await Promise.all([
+            safeCall(ctx.env, token, "subscriberUsageOverPeriod", {
+                subscriber: { iccid },
+                period: { start: toISODate(weekAgo), end: toISODate(now) },
+            }),
+            safeCall(ctx.env, token, "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) {
+            // Extract daily data volumes
+            const dailyData = [];
+            for (const entry of usageResult.data) {
+                const bytes = Number(entry.dataBytes ?? entry.dataVolume ?? entry.totalData ?? 0);
+                const date = String(entry.date ?? entry.day ?? "?");
+                dailyData.push({ date, bytes });
+            }
+            if (dailyData.length >= 2) {
+                // Calculate stats
+                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)}**`);
+                // Burn rate analysis against active packages
+                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. PACKAGE OPTIMIZER — recommend better-fit packages
+    // ---------------------------------------------------------------------------
+    server.registerTool("optimize_package", {
+        title: "Package Optimization Advisor",
+        description: "Compares a subscriber's actual usage against their current package and all " +
+            "available templates. Recommends better-fit packages to reduce waste or prevent " +
+            "overages. Calculates potential savings.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID to optimize"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ iccid }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
+        const now = new Date();
+        const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+        const [usageResult, pkgResult, templatesResult] = await Promise.all([
+            safeCall(ctx.env, token, "subscriberUsageOverPeriod", {
+                subscriber: { iccid },
+                period: { start: toISODate(weekAgo), end: toISODate(now) },
+            }),
+            safeCall(ctx.env, token, "listSubscriberPrepaidPackages", { iccid }),
+            safeCall(ctx.env, token, "listPrepaidPackageTemplate", {}),
+        ]);
+        const sections = [`# Package Optimization: ${iccid}\n`];
+        // Calculate average daily usage
+        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)}`);
+        }
+        // Current packages
+        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)`);
+                    // Flag waste
+                    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`);
+                    }
+                }
+            }
+        }
+        // Recommend templates
+        if (templatesResult.data && Array.isArray(templatesResult.data) && avgDailyData > 0) {
+            // Score templates by fit
+            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;
+                // Fit score: penalize both waste (too much data) and shortage (too little)
+                const ratio = limit > 0 ? projectedUsage / limit : 0;
+                const fitScore = 1 - Math.abs(1 - ratio); // 1.0 = perfect fit, 0 = terrible
+                const costPerGB = limit > 0 && price > 0 ? price / (limit / (1024 * 1024 * 1024)) : Infinity;
+                const name = String(t.name ?? t.templateId ?? "?");
+                return { name, limit, validity, price, projectedUsage, fitScore, costPerGB, ratio };
+            })
+                .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 SCORING
+    // ---------------------------------------------------------------------------
+    server.registerTool("churn_risk", {
+        title: "Churn Risk Assessment",
+        description: "Analyzes a subscriber's usage trends, package status, balance, and activity " +
+            "to produce a churn risk score (0-100) with contributing factors and retention " +
+            "recommendations.",
+        inputSchema: {
+            iccid: z.string().describe("The subscriber ICCID to assess"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ iccid }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
+        const now = new Date();
+        const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+        const [subResult, usageResult, pkgResult, activeResult] = await Promise.all([
+            safeCall(ctx.env, token, "getSingleSubscriber", { iccid }),
+            safeCall(ctx.env, token, "subscriberUsageOverPeriod", {
+                subscriber: { iccid },
+                period: { start: toISODate(weekAgo), end: toISODate(now) },
+            }),
+            safeCall(ctx.env, token, "listSubscriberPrepaidPackages", { iccid }),
+            safeCall(ctx.env, token, "getSubscriberActivePeriod", { iccid }),
+        ]);
+        let riskScore = 0;
+        const factors = [];
+        // Factor 1: Usage trend (declining usage = higher risk)
+        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) {
+                    const impact = 30;
+                    riskScore += impact;
+                    factors.push({ factor: "Declining usage", impact, detail: `Usage dropped ${Math.abs(trend * 100).toFixed(0)}% week-over-week` });
+                }
+                else if (trend < -0.2) {
+                    const impact = 15;
+                    riskScore += impact;
+                    factors.push({ factor: "Moderately declining usage", impact, 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" });
+        }
+        // Factor 2: Package status
+        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 {
+                // Check if all packages are near expiry
+                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" });
+                }
+                // Check if no recurring packages
+                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" });
+                }
+            }
+        }
+        // Factor 3: Balance
+        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" });
+            }
+        }
+        // Factor 4: Subscriber age (newer = higher risk)
+        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` });
+                }
+            }
+        }
+        // Cap at 100
+        riskScore = Math.min(riskScore, 100);
+        // Risk level
+        const level = riskScore >= 70 ? "HIGH" : riskScore >= 40 ? "MEDIUM" : "LOW";
+        // Build report
+        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} |`);
+            }
+        }
+        // Retention recommendations
+        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. NETWORK COVERAGE AUDIT — "am I on the right networks?"
+    // ---------------------------------------------------------------------------
+    server.registerTool("audit_network_coverage", {
+        title: "Network Coverage Audit",
+        description: "Analyzes which networks your subscribers are actually connecting to in a given " +
+            "country or across all countries. Compares against your steering lists to identify " +
+            "mismatches — subscribers roaming on expensive or non-preferred networks. " +
+            "Use this to answer: 'Am I using the right networks in country X?'",
+        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 },
+    }, async ({ accountId, limit: sampleLimit }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
+        const maxSample = sampleLimit ?? 50;
+        // Fetch subscribers and steering lists in parallel
+        const subParams = { status: "ACTIVE" };
+        if (accountId !== undefined)
+            subParams.accountId = accountId;
+        const [subsResult, resellerId] = await Promise.all([
+            safeCall(ctx.env, token, "listSubscriber", subParams),
+            getDefaultResellerId(ctx.env, token),
+        ]);
+        const steeringResult = await safeCall(ctx.env, token, "listSteeringList", resellerId);
+        if (subsResult.error)
+            return result(`Failed to fetch subscribers: ${subsResult.error}`, true);
+        const sections = [`# Network Coverage Audit\n`];
+        // Build steering list lookup
+        const steeringMap = new Map();
+        if (steeringResult.data && Array.isArray(steeringResult.data)) {
+            for (const sl of steeringResult.data) {
+                steeringMap.set(Number(sl.steeringListId ?? sl.id), sl);
+            }
+            sections.push(`## Steering Lists: ${steeringMap.size} configured`);
+        }
+        // Sample subscriber locations and networks
+        const countryStats = new Map();
+        if (subsResult.data && Array.isArray(subsResult.data)) {
+            const subs = subsResult.data.slice(0, maxSample);
+            sections.push(`## Sampling ${subs.length} active subscribers\n`);
+            // Fetch locations in batches of 10
+            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(ctx.env, token, "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");
+                        const iccid = String(batch[j].iccid ?? "");
+                        if (!countryStats.has(country)) {
+                            countryStats.set(country, { count: 0, networks: new Map(), subscribers: [] });
+                        }
+                        const stat = countryStats.get(country);
+                        stat.count++;
+                        stat.networks.set(network, (stat.networks.get(network) ?? 0) + 1);
+                        stat.subscribers.push(iccid);
+                    }
+                }
+            }
+        }
+        // Report by country
+        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 — "which countries should I target?"
+    // ---------------------------------------------------------------------------
+    server.registerTool("marketing_intelligence", {
+        title: "Marketing Intelligence Report",
+        description: "Analyzes your subscriber base to identify high-growth markets, underserved regions, " +
+            "and revenue concentration. Answers: 'Which countries should I target with marketing?' " +
+            "and 'Where are my most valuable subscribers?'",
+        inputSchema: {
+            accountId: z.number().optional().describe("Filter to a specific account"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ accountId }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
+        const params = {};
+        if (accountId !== undefined)
+            params.accountId = accountId;
+        const [subsResult, templatesResult, resellerId] = await Promise.all([
+            safeCall(ctx.env, token, "listSubscriber", params),
+            safeCall(ctx.env, token, "listPrepaidPackageTemplate", {}),
+            getDefaultResellerId(ctx.env, token),
+        ]);
+        const zonesResult = await safeCall(ctx.env, token, "listDetailedLocationZone", resellerId);
+        const sections = [`# Marketing Intelligence Report\n`];
+        // Subscriber distribution by location
+        if (subsResult.data && Array.isArray(subsResult.data)) {
+            const total = subsResult.data.length;
+            sections.push(`## Fleet Size: ${total} subscribers sampled\n`);
+            // Get locations for a sample
+            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(ctx.env, token, "getSubscriberLocation", {
+                    iccid: String(s.iccid ?? ""),
+                })));
+                for (let j = 0; j < batch.length; j++) {
+                    const loc = locations[j];
+                    const sub = batch[j];
+                    const country = loc.data
+                        ? String(loc.data.country ?? loc.data.countryCode ?? "Unknown")
+                        : "Unknown";
+                    if (!countryData.has(country)) {
+                        countryData.set(country, { subscribers: 0, activePackages: 0, totalBalance: 0 });
+                    }
+                    const cd = countryData.get(country);
+                    cd.subscribers++;
+                    cd.totalBalance += Number(sub.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} |`);
+                }
+                // Insights
+                sections.push(`\n## Market Insights`);
+                // Top market
+                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`);
+                    }
+                }
+                // High-value markets (high avg balance)
+                const highValue = sorted
+                    .filter(([, d]) => d.subscribers >= 3)
+                    .sort((a, b) => (b[1].totalBalance / b[1].subscribers) - (a[1].totalBalance / a[1].subscribers))
+                    .slice(0, 3);
+                if (highValue.length > 0) {
+                    sections.push(`\n### High-Value Markets (by avg balance)`);
+                    for (const [country, data] of highValue) {
+                        sections.push(`- **${country}**: avg balance ${(data.totalBalance / data.subscribers).toFixed(2)} (${data.subscribers} subs)`);
+                    }
+                }
+                // Underserved (1-2 subscribers — early traction)
+                const emerging = sorted.filter(([, d]) => d.subscribers >= 1 && d.subscribers <= 3);
+                if (emerging.length > 0) {
+                    sections.push(`\n### Emerging Markets (early traction, 1-3 subscribers)`);
+                    sections.push(`These markets show initial demand — consider targeted campaigns:`);
+                    for (const [country, data] of emerging) {
+                        sections.push(`- ${country}: ${data.subscribers} subscriber(s)`);
+                    }
+                }
+            }
+        }
+        // Available coverage vs actual usage
+        if (zonesResult.data && Array.isArray(zonesResult.data)) {
+            sections.push(`\n## Coverage Catalog`);
+            sections.push(`- Location zones available: ${zonesResult.data.length}`);
+        }
+        if (templatesResult.data && Array.isArray(templatesResult.data)) {
+            sections.push(`- Package templates available: ${templatesResult.data.length}`);
+            // Price analysis
+            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;
+                const minPrice = Math.min(...prices);
+                const maxPrice = Math.max(...prices);
+                sections.push(`\n### Pricing Range`);
+                sections.push(`- Min: ${minPrice.toFixed(2)} | Avg: ${avgPrice.toFixed(2)} | Max: ${maxPrice.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 — "who's costing me money?"
+    // ---------------------------------------------------------------------------
+    server.registerTool("high_cost_subscribers", {
+        title: "High Cost Subscriber Report",
+        description: "Identifies subscribers with disproportionately high data consumption relative " +
+            "to their package value. Finds subscribers burning through data at rates that " +
+            "erode margins. Answers: 'Which subscribers are costing me money?'",
+        inputSchema: {
+            accountId: z.number().optional().describe("Filter to a specific account"),
+            limit: z.number().optional().describe("Max subscribers to analyze (default 100)"),
+            thresholdPct: z.number().optional().describe("Usage % threshold to flag (default 80)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ accountId, limit: maxLimit, thresholdPct }) => {
+        const token = await ctx.getUserToken(ctx.props.sub);
+        const sampleSize = maxLimit ?? 100;
+        const threshold = thresholdPct ?? 80;
+        const subParams = { status: "ACTIVE" };
+        if (accountId !== undefined)
+            subParams.accountId = accountId;
+        const subsResult = await safeCall(ctx.env, token, "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 = [];
+        // Analyze in batches
+        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(ctx.env, token, "subscriberUsageOverPeriod", {
+                        subscriber: { iccid },
+                        period: { start: toISODate(weekAgo), end: toISODate(now) },
+                    }),
+                    safeCall(ctx.env, token, "listSubscriberPrepaidPackages", { iccid }),
+                    safeCall(ctx.env, token, "getSubscriberLocation", { iccid }),
+                ]);
+                // Calculate daily avg
+                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;
+                }
+                // Get active package info
+                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,
+                            });
+                        }
+                    }
+                }
+            }));
+        }
+        // Sort by utilization (highest first)
+        highCostSubs.sort((a, b) => b.utilizationPct - a.utilizationPct);
+        sections.push(`Analyzed ${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)}`);
+            // Country breakdown
+            const byCountry = new Map();
+            for (const s of highCostSubs) {
+                byCountry.set(s.country, (byCountry.get(s.country) ?? 0) + 1);
+            }
+            const countrySorted = [...byCountry.entries()].sort((a, b) => b[1] - a[1]);
+            if (countrySorted.length > 0) {
+                sections.push(`\n### By Country`);
+                for (const [country, count] of countrySorted) {
+                    sections.push(`- ${country}: ${count} high-cost subscriber(s)`);
+                }
+            }
+            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`);
+            sections.push(`4. Negotiate better wholesale rates for high-volume countries`);
+        }
+        return result(sections.join("\n"));
+    });
+}
+//# sourceMappingURL=intelligence.js.map