@hogsend/cli 0.2.1 → 0.2.2

package/package.json

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

package/skills/hogsend-extending/SKILL.md

@@ -0,0 +1,82 @@
+---
+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.
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Extending Hogsend
+
+There are **two** 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,
+   so each has an **engine-owned contract** you implement and swap behind.
+   `EmailProvider` and `PostHogService` are defined in `@hogsend/core` and
+   re-exported from `@hogsend/engine` (the canonical import). You supply an
+   implementation via `createHogsendClient({ email: { provider }, analytics })`
+   and the engine routes to it — including inbound provider webhooks.
+   `@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`.
+
+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`.
+
+**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.
+
+## Swapping a capability provider — the short version
+
+- **Implement the contract.** `import type { EmailProvider } from "@hogsend/engine"`
+  — four methods: `send`, `sendBatch`, `verifyWebhook`, `parseWebhook`. The
+  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):
+  `createHogsendClient({ analytics: createMyAnalytics(...) })`.
+- **You get everything else for free.** Template rendering, link-click + open
+  tracking, preference/suppression checks, the frequency cap, and the
+  `email_sends` row all live in the engine's `createTrackedMailer` — never in the
+  provider. They come along regardless of which provider you supply.
+- **Defaults.** Pass nothing and you get Resend (built from `RESEND_API_KEY`) +
+  PostHog (from `POSTHOG_API_KEY`). Inbound delivery webhooks land at the
+  engine-owned route `POST /v1/webhooks/resend`.
+- ⚠️ The contract's `SendEmailOptions` imports from `@hogsend/core` (or
+  `@hogsend/plugin-resend`), **not** `@hogsend/engine` — the engine's own
+  `SendEmailOptions` is a different, higher-level send type.
+
+## Wiring an integration — the short version
+
+- Install the SDK; write `src/lib/<service>.ts` exporting a
+  `create<Service>(config)` factory that **validates config at construction, not
+  at import** (so tests don't blow up on a missing env var).
+- Import it into a journey and call it: `await slack.sendMessage({ ... })`. It's a
+  function call, **not** `ctx.sendMessage` — `ctx` is orchestration-only.
+- Heavy or background work (a nightly CRM sync, a fan-out import) → author a
+  Hatchet task in `src/workflows/` and register it via
+  `createWorker({ extraWorkflows })`.
+
+## When to publish a `@hogsend/plugin-*` package
+
+Almost never from a scaffolded app. A standalone module in your `src/` is the
+right default. Author and publish a real `@hogsend/plugin-*` package only when an
+integration is **reusable across multiple apps** or you intend to **contribute it
+back to the engine** — that is engine-development work done in a clone of the
+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`).
+- **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
+  `@hogsend/plugin-*` package** in new code — use `@hogsend/engine` (canonical).
+  The plugins still re-export the contracts for back-compat, but new code should
+  import from the engine.

package/skills/hogsend-extending/references/build-an-integration.md

@@ -0,0 +1,114 @@
+# Building an integration
+
+An integration is **something your journey calls out to** — Slack, a CRM, Stripe,
+an internal HTTP API. It has **no contract** and the engine knows nothing about
+it. The simplest integration is the best one: install the SDK, write a thin
+wrapper, import it into a journey.
+
+This is *not* a capability provider — don't implement an engine contract for it,
+and don't put it on `ctx`. (For email/analytics, which the engine drives, see
+`swap-a-provider.md`.)
+
+## 1. Install the SDK
+
+```bash
+pnpm add @slack/web-api
+```
+
+## 2. Write a thin wrapper — fail at construction, not at import
+
+```ts
+// src/lib/slack.ts — your content
+import { WebClient } from "@slack/web-api";
+
+export interface SlackServiceConfig {
+  token: string;
+  defaultChannel?: string;
+}
+
+export function createSlackService(config: SlackServiceConfig) {
+  if (!config.token) {
+    throw new Error("SlackServiceConfig.token is required");
+  }
+  const client = new WebClient(config.token);
+
+  return {
+    async sendMessage(opts: { channel?: string; text: string }) {
+      const channel = opts.channel ?? config.defaultChannel;
+      if (!channel) throw new Error("No channel and no defaultChannel configured");
+      try {
+        const result = await client.chat.postMessage({ channel, text: opts.text });
+        return { ts: result.ts, channel: result.channel };
+      } catch (error) {
+        // Don't swallow — let the journey's error handling mark the run failed.
+        throw new Error(
+          `Slack sendMessage failed for ${channel}: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    },
+  };
+}
+```
+
+Top-level `process.env.X!` access throws on *import* (even in tests). Validate
+inside the factory instead.
+
+## 3. Use it in a journey — a function call, not `ctx`
+
+```ts
+// src/journeys/churn-alert.ts — your content
+import { days } from "@hogsend/core";
+import { defineJourney, sendEmail } from "@hogsend/engine";
+import { createSlackService } from "../lib/slack.js";
+import { Events, Templates } from "./constants/index.js";
+
+const slack = createSlackService({
+  token: process.env.SLACK_BOT_TOKEN ?? "",
+  defaultChannel: "#lifecycle-alerts",
+});
+
+export const churnAlert = defineJourney({
+  meta: { id: "churn-alert", name: "Churn alert", enabled: true, trigger: { event: Events.PAYMENT_FAILED } },
+  run: async (user, ctx) => {
+    await slack.sendMessage({ text: `Payment failed for ${user.email}.` });
+    await sendEmail({ to: user.email, userId: user.id, template: Templates.CHURN_PAYMENT_FAILED, subject: "Your payment didn't go through" });
+    await ctx.sleep({ duration: days(2) });
+    // ...escalate if still failing
+  },
+});
+```
+
+`slack.sendMessage` and `sendEmail` are both plain imports — neither is on `ctx`.
+That keeps the journey context focused on orchestration and avoids coupling
+integrations to the engine.
+
+## Conventions
+
+- **Optional caching.** If your service fetches slow-changing data (like
+  `@hogsend/plugin-posthog` does for person properties), accept an optional Redis
+  client + TTL in config and cache there.
+- **Need the DB?** Open a connection with `createDatabase()` from `@hogsend/db`
+  against your `DATABASE_URL`, or query a client-track table you defined in
+  `src/schema/`.
+- **Cleanup?** Expose a `shutdown()` and call it from your `src/worker.ts`
+  graceful-shutdown handler alongside `worker.stop()`.
+- **Testing.** Test against a mocked SDK client — no real API calls. The bundled
+  `packages/plugin-resend/src/__tests__/` show the pattern.
+
+## Background jobs (Hatchet tasks)
+
+Some integrations are better as durable background work than inline — a nightly
+CRM sync, a heavy backfill, a fan-out import. Author them as Hatchet tasks in your
+`src/workflows/` and register via `createWorker({ extraWorkflows })` (the option
+is `extraWorkflows`, NOT `workflows`). They run on the same worker as your
+journeys. For heavy backfills, use `runBatchedBackfill` from `@hogsend/engine`;
+the scaffold ships a `src/workflows/backfill-example.ts` to copy. See the
+`hogsend-webhooks-and-workflows` skill for the full pattern.
+
+## What integrations are not
+
+No manifest, no auto-discovery, no lifecycle hooks, no registration. You import
+what you need, where you need it. Integrations live entirely in your content, and
+the engine upgrades underneath them with `pnpm up`.

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

@@ -0,0 +1,126 @@
+# Swapping a capability provider
+
+A capability provider is a **swappable implementation of an engine-owned
+contract**. The engine drives the capability and routes to whatever you supply.
+Today there are two: email (`EmailProvider`) and analytics (`PostHogService`).
+
+## The `EmailProvider` contract
+
+Defined in `@hogsend/core`, re-exported canonically from `@hogsend/engine`. It is
+a **dumb wire** — delivery + webhook parse/verify only. No tracking, DB,
+preference, or render logic lives here.
+
+```ts
+import type { EmailProvider } from "@hogsend/engine";
+
+interface EmailProvider {
+  send(options: SendEmailOptions): Promise<SendResult>;            // → { id }
+  sendBatch(emails: BatchEmailItem[]): Promise<{ results: SendResult[] }>;
+  // Verify a provider webhook signature and return the parsed event.
+  // Throws if the signature is missing/invalid.
+  verifyWebhook(opts: { payload: string; headers: Record<string, string> }): WebhookEvent;
+  // Parse an unsigned payload (trusted contexts/tests).
+  parseWebhook(payload: string): WebhookEvent;
+}
+```
+
+`SendEmailOptions`, `BatchEmailItem`, `SendResult`, and `WebhookEvent` are the
+contract's supporting types. **Import the contract types from `@hogsend/engine`**,
+**except `SendEmailOptions`**, which collides with the engine's higher-level send
+type — import that one from `@hogsend/core`:
+
+```ts
+import type { EmailProvider, SendResult, WebhookEvent } from "@hogsend/engine";
+import type { SendEmailOptions } from "@hogsend/core";
+```
+
+## A provider skeleton
+
+The reference implementation to copy is `createResendProvider`
+(`packages/plugin-resend/src/provider.ts`). A custom one mirrors it:
+
+```ts
+// src/lib/my-email-provider.ts — your content
+import type { SendEmailOptions } from "@hogsend/core";
+import type { EmailProvider, SendResult, WebhookEvent } from "@hogsend/engine";
+
+export function createMyEmailProvider(config: { apiKey: string; webhookSecret?: string }): EmailProvider {
+  return {
+    async send(options: SendEmailOptions): Promise<SendResult> {
+      // Call your vendor's SDK. The engine hands you HTML already rewritten for
+      // link/open tracking (options.html) on the tracked path; render
+      // options.react yourself (renderToHtml/renderToPlainText from
+      // @hogsend/email) only if your vendor can't take React.
+      const id = await myVendor.send({ from: options.from, to: options.to, subject: options.subject, html: options.html });
+      return { id };
+    },
+    async sendBatch(emails) {
+      const results = await Promise.all(emails.map((e) => this.send(e as never)));
+      return { results };
+    },
+    verifyWebhook({ payload, headers }): WebhookEvent {
+      if (!config.webhookSecret) throw new Error("webhookSecret required to verify webhooks");
+      // Verify with your vendor's scheme, then NORMALIZE into the engine's
+      // WebhookEvent shape ({ type: "email.delivered" | "email.bounced" | ... }).
+      return normalizeMyVendorEvent(verify(payload, headers, config.webhookSecret));
+    },
+    parseWebhook(payload): WebhookEvent {
+      return normalizeMyVendorEvent(JSON.parse(payload));
+    },
+  };
+}
+```
+
+## Wire it
+
+```ts
+// src/index.ts — your content
+import { createHogsendClient } from "@hogsend/engine";
+import { templates } from "./emails/registry.js";
+import { createMyEmailProvider } from "./lib/my-email-provider.js";
+
+const client = createHogsendClient({
+  journeys,
+  email: {
+    templates,                                            // REQUIRED, nested under email
+    provider: createMyEmailProvider({ apiKey: process.env.MY_API_KEY! }),
+  },
+  // analytics: createMyAnalytics(...),                   // top-level (engine uses it)
+});
+```
+
+Pass nothing under `email.provider` and the engine builds the **default Resend
+provider** from `RESEND_API_KEY` / `RESEND_WEBHOOK_SECRET`.
+
+## What comes along for free
+
+Everything except the wire. The engine's `createTrackedMailer` runs, in order:
+check preferences/suppression → frequency cap → resolve + render the template →
+write the `email_sends` row (status `queued`) → rewrite links + inject the open
+pixel → **then** `provider.send(...)` → update status. So a swapped provider
+keeps **all** of tracking, rendering, preferences, and the `email_sends`
+pipeline.
+
+## Inbound webhooks
+
+The engine owns one inbound email-webhook route: `POST /v1/webhooks/resend`. It
+reads the raw body + headers and calls your provider's `verifyWebhook`, then maps
+the normalized `WebhookEvent` to `email_sends` status updates and
+bounce/complaint → suppression. Your provider only has to verify + normalize; the
+DB effects are engine-owned.
+
+## Analytics (`PostHogService`)
+
+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.
+
+## Don't over-reach
+
+You are implementing a contract, not building a framework. There is no provider
+registry, no marketplace, and no `@hogsend/provider-*` packages — to support a
+new vendor you implement `EmailProvider` (or `PostHogService`) and pass it in.
+That's the whole story.