add ip change notification and refine sender display

app/api/routes/public_ip.py

@@ -3,8 +3,9 @@ from sqlalchemy.orm import Session
 
 from app.dependencies import get_auth_db, get_current_auth_session
 from app.schemas.public_ip import PublicIPCheckResponse
+from app.config import get_settings
 from app.services.auth import AuthenticatedSession
-from app.services.public_ip import check_public_ipv4
+from app.services.public_ip import check_public_ipv4_and_notify
 
 router = APIRouter(tags=["public-ip"])
 
@@ -17,7 +18,7 @@ def run_public_ip_check(
     if current_auth is None:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="authentication required")
 
-    result = check_public_ipv4(session)
+    result = check_public_ipv4_and_notify(session, bootstrap_settings=get_settings())
     return PublicIPCheckResponse(
         status=result.status,
         checked_at=result.checked_at,

app/config.py

@@ -28,6 +28,7 @@ class Settings(BaseSettings):
     smtp_port: int = 587
     smtp_username: str = ""
     smtp_password: str = ""
+    smtp_from_name: str = ""
     smtp_from_address: str = ""
     smtp_to_address: str = ""
     smtp_use_starttls: bool = True

app/main.py

@@ -19,7 +19,7 @@ from app.api.routes.ticktick import router as ticktick_router
 from app.config import get_settings
 from app.services.auth import AuthBootstrapError, initialize_auth_schema
 from app.services.config_page import seed_missing_config_from_bootstrap, sync_app_hostname_from_bootstrap
-from app.services.public_ip import check_public_ipv4
+from app.services.public_ip import check_public_ipv4_and_notify
 from scripts.app_db_adopt import AppDatabaseAdoptionError, validate_app_runtime_db
 from scripts.location_db_adopt import LocationDatabaseAdoptionError, validate_location_runtime_db
 from scripts.poo_db_adopt import PooDatabaseAdoptionError, validate_poo_runtime_db
@@ -29,7 +29,7 @@ def _run_scheduled_public_ip_check() -> None:
     session_local = auth_db.get_auth_session_local()
     session: Session = session_local()
     try:
-        check_public_ipv4(session)
+        check_public_ipv4_and_notify(session, bootstrap_settings=get_settings())
     finally:
         session.close()
 

app/services/config_page.py

@@ -32,6 +32,7 @@ CONFIG_FIELDS: tuple[ConfigField, ...] = (
     ConfigField("SMTP", "SMTP_PORT", "smtp_port", "SMTP Port"),
     ConfigField("SMTP", "SMTP_USERNAME", "smtp_username", "SMTP Username"),
     ConfigField("SMTP", "SMTP_PASSWORD", "smtp_password", "SMTP Password", secret=True),
+    ConfigField("SMTP", "SMTP_FROM_NAME", "smtp_from_name", "SMTP From Name"),
     ConfigField("SMTP", "SMTP_FROM_ADDRESS", "smtp_from_address", "SMTP From Address"),
     ConfigField("SMTP", "SMTP_TO_ADDRESS", "smtp_to_address", "SMTP To Address"),
     ConfigField("SMTP", "SMTP_USE_STARTTLS", "smtp_use_starttls", "SMTP Use STARTTLS"),
@@ -273,6 +274,7 @@ def _settings_payload(settings: Settings) -> dict[str, Any]:
         "smtp_port": settings.smtp_port,
         "smtp_username": settings.smtp_username,
         "smtp_password": settings.smtp_password,
+        "smtp_from_name": settings.smtp_from_name,
         "smtp_from_address": settings.smtp_from_address,
         "smtp_to_address": settings.smtp_to_address,
         "smtp_use_starttls": settings.smtp_use_starttls,

app/services/email.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from datetime import UTC, datetime
 from email.message import EmailMessage
+from email.utils import formataddr
 import smtplib
 
 from app.config import Settings
@@ -21,6 +23,7 @@ class SMTPConfig:
     port: int
     username: str
     password: str
+    from_name: str
     from_address: str
     to_address: str
     use_starttls: bool
@@ -47,6 +50,7 @@ def get_smtp_config(settings: Settings, *, require_enabled: bool = True) -> SMTP
         port=settings.smtp_port,
         username=settings.smtp_username,
         password=settings.smtp_password,
+        from_name=settings.smtp_from_name,
         from_address=settings.smtp_from_address,
         to_address=settings.smtp_to_address,
         use_starttls=settings.smtp_use_starttls,
@@ -72,7 +76,7 @@ def send_plaintext_email(
     smtp_config = get_smtp_config(settings, require_enabled=require_enabled)
     message = EmailMessage()
     message["Subject"] = subject
-    message["From"] = smtp_config.from_address
+    message["From"] = _build_from_header(smtp_config)
     message["To"] = recipient or smtp_config.to_address
     message.set_content(body)
 
@@ -84,7 +88,11 @@ def send_plaintext_email(
                 smtp.ehlo()
             if smtp_config.username:
                 smtp.login(smtp_config.username, smtp_config.password)
-            smtp.send_message(message)
+            smtp.send_message(
+                message,
+                from_addr=smtp_config.from_address,
+                to_addrs=[recipient or smtp_config.to_address],
+            )
     except (OSError, smtplib.SMTPException) as exc:
         error_message = _sanitize_error_message(str(exc), smtp_config.password)
         raise EmailDeliveryError(error_message or "SMTP delivery failed") from exc
@@ -99,8 +107,43 @@ def send_smtp_test_email(settings: Settings) -> None:
     )
 
 
+def send_public_ip_changed_email(
+    settings: Settings,
+    *,
+    previous_ipv4: str,
+    current_ipv4: str,
+    detected_at: datetime,
+) -> None:
+    send_plaintext_email(
+        settings,
+        subject="Public IP changed",
+        body=(
+            "Your public IPv4 address has changed.\n\n"
+            f"Previous IP: {previous_ipv4}\n"
+            f"Current IP: {current_ipv4}\n"
+            f"Detected at: {_format_utc_timestamp(detected_at)}\n\n"
+            "If you use Namecheap API trusted IP restrictions, you may need to "
+            "update the trusted IP manually.\n"
+        ),
+    )
+
+
 def _sanitize_error_message(message: str, password: str) -> str:
     sanitized = message
     if password:
         sanitized = sanitized.replace(password, "[redacted]")
-    return sanitized
+    return sanitized
+
+
+def _format_utc_timestamp(value: datetime) -> str:
+    if value.tzinfo is None:
+        normalized = value.replace(tzinfo=UTC)
+    else:
+        normalized = value.astimezone(UTC)
+    return normalized.strftime("%Y-%m-%d %H:%M:%S UTC")
+
+
+def _build_from_header(smtp_config: SMTPConfig) -> str:
+    if smtp_config.from_name:
+        return formataddr((smtp_config.from_name, smtp_config.from_address))
+    return smtp_config.from_address

app/services/public_ip.py

@@ -10,7 +10,10 @@ import httpx
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
+from app.config import Settings
 from app.models.public_ip import PublicIPHistory, PublicIPState
+from app.services.config_page import build_runtime_settings
+from app.services.email import EmailConfigurationError, EmailDeliveryError, send_public_ip_changed_email
 
 logger = logging.getLogger(__name__)
 
@@ -31,6 +34,8 @@ class PublicIPCheckResult:
     status: PublicIPResultStatus
     checked_at: datetime
     changed: bool
+    previous_ipv4: str | None = None
+    current_ipv4: str | None = None
 
 
 def check_public_ipv4(
@@ -77,7 +82,12 @@ def check_public_ipv4(
             )
         )
         session.commit()
-        return PublicIPCheckResult(status="first_seen", checked_at=checked_at, changed=False)
+        return PublicIPCheckResult(
+            status="first_seen",
+            checked_at=checked_at,
+            changed=False,
+            current_ipv4=current_ipv4,
+        )
 
     if state.current_ipv4 == current_ipv4:
         state.last_checked_at = checked_at
@@ -85,9 +95,15 @@ def check_public_ipv4(
         state.last_check_error = None
         state.last_provider = provider_name
         session.commit()
-        return PublicIPCheckResult(status="unchanged", checked_at=checked_at, changed=False)
+        return PublicIPCheckResult(
+            status="unchanged",
+            checked_at=checked_at,
+            changed=False,
+            current_ipv4=current_ipv4,
+        )
 
-    state.previous_ipv4 = state.current_ipv4
+    previous_ipv4 = state.current_ipv4
+    state.previous_ipv4 = previous_ipv4
     state.current_ipv4 = current_ipv4
     state.last_checked_at = checked_at
     state.last_changed_at = checked_at
@@ -103,7 +119,43 @@ def check_public_ipv4(
         )
     )
     session.commit()
-    return PublicIPCheckResult(status="changed", checked_at=checked_at, changed=True)
+    return PublicIPCheckResult(
+        status="changed",
+        checked_at=checked_at,
+        changed=True,
+        previous_ipv4=previous_ipv4,
+        current_ipv4=current_ipv4,
+    )
+
+
+def check_public_ipv4_and_notify(
+    session: Session,
+    *,
+    bootstrap_settings: Settings,
+    fetch_public_ipv4: PublicIPv4Fetcher | None = None,
+    provider_name: str = PUBLIC_IP_PROVIDER_NAME,
+) -> PublicIPCheckResult:
+    result = check_public_ipv4(
+        session,
+        fetch_public_ipv4=fetch_public_ipv4,
+        provider_name=provider_name,
+    )
+
+    if result.status != "changed" or result.previous_ipv4 is None or result.current_ipv4 is None:
+        return result
+
+    runtime_settings = build_runtime_settings(session, bootstrap_settings)
+    try:
+        send_public_ip_changed_email(
+            runtime_settings,
+            previous_ipv4=result.previous_ipv4,
+            current_ipv4=result.current_ipv4,
+            detected_at=result.checked_at,
+        )
+    except (EmailConfigurationError, EmailDeliveryError) as exc:
+        logger.warning("Public IPv4 change notification failed: %s", exc)
+
+    return result
 
 
 def fetch_public_ipv4_from_provider() -> str: