@koda-sl/baker-cli 0.149.0 → 0.150.0-dev.04484bc24

package/dist/cli.js

@@ -36,7 +36,7 @@ import {
   toModelSafeImage,
   ulid,
   validateCanvasDeep
-} from "./chunk-OO5BDH3J.js";
+} from "./chunk-JBDSJZBZ.js";
 import {
   csvOrJson,
   daysAgoIso,
@@ -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 both maps as {} to clear the ad set's tracking parameters instead"
+    });
+  }
+  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),
@@ -8305,6 +8356,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
@@ -9829,6 +9900,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");
@@ -10361,7 +10514,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,
@@ -10369,7 +10523,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" },