@hogsend/cli 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "vitest": "^4.1.7",
-    "@hogsend/studio": "^0.3.0",
+    "@hogsend/studio": "^0.4.0",
     "@repo/typescript-config": "0.0.0"
   },
   "engines": {

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

@@ -59,7 +59,7 @@ export const welcome = defineJourney({
 ## Key concepts
 
 - **`ctx` is orchestration primitives ONLY** — `sleep`, `sleepUntil`, `when`,
-  `checkpoint`, `trigger`, `identify`, `guard.isSubscribed`,
+  `waitForEvent`, `checkpoint`, `trigger`, `identify`, `guard.isSubscribed`,
   `history.hasEvent/journey/email`, `posthog.capture`. Features are standalone
   imports: `sendEmail()` and `getPostHog()` come from `@hogsend/engine`, NOT off
   `ctx`.

package/skills/hogsend-authoring-journeys/references/branch-on-engagement.md

@@ -63,6 +63,30 @@ export const activation = defineJourney({
   after a long `ctx.sleep` — a user can unsubscribe during the wait. Enrollment
   only checks preferences at entry, not at each send.
 
+## Reactive alternative: `ctx.waitForEvent`
+
+The pattern above sleeps a **fixed window** then polls history — good when you
+want to wait a set time regardless. When you're waiting **for a specific event to
+happen** (and want to react the moment it does, or give up after a deadline),
+`ctx.waitForEvent` is the sharper tool: it resumes the instant the user fires the
+event, or returns `timedOut: true` when the timeout wins.
+
+```ts
+const { timedOut } = await ctx.waitForEvent({
+  event: Events.FEATURE_USED,
+  timeout: days(7),                 // required; capped at the 720h task limit
+  label: "await-activation",
+});
+if (!timedOut) return;              // they activated on their own — done
+if (!(await ctx.guard.isSubscribed())) return;
+await sendEmail({ /* nudge */ });
+```
+
+Rule of thumb: **fixed delay → `ctx.sleep` then `ctx.history.hasEvent`**;
+**wait until they do X (or time out) → `ctx.waitForEvent`**. The wait is
+forward-looking (only events after it begins count), and an `exitOn` match
+cancels it mid-wait, so no post-wait send fires after the journey exits.
+
 ## Idempotency — journeys can replay
 
 A journey task is durable, and a step before a `ctx.sleep` can be re-executed if

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

@@ -29,6 +29,29 @@ await ctx.sleepUntil(at, { label: "morning-nudge" });
 // .in(days(3)).at("HH:mm"), and chainers .tz(zone) / .window(start,end) / .ifPast("next"|"now")
 ```
 
+## Durable wait-for-event
+
+```ts
+// Park the journey until THIS user emits `event`, OR `timeout` elapses —
+// 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({
+  event: Events.FEATURE_USED,
+  timeout: days(7),           // REQUIRED, capped at the 720h task execution limit
+  label: "await-activation",  // optional — written as currentNodeId
+});
+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
+}
+```
+
+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.
+
 ## Observability
 
 ```ts

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

@@ -129,13 +129,16 @@ overlapping runs of the same journey.
 A `journeyStates` row tracks each run. Once the gates pass:
 
 - **enter** → row created with `status: "active"`, `currentNodeId: "start"`.
-- **`ctx.sleep` / `ctx.sleepUntil`** → `status: "waiting"` for the duration, back
-  to `"active"` on resume.
+- **`ctx.sleep` / `ctx.sleepUntil` / `ctx.waitForEvent`** → `status: "waiting"`
+  while suspended, back to `"active"` on resume.
 - **`run()` returns** → `status: "completed"`, `completedAt` set, and a
   `journey:completed` event is pushed.
 - **`run()` throws** → `status: "failed"`, `errorMessage` recorded, and a
   `journey:failed` event is pushed; the error re-throws so Hatchet sees the
   failure.
+- **`exitOn` matches (or cancelled)** → `status: "exited"`. If it happens while
+  the journey is suspended in a `ctx.sleep`/`ctx.waitForEvent`, the durable run
+  is cancelled so no further step runs — even mid-wait.
 
 Because the gates run before any state is created, a skipped event is invisible
 in `journeyStates` — to debug "why didn't this user enroll?", check the gate