@adkit/cli 1.12.10 → 1.12.12

package/dist/cli.js

@@ -167,12 +167,14 @@ function buildAuthSuggestion(code) {
 var AdkitClient = class {
   apiKey;
   baseUrl;
+  clientVersion;
   projectId;
-  constructor({ apiKey, baseUrl, projectId }) {
+  constructor({ apiKey, baseUrl, clientVersion, projectId }) {
     const isLocalhost = baseUrl.startsWith("http://localhost") || baseUrl.startsWith("http://127.0.0.1");
     if (baseUrl.startsWith("http://") && !isLocalhost) throw new Error("HTTPS is required \u2014 insecure HTTP base URLs are not allowed");
     this.apiKey = apiKey;
     this.baseUrl = baseUrl;
+    this.clientVersion = clientVersion;
     this.projectId = projectId;
   }
   // eslint-disable-next-line max-lines-per-function -- shared client error mapping is intentionally centralized here.
@@ -180,8 +182,11 @@ var AdkitClient = class {
     const url = `${this.baseUrl}${path3}`;
     const headers = {
       Authorization: `Bearer ${this.apiKey}`,
-      "Content-Type": "application/json"
+      "Content-Type": "application/json",
+      "User-Agent": this.clientVersion ? `adkit-cli/${this.clientVersion}` : "adkit-cli",
+      "x-adkit-client": "cli"
     };
+    if (this.clientVersion) headers["x-adkit-client-version"] = this.clientVersion;
     if (this.projectId) headers["x-adkit-project-id"] = this.projectId;
     const init = { method, headers };
     if (body !== void 0) init.body = JSON.stringify(body);
@@ -1375,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) {
@@ -4383,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.
@@ -4405,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.
@@ -5818,7 +5827,7 @@ function requireClient(flags, options = {}) {
   if (!apiKey) throw new CliError("NOT_AUTHENTICATED", "No API key found", "Run: adkit setup");
   const baseUrl = getBaseUrl();
   const projectId = options.projectOptional ? void 0 : selectedProject;
-  return new AdkitClient({ apiKey, baseUrl, projectId });
+  return new AdkitClient({ apiKey, baseUrl, clientVersion: CLI_VERSION, projectId });
 }
 function toPrintListDisplayRows(rows, isJson) {
   if (isJson) return rows;
@@ -5908,11 +5917,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");
@@ -5920,7 +5929,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);
@@ -5928,40 +5937,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}`);
     }
@@ -5971,14 +5983,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 ")}`);
@@ -5992,6 +6007,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.10",
+  "version": "1.12.12",
   "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",