gamealgo-cli 0.4.2 → 0.4.4

package/README.md

@@ -18,10 +18,13 @@ Run login from the game repository that should own the credentials:
 ```bash
 gamealgo login --host <admin-url> --admin-key <ga_admin_key>
 gamealgo whoami
+gamealgo quota --json
 ```
 
 The login is stored in the current project's `.gamealgo/cli.json`, which is automatically ignored by Git. Authenticated commands require this project-scoped login and verify its `gameId` against the Server before continuing, preventing credentials from another game from being reused accidentally.
 
+`gamealgo quota --json` returns the current effective plan, the per-user daily ordinary-event limit, UTC reset time, detail-query and retention windows, exempt revenue events, and today's actual quota-filtered count. Check it before adding or increasing telemetry.
+
 ## Current help and documentation
 
 ```bash
@@ -49,6 +52,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/client.js

@@ -201,6 +201,9 @@ export class GameAlgoAdminClient {
     async countEvents(body, options = {}) {
         return await this.post(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/count`, body, options);
     }
+    async getGameQuota() {
+        return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/quota`);
+    }
     async listEventCatalog(days = 30, diagnostics = true) {
         const params = new URLSearchParams({ days: String(days), diagnostics: diagnostics ? "1" : "0" });
         return await this.get(`/admin/v1/games/${encodeURIComponent(await this.gameId())}/events/catalog?${params.toString()}`);

package/dist/commands/dynamic-config.js

@@ -49,6 +49,12 @@ export async function handleDynamicConfig(client, args, global) {
         const key = optionalString(definition.key);
         if (!key)
             throw new Error("dynamic config definition.key is required");
+        if (definition.reportPack !== undefined) {
+            throw new Error("dynamic config definition.reportPack is no longer supported; inputs must reference the current Report Pack v2");
+        }
+        if (!Array.isArray(definition.inputs) || definition.inputs.length === 0) {
+            throw new Error("dynamic config definition.inputs must be a non-empty array");
+        }
         const body = { ...definition };
         delete body.key;
         const scriptPath = optionalString(flags.script);

package/dist/commands/quota.js

@@ -0,0 +1,16 @@
+import { parseFlags } from "../args.js";
+import { printResult } from "../output.js";
+import { writeTextFile } from "../resources.js";
+export async function handleQuota(client, args, global) {
+    const flags = parseFlags(args);
+    if (args.length)
+        throw new Error("usage: gamealgo quota [--out quota.json]");
+    const value = await client.getGameQuota();
+    if (flags.out) {
+        const filePath = String(flags.out);
+        await writeTextFile(filePath, JSON.stringify(value, null, 2) + "\n");
+        await printResult({ ok: true, out: filePath }, global);
+        return;
+    }
+    await printResult(value, global);
+}

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/dist/main.js

@@ -7,6 +7,7 @@ import { handleIntegration } from "./commands/integration.js";
 import { handleGameKey } from "./commands/keys.js";
 import { handleMarketing } from "./commands/marketing.js";
 import { handleOptimize } from "./commands/optimize.js";
+import { handleQuota } from "./commands/quota.js";
 import { handleReport } from "./commands/report.js";
 import { handleFileResource } from "./commands/resources.js";
 import { handleSkill } from "./commands/skill.js";
@@ -95,6 +96,10 @@ export async function main() {
             await handleEvents(client, args, global);
             return;
         }
+        if (command === "quota") {
+            await handleQuota(client, args, global);
+            return;
+        }
         if (command === "integration") {
             await handleIntegration(client, args, global);
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gamealgo-cli",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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
@@ -112,11 +114,16 @@ After approval, update the actual emission call sites and their normal-flow test
 
 ## Bound Custom Event Volume
 
-Before adding or changing a custom event, prefer a protocol-standard event or an existing custom event with the same meaning. Keep the event type stable and put variable values in payload fields; never generate event types from item IDs, levels, timestamps, user input, or other runtime values.
+Before adding or changing any event, run `gamealgo quota --json` and `gamealgo events list --days 30 --json`. Treat the returned effective plan and `ordinaryEvents.dailyLimitPerUser` as a hard per-game, per-user, per-UTC-day budget shared by standard and custom ordinary events. Estimate the user's total ordinary event volume across all existing and proposed call sites, leave headroom for normal retries and future events, and reduce or aggregate high-frequency telemetry before implementation when the bound can reach the current limit.
+
+Prefer a protocol-standard event or an existing custom event with the same meaning. Keep the event type stable and put variable values in payload fields; never generate event types from item IDs, levels, timestamps, user input, or other runtime values.
 
 Inspect every call site for render/update loops, timers, polling, transport retries, duplicate lifecycle callbacks, and re-entrant listeners. State the trigger boundary and estimate the maximum calls per user, session, context, and active user-day. Use the game's active-user estimate to describe the expected daily volume when it is available.
 
 - Standard SDK semantic events are governed by their protocol semantics. Do not disguise custom telemetry as a standard event to bypass safeguards.
+- `purchase` and `ad_view` are exempt only when they represent their real protocol semantics and pass their strict validation. Every other accepted event consumes the ordinary daily budget, including standard events and repeated `eventId` submissions.
+- `quota.today.filteredEvents` is the number of ordinary events actually rejected by quota enforcement today; `shadowWouldRejectEvents` is observation-only and must not be reported as data loss. If actual filtering is nonzero, identify and fix the highest-frequency emission paths before proposing more events.
+- The quota resets at UTC midnight, not the player's local midnight. If quota information is unavailable, do not assume Free, Enterprise, or unlimited capacity; report the missing prerequisite and avoid publishing a higher-volume telemetry design.
 - The SDK limits custom events to 1,000 occurrences per `context × eventType`, 5,000 total occurrences per context, and 100 distinct custom event types per context.
 - A custom event with an unbounded trigger or an expected rate above 1,000 calls per context requires explicit developer review before implementation. Explain the expected volume, storage and processing impact, and the guard that makes the trigger bounded.
 - Never add client-side retries around `track`, rename an event after rejection, remove its custom-event prefix, declare it standard, raise a safety limit, or call a lower-level transport to bypass a quota.
@@ -126,14 +133,15 @@ Before delivery, report the estimated bound, normal-flow tests, the limiting loo
 
 ## Treat Dynamic Config As A Production Publisher
 
-A dynamic config pipeline is Server-side automation that turns aggregated Report Pack inputs into a live config file. It does not authorize SDK changes, detailed production-data downloads, or live publication by itself.
+A dynamic config pipeline is Server-side automation that turns current Report Pack v2 ordinary Dataset snapshots into a live config file. It does not authorize SDK changes, detailed production-data downloads, or live publication by itself.
 
 - Define bounded aggregate inputs with Report Pack syntax. Keep filters, joins, aggregation, and data reduction in the managed query rather than passing event detail to JavaScript.
 - Keep transforms synchronous and deterministic. They may use only the supplied datasets, previous output, and scheduled metadata; never depend on network, filesystem, environment variables, wall-clock APIs, randomness, async functions, or Promise output.
 - The output file name and content type belong to the reviewed pipeline definition. The script may return only file content and JSON diagnostics.
 - Before publishing or materially updating an active pipeline, show the target game, input reports and windows, complete script diff, output file and content type, schedule, expected behavior, failure behavior, and user-facing or operational risks. Obtain explicit approval for that exact publication unless the user already gave it after seeing those details.
 - Prefer a disabled pipeline or a local script test while details are still under discussion. After an authorized publish, trigger one run, inspect the persisted run result and generated file version, and confirm that an unchanged second run is hash-deduplicated before treating the automation as verified.
-- Do not raise the 1 MiB script/input/output caps, the 5,000-row per-dataset cap, the 5-second execution cap, or the minimum 60-minute schedule to bypass a failing design. Reduce data in the Report Pack or simplify the transform.
+- Do not embed a Report Pack, use Advanced Query/raw SQL, or trigger warehouse queries from Dynamic Config. Inputs reuse v2 View aggregation over already-materialized ordinary Datasets and pin the Dataset fingerprint at publish time.
+- Do not raise the 1 MiB script/input/output caps, the 100-row per-input cap, the 500-row total cap, the 5-second execution cap, or the minimum daily schedule to bypass a failing design. Reduce the ordinary Dataset/View result or simplify the transform.
 
 Use `gamealgo dynamic-config list|get|publish|run|runs` for lifecycle operations. Dynamic config output continues through the ordinary SDK config-file delivery mechanism, so do not change client SDK code merely to consume a generated file that already uses the existing config API.