gamealgo-cli 0.4.2 → 0.4.3

package/README.md

@@ -49,6 +49,24 @@ gamealgo report advanced list
 
 All Report Packs use `schemaVersion: 2`, with custom `groups[].views` or platform-owned `groups[].standard`. Advanced query runs are explicit, are never preloaded, and remain available as immutable reports for 30 days.
 
+Managed marketing lifecycle queries can choose their runtime cohort shape without editing or publishing the Pack. For example, this returns one row per channel, Campaign, and country with D0–D30 retention as columns:
+
+```bash
+gamealgo report advanced run \
+  --query-id retention_drilldown \
+  --platform ios \
+  --from 2026-08-08 \
+  --to 2026-09-22 \
+  --observation-end 2026-09-22 \
+  --group-by network,campaign,country_code \
+  --day-offsets 0-30 \
+  --pivot-metric retention_rate \
+  --filter network=Meta \
+  --wait --out retention.json --json
+```
+
+Repeat `--filter field=value1,value2` for `cohort_dt`, `day_offset`, `network`, `campaign`, `campaign_id`, `country_code`, or `platform`. The CLI combines different fields with AND, merges repeated values for the same field, and automatically adds the internal `day_offset` grouping when `--group-by` is present. `--pivot-metric` accepts `retention_rate`, `active_users`, `daily_revenue`, `cumulative_revenue`, `ltv`, or `roas`; `--min-cohort-size` removes undersized groups.
+
 Help and documentation are fetched from the configured Server on every invocation. The CLI intentionally does not keep a documentation cache.
 
 ## Agent skill

package/dist/commands/report.js

@@ -165,6 +165,7 @@ export async function handleReport(client, args, global) {
 async function handleAdvancedReport(client, args, global) {
     const action = args.shift();
     if (action === "run") {
+        const marketingFilters = parseMarketingCohortFilterFlags(args);
         const flags = parseFlags(args);
         const queryId = requiredTextFlag(flags["query-id"], "--query-id");
         const startDate = requiredTextFlag(flags.from || flags.start || flags.startDate, "--from");
@@ -180,6 +181,7 @@ async function handleAdvancedReport(client, args, global) {
         const pack = packPath ? await readJsonFile(packPath) : undefined;
         if (pack !== undefined)
             assertWritableReportPackV2(pack, "report advanced run");
+        const marketingCohort = marketingCohortRunOptions(flags, marketingFilters);
         const wait = booleanFlag(flags.wait, "--wait");
         const timeoutMs = reportTimeoutMs(flags) ?? 15 * 60 * 1000;
         await announceTargetGame(client);
@@ -189,6 +191,7 @@ async function handleAdvancedReport(client, args, global) {
             endDate,
             platform,
             ...(pack !== undefined ? { pack } : {}),
+            ...(marketingCohort ? { marketingCohort } : {}),
         }, { timeoutMs: Math.min(timeoutMs, 30_000) });
         if (!wait) {
             await writeAdvancedOutput(created, flags, global);
@@ -229,6 +232,143 @@ async function handleAdvancedReport(client, args, global) {
     }
     throw new Error("usage: gamealgo report advanced <run|get|list>");
 }
+const MARKETING_COHORT_DIMENSIONS = new Set([
+    "cohort_dt",
+    "day_offset",
+    "network",
+    "campaign",
+    "campaign_id",
+    "country_code",
+    "platform",
+]);
+const MARKETING_COHORT_PIVOT_METRICS = new Set([
+    "retention_rate",
+    "active_users",
+    "daily_revenue",
+    "cumulative_revenue",
+    "ltv",
+    "roas",
+]);
+function parseMarketingCohortFilterFlags(args) {
+    const grouped = new Map();
+    for (let index = 0; index < args.length;) {
+        if (args[index] !== "--filter") {
+            index += 1;
+            continue;
+        }
+        const expression = args[index + 1];
+        if (!expression || expression.startsWith("--"))
+            throw new Error("--filter requires field=value");
+        const separator = expression.indexOf("=");
+        if (separator <= 0)
+            throw new Error("--filter must use field=value or field=value1,value2");
+        const field = normalizeMarketingCohortDimension(expression.slice(0, separator).trim(), "--filter");
+        const values = expression.slice(separator + 1).split(",").map((value) => value.trim()).filter(Boolean);
+        if (!values.length)
+            throw new Error(`--filter ${field} requires at least one value`);
+        grouped.set(field, [...new Set([...(grouped.get(field) ?? []), ...values])]);
+        args.splice(index, 2);
+    }
+    return [...grouped].map(([field, values]) => ({ field, values }));
+}
+function marketingCohortRunOptions(flags, filters) {
+    const cohortFlagNames = ["observation-end", "group-by", "day-offsets", "min-cohort-size", "pivot-metric"];
+    if (!filters.length && !cohortFlagNames.some((flag) => flags[flag] !== undefined))
+        return undefined;
+    const observationEndDate = optionalTextFlag(flags["observation-end"], "--observation-end");
+    if (observationEndDate && !isIsoDate(observationEndDate)) {
+        throw new Error("--observation-end must use YYYY-MM-DD");
+    }
+    const groupByValue = optionalTextFlag(flags["group-by"], "--group-by");
+    const groupBy = groupByValue
+        ? [...new Set(groupByValue.split(",")
+                .map((field) => normalizeMarketingCohortDimension(field.trim(), "--group-by"))
+                .filter(Boolean))]
+        : undefined;
+    if (groupBy && !groupBy.includes("day_offset"))
+        groupBy.push("day_offset");
+    const dayOffsetsValue = optionalTextFlag(flags["day-offsets"], "--day-offsets");
+    const dayOffsets = dayOffsetsValue ? parseMarketingCohortDayOffsets(dayOffsetsValue) : undefined;
+    const minCohortSizeValue = optionalTextFlag(flags["min-cohort-size"], "--min-cohort-size");
+    const minCohortSize = minCohortSizeValue === undefined ? undefined : Number(minCohortSizeValue);
+    if (minCohortSize !== undefined && (!Number.isInteger(minCohortSize) || minCohortSize < 1 || minCohortSize > 1_000_000)) {
+        throw new Error("--min-cohort-size must be an integer between 1 and 1000000");
+    }
+    const pivotMetric = optionalTextFlag(flags["pivot-metric"], "--pivot-metric");
+    if (pivotMetric && !MARKETING_COHORT_PIVOT_METRICS.has(pivotMetric)) {
+        throw new Error(`--pivot-metric must be one of ${[...MARKETING_COHORT_PIVOT_METRICS].join(", ")}`);
+    }
+    if (pivotMetric && !groupBy) {
+        throw new Error("--group-by is required when --pivot-metric is used");
+    }
+    const filter = filters.length === 0
+        ? undefined
+        : filters.length === 1
+            ? marketingCohortFilter(filters[0])
+            : { op: "and", filters: filters.map(marketingCohortFilter) };
+    return {
+        ...(observationEndDate ? { observationEndDate } : {}),
+        ...(groupBy ? { groupBy } : {}),
+        ...(dayOffsets ? { dayOffsets } : {}),
+        ...(minCohortSize !== undefined ? { minCohortSize } : {}),
+        ...(pivotMetric ? { pivotMetric } : {}),
+        ...(filter ? { filter } : {}),
+    };
+}
+function marketingCohortFilter(input) {
+    const values = input.field === "day_offset"
+        ? input.values.map((value) => {
+            const day = Number(value);
+            if (!Number.isInteger(day) || day < 0 || day > 30) {
+                throw new Error("--filter day_offset values must be integers between 0 and 30");
+            }
+            return day;
+        })
+        : input.values;
+    return values.length === 1
+        ? { field: input.field, op: "eq", value: values[0] }
+        : { field: input.field, op: "in", values };
+}
+function normalizeMarketingCohortDimension(value, flag) {
+    const aliases = {
+        channel: "network",
+        country: "country_code",
+        "campaign-id": "campaign_id",
+    };
+    const normalized = aliases[value] ?? value;
+    if (!MARKETING_COHORT_DIMENSIONS.has(normalized)) {
+        throw new Error(`${flag} dimension must be one of ${[...MARKETING_COHORT_DIMENSIONS].join(", ")}`);
+    }
+    return normalized;
+}
+function parseMarketingCohortDayOffsets(value) {
+    const offsets = new Set();
+    for (const part of value.split(",").map((item) => item.trim()).filter(Boolean)) {
+        const match = part.match(/^D?(\d+)(?:\s*-\s*D?(\d+))?$/i);
+        if (!match)
+            throw new Error("--day-offsets must use 0-30 or a comma-separated list such as 0,1,7,14,30");
+        const start = Number(match[1]);
+        const end = match[2] === undefined ? start : Number(match[2]);
+        if (start > end || start < 0 || end > 30) {
+            throw new Error("--day-offsets values must be between 0 and 30");
+        }
+        for (let day = start; day <= end; day += 1)
+            offsets.add(day);
+    }
+    if (!offsets.size)
+        throw new Error("--day-offsets requires at least one value");
+    return [...offsets].sort((left, right) => left - right);
+}
+function optionalTextFlag(value, flag) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${flag} requires a value`);
+    return value.trim();
+}
+function isIsoDate(value) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(`${value}T00:00:00.000Z`));
+}
 async function waitForAdvancedReport(client, runId, timeoutMs, startedAt) {
     while (true) {
         const response = await client.getAdvancedReportRun(runId, true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gamealgo-cli",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "GameAlgo command-line client for AI agents and game developers",
   "repository": {
     "type": "git",

package/skills/gamealgo/SKILL.md

@@ -59,6 +59,8 @@ Keep ratio and average components as additive Dataset columns and calculate the
 
 Use `gamealgo report result` to read an existing ordinary v2 materialization for an explicit date range and scope. It never starts a DW query. Use `gamealgo report advanced run --query-id <id> --platform <platform> --from <date> --to <date>` only when an explicit high-dimensional or non-preloaded query is required. `--pack <file>` supplies an immutable v2 Pack snapshot for that Run without publishing it. `advanced get` and `advanced list` only read the saved Run/history. Advanced results are whole-run bounded to 20,000 rows and 20 MiB and retained for 30 days; never replace this path with local production scans or a hidden query side channel.
 
+For a managed `marketing/lifecycle` advanced Dataset, use runtime cohort flags instead of generating many near-duplicate Packs: `--observation-end <date>`, `--group-by <comma-separated dimensions>`, `--day-offsets <0-30|list>`, `--min-cohort-size <n>`, `--pivot-metric <metric>`, and repeatable `--filter field=value1,value2`. The CLI automatically adds `day_offset` to `--group-by`. Prefer pivoting one requested metric so the 20,000-row check applies after D0–D30 become columns. When the user wants one aggregate matrix for the selected acquisition range, omit `cohort_dt`; include it only when separate daily cohorts are explicitly required.
+
 For initial integration or business dashboard work, standard dashboards are only the baseline. During the initial integration, inspect the actual game loop and define a separate game-specific new-user flow dashboard with meaningful milestones and drop-off diagnostics. Add required milestone telemetry and event catalog fields in the same integration instead of waiting for production volume. Validate the pipeline with test data; label business conclusions as awaiting data when production samples are immature, but do not omit the dashboard design.
 
 ## Follow Mandatory Checkpoints