Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: update dependencies #32

Merged
merged 2 commits into from
Jan 23, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -63,3 +63,6 @@ profile*

# package-lock
package-lock.json

# node-tap
.tap
94 changes: 51 additions & 43 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,19 @@
## fastify-mail
# fastify-mail

A [Fastify](https://www.fastify.io/) plugin that uses [point-of-view](https://github.com/fastify/point-of-view#readme) and [fastify-nodemailer](https://github.com/lependu/fastify-nodemailer#readme) to template and send email messages.

### Usage
## Usage

```sh
npm i @autotelic/fastify-mail
```

### Setup
## Setup

`fastify-mail` decorates the reply interface with the `mail` method and takes two options to get started: `pov` and `transporter`

##### Point-of-View
### Point-of-View

- `pov.engine` should be a template engine object used to configure point-of-view
- to see a list of engines currently supported by point-of-view with options, [view docs here](https://github.com/fastify/point-of-view/blob/master/index.d.ts)
- For quick start, `fastify-mail` only requires the engine. For example, using `nunjucks`:
Expand All @@ -23,14 +24,17 @@ npm i @autotelic/fastify-mail

- If you'd prefer to register `point-of-view` on your own, omit the `engine` option and `fastify-mail` will not register it.
- If you configure `point-of-view` with a different decorator name, add this to the options of `fastify-mail`

```js
fastify.register(mail, { pov: { propertyName: 'POV_DECORATOR' }, transporter: ... })
```

##### Nodemailer
### Nodemailer

- `transporter` should be an object defining connection data to be used as a `nodemailer` SMTP transport. [View nodemailer's docs here](https://nodemailer.com/smtp/)
- `fastify-mail` decorates `fastify` with `nodemailer` so a transporter must be defined
- For example, using `maildev`:

```js
const transporter = {
host: 'localhost',
Expand All @@ -41,7 +45,7 @@ npm i @autotelic/fastify-mail
fastify.register(mail, { pov: { engine: ... }, transporter })
```

### Example
## Example

```js
// index.js
Expand Down Expand Up @@ -78,69 +82,73 @@ fastify.get("/sendmail", async (req, reply) => {
})
```

#### Templates
## Templates

Each message must have the following templates with the file extension set in point-of-view config:
- 'html': Contains the html template for the email.
- 'text': Contains the text template for the email.

```
- 'html': Contains the html template for the email.
- 'text': Contains the text template for the email.

```sh
.
|--index.js
|--templates
|-- html.njk
|-- text.njk
```

#### Example Apps
## Example Apps

See [/examples/mailgun](./examples/mailgun) for a working example app using [nodemailer-mailgun-transport](https://github.com/xr0master/mailgun-nodemailer-transport#readme).

See [/examples/maildev](./examples/maildev) for a working example app using [MailDev](https://maildev.github.io/maildev/)

### API
## API

#### Decorator
### Decorator

This plugin decorates fastify with a `mail` object containing the following methods:

- sendMail: 'function' - Calls `createMessage` to generate an message and uses [fastify-nodemailer](https://github.com/lependu/fastify-nodemailer) to send the generated email.
- Accepts the following arguments:
- message: 'object'
*This is a valid 'message' object as per the Nodemailer API*
- from: 'string' - The email address the email is to be sent from.
- to: 'array' - Comma separated list or an array of recipients email addresses (`string`) that will appear on the To: field
- cc: 'array' - Comma separated list or an array of recipients email addresses (`string`) that will appear on the Cc: field
- bcc: 'array' - Comma separated list or an array of recipients email addresses (`string`) that will appear on the Bcc: field
- replyTo : 'string' - An email address that will appear on the Reply-To: field
- subject: 'string' - The subject of the email with context injected.
- html: 'string' - The HTML version of the message as an Unicode string, with context injected.
- text : 'string' - The plaintext version of the message as an Unicode string, with context injected

- opts: 'object' - Object containing options:
- templatePath: 'string' - the relative path to the message's templates.
- context: 'object' - Object containing context for the message (such as - variables that will be used in copy)

- Returns: 'object' with following properties:
- accepted : 'array' of email addresses accepted - eg. [ '[email protected]' ]
- rejected : 'array' of email addresses rejected - eg. [],
- envelopeTime
- messageTime
- messageSize
- response
- envelope
- messageId
- sendMail: 'function' - Calls `createMessage` to generate an message and uses [fastify-nodemailer](https://github.com/lependu/fastify-nodemailer) to send the generated email.
- Accepts the following arguments:
- message: 'object'
*This is a valid 'message' object as per the Nodemailer API*
- from: 'string' - The email address the email is to be sent from.
- to: 'array' - Comma separated list or an array of recipients email addresses (`string`) that will appear on the To: field
- cc: 'array' - Comma separated list or an array of recipients email addresses (`string`) that will appear on the Cc: field
- bcc: 'array' - Comma separated list or an array of recipients email addresses (`string`) that will appear on the Bcc: field
- replyTo : 'string' - An email address that will appear on the Reply-To: field
- subject: 'string' - The subject of the email with context injected.
- html: 'string' - The HTML version of the message as an Unicode string, with context injected.
- text : 'string' - The plaintext version of the message as an Unicode string, with context injected

- opts: 'object' - Object containing options:
- templatePath: 'string' - the relative path to the message's templates.
- context: 'object' - Object containing context for the message (such as - variables that will be used in copy)

- Returns: 'object' with following properties:
- accepted : 'array' of email addresses accepted - eg. [ '[email protected]' ]
- rejected : 'array' of email addresses rejected - eg. [],
- envelopeTime
- messageTime
- messageSize
- response
- envelope
- messageId

- createMessage: 'function' - Generates a message object where the data provided is updated to use templates where available with context variables injected
- Accepts the following arguments:
- Accepts the following arguments:
- message: 'object'
- fields as above
- templatePath: 'string' - the relative path to the message's templates.
- context: 'object' - Object containing context for the message (such as - variables that will be used in copy)

For more details on this response see the Nodemail documentation [View nodemailer's docs here](https://nodemailer.com/smtp/)
For more details on this response see the nodemailer documentation [View nodemailer's docs here](https://nodemailer.com/smtp/)

### Testing

[Tap](https://node-tap.org/) is used for testing. To run tests:

```sh
npm test
```
$ npm test
```
8 changes: 1 addition & 7 deletions examples/maildev/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# Fastify-Mail Plugin with MailDev Example

### Setup:

- Fork and clone [fastify-mail repo](https://github.com/autotelic/fastify-mail).
- Install dependencies: `npm i`
- Change directory to `examples/maildev` and install dependencies:
Expand All @@ -14,8 +12,7 @@
- Run a new docker container to get mailDev running:

```sh
docker pull maildev/maildev
docker run -p 1080:80 -p 1025:25 --name maildev maildev/maildev
docker run -p 1080:1080 -p 1025:1025 maildev/maildev bin/maildev --base-pathname /maildev -w 1080 -s 1025
```

- Open a new terminal and run fastify-mail example:
Expand All @@ -27,6 +24,3 @@
- Open a browser to `localhost:1080` to view test inbox.
- Send a GET request to `localhost:3000/sendmail` and watch it appear at `localhost:1080`.
- Send a GET request to `localhost:3000/no-templates` for a version where no templates are provided



2 changes: 1 addition & 1 deletion examples/maildev/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ module.exports = async function (fastify, options) {
'</html>\n'

const message = {
to: ['[email protected]'],
to: '[email protected]',
from: '[email protected]',
subject: 'Test Subject',
html: testHtml,
Expand Down
6 changes: 3 additions & 3 deletions examples/maildev/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@
"start": "fastify start index.js -l info -w"
},
"dependencies": {
"fastify": "^3.0.0",
"fastify-cli": "^2.5.1",
"nunjucks": "^3.2.2"
"fastify": "^4.25.2",
"fastify-cli": "^6.0.0",
"nunjucks": "^3.2.4"
}
}
4 changes: 2 additions & 2 deletions examples/mailgun/.env.example
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
export MAILGUN_API_KEY=1234
export MAILGUN_DOMAIN=sandbox...mailgun.org
export RECIPIENTS[email protected]
export [email protected]
export RECIPIENT[email protected]
export [email protected]
2 changes: 0 additions & 2 deletions examples/mailgun/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# Fastify-Mail Plugin with mailgun Example

### Setup:

- Fork and clone [fastify-mail repo](https://github.com/autotelic/fastify-mail).
- Install dependencies: `npm i`
- change directory to `examples/mailgun` and install dependencies:
Expand Down
11 changes: 8 additions & 3 deletions examples/mailgun/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,19 @@ module.exports = async function (fastify, options) {

const transporter = mg(mgConfig)

console.log(transporter)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] could we remove?


await fastify.register(fastifyMail, { pov: { engine: { nunjucks } }, transporter })

fastify.get('/sendmail', async (req, reply) => {
const recipients = [process.env.RECIPIENTS]
const templates = './templates'
const templatePath = './templates'
const context = { name: 'Test Name', sender: process.env.SENDER }

const queued = await fastify.mail.sendMail(recipients, templates, context)
const queued = await fastify.mail.sendMail({
to: process.env.RECIPIENT,
from: process.env.SENDER,
subject: 'fastify-mail test'
}, { templatePath, context })
if (queued.error) {
const { error } = queued
reply.send(error)
Expand Down
8 changes: 4 additions & 4 deletions examples/mailgun/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
"start": "fastify start index.js -l info -w"
},
"dependencies": {
"fastify": "^3.0.0",
"fastify-cli": "^2.5.1",
"nodemailer-mailgun-transport": "^2.0.2",
"nunjucks": "^3.2.2"
"fastify": "^4.25.2",
"fastify-cli": "^6.0.0",
"nodemailer-mailgun-transport": "^2.1.5",
"nunjucks": "^3.2.4"
}
}
2 changes: 1 addition & 1 deletion index.js
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ const fastifyMail = async (fastify, opts) => {
// mail decorator configurations:
const mail = {
// the method that external users will call to send emails
// it either sends the messsage straight to nodemailer or uses createMessage to render templates if opts.templatePath is a provided
// it either sends the message straight to nodemailer or uses createMessage to render templates if opts.templatePath is a provided
sendMail: async function (message, opts = {}) {
try {
const errors = this.validateMessage(message)
Expand Down
Loading
Loading