Merge branch 'release/1.0.5'

docs/.vitepress/config.js

@@ -12,23 +12,42 @@ export default {
       '/guppy/': guppyGuide(),
       '/wish/': wishGuide(),
       '/create-sails/': createSailsGuide(),
-      '/inertia-sails/': inertiaSailsGuide()
+      '/inertia-sails/': inertiaSailsGuide(),
+      '/mail/': mailGuide()
+    },
+    sitemap: {
+      hostname: 'https://docs.sailscasts.com'
     },
     editLink: {
       pattern:
         'https://github.com/sailscastshq/docs.sailscasts.com/edit/develop/docs/:path',
       text: 'Edit this page on GitHub'
     },
+    head: [
+      ['meta', { name: 'theme-color', content: '#07162d' }],
+      ['meta', { name: 'og:type', content: 'website' }],
+      ['meta', { name: 'og:locale', content: 'en' }],
+      ['meta', { name: 'og:site_name', content: 'Sailscasts Docs' }],
+      [
+        'script',
+        {
+          src: 'https://cdn.usefathom.com/script.js',
+          'data-site': 'OTDOQLCI',
+          'data-spa': 'auto',
+          defer: ''
+        }
+      ]
+    ],
     socialLinks: [
       {
         icon: 'github',
         link: 'https://github.com/sailscastshq/docs.sailscasts.com'
       },
       { icon: 'twitter', link: 'https://twitter.com/sailscastshq' },
-      { icon: 'discord', link: 'https://discord.com/invite/gbJZuNm' },
+      { icon: 'discord', link: 'https://sailscasts.com/chat' },
       {
         icon: 'youtube',
-        link: 'https://www.youtube.com/channel/UCje9Wo6cbh3IERItPbyq1QA'
+        link: 'https://youtube.com/@sailscasts'
       }
     ],
     footer: {
@@ -46,16 +65,20 @@ export default {
 function nav() {
   return [
     {
-      text: 'Software',
-      items: [{ text: 'guppy', link: '/guppy/' }]
+      text: 'Commercial projects',
+      items: [
+        { text: 'Guppy', link: '/guppy/' },
+        { text: 'Hagfish', link: '/hagfish/' }
+      ]
     },
     {
       text: 'Open Source',
       items: [
         { text: 'create-sails', link: '/create-sails/' },
         { text: 'inertia-sails', link: '/inertia-sails/' },
-        { text: 'wish', link: '/wish/' },
-        { text: 'captain-vane', link: '/captain-vane/' }
+        { text: 'Wish', link: '/wish/' },
+        { text: 'captain-vane', link: '/captain-vane/' },
+        { text: 'Mail', link: '/mail/', activeMatch: '/mail/' }
         // { text: 'sailboat', link: '/sailboat/' },
       ]
     },
@@ -145,7 +168,7 @@ function wishGuide() {
       collapsible: true,
       items: [
         { text: 'Introduction', link: '/wish/' },
-        { text: 'What is wish?', link: '/wish/what-is-wish' },
+        { text: 'What is Wish?', link: '/wish/what-is-wish' },
         { text: 'Installation', link: '/wish/installation' }
       ]
     },
@@ -202,3 +225,38 @@ function inertiaSailsGuide() {
     }
   ]
 }
+
+function mailGuide() {
+  return [
+    {
+      text: 'Introduction',
+      collapsed: false,
+      items: [
+        { text: 'Getting Started', link: 'mail/getting-started' },
+        { text: 'Configuration', link: 'mail/configuration' }
+      ]
+    },
+    {
+      text: 'Transports',
+      collapsed: false,
+      items: [
+        { text: 'SMTP', link: 'mail/smtp-transport' },
+        { text: 'Resend', link: 'mail/resend-transport' },
+        { text: 'Local Development', link: 'mail/local-development' }
+      ]
+    },
+    {
+      text: 'Writing Emails',
+      collapsed: false,
+      items: [
+        { text: 'Template', link: 'mail/email-template' },
+        { text: 'Layout', link: 'mail/email-layout' }
+      ]
+    },
+    {
+      text: 'Sending Emails',
+      collapsed: false,
+      items: [{ text: 'Send Helper', link: 'mail/send-helper' }]
+    }
+  ]
+}

docs/mail/configuration.md

@@ -0,0 +1,73 @@
+---
+title: Configuration
+editLink: true
+prev:
+  text: 'Getting Started'
+  link: '/mail/getting-started'
+next:
+  text: 'SMTP Transport'
+  link: '/mail/smtp-transport'
+---
+
+# {{ $frontmatter.title }}
+
+To configure mail, create a `config/mail.js` configuration file. Let's look at all the possible configurations you can have in `config/mail.js`
+
+## default
+
+The `default` config in `config/mail.js` tells Mail which mailer to use by default. The string passed to `default` must be the name of a registered mailer in the `mailers` object
+
+```js[config/mail.js]
+module.exports.mail =  {
+  default: 'log' // replace 'log' with any configured mailer you've set
+}
+```
+
+You can also set the `default` mailer with the `MAIL_MAILER` environment variable and Mail will automatically detect it.
+
+This is handy for specifying different default mailers in different environments your application will be running in.
+
+Also in `config/local.js` you specify a `mailer` which will be used as the default mailer in development.
+
+```js
+//config/local.js
+mailer: 'nodemailer'
+```
+
+## mailers
+
+The `mailers` configuration object contains
+
+```js
+  mailers: {
+   log: {
+      transport: 'log'
+    },
+    mailtrap: {
+      transport: 'smtp'
+    },
+    resend: {
+      transport: 'resend'
+    }
+  },
+```
+
+:::info What's a mailer?
+
+In Mail, a mailer is a configuration object that is registered in the `mailers` object in `config/mails.js` that specifies at the very least a transport that Mail will use in sending your emails.
+:::
+
+## from
+
+This config let you set a global from address for all your emails. It's really useful if your application sends emails from the same from address.
+
+By default Mail will use this address if no address is passed when you send an email with `sails.helpers.mail.send`
+
+```js
+from: {
+    address: '[email protected]',
+    name: 'The Boring JavaScript Stack'
+}
+```
+
+You can also set this config by specifying these two environment variables: `MAIL_FROM_NAME` and `MAIL_FROM_ADDRESS`.

docs/mail/email-layout.md

@@ -0,0 +1,48 @@
+---
+title: Email Layout
+editLink: true
+prev:
+  text: 'Email Template'
+  link: '/mail/email-template'
+next:
+  text: 'Send Helper'
+  link: '/mail/send-helper'
+---
+
+# {{ $frontmatter.title }}
+
+You can create layouts for the emails in your Sails application. This layout file, like [templates](/mail/email-template) is expected to be an EJS template.
+
+## Default layout
+
+By default, Mail will look for a layout file in `views/layouts` called `layout-email.ejs` to use as the default layout for all your email templates.
+
+## Example
+
+Here is an example email layout that's in `views/layouts/layout-email.ejs`:
+
+```html
+<% /* Default layout for email templates */ %>
+<div
+  style="width: 100%; font-family: 'Inter','Helvetica','arial', sans-serif; box-sizing: border-box; padding: 0; margin: 0;"
+>
+  <div
+    style="color: #192147; font-size: 16px; box-sizing: border-box; padding: 40px 60px 80px 28px; width: 100%; max-width: 600px; margin-left: auto; margin-right: auto;"
+  >
+    <div style="background: transparent; text-align: left;"></div>
+    <%- body %>
+    <hr style="color: #E2E4EA;" />
+    <div
+      style="text-align: left; padding-top: 15px; font-size: 12px; color: #3E4771;"
+    >
+      <p>
+        © 2023 The Boring JavaScript Stack<br />
+        All trademarks, service marks, and company names are the property of
+        their respective owners.
+      </p>
+    </div>
+  </div>
+</div>
+```
+
+Your email templates will be injected in the spot marked by `<%- body %>` above.

docs/mail/email-template.md

@@ -0,0 +1,55 @@
+---
+title: Email Template
+editLink: true
+prev:
+  text: 'Local Development'
+  link: '/mail/local-development'
+next:
+  text: 'Email Layout'
+  link: '/mail/email-layout'
+---
+
+# {{ $frontmatter.title }}
+
+Mail expects your email templates to be written in EJS template files or whatever template engine you've setup in your Sails project. These files are expected to be in the `views/emails` directory.
+
+## Naming convention
+
+When writing your email templates, you should prepend the file name with `email-` for example for an email template to send the account verification email to a user, the template can be named as `email-confirm-account.ejs`
+
+## Example
+
+Here is an example email template that's in `views/emails/email-verify-account.ejs`:
+
+```html
+<h2
+  style="margin-bottom: 32px; font-size: 24px; font-style: normal; font-weight: 700; line-height: 33px; letter-spacing: 0em; text-align: left;"
+>
+  Welcome, <%= fullName %>!
+</h2>
+<p style="margin-bottom: 32px;">
+  You're almost ready to get started. Just click the button below to verify the
+  email address for your account:
+</p>
+<div
+  style="background: #6C25C1; display: inline-block; color: white; text-decoration: none; border-radius: 4px; text-align: center; width: 151px; padding: 8px 16px 8px 16px"
+>
+  <a
+    style="margin: auto; font-size: 16px; text-decoration: none; color: white; line-height: 22px;"
+    href="<%= url.resolve(sails.config.custom.baseUrl,'/verify-email')+'?token='+encodeURIComponent(token) %>"
+    >Verify email</a
+  >
+</div>
+<p style="margin-bottom: 25px;">
+  If you have any trouble, try pasting this link in your browser:
+  <a
+    style="color: #00ACC4; word-wrap: break-word;"
+    href="<%= url.resolve(sails.config.custom.baseUrl,'/verify-email')+'?token='+encodeURIComponent(token) %>"
+    ><%=
+    url.resolve(sails.config.custom.baseUrl,'/verify-email')+'?token='+encodeURIComponent(token)
+    %></a
+  >
+</p>
+<p style="margin-bottom: 5px;">Sincerely,</p>
+<p style="margin-top: 0px;">The Boring JavaScript Stack Team</p>
+```

docs/mail/getting-started.md

@@ -0,0 +1,51 @@
+---
+title: Getting started
+editLink: true
+next:
+  text: 'Configuration'
+  link: '/mail/configuration'
+---
+
+# {{ $frontmatter.title }}
+
+## Introduction
+
+Mail or Sails Mail provides a sleek, elegant, and developer-friendly email API that turns sending emails into a walk in the park for your Sails applications.
+
+Mail introduces transports for sending emails via SMTP, Resend, etc which allows you to quickly and elegantly get started sending emails through any local or cloud-based email service of your choice.
+
+## Installation
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org) version 18 or higher
+- [Sails](https://sailsjs.com) version 1 or higher
+
+To install Mail, simply run the following command in your Sails project:
+
+```sh [npm]
+$ npm install sails-hook-mail
+```
+
+## Usage
+
+Mail exposes a `send` [helper](https://sailsjs.com/documentation/concepts/helpers) that you can call in your Sails actions or where ever you have access to helpers in your Sails application.
+
+For example we can send an email verification email when a user signs up successfully via a `user/signup.js` action:
+
+```js
+// controllers/user/signup.js
+await sails.helpers.mail.send.with({
+  subject: 'Verify your email',
+  template: 'email-verify-account',
+  to: unverifiedUser.email,
+  templateData: {
+    token: unverifiedUser.emailProofToken,
+    fullName: unverifiedUser.fullName
+  }
+})
+```
+
+You can already see a couple of the arguments you can pass to the send helper provided by Mail.
+
+Next, You can check out all the various supported [transports](/mail/transports) Mail provide for you to send your emails and how to configure them

docs/mail/index.md

@@ -0,0 +1,23 @@
+---
+layout: home
+hero:
+  name: Mail
+  tagline: The simple elegant way to send emails from a Sails applications.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /mail/getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/sailscastshq/sails-hook-mail
+features:
+  - icon: 👨🏾‍💻
+    title: Easy setup
+    details: Sails Mail provides an amazing and elegant API for sending emails.
+  - icon: 🚚
+    title: Multiple transports
+    details: Supports SMTP, Resend, log, and more transports, to allow you use your favorite email service without any stress.
+  - icon: 🛠️
+    title: Flexible configuration
+    details: Need multiple email transports or mailers in the same Sails project? Mail make that a breeze to do.
+---