@koda-sl/baker-cli 0.386.0-dev.8b1f99042 → 0.386.0-dev.d6e55699d

package/dist/chunk-W4W4ZRBP.js

@@ -0,0 +1,191 @@
+import {
+  hintLines,
+  splitHints
+} from "./chunk-D5FY4FAK.js";
+import {
+  isNotConnectedError,
+  writeJsonEnvelope
+} from "./chunk-BVM5IRZW.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-HREWXNTO.js";
+import {
+  requireChatId,
+  resolveChatId
+} from "./chunk-O6QKCJE4.js";
+
+// src/commands/ga4/shared.ts
+import { readFileSync } from "fs";
+function failValidation(message) {
+  writeJsonEnvelope({ ok: false, error: { code: "VALIDATION_ERROR", message } });
+  process.exit(1);
+}
+function requireTarget(args, entity) {
+  const positional = Array.isArray(args._) ? args._[0] : void 0;
+  const target = args.id ?? args.target ?? positional;
+  if (typeof target !== "string" || target.length === 0) {
+    failValidation(`pass the ${entity} id as the positional argument`);
+  }
+  return target;
+}
+function readJsonSource(args, flag) {
+  const inline = args[flag];
+  const file = args.file;
+  const raw = typeof file === "string" && file.length > 0 ? readFileSync(file, "utf8") : typeof inline === "string" && inline.length > 0 ? inline : void 0;
+  if (raw === void 0) {
+    failValidation(`pass --${flag} with inline JSON or --file with a path to a JSON file`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return failValidation(`--${flag} is not valid JSON`);
+  }
+}
+function asObject(value, flag, index) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    failValidation(
+      index === void 0 ? `--${flag} must be a JSON object` : `--${flag}[${index}] must be a JSON object`
+    );
+  }
+  return value;
+}
+function loadJsonArg(args, flag = "json") {
+  return asObject(readJsonSource(args, flag), flag);
+}
+function loadJsonPayloads(args) {
+  const parsed = readJsonSource(args, "json");
+  if (!Array.isArray(parsed)) {
+    return [asObject(parsed, "json")];
+  }
+  if (parsed.length === 0) {
+    failValidation("--json is an empty list \u2014 pass at least one definition");
+  }
+  return parsed.map((entry, index) => asObject(entry, "json", index));
+}
+var RETRYABLE_CODES = /* @__PURE__ */ new Set(["RATE_LIMITED", "UNAVAILABLE", "INTERNAL_ERROR", "NETWORK_ERROR", "TIMEOUT"]);
+function handleError(err) {
+  if (err instanceof ApiError) {
+    const readOnly = err.code === "FORBIDDEN" && /read the property but not change it/i.test(err.message);
+    writeJsonEnvelope({
+      ok: false,
+      error: {
+        code: err.code,
+        message: err.message,
+        ...readOnly ? {
+          fix: {
+            action: "reconnect",
+            explanation: "The Google Analytics connection is read-only. Ask the user to reconnect Google Analytics \u2014 in the dashboard, Brain \u2192 Integrations \u2192 Platforms \u2192 Google Analytics \u2014 which grants the permission to change the property. Reporting (`baker ga4 query`, `baker ga4 audit`) keeps working meanwhile, so carry on with the rest of the job and tell them what you will set up once they have reconnected. Don't claim anything was configured."
+          }
+        } : err.code === "UNAUTHORIZED" || err.code === "FORBIDDEN" && isNotConnectedError(err.code, err.message) ? {
+          fix: {
+            action: "request_connection",
+            explanation: 'Google Analytics is not connected for this company yet, or no property has been picked. Don\'t send the user to Settings \u2014 call the `request_connection` tool with { platform: "google-analytics", reason } and they connect and pick their property from inside the chat. If the `request_connection` call fails, say so plainly and give the exact route: dashboard \u2192 Brain \u2192 Integrations \u2192 Platforms \u2192 Google Analytics. Then carry on with the rest of the task.'
+          }
+        } : {},
+        retryable: RETRYABLE_CODES.has(err.code)
+      }
+    });
+    process.exit(1);
+  }
+  writeJsonEnvelope({ ok: false, error: { code: "NETWORK_ERROR", message: "Unexpected error", retryable: true } });
+  process.exit(1);
+}
+var STAGE_HINTS = [
+  "Staged only \u2014 nothing has changed in Google Analytics yet. These apply when the chat completes, and an applied change takes effect on the property immediately: there is no version to publish afterwards and no undo. Say the changes are ready and take effect when the user completes the chat \u2014 not that they are done already."
+];
+var WARNING_HINT = "Read the warnings above before telling the user this is ready.";
+async function stageOp(op) {
+  const chatId = requireChatId();
+  try {
+    const { data, hints } = splitHints(await apiPost("/api/ga4/draft/stage", { chatId, op }));
+    writeJsonEnvelope({
+      ok: true,
+      data,
+      hints: [...hints, ...STAGE_HINTS, ...data.warnings.length > 0 ? [WARNING_HINT] : []]
+    });
+  } catch (err) {
+    handleError(err);
+  }
+}
+async function stageOps(ops) {
+  const [only] = ops;
+  if (ops.length === 1 && only) {
+    await stageOp(only);
+    return;
+  }
+  const chatId = requireChatId();
+  try {
+    const { data, hints } = splitHints(
+      await apiPost("/api/ga4/draft/stage-batch", { chatId, ops })
+    );
+    writeJsonEnvelope({
+      ok: true,
+      data,
+      hints: [...hints, ...STAGE_HINTS, ...data.ops.some((op) => op.warnings.length > 0) ? [WARNING_HINT] : []]
+    });
+  } catch (err) {
+    handleError(err);
+  }
+}
+async function draftAction(path, body, chat) {
+  const chatId = resolveChatId(chat);
+  try {
+    const { data, hints } = splitHints(await apiPost(path, { chatId, ...body }));
+    writeJsonEnvelope({ ok: true, data, ...hints.length > 0 ? { hints } : {} });
+    return data;
+  } catch (err) {
+    handleError(err);
+  }
+}
+function renderDraft(response) {
+  if (response.count === 0) {
+    return "No Google Analytics changes staged on this chat.";
+  }
+  const lines = [
+    response.status === "discarded" ? `${response.count} Google Analytics change(s) discarded with their chat \u2014 none will apply` : `${response.count} staged Google Analytics change(s)`,
+    ...response.ops.map((op) => {
+      const status = op.result ? ` [${op.result.status}]` : "";
+      return `  ${op.ref}  ${op.summary}${status}`;
+    })
+  ];
+  if (response.status === "applied") {
+    const failed = response.ops.filter((op) => op.result?.status !== "applied");
+    lines.push(
+      "",
+      failed.length === 0 ? "All applied \u2014 these are in effect on the property now." : `${failed.length} of ${response.count} did not apply. The rest are in effect on the property.`
+    );
+  }
+  if (response.publishError) {
+    lines.push("", response.publishError);
+  }
+  return lines.join("\n");
+}
+async function draftList(json, chat) {
+  const chatId = resolveChatId(chat);
+  try {
+    const response = await apiPost("/api/ga4/draft", { chatId });
+    const { data, hints } = splitHints(response);
+    if (json) {
+      writeJsonEnvelope({ ok: true, data, ...hints.length > 0 ? { hints } : {} });
+      return;
+    }
+    process.stdout.write(`${renderDraft(data)}${hintLines(response)}
+`);
+  } catch (err) {
+    handleError(err);
+  }
+}
+
+export {
+  failValidation,
+  requireTarget,
+  loadJsonArg,
+  loadJsonPayloads,
+  handleError,
+  stageOp,
+  stageOps,
+  draftAction,
+  draftList
+};
+//# sourceMappingURL=chunk-W4W4ZRBP.js.map

package/dist/chunk-W4W4ZRBP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/ga4/shared.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport type { Ga4DraftListResponse, Ga4DraftStageBatchResponse, Ga4DraftStageResponse } from \"@baker/api/ga4\";\nimport { ApiError, apiPost } from \"../../client.ts\";\nimport { requireChatId, resolveChatId } from \"../../env.ts\";\nimport { isNotConnectedError } from \"../../error-handler.ts\";\nimport { hintLines, splitHints } from \"../ads/hints.ts\";\nimport { writeJsonEnvelope } from \"../ads/output.ts\";\n\n/**\n * Shared plumbing for the staged Google Analytics write commands. These NEVER\n * change the property directly: each stages a change onto this chat's draft, the\n * user reviews the whole set in the Analytics tab, and it applies when the chat\n * completes.\n */\n\nexport function failValidation(message: string): never {\n  writeJsonEnvelope({ ok: false, error: { code: \"VALIDATION_ERROR\", message } });\n  process.exit(1);\n}\n\nexport function requireTarget(args: Record<string, unknown>, entity: string): string {\n  const positional = Array.isArray(args._) ? args._[0] : undefined;\n  const target = args.id ?? args.target ?? positional;\n  if (typeof target !== \"string\" || target.length === 0) {\n    failValidation(`pass the ${entity} id as the positional argument`);\n  }\n  return target;\n}\n\nfunction readJsonSource(args: Record<string, unknown>, flag: \"patch\" | \"json\"): unknown {\n  const inline = args[flag];\n  const file = args.file;\n  const raw =\n    typeof file === \"string\" && file.length > 0\n      ? readFileSync(file, \"utf8\")\n      : typeof inline === \"string\" && inline.length > 0\n        ? inline\n        : undefined;\n  if (raw === undefined) {\n    failValidation(`pass --${flag} with inline JSON or --file with a path to a JSON file`);\n  }\n  try {\n    return JSON.parse(raw) as unknown;\n  } catch {\n    return failValidation(`--${flag} is not valid JSON`);\n  }\n}\n\nfunction asObject(value: unknown, flag: string, index?: number): Record<string, unknown> {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) {\n    failValidation(\n      index === undefined ? `--${flag} must be a JSON object` : `--${flag}[${index}] must be a JSON object`,\n    );\n  }\n  return value as Record<string, unknown>;\n}\n\n/** `--json '<inline>'` or `--file <path>` → a parsed object. */\nexport function loadJsonArg(args: Record<string, unknown>, flag: \"patch\" | \"json\" = \"json\"): Record<string, unknown> {\n  return asObject(readJsonSource(args, flag), flag);\n}\n\n/**\n * The same, but a JSON **array** is allowed and means \"stage all of these\n * together\".\n *\n * This is the only way to keep a bulk job cheap. Every stage call reads the\n * whole property first — the property, its data streams, its key events, its\n * custom definitions and its retention window — because that read is what the\n * duplicate and immutability refusals are derived from. One call per definition\n * therefore multiplies a routine \"make these eight parameters reportable\" into\n * roughly fifty Admin API reads against a quota Google counts per project.\n */\nexport function loadJsonPayloads(args: Record<string, unknown>): Record<string, unknown>[] {\n  const parsed = readJsonSource(args, \"json\");\n  if (!Array.isArray(parsed)) {\n    return [asObject(parsed, \"json\")];\n  }\n  if (parsed.length === 0) {\n    failValidation(\"--json is an empty list — pass at least one definition\");\n  }\n  return parsed.map((entry, index) => asObject(entry, \"json\", index));\n}\n\nconst RETRYABLE_CODES = new Set([\"RATE_LIMITED\", \"UNAVAILABLE\", \"INTERNAL_ERROR\", \"NETWORK_ERROR\", \"TIMEOUT\"]);\n\n/**\n * The one error shape for the whole family.\n *\n * Two different 403s reach here and they need opposite responses, which is why\n * the fix is keyed to the message and not just the status:\n *  - \"no Google Analytics connection / no property picked\" → the in-chat connect\n *    form, same as every other family.\n *  - \"this connection can read but not change the property\" → a RECONNECT, which\n *    is what every connection made before Baker could configure GA4 needs. The\n *    backend's message already says so, so it is passed through as the fix\n *    explanation rather than being replaced with the connect-form wording, which\n *    would send the user to set up a connection they already have.\n */\nexport function handleError(err: unknown): never {\n  if (err instanceof ApiError) {\n    const readOnly = err.code === \"FORBIDDEN\" && /read the property but not change it/i.test(err.message);\n    writeJsonEnvelope({\n      ok: false,\n      error: {\n        code: err.code,\n        message: err.message,\n        ...(readOnly\n          ? {\n              fix: {\n                action: \"reconnect\",\n                explanation:\n                  \"The Google Analytics connection is read-only. Ask the user to reconnect Google Analytics — in the \" +\n                  \"dashboard, Brain → Integrations → Platforms → Google Analytics — which grants the permission to change \" +\n                  \"the property. Reporting (`baker ga4 query`, `baker ga4 audit`) keeps working meanwhile, so carry \" +\n                  \"on with the rest of the job and tell them what you will set up once they have reconnected. Don't \" +\n                  \"claim anything was configured.\",\n              },\n            }\n          : err.code === \"UNAUTHORIZED\" || (err.code === \"FORBIDDEN\" && isNotConnectedError(err.code, err.message))\n            ? {\n                fix: {\n                  action: \"request_connection\",\n                  explanation:\n                    \"Google Analytics is not connected for this company yet, or no property has been picked. Don't \" +\n                    'send the user to Settings — call the `request_connection` tool with { platform: \"google-analytics\", ' +\n                    \"reason } and they connect and pick their property from inside the chat. If the \" +\n                    \"`request_connection` call fails, say so plainly and give the exact route: dashboard → Brain → \" +\n                    \"Integrations → Platforms → Google Analytics. Then carry on with the rest of the task.\",\n                },\n              }\n            : {}),\n        retryable: RETRYABLE_CODES.has(err.code),\n      },\n    });\n    process.exit(1);\n  }\n  writeJsonEnvelope({ ok: false, error: { code: \"NETWORK_ERROR\", message: \"Unexpected error\", retryable: true } });\n  process.exit(1);\n}\n\n/** Nudges returned after a stage so the agent's next step is obvious. */\nconst STAGE_HINTS = [\n  \"Staged only — nothing has changed in Google Analytics yet. These apply when the chat completes, and an applied \" +\n    \"change takes effect on the property immediately: there is no version to publish afterwards and no undo. Say \" +\n    \"the changes are ready and take effect when the user completes the chat — not that they are done already.\",\n];\n\nconst WARNING_HINT = \"Read the warnings above before telling the user this is ready.\";\n\nexport async function stageOp(op: Record<string, unknown>): Promise<void> {\n  const chatId = requireChatId();\n  try {\n    const { data, hints } = splitHints(await apiPost<Ga4DraftStageResponse>(\"/api/ga4/draft/stage\", { chatId, op }));\n    writeJsonEnvelope({\n      ok: true,\n      data,\n      hints: [...hints, ...STAGE_HINTS, ...(data.warnings.length > 0 ? [WARNING_HINT] : [])],\n    });\n  } catch (err) {\n    handleError(err);\n  }\n}\n\n/**\n * Stage several changes as ONE request against ONE read of the property.\n *\n * All-or-nothing: if any one of them is refused, none of them stage — which is\n * the honest outcome, since the refusals are things like \"two of these claim the\n * same parameter name\" that only mean anything about the set as a whole. A\n * single op falls through to the plain path so its envelope is unchanged.\n */\nexport async function stageOps(ops: Record<string, unknown>[]): Promise<void> {\n  const [only] = ops;\n  if (ops.length === 1 && only) {\n    await stageOp(only);\n    return;\n  }\n  const chatId = requireChatId();\n  try {\n    const { data, hints } = splitHints(\n      await apiPost<Ga4DraftStageBatchResponse>(\"/api/ga4/draft/stage-batch\", { chatId, ops }),\n    );\n    writeJsonEnvelope({\n      ok: true,\n      data,\n      hints: [...hints, ...STAGE_HINTS, ...(data.ops.some((op) => op.warnings.length > 0) ? [WARNING_HINT] : [])],\n    });\n  } catch (err) {\n    handleError(err);\n  }\n}\n\nexport async function draftAction(\n  path: string,\n  body: Record<string, unknown>,\n  chat?: unknown,\n): Promise<Record<string, unknown>> {\n  const chatId = resolveChatId(chat);\n  try {\n    const { data, hints } = splitHints(await apiPost<Record<string, unknown>>(path, { chatId, ...body }));\n    writeJsonEnvelope({ ok: true, data, ...(hints.length > 0 ? { hints } : {}) });\n    return data;\n  } catch (err) {\n    handleError(err);\n  }\n}\n\n/** A compact, readable view of everything staged on this chat. */\nexport function renderDraft(response: Ga4DraftListResponse): string {\n  if (response.count === 0) {\n    return \"No Google Analytics changes staged on this chat.\";\n  }\n  const lines = [\n    response.status === \"discarded\"\n      ? `${response.count} Google Analytics change(s) discarded with their chat — none will apply`\n      : `${response.count} staged Google Analytics change(s)`,\n    ...response.ops.map((op) => {\n      const status = op.result ? ` [${op.result.status}]` : \"\";\n      return `  ${op.ref}  ${op.summary}${status}`;\n    }),\n  ];\n  if (response.status === \"applied\") {\n    const failed = response.ops.filter((op) => op.result?.status !== \"applied\");\n    lines.push(\n      \"\",\n      failed.length === 0\n        ? \"All applied — these are in effect on the property now.\"\n        : `${failed.length} of ${response.count} did not apply. The rest are in effect on the property.`,\n    );\n  }\n  if (response.publishError) {\n    lines.push(\"\", response.publishError);\n  }\n  return lines.join(\"\\n\");\n}\n\nexport async function draftList(json: boolean, chat?: unknown): Promise<void> {\n  const chatId = resolveChatId(chat);\n  try {\n    const response = await apiPost<Ga4DraftListResponse>(\"/api/ga4/draft\", { chatId });\n    const { data, hints } = splitHints(response);\n    if (json) {\n      writeJsonEnvelope({ ok: true, data, ...(hints.length > 0 ? { hints } : {}) });\n      return;\n    }\n    process.stdout.write(`${renderDraft(data)}${hintLines(response)}\\n`);\n  } catch (err) {\n    handleError(err);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-WIRBRCTJ.js

@@ -0,0 +1,228 @@
+import {
+  NUMERIC_ID_REGEX
+} from "./chunk-JAYT43KX.js";
+
+// ../api/src/ads-google/change-history.ts
+var CHANGE_SCOPES = ["detail", "summary"];
+var CHANGE_SCOPE_MAX_DAYS = {
+  detail: 30,
+  summary: 90
+};
+var DEFAULT_CHANGE_DAYS = 7;
+var MAX_CHANGE_DAYS = CHANGE_SCOPE_MAX_DAYS.summary;
+function isChangeLookbackWithinReach(days, scope) {
+  return days <= CHANGE_SCOPE_MAX_DAYS[scope];
+}
+
+// ../api/src/ads-google/keyword-planning.ts
+import { z } from "zod";
+var ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+var micros = z.number().int().positive();
+var FORECAST_MATCH_TYPES = ["EXACT", "PHRASE", "BROAD"];
+var googleForecastBiddingSchema = z.discriminatedUnion("strategy", [
+  z.object({ strategy: z.literal("MANUAL_CPC"), maxCpcBidMicros: micros, dailyBudgetMicros: micros.optional() }),
+  z.object({
+    strategy: z.literal("MAXIMIZE_CLICKS"),
+    dailyTargetSpendMicros: micros,
+    maxCpcBidCeilingMicros: micros.optional()
+  }),
+  z.object({ strategy: z.literal("MAXIMIZE_CONVERSIONS"), dailyTargetSpendMicros: micros })
+]);
+var googleKeywordForecastRequestSchema = z.object({
+  customerId: z.string().regex(NUMERIC_ID_REGEX, "customerId must be the bare numeric customer id"),
+  managerId: z.string().optional(),
+  /** One forecast ad group per entry; most forecasts are a single group. */
+  adGroups: z.array(
+    z.object({
+      keywords: z.array(z.object({ text: z.string().trim().min(1).max(80), matchType: z.enum(FORECAST_MATCH_TYPES) })).min(1)
+    })
+  ).min(1),
+  locationIds: z.array(z.string().regex(NUMERIC_ID_REGEX)).optional(),
+  languageId: z.string().regex(NUMERIC_ID_REGEX).optional(),
+  bidding: googleForecastBiddingSchema,
+  /** Must start in the future and end within a year. Without them Baker forecasts the 30 days from tomorrow. */
+  startDate: z.string().regex(ISO_DATE).optional(),
+  endDate: z.string().regex(ISO_DATE).optional(),
+  currencyCode: z.string().length(3).optional()
+}).refine((body) => body.startDate === void 0 === (body.endDate === void 0), {
+  message: "Give both --start and --end, or neither (the forecast then covers the 30 days from tomorrow)",
+  path: ["endDate"]
+});
+var KEYWORD_FORECAST_SOURCE = "keyword_planner_forecast";
+var googleKeywordForecastResponseSchema = z.object({
+  source: z.literal(KEYWORD_FORECAST_SOURCE),
+  period: z.object({ startDate: z.string(), endDate: z.string() }),
+  forecast_clicks: z.number().nullable(),
+  forecast_cost_micros: z.number().nullable(),
+  forecast_conversions: z.number().nullable(),
+  forecast_average_cpc_micros: z.number().nullable(),
+  forecast_average_cpa_micros: z.number().nullable()
+});
+var googleAdGroupThemesRequestSchema = z.object({
+  customerId: z.string().regex(NUMERIC_ID_REGEX, "customerId must be the bare numeric customer id"),
+  managerId: z.string().optional(),
+  keywords: z.array(z.string().trim().min(1)).min(1),
+  /** Existing ad groups to sort the keywords into: numeric ids or `customers/{cid}/adGroups/{id}`. */
+  adGroups: z.array(z.string().min(1)).min(1)
+});
+var googleAdGroupThemesResponseSchema = z.object({
+  suggestions: z.array(
+    z.object({
+      keyword: z.string(),
+      suggested_keyword: z.string(),
+      match_type: z.string(),
+      ad_group: z.string(),
+      campaign: z.string()
+    })
+  ),
+  unusable_ad_groups: z.array(z.object({ ad_group: z.string(), campaign: z.string() }))
+});
+
+// ../api/src/ads-google/url-options.ts
+import { z as z2 } from "zod";
+var URL_OPTION_LEVELS = ["account", "campaign", "ad_group", "ad"];
+var googleUrlOptionValueSchema = z2.discriminatedUnion("state", [
+  z2.object({ state: z2.literal("set"), value: z2.string() }),
+  z2.object({ state: z2.literal("not_set") }),
+  z2.object({ state: z2.literal("not_read"), reason: z2.string() })
+]);
+var googleUrlOptionsRequestSchema = z2.object({
+  customerId: z2.string().regex(NUMERIC_ID_REGEX, "customerId must be the bare numeric customer id"),
+  managerId: z2.string().optional(),
+  /** Compact by default: only campaigns that actually override the account. `full` lists every campaign. */
+  full: z2.boolean().optional(),
+  skipCache: z2.boolean().optional()
+});
+var googleUrlOptionsCampaignSchema = z2.object({
+  id: z2.string(),
+  name: z2.string(),
+  status: z2.string(),
+  final_url_suffix: googleUrlOptionValueSchema,
+  tracking_url_template: googleUrlOptionValueSchema
+});
+var googleUrlOptionsAdGroupSchema = z2.object({
+  id: z2.string(),
+  name: z2.string(),
+  status: z2.string(),
+  campaign_id: z2.string(),
+  final_url_suffix: googleUrlOptionValueSchema,
+  tracking_url_template: googleUrlOptionValueSchema
+});
+var googleUrlOptionsAdSchema = z2.object({
+  id: z2.string(),
+  status: z2.string(),
+  ad_group_id: z2.string(),
+  campaign_id: z2.string(),
+  final_url_suffix: googleUrlOptionValueSchema,
+  tracking_url_template: googleUrlOptionValueSchema
+});
+var googleUrlOptionsResponseSchema = z2.object({
+  customer_id: z2.string(),
+  account: z2.object({
+    level: z2.literal("account"),
+    read: z2.boolean(),
+    final_url_suffix: googleUrlOptionValueSchema,
+    tracking_url_template: googleUrlOptionValueSchema
+  }),
+  campaigns: z2.object({
+    level: z2.literal("campaign"),
+    read: z2.boolean(),
+    /** Campaigns actually observed. 0 with `read: true` means the account has no non-removed campaigns. */
+    campaigns_read: z2.number().int().nonnegative(),
+    /** Campaigns observed to carry no override of their own — an explicit finding, not an omission. */
+    campaigns_without_override: z2.number().int().nonnegative(),
+    overrides: z2.array(googleUrlOptionsCampaignSchema),
+    /** Compact mode only: campaigns read but not listed because they carry no override. */
+    omitted: z2.number().int().nonnegative()
+  }),
+  /**
+   * Ad groups and ads that carry an override of their own — read by asking Google only for the
+   * entities whose suffix or template IS NOT NULL, so an account of thousands of ads costs one page.
+   * `read: true` with no overrides is a finding: nothing at this level overrides the levels above.
+   * `truncated` means more overriding entities exist than one page listed.
+   */
+  ad_groups: z2.object({
+    level: z2.literal("ad_group"),
+    read: z2.boolean(),
+    overrides: z2.array(googleUrlOptionsAdGroupSchema),
+    truncated: z2.boolean()
+  }),
+  ads: z2.object({
+    level: z2.literal("ad"),
+    read: z2.boolean(),
+    overrides: z2.array(googleUrlOptionsAdSchema),
+    truncated: z2.boolean()
+  }),
+  /** Levels this command could not read. Nothing here may be reported as "not configured". */
+  levels_not_read: z2.array(z2.object({ level: z2.enum(URL_OPTION_LEVELS), reason: z2.string() }))
+});
+var ACCOUNT_URL_OPTIONS_LOCATION = "Google Ads UI \u2192 Admin \u2192 Account settings \u2192 Tracking (account-level tracking template and final URL suffix)";
+var ACCOUNT_URL_OPTIONS_STAGE_COMMAND = 'baker ads google account update --customer-id <id> --final-url-suffix "utm_agency=baker"';
+function isSet(value) {
+  return value.state === "set";
+}
+function entityOverrideHints(label, plural, field, level) {
+  if (!level.read) return [];
+  const hints = [];
+  const overriding = level.overrides.filter((entity) => isSet(entity.final_url_suffix));
+  if (overriding.length > 0) {
+    const named = overriding.slice(0, 5).map((entity) => entity.name || entity.id).join(", ");
+    hints.push(
+      `${overriding.length} ${label}(s) set their own final URL suffix (${named}${overriding.length > 5 ? ", \u2026" : ""}). It REPLACES the campaign and account suffix for every click through it, so an account-wide parameter must be added to theirs too.`
+    );
+  }
+  if (level.truncated) {
+    hints.push(
+      `More ${plural} override the URL options than one page lists \u2014 read them all with \`baker ads google query\` on ${field}.final_url_suffix IS NOT NULL --all before saying which ones do.`
+    );
+  }
+  return hints;
+}
+function urlOptionsHints(report) {
+  const hints = [];
+  const { account, campaigns } = report;
+  if (!account.read) {
+    hints.push(
+      "The account level did NOT read \u2014 its URL options are unknown, not empty. Re-run before telling the user anything about account-wide tagging."
+    );
+  } else if (account.final_url_suffix.state === "not_set") {
+    hints.push(
+      `No account-level final URL suffix is set. An account-wide parameter (agency/partner tagging such as utm_agency=\u2026) belongs at the account level so it reaches every ad \u2014 stage it with \`${ACCOUNT_URL_OPTIONS_STAGE_COMMAND}\` (applies at Publish; the user sees it under ${ACCOUNT_URL_OPTIONS_LOCATION}).`
+    );
+  }
+  if (!campaigns.read) {
+    hints.push(
+      "Campaign-level URL options did NOT read \u2014 do not report that no campaign overrides exist. Re-run before concluding."
+    );
+  } else {
+    const overriding = campaigns.overrides.filter((c) => isSet(c.final_url_suffix));
+    if (overriding.length > 0) {
+      const named = overriding.slice(0, 5).map((c) => c.name || c.id).join(", ");
+      hints.push(
+        `A campaign's final URL suffix REPLACES the account-level one for that campaign \u2014 it does not merge. ${overriding.length} campaign(s) set their own (${named}${overriding.length > 5 ? ", \u2026" : ""}) and will not pick up an account-wide parameter until their own suffix carries it too. Every other campaign read here inherits the account level normally.`
+      );
+    }
+  }
+  hints.push(...entityOverrideHints("ad group", "ad groups", "ad_group", report.ad_groups));
+  hints.push(...entityOverrideHints("ad", "ads", "ad_group_ad.ad", report.ads));
+  const overridingLevelsNotRead = report.levels_not_read.filter((level) => level.level !== "account");
+  if (overridingLevelsNotRead.length > 0) {
+    hints.push(
+      `Not read at this level: ${overridingLevelsNotRead.map((l) => l.level).join(", ")}. A suffix set there still wins over the levels above it.`
+    );
+  }
+  if (campaigns.omitted > 0) {
+    hints.push(`${campaigns.omitted} campaign(s) read with no override of their own are not listed \u2014 pass --full.`);
+  }
+  return hints;
+}
+
+export {
+  CHANGE_SCOPES,
+  CHANGE_SCOPE_MAX_DAYS,
+  DEFAULT_CHANGE_DAYS,
+  isChangeLookbackWithinReach,
+  googleKeywordForecastRequestSchema,
+  urlOptionsHints
+};
+//# sourceMappingURL=chunk-WIRBRCTJ.js.map

package/dist/chunk-WIRBRCTJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../api/src/ads-google/change-history.ts","../../api/src/ads-google/keyword-planning.ts","../../api/src/ads-google/url-options.ts"],"sourcesContent":["/**\n * How far back Google's account history actually reaches, shared by the CLI and the\n * backend so the two layers cannot disagree about the limit.\n *\n * `change_event` carries field-level detail — old → new value and the user who made the\n * change — for the last 30 days. `change_status` reaches 90 days but only reports which\n * resources were added, changed or removed. Past 90 days there is no API at all; the\n * change has to be inferred from performance, or read from the Google Ads web UI.\n */\n\nexport const CHANGE_SCOPES = [\"detail\", \"summary\"] as const;\n\nexport type ChangeScope = (typeof CHANGE_SCOPES)[number];\n\nexport const CHANGE_SCOPE_MAX_DAYS: Record<ChangeScope, number> = {\n  detail: 30,\n  summary: 90,\n};\n\nexport const DEFAULT_CHANGE_DAYS = 7;\n\n/** Longest lookback any history resource can serve. */\nexport const MAX_CHANGE_DAYS = CHANGE_SCOPE_MAX_DAYS.summary;\n\nexport function isChangeLookbackWithinReach(days: number, scope: ChangeScope): boolean {\n  return days <= CHANGE_SCOPE_MAX_DAYS[scope];\n}\n\n/** The cheapest scope that can serve `days`, or null when nothing reaches that far. */\nexport function changeScopeForDays(days: number): ChangeScope | null {\n  return CHANGE_SCOPES.find((scope) => isChangeLookbackWithinReach(days, scope)) ?? null;\n}\n\n/**\n * Why a lookback was refused, and what to do instead. Callers that bypass the CLI get\n * this straight from the API, so it has to carry the way out of the window rather than\n * just the limit that was breached.\n */\nexport function changeLookbackMessage(days: number, scope: ChangeScope): string {\n  const reachable = changeScopeForDays(days);\n  if (reachable && reachable !== scope) {\n    return `Google keeps field-level change detail for ${CHANGE_SCOPE_MAX_DAYS.detail} days only, and ${days} days is outside that window. Use scope \"${reachable}\" to reach back ${CHANGE_SCOPE_MAX_DAYS[reachable]} days — it reports which resources changed, without the old and new values.`;\n  }\n  return `Google's account history reaches back ${MAX_CHANGE_DAYS} days at most, and ${days} days is outside that window. Infer the change from monthly spend per campaign instead; anything older with attribution exists only in the Google Ads web interface, which has no API.`;\n}\n","/**\n * Keyword Planner reads beyond ideas and historical volume: a forecast for a set of keywords\n * (`GenerateKeywordForecastMetrics`, v25 shape) and ad-group themes (`GenerateAdGroupThemes`,\n * which existing ad group each keyword belongs in).\n *\n * The v25 forecast takes a campaign to forecast — languages, locations, ONE bidding strategy and\n * ad groups of keywords — and answers with one set of campaign-level estimates. It has no network\n * choice, no per-keyword bids and no negatives; those were the pre-v18 keyword-plan shape.\n */\nimport { z } from \"zod\";\nimport { NUMERIC_ID_REGEX } from \"./limits\";\n\nconst ISO_DATE = /^\\d{4}-\\d{2}-\\d{2}$/;\nconst micros = z.number().int().positive();\n\nexport const FORECAST_MATCH_TYPES = [\"EXACT\", \"PHRASE\", \"BROAD\"] as const;\n\nexport const googleForecastBiddingSchema = z.discriminatedUnion(\"strategy\", [\n  z.object({ strategy: z.literal(\"MANUAL_CPC\"), maxCpcBidMicros: micros, dailyBudgetMicros: micros.optional() }),\n  z.object({\n    strategy: z.literal(\"MAXIMIZE_CLICKS\"),\n    dailyTargetSpendMicros: micros,\n    maxCpcBidCeilingMicros: micros.optional(),\n  }),\n  z.object({ strategy: z.literal(\"MAXIMIZE_CONVERSIONS\"), dailyTargetSpendMicros: micros }),\n]);\nexport type GoogleForecastBidding = z.infer<typeof googleForecastBiddingSchema>;\n\nexport const googleKeywordForecastRequestSchema = z\n  .object({\n    customerId: z.string().regex(NUMERIC_ID_REGEX, \"customerId must be the bare numeric customer id\"),\n    managerId: z.string().optional(),\n    /** One forecast ad group per entry; most forecasts are a single group. */\n    adGroups: z\n      .array(\n        z.object({\n          keywords: z\n            .array(z.object({ text: z.string().trim().min(1).max(80), matchType: z.enum(FORECAST_MATCH_TYPES) }))\n            .min(1),\n        }),\n      )\n      .min(1),\n    locationIds: z.array(z.string().regex(NUMERIC_ID_REGEX)).optional(),\n    languageId: z.string().regex(NUMERIC_ID_REGEX).optional(),\n    bidding: googleForecastBiddingSchema,\n    /** Must start in the future and end within a year. Without them Baker forecasts the 30 days from tomorrow. */\n    startDate: z.string().regex(ISO_DATE).optional(),\n    endDate: z.string().regex(ISO_DATE).optional(),\n    currencyCode: z.string().length(3).optional(),\n  })\n  .refine((body) => (body.startDate === undefined) === (body.endDate === undefined), {\n    message: \"Give both --start and --end, or neither (the forecast then covers the 30 days from tomorrow)\",\n    path: [\"endDate\"],\n  });\nexport type GoogleKeywordForecastRequest = z.infer<typeof googleKeywordForecastRequestSchema>;\n\nexport const KEYWORD_FORECAST_SOURCE = \"keyword_planner_forecast\" as const;\n\n/** Every number is Google's prediction for the whole forecast period — never an account result. */\nexport const googleKeywordForecastResponseSchema = z.object({\n  source: z.literal(KEYWORD_FORECAST_SOURCE),\n  period: z.object({ startDate: z.string(), endDate: z.string() }),\n  forecast_clicks: z.number().nullable(),\n  forecast_cost_micros: z.number().nullable(),\n  forecast_conversions: z.number().nullable(),\n  forecast_average_cpc_micros: z.number().nullable(),\n  forecast_average_cpa_micros: z.number().nullable(),\n});\nexport type GoogleKeywordForecastResponse = z.infer<typeof googleKeywordForecastResponseSchema>;\n\nexport const googleAdGroupThemesRequestSchema = z.object({\n  customerId: z.string().regex(NUMERIC_ID_REGEX, \"customerId must be the bare numeric customer id\"),\n  managerId: z.string().optional(),\n  keywords: z.array(z.string().trim().min(1)).min(1),\n  /** Existing ad groups to sort the keywords into: numeric ids or `customers/{cid}/adGroups/{id}`. */\n  adGroups: z.array(z.string().min(1)).min(1),\n});\nexport type GoogleAdGroupThemesRequest = z.infer<typeof googleAdGroupThemesRequestSchema>;\n\nexport const googleAdGroupThemesResponseSchema = z.object({\n  suggestions: z.array(\n    z.object({\n      keyword: z.string(),\n      suggested_keyword: z.string(),\n      match_type: z.string(),\n      ad_group: z.string(),\n      campaign: z.string(),\n    }),\n  ),\n  unusable_ad_groups: z.array(z.object({ ad_group: z.string(), campaign: z.string() })),\n});\nexport type GoogleAdGroupThemesResponse = z.infer<typeof googleAdGroupThemesResponseSchema>;\n","/**\n * `ads.google.url-options` — the URL/tracking options in force on an account.\n *\n * Google returns a field ONLY when it holds a value: an unset `final_url_suffix`\n * is not `\"\"`, it is a key that never appears in the row. Reported naively, that\n * is indistinguishable from a read that never happened — and a false \"no suffix\n * is configured\" has already been written into a client's knowledge base from\n * exactly that ambiguity.\n *\n * So every value here is a tagged union, never a bare string:\n *\n * - `{ state: \"set\", value }`   — observed, holds this value\n * - `{ state: \"not_set\" }`      — observed, Google carries no value at this level\n * - `{ state: \"not_read\", reason }` — never observed; says nothing about the account\n *\n * and every level Baker did NOT read is listed explicitly in `levels_not_read`\n * rather than silently omitted. Absence is only a finding when it is `not_set`.\n */\nimport { z } from \"zod\";\nimport { NUMERIC_ID_REGEX } from \"./limits\";\n\n/** Google resolves URL options most-specific-first; these are the levels that can carry one. */\nexport const URL_OPTION_LEVELS = [\"account\", \"campaign\", \"ad_group\", \"ad\"] as const;\nexport type GoogleUrlOptionLevel = (typeof URL_OPTION_LEVELS)[number];\n\nexport const googleUrlOptionValueSchema = z.discriminatedUnion(\"state\", [\n  z.object({ state: z.literal(\"set\"), value: z.string() }),\n  z.object({ state: z.literal(\"not_set\") }),\n  z.object({ state: z.literal(\"not_read\"), reason: z.string() }),\n]);\nexport type GoogleUrlOptionValue = z.infer<typeof googleUrlOptionValueSchema>;\n\nexport const googleUrlOptionsRequestSchema = z.object({\n  customerId: z.string().regex(NUMERIC_ID_REGEX, \"customerId must be the bare numeric customer id\"),\n  managerId: z.string().optional(),\n  /** Compact by default: only campaigns that actually override the account. `full` lists every campaign. */\n  full: z.boolean().optional(),\n  skipCache: z.boolean().optional(),\n});\nexport type GoogleUrlOptionsRequest = z.infer<typeof googleUrlOptionsRequestSchema>;\n\nexport const googleUrlOptionsCampaignSchema = z.object({\n  id: z.string(),\n  name: z.string(),\n  status: z.string(),\n  final_url_suffix: googleUrlOptionValueSchema,\n  tracking_url_template: googleUrlOptionValueSchema,\n});\nexport type GoogleUrlOptionsCampaign = z.infer<typeof googleUrlOptionsCampaignSchema>;\n\nexport const googleUrlOptionsAdGroupSchema = z.object({\n  id: z.string(),\n  name: z.string(),\n  status: z.string(),\n  campaign_id: z.string(),\n  final_url_suffix: googleUrlOptionValueSchema,\n  tracking_url_template: googleUrlOptionValueSchema,\n});\nexport type GoogleUrlOptionsAdGroup = z.infer<typeof googleUrlOptionsAdGroupSchema>;\n\nexport const googleUrlOptionsAdSchema = z.object({\n  id: z.string(),\n  status: z.string(),\n  ad_group_id: z.string(),\n  campaign_id: z.string(),\n  final_url_suffix: googleUrlOptionValueSchema,\n  tracking_url_template: googleUrlOptionValueSchema,\n});\nexport type GoogleUrlOptionsAd = z.infer<typeof googleUrlOptionsAdSchema>;\n\nexport const googleUrlOptionsResponseSchema = z.object({\n  customer_id: z.string(),\n  account: z.object({\n    level: z.literal(\"account\"),\n    read: z.boolean(),\n    final_url_suffix: googleUrlOptionValueSchema,\n    tracking_url_template: googleUrlOptionValueSchema,\n  }),\n  campaigns: z.object({\n    level: z.literal(\"campaign\"),\n    read: z.boolean(),\n    /** Campaigns actually observed. 0 with `read: true` means the account has no non-removed campaigns. */\n    campaigns_read: z.number().int().nonnegative(),\n    /** Campaigns observed to carry no override of their own — an explicit finding, not an omission. */\n    campaigns_without_override: z.number().int().nonnegative(),\n    overrides: z.array(googleUrlOptionsCampaignSchema),\n    /** Compact mode only: campaigns read but not listed because they carry no override. */\n    omitted: z.number().int().nonnegative(),\n  }),\n  /**\n   * Ad groups and ads that carry an override of their own — read by asking Google only for the\n   * entities whose suffix or template IS NOT NULL, so an account of thousands of ads costs one page.\n   * `read: true` with no overrides is a finding: nothing at this level overrides the levels above.\n   * `truncated` means more overriding entities exist than one page listed.\n   */\n  ad_groups: z.object({\n    level: z.literal(\"ad_group\"),\n    read: z.boolean(),\n    overrides: z.array(googleUrlOptionsAdGroupSchema),\n    truncated: z.boolean(),\n  }),\n  ads: z.object({\n    level: z.literal(\"ad\"),\n    read: z.boolean(),\n    overrides: z.array(googleUrlOptionsAdSchema),\n    truncated: z.boolean(),\n  }),\n  /** Levels this command could not read. Nothing here may be reported as \"not configured\". */\n  levels_not_read: z.array(z.object({ level: z.enum(URL_OPTION_LEVELS), reason: z.string() })),\n});\nexport type GoogleUrlOptionsResponse = z.infer<typeof googleUrlOptionsResponseSchema>;\n\n/** Where Google keeps the account-level fields, verbatim, for an agent relaying it to a marketer. */\nexport const ACCOUNT_URL_OPTIONS_LOCATION =\n  \"Google Ads UI → Admin → Account settings → Tracking (account-level tracking template and final URL suffix)\";\n\n/**\n * How the account-level value is staged: `google.customer.update` rides the same `GoogleAdsService.Mutate`\n * batch as every other staged op (`customerOperation`), so it applies at Publish like the rest.\n */\nexport const ACCOUNT_URL_OPTIONS_STAGE_COMMAND =\n  'baker ads google account update --customer-id <id> --final-url-suffix \"utm_agency=baker\"';\n\nfunction isSet(value: GoogleUrlOptionValue): value is { state: \"set\"; value: string } {\n  return value.state === \"set\";\n}\n\n/** What an ad-group or ad level's overrides mean for an account-wide parameter. */\nfunction entityOverrideHints(\n  label: string,\n  plural: string,\n  field: string,\n  level: GoogleUrlOptionsResponse[\"ad_groups\"] | GoogleUrlOptionsResponse[\"ads\"],\n): string[] {\n  if (!level.read) return [];\n  const hints: string[] = [];\n  const overriding: Array<{ id: string; name?: string; final_url_suffix: GoogleUrlOptionValue }> =\n    level.overrides.filter((entity) => isSet(entity.final_url_suffix));\n  if (overriding.length > 0) {\n    const named = overriding\n      .slice(0, 5)\n      .map((entity) => entity.name || entity.id)\n      .join(\", \");\n    hints.push(\n      `${overriding.length} ${label}(s) set their own final URL suffix (${named}${overriding.length > 5 ? \", …\" : \"\"}). It REPLACES the campaign and account suffix for every click through it, so an account-wide parameter must be added to theirs too.`,\n    );\n  }\n  if (level.truncated) {\n    hints.push(\n      `More ${plural} override the URL options than one page lists — read them all with \\`baker ads google query\\` on ${field}.final_url_suffix IS NOT NULL --all before saying which ones do.`,\n    );\n  }\n  return hints;\n}\n\n/**\n * Post-read nudges. The account level is the right home for an account-wide parameter\n * (agency/partner tagging), so a missing account suffix is the finding worth surfacing —\n * and a level that failed to read must never be reported as unset.\n */\nexport function urlOptionsHints(report: GoogleUrlOptionsResponse): string[] {\n  const hints: string[] = [];\n  const { account, campaigns } = report;\n\n  if (!account.read) {\n    hints.push(\n      \"The account level did NOT read — its URL options are unknown, not empty. Re-run before telling the user anything about account-wide tagging.\",\n    );\n  } else if (account.final_url_suffix.state === \"not_set\") {\n    hints.push(\n      `No account-level final URL suffix is set. An account-wide parameter (agency/partner tagging such as utm_agency=…) belongs at the account level so it reaches every ad — stage it with \\`${ACCOUNT_URL_OPTIONS_STAGE_COMMAND}\\` (applies at Publish; the user sees it under ${ACCOUNT_URL_OPTIONS_LOCATION}).`,\n    );\n  }\n\n  if (!campaigns.read) {\n    hints.push(\n      \"Campaign-level URL options did NOT read — do not report that no campaign overrides exist. Re-run before concluding.\",\n    );\n  } else {\n    // `overrides` carries every campaign under --full, not just the overriding ones,\n    // so name the ones that actually set a suffix. Saying \"campaigns listed under\n    // `overrides`\" would tell the agent that campaigns inheriting fine are broken.\n    const overriding = campaigns.overrides.filter((c) => isSet(c.final_url_suffix));\n    if (overriding.length > 0) {\n      const named = overriding\n        .slice(0, 5)\n        .map((c) => c.name || c.id)\n        .join(\", \");\n      hints.push(\n        `A campaign's final URL suffix REPLACES the account-level one for that campaign — it does not merge. ${overriding.length} campaign(s) set their own (${named}${overriding.length > 5 ? \", …\" : \"\"}) and will not pick up an account-wide parameter until their own suffix carries it too. Every other campaign read here inherits the account level normally.`,\n      );\n    }\n  }\n\n  hints.push(...entityOverrideHints(\"ad group\", \"ad groups\", \"ad_group\", report.ad_groups));\n  hints.push(...entityOverrideHints(\"ad\", \"ads\", \"ad_group_ad.ad\", report.ads));\n\n  // Precedence is account → campaign → ad group → ad, most specific winning, so\n  // \"a suffix set there still wins\" only holds for levels BELOW the ones that read.\n  // `account` is the least specific — a campaign, ad-group or ad suffix overrides it —\n  // and it joins `levels_not_read` whenever the customer read fails, which would hand\n  // the agent the precedence backwards. Its own \"did NOT read\" hint above covers it.\n  const overridingLevelsNotRead = report.levels_not_read.filter((level) => level.level !== \"account\");\n  if (overridingLevelsNotRead.length > 0) {\n    hints.push(\n      `Not read at this level: ${overridingLevelsNotRead.map((l) => l.level).join(\", \")}. A suffix set there still wins over the levels above it.`,\n    );\n  }\n\n  if (campaigns.omitted > 0) {\n    hints.push(`${campaigns.omitted} campaign(s) read with no override of their own are not listed — pass --full.`);\n  }\n\n  return hints;\n}\n"],"mappings":"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","names":["z","z"]}

package/dist/chunk-WN4KX7GE.js

@@ -0,0 +1,25 @@
+// src/commands/avatars/wait.ts
+var WAIT_TIMEOUT_MS = 9e4;
+var WAIT_INTERVAL_MS = 3e3;
+function shouldKeepWaiting(avatar, elapsedMs) {
+  if (avatar.status === "ready") return { done: true, reason: "ready" };
+  if (avatar.status === "error" || avatar.status === "archived") return { done: true, reason: "settled" };
+  if (avatar.needsFace) return { done: true, reason: "needs-face" };
+  if (elapsedMs >= WAIT_TIMEOUT_MS) return { done: false, reason: "expired" };
+  return { done: false, reason: "building" };
+}
+async function waitForSheet(first, read, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+  const startedAt = Date.now();
+  let latest = first;
+  while (!shouldKeepWaiting(latest, Date.now() - startedAt).done) {
+    if (shouldKeepWaiting(latest, Date.now() - startedAt).reason === "expired") return latest;
+    await sleep(WAIT_INTERVAL_MS);
+    latest = await read();
+  }
+  return latest;
+}
+
+export {
+  waitForSheet
+};
+//# sourceMappingURL=chunk-WN4KX7GE.js.map

package/dist/chunk-WN4KX7GE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/avatars/wait.ts"],"sourcesContent":["import type { AvatarStatus } from \"@baker/api\";\n\n/**\n * Waiting for an avatar's identity sheet, inside the command rather than in the agent.\n *\n * The sheet is a ~30s render, and the agent is told never to sleep on it — right, because\n * a turn spent standing still is a turn the user watches do nothing. But when the only\n * work left DEPENDS on that avatar, \"do the next piece of work\" names work that does not\n * exist, and the observed turn simply ended: the user had to come back and say \"ya está\n * lista\" for the clip to be made.\n *\n * A command that blocks internally is the sanctioned shape for this — it has its own\n * deadline and returns the moment the thing is ready, which a polling loop written by the\n * agent does neither of.\n */\n\n/** How long to keep asking before giving up. Twice the sheet's usual render. */\nexport const WAIT_TIMEOUT_MS = 90_000;\n/** Gap between reads. Short enough to return promptly, long enough not to hammer. */\nexport const WAIT_INTERVAL_MS = 3_000;\n\nexport type WaitDecision =\n  | { done: true; reason: \"ready\" | \"settled\" | \"needs-face\" }\n  | { done: false; reason: \"building\" | \"expired\" };\n\n/** Just enough of an avatar to know whether waiting on it can ever end. */\nexport interface WaitSubject {\n  status: AvatarStatus;\n  /**\n   * The build is parked on a face the user has not picked yet.\n   *\n   * `generating` normally means a render is running. This is the one case where it\n   * does not: the casting portraits are in front of the user and nothing starts until\n   * they answer.\n   */\n  needsFace?: boolean;\n}\n\n/**\n * Whether to stop waiting on this avatar, given how long we have waited.\n *\n * `error` and `archived` stop it too: both are settled states, and waiting out the\n * deadline for one of them would burn 90 seconds to learn what the first read said.\n *\n * So does an avatar waiting on its face. Nothing is rendering, so the only thing that\n * can happen here is the deadline expiring — and it is the user's own turn to act, not\n * the agent's. Observed: an agent blocked the full 90 seconds twice, concluded the\n * avatar was broken, and deleted the one the user was at that moment picking a face for.\n */\nexport function shouldKeepWaiting(avatar: WaitSubject, elapsedMs: number): WaitDecision {\n  if (avatar.status === \"ready\") return { done: true, reason: \"ready\" };\n  if (avatar.status === \"error\" || avatar.status === \"archived\") return { done: true, reason: \"settled\" };\n  if (avatar.needsFace) return { done: true, reason: \"needs-face\" };\n  if (elapsedMs >= WAIT_TIMEOUT_MS) return { done: false, reason: \"expired\" };\n  return { done: false, reason: \"building\" };\n}\n\n/**\n * Re-reads the avatar until its sheet settles, or the deadline passes.\n *\n * Returns whatever the last read said either way — an expired wait is not a failure, it\n * is a slow render, and the caller's own hints already say what a still-building avatar\n * can and cannot be used for.\n */\nexport async function waitForSheet<T extends WaitSubject>(\n  first: T,\n  read: () => Promise<T>,\n  sleep: (ms: number) => Promise<void> = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),\n): Promise<T> {\n  const startedAt = Date.now();\n  let latest = first;\n  while (!shouldKeepWaiting(latest, Date.now() - startedAt).done) {\n    if (shouldKeepWaiting(latest, Date.now() - startedAt).reason === \"expired\") return latest;\n    await sleep(WAIT_INTERVAL_MS);\n    latest = await read();\n  }\n  return latest;\n}\n"],"mappings":";AAiBO,IAAM,kBAAkB;AAExB,IAAM,mBAAmB;AA8BzB,SAAS,kBAAkB,QAAqB,WAAiC;AACtF,MAAI,OAAO,WAAW,QAAS,QAAO,EAAE,MAAM,MAAM,QAAQ,QAAQ;AACpE,MAAI,OAAO,WAAW,WAAW,OAAO,WAAW,WAAY,QAAO,EAAE,MAAM,MAAM,QAAQ,UAAU;AACtG,MAAI,OAAO,UAAW,QAAO,EAAE,MAAM,MAAM,QAAQ,aAAa;AAChE,MAAI,aAAa,gBAAiB,QAAO,EAAE,MAAM,OAAO,QAAQ,UAAU;AAC1E,SAAO,EAAE,MAAM,OAAO,QAAQ,WAAW;AAC3C;AASA,eAAsB,aACpB,OACA,MACA,QAAuC,CAAC,OAAO,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC,GACnF;AACZ,QAAM,YAAY,KAAK,IAAI;AAC3B,MAAI,SAAS;AACb,SAAO,CAAC,kBAAkB,QAAQ,KAAK,IAAI,IAAI,SAAS,EAAE,MAAM;AAC9D,QAAI,kBAAkB,QAAQ,KAAK,IAAI,IAAI,SAAS,EAAE,WAAW,UAAW,QAAO;AACnF,UAAM,MAAM,gBAAgB;AAC5B,aAAS,MAAM,KAAK;AAAA,EACtB;AACA,SAAO;AACT;","names":[]}

package/dist/chunk-WNFTXSGR.js

@@ -0,0 +1,111 @@
+import {
+  reportError,
+  splitList
+} from "./chunk-752S7JF6.js";
+import {
+  apiGet
+} from "./chunk-HREWXNTO.js";
+import {
+  registerSchema,
+  writeJson
+} from "./chunk-WOTDHRNF.js";
+
+// src/commands/winning-ads/launches.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "winning-ads.launches",
+  description: 'What the brands you follow (or the ones named) launched in the last N days and which of those ads still run, each with its stage (new, testing, killed_early\u2026), and the tests each brand decided in that window (the version kept, what differed). The "what did competitors launch last week" report. Compact by default; --full lists every launch.',
+  args: {
+    since: { type: "number", description: "Days to look back, 1-90 (default 7)", required: false, default: 7 },
+    advertiser: {
+      type: "string",
+      description: "Comma list of advertiser ids instead of every followed brand",
+      required: false
+    },
+    platform: { type: "string", description: "Only this platform: meta|linkedin|tiktok|google", required: false },
+    full: { type: "boolean", description: "List every launch", required: false, default: false }
+  }
+});
+var COMPACT_LAUNCHES = 10;
+function compactLaunches(report, full) {
+  return {
+    since_days: report.since_days,
+    advertisers: report.advertisers.map((b) => ({
+      advertiser_id: b.advertiser_id,
+      label: b.label,
+      launched: b.launched,
+      still_running: b.still_running,
+      launches: (full ? b.launches : b.launches.slice(0, COMPACT_LAUNCHES)).map((l) => ({
+        ad_id: l.ad_id,
+        platform: l.platform,
+        format: l.format,
+        headline: l.headline,
+        first_seen_at: l.first_seen_at,
+        stage: l.stage,
+        idea: l.idea ?? null,
+        ...full ? { media_url: l.media_url } : {}
+      })),
+      tests_decided: (b.tests_decided ?? []).map((t) => ({
+        concept: t.concept,
+        versions: t.versions,
+        kept_ad_id: t.winner_ad_id,
+        decided_at: t.decided_at ?? null,
+        what_differed: t.what_differed
+      }))
+    }))
+  };
+}
+var IDEA_HINT = "Idea: whether each launch was a `new` idea (the first day of its concept), another version of one the brand was still `testing`, or a version built on a `winner` it had already kept. Many launches and no new idea means the brand is iterating on what works, not testing new directions: say so.";
+function launchesHints(report, named) {
+  if (!named && report.following_count === 0) {
+    return ["You follow no brands yet: `baker winning-ads follow <domain>` adds one, or pass --advertiser <id>."];
+  }
+  if (report.advertisers.length === 0) {
+    return [`No launches in the last ${report.since_days} days. Widen the window with --since 30.`];
+  }
+  const withIdeas = report.advertisers.some((b) => b.launches.some((l) => l.idea));
+  return [
+    ...withIdeas ? [IDEA_HINT] : [],
+    "Stages: new \u22647 days, testing \u226421 days, proven \u226460 days, evergreen beyond, killed_early = stopped within 2 weeks (a lost test). tests_decided is what each brand learned in the window: the version it kept (kept_ad_id) and what differed. `baker winning-ads search --survived-test` finds the versions brands kept across the library."
+  ];
+}
+var launchesCommand = defineCommand({
+  meta: {
+    name: "launches",
+    description: "What competitors launched lately and what still runs. Start here: baker winning-ads launches --since 7 (every followed brand), or --advertiser adv_1,adv_2"
+  },
+  args: {
+    since: { type: "string", description: "Days to look back, 1-90 (default 7)", required: false },
+    advertiser: { type: "string", description: "Comma list of advertiser ids", required: false },
+    platform: { type: "string", description: "Only this platform: meta|linkedin|tiktok|google", required: false },
+    full: { type: "boolean", description: "List every launch", required: false, default: false }
+  },
+  run: async ({ args }) => {
+    try {
+      const named = splitList(args.advertiser);
+      const params = { since_days: String(args.since ?? 7) };
+      if (named.length > 0) {
+        params.advertiser = named.join(",");
+      }
+      if (args.platform) {
+        params.platform = String(args.platform);
+      }
+      const report = await apiGet("/api/ad-library/launches", params);
+      writeJson({
+        ok: true,
+        data: compactLaunches(report, Boolean(args.full)),
+        hints: launchesHints(report, named.length > 0)
+      });
+    } catch (err) {
+      reportError(err);
+    }
+  }
+});
+
+export {
+  compactLaunches,
+  IDEA_HINT,
+  launchesHints,
+  launchesCommand
+};
+//# sourceMappingURL=chunk-WNFTXSGR.js.map