@farm.js/email 0.1.50 → 0.1.51-beta.1

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.
Files changed (2) hide show
  1. package/README.md +110 -3
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,11 +1,118 @@
1
1
  # @farm.js/email
2
2
 
3
- Email and Resend integration for Farm.js
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
- npm install @farm.js/email
12
+ pnpm add @farm.js/email
9
13
  ```
10
14
 
11
- See the [Farm.js repository](https://github.com/farming-labs/farm.js) for documentation, examples, and support.
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.50",
3
+ "version": "0.1.51-beta.1",
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/core": "0.1.50",
39
- "@farm.js/integration-utils": "0.1.50"
38
+ "@farm.js/core": "0.1.51-beta.1",
39
+ "@farm.js/integration-utils": "0.1.51-beta.1"
40
40
  },
41
41
  "devDependencies": {
42
42
  "@types/react": "19.2.13"