@wrangled/cli 0.3.41 → 0.3.43

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 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 first lead 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 first leads, 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.
+\`${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 first lead 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 first leads, and the report says so. \`--top <n>\` how many ads, pages or pairs each list shows (default 5, at most 20), \`--ad-format image|video|carousel\` ranks only ads with that format tag (run \`${cli} ads tag-formats\` first; the account's cost per sale still counts every ad), and \`--format json\` gives the report as data.
 
 ## What winners and flops taught: lessons
 
@@ -227,6 +227,8 @@ Ads not made here (built by hand or by an agency, names in no pattern) get the m
 
 To suggest tags, write them as JSON and run \`${cli} ads tag --file tags.json\` (or pipe it on stdin), up to 500 ads at a time: \`{"ads": [{"ad_id": "120214567890123", "tags": {"angle": "discovery", "desire": "money", "hook_spot": "spoken", "hook_text": "$29,000 is the smallest lead", "hook_kind": "big_win", "format": "video", "style": "presenter", "tag_reasons": {"worry": "none"}}, "confidence": "medium", "evidence": {"ad_name": "County lead v2", "transcript_start": "$29,000 is the smallest lead"}}]}\`. The tag fields are \`marketing\`, \`offer_key\`, \`landing_funnel_key\`, \`landing_step_key\`, \`persona\`, \`awareness\`, \`concept\`, \`angle\`, \`desire\`, \`hook_spot\`, \`hook_text\`, \`hook_kind\`, \`hook2_spot\`, \`hook2_kind\`, \`format\`, \`style\`, \`speaker\`, \`cta\`, \`proof\` and \`worry\`; leave out what you did not judge. A part with no value goes in \`tag_reasons\` as \`none\` (nothing on its list applies) or \`unclear\` (too little to judge, never \`high\` confidence). Confidence is \`high\`, \`medium\` or \`low\`. A value off its list is refused with the allowed values. New tags replace an ad's proposed ones, which stay as \`replaced\`; an ad whose tags a person confirmed is kept as it is.
 
+Start with \`${cli} ads tag-formats\`: it tags every untagged ad's format (image, video or carousel) from Meta's own records and the content library, with no model call and no cost, so \`${cli} winners --ad-format image\` works at once. It goes through the ads in batches, printing progress, until none is left; running it again tags nothing new. Its rows are proposed, high confidence, with \`evidence.tagger\` \`meta_format\`, and hold only the format: \`${cli} ads autotag\` still tags those ads and keeps the format, and so does a proposal of yours that leaves format out.
+
 To have the server tag ads for you, run \`${cli} ads autotag\` (\`--limit <n>\`, 1 to 100, default 25; \`--ad <id>\` for one ad; \`--json\`). It takes the biggest spenders with no tags yet, so each run moves on to the next ones (with \`--ad\`, that ad, its proposed tags asked about again and confirmed ones kept), reads each one's copy, video transcript and picture description, and asks TypeSafe's Jev the grammar's questions through the tool gateway, so a run's tool cap applies. Ads with the same copy, headlines, button, link and media are asked about once and share the tags; asking again about an unchanged ad costs nothing. It costs a tiny fraction of a cent per ad. The tags are proposed, with each part's confidence in the evidence; read them with \`${cli} ads tags\`. The \`back-tag\` playbook (\`${cli} skill install back-tag\` installs it as the \`${BACK_TAG_SKILL_NAME}\` skill; \`${cli} docs back-tag\` prints it) runs it in batches over a client's old ads and reports how much of the spend is tagged; a person then checks the ads carrying the top 20% of spend on the app's Tag check page.
 
 For what worked, query the \`ad_performance_tagged\` view: every Meta ad's daily results with its live tags next to them, \`tags_source\` (\`ad_tags\`, or null when untagged) and \`tags_status\`.
@@ -299,7 +301,7 @@ ${cli} brief [--from <date>] [--to <date>] [--channel <channel>] [--campaign <id
 ${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} messages results [--from <date>] [--to <date>] [--channel email|text] [--sequence <id>]   real sales after each follow-up email, text and sequence: every message the buyer clicked or replied to in the ${MESSAGE_CREDIT_DAYS} days before buying (helped), and the latest one (last nudge)
-${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 [--week <date> | --days <n> | --from <date> --to <date>] [--top <n>] [--ad-format image|video|carousel]   which Facebook ads and landing pages won and flopped in a week or any dates and over 30 days, judged on first-touch sales, or on Triple Whale's orders for a shop that has them
 ${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
@@ -358,6 +360,7 @@ ${cli} facts propose --file <fact.json>   suggest a fact for a person to confirm
 ${cli} lessons [--status active|retired] [--about ads|pages|funnel|messages|cross_channel] [--dimension <d>] | lessons add --file <lesson.json> | lessons retire <id> --note "<why>"   lessons from winners and flops, writing one, retiring one
 ${cli} tests [--status <status>] [--funnel <key>] [--limit <n>] | tests show <id> | tests draft --file <test.json> | tests start <id> | tests abandon <id> [--note "<why>"] | tests results <id> | tests decide <id> --decision <d> [--note "<why>"]   funnel tests, one change each
 ${cli} ads tags [--ad <id>] [--status <status>] [--limit <n>] | ads tag --file <tags.json>   the marketing tags of ads not made here, and suggesting them
+${cli} ads tag-formats   tag every untagged ad's format (image, video or carousel) from Meta's records, free; run it before ads autotag
 ${cli} ads autotag [--limit <n>] [--ad <id>]   have the server propose tags for the biggest spenders not yet tagged
 ${cli} content tags [<item-id>] [--kind email|text|page] | content to-check   the marketing tags of emails, texts and landing pages, and those waiting for a person
 ${cli} content autotag [<item-id> ...] [--kind email|text|page] [--limit <n>]   have the server propose tags for the emails, texts and pages worth most not yet tagged

package/dist/main.js

@@ -681,12 +681,12 @@ const commands = {
         },
     },
     winners: {
-        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)",
+        usage: "winners [--week <YYYY-MM-DD> | --days <n> | --from <YYYY-MM-DD> --to <YYYY-MM-DD>] [--top <n>] [--ad-format image|video|carousel]   (which Facebook ads and landing pages won and flopped, judged on real sales: first-touch, or Triple Whale's orders when the workspace has them)",
         async run(args, options) {
             if (args.length > 0)
-                throw new CliError("Usage: winners [--week <date> | --days <n> | --from <date> --to <date>] [--top <n>]", exitCodes.usage);
+                throw new CliError("Usage: winners [--week <date> | --days <n> | --from <date> --to <date>] [--top <n>] [--ad-format image|video|carousel]", exitCodes.usage);
             const query = new URLSearchParams();
-            for (const [name, value] of Object.entries({ ...winnersPeriod(options), top: options.top }))
+            for (const [name, value] of Object.entries({ ...winnersPeriod(options), top: options.top, format: options.entryTags.format }))
                 if (value !== undefined)
                     query.set(name, value);
             const report = await api(await resolveConnection(options.apiUrl), `/api/v1/winners${query.size ? `?${query}` : ""}`);
@@ -1326,6 +1326,33 @@ const commands = {
                 console.log(`Left out ${plural(result.nothingToRead)} with nothing to read: no copy, headline, transcript or picture description.`);
         },
     },
+    "ads tag-formats": {
+        usage: "ads tag-formats [--limit <n>] [--json]   tag every untagged ad's format (image, video or carousel) from Meta's records; free, no model",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: ads tag-formats [--limit <n>] [--json]", exitCodes.usage);
+            const connection = await resolveConnection(options.apiUrl);
+            const total = { tagged: 0, no_format: 0 };
+            let after = null;
+            for (;;) {
+                const body = { ...(after === null ? {} : { after }), ...(options.limit ? { limit: Number(options.limit) } : {}) };
+                const batch = await api(connection, AD_FORMATS_PATH, body);
+                total.tagged += batch.tagged;
+                total.no_format += batch.no_format;
+                if (options.format !== "json")
+                    console.error(`Tagged ${total.tagged} so far; ${batch.remaining} untagged ${batch.remaining === 1 ? "ad" : "ads"} left to look at.`);
+                if (batch.remaining === 0 || batch.next === null)
+                    break;
+                after = batch.next;
+            }
+            if (options.format === "json")
+                return printJson(total);
+            const plural = (n) => `${n} ${n === 1 ? "ad" : "ads"}`;
+            console.log(`Tagged the format of ${plural(total.tagged)}. Each is proposed, read from Meta's records; ads autotag still adds the other tags and keeps the format.`);
+            if (total.no_format > 0)
+                console.log(`Left ${plural(total.no_format)} untagged: neither Meta nor the content library says their format.`);
+        },
+    },
     "content tags": {
         usage: "content tags [<item-id>] [--kind email|text|page] [--status <status>] [--limit <n>] [--json]   the marketing tags of emails, texts and landing pages",
         async run(args, options) {
@@ -2041,7 +2068,9 @@ function money(value, currency) {
         return `${value.toFixed(2)} ${currency}`;
     }
 }
-const counted = (n, one) => `${n} ${n === 1 ? one : `${one}s`}`;
+/** A model that splits credit between ads gives fractional counts: show tenths at most, grouped as the server writes them. */
+const tenths = (n) => n.toLocaleString("en-US", { maximumFractionDigits: 1 });
+const counted = (n, one) => `${tenths(n)} ${tenths(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;
@@ -2052,7 +2081,8 @@ function winnersAdLines(ad, currency) {
     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, "first lead");
-    return `- ${name}: spent ${money(n.spend, currency)}, ${count ? `${count}, ` : ""}${cost}${tags ? `. Tags: ${tags}` : ""}\n  ${ad.pickedBecause}\n`;
+    const facebook = n.facebookResults == null ? "" : `, Facebook counts ${tenths(n.facebookResults)}`;
+    return `- ${name}: spent ${money(n.spend, currency)}, ${count ? `${count}, ` : ""}${cost}${facebook}${tags ? `. Tags: ${tags}` : ""}\n  ${ad.pickedBecause}\n`;
 }
 /** A page's or pair's line: the ad for a pair, the page, its visits and numbers, then why it is on the list. */
 function winnersPageLines(page, currency) {
@@ -2090,7 +2120,7 @@ function winnersWindowText(title, window) {
                 : s.accountCostPerSale === null
                     ? "no sale credited to a Facebook ad in these dates"
                     : `the account paid ${money(s.accountCostPerSale, s.currency)} per sale`;
-            const tied = s.adSales === null || !s.facebookSales ? "" : ` ${s.adSales} of ${counted(s.facebookSales, "Facebook sale")} could be tied to a specific ad.`;
+            const tied = s.adSales === null || !s.facebookSales ? "" : ` ${tenths(s.adSales)} of ${counted(s.facebookSales, "Facebook sale")} could be tied to a specific ad.`;
             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}.${tied} ${s.adsJudgedOnSales} judged on sales, ${s.adsJudgedOnSignups} judged on first leads.\n` +
@@ -2143,12 +2173,18 @@ 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 the dates asked for and the last 30 days, each currency apart. */
+/** How an older server, which sent no rule, credited a sale. */
+const FIRST_TOUCH_SALE_RULE = "Each sale goes to the Facebook ad that first brought the buyer in; payments typed into GoHighLevel by hand never count toward an ad.";
+/**
+ * The winners report as plain Markdown: what a sale means, then the dates asked for and, unless they are the same dates,
+ * 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(winnersDatesTitle(report.window), report.week) +
-        winnersWindowText(`Last 30 days, ${report.last30Days.from} to ${report.last30Days.to}`, report.last30Days));
+    const { week, last30Days } = report;
+    return (`# Winners and flops for ${report.workspace}${report.format ? `, ${report.format} ads only` : ""}\n\n` +
+        `A sale means ${report.saleMeans}. ${report.saleRule ?? FIRST_TOUCH_SALE_RULE}\n` +
+        winnersWindowText(winnersDatesTitle(report.window), week) +
+        (week.from === last30Days.from && week.to === last30Days.to ? "" : winnersWindowText(`Last 30 days, ${last30Days.from} to ${last30Days.to}`, last30Days)));
 }
 function reportQuery(options, extra) {
     const query = new URLSearchParams();
@@ -2247,6 +2283,7 @@ const FACTS_PATH = "/api/v1/facts";
 const AD_TAGS_PATH = "/api/v1/ad-tags";
 const KNOWLEDGE_TAGS_PATH = "/api/v1/knowledge/tags";
 const AD_AUTOTAG_PATH = "/api/v1/ad-tags/autotag";
+const AD_FORMATS_PATH = "/api/v1/ad-tags/formats";
 const SKIP_REASONS = { not_marketing: "Not marketing, so only that answer was saved", gate_unclear: "Could not tell whether it is marketing, so only that was saved", no_content: "Nothing to read", not_found: "No such ad" };
 const AD_TAG_COLUMNS = ["id", "ad", "status", "confidence", "offer", "persona", "angle", "hook", "format", "author"];
 const CONTENT_TAGS_PATH = "/api/v1/content-tags";
@@ -2493,10 +2530,12 @@ Options:
   --sort <column>       how content search sorts: recent (default) or a content_scorecard number, such as click_rate or roas
   --order desc|asc      content search's sort direction (default: desc, best or newest first)
   --limit <n>           how many results content search, creatives list, campaigns, voice, ads tags, content tags and content to-check
-                        return, or how many ads ads autotag tags and how many items content autotag tags
+                        return, how many ads ads autotag tags and how many items content autotag tags, or how many
+                        ads each ads tag-formats batch looks at (default 2000)
   --library <slug>      with knowledge search, only this library: creative-cartel, exodus or meta-policy
   --angle, --hook-kind, --ad-format, --awareness <value>   with knowledge search, only library entries tagged that way, and
-                        your own ads tagged the same way with their results; with knowledge tag, the tags to put on an entry
+                        your own ads tagged the same way with their results; with knowledge tag, the tags to put on an entry;
+                        with winners, --ad-format ranks only ads whose format tag is that one (run ads tag-formats first)
   --confidence high|medium|low   with knowledge tag, how sure you are of the tags
   --remove              with knowledge tag, take the tags off instead
   --ad <id>             with ads tags, only this Meta ad's tags; with ads autotag, only this ad

package/dist/playbooks.js

@@ -818,9 +818,15 @@ export const BACK_TAG_SKILL_NAME = `${cli}-back-tag`;
 export const BACK_TAG_BATCH = 100;
 /** Batches a run stops after unless the person asked for more. */
 export const BACK_TAG_MAX_BATCHES = 20;
+/** evidence.tagger of a format-only row read from Meta's records; the server's META_FORMAT_TAGGER. */
+export const META_FORMAT_TAGGER = "meta_format";
 /** The warehouse query the back-tag playbook reports coverage with, exported so tests run the same SQL. */
 export const backTagQueries = {
-    coverage: `WITH a AS (SELECT currency, ad_id, coalesce(sum(spend), 0) AS spend, max(tags_status) AS status FROM ad_performance_tagged GROUP BY currency, ad_id)
+    // A proposed row read from Meta's records holds only the format, so its ad still counts as untagged.
+    coverage: `WITH a AS (
+  SELECT p.currency, p.ad_id, coalesce(sum(p.spend), 0) AS spend,
+    max(CASE WHEN p.tags_status = 'proposed' AND t.evidence->>'tagger' = '${META_FORMAT_TAGGER}' THEN NULL ELSE p.tags_status END) AS status
+  FROM ad_performance_tagged p LEFT JOIN ad_tags t ON t.id = p.tags_id GROUP BY p.currency, p.ad_id)
 SELECT currency,
   count(*) FILTER (WHERE spend > 0) AS ads_with_spend,
   count(*) FILTER (WHERE spend > 0 AND status IS NOT NULL) AS ads_tagged,
@@ -867,7 +873,7 @@ It answers one row per currency, since money is never added across currencies: a
 ${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:
+Each call takes the ${BACK_TAG_BATCH} biggest-spending ads with no tags yet, so the next call moves on to the next ones. An ad whose only tag is its format, read from Meta's records by \`${cli} ads tag-formats\`, counts as not tagged yet; the tagger keeps that format. 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\`. Asking again won't help.
 - You have run ${BACK_TAG_MAX_BATCHES} batches, or the person's spending limit would be passed.
@@ -1558,7 +1564,7 @@ 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 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" },
+    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 sales (first-touch, or Triple Whale's orders when the workspace has them)", 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" },

package/package.json

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