@core / newsletter

1.1.0 ▾

1.1.0

verificadoMIT

GitHub

Newsletter: double opt-in, descadastro em um clique (RFC 8058), tags e campanhas em lotes retomáveis

Código11 arquivosContexto~889 tokensanálise aprovada

~889 tokens→ src/lib/newsletter/AGENTS.md→ .cursor/rules/genpm-core-newsletter.mdc

Isto é exatamente o que sua IA lê quando trabalha em src/lib/newsletter. Nada mais é adicionado ao contexto dela.

Purpose

Own-list newsletter: sign-ups with double opt-in and consent record, tags, one-click unsubscribe (RFC 8058 headers, required by Gmail/Yahoo for bulk senders) plus a visible link and postal address in every email, rich-text campaigns sent in resumable batches by @core/jobs (no duplicates), bounce/complaint suppression and GDPR erasure. Tables: subscribers, newsletter_campaigns, newsletter_sends. No open-tracking pixels, no automations.

Map

index.ts — public API: subscribe, confirmSubscription, unsubscribe, createCampaign, sendCampaign, markUndeliverable, deleteSubscriber, newsletterAdminResources, setNewsletterMessages.
newsletter.ts — logic and jobs. sender.ts — sending (Resend API with headers, or @core/email in dev). tokens.ts — signed links.
adapters/hono.ts — newsletterRoutes(). adapters/next.ts — subscribeRoute, confirmRoute, unsubscribeRoute.

Integration

Env: NEWSLETTER_FROM, NEWSLETTER_POSTAL_ADDRESS (legal requirement), NEWSLETTER_SECRET (≥ 32 chars), SITE_URL, and RESEND_API_KEY in production (other providers: implement NewsletterSender and call setNewsletterSender). Verify the sending domain (SPF, DKIM, DMARC) with the provider — tell the user how; you can't do it for them.
Migrations as in src/lib/db/AGENTS.md; the @core/jobs cron must run.
Routes under /newsletter (Hono app.route('/newsletter', newsletterRoutes()), or the Next handlers) and three simple pages: /newsletter/confirmed, /newsletter/unsubscribed, /newsletter/invalid. confirm and unsubscribe need GET and POST: GET only renders a minimal page with a button (mail link scanners open every URL), the button POSTs and acts; any other POST to unsubscribe is the RFC 8058 one-click (200, no redirect). Translate the page with texts (newsletterRoutes({ texts }) or the handlers' third argument).
Sign-up form: POST /newsletter/subscribe with email, the @core/antispam fields and an unchecked, required consent checkbox consent whose text version goes in a hidden consentVersion (with consentVersion, the server rejects the sign-up unless consent is checked: consent_required). Always show the same "check your inbox" message. A plain HTML form posted from the same site (Accept: text/html and a same-host Referer, what browsers send) is redirected back with ?newsletter=<status>#newsletter; other clients get JSON (202, or 400/429 with error).
Translate system emails with setNewsletterMessages((locale) => ({ confirmSubject, confirmText, unsubscribeLabel })).
Add ...newsletterAdminResources() to src/genpm/admin.ts; wire the provider's bounce/complaint webhook to markUndeliverable.
Verify: subscribe, open the confirmation link, send a campaign to yourself and unsubscribe with one click.

Conventions

Only active (confirmed) subscribers receive campaigns; tags segment them.
Batches claim recipients atomically (newsletter_sends.status = 'sending', FOR UPDATE SKIP LOCKED), so concurrent batch jobs never mail the same subscriber twice; claims older than 15 min (a dead worker) are retried.
Permissions: subscribers:read|update|delete, campaigns:read|create|update|send.

Don't

Don't import contacts without documented consent, and never pre-check the consent box.
Don't send campaigns from a request handler or remove the unsubscribe link/headers.
Don't reveal whether an email is already subscribed.

# @core/newsletter — rules for AI agents

## Purpose
Own-list newsletter: sign-ups with double opt-in and consent record, tags, one-click unsubscribe (RFC 8058 headers,
required by Gmail/Yahoo for bulk senders) plus a visible link and postal address in every email, rich-text campaigns
sent in resumable batches by @core/jobs (no duplicates), bounce/complaint suppression and GDPR erasure.
Tables: `subscribers`, `newsletter_campaigns`, `newsletter_sends`. No open-tracking pixels, no automations.

## Map
- `index.ts` — public API: `subscribe`, `confirmSubscription`, `unsubscribe`, `createCampaign`, `sendCampaign`, `markUndeliverable`, `deleteSubscriber`, `newsletterAdminResources`, `setNewsletterMessages`.
- `newsletter.ts` — logic and jobs. `sender.ts` — sending (Resend API with headers, or @core/email in dev). `tokens.ts` — signed links.
- `adapters/hono.ts` — `newsletterRoutes()`. `adapters/next.ts` — `subscribeRoute`, `confirmRoute`, `unsubscribeRoute`.

## Integration
1. Env: `NEWSLETTER_FROM`, `NEWSLETTER_POSTAL_ADDRESS` (legal requirement), `NEWSLETTER_SECRET` (≥ 32 chars), `SITE_URL`,
   and `RESEND_API_KEY` in production (other providers: implement `NewsletterSender` and call `setNewsletterSender`).
   Verify the sending domain (SPF, DKIM, DMARC) with the provider — tell the user how; you can't do it for them.
2. Migrations as in `src/lib/db/AGENTS.md`; the @core/jobs cron must run.
3. Routes under `/newsletter` (Hono `app.route('/newsletter', newsletterRoutes())`, or the Next handlers) and three
   simple pages: `/newsletter/confirmed`, `/newsletter/unsubscribed`, `/newsletter/invalid`. `confirm` and `unsubscribe`
   need GET and POST: GET only renders a minimal page with a button (mail link scanners open every URL), the button
   POSTs and acts; any other POST to `unsubscribe` is the RFC 8058 one-click (200, no redirect). Translate the page
   with `texts` (`newsletterRoutes({ texts })` or the handlers' third argument).
4. Sign-up form: `POST /newsletter/subscribe` with `email`, the @core/antispam fields and an unchecked, required consent
   checkbox `consent` whose text version goes in a hidden `consentVersion` (with `consentVersion`, the server rejects
   the sign-up unless `consent` is checked: `consent_required`). Always show the same "check your inbox" message.
   A plain HTML form posted from the same site (`Accept: text/html` and a same-host `Referer`, what browsers send) is
   redirected back with `?newsletter=<status>#newsletter`; other clients get JSON (202, or 400/429 with `error`).
5. Translate system emails with `setNewsletterMessages((locale) => ({ confirmSubject, confirmText, unsubscribeLabel }))`.
6. Add `...newsletterAdminResources()` to `src/genpm/admin.ts`; wire the provider's bounce/complaint webhook to `markUndeliverable`.
7. Verify: subscribe, open the confirmation link, send a campaign to yourself and unsubscribe with one click.

## Conventions
- Only `active` (confirmed) subscribers receive campaigns; tags segment them.
- Batches claim recipients atomically (`newsletter_sends.status = 'sending'`, `FOR UPDATE SKIP LOCKED`), so concurrent
  batch jobs never mail the same subscriber twice; claims older than 15 min (a dead worker) are retried.
- Permissions: `subscribers:read|update|delete`, `campaigns:read|create|update|send`.

## Don't
- Don't import contacts without documented consent, and never pre-check the consent box.
- Don't send campaigns from a request handler or remove the unsubscribe link/headers.
- Don't reveal whether an email is already subscribed.

A árvore exata que será injetada, após o .genpmignore. Fixada em

src/lib/newsletter/LICENSEsomente leitura · 48a34fe

MIT License

Copyright (c) 2026 GenPM

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Versão	Commit	Publicado	Análise
1.1.0	48a34fe	há 6 horas	análise aprovada

$genpm add @core/newsletter

Injeta: src/lib/newsletter
Commit
Tag: v1.1.0
Requer: @core/antispam ^1.0.0 @core/contracts ^1.0.0 @core/db ^1.0.0 @core/email ^1.0.1 @core/jobs ^1.0.0 @core/rich-text ^1.0.0
npm: zod ^4.0.0
Env: NEWSLETTER_FROM NEWSLETTER_POSTAL_ADDRESS NEWSLETTER_SECRET SITE_URL
Qualidade: 100/100
Usado por: 1
Instalações: 0 / 30d
Publicado: há 6 horas · genpm-system

Selo para o README

[![genpm](https://api.genpm.net/v1/badge/@core/newsletter.svg)](https://genpm.net/p/@core/newsletter)