@koda-sl/baker-cli 0.574.0-dev.19539e5a8 → 0.575.0-dev.85f21462e

package/dist/targeting-AVHPKERN.js

@@ -0,0 +1,762 @@
+import {
+  loadJsonFileArg
+} from "./chunk-WFTTF2MP.js";
+import {
+  metaTargetingSchema
+} from "./chunk-GC5P4KWY.js";
+import "./chunk-GDFJOCDO.js";
+import {
+  csvOrJson,
+  handleMetaError,
+  resolveAccountIdArg
+} from "./chunk-FCD5BPC5.js";
+import {
+  repeatedValues
+} from "./chunk-ERSX3MKH.js";
+import "./chunk-YT6YI47O.js";
+import "./chunk-4NZ47VXO.js";
+import "./chunk-D5FY4FAK.js";
+import "./chunk-HZ7QUFUW.js";
+import "./chunk-QALAJNBG.js";
+import {
+  writeAdsJson,
+  writeAdsOutput,
+  writeJsonEnvelope
+} from "./chunk-VJUVTMHY.js";
+import "./chunk-T4HIFVNK.js";
+import "./chunk-CGLNCFAG.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-HPF3USL2.js";
+import "./chunk-E2G2USTA.js";
+import "./chunk-EFZVDV7F.js";
+import "./chunk-U3LO5TDH.js";
+import "./chunk-TJTCHTR4.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-3WOFZTGC.js";
+import {
+  apiPost
+} from "./chunk-JCFZ7ECN.js";
+import "./chunk-OFSUVUXT.js";
+import "./chunk-OMLZ35HJ.js";
+import {
+  registerSchema
+} from "./chunk-NXNOXZGB.js";
+import "./chunk-YQSBHWOI.js";
+
+// ../api/src/ads-meta/discovery.ts
+import { z } from "zod";
+var META_TARGETING_CATEGORY_CLASSES = [
+  "interests",
+  "behaviors",
+  "demographics",
+  "life_events",
+  "industries",
+  "income",
+  "family_statuses"
+];
+var META_GEO_LOCATION_TYPES = [
+  "country",
+  "country_group",
+  "region",
+  "city",
+  "zip",
+  "geo_market",
+  "electoral_district",
+  "neighborhood",
+  "subcity",
+  "metro_area",
+  "medium_geo_area",
+  "place"
+];
+var accountIdSchema = z.string().regex(/^(act_)?\d+$/, "account id must be act_<digits>");
+var limitSchema = z.number().int().positive().max(1e3).optional();
+var metaTargetingRefSchema = z.object({ id: z.string().regex(/^\d+$/), type: z.string().min(1) });
+var metaTargetingLookupRequestSchema = z.discriminatedUnion("mode", [
+  z.object({
+    mode: z.literal("search"),
+    accountId: accountIdSchema,
+    q: z.string().min(1),
+    /** A spec key (interests, behaviors, work_employers, …) to keep the search to one kind. */
+    type: z.string().min(1).optional(),
+    /** Special Ad Categories: only the options Meta allows under them come back. */
+    specialAdCategories: z.array(z.string().min(1)).optional(),
+    limit: limitSchema
+  }),
+  z.object({
+    mode: z.literal("browse"),
+    accountId: accountIdSchema,
+    type: z.string().min(1).optional(),
+    /** Kept by Baker after the read: Meta's browse takes no text filter. */
+    q: z.string().min(1).optional(),
+    limit: limitSchema
+  }),
+  z.object({
+    mode: z.literal("categories"),
+    accountId: accountIdSchema,
+    class: z.enum(META_TARGETING_CATEGORY_CLASSES),
+    q: z.string().min(1).optional(),
+    limit: limitSchema
+  }),
+  z.object({
+    mode: z.literal("suggest"),
+    accountId: accountIdSchema,
+    options: z.array(metaTargetingRefSchema).min(1).max(50),
+    limit: limitSchema
+  }),
+  z.object({
+    mode: z.literal("validate"),
+    accountId: accountIdSchema,
+    options: z.array(metaTargetingRefSchema).max(500).optional(),
+    names: z.array(z.string().min(1)).max(500).optional()
+  }),
+  z.object({
+    mode: z.literal("geo"),
+    accountId: accountIdSchema,
+    q: z.string().min(1),
+    locationTypes: z.array(z.enum(META_GEO_LOCATION_TYPES)).optional(),
+    countryCode: z.string().length(2).optional(),
+    limit: limitSchema
+  }),
+  z.object({
+    mode: z.literal("locales"),
+    accountId: accountIdSchema,
+    q: z.string().min(1),
+    limit: limitSchema
+  })
+]);
+var metaDeliveryEstimateRequestSchema = z.object({
+  accountId: accountIdSchema,
+  targeting: metaTargetingSchema.optional(),
+  adSetId: z.string().regex(/^\d+$/).optional(),
+  optimizationGoal: z.string().min(1).optional(),
+  promotedObject: z.record(z.string(), z.unknown()).optional()
+}).refine((r) => r.targeting === void 0 !== (r.adSetId === void 0), {
+  message: "pass either a targeting spec or an existing ad set id, not both"
+}).refine((r) => r.targeting === void 0 || r.optimizationGoal !== void 0, {
+  message: "a targeting spec is sized for a goal \u2014 pass --optimization-goal (the ad set's, e.g. LINK_CLICKS)",
+  path: ["optimizationGoal"]
+});
+var metaTargetingDescribeRequestSchema = z.object({
+  accountId: accountIdSchema,
+  targeting: metaTargetingSchema.optional(),
+  adSetId: z.string().regex(/^\d+$/).optional()
+}).refine((r) => r.targeting === void 0 !== (r.adSetId === void 0), {
+  message: "pass either a targeting spec or an existing ad set id, not both"
+});
+var META_SMALL_AUDIENCE_THRESHOLD = 1e3;
+var GEO_KEY_LISTS = {
+  region: "regions",
+  city: "cities",
+  zip: "zips",
+  geo_market: "geo_markets",
+  electoral_district: "electoral_districts",
+  neighborhood: "neighborhoods",
+  subcity: "subcities",
+  metro_area: "metro_areas",
+  medium_geo_area: "medium_geo_areas",
+  place: "places"
+};
+function pushTo(record, key, value) {
+  const list = record[key] ?? [];
+  list.push(value);
+  record[key] = list;
+}
+function geoEntry(option, type) {
+  if (type === "country") return { key: "countries", value: option.country_code ?? option.id };
+  if (type === "country_group") return { key: "country_groups", value: option.id };
+  const list = GEO_KEY_LISTS[type];
+  return list ? { key: list, value: { key: option.id } } : void 0;
+}
+function targetingFragment(options) {
+  const detailed = {};
+  const geo = {};
+  const locales = [];
+  for (const option of options) {
+    const type = option.type ?? "interests";
+    const place = geoEntry(option, type);
+    if (type === "locale") {
+      locales.push(Number(option.id));
+    } else if (place) {
+      pushTo(geo, place.key, place.value);
+    } else {
+      pushTo(detailed, type, option.name ? { id: option.id, name: option.name } : { id: option.id });
+    }
+  }
+  const fragment = {};
+  if (Object.keys(geo).length > 0) fragment.geo_locations = geo;
+  if (locales.length > 0) fragment.locales = locales;
+  if (Object.keys(detailed).length > 0) fragment.flexible_spec = [detailed];
+  return fragment;
+}
+var NOT_DETAILED_OPTIONS = /* @__PURE__ */ new Set([
+  "custom_audiences",
+  "excluded_custom_audiences",
+  "connections",
+  "excluded_connections",
+  "friends_of_connections",
+  "product_audience_specs",
+  "excluded_product_audience_specs"
+]);
+var NUMERIC_ID = /^\d+$/;
+function entryId(entry) {
+  const id = typeof entry === "object" && entry !== null ? entry.id : void 0;
+  const text = typeof id === "number" && Number.isSafeInteger(id) ? String(id) : id;
+  return typeof text === "string" && NUMERIC_ID.test(text) ? text : void 0;
+}
+var TOP_LEVEL_DETAILED_KEYS = [
+  "interests",
+  "behaviors",
+  "life_events",
+  "industries",
+  "income",
+  "family_statuses",
+  "user_adclusters",
+  "work_employers",
+  "work_positions",
+  "education_schools",
+  "education_majors"
+];
+function collectEntries(type, entries, seen, out) {
+  for (const entry of entries) {
+    const id = entryId(entry);
+    if (id === void 0 || seen.has(`${type}:${id}`)) continue;
+    seen.add(`${type}:${id}`);
+    out.push({ id, type });
+  }
+}
+function collectFrom(group, seen, out) {
+  if (typeof group !== "object" || group === null || Array.isArray(group)) return;
+  for (const [type, entries] of Object.entries(group)) {
+    if (!NOT_DETAILED_OPTIONS.has(type) && Array.isArray(entries)) collectEntries(type, entries, seen, out);
+  }
+}
+function targetingOptionRefs(targeting) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const { flexible_spec, exclusions, ...topLevel } = targeting;
+  const detailed = new Set(TOP_LEVEL_DETAILED_KEYS);
+  collectFrom(Object.fromEntries(Object.entries(topLevel).filter(([key]) => detailed.has(key))), seen, out);
+  if (Array.isArray(flexible_spec)) {
+    for (const group of flexible_spec) collectFrom(group, seen, out);
+  }
+  collectFrom(exclusions, seen, out);
+  return out;
+}
+
+// src/commands/ads/meta/targeting.ts
+import { defineCommand } from "citty";
+
+// src/commands/ads/meta/targeting-rows.ts
+var FRAGMENT_SIZE = 5;
+function humanCount(n) {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1).replace(/\.0$/, "")}B`;
+  if (n >= 1e6) return `${Math.round(n / 1e6)}M`;
+  if (n >= 1e4) return `${Math.round(n / 1e3)}K`;
+  return String(n);
+}
+function audienceRange(lower, upper) {
+  if (lower === void 0 && upper === void 0) return void 0;
+  if (lower === void 0 || upper === void 0 || lower === upper) return humanCount(upper ?? lower ?? 0);
+  return `${humanCount(lower)}\u2013${humanCount(upper)}`;
+}
+function compactTargetingOption(option) {
+  const row = { id: option.id, name: option.name, type: option.type };
+  if (option.path?.length) row.path = option.path.join(" > ");
+  const audience = audienceRange(option.audience_size_lower_bound, option.audience_size_upper_bound);
+  if (audience) row.audience = audience;
+  if (option.country_code) row.country = option.country_code;
+  if (option.region) row.region = option.region;
+  if (option.valid !== void 0) row.valid = option.valid;
+  if (option.status) row.status = option.status;
+  return row;
+}
+var DETAILED_MODES = /* @__PURE__ */ new Set(["search", "browse", "categories", "suggest"]);
+function pasteHint(rows, where) {
+  const fragment = JSON.stringify(targetingFragment(rows.slice(0, FRAGMENT_SIZE)));
+  return `${where} \u2014 the first ${Math.min(rows.length, FRAGMENT_SIZE)} as a fragment of the ad set's --targeting-file (keep only the ones you mean): ${fragment}`;
+}
+function validationHints(rows) {
+  const invalid = rows.filter((row) => row.valid === false);
+  const retiring = rows.filter((row) => row.status === "DEPRECATING" || row.status === "NON-DELIVERABLE");
+  const hints = [];
+  if (invalid.length > 0) {
+    hints.push(
+      `${invalid.length} option(s) are not valid on this account (${invalid.map((r) => `${r.type ?? "?"} ${r.id}`).join(", ")}) \u2014 staging an ad set with them is refused. An id only counts under the key Meta lists it with; find the right one with \`targeting search --q <word>\` and use its \`type\`.`
+    );
+  }
+  if (retiring.length > 0) {
+    hints.push(
+      `${retiring.map((r) => `${r.name ?? r.id} (${r.status})`).join(", ")}: Meta is retiring these or no longer delivers to them \u2014 replace them; \`targeting suggest --id <type>:<id>\` lists close alternatives.`
+    );
+  }
+  if (hints.length === 0 && rows.length > 0) hints.push("Every option is valid and delivering on this account.");
+  return hints;
+}
+function targetingHints(mode, rows) {
+  if (mode === "validate") return validationHints(rows);
+  if (rows.length === 0) {
+    return [
+      mode === "geo" || mode === "locales" ? "Nothing matched. Meta matches the start of a place or language name \u2014 try the local spelling or a shorter word." : "Nothing matched. Meta names options in English \u2014 try an English or broader word, `targeting browse --type interests`, or `targeting categories --class behaviors`."
+    ];
+  }
+  if (DETAILED_MODES.has(mode)) {
+    return [
+      pasteHint(rows, "Detailed targeting goes in flexible_spec"),
+      "Options in one flexible_spec group are OR'd (anyone matching one); a second group ANDs (must match both). `type` is the key each id goes under \u2014 never move an id to another key. Audience sizes are Meta's worldwide range for the option alone; `targeting estimate` sizes the whole spec."
+    ];
+  }
+  if (mode === "geo") {
+    return [
+      pasteHint(rows, "Places go in geo_locations"),
+      'A city can take "radius" + "distance_unit" (10\u201350 mile / 17\u201380 kilometer). Special Ad Categories refuse zips and electoral districts and need a 15 mile radius on cities.'
+    ];
+  }
+  return [pasteHint(rows, "Languages go in locales (numbers, not names)")];
+}
+function estimateHints(estimate) {
+  if (!estimate.ready) {
+    return [
+      "Meta has not finished this estimate \u2014 run it again in a few seconds before reading the numbers. If it stays unready at 0, Meta could not size the spec at all: check its ids with `targeting validate --targeting-file <file>`."
+    ];
+  }
+  const upper = estimate.audienceUpperBound;
+  if (upper !== void 0 && upper <= META_SMALL_AUDIENCE_THRESHOLD) {
+    return [
+      "1,000 is the smallest estimate Meta reports, so this audience may be far smaller. Too narrow to deliver steadily or leave learning \u2014 widen places, ages or interests unless reaching only these people is the point. Staging an ad set with this audience warns the same."
+    ];
+  }
+  return [
+    "Monthly people the spec can reach for this goal (Meta's range, not a forecast of results). Compare variants by re-running with a changed --targeting-file."
+  ];
+}
+function parseOptionRef(raw) {
+  const match = /^(?:([a-z_]+):)?(\d+)$/.exec(raw.trim());
+  if (!match?.[2]) return void 0;
+  return { type: match[1] ?? "interests", id: match[2] };
+}
+
+// src/commands/ads/meta/targeting.ts
+function failValidation(message) {
+  writeAdsJson({ ok: false, error: { code: "VALIDATION_ERROR", message } });
+  process.exit(1);
+}
+function limitArg(args) {
+  if (args.limit === void 0) return void 0;
+  const n = Number(args.limit);
+  if (!Number.isInteger(n) || n <= 0 || n > 1e3) failValidation("--limit must be a whole number from 1 to 1000");
+  return n;
+}
+function csvList(value) {
+  if (typeof value !== "string" || value.trim() === "") return void 0;
+  return value.split(",").map((part) => part.trim()).filter(Boolean);
+}
+function optionRefs(rawArgs, parsed) {
+  return repeatedValues(rawArgs, "id", parsed).map((raw) => {
+    const ref = parseOptionRef(raw);
+    if (!ref) failValidation(`--id "${raw}" is not <type>:<id> (e.g. interests:6003437140731) or a bare id`);
+    return ref;
+  });
+}
+async function runLookup(args, request) {
+  const parsed = metaTargetingLookupRequestSchema.safeParse(request);
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    failValidation(issue ? `${issue.path.join(".") || "request"}: ${issue.message}` : "invalid request");
+  }
+  try {
+    const rows = await apiPost("/api/ads/meta/targeting", {
+      ...parsed.data,
+      ...args["no-cache"] ? { skipCache: true } : {}
+    });
+    const data = args.full ? rows.map((row) => ({ ...row })) : rows.map(compactTargetingOption);
+    const hints = targetingHints(parsed.data.mode, rows);
+    const fmt = csvOrJson(args);
+    if (fmt !== "json") {
+      writeAdsOutput(data, fmt, void 0, hints);
+      return;
+    }
+    writeJsonEnvelope({ ok: true, data, hints });
+  } catch (err) {
+    handleMetaError(err);
+  }
+}
+var commonArgs = {
+  "account-id": {
+    type: "string",
+    description: "Meta ad account ID (act_...) \u2014 options are looked up as this account sees them"
+  },
+  limit: { type: "string", description: "Max options (default 25, up to 1000)" },
+  full: {
+    type: "boolean",
+    description: "Every field Meta sent (description, raw audience bounds) instead of the compact row"
+  },
+  "no-cache": NO_CACHE_ARG,
+  output: { type: "string", description: "json|csv|jsonl|md", default: "json" }
+};
+var schemaCommonArgs = {
+  "account-id": { type: "string", description: "Meta ad account ID (act_123)", required: false },
+  limit: { type: "string", description: "Max options (default 25)", required: false },
+  full: { type: "boolean", description: "Every field Meta sent", required: false },
+  "no-cache": { type: "boolean", description: "Bypass the cache", required: false },
+  output: { type: "string", description: "json|csv|jsonl|md", required: false, default: "json" }
+};
+registerSchema({
+  command: "ads.meta.targeting.search",
+  description: "Find Meta detailed-targeting ids by word \u2014 interests, behaviors, demographics, employers, job titles, schools, life events \u2014 across every kind at once. Start here before writing any interest or behavior into a --targeting-file: targeting takes ids, never names. Each row's `type` is the key it goes under.",
+  args: {
+    q: { type: "string", description: "Word to search (English names work best)", required: true },
+    type: {
+      type: "string",
+      description: "Keep to one kind: interests|behaviors|work_employers|work_positions|education_schools|life_events|\u2026",
+      required: false
+    },
+    "special-ad-category": {
+      type: "string",
+      description: "HOUSING|EMPLOYMENT|FINANCIAL_PRODUCTS_SERVICES \u2014 only options allowed under it",
+      required: false
+    },
+    ...schemaCommonArgs
+  }
+});
+var searchCommand = defineCommand({
+  meta: {
+    name: "search",
+    description: 'Find detailed-targeting ids by word. Start here: baker ads meta targeting search --account-id act_123 --q "solar energy"'
+  },
+  args: {
+    q: { type: "string", description: "Word to search (English names work best)", required: true },
+    type: {
+      type: "string",
+      description: "Keep to one spec key, e.g. interests, behaviors, work_employers, work_positions"
+    },
+    "special-ad-category": {
+      type: "string",
+      description: "Comma list of Special Ad Categories \u2014 returns only options Meta allows under them"
+    },
+    ...commonArgs
+  },
+  run: async ({ args }) => runLookup(args, {
+    mode: "search",
+    accountId: await resolveAccountIdArg(args),
+    q: args.q,
+    type: args.type,
+    specialAdCategories: csvList(args["special-ad-category"]),
+    limit: limitArg(args)
+  })
+});
+registerSchema({
+  command: "ads.meta.targeting.browse",
+  description: "Browse Meta's detailed-targeting tree (what exists, with no word to search for), optionally one kind and narrowed by a word in the name or path.",
+  args: {
+    type: { type: "string", description: "interests|behaviors|life_events|work_positions|\u2026", required: false },
+    q: { type: "string", description: "Keep rows whose name or path contains this", required: false },
+    ...schemaCommonArgs
+  }
+});
+var browseCommand = defineCommand({
+  meta: {
+    name: "browse",
+    description: "Browse the detailed-targeting tree. Example: baker ads meta targeting browse --account-id act_123 --type behaviors --q travel"
+  },
+  args: {
+    type: { type: "string", description: "One spec key: interests, behaviors, life_events, \u2026" },
+    q: { type: "string", description: "Keep rows whose name or path contains this" },
+    ...commonArgs
+  },
+  run: async ({ args }) => runLookup(args, {
+    mode: "browse",
+    accountId: await resolveAccountIdArg(args),
+    type: args.type,
+    q: args.q,
+    limit: limitArg(args)
+  })
+});
+registerSchema({
+  command: "ads.meta.targeting.categories",
+  description: "List a whole Meta targeting class (behaviors, demographics, life_events, industries, income, family_statuses, \u2026) \u2014 the fixed lists a search word rarely finds.",
+  args: {
+    class: {
+      type: "string",
+      description: "Targeting class",
+      required: true,
+      enum: [...META_TARGETING_CATEGORY_CLASSES]
+    },
+    q: { type: "string", description: "Keep rows whose name or path contains this", required: false },
+    ...schemaCommonArgs
+  }
+});
+var categoriesCommand = defineCommand({
+  meta: {
+    name: "categories",
+    description: `List one targeting class whole. Classes: ${META_TARGETING_CATEGORY_CLASSES.join(", ")}. Example: baker ads meta targeting categories --account-id act_123 --class life_events --q parent`
+  },
+  args: {
+    class: { type: "string", description: `One of ${META_TARGETING_CATEGORY_CLASSES.join("|")}`, required: true },
+    q: { type: "string", description: "Keep rows whose name or path contains this" },
+    ...commonArgs
+  },
+  run: async ({ args }) => runLookup(args, {
+    mode: "categories",
+    accountId: await resolveAccountIdArg(args),
+    class: args.class,
+    q: args.q,
+    limit: limitArg(args)
+  })
+});
+registerSchema({
+  command: "ads.meta.targeting.suggest",
+  description: "Options Meta suggests next to ones you already chose (Meta's 'Suggestions' in Ads Manager). Repeat --id <type>:<id>.",
+  args: {
+    id: {
+      type: "string",
+      description: "Repeatable <type>:<id>, e.g. interests:6003437140731 (a bare id is an interest)",
+      required: true
+    },
+    ...schemaCommonArgs
+  }
+});
+var suggestCommand = defineCommand({
+  meta: {
+    name: "suggest",
+    description: "Related options for ones you picked. Example: baker ads meta targeting suggest --account-id act_123 --id interests:6003437140731 --id behaviors:6002714898572"
+  },
+  args: {
+    id: { type: "string", description: "Repeatable <type>:<id> (a bare id is read as an interest)", required: true },
+    ...commonArgs
+  },
+  run: async ({ args, rawArgs }) => runLookup(args, {
+    mode: "suggest",
+    accountId: await resolveAccountIdArg(args),
+    options: optionRefs(rawArgs, args.id),
+    limit: limitArg(args)
+  })
+});
+registerSchema({
+  command: "ads.meta.targeting.validate",
+  description: "Check detailed-targeting ids before staging: whether Meta accepts each on this account under its key, and whether Meta is retiring it. Pass a whole --targeting-file, repeated --id <type>:<id>, or --name.",
+  args: {
+    "targeting-file": {
+      type: "string",
+      description: "The ad set's targeting JSON \u2014 every id in it is checked",
+      required: false
+    },
+    id: { type: "string", description: "Repeatable <type>:<id>", required: false },
+    name: { type: "string", description: "Repeatable option name", required: false },
+    ...schemaCommonArgs
+  }
+});
+var validateCommand = defineCommand({
+  meta: {
+    name: "validate",
+    description: "Validate targeting ids before staging. Example: baker ads meta targeting validate --account-id act_123 --targeting-file t.json"
+  },
+  args: {
+    "targeting-file": {
+      type: "string",
+      description: "The ad set's targeting JSON \u2014 every detailed-targeting id in it"
+    },
+    id: { type: "string", description: "Repeatable <type>:<id>" },
+    name: { type: "string", description: "Repeatable option name, matched exactly" },
+    ...commonArgs
+  },
+  run: async ({ args, rawArgs }) => {
+    const fromFile = args["targeting-file"] ? targetingOptionRefs(loadJsonFileArg(args["targeting-file"])) : [];
+    const options = [...fromFile, ...optionRefs(rawArgs, args.id)];
+    const names = repeatedValues(rawArgs, "name", args.name);
+    if (options.length === 0 && names.length === 0) {
+      failValidation(
+        args["targeting-file"] ? "the targeting file names no detailed-targeting ids (interests, behaviors, flexible_spec \u2026) \u2014 nothing to validate" : "pass --targeting-file, --id <type>:<id> or --name"
+      );
+    }
+    await runLookup(args, {
+      mode: "validate",
+      accountId: await resolveAccountIdArg(args),
+      ...options.length > 0 ? { options } : {},
+      ...names.length > 0 ? { names } : {}
+    });
+  }
+});
+registerSchema({
+  command: "ads.meta.targeting.geo",
+  description: "Find Meta location keys \u2014 countries, regions, cities, zips, DMAs (geo_market), electoral districts, neighborhoods \u2014 for geo_locations.",
+  args: {
+    q: { type: "string", description: "Place name", required: true },
+    "location-types": {
+      type: "string",
+      description: `Comma list of ${META_GEO_LOCATION_TYPES.join("|")}`,
+      required: false
+    },
+    country: { type: "string", description: "ISO-2 country code to search within", required: false },
+    ...schemaCommonArgs
+  }
+});
+var geoCommand = defineCommand({
+  meta: {
+    name: "geo",
+    description: "Find location keys for geo_locations. Example: baker ads meta targeting geo --account-id act_123 --q Madrid --location-types city,region --country ES"
+  },
+  args: {
+    q: { type: "string", description: "Place name", required: true },
+    "location-types": { type: "string", description: `Comma list: ${META_GEO_LOCATION_TYPES.join(", ")}` },
+    country: { type: "string", description: "ISO-2 country code to search within (ES, US, \u2026)" },
+    ...commonArgs
+  },
+  run: async ({ args }) => runLookup(args, {
+    mode: "geo",
+    accountId: await resolveAccountIdArg(args),
+    q: args.q,
+    locationTypes: csvList(args["location-types"]),
+    countryCode: args.country,
+    limit: limitArg(args)
+  })
+});
+registerSchema({
+  command: "ads.meta.targeting.locales",
+  description: "Find Meta locale numbers for targeting.locales (languages people use Facebook in).",
+  args: {
+    q: { type: "string", description: "Language name, e.g. Spanish", required: true },
+    ...schemaCommonArgs
+  }
+});
+var localesCommand = defineCommand({
+  meta: {
+    name: "locales",
+    description: "Find language numbers for targeting.locales. Example: baker ads meta targeting locales --account-id act_123 --q Spanish"
+  },
+  args: {
+    q: { type: "string", description: "Language name", required: true },
+    ...commonArgs
+  },
+  run: async ({ args }) => runLookup(args, { mode: "locales", accountId: await resolveAccountIdArg(args), q: args.q, limit: limitArg(args) })
+});
+registerSchema({
+  command: "ads.meta.targeting.estimate",
+  description: "How many people a targeting spec reaches on this account for a goal (Meta's delivery estimate), or what an existing ad set reaches. Use it to size an audience before staging and to compare variants.",
+  args: {
+    "targeting-file": { type: "string", description: "Targeting JSON, as for adsets create", required: false },
+    "adset-id": { type: "string", description: "Estimate an existing ad set instead", required: false },
+    "optimization-goal": {
+      type: "string",
+      description: "e.g. LEAD_GENERATION, OFFSITE_CONVERSIONS, LINK_CLICKS",
+      required: false
+    },
+    "promoted-object": {
+      type: "string",
+      description: 'JSON, e.g. {"pixel_id":"111","custom_event_type":"LEAD"}',
+      required: false
+    },
+    "account-id": { type: "string", description: "Meta ad account ID (act_123)", required: false }
+  }
+});
+function promotedObjectArg(raw) {
+  if (typeof raw !== "string" || raw === "") return void 0;
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+  } catch {
+  }
+  failValidation("--promoted-object must be a JSON object");
+}
+var estimateCommand = defineCommand({
+  meta: {
+    name: "estimate",
+    description: "Audience size for a targeting spec or an ad set. Example: baker ads meta targeting estimate --account-id act_123 --targeting-file t.json --optimization-goal LEAD_GENERATION"
+  },
+  args: {
+    "targeting-file": { type: "string", description: "Targeting JSON (the same file adsets create takes)" },
+    "adset-id": { type: "string", description: "Existing ad set to estimate instead of a file" },
+    "optimization-goal": { type: "string", description: "The ad set's optimization goal \u2014 the estimate depends on it" },
+    "promoted-object": { type: "string", description: "Promoted object JSON for conversion goals" },
+    "account-id": commonArgs["account-id"]
+  },
+  run: async ({ args }) => {
+    const parsed = metaDeliveryEstimateRequestSchema.safeParse({
+      accountId: await resolveAccountIdArg(args),
+      targeting: args["targeting-file"] ? loadJsonFileArg(args["targeting-file"]) : void 0,
+      adSetId: args["adset-id"],
+      optimizationGoal: args["optimization-goal"],
+      promotedObject: promotedObjectArg(args["promoted-object"])
+    });
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0];
+      failValidation(issue ? `${issue.path.join(".") || "request"}: ${issue.message}` : "invalid request");
+    }
+    try {
+      const data = await apiPost("/api/ads/meta/delivery-estimate", parsed.data);
+      writeJsonEnvelope({ ok: true, data, hints: estimateHints(data) });
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+registerSchema({
+  command: "ads.meta.targeting.describe",
+  description: "A targeting spec, or a live ad set's targeting, in Meta's own words \u2014 the audience definition Ads Manager shows (locations, ages, interests, placements). Use it to say who an ad set reaches in plain words.",
+  args: {
+    "targeting-file": { type: "string", description: "Targeting JSON, as for adsets create", required: false },
+    "adset-id": { type: "string", description: "Describe an existing ad set instead", required: false },
+    "account-id": { type: "string", description: "Meta ad account ID (act_123)", required: false }
+  }
+});
+var describeCommand = defineCommand({
+  meta: {
+    name: "describe",
+    description: "Who a targeting spec or an ad set reaches, in Meta's words. Example: baker ads meta targeting describe --account-id act_123 --adset-id 6123"
+  },
+  args: {
+    "targeting-file": { type: "string", description: "Targeting JSON (the same file adsets create takes)" },
+    "adset-id": { type: "string", description: "Existing ad set to describe instead of a file" },
+    "account-id": commonArgs["account-id"]
+  },
+  run: async ({ args }) => {
+    const parsed = metaTargetingDescribeRequestSchema.safeParse({
+      accountId: await resolveAccountIdArg(args),
+      targeting: args["targeting-file"] ? loadJsonFileArg(args["targeting-file"]) : void 0,
+      adSetId: args["adset-id"]
+    });
+    if (!parsed.success) {
+      const issue = parsed.error.issues[0];
+      failValidation(issue ? `${issue.path.join(".") || "request"}: ${issue.message}` : "invalid request");
+    }
+    try {
+      const data = await apiPost("/api/ads/meta/targeting-describe", parsed.data);
+      writeJsonEnvelope({ ok: true, data });
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+var targetingCommand = defineCommand({
+  meta: {
+    name: "targeting",
+    description: `Look up the ids Meta targeting takes, check them, and size the audience \u2014 all reads, nothing staged.
+
+Start here before writing interests, behaviors, places or languages into an ad set's --targeting-file:
+  baker ads meta targeting search --account-id act_123 --q "solar energy"          \u2014 detailed targeting ids, every kind
+  baker ads meta targeting geo --account-id act_123 --q Madrid --country ES        \u2014 location keys
+  baker ads meta targeting locales --account-id act_123 --q Spanish                \u2014 language numbers
+  baker ads meta targeting categories --account-id act_123 --class behaviors       \u2014 a whole class
+  baker ads meta targeting browse --account-id act_123 --type interests --q energy
+  baker ads meta targeting suggest --account-id act_123 --id interests:6003437140731
+  baker ads meta targeting validate --account-id act_123 --targeting-file t.json   \u2014 before staging
+  baker ads meta targeting estimate --account-id act_123 --targeting-file t.json --optimization-goal LEAD_GENERATION
+  baker ads meta targeting describe --account-id act_123 --adset-id 6123             \u2014 the audience in Meta's words`
+  },
+  subCommands: {
+    search: searchCommand,
+    browse: browseCommand,
+    categories: categoriesCommand,
+    suggest: suggestCommand,
+    validate: validateCommand,
+    geo: geoCommand,
+    locales: localesCommand,
+    estimate: estimateCommand,
+    describe: describeCommand
+  }
+});
+export {
+  targetingCommand
+};
+//# sourceMappingURL=targeting-AVHPKERN.js.map