@farm.js/email 0.1.50 → 0.1.51-beta.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +110 -3
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,11 +1,118 @@
|
|
|
1
1
|
# @farm.js/email
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Transactional email for Farm.js applications, sent through Resend. Templates are React components
|
|
4
|
+
registered under typed ids, and the integration mounts routes to send, schedule, and preview them,
|
|
5
|
+
list them, and receive Resend webhooks.
|
|
4
6
|
|
|
5
7
|
See [Stability and Support](https://farmjs.dev/docs/stability) for what this package guarantees.
|
|
6
8
|
|
|
9
|
+
## Install
|
|
10
|
+
|
|
7
11
|
```bash
|
|
8
|
-
|
|
12
|
+
pnpm add @farm.js/email
|
|
9
13
|
```
|
|
10
14
|
|
|
11
|
-
|
|
15
|
+
`resend` and `@react-email/render` are dependencies, and `react` is a peer dependency. To scaffold
|
|
16
|
+
the registry entry and an email console at `/integrations/resend` in an existing app, run
|
|
17
|
+
`farm add integration resend --ui`.
|
|
18
|
+
|
|
19
|
+
## Configure
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
// src/lib/integrations.ts
|
|
23
|
+
import { resend, template } from "@farm.js/email";
|
|
24
|
+
import { WelcomeEmail } from "../emails/welcome";
|
|
25
|
+
import { getUser } from "./session";
|
|
26
|
+
|
|
27
|
+
export const appIntegrations = {
|
|
28
|
+
email: resend({
|
|
29
|
+
defaults: { from: "Acme <hello@acme.dev>" },
|
|
30
|
+
templates: {
|
|
31
|
+
welcome: template(WelcomeEmail, {
|
|
32
|
+
subject: ({ name }) => `Welcome, ${name}`,
|
|
33
|
+
}),
|
|
34
|
+
},
|
|
35
|
+
async authorize(request) {
|
|
36
|
+
return Boolean(await getUser(request));
|
|
37
|
+
},
|
|
38
|
+
}),
|
|
39
|
+
} as const;
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`template(Component, config)` takes the component first, so `data` is typed from its props. The
|
|
43
|
+
config sets `subject` and may set `previewText`, `from`, and `replyTo`, each a value or a function
|
|
44
|
+
of the data.
|
|
45
|
+
|
|
46
|
+
| Variable | Purpose |
|
|
47
|
+
| ----------------------- | ------------------------------------------------------------------------ |
|
|
48
|
+
| `RESEND_API_KEY` | Builds the Resend client. Required unless `instance` or `apiKey` is set. |
|
|
49
|
+
| `RESEND_FROM_EMAIL` | Default sender when a template and `defaults.from` set none. |
|
|
50
|
+
| `RESEND_REPLY_TO_EMAIL` | Default reply-to address. |
|
|
51
|
+
| `RESEND_WEBHOOK_SECRET` | Default secret for the webhook route. |
|
|
52
|
+
|
|
53
|
+
Sending fails without a sender from the template, `defaults.from`, or `RESEND_FROM_EMAIL`.
|
|
54
|
+
|
|
55
|
+
## Who can send
|
|
56
|
+
|
|
57
|
+
The send, schedule, and preview routes spend the app's Resend credits and send from its verified
|
|
58
|
+
domain, so they refuse anonymous callers.
|
|
59
|
+
|
|
60
|
+
- Pass `authorize(request, { route })`. Return `true` to allow, `false` for `401`, or a `Response`.
|
|
61
|
+
- Without `authorize`, the routes answer `401` unless `allowUnauthenticated: true` is set, which is
|
|
62
|
+
only for apps that already gate the base path in middleware.
|
|
63
|
+
- Requests from other origins get `403` unless listed in `allowedOrigins`.
|
|
64
|
+
- Callers cannot set `from`, `replyTo`, `cc`, `bcc`, `attachments`, `tags`, or `topicId` unless
|
|
65
|
+
`allowCallerHeaders: true` is set. `to` always comes from the caller, so check it in `authorize`.
|
|
66
|
+
|
|
67
|
+
## Send and schedule
|
|
68
|
+
|
|
69
|
+
Call the routes through `apiClient` or `api` from `createIntegrations` in `@farm.js/core/client`.
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
const sent = await apiClient.email.send({
|
|
73
|
+
body: { templateId: "welcome", to: "ada@example.com", data: { name: "Ada" } },
|
|
74
|
+
});
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
import { emailSchedule } from "@farm.js/email/schedule";
|
|
79
|
+
|
|
80
|
+
await apiClient.email.schedule({
|
|
81
|
+
body: {
|
|
82
|
+
templateId: "welcome",
|
|
83
|
+
to: "ada@example.com",
|
|
84
|
+
data: { name: "Ada" },
|
|
85
|
+
when: emailSchedule.after.minutes(30),
|
|
86
|
+
},
|
|
87
|
+
});
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
`when` accepts a `Date`, a number of seconds from now, an `emailSchedule` delay or preset, or a
|
|
91
|
+
string, which is passed to Resend as is.
|
|
92
|
+
|
|
93
|
+
## Routes
|
|
94
|
+
|
|
95
|
+
| Route | Purpose |
|
|
96
|
+
| -------------------------- | -------------------------------------------------------------- |
|
|
97
|
+
| `POST /api/email/send` | Render and send a template. |
|
|
98
|
+
| `POST /api/email/schedule` | Render and schedule a template. |
|
|
99
|
+
| `POST /api/email/preview` | Render a template without sending it. |
|
|
100
|
+
| `GET /api/email/templates` | List template ids and preview props. Not gated by `authorize`. |
|
|
101
|
+
| `POST /api/email/webhook` | Verify a Resend event and call `onEvent`. |
|
|
102
|
+
|
|
103
|
+
`basePath` moves them all. The webhook route mounts only when `webhooks` is set, with its secret
|
|
104
|
+
defaulting to `RESEND_WEBHOOK_SECRET`. A failed verification gets `400`, and `onError` can return a
|
|
105
|
+
response of its own.
|
|
106
|
+
|
|
107
|
+
## Entry points
|
|
108
|
+
|
|
109
|
+
`@farm.js/email/client` exports `template`, `resendClient`, `createResendClientApi`, and the types
|
|
110
|
+
without loading the Resend SDK. `@farm.js/email/schedule` exports `emailSchedule` on its own.
|
|
111
|
+
|
|
112
|
+
## Documentation
|
|
113
|
+
|
|
114
|
+
- [Email integration](https://farmjs.dev/docs/integrations/email)
|
|
115
|
+
- [`examples/email-integrations/resend-example`](https://github.com/farming-labs/farm.js/tree/main/examples/email-integrations/resend-example)
|
|
116
|
+
|
|
117
|
+
Report issues and find examples in the
|
|
118
|
+
[Farm.js repository](https://github.com/farming-labs/farm.js).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@farm.js/email",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.51-beta.0",
|
|
4
4
|
"description": "Email and Resend integration for Farm.js",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -35,8 +35,8 @@
|
|
|
35
35
|
"dependencies": {
|
|
36
36
|
"@react-email/render": "2.0.6",
|
|
37
37
|
"resend": "6.10.0",
|
|
38
|
-
"@farm.js/
|
|
39
|
-
"@farm.js/
|
|
38
|
+
"@farm.js/integration-utils": "0.1.51-beta.0",
|
|
39
|
+
"@farm.js/core": "0.1.51-beta.0"
|
|
40
40
|
},
|
|
41
41
|
"devDependencies": {
|
|
42
42
|
"@types/react": "19.2.13"
|