@hogsend/cli 0.13.2 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/cli",
-  "version": "0.13.2",
+  "version": "0.16.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.16.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.16.0",
+    "@hogsend/engine": "^0.16.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,65 @@ 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.
+- **No landing page?** `href={HOSTED_ANSWER_HREF}` (from `@hogsend/email`)
+  resolves to the engine-hosted answer page: a thanks page with an optional
+  free-text box whose submission ingests `<event>.comment` (one comment per
+  send + event). Possession of the link is the auth, like unsubscribe.
+- **Cross-device stitch (opt-in):** `TRACKING_IDENTITY_TOKEN=true` appends an
+  encrypted one-hour `hs_t` token to tracked redirects; the landing site
+  exchanges it at `POST /v1/t/identify` for the distinct id and calls
+  `posthog.identify`. Never put a raw email in a URL — the token exists so
+  you don't have to.

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/skills/hogsend-conditions/SKILL.md

@@ -37,10 +37,12 @@ Not every surface accepts all four types — match the type to the field:
 
 - **`trigger.where`** (journey) → `PropertyCondition[]` ONLY. Property
   conditions, AND-ed together, evaluated against the triggering event's
-  properties. No event/engagement/composite legs here.
+  properties. No event/engagement/composite legs here. Authoring sugar: a
+  builder function — `where: (b) => b.prop("score").lte(6)` (or an array of
+  terminals) — resolves ONCE at `defineJourney` time to the identical POJOs.
 - **`exitOn[].where`** (journey) → `PropertyCondition[]` ONLY. Same shape;
   AND-ed against the incoming event's properties. Omit `where` to exit on the
-  event name alone.
+  event name alone. Accepts the same builder-function sugar.
 - **`criteria`** (bucket) → a single `ConditionEval` tree — ALL FOUR types,
   composed with `composite` / `b.all()` / `b.any()`. This is the only surface
   that runs against the database (event counts, engagement, windows).
@@ -57,7 +59,8 @@ Not every surface accepts all four types — match the type to the field:
 
 ## Golden rules
 
-1. `trigger.where` and `exitOn[].where` take `PropertyCondition[]` only — if
+1. `trigger.where` and `exitOn[].where` take `PropertyCondition[]` (write them
+   with the `(b) => b.prop(...)` builder for short) — if
    you need an event count or a time window, that logic belongs in the
    journey's `run` body (`ctx.history.hasEvent`) or in a bucket's `criteria`,
    not in `where`.

package/skills/hogsend-conditions/references/examples.md

@@ -14,6 +14,23 @@ properties. Only `property` conditions are valid here — there is no `within`,
 no event count, no composite. (Need a count or a window? Put that logic in the
 `run` body via `ctx.history.hasEvent`, or model it as a bucket.)
 
+Author it either way — the builder form resolves once at `defineJourney` time
+to the identical data (same machinery as bucket criteria):
+
+```ts
+// Builder form (recommended)
+trigger: {
+  event: Events.NPS_DETRACTOR,
+  where: (b) => b.prop("score").lte(3),
+},
+
+// Multiple conditions: return an array (AND-ed)
+trigger: {
+  event: Events.CHECKOUT_ABANDONED,
+  where: (b) => [b.prop("plan").eq("pro"), b.prop("cartValue").gte(100)],
+},
+```
+
 ```ts
 import { days, hours } from "@hogsend/core";
 import { defineJourney, sendEmail } from "@hogsend/engine";
@@ -56,7 +73,8 @@ export const proCheckoutAbandoned = defineJourney({
 
 `exitOn` is an array of `{ event, where? }`. The engine matches the incoming
 event name; if `where` is present it must pass (`PropertyCondition[]`, AND-ed)
-for the exit to fire. Omit `where` to exit on the event name alone.
+for the exit to fire. Omit `where` to exit on the event name alone. The
+builder form works here too: `where: (b) => b.prop("plan").eq("pro")`.
 
 ```ts
 meta: {

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",