apphud-mcp 0.1.0

package/dist/src/services/apphudClient.js

@@ -0,0 +1,1632 @@
+import { ApphudMcpError, isApphudMcpError } from "../errors/toolError.js";
+const METRIC_VALUE_FIELDS = ["value", "count", "total", "current", "metric_value", "result", "amount", "y"];
+const DATE_CANDIDATE_FIELDS = [
+    "date",
+    "day",
+    "week",
+    "month",
+    "period",
+    "at",
+    "time",
+    "timestamp",
+    "occurred_at",
+    "x",
+    "label",
+];
+const BREAKDOWN_KEY_FIELDS = [
+    "key",
+    "name",
+    "label",
+    "category",
+    "group",
+    "dimension",
+    "country",
+    "platform",
+    "product",
+    "product_id",
+    "x",
+];
+const EVENT_ID_KEYS = ["event_id", "id", "uuid"];
+const EVENT_TYPE_KEYS = ["event_type", "event", "type", "name", "kind", "action"];
+const EVENT_USER_ID_KEYS = ["user_id", "userId", "customer_user_id", "customer_id", "uid", "subscriber_id"];
+const EVENT_PRODUCT_ID_KEYS = ["product_id", "productId", "sku", "subscription_product_id"];
+const EVENT_ORIGINAL_TRANSACTION_ID_KEYS = [
+    "original_transaction_id",
+    "originalTransactionId",
+    "original_tx_id",
+    "transaction_id",
+];
+const EVENT_SUBSCRIPTION_STATUS_KEYS = ["subscription_status", "status", "subscriptionState"];
+const EVENT_COUNTRY_KEYS = ["country", "country_code", "countryCode", "storefront"];
+const EVENT_PLATFORM_KEYS = ["platform", "os", "store"];
+const EVENT_PRICE_KEYS = ["price", "amount", "revenue", "proceeds", "value"];
+const EVENT_CURRENCY_KEYS = ["currency", "currency_code", "currencyCode"];
+const METRIC_KEY_ALIASES = {
+    active_subs: [
+        "active_subs",
+        "active_subscription",
+        "active_subscriptions",
+        "active_paid_subs",
+        "active_paid_subscription",
+        "active_paid_subscriptions",
+    ],
+    active_trials: ["active_trials", "active_trial", "trials_active"],
+    revenue_gross: ["revenue", "gross_revenue", "revenue_gross", "sales", "proceeds"],
+    refunds: ["refunds", "refunded", "refund_amount"],
+    trials_started: ["trials_started", "trial_started", "trials"],
+    trials_converted: ["trials_converted", "trial_converted", "trial_to_paid"],
+    new_subscriptions: ["new_subscriptions", "subscription_started", "subscriptions_started", "new_subs"],
+    renewals: ["renewals", "subscription_renewals"],
+    cancellations: ["cancellations", "canceled", "expires", "expirations"],
+    subscribers_retention: ["subscribers_retention", "retention", "subscription_retention"],
+    cumulative_ltv: ["cumulative_ltv", "ltv", "lifetime_value"],
+};
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function asArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => !!item && typeof item === "object");
+}
+function readStringValue(value) {
+    if (typeof value === "string" && value.trim().length > 0) {
+        return value.trim();
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return String(value);
+    }
+    return undefined;
+}
+function readRecordString(record, keys) {
+    for (const key of keys) {
+        const value = readStringValue(record[key]);
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function readBooleanValue(value) {
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        if (value === 1) {
+            return true;
+        }
+        if (value === 0) {
+            return false;
+        }
+        return undefined;
+    }
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (["1", "true", "yes", "y"].includes(normalized)) {
+            return true;
+        }
+        if (["0", "false", "no", "n"].includes(normalized)) {
+            return false;
+        }
+    }
+    return undefined;
+}
+function extractDashboardApps(payload) {
+    const idKeys = ["app_id", "appId", "id", "apple_id", "bundle_id", "bundleId", "slug"];
+    const nameKeys = ["app_name", "appName", "name", "title", "display_name", "bundle_id", "bundleId"];
+    const platformKeys = ["platform", "store", "os"];
+    const apps = new Map();
+    const visited = new WeakSet();
+    const maybeAddApp = (record) => {
+        let appId;
+        let appName;
+        let platform;
+        for (const key of idKeys) {
+            appId = readStringValue(record[key]);
+            if (appId) {
+                break;
+            }
+        }
+        for (const key of nameKeys) {
+            appName = readStringValue(record[key]);
+            if (appName) {
+                break;
+            }
+        }
+        for (const key of platformKeys) {
+            platform = readStringValue(record[key]);
+            if (platform) {
+                break;
+            }
+        }
+        if (!appId) {
+            return;
+        }
+        const normalizedId = appId.trim();
+        if (!normalizedId) {
+            return;
+        }
+        if (!apps.has(normalizedId)) {
+            apps.set(normalizedId, {
+                app_id: normalizedId,
+                app_name: appName ?? normalizedId,
+                platform,
+            });
+            return;
+        }
+        const existing = apps.get(normalizedId);
+        if (!existing) {
+            return;
+        }
+        if (existing.app_name === normalizedId && appName) {
+            existing.app_name = appName;
+        }
+        if (!existing.platform && platform) {
+            existing.platform = platform;
+        }
+    };
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node) {
+                walk(item);
+            }
+            return;
+        }
+        if (!isRecord(node)) {
+            return;
+        }
+        if (visited.has(node)) {
+            return;
+        }
+        visited.add(node);
+        maybeAddApp(node);
+        for (const value of Object.values(node)) {
+            walk(value);
+        }
+    };
+    walk(payload);
+    return Array.from(apps.values()).sort((left, right) => left.app_name.localeCompare(right.app_name));
+}
+function normalizeCustomer(userId, payload) {
+    const root = asRecord(payload.results ?? payload.result ?? payload.customer ?? payload);
+    const subscriptions = asArray(root.subscriptions ?? payload.subscriptions);
+    const purchases = asArray(root.purchases ?? payload.purchases);
+    const activeSubscription = subscriptions.find((subscription) => {
+        const status = String(subscription.status ?? "").toLowerCase();
+        return status === "active" || status === "trial" || status === "in_trial";
+    });
+    const isPremiumField = root.is_premium;
+    const isPremium = typeof isPremiumField === "boolean"
+        ? isPremiumField
+        : Boolean(activeSubscription || root.has_active_subscription === true);
+    const inTrial = Boolean(root.in_trial === true ||
+        root.is_in_trial === true ||
+        String(activeSubscription?.status ?? "").toLowerCase().includes("trial"));
+    const activeProductId = typeof activeSubscription?.product_id === "string"
+        ? activeSubscription.product_id
+        : typeof root.active_product_id === "string"
+            ? root.active_product_id
+            : undefined;
+    const expiresAt = typeof activeSubscription?.expires_at === "string"
+        ? activeSubscription.expires_at
+        : typeof root.expires_at === "string"
+            ? root.expires_at
+            : undefined;
+    return {
+        user_id: userId,
+        is_premium: isPremium,
+        active_product_id: activeProductId,
+        expires_at: expiresAt,
+        in_trial: inTrial,
+        subscriptions: subscriptions.map((subscription) => ({
+            product_id: typeof subscription.product_id === "string" ? subscription.product_id : undefined,
+            status: typeof subscription.status === "string" ? subscription.status : undefined,
+            expires_at: typeof subscription.expires_at === "string" ? subscription.expires_at : undefined,
+            is_in_retry: typeof subscription.is_in_retry === "boolean" ? subscription.is_in_retry : undefined,
+        })),
+        purchases: purchases.map((purchase) => ({
+            product_id: typeof purchase.product_id === "string" ? purchase.product_id : undefined,
+            purchased_at: typeof purchase.purchased_at === "string" ? purchase.purchased_at : undefined,
+            price: typeof purchase.price === "number" ? purchase.price : undefined,
+            currency: typeof purchase.currency === "string" ? purchase.currency : undefined,
+        })),
+        raw_source: "apphud_customers_api",
+        snapshot_at: new Date().toISOString(),
+    };
+}
+function normalizeMetricKey(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+function expandMetricAliases(metricKey) {
+    const normalized = normalizeMetricKey(metricKey);
+    const aliases = new Set([normalized]);
+    const canonicalAliases = METRIC_KEY_ALIASES[normalized] ?? [];
+    for (const alias of canonicalAliases) {
+        aliases.add(normalizeMetricKey(alias));
+    }
+    for (const [canonical, list] of Object.entries(METRIC_KEY_ALIASES)) {
+        if (list.map(normalizeMetricKey).includes(normalized)) {
+            aliases.add(canonical);
+            for (const alias of list) {
+                aliases.add(normalizeMetricKey(alias));
+            }
+        }
+    }
+    return aliases;
+}
+function parseNumericValue(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value !== "string") {
+        return null;
+    }
+    const sanitized = value.replace(/[,_\s]/g, "");
+    if (sanitized.length === 0) {
+        return null;
+    }
+    const parsed = Number(sanitized);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function readMetricValueFromRecord(record, aliases) {
+    if (aliases) {
+        for (const [key, value] of Object.entries(record)) {
+            if (!aliases.has(normalizeMetricKey(key))) {
+                continue;
+            }
+            if (isRecord(value)) {
+                const nested = readMetricValueFromRecord(value);
+                if (nested !== null) {
+                    return nested;
+                }
+            }
+            const numeric = parseNumericValue(value);
+            if (numeric !== null) {
+                return numeric;
+            }
+        }
+    }
+    for (const field of METRIC_VALUE_FIELDS) {
+        const numeric = parseNumericValue(record[field]);
+        if (numeric !== null) {
+            return numeric;
+        }
+    }
+    return null;
+}
+function parseDateValue(value) {
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString();
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        const timestampMs = value > 1_000_000_000_000 ? value : value * 1000;
+        const parsed = new Date(timestampMs);
+        return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+    }
+    return null;
+}
+function extractDateFromRecord(record) {
+    for (const field of DATE_CANDIDATE_FIELDS) {
+        const parsed = parseDateValue(record[field]);
+        if (parsed) {
+            return parsed;
+        }
+    }
+    for (const [key, value] of Object.entries(record)) {
+        if (!/(date|time|day|week|month|period|at|timestamp)/i.test(key)) {
+            continue;
+        }
+        const parsed = parseDateValue(value);
+        if (parsed) {
+            return parsed;
+        }
+    }
+    return null;
+}
+function normalizeEventType(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizeCurrency(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.trim().toUpperCase();
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizePlatform(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized.includes("ios") || normalized.includes("apple")) {
+        return "ios";
+    }
+    if (normalized.includes("android") || normalized.includes("google") || normalized.includes("play")) {
+        return "android";
+    }
+    if (normalized.includes("web")) {
+        return "web";
+    }
+    return undefined;
+}
+function extractBreakdownKeyFromRecord(record) {
+    for (const field of BREAKDOWN_KEY_FIELDS) {
+        const value = record[field];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value;
+        }
+    }
+    return null;
+}
+function metricNamedKey(record) {
+    return normalizeMetricKey(String(record.metric ?? record.key ?? record.id ?? record.name ?? record.code ?? record.slug ?? ""));
+}
+function isLikelyMetricIdentifier(value) {
+    return /[a-z]/.test(value) && value.length >= 3 && value.length <= 80;
+}
+export function extractMetricValue(payload, metricKey) {
+    const aliases = expandMetricAliases(metricKey);
+    const visited = new WeakSet();
+    const search = (node, path) => {
+        if (Array.isArray(node)) {
+            for (let index = 0; index < node.length; index += 1) {
+                const found = search(node[index], `${path}[${index}]`);
+                if (found) {
+                    return found;
+                }
+            }
+            return null;
+        }
+        if (!isRecord(node)) {
+            return null;
+        }
+        if (visited.has(node)) {
+            return null;
+        }
+        visited.add(node);
+        const namedMetric = metricNamedKey(node);
+        if (namedMetric && aliases.has(namedMetric)) {
+            const metricValue = readMetricValueFromRecord(node, aliases);
+            if (metricValue !== null) {
+                return { value: metricValue, path };
+            }
+        }
+        const directValue = readMetricValueFromRecord(node, aliases);
+        if (directValue !== null && path !== "$") {
+            return { value: directValue, path };
+        }
+        for (const [key, value] of Object.entries(node)) {
+            if (aliases.has(normalizeMetricKey(key))) {
+                if (isRecord(value)) {
+                    const nested = readMetricValueFromRecord(value);
+                    if (nested !== null) {
+                        return { value: nested, path: `${path}.${key}` };
+                    }
+                }
+                const direct = parseNumericValue(value);
+                if (direct !== null) {
+                    return { value: direct, path: `${path}.${key}` };
+                }
+            }
+        }
+        for (const [key, value] of Object.entries(node)) {
+            const found = search(value, `${path}.${key}`);
+            if (found) {
+                return found;
+            }
+        }
+        return null;
+    };
+    const extracted = search(payload, "$");
+    return extracted ? extracted : { value: null };
+}
+export function extractActiveSubscriptionsValue(payload) {
+    return extractMetricValue(payload, "active_subs");
+}
+export function extractTimeseries(payload, metricKey) {
+    const aliases = metricKey ? expandMetricAliases(metricKey) : undefined;
+    const visited = new WeakSet();
+    const fromLabelsData = (node, path) => {
+        const labels = Array.isArray(node.labels) ? node.labels : null;
+        if (!labels) {
+            return null;
+        }
+        const dataCandidate = (Array.isArray(node.data) ? node.data : null) ??
+            (Array.isArray(node.values) ? node.values : null) ??
+            (Array.isArray(node.points) ? node.points : null);
+        if (!dataCandidate || dataCandidate.length !== labels.length) {
+            return null;
+        }
+        const points = [];
+        for (let index = 0; index < labels.length; index += 1) {
+            const date = parseDateValue(labels[index]);
+            const value = parseNumericValue(dataCandidate[index]);
+            if (!date || value === null) {
+                continue;
+            }
+            points.push({ date, value });
+        }
+        if (points.length === 0) {
+            return null;
+        }
+        return { points, path };
+    };
+    const parsePointRecord = (record) => {
+        const date = extractDateFromRecord(record);
+        if (!date) {
+            return null;
+        }
+        let value = null;
+        if (aliases) {
+            value = readMetricValueFromRecord(record, aliases);
+        }
+        if (value === null) {
+            value = readMetricValueFromRecord(record);
+        }
+        if (value === null) {
+            return null;
+        }
+        return { date, value };
+    };
+    const search = (node, path) => {
+        if (Array.isArray(node)) {
+            const points = node
+                .map((item) => (isRecord(item) ? parsePointRecord(item) : null))
+                .filter((point) => Boolean(point));
+            if (points.length >= 2) {
+                return { points, path };
+            }
+            for (let index = 0; index < node.length; index += 1) {
+                const found = search(node[index], `${path}[${index}]`);
+                if (found) {
+                    return found;
+                }
+            }
+            return null;
+        }
+        if (!isRecord(node)) {
+            return null;
+        }
+        if (visited.has(node)) {
+            return null;
+        }
+        visited.add(node);
+        const labelsData = fromLabelsData(node, path);
+        if (labelsData) {
+            return labelsData;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            const found = search(value, `${path}.${key}`);
+            if (found) {
+                return found;
+            }
+        }
+        return null;
+    };
+    const extracted = search(payload, "$");
+    if (!extracted) {
+        return { points: [] };
+    }
+    const deduped = extracted.points
+        .slice()
+        .sort((a, b) => a.date.localeCompare(b.date))
+        .filter((point, index, list) => index === 0 || point.date !== list[index - 1]?.date);
+    return { points: deduped, path: extracted.path };
+}
+export function extractBreakdown(payload, metricKey) {
+    const aliases = metricKey ? expandMetricAliases(metricKey) : undefined;
+    const visited = new WeakSet();
+    const fromLabelsData = (node, path) => {
+        const labels = Array.isArray(node.labels) ? node.labels : null;
+        if (!labels) {
+            return null;
+        }
+        const dataCandidate = (Array.isArray(node.data) ? node.data : null) ??
+            (Array.isArray(node.values) ? node.values : null) ??
+            (Array.isArray(node.points) ? node.points : null);
+        if (!dataCandidate || dataCandidate.length !== labels.length) {
+            return null;
+        }
+        const rows = [];
+        for (let index = 0; index < labels.length; index += 1) {
+            const key = labels[index];
+            const numeric = parseNumericValue(dataCandidate[index]);
+            if (typeof key !== "string" || key.trim().length === 0 || numeric === null) {
+                continue;
+            }
+            rows.push({ key, value: numeric });
+        }
+        if (rows.length === 0) {
+            return null;
+        }
+        return { rows, path };
+    };
+    const parseRow = (record) => {
+        const key = extractBreakdownKeyFromRecord(record);
+        if (!key) {
+            return null;
+        }
+        let value = null;
+        if (aliases) {
+            value = readMetricValueFromRecord(record, aliases);
+        }
+        if (value === null) {
+            value = readMetricValueFromRecord(record);
+        }
+        if (value === null) {
+            return null;
+        }
+        return { key, value };
+    };
+    const search = (node, path) => {
+        if (Array.isArray(node)) {
+            const rows = node
+                .map((item) => (isRecord(item) ? parseRow(item) : null))
+                .filter((row) => Boolean(row));
+            if (rows.length > 0) {
+                return { rows, path };
+            }
+            for (let index = 0; index < node.length; index += 1) {
+                const found = search(node[index], `${path}[${index}]`);
+                if (found) {
+                    return found;
+                }
+            }
+            return null;
+        }
+        if (!isRecord(node)) {
+            return null;
+        }
+        if (visited.has(node)) {
+            return null;
+        }
+        visited.add(node);
+        const labelsData = fromLabelsData(node, path);
+        if (labelsData) {
+            return labelsData;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            const found = search(value, `${path}.${key}`);
+            if (found) {
+                return found;
+            }
+        }
+        return null;
+    };
+    const extracted = search(payload, "$");
+    if (!extracted) {
+        return { rows: [] };
+    }
+    return {
+        rows: extracted.rows.sort((a, b) => b.value - a.value),
+        path: extracted.path,
+    };
+}
+export function extractMetricCatalog(payload) {
+    const visited = new WeakSet();
+    const collected = new Map();
+    const maybeAdd = (rawKey, label) => {
+        const raw = typeof rawKey === "string" && rawKey.trim().length > 0 ? rawKey.trim() : undefined;
+        const rawLabel = typeof label === "string" && label.trim().length > 0 ? label.trim() : undefined;
+        const metricKey = normalizeMetricKey(raw ?? rawLabel ?? "");
+        if (!metricKey || !isLikelyMetricIdentifier(metricKey)) {
+            return;
+        }
+        if (!collected.has(metricKey)) {
+            collected.set(metricKey, {
+                metric_key: metricKey,
+                label: rawLabel ?? raw ?? metricKey,
+                raw_key: raw,
+            });
+            return;
+        }
+        const existing = collected.get(metricKey);
+        if (!existing) {
+            return;
+        }
+        if ((!existing.raw_key || existing.raw_key.length === 0) && raw) {
+            existing.raw_key = raw;
+        }
+        if (existing.label === metricKey && rawLabel) {
+            existing.label = rawLabel;
+        }
+    };
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node) {
+                walk(item);
+            }
+            return;
+        }
+        if (!isRecord(node)) {
+            return;
+        }
+        if (visited.has(node)) {
+            return;
+        }
+        visited.add(node);
+        maybeAdd(node.key ?? node.id ?? node.metric ?? node.code ?? node.slug, node.name ?? node.label ?? node.title);
+        for (const [key, value] of Object.entries(node)) {
+            if (["key", "id", "metric", "code", "slug"].includes(key)) {
+                maybeAdd(value, node.name ?? node.label ?? node.title);
+            }
+            walk(value);
+        }
+    };
+    walk(payload);
+    if (collected.size === 0) {
+        const fallback = [
+            "active_subs",
+            "active_trials",
+            "revenue_gross",
+            "refunds",
+            "trials_started",
+            "trials_converted",
+            "new_subscriptions",
+            "renewals",
+            "cancellations",
+            "subscribers_retention",
+            "cumulative_ltv",
+        ];
+        for (const metric of fallback) {
+            collected.set(metric, {
+                metric_key: metric,
+                label: metric,
+            });
+        }
+    }
+    return Array.from(collected.values()).sort((a, b) => a.metric_key.localeCompare(b.metric_key));
+}
+function parseDashboardEventRecord(record) {
+    const eventTypeRaw = readRecordString(record, EVENT_TYPE_KEYS);
+    const eventType = normalizeEventType(eventTypeRaw);
+    const userId = readRecordString(record, EVENT_USER_ID_KEYS);
+    let occurredAt = null;
+    for (const key of ["occurred_at", "created_at", "timestamp", "time", "purchased_at"]) {
+        const parsed = parseDateValue(record[key]);
+        if (parsed) {
+            occurredAt = parsed;
+            break;
+        }
+    }
+    if (!occurredAt) {
+        occurredAt = extractDateFromRecord(record);
+    }
+    const eventId = readRecordString(record, EVENT_ID_KEYS);
+    const productId = readRecordString(record, EVENT_PRODUCT_ID_KEYS);
+    const originalTransactionId = readRecordString(record, EVENT_ORIGINAL_TRANSACTION_ID_KEYS);
+    const subscriptionStatus = readRecordString(record, EVENT_SUBSCRIPTION_STATUS_KEYS);
+    const country = readRecordString(record, EVENT_COUNTRY_KEYS);
+    const platform = normalizePlatform(readRecordString(record, EVENT_PLATFORM_KEYS));
+    const price = (() => {
+        for (const key of EVENT_PRICE_KEYS) {
+            const parsed = parseNumericValue(record[key]);
+            if (parsed !== null) {
+                return parsed;
+            }
+        }
+        return undefined;
+    })();
+    const currency = normalizeCurrency(readRecordString(record, EVENT_CURRENCY_KEYS));
+    let score = 0;
+    if (eventType) {
+        score += 3;
+    }
+    if (userId) {
+        score += 3;
+    }
+    if (occurredAt) {
+        score += 3;
+    }
+    if (productId || originalTransactionId || country || platform || price !== undefined) {
+        score += 1;
+    }
+    if (score < 3) {
+        return { score };
+    }
+    // Avoid false positives on generic date/value arrays by requiring core event identity.
+    if (!eventType && !userId) {
+        return { score };
+    }
+    // Event rows should have a stable locator: time or explicit event id.
+    if (!occurredAt && !eventId) {
+        return { score };
+    }
+    return {
+        score,
+        event: {
+            event_id: eventId,
+            event_type: eventType ?? "unknown",
+            occurred_at: occurredAt ?? undefined,
+            user_id: userId,
+            product_id: productId,
+            original_transaction_id: originalTransactionId,
+            subscription_status: subscriptionStatus,
+            country,
+            platform,
+            price,
+            currency,
+            raw: record,
+        },
+    };
+}
+function extractDashboardEventsPagination(payload) {
+    const visited = new WeakSet();
+    let nextCursor;
+    let hasMore;
+    const readCursor = (record, keys) => {
+        for (const key of keys) {
+            const value = readStringValue(record[key]);
+            if (value) {
+                return value;
+            }
+        }
+        return undefined;
+    };
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node) {
+                walk(item);
+            }
+            return;
+        }
+        if (!isRecord(node)) {
+            return;
+        }
+        if (visited.has(node)) {
+            return;
+        }
+        visited.add(node);
+        if (hasMore === undefined) {
+            for (const key of ["has_more", "hasMore", "has_next", "hasNext", "more"]) {
+                const value = readBooleanValue(node[key]);
+                if (value !== undefined) {
+                    hasMore = value;
+                    break;
+                }
+            }
+        }
+        if (!nextCursor) {
+            nextCursor = readCursor(node, [
+                "next_cursor",
+                "nextCursor",
+                "next_page_cursor",
+                "nextPageCursor",
+                "next_page_token",
+                "nextPageToken",
+                "continuation_token",
+                "continuationToken",
+                "after",
+                "next",
+            ]);
+        }
+        for (const value of Object.values(node)) {
+            walk(value);
+        }
+    };
+    walk(payload);
+    return {
+        nextCursor,
+        hasMore: hasMore ?? (nextCursor ? true : undefined),
+    };
+}
+export function extractDashboardEvents(payload) {
+    const visited = new WeakSet();
+    let best;
+    const maybeTake = (candidate) => {
+        if (candidate.events.length === 0) {
+            return;
+        }
+        if (!best) {
+            best = candidate;
+            return;
+        }
+        if (candidate.score > best.score) {
+            best = candidate;
+            return;
+        }
+        if (candidate.score === best.score && candidate.events.length > best.events.length) {
+            best = candidate;
+        }
+    };
+    const walk = (node, path) => {
+        if (Array.isArray(node)) {
+            const parsed = node
+                .map((item) => (isRecord(item) ? parseDashboardEventRecord(item) : { score: 0 }))
+                .filter((result) => Boolean(result.event));
+            if (parsed.length > 0) {
+                maybeTake({
+                    events: parsed.map((entry) => entry.event),
+                    path,
+                    score: parsed.reduce((sum, entry) => sum + entry.score, 0),
+                });
+            }
+            for (let index = 0; index < node.length; index += 1) {
+                walk(node[index], `${path}[${index}]`);
+            }
+            return;
+        }
+        if (!isRecord(node)) {
+            return;
+        }
+        if (visited.has(node)) {
+            return;
+        }
+        visited.add(node);
+        for (const [key, value] of Object.entries(node)) {
+            walk(value, `${path}.${key}`);
+        }
+    };
+    walk(payload, "$");
+    const pagination = extractDashboardEventsPagination(payload);
+    return {
+        events: best?.events ?? [],
+        path: best?.path,
+        nextCursor: pagination.nextCursor,
+        hasMore: pagination.hasMore,
+    };
+}
+function getAnalyticsStatusFromError(error) {
+    if (!isApphudMcpError(error) || !error.details) {
+        return undefined;
+    }
+    const status = error.details.status;
+    return typeof status === "number" ? status : undefined;
+}
+function shouldTryNextAnalyticsCandidate(error) {
+    if (!isApphudMcpError(error)) {
+        return false;
+    }
+    const status = getAnalyticsStatusFromError(error);
+    return error.code === "UPSTREAM_ERROR" && (status === 404 || status === 405);
+}
+export class ApphudClient {
+    config;
+    secretStore;
+    analyticsSessionCookie = null;
+    analyticsLoginInFlight = null;
+    constructor(config, secretStore) {
+        this.config = config;
+        this.secretStore = secretStore;
+    }
+    async fetchCustomer(app, userId) {
+        const apiKey = await this.secretStore.getSecret(app.secretsRef);
+        if (!apiKey) {
+            throw new ApphudMcpError("FORBIDDEN", `Missing Apphud API key secret for ref ${app.secretsRef}`, {
+                statusCode: 403,
+            });
+        }
+        const baseUrl = this.config.apphudCustomersApiBaseUrl.replace(/\/$/, "");
+        const url = `${baseUrl}/${encodeURIComponent(userId)}`;
+        const headers = new Headers();
+        headers.set(this.config.apphudCustomersApiAuthHeader, `${this.config.apphudCustomersApiAuthPrefix}${apiKey}`);
+        headers.set("Accept", "application/json");
+        let response;
+        try {
+            response = await fetch(url, {
+                method: "GET",
+                headers,
+                signal: AbortSignal.timeout(10_000),
+            });
+        }
+        catch (error) {
+            throw new ApphudMcpError("UPSTREAM_TIMEOUT", "Failed to fetch Apphud Customers API", {
+                statusCode: 504,
+                details: { reason: error instanceof Error ? error.message : "unknown" },
+            });
+        }
+        if (response.status === 402 || response.status === 403) {
+            throw new ApphudMcpError("APPHUD_CUSTOMERS_API_UNAVAILABLE", "Customers API is not available for this Apphud plan", {
+                statusCode: 403,
+                actionHint: "Enable Customers API access in Apphud plan and verify API key permissions",
+            });
+        }
+        if (!response.ok) {
+            const bodyText = await response.text();
+            throw new ApphudMcpError("UPSTREAM_ERROR", `Apphud Customers API request failed with status ${response.status}`, {
+                statusCode: 502,
+                details: { status: response.status, body: bodyText.slice(0, 500) },
+            });
+        }
+        const payloadUnknown = (await response.json());
+        const payload = asRecord(payloadUnknown);
+        const normalized = normalizeCustomer(userId, payload);
+        return {
+            rawPayload: payload,
+            normalized,
+        };
+    }
+    async listAnalyticsMetrics(app, options) {
+        const apphudAppId = options?.apphudAppId ?? app.appId;
+        const attempts = [
+            {
+                path: "/api/v1/chart/list",
+                method: "GET",
+                query: { app: apphudAppId },
+            },
+            {
+                path: "/api/v1/dash/options",
+                method: "GET",
+                query: { app: apphudAppId },
+            },
+        ];
+        let lastError;
+        for (const attempt of attempts) {
+            try {
+                const response = await this.requestAnalytics({
+                    app,
+                    path: attempt.path,
+                    method: attempt.method,
+                    query: attempt.query,
+                    body: attempt.body,
+                });
+                const metrics = extractMetricCatalog(response.payload);
+                if (metrics.length > 0) {
+                    return {
+                        apphudAppId,
+                        metrics,
+                        sourcePath: attempt.path,
+                        rawPayload: response.payload,
+                    };
+                }
+            }
+            catch (error) {
+                if (!shouldTryNextAnalyticsCandidate(error)) {
+                    throw error;
+                }
+                lastError = error;
+            }
+        }
+        if (lastError) {
+            throw lastError;
+        }
+        return {
+            apphudAppId,
+            metrics: extractMetricCatalog({}),
+            sourcePath: "static_fallback",
+            rawPayload: {},
+        };
+    }
+    async listDashboardApps(app) {
+        const authApp = app ?? this.createSyntheticAuthApp();
+        const attempts = [
+            { path: "/apps", method: "GET" },
+            { path: "/apps/list", method: "GET" },
+            { path: "/api/v1/apps", method: "GET" },
+            { path: "/api/v1/apps/list", method: "GET" },
+            { path: "/dash/apps", method: "GET" },
+        ];
+        let lastError;
+        for (const attempt of attempts) {
+            try {
+                const response = await this.requestAnalytics({
+                    app: authApp,
+                    path: attempt.path,
+                    method: attempt.method,
+                });
+                const apps = extractDashboardApps(response.payload);
+                if (apps.length > 0) {
+                    return {
+                        apps,
+                        sourcePath: attempt.path,
+                        rawPayload: response.payload,
+                    };
+                }
+            }
+            catch (error) {
+                if (!shouldTryNextAnalyticsCandidate(error)) {
+                    throw error;
+                }
+                lastError = error;
+            }
+        }
+        if (lastError) {
+            throw lastError;
+        }
+        return {
+            apps: [],
+            sourcePath: "no_apps_detected",
+            rawPayload: {},
+        };
+    }
+    async fetchDashboardEvents(app, options) {
+        const apphudAppId = options.apphudAppId ?? app.appId;
+        const limit = Math.min(Math.max(options.limit ?? 100, 1), 500);
+        const normalizedEventType = normalizeEventType(options.eventType);
+        const filters = this.normalizeFilters({
+            event_type: normalizedEventType,
+            user_id: options.userId,
+            product_id: options.productId,
+            country: options.country,
+            platform: options.platform,
+        });
+        const bodyBase = {
+            app: apphudAppId,
+            from: options.from,
+            to: options.to,
+            time_range: {
+                from: options.from,
+                to: options.to,
+            },
+            limit,
+            filters,
+            use_and: true,
+        };
+        if (options.cursor) {
+            bodyBase.cursor = options.cursor;
+            bodyBase.page_cursor = options.cursor;
+            bodyBase.after = options.cursor;
+        }
+        if (normalizedEventType) {
+            bodyBase.event_type = normalizedEventType;
+            bodyBase.event = normalizedEventType;
+            bodyBase.type = normalizedEventType;
+        }
+        if (options.userId) {
+            bodyBase.user_id = options.userId;
+            bodyBase.customer_user_id = options.userId;
+        }
+        if (options.productId) {
+            bodyBase.product_id = options.productId;
+        }
+        if (options.country) {
+            bodyBase.country = options.country;
+        }
+        if (options.platform) {
+            bodyBase.platform = options.platform;
+        }
+        const queryBase = {
+            app: apphudAppId,
+            from: options.from,
+            to: options.to,
+            limit: String(limit),
+        };
+        if (options.cursor) {
+            queryBase.cursor = options.cursor;
+            queryBase.after = options.cursor;
+            queryBase.page_cursor = options.cursor;
+        }
+        if (normalizedEventType) {
+            queryBase.event_type = normalizedEventType;
+            queryBase.event = normalizedEventType;
+            queryBase.type = normalizedEventType;
+        }
+        if (options.userId) {
+            queryBase.user_id = options.userId;
+            queryBase.customer_user_id = options.userId;
+        }
+        if (options.productId) {
+            queryBase.product_id = options.productId;
+        }
+        if (options.country) {
+            queryBase.country = options.country;
+        }
+        if (options.platform) {
+            queryBase.platform = options.platform;
+        }
+        const attempts = [
+            { path: "/api/v1/events/list", method: "POST", body: bodyBase },
+            { path: "/api/v1/events", method: "POST", body: bodyBase },
+            { path: "/api/v1/subscribers/events", method: "POST", body: bodyBase },
+            { path: "/api/v1/events/list", method: "GET", query: queryBase },
+            { path: "/api/v1/events", method: "GET", query: queryBase },
+            { path: "/events/list", method: "GET", query: queryBase },
+            { path: "/events", method: "GET", query: queryBase },
+        ];
+        let firstSuccess;
+        let lastError;
+        for (const attempt of attempts) {
+            try {
+                const response = await this.requestAnalytics({
+                    app,
+                    path: attempt.path,
+                    method: attempt.method,
+                    query: attempt.query,
+                    body: attempt.body,
+                });
+                const extracted = extractDashboardEvents(response.payload);
+                const current = {
+                    apphudAppId,
+                    events: extracted.events,
+                    sourcePath: attempt.path,
+                    extractionPath: extracted.path,
+                    nextCursor: extracted.nextCursor,
+                    hasMore: extracted.hasMore,
+                    rawPayload: response.payload,
+                };
+                if (!firstSuccess) {
+                    firstSuccess = current;
+                }
+                if (current.events.length > 0 || current.nextCursor || current.hasMore !== undefined) {
+                    return current;
+                }
+            }
+            catch (error) {
+                if (!shouldTryNextAnalyticsCandidate(error)) {
+                    throw error;
+                }
+                lastError = error;
+            }
+        }
+        if (firstSuccess) {
+            return firstSuccess;
+        }
+        if (lastError) {
+            throw lastError;
+        }
+        return {
+            apphudAppId,
+            events: [],
+            sourcePath: "no_events_detected",
+            rawPayload: {},
+        };
+    }
+    async fetchDashNow(app, options) {
+        const apphudAppId = options?.apphudAppId ?? app.appId;
+        const body = {
+            use_and: true,
+            app: apphudAppId,
+            filters: this.normalizeFilters(options?.filters),
+        };
+        if (options?.platform) {
+            body.platform = options.platform;
+        }
+        const response = await this.requestAnalytics({
+            app,
+            path: "/api/v1/dash/now",
+            method: "POST",
+            body,
+        });
+        return {
+            apphudAppId,
+            payload: response.payload,
+        };
+    }
+    async fetchDashRange(app, options) {
+        const apphudAppId = options.apphudAppId ?? app.appId;
+        const body = {
+            use_and: true,
+            app: apphudAppId,
+            time_range: {
+                from: options.from,
+                to: options.to,
+            },
+            filters: this.normalizeFilters(options.filters),
+        };
+        if (options.platform) {
+            body.platform = options.platform;
+        }
+        if (options.granularity) {
+            body.granularity = options.granularity;
+        }
+        if (options.metricKey) {
+            body.chart = options.metricKey;
+            body.metric = options.metricKey;
+        }
+        if (options.dimension) {
+            body.dimension = options.dimension;
+            body.group_by = options.dimension;
+            body.segment_by = options.dimension;
+        }
+        const response = await this.requestAnalytics({
+            app,
+            path: "/api/v1/dash/range",
+            method: "POST",
+            body,
+        });
+        return {
+            apphudAppId,
+            payload: response.payload,
+        };
+    }
+    async fetchChartQuery(app, options) {
+        const apphudAppId = options.apphudAppId ?? app.appId;
+        const body = {
+            app: apphudAppId,
+            chart: options.metricKey,
+            metric: options.metricKey,
+            use_and: true,
+            filters: this.normalizeFilters(options.filters),
+        };
+        if (options.platform) {
+            body.platform = options.platform;
+        }
+        if (options.granularity) {
+            body.granularity = options.granularity;
+        }
+        if (options.dimension) {
+            body.dimension = options.dimension;
+            body.group_by = options.dimension;
+            body.segment_by = options.dimension;
+        }
+        if (options.from && options.to) {
+            body.from = options.from;
+            body.to = options.to;
+            body.time_range = {
+                from: options.from,
+                to: options.to,
+            };
+        }
+        const sourcePath = `/api/v1/chart/query/${options.shape}`;
+        const response = await this.requestAnalytics({
+            app,
+            path: sourcePath,
+            method: "POST",
+            body,
+        });
+        return {
+            apphudAppId,
+            payload: response.payload,
+            sourcePath,
+        };
+    }
+    async fetchActiveSubscriptions(app, options) {
+        const dash = await this.fetchDashNow(app, {
+            apphudAppId: options?.apphudAppId,
+            platform: options?.platform,
+        });
+        const extracted = extractActiveSubscriptionsValue(dash.payload);
+        if (extracted.value !== null) {
+            return {
+                apphudAppId: dash.apphudAppId,
+                value: extracted.value,
+                extractedFrom: extracted.path,
+                rawPayload: dash.payload,
+            };
+        }
+        const chart = await this.fetchChartQuery(app, {
+            shape: "line",
+            metricKey: "active_subs",
+            apphudAppId: dash.apphudAppId,
+            platform: options?.platform,
+        });
+        const fromSeries = extractTimeseries(chart.payload, "active_subs");
+        const lastPoint = fromSeries.points[fromSeries.points.length - 1];
+        return {
+            apphudAppId: dash.apphudAppId,
+            value: lastPoint?.value ?? null,
+            extractedFrom: fromSeries.path,
+            rawPayload: chart.payload,
+        };
+    }
+    async fetchAnalyticsRaw(app, input) {
+        const apphudAppId = input.apphudAppId ?? app.appId;
+        const normalizedPath = this.normalizeAnalyticsPath(input.path);
+        const query = normalizedPath.startsWith("/api/v1/")
+            ? {
+                app: input.query?.app ?? apphudAppId,
+                ...input.query,
+            }
+            : input.query;
+        const response = await this.requestAnalytics({
+            app,
+            path: normalizedPath,
+            method: input.method ?? "POST",
+            query,
+            body: input.body,
+        });
+        return {
+            apphudAppId,
+            payload: response.payload,
+            status: response.status,
+        };
+    }
+    async requestAnalytics(input) {
+        const baseUrl = this.config.apphudAnalyticsApiBaseUrl.replace(/\/$/, "");
+        const cleanPath = this.normalizeAnalyticsPath(input.path);
+        const url = new URL(`${baseUrl}${cleanPath}`);
+        if (input.query) {
+            for (const [key, value] of Object.entries(input.query)) {
+                if (typeof value === "string" && value.length > 0) {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        const headers = new Headers();
+        headers.set("Accept", "application/json");
+        if (input.method !== "GET") {
+            headers.set("Content-Type", "application/json");
+        }
+        const analyticsSecretRef = this.config.apphudAnalyticsAuthSecretRef ??
+            (this.config.apphudAnalyticsAuthHeader.toLowerCase() === "cookie" ? undefined : input.app.secretsRef);
+        const analyticsSecret = analyticsSecretRef ? await this.secretStore.getSecret(analyticsSecretRef) : null;
+        if (analyticsSecret) {
+            headers.set(this.config.apphudAnalyticsAuthHeader, `${this.config.apphudAnalyticsAuthPrefix}${analyticsSecret}`);
+        }
+        else {
+            const sessionCookie = await this.ensureAnalyticsSessionCookie();
+            if (sessionCookie) {
+                headers.set("Cookie", sessionCookie);
+            }
+            else if (analyticsSecretRef) {
+                throw new ApphudMcpError("FORBIDDEN", `Missing Apphud analytics auth secret for ref ${analyticsSecretRef}`, {
+                    statusCode: 403,
+                    actionHint: "Set APPHUD_ANALYTICS_AUTH_SECRET_REF or configure apphud.analytics_login_* refs and provide matching secrets in env",
+                });
+            }
+        }
+        let firstAttempt = await this.executeAnalyticsHttpRequest(url, input.method, headers, input.body, cleanPath);
+        if ((firstAttempt.response.status === 401 || firstAttempt.response.status === 403) && this.isAnalyticsAutoLoginConfigured()) {
+            const refreshedCookie = await this.ensureAnalyticsSessionCookie(true);
+            if (refreshedCookie) {
+                const retryHeaders = new Headers(headers);
+                retryHeaders.delete(this.config.apphudAnalyticsAuthHeader);
+                retryHeaders.set("Cookie", refreshedCookie);
+                firstAttempt = await this.executeAnalyticsHttpRequest(url, input.method, retryHeaders, input.body, cleanPath);
+            }
+        }
+        if (firstAttempt.response.status === 401 || firstAttempt.response.status === 403) {
+            throw new ApphudMcpError("APPHUD_ANALYTICS_API_UNAVAILABLE", "Apphud Analytics endpoint is not available with current credentials", {
+                statusCode: 403,
+                actionHint: "Verify analytics auth value or configure apphud.analytics_login_* (email/password refs) for auto-login and cookie refresh",
+                details: {
+                    status: firstAttempt.response.status,
+                    endpoint: cleanPath,
+                    body: firstAttempt.bodyText.slice(0, 500),
+                },
+            });
+        }
+        if (!firstAttempt.response.ok) {
+            throw new ApphudMcpError("UPSTREAM_ERROR", `Apphud Analytics API request failed with status ${firstAttempt.response.status}`, {
+                statusCode: 502,
+                details: {
+                    status: firstAttempt.response.status,
+                    endpoint: cleanPath,
+                    body: firstAttempt.bodyText.slice(0, 500),
+                },
+            });
+        }
+        return {
+            status: firstAttempt.response.status,
+            payload: this.parseAnalyticsBody(firstAttempt.bodyText),
+        };
+    }
+    createSyntheticAuthApp() {
+        const now = new Date().toISOString();
+        return {
+            appId: "dashboard",
+            tenantId: "tenant_default",
+            name: "dashboard",
+            status: "active",
+            secretsRef: "UNUSED",
+            webhookSecretRef: undefined,
+            createdAt: now,
+            updatedAt: now,
+        };
+    }
+    normalizeAnalyticsPath(path) {
+        const normalized = path.startsWith("/") ? path : `/${path}`;
+        if (normalized.startsWith("/api/")) {
+            return normalized;
+        }
+        if (normalized.startsWith("/dash/") || normalized.startsWith("/chart/")) {
+            return `/api/v1${normalized}`;
+        }
+        return normalized;
+    }
+    async executeAnalyticsHttpRequest(url, method, headers, body, endpoint) {
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body: method === "GET" ? undefined : JSON.stringify(body ?? {}),
+                signal: AbortSignal.timeout(10_000),
+            });
+        }
+        catch (error) {
+            throw new ApphudMcpError("UPSTREAM_TIMEOUT", "Failed to fetch Apphud Analytics API", {
+                statusCode: 504,
+                details: {
+                    endpoint,
+                    reason: error instanceof Error ? error.message : "unknown",
+                },
+            });
+        }
+        return {
+            response,
+            bodyText: await response.text(),
+        };
+    }
+    parseAnalyticsBody(bodyText) {
+        if (bodyText.length === 0) {
+            return {};
+        }
+        try {
+            return JSON.parse(bodyText);
+        }
+        catch {
+            return { raw: bodyText };
+        }
+    }
+    isAnalyticsAutoLoginConfigured() {
+        return Boolean(this.config.apphudAnalyticsLoginEmailSecretRef && this.config.apphudAnalyticsLoginPasswordSecretRef);
+    }
+    async ensureAnalyticsSessionCookie(forceRefresh = false) {
+        if (!forceRefresh && this.analyticsSessionCookie) {
+            return this.analyticsSessionCookie;
+        }
+        if (!this.isAnalyticsAutoLoginConfigured()) {
+            return null;
+        }
+        if (this.analyticsLoginInFlight) {
+            return this.analyticsLoginInFlight;
+        }
+        this.analyticsLoginInFlight = this.refreshAnalyticsSessionCookie();
+        try {
+            const cookie = await this.analyticsLoginInFlight;
+            if (cookie) {
+                this.analyticsSessionCookie = cookie;
+            }
+            return cookie;
+        }
+        finally {
+            this.analyticsLoginInFlight = null;
+        }
+    }
+    async refreshAnalyticsSessionCookie() {
+        const emailRef = this.config.apphudAnalyticsLoginEmailSecretRef;
+        const passwordRef = this.config.apphudAnalyticsLoginPasswordSecretRef;
+        if (!emailRef || !passwordRef) {
+            return null;
+        }
+        const [email, password] = await Promise.all([
+            this.secretStore.getSecret(emailRef),
+            this.secretStore.getSecret(passwordRef),
+        ]);
+        if (!email || !password) {
+            throw new ApphudMcpError("FORBIDDEN", "Missing Apphud analytics auto-login credentials", {
+                statusCode: 403,
+                details: {
+                    email_ref: emailRef,
+                    password_ref: passwordRef,
+                },
+                actionHint: "Set both apphud.analytics_login_* refs in config and matching env vars with Apphud dashboard email/password",
+            });
+        }
+        const loginPath = this.config.apphudAnalyticsLoginPath.startsWith("/")
+            ? this.config.apphudAnalyticsLoginPath
+            : `/${this.config.apphudAnalyticsLoginPath}`;
+        const loginCandidates = this.buildAnalyticsLoginCandidates(loginPath);
+        const headers = new Headers();
+        headers.set("Accept", "application/json");
+        headers.set("Content-Type", "application/json");
+        let lastStatus;
+        let lastBody = "";
+        let lastEndpoint = loginPath;
+        for (const candidate of loginCandidates) {
+            const loginRequest = await this.executeAnalyticsHttpRequest(new URL(candidate.url), "POST", headers, { email, password }, candidate.endpointLabel);
+            lastStatus = loginRequest.response.status;
+            lastBody = loginRequest.bodyText;
+            lastEndpoint = candidate.endpointLabel;
+            if (!loginRequest.response.ok) {
+                if (loginRequest.response.status === 404) {
+                    continue;
+                }
+                throw new ApphudMcpError("APPHUD_ANALYTICS_API_UNAVAILABLE", "Apphud analytics auto-login failed", {
+                    statusCode: 403,
+                    actionHint: "Verify Apphud dashboard email/password and ensure account can log in without extra interactive steps",
+                    details: {
+                        status: loginRequest.response.status,
+                        endpoint: candidate.endpointLabel,
+                        body: loginRequest.bodyText.slice(0, 500),
+                        attempted_login_urls: loginCandidates.map((item) => item.endpointLabel),
+                    },
+                });
+            }
+            const cookieHeader = this.extractCookieHeader(loginRequest.response.headers);
+            if (cookieHeader) {
+                return cookieHeader;
+            }
+            throw new ApphudMcpError("APPHUD_ANALYTICS_API_UNAVAILABLE", "Apphud analytics auto-login returned no session cookie", {
+                statusCode: 403,
+                actionHint: "Re-run login flow in Apphud dashboard and verify analytics endpoint still uses cookie auth",
+                details: {
+                    endpoint: candidate.endpointLabel,
+                    attempted_login_urls: loginCandidates.map((item) => item.endpointLabel),
+                },
+            });
+        }
+        throw new ApphudMcpError("APPHUD_ANALYTICS_API_UNAVAILABLE", "Apphud analytics auto-login failed", {
+            statusCode: 403,
+            actionHint: "Set apphud.analytics_login_path or analytics base URL compatible with your Apphud account (check attempted_login_urls)",
+            details: {
+                status: lastStatus,
+                endpoint: lastEndpoint,
+                body: lastBody.slice(0, 500),
+                attempted_login_urls: loginCandidates.map((item) => item.endpointLabel),
+            },
+        });
+    }
+    buildAnalyticsLoginCandidates(loginPath) {
+        const analyticsBaseUrl = this.config.apphudAnalyticsApiBaseUrl.replace(/\/$/, "");
+        const candidates = [];
+        const seen = new Set();
+        const pushCandidate = (baseUrl, path) => {
+            const normalizedBase = baseUrl.replace(/\/$/, "");
+            const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+            const endpointLabel = `${normalizedBase}${normalizedPath}`;
+            if (seen.has(endpointLabel)) {
+                return;
+            }
+            seen.add(endpointLabel);
+            candidates.push({
+                url: endpointLabel,
+                endpointLabel,
+            });
+        };
+        pushCandidate(analyticsBaseUrl, loginPath);
+        const rootBase = analyticsBaseUrl.replace(/\/api\/v\d+$/i, "");
+        if (rootBase !== analyticsBaseUrl) {
+            pushCandidate(rootBase, loginPath);
+            if (!loginPath.startsWith("/api/")) {
+                pushCandidate(rootBase, `/api/v1${loginPath.startsWith("/") ? loginPath : `/${loginPath}`}`);
+            }
+        }
+        return candidates;
+    }
+    extractCookieHeader(headers) {
+        const getSetCookie = headers.getSetCookie;
+        const setCookieValues = typeof getSetCookie === "function" ? getSetCookie.call(headers) : this.parseSetCookieHeader(headers.get("set-cookie"));
+        if (!setCookieValues || setCookieValues.length === 0) {
+            return null;
+        }
+        const pairs = setCookieValues
+            .map((cookieValue) => cookieValue.split(";")[0]?.trim() ?? "")
+            .filter((cookieValue) => cookieValue.length > 0);
+        if (pairs.length === 0) {
+            return null;
+        }
+        return pairs.join("; ");
+    }
+    parseSetCookieHeader(value) {
+        if (!value) {
+            return [];
+        }
+        return value
+            .split(/,(?=\s*[A-Za-z0-9_!#$%&'*+.^`|~-]+=)/g)
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0);
+    }
+    normalizeFilters(filters) {
+        if (!filters) {
+            return [];
+        }
+        const normalized = [];
+        for (const [key, value] of Object.entries(filters)) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+            normalized.push({
+                id: key,
+                values: [
+                    {
+                        condition: "equals",
+                        value: String(value),
+                    },
+                ],
+            });
+        }
+        return normalized;
+    }
+}