@koda-sl/baker-cli 0.151.0 → 0.152.0

package/README.md

@@ -858,6 +858,7 @@ audit --format md              # deliverable-ready markdown table
 
 campaign-groups create|update|pause|resume|duplicate    # staged writes (see below)
 campaigns create|update|pause|resume|archive|duplicate
+campaigns url-params <ad-set-id>                        # UTMs for every ad in the ad set
 creatives create|update|pause|resume|duplicate
 audiences create|upload
 conversions create|update
@@ -880,6 +881,12 @@ baker ads linkedin campaigns create --name "ABM Tier-1" --group li_temp_x1 \
 baker ads linkedin creatives create --campaign li_temp_x2 --format image \
   --image-id <bakerImageId> --headline "Book a demo" --landing-url https://example.com/demo --cta REQUEST_DEMO
 
+# UTMs belong on the ad set — LinkedIn appends them to every ad in it, live ones included
+baker ads linkedin campaigns url-params 123456 \
+  --param "utm_source=linkedin&utm_medium=paid-social" \
+  --dynamic utm_campaign=CAMPAIGN_NAME --dynamic utm_content=CREATIVE_ID
+baker ads linkedin campaigns url-params 123456 --clear        # remove them all
+
 # Fix the classic audit findings
 baker ads linkedin campaigns update 123456 --audience-expansion off --lan off
 baker ads linkedin campaigns update 123456 --bid 7.50 --daily-budget 100 --currency USD
@@ -4731,6 +4738,7 @@ This CLI is designed for AI agent consumption. Key patterns:
 - **0.121.0**: `lead-forms create` drops the `privacyPolicyText` field — LinkedIn's versioned lead-form API has no privacy-policy-text slot, so it was silently discarded on publish. Use `legalDisclaimer` (shown under the form) or `consents[]` (disclosure checkboxes) instead. (Companion backend fix: staged lead-form questions were serialized in a shape LinkedIn dropped — they now publish correctly, and the staged preview lists each question.)
 - **0.119.0**: `draft amend`/`draft show` land on both `baker ads google` and `baker ads linkedin` — a generic JSON-merge-patch to update any staged op in place plus a full-payload receipt, replacing remove+recreate as the correction path. Google gains `assets update` and `asset-groups create|update` (Performance Max asset groups are now their own entity — `ads create --format performanceMaxAssetGroup` never worked and is gone); `ads create --format video` moves from a bare YouTube id to `--video-assets` refs (**breaking flag change** — stage the video as an asset first); `--format demandGen` gains `--image-assets`/`--square-image-assets`/`--logo-image-assets` and flag-building for headlines/descriptions. LinkedIn's `draft list` now renders a readable Campaign group ▸ Campaign ▸ Creative tree by default (`--json` for raw), `creatives update` gains `--campaign` (re-parent while staged), and `campaigns update` passes create-only fields (`--group`/`--type`/`--locale`/`--associated-entity`) through when amending a `li_temp_*` staged create instead of always stripping them.
 - **0.150.0**: `baker landing critique` gains an `agent-washing` rule in the `copy` family — an autonomy claim ("fully autonomous", "while you sleep", "no human intervention") with no signal anywhere on the page about who oversees the agent (approval, review, override, undo/rollback, audit log, escalation) scores a warn. Page-scope, so a hero may defer the trust story to a later section; generic privacy boilerplate does not clear it. `CRITIC_VERSION` bumps to `2`.
+- **0.152.0**: `baker ads linkedin campaigns url-params <ad-set-id>` stages an ad set's URL tracking parameters (LinkedIn's `adTrackingParameters`) — `--param key=value` for fixed values (repeatable or `&`-joined), `--dynamic key=PLACEHOLDER` for values LinkedIn fills in per ad (`CAMPAIGN_NAME`, `CREATIVE_ID`, …), `--clear` to remove them. LinkedIn appends these to the landing URL of every ad in the ad set, including ads already running, so this replaces stamping the same UTM onto each ad's `--landing-url` — which missed later ads and double-appended keys the ad set already set. Account-level parameters remain UI-only (LinkedIn exposes no API for them).
 
 ## Publishing
 

package/dist/cli.js

@@ -1297,6 +1297,15 @@ var LINKEDIN_LIMITS = {
   campaign: {
     nameMax: 255
   },
+  /**
+   * LinkedIn documents no ceiling on URL tracking parameters; these are our own
+   * guards against a payload that would build an unusable landing URL.
+   */
+  trackingParams: {
+    keyMax: 100,
+    valueMax: 500,
+    parametersMax: 20
+  },
   creative: {
     commentarySoftMax: 600,
     // feed truncates with "…see more" beyond this
@@ -1435,6 +1444,17 @@ var CONVERSION_TYPES = [
 ];
 var CONVERSION_METHODS = ["INSIGHT_TAG", "CONVERSIONS_API"];
 var ATTRIBUTION_TYPES = ["LAST_TOUCH_BY_CAMPAIGN", "LAST_TOUCH_BY_CONVERSION"];
+var TRACKING_PARAM_DYNAMIC_VALUES = [
+  "ACCOUNT_ID",
+  "ACCOUNT_NAME",
+  "CAMPAIGN_GROUP_ID",
+  "CAMPAIGN_GROUP_NAME",
+  "CAMPAIGN_ID",
+  "CAMPAIGN_NAME",
+  "CREATIVE_ID",
+  "CREATIVE_NAME"
+];
+var TRACKING_PARAM_KEY_REGEX = /^[A-Za-z0-9_.-]+$/;
 var CURRENCY_MINIMUMS = {
   USD: { dailyBudgetMin: 10, unitCostMin: 2 },
   EUR: { dailyBudgetMin: 10, unitCostMin: 2 },
@@ -1592,6 +1612,35 @@ var campaignUpdateSchema = z3.object({
   }
   validateCampaignBudgets(p, ctx, { requireBudget: false });
 });
+var trackingParamKeySchema = z3.string().min(1).max(LINKEDIN_LIMITS.trackingParams.keyMax).regex(TRACKING_PARAM_KEY_REGEX, "tracking parameter keys may only use letters, digits, _ . and -");
+var trackingParamsSetSchema = z3.object({
+  dynamicValueParameters: z3.record(trackingParamKeySchema, z3.enum(TRACKING_PARAM_DYNAMIC_VALUES)).optional(),
+  customValueParameters: z3.record(trackingParamKeySchema, z3.string().min(1).max(LINKEDIN_LIMITS.trackingParams.valueMax)).optional()
+}).superRefine((p, ctx) => {
+  if (!p.dynamicValueParameters && !p.customValueParameters) {
+    ctx.addIssue({
+      code: "custom",
+      message: "set at least one parameter \u2014 pass --param key=value or --dynamic key=PLACEHOLDER, or --clear (both maps as {}) to remove the ad set's tracking parameters"
+    });
+  }
+  const both = Object.keys(p.dynamicValueParameters ?? {}).filter(
+    (key) => p.customValueParameters?.[key] !== void 0
+  );
+  if (both.length > 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["customValueParameters"],
+      message: `${both.join(", ")} is set as both a dynamic and a fixed parameter \u2014 LinkedIn appends each key once, so keep only one`
+    });
+  }
+  const count = Object.keys(p.dynamicValueParameters ?? {}).length + Object.keys(p.customValueParameters ?? {}).length;
+  if (count > LINKEDIN_LIMITS.trackingParams.parametersMax) {
+    ctx.addIssue({
+      code: "custom",
+      message: `${count} parameters \u2014 keep it under ${LINKEDIN_LIMITS.trackingParams.parametersMax}`
+    });
+  }
+});
 var commentarySchema = z3.string().min(1).max(LINKEDIN_LIMITS.creative.commentaryHardMax);
 var headlineSchema = z3.string().min(1).max(LINKEDIN_LIMITS.creative.headlineMax);
 var httpsUrlSchema = z3.string().url().refine((u) => u.startsWith("https://"), "landing pages must be https");
@@ -1970,6 +2019,7 @@ var LINKEDIN_DRAFT_OP_KINDS = [
   "campaignGroup.update",
   "campaign.create",
   "campaign.update",
+  "trackingParams.set",
   "creative.create",
   "creative.update",
   "audience.create",
@@ -1993,6 +2043,7 @@ var linkedinDraftOpInputSchema = z3.discriminatedUnion("kind", [
   updateOp("campaignGroup.update", campaignGroupUpdateSchema),
   createOp("campaign.create", campaignCreateSchema),
   updateOp("campaign.update", campaignUpdateSchema),
+  updateOp("trackingParams.set", trackingParamsSetSchema),
   createOp("creative.create", creativeCreateSchema),
   updateOp("creative.update", creativeUpdateSchema),
   createOp("audience.create", audienceCreateSchema),
@@ -8490,6 +8541,26 @@ registerSchema({
     file: { type: "string", description: "JSON file with fields to change", required: false }
   }
 });
+registerSchema({
+  command: "ads.linkedin.campaigns.url-params",
+  description: "Start here for UTMs: stage the URL tracking parameters on an ad set. LinkedIn appends them to the link of EVERY ad in the ad set, including ads already running, so this is the level to set campaign-wide UTMs at \u2014 editing each ad's landing URL instead risks the same key landing twice. --param takes fixed values (repeatable or &-joined); --dynamic takes a value LinkedIn fills in per ad (ACCOUNT_ID, ACCOUNT_NAME, CAMPAIGN_GROUP_ID, CAMPAIGN_GROUP_NAME, CAMPAIGN_ID, CAMPAIGN_NAME, CREATIVE_ID, CREATIVE_NAME). Applies on chat publish; message and conversation ads are unaffected.",
+  args: {
+    id: { type: "positional", description: "Ad set (campaign) id or URN", required: true },
+    ...writeAccountArgs,
+    param: {
+      type: "string",
+      description: 'Fixed key=value, repeatable or &-joined \u2014 e.g. "utm_source=linkedin&utm_medium=paid-social"',
+      required: false
+    },
+    dynamic: {
+      type: "string",
+      description: "key=PLACEHOLDER filled in per ad, repeatable \u2014 e.g. utm_campaign=CAMPAIGN_NAME",
+      required: false
+    },
+    clear: { type: "boolean", description: "Remove every tracking parameter from this ad set", required: false },
+    file: { type: "string", description: "JSON payload file; flags override file keys", required: false }
+  }
+});
 var statusSugarArgs = {
   id: { type: "positional", description: "Entity id or URN", required: true },
   ...writeAccountArgs
@@ -10014,6 +10085,88 @@ Example: baker ads linkedin ${entity} ${name} 123456`
     }
   });
 }
+function trackingPairs(value, flag) {
+  const raw = value === void 0 ? [] : Array.isArray(value) ? value : [value];
+  return raw.flatMap(
+    (entry) => String(entry).split("&").filter((pair) => pair.length > 0).map((pair) => {
+      const at = pair.indexOf("=");
+      if (at < 1 || at === pair.length - 1) {
+        failWriteValidation2(`${flag} expects key=value pairs \u2014 got "${pair}"`);
+      }
+      return [pair.slice(0, at).trim(), pair.slice(at + 1).trim()];
+    })
+  );
+}
+function asDynamicValue(value) {
+  const bare = value.replace(/^\{+|\}+$/g, "").toUpperCase();
+  return TRACKING_PARAM_DYNAMIC_VALUES.includes(bare) ? bare : void 0;
+}
+function trackingParamsPayload(args) {
+  if (args.clear) {
+    return { dynamicValueParameters: {}, customValueParameters: {} };
+  }
+  const customValueParameters = {};
+  for (const [key, value] of trackingPairs(args.param, "--param")) {
+    if (asDynamicValue(value)) {
+      failWriteValidation2(
+        `--param ${key}=${value} names a value LinkedIn fills in per ad \u2014 pass it as --dynamic ${key}=${value.replace(/^\{+|\}+$/g, "").toUpperCase()}`
+      );
+    }
+    customValueParameters[key] = value;
+  }
+  const dynamicValueParameters = {};
+  for (const [key, value] of trackingPairs(args.dynamic, "--dynamic")) {
+    const resolved = asDynamicValue(value);
+    if (!resolved) {
+      failWriteValidation2(
+        `--dynamic ${key}=${value} is not a value LinkedIn can fill in \u2014 use one of ${TRACKING_PARAM_DYNAMIC_VALUES.join(", ")}, or pass a fixed value with --param`
+      );
+    }
+    dynamicValueParameters[key] = resolved;
+  }
+  return mergePayload2(loadJsonFileArg2(args.file), {
+    customValueParameters: Object.keys(customValueParameters).length > 0 ? customValueParameters : void 0,
+    dynamicValueParameters: Object.keys(dynamicValueParameters).length > 0 ? dynamicValueParameters : void 0
+  });
+}
+var campaignsUrlParamsCommand = defineCommand37({
+  meta: {
+    name: "url-params",
+    description: `Stage the URL tracking parameters on an ad set \u2014 LinkedIn appends them to the link of EVERY ad in it, including ads already running. ${STAGED_NOTE}
+
+Start here: set UTMs at this level, not per ad. A per-ad landing URL is only for a genuinely different destination \u2014 LinkedIn appends the ad set's parameters on top of whatever the ad's own URL carries, so the same key set in both places lands twice.
+
+Values LinkedIn fills in per ad (--dynamic): ACCOUNT_ID, ACCOUNT_NAME, CAMPAIGN_GROUP_ID, CAMPAIGN_GROUP_NAME, CAMPAIGN_ID, CAMPAIGN_NAME, CREATIVE_ID, CREATIVE_NAME.
+
+Examples:
+  baker ads linkedin campaigns url-params 123456 --param "utm_source=linkedin&utm_medium=paid-social" --dynamic utm_campaign=CAMPAIGN_NAME --dynamic utm_content=CREATIVE_ID
+  baker ads linkedin campaigns url-params 123456 --param utm_agency=baker
+  baker ads linkedin campaigns url-params 123456 --clear`
+  },
+  args: {
+    id: { type: "positional", description: "Ad set (campaign) id or URN", required: true },
+    ...accountArgs,
+    param: {
+      type: "string",
+      description: 'Fixed key=value, repeatable or &-joined (e.g. --param "utm_source=linkedin&utm_medium=paid")'
+    },
+    dynamic: {
+      type: "string",
+      description: "key=PLACEHOLDER LinkedIn fills in per ad, repeatable (e.g. --dynamic utm_campaign=CAMPAIGN_NAME)"
+    },
+    clear: { type: "boolean", description: "Remove every tracking parameter from this ad set" },
+    file: { type: "string", description: "JSON file with the full payload; flags override file keys" }
+  },
+  run: async ({ args }) => {
+    const accountId = bareAccountId(args);
+    await stageOp({
+      kind: "trackingParams.set",
+      accountId,
+      target: requireTarget2(args, "ad set"),
+      payload: trackingParamsPayload(args)
+    });
+  }
+});
 var campaignsPauseCommand = statusSugarCommand("campaigns", "campaign.update", "pause");
 var campaignsResumeCommand = statusSugarCommand("campaigns", "campaign.update", "resume");
 var campaignsArchiveCommand = statusSugarCommand("campaigns", "campaign.update", "archive");
@@ -10546,7 +10699,8 @@ Examples:
   baker ads linkedin campaigns --account-id 503001492
   baker ads linkedin campaigns --account-id 503001492 --all-statuses --output csv
   baker ads linkedin campaigns update 123456 --daily-budget 100 --currency EUR
-  baker ads linkedin campaigns pause 123456`
+  baker ads linkedin campaigns pause 123456
+  baker ads linkedin campaigns url-params 123456 --param utm_source=linkedin   \u2014 UTMs for every ad in the ad set`
   },
   subCommands: {
     create: campaignsCreateCommand,
@@ -10554,7 +10708,8 @@ Examples:
     pause: campaignsPauseCommand,
     resume: campaignsResumeCommand,
     archive: campaignsArchiveCommand,
-    duplicate: campaignsDuplicateCommand
+    duplicate: campaignsDuplicateCommand,
+    "url-params": campaignsUrlParamsCommand
   },
   args: {
     "account-id": { type: "string", description: "Numeric account ID or urn:li:sponsoredAccount:N" },