Send email when new passlist entry is added

functions/package.json

@@ -32,13 +32,14 @@
     "cors": "2.8.5",
     "csv-parser": "2.3.3",
     "firebase-admin": "12.1.0",
-    "firebase-functions": "^5.0.1",
+    "firebase-functions": "^5.1.1",
     "google-auth-library": "6.1.3",
     "googleapis": "64.0.0",
     "http-status-codes": "1.4.0",
     "immutable": "^4.3.6",
     "jsonstream-ts": "1.3.6",
     "module-alias": "^2.2.2",
+    "nodemailer": "^6.9.16",
     "requests": "0.3.0",
     "ts-node": "^10.9.1"
   },
@@ -53,6 +54,7 @@
     "@types/geojson": "^7946.0.14",
     "@types/jasmine": "^4.3.5",
     "@types/jsonstream": "0.8.30",
+    "@types/nodemailer": "^6.4.16",
     "@types/terraformer__wkt": "2.0.0",
     "firebase-functions-test": "^3.3.0",
     "firebase-tools": "13.6.0",

functions/src/common/context.ts

@@ -15,10 +15,12 @@
  */
 
 import {Datastore} from './datastore';
+import {MailService} from './mail-service';
 import {initializeApp, getApp} from 'firebase-admin/app';
 import {getFirestore} from 'firebase-admin/firestore';
 
 let datastore: Datastore | undefined;
+let mailService: MailService | undefined;
 
 export function initializeFirebaseApp() {
   try {
@@ -36,6 +38,19 @@ export function getDatastore(): Datastore {
   return datastore;
 }
 
+export async function getMailService(): Promise<MailService | undefined> {
+  if (!mailService) {
+    try {
+      const config = await MailService.gerMailServerConfig(getDatastore());
+
+      mailService = new MailService(config);
+    } catch (e) {
+      console.error(e);
+    }
+  }
+  return mailService;
+}
+
 export function resetDatastore() {
   datastore = undefined;
 }

functions/src/common/datastore.ts

@@ -29,7 +29,7 @@
  */
 type pseudoGeoJsonGeometry = {
   type: string;
   coordinates: any;
 };
 
 /**
@@ -37,11 +37,21 @@
  */
 export const config = () => 'config';
 
+/**
+ * Returns the path of passlist entry doc with the specified id.
+ */
+export const passlistEntry = (entryId: string) => `passlist/${entryId}`;
+
 /**
  * Returns the path of integrations doc.
  */
 export const integrations = () => config() + '/integrations';
 
+/**
+ * Returns the path of mail doc.
+ */
+export const mail = () => config() + '/mail';
+
 /**
  * Returns path to survey colection. This is a function for consistency with other path functions.
  */
@@ -81,6 +91,12 @@
 export const submission = (surveyId: string, submissionId: string) =>
   submissions(surveyId) + '/' + submissionId;
 
+/**
+ * Returns the path of template doc with the specified id.
+ */
+export const mailTemplate = (templateId: string) =>
+  `${mail()}/templates/${templateId}`;
+
 export class Datastore {
   private db_: firestore.Firestore;
 
@@ -124,6 +140,10 @@
     return this.db_.collection(integrations() + '/propertyGenerators').get();
   }
 
+  fetchMail() {
+    return this.db_.doc(mail()).get();
+  }
+
   fetchSurvey(surveyId: string) {
     return this.db_.doc(survey(surveyId)).get();
   }
@@ -188,6 +208,10 @@
     }
   }
 
+  fetchMailTemplate(templateId: string) {
+    return this.fetchDoc_(mailTemplate(templateId));
+  }
+
   fetchSheetsConfig(surveyId: string) {
     return this.fetchDoc_(`${survey(surveyId)}/sheets/config`);
   }
@@ -220,7 +244,7 @@
     await loiRef.update({[l.properties]: loiDoc[l.properties]});
   }
 
   static toFirestoreMap(geometry: any) {
     return Object.fromEntries(
       Object.entries(geometry).map(([key, value]) => [
         key,
@@ -229,7 +253,7 @@
     );
   }
 
   static toFirestoreValue(value: any): any {
     if (value === null) {
       return null;
     }
@@ -257,7 +281,7 @@
    *
    * @returns GeoJSON geometry object (with geometry as list of lists)
    */
   static fromFirestoreMap(geoJsonGeometry: any): any {
     const geometryObject = geoJsonGeometry as pseudoGeoJsonGeometry;
     if (!geometryObject) {
       throw new Error(
@@ -272,7 +296,7 @@
     return geometryObject;
   }
 
   static fromFirestoreValue(coordinates: any) {
     if (coordinates instanceof GeoPoint) {
       // Note: GeoJSON coordinates are in lng-lat order.
       return [coordinates.longitude, coordinates.latitude];
@@ -281,7 +305,7 @@
     if (typeof coordinates !== 'object') {
       return coordinates;
     }
     const result = new Array<any>(coordinates.length);
 
     Object.entries(coordinates).map(([i, nestedValue]) => {
       const index = Number.parseInt(i);

functions/src/common/mail-service.ts

@@ -0,0 +1,85 @@
+/**
+ * Copyright 2024 The Ground Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as nodemailer from 'nodemailer';
+import {Datastore} from './datastore';
+
+type MailConfig = {
+  server?: MailServerConfig;
+};
+
+type MailServerConfig = {
+  id: string;
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  sender?: string;
+};
+
+export interface MailServiceEmail {
+  to: string;
+  subject: string;
+  html: string;
+}
+
+export class MailService {
+  private transporter_: nodemailer.Transporter;
+  private sender_: string;
+
+  constructor(mailServerConfig: MailServerConfig) {
+    const {host, port, username, password, sender} = mailServerConfig;
+
+    this.sender_ = sender || username;
+
+    this.transporter_ = nodemailer.createTransport({
+      host,
+      port,
+      auth: {user: username, pass: password},
+      sender: this.sender_,
+    });
+  }
+
+  async sendMail(email: MailServiceEmail) {
+    await new Promise<void>((resolve, reject) => {
+      this.transporter_.sendMail(
+        {from: this.sender_, ...email},
+        (error: Error | any, _info: any) => {
+          if (error) {
+            // 501 and 550 are errors from the mail server: email address not found
+            if (error.responseCode === 501 || error.responseCode === 550) {
+              reject(new Error(error.response));
+            } else {
+              reject(error);
+            }
+          } else {
+            resolve();
+          }
+        }
+      );
+    });
+  }
+
+  static async gerMailServerConfig(db: Datastore): Promise<MailServerConfig> {
+    const mail = await db.fetchMail();
+    if (!mail.exists) throw new Error('Unable to find Mail Configuration');
+    const mailConfig = mail.data() as MailConfig;
+    const mailServerConfig = mailConfig.server;
+    if (!mailServerConfig)
+      throw new Error('Unable to find Mail Server Configuration');
+    return mailServerConfig;
+  }
+}

functions/src/common/utils.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright 2024 The Ground Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export function stringFormat(s: string, ...args: any[]): string {
+  return s.replace(/\{(\d+)\}/g, (_, index) => args[index] || `{${index}}`);
+}

functions/src/index.ts

@@ -23,16 +23,20 @@ import {importGeoJsonCallback} from './import-geojson';
 import {exportCsvHandler} from './export-csv';
 import {onCall} from 'firebase-functions/v2/https';
 import {onCreateLoiHandler} from './on-create-loi';
+import {onCreatePasslistEntryHandler} from './on-create-passlist-entry';
 import {onWriteJobHandler} from './on-write-job';
 import {onWriteLoiHandler} from './on-write-loi';
 import {onWriteSubmissionHandler} from './on-write-submission';
 import {onWriteSurveyHandler} from './on-write-survey';
-import {job, loi, submission, survey} from './common/datastore';
+import {job, loi, passlistEntry, submission, survey} from './common/datastore';
 import {initializeFirebaseApp} from './common/context';
 
 // Ensure Firebase is initialized.
 initializeFirebaseApp();
 
+/** Template for passlist entry write triggers capturing passlist entry id. */
+const passlistEntryPathTemplate = passlistEntry('{entryId}');
+
 /** Template for job write triggers capturing survey and job id. */
 const jobPathTemplate = job('{surveyId}', '{jobId}');
 
@@ -49,6 +53,10 @@ export const profile = {
   refresh: onCall(request => handleProfileRefresh(request)),
 };
 
+export const onCreatePasslistEntry = functions.firestore
+  .document(passlistEntryPathTemplate)
+  .onCreate(onCreatePasslistEntryHandler);
+
 export const importGeoJson = onHttpsRequestAsync(importGeoJsonCallback);
 
 export const exportCsv = onHttpsRequest(exportCsvHandler);

functions/src/on-create-passlist-entry.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright 2024 The Ground Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {EventContext} from 'firebase-functions';
+import {QueryDocumentSnapshot} from 'firebase-functions/v1/firestore';
+import {getDatastore, getMailService} from './common/context';
+import {MailServiceEmail} from './common/mail-service';
+import {stringFormat} from './common/utils';
+
+export async function onCreatePasslistEntryHandler(
+  _: QueryDocumentSnapshot,
+  context: EventContext
+) {
+  const entryId = context!.params.entryId;
+
+  const db = getDatastore();
+
+  const template = await db.fetchMailTemplate('passlisted');
+
+  if (template) {
+    const {subject, html} = template;
+
+    const mail = {
+      to: entryId,
+      subject,
+      html: stringFormat(html || '', [entryId]),
+    } as MailServiceEmail;
+
+    const mailService = await getMailService();
+
+    await mailService?.sendMail(mail);
+  }
+}

lib/package.json

@@ -26,7 +26,7 @@
   "dependencies": {
     "@google-cloud/firestore": "^7.7.0",
     "@ground/proto": "file:../proto",
-    "firebase-functions": "^5.0.1",
+    "firebase-functions": "^5.1.1",
     "immutable": "^4.3.6",
     "long": "^5.2.3",
     "protobufjs": "^7.3.0"