@wrangled/cli 0.3.9 → 0.3.11

package/dist/guide.js

@@ -62,7 +62,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. 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. 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
 
@@ -166,6 +166,10 @@ Kinds are \`exclusion\`, \`gap\`, \`baseline\`, \`change\`, \`definition\`, \`ca
 
 To suggest a fact, write it as JSON and run \`${cli} facts propose --file fact.json\` (or pipe it on stdin): \`{"kind": "gap", "subject_type": "table", "subject_ref": "meta_insights_daily", "key": "history_start", "value": {"table": "meta_insights_daily", "from": "2026-04-07"}, "summary": "Facebook ad numbers only go back to April 7, 2026.", "evidence": {"query": "SELECT min(date) FROM meta_insights_daily"}}\`. You only suggest: a person confirms, fixes or rejects it in the app. A fact with the same kind, subject and key already open is refused as \`fact_exists\`. Evidence is counts, queries and ids, never names, emails or phones.
 
+## What customers keep saying
+
+Every hour an AI reads the workspace's new Facebook and Instagram comments, Google reviews and Reddit posts and comments, pulls out openers (lines that would open an ad), objections (why people hesitate) and phrases (customers' own words for their problem or result), and groups the ones that say the same thing. Names, emails, phone numbers and handles are taken out first. \`${cli} voice\` lists the groups, most common first (\`--kind opener|objection|phrase\`, \`--limit <n>\` up to 200, \`--json\`), each with how many rows said it, their likes, and up to 3 real quotes. In \`--json\`, each quote's \`{kind, ref, quote}\` goes straight into a creative's \`researchSources\`, and a group itself can be cited as its \`ref\`, \`voice_clusters:<id>\`. The same rows are in the \`voice_clusters\` and \`voice_insights\` tables.
+
 ## The weekly story
 
 Each workspace keeps a weekly story: a one-screen read of what the data says this week, why, what is working, what the data cannot tell us, and what to do next. \`${cli} story\` prints the newest version, \`${cli} story list\` every version newest first, and \`${cli} story show <version>\` one of them (each takes \`--json\`). Every save is a new version; nothing is ever changed or deleted.
@@ -225,7 +229,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] [--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] [--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
@@ -268,6 +272,9 @@ ${cli} funnels evidence   prices paid, buyer paths, GoHighLevel funnels, calenda
 ${cli} funnels draft --file <map.json> [--note <why>] [--evidence '<json>' | @file.json] [--based-on <n>] [--counts-from fix|<date>] [--questions @file.json]   save the whole map; it goes live when every step can be counted
 ${cli} facts [--kind <kind>] [--subject <type>[:<ref>]] [--status <status>] [--json] | facts show <id>   settled facts about the data, to treat as true
 ${cli} facts propose --file <fact.json>   suggest a fact for a person to confirm
+${cli} voice [--kind opener|objection|phrase] [--limit <n>] [--json]   what customers keep saying, grouped and counted, with real quotes
+${cli} voice lists                  where that voice comes from: the competitors whose ads, and the subreddits and Reddit search phrases whose posts, are saved, and suggestions waiting
+${cli} voice suggest competitor|subreddit|search_phrase "<value>" [--note <why>]   suggest a competitor, subreddit or Reddit search phrase for a person to approve
 ${cli} story [--json] | story list | story show <version>   the weekly story, its versions, and the rows behind each sentence
 ${cli} story submit --file <story.json>   save the next version of the weekly story
 ${cli} worker list | worker runs <hand-id | skill> [--limit <n>] | worker run-now <hand-id | skill>   this workspace's scheduled hands, their runs and costs, and Run now

package/dist/main.js

@@ -1099,6 +1099,24 @@ const commands = {
             console.log(renderTable(FACT_COLUMNS, facts.map(factRow)));
         },
     },
+    voice: {
+        usage: "voice [--kind opener|objection|phrase] [--limit <n>] [--json]   what customers keep saying, most common first",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: voice [--kind opener|objection|phrase] [--limit <n>] [--json]", exitCodes.usage);
+            const query = new URLSearchParams();
+            if (options.kind)
+                query.set("kind", options.kind);
+            if (options.limit)
+                query.set("limit", options.limit);
+            const { clusters } = await api(await resolveConnection(options.apiUrl), `${VOICE_PATH}${query.size ? `?${query}` : ""}`);
+            if (options.format === "json")
+                return printJson({ clusters });
+            if (clusters.length === 0)
+                return console.log("Nothing grouped yet.");
+            console.log(renderTable(VOICE_COLUMNS, clusters.map(voiceRow)));
+        },
+    },
     "facts show": {
         usage: "facts show <id>   one fact with its value and evidence",
         async run(args, options) {
@@ -1121,6 +1139,42 @@ const commands = {
             console.log(`Proposed fact ${fact.id}. A person confirms or rejects it in the app.`);
         },
     },
+    "voice lists": {
+        usage: "voice lists   where the voice comes from: the competitors whose ads, and the subreddits and Reddit search phrases whose posts, this workspace saves, and the suggestions waiting",
+        async run(args, options) {
+            if (args.length > 0)
+                throw new CliError("Usage: voice lists", exitCodes.usage);
+            const lists = await api(await resolveConnection(options.apiUrl), VOICE_LISTS_PATH);
+            if (options.format === "json")
+                return printJson(lists);
+            const rows = [
+                ...lists.competitors.map((c) => ({ list: "competitor", entry: `${c.name} (Page ${c.pageId})`, status: "listed", note: null })),
+                ...lists.subreddits.map((s) => ({ list: "subreddit", entry: `r/${s}`, status: "listed", note: null })),
+                ...lists.phrases.map((p) => ({ list: "search_phrase", entry: p, status: "listed", note: null })),
+                ...lists.suggestions.map((s) => ({ list: s.kind, entry: s.kind === "subreddit" ? `r/${s.value}` : s.value, status: "suggested", note: s.note })),
+            ];
+            if (rows.length === 0)
+                return console.log("No competitors, subreddits or phrases yet, and no suggestions.");
+            console.log(renderTable(["list", "entry", "status", "note"], rows));
+        },
+    },
+    "voice suggest": {
+        usage: "voice suggest competitor|subreddit|search_phrase <value> [--note <why>]   suggest a competitor, subreddit or Reddit search phrase; a person approves it in the app",
+        async run(args, options) {
+            const [kind, value, ...rest] = args;
+            if (!kind || !["competitor", "subreddit", "search_phrase"].includes(kind) || value === undefined || rest.length > 0) {
+                throw new CliError('Usage: voice suggest competitor|subreddit|search_phrase "<value>" [--note <why>]; put a value with spaces in quotes', exitCodes.usage);
+            }
+            const result = await api(await resolveConnection(options.apiUrl), VOICE_SUGGESTIONS_PATH, { kind, value, note: options.note });
+            if (options.format === "json")
+                return printJson(result);
+            if (result.outcome === "already_listed")
+                return console.log(`That ${kind.replace("_", " ")} is already on the list.`);
+            if (result.outcome === "already_suggested")
+                return console.log(`That ${kind.replace("_", " ")} is already suggested (${result.suggestion.id}), waiting for a person.`);
+            console.log(`Suggested ${kind.replace("_", " ")} ${result.suggestion.value} (${result.suggestion.id}). A person approves or dismisses it in the app.`);
+        },
+    },
     story: {
         usage: "story   the newest weekly story, with the rows behind each sentence",
         async run(args, options) {
@@ -1564,7 +1618,11 @@ function printReport(title, report, labels, numbers) {
 }
 const agentPath = (options) => `/api/v1/agents/${encodeURIComponent(options.agent)}`;
 const FACTS_PATH = "/api/v1/facts";
+const VOICE_LISTS_PATH = "/api/v1/voice-lists";
+const VOICE_SUGGESTIONS_PATH = "/api/v1/voice-lists/suggestions";
 const FACT_COLUMNS = ["id", "kind", "subject", "key", "status", "summary"];
+const VOICE_PATH = "/api/v1/voice";
+const VOICE_COLUMNS = ["ref", "kind", "said by", "likes", "label", "top quote"];
 function knowledgeBlock(r, i) {
     const lines = [`${i + 1}. ${r.title}`, `   ${r.kind}, ${r.evidence.replaceAll("_", " ")}`];
     if (r.url)
@@ -1574,6 +1632,9 @@ function knowledgeBlock(r, i) {
         lines.push(`   Caveat: ${r.caveat}`);
     return lines.join("\n");
 }
+function voiceRow(c) {
+    return { ref: c.ref, kind: c.kind, "said by": c.supportCount, likes: c.likeSum, label: excerpt(c.label, 60), "top quote": c.evidence[0] ? excerpt(c.evidence[0].quote, 60) : null };
+}
 function factRow(f) {
     return { id: f.id, kind: f.kind, subject: `${f.subjectType}:${f.subjectRef}`, key: f.key, status: f.status, summary: excerpt(f.summary, 80) };
 }
@@ -1634,7 +1695,7 @@ Options:
   --wait <seconds>      how long tools run and tools get wait for a run (default: ${DEFAULT_WAIT_SECONDS}; 0 returns at once)
   --agent <kind>        which agent the agent commands use: meta_ads (default) or p3_refresh; in a scheduled hand's run, skill
                         (the run's skill's agent) is the default
-  --kind <kind>         what sends to a new intake address: generic (default), ghl_workflow, aloware, webinarfuel, stealth_seminar or mailgun
+  --kind <kind>         what sends to a new intake address: generic (default), ghl_workflow, aloware, webinarfuel, stealth_seminar, mailgun or thrivecart_events
   --retention-days <n>  how many days intake create keeps each event (default: 90)
   --signing-key-stdin   read the sender's signing key for intake create or intake signing-key from stdin (mailgun needs one)
   --table <name>        the table import csv loads the file into, or import remove drops, as import_<name>;
@@ -1686,7 +1747,7 @@ Options:
   --from, --to <n>      with content diff, the two versions to compare (default: the one before the current one, and the current one)
   --sort <column>       how content search sorts: recent (default) or a content_scorecard number, such as click_rate or roas
   --order desc|asc      content search's sort direction (default: desc, best or newest first)
-  --limit <n>           how many results content search, creatives list and campaigns return
+  --limit <n>           how many results content search, creatives list, campaigns and voice return
   --max-seconds <n>     stop a runner's run after this many seconds, if that comes before its deadline
   --workspace <slug>    for worker promote and worker drop: the workspace whose hand they change
   -h, --help            show this help

package/dist/playbooks.js

@@ -595,7 +595,7 @@ ${cli} funnels show --format json > current.json
 
 \`evidence.json\` is \`{"evidence": {...}, "text": "..."}\`. The parts below are under \`.evidence\`, each either \`{"status": "ok", "rows": [...]}\` or \`{"status": "not_connected", "note": "..."}\`. Amounts are in whole currency units (1500 is 1,500.00), over the last \`.evidence.windowDays\` days unless a part says otherwise.
 
-- **prices**: the prices people pay, on each platform, with how many buyers and payments. A GoHighLevel or Shopify row has the product's \`name\`; a Stripe charge has none. For GoHighLevel, \`payments\` counts orders, not instalments. A GoHighLevel sale taken through Stripe shows twice, as a GoHighLevel row naming the product and a Stripe row with only the amount, and the two amounts can differ a little (1497 and 1500).
+- **prices**: the prices people pay, on each platform, with how many buyers and payments. A GoHighLevel or Shopify row has the product's \`name\`, a Kajabi row the offer's title, with the Kajabi offer id as \`productId\`; a Stripe charge has none. For GoHighLevel, \`payments\` counts orders, not instalments. A GoHighLevel or Kajabi sale taken through Stripe shows twice, as a row naming the product and a Stripe row with only the amount, and the two amounts can differ a little (1497 and 1500).
 - **buyerPaths**: the most common orders in which one person paid, with the median days between each payment. A small payment minutes after a big one is an order bump or upsell; a large payment weeks later is a back-end offer. A path such as \`[1500, 497, 3500]\` with medians \`[0, 60]\` reads: course, then an upsell the same day, then an event about two months later. A GoHighLevel checkout with an order bump is one payment of both prices together: 1994 is 1497 + 497. Before you take an amount for a new offer, check whether it is a sum of prices you already know.
 - **funnels**, **calendars**, **pipelineStages**, **tags**: what GoHighLevel holds. Tags often name purchases and memberships.
 - **webinars**: sign-ups, viewers and offer clicks per webinar id.
@@ -641,8 +641,8 @@ Start from the shape that fits, then rename and add steps to match what you read
 
 Write \`map.json\` as \`{"offers": [...], "funnels": [...]}\`, in this order.
 
-1. **Offers**, front end first, numbered by \`stack_position\` from 1. Each has an \`offer_key\` (lowercase, digits and underscores), \`name\`, \`tier\` (\`front_end\` or \`back_end\`), \`delivery\` (course, event, coaching, service, product, membership, webinar, lead_magnet or other), \`price\`, \`currency\`, an optional \`price_note\` (plain words on the price: other prices, payment plans, doubts), and \`matches\`: how a sale is recognised. A match is \`{"platform": ..., "match_type": ..., "value": "..."}\`: platform \`stripe\`, \`ghl\` or \`shopify\`, and match_type \`product_id\`, \`price_id\`, \`amount\` (whole units, with a \`currency\`), \`name_contains\` (any part of the product's name, ignoring case) or \`name_starts_with\` (the start of the product's name, ignoring case). Use \`name_starts_with\` for a family of products whose names begin with one code, such as event tickets named "OCA Dallas" and "OCA Austin"; \`name_contains\` "OCA" would also catch "Local Coaching". Stripe charges carry no product, so match them by \`amount\`. Prefer a GoHighLevel or Shopify name match on the product's name when one price is shared by two offers, as a $497 bump and a $497 guest ticket can be. An offer nobody pays for, such as a free webinar, may have no \`matches\`.
-   - **Price.** A free webinar's \`price\` is 0 when its page or GoHighLevel says it is free. When GoHighLevel and Stripe both show a sale, \`price\` is the GoHighLevel price that names the product, \`price_note\` gives the Stripe amount, and the offer matches both: a GoHighLevel name match and the Stripe \`amount\`. Any other price you cannot find in the evidence is \`null\`, with a \`price_note\` saying why.
+1. **Offers**, front end first, numbered by \`stack_position\` from 1. Each has an \`offer_key\` (lowercase, digits and underscores), \`name\`, \`tier\` (\`front_end\` or \`back_end\`), \`delivery\` (course, event, coaching, service, product, membership, webinar, lead_magnet or other), \`price\`, \`currency\`, an optional \`price_note\` (plain words on the price: other prices, payment plans, doubts), and \`matches\`: how a sale is recognised. A match is \`{"platform": ..., "match_type": ..., "value": "..."}\`: platform \`stripe\`, \`ghl\`, \`shopify\` or \`kajabi\`, and match_type \`product_id\`, \`price_id\`, \`amount\` (whole units, with a \`currency\`), \`name_contains\` (any part of the product's name, ignoring case) or \`name_starts_with\` (the start of the product's name, ignoring case). Use \`name_starts_with\` for a family of products whose names begin with one code, such as event tickets named "OCA Dallas" and "OCA Austin"; \`name_contains\` "OCA" would also catch "Local Coaching". Stripe charges carry no product, so match them by \`amount\`. For Kajabi, \`product_id\` is the offer id and a name match reads the offer's title; Kajabi has no \`price_id\`. Prefer a GoHighLevel or Shopify name match on the product's name when one price is shared by two offers, as a $497 bump and a $497 guest ticket can be. An offer nobody pays for, such as a free webinar, may have no \`matches\`.
+   - **Price.** A free webinar's \`price\` is 0 when its page or GoHighLevel says it is free. When GoHighLevel or Kajabi and Stripe both show a sale, \`price\` is the GoHighLevel or Kajabi price that names the product, \`price_note\` gives the Stripe amount, and the offer matches both: a GoHighLevel name match or the Kajabi offer, and the Stripe \`amount\`. A sale Stripe holds counts only under Stripe. Any other price you cannot find in the evidence is \`null\`, with a \`price_note\` saying why.
 2. **Funnels and steps.** A funnel has a \`funnel_key\`, \`name\`, \`kind\` (\`front_end\` or \`back_end\`), \`entry_offer_key\`, \`window_days\` (how many days after one step a sale still counts for the next; 365 when left out) and \`steps\`. A step has a \`step_key\`, \`position\` (1, 2, 3 in the order people walk them), \`step_type\`, \`name\`, and optionally the \`offer_key\` it sells, a \`wait_note\` (plain words on the wait before it, such as "the months after the course"), \`assets\` and \`rules\`.
    - Step types: \`ad\`, \`landing_page\`, \`vsl\`, \`optin\`, \`application\`, \`booking\`, \`confirmation\`, \`sales_call\`, \`checkout\`, \`order_bump\`, \`upsell\`, \`downsell\`, \`thank_you\`, \`webinar_registration\`, \`webinar\`, \`event\`, \`email_nurture\`, \`sms_nurture\`, \`onboarding\`, \`other\`.
 3. **Assets** on each step: \`{"asset_type": ..., "ref": ...}\` with refs from the evidence: \`meta_campaign\` (campaign id), \`url\` (page address), \`content_item\` (content item id), \`ghl_funnel_step\` (step id), \`ghl_calendar\`, \`ghl_pipeline_stage\`, \`ghl_tag\`, \`webinar\` (webinar id). Give the step after Traffic its page, the funnel's first page, as a \`url\`, a \`content_item\` from \`pages\` or a \`ghl_funnel_step\`: the Traffic step finds its ads from it. Only that step's pages count, so a checkout page that two funnels share is never mistaken for a first page.

package/package.json

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