@wrangled/cli 0.3.23 → 0.3.24

package/dist/guide.js

@@ -20,6 +20,10 @@ Run \`${cli} guide\` first. It says, in plain words, what this workspace has. It
 
 Before writing new ads or a campaign plan, run \`${cli} brief\`. In one read it gives the offer (from the confirmed offers and funnels map, else the brand notes and landing pages, or it says the offer is unknown), the brand voice, the best ads by spend and by results with their words and a piece of their video transcript, the ads to avoid repeating, the pages those ads send people to, the funnel and top campaigns, who the top Facebook campaigns were aimed at, and what is missing. \`--from\` and \`--to\` pick the dates (default: the last 30 days), \`--channel\` or \`--campaign <id>\` narrow it, and \`--top <n>\` sets how many of each list it shows (default 5, at most 20). It prints plain Markdown to paste into a prompt; \`--format json\` gives the same brief as data. It says what it cut to stay short.
 
+## Which Facebook ads won: winners and flops
+
+\`${cli} winners\` says which Facebook ads won and which flopped, for one Monday-to-Sunday week and for the 30 days ending that Sunday, judged on real sales: each sale goes to the Facebook ad that first brought the buyer in, and payments typed into GoHighLevel by hand never count toward an ad. An ad with no sales that has spent less than twice the account's cost per sale is too new to judge on sales, so it is judged on cost per sign-up and listed apart. Each ad says in a sentence why it is on its list. \`--week <YYYY-MM-DD>\` picks any day of the week (default: the latest complete week), \`--top <n>\` how many ads each list shows (default 5, at most 20), and \`--format json\` gives the report as data.
+
 ## Content: search before SQL
 
 To find content, such as "the 10 emails with the best click rate", "our 5 best videos by return on ad spend" or "every landing page that mentions the guarantee", use \`${cli} content search\` before writing SQL on the \`content_\` tables.
@@ -243,6 +247,7 @@ ${cli} whoami                       show the current workspace and library acces
 ${cli} knowledge search "<question>" [--limit <n>] [--kind <kind>]   short, cited snippets from the Creative Cartel know-how library (keys with library access)
 ${cli} guide                        what this workspace's data holds, how fresh it is, and what is missing: read it first
 ${cli} brief [--from <date>] [--to <date>] [--channel <channel>] [--campaign <id>] [--top <n>]   the offer, voice, best and worst ads, pages, results and audience: start here before writing ads
+${cli} winners [--week <date>] [--top <n>]   which Facebook ads won and flopped this week and over 30 days, judged on first-touch sales
 ${cli} warehouse schema [--summary] [--table <name> ...] [--search <words>]   list tables and columns; --summary for one row per table
 ${cli} warehouse query "<sql>"      run one read-only query (or --file <path>, or stdin); --out <file.csv | file.ndjson | file.json> saves the rows; add --all for every row
 ${cli} funnel [--from <date>] [--to <date>] [--grain day|week|month]   spend, leads, calls and sales per period, with totals

package/dist/main.js

@@ -10,6 +10,7 @@ import { firstSymlink, inRunFolder, writeFileAtomic } from "./files.js";
 import { guide, skill } from "./guide.js";
 import { PULL_STATE_FILE, pullContent } from "./pull.js";
 import { AGENTS_MD_MARKER, metaAdsAgentsMd, PLAYBOOK_CHOICES, playbooks } from "./playbooks.js";
+import { OPENROUTER_KEY_ENV } from "./runner/codex.js";
 import { AGENT_ENV, HARNESS_COMMAND_ENV, RUNNER_TOKEN_ENV, runLoop, runOnce } from "./runner/run.js";
 import { SKILL_NAME_PATTERN } from "./skill-zip.js";
 import { installSkillFolder, operatorConnection, packSkill, parseSkillRef, readSkillFolder, unpackSkill, } from "./skills.js";
@@ -609,6 +610,21 @@ const commands = {
             process.stdout.write(brief.text);
         },
     },
+    winners: {
+        usage: "winners [--week <YYYY-MM-DD>] [--top <n>]   (which Facebook ads won and flopped, judged on real first-touch sales)",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: winners [--week <date>] [--top <n>]", exitCodes.usage);
+            const query = new URLSearchParams();
+            for (const [name, value] of Object.entries({ week: options.week, top: options.top }))
+                if (value !== undefined)
+                    query.set(name, value);
+            const report = await api(await resolveConnection(options.apiUrl), `/api/v1/winners${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson(report);
+            process.stdout.write(winnersText(report));
+        },
+    },
     examples: {
         usage: "examples   (plain questions with SQL that answers them, for the tables this workspace has)",
         async run(args, options) {
@@ -1209,6 +1225,8 @@ const commands = {
                 console.log(`Failed for ${failure.adIds.join(", ")}: ${failure.error}`);
             if (result.stopped === "tool_cap")
                 console.log("Stopped early: the run's tool spending cap was reached.");
+            if (result.nothingToRead > 0)
+                console.log(`Left out ${plural(result.nothingToRead)} with nothing to read: no copy, headline, transcript or picture description.`);
         },
     },
     "content tags": {
@@ -1693,6 +1711,7 @@ async function withRunner(options, work) {
             apiUrl: resolveApiUrl(options.apiUrl, null),
             token,
             harnessCommand: process.env[HARNESS_COMMAND_ENV] || undefined,
+            openRouterKey: process.env[OPENROUTER_KEY_ENV] || undefined,
             maxSeconds: options.maxSeconds,
             signal: stop.signal,
             say: (line) => console.log(line),
@@ -1769,6 +1788,59 @@ const CAMPAIGN_NUMBERS = [
     "roas_first_touch",
     "roas_last_touch",
 ];
+function money(value, currency) {
+    try {
+        return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(value);
+    }
+    catch {
+        return `${value.toFixed(2)} ${currency}`;
+    }
+}
+const counted = (n, one) => `${n} ${n === 1 ? one : `${one}s`}`;
+/** An ad's line: name, SKU and campaign, its numbers, its tags, then why it is on the list. */
+function winnersAdLines(ad, currency) {
+    const n = ad.numbers;
+    const onSales = ad.judgedOn === "sales";
+    const cost = onSales
+        ? n.costPerSale === null ? "no sales" : `${money(n.costPerSale, currency)} per sale`
+        : n.costPerSignup === null ? "no sign-ups" : `${money(n.costPerSignup, currency)} per sign-up`;
+    const name = [ad.name ?? `Ad ${ad.adId}`, ad.sku && `[${ad.sku}]`, ad.campaignName && `(${ad.campaignName})`].filter(Boolean).join(" ");
+    const tags = Object.entries(ad.tags).map(([field, value]) => `${field}: ${value}`).join(", ");
+    const count = onSales ? n.sales !== null && counted(n.sales, "sale") : n.signups !== null && counted(n.signups, "sign-up");
+    return `- ${name}: spent ${money(n.spend, currency)}, ${count ? `${count}, ` : ""}${cost}${tags ? `. Tags: ${tags}` : ""}\n  ${ad.pickedBecause}\n`;
+}
+function winnersWindowText(title, window) {
+    const head = `\n## ${title}, ${window.from} to ${window.to}\n`;
+    if (window.sections.length === 0)
+        return `${head}\nNo Facebook ad spent in these dates.\n`;
+    return (head +
+        window.sections
+            .map((s) => {
+            const list = (heading, ads) => `\n${heading}\n${ads.length === 0 ? "- none\n" : ads.map((ad) => winnersAdLines(ad, s.currency)).join("")}`;
+            const account = s.salesSource === "not_connected"
+                ? "sales are not connected"
+                : s.accountCostPerSale === null
+                    ? "no sale credited to a Facebook ad in these dates"
+                    : `the account paid ${money(s.accountCostPerSale, s.currency)} per sale`;
+            const tests = s.tests.map((t) => `- Test ${t.testId}${t.hypothesisId ? ` (idea ${t.hypothesisId})` : ""}: ${counted(t.ads.length, "ad")}, spent ${money(t.spend, s.currency)}, ${counted(t.sales, "sale")}` +
+                `${t.costPerSale === null ? "" : `, ${money(t.costPerSale, s.currency)} per sale`}\n`);
+            return (`\nIn ${s.currency}: ${account}. ${s.adsJudgedOnSales} judged on sales, ${s.adsJudgedOnSignups} judged on sign-ups.\n` +
+                s.notes.map((note) => `${note}\n`).join("") +
+                list("Winners", s.winners) +
+                list("Flops", s.flops) +
+                list(`${s.onSignups.title}: best`, s.onSignups.best) +
+                list(`${s.onSignups.title}: worst`, s.onSignups.worst) +
+                (tests.length > 0 ? `\nAdzara tests\n${tests.join("")}` : ""));
+        })
+            .join(""));
+}
+/** The winners report as plain Markdown: what a sale means, then this week and the last 30 days, each currency apart. */
+function winnersText(report) {
+    return (`# Winners and flops for ${report.workspace}\n\n` +
+        `A sale means ${report.saleMeans}. Each sale goes to the Facebook ad that first brought the buyer in; payments typed into GoHighLevel by hand never count toward an ad.\n` +
+        winnersWindowText("This week", report.week) +
+        winnersWindowText("Last 30 days", report.last30Days));
+}
 function reportQuery(options, extra) {
     const query = new URLSearchParams();
     for (const [name, value] of Object.entries({ from: options.from, to: options.to, ...extra }))
@@ -1915,7 +1987,8 @@ Options:
   --channel <channel>   only this channel's campaigns (and, with brief, its ads): meta, google, affiliate, a utm_source, unknown or recorded_in_crm;
                         for content track-link, where the link goes: facebook, email, sms or web (default)
   --campaign <id>       the campaign content track-link puts in utm_campaign; with brief, the one campaign it covers
-  --top <n>             how many best ads, worst ads, pages and campaigns brief shows (default: 5, at most 20)
+  --top <n>             how many best ads, worst ads, pages and campaigns brief shows, or ads in each winners list (default: 5, at most 20)
+  --week <YYYY-MM-DD>   any day of the week winners covers, Monday to Sunday (default: the latest complete week)
   --body, --html <text | @file>   the words, or the full HTML, content create, capture and edit save
   --file <path>         an image, video or audio file, up to 50 MB, content create, capture and edit save; repeat for several
   --transcript <text | @file>   what is said in the first video or audio file content capture saves, so none is paid for
@@ -2007,6 +2080,7 @@ function parseOptions(argv) {
             channel: { type: "string" },
             campaign: { type: "string" },
             top: { type: "string" },
+            week: { type: "string" },
             name: { type: "string" },
             subject: { type: "string" },
             preview: { type: "string" },
@@ -2103,6 +2177,7 @@ function parseOptions(argv) {
             channel: values.channel,
             campaign: values.campaign,
             top: values.top,
+            week: values.week,
             name: values.name,
             subject: values.subject,
             preview: values.preview,

package/dist/playbooks.js

@@ -864,11 +864,11 @@ ${cli} ads autotag --limit ${BACK_TAG_BATCH} --json > batch.json
 
 Each call takes the ${BACK_TAG_BATCH} biggest-spending ads with no tags yet, so the next call moves on to the next ones. Open \`batch.json\` after each one. An ad Jev says is not marketing (\`not_marketing\`), or can't tell about (\`gate_unclear\`), is listed under \`skipped\` but was saved with only that answer, so it counts as progress. Run it again until one of these happens:
 
-- A batch saved nothing new: \`proposed\` is empty, and every ad under \`skipped\` is \`no_content\` (nothing to read: no copy, transcript or picture description) or \`not_found\`, with the rest under \`failed\`. The same ads would come back next time, so asking again won't help.
+- A batch saved nothing new: \`proposed\` is empty, and every ad under \`skipped\` is \`no_content\` (nothing to read: no copy, transcript or picture description) or \`not_found\`, with the rest under \`failed\`. Asking again won't help.
 - You have run ${BACK_TAG_MAX_BATCHES} batches, or the person's spending limit would be passed.
 - \`stopped\` is \`tool_cap\`: the run's tool spending cap was reached.
 
-Keep a running count of ads proposed, ads skipped (and why), failures and \`costUsd\` from each batch.
+Keep a running count of ads proposed, ads skipped (and why), failures and \`costUsd\` from each batch. \`nothingToRead\` counts the untagged ads the tagger left out because they have nothing to read; keep the last batch's number.
 
 ## 3. Report
 
@@ -876,7 +876,7 @@ Run the coverage query from step 1 again, then finish with a short report in pla
 
 - How many ads you tagged this run and what it cost.
 - How many ads that spent anything now have tags, and what share of the spend that is (\`pct_spend_tagged\`); what share of spend a person has confirmed (\`pct_spend_confirmed\`). Give each currency's shares on their own; never add them together.
-- How many ads are still untagged and why, if the batches said (nothing to read, failures).
+- How many ads are still untagged and why, if the batches said: \`nothingToRead\` ads have nothing to read (no copy, headline, transcript or picture description), plus any failures.
 - What to do next: open the Ad tags page in the ${brand.name} web app, press Make the list (or Make a new list) under Check these first, and confirm, fix or skip the ads that carry the top 20% of spend. Everything else stays as the tagger's best guess, marked not yet confirmed.
 
 ## Commands

package/dist/runner/claim.js

@@ -1,6 +1,7 @@
 import { CliError, exitCodes } from "../api.js";
 import { SKILL_NAME_PATTERN } from "../skill-zip.js";
 export const harnessNames = ["claude", "codex"];
+const aiBillings = ["run_key", "shared_key", "subscription"];
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** The claim response as the runner uses it. Never echoes the body: it holds the run key. */
 export function parseClaim(body) {
@@ -28,6 +29,12 @@ export function parseClaim(body) {
         throw bad("deadline");
     if (body.openRouterKey !== undefined && (typeof body.openRouterKey !== "string" || body.openRouterKey.length === 0))
         throw bad("openRouterKey");
+    // A server from before `aiBilling` says run_key only by sending a key.
+    const aiBilling = body.aiBilling ?? (body.openRouterKey === undefined ? "subscription" : "run_key");
+    if (!aiBillings.includes(aiBilling))
+        throw bad("aiBilling");
+    if ((aiBilling === "run_key") !== (typeof body.openRouterKey === "string"))
+        throw bad("openRouterKey");
     return {
         runId: run.id,
         runKey: body.runKey,
@@ -37,6 +44,6 @@ export function parseClaim(body) {
         prompt: body.prompt,
         aiCapUsd: caps.aiCents / 100,
         deadline,
-        billing: typeof body.openRouterKey === "string" ? { kind: "openrouter", key: body.openRouterKey } : { kind: "subscription" },
+        billing: typeof body.openRouterKey === "string" ? { kind: "openrouter", key: body.openRouterKey } : { kind: aiBilling },
     };
 }

package/dist/runner/run.js

@@ -8,6 +8,7 @@ import { brand, envPrefix } from "../brand.js";
 import { RUN_ROOT_ENV } from "../files.js";
 import { installSkillFolder, unpackSkill } from "../skills.js";
 import { parseClaim } from "./claim.js";
+import { OPENROUTER_KEY_ENV } from "./codex.js";
 import { MAX_TURNS } from "./harness.js";
 import { commandHarness, harnesses } from "./harnesses.js";
 import { LogTail, redact, RUN_ERROR_MAX_BYTES, tailBytes } from "./redact.js";
@@ -68,7 +69,7 @@ export async function runOnce(options) {
     if (answer === "")
         return { kind: "idle" };
     const claim = parseClaim(JSON.parse(answer));
-    const secrets = [claim.runKey, options.token, ...(claim.billing.kind === "openrouter" ? [claim.billing.key] : [])];
+    const secrets = [claim.runKey, options.token, ...(claim.billing.kind === "openrouter" ? [claim.billing.key] : []), ...(options.openRouterKey ? [options.openRouterKey] : [])];
     const say = (line) => options.say(redact(line, secrets));
     say(`Claimed run ${claim.runId}: ${claim.skill.name} version ${claim.skill.version} with ${claim.harness}.`);
     const stop = new AbortController();
@@ -90,6 +91,9 @@ export async function runOnce(options) {
         dir = await mkdtemp(join(tmpdir(), `${brand.slug}-run-`));
         const result = await execute(claim, dir, options, stop.signal, (text) => log.append(text));
         report = finishReport(result, stop.signal.reason);
+        const aiCents = reportedAiCents(claim.billing, result.tokens);
+        if (aiCents !== undefined)
+            report.aiCents = aiCents;
     }
     catch (error) {
         report = { status: "failed", error: stop.signal.aborted ? stopMessages[stop.signal.reason] : `The runner failed: ${error.message}` };
@@ -143,6 +147,7 @@ function finishReport(result, stopped) {
 }
 /** Puts the skill, the run key's login and a `wr` in `dir`, then runs the harness there. */
 async function execute(claim, dir, options, signal, log) {
+    const billing = harnessBilling(claim, options.openRouterKey);
     const skillsDir = join(dir, claim.harness === "claude" ? ".claude" : ".codex", "skills");
     await installSkillFolder(skillsDir, claim.skill.name, unpackSkill(claim.skill, await getSigned(claim.skill.url)), []);
     const configHome = join(dir, ".config");
@@ -158,7 +163,7 @@ async function execute(claim, dir, options, signal, log) {
         skill: claim.skill.name,
         prompt: runPrompt(claim.prompt),
         model: claim.model,
-        billing: claim.billing,
+        billing,
         aiCapUsd: claim.aiCapUsd,
         maxTurns: MAX_TURNS,
         env: harnessEnv(process.env, { dir, binDir, configHome, apiUrl: options.apiUrl }),
@@ -166,6 +171,30 @@ async function execute(claim, dir, options, signal, log) {
         log,
     });
 }
+/**
+ * How the harness pays. A shared_key run pays OpenRouter with the runner's own key, and only Claude Code, whose budget
+ * stops it at the AI cap, may run that way: nothing would hold a Codex run to its cap on a key shared by every run.
+ */
+export function harnessBilling(claim, openRouterKey) {
+    if (claim.billing.kind !== "shared_key")
+        return claim.billing;
+    if (!openRouterKey) {
+        throw new Error(`This run pays for AI with the runner's own OpenRouter key, but ${OPENROUTER_KEY_ENV} is not set on this runner. Set it, or set OPENROUTER_PROVISIONING_KEY on the server to an OpenRouter management key so each run gets its own key.`);
+    }
+    if (claim.harness === "codex") {
+        throw new Error(`A Codex run cannot keep to its AI cap on the runner's shared OpenRouter key. Set OPENROUTER_PROVISIONING_KEY on the server to an OpenRouter management key so each run gets its own capped key.`);
+    }
+    return { kind: "openrouter", key: openRouterKey };
+}
+/**
+ * The AI spend a finish report carries: only a shared_key run's, whose spend the server cannot read from OpenRouter
+ * itself, from the harness's own estimate. A zero estimate may mean the harness could not price the model, so it is not
+ * sent; a run without a report counts at its full cap.
+ */
+export function reportedAiCents(billing, tokens) {
+    const costUsd = tokens?.costUsd;
+    return billing.kind === "shared_key" && costUsd !== undefined && costUsd > 0 ? Math.ceil(costUsd * 100) : undefined;
+}
 /** Beats now (moving the run to running) and every minute; a cancel, or a server that no longer knows the run, stops it. */
 function startHeartbeat(connection, runId, cancel, say) {
     const beat = async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrangled/cli",
-  "version": "0.3.23",
+  "version": "0.3.24",
   "description": "Command-line access to your marketing data warehouse, for people and coding agents",
   "type": "module",
   "bin": {