@adkit/cli 1.12.20 → 1.12.22

package/dist/cli.js

@@ -1833,9 +1833,11 @@ var SEARCH_TERMS_FLAGS = ["campaign", "ad-group", "keyword", "keyword-match-type
 var PLACEMENT_REPORT_FLAGS = ["campaign", "ad-group", "period", "from", "to", "sort", "limit", "raw"];
 var GOOGLE_RESULTS_FLAGS = ["campaign", "ad-group", "period", "from", "to", "sort", "limit", "status", "breakdown", "fields", "conversion-actions", "raw"];
 var GOOGLE_KEYWORD_RESULTS_FLAGS = ["campaign", "ad-group", "period", "from", "to", "sort", "limit", "status", "fields", "raw"];
+var CONVERSION_UPLOAD_FLAGS = ["conversion", "gclid", "gbraid", "wbraid", "occurred-at", "value", "currency", "order-id", "conversion-environment", "validate-only", "job-id"];
 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 NUMBER_FLAG_PATTERN = /^(?:\d+|\d+\.\d+|\.\d+)(?:e[+-]?\d+)?$/iu;
 function generateCampaignName2() {
   return `campaign ${getDateStamp()}`;
 }
@@ -1961,6 +1963,51 @@ function buildGoogleMediaUploadSource(flags) {
   if (name) source.name = name;
   return source;
 }
+function buildGoogleClickConversionUploadInput(flags) {
+  const conversionId = requireSingleFlagValue(flags, "conversion", {
+    missingHint: 'Run: adkit manage google conversions upload --conversion 123 --gclid <gclid> --occurred-at "2026-06-24 13:45:00+00:00" --value 120 --currency USD --validate-only'
+  });
+  const occurredAt = requireSingleFlagValue(flags, "occurred-at", {
+    missingHint: 'Google offline uploads require a timestamp with timezone, e.g. "2026-06-24 13:45:00+00:00"'
+  });
+  const value = readNumberFlag(flags, "value", "Google offline uploads require --value <number>");
+  const currency = requireSingleFlagValue(flags, "currency", {
+    missingHint: "Google offline uploads require --currency <ISO code>, e.g. USD"
+  });
+  const conversion = {
+    conversionId,
+    occurredAt,
+    value,
+    currency
+  };
+  const gclid = readSingleFlagValue(flags, "gclid", "Use one --gclid value");
+  const gbraid = readSingleFlagValue(flags, "gbraid", "Use one --gbraid value");
+  const wbraid = readSingleFlagValue(flags, "wbraid", "Use one --wbraid value");
+  const orderId = readSingleFlagValue(flags, "order-id", "Use one --order-id value");
+  const conversionEnvironment = readSingleFlagValue(flags, "conversion-environment", "Use one --conversion-environment value");
+  if (gclid) conversion.gclid = gclid;
+  if (gbraid) conversion.gbraid = gbraid;
+  if (wbraid) conversion.wbraid = wbraid;
+  if (orderId) conversion.orderId = orderId;
+  if (conversionEnvironment) conversion.conversionEnvironment = conversionEnvironment;
+  return conversion;
+}
+function readNumberFlag(flags, key, hint) {
+  const rawValue = requireSingleFlagValue(flags, key, { missingHint: hint });
+  const trimmedValue = rawValue.trim();
+  const value = NUMBER_FLAG_PATTERN.test(trimmedValue) ? Number(trimmedValue) : Number.NaN;
+  if (!Number.isFinite(value) || value < 0) throw new CliError("INVALID_VALUE", `Invalid number for --${key}: ${rawValue}`, hint);
+  return value;
+}
+function applyGoogleClickConversionUploadOptions(body, flags) {
+  if (flags["validate-only"] === true) body.validateOnly = true;
+  const rawJobId = readSingleFlagValue(flags, "job-id", "Use one --job-id value");
+  if (!rawJobId) return;
+  const trimmedJobId = rawJobId.trim();
+  const jobId = /^\d+$/u.test(trimmedJobId) ? Number(trimmedJobId) : Number.NaN;
+  if (!Number.isInteger(jobId) || jobId >= 2147483648) throw new CliError("INVALID_VALUE", `Invalid integer for --job-id: ${rawJobId}`, "Use a non-negative integer below 2147483648");
+  body.jobId = jobId;
+}
 function resolveAssetScope(flags) {
   const scopeType = typeof flags.scope === "string" ? flags.scope : void 0;
   if (scopeType !== "account" && scopeType !== "campaign" && scopeType !== "ad-group") throw new CliError("MISSING_FLAG", "Missing required flag: `--scope`", "Use --scope account|campaign|ad-group");
@@ -2301,6 +2348,24 @@ async function uploadMedia2(client, _args, flags) {
   const path3 = `/manage/google/media${query}`;
   return client.post(path3, body);
 }
+async function uploadGoogleConversions(client, _args, flags) {
+  validateFlags(flags, CONVERSION_UPLOAD_FLAGS, "manage google conversions upload");
+  if (flags.publish === true) throw new CliError("INVALID_VALUE", "`--publish` is not used for conversion uploads", "Use --validate-only for a dry run; omit it to upload directly.");
+  if (typeof flags.data === "string") {
+    const rawBody = parseDataFlag(flags, 'Use { "conversions": [...] } for Google conversion upload');
+    const accountId2 = resolveGoogleAccountId(rawBody, flags);
+    const body2 = removeQueryOnlyBodyKeys(rawBody, ["accountId"]);
+    const query2 = queryString({ accountId: accountId2 });
+    const path4 = `/manage/google/conversions/upload${query2}`;
+    return client.post(path4, body2);
+  }
+  const body = { conversions: [buildGoogleClickConversionUploadInput(flags)] };
+  applyGoogleClickConversionUploadOptions(body, flags);
+  const accountId = typeof flags.account === "string" ? flags.account : void 0;
+  const query = queryString({ accountId });
+  const path3 = `/manage/google/conversions/upload${query}`;
+  return client.post(path3, body);
+}
 async function listGoogleCampaigns(client, _args, flags) {
   validateFlags(flags, CAMPAIGN_LIST_FLAGS, "manage google campaigns list");
   const qs = buildGoogleListQuery(flags);
@@ -2843,7 +2908,7 @@ function readTikTokPlatformOverridesFlag(flags) {
 function isCliTikTokPlatformOverrides(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
-function readNumberFlag(flags, key) {
+function readNumberFlag2(flags, key) {
   const value = flags[key];
   if (value === void 0) return void 0;
   if (typeof value !== "string") throw new CliError("INVALID_VALUE", `Use one --${key} value`, `Run: adkit manage tiktok --help`);
@@ -2852,8 +2917,8 @@ function readNumberFlag(flags, key) {
   return parsed;
 }
 function buildTikTokBudget(flags) {
-  const daily = readNumberFlag(flags, "budget-daily");
-  const lifetime = readNumberFlag(flags, "budget-lifetime");
+  const daily = readNumberFlag2(flags, "budget-daily");
+  const lifetime = readNumberFlag2(flags, "budget-lifetime");
   if (daily === void 0 && lifetime === void 0) return void 0;
   if (daily !== void 0 && lifetime !== void 0) throw new CliError("INVALID_VALUE", "Use either --budget-daily or --budget-lifetime", "TikTok accepts one budget mode per campaign/ad group");
   return daily !== void 0 ? { daily } : { lifetime };
@@ -2898,7 +2963,7 @@ function buildTikTokAdGroupPayload(flags, mode) {
   if (typeof flags["start-date"] === "string") payload.startDate = flags["start-date"];
   if (typeof flags["end-date"] === "string") payload.endDate = flags["end-date"];
   if (typeof flags.pacing === "string") payload.pacing = flags.pacing;
-  const bidAmount = readNumberFlag(flags, "bid-amount");
+  const bidAmount = readNumberFlag2(flags, "bid-amount");
   if (bidAmount !== void 0) payload.bidAmount = bidAmount;
   if (typeof flags["event-type"] === "string") {
     payload.conversion = {
@@ -4753,7 +4818,7 @@ Notes:
   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.
   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 action (publish is blocked without one). Non-retail only. Build it with --data.
+  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.
   For spend/clicks/conversions: adkit manage google results
 
@@ -5302,6 +5367,33 @@ Notes:
   Upload returns assets[].id and assets[].resourceName. Use either value in Display ad media[].id.
   Display media roles: marketing_image, square_marketing_image, logo, square_logo.
   Videos are not supported in Google Display v1; upload images only.`;
+var GOOGLE_CONVERSIONS_HELP = `adkit manage google conversions \u2014 Google Ads conversion tracking
+
+  upload              Upload offline click conversion events
+
+Flags (upload):
+  --conversion <id>   Google conversion ID (platformId), must be type upload_clicks
+  --gclid <id>        Google click ID
+  --gbraid <id>       GBRAID click parameter
+  --wbraid <id>       WBRAID click parameter
+  --occurred-at <ts>  Conversion timestamp with timezone, e.g. "2026-06-24 13:45:00+00:00"
+  --value <n>         Conversion value
+  --currency <code>   ISO currency code, e.g. USD
+  --order-id <id>     Optional order ID for dedupe/adjustments
+  --conversion-environment <web|app>
+  --validate-only     Validate without importing conversions
+  --job-id <n>        Optional Google diagnostics job id
+  --account <id>      Optional if one Google Ads account is connected
+  --data <json>       Batch body: {"conversions":[...],"validateOnly":true}
+
+Examples:
+  adkit manage google conversions upload --conversion 123 --gclid EAIaIQob... --occurred-at "2026-06-24 13:45:00+00:00" --value 120 --currency USD --validate-only
+  adkit manage google conversions upload --data '{"conversions":[{"conversionId":"123","gclid":"EAIaIQob...","occurredAt":"2026-06-24 13:45:00+00:00","value":120,"currency":"USD"}],"validateOnly":true}' --account 1234567890
+
+Notes:
+  Upload sends events directly to Google; it is not a draft flow.
+  Use --validate-only before a real upload when testing a new CRM/backend export.
+  Real uploads require publish access.`;
 var META_RESEARCH_HELP = `adkit manage meta research \u2014 Meta Ads research tools
 
   interests <query>   Search targeting interests (returns IDs for ad set targeting)
@@ -5362,6 +5454,7 @@ Examples:
   "google change-history": GOOGLE_CHANGE_HISTORY_HELP,
   "google research": GOOGLE_RESEARCH_HELP,
   "google media": GOOGLE_MEDIA_HELP,
+  "google conversions": GOOGLE_CONVERSIONS_HELP,
   "tiktok accounts": `adkit manage tiktok accounts \u2014 TikTok Ads accounts
 
   list                List connected TikTok advertisers
@@ -5537,7 +5630,7 @@ Examples:
 
   Bypasses normalized AdKit entity validation, but still runs account and safety checks.
   GET requests execute immediately. POST/PATCH/DELETE create drafts by default; add --publish to execute mutating requests immediately.
-  Must be enabled in project settings first.
+  Must be enabled in Agent Permissions first.
   Use this for unsupported native platform resources/workflows. Use platformOverrides instead when you only need raw fields on a supported normalized resource.
   Use the selected platform's official endpoint paths, field names, enum values, and resource shapes. Do not translate normalized AdKit field names into raw API payloads by guessing.
 
@@ -5604,6 +5697,7 @@ Entity groups:
   ads                 Manage responsive search and Display ads
   keywords            Manage keywords and negatives \u2014 config only, not metrics
   keywords negative-lists   Shared negative keyword lists (create, attach to campaigns)
+  conversions         Manage conversion tracking and upload offline conversions
   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
@@ -5615,7 +5709,8 @@ ${FLAG.account}
 ${FLAG.publish}
 ${FLAG.data}
 
-Mutations are draft-first by default. Use --publish to publish immediately.
+Config mutations are draft-first by default. Use --publish to publish immediately.
+Conversion uploads send events directly; use --validate-only for a dry run.
 ${rawPlatformCommandLine("google")}
 Display path: research topics/interests, upload images with google media, create campaigns --campaign-type display, create ad-groups with targeting, then create ads with type:"responsive_display".
 Google Display Ads is in beta \u2014 some first-class normalized Display features may not be available yet.
@@ -5901,6 +5996,7 @@ var HELP_FULL = {
   "google change-history": GOOGLE_CHANGE_HISTORY_HELP,
   "google research": GOOGLE_RESEARCH_HELP,
   "google media": GOOGLE_MEDIA_HELP,
+  "google conversions": GOOGLE_CONVERSIONS_HELP,
   "meta research": META_RESEARCH_HELP,
   "studio generate": STUDIO_GENERATE_HELP_FULL,
   "library advertisers": `adkit library advertisers \u2014 Browse, inspect, and discover advertisers
@@ -6817,7 +6913,7 @@ async function main() {
               case "list":
               case void 0:
                 data = await listAccounts(client, restArgs, flags);
-                emptyHint = "No Meta ad accounts connected. Run `adkit setup manage` or connect via https://app.adkit.so/settings/integrations";
+                emptyHint = "No Meta ad accounts connected. Run `adkit setup manage` or connect a workspace login via https://app.adkit.so/dashboard/settings/workspace-integrations";
                 break;
               case "connect":
                 data = await connectAccount(client, restArgs, flags);
@@ -6988,7 +7084,7 @@ async function main() {
               case "list":
               case void 0:
                 data = await listAccounts2(client, restArgs, flags);
-                emptyHint = "No Google Ads accounts connected. Run `adkit setup manage` or connect via https://app.adkit.so/settings/integrations";
+                emptyHint = "No Google Ads accounts connected. Run `adkit setup manage` or connect a workspace login via https://app.adkit.so/dashboard/settings/workspace-integrations";
                 break;
               case "available":
                 data = await listAvailable(client, restArgs, flags);
@@ -7220,6 +7316,20 @@ async function main() {
             else data = await listGoogleResults(client, restArgs, flags);
             break;
           }
+          case "conversions": {
+            if (!action || flags.help) {
+              showHelp("google conversions", flags.help === "full");
+              process.exit(0);
+            }
+            switch (action) {
+              case "upload":
+                data = await uploadGoogleConversions(client, restArgs, flags);
+                break;
+              default:
+                throw new CliError("UNKNOWN_COMMAND", `Unknown action: google conversions ${action}`, "Available: upload");
+            }
+            break;
+          }
           case "change-history": {
             if (action && action !== "list") throw new CliError("UNKNOWN_COMMAND", `Unknown action: google change-history ${action}`, "Available: list");
             data = await listGoogleChangeHistory(client, restArgs, flags);
@@ -7246,7 +7356,7 @@ async function main() {
             break;
           }
           default:
-            throw new CliError("UNKNOWN_COMMAND", `Unknown entity: google ${entity}`, "Available: accounts, assets, media, campaigns, ad-groups, ads, keywords, 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");
         }
       } else if (platform2 === "tiktok") {
         switch (entity) {
@@ -7255,7 +7365,7 @@ async function main() {
               case "list":
               case void 0:
                 data = await listTikTokAccounts(client, restArgs, flags);
-                emptyHint = "No TikTok Ads accounts connected. Run `adkit setup manage` or connect via https://app.adkit.so/settings/integrations";
+                emptyHint = "No TikTok Ads accounts connected. Run `adkit setup manage` or connect a workspace login via https://app.adkit.so/dashboard/settings/workspace-integrations";
                 break;
               case "available":
                 data = await listTikTokAvailableAccounts(client, restArgs, flags);
@@ -7372,7 +7482,7 @@ async function main() {
               case "list":
               case void 0:
                 data = await listRedditAccounts(client, restArgs, flags);
-                emptyHint = "No Reddit Ads accounts connected. Run `adkit setup manage` or connect via https://app.adkit.so/settings/integrations";
+                emptyHint = "No Reddit Ads accounts connected. Run `adkit setup manage` or connect a workspace login via https://app.adkit.so/dashboard/settings/workspace-integrations";
                 break;
               case "available":
                 data = await listRedditAvailableAccounts(client, restArgs, flags);

package/package.json

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