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