emdash-aws-ses 1.0.2 → 1.0.3

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 +159 -0
  2. package/package.json +9 -1
package/README.md ADDED
@@ -0,0 +1,159 @@
1
+ # emdash-aws-ses
2
+
3
+ A standalone, lightweight SMTP email transport plugin for **EmDash CMS** designed to route all system emails securely through **Amazon SES (Simple Email Service)**.
4
+
5
+ By registering exclusively with EmDash’s mail delivery hooks, this plugin routes all native transactional emails (including passwordless magic links, collaborator invitations, and system notifications) through your AWS infrastructure.
6
+
7
+ ---
8
+
9
+ ## Features
10
+
11
+ * **Exclusive Email Routing:** Intercepts the global EmDash `email:deliver` hook with `exclusive: true` to route all outgoing mail using secure SMTP transport powered by `nodemailer`.
12
+ * **Interactive Block Kit UI:** Provides a built-in, responsive configuration and test dashboard directly inside the EmDash administrative panel.
13
+ * **Secure Database Persistence:** Saves your SMTP credentials securely inside your active database (SQLite or PostgreSQL) via the native EmDash key-value (`ctx.kv`) store.
14
+ * **Built-in Diagnostics:** Validates SMTP server handshakes and sends HTML/plaintext test emails to any recipient directly from the visual test tab.
15
+
16
+ ---
17
+
18
+ ## Prerequisites
19
+
20
+ Before installing the plugin, ensure you have configured your AWS environment:
21
+ 1. **Verified Identity:** Confirm that your sender domain (e.g., `your-domain.com`) or specific email address (e.g., `info@your-domain.com`) is verified in your **Amazon SES** console. Unverified identities will be rejected by AWS.
22
+ 2. **SMTP Credentials:** Go to the *SMTP Settings* tab in your Amazon SES console and click **Create SMTP Credentials** to generate a dedicated IAM SMTP Username and SMTP Password.
23
+
24
+ ---
25
+
26
+ ## Installation
27
+
28
+ Install the package into your main Astro + EmDash website directory:
29
+
30
+ ### From the public npm registry (Recommended):
31
+ ```bash
32
+ npm install emdash-aws-ses
33
+ ```
34
+
35
+ ### From a local development directory:
36
+ ```bash
37
+ npm install ../path/to/emdash-aws-ses
38
+ ```
39
+
40
+ ---
41
+
42
+ ## Integration in Astro
43
+
44
+ To enable the plugin, import and register `awsSesPlugin()` inside the `plugins` array of the EmDash integration in your `astro.config.mjs` file:
45
+
46
+ ```javascript
47
+ // astro.config.mjs
48
+ import "dotenv/config";
49
+
50
+ import node from "@astrojs/node";
51
+ import react from "@astrojs/react";
52
+ import { defineConfig } from "astro/config";
53
+ import emdash, { local } from "emdash/astro";
54
+ import { sqlite } from "emdash/db";
55
+
56
+ // 1. Import the plugin
57
+ import { awsSesPlugin } from "emdash-aws-ses";
58
+
59
+ export default defineConfig({
60
+ output: "server",
61
+ adapter: node({
62
+ mode: "standalone",
63
+ }),
64
+ image: {
65
+ layout: "constrained",
66
+ responsiveStyles: true,
67
+ },
68
+ integrations: [
69
+ react(),
70
+ emdash({
71
+ database: sqlite({
72
+ // Dynamic SQLite database resolution for Coolify
73
+ url: process.env.NODE_ENV === "production"
74
+ ? "file:/app/data/data.db"
75
+ : "file:./data.db",
76
+ }),
77
+ storage: local({
78
+ // Dynamic persistent directory mapping for Coolify
79
+ directory: process.env.NODE_ENV === "production"
80
+ ? "/app/data/uploads"
81
+ : "./uploads",
82
+ baseUrl: "/_emdash/api/media/file",
83
+ }),
84
+ // 2. Register your plugin here
85
+ plugins: [
86
+ awsSesPlugin(),
87
+ ],
88
+ }),
89
+ ],
90
+ devToolbar: { enabled: false },
91
+ });
92
+ ```
93
+
94
+ ---
95
+
96
+ ## Configuration & Usage
97
+
98
+ Once your application is running, navigate to your CMS admin panel at `https://your-domain.com/_emdash/admin`.
99
+
100
+ ### 1. SMTP Settings Panel
101
+ Go to **Settings** -> **Plugins** -> **AWS SES Settings** and fill out the interactive configuration form:
102
+
103
+ | Field | Description | Example |
104
+ | :--- | :--- | :--- |
105
+ | **SMTP Host** | The SMTP endpoint host provided by Amazon SES. | `email-smtp.us-east-1.amazonaws.com` |
106
+ | **SMTP Port** | The secure SMTP port (STARTTLS or SSL/TLS). | `587` (Recommended) or `465` |
107
+ | **SMTP Username** | Your dedicated IAM SMTP Username generated in AWS. | `AKIA...` |
108
+ | **SMTP Password** | Your dedicated IAM SMTP Password generated in AWS. | `xxxXXXxxx` |
109
+ | **AWS Region** | The geographic AWS region where your SES is hosted. | `us-east-1` |
110
+ | **Default From Address** | A verified and authorized sender email address in AWS. | `noreply@your-domain.com` |
111
+ | **From Name** | The display name recipients will see. | `Your Company` |
112
+ | **Reply-To Address** | An optional reply-to address for user responses. | `support@your-domain.com` |
113
+
114
+ Click **Save Settings** to write your changes securely to the database.
115
+
116
+ ### 2. Testing the Connection
117
+ Navigate to the **Test & Status** tab inside the plugin's dashboard to diagnose the pipeline:
118
+ * Click **Test Connection** to trigger an on-demand SMTP handshake validation.
119
+ * Type an email address in the **Recipient Email** field and click **Send Test** to send a test HTML and plaintext message.
120
+
121
+ ---
122
+
123
+ ## Under the Hood (Developer Reference)
124
+
125
+ The plugin implements the standard `SandboxedPlugin` interface exposed by EmDash.
126
+
127
+ ### `plugin:install` Lifecycle Hook
128
+ Fires automatically when the plugin is registered in the CMS. It seeds default SMTP values (`email-smtp.us-east-1.amazonaws.com` on port `587`) securely inside `ctx.kv` to ensure a smooth first-time startup.
129
+
130
+ ### `email:deliver` Event Handler
131
+ Registers with `exclusive: true`. This setting commands EmDash to bypass any default local SMTP transporters or falling-back configurations, sending the `EmailDeliverEvent` payload directly to the custom SES transport handler.
132
+
133
+ ---
134
+
135
+ ## Local Development
136
+
137
+ If you want to contribute to this plugin, modify the source code, or test it locally, you must compile the TypeScript files into executable JavaScript:
138
+
139
+ 1. Clone the repository and navigate to the directory:
140
+ ```bash
141
+ git clone https://github.com/ab6162/emdash-aws-ses.git
142
+ cd emdash-aws-ses
143
+ ```
144
+
145
+ 2. Install the local development dependencies:
146
+ ```bash
147
+ npm install
148
+ ```
149
+
150
+ 3. Build the distribution files:
151
+ ```bash
152
+ npm run build
153
+ ```
154
+
155
+ This will generate the `/dist` directory containing the ESM and CommonJS compiled outputs.
156
+
157
+ ## License
158
+
159
+ This project is licensed under the MIT License. See the `LICENSE` file for more details.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "emdash-aws-ses",
3
- "version": "1.0.2",
3
+ "version": "1.0.3",
4
4
  "description": "Amazon SES SMTP email transport plugin for EmDash CMS",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -10,6 +10,14 @@
10
10
  "astro",
11
11
  "aws"
12
12
  ],
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/ab6162/emdash-aws-ses.git"
16
+ },
17
+ "bugs": {
18
+ "url": "https://github.com/ab6162/emdash-aws-ses/issues"
19
+ },
20
+ "homepage": "https://github.com/ab6162/emdash-aws-ses#readme",
13
21
  "type": "module",
14
22
  "main": "./dist/index.cjs",
15
23
  "module": "./dist/index.js",