npm - @hogsend/cli - Versions diffs - 0.1.0 → 0.2.1 - Mend

@hogsend/cli 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (45) hide show

package/skills/hogsend-authoring-emails/references/email-components.md ADDED Viewed

@@ -0,0 +1,112 @@
+# Building the component — shared `_components`, props, preview/category, plaintext
+You write the `.tsx` with [react-email](https://react.email) primitives, but
+compose the shared chrome in `src/emails/_components/` instead of hand-rolling
+HTML. That keeps every email visually consistent and leaves the right slots open
+for the engine to inject tracking + unsubscribe.
+## The shared `_components`
+| Module | Exports | Role |
+|--------|---------|------|
+| `_components/layout.js` | `Layout` | The shell: `<Html>` + `<Head>` + `<Preview>` + `<Tailwind>`, the wordmark, one bordered white card, then the footer. |
+| `_components/ui.js` | `Eyebrow`, `Title`, `Body`, `Button`, `Callout`, `CodeBlock`, `Bullets`, `Divider` | Email-safe design-system primitives. |
+| `_components/logo.js` | `Logo` | Your wordmark above the card. |
+| `_components/footer.js` | `Footer` | Renders the `unsubscribeUrl` / `preferencesUrl` links (rendered by `Layout`, not directly by you). |
+`Layout`'s props are the only surface most templates touch:
+```ts
+interface LayoutProps {
+  preview: string;          // inbox snippet — required
+  eyebrow?: string;         // small uppercase label above the heading
+  unsubscribeUrl?: string;  // forwarded to <Footer>
+  preferencesUrl?: string;  // forwarded to <Footer>
+  children: ReactNode;
+}
+```
+A minimal template composes them like this:
+```tsx
+// biome-ignore lint/correctness/noUnusedImports: required for JSX runtime
+import React from "react";
+import { Layout } from "./_components/layout.js";
+import { Body, Bullets, Button, Callout, Divider, Title } from "./_components/ui.js";
+import type { TrialEndingEmailProps } from "./types.js";
+export default function TrialEndingEmail({
+  name = "there",
+  daysLeft = 3,
+  upgradeUrl = "https://app.example.com/billing",
+  unsubscribeUrl,
+}: TrialEndingEmailProps) {
+  return (
+    <Layout
+      preview={`${daysLeft} days left on your trial`}
+      eyebrow="Heads up"
+      unsubscribeUrl={unsubscribeUrl}
+    >
+      <Title>Your trial ends in {daysLeft} days</Title>
+      <Body>Hey {name}, here's what you keep when you upgrade:</Body>
+      <Bullets items={["Unlimited journeys", "Full event history", "Priority support"]} />
+      <Divider />
+      <Button href={upgradeUrl}>Upgrade now</Button>
+      <Callout tone="warn">Card on file is never charged automatically.</Callout>
+    </Layout>
+  );
+}
+```
+These files live in YOUR repo and are yours to edit — change the colors, add
+primitives, swap `Logo` for a hosted `<Img>`. Use ESM `.js` extensions on the
+relative imports (consumer convention), even though the files are `.tsx`.
+## Props typing
+Define the props interface in `src/emails/types.ts` and import it into the
+component. Two conventions:
+- **Default every prop in the destructure** (`name = "there"`) so previews and
+  admin catalogs render without real data, and a missing prop never produces
+  `undefined` in the body.
+- **Always accept an optional `unsubscribeUrl?: string`.** The engine injects it
+  on send so `Layout`/`Footer` can render the unsubscribe link — see
+  `tracking-and-unsubscribe.md`. Make it optional; direct render/preview calls
+  won't pass it.
+## Subject, preview, category — on the registry entry, not the component
+These live on the `TemplateDefinition` in `src/emails/registry.ts`, NOT inside
+the `.tsx`:
+```ts
+export interface TemplateDefinition<P = Record<string, unknown>> {
+  component: (props: P) => ReactElement;
+  defaultSubject: string;        // fallback subject when send() omits `subject`
+  category?: string;             // e.g. "transactional" | "journey"
+  preview?: (props: P) => string; // inbox snippet, computed from props
+  examples?: Partial<P>;         // sample props for admin previews only
+}
+```
+- **`defaultSubject`** is used when the send call doesn't pass an explicit
+  `subject`. Journeys usually pass their own subject; transactional one-offs lean
+  on the default.
+- **`category`** drives frequency capping. The engine's frequency cap exempts
+  `"transactional"` by default — mark genuine transactional mail (receipts,
+  password resets) `"transactional"` and marketing/lifecycle mail `"journey"` so
+  caps apply correctly.
+- **`preview`** sets the snippet most inboxes show next to the subject. Note the
+  `Layout`'s own `preview` prop renders react-email's hidden `<Preview>` text in
+  the HTML; the registry `preview` is the value surfaced to admin/preview tooling
+  via `getPreviewText`. Keep them consistent.
+## Plaintext
+You do not author a separate plaintext file. The engine renders both halves from
+the same component: `renderToHtml(element)` and `renderToPlainText(element)`
+(react-email's `render(element, { plainText: true })`). Write the component once;
+keep links as real `<a href>` / react-email `Button`/`Link` so the plaintext
+extractor produces readable URLs. See `preview-and-render.md` for the render
+machinery.

package/skills/hogsend-authoring-emails/references/preview-and-render.md ADDED Viewed

@@ -0,0 +1,116 @@
+# Render & preview — render helpers, the registry, how the consumer wires it
+`@hogsend/email` is render machinery only. It exposes the render functions, the
+registry helpers, and the open `TemplateRegistryMap` type — but no concrete
+templates. Your app supplies the registry; the engine threads it through at send
+and render time.
+## The render helpers
+```ts
+import { renderToHtml, renderToPlainText } from "@hogsend/email";
+import type { ReactElement } from "react";
+// Both wrap react-email's render():
+const html = await renderToHtml(element);        // render(element)
+const text = await renderToPlainText(element);   // render(element, { plainText: true })
+```
+You rarely call these directly — the engine's mailer does it for you (HTML + text
+from one component). They're useful for snapshot tests of a `.tsx`.
+## The registry helpers
+`@hogsend/email` resolves a template KEY against a `TemplateRegistry` you pass
+in:
+```ts
+import { getTemplate, getPreviewText, createRegistry } from "@hogsend/email";
+// Resolve key → { element, subject, category }
+const { element, subject, category } = getTemplate({
+  key: "activation/welcome",
+  props: { name: "Ada", dashboardUrl: "https://app.example.com" },
+  registry, // your src/emails/registry.ts `templates`
+});
+// Compute the inbox snippet from the entry's `preview(props)`
+const snippet = getPreviewText({ key: "activation/welcome", props, registry });
+```
+`createRegistry(base, overrides)` shallow-merges a partial over a base registry —
+handy if you ever inherit a starter set and tweak a few keys:
+```ts
+export const templates = createRegistry(starterTemplates, {
+  "activation/welcome": { ...starterTemplates["activation/welcome"], category: "journey" },
+});
+```
+## How the consumer registry is built and threaded
+You build the registry once in `src/emails/registry.ts` and re-export it from
+`src/emails/index.ts`:
+```ts
+// src/emails/registry.ts
+import type { TemplateRegistry } from "@hogsend/email";
+import WelcomeEmail from "./welcome.js";
+import ActivationNudgeEmail from "./activation-nudge.js";
+export const templates: TemplateRegistry = {
+  "activation/welcome": {
+    component: WelcomeEmail,
+    defaultSubject: "Welcome aboard",
+    category: "transactional",
+    preview: (props) => `Welcome, ${props.name}!`,
+  },
+  "activation/nudge": {
+    component: ActivationNudgeEmail,
+    defaultSubject: "You haven't tried the key feature yet",
+    category: "journey",
+    preview: (props) => `${props.name}, you're missing out`,
+  },
+};
+```
+```ts
+// src/emails/index.ts
+export { templates } from "./registry.js";
+export type { ActivationNudgeEmailProps, WelcomeEmailProps } from "./types.js";
+```
+The wiring into the engine already exists in `src/index.ts` — you don't add it,
+but this is what it looks like:
+```ts
+// src/index.ts (already present in the scaffold)
+import { createHogsendClient } from "@hogsend/engine";
+import { templates } from "./emails/index.js";
+const client = createHogsendClient({ journeys, buckets, email: { templates } });
+```
+`createHogsendClient` stores your `templates` on the email-service config; the
+engine's `createTrackedMailer` reads `config.templates` and passes it to
+`getTemplate({ key, props, registry })` on every `send` and `render`. That is the
+whole reason the engine never bakes in business templates — yours flow in here.
+## Previewing a template
+For an at-a-glance HTML preview during development, render a component to a file:
+```ts
+// scripts/preview.ts (your repo, run with tsx)
+import { renderToHtml } from "@hogsend/email";
+import { writeFileSync } from "node:fs";
+import { templates } from "../src/emails/index.js";
+const { component } = templates["activation/welcome"];
+const html = await renderToHtml(component({ name: "Ada" }));
+writeFileSync("preview.html", html);
+```
+Or run react-email's own dev server if you keep one configured. To inspect real
+sends (open/click/bounce rates per template) against a running instance, use the
+**hogsend-cli** skill rather than rendering locally.

package/skills/hogsend-authoring-emails/references/template-four-file-contract.md ADDED Viewed

@@ -0,0 +1,134 @@
+# The template contract — five touch points that must agree
+A sendable, type-checked template is one string (`"activation/welcome"`) wired
+across five files. Get any of them out of sync and you get a compile error at
+the `send` call site — this is the single most common email-authoring bug. The
+checklist:
+| # | File | What it declares | Keyed on |
+|---|------|------------------|----------|
+| 1 | `src/emails/<name>.tsx` | the react-email component (default export) | imported by (3) |
+| 2 | `src/emails/types.ts` | the `Props` interface | imported by (1) + (4) |
+| 3 | `src/emails/registry.ts` | `templates[key]` → component + subject + category | **the key** |
+| 4 | `src/emails/templates.d.ts` | augments `TemplateRegistryMap` so `key → Props` | **the key** + Props |
+| 5 | `src/journeys/constants/index.ts` | `Templates.*` constant journeys send | **the key** |
+The **key** in (3), (4), and (5) must be byte-identical. The **Props** in (2)
+must match what (1) destructures and what (4) maps the key to.
+## Walk through, file by file
+### 1. The component — `src/emails/order-shipped.tsx`
+```tsx
+// biome-ignore lint/correctness/noUnusedImports: required for JSX runtime
+import React from "react";
+import { Layout } from "./_components/layout.js";
+import { Body, Button, Title } from "./_components/ui.js";
+import type { OrderShippedEmailProps } from "./types.js";
+export default function OrderShippedEmail({
+  name = "there",
+  trackingUrl = "https://example.com/track",
+  unsubscribeUrl,
+}: OrderShippedEmailProps) {
+  return (
+    <Layout
+      preview={`Your order is on its way, ${name}`}
+      eyebrow="Shipped"
+      unsubscribeUrl={unsubscribeUrl}
+    >
+      <Title>Your order is on its way</Title>
+      <Body>Hey {name}, we just handed it to the carrier.</Body>
+      <Button href={trackingUrl}>Track your package</Button>
+    </Layout>
+  );
+}
+```
+### 2. The props — `src/emails/types.ts`
+```ts
+export interface OrderShippedEmailProps {
+  name: string;
+  trackingUrl?: string;
+  // Engine-injected on send (see tracking-and-unsubscribe.md) — accept it so
+  // the Layout/Footer can render an unsubscribe link. Always optional.
+  unsubscribeUrl?: string;
+}
+```
+### 3. The registry entry — `src/emails/registry.ts`
+```ts
+import type { TemplateRegistry } from "@hogsend/email";
+import OrderShippedEmail from "./order-shipped.js";
+// ...other imports
+export const templates: TemplateRegistry = {
+  // ...other entries
+  "fulfilment/order-shipped": {
+    component: OrderShippedEmail,
+    defaultSubject: "Your order is on its way",
+    category: "transactional",
+    preview: (props) => `On its way, ${props.name}`,
+  },
+};
+```
+### 4. The augmentation — `src/emails/templates.d.ts`
+```ts
+import type { OrderShippedEmailProps } from "./types.js";
+declare module "@hogsend/email" {
+  interface TemplateRegistryMap {
+    // ...other keys
+    "fulfilment/order-shipped": OrderShippedEmailProps;
+  }
+}
+```
+`@hogsend/email` ships an **empty** `TemplateRegistryMap`. This `declare module`
+block is the only thing that teaches the type system your keys → props, which is
+what makes `emailService.send({ template, props })` type-check.
+### 5. The constant — `src/journeys/constants/index.ts`
+```ts
+export const Templates = {
+  // ...existing keys
+  ORDER_SHIPPED: "fulfilment/order-shipped",
+} as const;
+```
+Journeys send `template: Templates.ORDER_SHIPPED`, never a raw string, so a typo
+is a compile error rather than a silently-missing template at runtime.
+## The #1 type-error trap
+The send site resolves props from the registry map:
+```ts
+// engine signature (do not edit): send<K extends TemplateName>(
+//   options: { template: K; props: TemplateRegistryMap[K]; ... })
+await container.emailService.send({
+  template: "fulfilment/order-shipped",
+  props: { name: "Ada", trackingUrl: "https://…" }, // typed by templates.d.ts
+  to: user.email,
+});
+```
+If you added the registry entry (3) but forgot the augmentation (4), `TemplateName`
+won't include your key and `template:` rejects the string. If (2) and (4)
+disagree on Props, `props:` rejects the object. **When you see "is not assignable
+to TemplateName" or a props mismatch, re-check 2/3/4/5 against each other.**
+## Rename / delete checklist
+Renaming `"a/old"` → `"a/new"`: change the literal in (3), (4), and (5) together;
+no `.tsx`/`types.ts` change needed if the component/props are unchanged. Deleting
+a template: remove its entry from (3), its line from (4), its `Templates.*`
+constant from (5) if present, then delete the `.tsx` and its `Props` from (2).
+Leaving a key in (4) with no (3) entry, or vice-versa, will surface as a type or
+runtime error.

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

@@ -0,0 +1,127 @@
+# Tracking & unsubscribe — what happens automatically on every send
+This is co-located with email authoring on purpose: link-click tracking, open
+tracking, preference checks, and unsubscribe are **automatic on every send**.
+The engine's `createTrackedMailer` owns the whole pipeline; the email provider
+(`createResendProvider`) is just the dumb wire. You author the `.tsx`; the engine
+does the rest. You should NOT call any of these helpers yourself — this reference
+explains what runs so you author components that leave room for it.
+## The send pipeline (engine-owned, runs on `send` / `sendEmail`)
+```
+emailService.send({ template, props, to, ... })   // or sendEmail({...}) in a journey
+        │
+        ▼  createTrackedMailer.send → sendTrackedEmail (the DB-backed path)
+  1. preference / suppression check, then frequency cap
+        (both skipped when skipPreferenceCheck is set)
+  2. getTemplate(key, props, registry) → resolve element + subject + category
+  3. insert email_sends row  → gives the send a stable emailSendId (status "queued")
+  4. renderToHtml(element), then prepareTrackedHtml(html, emailSendId, baseUrl, db):
+        • rewriteLinks()    — every <a href="https?://…"> → /v1/t/c/:linkId
+        • injectOpenPixel() — <img src="/v1/t/o/:emailSendId"> before </body>
+        (only when baseUrl + prepareTrackedHtml are present; else send the raw react element)
+  5. provider.send(...)     — Resend gets the already-rewritten HTML
+  6. update email_sends → resendId + status "sent" (or "failed" on throw)
+```
+Tracking comes along regardless of which provider you supply, because steps 2–4
+live in the engine, not the provider. The tracking domain is `options.baseUrl`
+(threaded from `config.baseUrl`, i.e. `API_PUBLIC_URL`).
+## Link-click tracking
+`rewriteLinks` (engine `lib/tracking.ts`) scans the rendered HTML for
+`href="https://…"`, deduplicates the URLs, bulk-inserts one `tracked_links` row
+per unique URL, then single-pass replaces each href with
+`{API_PUBLIC_URL}/v1/t/c/{linkId}`. At click time:
+- `GET /v1/t/c/:id` records a `link_clicks` row (IP + user-agent), increments
+  `tracked_links.click_count`, sets `email_sends.clicked_at` (first click only,
+  `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.
+Authoring implication: use real `<a href>` / react-email `Button`/`Link` with
+absolute `https://` URLs and they're tracked automatically. Non-HTTP links
+(`mailto:`, `tel:`) are left alone — the regex only matches `https?://`.
+## Open tracking
+`injectOpenPixel` appends a 1×1 GIF `<img src="{API_PUBLIC_URL}/v1/t/o/{emailSendId}">`
+just before `</body>` (so always compose inside `Layout`, which emits a proper
+`<body>`). At open time:
+- `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`).
+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
+your `Events` constants and check `ctx.history.hasEvent({ event })` to branch on
+engagement — see the **hogsend-authoring-journeys** skill.
+## Preference / suppression check
+Before sending, `sendTrackedEmail` checks `email_preferences` for the recipient.
+If the user is unsubscribed/suppressed/category-unsubscribed, the send is skipped
+and the result `status` reflects it (`"unsubscribed"` / `"suppressed"` /
+`"skipped"`) — no provider call. Genuinely transactional mail that must always go
+out can pass `skipPreferenceCheck: true`. Frequency caps also short-circuit here
+(`status: "skipped", reason: "frequency_capped"`); `category: "transactional"` is
+exempt from caps by default.
+## Unsubscribe — token, URL, and the footer slot
+The unsubscribe link is a signed, expiring token, not a DB lookup. The engine's
+`sendEmail` builds it for journey sends:
+```ts
+import { generateUnsubscribeUrl } from "@hogsend/email";
+// engine builds this for you when API_PUBLIC_URL + BETTER_AUTH_SECRET are set:
+const unsubscribeUrl = generateUnsubscribeUrl({
+  baseUrl: process.env.API_PUBLIC_URL,
+  secret: process.env.BETTER_AUTH_SECRET,
+  externalId: userId,
+  email: to,
+});
+// → {baseUrl}/v1/email/unsubscribe?token=<base64url payload>.<hmac-sha256 sig>
+```
+It is injected into your template as the `unsubscribeUrl` prop AND set as the
+`List-Unsubscribe` + `List-Unsubscribe-Post` headers (one-click unsubscribe). All
+you do as the author is **accept `unsubscribeUrl?: string` in your props and pass
+it to `Layout`** (which forwards it to `Footer`) — that's the slot:
+```tsx
+export default function MyEmail({ name = "there", unsubscribeUrl }: MyEmailProps) {
+  return (
+    <Layout preview={`Hi ${name}`} unsubscribeUrl={unsubscribeUrl}>
+      {/* … */}
+    </Layout>
+  );
+}
+```
+There is a matching `generatePreferenceCenterUrl(...)` →
+`{baseUrl}/v1/email/preferences?token=…` (action `"manage"`) for a full
+preference center link; pass it as `preferencesUrl` to `Layout` the same way.
+## Why these links aren't click-tracked
+`rewriteLinks` skips any URL containing `/v1/email/unsubscribe` or
+`/v1/email/preferences` (the `SKIP_PATTERNS`), so unsubscribe and preference
+links go straight through un-rewritten — an unsubscribe must never bounce through
+the click endpoint. You don't need to do anything for this; it's handled.
+## What you do NOT do
+- Don't call `prepareTrackedHtml`, `rewriteLinks`, or `injectOpenPixel` — the
+  mailer calls them.
+- Don't call `generateUnsubscribeUrl` in a template — the engine injects the URL.
+- Don't hand-roll an open pixel or rewrite links in your `.tsx`.
+Author the component; the engine guarantees tracking + unsubscribe on send.
+Full system docs: `docs/tracking.md`.

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

@@ -0,0 +1,88 @@
+---
+name: hogsend-authoring-journeys
+description: Use when adding or editing a lifecycle journey in src/journeys/ — wiring a defineJourney() trigger/entryLimit/exitOn/suppress, writing the run(user, ctx) control flow, durable sleeps, branching on history/engagement, sending email from a journey, and the register-in-index + thread-into-client/worker ritual.
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+# Authoring Hogsend journeys
+A journey is a code-first lifecycle flow. You declare a `defineJourney({ meta,
+run })` in `src/journeys/`: `meta` says who enters and when they exit, and
+`run(user, ctx)` is plain TypeScript control flow — send email, durably sleep,
+branch on history. Each journey compiles to its own Hatchet durable task, so the
+worker can restart mid-flow and resume exactly where it left off.
+You are editing a **scaffolded consumer app** (content only). You import from
+`@hogsend/engine` and `@hogsend/core`; you never touch engine internals.
+## Anatomy of a journey
+```ts
+import { days, hours } from "@hogsend/core";
+import { defineJourney, sendEmail } from "@hogsend/engine";
+import { Events, Templates } from "./constants/index.js";
+export const welcome = defineJourney({
+  meta: {
+    id: "welcome",                               // stable, unique id
+    name: "Welcome Series",
+    enabled: true,
+    trigger: { event: Events.USER_CREATED },     // event that enrolls a user
+    entryLimit: "once",                          // re-entry policy (+ entryPeriod)
+    suppress: hours(12),                         // required declared cool-down field
+    exitOn: [{ event: Events.USER_DELETED }],    // events that pull users out
+  },
+  run: async (user, ctx) => {
+    await sendEmail({                            // STANDALONE import, not ctx.*
+      to: user.email,
+      userId: user.id,
+      journeyStateId: user.stateId,
+      template: Templates.ACTIVATION_WELCOME,
+      subject: "Welcome — let's get you set up",
+      journeyName: user.journeyName,
+    });
+    await ctx.sleep({ duration: days(2), label: "post-welcome" });
+    const { found } = await ctx.history.hasEvent({
+      userId: user.id,
+      event: Events.FEATURE_USED,
+    });
+    if (!found) {
+      await sendEmail({ /* nudge */ });
+    }
+  },
+});
+```
+## 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`.
+- **Duration helpers** `days()` / `hours()` / `minutes()` from `@hogsend/core`
+  (also re-exported by `@hogsend/engine`) — never magic strings.
+- **`user`** carries `id`, `email`, `properties`, `stateId`, `journeyId`,
+  `journeyName` — pass `user.stateId` to `sendEmail` so the send is attributed.
+- **Constants** `Events` / `Templates` live in your `src/journeys/constants/`.
+  `Templates` keys must match a key in `src/emails/` registry.
+## Task playbooks — load the matching reference
+- **Shape `meta` (trigger, entryLimit, exitOn, suppress) + understand the
+  enrollment gates and state transitions** → `references/journey-meta.md`
+- **The full `ctx` primitive API and what is deliberately NOT on it** →
+  `references/journey-context.md`
+- **Send an email from inside `run`** → `references/sending-email-from-a-journey.md`
+- **Branch after a sleep on engagement / history, idempotently** →
+  `references/branch-on-engagement.md`
+- **Register a new journey: export + thread into client/worker + ENABLED_JOURNEYS**
+  → `references/register-a-journey.md`
+For `trigger.where` / `exitOn[].where` property conditions and the duration
+helpers in depth, see the **hogsend-conditions** skill. To verify a journey runs
+against a live instance (enroll a test user, watch it complete), see the
+**hogsend-cli** skill.