apphud-mcp 0.1.0

package/dist/src/services/analyticsService.js

@@ -0,0 +1,934 @@
+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";
+function normalizeEventTypeFilter(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return normalized.length > 0 ? normalized : undefined;
+}
+function safeIso(value) {
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+        return value;
+    }
+    return parsed.toISOString();
+}
+function toPointSummary(points) {
+    if (points.length === 0) {
+        return { total: 0, average: null };
+    }
+    const total = points.reduce((sum, point) => sum + point.value, 0);
+    return {
+        total,
+        average: Number((total / points.length).toFixed(4)),
+    };
+}
+function mapShares(rows) {
+    const total = rows.reduce((sum, row) => sum + row.value, 0);
+    return rows.map((row) => ({
+        key: row.key,
+        value: row.value,
+        share: total <= 0 ? 0 : Number((row.value / total).toFixed(6)),
+    }));
+}
+function asRetentionRate(value) {
+    if (value <= 1) {
+        return Number(value.toFixed(6));
+    }
+    return Number((value / 100).toFixed(6));
+}
+function periodIndexFromLabel(label) {
+    const match = label.match(/(\d+)/);
+    if (!match) {
+        return 0;
+    }
+    const parsed = Number(match[1]);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function shiftPeriod(from, to) {
+    const fromDate = new Date(from);
+    const toDate = new Date(to);
+    if (Number.isNaN(fromDate.getTime()) || Number.isNaN(toDate.getTime())) {
+        return { from, to };
+    }
+    const diff = toDate.getTime() - fromDate.getTime();
+    const prevTo = new Date(fromDate.getTime() - 1);
+    const prevFrom = new Date(prevTo.getTime() - diff);
+    return {
+        from: prevFrom.toISOString(),
+        to: prevTo.toISOString(),
+    };
+}
+export class AnalyticsService {
+    appService;
+    apphudClient;
+    constructor(appService, apphudClient) {
+        this.appService = appService;
+        this.apphudClient = apphudClient;
+    }
+    async appsList(auth, input = {}) {
+        this.assertRawAccess(auth, input.include_raw);
+        const apps = await this.apphudClient.listDashboardApps();
+        return {
+            source: "apphud_analytics_api",
+            count: apps.apps.length,
+            apps: apps.apps,
+            source_used: apps.sourcePath,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, apps.rawPayload),
+        };
+    }
+    async eventsList(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const limit = Math.min(Math.max(input.limit ?? 100, 1), 500);
+        const filters = input.filters ?? {};
+        const normalizedEventType = normalizeEventTypeFilter(filters.event_type);
+        const response = await this.apphudClient.fetchDashboardEvents(app, {
+            apphudAppId: input.apphud_app_id,
+            from: input.from,
+            to: input.to,
+            limit,
+            cursor: input.cursor,
+            eventType: filters.event_type,
+            userId: filters.user_id,
+            productId: filters.product_id,
+            country: filters.country,
+            platform: filters.platform,
+        });
+        const filteredEvents = response.events.filter((event) => {
+            if (normalizedEventType && normalizeEventTypeFilter(event.event_type) !== normalizedEventType) {
+                return false;
+            }
+            if (filters.user_id && event.user_id !== filters.user_id) {
+                return false;
+            }
+            if (filters.product_id && event.product_id !== filters.product_id) {
+                return false;
+            }
+            if (filters.country && event.country?.toLowerCase() !== filters.country.toLowerCase()) {
+                return false;
+            }
+            if (filters.platform && event.platform !== filters.platform) {
+                return false;
+            }
+            return true;
+        });
+        const events = filteredEvents.slice(0, limit).map((event) => ({
+            event_id: event.event_id,
+            event_type: event.event_type,
+            occurred_at: event.occurred_at,
+            user_id: event.user_id,
+            product_id: event.product_id,
+            original_transaction_id: event.original_transaction_id,
+            subscription_status: event.subscription_status,
+            country: event.country,
+            platform: event.platform,
+            price: event.price,
+            currency: event.currency,
+            raw: input.include_raw && auth.role === "admin" ? event.raw : undefined,
+        }));
+        const hasMore = response.hasMore ?? (response.nextCursor ? true : undefined);
+        const warnings = [];
+        if (events.length === 0) {
+            warnings.push("No events extracted from Apphud dashboard response. Try apphud.analytics.query.raw with include_raw=true to inspect endpoint payload.");
+        }
+        return {
+            app_id: app.appId,
+            apphud_app_id: response.apphudAppId,
+            from: safeIso(input.from),
+            to: safeIso(input.to),
+            limit,
+            cursor: input.cursor,
+            filters: {
+                event_type: filters.event_type,
+                user_id: filters.user_id,
+                product_id: filters.product_id,
+                country: filters.country,
+                platform: filters.platform,
+            },
+            events,
+            events_count: events.length,
+            next_cursor: response.nextCursor,
+            has_more: hasMore,
+            source: "apphud_analytics_api",
+            source_used: response.sourcePath,
+            extracted_from: response.extractionPath,
+            warnings,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, response.rawPayload),
+        };
+    }
+    async activeSubscriptions(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const analytics = await this.apphudClient.fetchActiveSubscriptions(app, {
+            apphudAppId: input.apphud_app_id,
+            platform: input.platform,
+        });
+        return {
+            app_id: app.appId,
+            apphud_app_id: analytics.apphudAppId,
+            metric_key: "active_subs",
+            platform: input.platform,
+            value: analytics.value,
+            source: "apphud_analytics_api",
+            extracted_from: analytics.extractedFrom,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, analytics.rawPayload),
+        };
+    }
+    async capabilities(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const metrics = await this.apphudClient.listAnalyticsMetrics(app, {
+            apphudAppId: input.apphud_app_id,
+        });
+        return {
+            app_id: app.appId,
+            apphud_app_id: metrics.apphudAppId,
+            analytics_available: true,
+            source: "apphud_analytics_api",
+            supported_tools: [
+                "apphud.analytics.events.list",
+                "apphud.analytics.metrics.list",
+                "apphud.analytics.metric.value",
+                "apphud.analytics.metric.timeseries",
+                "apphud.analytics.metric.breakdown",
+                "apphud.analytics.revenue.summary",
+                "apphud.analytics.subscriptions.summary",
+                "apphud.analytics.conversion.trial_to_paid",
+                "apphud.analytics.cohorts.retention",
+                "apphud.analytics.cohorts.ltv",
+                "apphud.analytics.query.raw",
+            ],
+            supported_shapes: ["value", "timeseries", "breakdown", "raw"],
+            metrics_count: metrics.metrics.length,
+            metrics_sample: metrics.metrics.slice(0, 20),
+            source_used: metrics.sourcePath,
+            warning: ANALYTICS_ONLY_TOOLS,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, metrics.rawPayload),
+        };
+    }
+    async metricsList(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const metrics = await this.apphudClient.listAnalyticsMetrics(app, {
+            apphudAppId: input.apphud_app_id,
+        });
+        return {
+            app_id: app.appId,
+            apphud_app_id: metrics.apphudAppId,
+            metrics: metrics.metrics,
+            count: metrics.metrics.length,
+            source_used: metrics.sourcePath,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, metrics.rawPayload),
+        };
+    }
+    async metricValue(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const resolved = await this.resolveMetricValue(app, {
+            apphudAppId: input.apphud_app_id,
+            metricKey: input.metric_key,
+            from: input.from,
+            to: input.to,
+            platform: input.platform,
+            filters: input.filters,
+            includeRaw: input.include_raw,
+            auth,
+        });
+        return {
+            app_id: app.appId,
+            apphud_app_id: input.apphud_app_id ?? app.appId,
+            metric_key: input.metric_key,
+            from: input.from,
+            to: input.to,
+            platform: input.platform,
+            value: resolved.value,
+            source: "apphud_analytics_api",
+            source_used: resolved.source_used,
+            extracted_from: resolved.extracted_from,
+            warnings: resolved.warnings,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, resolved.raw_payload),
+        };
+    }
+    async metricTimeseries(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const warnings = [];
+        let sourceUsed = "/dash/range";
+        let extractedFrom;
+        let rawPayload;
+        const dashRange = await this.apphudClient.fetchDashRange(app, {
+            apphudAppId: input.apphud_app_id,
+            from: input.from,
+            to: input.to,
+            granularity: input.granularity,
+            metricKey: input.metric_key,
+            platform: input.platform,
+            filters: input.filters,
+        });
+        rawPayload = dashRange.payload;
+        const extractedDash = extractTimeseries(dashRange.payload, input.metric_key);
+        let points = extractedDash.points;
+        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,
+                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;
+        }
+        const summary = toPointSummary(points);
+        return {
+            app_id: app.appId,
+            apphud_app_id: input.apphud_app_id ?? app.appId,
+            metric_key: input.metric_key,
+            from: safeIso(input.from),
+            to: safeIso(input.to),
+            granularity: input.granularity ?? "day",
+            platform: input.platform,
+            points,
+            points_count: points.length,
+            total: Number(summary.total.toFixed(4)),
+            average: summary.average,
+            source: "apphud_analytics_api",
+            source_used: sourceUsed,
+            extracted_from: extractedFrom,
+            warnings,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, rawPayload),
+        };
+    }
+    async metricBreakdown(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const warnings = [];
+        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;
+        if (rows.length === 0) {
+            warnings.push("No breakdown in chart/query/column payload, fallback to dash/range");
+            const dashRange = await this.apphudClient.fetchDashRange(app, {
+                apphudAppId: input.apphud_app_id,
+                from: input.from,
+                to: input.to,
+                granularity: input.granularity,
+                metricKey: input.metric_key,
+                dimension: input.dimension,
+                platform: input.platform,
+                filters: input.filters,
+            });
+            sourceUsed = "/dash/range";
+            rawPayload = dashRange.payload;
+            const extractedRange = extractBreakdown(dashRange.payload, input.metric_key);
+            rows = extractedRange.rows;
+            extractedFrom = extractedRange.path;
+        }
+        const limit = input.limit ?? 20;
+        const limited = rows.slice(0, limit);
+        return {
+            app_id: app.appId,
+            apphud_app_id: input.apphud_app_id ?? app.appId,
+            metric_key: input.metric_key,
+            dimension: input.dimension,
+            from: safeIso(input.from),
+            to: safeIso(input.to),
+            granularity: input.granularity ?? "day",
+            platform: input.platform,
+            rows: mapShares(limited),
+            rows_count: limited.length,
+            source: "apphud_analytics_api",
+            source_used: sourceUsed,
+            extracted_from: extractedFrom,
+            warnings,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, rawPayload),
+        };
+    }
+    async revenueSummary(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const gross = await this.resolveMetricValue(app, {
+            apphudAppId: input.apphud_app_id,
+            metricKey: "revenue_gross",
+            from: input.from,
+            to: input.to,
+            platform: input.platform,
+            filters: input.filters,
+            includeRaw: false,
+            auth,
+        });
+        const refunds = await this.resolveMetricValue(app, {
+            apphudAppId: input.apphud_app_id,
+            metricKey: "refunds",
+            from: input.from,
+            to: input.to,
+            platform: input.platform,
+            filters: input.filters,
+            includeRaw: false,
+            auth,
+        });
+        const grossValue = gross.value ?? 0;
+        const refundsValue = Math.abs(refunds.value ?? 0);
+        const net = gross.value === null && refunds.value === null ? null : Number((grossValue - refundsValue).toFixed(4));
+        let compare;
+        if (input.compare_prev_period) {
+            const prev = shiftPeriod(input.from, input.to);
+            const prevGross = await this.resolveMetricValue(app, {
+                apphudAppId: input.apphud_app_id,
+                metricKey: "revenue_gross",
+                from: prev.from,
+                to: prev.to,
+                platform: input.platform,
+                filters: input.filters,
+                includeRaw: false,
+                auth,
+            });
+            const previous = prevGross.value;
+            const delta = previous === null || gross.value === null ? null : Number((gross.value - previous).toFixed(4));
+            compare = {
+                previous_from: prev.from,
+                previous_to: prev.to,
+                previous_revenue_gross: previous,
+                delta_vs_prev: delta,
+            };
+        }
+        return {
+            app_id: app.appId,
+            apphud_app_id: input.apphud_app_id ?? app.appId,
+            from: safeIso(input.from),
+            to: safeIso(input.to),
+            platform: input.platform,
+            revenue_gross: gross.value,
+            refunds: refunds.value,
+            net_revenue_estimate: net,
+            source: "apphud_analytics_api",
+            source_used: [gross.source_used, refunds.source_used],
+            warnings: Array.from(new Set([...gross.warnings, ...refunds.warnings])),
+            compare_prev_period: compare,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: input.include_raw && auth.role === "admin"
+                ? {
+                    gross: gross.raw_payload,
+                    refunds: refunds.raw_payload,
+                }
+                : undefined,
+        };
+    }
+    async subscriptionsSummary(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const metricInputBase = {
+            apphudAppId: input.apphud_app_id,
+            from: input.from,
+            to: input.to,
+            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, { ...metricInputBase, metricKey: "new_subscriptions" }),
+            this.resolveMetricValue(app, { ...metricInputBase, metricKey: "renewals" }),
+            this.resolveMetricValue(app, { ...metricInputBase, metricKey: "cancellations" }),
+        ]);
+        const churnRateEstimate = typeof cancellations.value === "number" && typeof activePaid.value === "number" && activePaid.value > 0
+            ? Number((cancellations.value / activePaid.value).toFixed(6))
+            : null;
+        return {
+            app_id: app.appId,
+            apphud_app_id: input.apphud_app_id ?? app.appId,
+            from: input.from,
+            to: input.to,
+            platform: input.platform,
+            active_paid: activePaid.value,
+            active_trials: activeTrials.value,
+            new_subscriptions: newSubs.value,
+            renewals: renewals.value,
+            cancellations: cancellations.value,
+            churn_rate_estimate: churnRateEstimate,
+            source: "apphud_analytics_api",
+            source_used: [
+                activePaid.source_used,
+                activeTrials.source_used,
+                newSubs.source_used,
+                renewals.source_used,
+                cancellations.source_used,
+            ],
+            warnings: Array.from(new Set([
+                ...activePaid.warnings,
+                ...activeTrials.warnings,
+                ...newSubs.warnings,
+                ...renewals.warnings,
+                ...cancellations.warnings,
+            ])),
+            retrieved_at: new Date().toISOString(),
+            raw_payload: input.include_raw && auth.role === "admin"
+                ? {
+                    active_paid: activePaid.raw_payload,
+                    active_trials: activeTrials.raw_payload,
+                    new_subscriptions: newSubs.raw_payload,
+                    renewals: renewals.raw_payload,
+                    cancellations: cancellations.raw_payload,
+                }
+                : undefined,
+        };
+    }
+    async conversionTrialToPaid(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const started = await this.resolveMetricValue(app, {
+            apphudAppId: input.apphud_app_id,
+            metricKey: "trials_started",
+            from: input.from,
+            to: input.to,
+            platform: input.platform,
+            filters: input.filters,
+            includeRaw: false,
+            auth,
+        });
+        const converted = await this.resolveMetricValue(app, {
+            apphudAppId: input.apphud_app_id,
+            metricKey: "trials_converted",
+            from: input.from,
+            to: input.to,
+            platform: input.platform,
+            filters: input.filters,
+            includeRaw: false,
+            auth,
+        });
+        const conversionRate = typeof started.value === "number" && started.value > 0 && typeof converted.value === "number"
+            ? Number((converted.value / started.value).toFixed(6))
+            : null;
+        return {
+            app_id: app.appId,
+            apphud_app_id: input.apphud_app_id ?? app.appId,
+            from: safeIso(input.from),
+            to: safeIso(input.to),
+            platform: input.platform,
+            trials_started: started.value,
+            trials_converted: converted.value,
+            conversion_rate: conversionRate,
+            median_time_to_convert: null,
+            source: "apphud_analytics_api",
+            source_used: [started.source_used, converted.source_used],
+            warnings: Array.from(new Set([...started.warnings, ...converted.warnings])),
+            retrieved_at: new Date().toISOString(),
+            raw_payload: input.include_raw && auth.role === "admin"
+                ? {
+                    trials_started: started.raw_payload,
+                    trials_converted: converted.raw_payload,
+                }
+                : undefined,
+        };
+    }
+    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;
+        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,
+            }));
+        }
+        else {
+            warnings.push("No retention series returned by analytics endpoint");
+        }
+        return {
+            app_id: app.appId,
+            apphud_app_id: input.apphud_app_id ?? app.appId,
+            from: safeIso(input.from),
+            to: safeIso(input.to),
+            granularity: input.granularity ?? "week",
+            cohort_by: "subscription_started",
+            rows: [
+                {
+                    cohort_start_date: safeIso(input.from).slice(0, 10),
+                    users_count: null,
+                    periods,
+                },
+            ],
+            source: "apphud_analytics_api",
+            source_used: chart.sourcePath,
+            extracted_from: extractedFrom,
+            warnings,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, chart.payload),
+        };
+    }
+    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"] : [];
+        return {
+            app_id: app.appId,
+            apphud_app_id: input.apphud_app_id ?? app.appId,
+            from: safeIso(input.from),
+            to: safeIso(input.to),
+            granularity: input.granularity ?? "week",
+            rows: [
+                {
+                    cohort_start_date: safeIso(input.from).slice(0, 10),
+                    periods,
+                },
+            ],
+            source: "apphud_analytics_api",
+            source_used: chart.sourcePath,
+            extracted_from: series.path,
+            warnings,
+            retrieved_at: new Date().toISOString(),
+            raw_payload: this.selectRawPayload(auth, input.include_raw, chart.payload),
+        };
+    }
+    async queryRaw(auth, input) {
+        const app = await this.resolveApp(auth, input.app_id, input.apphud_app_id);
+        this.assertRawAccess(auth, input.include_raw);
+        const query = input.query;
+        if (query.shape === "value") {
+            if (!query.metric_key) {
+                throw new ApphudMcpError("INVALID_PAYLOAD", "query.metric_key is required for shape=value", {
+                    statusCode: 400,
+                });
+            }
+            return this.metricValue(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                metric_key: query.metric_key,
+                from: query.from,
+                to: query.to,
+                platform: query.platform,
+                filters: query.filters,
+                include_raw: input.include_raw,
+            });
+        }
+        if (query.shape === "timeseries") {
+            if (!query.metric_key || !query.from || !query.to) {
+                throw new ApphudMcpError("INVALID_PAYLOAD", "query.metric_key/from/to are required for shape=timeseries", {
+                    statusCode: 400,
+                });
+            }
+            return this.metricTimeseries(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                metric_key: query.metric_key,
+                from: query.from,
+                to: query.to,
+                granularity: query.granularity,
+                platform: query.platform,
+                filters: query.filters,
+                include_raw: input.include_raw,
+            });
+        }
+        if (query.shape === "breakdown") {
+            if (!query.metric_key || !query.from || !query.to || !query.dimension) {
+                throw new ApphudMcpError("INVALID_PAYLOAD", "query.metric_key/from/to/dimension are required for shape=breakdown", {
+                    statusCode: 400,
+                });
+            }
+            return this.metricBreakdown(auth, {
+                app_id: input.app_id,
+                apphud_app_id: input.apphud_app_id,
+                metric_key: query.metric_key,
+                from: query.from,
+                to: query.to,
+                dimension: query.dimension,
+                granularity: query.granularity,
+                platform: query.platform,
+                filters: query.filters,
+                limit: query.limit,
+                include_raw: input.include_raw,
+            });
+        }
+        if (!query.endpoint_path) {
+            throw new ApphudMcpError("INVALID_PAYLOAD", "query.endpoint_path is required for shape=raw", {
+                statusCode: 400,
+            });
+        }
+        const raw = await this.apphudClient.fetchAnalyticsRaw(app, {
+            path: query.endpoint_path,
+            method: query.method,
+            apphudAppId: input.apphud_app_id,
+            query: query.query_params,
+            body: query.body,
+        });
+        return {
+            app_id: app.appId,
+            apphud_app_id: raw.apphudAppId,
+            shape: query.shape,
+            endpoint_path: query.endpoint_path,
+            method: query.method ?? "POST",
+            source: "apphud_analytics_api",
+            status: raw.status,
+            retrieved_at: new Date().toISOString(),
+            response: this.selectRawPayload(auth, true, raw.payload),
+        };
+    }
+    async resolveApp(auth, appId, apphudAppId) {
+        const explicitAppId = appId?.trim() || apphudAppId?.trim();
+        if (explicitAppId) {
+            return this.resolveOrFallbackApp(auth, explicitAppId);
+        }
+        const discovered = await this.apphudClient.listDashboardApps();
+        if (discovered.apps.length === 1) {
+            const single = discovered.apps[0];
+            if (!single) {
+                throw new ApphudMcpError("APP_NOT_FOUND", "No Apphud apps available for this account", {
+                    statusCode: 404,
+                    actionHint: "Check Apphud account apps visibility and analytics permissions",
+                });
+            }
+            return this.resolveOrFallbackApp(auth, single.app_id, single.app_name);
+        }
+        if (discovered.apps.length === 0) {
+            throw new ApphudMcpError("APP_NOT_FOUND", "No Apphud apps available for this account", {
+                statusCode: 404,
+                actionHint: "Check Apphud account apps visibility and analytics permissions",
+            });
+        }
+        throw new ApphudMcpError("INVALID_PAYLOAD", "app_id is required when account has multiple apps", {
+            statusCode: 400,
+            actionHint: "Call apphud.apps.list and pass app_id from returned list",
+            details: {
+                app_ids: discovered.apps.slice(0, 50).map((app) => app.app_id),
+            },
+        });
+    }
+    async resolveOrFallbackApp(auth, appId, appName) {
+        try {
+            return await this.appService.requireActiveAppForTenant(appId, auth.tenantId);
+        }
+        catch (error) {
+            if (!isApphudMcpError(error) || error.code !== "APP_NOT_FOUND") {
+                throw error;
+            }
+            const now = new Date().toISOString();
+            return {
+                appId,
+                tenantId: auth.tenantId,
+                name: appName ?? appId,
+                status: "active",
+                secretsRef: "UNUSED",
+                webhookSecretRef: undefined,
+                createdAt: now,
+                updatedAt: now,
+            };
+        }
+    }
+    async resolveMetricValue(app, options) {
+        const warnings = [];
+        if (options.from && options.to) {
+            const dashRange = await this.apphudClient.fetchDashRange(app, {
+                apphudAppId: options.apphudAppId,
+                from: options.from,
+                to: options.to,
+                metricKey: options.metricKey,
+                platform: options.platform,
+                filters: options.filters,
+            });
+            const extractedRange = extractMetricValue(dashRange.payload, options.metricKey);
+            if (extractedRange.value !== null) {
+                return {
+                    value: extractedRange.value,
+                    source_used: "/dash/range",
+                    extracted_from: extractedRange.path,
+                    raw_payload: this.selectRawPayload(options.auth, options.includeRaw, dashRange.payload),
+                    warnings,
+                };
+            }
+            const extractedSeries = extractTimeseries(dashRange.payload, options.metricKey);
+            if (extractedSeries.points.length > 0) {
+                const total = extractedSeries.points.reduce((sum, point) => sum + point.value, 0);
+                return {
+                    value: Number(total.toFixed(4)),
+                    source_used: "/dash/range",
+                    extracted_from: extractedSeries.path,
+                    raw_payload: this.selectRawPayload(options.auth, options.includeRaw, dashRange.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,
+                apphudAppId: options.apphudAppId,
+                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);
+                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,
+                };
+            }
+            return {
+                value: null,
+                source_used: chart.sourcePath,
+                raw_payload: this.selectRawPayload(options.auth, options.includeRaw, chart.payload),
+                warnings: [...warnings, "Metric not found in analytics payloads"],
+            };
+        }
+        const dashNow = await this.apphudClient.fetchDashNow(app, {
+            apphudAppId: options.apphudAppId,
+            platform: options.platform,
+            filters: options.filters,
+        });
+        const extractedNow = extractMetricValue(dashNow.payload, options.metricKey);
+        if (extractedNow.value !== null) {
+            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/now payload, fallback to chart/query/line");
+        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);
+        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"],
+        };
+    }
+    assertRawAccess(auth, includeRaw) {
+        if (!includeRaw) {
+            return;
+        }
+        if (auth.role !== "admin") {
+            throw new ApphudMcpError("FORBIDDEN", "Only admin can request raw payload", {
+                statusCode: 403,
+            });
+        }
+    }
+    selectRawPayload(auth, includeRaw, payload) {
+        if (!includeRaw) {
+            return undefined;
+        }
+        if (auth.role !== "admin") {
+            throw new ApphudMcpError("FORBIDDEN", "Only admin can request raw payload", {
+                statusCode: 403,
+            });
+        }
+        return payload;
+    }
+}