@hogsend/cli 0.7.0 → 0.9.0

package/package.json

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

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

@@ -0,0 +1,217 @@
+---
+name: hogsend-authoring-destinations
+description: Use when adding or editing a code-defined OUTBOUND destination in src/destinations/ — defineDestination({ meta:{id}, events, transform(envelope, ctx) -> { url, method?, headers, body, isSuccess? } | null }) from @hogsend/engine. A destination is a delivery-time transform keyed by webhook_endpoints.kind that fans the outbound event catalog (contact.*, email.*, journey.completed, bucket.*) out to a product/data tool (PostHog, Segment, Slack, a CRM, a warehouse), reusing the engine's durable retry/backoff/DLQ delivery for free. Covers the shipped presets (webhook/posthog/segment/slack), ENABLED_DESTINATION_PRESETS, per-endpoint config credentials, the null-skip and throw-is-config-error contract, and the register ritual (src/destinations/index.ts + thread destinations into createHogsendClient in BOTH src/index.ts and src/worker.ts). NOT for ad-platform CAPI (deferred to PostHog CDP).
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Authoring Hogsend destinations
+
+A **destination** is a code-defined target for Hogsend's OUTBOUND event stream —
+PostHog, Segment, Slack, a CRM, a data warehouse. You declare it with
+`defineDestination()` in `src/destinations/`, the symmetric twin of
+`defineWebhookSource()` on the inbound side. It is the AUTHORING layer for event
+**fan-out**.
+
+The headline fact: a destination is a **delivery-time transform**, not a new
+delivery pipeline. The engine already has a durable outbound spine — every
+catalog event (`contact.*`, `email.*`, `journey.completed`, `bucket.*`) is
+written as a `webhook_deliveries` row and POSTed with retry / backoff / DLQ /
+reaper. A destination just **rewrites the HTTP request** for an endpoint whose
+`kind` matches your destination's `id`. You inherit ALL the durable delivery
+machinery for free — you only write the per-vendor projection.
+
+You are editing a **scaffolded consumer app** (content only). You import
+`defineDestination` from `@hogsend/engine`; you never touch engine internals (the
+registry, the delivery task, the retry machinery are all engine-owned). Relative
+imports use the ESM `.js` extension.
+
+> ⚠️ Destinations are for event **fan-out**. They are NOT the home for
+> ad-platform conversion forwarding (CAPI) — that stays deferred to PostHog CDP;
+> Hogsend just fires the events.
+
+## Do you even need to write one?
+
+Probably not. The engine ships four presets, each `defineDestination()` already:
+
+| preset id | target | credentials (per-endpoint `config`) |
+|-----------|--------|-------------------------------------|
+| `webhook` | the DEFAULT signed Standard-Webhooks POST to a subscriber URL | `secret` column (a `whsec_…`) |
+| `posthog` | PostHog capture endpoint | `{ apiKey, host?, eventNames? }` |
+| `segment` | Segment HTTP Tracking API (`/v1/track`, Basic auth) | `{ writeKey, host?, eventNames? }` |
+| `slack`   | Slack incoming webhook (formatted text block) | `{ url?, username?, iconEmoji? }` — `url` falls back to the endpoint `url` column |
+
+`webhook` and `posthog` are **always** registered. `segment`/`slack` register when
+`ENABLED_DESTINATION_PRESETS` allows them (see below). To USE a preset you create a
+`webhook_endpoints` row with that `kind` and its `config` (via the admin API /
+`hs.webhooks` SDK) — **no code**. Write a `defineDestination()` only for a NEW
+target shape, or to OVERRIDE a preset of the same id.
+
+## The shape
+
+```ts
+import { defineDestination } from "@hogsend/engine";
+
+export const crm = defineDestination({
+  meta: {
+    id: "crm",                 // == webhook_endpoints.kind it delivers
+    name: "Acme CRM",
+    description: "Forward lifecycle events to Acme.",
+  },
+  events: ["contact.created", "email.bounced"], // catalog events it accepts
+  transform(envelope, ctx) {
+    // envelope = the FROZEN { id, type, timestamp, data } emitOutbound wrote.
+    // ctx.endpoint = the LIVE webhook_endpoints row (url, config, secret).
+    const cfg = (ctx.endpoint.config ?? {}) as { token?: string };
+    if (!cfg.token) {
+      // A THROW = non-retryable CONFIG error → straight to the DLQ.
+      throw new Error("crm destination missing config.token");
+    }
+    return {
+      url: "https://api.acme.example/ingest",
+      method: "POST",                          // optional, defaults to POST
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${cfg.token}`,
+      },
+      body: JSON.stringify({ type: envelope.type, data: envelope.data }),
+      // isSuccess?: (status, bodySnippet) => boolean  — optional; default is 2xx.
+    };
+  },
+});
+```
+
+`defineDestination({ meta, events, transform })`:
+
+| field | required | notes |
+|-------|----------|-------|
+| `meta.id` | yes | The `webhook_endpoints.kind` this destination delivers. Pick a stable lowercase id; an endpoint with `kind === meta.id` routes here. Reusing a preset id (`posthog`/`segment`/`slack`) **overrides** that preset (you win on the merge). |
+| `meta.name` | yes | Human label. |
+| `meta.description` | no | One-liner. |
+| `events` | yes | The outbound catalog events this destination accepts (`OutboundEventName[]`). Per-endpoint subscription is STILL scoped by `webhook_endpoints.event_types`, so an endpoint only ever receives what it subscribed to — `events` documents intent and is the authoring-time contract. |
+| `transform` | yes | `(envelope, ctx) => { url, method?, headers, body, isSuccess? } \| null`. **Synchronous.** |
+
+`defineDestination` is an identity/validating function (like `defineWebhookSource`)
+— it returns its argument so a typo in the shape is a compile error.
+
+## The transform contract — three outcomes
+
+The `transform` runs once per delivery ATTEMPT (including retries), so it must be a
+**pure projection** of the envelope + endpoint — never mutate external state in it.
+
+1. **Return an `AdapterRequest`** (`{ url, headers, body, method?, isSuccess? }`)
+   → the delivery task POSTs exactly those bytes. `body` is the EXACT bytes sent
+   (for the `webhook` preset they are the SIGNED bytes — never re-stringify them).
+   Success is the default 2xx rule unless you supply `isSuccess`.
+2. **Return `null`** → SKIP delivery for that envelope. The row is marked
+   `delivered` as a successful **no-op** (no POST, no retry, no DLQ). Use this to
+   filter: e.g. only forward `email.bounced` for a certain template, drop the
+   rest.
+3. **Throw** → a non-retryable CONFIG error (missing credential, bad shape). The
+   row fast-fails straight to the dead-letter queue — it does NOT burn the retry
+   budget. A bad config should fail loudly, not silently retry 8 times.
+
+A network error / timeout / retryable HTTP status (`5xx`, `408`, `429`) is the
+delivery task's job — it retries with backoff off `nextRetryAt`. You never handle
+retries in a transform.
+
+## Where credentials live
+
+Destination credentials are **per-endpoint**, in `webhook_endpoints.config`
+(a JSONB bag) — NOT env vars, NOT a fake `whsec_`. The transform reads
+`ctx.endpoint.config`. This is the deliberate split from inbound presets (whose
+secrets are env-gated): a destination can have many endpoints, each with its own
+key, region, channel. `ENABLED_DESTINATION_PRESETS` only decides which preset
+TRANSFORMS are resolvable, never supplies a credential.
+
+## `ENABLED_DESTINATION_PRESETS` — which presets register
+
+A process-wide env knob (same `*`/csv/`none`/absent grammar as
+`ENABLED_WEBHOOK_PRESETS`), resolving which PRESET transforms are in the registry:
+
+- absent → `webhook` + `posthog` only (the always-on set).
+- `"none"` → STILL `webhook` + `posthog` (you can never disable the
+  no-regression signed-POST path or the auto-seeded PostHog destination).
+- a csv (e.g. `"segment,slack"`) → those, **unioned** with the always-on set.
+- `"*"` → every shipped preset.
+
+Your own `defineDestination()` destinations are NOT gated by this env — they are
+always registered (they came from your `destinations` array). The env governs
+PRESETS only.
+
+## Registering a destination (the wiring ritual)
+
+A defined destination does nothing until it is (1) exported from the barrel and
+(2) threaded into `createHogsendClient` in BOTH entry points. Like buckets — and
+UNLIKE lists — the wiring touches both `src/index.ts` and `src/worker.ts`, because
+the durable delivery task runs in the WORKER process and resolves transforms from
+the process registry `createHogsendClient` installs. **`destinations` is NOT passed
+to `createWorker`** — the worker's `createHogsendClient` call installs the registry.
+
+### 1. Export from `src/destinations/index.ts`
+
+```ts
+// src/destinations/index.ts
+import type { DefinedDestination } from "@hogsend/engine";
+import { crm } from "./crm.js"; // your defineDestination(), or inline it here
+
+// All defined destinations for this app. Passed to
+// createHogsendClient({ destinations }) in BOTH src/index.ts and src/worker.ts.
+export const destinations: DefinedDestination[] = [crm];
+```
+
+### 2. Thread into `createHogsendClient` in `src/index.ts`
+
+```ts
+import { createApp, createHogsendClient } from "@hogsend/engine";
+import { destinations } from "./destinations/index.js";
+// ...templates, journeys, webhookSources...
+
+const client = createHogsendClient({
+  journeys,
+  destinations,        // ← merged with the env presets; consumer wins on id collision
+  email: { templates },
+});
+const app = createApp(client, { webhookSources });
+```
+
+### 3. Thread into `createHogsendClient` in `src/worker.ts`
+
+```ts
+import { createHogsendClient, createWorker } from "@hogsend/engine";
+import { destinations } from "./destinations/index.js";
+
+const client = createHogsendClient({
+  journeys,
+  destinations,        // ← same array; the WORKER's delivery task needs the registry
+  email: { templates },
+});
+const worker = createWorker({ container: client, journeys /* …, NO destinations */ });
+```
+
+Wire `destinations` into `createHogsendClient` in BOTH files. Passing it to
+`createWorker` is not an accepted option — the worker resolves the registry through
+its OWN `createHogsendClient` call.
+
+## Creating the endpoint that uses your destination
+
+The destination is the TRANSFORM; an endpoint row is what makes it fire. Create
+one with the admin API / `hs.webhooks.create` with `kind` = your destination id,
+its `config` credentials, and the `eventTypes` it subscribes to. See the
+**hogsend-client-sdk** / **hogsend-cli** skills for managing outbound endpoints.
+
+## Golden rules
+
+1. A destination is a delivery-time transform keyed by `webhook_endpoints.kind`,
+   reusing the engine's durable delivery. You write the projection, not a pipeline.
+2. `transform` is SYNCHRONOUS and a PURE projection (runs per attempt). Return a
+   request, return `null` to skip (delivered no-op), or throw on bad config (→ DLQ).
+3. Credentials live per-endpoint in `webhook_endpoints.config`, never in env.
+   `ENABLED_DESTINATION_PRESETS` only governs which PRESETS register.
+4. `webhook` + `posthog` presets are always on; you cannot disable them.
+5. Wire `destinations` into `createHogsendClient` in BOTH `src/index.ts` AND
+   `src/worker.ts`. Do NOT pass it to `createWorker`.
+6. Reusing a preset id overrides that preset (consumer wins on the merge).
+7. Destinations are event fan-out — NOT ad-platform CAPI (deferred to PostHog CDP).

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

@@ -41,7 +41,10 @@ per unique URL, then single-pass replaces each href with
   `WHERE clicked_at IS NULL`), then **302-redirects to the original URL**.
 - After responding it fire-and-forgets an `email.link_clicked` event (props:
   `emailSendId`, `templateKey`, `linkUrl`, `linkId`) into PostHog + the ingest
-  pipeline, so journeys can branch on it and `exitOn` can fire.
+  pipeline, so journeys can branch on it and `exitOn` can fire. It ALSO emits the
+  outbound-catalog `email.clicked` event, which fans out durably to every
+  subscribed DESTINATION — **per-hit, not first-touch** (every click is delivered,
+  unlike the first-only `clicked_at` column).
 
 Authoring implication: use real `<a href>` / react-email `Button`/`Link` with
 absolute `https://` URLs and they're tracked automatically. Non-HTTP links
@@ -56,7 +59,9 @@ just before `</body>` (so always compose inside `Layout`, which emits a proper
 - `GET /v1/t/o/:id` sets `email_sends.opened_at` (first open only), returns a
   42-byte transparent GIF with `Cache-Control: no-store`.
 - Then fire-and-forgets an `email.opened` event (props: `emailSendId`,
-  `templateKey`).
+  `templateKey`) into PostHog + the ingest pipeline, and emits the outbound-catalog
+  `email.opened` event that fans out durably to every subscribed DESTINATION —
+  **per-hit, not first-touch**.
 
 The engine's own constants for these are `EMAIL_OPENED = "email.opened"` and
 `EMAIL_LINK_CLICKED = "email.link_clicked"`. In journey code, reference them via

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

@@ -59,10 +59,17 @@ export const welcome = defineJourney({
 ## Key concepts
 
 - **`ctx` is orchestration primitives ONLY** — `sleep`, `sleepUntil`, `when`,
-  `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`.
+  `waitForEvent`, `checkpoint`, `trigger`, `guard.isSubscribed`,
+  `history.hasEvent/journey/email`. Features are standalone imports: `sendEmail()`
+  comes from `@hogsend/engine`, NOT off `ctx`.
+- **Fan-out is DESTINATIONS, not `ctx`.** There is no `ctx.identify` /
+  `ctx.posthog.capture` — those single-vendor PostHog shims were removed. To get
+  user/event data into product + data tools (PostHog, Segment, Slack, a CRM, a
+  warehouse), set up an outbound DESTINATION: the email/contact/journey/bucket
+  lifecycle is delivered there durably (retry/backoff/DLQ), keyed by
+  `webhook_endpoints.kind`. EVERY destination receives EVERY open and click
+  (per-hit, not first-touch), and `email.delivered` is the canonical "email was
+  received" signal. See the **hogsend-authoring-destinations** skill.
 - **Duration helpers** `days()` / `hours()` / `minutes()` from `@hogsend/core`
   (also re-exported by `@hogsend/engine`) — never magic strings.
 - **`user`** carries `id`, `email`, `properties`, `stateId`, `journeyId`,

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

@@ -72,15 +72,27 @@ await ctx.trigger({
 });
 ```
 
-## PostHog (no-op without POSTHOG_API_KEY)
+## Fanning data out — use DESTINATIONS, not `ctx`
 
-```ts
-// Set person properties on PostHog for the current user.
-ctx.identify({ plan: "pro", onboarded: true });   // synchronous, void
+There is **no `ctx.identify` and no `ctx.posthog.capture`** — those single-vendor
+PostHog shims were removed. `ctx` does not fan data out to product/data tools.
 
-// Fire a custom PostHog event for the current user.
-ctx.posthog.capture({ event: "journey_step_reached", properties: { step: 2 } });
-```
+To mirror user/event data into PostHog, Segment, Slack, a CRM or a warehouse, set
+up an outbound **DESTINATION**: the email/contact/journey/bucket lifecycle is
+delivered there DURABLY (retry / backoff / DLQ), keyed by `webhook_endpoints.kind`.
+You don't fire it from `run` — it receives the lifecycle automatically:
+
+- `email.sent` / `email.delivered` / `email.opened` / `email.clicked` /
+  `email.bounced` / `email.complained`, `contact.*`, `journey.completed`,
+  `bucket.entered` / `bucket.left`.
+- `email.delivered` is the canonical **"email was received"** signal.
+- EVERY destination receives EVERY open and click — **per-hit, not first-touch** —
+  so downstream tools see the full engagement stream.
+
+See the **hogsend-authoring-destinations** skill. (PostHog is now JUST a
+destination, `kind="posthog"`.) If you need a fire-and-forget raw write inside a
+journey, `getPostHog()` is still importable from `@hogsend/engine` — but for
+fan-out, reach for a destination, not an in-journey vendor call.
 
 ## Guards
 
@@ -122,7 +134,9 @@ orchestration:
 - **`sendEmail()`** — `import { sendEmail } from "@hogsend/engine"`. See
   `references/sending-email-from-a-journey.md`.
 - **`getPostHog()`** — `import { getPostHog } from "@hogsend/engine"` for the raw
-  PostHog service (`ctx.identify` / `ctx.posthog.capture` cover the common cases).
+  PostHog service (a fire-and-forget escape hatch). For fanning lifecycle data out
+  to product/data tools, prefer an outbound DESTINATION (see above) — it delivers
+  durably and is vendor-neutral.
 - **SMS / push / Slack** — plain functions you import, never on `ctx`.
 - There is **no `ctx.db`, no `ctx.sendEmail`, no `ctx.hatchet`** surfaced to
   consumer journeys. If you reach for one of those, you are modelling it wrong —

package/skills/hogsend-cli/SKILL.md

@@ -74,6 +74,7 @@ Most commands READ (admin API). A handful WRITE through the data plane — marke
 | `hogsend events <userId>` | Raw event stream for one user (READ — `<userId>` stays the read path). |
 | `hogsend events send <name>` | **(write)** Push an event → `POST /v1/events`. `--email`/`--user-id` (≥1 required), `--prop`/`--props` (event props), `--contact-prop`/`--contact-props` (contact props), `--list`/`--unlist`, `--idempotency-key`, `--timestamp`. |
 | `hogsend emails send <template>` | **(write)** Send a transactional email → `POST /v1/emails`. `--to`/`--user-id` (≥1 required), `--prop`/`--props`, `--subject`, `--from`, `--reply-to`, `--category`, `--idempotency-key`, `--skip-preference-check` (needs full-admin). |
+| `hogsend webhooks list/get/create/update/delete/rotate-secret/test` | Manage **outbound** signed webhook endpoints (the event stream Hogsend emits to your URLs) → `/v1/admin/webhooks`. Needs the **admin key**, not the data key. `create --url <url>` + repeatable `--event <type>` or `--all-events`; the signing secret prints ONCE on `create` + `rotate-secret`. |
 | `hogsend skills list/add` | Manage these bundled agent skills. |
 | `hogsend upgrade` | Bump `@hogsend/*` deps to latest + refresh vendored skills. |
 | `hogsend setup` | Interactive LOCAL onboarding (docker, secret, migrate). |

package/skills/hogsend-client-sdk/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hogsend-client-sdk
-description: Use when calling Hogsend from your own product/app code (a signup handler, a billing webhook, a cron) via the @hogsend/client SDK + public data-plane API — new Hogsend({ baseUrl, apiKey }), then contacts.upsert/find/delete, events.send (alias .track), emails.send, lists.list/subscribe/unsubscribe. Teaches the contactProperties-vs-eventProperties split on POST /v1/events, the ingest-scoped HOGSEND_API_KEY, the 202 + listsError warning, and HogsendAPIError/RateLimitError. NOT for use inside a journey (there, use sendEmail()/ctx.trigger()). The scaffold ships a preconfigured `hs` at src/lib/hogsend.ts.
+description: Use when calling Hogsend from your own product/app code (a signup handler, a billing webhook, a cron) via the @hogsend/client SDK + public data-plane API — new Hogsend({ baseUrl, apiKey }), then contacts.upsert/find/delete, events.send (alias .track), emails.send, lists.list/subscribe/unsubscribe, webhooks.create/list/get/update/delete/rotateSecret/sendTest (ADMIN plane — needs a full-admin key), and verifyHogsendWebhook for the subscriber side. Teaches the contactProperties-vs-eventProperties split on POST /v1/events, the ingest-scoped HOGSEND_API_KEY, the 202 + listsError warning, and HogsendAPIError/RateLimitError. NOT for use inside a journey (there, use sendEmail()/ctx.trigger()). The scaffold ships a preconfigured `hs` at src/lib/hogsend.ts.
 license: MIT
 metadata:
   author: withSeismic
@@ -103,6 +103,63 @@ await hs.emails.send({                          // POST /v1/emails
 await hs.lists.list();                          // GET  /v1/lists -> ListSummary[]
 await hs.lists.subscribe({ list: "newsletter", email: "ada@example.com" });
 await hs.lists.unsubscribe({ list: "newsletter", userId: "u_1" });
+
+// Webhooks (ADMIN plane — needs a full-admin apiKey, NOT the ingest key) ---
+await hs.webhooks.create({                      // POST /v1/admin/webhooks
+  url: "https://your.app/hooks",
+  eventTypes: ["contact.created", "email.sent"],
+});                                             // -> endpoint incl. full `secret` (shown ONCE)
+await hs.webhooks.list();                        // -> WebhookEndpoint[]
+await hs.webhooks.rotateSecret("we_123");        // -> { id, secret, secretPrefix } (secret ONCE)
+```
+
+## `hs.webhooks` — outbound endpoints (DIFFERENT plane + key)
+
+`hs.webhooks.*` manages the **outbound** signed event stream Hogsend emits to
+your URLs (`contact.*`, `email.*`, `journey.completed`, `bucket.*`). Unlike every
+other resource above, it targets the **ADMIN plane** (`/v1/admin/webhooks`) and
+**requires a full-admin `apiKey`** — a leaked ingest key must never register an
+exfiltration endpoint. Construct a separate `Hogsend` instance with an admin key
+if your data-plane `hs` only holds an ingest key.
+
+`create`/`list`/`get`/`update`/`delete`/`rotateSecret`/`sendTest`. The full
+signing secret (`whsec_…`) is returned **only once** — on `create` and
+`rotateSecret`; `list`/`get` only expose `secretPrefix`. Store it on create.
+
+`create`/`update` also take a **`kind`** (+ **`config`**) — this is how you manage
+an outbound DESTINATION from the SDK. `kind="webhook"` (the default) is the
+byte-identical signed POST. A keyed destination (`kind="posthog"|"segment"|"slack"|…`)
+fans the same event stream out to that tool via a server-side transform; its
+credentials live in `config` (e.g. `{ apiKey }`) — never an env var — and it
+returns NO `secret` (it authenticates via `config`). Same durable
+retry/backoff/DLQ spine either way.
+
+```ts
+// Fan the email lifecycle out to PostHog as a managed destination — no code:
+await hs.webhooks.create({
+  url: "https://us.i.posthog.com",            // host (the posthog transform appends /capture/)
+  eventTypes: ["email.delivered", "email.opened", "email.clicked", "email.bounced"],
+  kind: "posthog",
+  config: { apiKey: process.env.POSTHOG_API_KEY! },
+});
+```
+
+**Subscriber side:** in the handler that RECEIVES Hogsend's signed POSTs, call
+`verifyHogsendWebhook({ payload, headers, secret })` (also exported from
+`@hogsend/client`). Pass the **raw request body bytes** (never a re-stringified
+object); it returns the parsed `{ id, type, timestamp, data }` envelope and
+THROWS on a bad/missing signature or a timestamp outside the 5-minute tolerance.
+Deliveries are at-least-once — dedupe on the `Webhook-Id` header.
+
+```ts
+import { verifyHogsendWebhook } from "@hogsend/client";
+
+const event = verifyHogsendWebhook({
+  payload: rawBody,        // the EXACT bytes Hogsend signed
+  headers: req.headers,
+  secret: process.env.HOGSEND_WEBHOOK_SECRET!, // whsec_… from create / rotate
+});
+// switch on event.type …
 ```
 
 ## `eventProperties` vs `contactProperties` (the split that trips people up)

package/skills/hogsend-client-sdk/references/api-surface.md

@@ -157,6 +157,114 @@ For how `subscribe`/`unsubscribe` interact with a list's `defaultOptIn` polarity
 (opt-in needs an exact `true`, opt-out is blocked only on an exact `false`), see
 the hogsend-authoring-lists skill.
 
+## `hs.webhooks` (ADMIN plane — full-admin key required)
+
+Manage **outbound** webhook endpoints (the Svix-style signed event stream Hogsend
+emits to subscriber URLs). Every method targets `/v1/admin/webhooks` and requires
+a **full-admin** `apiKey` — NOT the ingest data key the resources above use.
+Signing-secret management is the same trust class as API-key management.
+
+### `webhooks.create(input) → CreatedWebhookEndpoint`
+
+`POST /v1/admin/webhooks`. Register an endpoint subscribed to one or more of the
+13 outbound event types. For the default `kind="webhook"` it returns the endpoint
+INCLUDING the full signing `secret` (`whsec_…`) — shown ONLY here and on
+`rotateSecret`. Store it now. A keyed DESTINATION (`kind="posthog"|"segment"|
+"slack"|…`) carries its credentials in `config` and returns NO secret.
+
+```ts
+type CreateWebhookInput = {
+  url: string;
+  eventTypes: OutboundEventType[]; // contact.* | email.* | journey.completed | bucket.*
+  description?: string;
+  disabled?: boolean;
+  kind?: WebhookKind;              // "webhook" (default signed POST) | "posthog" | "segment" | "slack" | (string & {})
+  config?: Record<string, unknown>; // per-destination credentials, e.g. { apiKey } — ignored for kind="webhook"
+};
+
+interface WebhookEndpoint {
+  id: string;                         // we_…
+  url: string;
+  description: string | null;
+  eventTypes: OutboundEventType[];
+  secretPrefix: string | null;        // first chars, e.g. whsec_AbCd — null for keyed destinations
+  kind: WebhookKind;                  // delivery transform selector
+  config: Record<string, unknown> | null; // credentials REDACTED in responses (apiKey → "***"); null for kind="webhook"
+  status: "enabled" | "disabled";
+  organizationId: string | null;
+  lastDeliveryAt: string | null;      // ISO
+  createdAt: string;                  // ISO
+  updatedAt: string;                  // ISO
+}
+
+// `secret` is present ONLY for kind="webhook" (keyed destinations carry none), hence optional.
+type CreatedWebhookEndpoint = WebhookEndpoint & { secret?: string }; // full secret ONCE
+```
+
+### `webhooks.list(opts?) → WebhookEndpoint[]`
+
+`GET /v1/admin/webhooks`. Newest first; `opts` = `{ limit?, offset?,
+includeDisabled? }`. Returns the endpoints array (unwrapped from the
+`{ endpoints, total, limit, offset }` envelope). No `secret` — `secretPrefix` only.
+
+### `webhooks.get(id) → WebhookEndpoint`
+
+`GET /v1/admin/webhooks/{id}`. One endpoint (404 → `HogsendAPIError`). No secret.
+
+### `webhooks.update(id, input) → WebhookEndpoint`
+
+`PATCH /v1/admin/webhooks/{id}`. Only the provided fields change;
+`description: null` clears it. Does NOT return or rotate the secret.
+
+```ts
+type UpdateWebhookInput = {
+  url?: string;
+  eventTypes?: OutboundEventType[];
+  description?: string | null;
+  disabled?: boolean;
+  kind?: WebhookKind;                       // switch the delivery transform
+  config?: Record<string, unknown> | null;  // replace per-destination config; null clears it
+};
+```
+
+### `webhooks.delete(id) → { deleted }`
+
+`DELETE /v1/admin/webhooks/{id}`. Hard-delete; cascade drops its deliveries.
+
+### `webhooks.rotateSecret(id) → { id, secret, secretPrefix }`
+
+`POST /v1/admin/webhooks/{id}/rotate-secret`. Hard cutover — the OLD secret is
+invalidated immediately; in-flight retries re-sign with the new one. The new
+`secret` is returned ONCE. Update every subscriber.
+
+### `webhooks.sendTest(id) → { enqueued, eventType: "webhook.test" }`
+
+`POST /v1/admin/webhooks/{id}/test`. Enqueues an out-of-band `webhook.test`
+delivery, sent regardless of the endpoint's subscribed `eventTypes`.
+
+## `verifyHogsendWebhook(opts)` — the subscriber side
+
+A standalone helper exported from `@hogsend/client` (not on the `Hogsend`
+instance) for the handler that RECEIVES Hogsend's signed POSTs.
+
+```ts
+import { verifyHogsendWebhook } from "@hogsend/client";
+
+const event = verifyHogsendWebhook({
+  payload: rawBody,   // the EXACT raw request body bytes — never a re-stringified object
+  headers: req.headers,
+  secret: "whsec_…",  // the endpoint secret from create / rotateSecret
+});
+// event === { id, type, timestamp, data }
+```
+
+- Returns the parsed envelope (`{ id, type, timestamp, data }`) on success.
+- **THROWS** on a bad signature, a missing signature header, or a timestamp
+  outside the 5-minute tolerance — wrap in `try/catch` and reply `401` on throw.
+- Accepts both the `Webhook-*` and `svix-*` header aliases (case-insensitive).
+  Uses svix when available, with a pure `node:crypto` HMAC-SHA256 fallback.
+- Deliveries are **at-least-once** — dedupe on the `Webhook-Id` (`event.id`).
+
 ## Construction options (recap)
 
 ```ts

package/skills/hogsend-extending/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hogsend-extending
-description: Use when extending a Hogsend app beyond journeys/emails/buckets — swapping the email or analytics provider behind its engine-owned contract (EmailProvider / PostHogService), wiring an outbound integration (Slack, a CRM, Stripe) as plain code called from a journey, or deciding when to publish a reusable @hogsend/plugin-* package. Covers the two categories of extension and where each is wired.
+description: Use when extending a Hogsend app beyond journeys/emails/buckets — swapping the email or analytics provider behind its engine-owned contract (EmailProvider / PostHogService), wiring an outbound integration (Slack, a CRM, Stripe) as plain code called from a journey, fanning the outbound EVENT stream out to a tool via a code-defined destination (defineDestination, see hogsend-authoring-destinations), or deciding when to publish a reusable @hogsend/plugin-* package. Covers the categories of extension and where each is wired.
 license: MIT
 metadata:
   author: withSeismic
@@ -9,7 +9,7 @@ metadata:
 
 # Extending Hogsend
 
-There are **two** ways to extend a Hogsend app, and they are different
+There are **three** ways to extend a Hogsend app, and they are different
 mechanisms — don't reach for the wrong one.
 
 1. **Capability providers** (email, analytics). The engine itself drives these,
@@ -21,15 +21,30 @@ mechanisms — don't reach for the wrong one.
    `@hogsend/plugin-resend` and `@hogsend/plugin-posthog` are the **bundled
    defaults and reference implementations**; you only swap when you want a
    different vendor. → `references/swap-a-provider.md`.
+   Note: the `analytics` (`PostHogService`) role is now NARROW — it is NOT the
+   outbound-event firing path (that's destinations, below). It's load-bearing for
+   exactly two things: the identity **PULL** (`getPersonProperties` for per-user
+   timezone resolution at enrollment) and the opt-in `bucket.syncToPostHog`
+   person-property mirror. PostHog is otherwise just a destination (`kind="posthog"`).
 
-2. **Integrations** (everything you call *out* to — Slack, a CRM, Stripe, an
-   internal HTTP API). **No contract, no framework.** Install the SDK, write a
-   thin wrapper in your own `src/lib/`, import it into a journey, and call it like
-   a function. The engine never sees it. → `references/build-an-integration.md`.
+2. **Integrations** (a one-directional call *out* to a service — post to Slack,
+   create a CRM record, charge Stripe — from inside a JOURNEY at a specific
+   step). **No contract, no framework.** Install the SDK, write a thin wrapper in
+   your own `src/lib/`, import it into a journey, and call it like a function. The
+   engine never sees it. → `references/build-an-integration.md`.
 
-**The deciding question: does the engine call it, or do you?** If the engine
-drives the capability (sending mail, capturing analytics) it's a provider behind
-a contract. If your journey reaches outward, it's a plain integration.
+3. **Destinations** (fan the engine's OUTBOUND EVENT stream — `contact.*`,
+   `email.*`, `journey.completed`, `bucket.*` — out to a tool DURABLY, on every
+   matching event, not at a single journey step). A code-defined
+   `defineDestination()` is a delivery-time transform keyed by an endpoint
+   `kind`; it reuses the engine's durable retry / backoff / DLQ delivery. The
+   engine ships `webhook`/`posthog`/`segment`/`slack` presets. → the
+   **hogsend-authoring-destinations** skill.
+
+**The deciding questions.** Does the engine DRIVE the capability (sending mail,
+capturing analytics)? → a provider behind a contract (1). Are you reaching out at
+ONE journey step? → a plain integration (2). Do you want EVERY lifecycle event
+mirrored to a tool, durably? → a destination (3).
 
 ## Swapping a capability provider — the short version
 
@@ -38,7 +53,8 @@ a contract. If your journey reaches outward, it's a plain integration.
   reference implementation to copy is `packages/plugin-resend/src/provider.ts`
   (`createResendProvider`).
 - **Wire it.** `createHogsendClient({ email: { templates, provider: createMyProvider(...) } })`.
-  Analytics is a **top-level** option (the engine itself fires captures):
+  Analytics is a **top-level** option (the engine uses it for the identity pull +
+  bucket sync, not for outbound fan-out):
   `createHogsendClient({ analytics: createMyAnalytics(...) })`.
 - **You get everything else for free.** Template rendering, link-click + open
   tracking, preference/suppression checks, the frequency cap, and the
@@ -62,6 +78,19 @@ a contract. If your journey reaches outward, it's a plain integration.
   Hatchet task in `src/workflows/` and register it via
   `createWorker({ extraWorkflows })`.
 
+## Fanning the event stream to a tool — the short version
+
+When you want a tool to receive EVERY matching lifecycle event (an analytics
+warehouse mirroring `email.*`, a Slack channel pinged on `email.bounced`), don't
+hand-roll an integration call in every journey — author an outbound
+**destination** instead. `defineDestination({ meta:{id}, events, transform })` in
+`src/destinations/` is a delivery-time projection keyed by an endpoint `kind`,
+and it inherits the engine's durable retry / backoff / DLQ delivery for free. The
+engine ships `webhook` (default signed POST), `posthog`, `segment`, and `slack`
+presets, so most fan-out is config (a `webhook_endpoints` row), not code. Wire
+your `destinations` array into `createHogsendClient` in BOTH `src/index.ts` and
+`src/worker.ts`. → the **hogsend-authoring-destinations** skill.
+
 ## When to publish a `@hogsend/plugin-*` package
 
 Almost never from a scaffolded app. A standalone module in your `src/` is the
@@ -73,7 +102,9 @@ Hogsend monorepo, not in your client app.
 ## What NOT to do
 
 - **Don't put a service on `ctx`.** `ctx` is durable-orchestration primitives only
-  (`sleep`, `checkpoint`, `trigger`, `guard`, `history`, `posthog`, `identify`).
+  (`sleep`, `sleepUntil`, `when`, `waitForEvent`, `checkpoint`, `trigger`, `guard`,
+  `history`). There is no `ctx.posthog` / `ctx.identify` — those were removed; fan
+  data out with a destination instead.
 - **Don't reach for a provider contract for a one-directional call** — that's an
   integration (just code).
 - **Don't import the `EmailProvider`/`PostHogService` contract from a

package/skills/hogsend-extending/references/swap-a-provider.md

@@ -115,8 +115,21 @@ Same shape: the `PostHogService` contract lives in `@hogsend/core`
 (canonical `@hogsend/engine`); `createPostHogService` (`@hogsend/plugin-posthog`)
 is the default + reference impl. Supply your own via the **top-level**
 `createHogsendClient({ analytics })` option. PostHog is optional — with no
-`POSTHOG_API_KEY` the engine resolves analytics to `undefined` and every capture
-is a no-op.
+`POSTHOG_API_KEY` the engine resolves analytics to `undefined` and the reads
+below become no-ops.
+
+Its role is now **NARROW**. The engine no longer fires the outbound event catalog
+(`email.*` / `contact.*` / `journey.completed` / `bucket.*`) through analytics —
+that fan-out moved to **destinations** on the durable webhook spine, and PostHog
+is now just one destination (`kind="posthog"`, see hogsend-authoring-destinations).
+`PostHogService` is load-bearing for exactly two things, both of which a swapped
+provider must still satisfy:
+
+1. The identity **PULL** — `getPersonProperties(distinctId)`, used for per-user
+   timezone resolution at journey enrollment.
+2. The opt-in `bucket.syncToPostHog` person-property mirror (`$set`/`$unset` of a
+   cohort boolean on bucket transitions) — a PostHog-direct write because `$set`
+   identity semantics have no vendor-neutral envelope.
 
 ## Don't over-reach