apphud-mcp 0.2.2 → 0.2.5

package/dist/src/services/apphudClient.js

@@ -28,8 +28,8 @@ const BREAKDOWN_KEY_FIELDS = [
 ];
 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_USER_ID_KEYS = ["user_id", "userId", "customer_user_id", "customer_id", "customer_uid", "uid", "subscriber_id"];
+const EVENT_PRODUCT_ID_KEYS = ["product_id", "productId", "sku", "subscription_product_id", "product"];
 const EVENT_ORIGINAL_TRANSACTION_ID_KEYS = [
     "original_transaction_id",
     "originalTransactionId",
@@ -39,7 +39,18 @@ const EVENT_ORIGINAL_TRANSACTION_ID_KEYS = [
 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_PRICE_KEYS = [
+    "price",
+    "price_usd",
+    "amount",
+    "revenue",
+    "proceeds",
+    "value",
+    "usd_price",
+    "local_price",
+    "usd_proceeds",
+    "local_proceeds",
+];
 const EVENT_CURRENCY_KEYS = ["currency", "currency_code", "currencyCode"];
 const METRIC_KEY_ALIASES = {
     active_subs: [
@@ -51,16 +62,51 @@ const METRIC_KEY_ALIASES = {
         "active_paid_subscriptions",
     ],
     active_trials: ["active_trials", "active_trial", "trials_active"],
-    revenue_gross: ["revenue", "gross_revenue", "revenue_gross", "sales", "proceeds"],
+    revenue_gross: ["revenue", "gross_revenue", "revenue_gross"],
+    sales: ["sales"],
+    proceeds: ["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"],
+    trials_converted: ["trials_converted", "trial_converted", "trial_conversions", "trial_to_paid"],
+    new_subscriptions: [
+        "new_subscriptions",
+        "new_regular_subscriptions",
+        "subscription_started",
+        "subscriptions_started",
+        "new_subs",
+    ],
+    renewals: ["renewals", "subscription_renewed", "subscription_renewals"],
+    cancellations: ["cancellations", "trial_canceled", "trial_cancelled", "trial_cancellations", "subscription_canceled"],
+    subscribers_retention: ["subscribers_retention", "subscribers_retention_new", "retention", "subscription_retention"],
     cumulative_ltv: ["cumulative_ltv", "ltv", "lifetime_value"],
 };
+const METRIC_KEY_TO_LABELS = {
+    active_subs: ["Active Paid Subscriptions"],
+    active_trial: ["Active Trials"],
+    active_trials: ["Active Trials"],
+    revenue_gross: ["Gross revenue"],
+    sales: ["Sales"],
+    proceeds: ["Proceeds"],
+    refunds: ["Refunds"],
+    new_subscriptions: ["New Regular Subscriptions"],
+    trials_started: ["Trials"],
+    trials_converted: ["Trial Conversions"],
+    cancellations: ["Trial Cancellations"],
+    new_users: ["New Users"],
+    renewals: ["Renewals"],
+    active_intro: ["Active Intro Offers"],
+    active_promo: ["Active Promo Offers"],
+};
+const METRIC_KEY_REQUEST_ALIASES = {
+    active_trials: ["active_trial"],
+    trials_started: ["trial_started"],
+    trials_converted: ["trial_converted", "trial_conversions"],
+    new_subscriptions: ["subscription_started", "new_regular_subscriptions"],
+    renewals: ["subscription_renewed"],
+    cancellations: ["trial_canceled", "subscription_canceled"],
+    revenue_gross: ["revenue", "gross_revenue"],
+    subscribers_retention: ["subscribers_retention_new"],
+};
 function asRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return {};
@@ -338,6 +384,14 @@ function normalizeMetricKey(value) {
         .replace(/[^a-z0-9]+/g, "_")
         .replace(/^_+|_+$/g, "");
 }
+function resolveMetricRequestKey(metricKey) {
+    const normalized = normalizeMetricKey(metricKey);
+    const direct = METRIC_KEY_REQUEST_ALIASES[normalized];
+    if (direct && direct.length > 0) {
+        return normalizeMetricKey(direct[0] ?? normalized);
+    }
+    return normalized;
+}
 function expandMetricAliases(metricKey) {
     const normalized = normalizeMetricKey(metricKey);
     const aliases = new Set([normalized]);
@@ -355,6 +409,17 @@ function expandMetricAliases(metricKey) {
     }
     return aliases;
 }
+function resolveMetricLabels(metricKey, aliases) {
+    const labels = new Set();
+    const keysToCheck = new Set([normalizeMetricKey(metricKey), ...aliases]);
+    for (const key of keysToCheck) {
+        const mappedLabels = METRIC_KEY_TO_LABELS[key] ?? [];
+        for (const label of mappedLabels) {
+            labels.add(normalizeMetricKey(label));
+        }
+    }
+    return labels;
+}
 function parseNumericValue(value) {
     if (typeof value === "number" && Number.isFinite(value)) {
         return value;
@@ -362,11 +427,15 @@ function parseNumericValue(value) {
     if (typeof value !== "string") {
         return null;
     }
-    const sanitized = value.replace(/[,_\s]/g, "");
-    if (sanitized.length === 0) {
+    const compact = value.replace(/[,_\s]/g, "");
+    if (compact.length === 0) {
+        return null;
+    }
+    const cleaned = compact.replace(/[^0-9+.\-]/g, "");
+    if (!/[0-9]/.test(cleaned)) {
         return null;
     }
-    const parsed = Number(sanitized);
+    const parsed = Number(cleaned);
     return Number.isFinite(parsed) ? parsed : null;
 }
 function readMetricValueFromRecord(record, aliases) {
@@ -514,8 +583,135 @@ function metricNamedKey(record) {
 function isLikelyMetricIdentifier(value) {
     return /[a-z]/.test(value) && value.length >= 3 && value.length <= 80;
 }
+function extractMetricValueFromDashboardGroups(payload, metricKey, aliases) {
+    const expectedLabels = resolveMetricLabels(metricKey, aliases);
+    const matched = [];
+    const available = new Set();
+    const visited = new WeakSet();
+    let hasGroups = false;
+    const walk = (node, path) => {
+        if (Array.isArray(node)) {
+            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);
+        const groups = asArray(node.groups);
+        if (groups.length > 0) {
+            hasGroups = true;
+            for (let groupIndex = 0; groupIndex < groups.length; groupIndex += 1) {
+                const group = groups[groupIndex];
+                if (!group) {
+                    continue;
+                }
+                const items = asArray(group.items);
+                for (let itemIndex = 0; itemIndex < items.length; itemIndex += 1) {
+                    const item = items[itemIndex];
+                    if (!item) {
+                        continue;
+                    }
+                    const itemPath = `${path}.groups[${groupIndex}].items[${itemIndex}]`;
+                    const names = [item.short_name, item.name, item.raw_key, item.metric, item.key, item.chart_id, item.chartId]
+                        .map((value) => readStringValue(value))
+                        .filter((value) => Boolean(value));
+                    const normalizedNames = new Set(names.map((value) => normalizeMetricKey(value)));
+                    const title = readStringValue(item.name) ?? readStringValue(item.short_name) ?? readStringValue(item.raw_key);
+                    if (title) {
+                        available.add(title);
+                    }
+                    const matchesByAlias = Array.from(normalizedNames).some((name) => aliases.has(name));
+                    const matchesByLabel = Array.from(normalizedNames).some((name) => expectedLabels.has(name));
+                    if (!matchesByAlias && !matchesByLabel) {
+                        continue;
+                    }
+                    const values = asArray(item.values);
+                    for (let valueIndex = 0; valueIndex < values.length; valueIndex += 1) {
+                        const valueEntry = values[valueIndex];
+                        if (!valueEntry) {
+                            continue;
+                        }
+                        if (normalizeMetricKey(String(valueEntry.name ?? "")) !== "value") {
+                            continue;
+                        }
+                        const parsedValue = parseNumericValue(valueEntry.value);
+                        if (parsedValue === null) {
+                            continue;
+                        }
+                        matched.push({
+                            name: title ?? "unknown",
+                            path: `${itemPath}.values[${valueIndex}]`,
+                            value: parsedValue,
+                        });
+                    }
+                }
+            }
+        }
+        for (const [key, value] of Object.entries(node)) {
+            walk(value, `${path}.${key}`);
+        }
+    };
+    walk(payload, "$");
+    if (!hasGroups) {
+        return { kind: "not_applicable" };
+    }
+    const availableMetrics = Array.from(available.values()).sort((left, right) => left.localeCompare(right));
+    if (matched.length === 1) {
+        const singleMatch = matched[0];
+        if (!singleMatch) {
+            return {
+                kind: "not_found",
+                availableMetrics,
+            };
+        }
+        return {
+            kind: "resolved",
+            value: singleMatch.value,
+            path: singleMatch.path,
+        };
+    }
+    if (matched.length > 1) {
+        return {
+            kind: "ambiguous",
+            candidates: matched.map((item) => ({ name: item.name, path: item.path })),
+            availableMetrics,
+        };
+    }
+    return {
+        kind: "not_found",
+        availableMetrics,
+    };
+}
 export function extractMetricValue(payload, metricKey) {
     const aliases = expandMetricAliases(metricKey);
+    const dashboardExtraction = extractMetricValueFromDashboardGroups(payload, metricKey, aliases);
+    if (dashboardExtraction.kind === "resolved") {
+        return {
+            value: dashboardExtraction.value,
+            path: dashboardExtraction.path,
+        };
+    }
+    if (dashboardExtraction.kind === "ambiguous") {
+        return {
+            value: null,
+            code: "METRIC_AMBIGUOUS",
+            candidates: dashboardExtraction.candidates,
+            available_metrics: dashboardExtraction.availableMetrics,
+        };
+    }
+    if (dashboardExtraction.kind === "not_found") {
+        return {
+            value: null,
+            code: "METRIC_NOT_FOUND",
+            available_metrics: dashboardExtraction.availableMetrics,
+        };
+    }
     const search = (node, path, mode, visited) => {
         if (Array.isArray(node)) {
             for (let index = 0; index < node.length; index += 1) {
@@ -837,12 +1033,13 @@ export function extractMetricCatalog(payload) {
     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 properties = asRecord(record.properties);
+    const eventTypeRaw = readRecordString(record, EVENT_TYPE_KEYS) ?? readRecordString(properties, EVENT_TYPE_KEYS);
     const eventType = normalizeEventType(eventTypeRaw);
-    const userId = readRecordString(record, EVENT_USER_ID_KEYS);
+    const userId = readRecordString(record, EVENT_USER_ID_KEYS) ?? readRecordString(properties, EVENT_USER_ID_KEYS);
     let occurredAt = null;
     for (const key of ["occurred_at", "created_at", "timestamp", "time", "purchased_at"]) {
-        const parsed = parseDateValue(record[key]);
+        const parsed = parseDateValue(record[key] ?? properties[key]);
         if (parsed) {
             occurredAt = parsed;
             break;
@@ -852,21 +1049,21 @@ function parseDashboardEventRecord(record) {
         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 productId = readRecordString(record, EVENT_PRODUCT_ID_KEYS) ?? readRecordString(properties, EVENT_PRODUCT_ID_KEYS);
+    const originalTransactionId = readRecordString(record, EVENT_ORIGINAL_TRANSACTION_ID_KEYS) ?? readRecordString(properties, EVENT_ORIGINAL_TRANSACTION_ID_KEYS);
+    const subscriptionStatus = readRecordString(record, EVENT_SUBSCRIPTION_STATUS_KEYS) ?? readRecordString(properties, EVENT_SUBSCRIPTION_STATUS_KEYS);
+    const country = readRecordString(record, EVENT_COUNTRY_KEYS) ?? readRecordString(properties, EVENT_COUNTRY_KEYS);
+    const platform = normalizePlatform(readRecordString(record, EVENT_PLATFORM_KEYS) ?? readRecordString(properties, EVENT_PLATFORM_KEYS));
     const price = (() => {
         for (const key of EVENT_PRICE_KEYS) {
-            const parsed = parseNumericValue(record[key]);
+            const parsed = parseNumericValue(record[key] ?? properties[key]);
             if (parsed !== null) {
                 return parsed;
             }
         }
         return undefined;
     })();
-    const currency = normalizeCurrency(readRecordString(record, EVENT_CURRENCY_KEYS));
+    const currency = normalizeCurrency(readRecordString(record, EVENT_CURRENCY_KEYS) ?? readRecordString(properties, EVENT_CURRENCY_KEYS));
     let score = 0;
     if (eventType) {
         score += 3;
@@ -1471,8 +1668,9 @@ export class ApphudClient {
             body.granularity = options.granularity;
         }
         if (options.metricKey) {
-            body.chart = options.metricKey;
-            body.metric = options.metricKey;
+            const requestMetricKey = resolveMetricRequestKey(options.metricKey);
+            body.chart = requestMetricKey;
+            body.metric = requestMetricKey;
         }
         if (options.dimension) {
             body.dimension = options.dimension;
@@ -1492,6 +1690,7 @@ export class ApphudClient {
     }
     async fetchChartQuery(app, options) {
         const apphudAppId = options.apphudAppId ?? app.appId;
+        const requestMetricKey = resolveMetricRequestKey(options.metricKey);
         const step = resolveAnalyticsStepDays({
             from: options.from,
             to: options.to,
@@ -1499,8 +1698,8 @@ export class ApphudClient {
         });
         const body = {
             app: apphudAppId,
-            chart: options.metricKey,
-            metric: options.metricKey,
+            chart: requestMetricKey,
+            metric: requestMetricKey,
             step,
             use_and: true,
             filters: this.normalizeFilters(options.filters),