@adkit/cli 1.13.5 → 1.13.6

package/dist/cli.js

@@ -1253,7 +1253,7 @@ async function listMetaCampaigns(client, _args, flags) {
 }
 var CAMPAIGN_FLAGS = ["name", "objective", "status", "budget-daily", "budget-total", "abo", "bid-strategy"];
 var ADSET_FLAGS = ["campaign", "name", "status", "optimization", "budget-daily", "budget-total", "bid-strategy", "bid-amount", "countries", "genders", "targeting", "pixel", "event-type", "interest"];
-var AD_FLAGS = ["creative", "adset", "name", "status", "media", "media-format", "primary-text", "headline", "description", "cta", "url", "lead-form", "page", "post"];
+var AD_FLAGS = ["creative", "adset", "name", "status", "media", "media-format", "primary-text", "headline", "link-description", "cta", "url", "lead-form", "page", "post"];
 var CREATIVE_FLAGS = ["page-id", "headline", "primary-text", "link-description", "link-url", "cta", "name", "image-hash", "image-url", "video-id", "force"];
 var MEDIA_FLAGS = ["file", "url", "account"];
 var ADSET_BID_STRATEGIES_REQUIRING_AMOUNT = /* @__PURE__ */ new Set(["cost_cap", "bid_cap"]);
@@ -1430,10 +1430,10 @@ async function createAd(client, _args, flags) {
   }
   validateFlags(flags, AD_FLAGS, "manage meta ads create");
   const creativeId = typeof flags.creative === "string" ? flags.creative : void 0;
-  const mediaFlags = ["media", "media-format", "primary-text", "headline", "description", "cta", "lead-form"];
+  const mediaFlags = ["media", "media-format", "primary-text", "headline", "link-description", "cta", "lead-form"];
   const hasMediaFlags = mediaFlags.some((f) => flags[f] !== void 0);
   const postId = typeof flags.post === "string" ? flags.post : void 0;
-  if (creativeId && hasMediaFlags) throw new CliError("INVALID_VALUE", "`--creative` cannot be combined with --media, --primary-text, --headline, --description, or --cta", "Use --creative to reference an existing creative, OR use --media/--primary-text/etc. to create a new one");
+  if (creativeId && hasMediaFlags) throw new CliError("INVALID_VALUE", "`--creative` cannot be combined with --media, --primary-text, --headline, --link-description, or --cta", "Use --creative to reference an existing creative, OR use --media/--primary-text/etc. to create a new one");
   if (postId && (creativeId || hasMediaFlags)) throw new CliError("INVALID_VALUE", "`--post` cannot be combined with --creative, --media, or text flags", "Use --post alone to create an ad from an existing post");
   if (flags["lead-form"] !== void 0 && (typeof flags["lead-form"] !== "string" || !flags["lead-form"].trim())) throw new CliError("MISSING_FLAG", "Lead Form ads require an Instant Form ID. Pass --lead-form <id>.", "Copy the form ID from Meta Instant Forms and pass it as --lead-form <id>.");
   if (postId) {
@@ -1466,7 +1466,7 @@ async function createAd(client, _args, flags) {
   const mediaFormatInputs = collectFlagValues(flags, "media-format");
   const primaryTexts = collectFlagValues(flags, "primary-text");
   const headlines = collectFlagValues(flags, "headline");
-  const descriptions = collectFlagValues(flags, "description");
+  const linkDescriptions = collectFlagValues(flags, "link-description");
   if (mediaInputs.length === 0) throw new CliError("MISSING_FLAG", "Missing required flag: `--media` (or use `--creative` to reference an existing creative)", 'Run: adkit manage meta ads create --media ./hero.mp4 --primary-text "Hello" --adset as_xyz --publish');
   if (mediaFormatInputs.length > 0 && mediaFormatInputs.length !== mediaInputs.length) throw new CliError("INVALID_VALUE", "Pass one --media-format value for each --media value.", "Use --media-format default for the base media, then square, vertical, or horizontal for replacements.");
   const mediaFormats = mediaFormatInputs.map(readMediaFormatFlag);
@@ -1509,7 +1509,7 @@ async function createAd(client, _args, flags) {
   const ad = { adsetId, media };
   if (primaryTexts.length) ad.primaryTexts = primaryTexts;
   if (headlines.length) ad.headlines = headlines;
-  if (descriptions.length) ad.descriptions = descriptions;
+  if (linkDescriptions.length) ad.linkDescriptions = linkDescriptions;
   if (typeof flags.cta === "string") ad.cta = flags.cta;
   if (typeof flags.name === "string") ad.name = flags.name;
   if (typeof flags.url === "string") ad.url = flags.url;
@@ -1852,6 +1852,7 @@ var CONVERSION_UPLOAD_FLAGS = ["conversion", "gclid", "gbraid", "wbraid", "occur
 var CHANGE_HISTORY_FLAGS = ["account", "period", "from", "to", "limit", "resource", "campaign", "ad-group"];
 var KEYWORD_RESEARCH_FLAGS = ["url", "location", "language", "limit", "min-volume"];
 var TARGETING_RESEARCH_FLAGS = ["limit"];
+var GEO_LOCATION_SEARCH_FLAGS = ["country-code", "locale", "type", "limit"];
 var NUMBER_FLAG_PATTERN = /^(?:\d+|\d+\.\d+|\.\d+)(?:e[+-]?\d+)?$/iu;
 function generateCampaignName2() {
   return `campaign ${getDateStamp()}`;
@@ -2815,6 +2816,18 @@ async function researchInterests(client, args, flags) {
   const path3 = `/manage/google/research/interests${qs}`;
   return client.get(path3);
 }
+async function searchGoogleGeoLocations(client, args, flags) {
+  validateFlags(flags, GEO_LOCATION_SEARCH_FLAGS, "manage google geo-locations search");
+  const query = args.join(" ").trim();
+  if (!query) throw new CliError("MISSING_ARGUMENT", "Missing location query", 'Run: adkit manage google geo-locations search "Austin, Texas" --country-code US --type city');
+  const accountId = typeof flags.account === "string" ? flags.account : void 0;
+  const countryCode = typeof flags["country-code"] === "string" ? flags["country-code"] : void 0;
+  const locale = typeof flags.locale === "string" ? flags.locale : void 0;
+  const type = typeof flags.type === "string" ? flags.type : void 0;
+  const limit = typeof flags.limit === "string" ? flags.limit : void 0;
+  const qs = queryString({ accountId, query, countryCode, locale, type, limit });
+  return client.get(`/manage/google/geo-locations${qs}`);
+}
 function buildGoogleTargetingResearchQuery(args, flags, missingQueryHint) {
   const q = args.join(" ").trim();
   if (!q) throw new CliError("MISSING_ARGUMENT", "Missing query", missingQueryHint);
@@ -4745,7 +4758,7 @@ Flags (create \u2014 new creative from media):
   --media <path|url>  Media file or URL (repeatable). Handles upload + processing automatically for single-image/video ads
   --primary-text <t>  Ad body text (repeatable)
   --headline <text>   Headline text (repeatable)
-  --description <t>   Description text (repeatable, optional)
+  --link-description <t> Link preview subtitle (repeatable, optional)
 ${FLAG.cta}
   --name <name>       Ad name
   --url <url>         Landing page URL
@@ -4807,7 +4820,7 @@ Flags (create \u2014 new creative from media):
   --media-format <f>  Optional format for each --media: default, square, vertical, horizontal
   --primary-text <t>  Ad body text (repeatable)
   --headline <text>   Headline text (repeatable)
-  --description <t>   Description text (repeatable, optional)
+  --link-description <t> Link preview subtitle (repeatable, optional)
 ${FLAG.cta}
   --name <name>       Ad name
   --url <url>         Landing page URL
@@ -4843,6 +4856,7 @@ Note:
   media               [{ id: "imageHashOrVideoId" }, { id: "...", format: "vertical" }]
                       Normal media works on all placements. Add format only to replace a specific placement group with different media: square (Feed), vertical (Stories/Reels), horizontal (Right Column).
                       Do not use top-level media for carousel ads.
+  linkDescriptions    Link-preview subtitle copy for feed ads.
   carouselCards
                       Card list for carousel ads. Each card needs headline and media.
   carouselCards[].headline
@@ -5144,7 +5158,8 @@ Flags (list):
 
 Note:
   list returns campaign configuration only (name, status, budget).
-  Geo targeting lives in targeting.geoLocations. Use type=country for country targeting.
+  Geo targeting lives in targeting.geoLocations. Use type=country for countries.
+  For cities, regions, postal codes, and metros, run google geo-locations search and use the returned bare code.
   Advanced geo examples: adkit manage google campaigns --help full
   Display creation starts here: campaigns create --campaign-type display, then create Display ad groups and responsive_display ads.
   Performance Max: campaignType "performance_max" with asset groups \u2014 build it with --data. See --help full.
@@ -5195,9 +5210,9 @@ Flags (list):
 Notes:
   Use google assets for explicit account/campaign/ad-group attachment, reusable libraries, or richer sitelinks via --data.
   list returns campaign configuration only (name, status, budget).
-  Geo targeting lives in targeting.geoLocations. Use type=country for simple countries, or type=platformLocation for raw Google location/proximity geo.
-  With platformLocation, pass the exact Google geo object to send; AdKit does not look up or convert city names or addresses.
-  Google excludes support location geo target constants, not proximity radius exclusions.
+  Geo targeting lives in targeting.geoLocations. Use type=country for countries and copy named locations from google geo-locations search.
+  platformLocation accepts exact Google geo objects for advanced criteria and existing raw values.
+  Google exclusions support named locations. Proximity circles belong in include.
   Display campaign creation uses campaignType:"display" or --campaign-type display. Videos are not supported for Display media in v1.
   Performance Max: campaignType "performance_max" with exactly one assetGroups[] entry. Text assets inline ({role,text}); image assets are uploaded via google media first, then referenced by id/resourceName. Needs an enabled conversion (publish is blocked without one). Non-retail only. Build it with --data.
   View a Performance Max campaign by ID to read back assetGroups from Google. There is no separate google asset-groups command.
@@ -5207,7 +5222,7 @@ Examples:
   adkit manage google campaigns list --account 1234567890
   adkit manage google campaigns create --name "Display Prospecting" --campaign-type display --budget-daily 50 --account 1234567890
   adkit manage google campaigns create --data '{"campaigns":[{"name":"Display US","campaignType":"display","budget":{"daily":50},"targeting":{"geoLocations":{"include":[{"type":"country","country":"US"}]}}}]}' --account 1234567890
-  adkit manage google campaigns create --data '{"campaigns":[{"name":"Search US Native","campaignType":"search","budget":{"daily":5},"targeting":{"geoLocations":{"include":[{"type":"platformLocation","platform":"google","value":{"location":{"geo_target_constant":"geoTargetConstants/2840"}}}]}}}]}' --account 1234567890
+  adkit manage google campaigns create --data '{"campaigns":[{"name":"Austin Search","campaignType":"search","budget":{"daily":5},"targeting":{"geoLocations":{"include":[{"type":"city","code":"1026201"}]}}}]}' --account 1234567890
   adkit manage google campaigns create --data '{"campaigns":[{"name":"SF Radius","campaignType":"search","budget":{"daily":5},"targeting":{"geoLocations":{"include":[{"type":"platformLocation","platform":"google","value":{"proximity":{"geo_point":{"latitude_in_micro_degrees":37774900,"longitude_in_micro_degrees":-122419400},"radius":5,"radius_units":"MILES"}}}]}}}]}' --account 1234567890
   adkit manage google campaigns create --data '{"campaigns":[{"name":"PMAX Launch","campaignType":"performance_max","budget":{"daily":50},"bidStrategy":"maximize_conversions","assetGroups":[{"name":"Asset Group 1","finalUrls":["https://example.com"],"assets":[{"role":"headline","text":"Ship faster"},{"role":"headline","text":"Save hours every week"},{"role":"headline","text":"Start free today"},{"role":"long_headline","text":"Automate your ad workflow and launch in minutes"},{"role":"description","text":"Automate your workflow in minutes"},{"role":"description","text":"No credit card required"},{"role":"business_name","text":"Acme"},{"role":"logo","id":"<uploaded-asset-id>"},{"role":"marketing_image","id":"<uploaded-asset-id>"},{"role":"square_marketing_image","id":"<uploaded-asset-id>"}],"signals":[{"type":"search_theme","text":"project management software"}]}]}]}' --account 1234567890
   adkit manage google campaigns update 987654321 --status paused --account 1234567890
@@ -5731,6 +5746,24 @@ Notes:
   Topic search returns IDs for targeting.content.topics.include/exclude.
   Interest search returns IDs for targeting.audience.interests.include/exclude.
   Websites use direct URLs in targeting.content.websites.include/exclude. Bare numeric customAudiences IDs are treated as Google user lists (remarketing/Customer Match); for custom segments, pass a customAudiences/{id} or customers/{accountId}/customAudiences/{id} resource path.`;
+var GOOGLE_GEO_LOCATIONS_HELP = `adkit manage google geo-locations \u2014 Find locations for campaign targeting
+
+  search <place...>   Find enabled Google locations and return bare codes and AdKit types
+
+Flags:
+  --account <id>      Optional if one Google Ads account is connected
+  --country-code <c>  ISO country code such as US
+  --locale <locale>   Google result locale such as en
+  --type <type>       country, region, city, postal_code, or metro
+  --limit <n>         Max results (1-50, default: 10)
+
+Examples:
+  adkit manage google geo-locations search "Austin, Texas" --country-code US --type city
+  adkit manage google geo-locations search Paris --country-code FR --locale fr
+
+Supported results contain type; unmapped Google categories contain platformType.
+Pass type and the bare code into campaign targeting. For country, use {"type":"country","country":"US"}.
+AdKit builds the Google resource name.`;
 var GOOGLE_MEDIA_HELP = `adkit manage google media \u2014 Upload creative media to Google Ads
 
   upload              Upload an image and return reusable Google asset IDs
@@ -5841,6 +5874,7 @@ Examples:
   "google results keywords": GOOGLE_RESULTS_KEYWORDS_HELP,
   "google change-history": GOOGLE_CHANGE_HISTORY_HELP,
   "google research": GOOGLE_RESEARCH_HELP,
+  "google geo-locations": GOOGLE_GEO_LOCATIONS_HELP,
   "google media": GOOGLE_MEDIA_HELP,
   "google conversions": GOOGLE_CONVERSIONS_HELP,
   "tiktok accounts": `adkit manage tiktok accounts \u2014 TikTok Ads accounts
@@ -6274,6 +6308,7 @@ Entity groups:
   results             Performance metrics (campaigns, ad-groups, ads, keywords, search-terms)
   change-history      Recent Google Ads account changes from the last 30 days
   research            Keyword Planner plus Display topic/interest IDs
+  geo-locations       Find Google location codes for campaign targeting
   assets              Manage reusable assets (sitelinks, callouts, structured snippets, images)
   media               Upload images for Display creative media
 
@@ -6615,6 +6650,7 @@ var HELP_FULL = {
   "google results keywords": GOOGLE_RESULTS_KEYWORDS_HELP,
   "google change-history": GOOGLE_CHANGE_HISTORY_HELP,
   "google research": GOOGLE_RESEARCH_HELP,
+  "google geo-locations": GOOGLE_GEO_LOCATIONS_HELP,
   "google media": GOOGLE_MEDIA_HELP,
   "google conversions": GOOGLE_CONVERSIONS_HELP,
   "meta research": META_RESEARCH_HELP,
@@ -6951,15 +6987,17 @@ function printSingleEntity(e, entity) {
     const creative = ad.creative;
     if (creative) {
       lines.push("", "  Creative", "");
-      if (creative.id) lines.push(`  ID:           ${formatForTTY(creative.id)}`);
-      if (creative.headline) lines.push(`  Headline:     ${formatForTTY(creative.headline)}`);
-      if (creative.body) lines.push(`  Body:         ${formatForTTY(creative.body)}`);
-      if (creative.description) lines.push(`  Description:  ${formatForTTY(creative.description)}`);
+      const headlines = creative.headlines?.join(", ");
+      const primaryTexts = creative.primaryTexts?.join(", ");
+      const linkDescriptions = creative.linkDescriptions?.join(", ");
+      const mediaItems = creative.media?.map((item) => `${item.role}:${item.id}`) ?? [];
+      const media = mediaItems.join(", ");
+      if (headlines) lines.push(`  Headline:     ${formatForTTY(headlines)}`);
+      if (primaryTexts) lines.push(`  Body:         ${formatForTTY(primaryTexts)}`);
+      if (linkDescriptions) lines.push(`  Description:  ${formatForTTY(linkDescriptions)}`);
       if (creative.cta) lines.push(`  CTA:          ${formatForTTY(creative.cta)}`);
-      if (creative.linkUrl) lines.push(`  Link:         ${formatForTTY(creative.linkUrl)}`);
-      if (creative.imageUrl) lines.push(`  Image:        ${formatForTTY(creative.imageUrl)}`);
-      if (creative.thumbnailUrl) lines.push(`  Thumbnail:    ${formatForTTY(creative.thumbnailUrl)}`);
-      if (creative.videoId) lines.push(`  Video ID:     ${formatForTTY(creative.videoId)}`);
+      if (creative.url) lines.push(`  Link:         ${formatForTTY(creative.url)}`);
+      if (media) lines.push(`  Media:        ${formatForTTY(media)}`);
     }
     if (createdAt) lines.push(`  Created:      ${createdAt}`);
   }
@@ -7978,8 +8016,18 @@ async function main() {
             }
             break;
           }
+          case "geo-locations": {
+            if (!action) {
+              showHelp("google geo-locations", flags.help === "full");
+              return;
+            }
+            if (action !== "search") throw new CliError("UNKNOWN_COMMAND", `Unknown action: google geo-locations ${action}`, "Available: search");
+            data = await searchGoogleGeoLocations(client, restArgs, flags);
+            emptyHint = "No matching Google locations found. Try a broader place name or country filter.";
+            break;
+          }
           default:
-            throw new CliError("UNKNOWN_COMMAND", `Unknown entity: google ${entity}`, "Available: accounts, assets, media, campaigns, ad-groups, ads, keywords, conversions, results, change-history, research");
+            throw new CliError("UNKNOWN_COMMAND", `Unknown entity: google ${entity}`, "Available: accounts, assets, media, campaigns, ad-groups, ads, keywords, conversions, results, change-history, research, geo-locations");
         }
       } else if (platform2 === "tiktok") {
         switch (entity) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adkit/cli",
-  "version": "1.13.5",
+  "version": "1.13.6",
   "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",