Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -1,16 +1,16 @@
# Email-Sequence Engine (Marketing-Funnel Phase 3)
**Status:** Phase 05 Task #80 — the sequence data model, pure engine foundation, admin UI/CLI, local E2E readiness seed fixtures, unsubscribe route, open/click tracking routes, worker bootstrap contracts, delayed-step enqueueing foundation, bundled template renderer, `@toolctrl/mail` Mailjet adapter, signed Mailjet bounce webhook handling, unit-tested stale-lead/trial-expiring cron runner functions, and live admin statistics views are in place. This is shipped foundation/admin-preview work, not an end-to-end production email-delivery claim for marketing sequences. The worker entrypoints are default-safe: `MARKETING_SEQUENCES_ENABLED` must be explicitly set to `true` before sequence subscribers do work; entrypoint tests prove the sequence workers and readiness probes stay disabled while the flag is unset. Keep it unset or `false` in production until production/demo seed rollout evidence, statistics aggregation cron, Playwright E2E coverage, delivery webhook production evidence, and production scheduled-job registration/deploy evidence are complete.
**Status:** Phase 05 Task #80 — the sequence data model, pure engine foundation, admin UI/CLI, local E2E readiness seed fixtures, unsubscribe route, open/click tracking routes, worker bootstrap contracts, delayed-step enqueueing foundation, bundled template renderer, `@hivegrid/mail` Mailjet adapter, signed Mailjet bounce webhook handling, unit-tested stale-lead/trial-expiring cron runner functions, and live admin statistics views are in place. This is shipped foundation/admin-preview work, not an end-to-end production email-delivery claim for marketing sequences. The worker entrypoints are default-safe: `MARKETING_SEQUENCES_ENABLED` must be explicitly set to `true` before sequence subscribers do work; entrypoint tests prove the sequence workers and readiness probes stay disabled while the flag is unset. Keep it unset or `false` in production until production/demo seed rollout evidence, statistics aggregation cron, Playwright E2E coverage, delivery webhook production evidence, and production scheduled-job registration/deploy evidence are complete.
## What ships
| Component | Package | Notes |
| ------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Data model | `prisma/schema/emailSequences.prisma` | `EmailSequence`, `EmailSequenceRun`, `EmailSequenceStepDelivery` |
| Engine | `@toolctrl/email-sequences` | pure-logic — types, conditions, engine, step-runner |
| Template definitions | `@toolctrl/email-templates` | welcome / trial-reminder / re-activation / generic-step renderer used by the worker runtime |
| Engine | `@hivegrid/email-sequences` | pure-logic — types, conditions, engine, step-runner |
| Template definitions | `@hivegrid/email-templates` | welcome / trial-reminder / re-activation / generic-step renderer used by the worker runtime |
| Trigger worker contract | `apps/worker/src/jobs/email-sequence-trigger.ts` | consumes matching outbox events, persists trigger context, and starts runs idempotently |
| Scheduler worker contract | `apps/worker/src/jobs/email-sequence-scheduler.ts` | step-runner foundation; runtime enqueues idempotent delayed jobs and sends through `@toolctrl/mail` when Mailjet env is configured |
| Scheduler worker contract | `apps/worker/src/jobs/email-sequence-scheduler.ts` | step-runner foundation; runtime enqueues idempotent delayed jobs and sends through `@hivegrid/mail` when Mailjet env is configured |
| Unsubscribe route | `apps/web/app/routes/unsubscribe.$token.tsx` | RFC-8058 one-click (GET + POST) |
| Tracking — open | `apps/web/app/routes/email/track-open.$deliveryId[.gif].tsx` | 1×1 transparent GIF |
| Tracking — click | `apps/web/app/routes/email/track-click.$deliveryId.tsx` | 302-redirect + first-touch update |
@@ -31,7 +31,7 @@ handler is pure foundation and the general subscriber is not bootstrapped from `
## Architecture
The diagram below shows the sequence flow. The delayed-job producer, bundled template renderer, and `@toolctrl/mail` Mailjet adapter exist, but missing Mailjet configuration still fails closed and the remaining production follow-ups below must be completed before this path should be treated as approved production delivery.
The diagram below shows the sequence flow. The delayed-job producer, bundled template renderer, and `@hivegrid/mail` Mailjet adapter exist, but missing Mailjet configuration still fails closed and the remaining production follow-ups below must be completed before this path should be treated as approved production delivery.
```
┌──────────────────────────────┐
@@ -51,7 +51,7 @@ The diagram below shows the sequence flow. The delayed-job producer, bundled tem
│ - runStep │
│ ├── conditions │
│ ├── renderTemplate │ bundled sequence templates
│ ├── sendMail │ @toolctrl/mail Mailjet adapter
│ ├── sendMail │ @hivegrid/mail Mailjet adapter
│ ├── markDelivery │
│ └── advanceSequenceRun │
└──────────────────────────────┘
@@ -110,7 +110,7 @@ The admin stats dashboard documents these as approximations. It currently comput
## Templates
Minimal React-Email-style template definitions exist. The worker runtime turns these definitions into a `@toolctrl/mail` send payload, but the remaining production follow-ups below still need to land before marketing sequences should be cited as approved production mail end to end.
Minimal React-Email-style template definitions exist. The worker runtime turns these definitions into a `@hivegrid/mail` send payload, but the remaining production follow-ups below still need to land before marketing sequences should be cited as approved production mail end to end.
| Template | Trigger example | Variables |
| -------------------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
@@ -119,7 +119,7 @@ Minimal React-Email-style template definitions exist. The worker runtime turns t
| `ReActivationEmail` | `lead.stale_60d` | `recipientName?`, `productName`, `returnUrl`, `highlight?`, `unsubscribeUrl` |
| `GenericStepEmail` | onboarding-drip / operator-defined | `headline`, `bodyParagraphs[]`, `ctaUrl?`, `ctaLabel?`, `unsubscribeUrl` |
The full React-Email migration tracked under #75 is no longer the blocker here; the worker runtime renders the bundled sequence templates and sends through `@toolctrl/mail` when `MAILJET_API_KEY` and `MAILJET_FROM_EMAIL` are configured together. If either key is absent, step delivery fails closed with `email_sequence_mail_sender_unavailable`.
The full React-Email migration tracked under #75 is no longer the blocker here; the worker runtime renders the bundled sequence templates and sends through `@hivegrid/mail` when `MAILJET_API_KEY` and `MAILJET_FROM_EMAIL` are configured together. If either key is absent, step delivery fails closed with `email_sequence_mail_sender_unavailable`.
## Admin UI
@@ -139,7 +139,7 @@ No drag-drop step builder — operators paste step + condition JSON directly int
## CLI
`toolctrl-cli sequences <subcommand>` exposes operator commands:
`hivegrid-cli sequences <subcommand>` exposes operator commands:
| Subcommand | Purpose | `--json` |
| -------------------------------------- | -------------------------------------------------------------- | -------- |
@@ -169,9 +169,9 @@ Both use date-keyed dispatch keys (`lead.stale_60d.<id>.<YYYY-MM-DD>` /
| ----------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `MARKETING_TOKEN_SECRET` | (falls back to `LEAD_CONVERSION_SECRET`) | HMAC key for unsubscribe tokens |
| `MARKETING_SEQUENCES_ENABLED` | unset / `false` in production examples | Opt-in switch — trigger, scheduler, and sequence cron producers only do work when this is exactly `true`. Keep this unset or `false` in production until the remaining production follow-ups are approved. |
| `MAILJET_API_KEY` | unset | Required with `MAILJET_FROM_EMAIL` for sequence step delivery through `@toolctrl/mail`; missing configuration fails closed. |
| `MAILJET_FROM_EMAIL` | unset | Required with `MAILJET_API_KEY` for sequence step delivery through `@toolctrl/mail`; missing configuration fails closed. |
| `MAILJET_FROM_NAME` | unset | Optional display name passed to `@toolctrl/mail`. |
| `MAILJET_API_KEY` | unset | Required with `MAILJET_FROM_EMAIL` for sequence step delivery through `@hivegrid/mail`; missing configuration fails closed. |
| `MAILJET_FROM_EMAIL` | unset | Required with `MAILJET_API_KEY` for sequence step delivery through `@hivegrid/mail`; missing configuration fails closed. |
| `MAILJET_FROM_NAME` | unset | Optional display name passed to `@hivegrid/mail`. |
| `MAILJET_WEBHOOK_SECRET` | unset | Required on the API runtime for signed sequence bounce webhook ingestion at `/v1/email-sequences/mailjet/webhooks`. |
## Troubleshooting
@@ -182,7 +182,7 @@ Both use date-keyed dispatch keys (`lead.stale_60d.<id>.<YYYY-MM-DD>` /
- Open-rate looks impossible (>100%) → Apple Mail Privacy Protection pre-fetch; combine with click-rate for a more reliable engagement signal.
- Hard bounce → run transitions to `failed` and no further steps fire. The Lead row's `unsubscribedAt` is NOT touched (Phase 1 lead-model owns that semantic; bounce is per-run only).
- Sequence isn't sending — use this quick diagnostic checklist:
1. `toolctrl-cli sequences list --json` → confirm `isEnabled=true` on the matching row.
1. `hivegrid-cli sequences list --json` → confirm `isEnabled=true` on the matching row.
2. `triggerEvent` matches the normalised outbox event-type. Outbox emits
`marketing.lead.captured` but sequences store `lead.captured` — the trigger handler
normalises both directions. Manually configured sequences with a `marketing.`-prefixed
@@ -195,15 +195,13 @@ Both use date-keyed dispatch keys (`lead.stale_60d.<id>.<YYYY-MM-DD>` /
Pending `marketing.*` rows in the database outbox instead mean the
dispatcher still needs to be running on the `general` group.
- Trial-expiring cron emits nothing — verify the subscription store actually has rows with a
`trialEndsAt` inside the horizon (default 3 days). Bare Stripe-managed trials may not have a
`trialEndsAt` inside the horizon (default 3 days). Bare Legacy-Provider-managed trials may not have a
cached `trialEndsAt` column; the cron skips them silently.
- Stale-lead cron over-eager — bump `MARKETING_STALE_LEAD_DAYS` (or pass a non-default
`thresholdDays` to the cron when wiring) and re-run.
## Status
Detail spec: `docs/improvement-plan/05-business-features/marketing-funnel-phase-3.md`
Open follow-ups:
- Promote the four local readiness sequence definitions into deployable demo/production seed data, with environment-specific owner approval.