@koda-sl/baker-cli 0.551.0 → 0.554.0

package/dist/audiences-5TOTVZMK.js

@@ -0,0 +1,85 @@
+import {
+  parseXApiError
+} from "./chunk-FIN4ZXGJ.js";
+import {
+  resolveXAccountId
+} from "./chunk-H6GTG665.js";
+import {
+  cacheGet,
+  cacheSet,
+  writeAdsJson,
+  writeAdsOutput
+} from "./chunk-QYH2UZAK.js";
+import {
+  ApiError,
+  apiGet
+} from "./chunk-GFWWHCBF.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  registerSchema
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/x/audiences.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "ads.x.audiences",
+  description: "List custom audiences for an X Ads account. Returns id, name, audience_size, audience_type, targetable status. Audiences need 100+ active users in the past 90 days to be targetable.",
+  args: {
+    "account-id": { type: "string", description: "X Ads account ID", required: false },
+    "no-cache": { type: "boolean", description: "Skip cache", required: false },
+    output: { type: "string", description: "Format: json|csv|md", required: false, default: "json" }
+  }
+});
+var audiencesCommand = defineCommand({
+  meta: {
+    name: "audiences",
+    description: `List X Ads custom audiences.
+
+Examples:
+  baker ads x audiences --account-id 18ce53xyz`
+  },
+  args: {
+    "account-id": { type: "string", description: "X Ads account ID", required: false },
+    "no-cache": { type: "boolean", description: "Skip cache", required: false },
+    output: { type: "string", description: "Format: json|csv|md", required: false, default: "json" }
+  },
+  run: async ({ args }) => {
+    const accountId = await resolveXAccountId(args);
+    const useCache = !args["no-cache"];
+    const cacheKey = `audiences:${accountId}`;
+    if (useCache) {
+      const cached = cacheGet("x-account-data", cacheKey);
+      if (cached) {
+        writeAdsJson({ ok: true, data: cached.data, cached: true });
+        return;
+      }
+    }
+    try {
+      const params = { "account-id": accountId };
+      if (!useCache) params["skip-cache"] = "true";
+      const data = await apiGet("/api/ads/x/custom-audiences", params);
+      if (useCache) {
+        cacheSet("x-account-data", cacheKey, data, 6 * 60 * 60 * 1e3);
+      }
+      const format = args.output || "json";
+      if (format !== "json") {
+        writeAdsOutput(data, format);
+        return;
+      }
+      writeAdsJson({ ok: true, data });
+    } catch (err) {
+      if (err instanceof ApiError) {
+        writeAdsJson(parseXApiError(err.message, accountId));
+        process.exit(1);
+      }
+      writeAdsJson({ ok: false, error: { code: "NETWORK_ERROR", message: "Unexpected error" } });
+      process.exit(1);
+    }
+  }
+});
+export {
+  audiencesCommand
+};
+//# sourceMappingURL=audiences-5TOTVZMK.js.map

package/dist/audiences-ZDOK3OYC.js

@@ -0,0 +1,106 @@
+import {
+  META_LIST_SHAPE_ARGS,
+  registerMetaListSchema,
+  shapeMetaListRows,
+  writeMetaListRows
+} from "./chunk-ZW2CN6L6.js";
+import {
+  csvOrJson,
+  handleMetaError,
+  resolveAccountIdArg
+} from "./chunk-QY7EK6Q4.js";
+import "./chunk-QALAJNBG.js";
+import "./chunk-QYH2UZAK.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-GO6ISZUZ.js";
+import "./chunk-65Y3RCWP.js";
+import {
+  apiGet
+} from "./chunk-GFWWHCBF.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/meta/audiences.ts
+import { defineCommand } from "citty";
+var listArgs = {
+  "account-id": { type: "string", description: "Meta ad account ID" },
+  "name-contains": {
+    type: "string",
+    description: "Only audiences whose name contains this text, matched by Meta before anything is returned: --name-contains Cerradas. A lookalike can be named anything, so find one audience's lookalikes with --seed <its id>"
+  },
+  seed: {
+    type: "string",
+    description: "Only the lookalikes built from this source audience id, whatever they are named: --seed 120240480760260208"
+  },
+  limit: { type: "string", description: "Max rows (default 500)" },
+  "no-cache": NO_CACHE_ARG,
+  ...META_LIST_SHAPE_ARGS
+};
+registerMetaListSchema(
+  "audiences",
+  "List custom and lookalike audiences, as a table by default: id, name, subtype, size_min, size_max, retention_days, updated_date \u2014 plus delivery (why Meta says it cannot be used) and seed_id (the audience a lookalike was built from) when a row has one. The rule, data source and pixel are one --fields away (--fields id,name,rule) or --full. Start here to find one audience: baker ads meta audiences --name-contains <text>; then its lookalikes, whatever they are named: --seed <its id>. --output json returns the rows in the envelope.",
+  listArgs
+);
+var listCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "List custom audiences. Runs by default when no subcommand is given. Example: baker ads meta audiences --name-contains buyers"
+  },
+  args: listArgs,
+  run: async ({ args }) => {
+    const accountId = await resolveAccountIdArg(args);
+    try {
+      const params = { "account-id": accountId };
+      if (args["name-contains"]) params["name-contains"] = args["name-contains"];
+      if (args.seed) params.seed = args.seed;
+      if (args.limit) params.limit = args.limit;
+      if (args["no-cache"]) params["skip-cache"] = "true";
+      const data = await apiGet("/api/ads/meta/audiences", params);
+      writeMetaListRows("audiences", shapeMetaListRows("audiences", data, args), csvOrJson(args));
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+var audiencesCommand = defineCommand({
+  meta: {
+    name: "audiences",
+    description: `List custom audiences, or stage writes (create/update/delete, members add|remove|replace). Write subcommands stage ops on this chat's draft.
+Includes lookalikes, website-pixel audiences, customer-file audiences. Meta hides exact size when count < 1000.
+
+Listings print a table by default: id, name, subtype, size_min, size_max, retention_days, updated_date, plus
+delivery and seed_id when a row has one. The rule and data source are --fields (dotted paths) or --full away.
+
+Examples:
+  baker ads meta audiences --account-id act_123
+  baker ads meta audiences --name-contains Cerradas            \u2014 find one audience by name
+  baker ads meta audiences --seed 120240480760260208           \u2014 the lookalikes built from that audience
+  baker ads meta audiences --name-contains Leads --fields id,name,rule,retention_days --output json
+  baker ads meta audiences create --name "Site 30d" --subtype WEBSITE --file rule.json
+  baker ads meta audiences create --name "Past buyers" --subtype CUSTOM --file buyers.json   # {"members":[{"email":"\u2026"}]}
+  baker ads meta audiences create --name "Customers" --subtype CUSTOM --customer-file-source USER_PROVIDED_ONLY
+  baker ads meta audiences members add meta_temp_ab12 --file customers.csv --country ES
+  baker ads meta audiences saved --account-id act_123            \u2014 saved audiences (read-only)`
+  },
+  subCommands: {
+    list: listCommand,
+    create: () => import("./write-commands-5LEEPKA7.js").then((m) => m.audiencesCreateCommand),
+    update: () => import("./write-commands-5LEEPKA7.js").then((m) => m.audiencesUpdateCommand),
+    delete: () => import("./audience-writes-5KT6FHUY.js").then((m) => m.audiencesDeleteCommand),
+    members: () => import("./audience-writes-5KT6FHUY.js").then((m) => m.audiencesMembersCommand),
+    saved: () => import("./audience-writes-5KT6FHUY.js").then((m) => m.savedAudiencesCommand)
+  },
+  // `args` stays even though the parent has no `run`: citty scans rawArgs for the
+  // subcommand name using THIS command's arg defs, so without them `--account-id act_1`
+  // would read `act_1` as a subcommand. `default` (not `run`) dispatches the bare
+  // invocation — citty falls through to `run` after a subcommand, double-executing it.
+  args: listArgs,
+  default: "list"
+});
+export {
+  audiencesCommand
+};
+//# sourceMappingURL=audiences-ZDOK3OYC.js.map

package/dist/audit-RBRXPPKK.js

@@ -0,0 +1,154 @@
+import {
+  handleLinkedinError,
+  resolveAccountIdArg
+} from "./chunk-42JTSTQ3.js";
+import {
+  writeAdsJson
+} from "./chunk-QYH2UZAK.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-GO6ISZUZ.js";
+import "./chunk-RCNAKWK7.js";
+import "./chunk-QV6AST5T.js";
+import "./chunk-WCU362Z6.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-R7XDGNZD.js";
+import "./chunk-MSMTG6OC.js";
+import {
+  apiPost
+} from "./chunk-GFWWHCBF.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/linkedin/audit.ts
+import { defineCommand } from "citty";
+var SEVERITY_RANK = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3
+};
+var STATUS_RANK = {
+  fail: 0,
+  warn: 1,
+  partial: 2,
+  pass: 3,
+  n_a: 4
+};
+function filterFindings(findings, severity, area) {
+  return findings.filter((f) => {
+    if (severity && !severity.includes(f.severity)) return false;
+    if (area && !area.includes(f.area)) return false;
+    return true;
+  });
+}
+function sortFindings(findings) {
+  return [...findings].sort((a, b) => {
+    const sa = STATUS_RANK[a.status] - STATUS_RANK[b.status];
+    if (sa !== 0) return sa;
+    return SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+  });
+}
+function renderMarkdown(result) {
+  const lines = [];
+  lines.push(`# LinkedIn Ads Audit \u2014 ${result.account.name} (${result.account.id})`);
+  lines.push("");
+  lines.push(
+    `**Scope:** ${result.scope.campaigns} campaigns, ${result.scope.creatives} creatives, last ${result.scope.windowDays}d`
+  );
+  lines.push("");
+  lines.push(
+    `**Summary:** ${result.summary.pass} pass \u2022 ${result.summary.critical} critical \u2022 ${result.summary.high} high \u2022 ${result.summary.medium} medium \u2022 ${result.summary.low} low \u2022 ${result.summary.n_a} n/a (${result.summary.totalChecks} total)`
+  );
+  lines.push("");
+  lines.push("| # | Area | Check | Status | Severity | Notes |");
+  lines.push("|---|------|-------|--------|----------|-------|");
+  result.findings.forEach((f, idx) => {
+    const note = noteOf(f);
+    lines.push(
+      `| ${idx + 1} | ${f.area} | ${escapeMd(f.check)} | ${f.status.toUpperCase()} | ${f.severity} | ${escapeMd(note)} |`
+    );
+  });
+  return lines.join("\n");
+}
+function escapeMd(text) {
+  return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function noteOf(f) {
+  if (f.status === "pass") return "";
+  const ev = f.evidence ? JSON.stringify(f.evidence) : "";
+  const fix = f.fix?.explanation ?? "";
+  return [fix, ev].filter(Boolean).join(" \u2014 ");
+}
+var auditCommand = defineCommand({
+  meta: {
+    name: "audit",
+    description: `Run a LinkedIn Ads playbook audit \u2014 30+ checks across Settings, Tracking,
+Audience, Campaigns, Creative, Performance, Bidding, and Compliance.
+
+Each finding has {id, area, check, status, severity, evidence, fix} fields with
+playbook citations. The default JSON output is agent-friendly; --format md
+renders a deliverable-ready table that mirrors the google-ads-playbook
+10-audit-summary.md style.
+
+Exit code 0 always. Use the JSON 'summary' counts to decide if action is needed.
+
+Examples:
+  baker ads linkedin audit --account-id 503001492
+  baker ads linkedin audit --account-id 503001492 --campaign-id 1234        # narrow scope
+  baker ads linkedin audit --account-id 503001492 --window-days 90
+  baker ads linkedin audit --account-id 503001492 --severity critical,high
+  baker ads linkedin audit --account-id 503001492 --area Settings,Tracking
+  baker ads linkedin audit --account-id 503001492 --format md`
+  },
+  args: {
+    "account-id": { type: "string", description: "Numeric account ID or urn:li:sponsoredAccount:N" },
+    "account-urn": { type: "string", description: "Alias for --account-id" },
+    "campaign-id": { type: "string", description: "Narrow scope to a single campaign" },
+    "window-days": { type: "string", description: "Lookback window for performance checks (default: 30)" },
+    severity: { type: "string", description: "CSV severity filter: critical,high,medium,low" },
+    area: {
+      type: "string",
+      description: "CSV area filter: Settings,Tracking,Audience,Campaigns,Creative,Performance,Bidding,Compliance,Hygiene"
+    },
+    format: { type: "string", description: "Output format: json | md (default: json)" },
+    "no-cache": NO_CACHE_ARG
+  },
+  run: async ({ args }) => {
+    const accountId = resolveAccountIdArg(args);
+    const windowDays = args["window-days"] ? Number(args["window-days"]) : 30;
+    if (!Number.isFinite(windowDays) || windowDays < 1 || windowDays > 365) {
+      handleLinkedinError(new Error("--window-days must be 1..365"));
+    }
+    try {
+      const data = await apiPost("/api/ads/linkedin/audit", {
+        accountId,
+        campaignId: args["campaign-id"] ? String(args["campaign-id"]) : void 0,
+        windowDays,
+        skipCache: Boolean(args["no-cache"])
+      });
+      const severityFilter = args.severity?.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+      const areaFilter = args.area?.split(",").map((s) => s.trim()).filter(Boolean);
+      const filtered = filterFindings(data.findings, severityFilter, areaFilter);
+      const sorted = sortFindings(filtered);
+      const result = { ...data, findings: sorted };
+      const fmt = args.format ?? "json";
+      if (fmt === "md") {
+        process.stdout.write(`${renderMarkdown(result)}
+`);
+        return;
+      }
+      writeAdsJson({ ok: true, data: result });
+    } catch (err) {
+      handleLinkedinError(err);
+    }
+  }
+});
+export {
+  auditCommand
+};
+//# sourceMappingURL=audit-RBRXPPKK.js.map

package/dist/audit-SACXTAIP.js

@@ -0,0 +1,88 @@
+import {
+  resolvePropertyId
+} from "./chunk-G4JTXVLA.js";
+import {
+  cacheGet,
+  cacheSet,
+  handleConnectionError,
+  isNotConnectedError,
+  writeJsonEnvelope
+} from "./chunk-QYH2UZAK.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-GFWWHCBF.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  registerSchema
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ga4/audit.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "ga4.audit",
+  description: "Run all GA4 admin health checks at once. Checks data retention, Google Ads linkage, phantom conversions, audience defaults, data streams, and attribution settings. Returns raw data plus playbook-aligned warnings.",
+  args: {
+    "property-id": { type: "string", description: "GA4 property ID (auto-resolved if not provided)", required: false },
+    "no-cache": { type: "boolean", description: "Skip cache, hit API directly", required: false }
+  }
+});
+var auditCommand = defineCommand({
+  meta: {
+    name: "audit",
+    description: `Run all GA4 admin health checks. Returns property config with playbook warnings.
+
+Checks:
+  - Data retention (should be FOURTEEN_MONTHS)
+  - Google Ads linkage (must match audited account)
+  - Phantom conversions (page_view, scroll as conversions)
+  - Audience membership defaults (30-day B2B traps)
+  - Data streams and filters
+  - Attribution settings
+
+Examples:
+  baker ga4 audit
+  baker ga4 audit --property-id properties/123456789`
+  },
+  args: {
+    "property-id": { type: "string", description: "GA4 property ID", required: false },
+    "no-cache": { type: "boolean", description: "Skip cache", required: false }
+  },
+  run: async ({ args }) => {
+    const propertyId = await resolvePropertyId(args);
+    const useCache = !args["no-cache"];
+    const cacheKey = `audit:${propertyId}`;
+    if (useCache) {
+      const cached = cacheGet("ga4-audit", cacheKey);
+      if (cached) {
+        writeJsonEnvelope({ ...cached.data, cached: true });
+        return;
+      }
+    }
+    try {
+      const body = { propertyId };
+      if (!useCache) body.skipCache = true;
+      const data = await apiPost("/api/ga4/audit", body);
+      if (useCache) {
+        cacheSet("ga4-audit", cacheKey, data, 6 * 60 * 60 * 1e3);
+      }
+      writeJsonEnvelope(data);
+    } catch (err) {
+      if (err instanceof ApiError) {
+        if (isNotConnectedError(err.code, err.message)) {
+          handleConnectionError("ga4", err.message);
+        }
+        writeJsonEnvelope({ ok: false, error: { code: err.code, message: err.message } });
+        process.exit(1);
+      }
+      writeJsonEnvelope({ ok: false, error: { code: "NETWORK_ERROR", message: "Unexpected error" } });
+      process.exit(1);
+    }
+  }
+});
+export {
+  auditCommand
+};
+//# sourceMappingURL=audit-SACXTAIP.js.map

package/dist/autocomplete-P5OU7QVL.js

@@ -0,0 +1,114 @@
+import {
+  noSerpRowsHints
+} from "./chunk-WGJ2QEW4.js";
+import {
+  RESEARCH_DATA_NOTE,
+  handleResearchError,
+  writeResearchHints,
+  writeResearchJson,
+  writeResearchOutput
+} from "./chunk-CXYX6G3I.js";
+import {
+  buildResearchQueryContext,
+  warnDefaults
+} from "./chunk-FVDC6AKZ.js";
+import "./chunk-SNWFM2DB.js";
+import "./chunk-RCNAKWK7.js";
+import "./chunk-QV6AST5T.js";
+import "./chunk-WCU362Z6.js";
+import "./chunk-GIWHHCD6.js";
+import "./chunk-SOPVIIUW.js";
+import "./chunk-G4FG5EQO.js";
+import "./chunk-R7XDGNZD.js";
+import "./chunk-MSMTG6OC.js";
+import {
+  apiPost
+} from "./chunk-GFWWHCBF.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import {
+  registerSchema
+} from "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/research/autocomplete.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "research.autocomplete",
+  description: "Get Google Autocomplete suggestions for a seed keyword. Useful for keyword expansion and discovering what people actually search for. If --location and --language are omitted, defaults to United States (us) and English (en).",
+  args: {
+    keyword: { type: "string", description: "Seed keyword (positional)", required: true },
+    location: {
+      type: "string",
+      description: "Country code (us, uk, es, de...) or DataForSEO location code. Defaults to us (United States) if omitted",
+      required: false
+    },
+    language: {
+      type: "string",
+      description: "Language code or name. Defaults to en (English) if omitted",
+      required: false
+    },
+    limit: { type: "string", description: "Max suggestions (default: 10, max: 20)", required: false },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  }
+});
+var FIELDS = {
+  suggestion: "Autocomplete suggestion from Google"
+};
+var autocompleteCommand = defineCommand({
+  meta: {
+    name: "autocomplete",
+    description: `Get Google Autocomplete suggestions for keyword expansion.
+
+Examples:
+  baker research autocomplete "running shoes"
+  baker research autocomplete "crm" --location uk --limit 5`
+  },
+  args: {
+    keyword: { type: "positional", description: "Seed keyword", required: true },
+    location: { type: "string", description: "Country code or location code (default: us)", required: false },
+    language: { type: "string", description: "Language code or name (default: en)", required: false },
+    limit: { type: "string", description: "Max suggestions (default: 10, max: 20)", required: false },
+    output: { type: "string", description: "Format: json|csv|md|jsonl", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip server cache, hit API directly", required: false }
+  },
+  run: async ({ args }) => {
+    const keyword = args.keyword;
+    const location = args.location || void 0;
+    const language = args.language || void 0;
+    const limit = args.limit ? Number(args.limit) : void 0;
+    const skipCache = args["no-cache"] ? true : void 0;
+    const queryContext = buildResearchQueryContext(location, language);
+    try {
+      const data = await apiPost("/api/research/autocomplete", {
+        keyword,
+        location,
+        language,
+        limit,
+        skipCache
+      });
+      warnDefaults(queryContext);
+      const format = args.output || "json";
+      const hints = noSerpRowsHints(data.length, queryContext);
+      if (format !== "json") {
+        writeResearchOutput(data, format);
+        writeResearchHints(hints, format);
+        return;
+      }
+      writeResearchJson({
+        ok: true,
+        data,
+        fields: FIELDS,
+        note: RESEARCH_DATA_NOTE,
+        query_context: queryContext,
+        hints
+      });
+    } catch (err) {
+      handleResearchError(err);
+    }
+  }
+});
+export {
+  autocompleteCommand
+};
+//# sourceMappingURL=autocomplete-P5OU7QVL.js.map

package/dist/avatars-UHBA2BQ3.js

@@ -0,0 +1,38 @@
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/avatars/index.ts
+import { defineCommand } from "citty";
+var avatarsCommand = defineCommand({
+  meta: {
+    name: "avatars",
+    description: `Reusable AI presenters this company can cast into images and video. An avatar holds one settled identity, so the same face can carry a whole campaign. Subcommands: list, get, create, research, update, delete.
+
+How casting works:
+  1. baker avatars list                       See who this company already has (reuse before you create)
+  2. baker avatars get <handle>               Status, identity sheet URL, subject description
+  3. baker images generate "<scene>" --reference <sheetUrl>
+                                              Ground the render on the identity sheet, never on a source photo,
+                                              and copy the subject description into the prompt verbatim
+
+Examples:
+  baker avatars list --status ready --output md
+  baker avatars get marta --full
+  baker avatars create --name "Marta" --subject "woman in her early 40s, shoulder-length dark hair, light olive skin"
+  baker avatars research "Lautaro Suarez, CTO at Vibiz" --create   A real, named person, from their public photos
+  baker avatars update marta --subject "\u2026" --regenerate-sheet
+  baker avatars delete marta --archive
+Full guide: __tooling__/docs/tools/baker/avatars.md`
+  },
+  subCommands: {
+    list: () => import("./list-OTZB7DOX.js").then((m) => m.listCommand),
+    get: () => import("./get-Q4M6G7YN.js").then((m) => m.getCommand),
+    create: () => import("./create-TKOG7DNJ.js").then((m) => m.createCommand),
+    research: () => import("./research-7YDQOKA6.js").then((m) => m.researchCommand),
+    update: () => import("./update-ESK6PSME.js").then((m) => m.updateCommand),
+    delete: () => import("./delete-POHL3TKX.js").then((m) => m.deleteCommand)
+  }
+});
+export {
+  avatarsCommand
+};
+//# sourceMappingURL=avatars-UHBA2BQ3.js.map