Send email when new passlist entry is added (#2087)

Co-authored-by: Gino Miceli <[email protected]>

Author: rfontanarosa

functions/package.json

@@ -32,14 +32,16 @@
     "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",
+    "sanitize-html": "^2.13.1",
     "ts-node": "^10.9.1"
   },
   "engines": {
@@ -53,6 +55,8 @@
     "@types/geojson": "^7946.0.14",
     "@types/jasmine": "^4.3.5",
     "@types/jsonstream": "0.8.30",
+    "@types/nodemailer": "^6.4.16",
+    "@types/sanitize-html": "^2.13.0",
     "@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 {
@@ -29,13 +31,22 @@ export function initializeFirebaseApp() {
 }
 
 export function getDatastore(): Datastore {
-  if (!datastore) {
-    initializeFirebaseApp();
-    datastore = new Datastore(getFirestore());
-  }
+  if (datastore) return datastore;
+  initializeFirebaseApp();
+  datastore = new Datastore(getFirestore());
   return datastore;
 }
 
+export async function getMailService(): Promise<MailService | undefined> {
+  if (mailService) return mailService;
+  const mailServerConfig = await MailService.getMailServerConfig(
+    getDatastore()
+  );
+  if (!mailServerConfig) return;
+  mailService = new MailService(mailServerConfig);
+  return mailService;
+}
+
 export function resetDatastore() {
   datastore = undefined;
 }

functions/src/common/datastore.ts

@@ -39,11 +39,21 @@ type pseudoGeoJsonGeometry = {
  */
 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.
  */
@@ -83,6 +93,12 @@ export const submissions = (surveyId: string) =>
 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;
 
@@ -126,6 +142,10 @@ export class Datastore {
     return this.db_.collection(integrations() + '/propertyGenerators').get();
   }
 
+  fetchMailConfig() {
+    return this.fetchDoc_(mail());
+  }
+
   fetchSurvey(surveyId: string) {
     return this.db_.doc(survey(surveyId)).get();
   }
@@ -145,6 +165,10 @@ export class Datastore {
       .get();
   }
 
+  fetchMailTemplate(templateId: string) {
+    return this.fetchDoc_(mailTemplate(templateId));
+  }
+
   fetchSheetsConfig(surveyId: string) {
     return this.fetchDoc_(`${survey(surveyId)}/sheets/config`);
   }

functions/src/common/mail-service.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 sanitizeHtml from 'sanitize-html';
+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;
+}
+
+/**
+ * Service for sending emails.
+ */
+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_,
+    });
+  }
+
+  /**
+   * Sends an email.
+   *
+   * @param email - Email object containing recipient, subject, and body.
+   */
+  async sendMail(email: MailServiceEmail): Promise<void> {
+    const {html} = email;
+
+    const safeHtml = sanitizeHtml(html, {
+      allowedTags: ['br', 'a'],
+      allowedAttributes: {
+        a: ['href'],
+      },
+    });
+
+    try {
+      await this.transporter_.sendMail({
+        from: this.sender_,
+        ...email,
+        html: safeHtml,
+      });
+    } catch (err) {
+      console.error(err);
+    }
+  }
+
+  /**
+   * Retrieves the mail server configuration from the database.
+   */
+  static async getMailServerConfig(
+    db: Datastore
+  ): Promise<MailServerConfig | undefined> {
+    const mailConfig = (await db.fetchMailConfig()) as MailConfig;
+    if (!mailConfig?.server) console.debug('Unable to find mail configuration');
+    return mailConfig?.server;
+  }
+}

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

@@ -24,16 +24,20 @@ import {exportCsvHandler} from './export-csv';
 import {exportGeojsonHandler} from './export-geojson';
 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}');
 
@@ -50,6 +54,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-loi.ts

@@ -34,6 +34,13 @@ type PropertyGenerator = {
   url: string;
 };
 
+/**
+ * Handles the creation of a Location of Interest (LOI) document in Firestore.
+ * This function is triggered by a Cloud Function on Firestore document creation.
+ *
+ * @param snapshot The QueryDocumentSnapshot object containing the created LOI data.
+ * @param context The EventContext object provided by the Cloud Functions framework.
+ */
 export async function onCreateLoiHandler(
   snapshot: QueryDocumentSnapshot,
   context: EventContext

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

@@ -0,0 +1,94 @@
+/**
+ * Copyright 2025 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 {
+  createMockFirestore,
+  newDocumentSnapshot,
+  newEventContext,
+  stubAdminApi,
+} from '@ground/lib/dist/testing/firestore';
+import {resetDatastore} from './common/context';
+import {Firestore} from 'firebase-admin/firestore';
+import * as functions from './index';
+import * as context from './common/context';
+import {MailService} from './common/mail-service';
+
+const test = require('firebase-functions-test')();
+
+describe('onCreatePasslistEntry()', () => {
+  let mockFirestore: Firestore;
+  let getMailServiceMock: any;
+  let mailServiceMock: any;
+
+  const serverConfig = {
+    port: 5555,
+  };
+  const mail = {
+    html: 'html',
+    subject: 'subject',
+    to: '[email protected]',
+  };
+
+  beforeEach(() => {
+    mockFirestore = createMockFirestore();
+    stubAdminApi(mockFirestore);
+
+    mailServiceMock = jasmine.createSpyObj('MailService', [
+      'sendMail',
+    ]) as jasmine.SpyObj<MailService>;
+
+    getMailServiceMock = spyOn(context, 'getMailService').and.returnValue(
+      mailServiceMock
+    );
+  });
+
+  afterEach(() => {
+    resetDatastore();
+  });
+
+  afterAll(() => {
+    test.cleanup();
+  });
+
+  it('passlist notification email template exists', async () => {
+    await mockFirestore.collection('passlists').add({});
+    await test.wrap(functions.onCreatePasslistEntry)(newDocumentSnapshot({}));
+    expect(getMailServiceMock).not.toHaveBeenCalled();
+  });
+
+  it('mail server config exists', async () => {
+    const docRef = mockFirestore.doc('config/mail');
+    docRef.set({server: serverConfig});
+    const docSnapshot = await docRef.get();
+    const data = docSnapshot.data();
+    expect(data).toEqual({server: serverConfig});
+    expect(docSnapshot.exists).toBe(true);
+    expect(docSnapshot.id).toBe('mail');
+  });
+
+  it('sends email notification', async () => {
+    mockFirestore.doc('config/mail').set({server: serverConfig});
+    mockFirestore.doc('config/mail/templates/passlisted').set(mail);
+    mockFirestore.doc(`passlists/${mail.to}`).set({});
+    await test.wrap(functions.onCreatePasslistEntry)(
+      newDocumentSnapshot({}),
+      newEventContext({entryId: mail.to})
+    );
+    expect(getMailServiceMock).toHaveBeenCalled();
+    expect(mailServiceMock.sendMail).toHaveBeenCalled();
+    expect(mailServiceMock.sendMail).toHaveBeenCalledWith(mail);
+  });
+});