@wrangled/cli 0.3.37 → 0.3.38

package/dist/guide.js

@@ -40,7 +40,7 @@ ${brand.name} does not build pages; it hands whoever builds one what is already
 
 ## Which Facebook ads and pages 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. Each currency also says how many of its Facebook sales could be tied to a specific ad (\`adSales\` of \`facebookSales\` in the JSON): a sale whose link names no single ad counts toward Facebook but toward no ad. It judges the landing pages the ads sent people to the same way, and each ad on each page as an ad-and-page pair: a page or pair counts only once the page reader has read the page and it got at least 100 visits in the dates, and pairs are listed only for an ad that sent people to two or more pages, or a page that got people from two or more ads, each naming what the same ad cost on its other pages. \`--week <YYYY-MM-DD>\` picks any day of the week (default: the latest complete week), \`--top <n>\` how many ads, pages or pairs each list shows (default 5, at most 20), and \`--format json\` gives the report as data.
+\`${cli} winners\` says which Facebook ads won and which flopped, for the dates asked for and for the 30 days ending on their last day, 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. Each currency also says how many of its Facebook sales could be tied to a specific ad (\`adSales\` of \`facebookSales\` in the JSON): a sale whose link names no single ad counts toward Facebook but toward no ad. It judges the landing pages the ads sent people to the same way, and each ad on each page as an ad-and-page pair: a page or pair counts only once the page reader has read the page and it got at least 100 visits in the dates, and pairs are listed only for an ad that sent people to two or more pages, or a page that got people from two or more ads, each naming what the same ad cost on its other pages. \`--week <YYYY-MM-DD>\` picks any day of a Monday-to-Sunday week (default: the latest complete week), \`--days <n>\` the last n complete days ending yesterday, and \`--from <YYYY-MM-DD> --to <YYYY-MM-DD>\` any dates; use one of them, at most 90 days. Check as often as suits the client, daily or every few days: a short window holds few sales, so more ads are judged on sign-ups, and the report says so. \`--top <n>\` how many ads, pages or pairs each list shows (default 5, at most 20), and \`--format json\` gives the report as data.
 
 ## What winners and flops taught: lessons
 
@@ -50,11 +50,11 @@ Write one as JSON, \`{"text": "...", "dimension": "hook", "evidence": [{"ad": "<
 
 ## Sending winners to Exodus
 
-\`${cli} winners send-to-exodus\` sends the week's winners to Exodus so it makes new ads from them: one package per Facebook page, each winner with its reason, its numbers, and a note of the lessons it proves, persona lessons and the week's freshest customer words. Winners whose page, words or format are unknown are left out and listed with why. \`--week <YYYY-MM-DD>\` picks the week (default: the latest complete week). \`--dry-run\` asks Exodus what it would create or update and writes nothing. Sending the same week again is safe: an unchanged package is not sent twice, and Exodus updates each ad in place. A real send needs the workspace's Exodus brand and a Scrape Creators key on the Exodus account.
+\`${cli} winners send-to-exodus\` sends the winners to Exodus so it makes new ads from them: one package per Facebook page, each winner with its reason, its numbers, and a note of the lessons it proves, persona lessons and the freshest customer words of the dates. Winners whose page, words or format are unknown are left out and listed with why. \`--week <YYYY-MM-DD>\`, \`--days <n>\` or \`--from\` and \`--to\` pick the dates, as for \`${cli} winners\` (default: the latest complete week). \`--dry-run\` asks Exodus what it would create or update and writes nothing. Sending the same dates again is safe: an unchanged package is not sent twice, and Exodus updates each ad in place. A real send needs the workspace's Exodus brand and a Scrape Creators key on the Exodus account.
 
 ## The weekly loop: a sample for an orchestrator agent
 
-The \`weekly-loop\` playbook (\`${cli} skill install weekly-loop\` installs it as the \`${WEEKLY_LOOP_SKILL_NAME}\` skill; \`${cli} docs weekly-loop\` prints it) is a sample week for a local agent that runs a client's Facebook ads with its owner. It names the command and the MCP tool for each step: the winners and flops report, lessons, fresh customer words, the brief, the offers and funnels map, making ads (Exodus, paid tools or the agent's own skills), and the results of what was published, read back by Adzara's labels. Judge winners by ${brand.name}'s real-sales report (\`${cli} winners\`); Adzara's results are Meta's count. Approvals and decisions happen in the agent's own session with the owner; ${brand.name} records none. Ads are published and changed through Adzara, never through ${brand.name}.
+The \`weekly-loop\` playbook (\`${cli} skill install weekly-loop\` installs it as the \`${WEEKLY_LOOP_SKILL_NAME}\` skill; \`${cli} docs weekly-loop\` prints it) is a sample to borrow from, not a schedule, for a local agent that runs a client's Facebook ads with its owner: its steps can run daily, several times a week or weekly, and the winners report covers whatever dates are asked for. It names the command and the MCP tool for each step: the winners and flops report, lessons, fresh customer words, the brief, the offers and funnels map, making ads (Exodus, paid tools or the agent's own skills), and the results of what was published, read back by Adzara's labels. Judge winners by ${brand.name}'s real-sales report (\`${cli} winners\`); Adzara's results are Meta's count. Approvals and decisions happen in the agent's own session with the owner; ${brand.name} records none. Ads are published and changed through Adzara, never through ${brand.name}.
 
 ## Trying one change: funnel tests
 
@@ -298,8 +298,8 @@ ${cli} guide                        what this workspace's data holds, how fresh
 ${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} pages brief --step <key> [--funnel <key>] | --page <ref>   the offer, step, current page, best and worst pages of its kind, its ads and how to hand a page back: start here before writing a landing page
 ${cli} pages results [--from <date>] [--to <date>] [--page <ref>]   each landing page's, and each ad and page pair's, real first-touch sales, cost per sale and sales per page view
-${cli} winners [--week <date>] [--top <n>]   which Facebook ads and landing pages won and flopped this week and over 30 days, judged on first-touch sales
-${cli} winners send-to-exodus [--week <date>] [--dry-run]   send the week's winners, with their reasons, lessons and customer words, to Exodus; safe to send again
+${cli} winners [--week <date> | --days <n> | --from <date> --to <date>] [--top <n>]   which Facebook ads and landing pages won and flopped in a week or any dates and over 30 days, judged on first-touch sales
+${cli} winners send-to-exodus [--week <date> | --days <n> | --from <date> --to <date>] [--dry-run]   send the winners, with their reasons, lessons and customer words, to Exodus; safe to send again
 ${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

@@ -670,12 +670,12 @@ const commands = {
         },
     },
     winners: {
-        usage: "winners [--week <YYYY-MM-DD>] [--top <n>]   (which Facebook ads and landing pages won and flopped, judged on real first-touch sales)",
+        usage: "winners [--week <YYYY-MM-DD> | --days <n> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>] [--top <n>]   (which Facebook ads and landing pages 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);
+                throw new CliError("Usage: winners [--week <date> | --days <n> | --from <date> --to <date>] [--top <n>]", exitCodes.usage);
             const query = new URLSearchParams();
-            for (const [name, value] of Object.entries({ week: options.week, top: options.top }))
+            for (const [name, value] of Object.entries({ ...winnersPeriod(options), top: options.top }))
                 if (value !== undefined)
                     query.set(name, value);
             const report = await api(await resolveConnection(options.apiUrl), `/api/v1/winners${query.size ? `?${query}` : ""}`);
@@ -685,14 +685,12 @@ const commands = {
         },
     },
     "winners send-to-exodus": {
-        usage: "winners send-to-exodus [--week <YYYY-MM-DD>] [--dry-run]   send the week's winning ads, with their reasons, lessons and customer words, to Exodus; safe to send again",
+        usage: "winners send-to-exodus [--week <YYYY-MM-DD> | --days <n> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>] [--dry-run]   send the winning ads, with their reasons, lessons and customer words, to Exodus; safe to send again",
         async run(args, options) {
             if (args.length > 0)
-                throw new CliError("Usage: winners send-to-exodus [--week <date>] [--dry-run]", exitCodes.usage);
-            const sent = await api(await resolveConnection(options.apiUrl), "/api/v1/winners/exodus", {
-                ...(options.week === undefined ? {} : { week: options.week }),
-                dryRun: options.dryRun,
-            });
+                throw new CliError("Usage: winners send-to-exodus [--week <date> | --days <n> | --from <date> --to <date>] [--dry-run]", exitCodes.usage);
+            const period = Object.entries(winnersPeriod(options)).filter(([, value]) => value !== undefined);
+            const sent = await api(await resolveConnection(options.apiUrl), "/api/v1/winners/exodus", { ...Object.fromEntries(period), dryRun: options.dryRun });
             if (options.format === "json")
                 printJson(sent);
             else
@@ -2059,7 +2057,7 @@ function winnersPageLines(page, currency) {
     return `- ${ad}${name}: ${counted(Math.round(n.visits), "visit")}, spent ${money(n.spend, currency)}, ${count ? `${count}, ` : ""}${cost}${bought}\n  ${page.pickedBecause}\n`;
 }
 function winnersWindowText(title, window) {
-    const head = `\n## ${title}, ${window.from} to ${window.to}\n`;
+    const head = `\n## ${title}\n`;
     if (window.sections.length === 0)
         return `${head}\nNo Facebook ad spent in these dates.\n`;
     return (head +
@@ -2095,8 +2093,19 @@ function winnersWindowText(title, window) {
         })
             .join(""));
 }
+/** The window flags as the API takes them; the server refuses two windows at once or half a range. */
+function winnersPeriod(options) {
+    return { week: options.week, days: options.days, from: options.from, to: options.to };
+}
+/** "This week, 2026-09-28 to 2026-10-04", "Last 3 days, 2026-10-04 to 2026-10-06" or "2026-10-01 to 2026-10-03". */
+function winnersDatesTitle(window) {
+    const dates = `${window.from} to ${window.to}`;
+    if (window.kind === "week")
+        return `This week, ${dates}`;
+    return window.kind === "days" ? `Last ${counted(window.days, "day")}, ${dates}` : dates;
+}
 function winnersSendText(sent) {
-    const lines = [`Week ${sent.week.from} to ${sent.week.to}${sent.dryRun ? ", dry run: nothing was written to Exodus" : ""}.`];
+    const lines = [`${sent.window.kind === "week" ? "Week " : ""}${sent.window.from} to ${sent.window.to}${sent.dryRun ? ", dry run: nothing was written to Exodus" : ""}.`];
     if (sent.pages.length === 0)
         lines.push("No winners to send.");
     for (const page of sent.pages) {
@@ -2123,12 +2132,12 @@ function winnersSendText(sent) {
         lines.push("Left out:", ...sent.skipped.map((s) => `  ${s.adId}: ${s.reason}`));
     return `${lines.join("\n")}\n`;
 }
-/** The winners report as plain Markdown: what a sale means, then this week and the last 30 days, each currency apart. */
+/** The winners report as plain Markdown: what a sale means, then the dates asked for 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));
+        winnersWindowText(winnersDatesTitle(report.window), report.week) +
+        winnersWindowText(`Last 30 days, ${report.last30Days.from} to ${report.last30Days.to}`, report.last30Days));
 }
 function reportQuery(options, extra) {
     const query = new URLSearchParams();
@@ -2384,6 +2393,8 @@ Options:
   --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, 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)
+  --days <n>            winners: the last n complete days, ending yesterday, instead of a week (at most 90); or give winners
+                        --from and --to for any dates
   --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
@@ -2489,6 +2500,7 @@ function parseOptions(argv) {
             campaign: { type: "string" },
             top: { type: "string" },
             week: { type: "string" },
+            days: { type: "string" },
             name: { type: "string" },
             subject: { type: "string" },
             preview: { type: "string" },
@@ -2597,6 +2609,7 @@ function parseOptions(argv) {
             campaign: values.campaign,
             top: values.top,
             week: values.week,
+            days: values.days,
             name: values.name,
             subject: values.subject,
             preview: values.preview,

package/dist/playbooks.js

@@ -1558,15 +1558,15 @@ const testResultsSql = "SELECT test_id, currency, sum(spend) AS spend, sum(sales
 const lineageSql = "SELECT facebook_ad_id, hypothesis_id, test_id, creative_id, asset_version FROM adzara_ad_lineage ORDER BY synced_at DESC LIMIT 100";
 /** The commands the weekly loop shows, in order; its text is made from them, so a test runs exactly these. */
 export const weeklyLoopCommands = {
-    winners: { purpose: "the week's Facebook winners and flops, and the 30 days ending that Sunday, judged on real first-touch sales", argv: ["winners", "--week", "<week-monday>", "--format", "json"], mcp: "get_winners_report" },
+    winners: { purpose: "the Facebook winners and flops of the dates asked for, here a week, and of the 30 days ending on their last day, judged on real first-touch sales", argv: ["winners", "--week", "<week-monday>", "--format", "json"], mcp: "get_winners_report" },
     lessons: { purpose: "what earlier weeks taught, the most often seen first", argv: ["lessons", "--format", "json"], mcp: "get_lessons" },
     writeLessons: { purpose: "install the lessons playbook, then follow it to add, reinforce or retire this week's lessons", argv: ["skill", "install", "lessons"], mcp: "record_lesson" },
     voice: { purpose: "fresh customer words: the most usable single lines said since that Monday", argv: ["voice", "--since", "<week-monday>", "--sort", "useful", "--json"], mcp: "get_customer_voice" },
     brief: { purpose: "the campaign brief: offer, voice, lessons, best and worst ads, pages and audience, as Markdown", argv: ["brief"], mcp: "get_campaign_brief" },
     funnelMap: { purpose: "the offers and funnels map: what is sold, at what price, and the steps a buyer takes", argv: ["funnels", "show"], mcp: "get_funnel_map" },
     cro: { purpose: "install the cro playbook, then follow it to turn the funnel's costliest leaks into test ideas for the owner and read the running tests", argv: ["skill", "install", "cro"], mcp: "draft_funnel_test" },
-    exodusPreview: { purpose: "ask Exodus what it would make from the week's winners, writing nothing", argv: ["winners", "send-to-exodus", "--week", "<week-monday>", "--dry-run"], mcp: "send_winners_to_exodus" },
-    exodusSend: { purpose: "send the week's winners to Exodus so it makes new ads from them; sending again is safe", argv: ["winners", "send-to-exodus", "--week", "<week-monday>"], mcp: "send_winners_to_exodus" },
+    exodusPreview: { purpose: "ask Exodus what it would make from the winners of the same dates, writing nothing", argv: ["winners", "send-to-exodus", "--week", "<week-monday>", "--dry-run"], mcp: "send_winners_to_exodus" },
+    exodusSend: { purpose: "send those winners to Exodus so it makes new ads from them; sending again is safe", argv: ["winners", "send-to-exodus", "--week", "<week-monday>"], mcp: "send_winners_to_exodus" },
     paidTools: { purpose: "the paid making tools this workspace can run; each run costs money", argv: ["tools", "list"], mcp: "list_tools" },
     testResults: { purpose: "spend, first-touch sales and cost per sale for each Adzara test over the last 30 days", argv: ["warehouse", "query", testResultsSql], mcp: "query_warehouse" },
     lineage: { purpose: "which Meta ad carries which Adzara labels: idea, test, creative and version", argv: ["warehouse", "query", lineageSql], mcp: "query_warehouse" },
@@ -1586,7 +1586,7 @@ ${commandLine(c)}
 Without a shell: MCP \`${c.mcp}\`.`;
 export const weeklyLoopPlaybook = `# Weekly loop playbook (sample)
 
-A sample for a local orchestrator agent that runs a client's Facebook ads week with its owner. Once a week it reads what sold, learns from it, gathers fresh material, gets new ads made, has them published through Adzara, and later reads their results back. ${brand.name} supplies the data and keeps no part of the loop's decisions.
+A sample to borrow from, not a schedule, for a local orchestrator agent that runs a client's Facebook ads with its owner. It reads what sold, learns from it, gathers fresh material, gets new ads made, has them published through Adzara, and later reads their results back. It is written as a week, but its steps can run daily, several times a week or weekly, each on its own rhythm: the winners report covers whatever dates you ask for. ${brand.name} supplies the data and keeps no part of the loop's decisions.
 
 Every \`${cli}\` command acts on the one workspace the saved API key belongs to. Each step also names the MCP tool that does the same, for an agent connected over MCP without a shell.
 
@@ -1601,7 +1601,7 @@ Every \`${cli}\` command acts on the one workspace the saved API key belongs to.
 
 ${step(W.winners)}
 
-${W.winners.purpose[0].toUpperCase()}${W.winners.purpose.slice(1)}. Each ad has its \`numbers\`, \`pickedBecause\`, \`tags\` and Adzara \`test\`; each section's \`tests\` adds up each Adzara test. Leave out \`--week\` for the latest complete week.
+${W.winners.purpose[0].toUpperCase()}${W.winners.purpose.slice(1)}. Each ad has its \`numbers\`, \`pickedBecause\`, \`tags\` and Adzara \`test\`; each section's \`tests\` adds up each Adzara test. Leave out \`--week\` for the latest complete week. To check more often, swap \`--week\` for \`--days <n>\`, the last n complete days ending yesterday, or \`--from <YYYY-MM-DD> --to <YYYY-MM-DD>\` for any dates (the MCP tool takes \`week\`, \`days\` or \`from\` and \`to\`). A short window holds few sales, so fewer ads can be judged on sales and more are judged on sign-ups; the report says so in \`notes\`.
 
 ## 2. Lessons
 
@@ -1641,7 +1641,7 @@ Follow the installed skill. It drafts at most 3 funnel tests, each with one chan
 
 Exodus is one way to make ads among several. Pick what fits the week.
 
-**Exodus.** Preview what it would make from the week's winners, then send. The MCP tool takes \`week\` and \`dryRun\`. A real send needs the workspace's Exodus brand and a Scrape Creators key on the Exodus account.
+**Exodus.** Preview what it would make from the winners, then send. It takes the same dates as the winners report: \`--week\`, \`--days\` or \`--from\` and \`--to\`; over MCP, \`week\`, \`days\` or \`from\` and \`to\`, and \`dryRun\`. A real send needs the workspace's Exodus brand and a Scrape Creators key on the Exodus account.
 
 ${step(W.exodusPreview)}
 

package/package.json

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