@hogsend/cli 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/cli",
-  "version": "0.11.0",
+  "version": "0.12.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.11.0",
+    "@hogsend/studio": "^0.12.0",
     "@repo/typescript-config": "0.0.0"
   },
   "engines": {
@@ -42,8 +42,8 @@
     "@clack/prompts": "^1.5.0",
     "better-auth": "^1.6.11",
     "picocolors": "^1.1.1",
-    "@hogsend/db": "^0.11.0",
-    "@hogsend/engine": "^0.11.0"
+    "@hogsend/db": "^0.12.0",
+    "@hogsend/engine": "^0.12.0"
   },
   "scripts": {
     "prebuild": "node scripts/bundle-studio.mjs",

package/skills/hogsend-integrate/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: hogsend-integrate
+description: Use when wiring an EXISTING product codebase — Next.js (App or Pages Router), Express, Hono, Remix, SvelteKit, or any Node server — to a running Hogsend instance via @hogsend/client. The outside-in playbook — detect the host stack, find the signup/auth/billing seams (better-auth, Clerk, Supabase, Stripe, NextAuth), install @hogsend/client, add contacts.upsert on signup + events.send on key actions + emails.send for transactional, wire HOGSEND_API_URL/HOGSEND_API_KEY env, then verify ingestion with `hogsend events`. NOT for code inside a Hogsend app itself (there, use hogsend-client-sdk for app code or the authoring skills for journeys/emails) and NOT for migrating off Loops/Customer.io/Resend Broadcasts (that is hogsend-migrate).
+license: MIT
+metadata:
+  author: withSeismic
+  version: "1.0.0"
+---
+
+# Integrate a host app with Hogsend
+
+This skill drives the **outside-in** flow: you are working in someone's PRODUCT
+codebase (a SaaS app, a marketing site backend — NOT a Hogsend app), and the
+goal is to wire it to a running Hogsend instance so that signups become
+contacts, key actions become events (which trigger journeys), and transactional
+sends go through Hogsend's tracked pipeline.
+
+The shape of the work: **detect the stack → find the seams → wire the client →
+add the calls → verify ingestion.** Confirm the seams with the user before
+editing; everything else is mechanical.
+
+## Step 0 — orientation guard (am I in the right codebase?)
+
+Check `package.json` first. If it depends on `@hogsend/engine` — or the project
+has `src/journeys/` + `src/emails/` — you are INSIDE a Hogsend app, and this
+skill does not apply:
+
+- App code inside a Hogsend app → the **hogsend-client-sdk** skill (the
+  scaffold already ships a preconfigured `hs` at `src/lib/hogsend.ts`).
+- Journeys / emails / lists / webhook sources → the **hogsend-authoring-\***
+  skills.
+
+This skill targets the HOST product. The only Hogsend dependency you will add
+here is `@hogsend/client`.
+
+## Step 1 — detect the stack
+
+Probe, don't ask. Each framework decides where server-side code lives and where
+the shared client module goes (full wiring per framework →
+`references/framework-recipes.md`):
+
+| Probe | Stack | Server-side code lives in |
+|---|---|---|
+| `next.config.*` + `app/` (or `src/app/`) | Next.js App Router | route handlers `app/**/route.ts`, server actions |
+| `next.config.*` + `pages/api/` | Next.js Pages Router | `pages/api/**` |
+| `express` dep + `app.post(`/`router.post(` | Express | route handlers, middleware |
+| `hono` dep + `new Hono(` | Hono | route handlers |
+| `@remix-run/*` (or `react-router` v7 framework mode) | Remix | `action`/`loader` exports |
+| `@sveltejs/kit` dep | SvelteKit | `src/routes/**/+server.ts`, `+page.server.ts`, `src/lib/server/` |
+
+**The one rule that never changes: the client is server-only.** `HOGSEND_API_KEY`
+must NEVER reach the browser bundle — no `NEXT_PUBLIC_`/`VITE_`/`PUBLIC_`
+prefixes, no client-component imports. Fire events from route handlers, server
+actions, API routes, and webhooks.
+
+## Step 2 — find the signup/auth/billing seams
+
+Grep for the places identity is created and money changes hands. Report what you
+find as a short table and **confirm with the user before editing**. Detection
+greps + a wired snippet per provider → `references/auth-billing-seams.md`:
+
+| Seam | Grep for |
+|---|---|
+| better-auth | `betterAuth(`, `databaseHooks` |
+| Clerk | `clerkMiddleware`, a webhook handler verifying `svix-*` headers |
+| Supabase Auth | `supabase.auth.signUp`, `auth.admin`, auth webhook handlers |
+| NextAuth / Auth.js | `NextAuth(`, `events:` (esp. `createUser`) |
+| Stripe | `stripe.webhooks.constructEvent`, `checkout.session.completed`, `customer.subscription.` |
+| Hand-rolled | `signup`/`register` route handlers, `INSERT INTO users`, ORM `user.create` |
+
+Also note: if the team prefers zero host-code for a provider, Hogsend itself
+ships **inbound webhook presets** for Clerk/Supabase/Stripe/Segment (point the
+provider's webhook at the Hogsend instance's `POST /v1/webhooks/{clerk,supabase,stripe,segment}`,
+set the secret env on the HOGSEND side). Host-side `@hogsend/client` calls and
+Hogsend-side presets are alternatives — don't double-fire the same event.
+
+## Step 3 — wire the client (one shared server module)
+
+```bash
+pnpm add @hogsend/client        # or npm i / yarn add — never hand-edit versions
+```
+
+Create ONE server-only module exporting a singleton (placement per framework in
+`references/framework-recipes.md`; e.g. `lib/hogsend.ts`, or
+`hogsend.server.ts` where the framework enforces server-only by suffix):
+
+```ts
+// lib/hogsend.ts — server-only. Do not import from client components.
+import { Hogsend } from "@hogsend/client";
+
+export const hogsend = new Hogsend({
+  baseUrl: process.env.HOGSEND_API_URL!,
+  apiKey: process.env.HOGSEND_API_KEY!,
+});
+```
+
+**Host-app env convention** (add to `.env` + the project's env example file):
+
+```bash
+HOGSEND_API_URL=https://hogsend.your-company.com   # the Hogsend API base URL
+HOGSEND_API_KEY=hsk_...                            # ingest-scoped data-plane key
+```
+
+The key needs the `ingest` scope (or `full-admin`, which implies it) — minted in
+the Hogsend app. These names match what the `hogsend` CLI reads, so verification
+(Step 5) works with the same env. Do NOT conflate with the Hogsend app's own
+internal `API_PUBLIC_URL` — that var belongs inside the scaffolded Hogsend app,
+not the host.
+
+## Step 4 — add the calls at the seams
+
+Three call patterns cover almost every integration (full SDK surface, identity
+rules, and error types → the **hogsend-client-sdk** skill):
+
+```ts
+import { hogsend } from "../lib/hogsend.js";
+
+// 1. Signup → upsert the contact
+await hogsend.contacts.upsert({
+  email: user.email,
+  userId: user.id,                          // your stable external id
+  properties: { name: user.name, plan: "free" },
+});
+
+// 2. Key actions → send events (these trigger journeys on the Hogsend side)
+await hogsend.events.send({
+  userId: user.id,
+  name: "subscription_started",
+  eventProperties: { plan: "pro", amount: 49 },   // facts about THIS event
+  contactProperties: { plan: "pro" },             // durable facts, merged onto the contact
+  idempotencyKey: stripeEvent.id,                 // dedupes webhook retries
+});
+
+// 3. Transactional → send through Hogsend's tracked pipeline
+await hogsend.emails.send({
+  to: user.email,                                 // or userId: user.id
+  template: "password-reset",                     // a key from the HOGSEND app's registry
+  props: { resetUrl },
+});
+```
+
+Rules that matter:
+
+- **Every write needs an identity** — at least one of `email` / `userId`.
+- **The property-bag split:** `eventProperties` describe the event and are what
+  journey `trigger.where`/`exitOn` rules evaluate; `contactProperties` merge
+  onto the contact. Don't conflate them.
+- **Idempotency on webhook-driven sends:** pass the provider's event id (e.g.
+  the Stripe event id) as `idempotencyKey` so retries don't double-ingest.
+- **`template` keys live in the Hogsend app**, not the host — list what exists
+  before wiring a send (ask the user, or check the Hogsend app's
+  `src/emails/registry.ts`). A new template is authored on the Hogsend side
+  (the **hogsend-authoring-emails** skill).
+- **Hot paths:** `events.send` returns 202 once stored. Don't let analytics
+  block a signup response — catch and log, or fire-and-forget with an error
+  handler. Catch `RateLimitError` (has `retryAfter` seconds) and
+  `HogsendAPIError` (`status === 0` = transport failure) from
+  `@hogsend/client`. If you pass `lists`, check the result's `listsError`.
+
+Pick 3-5 high-signal events (signup, activation moment, subscription started/
+cancelled) over instrumenting everything — journeys trigger on these names, so
+agree the event names with the user and keep them stable.
+
+## Step 5 — verify the loop end-to-end
+
+Use the `hogsend` CLI against the same instance (`HOGSEND_API_URL` is read from
+env; full transcript → `references/verification.md`):
+
+```bash
+# 1. Fire a test event through the data plane (or trigger the real code path)
+hogsend events send signup --user-id test_agent_$(date +%s) --prop source=integration-test --json
+
+# 2. Confirm it was stored (admin key required for the read path)
+hogsend events <that-user-id> --json
+```
+
+`stored: true` on the send + the event appearing in the read = the pipe works.
+Then exercise the REAL seam (sign a test user up, replay a Stripe test webhook)
+and confirm the same way. Fallbacks: `hogsend doctor --json` (instance health),
+`hogsend contacts get <userId> --json` (contact landed), and Studio's contacts
+view on the Hogsend instance.
+
+## What happens on the Hogsend side
+
+Wiring the host is half the story — events only DO something when a journey
+triggers on them. Defining journeys/templates/lists happens in the Hogsend app:
+**hogsend-authoring-journeys**, **hogsend-authoring-emails**,
+**hogsend-authoring-lists**. For the complete `@hogsend/client` API surface, the
+**hogsend-client-sdk** skill.
+
+## Task playbooks — load the matching reference
+
+- **Per-framework wiring (module placement, route-handler examples, env
+  loading)** → `references/framework-recipes.md`
+- **Per-provider seam detection + wired snippets (better-auth, Clerk, Supabase,
+  Stripe, NextAuth)** → `references/auth-billing-seams.md`
+- **The verification transcript (CLI flags, expected output, failure
+  triage)** → `references/verification.md`

package/skills/hogsend-integrate/references/auth-billing-seams.md

@@ -0,0 +1,199 @@
+# Auth + billing seams — detection and wiring per provider
+
+How to FIND the place identity is created (or money moves) in the host
+codebase, and what to add there. Provider APIs evolve — treat the greps as
+"look for", verify against the project's actual code, and confirm the seam
+table with the user before editing.
+
+For Clerk, Supabase, Stripe, and Segment there is always a **zero-host-code
+alternative**: Hogsend ships inbound webhook presets at
+`POST /v1/webhooks/{clerk,supabase,stripe,segment}` on the Hogsend instance
+(signature-verified; enabled by setting the provider's secret env var on the
+HOGSEND side, e.g. `STRIPE_WEBHOOK_SECRET`). Use the preset when the team wants
+the provider's full lifecycle mirrored without touching the host app; use
+host-side `@hogsend/client` calls when they want control over event names and
+properties. **Pick one per provider — never both** (you'd double-ingest).
+
+## better-auth
+
+**Detect:** `better-auth` in package.json; grep `betterAuth(` for the config
+(commonly `lib/auth.ts` / `src/auth.ts`); look for `databaseHooks`.
+
+**Wire:** the `databaseHooks.user.create.after` hook fires once per new user —
+the cleanest signup seam:
+
+```ts
+import { betterAuth } from "better-auth";
+import { hogsend } from "./hogsend"; // the shared server module
+
+export const auth = betterAuth({
+  // …existing config…
+  databaseHooks: {
+    user: {
+      create: {
+        after: async (user) => {
+          await hogsend.contacts.upsert({
+            email: user.email,
+            userId: user.id,
+            properties: { name: user.name },
+          });
+          await hogsend.events.send({ userId: user.id, name: "signup" });
+        },
+      },
+    },
+  },
+});
+```
+
+## Clerk
+
+**Detect:** `@clerk/nextjs` (or another `@clerk/*` SDK); grep
+`clerkMiddleware`. An existing Clerk webhook handler verifies `svix-id` /
+`svix-timestamp` / `svix-signature` headers.
+
+**Wire (host-side):** Clerk's reliable signup signal is its `user.created`
+webhook (client-side callbacks miss OAuth signups). If the app already has a
+Clerk webhook route, add Hogsend calls to its `user.created` branch:
+
+```ts
+// inside the verified Clerk webhook handler
+if (evt.type === "user.created") {
+  const u = evt.data;
+  const email = u.email_addresses?.[0]?.email_address;
+  await hogsend.contacts.upsert({
+    email,
+    userId: u.id,
+    properties: { firstName: u.first_name, lastName: u.last_name },
+  });
+  await hogsend.events.send({
+    userId: u.id,
+    name: "signup",
+    idempotencyKey: `clerk_${u.id}_created`,
+  });
+}
+```
+
+**Or (zero host code):** point a Clerk webhook endpoint at the Hogsend
+instance's `POST /v1/webhooks/clerk` and set `CLERK_WEBHOOK_SECRET` on the
+Hogsend deployment. The preset maps `user.created/updated/deleted` and
+`waitlistEntry.created` automatically.
+
+## Supabase Auth
+
+**Detect:** `@supabase/supabase-js` / `@supabase/ssr`; grep
+`supabase.auth.signUp`, `auth.admin`, or a database webhook/trigger on
+`auth.users`.
+
+**Wire (host-side):** after a successful `signUp` call (server-side — e.g. a
+route handler using the server client):
+
+```ts
+const { data, error } = await supabase.auth.signUp({ email, password });
+if (!error && data.user) {
+  await hogsend.contacts.upsert({ email, userId: data.user.id });
+  await hogsend.events.send({ userId: data.user.id, name: "signup" });
+}
+```
+
+Caveat: client-side-only `signUp` calls have no server seam — either move the
+call server-side, add a database webhook on `auth.users`, or use the preset.
+
+**Or (zero host code):** point a Supabase database webhook (on `auth.users`
+inserts) at the Hogsend instance's `POST /v1/webhooks/supabase` and set
+`SUPABASE_WEBHOOK_SECRET` on the Hogsend deployment.
+
+## NextAuth / Auth.js
+
+**Detect:** `next-auth` / `@auth/core`; grep `NextAuth(`. The config commonly
+lives in `auth.ts` / `app/api/auth/[...nextauth]/route.ts`.
+
+**Wire:** the `events.createUser` event fires once when the adapter persists a
+new user:
+
+```ts
+export const { handlers, auth } = NextAuth({
+  // …existing config…
+  events: {
+    async createUser({ user }) {
+      await hogsend.contacts.upsert({
+        email: user.email ?? undefined,
+        userId: user.id,
+        properties: { name: user.name },
+      });
+      await hogsend.events.send({ userId: user.id!, name: "signup" });
+    },
+  },
+});
+```
+
+(`events.createUser` requires a database adapter; with pure JWT sessions there
+is no persistent user creation moment — instrument the app's own
+profile-creation step instead.)
+
+## Stripe (billing)
+
+**Detect:** `stripe` dep; grep `stripe.webhooks.constructEvent` for the webhook
+handler, then `checkout.session.completed` / `customer.subscription.` for the
+lifecycle branches.
+
+**Wire (host-side):** add events inside the existing verified webhook handler.
+ALWAYS pass the Stripe event id as `idempotencyKey` — Stripe retries
+deliveries:
+
+```ts
+// inside the handler, after constructEvent succeeded
+switch (event.type) {
+  case "checkout.session.completed": {
+    const session = event.data.object;
+    await hogsend.events.send({
+      email: session.customer_details?.email ?? undefined,
+      userId: session.client_reference_id ?? undefined,
+      name: "subscription_started",
+      eventProperties: {
+        amount: session.amount_total,
+        currency: session.currency,
+      },
+      contactProperties: { plan: "pro" },
+      idempotencyKey: event.id,
+    });
+    break;
+  }
+  case "customer.subscription.deleted": {
+    await hogsend.events.send({
+      userId: lookupUserIdByCustomer(event.data.object.customer), // app-specific
+      name: "subscription_cancelled",
+      contactProperties: { plan: "free" },
+      idempotencyKey: event.id,
+    });
+    break;
+  }
+}
+```
+
+Identity note: Stripe events carry a Stripe customer id, not your user id. Use
+whatever mapping the app already has (`client_reference_id`, a `userId` in
+`metadata`, or a customers table) — at least one of `email`/`userId` is
+required on every send.
+
+**Or (zero host code):** add a second Stripe webhook endpoint pointed at the
+Hogsend instance's `POST /v1/webhooks/stripe` and set `STRIPE_WEBHOOK_SECRET`
+on the Hogsend deployment.
+
+## Hand-rolled auth
+
+**Detect:** grep `signup`, `register`, `createUser`, ORM calls
+(`prisma.user.create`, `db.insert(users)`), `INSERT INTO users`.
+
+**Wire:** add the upsert + event immediately after the user row is committed
+(after, not before — don't ingest users whose creation then rolls back).
+
+## Output of this step
+
+Before editing, present the seams found:
+
+| Seam | File | Action |
+|---|---|---|
+| better-auth signup | `src/lib/auth.ts` | add `databaseHooks.user.create.after` |
+| Stripe webhook | `app/api/stripe/route.ts` | add events on 2 branches |
+
+…and get a yes. Then wire, then verify (`references/verification.md`).

package/skills/hogsend-integrate/references/framework-recipes.md

@@ -0,0 +1,208 @@
+# Framework recipes — wiring `@hogsend/client` per stack
+
+One shared server-only module, one import per seam. Adjust paths to the
+project's conventions (`src/` prefix, path aliases) — the probes in SKILL.md
+tell you which recipe applies.
+
+In every recipe the module is the same; only the placement changes:
+
+```ts
+import { Hogsend } from "@hogsend/client";
+
+export const hogsend = new Hogsend({
+  baseUrl: process.env.HOGSEND_API_URL!,
+  apiKey: process.env.HOGSEND_API_KEY!,
+});
+```
+
+Env (`.env` + the project's `.env.example`):
+
+```bash
+HOGSEND_API_URL=https://hogsend.your-company.com
+HOGSEND_API_KEY=hsk_...   # ingest-scoped key, server-side only
+```
+
+## Next.js — App Router
+
+- **Module:** `lib/hogsend.ts` (or `src/lib/hogsend.ts`). Add
+  `import "server-only";` at the top if the project uses the `server-only`
+  package — it turns an accidental client-component import into a build error.
+- **Call from:** route handlers (`app/**/route.ts`), server actions
+  (`"use server"`), and webhook handlers. Never from `"use client"` components.
+
+```ts
+// app/api/signup/route.ts
+import { hogsend } from "@/lib/hogsend";
+
+export async function POST(req: Request) {
+  const { email, name } = await req.json();
+  const user = await createUser({ email, name }); // the app's existing logic
+
+  await hogsend.contacts.upsert({
+    email,
+    userId: user.id,
+    properties: { name },
+  });
+  await hogsend.events.send({ userId: user.id, name: "signup" });
+
+  return Response.json({ ok: true });
+}
+```
+
+Env note: server-side `process.env.HOGSEND_API_KEY` works out of the box (Next
+loads `.env*`). Never add a `NEXT_PUBLIC_` variant.
+
+## Next.js — Pages Router
+
+- **Module:** `lib/hogsend.ts`. **Call from:** `pages/api/**` handlers and
+  `getServerSideProps` only.
+
+```ts
+// pages/api/signup.ts
+import type { NextApiRequest, NextApiResponse } from "next";
+import { hogsend } from "../../lib/hogsend";
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse,
+) {
+  const user = await createUser(req.body);
+  await hogsend.contacts.upsert({ email: user.email, userId: user.id });
+  await hogsend.events.send({ userId: user.id, name: "signup" });
+  res.status(200).json({ ok: true });
+}
+```
+
+## Express
+
+- **Module:** wherever the project keeps shared services (`src/lib/hogsend.ts`,
+  `src/services/hogsend.ts`). Ensure env is loaded before the module is
+  imported (the project's existing `dotenv` setup usually covers this).
+
+```ts
+// src/routes/auth.ts
+import { Router } from "express";
+import { hogsend } from "../lib/hogsend.js";
+
+const router = Router();
+
+router.post("/signup", async (req, res, next) => {
+  try {
+    const user = await createUser(req.body);
+    await hogsend.contacts.upsert({ email: user.email, userId: user.id });
+    await hogsend.events.send({ userId: user.id, name: "signup" });
+    res.json({ ok: true });
+  } catch (err) {
+    next(err);
+  }
+});
+```
+
+## Hono
+
+- **Module:** `src/lib/hogsend.ts`. On Node, `process.env` works directly. On
+  edge runtimes (Cloudflare Workers), env arrives per-request via `c.env` — in
+  that case construct the client inside the handler (or a middleware) from
+  `c.env.HOGSEND_API_URL` / `c.env.HOGSEND_API_KEY` instead of a module-level
+  singleton.
+
+```ts
+// src/routes/auth.ts (Node runtime)
+import { Hono } from "hono";
+import { hogsend } from "../lib/hogsend.js";
+
+const auth = new Hono();
+
+auth.post("/signup", async (c) => {
+  const body = await c.req.json();
+  const user = await createUser(body);
+  await hogsend.contacts.upsert({ email: user.email, userId: user.id });
+  await hogsend.events.send({ userId: user.id, name: "signup" });
+  return c.json({ ok: true });
+});
+```
+
+## Remix (and React Router v7 framework mode)
+
+- **Module:** `app/lib/hogsend.server.ts` — the `.server.ts` suffix makes the
+  bundler exclude it from the client build (this is the framework's own
+  server-only mechanism; use it).
+- **Call from:** `action` / `loader` exports and resource routes.
+
+```ts
+// app/routes/signup.tsx
+import type { ActionFunctionArgs } from "@remix-run/node";
+import { hogsend } from "~/lib/hogsend.server";
+
+export async function action({ request }: ActionFunctionArgs) {
+  const form = await request.formData();
+  const user = await createUser(Object.fromEntries(form));
+  await hogsend.contacts.upsert({ email: user.email, userId: user.id });
+  await hogsend.events.send({ userId: user.id, name: "signup" });
+  return { ok: true };
+}
+```
+
+## SvelteKit
+
+- **Module:** `src/lib/server/hogsend.ts` — anything under `src/lib/server/`
+  is enforced server-only by SvelteKit. Prefer the framework's private env
+  module over `process.env`:
+
+```ts
+// src/lib/server/hogsend.ts
+import { env } from "$env/dynamic/private";
+import { Hogsend } from "@hogsend/client";
+
+export const hogsend = new Hogsend({
+  baseUrl: env.HOGSEND_API_URL!,
+  apiKey: env.HOGSEND_API_KEY!,
+});
+```
+
+- **Call from:** `+server.ts` endpoints and `+page.server.ts` actions:
+
+```ts
+// src/routes/signup/+page.server.ts
+import { hogsend } from "$lib/server/hogsend";
+
+export const actions = {
+  default: async ({ request }) => {
+    const form = await request.formData();
+    const user = await createUser(Object.fromEntries(form));
+    await hogsend.contacts.upsert({ email: user.email, userId: user.id });
+    await hogsend.events.send({ userId: user.id, name: "signup" });
+    return { ok: true };
+  },
+};
+```
+
+## Anything else (Fastify, NestJS, plain Node, cron workers)
+
+The pattern is identical: one shared module holding the singleton, imported by
+server-side handlers. `@hogsend/client` is a thin wrapper over native `fetch`
+(ESM + CJS; declares `engines.node >= 22`), so it runs in any modern Node
+server. For NestJS, wrap it in an
+injectable provider; for queues/crons, import the same module from the job
+handler.
+
+## Hot-path guidance (applies to every framework)
+
+Don't let lifecycle instrumentation take down a signup. Two acceptable shapes:
+
+```ts
+// a) awaited, but non-fatal
+try {
+  await hogsend.events.send({ userId: user.id, name: "signup" });
+} catch (err) {
+  console.error("hogsend ingest failed", err); // log + continue
+}
+
+// b) fire-and-forget with an attached handler (never a bare floating promise)
+void hogsend.events
+  .send({ userId: user.id, name: "signup" })
+  .catch((err) => console.error("hogsend ingest failed", err));
+```
+
+For webhook handlers (Stripe, Clerk), prefer (a) awaited — the provider retries
+on 5xx, and `idempotencyKey` makes the retry safe.