kempo-resend 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# kempo-resend
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sends the emails kempo logs through [Resend](https://resend.com). Kempo does not send email itself: it saves every email in its log (**Admin > Emails**) and hands it to an email extension through the `email:send` hook. This is that extension for Resend.
+
+It has no dependencies: it makes one HTTPS call to Resend's API per email.
+
+## Setup
+
+1. Install it from Admin > Extensions.
+2. On **Admin > Settings**, open the **Resend** tab and paste your API key (from [resend.com/api-keys](https://resend.com/api-keys)). It is stored encrypted and never shown again.
+3. Choose what Resend sends as. Either set **Email from** (System tab) to an address on a domain you have verified with Resend, such as `Your Shop <orders@yourdomain.com>`, or set **Resend From** on the Resend tab, which is used for Resend only and wins over Email from. Resend refuses any other sender.
+
+   **Trying it before you verify a domain:** put `onboarding@resend.dev` in **Resend From** on the Resend tab. Resend lets any account send as that address, but only to the email address you signed up to Resend with.
+4. On **Admin > Emails**, press **Send a test email** to check it.
+
+`SETTINGS_ENCRYPTION_KEY` must be set on the server (kempo makes one for you the first time it starts), because the key is stored encrypted.
+
+**Coming from kempo before email extensions:** the key used to be `RESEND_API_KEY` in `.env`. If that is still set when you install this and no key is saved here, it is saved as the setting for you. The `.env` value is left alone.
+
+## What it does
+
+For each email kempo asks to send, the handler posts `{ from, to, subject, html }` to `https://api.resend.com/emails` with `Authorization: Bearer <key>`, and answers kempo with `{ sent: true, provider: 'resend', messageId }` (the id Resend gives) or `{ sent: false, error }`. Kempo records the result in the log, tries a failed email again (the **Email max retries** setting, 1 by default), and keeps the log for the retention settings. A failure shows in the log in Resend's own words:
+
+| Resend says | The log says |
+|---|---|
+| 401, or 403 about the key | Resend did not accept the API key |
+| 403 about a domain | Resend: The example.com domain is not verified |
+| 422 | Resend: Invalid `to` field |
+| 429 | Resend: Too many requests |
+
+With no key saved the handler answers that it did not send, so if another email extension is installed (kempo-smtp), it gets the email instead. The first one to send it ends the chain.
+
+## Settings
+
+| Setting | Meaning |
+|---|---|
+| `resend_api_key` | Secret. Your Resend API key |
+| `resend_from` | Optional. The address to send as through Resend, instead of Email from. Empty uses Email from |
+
+## Tests
+
+`npm test` covers the request, every kind of failure and the key migration with a fake `fetch`. It never contacts Resend.

package/admin/settings-tab.global.html

@@ -0,0 +1 @@
+<content id="kempo-resend-settings-tab" name="Resend settings tab" owner="kempo-resend" enabled="true" locked="true" location="admin-settings-tabs" priority="20"><k-settings-tab name="resend" label="Resend" position="400"><k-settings-panel owner="kempo-resend"></k-settings-panel></k-settings-tab></content>

package/hooks/send.js

@@ -0,0 +1,13 @@
+import { getSetting } from 'kempo/server/sdk.js';
+import { sendWithResend } from '../server/utils/resend.js';
+
+/*
+  The `email:send` handler: sends the email through Resend (as the Resend tab's From address when one is set, else as the site's
+  Email from) and says how it went (kempo keeps the log). With no API key saved it answers
+  that it did not send, so another email extension, if there is one, gets its turn.
+*/
+export default async ({ email }) => {
+  const [, apiKey] = await getSetting('kempo-resend', 'resend_api_key', '');
+  const [, from] = await getSetting('kempo-resend', 'resend_from', '');
+  return sendWithResend({ apiKey, email, from });
+};

package/install.js

@@ -0,0 +1,24 @@
+import { getSetting, setSetting } from 'kempo/server/sdk.js';
+
+/*
+  Before kempo had email extensions its Resend key was `RESEND_API_KEY` in the site's .env. If that is set and no key is saved yet, it is
+  saved as this extension's setting (encrypted), so a site that already used Resend only has to install this. The .env value is left
+  alone, and once a key is saved here it is never overwritten.
+*/
+export const migrateKey = ({ env, saved }) => (!saved && env ? env.trim() : '');
+
+export default async () => {
+  if(!process.env.SETTINGS_ENCRYPTION_KEY){
+    console.warn('[kempo-resend] SETTINGS_ENCRYPTION_KEY is not set, so the Resend API key cannot be stored. Start the server once to have kempo make one, then reinstall this extension.');
+    return;
+  }
+
+  const [, saved] = await getSetting('kempo-resend', 'resend_api_key', '');
+  const key = migrateKey({ env: process.env.RESEND_API_KEY, saved });
+  if(key){
+    const [error] = await setSetting('kempo-resend', 'resend_api_key', key, 'secret', false, 'Your Resend API key, from resend.com/api-keys. Stored encrypted and never shown again. The address emails are sent from must be on a domain you have verified with Resend');
+    if(error) console.warn(`[kempo-resend] The key from RESEND_API_KEY could not be saved: ${error.msg}`);
+    else console.log('[kempo-resend] Saved RESEND_API_KEY from the environment as the Resend API key setting.');
+  }
+  console.log('[kempo-resend] Installed. Add your Resend API key on the Resend tab of the Settings page, and set the Email from address (on a domain verified with Resend).');
+};

package/kempo-config.json

@@ -0,0 +1,21 @@
+{
+  "docs": "https://github.com/dustinpoissant/kempo-resend#readme",
+  "git": "https://github.com/dustinpoissant/kempo-resend",
+  "hooks": {
+    "email:send": "./hooks/send.js"
+  },
+  "settings": [
+    {
+      "name": "resend_from",
+      "value": "",
+      "type": "string",
+      "description": "The address to send as through Resend, instead of the site's Email from setting, as name@yourdomain.com or Shop Name <name@yourdomain.com>. Leave empty to use Email from. For testing, Resend lets any account send as onboarding@resend.dev, but only to the address you signed up to Resend with"
+    },
+    {
+      "name": "resend_api_key",
+      "value": "",
+      "type": "secret",
+      "description": "Your Resend API key, from resend.com/api-keys. Stored encrypted and never shown again. The address emails are sent from must be on a domain you have verified with Resend"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "kempo-resend",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Sends the emails kempo logs through Resend (resend.com), with the API key kept as an encrypted setting.",
+  "license": "MIT",
+  "author": "Dustin Poissant",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "admin",
+    "hooks",
+    "server",
+    "install.js",
+    "update.js",
+    "uninstall.js",
+    "kempo-config.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dustinpoissant/kempo-resend.git"
+  },
+  "peerDependencies": {
+    "kempo": ">=4.8.0"
+  },
+  "exports": {
+    "./install": "./install.js",
+    "./update": "./update.js",
+    "./uninstall": "./uninstall.js"
+  }
+}

package/server/utils/resend.js

@@ -0,0 +1,47 @@
+/*
+  Sending one email through Resend's HTTP API (resend.com/docs/api-reference/emails/send-email). It is given the key and a `fetch`, so it
+  is tested with a fake one and Resend is never needed. There is no SDK: the call is one POST.
+
+  `POST https://api.resend.com/emails` with `Authorization: Bearer <key>` and `{ from, to, subject, html }`. A success is 200 with
+  `{ id }`. A failure is a 4xx or 5xx with `{ statusCode, name, message }`, such as 401 for a bad key, 403 for a sender address on a
+  domain that is not verified, 422 for an address that is not valid, 429 when sending too fast.
+*/
+export const ENDPOINT = 'https://api.resend.com/emails';
+
+/* name@example.com, or Shop Name <name@example.com>, on one line. */
+export const isAddress = value => typeof value === 'string' && value.length <= 200 && /^(?:[^<>\r\n@]+<[^<>\s@]+@[^<>\s@]+\.[^<>\s@]+>|[^<>\s@]+@[^<>\s@]+\.[^<>\s@]+)$/.test(value.trim());
+
+/*
+  `from` is the Resend tab's own sender, which wins over the site's (`email.from`) when it is set, so Resend can send as an address that is on
+  a domain verified with it (or as onboarding@resend.dev while testing) whatever the rest of the site sends as.
+
+  Resolves to `{ sent: true, provider, messageId }` or `{ sent: false, error }` (with `skipped: true` when there is no key, so kempo knows it did not try): what an email:send handler answers. It never throws. */
+export const sendWithResend = async ({ apiKey, email, from: override = '', fetchImpl = globalThis.fetch }) => {
+  if(!apiKey) return { sent: false, skipped: true, error: 'No Resend API key is saved. Add one on the Resend tab of the Settings page' };
+
+  const from = String(override ?? '').trim() || email.from;
+  if(override && String(override).trim() && !isAddress(String(override).trim())) return { sent: false, error: `The Resend From setting (${String(override).trim()}) must look like name@yourdomain.com or Shop Name <name@yourdomain.com>` };
+
+  let response;
+  try {
+    response = await fetchImpl(ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify({ from, to: [email.to], subject: email.subject, html: email.html }),
+    });
+  } catch(error) {
+    return { sent: false, error: `Resend could not be reached: ${error?.message ?? 'no answer'}` };
+  }
+
+  let body = null;
+  try { body = await response.json(); } catch { /* an answer that is not JSON is reported by its status */ }
+
+  if(response.status === 401 || (response.status === 403 && /api key/i.test(body?.message ?? ''))) return { sent: false, error: 'Resend did not accept the API key' };
+  if(!response.ok){
+    const reason = body?.message ?? `answered ${response.status}`;
+    const sender = /domain/i.test(reason) && [403, 422].includes(response.status) ? ` (it was sent as ${from}). Set ${String(override ?? '').trim() ? 'Resend From on the Resend tab' : 'Email from, on the System tab of the Settings page,'} to an address on a domain verified with Resend` : '';
+    return { sent: false, error: `Resend: ${reason}${sender}` };
+  }
+  if(!body?.id) return { sent: false, error: 'Resend answered without saying the email was accepted' };
+  return { sent: true, provider: 'resend', messageId: body.id };
+};

package/uninstall.js

@@ -0,0 +1,2 @@
+/* The hook and the setting are removed with the extension, so there is nothing to undo. */
+export default async () => {};

package/update.js

@@ -0,0 +1,6 @@
+import install from './install.js';
+
+/* An update repeats the install, which only ever adds a key that is not saved yet. */
+export default async () => {
+  await install();
+};