@wrangled/cli 0.3.151 → 0.3.153

package/dist/ad-calls.js

@@ -0,0 +1,20 @@
+import { renderTable } from "./table.js";
+const COLUMNS = ["ad_id", "ad_name", "meta", "first_touch", "first_delta", "last_touch", "last_delta"];
+const count = (n) => (n === null ? "n/a" : String(n));
+const signed = (n) => (n !== null && n > 0 ? `+${n}` : count(n));
+function counted(report) {
+    if (report.event !== null)
+        return `Meta's ${report.event} events`;
+    if (report.result_types.length === 0)
+        return "Meta's results";
+    return `Meta's results (${report.result_types.join(", ")})`;
+}
+export function renderAdCalls(report) {
+    const header = `Calls per Facebook ad ${report.from} to ${report.to}: ${counted(report)} against booked calls credited to the first and last touch. Deltas are booked minus Meta.`;
+    if (report.ads.length === 0)
+        return `${header}\nNo ad has calls in either source.\n`;
+    const row = (c) => ({ meta: count(c.meta_calls), first_touch: count(c.first_touch), first_delta: signed(c.first_touch_delta), last_touch: count(c.last_touch), last_delta: signed(c.last_touch_delta) });
+    const table = renderTable(COLUMNS, [...report.ads.map((a) => ({ ad_id: a.ad_id, ad_name: a.ad_name, ...row(a) })), { ad_id: "total", ...row(report.totals) }]);
+    const unconnected = report.booked_calls_connected ? "" : "No booked-call source is connected, so booked calls and deltas are n/a.\n";
+    return `${header}\n${table}\n${unconnected}`;
+}

package/dist/guide.js

@@ -155,6 +155,8 @@ 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} calls unattributed [--attribution first_touch|last_touch] [--limit <n>]\` answers "why do these booked calls have no ad?": it counts the booked calls in the range (by day booked), how many were credited to a Facebook ad and how many were not, as \`ad_results_daily\` credits them (to the first touch by default), splits the calls with no ad by why (\`no_person\`: the booking's contact has no email or phone to match a person; \`meta_without_ad\`: a Facebook visit whose link named no single ad; \`not_meta\`: another channel; \`visit_after_call\`: the visits are dated after the booking; \`last_visit_only\`: only a latest visit, no first; \`no_visit\`: no tagged visit at all), then lists those calls newest first with the booking's contact id, the person id and the touch's channel, campaign, ad and landing page. With and without add up to every booked call. \`--limit\` is 1 to 1000 (default 200); the counts always cover every call. The rows are in the \`booked_call_credits\` view; join \`touches\` on \`person_id\` to see each visit's tags.
+- \`${cli} calls compare [--event <event>]\` answers "do Meta's call numbers match the booked calls?": per Facebook ad over the range, the calls Meta reports (its results, the workspace's chosen result type as Ads Manager shows it, or with \`--event\` that one Meta action type, such as schedule_website), the booked calls \`ad_results_daily\` credits to the ad on the first touch and on the last touch, and each delta, booked minus Meta (negative when Meta reports more). An ad missing from one source counts 0 there. Most Meta calls first, then a total row; \`--format json\` gives the same numbers.
 - \`${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.

package/dist/main.js

@@ -9,6 +9,8 @@ import { api, ApiError, apiDownload, apiText, apiUpload, CliError, exitCodes, ge
 import { brand, envPrefix } from "./brand.js";
 import { campaignLayout, money, moneyLayout } from "./report-columns.js";
 import { renderDataMap, renderQuestions } from "./map.js";
+import { renderAdCalls } from "./ad-calls.js";
+import { renderUnattributedCalls } from "./unattributed-calls.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";
 import { sendCopies, sendStatusChanges } from "./meta-progress.js";
@@ -577,6 +579,33 @@ const commands = {
             printLeftOut(campaignResults.left_out, "the totals (the rows keep it)");
         },
     },
+    "calls unattributed": {
+        usage: "calls unattributed [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--attribution first_touch|last_touch] [--limit <n>]   (booked calls credited to no Facebook ad, and why each one has none)",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: calls unattributed [--from <date>] [--to <date>] [--attribution first_touch|last_touch] [--limit <n>]", exitCodes.usage);
+            const touch = options.attribution === undefined ? undefined : CALL_TOUCHES.get(options.attribution);
+            if (options.attribution !== undefined && touch === undefined)
+                throw new CliError("--attribution is first_touch or last_touch.", exitCodes.usage);
+            const query = reportQuery(options, { touch, limit: options.limit });
+            const { unattributedCalls } = await api(await resolveConnection(options), `/api/v1/reports/unattributed-calls${query}`);
+            if (options.format === "json")
+                return printJson({ unattributedCalls });
+            process.stdout.write(renderUnattributedCalls(unattributedCalls));
+        },
+    },
+    "calls compare": {
+        usage: "calls compare [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--event <event>]   (calls per Facebook ad: what Meta reports next to the booked calls credited on the first and last touch)",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: calls compare [--from <date>] [--to <date>] [--event <event>]", exitCodes.usage);
+            const query = reportQuery(options, { event: options.event });
+            const { adCalls } = await api(await resolveConnection(options), `/api/v1/reports/ad-calls${query}`);
+            if (options.format === "json")
+                return printJson({ adCalls });
+            process.stdout.write(renderAdCalls(adCalls));
+        },
+    },
     "tools list": {
         usage: "tools list",
         async run(_args, options) {
@@ -4449,6 +4478,10 @@ function amountOption(flag, value) {
         throw new CliError(`${flag} must be a number above 0, such as 10000.`, exitCodes.usage);
     return n;
 }
+const CALL_TOUCHES = new Map([
+    ["first_touch", "first"],
+    ["last_touch", "last"],
+]);
 function reportQuery(options, extra) {
     const query = new URLSearchParams();
     for (const [name, value] of Object.entries({ from: options.from, to: options.to, ...extra }))
@@ -5039,8 +5072,8 @@ Options:
   --where <json | @file.json>   tables delete-rows: {column: value} pairs a row must all match to be deleted
   --mode append|replace tables import: add the file's rows (default) or replace every row the table has
   --yes                 confirm intake delete, import remove, tables drop, content collections remove or remove-item, which delete saved data for good
-  --from <YYYY-MM-DD>   first day funnel, campaigns, money, metrics query, brief, pages results and messages results cover (default: 29 days before --to)
-  --to <YYYY-MM-DD>     last day funnel, campaigns, money, metrics query, brief, pages results and messages results cover (default: today in the workspace reporting time zone);
+  --from <YYYY-MM-DD>   first day funnel, campaigns, money, calls unattributed, calls compare, metrics query, brief, pages results and messages results cover (default: 29 days before --to)
+  --to <YYYY-MM-DD>     last day funnel, campaigns, money, calls unattributed, calls compare, metrics query, brief, pages results and messages results cover (default: today in the workspace reporting time zone);
                         for outbound push, where the leads go: instantly:<campaign-id>
   --grain <grain>       how funnel and money group days: day (default), week (starting Monday) or month
   --month <YYYY-MM>     the month tools usage covers, in the workspace reporting time zone (default: this month)
@@ -5050,7 +5083,8 @@ Options:
                         Facebook ad, ad set or ad name (ad, adset, creative), or by a confirmed custom label (metrics custom list); repeat for
                         several
   --where <dim>=<v,v>   metrics query and feeds create: only rows with one of these values; <dim>!=<v,v> keeps the rest; repeat for several
-  --attribution first_touch|last_touch   metrics query and feeds create: which ad touch gets the credit for leads and sales by channel or campaign
+  --attribution first_touch|last_touch   metrics query and feeds create: which ad touch gets the credit for leads and sales by channel or campaign;
+                        calls unattributed: which touch credits each booked call
   --last-days <n>       feeds create: how many days the sheet link covers, ending today and counting it (default 30, at most 400)
                         (default: first_touch)
   --channel <channel>   only this channel's campaigns (and, with brief, its ads): meta, google, affiliate, a utm_source, unknown or recorded_in_crm;
@@ -5114,6 +5148,7 @@ Options:
   --pixel <id>          meta audience create --kind website: the pixel that saw the visits
   --url-contains <text> meta audience create --kind website: only visits to pages whose address contains this
   --event <event>       meta audience create --kind website: only visits that fired this pixel event, such as Purchase or Lead
+                        calls compare: count the Meta action type <event>, such as schedule_website, as Meta's calls instead of its results
   --video <id>          meta audience create --kind video: a video watched; repeat for several
   --watched <how much>  meta audience create --kind video: 3s, 10s, thruplay, 25%, 50%, 75% or 95%
   --page <id>           meta audience create --kind page: the Facebook Page
@@ -5176,7 +5211,7 @@ Options:
                         first; repeat for several
   --order desc|asc      content search's sort direction (default: desc, best or newest first)
   --offset <n>          api setup, api try: where in the guide or the answer the slice starts, in characters
-  --limit <n>           api setup, api try: how many characters of the guide (default 20,000) or the answer (default 65,536); how many results content search, creatives list, media list, campaigns, voice, ads tags, content tags,
+  --limit <n>           api setup, api try: how many characters of the guide (default 20,000) or the answer (default 65,536); how many results content search, creatives list, media list, campaigns, calls unattributed (default 200, at most 1000), voice, ads tags, content tags,
                         content to-check and seo page-two 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; seo page-two: 50)
   --library <slug>      with knowledge search, only this library: creative-cartel, exodus or meta-policy

package/dist/unattributed-calls.js

@@ -0,0 +1,17 @@
+import { renderTable } from "./table.js";
+const CALL_COLUMNS = ["booked_on", "started_on", "credit", "record_source", "contact_id", "outcome", "channel", "campaign_id", "ad_id", "landing_page_key"];
+export function renderUnattributedCalls(report) {
+    const range = `${report.from} to ${report.to}`;
+    if (report.booked_calls === null)
+        return `No booked-call source is connected, so there are no booked calls from ${range}.\n`;
+    const lines = [
+        `Booked calls ${range}, credited to the ${report.touch} touch: ${report.booked_calls} in all, ${report.with_ad} with a Facebook ad, ${report.without_ad} without one.`,
+    ];
+    if (report.without_ad === 0)
+        return `${lines[0]}\n`;
+    lines.push("", "Why calls have no ad:", renderTable(["credit", "calls"], report.by_credit.filter((c) => c.calls > 0)));
+    lines.push("", "Calls with no ad, newest first:", renderTable(CALL_COLUMNS, report.calls));
+    if (report.truncated)
+        lines.push(`Showing the newest ${report.calls.length} of ${report.without_ad}; --limit shows up to 1000.`);
+    return `${lines.join("\n")}\n`;
+}

package/package.json

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