@wrangled/cli 0.3.148 → 0.3.150

package/dist/guide.js

@@ -156,6 +156,7 @@ For "how is the funnel doing?", "which campaigns are working?" and "where does t
 - \`${cli} funnel [--grain day|week|month]\` prints ad spend, leads, booked calls, calls held, sales and net revenue per day, week (starting Monday) or month, with cost per lead, per booked call and per sale and ROAS, then totals for the whole range.
 - \`${cli} campaigns [--channel <channel>] [--limit <n>]\` prints each campaign's spend, leads, booked calls, sales and revenue, best first (most first-touch revenue, then most spend), then totals over every matching campaign. Each lead and sale is credited to the person's first touch and last touch side by side. \`--limit\` is 1 to 200 (default 50); \`--channel\` is meta, google, affiliate, a utm_source, unknown or recorded_in_crm.
 - \`${cli} money [--grain day|week|month]\` prints money in (gross, refunds, net, orders), ad spend, affiliate payouts, what is left after ad costs and ROAS per period, then totals for the whole range, money in per payment source (stripe, ghl) and the biggest refund days. Refunds come off on the day they were made, not the day of the sale. \`left_after_ad_costs\` is net less ad spend and affiliate payouts; it is not profit. Its \`roas\` is net over ad spend alone, so it differs from \`${cli} funnel\`'s, which divides by all spend including affiliate payouts.
+- When no payment tool, store or CRM sales are connected but Triple Whale is, \`${cli} money\` takes money in from Triple Whale's store totals and \`${cli} campaigns\` adds the orders, revenue and ROAS Triple Whale credits to each Facebook campaign (\`orders_triple_whale\`, \`revenue_triple_whale\`, \`roas_triple_whale\`), counted as \`${cli} winners\` counts them. Each says so under its table. Triple Whale can credit one order to several ads, so campaign orders can add up to more than the store's. With neither, each report says what is missing and leaves out the columns that would be blank.
 - Money is never converted or added across currencies: there is one row per currency, and one total per currency. In \`${cli} funnel\`, leads and calls are counted for the whole period and repeat on every currency row, so never add them across its rows. In \`${cli} campaigns\`, each campaign's leads and calls sit on the row of the currency it spends in (or a blank-currency row when it has no spend), so they do add up across rows and totals. Ratios come from the summed numbers, not averages. An empty cell means the source is not connected, or a ratio would divide by 0.
 - \`${cli} metrics query --metric <name> [--by <dimension>]...\` gives any of the standard numbers by name, split and filtered your way, such as \`--metric spend --metric cost_per_lead --by channel --where channel!=affiliate --sort=-spend\`. It sums the parts before dividing, keeps currencies apart, credits leads and sales by channel or campaign to the first touch (\`--attribution last_touch\` for the last), and prints an empty number, never 0, for a source that is not connected. An unknown name fails with the list of real ones. Use it before writing SQL for a number these reports do not split the way you need.
 - \`${cli} metrics search "<everyday words>"\` finds the name \`metrics query\` takes from your own words, such as \`"show rate"\`, \`"cost per booked call"\` or \`"first time buyers"\`: each match with what it means, which of the client's sources feed it and whether they are connected, and for a split like channel or campaign up to five of the client's own values. \`${cli} metrics list\` prints every number and split. The client's own confirmed labels and numbers show beside the catalog's, marked "(custom)". Search before guessing a name.
@@ -567,6 +568,7 @@ ${cli} facts [--kind <kind>] [--subject <type>[:<ref>]] [--status <status>] [--j
 ${cli} number-alerts [--since <date>]   the key numbers that swung far from normal, day by day
 ${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 p1   this brand's P1 test ads by verdict, judged on its own sales against its P1 thresholds, with Meta's count beside
 ${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 names [--unparsed]   Meta ad names and the tags each gives; --unparsed lists those that fit no pattern

package/dist/main.js

@@ -7,6 +7,7 @@ import { basename, dirname, extname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { api, ApiError, apiDownload, apiText, apiUpload, CliError, exitCodes, getSigned, IMPORT_LIMITS, DOCUMENT_LIMITS, META_IDS_MAX, PROFILE_MESSAGING_KINDS, OUTCOME_PARTS, FACET_WORDS, GOOGLE_ADS_IDS_MAX, IMPORT_NAME_PATTERN, AGENT_TABLE_LIMITS, AGENT_TABLE_NAME_PATTERN, putSigned, CLIENT_FILE, parseClientName, readSavedLogins, removeCredentials, resolveApiUrl, resolveConnection, resolveLogin, UnreadableCredentialsError, writeCredentials, OUTBOUND_PUSH_MAX, entryTagFlags, streamSigned, } from "./api.js";
 import { brand, envPrefix } from "./brand.js";
+import { campaignLayout, money, moneyLayout } from "./report-columns.js";
 import { renderDataMap, renderQuestions } from "./map.js";
 import { apiSetupPath, parseAuthFlag, parseQueryFlags, setupText, submittedText, testText, tryText, waitingText, } from "./api-setup.js";
 import { answerRow, batches, ENRICH_EMAIL_USAGE, parsePeople, parseSteps } from "./enrich.js";
@@ -242,7 +243,7 @@ const commands = {
             const { funnel } = await api(await resolveConnection(options), `/api/v1/reports/funnel${query}`);
             if (options.format === "json")
                 return printJson({ funnel });
-            printReport(`Funnel by ${funnel.grain}`, funnel, ["period", "currency"], FUNNEL_NUMBERS);
+            printReport(`Funnel by ${funnel.grain}`, funnel, ["period", "currency"], { numbers: FUNNEL_NUMBERS, before: [], after: [] });
             printLeftOut(funnel.left_out, "sales, revenue_net and roas");
         },
     },
@@ -480,7 +481,7 @@ const commands = {
             const { money } = await api(await resolveConnection(options), `/api/v1/reports/money${query}`);
             if (options.format === "json")
                 return printJson({ money });
-            printReport(`Money by ${money.grain}`, money, ["period", "currency"], MONEY_NUMBERS);
+            printReport(`Money by ${money.grain}`, money, ["period", "currency"], moneyLayout(money));
             if (money.by_source.length > 0)
                 console.log(`\nMoney in by payment source:\n${renderTable(["source", "currency", "gross", "refunds", "net", "orders"], money.by_source)}`);
             if (money.store_orders_in_stripe?.length) {
@@ -552,7 +553,7 @@ const commands = {
             if (options.format === "json")
                 return printJson({ campaignResults });
             const title = campaignResults.channel === null ? "Campaigns, best first" : `${campaignResults.channel} campaigns, best first`;
-            printReport(title, campaignResults, ["channel", "campaign_id", "campaign_name", "currency"], CAMPAIGN_NUMBERS);
+            printReport(title, campaignResults, ["channel", "campaign_id", "campaign_name", "currency"], campaignLayout(campaignResults));
             printLeftOut(campaignResults.left_out, "the totals (the rows keep it)");
         },
     },
@@ -3154,6 +3155,17 @@ const commands = {
             console.log(renderTable(TEST_COLUMNS, tests.map(testRow)));
         },
     },
+    "tests p1": {
+        usage: "tests p1   this brand's P1 test ads by verdict (working, not working, paused, ready for P3, still testing), judged on its own sales against its P1 thresholds",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: tests p1", exitCodes.usage);
+            const report = await api(await resolveConnection(options), "/api/v1/p1-tests");
+            if (options.format === "json")
+                return printJson(report);
+            process.stdout.write(p1TestsText(report));
+        },
+    },
     "tests show": {
         usage: "tests show <id|test_id>   one funnel test in full",
         async run(args, options) {
@@ -4092,27 +4104,6 @@ function historyText(history) {
     return main + catchingUp.join("");
 }
 const FUNNEL_NUMBERS = ["spend", "leads", "booked_calls", "calls_held", "sales_count", "revenue_net", "new_buyers", "cost_per_lead", "cost_per_booked_call", "cost_per_sale", "cost_per_new_buyer", "roas"];
-const MONEY_NUMBERS = ["gross", "refunds", "net", "orders", "ad_spend", "affiliate_payouts", "left_after_ad_costs", "roas"];
-const CAMPAIGN_NUMBERS = [
-    "spend",
-    "leads_first_touch",
-    "leads_last_touch",
-    "booked_calls_first_touch",
-    "sales_first_touch",
-    "revenue_first_touch",
-    "revenue_last_touch",
-    "cost_per_lead_first_touch",
-    "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}`;
-    }
-}
 function newIdeasLine({ target, proposedToday, stalled, costPerResult: cpr }, ideasPerDay) {
     const split = `${target} of ${ideasPerDay}${proposedToday > 0 ? `, ${proposedToday} already proposed` : ""}`;
     if (!cpr)
@@ -4247,6 +4238,45 @@ const FIRST_TOUCH_SALE_RULE = "Each sale goes to the Facebook ad that first brou
  * The winners report as plain Markdown: which goal the ads are judged on and what one means, then the dates asked for and,
  * unless they are the same dates, the last 30 days, each currency apart.
  */
+const P1_GROUPS = [
+    ["working", "Working"],
+    ["not_working", "Not working"],
+    ["paused", "Paused"],
+    ["ready_for_p3", "Ready for P3"],
+    ["testing", "Still testing"],
+    [null, "No verdict"],
+];
+function p1TestsText(report) {
+    const { window, thresholds: t, judgedOn } = report;
+    const lines = [`P1 tests for ${report.brand}, ${window.from} to ${window.to} (${window.days} days), judged on ${judgedOn.label}`];
+    const amount = (n, currency) => (n === null ? "" : currency === null ? n.toFixed(2) : money(n, currency));
+    if (t !== null) {
+        const currency = report.ads.find((ad) => ad.currency !== null)?.currency ?? null;
+        lines.push(`Thresholds: not working after ${amount(t.minSpend, currency)} spent; working at ${amount(t.maxCostPerResult, currency)} or less per ${judgedOn.one}; ` +
+            `ready for P3 at ${t.p3MinResults} or more at ${amount(t.p3MaxCostPerResult, currency)} or less each`);
+    }
+    if (report.missing !== null)
+        lines.push(report.missing);
+    const columns = ["ad", "campaign", "spend", `results (${judgedOn.label})`, "Meta's count", "cost per result", "why"];
+    for (const [verdict, title] of P1_GROUPS) {
+        const ads = report.ads.filter((ad) => ad.verdict === verdict);
+        if (ads.length === 0)
+            continue;
+        const rows = ads.map((ad) => ({
+            ad: `${ad.name} (${ad.adId})`,
+            campaign: ad.campaignName,
+            spend: amount(ad.spend, ad.currency),
+            [columns[3]]: String(ad.results),
+            "Meta's count": ad.metaResults === null ? "" : `${ad.metaResults}${ad.metaDisagrees ? " (differs)" : ""}`,
+            "cost per result": amount(ad.costPerResult, ad.currency),
+            why: ad.because,
+        }));
+        lines.push("", `${title} (${ads.length})`, renderTable(columns, rows));
+    }
+    if (report.ads.length === 0)
+        lines.push("", "No live ads in the P1 campaigns.");
+    return `${lines.join("\n")}\n`;
+}
 function winnersText(report) {
     const { week, last30Days } = report;
     const words = winnersWords(report);
@@ -4528,13 +4558,19 @@ function printLeftOut(leftOut, figures) {
     const rows = leftOut.flatMap((l) => l.amounts.map((a) => ({ fact: l.fact_id, currency: a.currency, revenue: a.revenue, sales: a.sales, rule: l.summary })));
     console.log(`\nLeft out of ${figures} by confirmed leave-out rules:\n${renderTable(["fact", "currency", "revenue", "sales", "rule"], rows)}`);
 }
-function printReport(title, report, labels, numbers) {
+function printReport(title, report, labels, { numbers, before, after }) {
+    if (before.length > 0)
+        console.log(`${before.join("\n")}\n`);
     if (report.rows.length === 0)
-        return console.log(`No numbers from ${report.from} to ${report.to}.`);
-    console.log(`${title}, ${report.from} to ${report.to}:`);
-    console.log(renderTable([...labels, ...numbers], report.rows));
-    console.log("\nTotals:");
-    console.log(renderTable(["currency", ...numbers], report.totals));
+        console.log(`No numbers from ${report.from} to ${report.to}.`);
+    else {
+        console.log(`${title}, ${report.from} to ${report.to}:`);
+        console.log(renderTable([...labels, ...numbers], report.rows));
+        console.log("\nTotals:");
+        console.log(renderTable(["currency", ...numbers], report.totals));
+    }
+    for (const line of after)
+        console.log(line);
 }
 const agentPath = (options) => `/api/v1/agents/${encodeURIComponent(options.agent)}`;
 const FACTS_PATH = "/api/v1/facts";

package/dist/report-columns.js

@@ -0,0 +1,57 @@
+import { brand } from "./brand.js";
+export const MONEY_NUMBERS = ["gross", "refunds", "net", "orders", "ad_spend", "affiliate_payouts", "left_after_ad_costs", "roas"];
+export const CAMPAIGN_NUMBERS = [
+    "spend",
+    "leads_first_touch",
+    "leads_last_touch",
+    "booked_calls_first_touch",
+    "sales_first_touch",
+    "revenue_first_touch",
+    "revenue_last_touch",
+    "cost_per_lead_first_touch",
+    "roas_first_touch",
+    "roas_last_touch",
+];
+const MONEY_IN_NUMBERS = new Set(["gross", "refunds", "net", "orders", "left_after_ad_costs", "roas"]);
+const TRIPLE_WHALE_NUMBERS = ["orders_triple_whale", "revenue_triple_whale", "roas_triple_whale"];
+const NO_CRM_SALES = "no payment tool, store or CRM sales are connected";
+export function money(value, currency) {
+    try {
+        return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(value);
+    }
+    catch {
+        return `${value.toFixed(2)} ${currency}`;
+    }
+}
+/** A server older than this CLI sends no sales_from; its money in is daily_sales'. */
+export function moneyLayout({ sales_from: from }) {
+    if (from === undefined || from.source === "daily_sales")
+        return { numbers: MONEY_NUMBERS, before: [], after: [] };
+    if (from.source === null)
+        return { numbers: MONEY_NUMBERS.filter((n) => !MONEY_IN_NUMBERS.has(n)), before: [from.why], after: [] };
+    return { numbers: MONEY_NUMBERS, before: [], after: [`\nMoney in is Triple Whale's ${from.detail}, because ${NO_CRM_SALES}.`] };
+}
+const blankEverywhere = (column, rows) => rows.every((row) => row[column] === null || row[column] === undefined);
+/**
+ * Without daily_sales, the first- and last-touch columns blank in every row and total are left out, and with Triple
+ * Whale its own orders, revenue and return on ad spend are added.
+ */
+export function campaignLayout(report) {
+    const from = report.sales_from;
+    if (from === undefined || from.source === "daily_sales")
+        return { numbers: CAMPAIGN_NUMBERS, before: [], after: [] };
+    const all = [...report.rows, ...report.totals];
+    const touches = CAMPAIGN_NUMBERS.filter((n) => n === "spend" || !blankEverywhere(n, all));
+    if (from.source === null)
+        return { numbers: touches, before: [from.why], after: [] };
+    const others = (report.triple_whale_other_campaigns ?? []).map(({ currency, orders, revenue }) => `Triple Whale credits ${orders} more ${orders === 1 ? "order" : "orders"}${revenue === null || currency === null ? "" : ` (${money(revenue, currency)})`} to Facebook ads that aren't in the ad accounts ${brand.name} is connected to, so they aren't in the rows above.`);
+    return {
+        numbers: [...touches, ...TRIPLE_WHALE_NUMBERS],
+        before: [],
+        after: [
+            `\nOrders and revenue are what Triple Whale credits to each Facebook campaign (${from.detail}), because ${NO_CRM_SALES}. ` +
+                "Triple Whale can credit one order to more than one ad, so these can add up to more than the store's own orders.",
+            ...others,
+        ],
+    };
+}

package/package.json

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