@core / email

1.0.0 ▾

1.0.0

verificadoMIT

GitHub

E-mail transacional com templates React Email tipados: Resend, SMTP ou console em dev

Código9 arquivosContexto~544 tokensanálise aprovada

~544 tokens→ src/lib/email/AGENTS.md→ .cursor/rules/genpm-core-email.mdc

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

@core/email — rules for AI agents

Purpose

Transactional email with typed templates: sendEmail('welcome', { to, props }). Providers: Resend (default), SMTP (optional, via nodemailer) and a console provider for development. Templates use React Email. No marketing lists, no queues, no tracking pixels.

Map

index.ts — public API: sendEmail, renderEmail, setEmailProvider, provider factories, TemplateProps.
send.ts — the template registry (templates) and sendEmail.
templates/*.ts — welcome, magicLink, receipt, plus the shared layout.ts.
providers.ts — EmailProvider interface and implementations.

Integration

Env: EMAIL_FROM ("App <hello@yourdomain.com>") and RESEND_API_KEY (verify the domain in Resend first). Without RESEND_API_KEY, outside production, emails are printed to the console. @types/react is only needed at build time: move it to devDependencies if GenPM added it to dependencies. SMTP instead: EMAIL_PROVIDER=smtp, SMTP_URL=smtps://user:pass@host:465 and install nodemailer.

Send from server code only:

import { sendEmail } from './lib/email/index.js';
await sendEmail('welcome', { to: user.email, props: { name: user.name, appUrl: 'https://app.example.com' } });

With @core/auth: send welcome after the first login (when the user was just created).
Verify: run the app without RESEND_API_KEY and check the console output.

Conventions

New template: create templates/<name>.ts exporting { subject(props), render(props) } built with createElement as h (no JSX, so it works with any jsxImportSource), then add it to templates and TemplateProps in send.ts. TypeScript then enforces its props everywhere.
Amounts in minor units (cents); links absolute (https://…).
Keep sendEmail calls out of request hot paths when possible (after the response, or in a job).

Don't

Don't send from the browser or expose RESEND_API_KEY to client code.
Don't interpolate untrusted HTML into templates; pass plain strings (React escapes them).
Don't log full email bodies in production (they may contain sign-in links).

# @core/email — rules for AI agents

## Purpose
Transactional email with typed templates: `sendEmail('welcome', { to, props })`. Providers: Resend (default), SMTP
(optional, via `nodemailer`) and a console provider for development. Templates use React Email. No marketing lists,
no queues, no tracking pixels.

## Map
- `index.ts` — public API: `sendEmail`, `renderEmail`, `setEmailProvider`, provider factories, `TemplateProps`.
- `send.ts` — the template registry (`templates`) and `sendEmail`.
- `templates/*.ts` — `welcome`, `magicLink`, `receipt`, plus the shared `layout.ts`.
- `providers.ts` — `EmailProvider` interface and implementations.

## Integration
1. Env: `EMAIL_FROM` (`"App <hello@yourdomain.com>"`) and `RESEND_API_KEY` (verify the domain in Resend first).
   Without `RESEND_API_KEY`, outside production, emails are printed to the console.
   `@types/react` is only needed at build time: move it to devDependencies if GenPM added it to dependencies.
   SMTP instead: `EMAIL_PROVIDER=smtp`, `SMTP_URL=smtps://user:pass@host:465` and install `nodemailer`.
2. Send from server code only:
   ```ts
   import { sendEmail } from './lib/email/index.js';
   await sendEmail('welcome', { to: user.email, props: { name: user.name, appUrl: 'https://app.example.com' } });
   ```
3. With `@core/auth`: send `welcome` after the first login (when the user was just created).
4. Verify: run the app without `RESEND_API_KEY` and check the console output.

## Conventions
- New template: create `templates/<name>.ts` exporting `{ subject(props), render(props) }` built with
  `createElement as h` (no JSX, so it works with any `jsxImportSource`), then add it to `templates` and
  `TemplateProps` in `send.ts`. TypeScript then enforces its props everywhere.
- Amounts in minor units (cents); links absolute (`https://…`).
- Keep `sendEmail` calls out of request hot paths when possible (after the response, or in a job).

## Don't
- Don't send from the browser or expose `RESEND_API_KEY` to client code.
- Don't interpolate untrusted HTML into templates; pass plain strings (React escapes them).
- Don't log full email bodies in production (they may contain sign-in links).

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

src/lib/email/send.tssomente leitura · 3e2976e

// sendEmail tipado por plantilla: el nombre elige las props obligatorias.
import { render, toPlainText } from '@react-email/render';
import { defaultProvider, type EmailProvider, type SendResult } from './providers.js';
import { type MagicLinkProps, magicLink } from './templates/magic-link.js';
import { type ReceiptProps, receipt } from './templates/receipt.js';
import { type WelcomeProps, welcome } from './templates/welcome.js';

export const templates = { welcome, magicLink, receipt } as const;
export type TemplateProps = { welcome: WelcomeProps; magicLink: MagicLinkProps; receipt: ReceiptProps };
export type TemplateName = keyof TemplateProps;

let provider: EmailProvider | null = null;

export function setEmailProvider(p: EmailProvider): void {
  provider = p;
}

export function getEmailProvider(): EmailProvider {
  provider ??= defaultProvider();
  return provider;
}

export async function renderEmail<K extends TemplateName>(name: K, props: TemplateProps[K]): Promise<{ subject: string; html: string; text: string }> {
  const t = templates[name] as unknown as { subject(p: TemplateProps[K]): string; render(p: TemplateProps[K]): Parameters<typeof render>[0] };
  const html = await render(t.render(props));
  return { subject: t.subject(props), html, text: toPlainText(html) };
}

export async function sendEmail<K extends TemplateName>(
  name: K,
  opts: { to: string | string[]; props: TemplateProps[K]; replyTo?: string; from?: string },
): Promise<SendResult> {
  const from = opts.from ?? process.env.EMAIL_FROM;
  if (!from) throw new Error('EMAIL_FROM is not set (e.g. "App <hello@example.com>")');
  const { subject, html, text } = await renderEmail(name, opts.props);
  return getEmailProvider().send({ from, to: opts.to, subject, html, text, ...(opts.replyTo ? { replyTo: opts.replyTo } : {}) });
}