@koda-sl/baker-cli 0.25.1 → 0.27.0

package/dist/commands/ads/x/promoted-tweets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promoted-tweets.js","sourceRoot":"","sources":["../../../../src/commands/ads/x/promoted-tweets.ts"],"names":[],"mappings":"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"}

package/dist/commands/ads/x/run-list.d.ts

@@ -0,0 +1,17 @@
+interface ListParams {
+    path: string;
+    cacheCategory: string;
+    cacheKey: string;
+    cacheTtlMs?: number;
+    params: Record<string, string | undefined>;
+    format: string;
+    accountId?: string;
+    useCache: boolean;
+}
+/**
+ * Shared GET-list flow: cache check → request → cache set → format-aware output.
+ * Centralizing this keeps each CLI command file under Biome's complexity budget.
+ */
+export declare function runListCommand(opts: ListParams): Promise<void>;
+export {};
+//# sourceMappingURL=run-list.d.ts.map

package/dist/commands/ads/x/run-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-list.d.ts","sourceRoot":"","sources":["../../../../src/commands/ads/x/run-list.ts"],"names":[],"mappings":"AAKA,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAwCD;;;GAGG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAYpE"}

package/dist/commands/ads/x/run-list.js

@@ -0,0 +1,60 @@
+import { ApiError, apiGet } from "../../../client.js";
+import { cacheGet, cacheSet } from "../cache.js";
+import { writeAdsJson, writeAdsOutput } from "../output.js";
+import { parseXApiError } from "./error-parser.js";
+function buildCleanParams(opts) {
+    const out = {};
+    for (const [k, v] of Object.entries(opts.params)) {
+        if (v !== undefined && v !== "") {
+            out[k] = v;
+        }
+    }
+    if (!opts.useCache) {
+        out["skip-cache"] = "true";
+    }
+    return out;
+}
+function emitFromCache(opts) {
+    if (!opts.useCache || opts.cacheTtlMs === undefined)
+        return false;
+    const cached = cacheGet(opts.cacheCategory, opts.cacheKey);
+    if (!cached)
+        return false;
+    writeAdsJson({ ok: true, data: cached.data, cached: true });
+    return true;
+}
+function emitData(opts, data) {
+    if (opts.format !== "json") {
+        writeAdsOutput(data, opts.format);
+        return;
+    }
+    writeAdsJson({ ok: true, data });
+}
+function emitError(opts, err) {
+    if (err instanceof ApiError) {
+        writeAdsJson(parseXApiError(err.message, opts.accountId ?? "—"));
+        process.exit(1);
+    }
+    writeAdsJson({ ok: false, error: { code: "NETWORK_ERROR", message: "Unexpected error" } });
+    process.exit(1);
+}
+/**
+ * Shared GET-list flow: cache check → request → cache set → format-aware output.
+ * Centralizing this keeps each CLI command file under Biome's complexity budget.
+ */
+export async function runListCommand(opts) {
+    if (emitFromCache(opts))
+        return;
+    const params = buildCleanParams(opts);
+    try {
+        const data = await apiGet(opts.path, params);
+        if (opts.useCache && opts.cacheTtlMs !== undefined) {
+            cacheSet(opts.cacheCategory, opts.cacheKey, data, opts.cacheTtlMs);
+        }
+        emitData(opts, data);
+    }
+    catch (err) {
+        emitError(opts, err);
+    }
+}
+//# sourceMappingURL=run-list.js.map

package/dist/commands/ads/x/run-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-list.js","sourceRoot":"","sources":["../../../../src/commands/ads/x/run-list.ts"],"names":[],"mappings":"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"}

package/dist/commands/ads/x/stats/index.d.ts

@@ -0,0 +1,2 @@
+export declare const statsCommand: import("citty").CommandDef<import("citty").ArgsDef>;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/ads/x/stats/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/commands/ads/x/stats/index.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,YAAY,qDAyBvB,CAAC"}

package/dist/commands/ads/x/stats/index.js

@@ -0,0 +1,32 @@
+import { defineCommand } from "citty";
+import { statsJobCommand } from "./job.js";
+import { statsJobCreateCommand } from "./job-create.js";
+import { statsJobStatusCommand } from "./job-status.js";
+import { statsSyncCommand } from "./sync.js";
+export const statsCommand = defineCommand({
+    meta: {
+        name: "stats",
+        description: `X Ads analytics. Sync (≤7 days, no segmentation) or async jobs (≤90 days, segmentable).
+
+Subcommands:
+  sync         — synchronous stats (max 7 days). Cheapest, fastest.
+  job          — async stats job, end-to-end (creates + polls + downloads). Must run in the background.
+                 Use for ranges >7 days, segmented stats, or when sync limits are hit.
+  job-create   — low-level: create an async stats job and return the ID immediately
+  job-status   — low-level: poll job status / get the download URL
+
+Examples:
+  baker ads x stats sync --preset campaign-engagement-7d --entity-ids abc,def
+  baker ads x stats job --account-id 18ce53xyz --entity CAMPAIGN \\
+    --entity-ids abc,def --start-time 2026-04-01T00:00:00Z \\
+    --end-time 2026-05-01T00:00:00Z --metric-groups ENGAGEMENT,BILLING
+  baker ads x stats job-status --account-id 18ce53xyz --job-id abc`,
+    },
+    subCommands: {
+        sync: statsSyncCommand,
+        job: statsJobCommand,
+        "job-create": statsJobCreateCommand,
+        "job-status": statsJobStatusCommand,
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/commands/ads/x/stats/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/commands/ads/x/stats/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;IACxC,IAAI,EAAE;QACJ,IAAI,EAAE,OAAO;QACb,WAAW,EAAE;;;;;;;;;;;;;;mEAckD;KAChE;IACD,WAAW,EAAE;QACX,IAAI,EAAE,gBAAgB;QACtB,GAAG,EAAE,eAAe;QACpB,YAAY,EAAE,qBAAqB;QACnC,YAAY,EAAE,qBAAqB;KACpC;CACF,CAAC,CAAC"}

package/dist/commands/ads/x/stats/job-create.d.ts

@@ -0,0 +1,58 @@
+export declare const statsJobCreateCommand: import("citty").CommandDef<{
+    readonly "account-id": {
+        readonly type: "string";
+        readonly description: "X Ads account ID";
+        readonly required: false;
+    };
+    readonly entity: {
+        readonly type: "string";
+        readonly description: "Entity type";
+        readonly required: true;
+    };
+    readonly "entity-ids": {
+        readonly type: "string";
+        readonly description: "CSV of entity IDs";
+        readonly required: true;
+    };
+    readonly "start-time": {
+        readonly type: "string";
+        readonly description: "ISO start";
+        readonly required: true;
+    };
+    readonly "end-time": {
+        readonly type: "string";
+        readonly description: "ISO end";
+        readonly required: true;
+    };
+    readonly granularity: {
+        readonly type: "string";
+        readonly description: "Granularity";
+        readonly required: false;
+    };
+    readonly "metric-groups": {
+        readonly type: "string";
+        readonly description: "Metric groups CSV";
+        readonly required: true;
+    };
+    readonly placement: {
+        readonly type: "string";
+        readonly description: "Placement";
+        readonly required: false;
+    };
+    readonly "segmentation-type": {
+        readonly type: "string";
+        readonly description: "Segmentation type";
+        readonly required: false;
+    };
+    readonly country: {
+        readonly type: "string";
+        readonly description: "Country filter";
+        readonly required: false;
+    };
+    readonly platform: {
+        readonly type: "string";
+        readonly description: "Platform filter";
+        readonly required: false;
+    };
+}>;
+//# sourceMappingURL=job-create.d.ts.map

package/dist/commands/ads/x/stats/job-create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-create.d.ts","sourceRoot":"","sources":["../../../../../src/commands/ads/x/stats/job-create.ts"],"names":[],"mappings":"AAmCA,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4DhC,CAAC"}

package/dist/commands/ads/x/stats/job-create.js

@@ -0,0 +1,95 @@
+import { defineCommand } from "citty";
+import { ApiError, apiPost } from "../../../../client.js";
+import { registerSchema } from "../../../../schemas.js";
+import { writeAdsJson } from "../../output.js";
+import { parseXApiError } from "../error-parser.js";
+import { resolveXAccountId } from "../output.js";
+registerSchema({
+    command: "ads.x.statsJobCreate",
+    description: "Create an asynchronous X Ads stats job (range up to 90 days non-segmented, 45 days segmented). Returns a job id; poll with `stats job-status`. Times must be ISO 8601 hour-aligned.",
+    args: {
+        "account-id": { type: "string", description: "X Ads account ID", required: false },
+        entity: { type: "string", description: "CAMPAIGN | LINE_ITEM | PROMOTED_TWEET | ...", required: true },
+        "entity-ids": { type: "string", description: "CSV of entity IDs (max 20)", required: true },
+        "start-time": { type: "string", description: "ISO 8601 hour-aligned start", required: true },
+        "end-time": { type: "string", description: "ISO 8601 hour-aligned end", required: true },
+        granularity: { type: "string", description: "TOTAL | DAY | HOUR", required: false },
+        "metric-groups": { type: "string", description: "CSV of metric groups", required: true },
+        placement: { type: "string", description: "ALL_ON_TWITTER | PUBLISHER_NETWORK", required: false },
+        "segmentation-type": { type: "string", description: "Segmentation (e.g. AGE, GENDER, LOCATIONS)", required: false },
+        country: { type: "string", description: "Country filter", required: false },
+        platform: { type: "string", description: "Platform filter", required: false },
+    },
+});
+function parseCsv(v) {
+    if (typeof v !== "string" || v.length === 0)
+        return undefined;
+    const parts = v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return parts.length > 0 ? parts : undefined;
+}
+export const statsJobCreateCommand = defineCommand({
+    meta: {
+        name: "job-create",
+        description: `Create an async X Ads stats job (up to 90 days, supports segmentation).
+
+Examples:
+  baker ads x stats job-create --account-id 18ce53xyz --entity CAMPAIGN \\
+    --entity-ids abc,def --start-time 2026-04-01T00:00:00Z \\
+    --end-time 2026-05-01T00:00:00Z --metric-groups ENGAGEMENT,BILLING \\
+    --segmentation-type LOCATIONS`,
+    },
+    args: {
+        "account-id": { type: "string", description: "X Ads account ID", required: false },
+        entity: { type: "string", description: "Entity type", required: true },
+        "entity-ids": { type: "string", description: "CSV of entity IDs", required: true },
+        "start-time": { type: "string", description: "ISO start", required: true },
+        "end-time": { type: "string", description: "ISO end", required: true },
+        granularity: { type: "string", description: "Granularity", required: false },
+        "metric-groups": { type: "string", description: "Metric groups CSV", required: true },
+        placement: { type: "string", description: "Placement", required: false },
+        "segmentation-type": { type: "string", description: "Segmentation type", required: false },
+        country: { type: "string", description: "Country filter", required: false },
+        platform: { type: "string", description: "Platform filter", required: false },
+    },
+    run: async ({ args }) => {
+        const accountId = await resolveXAccountId(args);
+        const entityIds = parseCsv(args["entity-ids"]);
+        const metricGroups = parseCsv(args["metric-groups"]);
+        if (!entityIds || !metricGroups) {
+            writeAdsJson({
+                ok: false,
+                error: { code: "MISSING_PARAMETER", message: "entity-ids and metric-groups are required" },
+            });
+            process.exit(1);
+        }
+        const body = {
+            accountId,
+            entity: args.entity,
+            entityIds,
+            startTime: args["start-time"],
+            endTime: args["end-time"],
+            granularity: args.granularity ?? "DAY",
+            metricGroups,
+            placement: args.placement ?? "ALL_ON_TWITTER",
+            segmentationType: args["segmentation-type"],
+            country: args.country,
+            platform: args.platform,
+        };
+        try {
+            const data = await apiPost("/api/ads/x/stats/jobs", body);
+            writeAdsJson({ ok: true, data });
+        }
+        catch (err) {
+            if (err instanceof ApiError) {
+                writeAdsJson(parseXApiError(err.message, accountId));
+                process.exit(1);
+            }
+            writeAdsJson({ ok: false, error: { code: "NETWORK_ERROR", message: "Unexpected error" } });
+            process.exit(1);
+        }
+    },
+});
+//# sourceMappingURL=job-create.js.map

package/dist/commands/ads/x/stats/job-create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-create.js","sourceRoot":"","sources":["../../../../../src/commands/ads/x/stats/job-create.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,cAAc,CAAC;IACb,OAAO,EAAE,sBAAsB;IAC/B,WAAW,EACT,qLAAqL;IACvL,IAAI,EAAE;QACJ,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kBAAkB,EAAE,QAAQ,EAAE,KAAK,EAAE;QAClF,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6CAA6C,EAAE,QAAQ,EAAE,IAAI,EAAE;QACtG,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4BAA4B,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC3F,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,6BAA6B,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC5F,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,2BAA2B,EAAE,QAAQ,EAAE,IAAI,EAAE;QACxF,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,oBAAoB,EAAE,QAAQ,EAAE,KAAK,EAAE;QACnF,eAAe,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sBAAsB,EAAE,QAAQ,EAAE,IAAI,EAAE;QACxF,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,oCAAoC,EAAE,QAAQ,EAAE,KAAK,EAAE;QACjG,mBAAmB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4CAA4C,EAAE,QAAQ,EAAE,KAAK,EAAE;QACnH,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,EAAE;QAC3E,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,EAAE,QAAQ,EAAE,KAAK,EAAE;KAC9E;CACF,CAAC,CAAC;AAEH,SAAS,QAAQ,CAAC,CAAU;IAC1B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9D,MAAM,KAAK,GAAG,CAAC;SACZ,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9C,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC;IACjD,IAAI,EAAE;QACJ,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE;;;;;;kCAMiB;KAC/B;IACD,IAAI,EAAE;QACJ,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kBAAkB,EAAE,QAAQ,EAAE,KAAK,EAAE;QAClF,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI,EAAE;QACtE,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mBAAmB,EAAE,QAAQ,EAAE,IAAI,EAAE;QAClF,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC1E,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE;QACtE,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE;QAC5E,eAAe,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mBAAmB,EAAE,QAAQ,EAAE,IAAI,EAAE;QACrF,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE;QACxE,mBAAmB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mBAAmB,EAAE,QAAQ,EAAE,KAAK,EAAE;QAC1F,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,EAAE;QAC3E,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,EAAE,QAAQ,EAAE,KAAK,EAAE;KAC9E;IACD,GAAG,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QACtB,MAAM,SAAS,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;QAC/C,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;QACrD,IAAI,CAAC,SAAS,IAAI,CAAC,YAAY,EAAE,CAAC;YAChC,YAAY,CAAC;gBACX,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,2CAA2C,EAAE;aAC3F,CAAC,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,IAAI,GAAG;YACX,SAAS;YACT,MAAM,EAAE,IAAI,CAAC,MAAgB;YAC7B,SAAS;YACT,SAAS,EAAE,IAAI,CAAC,YAAY,CAAW;YACvC,OAAO,EAAE,IAAI,CAAC,UAAU,CAAW;YACnC,WAAW,EAAG,IAAI,CAAC,WAAkC,IAAI,KAAK;YAC9D,YAAY;YACZ,SAAS,EAAG,IAAI,CAAC,SAAgC,IAAI,gBAAgB;YACrE,gBAAgB,EAAE,IAAI,CAAC,mBAAmB,CAAuB;YACjE,OAAO,EAAE,IAAI,CAAC,OAA6B;YAC3C,QAAQ,EAAE,IAAI,CAAC,QAA8B;SAC9C,CAAC;QACF,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAU,uBAAuB,EAAE,IAAI,CAAC,CAAC;YACnE,YAAY,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;gBAC5B,YAAY,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;gBACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,YAAY,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,kBAAkB,EAAE,EAAE,CAAC,CAAC;YAC3F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;CACF,CAAC,CAAC"}

package/dist/commands/ads/x/stats/job-status.d.ts

@@ -0,0 +1,18 @@
+export declare const statsJobStatusCommand: import("citty").CommandDef<{
+    readonly "account-id": {
+        readonly type: "string";
+        readonly description: "X Ads account ID";
+        readonly required: false;
+    };
+    readonly "job-id": {
+        readonly type: "string";
+        readonly description: "Job ID";
+        readonly required: false;
+    };
+    readonly "job-ids": {
+        readonly type: "string";
+        readonly description: "CSV of job IDs";
+        readonly required: false;
+    };
+}>;
+//# sourceMappingURL=job-status.d.ts.map

package/dist/commands/ads/x/stats/job-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-status.d.ts","sourceRoot":"","sources":["../../../../../src/commands/ads/x/stats/job-status.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;EAsChC,CAAC"}

package/dist/commands/ads/x/stats/job-status.js

@@ -0,0 +1,58 @@
+import { defineCommand } from "citty";
+import { ApiError, apiGet } from "../../../../client.js";
+import { registerSchema } from "../../../../schemas.js";
+import { writeAdsJson } from "../../output.js";
+import { parseXApiError } from "../error-parser.js";
+import { resolveXAccountId } from "../output.js";
+registerSchema({
+    command: "ads.x.statsJobStatus",
+    description: "Check the status of one or more X Ads stats jobs. Returns status (PROCESSING|SUCCESS|FAILED) and a downloadable url when SUCCESS. Pass --job-id or --job-ids (CSV).",
+    args: {
+        "account-id": { type: "string", description: "X Ads account ID", required: false },
+        "job-id": { type: "string", description: "Single job ID", required: false },
+        "job-ids": { type: "string", description: "CSV of job IDs", required: false },
+    },
+});
+export const statsJobStatusCommand = defineCommand({
+    meta: {
+        name: "job-status",
+        description: `Poll the status of an async X Ads stats job.
+
+Examples:
+  baker ads x stats job-status --account-id 18ce53xyz --job-id abc
+  baker ads x stats job-status --account-id 18ce53xyz --job-ids abc,def`,
+    },
+    args: {
+        "account-id": { type: "string", description: "X Ads account ID", required: false },
+        "job-id": { type: "string", description: "Job ID", required: false },
+        "job-ids": { type: "string", description: "CSV of job IDs", required: false },
+    },
+    run: async ({ args }) => {
+        const accountId = await resolveXAccountId(args);
+        if (!args["job-id"] && !args["job-ids"]) {
+            writeAdsJson({
+                ok: false,
+                error: { code: "MISSING_PARAMETER", message: "Pass --job-id or --job-ids" },
+            });
+            process.exit(1);
+        }
+        try {
+            const params = { "account-id": accountId };
+            if (args["job-id"])
+                params["job-id"] = args["job-id"];
+            if (args["job-ids"])
+                params["job-ids"] = args["job-ids"];
+            const data = await apiGet("/api/ads/x/stats/jobs", params);
+            writeAdsJson({ ok: true, data });
+        }
+        catch (err) {
+            if (err instanceof ApiError) {
+                writeAdsJson(parseXApiError(err.message, accountId));
+                process.exit(1);
+            }
+            writeAdsJson({ ok: false, error: { code: "NETWORK_ERROR", message: "Unexpected error" } });
+            process.exit(1);
+        }
+    },
+});
+//# sourceMappingURL=job-status.js.map

package/dist/commands/ads/x/stats/job-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-status.js","sourceRoot":"","sources":["../../../../../src/commands/ads/x/stats/job-status.ts"],"names":[],"mappings":"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"}

package/dist/commands/ads/x/stats/job.d.ts

@@ -0,0 +1,63 @@
+export declare const statsJobCommand: import("citty").CommandDef<{
+    readonly "account-id": {
+        readonly type: "string";
+        readonly description: "X Ads account ID";
+        readonly required: false;
+    };
+    readonly entity: {
+        readonly type: "string";
+        readonly description: "Entity type";
+        readonly required: true;
+    };
+    readonly "entity-ids": {
+        readonly type: "string";
+        readonly description: "CSV of entity IDs";
+        readonly required: true;
+    };
+    readonly "start-time": {
+        readonly type: "string";
+        readonly description: "ISO start";
+        readonly required: true;
+    };
+    readonly "end-time": {
+        readonly type: "string";
+        readonly description: "ISO end";
+        readonly required: true;
+    };
+    readonly granularity: {
+        readonly type: "string";
+        readonly description: "Granularity";
+        readonly required: false;
+    };
+    readonly "metric-groups": {
+        readonly type: "string";
+        readonly description: "Metric groups CSV";
+        readonly required: true;
+    };
+    readonly placement: {
+        readonly type: "string";
+        readonly description: "Placement";
+        readonly required: false;
+    };
+    readonly "segmentation-type": {
+        readonly type: "string";
+        readonly description: "Segmentation type";
+        readonly required: false;
+    };
+    readonly country: {
+        readonly type: "string";
+        readonly description: "Country filter";
+        readonly required: false;
+    };
+    readonly platform: {
+        readonly type: "string";
+        readonly description: "Platform filter";
+        readonly required: false;
+    };
+    readonly "no-cache": {
+        readonly type: "boolean";
+        readonly description: "Skip result cache";
+        readonly required: false;
+    };
+}>;
+//# sourceMappingURL=job.d.ts.map

package/dist/commands/ads/x/stats/job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.d.ts","sourceRoot":"","sources":["../../../../../src/commands/ads/x/stats/job.ts"],"names":[],"mappings":"AA+FA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2G1B,CAAC"}

package/dist/commands/ads/x/stats/job.js

@@ -0,0 +1,183 @@
+import { gunzipSync } from "node:zlib";
+import { defineCommand } from "citty";
+import { ApiError, apiGet, apiPost } from "../../../../client.js";
+import { registerSchema } from "../../../../schemas.js";
+import { cacheGet, cacheSet } from "../../cache.js";
+import { writeAdsJson } from "../../output.js";
+import { parseXApiError } from "../error-parser.js";
+import { resolveXAccountId } from "../output.js";
+const POLL_INTERVAL_MS = 10_000;
+const DEADLINE_MS = 12 * 60 * 1000;
+const RESULT_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+registerSchema({
+    command: "ads.x.statsJob",
+    description: "Asynchronous X Ads stats job, fully synchronous from the CLI's perspective. Creates the job, polls every 10s, downloads + decompresses the gzip result, returns inline JSON. Hard deadline 12 min — must run in the background. Use this for ranges >7 days, segmented stats, or any query that hits sync limits. For fine-grained control, use `stats job-create` + `stats job-status` separately.",
+    args: {
+        "account-id": { type: "string", description: "X Ads account ID", required: false },
+        entity: { type: "string", description: "CAMPAIGN | LINE_ITEM | PROMOTED_TWEET | ...", required: true },
+        "entity-ids": { type: "string", description: "CSV of entity IDs (max 20)", required: true },
+        "start-time": { type: "string", description: "ISO 8601 hour-aligned start", required: true },
+        "end-time": { type: "string", description: "ISO 8601 hour-aligned end", required: true },
+        granularity: { type: "string", description: "TOTAL | DAY | HOUR", required: false },
+        "metric-groups": { type: "string", description: "CSV of metric groups", required: true },
+        placement: { type: "string", description: "ALL_ON_TWITTER | PUBLISHER_NETWORK", required: false },
+        "segmentation-type": { type: "string", description: "Segmentation (e.g. AGE, GENDER, LOCATIONS)", required: false },
+        country: { type: "string", description: "Country filter", required: false },
+        platform: { type: "string", description: "Platform filter", required: false },
+        "no-cache": { type: "boolean", description: "Skip result cache (still does the live job)", required: false },
+    },
+});
+function parseCsv(v) {
+    if (typeof v !== "string" || v.length === 0)
+        return undefined;
+    const parts = v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return parts.length > 0 ? parts : undefined;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function downloadAndDecompress(url) {
+    const res = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+    if (!res.ok) {
+        throw new ApiError("INTERNAL_ERROR", `Stats job download failed (${res.status})`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const decompressed = gunzipSync(buf);
+    return JSON.parse(decompressed.toString("utf-8"));
+}
+async function pollUntilDone(accountId, jobId) {
+    const deadline = Date.now() + DEADLINE_MS;
+    let lastLog = 0;
+    while (Date.now() < deadline) {
+        await sleep(POLL_INTERVAL_MS);
+        const jobs = await apiGet("/api/ads/x/stats/jobs", {
+            "account-id": accountId,
+            "job-id": jobId,
+        });
+        const job = jobs[0];
+        if (!job) {
+            throw new ApiError("NOT_FOUND", `Stats job ${jobId} not found`);
+        }
+        if (job.status === "SUCCESS") {
+            return job;
+        }
+        if (job.status === "FAILED" || job.status === "CANCELLED") {
+            throw new ApiError("INTERNAL_ERROR", `Stats job ${jobId} ended in status ${job.status}`);
+        }
+        const elapsed = DEADLINE_MS - (deadline - Date.now());
+        if (elapsed - lastLog > 30_000) {
+            process.stderr.write(`  polling... (${job.status}, ${Math.round(elapsed / 1000)}s elapsed)\n`);
+            lastLog = elapsed;
+        }
+    }
+    throw new ApiError("TIMEOUT", `Stats job ${jobId} did not complete within ${DEADLINE_MS / 60_000} minutes`);
+}
+function buildCacheKey(body) {
+    return `stats-job:${JSON.stringify(body)}`;
+}
+export const statsJobCommand = defineCommand({
+    meta: {
+        name: "job",
+        description: `Async X Ads stats job, sync from the CLI's perspective. Creates → polls → downloads → returns.
+
+Must run in the background (the harness enforces this).
+
+Use this when:
+  • Date range > 7 days
+  • Need segmentation (AGE, GENDER, LOCATIONS, ...)
+  • Sync stats hit a limit
+
+Examples:
+  baker ads x stats job --account-id 18ce53xyz --entity CAMPAIGN \\
+    --entity-ids abc,def --start-time 2026-04-01T00:00:00Z \\
+    --end-time 2026-05-01T00:00:00Z --metric-groups ENGAGEMENT,BILLING
+
+  baker ads x stats job --account-id 18ce53xyz --entity LINE_ITEM \\
+    --entity-ids abc --start-time 2026-04-01T00:00:00Z \\
+    --end-time 2026-05-01T00:00:00Z --metric-groups ENGAGEMENT \\
+    --segmentation-type LOCATIONS
+
+For fine-grained control (don't wait, poll yourself), use:
+  baker ads x stats job-create   — create + return job ID immediately
+  baker ads x stats job-status   — poll job status / get download URL`,
+    },
+    args: {
+        "account-id": { type: "string", description: "X Ads account ID", required: false },
+        entity: { type: "string", description: "Entity type", required: true },
+        "entity-ids": { type: "string", description: "CSV of entity IDs", required: true },
+        "start-time": { type: "string", description: "ISO start", required: true },
+        "end-time": { type: "string", description: "ISO end", required: true },
+        granularity: { type: "string", description: "Granularity", required: false },
+        "metric-groups": { type: "string", description: "Metric groups CSV", required: true },
+        placement: { type: "string", description: "Placement", required: false },
+        "segmentation-type": { type: "string", description: "Segmentation type", required: false },
+        country: { type: "string", description: "Country filter", required: false },
+        platform: { type: "string", description: "Platform filter", required: false },
+        "no-cache": { type: "boolean", description: "Skip result cache", required: false },
+    },
+    run: async ({ args }) => {
+        const accountId = await resolveXAccountId(args);
+        const entityIds = parseCsv(args["entity-ids"]);
+        const metricGroups = parseCsv(args["metric-groups"]);
+        if (!entityIds || !metricGroups) {
+            writeAdsJson({
+                ok: false,
+                error: { code: "MISSING_PARAMETER", message: "entity-ids and metric-groups are required" },
+            });
+            process.exit(1);
+        }
+        const body = {
+            accountId,
+            entity: args.entity,
+            entityIds,
+            startTime: args["start-time"],
+            endTime: args["end-time"],
+            granularity: args.granularity ?? "DAY",
+            metricGroups,
+            placement: args.placement ?? "ALL_ON_TWITTER",
+            segmentationType: args["segmentation-type"],
+            country: args.country,
+            platform: args.platform,
+        };
+        const useCache = !args["no-cache"];
+        const cacheKey = buildCacheKey(body);
+        if (useCache) {
+            const cached = cacheGet("x-stats", cacheKey);
+            if (cached) {
+                process.stderr.write("Result served from cache.\n");
+                writeAdsJson({ ok: true, data: cached.data, cached: true });
+                return;
+            }
+        }
+        try {
+            process.stderr.write(`Creating X Ads stats job for entity=${body.entity}, ${entityIds.length} IDs...\n`);
+            const job = await apiPost("/api/ads/x/stats/jobs", body);
+            process.stderr.write(`Job ${job.id} queued. Polling every ${POLL_INTERVAL_MS / 1000}s...\n`);
+            const finished = await pollUntilDone(accountId, job.id);
+            if (!finished.url) {
+                throw new ApiError("INTERNAL_ERROR", `Stats job ${job.id} succeeded but returned no download URL`);
+            }
+            process.stderr.write("Job complete. Downloading + decompressing results...\n");
+            const data = await downloadAndDecompress(finished.url);
+            if (useCache) {
+                cacheSet("x-stats", cacheKey, data, RESULT_CACHE_TTL_MS);
+            }
+            writeAdsJson({ ok: true, data });
+        }
+        catch (err) {
+            if (err instanceof ApiError) {
+                writeAdsJson(parseXApiError(err.message, accountId));
+                process.exit(1);
+            }
+            writeAdsJson({
+                ok: false,
+                error: { code: "NETWORK_ERROR", message: err instanceof Error ? err.message : "Unexpected error" },
+            });
+            process.exit(1);
+        }
+    },
+});
+//# sourceMappingURL=job.js.map