@hogsend/cli 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/cli",
-  "version": "0.7.0",
+  "version": "0.8.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.8.0",
     "@repo/typescript-config": "0.0.0"
   },
   "engines": {

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,45 @@ 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.
+
+**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,105 @@ 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
+12 outbound event types. Returns the endpoint INCLUDING the full signing
+`secret` (`whsec_…`) — shown ONLY here and on `rotateSecret`. Store it now.
+
+```ts
+type CreateWebhookInput = {
+  url: string;
+  eventTypes: OutboundEventType[]; // contact.* | email.* | journey.completed | bucket.*
+  description?: string;
+  disabled?: boolean;
+};
+
+interface WebhookEndpoint {
+  id: string;                         // we_…
+  url: string;
+  description: string | null;
+  eventTypes: OutboundEventType[];
+  secretPrefix: string;               // first 12 chars, e.g. whsec_AbCd
+  status: "enabled" | "disabled";
+  organizationId: string | null;
+  lastDeliveryAt: string | null;      // ISO
+  createdAt: string;                  // ISO
+  updatedAt: string;                  // ISO
+}
+
+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;
+};
+```
+
+### `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-webhooks-and-workflows/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hogsend-webhooks-and-workflows
-description: Use when adding an inbound webhook source in src/webhook-sources/ (defineWebhookSource — auth header + envKey, optional Zod schema, transform(payload, ctx) -> IngestEvent | null, served at POST /v1/webhooks/:id) or a custom Hatchet task in src/workflows/ passed as extraWorkflows (NOT workflows) to createWorker, including the idempotent batched expand→migrate→contract backfill pattern.
+description: Use when adding an inbound webhook source in src/webhook-sources/ (defineWebhookSource — auth as a match|signature discriminated union, optional Zod schema, transform(payload, ctx) -> IngestEvent | null, served at POST /v1/webhooks/:id), reaching for a built-in integration preset (Clerk/Supabase/Stripe/Segment), or a custom Hatchet task in src/workflows/ passed as extraWorkflows (NOT workflows) to createWorker, including the idempotent batched expand→migrate→contract backfill pattern. Outbound signed webhooks are managed separately (hogsend webhooks CLI / hs.webhooks).
 license: MIT
 metadata:
   author: withSeismic
@@ -25,10 +25,20 @@ Relative imports use the ESM `.js` extension.
 
 - **`defineWebhookSource({ meta, auth, schema?, transform })`** (from
   `@hogsend/engine`) — declares one source served at `POST /v1/webhooks/:id`.
-  `auth` matches a request header against an env secret; `schema` is an optional
-  Zod validator; `transform(payload, ctx)` returns an `IngestEvent | null`
-  (`null` = accept-and-skip). Register sources in `src/webhook-sources/index.ts`
-  and pass them to `createApp(client, { webhookSources })` in `src/index.ts`.
+  `auth` is a **discriminated union on `type`**: `"match"` (shared-secret
+  equality against a header/`Authorization: Bearer`; OPEN when the secret is
+  unset) or `"signature"` (`scheme: "svix" | "stripe" | "hmac-hex"`, with an
+  `envKey`, optional `header`/`fallbackMatchHeader`; FAILS CLOSED with 401 when
+  the secret is unset). `schema` is an optional Zod validator; `transform(payload,
+  ctx)` returns an `IngestEvent | null` (`null` = accept-and-skip). Register
+  sources in `src/webhook-sources/index.ts` and pass them to
+  `createApp(client, { webhookSources })` in `src/index.ts`.
+- **Built-in integration presets** — the engine ships four ready-made inbound
+  sources (Clerk, Supabase, Stripe, Segment) served at
+  `POST /v1/webhooks/{clerk,supabase,stripe,segment}` with no code to write. Each
+  mounts only when its secret env var is set AND `ENABLED_WEBHOOK_PRESETS`
+  allows it (`"*"`/absent = auto, a csv of ids = exactly those, `"none"` = off).
+  Defining your own source with the SAME id overrides the preset (you win).
 - **`IngestEvent`** — the shape `transform` must return:
   `{ event, userId, userEmail, properties, idempotencyKey? }`. The route feeds it
   straight into `ingestEvent()`, so a webhook can enroll users into journeys.
@@ -66,3 +76,8 @@ Relative imports use the ESM `.js` extension.
   helpers.
 - To verify a webhook or task against a running instance (events landing,
   contacts upserted, journeys firing), see the **hogsend-cli** skill.
+- **Inbound vs outbound:** this skill is about *inbound* sources (HTTP → engine).
+  The engine also emits an *outbound* signed event stream (`contact.*`,
+  `email.*`, `journey.completed`, `bucket.*`) to subscriber URLs — manage those
+  endpoints with `hogsend webhooks …` (hogsend-cli skill) or `hs.webhooks.*`
+  (hogsend-client-sdk skill), and verify deliveries with `verifyHogsendWebhook`.

package/skills/hogsend-webhooks-and-workflows/references/webhook-source.md

@@ -18,19 +18,40 @@ You write the source files; the engine owns the route. Edit only
 | `meta.id` | `string` | The `:sourceId` segment in the URL. Keep it URL-safe. |
 | `meta.name` | `string` | Human label. |
 | `meta.description?` | `string` | Optional. |
-| `auth.header` | `string` | Request header carrying the shared secret. |
-| `auth.envKey` | `string` | Env var holding the expected secret value. |
-| `auth.type` | `"match"` | Only mode today: header value must equal the env value. |
+| `auth` | discriminated union on `type` | `"match"` or `"signature"` — see below. |
 | `schema?` | `z.ZodSchema<T>` | Optional Zod validator; on success `payload` is typed `T`. |
 | `transform(payload, ctx)` | `=> Promise<IngestEvent \| null>` | Map payload → event. Return `null` to accept-and-skip. |
 
-### Auth behaviour (important)
+### Auth: a discriminated union on `type`
 
-The route enforces auth **only when the env secret is set**. If
-`process.env[auth.envKey]` is empty/undefined the source is treated as **open**
-(no auth). When the secret is present, the request must send it either in
-`auth.header` or as `Authorization: Bearer <secret>`; otherwise the route returns
-`401`. Always set the env secret in any non-local environment.
+`auth` is a discriminated union — pick the variant that matches your provider:
+
+```ts
+// "match" — plain shared-secret equality (the PostHog scaffold source uses this)
+auth: { type: "match"; header: string; envKey: string }
+
+// "signature" — provider HMAC verification over the EXACT raw body bytes
+auth: {
+  type: "signature";
+  scheme: "svix" | "stripe" | "hmac-hex";
+  envKey: string;
+  header?: string;             // the signature header to read
+  fallbackMatchHeader?: string; // e.g. Supabase's plain x-supabase-webhook-secret
+  verify?(args): boolean | Promise<boolean>; // optional override of the scheme
+}
+```
+
+**Auth behaviour (important — the two variants differ on the unset-secret case):**
+
+- **`"match"`** enforces auth **only when the env secret is set**. If
+  `process.env[envKey]` is empty/undefined the source is treated as **open** (no
+  auth). When the secret is present, the request must send it in `header` or as
+  `Authorization: Bearer <secret>`, else the route returns `401`. Always set the
+  secret in any non-local environment.
+- **`"signature"`** **FAILS CLOSED** — when its secret is unset the route returns
+  `401` and never reaches `transform`. The route reads the EXACT raw body once
+  and verifies the HMAC (Svix / Stripe `t=…,v1=…` with 5-min tolerance / generic
+  hex HMAC) over those bytes. The raw bytes are also exposed as `ctx.rawBody`.
 
 ### Validation
 
@@ -52,9 +73,11 @@ interface IngestEvent {
 }
 ```
 
-`ctx` is `{ db, logger }` — a Drizzle `Database` and the engine logger — for
-lookups/diagnostics inside the transform. It does **not** carry `hatchet` or the
-registry; those are applied by the route when it calls `ingestEvent`.
+`ctx` is `{ db, logger, rawBody?, headers? }` — a Drizzle `Database`, the engine
+logger, and (populated by the route) the EXACT raw request body bytes and the
+lowercased request headers, for lookups/diagnostics or provider-specific raw
+access inside the transform. It does **not** carry `hatchet` or the registry;
+those are applied by the route when it calls `ingestEvent`.
 
 Notes that match the engine's behaviour:
 
@@ -160,6 +183,28 @@ const app = createApp(client, { webhookSources });
 
 That's it. Your source is now live at `POST /v1/webhooks/stripe`.
 
+## Built-in integration presets (no code)
+
+Before writing a source, check whether the engine already ships one. Four
+presets are built into `@hogsend/engine` and served with no consumer code:
+
+| Preset | Route | Scheme | Secret env var |
+|--------|-------|--------|----------------|
+| `clerk` | `POST /v1/webhooks/clerk` | `svix` | `CLERK_WEBHOOK_SECRET` |
+| `supabase` | `POST /v1/webhooks/supabase` | `svix` (+ plain `x-supabase-webhook-secret` fallback) | `SUPABASE_WEBHOOK_SECRET` |
+| `stripe` | `POST /v1/webhooks/stripe` | `stripe` | `STRIPE_WEBHOOK_SECRET` |
+| `segment` | `POST /v1/webhooks/segment` | `hmac-hex` | `SEGMENT_WEBHOOK_SECRET` |
+
+A preset mounts only when **both** its secret env var is set **and**
+`ENABLED_WEBHOOK_PRESETS` allows it: `"*"`/absent = auto (every preset whose
+secret is set), a comma-separated list of ids = exactly those (still requires the
+secret), `"none"` = all off. A preset with no secret is never mounted (signature
+sources fail closed). Defining your own `defineWebhookSource` with the SAME id
+**overrides** the preset — the consumer always wins. Each preset's exact
+provider-event → Hogsend-event mapping (and the `contactProperties` vs
+`eventProperties` split) lives in its source file under
+`packages/engine/src/webhook-sources/presets/`.
+
 ## Authoring a new source — checklist
 
 1. Create `src/webhook-sources/<id>.ts` exporting a `defineWebhookSource({...})`.

package/src/commands/index.ts

@@ -12,6 +12,7 @@ import { statsCommand } from "./stats.js";
 import { studioCommand } from "./studio.js";
 import type { Command } from "./types.js";
 import { upgradeCommand } from "./upgrade.js";
+import { webhooksCommand } from "./webhooks.js";
 
 /**
  * The command registry. The router (src/bin.ts) matches the leading argv token
@@ -29,6 +30,7 @@ export const commands: Command[] = [
   eventsCommand,
   emailsCommand,
   campaignsCommand,
+  webhooksCommand,
   studioCommand,
   setupCommand,
   skillsCommand,