@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/adapters/next.tssomente leitura · 48a34fe

// Adaptador Next.js (route handlers):
//   app/newsletter/subscribe/route.ts   → export { subscribeRoute as POST } from '@/lib/newsletter/adapters/next';
//   app/newsletter/confirm/route.ts     → export { confirmRoute as GET, confirmRoute as POST } from '@/lib/newsletter/adapters/next';
//   app/newsletter/unsubscribe/route.ts → export { unsubscribeRoute as GET, unsubscribeRoute as POST } from '@/lib/newsletter/adapters/next';
// y las páginas /newsletter/confirmed, /newsletter/unsubscribed y /newsletter/invalid.
import { handleConfirm, handleSubscribe, handleUnsubscribe } from './http.ts';

export const subscribeRoute = (req: Request) => handleSubscribe(req);
export const confirmRoute = (req: Request) => handleConfirm(req);
export const unsubscribeRoute = (req: Request) => handleUnsubscribe(req);

Versão	Commit	Publicado	Análise
1.1.0	48a34fe	há 7 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á 7 horas · genpm-system

Selo para o README

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