# Notification Service Integrations

> External notification provider integration documentation.

---

## Overview

Aphrodite integrates with multiple notification channels.

| Provider | Channel | Use Case             |
| -------- | ------- | -------------------- |
| SendGrid | Email   | Transactional email  |
| FCM      | Push    | Mobile/web push      |
| APNs     | Push    | iOS native push      |
| Twilio   | SMS     | Critical alerts, 2FA |

---

## SendGrid (Email)

**API Documentation:** https://docs.sendgrid.com

### Configuration

```typescript
interface SendGridConfig {
  apiKey: string;
  fromEmail: string;
  fromName: string;
  templates: {
    welcome: string;
    passwordReset: string;
    tip: string;
    streamLive: string;
    subscription: string;
  };
}
```

### Send Email

```typescript
import sgMail from '@sendgrid/mail';

sgMail.setApiKey(config.apiKey);

async function sendEmail(params: EmailParams): Promise<void> {
  await sgMail.send({
    to: params.to,
    from: {
      email: config.fromEmail,
      name: config.fromName,
    },
    templateId: params.templateId,
    dynamicTemplateData: params.data,
    trackingSettings: {
      clickTracking: { enable: true },
      openTracking: { enable: true },
    },
  });
}
```

### Email Templates

| Template         | Purpose                   |
| ---------------- | ------------------------- |
| `d-welcome`      | Welcome email             |
| `d-password`     | Password reset            |
| `d-tip`          | Tip received notification |
| `d-stream-live`  | Stream started            |
| `d-subscription` | Subscription confirmation |

---

## Firebase Cloud Messaging (FCM)

**API Documentation:** https://firebase.google.com/docs/cloud-messaging

### Configuration

```typescript
interface FCMConfig {
  projectId: string;
  clientEmail: string;
  privateKey: string;
}
```

### Initialize

```typescript
import * as admin from 'firebase-admin';

admin.initializeApp({
  credential: admin.credential.cert({
    projectId: config.projectId,
    clientEmail: config.clientEmail,
    privateKey: config.privateKey,
  }),
});
```

### Send Push Notification

```typescript
async function sendPush(params: PushParams): Promise<void> {
  const message: admin.messaging.Message = {
    token: params.deviceToken,
    notification: {
      title: params.title,
      body: params.body,
      imageUrl: params.imageUrl,
    },
    data: params.data,
    android: {
      priority: 'high',
      notification: {
        channelId: params.channelId || 'default',
        clickAction: 'FLUTTER_NOTIFICATION_CLICK',
      },
    },
    apns: {
      payload: {
        aps: {
          badge: params.badge,
          sound: params.sound || 'default',
          'content-available': 1,
        },
      },
    },
    webpush: {
      fcmOptions: {
        link: params.actionUrl,
      },
    },
  };

  await admin.messaging().send(message);
}
```

### Send to Multiple Devices

```typescript
async function sendMulticast(
  tokens: string[],
  notification: NotificationPayload
): Promise<admin.messaging.BatchResponse> {
  return admin.messaging().sendEachForMulticast({
    tokens,
    notification: {
      title: notification.title,
      body: notification.body,
    },
    data: notification.data,
  });
}
```

---

## Apple Push Notification Service (APNs)

**API Documentation:**
https://developer.apple.com/documentation/usernotifications

### Configuration

```typescript
interface APNsConfig {
  keyId: string;
  teamId: string;
  authKeyPath: string;
  bundleId: string;
  production: boolean;
}
```

### Send Notification

```typescript
import apn from 'apn';

const provider = new apn.Provider({
  token: {
    key: config.authKeyPath,
    keyId: config.keyId,
    teamId: config.teamId,
  },
  production: config.production,
});

async function sendAPNs(params: APNsParams): Promise<void> {
  const notification = new apn.Notification({
    alert: {
      title: params.title,
      body: params.body,
    },
    badge: params.badge,
    sound: params.sound || 'default',
    topic: config.bundleId,
    payload: params.data,
  });

  await provider.send(notification, params.deviceToken);
}
```

---

## Twilio (SMS)

**API Documentation:** https://www.twilio.com/docs/sms

### Configuration

```typescript
interface TwilioConfig {
  accountSid: string;
  authToken: string;
  fromNumber: string;
}
```

### Send SMS

```typescript
import twilio from 'twilio';

const client = twilio(config.accountSid, config.authToken);

async function sendSMS(params: SMSParams): Promise<void> {
  await client.messages.create({
    body: params.message,
    from: config.fromNumber,
    to: params.to,
  });
}
```

### Use Cases

- Two-factor authentication codes
- Critical security alerts
- Payment confirmations
- Stream reminders (opt-in)

---

## Unified Notification Service

```typescript
// libs/aphrodite/notifications/src/service.ts
export class NotificationService {
  constructor(
    private sendgrid: SendGridClient,
    private fcm: FCMClient,
    private apns: APNsClient,
    private twilio: TwilioClient
  ) {}

  async notify(user: User, notification: Notification): Promise<void> {
    const preferences = await this.getPreferences(user.id);

    const promises: Promise<void>[] = [];

    if (preferences.email && notification.channels.includes('email')) {
      promises.push(this.sendEmail(user.email, notification));
    }

    if (preferences.push && notification.channels.includes('push')) {
      promises.push(this.sendPush(user.deviceTokens, notification));
    }

    if (preferences.sms && notification.channels.includes('sms')) {
      promises.push(this.sendSMS(user.phone, notification));
    }

    await Promise.allSettled(promises);
  }
}
```

---

## Document History

| Date       | Version | Changes                                |
| ---------- | ------- | -------------------------------------- |
| 2026-01-18 | 1.0.0   | Initial Notification Integrations docs |
