@hogsend/cli 0.11.0 → 0.12.0

package/skills/hogsend-integrate/references/verification.md

@@ -0,0 +1,86 @@
+# Verification — prove the pipe works with the `hogsend` CLI
+
+After wiring, verify end-to-end with the `hogsend` CLI (ships with
+`@hogsend/cli`; run via `pnpm dlx @hogsend/cli` or a global install). It reads
+the same env names the host app uses:
+
+- **Base URL:** `--url <baseUrl>` > `HOGSEND_API_URL` > default
+  `http://localhost:3002`.
+- **Data key** (writes — `events send`): `--data-key` > `HOGSEND_DATA_KEY` >
+  `HOGSEND_API_KEY`. The ingest key the host app already has works here.
+- **Admin key** (reads — `events <userId>`, `contacts`, `stats`):
+  `--admin-key` > `HOGSEND_ADMIN_KEY` > `ADMIN_API_KEY`. Ask the user for one
+  if the host env only carries the ingest key.
+
+Always pass `--json` when parsing output programmatically.
+
+## 0. Is the instance reachable?
+
+```bash
+hogsend doctor --json
+```
+
+Expect verdict `ok` (unauthenticated `/v1/health` — needs no key). If
+`unreachable`, fix `HOGSEND_API_URL` before debugging anything else.
+
+## 1. Fire a synthetic event through the data plane
+
+```bash
+TEST_ID="test_agent_$(date +%s)"
+hogsend events send signup --user-id "$TEST_ID" --prop source=integration-test --json
+```
+
+Expected output (202 path):
+
+```json
+{ "stored": true, "exits": [] }
+```
+
+`stored: true` = the event row is durably written. This proves base URL + key +
+scope are right, independent of the host app's code.
+
+## 2. Confirm it landed (read path, admin key)
+
+```bash
+hogsend events "$TEST_ID" --json
+```
+
+Expect one `signup` event with `properties.source = "integration-test"`. Also
+useful:
+
+```bash
+hogsend contacts get "$TEST_ID" --json      # contact upserted by ingestion
+hogsend contacts timeline "$TEST_ID" --json # merged event/email/journey view
+```
+
+## 3. Exercise the REAL seam
+
+Trigger the actual code path you wired — sign a test user up, or replay a
+provider webhook (`stripe trigger checkout.session.completed` with the Stripe
+CLI, Clerk's "Send Example" button). Then re-run step 2 with the real user's
+id/email and confirm the event + contact appear.
+
+## 4. Did anything react?
+
+If journeys are defined on the Hogsend side, the send result's `exits` array
+and `hogsend journeys list --json` (enabled journeys + state counts) show
+whether the event enrolled/exited anyone. No journeys reacting is fine at this
+stage — wiring the host comes first; authoring journeys is the
+hogsend-authoring-journeys skill.
+
+## Triage table
+
+| Symptom | Likely cause |
+|---|---|
+| `doctor` verdict `unreachable` | wrong `HOGSEND_API_URL`, instance down |
+| 401 on `events send` | key lacks the `ingest` scope, or wrong key entirely |
+| 401 on `events <userId>` | read path needs the ADMIN key, not the ingest key |
+| `stored: false` | deduped — you re-sent an `idempotencyKey` already used |
+| send ok, but nothing from the real seam | host code path not firing — log inside the seam, check the server actually restarted with new env |
+| `RateLimitError` in app logs | back off `retryAfter` seconds; batch less aggressively |
+
+## Clean up
+
+Synthetic `test_agent_*` contacts can be removed via the SDK
+(`hogsend.contacts.delete({ userId: TEST_ID })`) or left — they're inert
+without an email address.

package/skills/hogsend-migrate/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: hogsend-migrate
+description: Use when migrating a product OFF Loops, Customer.io, or Resend Broadcasts/Audiences onto Hogsend — auditing the existing email-SaaS integration (SDK calls in code + GUI-side workflows/campaigns/segments/templates), mapping each source concept to its Hogsend equivalent (contacts.upsert, events.send, defineJourney journeys, four-file react-email templates, defineList lists, buckets, campaigns, webhook sources), then executing an incremental dual-write → verify → switch → remove cutover that preserves unsubscribes/suppression. NOT for a greenfield integration with no incumbent (that is hogsend-integrate) and NOT for authoring mechanics themselves (delegate to the hogsend-authoring-* skills).
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Migrate to Hogsend (from Loops / Customer.io / Resend Broadcasts)
+
+A migration has two halves: the **code half** (SDK calls you can grep) and the
+**GUI half** (workflows, campaigns, segments, templates that live only in the
+source platform's dashboard). This skill audits both, maps every source concept
+to its Hogsend equivalent, and runs an incremental cutover — never a big-bang
+switch.
+
+Two codebases are in play. The **host product** keeps (rewired) SDK calls — work
+there follows the **hogsend-integrate** patterns. The **Hogsend app** (a
+scaffolded `create-hogsend` project) is where journeys, templates, and lists are
+authored — mechanics delegate to the **hogsend-authoring-\*** skills.
+
+## Non-negotiable safety rules (read before anything else)
+
+1. **Import unsubscribes BEFORE any Hogsend send.** A migration that emails one
+   unsubscribed person is a failed migration (and a legal problem). Export the
+   source platform's suppression/unsubscribe list first and apply it (cutover
+   reference shows how). Never bulk-unsubscribe everyone "to be safe" either —
+   polarity matters.
+2. **Dual-write before switching.** Old and new pipelines run side by side
+   until verified. Hogsend writes are idempotent-friendly (`idempotencyKey`),
+   so dual-writing is cheap.
+3. **One sender of each email at a time.** When a Hogsend journey goes live,
+   pause the corresponding source-platform workflow in the same change window —
+   duplicated sends erode trust faster than missed ones.
+
+## Step 1 — audit what exists
+
+**Code half** — grep the host product (full per-platform greps + before/after
+snippets in the matching reference):
+
+| Platform | Grep for |
+|---|---|
+| Loops | `loops` dep (`loops` / `@loops/*`), `sendEvent`, `updateContact`, `sendTransactionalEmail`, `transactionalId` |
+| Customer.io | `customerio-node` dep, `cio.identify`, `cio.track`, `trackAnonymous`, `triggerBroadcast`, in-app `_cio` snippet |
+| Resend Broadcasts | `resend.broadcasts.`, `resend.audiences.`, `resend.contacts.` — DISTINCT from plain `resend.emails.send` (transactional, may stay) |
+
+**GUI half** — not in the codebase; ask the user to export or screenshot from
+the source dashboard:
+
+- workflows/campaigns (triggers, delays, branches, exit rules)
+- segments/audiences (definitions, member counts)
+- templates (HTML/content + which are transactional vs marketing)
+- the suppression/unsubscribe list (CRITICAL — rule 1)
+- API keys' event names actually flowing (last 30 days), to scope the event
+  vocabulary
+
+Output of this step: an inventory table (source asset → type → destination in
+Hogsend → owner) the user signs off on.
+
+## Step 2 — map concepts (per-platform tables)
+
+The shared shape — almost everything lands in one of seven Hogsend concepts:
+
+| Source concept (any platform) | Hogsend equivalent |
+|---|---|
+| Contact / person / audience member | contact — `hs.contacts.upsert` (`@hogsend/client`) |
+| Event / track call | `hs.events.send` (`eventProperties` vs `contactProperties` split) |
+| Workflow / loop / campaign-with-delays | journey — `defineJourney()` in the Hogsend app's `src/journeys/` |
+| Transactional email | `hs.emails.send` + a four-file react-email template in `src/emails/` |
+| Mailing list / audience / topic | list — `defineList()` (polarity via `defaultOptIn`) |
+| Behavioral segment | bucket — `defineBucket()` (criteria-driven, real-time) |
+| One-off broadcast/newsletter | campaign — `hs.campaigns.send` / `hogsend campaigns send` (targets a list or bucket) |
+
+Platform-specific tables, audit greps, and rewrite examples:
+
+- **Loops** → `references/loops-mapping.md`
+- **Customer.io** → `references/customerio-mapping.md`
+- **Resend Broadcasts/Audiences** → `references/resend-broadcasts-mapping.md`
+  (special case: Resend can REMAIN the delivery wire — Hogsend's default
+  `EmailProvider` is Resend, so this migration replaces the orchestration
+  layer, not necessarily the sending infrastructure)
+
+## Step 3 — generate the Hogsend setup
+
+Work in the Hogsend app, one source asset at a time. This skill decides WHAT to
+build; the authoring skills own HOW:
+
+- **Each workflow/campaign-with-logic → a `defineJourney()`** in
+  `src/journeys/`. Translate: entry trigger → `trigger: { event, where? }`;
+  re-entry rules → `entryLimit: "once" | "once_per_period" | "unlimited"`;
+  goal/exit rules → `exitOn`; delays → `await ctx.sleep({ duration: days(n) })`;
+  branches → plain TypeScript `if` on `ctx.history.hasEvent(...)`. Mechanics +
+  registration ritual → **hogsend-authoring-journeys**; condition syntax →
+  **hogsend-conditions**.
+- **Each template → the four-file contract** (`src/emails/<name>.tsx` +
+  `types.ts` props + `registry.ts` entry + `templates.d.ts` augmentation).
+  Port content into react-email components; subjects/preview/category live on
+  the registry entry. → **hogsend-authoring-emails**.
+- **Each list/audience/topic → `defineList({ id, name, defaultOptIn })`** in
+  `src/lists/`. Get `defaultOptIn` right: a newsletter people subscribed to is
+  opt-in (`defaultOptIn: false`); product/account notices are typically opt-out
+  (`defaultOptIn: true`). → **hogsend-authoring-lists**.
+- **Each behavioral segment → a bucket** (criteria tree over events/properties)
+  when it gates journeys or campaigns. → **hogsend-authoring-buckets**.
+- **Inbound webhooks worth keeping** (the source platform was receiving
+  provider webhooks that should now hit Hogsend) → `defineWebhookSource()` or
+  the built-in Clerk/Supabase/Stripe/Segment presets. →
+  **hogsend-webhooks-and-workflows**.
+- **Outbound syncs** (source platform pushed data to other tools) → webhook
+  endpoints / keyed destinations (`hs.webhooks.create` with `kind`). →
+  **hogsend-authoring-destinations**.
+
+Then rewire the host product's SDK calls to `@hogsend/client` equivalents
+(per-platform before/after in the references; client patterns in
+**hogsend-client-sdk** / **hogsend-integrate**).
+
+## Step 4 — incremental cutover (dual-write → verify → switch → remove)
+
+The full checklist with commands is `references/cutover-checklist.md`. The
+stages:
+
+1. **Dual-write.** Import contacts + suppression state (suppression FIRST).
+   Add Hogsend calls BESIDE the existing SDK calls — same handlers, both fire.
+   Journeys are authored but disabled (`enabled: false` or left out of
+   `ENABLED_JOURNEYS`). Nothing user-visible changes.
+2. **Verify.** Compare event volume between platforms over a few days
+   (`hogsend stats --json`, `hogsend events <userId> --json` spot checks).
+   Enable each journey for a seed/test contact, walk the full flow, diff
+   rendered templates against the originals (`hogsend emails send <template>
+   --to you@…`).
+3. **Switch.** Per flow: enable the Hogsend journey
+   (`hogsend journeys enable <id>` or `ENABLED_JOURNEYS`) and pause the source
+   workflow in the same window. Flip transactional sends to `hs.emails.send`.
+   Run broadcasts as Hogsend campaigns.
+4. **Remove.** After a clean soak (1-2 send cycles), delete the old SDK calls,
+   uninstall the dep, revoke the old API keys, export a final archive from the
+   source platform, then close the account.
+
+## Task playbooks — load the matching reference
+
+- **Migrating from Loops** → `references/loops-mapping.md`
+- **Migrating from Customer.io** → `references/customerio-mapping.md`
+- **Migrating from Resend Broadcasts/Audiences** →
+  `references/resend-broadcasts-mapping.md`
+- **Executing the cutover (imports, verification commands, switch order,
+  rollback)** → `references/cutover-checklist.md`

package/skills/hogsend-migrate/references/customerio-mapping.md

@@ -0,0 +1,93 @@
+# Customer.io → Hogsend mapping
+
+Audit greps, the concept table, and before/after rewrites for a codebase using
+Customer.io. Customer.io's API surface varies by SDK (`customerio-node` Track
+vs App API clients) and product tier — treat the left-hand column as "look
+for", and verify against the project's actual calls.
+
+## Audit greps (code half)
+
+```bash
+grep -rn "customerio" package.json            # commonly `customerio-node`
+grep -rn "TrackClient\|APIClient\|cio\." src/
+grep -rn "identify\|\.track(\|trackAnonymous\|triggerBroadcast" src/
+grep -rn "_cio" src/ public/                  # in-app/browser snippet
+grep -rn "CUSTOMERIO\|CIO_" . --include="*.env*"
+```
+
+GUI half (export/screenshot from the Customer.io dashboard): campaigns (entry
+trigger, filters, delays, branches, goal/exit settings), segments (definitions
++ whether data-driven or manual), broadcasts/newsletters, transactional
+messages, subscription preferences/topics, and the suppression list.
+
+## Concept mapping
+
+| Customer.io concept | Hogsend equivalent | Notes |
+|---|---|---|
+| Person + attributes (`identify`) | contact — `hs.contacts.upsert({ userId, email?, properties })` | CIO is id-keyed; Hogsend takes `userId` and/or `email`. Attributes → `properties` |
+| `track(id, event, data)` | `hs.events.send({ userId, name, eventProperties, contactProperties? })` | CIO has ONE data bag; Hogsend has two. Sort each field: per-occurrence → `eventProperties`, durable → `contactProperties` |
+| Anonymous events (`trackAnonymous`) | no direct equivalent | Hogsend writes need an identity (`email`/`userId`). Defer anonymous tracking to your product-analytics tool; ingest on identification |
+| Campaign (triggered workflow) | journey — `defineJourney()` | Trigger → `trigger.event` (+ `where` for filters); frequency settings → `entryLimit`; goal/exit → `exitOn`; delays → `ctx.sleep`; time-windows → `ctx.when`; "wait until event" → `ctx.waitForEvent` |
+| Segment (data-driven) | bucket — `defineBucket()` criteria tree | Real-time membership; journeys can trigger on `bucket.entered`/`bucket.left` transitions → hogsend-authoring-buckets |
+| Segment (manual) | list — `defineList()` + explicit membership writes | Manual segments are membership-by-assignment, which is what lists are |
+| Broadcast / newsletter | campaign — `hs.campaigns.send({ list \| bucket, template })` | API-triggered broadcasts (`triggerBroadcast`) also map here |
+| Transactional message | `hs.emails.send({ to \| userId, template, props })` | Each transactional message id becomes a template key in `src/emails/` |
+| Subscription preferences / topics | lists (`defineList`) + the built-in preference center | Topic opt-ins → `defaultOptIn: false`; suppression import → `cutover-checklist.md` |
+| Reporting webhooks (CIO → your systems) | webhook endpoints / keyed destinations — `hs.webhooks.create({ url, eventTypes, kind?, config? })` | Hogsend emits `email.*`, `contact.*`, `journey.completed`, `bucket.*` on a durable signed spine |
+
+## Before / after
+
+Identify + track (host product code):
+
+```ts
+// BEFORE (customerio-node Track API — shape varies by version)
+cio.identify("u_1", { email: "ada@example.com", plan: "pro" });
+cio.track("u_1", { name: "subscription_started", data: { plan: "pro", amount: 49 } });
+
+// AFTER (@hogsend/client)
+import { hogsend } from "../lib/hogsend.js";
+
+await hogsend.contacts.upsert({
+  userId: "u_1",
+  email: "ada@example.com",
+  properties: { plan: "pro" },
+});
+await hogsend.events.send({
+  userId: "u_1",
+  name: "subscription_started",
+  eventProperties: { plan: "pro", amount: 49 }, // facts about THIS event
+  contactProperties: { plan: "pro" },           // durable fact on the person
+});
+```
+
+Campaign → journey translation guide (authored in the Hogsend app —
+mechanics → hogsend-authoring-journeys, conditions → hogsend-conditions):
+
+| Campaign builder block | Journey code |
+|---|---|
+| "Person enters when event X" | `trigger: { event: "X" }` |
+| "…and attribute filter" | `trigger: { where: { type: "property", … } }` |
+| "Can enter once / every N days" | `entryLimit: "once"` / `"once_per_period"` |
+| "Exit when goal event Y" | `exitOn: [{ event: "Y" }]` |
+| "Wait 3 days" | `await ctx.sleep({ duration: days(3) })` |
+| "Wait until Tuesday 9am (their tz)" | `ctx.when` scheduler + `ctx.sleepUntil` |
+| "Wait up to 7 days for event Z" | `await ctx.waitForEvent({ event: "Z", timeout: days(7) })` |
+| "True/false branch on behavior" | `if` on `ctx.history.hasEvent(...)` / `ctx.history.email(...)` |
+| "Send email" | `await sendEmail({ …, journeyStateId: user.stateId })` |
+
+## Customer.io-specific gotchas
+
+- **One data bag → two.** The single `data` object on `cio.track` must be
+  consciously split into `eventProperties` vs `contactProperties`. Default
+  per-field to `eventProperties`; promote to `contactProperties` only what a
+  later check on the person should read.
+- **Anonymous → identified flows have no Hogsend equivalent** — plan to start
+  lifecycle tracking at identification (signup), which is where journeys
+  almost always start anyway.
+- **In-app `_cio` snippet** (browser tracking) is product analytics, not
+  lifecycle orchestration. Don't port it to Hogsend; if the team uses PostHog,
+  that's its home, and Hogsend can consume those signals later.
+- **Liquid templates** don't transplant. Re-author as react-email with typed
+  props; conditional content blocks become plain JSX conditionals.
+- **Campaign analytics history stays behind.** Export CSVs for the record;
+  Hogsend metrics start at cutover.

package/skills/hogsend-migrate/references/cutover-checklist.md

@@ -0,0 +1,136 @@
+# Cutover checklist — dual-write → verify → switch → remove
+
+The execution playbook. Work flow-by-flow, never big-bang. Keys: data-plane
+writes use the ingest key (`HOGSEND_API_KEY`); admin reads/writes use an admin
+key (`HOGSEND_ADMIN_KEY` / `ADMIN_API_KEY`). `--json` on every CLI call you
+parse.
+
+## Stage 0 — imports (BEFORE anything sends)
+
+### 0a. Contacts
+
+Bulk path — the admin import endpoint (admin key):
+
+```
+POST /v1/admin/contacts/import
+{ "format": "csv" | "json", "data": "<file contents>", "fileName?": "..." }
+→ 202 { jobId, status }
+GET /v1/admin/contacts/import/{jobId}   → processed/failed counts + errors
+```
+
+Rows carry `externalId?`, `email?`, `properties?` (CSV: those columns; at least
+one identity per row). **The bulk import does NOT carry list membership or
+unsubscribe state** — handle those in 0b/0c.
+
+Scripted alternative (and the way to set list membership in the same pass):
+loop the export through the SDK —
+
+```ts
+for (const row of exported) {
+  await hogsend.contacts.upsert({
+    email: row.email,
+    userId: row.externalId,
+    properties: row.properties,
+    lists: { newsletter: row.subscribedToNewsletter === true },
+  });
+}
+```
+
+`contacts.upsert` is a true upsert — re-running the loop is safe.
+
+### 0b. List membership
+
+Either inline via `lists` on the upsert (above), or per-list:
+
+```ts
+await hogsend.lists.subscribe({ list: "newsletter", email: row.email });
+```
+
+Mind polarity: for an opt-in list (`defaultOptIn: false`) you only need to
+subscribe the members; for an opt-out list you only need to record the
+unsubscribes.
+
+### 0c. Suppression / unsubscribes (THE critical import)
+
+- **List-level unsubscribes** →
+  `hogsend.lists.unsubscribe({ list, email })` per contact+list.
+- **Global unsubscribes** ("never email this person") → the admin preferences
+  route, per contact (UUID or externalId both work as `{contactId}`):
+
+```
+PUT /v1/admin/contacts/{contactId}/preferences
+{ "unsubscribedAll": true }
+```
+
+(`suppressed: true` is also accepted there — use it for hard-bounced/complained
+addresses from the source platform's suppression export.)
+
+**Gate: do not proceed to any send until a spot check passes** — pick 3 known
+unsubscribed addresses, confirm via
+`hogsend contacts get <id> --json` / the preferences route that they show
+`unsubscribedAll: true`, and confirm a test `hogsend emails send` to one of
+them is refused by the preference check.
+
+## Stage 1 — dual-write
+
+- Add `@hogsend/client` calls BESIDE the existing SDK calls (same handlers,
+  both fire). Use `idempotencyKey` on webhook-driven events.
+- Author journeys/templates/lists in the Hogsend app, but keep journeys OFF:
+  `enabled: false` in meta, or excluded from the `ENABLED_JOURNEYS` env
+  (comma-separated ids; `*` = all).
+- Keep the source platform fully live. Nothing user-visible changes.
+
+## Stage 2 — verify (run a few days)
+
+```bash
+hogsend doctor --json                 # instance healthy
+hogsend stats --json                  # totalContacts matches the import
+hogsend events <userId> --json        # spot-check: events arriving for real users
+hogsend contacts timeline <id> --json # merged activity view for a known user
+```
+
+- **Volume:** compare daily event counts per event name against the source
+  platform's numbers. Investigate gaps > a few percent.
+- **Journeys:** enroll a seed contact (your own address):
+  `hogsend events send signup --email you@yourco.com --json`, temporarily
+  enable the journey (`hogsend journeys enable <id>`), walk the full flow —
+  delays, branches, sends — then disable again if the soak isn't done.
+- **Templates:** send each to yourself
+  (`hogsend emails send <template> --to you@yourco.com --prop key=value`) and
+  diff against the source platform's rendering. Check the unsubscribe link
+  resolves.
+
+## Stage 3 — switch (per flow, old OFF in the same window)
+
+For each lifecycle flow, in one change window:
+
+1. Enable the Hogsend journey — `hogsend journeys enable <id> --json` (or ship
+   `enabled: true` / add to `ENABLED_JOURNEYS` and deploy).
+2. Pause the corresponding workflow/campaign in the source platform's
+   dashboard.
+3. Watch the first real enrollments: `hogsend journeys get <id> --json`
+   (state counts + recent states).
+
+For transactional: flip each call site from the old SDK to `hs.emails.send`
+(delete the old call, don't dual-send transactional — a user must never get
+two password resets). For broadcasts: run the next one as a Hogsend campaign
+(`hogsend campaigns send --list … --template …`; progress via
+`hogsend campaigns status <id> --json`).
+
+## Stage 4 — remove
+
+After 1-2 clean send cycles:
+
+- Delete the old SDK calls and the dep (`pnpm remove <pkg>`); remove its env
+  vars from every environment.
+- Revoke the source platform's API keys.
+- Export final archives (campaign history, analytics) — they don't migrate.
+- Re-export the source's suppression list ONE more time and re-run 0c — people
+  unsubscribed during the dual-write window must not be lost.
+- Close/downgrade the account.
+
+## Rollback
+
+Until Stage 4, rollback is cheap and symmetrical: disable the Hogsend journey
+(`hogsend journeys disable <id>`), resume the source workflow. That symmetry is
+the reason for flow-by-flow switching — keep it until you delete the old code.

package/skills/hogsend-migrate/references/loops-mapping.md

@@ -0,0 +1,132 @@
+# Loops → Hogsend mapping
+
+Audit greps, the concept table, and before/after rewrites for a codebase using
+Loops (loops.so). Loops' own API may differ by SDK version — treat the
+left-hand column as "look for", and verify against the project's actual calls.
+
+## Audit greps (code half)
+
+```bash
+grep -rn "loops" package.json                 # the SDK dep (commonly `loops`)
+grep -rn "sendEvent\|updateContact\|sendTransactionalEmail\|createContact" src/
+grep -rn "transactionalId" src/               # transactional template ids
+grep -rn "LOOPS_API_KEY\|loops.so" . --include="*.env*" --include="*.ts"
+```
+
+GUI half (ask the user to export/screenshot from the Loops dashboard): Loops
+(the workflows), audiences/segments, mailing lists + their opt-in state,
+email templates, and the unsubscribed-contacts export.
+
+## Concept mapping
+
+| Loops concept | Hogsend equivalent | Notes |
+|---|---|---|
+| Contact (+ contact properties) | contact — `hs.contacts.upsert({ email, userId?, properties })` | Loops keys contacts on email; carry the app's user id as `userId` too — Hogsend identity is `email` and/or `userId` |
+| `sendEvent` (event + event/contact properties) | `hs.events.send({ …, eventProperties, contactProperties })` | Keep the bag split deliberate: per-occurrence facts → `eventProperties` (drive journey `trigger.where`/`exitOn`); durable facts → `contactProperties` |
+| Loop (the visual workflow) | journey — `defineJourney()` in `src/journeys/` | Entry trigger → `trigger.event`; "enter once" → `entryLimit: "once"`; goal/exit → `exitOn`; timers → `ctx.sleep({ duration: days(n) })`; audience filters → `trigger.where` conditions |
+| Transactional email (`sendTransactionalEmail` + `transactionalId`) | `hs.emails.send({ to | userId, template, props })` + a four-file template | Each `transactionalId` becomes a template key in the Hogsend app's `src/emails/` registry; `dataVariables` become typed `props` |
+| Mailing list (opt-in/opt-out toggle) | list — `defineList({ id, name, defaultOptIn })` | Loops' "public" opt-in lists → `defaultOptIn: false`; default-subscribed lists → `defaultOptIn: true` |
+| Audience / segment filter | bucket (`defineBucket`) when behavioral; `trigger.where` when it's just an entry filter | Don't over-build: a one-condition audience is usually just a `where` clause |
+| Campaign (one-off blast) | campaign — `hs.campaigns.send({ list | bucket, template, props })` | Or `hogsend campaigns send --list … --template …` |
+| Unsubscribed contacts | suppression import — see `cutover-checklist.md` | Import BEFORE any send |
+
+## Before / after
+
+Contact + event (host product code):
+
+```ts
+// BEFORE (Loops — shape varies by SDK version)
+await loops.updateContact("ada@example.com", { plan: "pro" });
+await loops.sendEvent({
+  email: "ada@example.com",
+  eventName: "subscription_started",
+  eventProperties: { plan: "pro" },
+});
+
+// AFTER (@hogsend/client)
+import { hogsend } from "../lib/hogsend.js";
+
+await hogsend.contacts.upsert({
+  email: "ada@example.com",
+  userId: user.id,
+  properties: { plan: "pro" },
+});
+await hogsend.events.send({
+  email: "ada@example.com",
+  userId: user.id,
+  name: "subscription_started",
+  eventProperties: { plan: "pro" },
+});
+```
+
+Transactional:
+
+```ts
+// BEFORE (Loops)
+await loops.sendTransactionalEmail({
+  transactionalId: "clxyz...",
+  email: "ada@example.com",
+  dataVariables: { resetUrl },
+});
+
+// AFTER — template authored in the Hogsend app first
+// (four-file contract → hogsend-authoring-emails skill)
+await hogsend.emails.send({
+  to: "ada@example.com",
+  template: "password-reset",
+  props: { resetUrl },
+});
+```
+
+A Loop becomes a journey (authored in the HOGSEND app, not the host —
+mechanics → hogsend-authoring-journeys):
+
+```ts
+// "When signup occurs → wait 2 days → if no project created, send nudge"
+import { days } from "@hogsend/core";
+import { defineJourney, sendEmail } from "@hogsend/engine";
+import { Events, Templates } from "./constants/index.js";
+
+export const onboardingNudge = defineJourney({
+  meta: {
+    id: "onboarding-nudge",
+    name: "Onboarding nudge",
+    enabled: false, // stays off until the cutover switch stage
+    trigger: { event: Events.SIGNUP },
+    entryLimit: "once",
+    suppress: days(7),
+    exitOn: [{ event: Events.PROJECT_CREATED }],
+  },
+  run: async (user, ctx) => {
+    await ctx.sleep({ duration: days(2), label: "post-signup" });
+    const { found } = await ctx.history.hasEvent({
+      userId: user.id,
+      event: Events.PROJECT_CREATED,
+    });
+    if (!found) {
+      await sendEmail({
+        to: user.email,
+        userId: user.id,
+        journeyStateId: user.stateId,
+        template: Templates.ONBOARDING_NUDGE,
+        journeyName: user.journeyName,
+      });
+    }
+  },
+});
+```
+
+## Loops-specific gotchas
+
+- **Email-keyed identity.** Loops contacts are keyed on email. If the app has
+  stable user ids, send BOTH on every Hogsend write so identities link
+  (`linked: true` in the upsert result confirms a merge).
+- **Event property names become your journey vocabulary.** Journeys'
+  `trigger.where` matches `eventProperties` keys — keep names stable across the
+  rewrite, or update both sides together.
+- **Template content is GUI-side.** Export each template's content from the
+  Loops editor; you are re-authoring it as react-email, not copying HTML
+  verbatim (use the Hogsend app's `src/emails/_components/` chrome).
+- **Loops' unsubscribe is per-mailing-list + global.** Map list-level
+  unsubscribes to `hs.lists.unsubscribe({ list, email })` and global ones to
+  the admin preferences route (`unsubscribedAll`) — see `cutover-checklist.md`.