@koda-sl/baker-cli 0.384.0 → 0.385.0

package/README.md

@@ -163,7 +163,7 @@ Multi-platform ad commands. Google, Meta, and LinkedIn support both reads and **
 
 ### `baker ads google accounts`
 
-List all accessible Google Ads accounts. Run this first to find account IDs.
+List the Google Ads accounts selected for this company. Run this first to find account IDs.
 
 ```bash
 baker ads google accounts
@@ -788,7 +788,7 @@ Read X Ads campaigns, line items, promoted tweets, creatives, audiences, and ana
 
 | Subcommand | What it returns |
 |---|---|
-| `accounts` | All accessible X Ads accounts |
+| `accounts` | X Ads accounts selected for this company that X currently lists |
 | `funding` | Funding instruments for an account |
 | `campaigns` | Campaigns (filter by `--funding-instrument-ids`, `--campaign-ids`) |
 | `line-items` | Line items / ad groups (filter by `--campaign-ids`, `--line-item-ids`) |
@@ -892,7 +892,7 @@ baker ads meta insights --object act_123 --level adset \
 baker ads meta activities --account-id act_123 --days 7
 
 # "Which Page should this ad run from?"
-baker ads meta pages                                                 # Facebook Pages the user manages (tasks shows which can ADVERTISE)
+baker ads meta pages                                                 # Pages with promotingAccountIds and hasPageAccessToken
 
 # "What is the lead form collecting, and how many came in?"
 baker ads meta lead-forms --page-id 100635183117758                  # instant forms on a Page + lead counts
@@ -930,6 +930,8 @@ baker ads meta custom-conversions --account-id act_123          # id, event cate
 baker ads meta custom-conversions --account-id act_123 --full   # raw rule JSON, retention, timestamps
 ```
 
+Use a Page only with an ad account listed in its `promotingAccountIds`. Instant-form reads need `hasPageAccessToken: true` on that Page and the company's lead-ads permissions.
+
 **Custom Conversions** — a marketer's own conversion (a pixel event narrowed by a rule, e.g. "PageView on /gracias"), which is what "my conversions" almost always means. To optimize an ad set toward one, pass `--custom-conversion-id <id>` and nothing else: Baker reads the conversion off Meta at stage time and fills its pixel, event category and rule, the same four fields Ads Manager stores. Staging refuses an archived or unavailable conversion, one not built on a pixel, and one belonging to another ad account. Deleting one — in Events Manager or over the API — archives it: it leaves the panel but stays readable on the account, so the listing still shows it flagged `archived`.
 
 `custom-conversions create` stages a new one (`--name`, `--pixel-id`, `--custom-event-type`, plus `--url-contains "/gracias"` or `--rule-file`). A rule is a tree of `and`/`or` over `{"<field>":{"<operator>":<value>}}` leaves, where the field is `URL`, `event`, `referrer` or any event parameter the pixel sends (`value`, `content_category`, or your own), so `--url-contains` is only the single-URL shortcut and `--rule-file` reaches the rest. Meta accepts an unmatchable rule and reports success, so staging refuses unknown operators, bare values, empty branches and two conditions written side by side where `and` was meant, before the op is staged. A case-sensitive `contains` is a real operator and gets through — on a URL always write `i_contains`. It is create-only, because Meta's edge offers neither update nor a delete that removes — which is also why staging refuses a create whose pixel, event category and rule already exist, live on the account or staged earlier in the same chat, or one that would pass Meta's cap of 100 per account. An ad set in the same chat can chain to it with `--custom-conversion-id meta_temp_*`.
@@ -997,9 +999,8 @@ To find one entity by name, pass `--name-contains <text>` to `campaigns`, `adset
 
 ```
 accounts            # ad accounts in the connected scope
-accounts --include-all   # every account the token can see (admin/debug)
 account             # single-account detail (currency, balance, business, status)
-businesses          # /me/businesses
+businesses          # businesses linked to selected ad accounts
 campaigns           # ACTIVE-only by default
 adsets              # filter by --campaign-id
 ads                 # filter by --adset-id or --campaign-id
@@ -1125,7 +1126,6 @@ baker ads linkedin bid-pricing --account-id 503001492 \
 
 ```
 accounts                       # accounts in the connected picker scope
-accounts --include-all         # every account the token can see
 account                        # single-account detail (currency, type, status)
 
 campaign-groups                # default ACTIVE-only
@@ -1497,7 +1497,7 @@ A Google Analytics connection made before writes shipped is read-only and every
 
 ### `baker ga4 properties`
 
-List accessible GA4 properties. Run this first to find property IDs.
+List the GA4 properties selected for this company. Run this first to find property IDs.
 
 ```bash
 baker ga4 properties
@@ -3751,6 +3751,10 @@ baker schema tag-manager read   # Kebab-case paths resolve to their registered n
 
 Not every command registers a schema. On `NOT_FOUND` the error carries a structured `fix` pointing at `--help` and the family's agent doc (`__tooling__/docs/tools/baker/<family>.md` in sandboxes). Every top-level family's `--help` also ends with a `Full guide:` line pointing at that doc; `packages/cli/__tests__/doc-coverage.test.ts` fails CI if a mounted command is missing from its family doc.
 
+### `baker tag-manager containers`
+
+Lists the company's selected Tag Manager containers that the connected Google account can still open. If access to a selected container was lost, the response names it in `unavailableContainers` and asks the user to reconnect with an account that can open it.
+
 ## `baker studio` — make new imagery
 
 The generation lane. `baker images` **sources** what already exists; `baker studio` **makes** what doesn't. Every call opens a *batch* — one brief, 1-8 takes, rendered in parallel — recorded against the calling chat and shown in the dashboard Studio next to the batches the client ran themselves.

package/dist/cli.js

@@ -20545,9 +20545,8 @@ function requireTargets(args5, entity) {
 var CHAT_READ_ARG_DESCRIPTION = CHAT_READ_ARG.description;
 registerSchema({
   command: "ads.linkedin.accounts",
-  description: "List LinkedIn ad accounts in the company's connected scope. Pass --include-all to list every account the OAuth token can see.",
+  description: "List LinkedIn ad accounts in the company's connected scope.",
   args: {
-    "include-all": { type: "boolean", description: "Ignore picker scope", required: false },
     "no-cache": NO_CACHE_ARG,
     output: { type: "string", description: "json|csv|jsonl|md", required: false, default: "json" }
   }
@@ -22258,11 +22257,7 @@ Examples:
 
 // src/commands/ads/linkedin/accounts.ts
 import { defineCommand as defineCommand35 } from "citty";
-var ACCOUNTS_TTL_MS = 60 * 60 * 1e3;
-function accountHints2(accounts, includeAll) {
-  if (includeAll) {
-    return [];
-  }
+function accountHints2(accounts) {
   return connectedResourceHints({
     plural: "LinkedIn ad accounts",
     singular: "LinkedIn ad account",
@@ -22277,44 +22272,23 @@ var accountsCommand2 = defineCommand35({
 
 Examples:
   baker ads linkedin accounts
-  baker ads linkedin accounts --include-all   # ignore picker scope, list every account the token can see
   baker ads linkedin accounts --output csv`
   },
   args: {
-    "include-all": { type: "boolean", description: "List all accessible accounts, ignoring picker scope" },
     "no-cache": NO_CACHE_ARG,
     output: { type: "string", description: "Output format: json|csv|jsonl|md", default: "json" }
   },
   run: async ({ args: args5 }) => {
-    const includeAll = args5["include-all"] === true;
-    const useCache = !args5["no-cache"];
-    const cacheKey = `accounts:${includeAll ? "all" : "scoped"}`;
-    if (useCache) {
-      const cached = cacheGet("linkedin-accounts", cacheKey);
-      if (cached) {
-        writeJsonEnvelope({
-          ok: true,
-          data: cached.data,
-          cached: true,
-          hints: accountHints2(cached.data, includeAll)
-        });
-        return;
-      }
-    }
     try {
       const params = {};
-      if (includeAll) params["include-all"] = "true";
-      if (!useCache) params["skip-cache"] = "true";
+      if (args5["no-cache"]) params["skip-cache"] = "true";
       const data = await apiGet("/api/ads/linkedin/accounts", params);
-      if (useCache) {
-        cacheSet("linkedin-accounts", cacheKey, data, ACCOUNTS_TTL_MS);
-      }
       const fmt = csvOrJson2(args5);
       if (fmt !== "json") {
         writeAdsOutput(data, fmt);
         return;
       }
-      writeJsonEnvelope({ ok: true, data, hints: accountHints2(data, includeAll) });
+      writeJsonEnvelope({ ok: true, data, hints: accountHints2(data) });
     } catch (err) {
       handleLinkedinError(err);
     }
@@ -24313,7 +24287,6 @@ var linkedinCommand = defineCommand53({
 
 Discovery:
   baker ads linkedin accounts                                    \u2014 accounts in this company's connected scope
-  baker ads linkedin accounts --include-all                      \u2014 every account the token can see
   baker ads linkedin account --account-id 503001492              \u2014 single-account detail (currency, type, status)
   baker ads linkedin url-params [--ad-sets]                      \u2014 UTMs in effect today, and keys set at two levels
 
@@ -24408,10 +24381,7 @@ Examples:
 
 // src/commands/ads/meta/accounts.ts
 import { defineCommand as defineCommand55 } from "citty";
-function accountHints3(accounts, includeAll) {
-  if (includeAll) {
-    return [];
-  }
+function accountHints3(accounts) {
   return connectedResourceHints({
     plural: "Meta ad accounts",
     singular: "Meta ad account",
@@ -24429,44 +24399,23 @@ var accountsCommand3 = defineCommand55({
 
 Examples:
   baker ads meta accounts
-  baker ads meta accounts --include-all   # ignore picker scope and list every account the token can see
   baker ads meta accounts --output csv`
   },
   args: {
-    "include-all": { type: "boolean", description: "List all accessible accounts, ignoring picker scope" },
     "no-cache": NO_CACHE_ARG,
     output: { type: "string", description: "Output format: json|csv|jsonl|md", default: "json" }
   },
   run: async ({ args: args5 }) => {
-    const includeAll = args5["include-all"] === true;
-    const useCache = !args5["no-cache"];
-    const cacheKey = `accounts:${includeAll ? "all" : "scoped"}`;
-    if (useCache) {
-      const cached = cacheGet("meta-accounts", cacheKey);
-      if (cached) {
-        writeJsonEnvelope({
-          ok: true,
-          data: cached.data,
-          cached: true,
-          hints: accountHints3(cached.data, includeAll)
-        });
-        return;
-      }
-    }
     try {
       const params = {};
-      if (includeAll) params["include-all"] = "true";
-      if (!useCache) params["skip-cache"] = "true";
+      if (args5["no-cache"]) params["skip-cache"] = "true";
       const data = await apiGet("/api/ads/meta/accounts", params);
-      if (useCache) {
-        cacheSet("meta-accounts", cacheKey, data, 60 * 60 * 1e3);
-      }
       const fmt = csvOrJson(args5);
       if (fmt !== "json") {
         writeAdsOutput(data, fmt);
         return;
       }
-      writeJsonEnvelope({ ok: true, data, hints: accountHints3(data, includeAll) });
+      writeJsonEnvelope({ ok: true, data, hints: accountHints3(data) });
     } catch (err) {
       handleMetaError(err);
     }
@@ -27352,7 +27301,7 @@ import { defineCommand as defineCommand61 } from "citty";
 var businessesCommand = defineCommand61({
   meta: {
     name: "businesses",
-    description: `List Meta Business Manager accounts the connected user has access to. Required for ad-studies and product-catalogs commands.
+    description: `List Meta Business Manager accounts linked to this company's selected ad accounts. Required for ad-studies and product-catalogs commands.
 
 Examples:
   baker ads meta businesses`
@@ -28222,9 +28171,13 @@ Async is automatic for heavy queries; pass --async to force it, or --no-async to
 import { defineCommand as defineCommand67 } from "citty";
 registerSchema({
   command: "ads.meta.lead-forms",
-  description: "List the instant (lead) forms on a Facebook Page, with how many leads each has collected. Start here: a lead is fetched by form id, and `baker ads meta pages` gives the page id.",
+  description: "List the instant (lead) forms on a Facebook Page, with how many leads each has collected. Start here: a lead is fetched by form id. Use a Page from `baker ads meta pages` with hasPageAccessToken: true.",
   args: {
-    "page-id": { type: "string", description: "Facebook Page ID \u2014 from `baker ads meta pages`", required: true },
+    "page-id": {
+      type: "string",
+      description: "Facebook Page ID \u2014 from `baker ads meta pages` with hasPageAccessToken: true",
+      required: true
+    },
     full: { type: "boolean", description: "Include each form's questions", required: false },
     output: { type: "string", description: "json|csv", required: false, default: "json" }
   }
@@ -28297,7 +28250,7 @@ function leadPageHints(page, full) {
 var leadFormsCommand2 = defineCommand67({
   meta: {
     name: "lead-forms",
-    description: `List the instant (lead) forms on a Facebook Page, with each form's lead count. A lead is read by form id, so start here \u2014 get the Page id from \`baker ads meta pages\`.
+    description: `List the instant (lead) forms on a Facebook Page, with each form's lead count. A lead is read by form id, so start here \u2014 get a Page id with hasPageAccessToken: true from \`baker ads meta pages\`.
 
 Examples:
   baker ads meta lead-forms --page-id 100635183117758
@@ -28312,7 +28265,11 @@ Examples:
     try {
       const pageId = args5["page-id"];
       if (!pageId) {
-        handleLeadsError(new Error("--page-id is required. Run `baker ads meta pages` to find it."));
+        handleLeadsError(
+          new Error(
+            "--page-id is required. Run `baker ads meta pages` and choose a Page with hasPageAccessToken: true."
+          )
+        );
       }
       const params = { "page-id": pageId };
       if (args5.full) params.full = "true";
@@ -28398,27 +28355,21 @@ var metaMediaCommand = defineCommand68({
 
 // src/commands/ads/meta/pages.ts
 import { defineCommand as defineCommand69 } from "citty";
-function advertisablePages(data) {
-  return data.filter((p) => Array.isArray(p.tasks) && p.tasks.includes("ADVERTISE"));
-}
 function pageSelectionHints(data) {
-  const advertisable = advertisablePages(data);
-  if (advertisable.length > 1) {
-    return [
-      "MULTIPLE Pages can run ads \u2014 do NOT guess. Confirm with the user which Page an ad should run from before passing --page to `creatives create`; a wrong Page publishes the ad under the wrong brand identity and staging will not catch it."
-    ];
-  }
-  if (data.length > 0 && advertisable.length === 0) {
+  if (data.length === 0) return [];
+  const accountHint = "Use a Page only with an ad account listed in its promotingAccountIds. hasPageAccessToken must be true to read instant forms; null means Meta could not check it. Form reads also require the company's lead-ads permissions.";
+  if (data.length > 1) {
     return [
-      "NO Page can run ads \u2014 none of the connected user's Pages carry the ADVERTISE task. Ask the user to grant Advertise access to the right Page before creating an ad; a readable-but-non-advertising Page still passes staging and would fail or run under the wrong identity."
+      accountHint,
+      "MULTIPLE Pages can run ads from the selected Meta ad accounts \u2014 do NOT guess. Confirm with the user which Page an ad should run from before passing --page to `creatives create`; a wrong Page publishes the ad under the wrong brand identity and staging will not catch it."
     ];
   }
-  return [];
+  return [accountHint];
 }
 var pagesCommand = defineCommand69({
   meta: {
     name: "pages",
-    description: `List the Facebook Pages the connected user manages. Every Meta ad publishes from a Page, so use this to identify the Page an ad should run from. The 'tasks' field shows what the user can do on each Page (ADVERTISE means it can back ads). If exactly one Page can ADVERTISE, use it; if more than one can, confirm with the user which Page to use; if none can, ask the user to grant Advertise access \u2014 a wrong or non-advertising Page publishes under the wrong brand identity.
+    description: `List the Facebook Pages that the selected Meta ad accounts can promote, showing which accounts can promote each Page. Every Meta ad publishes from a Page, so match its promotingAccountIds to the target account. hasPageAccessToken shows whether the connected person can also read that Page's instant forms. If more than one Page is listed, confirm the brand with the user.
 
 Examples:
   baker ads meta pages`
@@ -28677,9 +28628,8 @@ var metaCommand = defineCommand72({
 
 Discovery:
   baker ads meta accounts                                \u2014 accounts in this company's connected scope
-  baker ads meta accounts --include-all                  \u2014 every account the token can see
   baker ads meta businesses                              \u2014 Business Manager IDs
-  baker ads meta pages                                   \u2014 Facebook Pages the user manages (an ad's identity)
+  baker ads meta pages                                   \u2014 Facebook Pages the selected ad accounts can promote (an ad's identity)
   baker ads meta lead-forms --page-id 100635183117758    \u2014 instant (lead) forms on a Page, with lead counts
   baker ads meta leads --form-id 987654321               \u2014 the leads one form collected (contact details masked)
 
@@ -66965,7 +66915,7 @@ var draftCommand5 = defineCommand218({
 import { defineCommand as defineCommand219 } from "citty";
 registerSchema({
   command: "tagManager.containers",
-  description: "List the Google Tag Manager containers this company's connection can reach. Every container the company connected is flagged `connected: true` \u2014 there can be several, and Baker may read and change all of them. Start here to confirm which containers you are managing.",
+  description: "List the Google Tag Manager containers this company selected. There can be several, and Baker may read and change all of them. Start here to confirm which containers you are managing.",
   args: {}
 });
 registerSchema({
@@ -66986,27 +66936,34 @@ registerSchema({
     full: { type: "boolean", description: "Include the raw Tag Manager object for each entity", required: false }
   }
 });
-function containersHints(containers) {
-  const connected = containers.filter((container) => container.connected);
-  if (connected.length === 0) {
-    return [
-      "None of the containers this company connected came back from Tag Manager. The connected Google account may have lost access to them \u2014 ask the user to reconnect or pick a container again."
-    ];
-  }
-  return connectedResourceHints({
+function containersHints(containers, unavailableContainers = []) {
+  const hints2 = connectedResourceHints({
     plural: "Tag Manager containers",
     singular: "Tag Manager container",
     flag: "--container",
-    resources: connected.map((container) => ({
+    resources: containers.map((container) => ({
       id: container.containerId,
       label: `${container.publicId} \xB7 ${container.name}`
     }))
   });
+  if (unavailableContainers.length > 0) {
+    const [available] = containers;
+    if (containers.length === 1 && available) {
+      hints2.length = 0;
+      hints2.push(
+        `Use --container ${available.containerId} for ${available.publicId} (${available.name}); another selected container cannot be opened.`
+      );
+    }
+    hints2.push(
+      `Tag Manager cannot open ${unavailableContainers.map((container) => `${container.publicId} (${container.name})`).join(", ")}. Ask the user to reconnect with a Google account that has access to these containers.`
+    );
+  }
+  return hints2;
 }
 var containersCommand = defineCommand219({
   meta: {
     name: "containers",
-    description: `List Tag Manager containers reachable by this company's connection.
+    description: `List Tag Manager containers selected by this company.
 
 Start here:
   baker tag-manager containers`
@@ -67014,7 +66971,7 @@ Start here:
   run: async () => {
     try {
       const data = await apiGet("/api/tag-manager/containers");
-      writeJsonEnvelope({ ok: true, data, hints: containersHints(data.containers) });
+      writeJsonEnvelope({ ok: true, data, hints: containersHints(data.containers, data.unavailableContainers) });
     } catch (err) {
       handleError8(err);
     }