@koda-sl/baker-cli 0.119.0 → 0.120.0-dev.3b02f951b

package/README.md

@@ -82,7 +82,7 @@ Use `--output` to change format:
 
 ### Ad Platforms (`baker ads`)
 
-Multi-platform ad data commands. Currently supports Google Ads, with Meta, LinkedIn, and TikTok coming.
+Multi-platform ad commands. Google, Meta, and LinkedIn support both reads and **staged writes** (create/update campaigns, ad sets/ad groups, ads, creatives, audiences — applied on chat publish); X (Twitter) is read + analytics. TikTok is coming.
 
 ---
 
@@ -883,6 +883,36 @@ baker ads meta pixels --account-id act_123
 baker ads meta pixels --pixel-id 9988 --stats --days 7
 ```
 
+#### Staged writes (`baker ads meta campaigns|adsets|ads|creatives|audiences|media|draft`)
+
+Meta writes mirror the Google/LinkedIn model: they **never hit the Graph API when you run them**. Each op is validated at stage time (field shapes, budget rules, page/Instagram identity ownership, CBO/ABO exclusivity, status-transition legality), shows in the dashboard chat as a pending Meta change, and applies only when the chat is published. Meta has no atomic batch mutate, so ops apply **sequentially** on publish — one failure skips its dependents but the publish completes.
+
+If the company's `metaAdsWriteEnabled` flag is off (the default), publish runs the identical lifecycle **simulated** — fake `sim_meta_*` ids, zero Meta calls. The stage response and `baker ads meta draft` show `mode: "simulated"`.
+
+Chain a full ad from scratch with `meta_temp_*` refs (each create returns one):
+
+```bash
+# 1. (optional) upload creative media from the Baker library → publishes an image hash
+baker ads meta media upload --account-id act_123 --kind image --image-id <bakerImageId>   # → meta_temp_img
+
+# 2. campaign → ad set → creative → ad
+baker ads meta campaigns create   --account-id act_123 --name "Q3 Prospecting" --objective OUTCOME_LEADS --daily-budget 50   # → meta_temp_camp
+baker ads meta adsets create      --account-id act_123 --campaign meta_temp_camp --name "US 25-54" \
+  --optimization-goal OFFSITE_CONVERSIONS --billing-event IMPRESSIONS --pixel-id 111 --custom-event-type LEAD \
+  --targeting-file targeting.json   # → meta_temp_as
+baker ads meta creatives create   --account-id act_123 --page 555 --instagram-user 777 \
+  --message "Save money on pet insurance" --link https://example.com --headline "Best cover" \
+  --image-ref meta_temp_img --cta SHOP_NOW --standard-enhancements on   # → meta_temp_cr
+baker ads meta ads create         --account-id act_123 --name "Ad 1" --adset meta_temp_as --creative meta_temp_cr
+
+# review + edit before publish
+baker ads meta draft
+baker ads meta draft remove meta_temp_cr   # removing a create cascades to dependents
+baker ads meta draft clear
+```
+
+Status changes are `pause|resume|archive` subcommands on `campaigns`/`adsets`/`ads`. `duplicate` reconstructs a paused copy from the live snapshot (`--replace` also pauses the original once the copy publishes). Carousel/dynamic creatives and complex targeting go via `--file` (creativeType `carousel`/`dynamic`; full Meta targeting spec). Advantage+ Creative enhancements: `--standard-enhancements on|off`, or per-feature toggles via a `--file` `enhancements.features` map.
+
 #### Smart defaults (so agents don't enumerate the API)
 
 **`insights`** — the workhorse:
@@ -930,7 +960,7 @@ The HTTP backend exposes more endpoints (catalogs, ad-studies, ad-images, labels
 
 - `spend` is a decimal string in account currency, not an integer.
 - `effective_status` ≠ `status`. The dashboard shows effective_status (e.g. `WITH_ISSUES`, `PENDING_REVIEW`, `DISAPPROVED`, `ADSET_PAUSED`).
-- Meta creatives are effectively immutable once attached. Editing copy/image/CTA = create a new creative + reattach (writes are out of scope for now).
+- Meta creatives are effectively immutable once attached. Editing copy/image/CTA = stage a new creative + `ads update <id> --creative <ref>` (or `creatives duplicate`), not an edit of the live creative — see [Staged writes](#staged-writes-baker-ads-meta-campaignsadsetsadscreativesaudiencesmediadraft) above.
 - Currency offsets are non-uniform (JPY/KRW = 1, KWD/BHD = 1000, most = 100). Read `account.currency` before doing budget math.
 
 ---
@@ -2631,6 +2661,17 @@ baker canvas run my-canvas.json
 #     single node — that old serial workaround is obsolete.
 baker canvas run my-canvas.json --parallel 8
 
+# 2c. Runs persist across sandboxes/sessions by default: node results sync to a
+#     company-scoped remote cache (small JSON pointers; bytes stay in R2), so a FRESH
+#     sandbox re-runs an already-computed canvas at zero credits — assets rehydrate
+#     from R2, sha-verified. Every run also posts a durable history record (per-node
+#     outputs, credits, cached/fresh) that powers the dashboard's Creatives
+#     generations timeline. Opt out with --remote-cache off (env
+#     BAKER_CANVAS_REMOTE_CACHE=off) and --no-record. With --remote-cache off,
+#     assets are not uploaded, so a recorded run keeps its stats but has no
+#     browsable outputs — pass --no-record too if you want nothing persisted.
+baker canvas run my-canvas.json --remote-cache off --no-record
+
 # 3. Inspect a finished run (per-node timing, file list, optional video thumbs)
 baker canvas inspect <run_id>
 
@@ -3942,6 +3983,7 @@ baker canvas run ./reference-ad.video.canvas.json
 | Flag | Default | Effect |
 |---|---|---|
 | `--out <path>` | `<video-dir>/<name>.video.canvas.json` | Where to write the canvas (composition is copied alongside). |
+| `--slug <slug>` | — | Creative slug (lowercase kebab): writes the canvas to `src/creatives/<slug>/<slug>.canvas.json` — the repo convention that attaches every run to the creative's dashboard generation history. `--out` wins over `--slug`. |
 | `--frames <mode>` | `generate` | `generate` emits ONE recast keyframe per scene (the original frame is dropped so the dropped `el_*` assets drive identity); `reuse` wires the real extracted first+last frames straight into the clips (faithful, cheaper, no recast). |
 | `--ambient` | off | Give silent **b-roll** scenes native diegetic ambient (Seedance `generate_audio`), mixed deep under the music bed. Talking scenes already carry voice; check levels don't muddy the mix before keeping it. |
 | `--max-scenes <n>` | all source scenes | **Cost lever that reduces fidelity** — caps the deconstruct, MERGING away every scene beyond the cap (fewer cuts, lost beats). Prints a warning when set; omit it to reproduce every scene. |
@@ -3983,6 +4025,7 @@ baker canvas run ./static-ad.canvas.json
 |---|---|---|
 | `--context <text>` | — | Known provenance (advertiser, category, market) to ground the describe. |
 | `--out <path>` | `<image-dir>/static-ad.canvas.json` (cwd when `<image>` is a URL) | Where to write the canvas (`prompt.json` is written alongside). |
+| `--slug <slug>` | — | Creative slug (lowercase kebab): writes the canvas to `src/creatives/<slug>/<slug>.canvas.json` — the repo convention that attaches every run to the creative's dashboard generation history. `--out` wins over `--slug`. |
 | `--describe-model <id>` | registry default (`~google/gemini-pro-latest`) | Override the `image_describe` model. |
 | `--select-model <id>` | registry default (`~google/gemini-flash-latest`) | Override the element-selection `text_generate` model. |
 | `--layout-model <id>` | registry default (`~google/gemini-flash-latest`) | Override the global-layout `text_generate` model. |
@@ -4454,6 +4497,26 @@ import {
 } from "@koda-sl/baker-cli/engine";
 ```
 
+## Creatives
+
+Publish an approved canvas render as a first-class Baker creative. The image uploads to the Baker image library (tagged `creative`), a creative record is created/updated, and the command prints the creative reference JSON the dashboard renders in chat.
+
+```bash
+baker creatives publish ./canvas/<run_id>/<final>.png --title "Spring Offer 4x5" \
+  --slug spring-offer-4x5 --run-id r_01JXYZ... \
+  --source-reference-url "https://www.facebook.com/ads/library/?id=..."
+```
+
+| Flag | Effect |
+|---|---|
+| `--title <text>` | Required. Human title for the creative. |
+| `--slug <slug>` | Creative slug (`src/creatives/<slug>/`) — attaches the image to that creative's row, marks it `published`. |
+| `--run-id <r_…>` | Pins the approved generation from the creative's run history as the published one. |
+| `--source-reference-url <url>` | Original reference ad URL, recorded on the creative. |
+| `--context <text>` | Optional describe context for the uploaded image asset. |
+
+Without `--slug` the command behaves as before (one creative record per published image). With `--slug` it upserts the repo-convention row — the same one the dashboard's Creatives tab and the `src/creatives/{slug}/` folder describe — so publish, repo sync, and run history all land on a single record regardless of order.
+
 ## Help & Discovery
 
 Every command supports `--help` for usage info:

package/dist/chunk-5WRI5ZAA.js

@@ -0,0 +1,31 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+export {
+  __commonJS,
+  __toESM
+};
+//# sourceMappingURL=chunk-5WRI5ZAA.js.map

package/dist/chunk-5WRI5ZAA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-AVJ3B6LC.js

@@ -0,0 +1,97 @@
+import {
+  handleConnectionError,
+  writeAdsJson
+} from "./chunk-ISFSUDEQ.js";
+import {
+  ApiError
+} from "./chunk-K47Q73CK.js";
+import {
+  getEnv
+} from "./chunk-YTEAWSEM.js";
+
+// src/commands/ads/meta/shared.ts
+var DAY_MS = 864e5;
+function handleMetaError(err) {
+  if (err instanceof ApiError) {
+    if (err.code === "UNAUTHORIZED" || err.code === "NOT_FOUND") {
+      handleConnectionError("meta_ads", err.message);
+    }
+    const envelope = {
+      ok: false,
+      error: {
+        code: err.code,
+        message: err.message,
+        fix: { action: "reject", explanation: err.message },
+        retryable: err.code === "RATE_LIMITED" || err.code === "INTERNAL_ERROR"
+      }
+    };
+    writeAdsJson(envelope);
+    process.exit(1);
+  }
+  const message = err instanceof Error ? err.message : "Unexpected error";
+  writeAdsJson({ ok: false, error: { code: "NETWORK_ERROR", message } });
+  process.exit(1);
+}
+var ACCOUNT_ID_RE = /^(act_)?[0-9]+$/;
+function resolveAccountIdArg(args) {
+  const fromArgs = args["account-id"];
+  const id = fromArgs || getEnv().BAKER_META_AD_ACCOUNT_ID;
+  if (!id) {
+    writeAdsJson({
+      ok: false,
+      error: {
+        code: "MISSING_ACCOUNT_ID",
+        message: "Pass --account-id or set BAKER_META_AD_ACCOUNT_ID. Run `baker ads meta accounts` to find IDs."
+      }
+    });
+    process.exit(1);
+  }
+  if (!ACCOUNT_ID_RE.test(id)) {
+    writeAdsJson({
+      ok: false,
+      error: {
+        code: "INVALID_ACCOUNT_ID",
+        message: `Invalid account ID "${id}". Expected numeric ID, optionally prefixed with "act_".`
+      }
+    });
+    process.exit(1);
+  }
+  return id.startsWith("act_") ? id : `act_${id}`;
+}
+function getDateRange(args) {
+  const datePreset = args["date-preset"];
+  const since = args.since;
+  const until = args.until;
+  if (since && until) return { since, until };
+  return { datePreset: datePreset ?? "last_7d" };
+}
+function todayIso() {
+  return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+}
+function daysAgoIso(days) {
+  return new Date(Date.now() - days * DAY_MS).toISOString().slice(0, 10);
+}
+function csvOrJson(args) {
+  return args.output ?? "json";
+}
+function resolveEffectiveStatus(args) {
+  if (args["all-statuses"]) {
+    return void 0;
+  }
+  const explicit = args["effective-status"];
+  if (explicit) {
+    return explicit;
+  }
+  return "ACTIVE";
+}
+
+export {
+  handleMetaError,
+  resolveAccountIdArg,
+  getDateRange,
+  todayIso,
+  daysAgoIso,
+  csvOrJson,
+  resolveEffectiveStatus
+};
+//# sourceMappingURL=chunk-AVJ3B6LC.js.map

package/dist/chunk-AVJ3B6LC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/commands/ads/meta/shared.ts"],"sourcesContent":["import { ApiError } from \"../../../client.ts\";\nimport { getEnv } from \"../../../env.ts\";\nimport { handleConnectionError } from \"../../../error-handler.ts\";\nimport { writeAdsJson } from \"../output.ts\";\nimport type { AdsErrorEnvelope } from \"../types.ts\";\n\nconst DAY_MS = 86_400_000;\n\nexport function handleMetaError(err: unknown): never {\n  if (err instanceof ApiError) {\n    if (err.code === \"UNAUTHORIZED\" || err.code === \"NOT_FOUND\") {\n      handleConnectionError(\"meta_ads\", err.message);\n    }\n    const envelope: AdsErrorEnvelope = {\n      ok: false,\n      error: {\n        code: err.code,\n        message: err.message,\n        fix: { action: \"reject\", explanation: err.message },\n        retryable: err.code === \"RATE_LIMITED\" || err.code === \"INTERNAL_ERROR\",\n      },\n    };\n    writeAdsJson(envelope);\n    process.exit(1);\n  }\n  const message = err instanceof Error ? err.message : \"Unexpected error\";\n  writeAdsJson({ ok: false, error: { code: \"NETWORK_ERROR\", message } });\n  process.exit(1);\n}\n\nconst ACCOUNT_ID_RE = /^(act_)?[0-9]+$/;\n\n/** Pull the default Meta ad account ID from `--account-id` arg or `BAKER_META_AD_ACCOUNT_ID` env. */\nexport function resolveAccountIdArg(args: Record<string, unknown>): string {\n  const fromArgs = args[\"account-id\"] as string | undefined;\n  const id = fromArgs || getEnv().BAKER_META_AD_ACCOUNT_ID;\n  if (!id) {\n    writeAdsJson({\n      ok: false,\n      error: {\n        code: \"MISSING_ACCOUNT_ID\",\n        message: \"Pass --account-id or set BAKER_META_AD_ACCOUNT_ID. Run `baker ads meta accounts` to find IDs.\",\n      },\n    });\n    process.exit(1);\n  }\n  if (!ACCOUNT_ID_RE.test(id)) {\n    writeAdsJson({\n      ok: false,\n      error: {\n        code: \"INVALID_ACCOUNT_ID\",\n        message: `Invalid account ID \"${id}\". Expected numeric ID, optionally prefixed with \"act_\".`,\n      },\n    });\n    process.exit(1);\n  }\n  return id.startsWith(\"act_\") ? id : `act_${id}`;\n}\n\nexport function getDateRange(args: Record<string, unknown>): { datePreset?: string; since?: string; until?: string } {\n  const datePreset = args[\"date-preset\"] as string | undefined;\n  const since = args.since as string | undefined;\n  const until = args.until as string | undefined;\n  if (since && until) return { since, until };\n  return { datePreset: datePreset ?? \"last_7d\" };\n}\n\nexport function todayIso(): string {\n  return new Date().toISOString().slice(0, 10);\n}\n\nexport function daysAgoIso(days: number): string {\n  return new Date(Date.now() - days * DAY_MS).toISOString().slice(0, 10);\n}\n\nexport function csvOrJson(args: Record<string, unknown>): string {\n  return (args.output as string | undefined) ?? \"json\";\n}\n\n/**\n * Default to ACTIVE-only on listings — that's almost always what an AI agent or\n * a human glance wants. Pass `--effective-status ACTIVE,PAUSED` to override, or\n * `--all-statuses` to drop the filter entirely.\n */\nexport function resolveEffectiveStatus(args: Record<string, unknown>): string | undefined {\n  if (args[\"all-statuses\"]) {\n    return undefined;\n  }\n  const explicit = args[\"effective-status\"] as string | undefined;\n  if (explicit) {\n    return explicit;\n  }\n  return \"ACTIVE\";\n}\n"],"mappings":";;;;;;;;;;;;AAMA,IAAM,SAAS;AAER,SAAS,gBAAgB,KAAqB;AACnD,MAAI,eAAe,UAAU;AAC3B,QAAI,IAAI,SAAS,kBAAkB,IAAI,SAAS,aAAa;AAC3D,4BAAsB,YAAY,IAAI,OAAO;AAAA,IAC/C;AACA,UAAM,WAA6B;AAAA,MACjC,IAAI;AAAA,MACJ,OAAO;AAAA,QACL,MAAM,IAAI;AAAA,QACV,SAAS,IAAI;AAAA,QACb,KAAK,EAAE,QAAQ,UAAU,aAAa,IAAI,QAAQ;AAAA,QAClD,WAAW,IAAI,SAAS,kBAAkB,IAAI,SAAS;AAAA,MACzD;AAAA,IACF;AACA,iBAAa,QAAQ;AACrB,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,QAAM,UAAU,eAAe,QAAQ,IAAI,UAAU;AACrD,eAAa,EAAE,IAAI,OAAO,OAAO,EAAE,MAAM,iBAAiB,QAAQ,EAAE,CAAC;AACrE,UAAQ,KAAK,CAAC;AAChB;AAEA,IAAM,gBAAgB;AAGf,SAAS,oBAAoB,MAAuC;AACzE,QAAM,WAAW,KAAK,YAAY;AAClC,QAAM,KAAK,YAAY,OAAO,EAAE;AAChC,MAAI,CAAC,IAAI;AACP,iBAAa;AAAA,MACX,IAAI;AAAA,MACJ,OAAO;AAAA,QACL,MAAM;AAAA,QACN,SAAS;AAAA,MACX;AAAA,IACF,CAAC;AACD,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,MAAI,CAAC,cAAc,KAAK,EAAE,GAAG;AAC3B,iBAAa;AAAA,MACX,IAAI;AAAA,MACJ,OAAO;AAAA,QACL,MAAM;AAAA,QACN,SAAS,uBAAuB,EAAE;AAAA,MACpC;AAAA,IACF,CAAC;AACD,YAAQ,KAAK,CAAC;AAAA,EAChB;AACA,SAAO,GAAG,WAAW,MAAM,IAAI,KAAK,OAAO,EAAE;AAC/C;AAEO,SAAS,aAAa,MAAwF;AACnH,QAAM,aAAa,KAAK,aAAa;AACrC,QAAM,QAAQ,KAAK;AACnB,QAAM,QAAQ,KAAK;AACnB,MAAI,SAAS,MAAO,QAAO,EAAE,OAAO,MAAM;AAC1C,SAAO,EAAE,YAAY,cAAc,UAAU;AAC/C;AAEO,SAAS,WAAmB;AACjC,UAAO,oBAAI,KAAK,GAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AAC7C;AAEO,SAAS,WAAW,MAAsB;AAC/C,SAAO,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,EAAE;AACvE;AAEO,SAAS,UAAU,MAAuC;AAC/D,SAAQ,KAAK,UAAiC;AAChD;AAOO,SAAS,uBAAuB,MAAmD;AACxF,MAAI,KAAK,cAAc,GAAG;AACxB,WAAO;AAAA,EACT;AACA,QAAM,WAAW,KAAK,kBAAkB;AACxC,MAAI,UAAU;AACZ,WAAO;AAAA,EACT;AACA,SAAO;AACT;","names":[]}