mirror of
https://github.com/juherr/kill-the-news.git
synced 2026-06-20 22:03:48 +00:00
docs(spec): subscription confirmation surfacing design
Brainstormed design for detecting newsletter confirmation emails at ingestion, marking them, and surfacing the confirmation link in the admin (detail section, list badge, dashboard pill, emails-page banner). v1 does no outbound request; server on-detect actions deferred. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Julien Herr
@@ -0,0 +1,206 @@
|
||||
# Subscription confirmation surfacing — design
|
||||
|
||||
_Date: 2026-05-25 · Origin: TODO.md `P1·M` "Subscription confirmation handling" (upstream issues #5, #23, #57, #73, #89, #95, #97)_
|
||||
|
||||
## Problem
|
||||
|
||||
Newsletters require a "click to confirm your subscription" step. The confirmation
|
||||
email lands in the feed like any other item, so the user has to hunt the link
|
||||
inside a feed reader — the single most recurring upstream request. Until they
|
||||
confirm, the feed stays empty and the tool looks broken.
|
||||
|
||||
## Goal (v1 scope)
|
||||
|
||||
Detect confirmation emails at ingestion, **mark** them, and **surface the
|
||||
confirmation link prominently** in the admin so the user can click it. No outbound
|
||||
requests — the worker never follows the link in v1.
|
||||
|
||||
Explicitly deferred to a later batch (noted in TODO): a server-configured
|
||||
on-detection action (`none` / `autoclick` / `forward` to the fallback box).
|
||||
|
||||
## Non-goals
|
||||
|
||||
- No auto-clicking / server-side following of confirmation links (SSRF surface).
|
||||
- No per-feed action configuration.
|
||||
- No detection of whether confirmation actually succeeded (impossible without
|
||||
autoclick) — "dismiss" just stops the reminder.
|
||||
|
||||
## Architecture overview
|
||||
|
||||
Detection is a **pure domain service** fed by infra-extracted links/text; the
|
||||
result is persisted on the email's metadata at ingestion and a feed-level flag is
|
||||
projected into `feeds:list` so the dashboard stays at one KV read.
|
||||
|
||||
```
|
||||
ingestion (storeEmail)
|
||||
├─ infra: htmlToText(content) + extractLinks(content)
|
||||
├─ domain: detectConfirmation({subject, text, links}) → {score, links[]} | null
|
||||
├─ if detected → EmailMetadata.confirmation = { links }
|
||||
└─ Feed.ingest() raises FeedMetadata.pendingConfirmation = true
|
||||
→ FeedRepository.saveMetadata projects pendingConfirmation into feeds:list
|
||||
```
|
||||
|
||||
## 1. Detection
|
||||
|
||||
### `src/domain/confirmation.ts` (new, pure — no DOM)
|
||||
|
||||
```ts
|
||||
detectConfirmation(input: {
|
||||
subject: string;
|
||||
text: string; // plain-text rendition of the body
|
||||
links: { href: string; text: string }[];
|
||||
}): { score: number; links: string[] } | null
|
||||
```
|
||||
|
||||
- **Multilingual keyword lists** (FR/EN/DE/ES and extensible) for subject + body:
|
||||
`confirm`, `verify`, `activate`, `subscribe`, `confirmer`, `valider`,
|
||||
`activer`, `bestätigen`, `confirmar`, `verificar`, … (case/diacritic-insensitive
|
||||
matching).
|
||||
- **Link scoring** by anchor text + URL path/query signals: `/confirm`, `/verify`,
|
||||
`/activate`, `/subscribe`, `/opt-in`, `token=`, `confirm=`, `?c=`, etc.
|
||||
- **Combined score** = subject/body keyword signal + best link signal. Above a
|
||||
tuned `THRESHOLD` → return the ranked candidate links (top 3). Below → `null`.
|
||||
- Only `http(s):` links are ever considered/returned (no `javascript:`/`data:`/
|
||||
`mailto:`).
|
||||
- This module owns the business knowledge (keyword vocab, weights, threshold);
|
||||
it is unit-tested in isolation.
|
||||
|
||||
### `src/infrastructure/html-processor.ts` — `extractLinks`
|
||||
|
||||
```ts
|
||||
extractLinks(content: string): { href: string; text: string }[]
|
||||
```
|
||||
|
||||
- HTML: linkedom parse, collect `<a href>` + anchor text.
|
||||
- Plain text: regex URL fallback (href = url, text = url).
|
||||
- Infra owns DOM parsing; the domain receives plain data.
|
||||
|
||||
### `src/application/email-processor.ts` — wire-in
|
||||
|
||||
In `storeEmail`, before building `newEntry`:
|
||||
|
||||
```ts
|
||||
const text = htmlToText(input.content);
|
||||
const links = extractLinks(input.content);
|
||||
const confirmation = detectConfirmation({
|
||||
subject: input.subject,
|
||||
text,
|
||||
links,
|
||||
});
|
||||
// → EmailMetadata.confirmation = confirmation ? { links: confirmation.links } : undefined
|
||||
```
|
||||
|
||||
Computed once at reception. Dedup/ingest flow otherwise unchanged.
|
||||
|
||||
## 2. Data model (additive)
|
||||
|
||||
### `EmailMetadata` (`src/types/index.ts`)
|
||||
|
||||
```ts
|
||||
confirmation?: { links: string[] }; // present ⇒ detected; links = ranked top-3
|
||||
```
|
||||
|
||||
Presence powers the list badge and the detail section. Additive → pre-feature
|
||||
emails have nothing (no retroactive false positives).
|
||||
|
||||
### `FeedMetadata` (`src/types/index.ts`)
|
||||
|
||||
```ts
|
||||
pendingConfirmation?: boolean; // ≥1 unactioned confirmation email present
|
||||
```
|
||||
|
||||
### `FeedListItem` (`src/types/index.ts`)
|
||||
|
||||
```ts
|
||||
pendingConfirmation?: boolean; // projected from FeedMetadata for the dashboard
|
||||
```
|
||||
|
||||
### Aggregate `Feed` (`src/domain/feed.aggregate.ts`)
|
||||
|
||||
- `ingest()` sets `pendingConfirmation = true` when the new `EmailMetadata` carries
|
||||
`confirmation`.
|
||||
- `removeEmails()` recomputes the flag (false when no confirmation email remains).
|
||||
- `dismissConfirmation()` sets it to false.
|
||||
- read accessor `pendingConfirmation`.
|
||||
|
||||
### Persistence (`src/infrastructure/feed-repository.ts` + `feed-mapper.ts`)
|
||||
|
||||
- `FeedMetadata` round-trips `pendingConfirmation`.
|
||||
- **Sync invariant extended**: `saveMetadata` projects `pendingConfirmation` into
|
||||
the `feeds:list` item (today only `save`/`saveConfig` upsert the list). This is
|
||||
the one metadata-derived field the list carries; it keeps the dashboard at a
|
||||
single KV read instead of N per-feed metadata reads.
|
||||
|
||||
## 3. Admin UI
|
||||
|
||||
### a) Detail view — dedicated section (`routes/admin/emails.tsx`, `GET /emails/:emailKey`)
|
||||
|
||||
Above the Rendered/Raw toggle, shown when `email.confirmation`:
|
||||
|
||||
- Heading "Confirm your subscription".
|
||||
- Best-scored link as a **primary button**; remaining candidates as secondary
|
||||
links. URLs shown in clear text (transparency). `target="_blank" rel="noopener
|
||||
noreferrer"`.
|
||||
|
||||
### b) Email list badge (`routes/admin/emails.tsx`, `GET /feeds/:feedId/emails`)
|
||||
|
||||
A "Confirmation" badge in the subject cell of rows where `email.confirmation`
|
||||
exists, styled like the existing attachment indicator.
|
||||
|
||||
### c) Dashboard indicator (`routes/admin.tsx`, `GET /`)
|
||||
|
||||
A "Confirmation pending" pill on feeds whose `FeedListItem.pendingConfirmation` is
|
||||
true (list + table views), read with zero extra KV reads. Links to the feed's
|
||||
emails page.
|
||||
|
||||
### d) Feed emails-page banner (`routes/admin/emails.tsx`)
|
||||
|
||||
When `feedMetadata.pendingConfirmation`: a top banner "A confirmation email was
|
||||
detected" linking to the latest confirmation email, plus a "Mark as confirmed"
|
||||
button (dismiss).
|
||||
|
||||
### Post-creation redirect
|
||||
|
||||
`POST /admin/feeds/create` redirects to `/admin/feeds/:feedId/emails` (not the
|
||||
dashboard) so the user lands where the banner appears once the (async) confirmation
|
||||
email arrives.
|
||||
|
||||
## 4. Dismiss action
|
||||
|
||||
`POST /admin/feeds/:feedId/confirmation/dismiss`:
|
||||
|
||||
- load aggregate → `feed.dismissConfirmation()` → `repo.saveMetadata(feed)`
|
||||
(reprojects `pendingConfirmation:false` into `feeds:list`).
|
||||
- JSON response for the banner's fetch (mirrors the existing sender-filter
|
||||
pattern); redirect fallback for no-JS.
|
||||
- Protected by the existing admin auth + CSRF middleware.
|
||||
|
||||
"Dismiss" = "stop reminding me" (no real confirmation tracking without autoclick).
|
||||
Deleting the confirmation email(s) also clears the flag via `removeEmails`.
|
||||
|
||||
## Security
|
||||
|
||||
- v1 performs **no outbound request** → no SSRF surface.
|
||||
- Candidate `href`s filtered to `http(s):` only; never `javascript:`/`data:`.
|
||||
- Output escaped via normal hono/jsx rendering.
|
||||
|
||||
## Testing (TDD)
|
||||
|
||||
- `confirmation.test.ts` (domain): multilingual scoring, threshold, link ranking,
|
||||
negative cases (normal newsletter doesn't trigger), plain-text body.
|
||||
- `html-processor.test.ts`: `extractLinks` for HTML and plain text.
|
||||
- `email-processor.test.ts`: confirmation email → `EmailMetadata.confirmation`
|
||||
populated + `pendingConfirmation` raised; dedup/ingest otherwise unchanged.
|
||||
- `admin.test.ts` / emails tests: list badge, detail section, dashboard pill,
|
||||
banner, dismiss route (clears flag + reprojects into list).
|
||||
|
||||
Close green: `npx tsc --noEmit`, `npm test`, `npm run build`.
|
||||
|
||||
## Docs
|
||||
|
||||
- `README.md` + `INSTALL.md`: "Subscription confirmation surfacing" capability.
|
||||
- `docs/index.html` (landing): feature card — a genuine differentiator vs
|
||||
kill-the-newsletter.
|
||||
- `TODO.md`: check off `P1·M` "Subscription confirmation handling"; add a new
|
||||
`P2·M` "Confirmation on-detect action (none/autoclick/forward)" item capturing
|
||||
the deferred server options + SSRF/fallback notes.
|
||||
Reference in New Issue
Block a user