@koda-sl/baker-cli 0.553.0 → 0.555.0

package/README.md

@@ -923,6 +923,8 @@ baker ads google draft validate --full       # every op, with the built request
 baker ads google draft show g_temp_ab12      # full staged payload — the receipt before publish
 baker ads google draft amend g_temp_ab12 --patch '{"amountMicros": 60000000}'   # update in place, never remove+recreate
 baker ads google draft remove g_temp_ab12    # cascades to dependents
+baker ads google draft remove g_temp_a g_temp_b g_temp_c    # many refs, one call, one summary
+baker ads google draft amend --where kind=google.keyword.add,under=g_temp_c1,matchType=EXACT --patch '{"matchType":"BROAD"}'   # select by kind/parent/payload field; --dry-run to preview
 baker ads google draft clear
 
 # Read an earlier chat's changes (read-only; staging stays on the current chat)
@@ -980,7 +982,7 @@ Command groups: `account` (update), `budgets` (create/update/remove), `campaigns
 
 **Batch keyword adds** — `keywords add`, `negative-keywords add`, and `keyword-lists add` take a whole batch in one command: comma-separate `--text` entries and/or pass `--file <list.txt>` (one keyword per line). A `:EXACT`/`:PHRASE`/`:BROAD` suffix per entry overrides the `--match-type` default. Batches stage all-or-nothing as one request (limit 500); each keyword still lands as its own draft op, so it stays individually removable/amendable.
 
-**Bulk changes — one file, one call** — `draft stage --file ops.json [--customer-id <id>]` stages up to 500 ops of any mix of kinds in one request: the file is a JSON array (or JSON Lines) of whole ops `{"kind","customerId"?,"target"?,"payload"?}`; `--customer-id` fills ops that leave it out. All-or-nothing on validity (an error names `ops[i]`); ops the account already satisfies come back as `skipped`. An op may name a `g_temp_*` ref from an earlier call, not one from the same file. `draft amend --file amends.json` (no ref) amends many staged ops at once from `[{"ref","patch"}, …]`, all or none. The `--file` create commands (`assets create|attach`, `audiences create`, `conversions create`, `bidding-strategies create`, `labels attach`, `campaign-criteria add`, `ad-group-criteria add`) take a JSON array of payloads too. `keywords pause|resume <target>…` (or `--file`, one resource name per line) change many keywords' status in one call, and `keyword-lists remove --list-ref <id> --text "a,b:EXACT"` takes terms out of a shared negative list — the CLI reads the list to find each member (no `:MATCH_TYPE` = every match type), or takes members by resource name / `listId~criterionId`. Five single stages of one kind in a row on a chat earn a `LOOP:` hint pointing at these. A chat's draft holds any number of ops (each is its own record); only one op over `GOOGLE_DRAFT_OP_MAX_BYTES` (512 KB) is refused — the stage or amend stages nothing and answers `OP_TOO_LARGE` with an `error.fix` (split that change).
+**Bulk changes — one file, one call** — `draft stage --file ops.json [--customer-id <id>]` stages up to 500 ops of any mix of kinds in one request: the file is a JSON array (or JSON Lines) of whole ops `{"kind","customerId"?,"target"?,"payload"?}`; `--customer-id` fills ops that leave it out. All-or-nothing on validity (an error names `ops[i]`); ops the account already satisfies come back as `skipped`. An op may name a `g_temp_*` ref from an earlier call, not one from the same file. `draft amend --file amends.json` (no ref) amends many staged ops at once from `[{"ref","patch"}, …]`, all or none. Several refs (`draft amend g_temp_a g_temp_b --patch '{…}'`) or `--where kind=…,under=…,<payload field>=…` take one patch the same way, and `draft remove` takes several refs or `--where` too. Every platform's `draft remove` (and `draft amend`, where it has one) takes several refs, space- or comma-separated, and prints one summary. The `--file` create commands (`assets create|attach`, `audiences create`, `conversions create`, `bidding-strategies create`, `labels attach`, `campaign-criteria add`, `ad-group-criteria add`) take a JSON array of payloads too. `keywords pause|resume <target>…` (or `--file`, one resource name per line) change many keywords' status in one call, and `keyword-lists remove --list-ref <id> --text "a,b:EXACT"` takes terms out of a shared negative list — the CLI reads the list to find each member (no `:MATCH_TYPE` = every match type), or takes members by resource name / `listId~criterionId`. Five single stages of one kind in a row on a chat earn a `LOOP:` hint pointing at these. A chat's draft holds any number of ops (each is its own record); only one op over `GOOGLE_DRAFT_OP_MAX_BYTES` (512 KB) is refused — the stage or amend stages nothing and answers `OP_TOO_LARGE` with an `error.fix` (split that change).
 
 **Pausing or removing a keyword returns a per-ad-group hint** — `keywords update --status PAUSED|REMOVED` and `keywords remove` come back with hints telling you to base the decision on `keyword_view` rows carrying `ad_group.id` + `ad_group_criterion.criterion_id`, never on campaign totals. A keyword's criterion id is derived from its text + match type, so every copy of the same keyword across ad groups shares one id and any aggregate blends the copy holding the history with the copies that never served. The `keyword-analysis` and `positive-keywords` presets select both ids so one query identifies each copy. A bid or URL edit gets no hint — only a pause/removal can strand history.
 
@@ -3445,7 +3447,7 @@ baker images extract https://stripe.com --auto-ingest 5
 baker images extract https://example.com --wait-for 1500 --limit 20
 ```
 
-Every image extracted from a page shares the scraped-page URL as `externalUrl`. Big pages can return 100+ images — cap auto-ingest at 20.
+Every image extracted from a page shares the scraped-page URL as `externalUrl`. `--limit` takes 1-50 (default 50). Big pages can return 100+ images — cap auto-ingest at 20.
 
 A failed extract says which kind of failure it was, with `retryable` and a `fix`:
 
@@ -3455,6 +3457,8 @@ A failed extract says which kind of failure it was, with `retryable` and a `fix`
 | `VALIDATION_ERROR` | The page itself refused (e.g. HTTP 404) or is too large to read | Do not retry; fall back |
 | `INTERNAL_ERROR` | A fault on Baker's side | Do not retry; fall back |
 
+A flag out of range (`--limit 60`) is caught before the call — on `extract`, `stock` and `google` alike — a `VALIDATION_ERROR` whose `fix` (`retry_with_changes`) names the flag and the range it takes. A refusal that is not about the page (`FORBIDDEN`, `UNAUTHORIZED`) carries no fallback.
+
 The fallback is `baker images screenshot <url>` for the page as one image, or `baker images logo <domain>` for the brand's mark. A `503` from any command now maps to `UNAVAILABLE` instead of `INTERNAL_ERROR`.
 
 **Flags:**
@@ -3747,7 +3751,7 @@ Response:
 
 Remote image URLs and/or library image ids → local files. The missing first half of `source → download → normalize → place`: `normalize` refuses URLs and takes no library ids, so without this the only route to disk was `curl`. Local-only, like `normalize` / `crop` / `dimensions` — bytes go straight to disk, never through the backend.
 
-Targets are space- or comma-separated and may mix both kinds. `--out` is a directory (which must exist) or, with a single target, an exact file path; it defaults to the working directory. Names that would collide are disambiguated, and the extension is derived from the response content type.
+Targets are space- or comma-separated and may mix both kinds. `--out` is a directory (created if it does not exist yet; write it with a trailing `/`) or, with a single target, an exact file path, whose folder is created too; it defaults to the working directory. Names that would collide are disambiguated, and the extension is derived from the response content type.
 
 ```bash
 baker images download https://media.withbaker.com/…/logo.webp
@@ -3755,7 +3759,7 @@ baker images download j57abc123 j57def456 --out src/pages/pricing/_images/
 baker images download https://…/hero.png --out ./hero.png
 ```
 
-Response lists what landed and what didn't — a partial failure is still `ok: true`, with the failures in `failed[]` and a hint saying so. Every target failing is `DOWNLOAD_FAILED`. Passing a path that is already on disk is a `VALIDATION_ERROR` whose `fix` points at using the local transforms directly.
+Response lists what landed and what didn't — a partial failure is still `ok: true`, with the failures in `failed[]` and a hint saying so. Every target failing is `DOWNLOAD_FAILED`, and each entry in `failed[]` carries a `cause` (`write`, `too_large`, `library`, `refused` for a 403/404 or any other refusal (another 4xx, a security check, an address not on the public web), `unavailable` only for a 5xx or no answer); the `fix` is built from those causes, so a file over the size limit, a local write error or a host that is only down is not reported as a host refusing the bytes. Passing a path that is already on disk is a `VALIDATION_ERROR` whose `fix` points at using the local transforms directly.
 
 Only addresses on the public web are fetched. A URL pointing at loopback, a private range or a link-local address is declined before any request is made — it holds nothing this command could usefully download. The same rule covers the canvas scaffolders and the shared image reader.
 

package/dist/account-H5CL6KUY.js

@@ -0,0 +1,82 @@
+import {
+  csvOrJson,
+  handleLinkedinError,
+  resolveAccountIdArg
+} from "./chunk-OTFHIGEO.js";
+import {
+  writeAdsJson,
+  writeAdsOutput
+} from "./chunk-QYH2UZAK.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-GO6ISZUZ.js";
+import "./chunk-MKLAZD23.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 {
+  apiGet
+} from "./chunk-GFWWHCBF.js";
+import "./chunk-JXTNP3B5.js";
+import "./chunk-45D6WRCJ.js";
+import "./chunk-CCYZJMZ7.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/linkedin/account.ts
+import { defineCommand } from "citty";
+var accountDetailCommand = defineCommand({
+  meta: {
+    name: "detail",
+    description: `Single LinkedIn ad account detail (currency, status, type).
+
+Examples:
+  baker ads linkedin account --account-id 503001492
+  baker ads linkedin account --account-urn urn:li:sponsoredAccount:503001492 --output md`
+  },
+  args: {
+    "account-id": { type: "string", description: "Numeric account ID or urn:li:sponsoredAccount:N" },
+    "account-urn": { type: "string", description: "Alias for --account-id" },
+    "no-cache": NO_CACHE_ARG,
+    output: { type: "string", description: "json|csv|jsonl|md", default: "json" }
+  },
+  run: async ({ args }) => {
+    const accountId = resolveAccountIdArg(args);
+    try {
+      const params = { "account-id": accountId };
+      if (args["no-cache"]) params["skip-cache"] = "true";
+      const data = await apiGet("/api/ads/linkedin/account", params);
+      const fmt = csvOrJson(args);
+      if (fmt !== "json") {
+        writeAdsOutput([data], fmt);
+        return;
+      }
+      writeAdsJson({ ok: true, data });
+    } catch (err) {
+      handleLinkedinError(err);
+    }
+  }
+});
+var accountCommand = defineCommand({
+  meta: {
+    name: "account",
+    description: `LinkedIn ad account: its detail, and the settings that apply across every ad set in it.
+
+Examples:
+  baker ads linkedin account --account-id 503001492                          \u2014 currency, status, type
+  baker ads linkedin account url-params --param utm_source=linkedin          \u2014 UTMs for every ad in the account`
+  },
+  subCommands: {
+    detail: accountDetailCommand,
+    "url-params": () => import("./write-commands-3U5ZMIHH.js").then((m) => m.accountUrlParamsCommand)
+  },
+  args: accountDetailCommand.args,
+  default: "detail"
+});
+export {
+  accountCommand
+};
+//# sourceMappingURL=account-H5CL6KUY.js.map

package/dist/account-assets-QMKT5AT7.js

@@ -0,0 +1,290 @@
+import {
+  csvOrJson,
+  handleMetaError,
+  resolveAccountIdArg
+} from "./chunk-QY7EK6Q4.js";
+import "./chunk-QALAJNBG.js";
+import {
+  writeAdsOutput,
+  writeJsonEnvelope
+} from "./chunk-QYH2UZAK.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-GO6ISZUZ.js";
+import {
+  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/meta/account-assets.ts
+import { defineCommand } from "citty";
+function emit(rows, args, hints) {
+  const fmt = csvOrJson(args);
+  if (fmt !== "json") {
+    writeAdsOutput(rows, fmt, void 0, hints);
+    return;
+  }
+  writeJsonEnvelope(hints.length > 0 ? { ok: true, data: rows, hints } : { ok: true, data: rows });
+}
+async function read(path, params, args) {
+  if (args["no-cache"]) params["skip-cache"] = "true";
+  return await apiGet(path, params);
+}
+var outputArg = { type: "string", description: "json|csv|jsonl|md", default: "json" };
+var accountArg = { type: "string", description: "Meta ad account ID (act_...)" };
+var schemaAccount = { type: "string", description: "Meta ad account ID (act_123)", required: false };
+var schemaNoCache = { type: "boolean", description: "Bypass the cache", required: false };
+var schemaOutput = { type: "string", description: "json|csv|jsonl|md", required: false, default: "json" };
+function instagramIdentityHints(rows) {
+  if (rows.length === 0) {
+    return [
+      "No Instagram account is linked to this ad account or its Pages. A creative without --instagram-user cannot run in Instagram feeds, Stories or Reels \u2014 the account owner links one in Meta Business settings (Accounts \u2192 Instagram accounts) and assigns it to the ad account."
+    ];
+  }
+  const listed = rows.filter((row) => row.sources.includes("ad_account") || row.sources.includes("connected"));
+  const hints = ["Pass the id as `creatives create --instagram-user <id>`."];
+  if (listed.length > 0 && listed.length < rows.length) {
+    hints.push(
+      `Use one listed on the ad account (${listed.map((row) => row.username ?? row.id).join(", ")}): when the account lists any, staging refuses an identity it does not list.`
+    );
+  } else if (listed.length === 0) {
+    hints.push(
+      "Only Page identities are listed (page = the Page's linked Instagram account, page_backed = an Instagram presence Meta made for a Page with none). Meta accepts either as --instagram-user; a page_backed one shows the Page's name and picture on Instagram."
+    );
+  }
+  if (new Set(rows.map((row) => row.pageId).filter(Boolean)).size > 1) {
+    hints.push("Several Pages are involved \u2014 use the identity of the Page the creative runs from (--page).");
+  }
+  return hints;
+}
+registerSchema({
+  command: "ads.meta.instagram-accounts",
+  description: "The Instagram accounts an ad on this account can run as \u2014 the id `creatives create --instagram-user` takes. Lists accounts assigned or connected to the ad account and each promotable Page's linked or page-backed one.",
+  args: {
+    "account-id": schemaAccount,
+    "no-cache": schemaNoCache,
+    output: { type: "string", description: "json|csv", required: false, default: "json" }
+  }
+});
+var instagramAccountsCommand = defineCommand({
+  meta: {
+    name: "instagram-accounts",
+    description: "Instagram identities an ad can run as (the --instagram-user id). Start here before creatives create: baker ads meta instagram-accounts --account-id act_123"
+  },
+  args: { "account-id": accountArg, "no-cache": NO_CACHE_ARG, output: outputArg },
+  run: async ({ args }) => {
+    const accountId = await resolveAccountIdArg(args);
+    try {
+      const rows = await read(
+        "/api/ads/meta/instagram-accounts",
+        { "account-id": accountId },
+        args
+      );
+      emit(
+        rows.map((row) => ({ ...row, sources: row.sources.join(",") })),
+        args,
+        instagramIdentityHints(rows)
+      );
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+registerSchema({
+  command: "ads.meta.apps",
+  description: "The apps this ad account can promote (app installs / app engagement), with their store URLs \u2014 the application_id and object_store_url an app ad set's promoted_object takes.",
+  args: { "account-id": schemaAccount, "no-cache": schemaNoCache, output: schemaOutput }
+});
+var appsCommand = defineCommand({
+  meta: {
+    name: "apps",
+    description: "Apps the ad account can promote, for an app ad set's promoted_object. Example: baker ads meta apps --account-id act_123"
+  },
+  args: { "account-id": accountArg, "no-cache": NO_CACHE_ARG, output: outputArg },
+  run: async ({ args }) => {
+    const accountId = await resolveAccountIdArg(args);
+    try {
+      const rows = await read(
+        "/api/ads/meta/apps",
+        { "account-id": accountId },
+        args
+      );
+      emit(
+        rows.map((row) => ({ ...row })),
+        args,
+        rows.length > 0 ? [
+          'An app ad set promotes one: promoted_object {"application_id":"<id>","object_store_url":"<store url>"}. Use a real store URL (itunes / google_play); fb_canvas and instant_game are not app stores.'
+        ] : [
+          "No promotable apps. The app has to be registered in Meta for Developers and its owner has to add this ad account under the app's Advanced settings \u2192 Advertising accounts."
+        ]
+      );
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+registerSchema({
+  command: "ads.meta.dsa-recommendations",
+  description: "Names Meta suggests for the EU Digital Services Act disclosure (who benefits from and who pays for an ad) on this account.",
+  args: { "account-id": schemaAccount, "no-cache": schemaNoCache }
+});
+var dsaRecommendationsCommand = defineCommand({
+  meta: {
+    name: "dsa-recommendations",
+    description: "Meta's suggested DSA beneficiary/payor names for EU ad sets. Example: baker ads meta dsa-recommendations --account-id act_123"
+  },
+  args: { "account-id": accountArg, "no-cache": NO_CACHE_ARG },
+  run: async ({ args }) => {
+    const accountId = await resolveAccountIdArg(args);
+    try {
+      const names = await read("/api/ads/meta/dsa-recommendations", { "account-id": accountId }, args);
+      writeJsonEnvelope({
+        ok: true,
+        data: names,
+        hints: [
+          "An ad set reaching the EU needs dsa_beneficiary and dsa_payor. When they are missing Baker fills both from the ad account's saved EU advertiser and payer, else the first of these, else the business name; pass one of these instead when the user names someone else (an agency paying for a client)."
+        ]
+      });
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+function compactImage(row) {
+  return {
+    hash: row.hash,
+    name: row.name,
+    width: row.width,
+    height: row.height,
+    status: row.status,
+    created_time: row.created_time
+  };
+}
+registerSchema({
+  command: "ads.meta.images",
+  description: "The ad account's image library \u2014 each image_hash a creative can reuse without uploading again. --hash looks one up.",
+  args: {
+    "account-id": schemaAccount,
+    hash: { type: "string", description: "One image hash", required: false },
+    limit: { type: "string", description: "Max rows (default 500)", required: false },
+    full: { type: "boolean", description: "URLs, permalink and which creatives use it", required: false },
+    "no-cache": schemaNoCache,
+    output: schemaOutput
+  }
+});
+var imagesCommand = defineCommand({
+  meta: {
+    name: "images",
+    description: "Image library of the ad account (image hashes). Example: baker ads meta images --account-id act_123 --limit 20; --hash <hash> for one"
+  },
+  args: {
+    "account-id": accountArg,
+    hash: { type: "string", description: "Look up one image hash" },
+    limit: { type: "string", description: "Max rows (default 500)" },
+    full: { type: "boolean", description: "Every field: url, permalink_url, creatives" },
+    "no-cache": NO_CACHE_ARG,
+    output: outputArg
+  },
+  run: async ({ args }) => {
+    const accountId = await resolveAccountIdArg(args);
+    const params = { "account-id": accountId };
+    if (args.hash) params.hash = args.hash;
+    if (args.limit) params.limit = args.limit;
+    try {
+      const rows = await read("/api/ads/meta/images", params, args);
+      emit(args.full ? rows : rows.map(compactImage), args, [
+        "A creative reuses one with its hash (the `image_hash` of a creative file). To push a Baker-library image, stage `media upload` instead."
+      ]);
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+registerSchema({
+  command: "ads.meta.labels",
+  description: "Ad labels defined on the account (Meta's tags for campaigns, ad sets, ads and creatives).",
+  args: { "account-id": schemaAccount, "no-cache": schemaNoCache, output: schemaOutput }
+});
+var labelsListArgs = { "account-id": accountArg, "no-cache": NO_CACHE_ARG, output: outputArg };
+var labelsCommand = defineCommand({
+  meta: {
+    name: "labels",
+    description: `Ad labels on the account (list), or stage label writes: create, rename, delete, attach (file campaigns/ad sets/ads/creatives under one), detach.
+  baker ads meta labels --account-id act_123
+  baker ads meta labels create --name "Q4 launch"
+  baker ads meta labels attach <labelId|meta_temp_\u2026> --campaigns 6123,6124 --ads 6125`
+  },
+  subCommands: {
+    list: () => labelsListCommand,
+    create: () => import("./asset-writes-JVFE457M.js").then((m) => m.labelsCreateCommand),
+    rename: () => import("./asset-writes-JVFE457M.js").then((m) => m.labelsRenameCommand),
+    delete: () => import("./asset-writes-JVFE457M.js").then((m) => m.labelsDeleteCommand),
+    attach: () => import("./asset-writes-JVFE457M.js").then((m) => m.labelsAttachCommand),
+    detach: () => import("./asset-writes-JVFE457M.js").then((m) => m.labelsDetachCommand)
+  },
+  args: labelsListArgs,
+  default: "list"
+});
+var labelsListCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "Ad labels on the account. Runs by default. Example: baker ads meta labels --account-id act_123"
+  },
+  args: labelsListArgs,
+  run: async ({ args }) => {
+    const accountId = await resolveAccountIdArg(args);
+    try {
+      const rows = await read("/api/ads/meta/labels", { "account-id": accountId }, args);
+      emit(rows, args, rows.length === 0 ? ["This account has no ad labels."] : []);
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+registerSchema({
+  command: "ads.meta.high-demand-periods",
+  description: "The budget boosts (high-demand periods) set on a campaign or ad set: when each runs and by how much.",
+  args: {
+    "campaign-id": { type: "string", description: "Campaign or ad set ID", required: true },
+    "no-cache": schemaNoCache,
+    output: schemaOutput
+  }
+});
+var highDemandPeriodsCommand = defineCommand({
+  meta: {
+    name: "high-demand-periods",
+    description: "Budget boosts on a campaign or ad set. Example: baker ads meta high-demand-periods --campaign-id 6123 (stage new ones with --budget-boost on campaigns or adsets create|update)"
+  },
+  args: {
+    "campaign-id": { type: "string", description: "Campaign (or ad set) ID", required: true },
+    "no-cache": NO_CACHE_ARG,
+    output: outputArg
+  },
+  run: async ({ args }) => {
+    try {
+      const rows = await read(
+        "/api/ads/meta/high-demand-periods",
+        { "campaign-id": args["campaign-id"] },
+        args
+      );
+      emit(rows, args, rows.length === 0 ? ["No budget boosts on this campaign."] : []);
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+export {
+  appsCommand,
+  dsaRecommendationsCommand,
+  highDemandPeriodsCommand,
+  imagesCommand,
+  instagramAccountsCommand,
+  instagramIdentityHints,
+  labelsCommand
+};
+//# sourceMappingURL=account-assets-QMKT5AT7.js.map