@wrangled/cli 0.3.38 → 0.3.40

package/dist/api.js

@@ -21,6 +21,8 @@ export class UnreadableCredentialsError extends CliError {
  * in src/lib/knowledge/tags.ts. format's flag is --ad-format, because --format picks the output.
  */
 export const entryTagFlags = { angle: "angle", hook_kind: "hook-kind", format: "ad-format", awareness: "awareness" };
+/** The days before a sale in which a click or reply helps it, as the app counts them (MESSAGE_CREDIT_DAYS). */
+export const MESSAGE_CREDIT_DAYS = 7;
 /** Copies of the server's IMPORT_LIMITS and import name rule; src/lib/cli-consistency.test.ts keeps them in step. */
 export const IMPORT_LIMITS = { bytes: 50 * 1024 * 1024, rows: 1_000_000, columns: 500 };
 export const IMPORT_NAME_PATTERN = /^[a-z][a-z0-9_]{0,40}$/;

package/dist/guide.js

@@ -1,4 +1,4 @@
-import { IMPORT_LIMITS } from "./api.js";
+import { IMPORT_LIMITS, MESSAGE_CREDIT_DAYS } from "./api.js";
 import { brand, envPrefix } from "./brand.js";
 import { BACK_TAG_SKILL_NAME, CRO_SKILL_NAME, GRAMMAR_SKILL_NAME, LEARN_NAMES_SKILL_NAME, LESSONS_SKILL_NAME, MAP_OFFERS_SKILL_NAME, PLAYBOOK_CHOICES, STORY_SKILL_NAME, WEEKLY_LOOP_SKILL_NAME } from "./playbooks.js";
 import { PULL_STATE_FILE } from "./pull.js";
@@ -113,7 +113,7 @@ For "how is the funnel doing?", "which campaigns are working?" and "where does t
 
 ## Webhook addresses
 
-A webhook address lets a tool such as a form or webinar platform push events into the warehouse's \`raw_events\` table. \`${cli} intake list\` shows each address with whether it is on, how many days it keeps events, the events of the last 24 hours, the last event's time, and the rows it holds. \`${cli} intake create <label>\` makes one and prints its link, address and token. The link is the one URL to paste into the sending tool: the address with the token on the end, or for Mailgun the bare address. Add \`--kind ghl_workflow\` for a GoHighLevel workflow's Webhook step: its events also land, typed, in \`ghl_events\`. Add \`--kind aloware\` for Aloware's call and text webhooks: they also land, typed, in \`aloware_calls\` and \`aloware_texts\`. Add \`--kind webinarfuel\` or \`--kind stealth_seminar\` for a webinar tool: its sign-ups, attendance, replays and offer clicks land in \`webinar_events\`. Add \`--kind mailgun --signing-key-stdin\`, with Mailgun's HTTP webhook signing key piped on stdin, for a Mailgun account's webhooks: each event's signature is checked and alone proves the sender, so Mailgun posts to the address itself with no token, and its events also land, typed, in \`mailgun_events\`. When the account's key changes, pipe the new one to \`${cli} intake signing-key <id> --signing-key-stdin\`; deleting the workspace's last Mailgun address deletes the key. Add \`--kind thrivecart_events\` for a ThriveCart account's webhook: affiliate commissions earned, taken back and paid out also land, typed, in \`thrivecart_affiliate_commissions\`, where they stay after their events pass the retention, and \`daily_spend\` counts them. The link and token are shown only then and after \`${cli} intake rotate <id>\`. Paste the link into the sending tool, or, when the tool can set a header, give it the address and \`Authorization: Bearer <token>\` instead, which keeps the token out of request logs. Never paste either anywhere else. Events are kept for 90 days unless \`--retention-days\` or \`${cli} intake retention <id> <days>\` says otherwise (1 to 3650). \`${cli} intake delete <id> --yes\` deletes the address and every event it saved. A website visit tag shows in \`${cli} intake list\` as an address of kind \`visit_tag\`, and each page view it records lands in \`site_visits\` (host, path, referrer host, UTM tags, click ids, country, device type, a bot flag and a random visitor id). \`${cli} intake create\` cannot make one: a tag has no token and needs its list of allowed sites, so an operator makes it with the server's \`npm run visit-tag:create\` script.
+A webhook address lets a tool such as a form or webinar platform push events into the warehouse's \`raw_events\` table. \`${cli} intake list\` shows each address with whether it is on, how many days it keeps events, the events of the last 24 hours, the last event's time, and the rows it holds. \`${cli} intake create <label>\` makes one and prints its link, address and token. The link is the one URL to paste into the sending tool: the address with the token on the end, or for Mailgun the bare address. Add \`--kind ghl_workflow\` for a GoHighLevel workflow's Webhook step: its events also land, typed, in \`ghl_events\`. Add \`--kind aloware\` for Aloware's call and text webhooks: they also land, typed, in \`aloware_calls\` and \`aloware_texts\`. Add \`--kind webinarfuel\` or \`--kind stealth_seminar\` for a webinar tool: its sign-ups, attendance, replays and offer clicks land in \`webinar_events\`. Add \`--kind mailgun --signing-key-stdin\`, with Mailgun's HTTP webhook signing key piped on stdin, for a Mailgun account's webhooks: each event's signature is checked and alone proves the sender, so Mailgun posts to the address itself with no token, and its events also land, typed, in \`mailgun_events\`. When the account's key changes, pipe the new one to \`${cli} intake signing-key <id> --signing-key-stdin\`; deleting the workspace's last Mailgun address deletes the key. Add \`--kind thrivecart_events\` for a ThriveCart account's webhook: affiliate commissions earned, taken back and paid out also land, typed, in \`thrivecart_affiliate_commissions\`, where they stay after their events pass the retention, and \`daily_spend\` counts them. Add \`--kind roezan\` once the workspace's Roezan source is connected: the server uses the source's key to ask Roezan to send each new broadcast to the link (\`subscription\` in the answer says whether that worked; if not, add the link in Roezan's Webhooks tab), each broadcast an event names lands in \`roezan_broadcast_events\`, and the Roezan source reads it on its next hourly sync. The link and token are shown only then and after \`${cli} intake rotate <id>\`. Paste the link into the sending tool, or, when the tool can set a header, give it the address and \`Authorization: Bearer <token>\` instead, which keeps the token out of request logs. Never paste either anywhere else. Events are kept for 90 days unless \`--retention-days\` or \`${cli} intake retention <id> <days>\` says otherwise (1 to 3650). \`${cli} intake delete <id> --yes\` deletes the address and every event it saved. A website visit tag shows in \`${cli} intake list\` as an address of kind \`visit_tag\`, and each page view it records lands in \`site_visits\` (host, path, referrer host, UTM tags, click ids, country, device type, a bot flag and a random visitor id). \`${cli} intake create\` cannot make one: a tag has no token and needs its list of allowed sites, so an operator makes it with the server's \`npm run visit-tag:create\` script.
 
 ## Limits
 
@@ -298,6 +298,7 @@ ${cli} guide                        what this workspace's data holds, how fresh
 ${cli} brief [--from <date>] [--to <date>] [--channel <channel>] [--campaign <id>] [--top <n>]   the offer, voice, best and worst ads, pages, results and audience: start here before writing ads
 ${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 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
@@ -309,7 +310,7 @@ ${cli} sources list                 list data sources and their health
 ${cli} sources show <id>            show one source's health, tables and last sync runs
 ${cli} sources settings <id> [<key>=<value> ...]   show a key source's settings, or check them with its saved key and save them
 ${cli} intake list                  list webhook addresses and their health
-${cli} intake create <label> [--kind generic|ghl_workflow|aloware|webinarfuel|stealth_seminar|mailgun|thrivecart_events] [--retention-days <n>] [--signing-key-stdin]   make a webhook address; prints its link and token once
+${cli} intake create <label> [--kind generic|ghl_workflow|aloware|webinarfuel|stealth_seminar|mailgun|thrivecart_events|roezan] [--retention-days <n>] [--signing-key-stdin]   make a webhook address; prints its link and token once
 ${cli} intake rotate <id>           replace an address's token; prints the new link and token once
 ${cli} intake signing-key <id> --signing-key-stdin   replace the workspace's signing key for that address's kind (mailgun)
 ${cli} intake disable <id> | enable <id>   turn an address off or back on

package/dist/main.js

@@ -669,6 +669,17 @@ const commands = {
             printPageResults(results);
         },
     },
+    "messages results": {
+        usage: "messages results [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--channel email|text] [--sequence <workflow id>]   (which follow-up emails, texts and sequences bring real sales)",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: messages results [--from <date>] [--to <date>] [--channel email|text] [--sequence <workflow id>]", exitCodes.usage);
+            const results = await api(await resolveConnection(options.apiUrl), `/api/v1/messages/results${reportQuery(options, { channel: options.channel, sequence: options.sequence })}`);
+            if (options.format === "json")
+                return printJson(results);
+            printMessageResults(results);
+        },
+    },
     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)",
         async run(args, options) {
@@ -2170,6 +2181,51 @@ function printPageResults(results) {
     console.log(renderTable(["page", "ad", "ad name", "currency", ...PAGE_NUMBERS], results.adPages.map((r) => ({ ...pageNumbers(r), ad: r.adId ?? "(no Meta ad)", "ad name": r.adName === null ? "" : excerpt(r.adName, 30) }))));
     console.log('\n"by ad link" counts sales whose buyer\'s landing page was not recorded, credited to the page the ad links to now.');
 }
+const MESSAGE_NUMBERS = ["currency", "helped", "helped revenue", "last nudge", "last nudge revenue", "first from Facebook"];
+/** One row per currency the sales are in, or one row with no sales. */
+function salesRows(label, sales) {
+    if (sales.length === 0)
+        return [{ ...label, helped: 0, "last nudge": 0 }];
+    return sales.map((s) => ({
+        ...label,
+        currency: s.currency,
+        helped: s.salesHelped,
+        "helped revenue": s.revenueHelped,
+        "last nudge": s.salesLastNudge,
+        "last nudge revenue": s.revenueLastNudge,
+        "first from Facebook": s.buyersFirstTouchMeta,
+    }));
+}
+const messageLabel = (m) => excerpt(m.name ?? m.subject ?? (m.realSales === "available" ? m.messageKey : (m.itemId ?? "")), 40);
+function printMessageResults(results) {
+    const real = results.messages.flatMap((m) => (m.realSales === "available" ? [m] : []));
+    const claimed = results.messages.flatMap((m) => (m.realSales === "not_available" ? [m] : []));
+    if (results.messages.length === 0 && results.sequences.length === 0)
+        return console.log(`No follow-up results from ${results.from} to ${results.to}.`);
+    console.log(`Follow-up emails and texts, most helped sales first, ${results.from} to ${results.to}:`);
+    console.log(renderTable(["message", "channel", "platform", "sent", "clicked", "replied", ...MESSAGE_NUMBERS, "per 1,000 sent"], real.flatMap((m) => salesRows({ message: messageLabel(m), channel: m.channel, platform: m.platform, sent: m.peopleSent ?? (m.toolNumbersInRange === "unknown" ? "unknown" : m.toolSends), clicked: m.peopleClicked, replied: m.peopleReplied, "per 1,000 sent": m.salesPer1000Sent }, m.sales))));
+    if (results.sequences.length > 0) {
+        console.log("\nSequences:");
+        console.log(renderTable(["sequence", "name", "messages", ...MESSAGE_NUMBERS], results.sequences.flatMap((q) => salesRows({ sequence: q.sequenceKey, name: q.name ?? "", messages: q.messages }, q.sales))));
+    }
+    if (claimed.length > 0) {
+        console.log("\nFrom tools that never say who clicked, so no real sales; revenue is the tool's own claim:");
+        console.log(renderTable(["message", "channel", "platform", "sends", "clicks", "tool-claimed revenue"], claimed.map((m) => m.toolNumbersInRange === "unknown"
+            ? { message: messageLabel(m), channel: m.channel, platform: m.platform, sends: "unknown", clicks: "unknown", "tool-claimed revenue": "unknown" }
+            : {
+                message: messageLabel(m),
+                channel: m.channel,
+                platform: m.platform,
+                sends: m.toolSends,
+                clicks: m.toolClicks,
+                "tool-claimed revenue": (m.toolClaimedRevenue ?? []).map((r) => `${r.revenue} ${r.currency ?? ""}`.trim()).join(", "),
+            })));
+    }
+    if (results.messages.some((m) => m.toolNumbersInRange === "unknown")) {
+        console.log("\nunknown: the tool keeps only running totals, and none was read before these dates for a message sent earlier, so how much fell in them cannot be told.");
+    }
+    console.log(`\n"helped" counts every message the buyer clicked or replied to in the ${results.creditDays} days before buying, so one sale counts for several messages; "last nudge" gives each sale only to the latest one, so those add up.`);
+}
 /** The rows, then the totals, which are one row per currency. */
 /** What confirmed leave-out rules took out of `figures`, one line per rule and currency. */
 function printLeftOut(leftOut, figures) {
@@ -2385,11 +2441,13 @@ Options:
   --force               content unpublish: take the page down even while delivering Meta ads link to it
   --plan <json>         meta adset publish: the ad set to make, {"kind": "copy", ...} or {"kind": "create", ...}
   --yes                 confirm intake delete or import remove, which delete saved data for good
-  --from <YYYY-MM-DD>   first day funnel, campaigns, money, brief and pages results cover (default: 29 days before --to)
-  --to <YYYY-MM-DD>     last day funnel, campaigns, money, brief and pages results cover (default: today in the workspace reporting time zone)
+  --from <YYYY-MM-DD>   first day funnel, campaigns, money, brief, pages results and messages results cover (default: 29 days before --to)
+  --to <YYYY-MM-DD>     last day funnel, campaigns, money, brief, pages results and messages results cover (default: today in the workspace reporting time zone)
   --grain <grain>       how funnel and money group days: day (default), week (starting Monday) or month
   --channel <channel>   only this channel's campaigns (and, with brief, its ads): meta, google, affiliate, a utm_source, unknown or recorded_in_crm;
-                        for content track-link, where the link goes: facebook, email, sms or web (default)
+                        for content track-link, where the link goes: facebook, email, sms or web (default);
+                        with messages results, email or text
+  --sequence <id>       with messages results, only the messages in this GoHighLevel workflow, and only that sequence
   --campaign <id>       the campaign content track-link puts in utm_campaign; with brief, the one campaign it covers
   --top <n>             how many best ads, worst ads, pages and campaigns brief shows, or ads in each winners list (default: 5, at most 20)
   --week <YYYY-MM-DD>   any day of the week winners covers, Monday to Sunday (default: the latest complete week)
@@ -2544,6 +2602,7 @@ function parseOptions(argv) {
             funnel: { type: "string" },
             step: { type: "string" },
             page: { type: "string" },
+            sequence: { type: "string" },
             workspace: { type: "string" },
             "max-seconds": { type: "string" },
             angle: { type: "string" },
@@ -2653,6 +2712,7 @@ function parseOptions(argv) {
             funnel: values.funnel,
             step: values.step,
             page: values.page,
+            sequence: values.sequence,
             workspace: values.workspace,
             maxSeconds,
             entryTags: Object.fromEntries(Object.entries(entryTagFlags).flatMap(([field, flag]) => (values[flag] === undefined ? [] : [[field, values[flag]]]))),
@@ -3400,15 +3460,17 @@ function parseRetentionDays(text) {
         throw new CliError("Retention must be a whole number of days, at least 1.", exitCodes.usage);
     return days;
 }
-function printIntakeToken({ endpoint, address, token, link }, format) {
+function printIntakeToken({ endpoint, address, token, link, subscription }, format) {
     if (format === "json")
-        printJson({ endpoint, address, token, link });
+        printJson({ endpoint, address, token, link, ...(subscription ? { subscription } : {}) });
     else {
         if (link)
             console.log(`Link:    ${link}`);
         console.log(`Address: ${address}`);
         console.log(`Header:  Authorization: Bearer ${token}`);
         console.log(`Token:   ${token}`);
+        if (subscription)
+            console.log(`Setup:   ${subscription.message}`);
     }
     console.error(`The token for ${endpoint.label} is shown only now. Rotate it if it is lost.`);
 }

package/package.json

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