packages/ at markup-kit dd1e6eb5270e
A snapshot of packages/ in the Weft repository; the official packages are published from these commits. Markup-Kit-Commit: dd1e6eb5270e62e0c8b6c202b3d01f0da6e00ddc
This commit is contained in:
commit
306b143104
72 changed files with 10915 additions and 0 deletions
132
email/README.md
Normal file
132
email/README.md
Normal file
|
|
@ -0,0 +1,132 @@
|
|||
# @weft/email
|
||||
|
||||
Email for Weft: sending through Resend and Postmark, MIME messages with attachments, and templates that render to HTML and
|
||||
text. Its only capabilities are `http.fetch@api.resend.com`, `http.fetch@api.postmarkapp.com` and `http.media`, because its
|
||||
`Img` component shows the image a template names.
|
||||
|
||||
```sh
|
||||
weft add weft/email
|
||||
```
|
||||
|
||||
```weft
|
||||
import { send } from "@weft/email"
|
||||
import { resend } from "@weft/email/resend"
|
||||
import { document } from "@weft/email/template"
|
||||
import { render } from "std/app"
|
||||
import { env } from "std/process"
|
||||
import Receipt from "./Receipt"
|
||||
|
||||
let mail = resend({ apiKey: env("RESEND_API_KEY")! })
|
||||
|
||||
let body = document(render(Receipt, { name: "Ana", total: "19,99 €" }), {
|
||||
title: "Your receipt",
|
||||
preheader: "Thanks for your order",
|
||||
footer: "Example d.o.o., Ljubljana",
|
||||
})
|
||||
let sent = try await send(mail, {
|
||||
from: { email: "info@example.com", name: "Example" },
|
||||
to: ["ana@example.com"],
|
||||
subject: "Your receipt",
|
||||
html: body.html,
|
||||
text: body.text,
|
||||
})
|
||||
```
|
||||
|
||||
```weft file=Receipt.weft
|
||||
import Button from "@weft/email/components/Button"
|
||||
import Facts from "@weft/email/components/Facts"
|
||||
import H1 from "@weft/email/components/H1"
|
||||
import P from "@weft/email/components/P"
|
||||
import Strong from "@weft/email/components/Strong"
|
||||
|
||||
prop name: string
|
||||
prop total: string
|
||||
---
|
||||
<H1>Thank you!</H1>
|
||||
<P>Hi <Strong>{name}</Strong>, your payment came through.</P>
|
||||
<Facts rows={[["Total", total]]} />
|
||||
<Button url="https://example.com/orders" label="Your orders" />
|
||||
```
|
||||
|
||||
## Modules
|
||||
|
||||
| module | what |
|
||||
|---|---|
|
||||
| `@weft/email` | `Message`, `send`, `validate`, `allowlist`, `memory` and `outbox` for tests |
|
||||
| `@weft/email/resend` | `resend({ apiKey })` |
|
||||
| `@weft/email/postmark` | `postmark({ serverToken, messageStream? })` |
|
||||
| `@weft/email/mime` | `toMime(message)`, the message as RFC 5322 text |
|
||||
| `@weft/email/template` | `document`, `isSafeUrl` |
|
||||
| `@weft/email/components/…` | `H1`, `H2`, `P`, `Strong`, `Em`, `A`, `Img`, `Ul`, `Ol`, `Facts`, `Button`, `Hr` |
|
||||
|
||||
## Messages
|
||||
|
||||
`send` validates a message before anything leaves. A line break in a subject, a display name or a header is refused, because it
|
||||
would let whoever typed that text add headers of their own, such as a `Bcc`.
|
||||
|
||||
```weft
|
||||
try await send(mail, {
|
||||
from: { email: "info@example.com", name: "Example" },
|
||||
to: ["ana@example.com"],
|
||||
replyTo: "owner@example.com",
|
||||
subject: "Your ticket",
|
||||
html: body.html,
|
||||
text: body.text,
|
||||
headers: [["List-Unsubscribe", "<https://example.com/unsubscribe?id=1>"]],
|
||||
attachments: [
|
||||
{ filename: "ticket.pdf", content: pdf, type: "application/pdf" },
|
||||
{ filename: "logo.png", content: logo, type: "image/png", contentId: "logo" }, // <img src="cid:logo">
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
## Errors are values
|
||||
|
||||
| `EmailError` | what to do |
|
||||
|---|---|
|
||||
| `InvalidMessage { field, message }` | fix the message: nothing was attempted |
|
||||
| `Rejected { status, code, message }` | a bad key, an unverified domain, a suppressed address: sending it again won't help |
|
||||
| `RateLimited { message, retryAfter }` | try again later |
|
||||
| `ProviderFailure { status, message }` | try again later |
|
||||
| `ConnectionFailed { message }` | the message **may** have been sent |
|
||||
| `BadResponse { message }` | the message may have been sent |
|
||||
|
||||
Nothing is retried for you, because sending an email twice is worse than a delay. With Resend, `idempotencyKey` makes a repeat
|
||||
safe:
|
||||
|
||||
```weft
|
||||
let mail = resend({ apiKey, idempotencyKey: m => `order-${orderId}` })
|
||||
```
|
||||
|
||||
## Staging
|
||||
|
||||
`allowlist` sends only to the addresses listed, and skips the rest without failing, so a staging site can't email real customers.
|
||||
`"*"` lifts the limit:
|
||||
|
||||
```weft
|
||||
let mail = allowlist(resend({ apiKey }), (env("EMAIL_ALLOWLIST") ?? "info@example.com").split(","))
|
||||
```
|
||||
|
||||
In tests, `memory()` keeps messages in `outbox()` instead of sending them.
|
||||
|
||||
## Templates
|
||||
|
||||
A template is a Weft component. `render` from `std/app` turns it into HTML with inline styles and a text version that reads as if a
|
||||
person wrote it. Everything a component shows is escaped, and a link that isn't `http`, `https`, `mailto`, `tel` or `cid` keeps
|
||||
only its text. Your own markup works too: classes become inline styles, and `hover:`, `dark:` and breakpoint classes are left out.
|
||||
|
||||
`document` wraps a rendered template in the whole email, a centred column that works in mail clients.
|
||||
|
||||
## What has and hasn't been tested
|
||||
|
||||
`node packages/email/scripts/integration.mjs` sends through both providers' APIs to a scripted server, and checks a full message
|
||||
with Python's `email` parser, an independent reader of the MIME. `weft test tests/email.test.weft` covers validation, encoding,
|
||||
payloads and templates. **No email has been sent through Resend or Postmark themselves**: the payloads follow their API references,
|
||||
so try a test key before relying on this.
|
||||
|
||||
## Limits
|
||||
|
||||
- **No SMTP.** `std` has no TCP or TLS sockets, so this package can't talk to a mail server. `toMime` already writes what SMTP's
|
||||
`DATA` needs, so only the socket is missing.
|
||||
- **It reaches only Resend's and Postmark's API hosts.** As a dependency, a `baseUrl` on any other host fails with a
|
||||
`CapabilityError`. To point it at a test server, the app lists that host in `allow` too, beside the two API hosts.
|
||||
Loading…
Reference in a new issue