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.
This commit was merged in pull request #106.
This commit is contained in:
chihlasm
1
backend/app/services/psa/__init__.py
Normal file
1
backend/app/services/psa/__init__.py
Normal file
@@ -0,0 +1 @@
|
||||
"""PSA integration abstraction layer."""
|
||||
68
backend/app/services/psa/base.py
Normal file
68
backend/app/services/psa/base.py
Normal file
@@ -0,0 +1,68 @@
|
||||
"""Abstract base class for PSA provider implementations."""
|
||||
from __future__ import annotations
|
||||
|
||||
from abc import ABC, abstractmethod
|
||||
|
||||
from .types import (
|
||||
ConnectionTestResult,
|
||||
PSATicket,
|
||||
PSANote,
|
||||
PSAStatus,
|
||||
PSACompany,
|
||||
PSAMember,
|
||||
PSAConfiguration,
|
||||
)
|
||||
|
||||
|
||||
class PSAProvider(ABC):
|
||||
"""Abstract base for PSA integrations (ConnectWise, Autotask, etc.)."""
|
||||
|
||||
@abstractmethod
|
||||
async def test_connection(self) -> ConnectionTestResult:
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def get_ticket(self, ticket_id: str) -> PSATicket:
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def search_tickets(self, query: str, **filters) -> list[PSATicket]:
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def post_note(
|
||||
self,
|
||||
ticket_id: str,
|
||||
text: str,
|
||||
note_type: str,
|
||||
member_id: str | None = None,
|
||||
) -> PSANote:
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def update_ticket_status(
|
||||
self,
|
||||
ticket_id: str,
|
||||
status_id: int,
|
||||
) -> PSATicket:
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def get_ticket_statuses(self, board_id: int) -> list[PSAStatus]:
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def list_companies(self, **filters) -> list[PSACompany]:
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def get_company(self, company_id: str) -> PSACompany:
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def list_members(self) -> list[PSAMember]:
|
||||
...
|
||||
|
||||
@abstractmethod
|
||||
async def get_ticket_configurations(self, ticket_id: str) -> list[PSAConfiguration]:
|
||||
...
|
||||
38
backend/app/services/psa/cache.py
Normal file
38
backend/app/services/psa/cache.py
Normal file
@@ -0,0 +1,38 @@
|
||||
"""Simple in-memory TTL cache for PSA API responses."""
|
||||
from __future__ import annotations
|
||||
|
||||
import time
|
||||
from typing import Any
|
||||
|
||||
|
||||
class PSACache:
|
||||
"""Account-scoped in-memory cache with TTL expiry."""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._store: dict[str, tuple[Any, float]] = {}
|
||||
|
||||
def get(self, key: str) -> Any | None:
|
||||
entry = self._store.get(key)
|
||||
if entry is None:
|
||||
return None
|
||||
value, expires_at = entry
|
||||
if time.time() > expires_at:
|
||||
del self._store[key]
|
||||
return None
|
||||
return value
|
||||
|
||||
def set(self, key: str, value: Any, ttl_seconds: int) -> None:
|
||||
self._store[key] = (value, time.time() + ttl_seconds)
|
||||
|
||||
def invalidate(self, prefix: str) -> None:
|
||||
"""Remove all entries matching a key prefix."""
|
||||
keys_to_remove = [k for k in self._store if k.startswith(prefix)]
|
||||
for k in keys_to_remove:
|
||||
del self._store[k]
|
||||
|
||||
def clear(self) -> None:
|
||||
self._store.clear()
|
||||
|
||||
|
||||
# Global singleton — acceptable at current scale (see design doc section 6)
|
||||
psa_cache = PSACache()
|
||||
1
backend/app/services/psa/connectwise/__init__.py
Normal file
1
backend/app/services/psa/connectwise/__init__.py
Normal file
@@ -0,0 +1 @@
|
||||
"""ConnectWise PSA provider implementation."""
|
||||
288
backend/app/services/psa/connectwise/client.py
Normal file
288
backend/app/services/psa/connectwise/client.py
Normal file
@@ -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
|
||||
283
backend/app/services/psa/connectwise/provider.py
Normal file
283
backend/app/services/psa/connectwise/provider.py
Normal file
@@ -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),
|
||||
)
|
||||
53
backend/app/services/psa/encryption.py
Normal file
53
backend/app/services/psa/encryption.py
Normal file
@@ -0,0 +1,53 @@
|
||||
"""Fernet-based credential encryption for PSA connections.
|
||||
|
||||
Uses the application SECRET_KEY to derive a Fernet encryption key via HKDF.
|
||||
Credentials are stored as a single encrypted JSON blob.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import base64
|
||||
|
||||
from cryptography.fernet import Fernet
|
||||
from cryptography.hazmat.primitives import hashes
|
||||
from cryptography.hazmat.primitives.kdf.hkdf import HKDF
|
||||
|
||||
from app.core.config import settings
|
||||
|
||||
|
||||
def _get_fernet() -> Fernet:
|
||||
"""Derive a Fernet key from the application SECRET_KEY."""
|
||||
hkdf = HKDF(
|
||||
algorithm=hashes.SHA256(),
|
||||
length=32,
|
||||
salt=b"resolutionflow-psa-credentials",
|
||||
info=b"psa-credential-encryption",
|
||||
)
|
||||
key = hkdf.derive(settings.SECRET_KEY.encode())
|
||||
fernet_key = base64.urlsafe_b64encode(key)
|
||||
return Fernet(fernet_key)
|
||||
|
||||
|
||||
def encrypt_credentials(credentials: dict) -> str:
|
||||
"""Encrypt a credentials dict to a Fernet token string."""
|
||||
f = _get_fernet()
|
||||
plaintext = json.dumps(credentials).encode()
|
||||
return f.encrypt(plaintext).decode()
|
||||
|
||||
|
||||
def decrypt_credentials(encrypted: str) -> dict:
|
||||
"""Decrypt a Fernet token string back to a credentials dict."""
|
||||
f = _get_fernet()
|
||||
plaintext = f.decrypt(encrypted.encode())
|
||||
return json.loads(plaintext)
|
||||
|
||||
|
||||
def mask_credential(value: str | None, visible_suffix: int = 4) -> str:
|
||||
"""Return a masked version of a credential for display.
|
||||
e.g., 'abcdefghij' -> '......ghij'
|
||||
"""
|
||||
if not value:
|
||||
return "\u2022\u2022\u2022\u2022\u2022\u2022"
|
||||
if len(value) <= visible_suffix:
|
||||
return "\u2022\u2022\u2022\u2022\u2022\u2022" + value
|
||||
return "\u2022\u2022\u2022\u2022\u2022\u2022" + value[-visible_suffix:]
|
||||
45
backend/app/services/psa/exceptions.py
Normal file
45
backend/app/services/psa/exceptions.py
Normal file
@@ -0,0 +1,45 @@
|
||||
"""Typed exceptions for PSA integration errors."""
|
||||
|
||||
|
||||
class PSAError(Exception):
|
||||
"""Base exception for all PSA integration errors."""
|
||||
def __init__(self, message: str, provider: str = "unknown"):
|
||||
self.provider = provider
|
||||
super().__init__(message)
|
||||
|
||||
|
||||
class PSAAuthError(PSAError):
|
||||
"""Invalid or expired credentials."""
|
||||
pass
|
||||
|
||||
|
||||
class PSAPermissionError(PSAError):
|
||||
"""Insufficient permissions on the PSA side."""
|
||||
pass
|
||||
|
||||
|
||||
class PSANotFoundError(PSAError):
|
||||
"""Requested resource (ticket, company, etc.) not found."""
|
||||
pass
|
||||
|
||||
|
||||
class PSARateLimitError(PSAError):
|
||||
"""Rate limit exceeded. retry_after_seconds may be set."""
|
||||
def __init__(self, message: str, retry_after_seconds: int | None = None, provider: str = "unknown"):
|
||||
self.retry_after_seconds = retry_after_seconds
|
||||
super().__init__(message, provider)
|
||||
|
||||
|
||||
class PSAServerError(PSAError):
|
||||
"""Remote PSA server error (5xx)."""
|
||||
pass
|
||||
|
||||
|
||||
class PSATimeoutError(PSAError):
|
||||
"""Request to PSA timed out."""
|
||||
pass
|
||||
|
||||
|
||||
class PSAConnectionError(PSAError):
|
||||
"""Cannot reach the PSA server."""
|
||||
pass
|
||||
51
backend/app/services/psa/registry.py
Normal file
51
backend/app/services/psa/registry.py
Normal file
@@ -0,0 +1,51 @@
|
||||
"""Factory for instantiating PSA providers from stored connection data."""
|
||||
from __future__ import annotations
|
||||
|
||||
from uuid import UUID
|
||||
|
||||
from sqlalchemy import select
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
from app.models.psa_connection import PsaConnection
|
||||
from app.services.psa.base import PSAProvider
|
||||
from app.core.config import settings
|
||||
from app.services.psa.encryption import decrypt_credentials
|
||||
from app.services.psa.exceptions import PSAConnectionError
|
||||
|
||||
|
||||
async def get_provider_for_account(
|
||||
account_id: UUID, db: AsyncSession
|
||||
) -> PSAProvider:
|
||||
"""Look up account's PSA connection, decrypt credentials, instantiate provider."""
|
||||
result = await db.execute(
|
||||
select(PsaConnection).where(
|
||||
PsaConnection.account_id == account_id,
|
||||
PsaConnection.is_active.is_(True),
|
||||
)
|
||||
)
|
||||
connection = result.scalar_one_or_none()
|
||||
|
||||
if not connection:
|
||||
raise PSAConnectionError(
|
||||
"No active PSA connection configured for this account.",
|
||||
provider="unknown",
|
||||
)
|
||||
|
||||
if connection.provider == "connectwise":
|
||||
from app.services.psa.connectwise.client import ConnectWiseClient
|
||||
from app.services.psa.connectwise.provider import ConnectWiseProvider
|
||||
|
||||
creds = decrypt_credentials(connection.credentials_encrypted)
|
||||
client = ConnectWiseClient(
|
||||
site_url=connection.site_url,
|
||||
company_id=connection.company_id,
|
||||
public_key=creds["public_key"],
|
||||
private_key=creds["private_key"],
|
||||
client_id=settings.CW_CLIENT_ID or "",
|
||||
)
|
||||
return ConnectWiseProvider(client)
|
||||
|
||||
raise PSAConnectionError(
|
||||
f"Unsupported PSA provider: {connection.provider}",
|
||||
provider=connection.provider,
|
||||
)
|
||||
63
backend/app/services/psa/types.py
Normal file
63
backend/app/services/psa/types.py
Normal file
@@ -0,0 +1,63 @@
|
||||
"""Provider-agnostic PSA data types."""
|
||||
from __future__ import annotations
|
||||
|
||||
from pydantic import BaseModel
|
||||
|
||||
|
||||
class ConnectionTestResult(BaseModel):
|
||||
success: bool
|
||||
message: str
|
||||
server_version: str | None = None
|
||||
|
||||
|
||||
class PSATicket(BaseModel):
|
||||
id: str
|
||||
summary: str
|
||||
company_name: str | None = None
|
||||
company_id: str | None = None
|
||||
board_name: str | None = None
|
||||
board_id: int | None = None
|
||||
status_name: str | None = None
|
||||
status_id: int | None = None
|
||||
priority_name: str | None = None
|
||||
priority_id: int | None = None
|
||||
closed: bool = False
|
||||
|
||||
|
||||
class PSANote(BaseModel):
|
||||
id: str
|
||||
text: str
|
||||
note_type: str
|
||||
created_at: str | None = None
|
||||
|
||||
|
||||
class PSAStatus(BaseModel):
|
||||
id: int
|
||||
name: str
|
||||
is_closed: bool = False
|
||||
|
||||
|
||||
class PSACompany(BaseModel):
|
||||
id: str
|
||||
name: str
|
||||
status: str | None = None
|
||||
|
||||
|
||||
class PSAMember(BaseModel):
|
||||
id: str
|
||||
identifier: str # CW login username
|
||||
name: str
|
||||
email: str | None = None
|
||||
|
||||
|
||||
class PSAConfiguration(BaseModel):
|
||||
id: str
|
||||
name: str
|
||||
type: str | None = None
|
||||
company_name: str | None = None
|
||||
|
||||
|
||||
class NoteType:
|
||||
INTERNAL_ANALYSIS = "internal_analysis"
|
||||
RESOLUTION = "resolution"
|
||||
DESCRIPTION = "description"
|
||||
Reference in New Issue
Block a user