Add exception classes

Allow2Error (base), ApiError (with http_status_code and response_body),
TokenExpiredError (with user_id), UnpairedError (with user_id) --
matching PHP exception hierarchy.

Co-Authored-By: claude-flow <ruv@ruv.net>

Author: Allow2CEO

allow2_service/exceptions/__init__.py

@@ -0,0 +1,13 @@
+"""Allow2 SDK exceptions."""
+
+from allow2_service.exceptions.base import Allow2Error
+from allow2_service.exceptions.api_error import ApiError
+from allow2_service.exceptions.token_expired import TokenExpiredError
+from allow2_service.exceptions.unpaired import UnpairedError
+
+__all__ = [
+    "Allow2Error",
+    "ApiError",
+    "TokenExpiredError",
+    "UnpairedError",
+]

allow2_service/exceptions/api_error.py

@@ -0,0 +1,33 @@
+"""Thrown when an Allow2 API call fails with an unexpected error."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from allow2_service.exceptions.base import Allow2Error
+
+
+class ApiError(Allow2Error):
+    """Thrown when an Allow2 API call fails with an unexpected error.
+
+    Args:
+        message: Human-readable error description.
+        http_status_code: The HTTP status code from the response.
+        response_body: The decoded JSON response body, if available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        http_status_code: int,
+        response_body: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(
+            message,
+            context={
+                "http_status_code": http_status_code,
+                "response_body": response_body,
+            },
+        )
+        self.http_status_code = http_status_code
+        self.response_body = response_body

allow2_service/exceptions/base.py

@@ -0,0 +1,22 @@
+"""Base exception for all Allow2 SDK errors."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class Allow2Error(RuntimeError):
+    """Base exception for all Allow2 SDK errors.
+
+    Args:
+        message: Human-readable error description.
+        context: Optional dictionary of additional context.
+    """
+
+    def __init__(
+        self,
+        message: str = "",
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.context: Dict[str, Any] = context or {}

allow2_service/exceptions/token_expired.py

@@ -0,0 +1,33 @@
+"""Thrown when the OAuth2 token refresh fails and no valid token is available."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from allow2_service.exceptions.base import Allow2Error
+
+
+class TokenExpiredError(Allow2Error):
+    """Thrown when the OAuth2 token refresh fails and no valid token is available.
+
+    The integration should redirect the user through OAuth2 re-pairing.
+
+    Args:
+        user_id: The integrating application's user ID.
+        message: Human-readable error description.
+    """
+
+    def __init__(
+        self,
+        user_id: str,
+        message: str = "OAuth2 token refresh failed. Re-authorization required.",
+        previous: Optional[BaseException] = None,
+    ) -> None:
+        super().__init__(message, context={"user_id": user_id})
+        self.user_id = user_id
+        if previous is not None:
+            self.__cause__ = previous
+
+    def get_user_id(self) -> str:
+        """Return the user ID associated with this error."""
+        return self.user_id

allow2_service/exceptions/unpaired.py

@@ -0,0 +1,28 @@
+"""Thrown when the service account is no longer linked (HTTP 401/403 from API)."""
+
+from __future__ import annotations
+
+from allow2_service.exceptions.base import Allow2Error
+
+
+class UnpairedError(Allow2Error):
+    """Thrown when the service account is no longer linked (HTTP 401/403 from API).
+
+    The integration should redirect the user through OAuth2 re-pairing.
+
+    Args:
+        user_id: The integrating application's user ID.
+        message: Human-readable error description.
+    """
+
+    def __init__(
+        self,
+        user_id: str,
+        message: str = "Service account is no longer linked. Re-pairing required.",
+    ) -> None:
+        super().__init__(message, context={"user_id": user_id})
+        self.user_id = user_id
+
+    def get_user_id(self) -> str:
+        """Return the user ID associated with this error."""
+        return self.user_id