@adkit/cli 1.12.11 → 1.12.13

package/dist/cli.js

@@ -1380,28 +1380,30 @@ function readMediaFormatFlag(value) {
   throw new CliError("INVALID_VALUE", `Invalid --media-format: ${value}`, "Use one of: default, square, vertical, horizontal.");
 }
 async function listResults(client, args, flags) {
-  validateFlags(flags, ["campaign", "adset", "ad", "status", "period", "from", "to", "metrics", "actions", "attribution-window", "breakdown", "sort", "limit", "confirm", "raw"], "manage meta results");
+  validateFlags(flags, ["account", "campaign-ids", "adset-ids", "ad-ids", "statuses", "period", "from", "to", "fields", "conversion-event-keys", "attribution-window", "breakdowns", "sort", "sort-direction", "limit", "offset", "confirm", "raw"], "manage meta results");
   const accountId = typeof flags.account === "string" ? flags.account : void 0;
   const level = parseResultsLevel(args);
   warnIgnoredResultsArgs(args);
-  const campaign = typeof flags.campaign === "string" ? flags.campaign : void 0;
-  const adset = typeof flags.adset === "string" ? flags.adset : void 0;
-  const ad = typeof flags.ad === "string" ? flags.ad : void 0;
-  const status2 = typeof flags.status === "string" ? flags.status : void 0;
+  const campaignIds = typeof flags["campaign-ids"] === "string" ? flags["campaign-ids"] : void 0;
+  const adsetIds = typeof flags["adset-ids"] === "string" ? flags["adset-ids"] : void 0;
+  const adIds = typeof flags["ad-ids"] === "string" ? flags["ad-ids"] : void 0;
+  const statuses = typeof flags.statuses === "string" ? flags.statuses : void 0;
   const period = typeof flags.period === "string" ? flags.period : void 0;
   const from = typeof flags.from === "string" ? flags.from : void 0;
   const to = typeof flags.to === "string" ? flags.to : void 0;
-  const metrics = typeof flags.metrics === "string" ? flags.metrics : void 0;
-  const actions = typeof flags.actions === "string" ? flags.actions : void 0;
+  const fields = typeof flags.fields === "string" ? flags.fields : void 0;
+  const conversionEventKeys = typeof flags["conversion-event-keys"] === "string" ? flags["conversion-event-keys"] : void 0;
   const attributionWindow = typeof flags["attribution-window"] === "string" ? flags["attribution-window"] : void 0;
-  const breakdown = typeof flags.breakdown === "string" ? flags.breakdown : void 0;
+  const breakdowns = typeof flags.breakdowns === "string" ? flags.breakdowns : void 0;
   const sort = typeof flags.sort === "string" ? flags.sort : void 0;
+  const sortDirection = typeof flags["sort-direction"] === "string" ? flags["sort-direction"] : void 0;
   const limit = typeof flags.limit === "string" ? flags.limit : void 0;
+  const offset = typeof flags.offset === "string" ? flags.offset : void 0;
   const confirm = flags.confirm === true ? "true" : void 0;
   const raw = flags.raw === true ? "true" : void 0;
-  const hasTimeBreakdown = breakdown?.split(",").some((b) => b === "day" || b === "week" || b === "month");
+  const hasTimeBreakdown = breakdowns?.split(",").some((b) => b === "day" || b === "week" || b === "month");
   if (period === "maximum" && hasTimeBreakdown && !confirm) throw new CliError("INVALID_VALUE", "maximum date range with time breakdowns (day/week/month) can produce very large result sets. Add --confirm to proceed.");
-  const qs = queryString({ accountId, level, campaign, adset, ad, status: status2, period, from, to, metrics, actions, "attribution-window": attributionWindow, breakdown, sort, limit, confirm, raw });
+  const qs = queryString({ accountId, level, campaignIds, adsetIds, adIds, statuses, period, from, to, fields, conversionEventKeys, attributionWindow, breakdowns, sort, sortDirection, limit, offset, confirm, raw });
   return client.get(`/manage/meta/results${qs}`);
 }
 async function createAd(client, _args, flags) {
@@ -4388,20 +4390,22 @@ var RESULTS_HELP = `adkit manage meta results \u2014 Meta performance insights
   [campaigns|adsets|ads]   Optional level positional arg (default: campaigns)
 
 Flags:
-  --campaign <ids>    Comma-separated campaign IDs
-  --adset <ids>       Comma-separated ad set IDs
-  --ad <ids>          Comma-separated ad IDs
-  --status <s>        active, paused (filter by entity status)
+  --campaign-ids <ids> Comma-separated campaign IDs
+  --adset-ids <ids>   Comma-separated ad set IDs
+  --ad-ids <ids>      Comma-separated ad IDs
+  --statuses <s>      active, paused (filter by entity status)
   --period <range>    Relative range like 7d or preset: today, yesterday, this_month, last_month, this_quarter, last_quarter, this_year, last_year, maximum (default: 30d)
   --from <date>       Start date, YYYY-MM-DD
   --to <date>         End date, YYYY-MM-DD
-  --metrics <list>    Override the default insights field preset
-  --actions <list>    purchase,lead or all
+  --fields <list>     Normalized fields, e.g. spend, impressions, clicks, conversionEvents, etc
+  --conversion-event-keys <list> purchase,lead or all
   --attribution-window <w>  1d_click, 7d_click, 1d_view, 7d_click_1d_view, 28d_click_1d_view
-  --breakdown <list>  day,week,month,age,gender,country,region,device_platform,publisher_platform,platform_position,impression_device
+  --breakdowns <list> day, week, month, age, gender, country, region, device_platform, publisher_platform, platform_position, impression_device
   --confirm           Required with --period maximum plus any breakdown
   --sort <field>      spend = descending, +spend = ascending
+  --sort-direction <d> asc or desc
   --limit <n>         Limit rows after sorting
+  --offset <n>        Skip rows after sorting
   --raw               Return Meta's paginated response without conversion
 
 Output: always JSON, even in TTY mode.
@@ -4410,15 +4414,15 @@ Examples:
   # Campaign overview (default: last 30 days)
   adkit manage meta results
   # Top-spending ads for a campaign
-  adkit manage meta results ads --campaign 123 --sort spend --limit 10
+  adkit manage meta results ads --campaign-ids 123 --sort spend --limit 10
   # Daily performance by age group
-  adkit manage meta results adsets --period 7d --breakdown day,age
+  adkit manage meta results adsets --period 7d --breakdowns day,age
   # Country breakdown for all time
-  adkit manage meta results ads --period maximum --breakdown country --confirm
+  adkit manage meta results ads --period maximum --breakdowns country --confirm
   # Conversion data for a campaign
-  adkit manage meta results --campaign 123 --actions purchase,lead
+  adkit manage meta results --campaign-ids 123 --conversion-event-keys purchase,lead
   # Raw API response with custom metrics
-  adkit manage meta results --campaign 123 --raw --metrics spend,impressions,actions`.trim();
+  adkit manage meta results --campaign-ids 123 --raw --fields spend,impressions,conversionEvents`.trim();
 var CREATIVE_HELP = `adkit manage meta creatives \u2014 Meta ad creatives
 
 Prefer using "ads create --media" which handles creative creation automatically.
@@ -5026,14 +5030,18 @@ Flags:
   --limit <n>         Max results
   --status <s>        Filter: enabled, paused, all
   --breakdown <b>     Split rows by: day, device, network (For placements, use "results placements")
-  --fields <list>    Response fields, e.g. cost,clicks,searchImpressionShare. Competitive metrics are opt-in.
+  --fields <list>    Response fields, e.g. cost,clicks,searchImpressionShare. Omit for default advertiser metrics; use all for every supported field.
   --raw               Return raw Google API response
   --account <id>      Optional if one Google Ads account is connected
 
-Competitive metrics (opt-in via --fields):
+Default metrics include:
+  Cost/clicks/conversions, CPA, CVR, ROAS, all conversions, view-through conversions,
+  top-position rates, search impression share where Google supports it, and serving/learning status.
+
+Visibility fields:
   Search: searchImpressionShare, searchRankLostImpressionShare, searchBudgetLostImpressionShare,
-          searchTopImpressionShare, searchAbsoluteTopImpressionShare, searchClickShare
-  Content: contentImpressionShare, contentRankLostImpressionShare, contentBudgetLostImpressionShare
+          searchTopImpressionShare, searchAbsoluteTopImpressionShare, searchClickShare (default where supported)
+  Content: contentImpressionShare, contentRankLostImpressionShare, contentBudgetLostImpressionShare (use --fields all)
   Note: search fields available at all levels except ads. Content fields not available at keywords or ads.
 
 Examples:
@@ -5045,7 +5053,7 @@ Examples:
   adkit manage google results placements --campaign 123 --period 30d
   adkit manage google results --period this_month --sort clicks --limit 20
   adkit manage google results search-terms --campaign 123 --period 30d
-  adkit manage google results --campaign 123 --fields default,searchImpressionShare,searchBudgetLostImpressionShare`;
+  adkit manage google results --campaign 123 --fields all`;
 var GOOGLE_RESULTS_PLACEMENTS_HELP = `adkit manage google results placements \u2014 Google placement report
 
   Shows each website, app, or YouTube placement where ads appeared.
@@ -5108,12 +5116,13 @@ Flags:
   --sort <field>      Sort by: cost (default), clicks, impressions, conversions, ctr, cpc
   --status <s>        Filter: enabled, paused, all (default: all)
   --limit <n>         Max results
-  --fields <list>    Response fields, e.g. cost,clicks,qualityScore,searchImpressionShare
+  --fields <list>    Response fields, e.g. cost,clicks,qualityScore,searchImpressionShare. Omit for default advertiser metrics.
   --raw               Return raw Google API response
 
-  Search competitive fields also available at keyword level:
-    searchImpressionShare, searchRankLostImpressionShare, searchBudgetLostImpressionShare,
-    searchTopImpressionShare, searchAbsoluteTopImpressionShare, searchClickShare
+  Default keyword metrics include CPA, CVR, ROAS, search impression share, search lost impression share,
+  search click share, primary serving/learning status, and Quality Score diagnostics.
+  Extra keyword diagnostics are available with --fields all, including:
+    systemServingStatus, approvalStatus, firstPageCpc, topOfPageCpc, firstPositionCpc
 
 Examples:
   adkit manage google results keywords --account 1234567890 --period 7d
@@ -5121,7 +5130,7 @@ Examples:
   adkit manage google results keywords --account 1234567890 --campaign 987654321 --period this_month
   adkit manage google results keywords --account 1234567890 --period last_month --fields cost,clicks,qualityScore
   adkit manage google results keywords --account 1234567890 --period 7d --fields default,primaryStatus
-  adkit manage google results keywords --account 1234567890 --period 30d --fields default,searchImpressionShare`;
+  adkit manage google results keywords --account 1234567890 --period 30d --fields all`;
 var GOOGLE_RESEARCH_HELP = `adkit manage google research \u2014 Google Ads research tools
 
   keywords <query>    Get keyword ideas from Google Keyword Planner
@@ -5913,11 +5922,11 @@ function printResultsCard(data) {
     const parts = [];
     const reportCurrency = str(report, "currency");
     const timezone = str(report, "timezone");
-    const attrWindow = str(report, "attribution_window");
+    const attrWindow = str(report, "attributionWindow") ?? str(report, "attribution_window");
     if (reportCurrency) parts.push(reportCurrency);
     if (timezone) parts.push(timezone);
     if (attrWindow) parts.push(attrWindow);
-    const dr = nested(report, "date_range");
+    const dr = nested(report, "dateRange") ?? nested(report, "date_range");
     if (dr) {
       const from = str(dr, "from");
       const to = str(dr, "to");
@@ -5925,7 +5934,7 @@ function printResultsCard(data) {
     }
     if (parts.length > 0) console.log(parts.join(" \xB7 "));
   }
-  const results = data.results;
+  const results = Array.isArray(data.rows) ? data.rows : data.results;
   if (!Array.isArray(results) || results.length === 0) {
     console.log("\nNo results for this period.");
     printWarnings(data.warnings);
@@ -5933,40 +5942,43 @@ function printResultsCard(data) {
   }
   for (const row of results) {
     if (!isObject(row)) continue;
-    const name = str(row, "campaign_name") || str(row, "adset_name") || str(row, "ad_name") || "Unknown";
+    const entity = nested(row, "entity");
+    const metrics = nested(row, "metrics");
+    const breakdown = nested(row, "breakdown");
+    const name = (entity ? str(entity, "name") : void 0) || str(row, "campaign_name") || str(row, "adset_name") || str(row, "ad_name") || "Unknown";
     const titleParts = [name];
-    const status2 = str(row, "status");
-    const spend = num(row, "spend");
+    const status2 = (entity ? str(entity, "status") : void 0) || str(row, "status");
+    const spend = (metrics ? num(metrics, "spend") : void 0) ?? num(row, "spend");
     if (status2) titleParts.push(status2);
     if (spend !== void 0) titleParts.push(`${fmtCurrency(spend, currency)} spent`);
-    const dateStart = str(row, "date_start");
-    const dateStop = str(row, "date_stop");
+    const dateStart = (breakdown ? str(breakdown, "day") ?? str(breakdown, "week") ?? str(breakdown, "month") ?? str(breakdown, "dateStart") : void 0) ?? str(row, "date_start");
+    const dateStop = (breakdown ? str(breakdown, "dateStop") : void 0) ?? str(row, "date_stop");
     if (dateStart && dateStop) titleParts.push(`${fmtShortDate(dateStart)} \u2013 ${fmtShortDate(dateStop)}`);
     else if (dateStart) titleParts.push(fmtShortDate(dateStart));
     else if (dateStop) titleParts.push(fmtShortDate(dateStop));
-    const age = str(row, "age");
+    const age = (breakdown ? str(breakdown, "age") : void 0) ?? str(row, "age");
     if (age) titleParts.push(age);
-    const gender = str(row, "gender");
+    const gender = (breakdown ? str(breakdown, "gender") : void 0) ?? str(row, "gender");
     if (gender) titleParts.push(gender);
-    const country = str(row, "country");
+    const country = (breakdown ? str(breakdown, "country") : void 0) ?? str(row, "country");
     if (country) titleParts.push(country);
-    const region = str(row, "region");
+    const region = (breakdown ? str(breakdown, "region") : void 0) ?? str(row, "region");
     if (region) titleParts.push(region);
-    const devicePlatform = str(row, "device_platform");
+    const devicePlatform = (breakdown ? str(breakdown, "devicePlatform") : void 0) ?? str(row, "device_platform");
     if (devicePlatform) titleParts.push(devicePlatform);
-    const publisherPlatform = str(row, "publisher_platform");
+    const publisherPlatform = (breakdown ? str(breakdown, "publisherPlatform") : void 0) ?? str(row, "publisher_platform");
     if (publisherPlatform) titleParts.push(publisherPlatform);
-    const platformPosition = str(row, "platform_position");
+    const platformPosition = (breakdown ? str(breakdown, "platformPosition") : void 0) ?? str(row, "platform_position");
     if (platformPosition) titleParts.push(platformPosition);
-    const impressionDevice = str(row, "impression_device");
+    const impressionDevice = (breakdown ? str(breakdown, "impressionDevice") : void 0) ?? str(row, "impression_device");
     if (impressionDevice) titleParts.push(impressionDevice);
     console.log(`
 ${titleParts.join(" \xB7 ")}`);
-    const impressions = num(row, "impressions");
+    const impressions = (metrics ? num(metrics, "impressions") : void 0) ?? num(row, "impressions");
     if (impressions !== void 0) console.log(`  Impressions   ${fmtNum(impressions)}`);
-    const reach = num(row, "reach");
+    const reach = (metrics ? num(metrics, "reach") : void 0) ?? num(row, "reach");
     if (reach !== void 0) {
-      const freq = num(row, "frequency");
+      const freq = (metrics ? num(metrics, "frequency") : void 0) ?? num(row, "frequency");
       const freqStr = freq !== void 0 ? ` (${fmtPct(freq)} freq)` : "";
       console.log(`  Reach         ${fmtNum(reach)}${freqStr}`);
     }
@@ -5976,14 +5988,17 @@ ${titleParts.join(" \xB7 ")}`);
       if (all) printClickLine("Clicks", all, currency);
       const outbound = nested(clicks, "outbound");
       if (outbound) printClickLine("Outbound", outbound, currency);
+    } else if (metrics) {
+      printClickLine("Clicks", { count: metrics.clicks, ctr: metrics.ctr, cpc: metrics.cpc }, currency);
+      printClickLine("Outbound", { count: metrics.outboundClicks, ctr: metrics.outboundCtr, cpc: metrics.costPerOutboundClick }, currency);
     }
-    const actions = nested(row, "actions");
+    const actions = nested(row, "conversionEvents") ?? nested(row, "actions");
     if (actions) {
       for (const [key, val] of Object.entries(actions)) {
         if (!isObject(val)) continue;
         const parts = [];
         const count = num(val, "count");
-        const cost = num(val, "cost");
+        const cost = num(val, "costPerResult") ?? num(val, "cost");
         if (count !== void 0) parts.push(fmtNum(count));
         if (cost !== void 0) parts.push(`${fmtCurrency(cost, currency)} each`);
         if (parts.length > 0) console.log(`  ${humanizeAction(key).padEnd(14)}${parts.join(" \xB7 ")}`);
@@ -5997,6 +6012,15 @@ ${titleParts.join(" \xB7 ")}`);
         for (const [key, val] of Object.entries(aq)) if (typeof val === "string" && val !== "UNKNOWN") parts.push(`${humanizeAction(key)}: ${val}`);
         if (parts.length > 0) console.log(`  Ad Quality    ${parts.join(" \xB7 ")}`);
       }
+    } else if (metrics) {
+      const parts = [];
+      const qualityRanking = str(metrics, "qualityRanking");
+      const engagementRateRanking = str(metrics, "engagementRateRanking");
+      const conversionRateRanking = str(metrics, "conversionRateRanking");
+      if (qualityRanking && qualityRanking !== "UNKNOWN") parts.push(`quality: ${qualityRanking}`);
+      if (engagementRateRanking && engagementRateRanking !== "UNKNOWN") parts.push(`engagement rate: ${engagementRateRanking}`);
+      if (conversionRateRanking && conversionRateRanking !== "UNKNOWN") parts.push(`conversion rate: ${conversionRateRanking}`);
+      if (parts.length > 0) console.log(`  Ad Quality    ${parts.join(" \xB7 ")}`);
     }
   }
   printWarnings(data.warnings);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adkit/cli",
-  "version": "1.12.11",
+  "version": "1.12.13",
   "description": "The Ads CLI for AI agents — manage Meta & Google ad campaigns, browse the ad library, and generate creatives from your terminal.",
   "keywords": [
     "ads cli",