Send Emails Library

This library provides a set of functions for sending emails within the Mercados Pecuarios project, using the Trigger Email from Firestore Firebase extension.

Description

The library offers two main functions:

• sendEmail: Sends a standard email with a specified subject, and a body in either text or HTML format.
• sendEmailByTemplate: Sends an email using a pre-defined Handlebars template stored in Firestore.

The library is written in TypeScript and is intended to be used in a Node.js environment.

Setup

1. Install Dependencies

To use this library, you first need to install the necessary dependencies:

npm install

2. Configure the Firebase Extension

This library relies on the firestore-send-email Firebase extension. You need to have this extension installed and configured in your Firebase project.

You can install the extension from the Firebase Extensions Hub.

Your firebase.json file should include the following configuration for the extension:

{
  "extensions": {
    "firestore-send-email": "firebase/[email protected]"
  }
}

You will also need to configure the extension with your SMTP credentials and specify the collections for email messages and templates.

• Email Messages Collection: The collection where the library will write new documents to trigger the sending of emails. The default is email-messages.
• Email Templates Collection: The collection where you will store your Handlebars email templates. The default is email-templates.

3. Environment Variables

The library uses the following environment variables:

• GCLOUD_PROJECT: Your Google Cloud project ID.
• GOOGLE_APPLICATION_CREDENTIALS: The path to your Google Cloud service account credentials file.
• FIRESTORE_EMULATOR_HOST: The host and port of the Firestore emulator (e.g., 127.0.0.1:8090).
• EMAIL_MESSAGES_COLLECTION: The name of the Firestore collection for email messages.
• EMAIL_TEMPLATES_COLLECTION: The name of the Firestore collection for email templates.

Running Tests

To run the tests, you need to have the Firestore emulator running. The tests will connect to the emulator, clean up the test collections, and then run a series of tests to ensure the library is working correctly.

To run the tests, use the following command:

npm test

Note: The tests are currently failing with a timeout error. This seems to be an issue with the test environment and not the library itself.

Usage

sendEmail

The sendEmail function allows you to send a standard email. You need to provide the recipient(s) and the message content.

import { sendEmail } from "@gamariverib/mercados-pecuarios-libs-send-emails";

async function sendSimpleEmail() {
  try {
    await sendEmail({
      to: "[email protected]",
      message: {
        subject: "Hello from Firebase!",
        text: "This is a plain text email.",
        html: "This is an <strong>HTML</strong> email.",
      },
    });
    console.log("Email sent successfully!");
  } catch (error) {
    console.error("Error sending email:", error);
  }
}

sendEmailByTemplate

The sendEmailByTemplate function allows you to send an email using a Handlebars template stored in Firestore. You need to provide the recipient(s), the name of the template, and any data to be used in the template.

First, you need to have a template stored in your Firestore templates collection. For example, a template named welcome-email could look like this:

Subject: Welcome, {{name}}! HTML: <p>Hello {{name}}, welcome to our platform!</p>

Then, you can use the sendEmailByTemplate function like this:

import { sendEmailByTemplate } from "@gamariverib/mercados-pecuarios-libs-send-emails";

async function sendTemplatedEmail() {
  try {
    await sendEmailByTemplate({
      to: "[email protected]",
      template: {
        name: "welcome-email",
        data: {
          name: "John Doe",
        },
      },
    });
    console.log("Templated email sent successfully!");
  } catch (error) {
    console.error("Error sending templated email:", error);
  }
}