# flarum-msteams-webhook

Spiegelt Flarum-**Web-Benachrichtigungen** (die Glocke im Forum) in den **Microsoft Teams Activity Feed**.

## Zielbild

Diese erste Version registriert **keinen eigenen Teams-Kanal in der Flarum-UI**. Stattdessen spiegelt die Erweiterung exakt die Benachrichtigungen, die ein Benutzer bereits im **Web/Alert-Kanal** aktiviert hat, nach Teams.

Das ist für Flarum 1.8.x die pragmatischste v1, weil dadurch:

- die bestehende Flarum-Benachrichtigungslogik unverändert bleibt,
- keine Anpassung der Notification-Grid-UI notwendig ist,
- und Teams nur die Benachrichtigungen erhält, die im Forum ohnehin als Web-Alert ankommen würden.

## Kompatibilität

- Flarum: **^1.8**
- PHP: **^8.1**
- Getestetes Zielsystem laut Projekt-Hinweis: **Flarum 1.8.15**, **PHP 8.3.6**

## Was die Extension macht

1. Hängt sich per `Extend\Notification()->beforeSending(...)` in den Flarum-Notification-Flow ein.
2. Prüft für jeden Empfänger, ob die betreffende Notification im **Web-Kanal (`alert`)** aktiviert ist.
3. Löst dafür einen **Queue-Job** aus.
4. Der Queue-Job holt per **Client Credentials Flow** ein Graph-Token.
5. Anschließend wird per Microsoft Graph eine **Teams Activity Feed Notification** an den Benutzer gesendet.

## Voraussetzungen in Microsoft 365 / Entra / Teams

### 1) Entra App Registration

Benötigte Konfiguration:

- `tenant_id`
- `client_id`
- `client_secret`

Benötigte Microsoft Graph **Application Permission**:

- bevorzugt: `TeamsActivity.Send.User`
- alternativ: `TeamsActivity.Send`

### 2) Teams App

Die Ziel-Benutzer müssen die Teams-App installiert haben, für die Benachrichtigungen verschickt werden.

Empfehlung für v1:

- Activity Type: `systemDefault`
- Teams App ID in der Extension-Konfiguration hinterlegen

### 3) Benutzer-Mapping

Diese v1 unterstützt folgende Auflösungsstrategien:

- `email` → `POST /users/{email}/teamwork/sendActivityNotification`
- `upn` → UPN aus User-Preference oder Fallback auf E-Mail
- `preference` → frei konfigurierbarer User-Preference-Key

Wenn euer Entra-/SSO-Login bereits mit identischer E-Mail / UPN arbeitet, reicht meist `email` oder `upn`.

## Installation

### Composer

```bash
composer require sbp-jm/flarum-msteams-webhook:dev-main
```

### Flarum Cache leeren

```bash
php flarum cache:clear
```

## Konfiguration

Da diese v1 noch kein Admin-UI mitliefert, werden die Settings direkt in der Flarum-`settings`-Tabelle gepflegt.

### Pflicht-Settings

```sql
REPLACE INTO settings (`key`, `value`) VALUES
('sbp-jm-msteams-webhook.enabled', '1'),
('sbp-jm-msteams-webhook.tenant_id', 'DEIN-TENANT-ID'),
('sbp-jm-msteams-webhook.client_id', 'DEINE-CLIENT-ID'),
('sbp-jm-msteams-webhook.client_secret', 'DEIN-CLIENT-SECRET'),
('sbp-jm-msteams-webhook.forum_base_url', 'https://forum.example.tld'),
('sbp-jm-msteams-webhook.user_lookup_strategy', 'email'),
('sbp-jm-msteams-webhook.activity_type', 'systemDefault'),
('sbp-jm-msteams-webhook.timeout_seconds', '15');
```

### Optionale Settings

```sql
REPLACE INTO settings (`key`, `value`) VALUES
('sbp-jm-msteams-webhook.teams_app_id', 'DEINE-TEAMS-APP-ID'),
('sbp-jm-msteams-webhook.icon_id', ''),
('sbp-jm-msteams-webhook.upn_preference_key', 'sbp-jm-msteams-webhook.upn'),
('sbp-jm-msteams-webhook.user_preference_key', 'sbp-jm-msteams-webhook.target');
```

## Queue / Scheduler

Die Extension ist für asynchrone Zustellung ausgelegt.

Empfohlen:

```bash
php flarum queue:work
```

Wenn ihr bereits den **database** Queue Driver und einen aktiven Scheduler verwendet, passt diese Erweiterung sehr gut in euer bestehendes Setup.

## Bekannte Einschränkungen der v1

- Noch **kein Admin-UI** zum Setzen der Settings
- Noch **kein User-UI** für persönliches Teams-Ziel / Opt-out
- Noch **keine Teams-Spalte** im Flarum-Notification-Grid
- Activity Feed setzt voraus, dass die passende Teams-App im Zielkontext installiert ist

## Nächste sinnvolle Schritte

1. Admin-UI für Settings ergänzen
2. User-UI für Ziel-UPN / Opt-out ergänzen
3. Optional eine echte `Teams`-Spalte im Notification Grid ergänzen
4. Test-Command (`php flarum teams:test-user <userId>`) hinzufügen
5. Persistentes Delivery-Log ergänzen

## Projektstruktur

```text
extend.php
src/
  Listener/
    MirrorAlertsToTeams.php
  Job/
    SendTeamsActivityNotificationJob.php
  Service/
    GraphTokenProvider.php
    TeamsActivityNotifier.php
  Support/
    NotificationPayloadFactory.php
    TargetResolver.php
```