@wrangled/cli 0.3.149 → 0.3.151

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

@@ -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.
@@ -452,6 +453,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,8 +5,9 @@ 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 { apiSetupPath, parseAuthFlag, parseQueryFlags, setupText, submittedText, testText, tryText, waitingText, } from "./api-setup.js";
 import { answerRow, batches, ENRICH_EMAIL_USAGE, parsePeople, parseSteps } from "./enrich.js";
@@ -28,6 +29,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>]';
@@ -113,6 +115,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) {
@@ -242,7 +263,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 +501,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 +573,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)");
         },
     },
@@ -4032,8 +4053,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,
@@ -4103,27 +4123,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)
@@ -4578,13 +4577,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";
@@ -5227,11 +5232,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" },
@@ -6996,7 +7004,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;
@@ -7004,6 +7012,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/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/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.149",
+  "version": "0.3.151",
   "description": "Command-line access to your marketing data warehouse, for people and coding agents",
   "type": "module",
   "bin": {