apphud-mcp 0.2.2 → 0.2.5

package/dist/src/services/analyticsService.js

@@ -1,6 +1,9 @@
 import { ApphudMcpError, isApphudMcpError } from "../errors/toolError.js";
 import { extractBreakdown, extractMetricValue, extractTimeseries, } from "./apphudClient.js";
 const ANALYTICS_ONLY_TOOLS = "Analytics tools use Apphud dashboard analytics endpoints directly";
+const SNAPSHOT_METRIC_KEYS = new Set(["active_subs", "active_subscriptions", "active_subscription", "active_trial", "active_trials"]);
+const REVENUE_METRIC_KEYS = new Set(["revenue", "revenue_gross", "gross_revenue", "sales", "proceeds", "cumulative_ltv", "cumulative_clv"]);
+const REFUND_METRIC_KEYS = new Set(["refunds", "refund", "refund_rate"]);
 function normalizeEventTypeFilter(value) {
     if (!value) {
         return undefined;
@@ -65,6 +68,57 @@ function shiftPeriod(from, to) {
         to: prevTo.toISOString(),
     };
 }
+function normalizeMetricKey(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+function metricEventTypeFilter(metricKey) {
+    const normalized = normalizeMetricKey(metricKey);
+    if (normalized === "trials_started" || normalized === "trial_started") {
+        return "trial_started";
+    }
+    if (normalized === "trials_converted" || normalized === "trial_converted") {
+        return "trial_converted";
+    }
+    if (normalized === "new_subscriptions" || normalized === "subscription_started" || normalized === "regular_conversions") {
+        return "subscription_started";
+    }
+    if (normalized === "renewals" || normalized === "subscription_renewed") {
+        return "subscription_renewed";
+    }
+    if (normalized === "cancellations" || normalized === "trial_canceled" || normalized === "trial_cancelled") {
+        return "trial_canceled";
+    }
+    if (normalized === "new_users" || normalized === "created") {
+        return "created";
+    }
+    return undefined;
+}
+function isSnapshotMetric(metricKey) {
+    return SNAPSHOT_METRIC_KEYS.has(normalizeMetricKey(metricKey));
+}
+function isRevenueMetric(metricKey) {
+    return REVENUE_METRIC_KEYS.has(normalizeMetricKey(metricKey));
+}
+function isRefundMetric(metricKey) {
+    return REFUND_METRIC_KEYS.has(normalizeMetricKey(metricKey));
+}
+function eventDateBucket(occurredAt, granularity) {
+    const parsed = new Date(occurredAt);
+    if (Number.isNaN(parsed.getTime())) {
+        return null;
+    }
+    if (granularity === "day") {
+        return parsed.toISOString().slice(0, 10);
+    }
+    const weekStart = new Date(Date.UTC(parsed.getUTCFullYear(), parsed.getUTCMonth(), parsed.getUTCDate()));
+    const weekDay = (weekStart.getUTCDay() + 6) % 7;
+    weekStart.setUTCDate(weekStart.getUTCDate() - weekDay);
+    return weekStart.toISOString().slice(0, 10);
+}
 export class AnalyticsService {
     appService;
     apphudClient;
@@ -249,6 +303,25 @@ export class AnalyticsService {
             includeRaw: input.include_raw,
             auth,
         });
+        if (resolved.code === "METRIC_AMBIGUOUS") {
+            throw new ApphudMcpError("METRIC_AMBIGUOUS", `Metric key '${input.metric_key}' matched multiple dashboard metrics`, {
+                statusCode: 400,
+                details: {
+                    metric_key: input.metric_key,
+                    candidates: resolved.candidates ?? [],
+                    available_metrics: resolved.available_metrics ?? [],
+                },
+            });
+        }
+        if (resolved.value === null) {
+            throw new ApphudMcpError("METRIC_NOT_FOUND", `Metric key '${input.metric_key}' not found in analytics payload`, {
+                statusCode: 404,
+                details: {
+                    metric_key: input.metric_key,
+                    available_metrics: resolved.available_metrics ?? [],
+                },
+            });
+        }
         return {
             app_id: app.appId,
             apphud_app_id: input.apphud_app_id ?? app.appId,
@@ -287,21 +360,77 @@ export class AnalyticsService {
         extractedFrom = extractedDash.path;
         if (points.length === 0) {
             warnings.push("No timeseries in dash/range payload, fallback to chart/query/line");
-            const chart = await this.apphudClient.fetchChartQuery(app, {
-                shape: "line",
-                metricKey: input.metric_key,
+            try {
+                const chart = await this.apphudClient.fetchChartQuery(app, {
+                    shape: "line",
+                    metricKey: input.metric_key,
+                    apphudAppId: input.apphud_app_id,
+                    from: input.from,
+                    to: input.to,
+                    granularity: input.granularity,
+                    platform: input.platform,
+                    filters: input.filters,
+                });
+                sourceUsed = chart.sourcePath;
+                rawPayload = chart.payload;
+                const extractedLine = extractTimeseries(chart.payload, input.metric_key);
+                points = extractedLine.points;
+                extractedFrom = extractedLine.path;
+            }
+            catch (error) {
+                const chartWarning = this.chartQueryFallbackWarning(error);
+                if (!chartWarning) {
+                    throw error;
+                }
+                warnings.push(chartWarning);
+            }
+        }
+        if (points.length === 0) {
+            const fromEvents = await this.fallbackTimeseriesFromEvents(app, {
                 apphudAppId: input.apphud_app_id,
+                metricKey: input.metric_key,
                 from: input.from,
                 to: input.to,
-                granularity: input.granularity,
+                granularity: input.granularity ?? "day",
                 platform: input.platform,
-                filters: input.filters,
             });
-            sourceUsed = chart.sourcePath;
-            rawPayload = chart.payload;
-            const extractedLine = extractTimeseries(chart.payload, input.metric_key);
-            points = extractedLine.points;
-            extractedFrom = extractedLine.path;
+            if (fromEvents.points.length > 0) {
+                sourceUsed = fromEvents.sourceUsed;
+                rawPayload = fromEvents.rawPayload;
+                extractedFrom = fromEvents.extractedFrom;
+                points = fromEvents.points.map((point) => ({ ...point }));
+                const dashValue = extractMetricValue(dashRange.payload, input.metric_key).value;
+                if (typeof dashValue === "number" && points.length > 0) {
+                    const pointsTotal = points.reduce((sum, point) => sum + point.value, 0);
+                    const delta = Number((dashValue - pointsTotal).toFixed(6));
+                    const maxAllowedAdjustment = Math.max(1, Math.abs(dashValue) * 0.05);
+                    if (Math.abs(delta) > 0 && Math.abs(delta) <= maxAllowedAdjustment) {
+                        const lastIndex = points.length - 1;
+                        const lastPoint = points[lastIndex];
+                        if (lastPoint) {
+                            points[lastIndex] = {
+                                ...lastPoint,
+                                value: Number((lastPoint.value + delta).toFixed(6)),
+                            };
+                            warnings.push("Events timeseries adjusted to match dashboard total");
+                        }
+                    }
+                }
+                warnings.push("Timeseries built from events feed because chart/query/line is unavailable");
+            }
+            else {
+                const extractedValue = extractMetricValue(dashRange.payload, input.metric_key);
+                if (typeof extractedValue.value === "number") {
+                    points = [
+                        {
+                            date: safeIso(input.to),
+                            value: Number(extractedValue.value.toFixed(4)),
+                        },
+                    ];
+                    extractedFrom = extractedValue.path;
+                    warnings.push("Timeseries not available; returned single aggregated point from dashboard range");
+                }
+            }
         }
         const summary = toPointSummary(points);
         return {
@@ -331,21 +460,31 @@ export class AnalyticsService {
         let sourceUsed = "/chart/query/column";
         let extractedFrom;
         let rawPayload;
-        const column = await this.apphudClient.fetchChartQuery(app, {
-            shape: "column",
-            metricKey: input.metric_key,
-            apphudAppId: input.apphud_app_id,
-            from: input.from,
-            to: input.to,
-            granularity: input.granularity,
-            dimension: input.dimension,
-            platform: input.platform,
-            filters: input.filters,
-        });
-        rawPayload = column.payload;
-        const extractedColumn = extractBreakdown(column.payload, input.metric_key);
-        let rows = extractedColumn.rows;
-        extractedFrom = extractedColumn.path;
+        let rows = [];
+        try {
+            const column = await this.apphudClient.fetchChartQuery(app, {
+                shape: "column",
+                metricKey: input.metric_key,
+                apphudAppId: input.apphud_app_id,
+                from: input.from,
+                to: input.to,
+                granularity: input.granularity,
+                dimension: input.dimension,
+                platform: input.platform,
+                filters: input.filters,
+            });
+            rawPayload = column.payload;
+            const extractedColumn = extractBreakdown(column.payload, input.metric_key);
+            rows = extractedColumn.rows;
+            extractedFrom = extractedColumn.path;
+        }
+        catch (error) {
+            const chartWarning = this.chartQueryFallbackWarning(error);
+            if (!chartWarning) {
+                throw error;
+            }
+            warnings.push(chartWarning);
+        }
         if (rows.length === 0) {
             warnings.push("No breakdown in chart/query/column payload, fallback to dash/range");
             const dashRange = await this.apphudClient.fetchDashRange(app, {
@@ -364,6 +503,28 @@ export class AnalyticsService {
             rows = extractedRange.rows;
             extractedFrom = extractedRange.path;
         }
+        const isAggregateDashRows = sourceUsed === "/dash/range" && typeof extractedFrom === "string" && extractedFrom.includes(".groups");
+        if (rows.length > 0 && input.dimension && isAggregateDashRows) {
+            warnings.push("dash/range returned aggregate metric rows, fallback to events feed for requested dimension");
+            rows = [];
+        }
+        if (rows.length === 0) {
+            const fromEvents = await this.fallbackBreakdownFromEvents(app, {
+                apphudAppId: input.apphud_app_id,
+                metricKey: input.metric_key,
+                from: input.from,
+                to: input.to,
+                platform: input.platform,
+                dimension: input.dimension,
+            });
+            if (fromEvents.rows.length > 0) {
+                rows = fromEvents.rows;
+                sourceUsed = fromEvents.sourceUsed;
+                extractedFrom = fromEvents.extractedFrom;
+                rawPayload = fromEvents.rawPayload;
+                warnings.push("Breakdown built from events feed because chart/query/column is unavailable");
+            }
+        }
         const limit = input.limit ?? 20;
         const limited = rows.slice(0, limit);
         return {
@@ -467,9 +628,16 @@ export class AnalyticsService {
             includeRaw: false,
             auth,
         };
+        const activeMetricInputBase = {
+            apphudAppId: input.apphud_app_id,
+            platform: input.platform,
+            filters: input.filters,
+            includeRaw: false,
+            auth,
+        };
         const [activePaid, activeTrials, newSubs, renewals, cancellations] = await Promise.all([
-            this.resolveMetricValue(app, { ...metricInputBase, metricKey: "active_subs" }),
-            this.resolveMetricValue(app, { ...metricInputBase, metricKey: "active_trials" }),
+            this.resolveMetricValue(app, { ...activeMetricInputBase, metricKey: "active_subs" }),
+            this.resolveMetricValue(app, { ...activeMetricInputBase, metricKey: "active_trials" }),
             this.resolveMetricValue(app, { ...metricInputBase, metricKey: "new_subscriptions" }),
             this.resolveMetricValue(app, { ...metricInputBase, metricKey: "renewals" }),
             this.resolveMetricValue(app, { ...metricInputBase, metricKey: "cancellations" }),
@@ -567,41 +735,55 @@ export class AnalyticsService {
     async cohortsRetention(auth, input) {
         const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
         this.assertRawAccess(auth, input.include_raw);
-        const chart = await this.apphudClient.fetchChartQuery(app, {
-            shape: "column",
-            metricKey: "subscribers_retention",
-            apphudAppId: input.apphud_app_id,
-            from: input.from,
-            to: input.to,
-            granularity: input.granularity,
-            platform: input.platform,
-            filters: input.filters,
-        });
-        const fromBreakdown = extractBreakdown(chart.payload, "subscribers_retention");
-        const fromSeries = extractTimeseries(chart.payload, "subscribers_retention");
         let periods = [];
-        let extractedFrom = fromBreakdown.path ?? fromSeries.path;
+        let extractedFrom;
+        let sourceUsed = "/api/v1/chart/query/column";
+        let rawPayload;
         const warnings = [];
-        if (fromBreakdown.rows.length > 0) {
-            periods = fromBreakdown.rows
-                .slice(0, input.max_periods ?? 52)
-                .map((row) => ({
-                period_index: periodIndexFromLabel(row.key),
-                retention_rate: asRetentionRate(row.value),
-                users_count: null,
-            }))
-                .sort((a, b) => Number(a.period_index) - Number(b.period_index));
-        }
-        else if (fromSeries.points.length > 0) {
-            periods = fromSeries.points
-                .slice(0, input.max_periods ?? 52)
-                .map((point, index) => ({
-                period_index: index,
-                retention_rate: asRetentionRate(point.value),
-                users_count: null,
-            }));
+        try {
+            const chart = await this.apphudClient.fetchChartQuery(app, {
+                shape: "column",
+                metricKey: "subscribers_retention_new",
+                apphudAppId: input.apphud_app_id,
+                from: input.from,
+                to: input.to,
+                granularity: input.granularity,
+                platform: input.platform,
+                filters: input.filters,
+            });
+            const fromBreakdown = extractBreakdown(chart.payload, "subscribers_retention");
+            const fromSeries = extractTimeseries(chart.payload, "subscribers_retention");
+            extractedFrom = fromBreakdown.path ?? fromSeries.path;
+            sourceUsed = chart.sourcePath;
+            rawPayload = chart.payload;
+            if (fromBreakdown.rows.length > 0) {
+                periods = fromBreakdown.rows
+                    .slice(0, input.max_periods ?? 52)
+                    .map((row) => ({
+                    period_index: periodIndexFromLabel(row.key),
+                    retention_rate: asRetentionRate(row.value),
+                    users_count: null,
+                }))
+                    .sort((a, b) => Number(a.period_index) - Number(b.period_index));
+            }
+            else if (fromSeries.points.length > 0) {
+                periods = fromSeries.points
+                    .slice(0, input.max_periods ?? 52)
+                    .map((point, index) => ({
+                    period_index: index,
+                    retention_rate: asRetentionRate(point.value),
+                    users_count: null,
+                }));
+            }
+        }
+        catch (error) {
+            const chartWarning = this.chartQueryFallbackWarning(error);
+            if (!chartWarning) {
+                throw error;
+            }
+            warnings.push(chartWarning);
         }
-        else {
+        if (periods.length === 0) {
             warnings.push("No retention series returned by analytics endpoint");
         }
         return {
@@ -619,33 +801,77 @@ export class AnalyticsService {
                 },
             ],
             source: "apphud_analytics_api",
-            source_used: chart.sourcePath,
+            source_used: sourceUsed,
             extracted_from: extractedFrom,
             warnings,
             retrieved_at: new Date().toISOString(),
-            raw_payload: this.selectRawPayload(auth, input.include_raw, chart.payload),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, rawPayload),
         };
     }
     async cohortsLtv(auth, input) {
         const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
         this.assertRawAccess(auth, input.include_raw);
-        const chart = await this.apphudClient.fetchChartQuery(app, {
-            shape: "line",
-            metricKey: "cumulative_ltv",
-            apphudAppId: input.apphud_app_id,
-            from: input.from,
-            to: input.to,
-            granularity: input.granularity,
-            platform: input.platform,
-            filters: input.filters,
-        });
-        const series = extractTimeseries(chart.payload, "cumulative_ltv");
-        const periods = series.points.slice(0, input.max_periods ?? 52).map((point, index) => ({
-            period_index: index,
-            ltv_value: Number(point.value.toFixed(6)),
-            date: point.date,
-        }));
-        const warnings = periods.length === 0 ? ["No LTV timeseries returned by analytics endpoint"] : [];
+        const warnings = [];
+        let sourceUsed = "/api/v1/chart/query/line";
+        let extractedFrom;
+        let rawPayload;
+        let periods = [];
+        try {
+            const chart = await this.apphudClient.fetchChartQuery(app, {
+                shape: "line",
+                metricKey: "cumulative_ltv",
+                apphudAppId: input.apphud_app_id,
+                from: input.from,
+                to: input.to,
+                granularity: input.granularity,
+                platform: input.platform,
+                filters: input.filters,
+            });
+            const series = extractTimeseries(chart.payload, "cumulative_ltv");
+            periods = series.points.slice(0, input.max_periods ?? 52).map((point, index) => ({
+                period_index: index,
+                ltv_value: Number(point.value.toFixed(6)),
+                date: point.date,
+            }));
+            extractedFrom = series.path;
+            sourceUsed = chart.sourcePath;
+            rawPayload = chart.payload;
+        }
+        catch (error) {
+            const chartWarning = this.chartQueryFallbackWarning(error);
+            if (!chartWarning) {
+                throw error;
+            }
+            warnings.push(chartWarning);
+        }
+        if (periods.length === 0) {
+            const fromEvents = await this.fallbackTimeseriesFromEvents(app, {
+                apphudAppId: input.apphud_app_id,
+                metricKey: "revenue_gross",
+                from: input.from,
+                to: input.to,
+                granularity: input.granularity ?? "week",
+                platform: input.platform,
+            });
+            if (fromEvents.points.length > 0) {
+                let cumulative = 0;
+                periods = fromEvents.points.slice(0, input.max_periods ?? 52).map((point, index) => {
+                    cumulative += point.value;
+                    return {
+                        period_index: index,
+                        ltv_value: Number(cumulative.toFixed(6)),
+                        date: point.date,
+                    };
+                });
+                sourceUsed = fromEvents.sourceUsed;
+                extractedFrom = fromEvents.extractedFrom;
+                rawPayload = fromEvents.rawPayload;
+                warnings.push("LTV approximated from cumulative revenue events because chart/query/line is unavailable");
+            }
+        }
+        if (periods.length === 0) {
+            warnings.push("No LTV timeseries returned by analytics endpoint");
+        }
         return {
             app_id: app.appId,
             apphud_app_id: input.apphud_app_id ?? app.appId,
@@ -659,11 +885,11 @@ export class AnalyticsService {
                 },
             ],
             source: "apphud_analytics_api",
-            source_used: chart.sourcePath,
-            extracted_from: series.path,
+            source_used: sourceUsed,
+            extracted_from: extractedFrom,
             warnings,
             retrieved_at: new Date().toISOString(),
-            raw_payload: this.selectRawPayload(auth, input.include_raw, chart.payload),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, rawPayload),
         };
     }
     async queryRaw(auth, input) {
@@ -802,6 +1028,16 @@ export class AnalyticsService {
     }
     async resolveMetricValue(app, options) {
         const warnings = [];
+        const availableMetrics = new Set();
+        let ambiguousCandidates;
+        const collectExtractionMeta = (extracted) => {
+            for (const metricName of extracted.available_metrics ?? []) {
+                availableMetrics.add(metricName);
+            }
+            if (extracted.code === "METRIC_AMBIGUOUS" && extracted.candidates && extracted.candidates.length > 0) {
+                ambiguousCandidates = extracted.candidates;
+            }
+        };
         if (options.from && options.to) {
             const dashRange = await this.apphudClient.fetchDashRange(app, {
                 apphudAppId: options.apphudAppId,
@@ -812,6 +1048,18 @@ export class AnalyticsService {
                 filters: options.filters,
             });
             const extractedRange = extractMetricValue(dashRange.payload, options.metricKey);
+            collectExtractionMeta(extractedRange);
+            if (extractedRange.code === "METRIC_AMBIGUOUS") {
+                return {
+                    value: null,
+                    source_used: "/dash/range",
+                    raw_payload: this.selectRawPayload(options.auth, options.includeRaw, dashRange.payload),
+                    warnings: [...warnings, "Metric key matched multiple dashboard rows"],
+                    code: "METRIC_AMBIGUOUS",
+                    available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
+                    candidates: ambiguousCandidates ?? [],
+                };
+            }
             if (extractedRange.value !== null) {
                 return {
                     value: extractedRange.value,
@@ -832,42 +1080,101 @@ export class AnalyticsService {
                     warnings,
                 };
             }
+            if (isSnapshotMetric(options.metricKey)) {
+                const dashNow = await this.apphudClient.fetchDashNow(app, {
+                    apphudAppId: options.apphudAppId,
+                    platform: options.platform,
+                    filters: options.filters,
+                });
+                const extractedNow = extractMetricValue(dashNow.payload, options.metricKey);
+                collectExtractionMeta(extractedNow);
+                if (extractedNow.value !== null) {
+                    warnings.push("Range requested for snapshot metric; used current dashboard value from /dash/now");
+                    return {
+                        value: extractedNow.value,
+                        source_used: "/dash/now",
+                        extracted_from: extractedNow.path,
+                        raw_payload: this.selectRawPayload(options.auth, options.includeRaw, dashNow.payload),
+                        warnings,
+                    };
+                }
+            }
             warnings.push("Metric not found in dash/range payload, fallback to chart/query/line");
-            const chart = await this.apphudClient.fetchChartQuery(app, {
-                shape: "line",
-                metricKey: options.metricKey,
+            try {
+                const chart = await this.apphudClient.fetchChartQuery(app, {
+                    shape: "line",
+                    metricKey: options.metricKey,
+                    apphudAppId: options.apphudAppId,
+                    from: options.from,
+                    to: options.to,
+                    platform: options.platform,
+                    filters: options.filters,
+                });
+                const extractedChart = extractMetricValue(chart.payload, options.metricKey);
+                collectExtractionMeta(extractedChart);
+                if (extractedChart.code === "METRIC_AMBIGUOUS") {
+                    return {
+                        value: null,
+                        source_used: chart.sourcePath,
+                        raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chart.payload),
+                        warnings: [...warnings, "Metric key matched multiple dashboard rows"],
+                        code: "METRIC_AMBIGUOUS",
+                        available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
+                        candidates: ambiguousCandidates ?? [],
+                    };
+                }
+                if (extractedChart.value !== null) {
+                    return {
+                        value: extractedChart.value,
+                        source_used: chart.sourcePath,
+                        extracted_from: extractedChart.path,
+                        raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chart.payload),
+                        warnings,
+                    };
+                }
+                const fromChartSeries = extractTimeseries(chart.payload, options.metricKey);
+                if (fromChartSeries.points.length > 0) {
+                    const total = fromChartSeries.points.reduce((sum, point) => sum + point.value, 0);
+                    return {
+                        value: Number(total.toFixed(4)),
+                        source_used: chart.sourcePath,
+                        extracted_from: fromChartSeries.path,
+                        raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chart.payload),
+                        warnings,
+                    };
+                }
+            }
+            catch (error) {
+                const chartWarning = this.chartQueryFallbackWarning(error);
+                if (!chartWarning) {
+                    throw error;
+                }
+                warnings.push(chartWarning);
+            }
+            const fromEvents = await this.fallbackMetricValueFromEvents(app, {
                 apphudAppId: options.apphudAppId,
+                metricKey: options.metricKey,
                 from: options.from,
                 to: options.to,
                 platform: options.platform,
-                filters: options.filters,
             });
-            const extractedChart = extractMetricValue(chart.payload, options.metricKey);
-            if (extractedChart.value !== null) {
-                return {
-                    value: extractedChart.value,
-                    source_used: chart.sourcePath,
-                    extracted_from: extractedChart.path,
-                    raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chart.payload),
-                    warnings,
-                };
-            }
-            const fromChartSeries = extractTimeseries(chart.payload, options.metricKey);
-            if (fromChartSeries.points.length > 0) {
-                const total = fromChartSeries.points.reduce((sum, point) => sum + point.value, 0);
+            if (fromEvents.value !== null) {
+                warnings.push("Metric value estimated from events feed because chart/query/line is unavailable");
                 return {
-                    value: Number(total.toFixed(4)),
-                    source_used: chart.sourcePath,
-                    extracted_from: fromChartSeries.path,
-                    raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chart.payload),
+                    value: fromEvents.value,
+                    source_used: fromEvents.sourceUsed,
+                    extracted_from: fromEvents.extractedFrom,
+                    raw_payload: this.selectRawPayload(options.auth, options.includeRaw, fromEvents.rawPayload),
                     warnings,
                 };
             }
             return {
                 value: null,
-                source_used: chart.sourcePath,
-                raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chart.payload),
+                source_used: "/dash/range",
+                raw_payload: this.selectRawPayload(options.auth, options.includeRaw, dashRange.payload),
                 warnings: [...warnings, "Metric not found in analytics payloads"],
+                code: "METRIC_NOT_FOUND",
+                available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
             };
         }
         const dashNow = await this.apphudClient.fetchDashNow(app, {
@@ -876,6 +1183,18 @@ export class AnalyticsService {
             filters: options.filters,
         });
         const extractedNow = extractMetricValue(dashNow.payload, options.metricKey);
+        collectExtractionMeta(extractedNow);
+        if (extractedNow.code === "METRIC_AMBIGUOUS") {
+            return {
+                value: null,
+                source_used: "/dash/now",
+                raw_payload: this.selectRawPayload(options.auth, options.includeRaw, dashNow.payload),
+                warnings: [...warnings, "Metric key matched multiple dashboard rows"],
+                code: "METRIC_AMBIGUOUS",
+                available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
+                candidates: ambiguousCandidates ?? [],
+            };
+        }
         if (extractedNow.value !== null) {
             return {
                 value: extractedNow.value,
@@ -886,33 +1205,249 @@ export class AnalyticsService {
             };
         }
         warnings.push("Metric not found in dash/now payload, fallback to chart/query/line");
-        const chartNow = await this.apphudClient.fetchChartQuery(app, {
-            shape: "line",
-            metricKey: options.metricKey,
+        try {
+            const chartNow = await this.apphudClient.fetchChartQuery(app, {
+                shape: "line",
+                metricKey: options.metricKey,
+                apphudAppId: options.apphudAppId,
+                platform: options.platform,
+                filters: options.filters,
+            });
+            const extractedChartNow = extractMetricValue(chartNow.payload, options.metricKey);
+            collectExtractionMeta(extractedChartNow);
+            if (extractedChartNow.code === "METRIC_AMBIGUOUS") {
+                return {
+                    value: null,
+                    source_used: chartNow.sourcePath,
+                    raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chartNow.payload),
+                    warnings: [...warnings, "Metric key matched multiple dashboard rows"],
+                    code: "METRIC_AMBIGUOUS",
+                    available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
+                    candidates: ambiguousCandidates ?? [],
+                };
+            }
+            if (extractedChartNow.value !== null) {
+                return {
+                    value: extractedChartNow.value,
+                    source_used: chartNow.sourcePath,
+                    extracted_from: extractedChartNow.path,
+                    raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chartNow.payload),
+                    warnings,
+                };
+            }
+            const series = extractTimeseries(chartNow.payload, options.metricKey);
+            const lastPoint = series.points[series.points.length - 1];
+            return {
+                value: lastPoint?.value ?? null,
+                source_used: chartNow.sourcePath,
+                extracted_from: series.path,
+                raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chartNow.payload),
+                warnings: [...warnings, "Metric value estimated from last chart point"],
+                code: lastPoint ? undefined : "METRIC_NOT_FOUND",
+                available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
+            };
+        }
+        catch (error) {
+            const chartWarning = this.chartQueryFallbackWarning(error);
+            if (!chartWarning) {
+                throw error;
+            }
+            return {
+                value: null,
+                source_used: "/dash/now",
+                raw_payload: this.selectRawPayload(options.auth, options.includeRaw, dashNow.payload),
+                warnings: [...warnings, chartWarning, "Metric not found in analytics payloads"],
+                code: "METRIC_NOT_FOUND",
+                available_metrics: Array.from(availableMetrics.values()).sort((left, right) => left.localeCompare(right)),
+            };
+        }
+    }
+    chartQueryFallbackWarning(error) {
+        if (!isApphudMcpError(error) || error.code !== "UPSTREAM_ERROR") {
+            return undefined;
+        }
+        const status = typeof error.details?.status === "number" ? error.details.status : undefined;
+        const endpoint = typeof error.details?.endpoint === "string" ? error.details.endpoint : "";
+        if (!endpoint.includes("/api/v1/chart/query/")) {
+            return undefined;
+        }
+        if (status !== 400 && status !== 404) {
+            return undefined;
+        }
+        const bodyText = typeof error.details?.body === "string" ? error.details.body : "";
+        let detailsMessage = "";
+        if (bodyText) {
+            try {
+                const parsed = JSON.parse(bodyText);
+                if (typeof parsed.details === "string" && parsed.details.trim().length > 0) {
+                    detailsMessage = parsed.details.trim();
+                }
+                else if (typeof parsed.message === "string" && parsed.message.trim().length > 0) {
+                    detailsMessage = parsed.message.trim();
+                }
+            }
+            catch {
+                detailsMessage = bodyText.slice(0, 120).trim();
+            }
+        }
+        return detailsMessage.length > 0
+            ? `Chart query fallback: ${detailsMessage}`
+            : "Chart query fallback: endpoint rejected request";
+    }
+    async fallbackTimeseriesFromEvents(app, options) {
+        const eventType = metricEventTypeFilter(options.metricKey);
+        const eventsResponse = await this.apphudClient.fetchDashboardEvents(app, {
             apphudAppId: options.apphudAppId,
+            from: options.from,
+            to: options.to,
+            limit: 500,
+            eventType,
+            platform: options.platform,
+        });
+        const byBucket = new Map();
+        for (const event of eventsResponse.events) {
+            if (!event.occurred_at) {
+                continue;
+            }
+            const bucket = eventDateBucket(event.occurred_at, options.granularity);
+            if (!bucket) {
+                continue;
+            }
+            const contribution = this.eventMetricContribution(options.metricKey, event);
+            if (contribution === null) {
+                continue;
+            }
+            byBucket.set(bucket, Number(((byBucket.get(bucket) ?? 0) + contribution).toFixed(6)));
+        }
+        const points = Array.from(byBucket.entries())
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([bucket, value]) => ({
+            date: `${bucket}T00:00:00.000Z`,
+            value: Number(value.toFixed(6)),
+        }));
+        return {
+            points,
+            sourceUsed: eventsResponse.sourcePath,
+            extractedFrom: eventsResponse.extractionPath,
+            rawPayload: eventsResponse.rawPayload,
+        };
+    }
+    async fallbackBreakdownFromEvents(app, options) {
+        const eventType = metricEventTypeFilter(options.metricKey);
+        const eventsResponse = await this.apphudClient.fetchDashboardEvents(app, {
+            apphudAppId: options.apphudAppId,
+            from: options.from,
+            to: options.to,
+            limit: 500,
+            eventType,
+            platform: options.platform,
+        });
+        const grouped = new Map();
+        for (const event of eventsResponse.events) {
+            const key = this.eventDimensionValue(event, options.dimension);
+            if (!key) {
+                continue;
+            }
+            const contribution = this.eventMetricContribution(options.metricKey, event);
+            if (contribution === null) {
+                continue;
+            }
+            grouped.set(key, Number(((grouped.get(key) ?? 0) + contribution).toFixed(6)));
+        }
+        const rows = Array.from(grouped.entries())
+            .map(([key, value]) => ({
+            key,
+            value: Number(value.toFixed(6)),
+        }))
+            .sort((left, right) => {
+            if (right.value !== left.value) {
+                return right.value - left.value;
+            }
+            return left.key.localeCompare(right.key);
+        });
+        return {
+            rows,
+            sourceUsed: eventsResponse.sourcePath,
+            extractedFrom: eventsResponse.extractionPath,
+            rawPayload: eventsResponse.rawPayload,
+        };
+    }
+    async fallbackMetricValueFromEvents(app, options) {
+        const fromEvents = await this.fallbackTimeseriesFromEvents(app, {
+            apphudAppId: options.apphudAppId,
+            metricKey: options.metricKey,
+            from: options.from,
+            to: options.to,
+            granularity: "day",
             platform: options.platform,
-            filters: options.filters,
         });
-        const extractedChartNow = extractMetricValue(chartNow.payload, options.metricKey);
-        if (extractedChartNow.value !== null) {
+        if (fromEvents.points.length === 0) {
             return {
-                value: extractedChartNow.value,
-                source_used: chartNow.sourcePath,
-                extracted_from: extractedChartNow.path,
-                raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chartNow.payload),
-                warnings,
+                value: null,
+                sourceUsed: fromEvents.sourceUsed,
+                extractedFrom: fromEvents.extractedFrom,
+                rawPayload: fromEvents.rawPayload,
             };
         }
-        const series = extractTimeseries(chartNow.payload, options.metricKey);
-        const lastPoint = series.points[series.points.length - 1];
+        const total = fromEvents.points.reduce((sum, point) => sum + point.value, 0);
         return {
-            value: lastPoint?.value ?? null,
-            source_used: chartNow.sourcePath,
-            extracted_from: series.path,
-            raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chartNow.payload),
-            warnings: [...warnings, "Metric value estimated from last chart point"],
+            value: Number(total.toFixed(6)),
+            sourceUsed: fromEvents.sourceUsed,
+            extractedFrom: fromEvents.extractedFrom,
+            rawPayload: fromEvents.rawPayload,
         };
     }
+    eventMetricContribution(metricKey, event) {
+        const normalizedMetric = normalizeMetricKey(metricKey);
+        const normalizedType = normalizeEventTypeFilter(event.event_type);
+        if (isRefundMetric(normalizedMetric)) {
+            if (!normalizedType?.includes("refund")) {
+                return null;
+            }
+            if (typeof event.price !== "number" || !Number.isFinite(event.price)) {
+                return null;
+            }
+            return Math.abs(event.price);
+        }
+        if (isRevenueMetric(normalizedMetric)) {
+            if (typeof event.price !== "number" || !Number.isFinite(event.price)) {
+                return null;
+            }
+            return event.price;
+        }
+        const expectedType = metricEventTypeFilter(normalizedMetric);
+        if (expectedType && normalizedType !== expectedType) {
+            return null;
+        }
+        return 1;
+    }
+    eventDimensionValue(event, dimension) {
+        const normalizedDimension = normalizeMetricKey(dimension);
+        if (normalizedDimension === "product" || normalizedDimension === "product_id") {
+            return event.product_id;
+        }
+        if (normalizedDimension === "event" || normalizedDimension === "event_type" || normalizedDimension === "type") {
+            return normalizeEventTypeFilter(event.event_type) ?? event.event_type;
+        }
+        if (normalizedDimension === "user" || normalizedDimension === "user_id") {
+            return event.user_id;
+        }
+        if (normalizedDimension === "country" || normalizedDimension === "country_code") {
+            return event.country;
+        }
+        if (normalizedDimension === "platform") {
+            return event.platform;
+        }
+        const raw = event.raw;
+        const value = raw[dimension];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return String(value);
+        }
+        return undefined;
+    }
     assertRawAccess(auth, includeRaw) {
         if (!includeRaw) {
             return;