@hogsend/cli 0.13.2 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/cli",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -34,7 +34,7 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "vitest": "^4.1.7",
-    "@hogsend/studio": "^0.13.2",
+    "@hogsend/studio": "^0.14.0",
     "@repo/typescript-config": "0.0.0"
   },
   "engines": {
@@ -44,8 +44,8 @@
     "@clack/prompts": "^1.5.0",
     "better-auth": "^1.6.11",
     "picocolors": "^1.1.1",
-    "@hogsend/db": "^0.13.2",
-    "@hogsend/engine": "^0.13.2"
+    "@hogsend/db": "^0.14.0",
+    "@hogsend/engine": "^0.14.0"
   },
   "scripts": {
     "prebuild": "node scripts/bundle-studio.mjs",

package/skills/hogsend-authoring-emails/SKILL.md

@@ -50,6 +50,12 @@ get a type error at the send call site — the #1 trap. See
   snippet; `category` drives frequency-cap exemption (`transactional` is exempt).
 - **Tracking + unsubscribe are automatic on `emailService.send` / `sendEmail`.**
   You never call `prepareTrackedHtml` or `generateUnsubscribeUrl` yourself.
+- **Semantic links (`EmailAction` from `@hogsend/email`)** make a click MEAN
+  something: an anchor that fires a real event (`event` + scalar `properties`)
+  through the full ingest pipeline — in-email yes/no questions, NPS scores,
+  one-tap choices. First answer per (send, event name) wins; scanner
+  click-bursts are suppressed. Details + rules in
+  `references/tracking-and-unsubscribe.md`.
 
 ## Task playbooks — load the matching reference
 

package/skills/hogsend-authoring-emails/references/tracking-and-unsubscribe.md

@@ -131,3 +131,56 @@ the click endpoint. You don't need to do anything for this; it's handled.
 
 Author the component; the engine guarantees tracking + unsubscribe on send.
 Full system docs: `docs/tracking.md`.
+
+---
+
+## Semantic links — in-email answers via `EmailAction`
+
+A plain tracked link tells you it WAS clicked; a semantic link tells you what
+the click MEANT. `EmailAction` (from `@hogsend/email`) renders an anchor that
+carries an event name + scalar properties; the engine lifts that metadata into
+the `tracked_links` row at send time (the attributes never reach the inbox) and
+emits the event through the FULL ingest pipeline at click time — journeys can
+`ctx.waitForEvent` it, destinations (PostHog et al) receive it as
+`email.action`, and `user_events` records it.
+
+```tsx
+import { EmailAction } from "@hogsend/email";
+import { Events } from "../journeys/constants/index.js";
+
+<EmailAction
+  event={Events.CHECKIN_ANSWERED}      // your event — NOT email.*/journey.*/bucket.*/contact.*
+  properties={{ answer: "yes" }}        // scalars only (string/number/boolean/null)
+  href="https://app.example.com/thanks" // where the human lands after the click
+  className="…"                          // styled like any anchor (Tailwind works)
+>
+  Going great
+</EmailAction>
+```
+
+Rules the engine enforces (a violation FAILS the send, loudly):
+
+- `event` must not use a reserved namespace (`email.`, `journey.`, `bucket.`,
+  `contact.` — dot or colon form).
+- `properties` values must be scalars; the JSON must stay under 2 KB.
+- The `href` must be an absolute http(s) URL (it is also click-tracked as
+  normal).
+
+Semantics at click time:
+
+- **First answer wins, per (send, event name).** An NPS row of eleven
+  EmailActions shares one answer slot — only the first clicked score ingests
+  (idempotency key `sem:<emailSendId>:<event>`). The generic `email.link_clicked`
+  still fires for every hit.
+- **Answers confirm after a ~30s window.** A click is only a provisional
+  answer: a deferred task judges it once the burst window has fully elapsed,
+  so a scanner that clicks every link (Outlook SafeLinks / Proofpoint) is seen
+  in full — including its first click — and suppressed before anything is
+  recorded. Cost: ~30s of answer latency (invisible to day-scale journey
+  waits). Still don't make destructive actions ("cancel my account") a
+  one-click EmailAction.
+- Two EmailActions may share the same `href` with different
+  `event`/`properties` — they get separate tracked links (no URL collapse).
+- The answering journey reads the payload from
+  `ctx.waitForEvent(...) → { timedOut, properties }` — see the
+  hogsend-authoring-journeys skill.

package/skills/hogsend-authoring-journeys/references/journey-context.md

@@ -36,7 +36,7 @@ await ctx.sleepUntil(at, { label: "morning-nudge" });
 // whichever first. The reactive alternative to "sleep a fixed window, then poll
 // ctx.history": it resumes the INSTANT the event lands. Forward-looking — only
 // events fired AFTER the wait begins count (use ctx.history.hasEvent for the past).
-const { timedOut } = await ctx.waitForEvent({
+const { timedOut, properties } = await ctx.waitForEvent({
   event: Events.FEATURE_USED,
   timeout: days(7),           // REQUIRED, capped at the 720h task execution limit
   label: "await-activation",  // optional — written as currentNodeId
@@ -44,10 +44,23 @@ const { timedOut } = await ctx.waitForEvent({
 if (timedOut) {
   // they never did it — nudge (re-check ctx.guard.isSubscribed() first after a long wait)
 } else {
-  // event arrived — they activated on their own
+  // event arrived — they activated on their own. `properties` carries the
+  // matched event's payload (best-effort, scalars only) — branch on the
+  // answer directly, e.g. a semantic-link NPS score:
+  // if (typeof properties?.score === "number" && properties.score <= 6) { … }
 }
 ```
 
+NEVER put the awaited event in `exitOn` too: an `exitOn` match mid-wait aborts
+the run (`JourneyExitedError`) BEFORE your post-wait branch executes. React via
+`waitForEvent` OR exit via `exitOn` — one event name, one role.
+
+Waiting twice for the same event (e.g. after a reminder send)? Pass
+`lookback: hours(1)` on the second wait — the wait is forward-looking, so an
+answer landing in the gap between the two waits would otherwise be missed;
+`lookback` checks recent `user_events` first and resolves immediately with the
+payload.
+
 If the journey `exitOn`-matches (or is cancelled) WHILE waiting, the run aborts
 cleanly — state goes `"exited"`, the durable run is cancelled, and no post-wait
 step (or email) fires. You don't catch anything; the engine handles it.

package/src/commands/webhooks.ts

@@ -4,7 +4,7 @@ import { color } from "../lib/output.js";
 import type { Command, CommandContext } from "./types.js";
 
 /**
- * The 13-event outbound catalog, VENDORED from the engine's
+ * The 14-event outbound catalog, VENDORED from the engine's
  * `WEBHOOK_EVENT_TYPES` (lib/webhook-signing.ts). The CLI cannot import the
  * engine, so the tuple is re-declared here and MUST be kept in sync BY HAND when
  * the engine catalog changes. The `webhook.test` sentinel is NOT a member.
@@ -18,6 +18,7 @@ const WEBHOOK_EVENT_TYPES = [
   "email.delivered",
   "email.opened",
   "email.clicked",
+  "email.action",
   "email.bounced",
   "email.complained",
   "journey.completed",