@wrangled/cli 0.3.150 → 0.3.152

package/dist/api.js

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { brand, envPrefix } from "./brand.js";
 import { RUN_ROOT_ENV, writeFileAtomic } from "./files.js";
+import { noteLatestCli } from "./version-check.js";
 export const exitCodes = { ok: 0, error: 1, usage: 2, auth: 3, timedOut: 4, interrupted: 130 };
 export class CliError extends Error {
     exitCode;
@@ -335,9 +336,9 @@ async function request(connection, path, init) {
         });
     }
     catch (error) {
-        const cause = error.cause?.message ?? error.message;
-        throw new CliError(`Cannot reach ${connection.apiUrl}: ${cause}`, exitCodes.error);
+        throw cannotReach(connection.apiUrl, error);
     }
+    noteLatestCli(response);
     if (response.status === 401) {
         throw new CliError(connection.rejected ?? `The API key was rejected by ${connection.apiUrl}. Run \`${brand.slug} login\` with a valid key.`, exitCodes.auth);
     }
@@ -347,6 +348,33 @@ async function request(connection, path, init) {
     }
     return response;
 }
+/** The build the API at `apiUrl` runs; it needs no key. */
+export async function fetchApiVersion(apiUrl) {
+    let response;
+    let body;
+    try {
+        response = await fetch(`${apiUrl}/api/v1/version`, { signal: AbortSignal.timeout(VERSION_TIMEOUT_MS) });
+        noteLatestCli(response);
+        if (!response.ok)
+            throw new CliError(`HTTP ${response.status} from /api/v1/version at ${apiUrl}`, exitCodes.error);
+        body = await response.json().catch(() => undefined);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw cannotReach(apiUrl, error);
+    }
+    const api = body?.api;
+    if (typeof api?.cliLatest !== "string" || (api.commit !== null && typeof api.commit !== "string")) {
+        throw new CliError(`/api/v1/version at ${apiUrl} did not answer with a version.`, exitCodes.error);
+    }
+    return { api: { commit: api.commit, cliLatest: api.cliLatest } };
+}
+const VERSION_TIMEOUT_MS = 5_000;
+function cannotReach(apiUrl, error) {
+    const cause = error.cause;
+    return new CliError(`Cannot reach ${apiUrl}: ${cause?.message || cause?.code || error.message}`, exitCodes.error);
+}
 function parseErrorBody(text) {
     try {
         return JSON.parse(text).error;

package/dist/guide.js

@@ -155,6 +155,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} 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} 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.
@@ -453,6 +454,7 @@ A scheduled agent's run acts as its skill's agent, the way the Facebook ads agen
 ${cli} login [--client <name>]      validate a key (prompted, piped, or ${envPrefix}_API_KEY) and save it, as the default or under a client's name
 ${cli} logout [--client <name>]     delete the default saved login, or one client's
 ${cli} whoami                       show the current workspace, library access, and which client's key is in use and why
+${cli} version                      this CLI's version, the commit the API runs, and the latest CLI it ships (also --version); needs no login
 ${cli} knowledge search "<question>" [--limit <n>] [--kind <kind>] [--hook-kind <v> ...]   short, cited snippets from the know-how libraries (keys with library access)
 ${cli} knowledge tag <entry-id> --hook-kind <v> --confidence <c>   tag a library entry with the marketing grammar (or --file tags.json)
 ${cli} guide                        what this workspace's data holds, how fresh it is, and what is missing: read it first

package/dist/main.js

@@ -5,10 +5,11 @@ import { mkdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 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 { 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, chosenApiUrl, fetchApiVersion, 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 { 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";
@@ -29,6 +30,7 @@ import { AGENT_ENV, HARNESS_COMMAND_ENV, RUNNER_TOKEN_ENV, runLoop, runOnce } fr
 import { npmRegistry } from "./runner/self-update.js";
 import { SKILL_NAME_PATTERN } from "./skill-zip.js";
 import { installSkillFolder, operatorConnection, packSkill, parseSkillRef, readSkillFolder, unpackSkill, } from "./skills.js";
+import { ownVersion } from "./version-check.js";
 import { versionAtLeast } from "./version.js";
 const DEFAULT_WAIT_SECONDS = 300;
 const META_AD_PAUSE_USAGE = 'meta ad pause <ad-id> --idempotency-key <key> --reason "<why>" [--name "<expected>"] [--run <run-id>]';
@@ -114,6 +116,25 @@ const commands = {
             console.log(`\n${clientReason(choice)}`);
         },
     },
+    version: {
+        usage: "version   this CLI's version, and the API's: the commit it runs and the latest CLI it ships (also --version)",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: version", exitCodes.usage);
+            const url = await chosenApiUrl(options);
+            const api = await fetchApiVersion(url).then(({ api }) => ({ url, commit: api.commit, cliLatest: api.cliLatest }), (error) => {
+                if (!(error instanceof CliError))
+                    throw error;
+                console.error(`error: ${error.message}`);
+                return null;
+            });
+            if (options.format === "json")
+                return printJson({ cli: ownVersion(), api });
+            console.log(`CLI ${ownVersion()}`);
+            if (api)
+                console.log(`API ${api.url} commit ${api.commit ?? "unknown"}, latest CLI ${api.cliLatest}`);
+        },
+    },
     "knowledge search": {
         usage: 'knowledge search ["<question>"] [--limit <n>] [--kind message|transcript|document|note] [--library <slug>] [--angle <v>] [--hook-kind <v>] [--ad-format <v>] [--awareness <v>]',
         async run(args, options) {
@@ -557,6 +578,21 @@ 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));
+        },
+    },
     "tools list": {
         usage: "tools list",
         async run(_args, options) {
@@ -4033,8 +4069,7 @@ async function withRunner(options, work) {
         await work({
             apiUrl: resolveApiUrl(options.apiUrl, null),
             token,
-            // main.js sits in dist/ (main.ts in src/), one below the package's package.json.
-            cliVersion: JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version,
+            cliVersion: ownVersion(),
             harnessCommand: process.env[HARNESS_COMMAND_ENV] || undefined,
             openRouterKey: process.env[OPENROUTER_KEY_ENV] || undefined,
             maxSeconds: options.maxSeconds,
@@ -4430,6 +4465,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 }))
@@ -5020,8 +5059,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, 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, 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)
@@ -5031,7 +5070,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;
@@ -5157,7 +5197,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
@@ -5213,11 +5253,14 @@ the runner starts instead of Claude Code or Codex.
 
 Run \`${brand.slug} docs\` for the full guide.
 `;
-/** A bare --questions (map's switch) as an empty value, since funnels draft gives --questions a value. */
-const bareQuestions = (argv) => argv.map((arg, i) => (arg === "--questions" && (i === argv.length - 1 || argv[i + 1].startsWith("-")) ? "--questions=" : arg));
+/**
+ * A bare --questions (map's switch) or --version (the version command, with no command before it) as an empty value,
+ * since funnels draft gives --questions a value, and funnels show and dashboards rollback --version.
+ */
+const bareSwitches = (argv) => argv.map((arg, i) => ((arg === "--questions" || arg === "--version") && (i === argv.length - 1 || argv[i + 1].startsWith("-")) ? `${arg}=` : arg));
 function parseOptions(argv) {
     const { values, positionals } = parseArgs({
-        args: bareQuestions(argv),
+        args: bareSwitches(argv),
         allowPositionals: true,
         options: {
             format: { type: "string", default: "table" },
@@ -6982,7 +7025,7 @@ async function newerCliHint() {
     // Tests run the CLI with NODE_ENV=test; they ask a registry only when they name one, so npm's real version cannot change their output.
     if (process.env.NODE_ENV === "test" && !process.env.npm_config_registry)
         return undefined;
-    const version = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version;
+    const version = ownVersion();
     const latest = await npmRegistry.latest(3_000).catch(() => undefined);
     if (latest === undefined || versionAtLeast(version, latest))
         return undefined;
@@ -6990,6 +7033,8 @@ async function newerCliHint() {
 }
 async function main(argv) {
     const { positionals, options, help: wantsHelp } = parseOptions(argv);
+    if (positionals.length === 0 && options.version === "" && !wantsHelp)
+        return commands.version.run([], options);
     if (wantsHelp || positionals.length === 0) {
         process.stdout.write(help);
         return;

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/dist/version-check.js

@@ -0,0 +1,28 @@
+import { readFileSync } from "node:fs";
+import { brand } from "./brand.js";
+import { VERSION_PATTERN, versionAtLeast } from "./version.js";
+let own;
+/** This CLI's version, from the package.json one folder above dist/ (and src/). */
+export function ownVersion() {
+    own ??= JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+    return own;
+}
+/** The response header that names the latest CLI version the API's build ships. */
+export const CLI_LATEST_HEADER = `x-${brand.slug}-cli-latest`;
+/** The line to warn with when `latest` is a newer version than `version`; nothing when it is not, or is no version at all. */
+export function cliUpdateWarning(version, latest) {
+    if (!latest || !VERSION_PATTERN.test(latest) || !VERSION_PATTERN.test(version) || versionAtLeast(version, latest))
+        return undefined;
+    return `warning: this CLI is ${version} and the API's latest is ${latest}. Update: npm install -g ${brand.npmPackage}@latest`;
+}
+let warned = false;
+/** Warns on stderr, once per process, when an API response says a newer CLI is out. */
+export function noteLatestCli(response) {
+    if (warned)
+        return;
+    const warning = cliUpdateWarning(ownVersion(), response.headers.get(CLI_LATEST_HEADER));
+    if (warning === undefined)
+        return;
+    warned = true;
+    process.stderr.write(`${warning}\n`);
+}

package/package.json

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