Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
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.
|
||||
|
||||
Reference in new issue
Block a user