@koda-sl/baker-cli 0.449.0 → 0.451.0-dev.b2a4eba2b

package/README.md

@@ -36,7 +36,7 @@ export BAKER_X_ADS_ACCOUNT_ID="18ce53xyz"
 export BAKER_CHAT_ID="<chat-id>"
 ```
 
-- `BAKER_API_KEY` must start with `bk_` (or `bkr_` for the read-only credential a Session review runs with)
+- `BAKER_API_KEY` must start with `bk_` (or `bkr_` for the read-only credential a Session review runs with, or `bkv_` for the one a published report runs with)
 - A missing or malformed `BAKER_API_KEY` / `BAKER_API_URL` ends any command that talks to Baker with `NOT_CONFIGURED` (non-retryable, with a `fix`) naming the variable and the rule it broke — never its value
 - A malformed `BAKER_GOOGLE_ADS_CUSTOMER_ID`, `BAKER_LINKEDIN_AD_ACCOUNT_ID` or `BAKER_X_ADS_ACCOUNT_ID` ends it with `VALIDATION_ERROR` instead, whose `fix` says to correct or unset the variable
 - `BAKER_API_URL` is your Convex site URL — the deployment the CLI talks to, not an address to show anybody
@@ -3726,11 +3726,11 @@ Read and shape this workspace's Forms (flows). Operates on the local `_data.json
 
 For ChatGPT Ads conversions, add a `chatgptAds` side effect to the Form step, choose a supported event name, and use `baker flows map` to map `advancedMatching` and optional `eventParams` (`value` and `currency`).
 
-**A Form has two halves, split by a trust boundary.** Its *structure* — steps, conditions, side effects, field mappings — is yours, and the write subcommands below edit exactly that. Its *confidential* half — connection secrets, OAuth accounts, third-party field definitions (HubSpot, Calendly, HighLevel, SavvyCal) — is configured through the `request_flow_input` tool (`baker_ui` MCP server): the agent authors the surrounding structure and references it by `nodeId`/`sideEffectId`, and the user enters secrets, connects accounts, and picks resources in the dashboard. Those values are written (encrypted, where a secret) into the Form on the chat's branch and go live when the chat is published. Nothing any of these commands does touches a live system.
+**A Form has two halves, split by a trust boundary.** Its *structure* — steps, conditions, side effects, field mappings — is yours, and the write subcommands below edit exactly that. Its *confidential* half — connection secrets, OAuth accounts, third-party field definitions (HubSpot, Calendly, HighLevel, SavvyCal) — is set with `baker flows connect` whenever the agent knows the answer (an email's recipients and subject always; a connected platform's resource; a webhook with no token), and otherwise through the `request_flow_input` tool (`baker_ui` MCP server): the agent authors the surrounding structure and references it by `nodeId`/`sideEffectId`, and the user enters secrets, connects accounts, and picks resources in the dashboard. Those values are written (encrypted, where a secret) into the Form on the chat's branch and go live when the chat is published. Nothing any of these commands does touches a live system.
 
 ```bash
 baker flows list                                   # every Form + how many confidential fields still need setup
-baker flows show contact                           # confidential fields + whether the destination changed under this Form
+baker flows show contact                           # confidential fields, where each sealed destination sends (never a credential), and drift
 baker flows show contact --full                    # include the full flow tree (secret values redacted)
 
 baker flows schema                                 # both vocabularies + the customForm field types
@@ -3746,6 +3746,8 @@ baker flows connect contact --node book --resource <id>          # fill a Calend
 baker flows connect contact --side-effect se-gsheet-1 --resource <spreadsheetId>   # a sheet Baker can reach (--tab to pick the tab)
 baker flows connect contact --side-effect se-gsheet-1 --new-sheet "Contact leads" --columns "Name,Email"   # create one and wire it
 baker flows connect contact --side-effect se-pipedrive-1         # Pipedrive / GoHighLevel contact: the account is the destination
+baker flows connect contact --side-effect se-email-1 --email "ana@x.com, luis@x.com" --subject "New lead — Contact"   # an email destination: the agent states it, never a card
+baker flows connect contact --side-effect se-httpWebhook-1 --url https://hooks.example.com/lead   # a webhook that needs no token
 baker flows connect contact --all --type googleSpreadsheet --same-as madrid:se-gsheet-1   # copy another Form's destination
 baker flows map contact --from map.json --write     # a whole mapping at once — past ~3 fields, use this
 baker flows map contact --map A=nombre --write      # one or two fields
@@ -3760,6 +3762,7 @@ Notes:
 - **`schema` takes the kind as an argument because `hubspot` is both** — a node type (embeds a form on the page) and a side-effect type (fires a behavioural event). They are different things with one name.
 - **`connect` wires a HubSpot form without asking the user.** When HubSpot is connected and the agent knows which form is meant, `baker flows connect <slug> --hubspot-form <formId> [--side-effect <id>]` attaches the account and the form to a `hubspotForm` side effect (`--all`: every one in the Form still missing it, never repointing one already wired) — the same thing the chat card writes, sealed by Baker so the config never passes through the agent. It refuses a form with spam prevention (captcha) on, and returns `destination.formGuid` for `map --hubspot-form`. The card (`request_flow_input`) stays for an unconnected account or an ambiguous choice.
 - **`options` + `connect` do the same for every other connected platform.** `baker flows options <kind>` lists what the connected account holds (Calendly events, SavvyCal links, GoHighLevel calendars and forms, the Google spreadsheets Baker can reach); `connect --node|--side-effect <id> --resource <id>` writes exactly what the card would. Pipedrive and a GoHighLevel contact take no resource. `--new-sheet` creates a spreadsheet in the connected Google account (Google only lets Baker reach sheets it created or the user chose), `--same-as <slug>:<id>` copies another Form's wired destination, `--all --type <kind>` fills every unwired one of a kind. Nothing connected answers `NOT_CONNECTED` with the `request_connection` fix; several accounts connected need `--account <id>`.
+- **`--email` / `--url` replace a destination whole, so they leave alone what only the user can set.** `--all --email` passes over an email that replies to the visitor's own answer (and says so in its hints); naming one is refused. A webhook that sends a credential keeps its address until the user re-enters both through `request_flow_input`. Unreadable settings are also left alone by default. For one unreadable email, `--replace-unreadable --email <complete list> --subject <text>` replaces the old setup when the user intends replacement, without revealing it. Never use this to add to an unknown recipient list; it cannot override `--all`, a known visitor reply, or a webhook. `flows show` reads back only destinations sealed for this company.
 - **Configure the destination before you map.** `columnMapping`/`fieldMapping` describe a *specific* destination — sheet columns, a portal's field names — that only `connect` or `request_flow_input` can set, and both return it. A mapping written first is valid JSON that ships and drops every submission; `verify` blocks the half-wired result.
 - **`map` reads the record shape off the side effect's type.** One property name, four record shapes: a Sheet is addressed by column letter, HubSpot by property name, Pipedrive and GoHighLevel by field key, Crmble by field id. That is why there is no `--key`, and why `--entity` and `--custom`/`--standard` are required rather than defaulted.
 - **A mapping is usually eight to fifteen fields, so `--from` is the main door.** It takes `{ "map": { "<destField>": "<value>" } }` from a file or stdin; `--map` flags are for one or two. Both produce identical output.

package/dist/account-IVVLUX4B.js

@@ -0,0 +1,80 @@
+import {
+  CHATGPT_ADS_REFERENCE,
+  runChatgptRead
+} from "./chunk-LHCOWIGI.js";
+import "./chunk-XNMSJP2X.js";
+import {
+  apiGet
+} from "./chunk-PCKVSSVT.js";
+import "./chunk-MCM3HMNZ.js";
+import "./chunk-UW36KPPH.js";
+import {
+  registerSchema
+} from "./chunk-NU7JSWVA.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/chatgpt/account.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "ads.chatgpt.account",
+  description: "The connected ChatGPT Ads account: name, currency, timezone, status, and the brand and account reviews that decide whether anything in it can serve.",
+  args: {
+    full: { type: "boolean", description: "Return ChatGPT Ads' own account object", required: false }
+  }
+});
+function accountHints(account) {
+  const hints = [];
+  if (account.brandReview.status !== "approved") {
+    const reason = account.brandReview.reason ? ` (${account.brandReview.reason})` : "";
+    hints.push(
+      `Brand review is ${account.brandReview.status}${reason}: nothing in this account serves until it is approved. Fix it in ChatGPT Ads Manager before changing campaigns.`
+    );
+  }
+  if (account.accountReview && account.accountReview.status !== "approved") {
+    hints.push(`A separate account review is ${account.accountReview.status}; delivery can wait on it too.`);
+  }
+  if (account.status === "paused") {
+    hints.push("The whole account is paused, so no campaign in it serves whatever its own status says.");
+  }
+  return hints;
+}
+var SHOW_ARGS = {
+  full: { type: "boolean", description: "Return ChatGPT Ads' own account object", required: false }
+};
+var accountShowCommand = defineCommand({
+  meta: {
+    name: "show",
+    description: "The connected ChatGPT Ads account. Example: baker ads chatgpt account"
+  },
+  args: SHOW_ARGS,
+  run: async ({ args }) => {
+    await runChatgptRead(
+      CHATGPT_ADS_REFERENCE.account,
+      () => apiGet("/api/ads/chatgpt/account", args.full ? { full: "true" } : void 0),
+      (account) => args.full ? [] : accountHints(account)
+    );
+  }
+});
+var accountCommand = defineCommand({
+  meta: {
+    name: "account",
+    description: `The connected ChatGPT Ads account. Start here: currency and timezone for every figure, and whether reviews let anything serve.
+
+Examples:
+  baker ads chatgpt account
+  baker ads chatgpt account --full
+  baker ads chatgpt account update --favicon-url https://example.com/icon.png   \u2014 staged; applies on publish`
+  },
+  subCommands: {
+    show: accountShowCommand,
+    update: () => import("./account-writes-TQOVHHB6.js").then((m) => m.accountUpdateCommand)
+  },
+  // A parent must never declare `run`: citty falls through to it after the matched subcommand.
+  args: SHOW_ARGS,
+  default: "show"
+});
+export {
+  accountCommand,
+  accountHints
+};
+//# sourceMappingURL=account-IVVLUX4B.js.map

package/dist/account-VBI3KT3Y.js

@@ -0,0 +1,49 @@
+import {
+  handleMetaError,
+  resolveAccountIdArg
+} from "./chunk-VSA63D2N.js";
+import {
+  writeAdsJson
+} from "./chunk-XNMSJP2X.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-X7ZODEXJ.js";
+import {
+  apiGet
+} from "./chunk-PCKVSSVT.js";
+import "./chunk-MCM3HMNZ.js";
+import "./chunk-UW36KPPH.js";
+import "./chunk-NU7JSWVA.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/meta/account.ts
+import { defineCommand } from "citty";
+var accountCommand = defineCommand({
+  meta: {
+    name: "account",
+    description: `Show single Meta ad account detail (currency, timezone, balance, business).
+
+Examples:
+  baker ads meta account --account-id act_123
+  BAKER_META_AD_ACCOUNT_ID=act_123 baker ads meta account`
+  },
+  args: {
+    "account-id": { type: "string", description: "Meta ad account ID (act_...)" },
+    "no-cache": NO_CACHE_ARG
+  },
+  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/meta/account", params);
+      writeAdsJson({ ok: true, data });
+    } catch (err) {
+      handleMetaError(err);
+    }
+  }
+});
+export {
+  accountCommand
+};
+//# sourceMappingURL=account-VBI3KT3Y.js.map

package/dist/account-W2FNH3MQ.js

@@ -0,0 +1,79 @@
+import {
+  csvOrJson,
+  handleLinkedinError,
+  resolveAccountIdArg
+} from "./chunk-QNZWLESV.js";
+import {
+  writeAdsJson,
+  writeAdsOutput
+} from "./chunk-XNMSJP2X.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-X7ZODEXJ.js";
+import "./chunk-BAUSWB7O.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-TEINLN64.js";
+import "./chunk-ZJWUBJYQ.js";
+import "./chunk-NE4F3FHN.js";
+import {
+  apiGet
+} from "./chunk-PCKVSSVT.js";
+import "./chunk-MCM3HMNZ.js";
+import "./chunk-UW36KPPH.js";
+import "./chunk-NU7JSWVA.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-FNKH7UQR.js").then((m) => m.accountUrlParamsCommand)
+  },
+  args: accountDetailCommand.args,
+  default: "detail"
+});
+export {
+  accountCommand
+};
+//# sourceMappingURL=account-W2FNH3MQ.js.map

package/dist/account-writes-TQOVHHB6.js

@@ -0,0 +1,66 @@
+import {
+  compact,
+  schemaArgs,
+  stageChatgptOp
+} from "./chunk-QW53AQYB.js";
+import {
+  CHATGPT_ADS_REFERENCE,
+  chatgptFailure
+} from "./chunk-LHCOWIGI.js";
+import {
+  writeJsonEnvelope
+} from "./chunk-XNMSJP2X.js";
+import {
+  apiGet
+} from "./chunk-PCKVSSVT.js";
+import "./chunk-MCM3HMNZ.js";
+import "./chunk-UW36KPPH.js";
+import {
+  registerSchema
+} from "./chunk-NU7JSWVA.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/chatgpt/account-writes.ts
+import { defineCommand } from "citty";
+var REFERENCE = CHATGPT_ADS_REFERENCE.account;
+var UPDATE_ARGS = {
+  name: { type: "string", description: "The advertiser name shown on every card" },
+  "favicon-url": { type: "string", description: "https:// square icon, at least 128 \xD7 128 px" }
+};
+registerSchema({
+  command: "ads.chatgpt.account.update",
+  description: "Stage a change to the advertiser's brand name or icon. It applies when the chat is published and starts a new brand review; nothing in the account serves until it is approved.",
+  args: schemaArgs(UPDATE_ARGS)
+});
+var accountUpdateCommand = defineCommand({
+  meta: {
+    name: "update",
+    description: `Stage a change to the brand name or icon (applies when the chat is published).
+
+Examples:
+  baker ads chatgpt account update --favicon-url https://example.com/icon.png
+  baker ads chatgpt account update --name "GreenLeaf Energy"`
+  },
+  args: UPDATE_ARGS,
+  run: async ({ args }) => {
+    let account;
+    try {
+      account = await apiGet("/api/ads/chatgpt/account");
+    } catch (err) {
+      writeJsonEnvelope({ ...chatgptFailure(err, REFERENCE) });
+      process.exit(1);
+    }
+    await stageChatgptOp(
+      {
+        kind: "account.update",
+        target: account.id,
+        payload: compact({ name: args.name, faviconUrl: args["favicon-url"] })
+      },
+      REFERENCE
+    );
+  }
+});
+export {
+  accountUpdateCommand
+};
+//# sourceMappingURL=account-writes-TQOVHHB6.js.map

package/dist/accounts-3KDFSNLS.js

@@ -0,0 +1,77 @@
+import {
+  csvOrJson,
+  handleLinkedinError
+} from "./chunk-QNZWLESV.js";
+import {
+  connectedResourceHints
+} from "./chunk-P4NSJS54.js";
+import {
+  AVAILABLE_ARG,
+  writeAvailableAccounts
+} from "./chunk-D2XZUIPA.js";
+import {
+  writeAdsOutput,
+  writeJsonEnvelope
+} from "./chunk-XNMSJP2X.js";
+import {
+  NO_CACHE_ARG
+} from "./chunk-X7ZODEXJ.js";
+import "./chunk-BAUSWB7O.js";
+import "./chunk-GXDLWBOY.js";
+import "./chunk-TEINLN64.js";
+import "./chunk-ZJWUBJYQ.js";
+import "./chunk-NE4F3FHN.js";
+import {
+  apiGet
+} from "./chunk-PCKVSSVT.js";
+import "./chunk-MCM3HMNZ.js";
+import "./chunk-UW36KPPH.js";
+import "./chunk-NU7JSWVA.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/linkedin/accounts.ts
+import { defineCommand } from "citty";
+function accountHints(accounts) {
+  return connectedResourceHints({
+    plural: "LinkedIn ad accounts",
+    singular: "LinkedIn ad account",
+    flag: "--account-id",
+    resources: accounts.map((account) => ({ id: account.externalId, label: account.name }))
+  });
+}
+var accountsCommand = defineCommand({
+  meta: {
+    name: "accounts",
+    description: `List LinkedIn ad accounts in this company's connected scope.
+
+Examples:
+  baker ads linkedin accounts
+  baker ads linkedin accounts --output csv
+  baker ads linkedin accounts --available   # every account the login reaches, selected or not`
+  },
+  args: {
+    "no-cache": NO_CACHE_ARG,
+    output: { type: "string", description: "Output format: json|csv|jsonl|md", default: "json" },
+    available: AVAILABLE_ARG
+  },
+  run: async ({ args }) => {
+    if (args.available) return writeAvailableAccounts("linkedin", handleLinkedinError);
+    try {
+      const params = {};
+      if (args["no-cache"]) params["skip-cache"] = "true";
+      const data = await apiGet("/api/ads/linkedin/accounts", params);
+      const fmt = csvOrJson(args);
+      if (fmt !== "json") {
+        writeAdsOutput(data, fmt);
+        return;
+      }
+      writeJsonEnvelope({ ok: true, data, hints: accountHints(data) });
+    } catch (err) {
+      handleLinkedinError(err);
+    }
+  }
+});
+export {
+  accountsCommand
+};
+//# sourceMappingURL=accounts-3KDFSNLS.js.map

package/dist/accounts-DJW5PRSE.js

@@ -0,0 +1,115 @@
+import {
+  NO_X_ACCOUNTS_EXPLANATION
+} from "./chunk-ZLZWMWB7.js";
+import {
+  connectedResourceHints
+} from "./chunk-P4NSJS54.js";
+import {
+  AVAILABLE_ARG,
+  writeAvailableAccounts
+} from "./chunk-D2XZUIPA.js";
+import {
+  cacheGet,
+  cacheSet,
+  handleConnectionError,
+  needsConnectionFix,
+  writeAdsJson,
+  writeAdsOutput,
+  writeJsonEnvelope
+} from "./chunk-XNMSJP2X.js";
+import {
+  ApiError,
+  apiGet
+} from "./chunk-PCKVSSVT.js";
+import "./chunk-MCM3HMNZ.js";
+import "./chunk-UW36KPPH.js";
+import {
+  registerSchema
+} from "./chunk-NU7JSWVA.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ads/x/accounts.ts
+import { defineCommand } from "citty";
+registerSchema({
+  command: "ads.x.accounts",
+  description: "List the X Ads accounts this company connected \u2014 there can be several, and every one of them is yours to work in. Returns accounts with id (base36), name, approval_status, timezone, currency. Run this first to find account IDs for other commands.",
+  args: {
+    "no-cache": { type: "boolean", description: "Skip cache, hit API directly", required: false },
+    output: { type: "string", description: "Format: json|csv|md", required: false, default: "json" },
+    available: AVAILABLE_ARG
+  }
+});
+function accountHints(accounts) {
+  if (accounts.length === 0) return [NO_X_ACCOUNTS_EXPLANATION];
+  return connectedResourceHints({
+    plural: "X Ads accounts",
+    singular: "X Ads account",
+    flag: "--account-id",
+    resources: accounts.map((account) => ({ id: account.id, label: account.name }))
+  });
+}
+function handleAccountsError(err) {
+  if (err instanceof ApiError) {
+    if (needsConnectionFix(err.code, err.message)) {
+      handleConnectionError("x_ads", err.message);
+    }
+    const envelope = {
+      ok: false,
+      error: {
+        code: err.code,
+        message: err.message,
+        fix: { action: "reject", explanation: err.message },
+        retryable: false
+      }
+    };
+    writeAdsJson(envelope);
+    process.exit(1);
+  }
+  writeAdsJson({ ok: false, error: { code: "NETWORK_ERROR", message: "Unexpected error" } });
+  process.exit(1);
+}
+var accountsCommand = defineCommand({
+  meta: {
+    name: "accounts",
+    description: `List accessible X Ads accounts. Returns account IDs needed for all other commands.
+
+Examples:
+  baker ads x accounts
+  baker ads x accounts --available   # every account the login reaches, selected or not`
+  },
+  args: {
+    "no-cache": { type: "boolean", description: "Skip cache", required: false },
+    output: { type: "string", description: "Format: json|csv|md", required: false, default: "json" },
+    available: AVAILABLE_ARG
+  },
+  run: async ({ args }) => {
+    if (args.available) return writeAvailableAccounts("x-ads", handleAccountsError);
+    const useCache = !args["no-cache"];
+    if (useCache) {
+      const cached = cacheGet("x-accounts", "list");
+      if (cached) {
+        writeJsonEnvelope({ ok: true, data: cached.data, cached: true, hints: accountHints(cached.data) });
+        return;
+      }
+    }
+    try {
+      const params = !useCache ? { "skip-cache": "true" } : void 0;
+      const data = await apiGet("/api/ads/x/accounts", params);
+      if (useCache) {
+        cacheSet("x-accounts", "list", data, 60 * 60 * 1e3);
+      }
+      const format = args.output || "json";
+      if (format !== "json") {
+        writeAdsOutput(data, format);
+        return;
+      }
+      writeJsonEnvelope({ ok: true, data, hints: accountHints(data) });
+    } catch (err) {
+      handleAccountsError(err);
+    }
+  }
+});
+export {
+  accountsCommand
+};
+//# sourceMappingURL=accounts-DJW5PRSE.js.map