feat: add email settings with database overrides for admin and vendor

Platform Email Settings (Admin): - Add GET/PUT/DELETE /admin/settings/email/* endpoints - Settings stored in admin_settings table override .env values - Support all providers: SMTP, SendGrid, Mailgun, Amazon SES - Edit mode UI with provider-specific configuration forms - Reset to .env defaults functionality - Test email to verify configuration Vendor Email Settings: - Add VendorEmailSettings model with one-to-one vendor relationship - Migration: v0a1b2c3d4e5_add_vendor_email_settings.py - Service: vendor_email_settings_service.py with tier validation - API endpoints: /vendor/email-settings/* (CRUD, status, verify) - Email tab in vendor settings page with full configuration - Warning banner until email is configured (like billing warnings) - Premium providers (SendGrid, Mailgun, SES) tier-gated to Business+ Email Service Updates: - get_platform_email_config(db) checks DB first, then .env - Configurable provider classes accept config dict - EmailService uses database-aware providers - Vendor emails use vendor's own SMTP (Wizamart doesn't pay) - "Powered by Wizamart" footer for Essential/Professional tiers - White-label (no footer) for Business/Enterprise tiers Other: - Add scripts/install.py for first-time platform setup - Add make install target - Update init-prod to include email template seeding 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-05 22:23:47 +01:00
parent ad28a8a9a3
commit 36603178c3
51 changed files with 4959 additions and 1141 deletions
--- a/app/api/v1/vendor/init.py
+++ b/app/api/v1/vendor/init.py
@@ -20,6 +20,7 @@ from . import (
    content_pages,
    customers,
    dashboard,
+    email_settings,
    email_templates,
    features,
    info,
@@ -61,6 +62,7 @@ router.include_router(dashboard.router, tags=["vendor-dashboard"])
 router.include_router(profile.router, tags=["vendor-profile"])
 router.include_router(settings.router, tags=["vendor-settings"])
 router.include_router(email_templates.router, tags=["vendor-email-templates"])
+router.include_router(email_settings.router, tags=["vendor-email-settings"])
 router.include_router(onboarding.router, tags=["vendor-onboarding"])

 # Business operations (with prefixes: /products/*, /orders/*, etc.)
--- a/app/api/v1/vendor/content_pages.py
+++ b/app/api/v1/vendor/content_pages.py
@@ -2,6 +2,9 @@
 """
 Vendor Content Pages API

+Vendor Context: Uses token_vendor_id from JWT token (authenticated vendor API pattern).
+The get_current_vendor_api dependency guarantees token_vendor_id is present.
+
 Vendors can:
 - View their content pages (includes platform defaults)
 - Create/edit/delete their own content page overrides
@@ -15,11 +18,10 @@ from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session

 from app.api.deps import get_current_vendor_api, get_db
-from app.exceptions.content_page import VendorNotAssociatedException
 from app.services.content_page_service import content_page_service
 from models.database.user import User

-router = APIRouter()
+router = APIRouter(prefix="/content-pages")
 logger = logging.getLogger(__name__)


@@ -111,11 +113,8 @@ def list_vendor_pages(

    Returns vendor-specific overrides + platform defaults (vendor overrides take precedence).
    """
-    if not current_user.vendor_id:
-        raise VendorNotAssociatedException()
-
    pages = content_page_service.list_pages_for_vendor(
-        db, vendor_id=current_user.vendor_id, include_unpublished=include_unpublished
+        db, vendor_id=current_user.token_vendor_id, include_unpublished=include_unpublished
    )

    return [page.to_dict() for page in pages]
@@ -132,11 +131,8 @@ def list_vendor_overrides(

    Shows what the vendor has customized.
    """
-    if not current_user.vendor_id:
-        raise VendorNotAssociatedException()
-
    pages = content_page_service.list_all_vendor_pages(
-        db, vendor_id=current_user.vendor_id, include_unpublished=include_unpublished
+        db, vendor_id=current_user.token_vendor_id, include_unpublished=include_unpublished
    )

    return [page.to_dict() for page in pages]
@@ -154,13 +150,10 @@ def get_page(

    Returns vendor override if exists, otherwise platform default.
    """
-    if not current_user.vendor_id:
-        raise VendorNotAssociatedException()
-
    page = content_page_service.get_page_for_vendor_or_raise(
        db,
        slug=slug,
-        vendor_id=current_user.vendor_id,
+        vendor_id=current_user.token_vendor_id,
        include_unpublished=include_unpublished,
    )

@@ -178,15 +171,12 @@ def create_vendor_page(

    This will be shown instead of the platform default for this vendor.
    """
-    if not current_user.vendor_id:
-        raise VendorNotAssociatedException()
-
    page = content_page_service.create_page(
        db,
        slug=page_data.slug,
        title=page_data.title,
        content=page_data.content,
-        vendor_id=current_user.vendor_id,
+        vendor_id=current_user.token_vendor_id,
        content_format=page_data.content_format,
        meta_description=page_data.meta_description,
        meta_keywords=page_data.meta_keywords,
@@ -214,14 +204,11 @@ def update_vendor_page(

    Can only update pages owned by this vendor.
    """
-    if not current_user.vendor_id:
-        raise VendorNotAssociatedException()
-
    # Update with ownership check in service layer
    page = content_page_service.update_vendor_page(
        db,
        page_id=page_id,
-        vendor_id=current_user.vendor_id,
+        vendor_id=current_user.token_vendor_id,
        title=page_data.title,
        content=page_data.content,
        content_format=page_data.content_format,
@@ -251,9 +238,6 @@ def delete_vendor_page(
    Can only delete pages owned by this vendor.
    After deletion, platform default will be shown (if exists).
    """
-    if not current_user.vendor_id:
-        raise VendorNotAssociatedException()
-
    # Delete with ownership check in service layer
-    content_page_service.delete_vendor_page(db, page_id, current_user.vendor_id)
+    content_page_service.delete_vendor_page(db, page_id, current_user.token_vendor_id)
    db.commit()
--- a/app/api/v1/vendor/email_settings.py
+++ b/app/api/v1/vendor/email_settings.py
@@ -0,0 +1,225 @@
+# app/api/v1/vendor/email_settings.py
+"""
+Vendor email settings API endpoints.
+
+Allows vendors to configure their email sending settings:
+- SMTP configuration (all tiers)
+- Advanced providers: SendGrid, Mailgun, SES (Business+ tier)
+- Sender identity (from_email, from_name, reply_to)
+- Signature/footer customization
+- Configuration verification via test email
+
+Vendor Context: Uses token_vendor_id from JWT token (authenticated vendor API pattern).
+"""
+
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, EmailStr, Field
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_current_vendor_api
+from app.core.database import get_db
+from app.exceptions import NotFoundError, ValidationError, AuthorizationError
+from app.services.vendor_email_settings_service import VendorEmailSettingsService
+from app.services.subscription_service import subscription_service
+from models.database.user import User
+
+router = APIRouter(prefix="/email-settings")
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# SCHEMAS
+# =============================================================================
+
+
+class EmailSettingsUpdate(BaseModel):
+    """Schema for creating/updating email settings."""
+
+    # Sender Identity (Required)
+    from_email: EmailStr = Field(..., description="Sender email address")
+    from_name: str = Field(..., min_length=1, max_length=100, description="Sender name")
+    reply_to_email: EmailStr | None = Field(None, description="Reply-to email address")
+
+    # Signature (Optional)
+    signature_text: str | None = Field(None, description="Plain text signature")
+    signature_html: str | None = Field(None, description="HTML signature/footer")
+
+    # Provider
+    provider: str = Field("smtp", description="Email provider: smtp, sendgrid, mailgun, ses")
+
+    # SMTP Settings
+    smtp_host: str | None = Field(None, description="SMTP server hostname")
+    smtp_port: int | None = Field(587, ge=1, le=65535, description="SMTP server port")
+    smtp_username: str | None = Field(None, description="SMTP username")
+    smtp_password: str | None = Field(None, description="SMTP password")
+    smtp_use_tls: bool = Field(True, description="Use STARTTLS")
+    smtp_use_ssl: bool = Field(False, description="Use SSL/TLS (port 465)")
+
+    # SendGrid
+    sendgrid_api_key: str | None = Field(None, description="SendGrid API key")
+
+    # Mailgun
+    mailgun_api_key: str | None = Field(None, description="Mailgun API key")
+    mailgun_domain: str | None = Field(None, description="Mailgun sending domain")
+
+    # SES
+    ses_access_key_id: str | None = Field(None, description="AWS access key ID")
+    ses_secret_access_key: str | None = Field(None, description="AWS secret access key")
+    ses_region: str | None = Field("eu-west-1", description="AWS region")
+
+
+class VerifyEmailRequest(BaseModel):
+    """Schema for verifying email settings."""
+
+    test_email: EmailStr = Field(..., description="Email address to send test email to")
+
+
+# =============================================================================
+# ENDPOINTS
+# =============================================================================
+
+
+@router.get("")
+def get_email_settings(
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """
+    Get current email settings for the vendor.
+
+    Returns settings with sensitive fields masked.
+    """
+    vendor_id = current_user.token_vendor_id
+    service = VendorEmailSettingsService(db)
+
+    settings = service.get_settings(vendor_id)
+    if not settings:
+        return {
+            "configured": False,
+            "settings": None,
+            "message": "Email settings not configured. Configure SMTP to send emails to customers.",
+        }
+
+    return {
+        "configured": settings.is_configured,
+        "verified": settings.is_verified,
+        "settings": settings.to_dict(),
+    }
+
+
+@router.get("/status")
+def get_email_status(
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """
+    Get email configuration status.
+
+    Used by frontend to show warning banner if not configured.
+    """
+    vendor_id = current_user.token_vendor_id
+    service = VendorEmailSettingsService(db)
+    return service.get_status(vendor_id)
+
+
+@router.get("/providers")
+def get_available_providers(
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """
+    Get available email providers for current tier.
+
+    Returns list of providers with availability status.
+    """
+    vendor_id = current_user.token_vendor_id
+    service = VendorEmailSettingsService(db)
+
+    # Get vendor's current tier
+    tier = subscription_service.get_current_tier(db, vendor_id)
+
+    return {
+        "providers": service.get_available_providers(tier),
+        "current_tier": tier.value if tier else None,
+    }
+
+
+@router.put("")
+def update_email_settings(
+    data: EmailSettingsUpdate,
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """
+    Create or update email settings.
+
+    Premium providers (SendGrid, Mailgun, SES) require Business+ tier.
+    """
+    vendor_id = current_user.token_vendor_id
+    service = VendorEmailSettingsService(db)
+
+    # Get vendor's current tier for validation
+    tier = subscription_service.get_current_tier(db, vendor_id)
+
+    try:
+        settings = service.create_or_update(
+            vendor_id=vendor_id,
+            data=data.model_dump(exclude_unset=True),
+            current_tier=tier,
+        )
+        return {
+            "success": True,
+            "message": "Email settings updated successfully",
+            "settings": settings.to_dict(),
+        }
+    except AuthorizationError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+    except ValidationError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/verify")
+def verify_email_settings(
+    data: VerifyEmailRequest,
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """
+    Verify email settings by sending a test email.
+
+    Sends a test email to the provided address and updates verification status.
+    """
+    vendor_id = current_user.token_vendor_id
+    service = VendorEmailSettingsService(db)
+
+    try:
+        result = service.verify_settings(vendor_id, data.test_email)
+        if result["success"]:
+            return result
+        else:
+            raise HTTPException(status_code=400, detail=result["message"])
+    except NotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except ValidationError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("")
+def delete_email_settings(
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """
+    Delete email settings.
+
+    Warning: This will disable email sending for the vendor.
+    """
+    vendor_id = current_user.token_vendor_id
+    service = VendorEmailSettingsService(db)
+
+    if service.delete(vendor_id):
+        return {"success": True, "message": "Email settings deleted"}
+    else:
+        raise HTTPException(status_code=404, detail="Email settings not found")