AI for coding? Nie ma ucieczki!

# 📧 ExchangeMailbox - Node.js Email Client

Projekt Node.js implementujący klasę `ExchangeMailbox` do wysyłania wiadomości email przez Microsoft Graph API.

## 🚀 Funkcjonalności

- ✅ **Klasa ExchangeMailbox** z metodą `sendMail`
- ✅ **Integracja z MS Graph API** do wysyłania emaili
- ✅ **Uwierzytelnianie** przez Azure AD (MSAL)
- ✅ **Konfiguracja przez zmienne środowiskowe** (.env)
- ✅ **Obsługa HTML i tekstowych emaili**
- ✅ **Wsparcie dla załączników**
- ✅ **Test połączenia** z MS Graph API
- ✅ **Przykłady użycia** i testy

## 📋 Wymagania

- Node.js 16+
- Konto Microsoft 365 / Azure AD
- Zarejestrowana aplikacja w Azure Portal
- **Uprawnienia administratora Azure AD** (do zatwierdzenia uprawnień aplikacji)

## 🛠️ Instalacja

1. **Sklonuj/pobierz projekt**
2. **Zainstaluj zależności:**

   ```bash
   npm install
   ```

3. **Skonfiguruj zmienne środowiskowe** (zobacz sekcję konfiguracja)

4. **Uruchom test:**
   ```bash
   npm start
   ```

## ⚙️ Konfiguracja Azure AD

### 1. Rejestracja aplikacji w Azure Portal

1. Przejdź do [Azure Portal](https://portal.azure.com)
2. Wybierz **Azure Active Directory** > **App registrations** > **New registration**
3. Podaj nazwę aplikacji (np. "ExchangeMailbox App")
4. Wybierz **Accounts in this organizational directory only**
5. Kliknij **Register**

### 2. Konfiguracja uprawnień API

1. W zarejestrowanej aplikacji przejdź do **API permissions**
2. Kliknij **Add a permission** > **Microsoft Graph** > **Application permissions**
3. Dodaj uprawnienie:
   - `Mail.Send` - do wysyłania emaili w imieniu aplikacji
4. Kliknij **Grant admin consent** (wymagane uprawnienia administratora)

> **Uwaga:** Używamy uwierzytelniania aplikacji (Client Credentials flow), które pozwala aplikacji działać bez logowania użytkownika, ale wymaga uprawnień administratora.

### 3. Utworzenie Client Secret

1. Przejdź do **Certificates & secrets**
2. Kliknij **New client secret**
3. Podaj opis i wybierz okres ważności
4. **Skopiuj wartość** - będzie potrzebna w pliku .env

### 4. Skopiuj identyfikatory

Z sekcji **Overview** skopiuj:

- **Application (client) ID**
- **Directory (tenant) ID**

## 🔧 Konfiguracja zmiennych środowiskowych

Skopiuj plik `.env` i wypełnij następujące wartości:

```env
# MS Graph API Configuration
AZURE_CLIENT_ID=your_client_id_here
AZURE_CLIENT_SECRET=your_client_secret_here
AZURE_TENANT_ID=your_tenant_id_here
SENDER_EMAIL=your_sender_email@yourdomain.com
TEST_RECIPIENT_EMAIL=test_recipient@example.com
```

### Gdzie znaleźć te wartości:

- **AZURE_CLIENT_ID**: Application ID z Azure Portal
- **AZURE_CLIENT_SECRET**: Client Secret utworzony w Azure Portal
- **AZURE_TENANT_ID**: Directory ID z Azure Portal
- **SENDER_EMAIL**: Email użytkownika, który będzie nadawcą (musi istnieć w organizacji)
- **TEST_RECIPIENT_EMAIL**: Email do testów (opcjonalne)

## 📖 Użycie

### Podstawowy przykład

```javascript
import { ExchangeMailbox } from './ExchangeMailbox.js'

const mailbox = new ExchangeMailbox()

// Wysłanie prostego emaila
const result = await mailbox.sendMail({
  to: 'odbiorca@example.com',
  subject: 'Temat wiadomości',
  body: 'Treść wiadomości'
})

if (result.success) {
  console.log('Email wysłany pomyślnie!')
} else {
  console.error('Błąd:', result.message)
}
```

### Email z HTML

```javascript
await mailbox.sendMail({
  to: 'odbiorca@example.com',
  subject: 'Email z HTML',
  body: '<h1>Witaj!</h1><p>To jest <strong>HTML</strong> email.</p>',
  bodyType: 'HTML'
})
```

### Email z załącznikami

```javascript
await mailbox.sendMail({
  to: 'odbiorca@example.com',
  subject: 'Email z załącznikiem',
  body: 'Zobacz załącznik w załączniku',
  attachments: [
    {
      name: 'dokument.pdf',
      contentBytes: 'base64_encoded_file_content',
      contentType: 'application/pdf'
    }
  ]
})
```

### Test połączenia

```javascript
const isConnected = await mailbox.testConnection()
if (isConnected) {
  console.log('Połączenie z MS Graph API działa!')
}
```

> **Uwaga:** Test połączenia sprawdza czy można uzyskać token dostępu z Azure AD. Nie wymaga dodatkowych uprawnień API.

## 🏃 Uruchomienie testów

```bash
# Uruchomienie testów
npm start

# lub bezpośrednio
node main.js
```

## 📁 Struktura projektu

```
exchange-mailbox-nodejs/
├── 📄 ExchangeMailbox.js    # Główna klasa do wysyłania emaili
├── 📄 main.js              # Testy i przykłady użycia
├── 📄 package.json         # Konfiguracja NPM i zależności
├── 📄 .env                 # Zmienne środowiskowe (konfiguracja)
├── 📄 .gitignore          # Wykluczenia Git (chroni .env)
├── 📄 README.md           # Dokumentacja (ten plik)
└── 📁 .github/
    └── 📄 copilot-instructions.md  # Instrukcje dla Copilot
```

## 🔍 Rozwiązywanie problemów

### Błędy uwierzytelniania

1. **"Invalid client credentials"** - sprawdź Client ID i Client Secret w pliku .env
2. **"Invalid tenant"** - sprawdź Tenant ID w pliku .env
3. **"Insufficient privileges"** - upewnij się że aplikacja ma uprawnienie `Mail.Send` i zostało zatwierdzone przez administratora

### Błędy wysyłania emaili

1. **"User not found"** - sprawdź czy SENDER_EMAIL to prawdziwy użytkownik w organizacji
2. **"Access denied"** - sprawdź czy admin zatwierdził uprawnienia aplikacji
3. **"Mailbox not found"** - upewnij się że użytkownik ma licencję Exchange Online

### Częste problemy podczas testów

1. **"/me request is only valid with delegated authentication flow"** - Ten błąd jest normalny, używamy uwierzytelniania aplikacji (client credentials)
2. **"Insufficient privileges to complete the operation"** - Nie jest potrzebne uprawnienie User.Read dla podstawowej funkcjonalności wysyłania emaili
3. **"TypeError: \_this.provider is not a function"** - Problem z konfiguracją klienta Graph, rozwiązany w aktualnej wersji

### Debugging

- Test połączenia sprawdza czy można uzyskać token dostępu (nie wymaga dodatkowych uprawnień)
- Włącz szczegółowe logi błędów w konsoli aby zobaczyć dokładne komunikaty z MS Graph API
- Sprawdź czy wszystkie zmienne środowiskowe w .env są wypełnione

## 📦 Zależności

- `@azure/msal-node` - Uwierzytelnianie Microsoft Authentication Library
- `@microsoft/microsoft-graph-client` - Klient MS Graph API
- `dotenv` - Ładowanie zmiennych środowiskowych

## 📄 Licencja

MIT License - możesz swobodnie używać, modyfikować i dystrybuować ten kod.

## 🆘 Pomoc

Jeśli napotkasz problemy:

1. Sprawdź konfigurację w Azure Portal
2. Zweryfikuj zmienne środowiskowe w `.env`
3. Uruchom test połączenia: `await mailbox.testConnection()`
4. Sprawdź logi błędów w konsoli

---

**📧 Miłego wysyłania emaili z ExchangeMailbox! 🚀**