Merge pull request #340 from FirebasePrivate/@ehesp/#310

Fixes to firestore-send-email #310

Author: Salakar

firestore-send-email/POSTINSTALL.md

@@ -22,7 +22,7 @@ You can test out this extension right away:
 **Note:** You can also use the [Firebase Admin SDK][admin_sdk] to add a document:
 ```
 admin.firestore().collection('${param:MAIL_COLLECTION}').add({
-  to: ['someone@example.com'],
+  to: 'someone@example.com',
   message: {
     subject: 'Hello from Firebase!',
     text: 'This is the plaintext section of the email body.',
@@ -41,11 +41,11 @@ The top-level fields of the document supply the email sender and recipient infor
 
 * **from:** The sender's email address. If not specified in the document, uses the configured "Default FROM address" parameter.
 * **replyTo:** The reply-to email address. If not specified in the document, uses the configured "Default REPLY-TO address" parameter.
-* **to:** An array containing the recipient email addresses.
+* **to:** A single recipient email address or an array containing multiple recipient email addresses.
 * **toUids:** An array containing the recipient UIDs.
-* **cc:** An array containing the CC recipient email addresses.
+* **cc:** A single recipient email address or an array containing multiple recipient email addresses.
 * **ccUids:** An array containing the CC recipient UIDs.
-* **bcc:** An array containing the BCC recipient email addresses.
+* **bcc:** A single recipient email address or an array containing multiple recipient email addresses.
 * **bccUids:** An array containing the BCC recipient UIDs.
 
 **NOTE:** The `toUids`, `ccUids`, and `bccUids` options deliver emails based on user UIDs keyed to email addresses within a Cloud Firestore document. To use these recipient options, you need to specify a Cloud Firestore collection for the extension's "Users collection" parameter. The extension can then read the `email` field for each UID specified in the `toUids`, `ccUids`, and/or `bccUids` fields.

firestore-send-email/PREINSTALL.md

@@ -2,21 +2,19 @@ Use this extension to render and send emails that contain the information from d
 
 Adding a document triggers this extension to send an email built from the document's fields. The document's top-level fields specify the email sender and recipients, including `to`, `cc`, and `bcc` options (each supporting UIDs). The document's `message` field specifies the other email elements, like subject line and email body (either plaintext or HTML)
 
-Here's a basic example documment write that would trigger this extension:
+Here's a basic example document write that would trigger this extension:
 
 ```js
 admin.firestore().collection('mail').add({
-  to: ['someone@example.com'],
+  to: 'someone@example.com',
   message: {
     subject: 'Hello from Firebase!',
     html: 'This is an <code>HTML</code> email body.',
   },
 })
 ```
 
-Because each email is built from a Cloud Firestore document, you can reference information stored in _other_ Cloud Firestore documents and fields, like image URLs.
-
-You can also optionally configure this extension to render emails using [Handlebar](https://handlebarsjs.com/) templates. Each template must be a document stored in a Cloud Firestore collection that you specify when configuring this extension.
+You can also optionally configure this extension to render emails using [Handlebar](https://handlebarsjs.com/) templates. Each template is a document stored in a Cloud Firestore collection.
 
 When you configure this extension, you'll need to supply your **SMTP credentials for mail delivery**.
 

firestore-send-email/extension.yaml

@@ -32,6 +32,9 @@ author:
 contributors:
   - authorName: Michael Bleigh
     url: https://github.com/mbleigh
+  - authorName: Elliot Hesp
+    email: elliot@invertase.io
+    url: https://github.com/ehesp
 
 roles:
   - role: datastore.user
@@ -90,25 +93,34 @@ params:
     type: string
     label: Email documents collection
     default: mail
+    validationRegex: "^[^/]+(/[^/]+/[^/]+)*$"
+    validationErrorMessage: Must be a valid Cloud Firestore collection
     required: true
     description: >-
       What is the path to the collection that contains the documents used to build and send the emails?
 
   - param: DEFAULT_FROM
     type: string
     label: Default FROM address
+    validationRegex: ^\S+@\S+\.\S+$
+    validationErrorMessage: Must be a valid email address
+    required: true
     description: >-
       The email address to use as the sender's address (if it's not specified in the added email document).
 
   - param: DEFAULT_REPLY_TO
     type: string
     label: Default REPLY-TO address
+    validationRegex: ^\S+@\S+\.\S+$
+    validationErrorMessage: Must be a valid email address
     description: >-
       The email address to use as the reply-to address (if it's not specified in the added email document).
 
   - param: USERS_COLLECTION
     type: string
     label: Users collection
+    validationRegex: "^[^/]+(/[^/]+/[^/]+)*$"
+    validationErrorMessage: Must be a valid Cloud Firestore collection
     description: >-
       A collection of documents keyed by user UID.
       If the `toUids`, `ccUids`, and/or `bccUids` recipient options are used in the added email document,
@@ -117,6 +129,8 @@ params:
   - param: TEMPLATES_COLLECTION
     type: string
     label: Templates collection
+    validationRegex: "^[^/]+(/[^/]+/[^/]+)*$"
+    validationErrorMessage: Must be a valid Cloud Firestore collection
     description: >-
       A collection of email templates keyed by name.
       This extension can render an email using a [Handlebar](https://handlebarsjs.com/) template,

firestore-send-email/functions/lib/index.js

@@ -32,7 +32,18 @@ const templates_1 = require("./templates");
 admin.initializeApp();
 const db = admin.firestore();
 const transport = nodemailer.createTransport(config_1.default.smtpConnectionUri);
-const templates = new templates_1.default(admin.firestore().collection(config_1.default.templatesCollection));
+let templates;
+if (config_1.default.templatesCollection) {
+    templates = new templates_1.default(admin.firestore().collection(config_1.default.templatesCollection));
+}
+function validateFieldArray(field, array) {
+    if (!Array.isArray(array)) {
+        throw new Error(`Invalid field "${field}". Expected an array of strings.`);
+    }
+    if (array.find(item => typeof item !== 'string')) {
+        throw new Error(`Invalid field "${field}". Expected an array of strings.`);
+    }
+}
 function processCreate(snap) {
     return __awaiter(this, void 0, void 0, function* () {
         return snap.ref.update({
@@ -47,35 +58,107 @@ function processCreate(snap) {
 }
 function preparePayload(payload) {
     return __awaiter(this, void 0, void 0, function* () {
-        if (config_1.default.templatesCollection && payload.template) {
-            payload.message = Object.assign(payload.message || {}, yield templates.render(payload.template.name, payload.template.data));
+        const { template } = payload;
+        if (templates && template) {
+            if (!template.name) {
+                throw new Error(`Template object is missing a 'name' parameter.`);
+            }
+            payload.message = Object.assign(payload.message || {}, yield templates.render(template.name, template.data));
+        }
+        let to = [];
+        let cc = [];
+        let bcc = [];
+        if (typeof payload.to === 'string') {
+            to = [payload.to];
+        }
+        else if (payload.to) {
+            validateFieldArray("to", payload.to);
+            to = to.concat(payload.to);
         }
-        if (!config_1.default.usersCollection ||
-            (!payload.toUids && !payload.ccUids && !payload.bccUids)) {
+        if (typeof payload.cc === 'string') {
+            cc = [payload.cc];
+        }
+        else if (payload.cc) {
+            validateFieldArray("cc", payload.cc);
+            cc = cc.concat(payload.cc);
+        }
+        if (typeof payload.bcc === 'string') {
+            bcc = [payload.bcc];
+        }
+        else if (payload.bcc) {
+            validateFieldArray("bcc", payload.bcc);
+            bcc = bcc.concat(payload.bcc);
+        }
+        if (!payload.toUids && !payload.ccUids && !payload.bccUids) {
+            payload.to = to;
+            payload.cc = cc;
+            payload.bcc = bcc;
             return payload;
         }
+        if (!config_1.default.usersCollection) {
+            throw new Error("Must specify a users collection to send using uids.");
+        }
+        let uids = [];
+        if (payload.toUids) {
+            validateFieldArray("toUids", payload.toUids);
+            uids = uids.concat(payload.toUids);
+        }
+        if (payload.ccUids) {
+            validateFieldArray("ccUids", payload.ccUids);
+            uids = uids.concat(payload.ccUids);
+        }
+        if (payload.bccUids) {
+            validateFieldArray("bccUids", payload.bccUids);
+            uids = uids.concat(payload.bccUids);
+        }
         const toFetch = {};
-        []
-            .concat(payload.toUids, payload.ccUids, payload.bccUids)
-            .forEach((uid) => (toFetch[uid] = null));
-        const docs = yield db.getAll(...Object.keys(toFetch).map((uid) => db.collection(config_1.default.usersCollection).doc(uid)), { fieldMask: ["email"] });
-        docs.forEach((doc) => {
-            if (doc.exists) {
-                toFetch[doc.id] = doc.get("email");
+        uids.forEach(uid => toFetch[uid] = null);
+        const documents = yield db.getAll(...Object.keys(toFetch).map((uid) => db.collection(config_1.default.usersCollection).doc(uid)), {
+            fieldMask: ["email"],
+        });
+        const missingUids = [];
+        documents.forEach((documentSnapshot) => {
+            if (documentSnapshot.exists) {
+                const email = documentSnapshot.get("email");
+                if (email) {
+                    toFetch[documentSnapshot.id] = email;
+                }
+                else {
+                    missingUids.push(documentSnapshot.id);
+                }
+            }
+            else {
+                missingUids.push(documentSnapshot.id);
             }
         });
+        logs.missingUids(missingUids);
         if (payload.toUids) {
-            payload.to = payload.toUids.map((uid) => toFetch[uid]);
-            delete payload.toUids;
+            payload.toUids.forEach((uid) => {
+                const email = toFetch[uid];
+                if (email) {
+                    to.push(email);
+                }
+            });
         }
+        payload.to = to;
         if (payload.ccUids) {
-            payload.cc = payload.ccUids.map((uid) => toFetch[uid]);
-            delete payload.ccUids;
+            payload.ccUids.forEach((uid) => {
+                const email = toFetch[uid];
+                if (email) {
+                    cc.push(email);
+                }
+            });
         }
+        payload.cc = cc;
         if (payload.bccUids) {
-            payload.bcc = payload.bccUids.map((uid) => toFetch[uid]);
-            delete payload.bccUids;
+            payload.bccUids.forEach((uid) => {
+                const email = toFetch[uid];
+                if (email) {
+                    bcc.push(email);
+                }
+            });
         }
+        payload.bcc = bcc;
         return payload;
     });
 }
@@ -90,6 +173,9 @@ function deliver(payload, ref) {
         };
         try {
             payload = yield preparePayload(payload);
+            if (!payload.to.length && !payload.cc.length && !payload.bcc.length) {
+                throw new Error("Failed to deliver email. Expected at least 1 recipient.");
+            }
             const result = yield transport.sendMail(Object.assign(payload.message, {
                 from: payload.from || config_1.default.defaultFrom,
                 replyTo: payload.replyTo || config_1.default.defaultReplyTo,

firestore-send-email/functions/lib/logs.js

@@ -51,3 +51,7 @@ function missingDeliveryField(ref) {
     console.error(`message=${ref.path} is missing 'delivery' field`);
 }
 exports.missingDeliveryField = missingDeliveryField;
+function missingUids(uids) {
+    console.log(`The following uids were provided, however a document does not exist or has no 'email' field: ${uids.join(',')}`);
+}
+exports.missingUids = missingUids;