feat: ConnectWise PSA integration (#106)

PSA abstraction layer with provider pattern, ConnectWise integration (connection management, ticket linking, note posting, status updates, member mapping), Integrations page UI, Fernet credential encryption, in-memory TTL cache, 6 DB migrations, ConnectWise API reference docs.

backend/app/services/psa/connectwise/__init__.py

@@ -0,0 +1 @@
+"""ConnectWise PSA provider implementation."""

backend/app/services/psa/connectwise/client.py

@@ -0,0 +1,288 @@
+"""Low-level HTTP client for ConnectWise PSA REST API.
+
+Handles auth headers, base URL resolution (cloud vs on-premise),
+pagination, retry with backoff, and error mapping.
+"""
+from __future__ import annotations
+
+import asyncio
+import base64
+import ipaddress
+import logging
+import socket
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from app.services.psa.exceptions import (
+    PSAAuthError,
+    PSAConnectionError,
+    PSANotFoundError,
+    PSAPermissionError,
+    PSARateLimitError,
+    PSAServerError,
+    PSATimeoutError,
+)
+
+logger = logging.getLogger(__name__)
+
+# Pinned CW API version per best-practices/PSA-Versioning.md
+CW_API_VERSION = "2025.16"
+CW_ACCEPT_HEADER = f"application/vnd.connectwise.com+json; version={CW_API_VERSION}"
+
+# Known CW cloud domains (for SSRF prevention)
+CW_ALLOWED_DOMAINS = {
+    "myconnectwise.net",
+    "connectwisedev.com",
+}
+
+REQUEST_TIMEOUT = 30.0
+MAX_RETRIES = 2
+MAX_PAGE_SIZE = 1000
+
+
+def _validate_site_url(site_url: str) -> None:
+    """Validate site_url is a known CW domain (SSRF prevention).
+
+    Rejects any hostname that is not a recognized ConnectWise domain
+    and any hostname that resolves to a private/loopback/link-local IP.
+    """
+    # Ensure scheme for parsing
+    url = site_url if "://" in site_url else f"https://{site_url}"
+    parsed = urlparse(url)
+    hostname = parsed.hostname or ""
+
+    # Check against allowed domains
+    if not any(
+        hostname.endswith(f".{domain}") or hostname == domain
+        for domain in CW_ALLOWED_DOMAINS
+    ):
+        raise PSAConnectionError(
+            f"Invalid ConnectWise site URL: {hostname}. "
+            "Must be a *.myconnectwise.net or *.connectwisedev.com domain.",
+            provider="connectwise",
+        )
+
+    # Resolve and check for private IPs
+    try:
+        addrs = socket.getaddrinfo(hostname, None)
+        for _, _, _, _, sockaddr in addrs:
+            ip = ipaddress.ip_address(sockaddr[0])
+            if ip.is_private or ip.is_loopback or ip.is_link_local:
+                raise PSAConnectionError(
+                    f"Site URL resolves to a private/internal address: {sockaddr[0]}",
+                    provider="connectwise",
+                )
+    except socket.gaierror:
+        raise PSAConnectionError(
+            f"Cannot resolve hostname: {hostname}",
+            provider="connectwise",
+        )
+
+
+class ConnectWiseClient:
+    """Async HTTP client for the ConnectWise PSA API.
+
+    Auth: Authorization: Basic {base64(companyId+publicKey:privateKey)} + clientId header
+    Accept: application/vnd.connectwise.com+json; version=2025.16
+    Base URL: resolved dynamically via /login/companyinfo/{companyId}
+    Pagination: page/pageSize params, max 1000 per page, while-loop pattern
+    Retry: respects 429 Retry-After, max 2 retries with exponential backoff for 5xx
+    Timeout: 30 seconds per request
+    """
+
+    def __init__(
+        self,
+        site_url: str,
+        company_id: str,
+        public_key: str,
+        private_key: str,
+        client_id: str,
+    ):
+        self.site_url = site_url.rstrip("/")
+        self.company_id = company_id
+        self.client_id = client_id
+
+        # Auth: Base64(companyId+publicKey:privateKey)
+        auth_string = f"{company_id}+{public_key}:{private_key}"
+        self._auth_b64 = base64.b64encode(auth_string.encode()).decode()
+
+        # Base URL resolved lazily on first request
+        self._base_url: str | None = None
+
+    async def _resolve_base_url(self) -> str:
+        """Resolve the CW API base URL using /login/companyinfo/{companyId}.
+
+        Cloud environments return a versioned codebase (e.g., v2025_3/) requiring
+        an 'api-' prefix on the hostname. On-premise returns v4_6_release/ with
+        no prefix needed.
+        """
+        if self._base_url:
+            return self._base_url
+
+        _validate_site_url(self.site_url)
+
+        info_url = f"https://{self.site_url}/login/companyinfo/{self.company_id}"
+
+        async with httpx.AsyncClient(timeout=REQUEST_TIMEOUT) as client:
+            try:
+                resp = await client.get(info_url)
+                resp.raise_for_status()
+            except httpx.TimeoutException:
+                raise PSATimeoutError(
+                    "Timed out resolving CW base URL", provider="connectwise"
+                )
+            except httpx.HTTPError as e:
+                raise PSAConnectionError(
+                    f"Failed to resolve CW base URL: {e}", provider="connectwise"
+                )
+
+        data = resp.json()
+        codebase = data.get("Codebase", "v4_6_release/")
+        site_url = data.get("SiteUrl", self.site_url)
+
+        # Cloud codebase (e.g., v2025_3/) requires api- prefix
+        if codebase != "v4_6_release/":
+            if not site_url.startswith("api-"):
+                site_url = f"api-{site_url}"
+
+        self._base_url = f"https://{site_url}/{codebase}apis/3.0"
+        logger.info("Resolved CW base URL: %s", self._base_url)
+        return self._base_url
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Basic {self._auth_b64}",
+            "clientId": self.client_id,
+            "Accept": CW_ACCEPT_HEADER,
+            "Content-Type": "application/json",
+        }
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any = None,
+        retries: int = MAX_RETRIES,
+    ) -> Any:
+        """Make an authenticated request to the CW API with retry and error mapping."""
+        base_url = await self._resolve_base_url()
+        url = f"{base_url}/{path.lstrip('/')}"
+
+        async with httpx.AsyncClient(timeout=REQUEST_TIMEOUT) as client:
+            for attempt in range(retries + 1):
+                try:
+                    resp = await client.request(
+                        method,
+                        url,
+                        headers=self._headers(),
+                        params=params,
+                        json=json_body,
+                    )
+                except httpx.TimeoutException:
+                    if attempt < retries:
+                        await asyncio.sleep(2 ** attempt)
+                        continue
+                    raise PSATimeoutError(
+                        "ConnectWise request timed out", provider="connectwise"
+                    )
+                except httpx.ConnectError:
+                    raise PSAConnectionError(
+                        "Cannot reach ConnectWise server", provider="connectwise"
+                    )
+
+                # Rate limit — retry with Retry-After backoff
+                if resp.status_code == 429:
+                    if attempt < retries:
+                        retry_after = int(resp.headers.get("Retry-After", "5"))
+                        await asyncio.sleep(retry_after)
+                        continue
+                    raise PSARateLimitError(
+                        "ConnectWise rate limit exceeded",
+                        retry_after_seconds=int(
+                            resp.headers.get("Retry-After", "60")
+                        ),
+                        provider="connectwise",
+                    )
+
+                # Map error status codes to typed exceptions
+                if resp.status_code == 401:
+                    raise PSAAuthError(
+                        "Invalid credentials. Check your API keys.",
+                        provider="connectwise",
+                    )
+                if resp.status_code == 403:
+                    raise PSAPermissionError(
+                        "Insufficient permissions. Check the API member's security role.",
+                        provider="connectwise",
+                    )
+                if resp.status_code == 404:
+                    raise PSANotFoundError(
+                        "Resource not found.", provider="connectwise"
+                    )
+                if resp.status_code >= 500:
+                    if attempt < retries:
+                        await asyncio.sleep(2 ** attempt)
+                        continue
+                    raise PSAServerError(
+                        "ConnectWise is experiencing issues. Try again.",
+                        provider="connectwise",
+                    )
+
+                resp.raise_for_status()
+                if resp.status_code == 204:
+                    return None
+                return resp.json()
+
+        # Should not reach here, but satisfy type checker
+        raise PSAConnectionError(
+            "Request failed after all retries", provider="connectwise"
+        )
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """GET request to CW API."""
+        return await self._request("GET", path, params=params)
+
+    async def post(self, path: str, json_body: Any = None) -> Any:
+        """POST request to CW API."""
+        return await self._request("POST", path, json_body=json_body)
+
+    async def patch(self, path: str, json_body: Any = None) -> Any:
+        """PATCH request to CW API (JSON Patch array format).
+
+        CW uses JSON Patch syntax: [{"op": "replace", "path": "field", "value": ...}]
+        """
+        return await self._request("PATCH", path, json_body=json_body)
+
+    async def delete(self, path: str) -> Any:
+        """DELETE request to CW API."""
+        return await self._request("DELETE", path)
+
+    async def get_paginated(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        max_pages: int = 10,
+    ) -> list[Any]:
+        """Fetch all pages of a paginated CW endpoint.
+
+        Uses navigable pagination with page/pageSize params.
+        Stops when a page returns fewer results than pageSize or max_pages is reached.
+        """
+        params = dict(params or {})
+        params.setdefault("pageSize", MAX_PAGE_SIZE)
+        all_results: list[Any] = []
+
+        for page in range(1, max_pages + 1):
+            params["page"] = page
+            results = await self.get(path, params=params)
+            if not results:
+                break
+            all_results.extend(results)
+            if len(results) < params["pageSize"]:
+                break
+
+        return all_results

backend/app/services/psa/connectwise/provider.py

@@ -0,0 +1,283 @@
+"""ConnectWise implementation of PSAProvider."""
+from __future__ import annotations
+
+from app.services.psa.base import PSAProvider
+from app.services.psa.cache import psa_cache
+from app.services.psa.types import (
+    ConnectionTestResult,
+    PSATicket,
+    PSANote,
+    PSAStatus,
+    PSACompany,
+    PSAMember,
+    PSAConfiguration,
+)
+from .client import ConnectWiseClient
+
+
+class ConnectWiseProvider(PSAProvider):
+    """ConnectWise PSA provider implementation."""
+
+    def __init__(self, client: ConnectWiseClient):
+        self.client = client
+
+    async def test_connection(self) -> ConnectionTestResult:
+        """Test the CW connection by fetching system info."""
+        try:
+            info = await self.client.get("/system/info")
+            return ConnectionTestResult(
+                success=True,
+                message="Connected successfully.",
+                server_version=info.get("version", None),
+            )
+        except Exception as e:
+            return ConnectionTestResult(
+                success=False,
+                message=str(e),
+                server_version=None,
+            )
+
+    # ── Tickets ───────────────────────────────────────────────────────
+
+    async def get_ticket(self, ticket_id: str) -> PSATicket:
+        """Fetch a single ticket by ID from ConnectWise."""
+        data = await self.client.get(
+            f"/service/tickets/{ticket_id}",
+            params={"fields": "id,summary,company,board,status,priority,closedFlag"},
+        )
+        return self._map_ticket(data)
+
+    async def search_tickets(self, query: str, **filters) -> list[PSATicket]:
+        """Search CW tickets by summary. Supports board_id and status_id filters."""
+        params: dict = {
+            "fields": "id,summary,company,board,status,priority,closedFlag",
+            "orderBy": "id desc",
+            "pageSize": 25,
+        }
+
+        # Build CW condition query
+        conditions: list[str] = []
+        if query:
+            conditions.append(f"summary contains '{query}'")
+        if filters.get("board_id"):
+            conditions.append(f"board/id = {filters['board_id']}")
+        if filters.get("status_id"):
+            conditions.append(f"status/id = {filters['status_id']}")
+        if not filters.get("include_closed", False):
+            conditions.append("closedFlag = false")
+
+        if conditions:
+            params["conditions"] = " and ".join(conditions)
+
+        data = await self.client.get("/service/tickets", params=params)
+
+        return [
+            self._map_ticket(t)
+            for t in (data if isinstance(data, list) else [])
+        ]
+
+    async def get_ticket_configurations(
+        self, ticket_id: str
+    ) -> list[PSAConfiguration]:
+        """Get configurations (assets) attached to a ticket."""
+        data = await self.client.get(
+            f"/service/tickets/{ticket_id}/configurations",
+            params={"fields": "id,deviceIdentifier,type,company"},
+        )
+        return [
+            PSAConfiguration(
+                id=str(c["id"]),
+                name=c.get("deviceIdentifier", ""),
+                type=c.get("type", {}).get("name") if c.get("type") else None,
+                company_name=c.get("company", {}).get("name") if c.get("company") else None,
+            )
+            for c in (data if isinstance(data, list) else [])
+        ]
+
+    # ── Board statuses (cached) ───────────────────────────────────────
+
+    async def get_ticket_statuses(self, board_id: int) -> list[PSAStatus]:
+        """Get available statuses for a CW service board (cached 1 hour)."""
+        cache_key = f"board_statuses:{board_id}"
+        cached = psa_cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        data = await self.client.get(
+            f"/service/boards/{board_id}/statuses",
+            params={"fields": "id,name,closedStatus", "pageSize": 100},
+        )
+        result = [
+            PSAStatus(
+                id=s["id"],
+                name=s["name"],
+                is_closed=s.get("closedStatus", False),
+            )
+            for s in (data if isinstance(data, list) else [])
+        ]
+        psa_cache.set(cache_key, result, ttl_seconds=3600)
+        return result
+
+    # ── Companies ─────────────────────────────────────────────────────
+
+    async def list_companies(self, **filters) -> list[PSACompany]:
+        """List companies from CW, optionally filtered by status."""
+        params: dict = {
+            "fields": "id,name,status",
+            "pageSize": 100,
+            "orderBy": "name asc",
+        }
+        conditions: list[str] = []
+        if filters.get("status"):
+            conditions.append(f"status/name = '{filters['status']}'")
+        if conditions:
+            params["conditions"] = " and ".join(conditions)
+
+        data = await self.client.get("/company/companies", params=params)
+        return [
+            PSACompany(
+                id=str(c["id"]),
+                name=c.get("name", ""),
+                status=c.get("status", {}).get("name") if c.get("status") else None,
+            )
+            for c in (data if isinstance(data, list) else [])
+        ]
+
+    async def get_company(self, company_id: str) -> PSACompany:
+        """Fetch a single company by ID."""
+        data = await self.client.get(
+            f"/company/companies/{company_id}",
+            params={"fields": "id,name,status"},
+        )
+        return PSACompany(
+            id=str(data["id"]),
+            name=data.get("name", ""),
+            status=data.get("status", {}).get("name") if data.get("status") else None,
+        )
+
+    # ── Notes & status updates ───────────────────────────────────────
+
+    async def post_note(
+        self,
+        ticket_id: str,
+        text: str,
+        note_type: str,
+        member_id: str | None = None,
+    ) -> PSANote:
+        """Post a note to a CW ticket.
+
+        Maps ResolutionFlow note types to CW flag fields:
+        - internal_analysis → internalAnalysisFlag (internal only)
+        - resolution → resolutionFlag (internal, triggers notifications)
+        - description → detailDescriptionFlag (external, triggers notifications)
+        """
+        from app.services.psa.types import NoteType
+
+        flags = {
+            NoteType.INTERNAL_ANALYSIS: {
+                "internalAnalysisFlag": True,
+                "resolutionFlag": False,
+                "detailDescriptionFlag": False,
+                "internalFlag": True,
+                "processNotifications": False,
+            },
+            NoteType.RESOLUTION: {
+                "internalAnalysisFlag": False,
+                "resolutionFlag": True,
+                "detailDescriptionFlag": False,
+                "internalFlag": True,
+                "processNotifications": True,
+            },
+            NoteType.DESCRIPTION: {
+                "internalAnalysisFlag": False,
+                "resolutionFlag": False,
+                "detailDescriptionFlag": True,
+                "internalFlag": False,
+                "processNotifications": True,
+            },
+        }
+
+        note_flags = flags.get(note_type, flags[NoteType.INTERNAL_ANALYSIS])
+
+        # NOTE: CW Developer Guide states \n is "Not Supported" in JSON bodies
+        # and may be collapsed to a single space. CW does support markdown in ticket
+        # notes (see PSA-Markdown.md). This needs sandbox testing — if newlines are
+        # lost, consider using double-space line breaks or HTML <br> tags instead.
+        body: dict = {
+            "text": text,
+            **note_flags,
+        }
+
+        if member_id:
+            body["member"] = {"id": int(member_id)}
+
+        data = await self.client.post(
+            f"/service/tickets/{ticket_id}/notes", json_body=body
+        )
+
+        return PSANote(
+            id=str(data.get("id", "")),
+            text=data.get("text", ""),
+            note_type=note_type,
+            created_at=data.get("dateCreated"),
+        )
+
+    async def update_ticket_status(
+        self, ticket_id: str, status_id: int
+    ) -> PSATicket:
+        """Update a CW ticket's status using JSON Patch format."""
+        patch_body = [
+            {"op": "replace", "path": "status", "value": {"id": status_id}}
+        ]
+        data = await self.client.patch(
+            f"/service/tickets/{ticket_id}", json_body=patch_body
+        )
+        return self._map_ticket(data)
+
+    async def list_members(self) -> list[PSAMember]:
+        """List CW system members (cached 15 minutes)."""
+        cache_key = "members:all"
+        cached = psa_cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        data = await self.client.get_paginated(
+            "/system/members",
+            params={
+                "fields": "id,identifier,firstName,lastName,officeEmail",
+                "conditions": "inactiveFlag = false",
+                "pageSize": 1000,
+            },
+        )
+
+        result = [
+            PSAMember(
+                id=str(m["id"]),
+                identifier=m.get("identifier", ""),
+                name=f"{m.get('firstName', '')} {m.get('lastName', '')}".strip(),
+                email=m.get("officeEmail"),
+            )
+            for m in data
+        ]
+
+        psa_cache.set(cache_key, result, ttl_seconds=900)
+        return result
+
+    # ── Private helpers ───────────────────────────────────────────────
+
+    @staticmethod
+    def _map_ticket(data: dict) -> PSATicket:
+        """Map a CW ticket JSON dict to a PSATicket."""
+        return PSATicket(
+            id=str(data["id"]),
+            summary=data.get("summary", ""),
+            company_name=data.get("company", {}).get("name"),
+            company_id=str(data["company"]["id"]) if data.get("company") else None,
+            board_name=data.get("board", {}).get("name"),
+            board_id=data.get("board", {}).get("id"),
+            status_name=data.get("status", {}).get("name"),
+            status_id=data.get("status", {}).get("id"),
+            priority_name=data.get("priority", {}).get("name"),
+            priority_id=data.get("priority", {}).get("id"),
+            closed=data.get("closedFlag", False),
+        )