Update doc and debugging.

alinex · Oct 20, 2016 · 0e3d961 · 0e3d961
1 parent 740187c
commit 0e3d961
Show file tree

Hide file tree

Showing 6 changed files with 234 additions and 138 deletions.
diff --git a/.docignore b/.docignore
@@ -0,0 +1,16 @@
+.project
+.settings
+.DS_Store
+*.sublime-*
+/coverage/
+/report/
+/data/
+/doc/
+/lib/
+/log/
+/node_modules/
+/var/lib/
+/var/local/
+npm-debug.log
+/man/
+/.*
diff --git a/.travis.yml b/.travis.yml
@@ -1,9 +1,21 @@
 language: node_js
 node_js:
-   - "0.10" # from 2013-03 maintenance till 2016-10
-   - "0.12" # from 2015-02 maintenance till 2017-04
-   - "4"  # LTS from 2015-10  maintenance till 2018-04
-   - "5"  # devel from 2015-10 current till 2016-06
-#   - "6"  # LTS   from 2016-10 maintenance till 2019-04
+  - "0.10" # from 2013-03 maintenance till 2016-10
+  - "0.12" # from 2015-02 maintenance till 2016-12
+  - "4"  # LTS   from 2015-10 maintenance till 2018-04
+  - "6"  # LTS   from 2016-10 maintenance till 2019-04
+#  - "7"  # devel from 2016-10
+
+# coveralls integration
 after_success:
-   - COVERALLS_SERVICE_NAME=travis-ci COVERALLS_REPO_TOKEN=8oEtXXHE0CjL5pHUpcPRRL2Qq9bYicmde node_modules/.bin/builder test --coveralls
+  - COVERALLS_SERVICE_NAME=travis-ci COVERALLS_REPO_TOKEN=8oEtXXHE0CjL5pHUpcPRRL2Qq9bYicmde node_modules/.bin/builder test --coveralls
+
+# Fix the c++ compiler on Ubuntu 14.04
+env:
+  - CXX=g++-4.8
+addons:
+  apt:
+    sources:
+      - ubuntu-toolchain-r-test
+    packages:
+      - g++-4.8
diff --git a/README.md b/README.md
@@ -1,9 +1,40 @@
-Package: alinex-mail
+Alinex Mail: Readme
 =================================================
 
-[![Build Status](https://travis-ci.org/alinex/node-mail.svg?branch=master)](https://travis-ci.org/alinex/node-mail)
-[![Coverage Status](https://coveralls.io/repos/alinex/node-mail/badge.png?branch=master)](https://coveralls.io/r/alinex/node-mail?branch=master)
-[![Dependency Status](https://gemnasium.com/alinex/node-mail.png)](https://gemnasium.com/alinex/node-mail)
+[![GitHub watchers](
+  https://img.shields.io/github/watchers/alinex/node-mail.svg?style=social&label=Watch&maxAge=2592000)](
+  https://github.com/alinex/node-mail/subscription)
+<!-- {.hidden-small} -->
+[![GitHub stars](
+  https://img.shields.io/github/stars/alinex/node-mail.svg?style=social&label=Star&maxAge=2592000)](
+  https://github.com/alinex/node-mail)
+[![GitHub forks](
+  https://img.shields.io/github/forks/alinex/node-mail.svg?style=social&label=Fork&maxAge=2592000)](
+  https://github.com/alinex/node-mail)
+<!-- {.hidden-small} -->
+<!-- {p:.right} -->
+
+[![npm package](
+  https://img.shields.io/npm/v/alinex-mail.svg?maxAge=2592000&label=latest%20version)](
+  https://www.npmjs.com/package/alinex-mail)
+[![latest version](
+  https://img.shields.io/npm/l/alinex-mail.svg?maxAge=2592000)](
+  #license)
+<!-- {.hidden-small} -->
+[![Travis status](
+  https://img.shields.io/travis/alinex/node-mail.svg?maxAge=2592000&label=develop)](
+  https://travis-ci.org/alinex/node-mail)
+[![Coveralls status](
+  https://img.shields.io/coveralls/alinex/node-mail.svg?maxAge=2592000)](
+  https://coveralls.io/r/alinex/node-mail?branch=master)
+[![Gemnasium status](
+  https://img.shields.io/gemnasium/alinex/node-mail.svg?maxAge=2592000)](
+  https://gemnasium.com/alinex/node-mail)
+[![GitHub issues](
+  https://img.shields.io/github/issues/alinex/node-mail.svg?maxAge=2592000)](
+  https://github.com/alinex/node-mail/issues)
+<!-- {.hidden-small} -->
+
 
 An easy to use module for sending mails.
 
@@ -15,8 +46,12 @@ An easy to use module for sending mails.
 While sending mails it will also transform inline images in html into cid images
 attached to the mail to make it more standard conform.
 
-> It is one of the modules of the [Alinex Namespace](http://alinex.github.io/code.html)
-> following the code standards defined in the [General Docs](http://alinex.github.io/develop).
+> It is one of the modules of the [Alinex Namespace](https://alinex.github.io/code.html)
+> following the code standards defined in the [General Docs](https://alinex.github.io/develop).
+
+__Read the complete documentation under
+[https://alinex.github.io/node-mail](https://alinex.github.io/node-mail).__
+<!-- {p: .hidden} -->
 
 
 Install
@@ -86,12 +121,10 @@ setup = mail.resolve setup
 
 Configuration
 -------------------------------------------------
+The configuration is based on multiple email templates. They can be made on top of
+each other.
 
-The configuration is based on multiple email templates.
-
-### Email Templates
-
-They will be defined under `/email`:
+They will be defined under `/email` and  an example may look like:
 
 ``` yaml
 # Email Templates
@@ -136,107 +169,23 @@ default:
 To make it more modular you may also add a `base` setting to use the setting defined
 there as a base and the options here may overwrite or enhance the base setup.
 
-#### Transport
-
-The transport setting defines how to send the email. This should specify the
-connection for the mailserver to use for sending. It is possible to do this using
-a connection url like above with the syntax:
-
-    <protocol>://<user>:<password>@<server>:<port>
+Read more at the {@link configSchema.coffee} page.
 
-Or you may specify it as object like:
 
-``` yaml
-transport:
-  pool: <boolean> # use pooled connections defaults to false
-  direct: <boolean> # set to true to try to connect directly to recipients MX
-  service: <string> # name of well-known service (will set host, port and secure options)
-  # services: 1und1, AOL, DebugMail.io, DynectEmail, FastMail, GandiMail, Gmail,
-  # Godaddy, GodaddyAsia, GodaddyEurope, hot.ee, Hotmail, iCloud, mail.ee, Mail.ru,
-  # Mailgun, Mailjet, Mandrill, Naver, Postmark, QQ, QQex, SendCloud, SendGrid,
-  # SES, Sparkpost, Yahoo, Yandex, Zoho
-  host: <string> # the hostname or IP address to connect to
-  port: <integer> # the port to connect to (defaults to 25 or 465)
-  secure: <boolean> # if true the connection will only use TLS else (the default)
-  # TLS may still be upgraded to if available via the STARTTLS command
-  ignoreTLS: <boolean> # if this is true and secure is false, TLS will not be used
-  requireTLS: <boolean> # if this is true and secure is false, it uses STARTTLS
-  # even if the server does not advertise support for it
-  tls: <object> # additional socket options like `{rejectUnauthorized: true}`
-  auth: # authentication objects
-    user: <string> # the username
-    pass: <string> # the password for the user
-  authMethod: <string> # preferred authentication method, eg. ‘PLAIN’
-  name: <string> # hostname of the client, used for identifying to the server
-  localAddress: <string> # the local interface to bind to for network connections
-  connectionTimeout: <integer> # milliseconds to wait for the connection to establish
-  greetingTimeout: <integer> # milliseconds to wait for the greeting after connection is established
-  socketTimeout: <integer> # milliseconds of inactivity to allow
-  debug: <boolean> # set to true to log the complete SMTP traffic
-  # if pool is set to true:
-  maxConnections: <integer> # the count of maximum simultaneous connections (defaults to 5)
-  maxMessages: <integer> # limits the message count to be sent using a single connection (defaults to 100)
-  rateLimit: <integer> # limits the message count to be sent in a second (defaults to false)    
-```
-
-#### Addressing
+Debugging
+----------------------------------------------
+If you have any problems you may always run it with debugging by setting the `DEBUG`
+environment variable like:
 
-First you can define the sender address using:
-
-``` yaml
-from: <string> # the address used as sender(often the same as used in transport)
-replyTo: <string> # address which should be used for replys
+``` coffee
+DEBUG=mail* myprog-usingsshtunnel
 ```
 
-And you give the addresses to send the mail to. In the following fields: `to`, `cc`
-and `bcc` you may give a single address or a list of addresses to use.
-All e-mail addresses can be plain e-mail addresses
-
-    name@mymailserver.com
-
-or with formatted name (includes unicode support)
-
-    "My Name" <name@mymailserver.com>
-
-#### Content
-
-The content of the mail consists of an subject line which should be not to long
-and the body. The body is given as [Markdown](http://alinex.github.io/develop/lang/markdown.html)
-syntax and supports all possibilities from
-[report](http://alinex.github.io/node-report/README.md.html#markup%20syntax).
-This will be converted to a plain text and html version for sending so that the
-mail client can choose the format to display.
-
-You may also give the 'text' and 'html' content as property itself. But keep in
-mind that within the base properties no markdown conversions are done. In the
-'body' it will.
-
-Like you see above, you can use handlebar syntax to use some variables from the
-code. This is possible in subject and body. And you may specify a
-locale to use for date formatting.
-
-You can also define different templates which can be referenced from within the
-job.
-
-Find more examples at [validator](http://alinex.github.io/node-validator/README.md.html#handlebars).
-
-#### Attachments
-
-The key `attachments` is used to add a list of files attached to the email and
-consists of the following properties:
-
-- `path` path to a file or an URL to include
-- `filename` filename to be reported as the name of the attached file
-- `content` String, Buffer or a Stream contents for the attachment
-- `contentType` optional content type for the attachment, if not set will be
-  derived from the filename property
-- `contentDisposition` optional content disposition type for the attachment,
-  defaults to ‘attachment’
-- `cid` optional content id for using inline images in HTML message source
-- `encoding` If set and content is string, then encodes the content to a Buffer
-  using the specified encoding. Example values: base64, hex, binary etc.
-- `headers` custom headers for the attachment node
+The following targets are possible:
+- `mail` general logging
+- `mail:data` output all mail elements instead of only the envelope
 
+If you enable debugging of `mail` the given configuration will also be validated.
 
 
 License

diff --git a/example.html b/example.html
diff --git a/src/configSchema.coffee b/src/configSchema.coffee
@@ -1,9 +1,18 @@
-# Configuration Schema
-# =================================================
+###
+Configuration
+===================================================
+The configuration consists of two parts:
+- Email Template
+- Collection of Templates
+###
 
 
-# Email Action
-# -------------------------------------------------
+###
+Email Template
+------------------------------------------------------
+{@schema #email}
+###
+
 exports.email = email =
   title: "Email Action"
   description: "the setup for an individual email action"
@@ -12,16 +21,21 @@ exports.email = email =
   keys:
     base:
       title: "Base Template"
+      description: "the template used as basis for this one"
       type: 'string'
-      description: "the template used as base for this"
       list: '<<<context:///email>>>'
     transport:
       title: "Service Connection"
       description: "the service connection to send mails through"
       type: 'or'
       or: [
+        title: "Transport URI"
+        description: "the transport method as URI string through which the mail
+        will be send like `<protocol>://<user>:<password>@<server>:<port>`"
         type: 'string'
       ,
+        title: "Transport Object"
+        description: "the mail transport settings through which the mail will be send"
         type: 'object'
       ]
     retry:
@@ -135,11 +149,77 @@ exports.email = email =
             type: 'string'
 
 
-# Complete Schema Definition
-# -------------------------------------------------
+###
+Collection of Templates
+------------------------------------------------------
+{@schema #templates}
+###
 
 exports.templates =
   title: "Email Templates"
   description: "the possible templates used for sending emails"
   type: 'object'
   entries: [email]
+
+
+###
+Addressing
+--------------------------------------------------------
+First you can define the sender address using:
+
+``` yaml
+from: <string> # the address used as sender(often the same as used in transport)
+replyTo: <string> # address which should be used for replys
+```
+
+And you give the addresses to send the mail to. In the following fields: `to`, `cc`
+and `bcc` you may give a single address or a list of addresses to use.
+All e-mail addresses can be plain e-mail addresses
+
+    name@mymailserver.com
+
+or with formatted name (includes unicode support)
+
+    "My Name" <name@mymailserver.com>
+
+
+Content
+--------------------------------------------------------
+The content of the mail consists of an subject line which should be not to long
+and the body. The body is given as [Markdown](http://alinex.github.io/develop/lang/markdown.html)
+syntax and supports all possibilities from
+[report](http://alinex.github.io/node-report/README.md.html#markup%20syntax).
+This will be converted to a plain text and html version for sending so that the
+mail client can choose the format to display.
+
+You may also give the 'text' and 'html' content as property itself. But keep in
+mind that within the base properties no markdown conversions are done. In the
+'body' it will.
+
+Like you see above, you can use handlebar syntax to use some variables from the
+code. This is possible in subject and body. And you may specify a
+locale to use for date formatting.
+
+You can also define different templates which can be referenced from within the
+job.
+
+Find more examples at [validator](http://alinex.github.io/node-validator/README.md.html#handlebars).
+
+
+Attachments
+--------------------------------------------------
+The key `attachments` is used to add a list of files attached to the email and
+consists of the following properties:
+
+- `path` path to a file or an URL to include
+- `filename` filename to be reported as the name of the attached file
+- `content` String, Buffer or a Stream contents for the attachment
+- `contentType` optional content type for the attachment, if not set will be
+  derived from the filename property
+- `contentDisposition` optional content disposition type for the attachment,
+  defaults to ‘attachment’
+- `cid` optional content id for using inline images in HTML message source
+- `encoding` If set and content is string, then encodes the content to a Buffer
+  using the specified encoding. Example values: base64, hex, binary etc.
+- `headers` custom headers for the attachment node
+###