jrrribeiro commited on
Commit
d94e719
·
1 Parent(s): 530fa70

feat(email): add HTTP fallback notifier for invite delivery

Browse files
README.md CHANGED
@@ -74,6 +74,14 @@ Invite email settings (SMTP):
74
  - `BIRDNET_SMTP_USERNAME`: SMTP username (optional).
75
  - `BIRDNET_SMTP_PASSWORD`: SMTP password or app token.
76
  - `BIRDNET_SMTP_USE_TLS`: set to `false` only when TLS is not available.
 
 
 
 
 
 
 
 
77
 
78
  JSON seed format examples:
79
 
@@ -240,6 +248,13 @@ Optional invite email settings:
240
  - `BIRDNET_SMTP_USERNAME`
241
  - `BIRDNET_SMTP_PASSWORD`
242
  - `BIRDNET_SMTP_USE_TLS`
 
 
 
 
 
 
 
243
 
244
  4. For first smoke test only, you may temporarily set:
245
  - `BIRDNET_ENABLE_DEMO_BOOTSTRAP=true`
 
74
  - `BIRDNET_SMTP_USERNAME`: SMTP username (optional).
75
  - `BIRDNET_SMTP_PASSWORD`: SMTP password or app token.
76
  - `BIRDNET_SMTP_USE_TLS`: set to `false` only when TLS is not available.
77
+ - `BIRDNET_SMTP_USE_SSL`: set to `true` for implicit SSL (typically port `465`).
78
+
79
+ Optional invite email fallback (HTTP API over port 443):
80
+
81
+ - `BIRDNET_INVITE_EMAIL_HTTP_ENABLED`: set to `true` to enable HTTP provider.
82
+ - `BIRDNET_INVITE_EMAIL_HTTP_ENDPOINT`: provider endpoint (expects JSON POST with bearer token).
83
+ - `BIRDNET_INVITE_EMAIL_HTTP_API_KEY`: provider API key.
84
+ - `BIRDNET_INVITE_EMAIL_HTTP_TIMEOUT_SECONDS`: request timeout in seconds (default: `20`).
85
 
86
  JSON seed format examples:
87
 
 
248
  - `BIRDNET_SMTP_USERNAME`
249
  - `BIRDNET_SMTP_PASSWORD`
250
  - `BIRDNET_SMTP_USE_TLS`
251
+ - `BIRDNET_SMTP_USE_SSL`
252
+
253
+ Optional HTTP fallback settings:
254
+ - `BIRDNET_INVITE_EMAIL_HTTP_ENABLED`
255
+ - `BIRDNET_INVITE_EMAIL_HTTP_ENDPOINT`
256
+ - `BIRDNET_INVITE_EMAIL_HTTP_API_KEY`
257
+ - `BIRDNET_INVITE_EMAIL_HTTP_TIMEOUT_SECONDS`
258
 
259
  4. For first smoke test only, you may temporarily set:
260
  - `BIRDNET_ENABLE_DEMO_BOOTSTRAP=true`
src/config/runtime_config.py CHANGED
@@ -24,6 +24,10 @@ class RuntimeConfig:
24
  smtp_password: str | None
25
  smtp_use_tls: bool
26
  smtp_use_ssl: bool = False
 
 
 
 
27
 
28
  @classmethod
29
  def from_env(cls) -> "RuntimeConfig":
@@ -91,6 +95,20 @@ class RuntimeConfig:
91
  raw_smtp_use_ssl = (os.getenv("BIRDNET_SMTP_USE_SSL") or "").strip().lower()
92
  smtp_use_ssl = raw_smtp_use_ssl in {"1", "true", "yes", "on"}
93
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
94
  return cls(
95
  detection_seed_path=detection_seed_path,
96
  validation_base_dir=validation_base_dir,
@@ -110,4 +128,8 @@ class RuntimeConfig:
110
  smtp_password=smtp_password,
111
  smtp_use_tls=smtp_use_tls,
112
  smtp_use_ssl=smtp_use_ssl,
 
 
 
 
113
  )
 
24
  smtp_password: str | None
25
  smtp_use_tls: bool
26
  smtp_use_ssl: bool = False
27
+ invite_email_http_enabled: bool = False
28
+ invite_email_http_endpoint: str | None = None
29
+ invite_email_http_api_key: str | None = None
30
+ invite_email_http_timeout_seconds: int = 20
31
 
32
  @classmethod
33
  def from_env(cls) -> "RuntimeConfig":
 
95
  raw_smtp_use_ssl = (os.getenv("BIRDNET_SMTP_USE_SSL") or "").strip().lower()
96
  smtp_use_ssl = raw_smtp_use_ssl in {"1", "true", "yes", "on"}
97
 
98
+ raw_invite_email_http_enabled = (os.getenv("BIRDNET_INVITE_EMAIL_HTTP_ENABLED") or "").strip().lower()
99
+ invite_email_http_enabled = raw_invite_email_http_enabled in {"1", "true", "yes", "on"}
100
+ invite_email_http_endpoint = (os.getenv("BIRDNET_INVITE_EMAIL_HTTP_ENDPOINT") or "").strip() or None
101
+ invite_email_http_api_key = (os.getenv("BIRDNET_INVITE_EMAIL_HTTP_API_KEY") or "").strip() or None
102
+ raw_invite_email_http_timeout = (os.getenv("BIRDNET_INVITE_EMAIL_HTTP_TIMEOUT_SECONDS") or "").strip()
103
+ invite_email_http_timeout_seconds = 20
104
+ if raw_invite_email_http_timeout:
105
+ try:
106
+ parsed = int(raw_invite_email_http_timeout)
107
+ if parsed > 0:
108
+ invite_email_http_timeout_seconds = parsed
109
+ except ValueError:
110
+ invite_email_http_timeout_seconds = 20
111
+
112
  return cls(
113
  detection_seed_path=detection_seed_path,
114
  validation_base_dir=validation_base_dir,
 
128
  smtp_password=smtp_password,
129
  smtp_use_tls=smtp_use_tls,
130
  smtp_use_ssl=smtp_use_ssl,
131
+ invite_email_http_enabled=invite_email_http_enabled,
132
+ invite_email_http_endpoint=invite_email_http_endpoint,
133
+ invite_email_http_api_key=invite_email_http_api_key,
134
+ invite_email_http_timeout_seconds=invite_email_http_timeout_seconds,
135
  )
src/services/invite_email_notifier.py CHANGED
@@ -2,8 +2,10 @@
2
 
3
  from dataclasses import dataclass
4
  from datetime import datetime
 
5
  import smtplib
6
  from email.message import EmailMessage
 
7
 
8
 
9
  @dataclass(frozen=True)
@@ -31,6 +33,85 @@ class NoopInviteEmailNotifier(InviteEmailNotifier):
31
  return False, "Invite email not sent: email notifications are disabled"
32
 
33
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
34
  class SmtpInviteEmailNotifier(InviteEmailNotifier):
35
  """SMTP-based email notifier for project invites."""
36
 
 
2
 
3
  from dataclasses import dataclass
4
  from datetime import datetime
5
+ import json
6
  import smtplib
7
  from email.message import EmailMessage
8
+ from urllib import request
9
 
10
 
11
  @dataclass(frozen=True)
 
33
  return False, "Invite email not sent: email notifications are disabled"
34
 
35
 
36
+ class HttpInviteEmailNotifier(InviteEmailNotifier):
37
+ """HTTP webhook-based notifier for invite emails."""
38
+
39
+ def __init__(
40
+ self,
41
+ sender_email: str,
42
+ endpoint: str,
43
+ api_key: str,
44
+ timeout_seconds: int = 20,
45
+ ):
46
+ self._sender_email = sender_email
47
+ self._endpoint = endpoint
48
+ self._api_key = api_key
49
+ self._timeout_seconds = max(5, int(timeout_seconds))
50
+
51
+ def send(self, payload: InviteEmailPayload) -> tuple[bool, str]:
52
+ body_text = (
53
+ f"Hello {payload.invitee_username},\n\n"
54
+ f"You were invited by {payload.invited_by} to collaborate on project '{payload.project_slug}' "
55
+ f"with role '{payload.role}'.\n"
56
+ f"Invite expires at: {payload.expires_at.isoformat()}\n\n"
57
+ "How to join:\n"
58
+ "1) Open Hugging Face and create an Access Token in Settings -> Access Tokens.\n"
59
+ "2) Open BirdNET Validator login.\n"
60
+ "3) Login using your Hugging Face token.\n"
61
+ "4) Go to 'Select Project' and accept your invite.\n\n"
62
+ f"Login URL: {payload.login_url or '(configured by admin)'}\n\n"
63
+ "If you were not expecting this invitation, ignore this email.\n"
64
+ )
65
+
66
+ req_payload = {
67
+ "from": self._sender_email,
68
+ "to": [payload.invitee_email],
69
+ "subject": f"BirdNET project invite: {payload.project_slug}",
70
+ "text": body_text,
71
+ "metadata": {
72
+ "project_slug": payload.project_slug,
73
+ "invitee_username": payload.invitee_username,
74
+ "role": payload.role,
75
+ },
76
+ }
77
+
78
+ try:
79
+ req = request.Request(
80
+ self._endpoint,
81
+ data=json.dumps(req_payload).encode("utf-8"),
82
+ headers={
83
+ "Content-Type": "application/json",
84
+ "Authorization": f"Bearer {self._api_key}",
85
+ },
86
+ method="POST",
87
+ )
88
+ with request.urlopen(req, timeout=self._timeout_seconds) as response:
89
+ status_code = int(getattr(response, "status", 0) or response.getcode())
90
+ if 200 <= status_code < 300:
91
+ return True, f"Invite email sent to {payload.invitee_email}"
92
+ return False, f"Invite created, but HTTP email API returned status {status_code}"
93
+ except Exception as exc:
94
+ return False, f"Invite created, but HTTP email delivery failed: {exc}"
95
+
96
+
97
+ class FallbackInviteEmailNotifier(InviteEmailNotifier):
98
+ """Tries a primary notifier first, then falls back to a secondary notifier."""
99
+
100
+ def __init__(self, primary: InviteEmailNotifier, secondary: InviteEmailNotifier):
101
+ self._primary = primary
102
+ self._secondary = secondary
103
+
104
+ def send(self, payload: InviteEmailPayload) -> tuple[bool, str]:
105
+ ok, status = self._primary.send(payload)
106
+ if ok:
107
+ return ok, status
108
+
109
+ fallback_ok, fallback_status = self._secondary.send(payload)
110
+ if fallback_ok:
111
+ return True, f"{status} | fallback: {fallback_status}"
112
+ return False, f"{status} | fallback: {fallback_status}"
113
+
114
+
115
  class SmtpInviteEmailNotifier(InviteEmailNotifier):
116
  """SMTP-based email notifier for project invites."""
117
 
src/ui/app_factory.py CHANGED
@@ -23,7 +23,12 @@ from src.repositories.in_memory_detection_repository import InMemoryDetectionRep
23
  from src.services.audio_fetch_service import AudioFetchService
24
  from src.services.detection_queue_service import DetectionQueueService
25
  from src.services.validation_service import ValidationService
26
- from src.services.invite_email_notifier import NoopInviteEmailNotifier, SmtpInviteEmailNotifier
 
 
 
 
 
27
  from src.auth.auth_service import AuthService
28
  from src.ui.login_page import create_login_page
29
  from src.ui.admin_panel import AdminPanelManager
@@ -2476,12 +2481,15 @@ def create_app() -> gr.Blocks:
2476
  )
2477
 
2478
  invite_notifier = NoopInviteEmailNotifier()
 
 
 
2479
  if (
2480
  runtime_config.invite_email_enabled
2481
  and runtime_config.invite_email_sender
2482
  and runtime_config.smtp_host
2483
  ):
2484
- invite_notifier = SmtpInviteEmailNotifier(
2485
  sender_email=runtime_config.invite_email_sender,
2486
  smtp_host=runtime_config.smtp_host,
2487
  smtp_port=runtime_config.smtp_port,
@@ -2491,6 +2499,27 @@ def create_app() -> gr.Blocks:
2491
  smtp_use_ssl=runtime_config.smtp_use_ssl,
2492
  )
2493
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2494
  # Initialize admin panel manager
2495
  admin_manager = AdminPanelManager(
2496
  auth_service,
 
23
  from src.services.audio_fetch_service import AudioFetchService
24
  from src.services.detection_queue_service import DetectionQueueService
25
  from src.services.validation_service import ValidationService
26
+ from src.services.invite_email_notifier import (
27
+ FallbackInviteEmailNotifier,
28
+ HttpInviteEmailNotifier,
29
+ NoopInviteEmailNotifier,
30
+ SmtpInviteEmailNotifier,
31
+ )
32
  from src.auth.auth_service import AuthService
33
  from src.ui.login_page import create_login_page
34
  from src.ui.admin_panel import AdminPanelManager
 
2481
  )
2482
 
2483
  invite_notifier = NoopInviteEmailNotifier()
2484
+ smtp_notifier = None
2485
+ http_notifier = None
2486
+
2487
  if (
2488
  runtime_config.invite_email_enabled
2489
  and runtime_config.invite_email_sender
2490
  and runtime_config.smtp_host
2491
  ):
2492
+ smtp_notifier = SmtpInviteEmailNotifier(
2493
  sender_email=runtime_config.invite_email_sender,
2494
  smtp_host=runtime_config.smtp_host,
2495
  smtp_port=runtime_config.smtp_port,
 
2499
  smtp_use_ssl=runtime_config.smtp_use_ssl,
2500
  )
2501
 
2502
+ if (
2503
+ runtime_config.invite_email_enabled
2504
+ and runtime_config.invite_email_sender
2505
+ and runtime_config.invite_email_http_enabled
2506
+ and runtime_config.invite_email_http_endpoint
2507
+ and runtime_config.invite_email_http_api_key
2508
+ ):
2509
+ http_notifier = HttpInviteEmailNotifier(
2510
+ sender_email=runtime_config.invite_email_sender,
2511
+ endpoint=runtime_config.invite_email_http_endpoint,
2512
+ api_key=runtime_config.invite_email_http_api_key,
2513
+ timeout_seconds=runtime_config.invite_email_http_timeout_seconds,
2514
+ )
2515
+
2516
+ if smtp_notifier and http_notifier:
2517
+ invite_notifier = FallbackInviteEmailNotifier(primary=smtp_notifier, secondary=http_notifier)
2518
+ elif smtp_notifier:
2519
+ invite_notifier = smtp_notifier
2520
+ elif http_notifier:
2521
+ invite_notifier = http_notifier
2522
+
2523
  # Initialize admin panel manager
2524
  admin_manager = AdminPanelManager(
2525
  auth_service,