npm package: @gamariverib/mercados-pecuarios-libs-send-emails
Description: Biblioteca de clases que contiene las funciones para el envío de correos electrónicos dentro del proyecto Mercados Pecuarios
Author: José Gamaliel Rivera Ibarra
Latest version: 0.2.1

# Send Emails Library

This library provides a set of functions for sending emails within the Mercados Pecuarios project, using the [Trigger Email from Firestore](https://extensions.dev/extensions/firebase/firestore-send-email) 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:

```bash
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](https://extensions.dev/extensions/firebase/firestore-send-email).

Your `firebase.json` file should include the following configuration for the extension:

```json
{
  "extensions": {
    "firestore-send-email": "firebase/firestore-send-email@0.2.4"
  }
}
```

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:

```bash
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.

```typescript
import { sendEmail } from "@gamariverib/mercados-pecuarios-libs-send-emails";

async function sendSimpleEmail() {
  try {
    await sendEmail({
      to: "recipient@example.com",
      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:

```typescript
import { sendEmailByTemplate } from "@gamariverib/mercados-pecuarios-libs-send-emails";

async function sendTemplatedEmail() {
  try {
    await sendEmailByTemplate({
      to: "recipient@example.com",
      template: {
        name: "welcome-email",
        data: {
          name: "John Doe",
        },
      },
    });
    console.log("Templated email sent successfully!");
  } catch (error) {
    console.error("Error sending templated email:", error);
  }
}
```