added tests and fixed docs

Author: mtrezza

spec/ApiMailAdapter.spec.js

@@ -219,13 +219,51 @@ describe('ApiMailAdapter', () => {
         },
         extra: {
           field: "ExampleExtra"
-        }
+        },
+        user: undefined,
       };
       const expectedArguments = Object.assign({}, options, { direct: true });
 
       await expectAsync(adapter.sendMail(options)).toBeResolved();
       expect(_sendMail.calls.all()[0].args[0]).toEqual(expectedArguments);
     });
+
+    it('passes user to callback when user is passed to sendMail()', async () => {
+      const adapter = new ApiMailAdapter(config);
+      const localeCallbackSpy = spyOn(config.templates.customEmailWithLocaleCallback, 'localeCallback').and.callThrough();
+      const options = {
+        templateName: 'customEmailWithLocaleCallback',
+        user: new Parse.User(),
+      };
+
+      await expectAsync(adapter.sendMail(options)).toBeResolved();
+      expect(localeCallbackSpy.calls.all()[0].args[0].get('locale')).toBe(options.user.get('locale'));
+    });
+
+    it('uses user email if no recipient is passed to sendMail()', async () => {
+      const adapter = new ApiMailAdapter(config);
+      const apiCallbackSpy = spyOn(adapter, 'apiCallback').and.callThrough();
+      const options = {
+        templateName: 'customEmailWithLocaleCallback',
+        user: new Parse.User(),
+      };
+
+      await expectAsync(adapter.sendMail(options)).toBeResolved();
+      expect(apiCallbackSpy.calls.all()[0].args[0].payload.to).toBe(options.user.get('email'));
+    });
+
+    it('overrides user email if recipient is passed to sendMail()', async () => {
+      const adapter = new ApiMailAdapter(config);
+      const apiCallbackSpy = spyOn(adapter, 'apiCallback').and.callThrough();
+      const options = {
+        recipient: '[email protected]',
+        templateName: 'customEmailWithLocaleCallback',
+        user: new Parse.User(),
+      };
+
+      await expectAsync(adapter.sendMail(options)).toBeResolved();
+      expect(apiCallbackSpy.calls.all()[0].args[0].payload.to).toBe(options.recipient);
+    });
   });
 
   describe('generate API payload', function () {

spec/helper.js

@@ -1,14 +1,14 @@
-'use strict';
-
 // Simulate Parse User class
 const Parse = {
   User: class User {
     get(key) {
       switch (key) {
         case 'username':
-          return 'ExampleUsername'
+          return 'ExampleUsername';
         case 'email':
-          return '[email protected]'
+          return '[email protected]';
+        case 'locale':
+          return 'de-AT';
       }
     }
   }

src/ApiMailAdapter.js

@@ -83,15 +83,16 @@ class ApiMailAdapter extends MailAdapter {
 
   /**
    * @function sendMail
-   * @desciption Sends an email.
+   * @description Sends an email.
    * @param {String} [sender] The email from address.
-   * @param {String} recipient The email recipient.
+   * @param {String} recipient The email recipient; if set overrides the email address of the `user`.
    * @param {String} [subject] The email subject.
    * @param {String} [text] The plain-text email content.
    * @param {String} [html] The HTML email content.
    * @param {String} [templateName] The template name.
-   * @param {String} [placeholders] The template placeholders.
-   * @param {String} [extra] Any additional variables to pass to the mail provider API.
+   * @param {Object} [placeholders] The template placeholders.
+   * @param {Object} [extra] Any additional variables to pass to the mail provider API.
+   * @param {Parse.User} [user] The Parse User that the is the recipient of the email.
    * @returns {Promise<Any>} The mail provider API response.
    */
   async sendMail({ sender, recipient, subject, text, html, templateName, placeholders, extra, user }) {
@@ -119,9 +120,9 @@ class ApiMailAdapter extends MailAdapter {
 
     // Define parameters
     let message;
-    const templateName = email.templateName;
-    // Get user from email object
     const user = email.user;
+    const userEmail = user ? user.get('email') : undefined;
+    const templateName = email.templateName;
 
     // If template name is not set
     if (!templateName) {
@@ -147,7 +148,7 @@ class ApiMailAdapter extends MailAdapter {
     if (email.direct) {
 
       // If recipient is not set
-      if (!email.recipient) {
+      if (!email.recipient && !userEmail) {
         throw Errors.Error.noRecipient;
       }
 
@@ -158,7 +159,7 @@ class ApiMailAdapter extends MailAdapter {
       message = Object.assign(
         {
           from: email.sender || this.sender,
-          to: email.recipient,
+          to: email.recipient || userEmail,
           subject: email.subject,
           text: email.text,
           html: email.html
@@ -174,14 +175,14 @@ class ApiMailAdapter extends MailAdapter {
       Object.assign(placeholders, {
         link,
         appName,
-        email: user.get('email'),
+        email: userEmail,
         username: user.get('username')
       });
 
       // Set message properties
       message = {
         from: this.sender,
-        to: user.get('email')
+        to: userEmail
       };
     }