feat(psa): add PSA abstraction layer — base types, exceptions, abstract interface

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

backend/app/services/psa/__init__.py

@@ -0,0 +1 @@
+"""PSA integration abstraction layer."""

backend/app/services/psa/base.py

@@ -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]:
+        ...

backend/app/services/psa/exceptions.py

@@ -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

backend/app/services/psa/types.py

@@ -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"