@koda-sl/baker-cli 0.567.0 → 0.569.0

package/dist/job-OJB6KIDV.js

@@ -0,0 +1,202 @@
+import {
+  parseXApiError
+} from "./chunk-FIN4ZXGJ.js";
+import {
+  resolveXAccountId
+} from "./chunk-ZICB4OI5.js";
+import {
+  cacheGet,
+  cacheSet,
+  writeAdsJson
+} from "./chunk-MK4HCMEA.js";
+import {
+  ApiError,
+  apiGet,
+  apiPost
+} from "./chunk-QEREDRZO.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  registerSchema
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/x/stats/job.ts
+import { gunzipSync } from "zlib";
+import { defineCommand } from "citty";
+var POLL_INTERVAL_MS = 1e4;
+var DEADLINE_MS = 12 * 60 * 1e3;
+var RESULT_CACHE_TTL_MS = 6 * 60 * 60 * 1e3;
+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 \u2014 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 void 0;
+  const parts = v.split(",").map((s) => s.trim()).filter(Boolean);
+  return parts.length > 0 ? parts : void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function downloadAndDecompress(url) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(6e4) });
+  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 > 3e4) {
+      process.stderr.write(`  polling... (${job.status}, ${Math.round(elapsed / 1e3)}s elapsed)
+`);
+      lastLog = elapsed;
+    }
+  }
+  throw new ApiError("TIMEOUT", `Stats job ${jobId} did not complete within ${DEADLINE_MS / 6e4} minutes`);
+}
+function buildCacheKey(body) {
+  return `stats-job:${JSON.stringify(body)}`;
+}
+var statsJobCommand = defineCommand({
+  meta: {
+    name: "job",
+    description: `Async X Ads stats job, sync from the CLI's perspective. Creates \u2192 polls \u2192 downloads \u2192 returns.
+
+Must run in the background (the harness enforces this).
+
+Use this when:
+  \u2022 Date range > 7 days
+  \u2022 Need segmentation (AGE, GENDER, LOCATIONS, ...)
+  \u2022 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   \u2014 create + return job ID immediately
+  baker ads x stats job-status   \u2014 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...
+`);
+      const job = await apiPost("/api/ads/x/stats/jobs", body);
+      process.stderr.write(`Job ${job.id} queued. Polling every ${POLL_INTERVAL_MS / 1e3}s...
+`);
+      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);
+    }
+  }
+});
+export {
+  statsJobCommand
+};
+//# sourceMappingURL=job-OJB6KIDV.js.map

package/dist/job-create-C6FGCDW4.js

@@ -0,0 +1,109 @@
+import {
+  parseXApiError
+} from "./chunk-FIN4ZXGJ.js";
+import {
+  resolveXAccountId
+} from "./chunk-ZICB4OI5.js";
+import {
+  writeAdsJson
+} from "./chunk-MK4HCMEA.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-QEREDRZO.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  registerSchema
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/x/stats/job-create.ts
+import { defineCommand } from "citty";
+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 void 0;
+  const parts = v.split(",").map((s) => s.trim()).filter(Boolean);
+  return parts.length > 0 ? parts : void 0;
+}
+var 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);
+    }
+  }
+});
+export {
+  statsJobCreateCommand
+};
+//# sourceMappingURL=job-create-C6FGCDW4.js.map

package/dist/job-status-4RJHESID.js

@@ -0,0 +1,74 @@
+import {
+  parseXApiError
+} from "./chunk-FIN4ZXGJ.js";
+import {
+  resolveXAccountId
+} from "./chunk-ZICB4OI5.js";
+import {
+  writeAdsJson
+} from "./chunk-MK4HCMEA.js";
+import {
+  ApiError,
+  apiGet
+} from "./chunk-QEREDRZO.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  registerSchema
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/x/stats/job-status.ts
+import { defineCommand } from "citty";
+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 }
+  }
+});
+var 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);
+    }
+  }
+});
+export {
+  statsJobStatusCommand
+};
+//# sourceMappingURL=job-status-4RJHESID.js.map

package/dist/keyword-metrics-NJV3WR75.js

@@ -0,0 +1,200 @@
+import {
+  keywordMetricsHints
+} from "./chunk-LQACNCAV.js";
+import {
+  RESEARCH_DATA_NOTE,
+  handleResearchError,
+  writeResearchHints,
+  writeResearchJson,
+  writeResearchOutput
+} from "./chunk-D3YAFC6K.js";
+import {
+  buildResearchQueryContext,
+  warnDefaults
+} from "./chunk-IGCS3X4F.js";
+import "./chunk-BMMXYR7A.js";
+import {
+  RESEARCH_KEYWORD_METRICS_MAX_KEYWORDS
+} from "./chunk-2Q7K4F4H.js";
+import "./chunk-QV6AST5T.js";
+import "./chunk-WCU362Z6.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-R7XDGNZD.js";
+import "./chunk-XHWHBGKX.js";
+import {
+  apiPost
+} from "./chunk-QEREDRZO.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  registerSchema
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/research/keyword-metrics.ts
+import { defineCommand } from "citty";
+
+// src/commands/research/keyword-metrics-rows.ts
+var KEYWORD_METRICS_SOURCE = "keyword_planner_estimate_via_dataforseo";
+function toOutputRow(row, options) {
+  const out = {
+    source: KEYWORD_METRICS_SOURCE,
+    keyword: row.keyword,
+    planner_search_volume: row.search_volume,
+    planner_cpc: row.cpc,
+    planner_low_top_of_page_bid: row.low_top_of_page_bid,
+    planner_high_top_of_page_bid: row.high_top_of_page_bid,
+    planner_competition: row.competition,
+    planner_competition_index: row.competition_index
+  };
+  if (options.clickstream) {
+    out.clickstream_search_volume = row.clickstream_search_volume;
+  }
+  if (options.full) {
+    out.keyword_difficulty = row.keyword_difficulty;
+    out.main_intent = row.main_intent;
+    out.planner_monthly_searches = row.monthly_searches;
+  }
+  return out;
+}
+function keywordMetricsFields(options) {
+  const fields = {
+    source: `Always "${KEYWORD_METRICS_SOURCE}". Every planner_ column below is Google's Keyword Planner ESTIMATE of total market volume, resold by DataForSEO \u2014 the same number \`baker ads google keywords metrics\` returns, not an independent measurement of it. Columns without the planner_ prefix are DataForSEO's own.`,
+    keyword: "The keyword asked for. A row with every metric null means DataForSEO holds no data on it \u2014 not that nobody searches it.",
+    planner_search_volume: "ESTIMATE: average monthly searches across the whole market, last 12 months",
+    planner_cpc: "ESTIMATE: average cost per click in USD (a single blended figure, not a top-of-page range)",
+    planner_low_top_of_page_bid: "ESTIMATE: low-range top-of-page bid in USD",
+    planner_high_top_of_page_bid: "ESTIMATE: high-range top-of-page bid in USD",
+    planner_competition: "ESTIMATE: competition level \u2014 LOW, MEDIUM or HIGH",
+    planner_competition_index: "ESTIMATE: competition index 0-100 (higher = more advertisers)"
+  };
+  if (options.clickstream) {
+    fields.clickstream_search_volume = "DataForSEO's OWN volume estimate, from clickstream panels \u2014 not Google's, and the only number here that is a genuine second opinion on demand. Expect it to differ from planner_search_volume; that is the point.";
+  }
+  if (options.full) {
+    fields.keyword_difficulty = "DataForSEO's 0-100 estimate of how hard ranking in the organic top 10 would be";
+    fields.main_intent = "DataForSEO's intent classification: informational, navigational, commercial or transactional";
+    fields.planner_monthly_searches = "ESTIMATE: 12-month volume breakdown ({year, month, search_volume})";
+  }
+  return fields;
+}
+
+// src/commands/research/keyword-metrics.ts
+registerSchema({
+  command: "research.keyword-metrics",
+  description: "Search volume, CPC, top-of-page bids and competition for a list of keywords you name \u2014 no domain needed. This is the command for sizing a market you have keywords for; the domain-bound ones (keywords-for-site, keyword-gap) answer a different question and should not be used as a workaround for this one. The volume is Google's Keyword Planner figure resold by DataForSEO, so it is not a second opinion on `baker ads google keywords metrics` \u2014 for that, pass --clickstream. If --location and --language are omitted, defaults to United States (us) and English (en). The response includes a query_context object showing which location/language were used.",
+  args: {
+    keywords: {
+      type: "string",
+      description: `Comma-separated keywords (max ${RESEARCH_KEYWORD_METRICS_MAX_KEYWORDS}, 80 chars each)`,
+      required: true
+    },
+    location: {
+      type: "string",
+      description: "Country code (us, mx, br, es...) or DataForSEO location code. Defaults to us (United States) if omitted \u2014 always set this for non-US markets",
+      required: false
+    },
+    language: {
+      type: "string",
+      description: "Language code or name. Defaults to en (English) if omitted \u2014 always set this for non-English markets",
+      required: false
+    },
+    clickstream: {
+      type: "boolean",
+      description: "Also return DataForSEO's own panel-derived volume (clickstream_search_volume), the only genuinely independent estimate of demand available here. Costs 2x.",
+      required: false
+    },
+    full: {
+      type: "boolean",
+      description: "Add keyword difficulty, search intent and the 12-month volume trend to each row",
+      required: false
+    },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  }
+});
+var keywordMetricsCommand = defineCommand({
+  meta: {
+    name: "keyword-metrics",
+    description: `Volume, CPC and competition for keywords you name. No domain required.
+
+Numbers are Keyword Planner ESTIMATES of total market volume, resold by DataForSEO \u2014 every column carrying one is named planner_. Pass --clickstream for DataForSEO's own independent estimate alongside.
+
+Examples:
+  baker research keyword-metrics "chatbot whatsapp,agente whatsapp ecommerce" --location mx --language es
+  baker research keyword-metrics "chatbot whatsapp" --location br --language pt --clickstream
+  baker research keyword-metrics "crm software,best crm" --full --output md`
+  },
+  args: {
+    keywords: { type: "positional", description: "Comma-separated keywords", required: true },
+    location: { type: "string", description: "Country code or location code (default: us)", required: false },
+    language: { type: "string", description: "Language code or name (default: en)", required: false },
+    clickstream: { type: "boolean", description: "Add DataForSEO's own volume estimate (costs 2x)", required: false },
+    full: { type: "boolean", description: "Add difficulty, intent and the 12-month trend", required: false },
+    output: { type: "string", description: "Format: json|csv|md|jsonl", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  },
+  run: async ({ args }) => {
+    const keywords = args.keywords.split(",").map((k) => k.trim()).filter(Boolean);
+    if (keywords.length === 0) {
+      writeResearchJson({
+        ok: false,
+        error: { code: "VALIDATION_ERROR", message: "Provide at least one keyword" }
+      });
+      process.exit(1);
+    }
+    if (keywords.length > RESEARCH_KEYWORD_METRICS_MAX_KEYWORDS) {
+      writeResearchJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: `Maximum ${RESEARCH_KEYWORD_METRICS_MAX_KEYWORDS} keywords per request`,
+          fix: {
+            action: "retry_with_changes",
+            explanation: `You sent ${keywords.length}. Split the list into batches of ${RESEARCH_KEYWORD_METRICS_MAX_KEYWORDS} and run the command once per batch \u2014 each batch is a separate charge, so batch by priority.`
+          }
+        }
+      });
+      process.exit(1);
+    }
+    const location = args.location || void 0;
+    const language = args.language || void 0;
+    const clickstream = Boolean(args.clickstream);
+    const full = Boolean(args.full);
+    const queryContext = buildResearchQueryContext(location, language);
+    try {
+      const result = await apiPost("/api/research/keyword-metrics", {
+        keywords,
+        location,
+        language,
+        includeClickstream: clickstream,
+        skipCache: args["no-cache"] ? true : void 0
+      });
+      const columns = { clickstream, full };
+      const rows = result.data.map((row) => toOutputRow(row, columns));
+      const hints = keywordMetricsHints({ rows: result.data, asked: keywords, clickstream, queryContext });
+      warnDefaults(queryContext);
+      const format = args.output || "json";
+      if (format !== "json") {
+        writeResearchOutput(rows, format);
+        writeResearchHints([...hints, RESEARCH_DATA_NOTE], format);
+        return;
+      }
+      writeResearchJson({
+        ok: true,
+        data: rows,
+        fields: keywordMetricsFields(columns),
+        note: RESEARCH_DATA_NOTE,
+        hints,
+        query_context: queryContext
+      });
+    } catch (err) {
+      handleResearchError(err);
+    }
+  }
+});
+export {
+  keywordMetricsCommand
+};
+//# sourceMappingURL=keyword-metrics-NJV3WR75.js.map