fix: merge main branch and renumber migration 037→040

Resolve all merge conflicts between our automation feature branch and
current main (v0.163.0, 920 commits ahead).

Conflicts resolved:
- app/api/__init__.py: add automation_router alongside main's new routers
  (classification_rules, qr_auth, sessions, system_reset)
- app/config.py: add main's new settings (dropbox_use_global_credentials,
  factory_reset_on_startup, enable_factory_reset)
- app/models.py: add main's new models (ClassificationRuleModel, UserSession,
  QRLoginChallenge, SharePoint integration type)
- app/utils/settings_service.py: merge automation_hooks_enabled with main's
  new metadata entries
- docs/API.md: merge automation API docs with main's classification rules docs
- docs/ConfigurationGuide.md: add factory reset settings
- tests/conftest.py: import both AutomationHook and new main models

Migration renumbered:
- 037_add_automation_hooks → 040_add_automation_hooks
- down_revision: 039_add_classification_rules (was 036_add_document_translation_fields)
- Chain: 036 → 037 → 038 → 039 → 040 (automation hooks)

For all non-automation files with conflicts, main's version was taken since
our branch did not modify those files (conflicts were from a stale prior merge).

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
Agent-Logs-Url: https://github.com/christianlouis/DocuElevate/sessions/cb62f012-3b69-4415-835e-3857ce3e9f45

app/api/dropbox.py

@@ -5,6 +5,7 @@ Dropbox API endpoints
 import logging
 import os
 from typing import Annotated, Optional
+from urllib.parse import quote
 
 import httpx
 from fastapi import APIRouter, Depends, Form, HTTPException, Request, status
@@ -23,6 +24,93 @@ logger = logging.getLogger(__name__)
 router = APIRouter()
 
 
+def _build_dropbox_redirect_uri(request: Request) -> str:
+    """Build the Dropbox OAuth callback redirect URI.
+
+    Uses ``PUBLIC_BASE_URL`` when configured (recommended for deployments behind
+    a reverse proxy that doesn't forward ``X-Forwarded-Proto``).  Falls back to
+    deriving the URI from the incoming request's scheme and host headers.
+    """
+    if settings.public_base_url:
+        return settings.public_base_url.rstrip("/") + "/dropbox-callback"
+    return f"{request.url.scheme}://{request.url.netloc}/dropbox-callback"
+
+
+@router.get("/dropbox/global-authorize-url")
+@require_login
+async def dropbox_global_authorize_url(request: Request):
+    """Return the Dropbox OAuth authorization URL using the global app credentials.
+
+    This endpoint is used when ``DROPBOX_ALLOW_GLOBAL_CREDENTIALS_FOR_INTEGRATIONS``
+    is enabled so that users can authorize their personal Dropbox integration without
+    needing to supply their own app key/secret.  Only the public ``app_key`` is
+    embedded in the URL; the ``app_secret`` is never sent to the browser.
+    """
+    if not settings.dropbox_allow_global_credentials_for_integrations:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Global credentials for integrations are not enabled",
+        )
+    if not settings.dropbox_app_key or not settings.dropbox_app_secret:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Global Dropbox credentials are not configured",
+        )
+    redirect_uri = _build_dropbox_redirect_uri(request)
+    authorize_url = (
+        "https://www.dropbox.com/oauth2/authorize"
+        f"?client_id={settings.dropbox_app_key}"
+        "&response_type=code"
+        "&token_access_type=offline"
+        f"&redirect_uri={quote(redirect_uri, safe='')}"
+    )
+    return {"authorize_url": authorize_url}
+
+
+@router.post("/dropbox/exchange-token-global")
+@require_login
+async def exchange_dropbox_token_global(
+    request: Request,
+    code: Annotated[str, Form(...)],
+    redirect_uri: Annotated[str, Form(...)],
+):
+    """Exchange an authorization code using the global Dropbox app credentials.
+
+    Used when ``DROPBOX_ALLOW_GLOBAL_CREDENTIALS_FOR_INTEGRATIONS`` is enabled so
+    that the ``app_secret`` is never exposed to the browser.  Only the OAuth code
+    and redirect URI need to be supplied by the client.
+    """
+    if not settings.dropbox_allow_global_credentials_for_integrations:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Global credentials for integrations are not enabled",
+        )
+    if not settings.dropbox_app_key or not settings.dropbox_app_secret:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Global Dropbox credentials are not configured",
+        )
+
+    token_url = "https://api.dropboxapi.com/oauth2/token"
+    payload = {
+        "client_id": settings.dropbox_app_key,
+        "client_secret": settings.dropbox_app_secret,
+        "code": code,
+        "redirect_uri": redirect_uri,
+        "grant_type": "authorization_code",
+    }
+
+    token_data = exchange_oauth_token(provider_name="Dropbox", token_url=token_url, payload=payload)
+
+    return {
+        "refresh_token": token_data["refresh_token"],
+        "access_token": token_data["access_token"],
+        "expires_in": token_data.get("expires_in", 14400),
+        # Return the public app_key so the callback can store it in the integration
+        "app_key": settings.dropbox_app_key,
+    }
+
+
 @router.post("/dropbox/exchange-token")
 @require_login
 async def exchange_dropbox_token(
@@ -210,6 +298,91 @@ async def test_dropbox_token(request: Request):
         return {"status": "error", "message": f"Connection error: {str(e)}"}
 
 
+@router.post("/dropbox/list-folders")
+@require_login
+async def list_dropbox_folders(
+    request: Request,
+    access_token: Annotated[str, Form(...)],
+    path: Annotated[str, Form()] = "",
+):
+    """
+    List folders in a Dropbox account for the directory selector.
+
+    Accepts an OAuth access token (short-lived) and a path to list.
+    Returns a flat list of folder entries under the given path.
+    """
+    try:
+        # Normalize path: Dropbox API uses "" for root, otherwise "/path"
+        folder_path = path.strip()
+        if folder_path == "/":
+            folder_path = ""
+        elif folder_path and not folder_path.startswith("/"):
+            folder_path = f"/{folder_path}"
+
+        headers = {
+            "Authorization": f"Bearer {access_token}",
+            "Content-Type": "application/json",
+        }
+
+        payload = {
+            "path": folder_path,
+            "recursive": False,
+            "include_deleted": False,
+            "include_has_explicit_shared_members": False,
+            "include_mounted_folders": True,
+        }
+
+        response = requests.post(
+            "https://api.dropboxapi.com/2/files/list_folder",
+            headers=headers,
+            json=payload,
+            timeout=settings.http_request_timeout,
+        )
+
+        if response.status_code == 401:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Access token is invalid or expired. Please re-authorize.",
+            )
+
+        if response.status_code != 200:
+            logger.error(f"Dropbox list_folder failed: {response.status_code} {response.text}")
+            raise HTTPException(
+                status_code=status.HTTP_502_BAD_GATEWAY,
+                detail=f"Failed to list Dropbox folders: {response.text}",
+            )
+
+        data = response.json()
+        folders = []
+        for entry in data.get("entries", []):
+            if entry.get(".tag") == "folder":
+                folders.append(
+                    {
+                        "name": entry["name"],
+                        "path": entry["path_display"],
+                        "id": entry.get("id", ""),
+                    }
+                )
+
+        # Sort folders alphabetically
+        folders.sort(key=lambda f: f["name"].lower())
+
+        return {
+            "folders": folders,
+            "path": folder_path or "/",
+            "has_more": data.get("has_more", False),
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception(f"Error listing Dropbox folders: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to list folders: {str(e)}",
+        )
+
+
 @router.post("/dropbox/save-settings")
 @require_login
 async def save_dropbox_settings(