# Mailing Services

This module provides mailing services for sending automated emails from the application using Mailgun.

## Setup

### 1. Install Dependencies

Make sure to install the required dependencies:

```bash
npm install mailgun-js firebase-admin firebase-functions
```

### 2. Configure Mailgun

To use the mailing services, you need to configure Mailgun credentials in your Firebase project:

```bash
firebase functions:config:set mailgun.api_key="your-mailgun-api-key" mailgun.domain="your-mailgun-domain" mailgun.from="MedClinic <no-reply@your-domain.com>"
```

To enable test mode (emails won't actually be sent):

```bash
firebase functions:config:set mailgun.test_mode="true"
```

### 3. Deploy Cloud Functions

Deploy the cloud functions to start handling email sending events:

```bash
firebase deploy --only functions
```

## Available Services

### Practitioner Invitation Service

Sends email invitations to practitioners when they are invited to join a clinic.

#### How it works:

1. When a new practitioner token is created in the Firestore database, the `onPractitionerTokenCreated` cloud function is triggered.
2. The function uses the `PractitionerInviteMailingService` to send an invitation email to the practitioner.
3. The email contains the token needed to claim their profile and instructions for registration.

### Patient Invitation Service

Sends email invitations to patients when a clinic admin creates their profile and generates an invitation token.

#### How it works:

1. When a new patient invitation token is created in the Firestore database (`patients/{patientId}/inviteTokens/{tokenId}`), the `onPatientTokenCreated` cloud function is triggered.
2. The function uses the `PatientInviteMailingService` to send an invitation email to the patient.
3. The email contains the token needed to claim their profile and instructions for registering in the patient app.

#### Example Usage in Code:

```typescript
import { PatientInviteMailingService } from "./admin/mailing";

// Create a new instance of the service
const mailingService = new PatientInviteMailingService(firestoreClient, mailgunClient);

// Send an invitation email
await mailingService.sendInvitationEmail({
  token: {
    id: "token-id",
    token: "ABC123",
    patientId: "patient-id",
    email: "patient@example.com",
    clinicId: "clinic-id",
    expiresAt: admin.firestore.Timestamp.fromDate(new Date()),
  },
  patient: {
    firstName: "Jane",
    lastName: "Doe",
  },
  clinic: {
    name: "Example Clinic",
    contactEmail: "admin@example.com",
    contactName: "Clinic Admin",
  },
  options: {
    registrationUrl: "https://your-app.com/patient/register",
    customSubject: "Claim Your Patient Profile",
  },
});
```

#### Example Usage in Code:

```typescript
import { PractitionerInviteMailingService } from "./admin/mailing";

// Create a new instance of the service
const mailingService = new PractitionerInviteMailingService();

// Send an invitation email
await mailingService.sendInvitationEmail({
  token: {
    id: "token-id",
    token: "ABC123",
    practitionerId: "practitioner-id",
    email: "doctor@example.com",
    clinicId: "clinic-id",
    expiresAt: admin.firestore.Timestamp.fromDate(new Date()),
  },
  practitioner: {
    firstName: "John",
    lastName: "Doe",
  },
  clinic: {
    name: "Example Clinic",
    contactEmail: "admin@example.com",
    contactName: "Clinic Admin",
  },
  options: {
    registrationUrl: "https://your-app.com/register",
    customSubject: "Join Our Clinic",
  },
});
```

## Adding New Mailing Services

To add a new mailing service:

1. Create a new directory in the `mailing` folder for your service
2. Create a service class that extends `BaseMailingService`
3. Create an HTML template in a `templates` subfolder
4. Create a cloud function to trigger the email sending
5. Export your new service in the index files

## Logging

All email sending attempts are logged to the `email_logs` collection in Firestore for tracking and debugging purposes.
