mcp-eregistrations-bpa 0.8.5__py3-none-any.whl

mcp_eregistrations_bpa/bpa_client/endpoints.py

@@ -0,0 +1,193 @@
+"""BPA API endpoint constants.
+
+This module defines all BPA API v3 (2016/06) endpoint URL patterns.
+Endpoints use string formatting for path parameters.
+
+Usage:
+    from mcp_eregistrations_bpa.bpa_client.endpoints import SERVICES, SERVICE_BY_ID
+
+    url = SERVICES  # "/service"
+    url = SERVICE_BY_ID.format(id=123)  # "/service/123"
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    # Service endpoints
+    "SERVICES",
+    "SERVICE_BY_ID",
+    "SERVICE_FIELDS",
+    "SERVICE_DETERMINANTS",
+    "SERVICE_FORMS",
+    "SERVICE_ROLES",
+    "SERVICE_REGISTRATIONS",
+    # Registration endpoints
+    "REGISTRATIONS",
+    "REGISTRATION_BY_ID",
+    "REGISTRATION_FIELDS",
+    "REGISTRATION_DETERMINANTS",
+    "REGISTRATION_COSTS",
+    "REGISTRATION_DOCUMENTS",
+    # Form endpoints
+    "FORMS",
+    "FORM_BY_ID",
+    "FORM_FIELDS",
+    "FORM_DETERMINANTS",
+    # Field endpoints
+    "FIELDS",
+    "FIELD_BY_ID",
+    "FIELD_DETERMINANTS",
+    "FIELD_REGISTRATIONS",
+    # Determinant endpoints
+    "DETERMINANTS",
+    "DETERMINANT_BY_ID",
+    "DETERMINANT_FIELDS",
+    "DETERMINANT_REGISTRATIONS",
+    # Role endpoints
+    "ROLES",
+    "ROLE_BY_ID",
+    # Cost endpoints
+    "COSTS",
+    "COST_BY_ID",
+    # Document endpoints
+    "DOCUMENTS",
+    "DOCUMENT_BY_ID",
+    # Component Actions endpoints
+    "COMPONENT_ACTIONS_BY_ID",
+    "SERVICE_COMPONENT_ACTIONS",
+]
+
+# =============================================================================
+# Service Endpoints
+# =============================================================================
+
+#: List all services
+SERVICES = "/service"
+
+#: Get/update/delete service by ID
+SERVICE_BY_ID = "/service/{id}"
+
+#: Fields for a specific service
+SERVICE_FIELDS = "/service/{service_id}/fields"
+
+#: Determinants for a specific service
+SERVICE_DETERMINANTS = "/service/{service_id}/determinant"
+
+#: Forms for a specific service
+SERVICE_FORMS = "/service/{service_id}/form"
+
+#: Roles for a specific service
+SERVICE_ROLES = "/service/{service_id}/roles"
+
+#: Registrations for a specific service
+SERVICE_REGISTRATIONS = "/service/{service_id}/registrations"
+
+# =============================================================================
+# Registration Endpoints
+# =============================================================================
+
+#: List all registrations
+REGISTRATIONS = "/registration"
+
+#: Get/update/delete registration by ID
+REGISTRATION_BY_ID = "/registration/{registration_id}"
+
+#: Fields for a specific registration
+REGISTRATION_FIELDS = "/registration/{registration_id}/fields"
+
+#: Determinants for a specific registration
+REGISTRATION_DETERMINANTS = "/registration/{registration_id}/determinants"
+
+#: Costs for a specific registration
+REGISTRATION_COSTS = "/registration/{registration_id}/costs"
+
+#: Documents for a specific registration
+REGISTRATION_DOCUMENTS = "/registration/{registration_id}/documents"
+
+# =============================================================================
+# Form Endpoints
+# =============================================================================
+
+#: List all forms
+FORMS = "/form"
+
+#: Get/update/delete form by ID
+FORM_BY_ID = "/form/{form_id}"
+
+#: Fields for a specific form
+FORM_FIELDS = "/form/{form_id}/fields"
+
+#: Determinants for a specific form
+FORM_DETERMINANTS = "/form/{form_id}/determinants"
+
+# =============================================================================
+# Field Endpoints
+# =============================================================================
+
+#: List all fields
+FIELDS = "/field"
+
+#: Get/update/delete field by ID
+FIELD_BY_ID = "/field/{field_id}"
+
+#: Determinants linked to a field (many-to-many)
+FIELD_DETERMINANTS = "/field/{field_id}/determinants"
+
+#: Registrations linked to a field (many-to-many)
+FIELD_REGISTRATIONS = "/field/{field_id}/registrations"
+
+# =============================================================================
+# Determinant Endpoints
+# =============================================================================
+
+#: List all determinants
+DETERMINANTS = "/determinant"
+
+#: Get/update/delete determinant by ID
+DETERMINANT_BY_ID = "/determinant/{determinant_id}"
+
+#: Fields linked to a determinant (many-to-many)
+DETERMINANT_FIELDS = "/determinant/{determinant_id}/fields"
+
+#: Registrations linked to a determinant (many-to-many)
+DETERMINANT_REGISTRATIONS = "/determinant/{determinant_id}/registrations"
+
+# =============================================================================
+# Role Endpoints
+# =============================================================================
+
+#: List all roles
+ROLES = "/role"
+
+#: Get/update/delete role by ID
+ROLE_BY_ID = "/role/{role_id}"
+
+# =============================================================================
+# Cost Endpoints
+# =============================================================================
+
+#: List all costs
+COSTS = "/cost"
+
+#: Get/update/delete cost by ID
+COST_BY_ID = "/cost/{cost_id}"
+
+# =============================================================================
+# Document Endpoints
+# =============================================================================
+
+#: List all documents
+DOCUMENTS = "/document"
+
+#: Get/update/delete document by ID
+DOCUMENT_BY_ID = "/document/{document_id}"
+
+# =============================================================================
+# Component Actions Endpoints
+# =============================================================================
+
+#: Get/update component actions by ID
+COMPONENT_ACTIONS_BY_ID = "/componentactions/{id}"
+
+#: Get/update/delete component actions for a specific service component
+SERVICE_COMPONENT_ACTIONS = "/service/{service_id}/componentactions/{component_key}"

mcp_eregistrations_bpa/bpa_client/errors.py

@@ -0,0 +1,276 @@
+"""BPA client error handling and translation.
+
+This module provides error classes for BPA API interactions and
+translates HTTP errors to AI-friendly ToolError messages.
+
+Error translation follows the pattern:
+    "[What happened]: [Why it matters]. [Suggested action]"
+
+Usage:
+    from mcp_eregistrations_bpa.bpa_client.errors import translate_error
+
+    try:
+        response.raise_for_status()
+    except httpx.HTTPStatusError as e:
+        raise translate_error(e)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from mcp.server.fastmcp.exceptions import ToolError
+
+if TYPE_CHECKING:
+    import httpx
+
+__all__ = [
+    "BPAClientError",
+    "BPAConnectionError",
+    "BPATimeoutError",
+    "BPAAuthenticationError",
+    "BPAPermissionError",
+    "BPANotFoundError",
+    "BPAValidationError",
+    "BPARateLimitError",
+    "BPAServerError",
+    "translate_error",
+    "translate_http_error",
+]
+
+
+class BPAClientError(Exception):
+    """Base exception for BPA client errors.
+
+    All BPA client errors inherit from this class.
+    """
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        """Initialize BPA client error.
+
+        Args:
+            message: Error message.
+            status_code: HTTP status code if applicable.
+        """
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class BPAConnectionError(BPAClientError):
+    """Connection to BPA API failed."""
+
+
+class BPATimeoutError(BPAClientError):
+    """Request to BPA API timed out."""
+
+
+class BPAAuthenticationError(BPAClientError):
+    """Authentication with BPA API failed (401)."""
+
+
+class BPAPermissionError(BPAClientError):
+    """Permission denied by BPA API (403)."""
+
+
+class BPANotFoundError(BPAClientError):
+    """Resource not found in BPA API (404)."""
+
+
+class BPAValidationError(BPAClientError):
+    """Validation error from BPA API (400)."""
+
+
+class BPARateLimitError(BPAClientError):
+    """Rate limit exceeded (429)."""
+
+
+class BPAServerError(BPAClientError):
+    """BPA server error (5xx)."""
+
+
+def translate_http_error(
+    error: httpx.HTTPStatusError,
+    *,
+    resource_type: str | None = None,
+    resource_id: str | int | None = None,
+) -> BPAClientError:
+    """Translate httpx HTTP error to BPA-specific exception.
+
+    Args:
+        error: The httpx HTTP status error.
+        resource_type: Optional resource type for context (e.g., "service").
+        resource_id: Optional resource ID for context.
+
+    Returns:
+        A BPAClientError subclass appropriate for the status code.
+    """
+    status_code = error.response.status_code
+    response_text = error.response.text[:200] if error.response.text else ""
+
+    # Build resource context
+    resource_context = ""
+    if resource_type:
+        resource_context = f" {resource_type}"
+        if resource_id is not None:
+            resource_context = f" {resource_type} (ID: {resource_id})"
+
+    if status_code == 400:
+        # Check for "Database object not found" which BPA returns as 400 instead of 404
+        if "Database object not found" in response_text:
+            # Extract the ID from the message if possible
+            import json
+
+            try:
+                error_data = json.loads(response_text)
+                error_msg = error_data.get("message", "")
+                # Parse "Database object not found by id = X" pattern
+                if "by id =" in error_msg:
+                    obj_id = error_msg.split("by id =")[1].split(",")[0].strip()
+                    return BPANotFoundError(
+                        f"Resource with ID '{obj_id}' not found. "
+                        "Verify the ID is correct.",
+                        status_code=status_code,
+                    )
+            except (json.JSONDecodeError, IndexError):
+                pass
+            return BPANotFoundError(
+                "Resource not found. Verify the ID is correct.",
+                status_code=status_code,
+            )
+        msg = f"Invalid request for{resource_context}: {response_text}".strip()
+        return BPAValidationError(msg, status_code=status_code)
+
+    if status_code == 401:
+        return BPAAuthenticationError(
+            "Authentication failed. Token may be invalid or expired.",
+            status_code=status_code,
+        )
+
+    if status_code == 403:
+        return BPAPermissionError(
+            f"Access denied to{resource_context}. Check your permissions.",
+            status_code=status_code,
+        )
+
+    if status_code == 404:
+        if resource_type:
+            msg = f"{resource_type.capitalize()} not found"
+            if resource_id is not None:
+                msg = f"{resource_type.capitalize()} with ID {resource_id} not found"
+        else:
+            msg = "Resource not found"
+        return BPANotFoundError(msg, status_code=status_code)
+
+    if status_code == 429:
+        return BPARateLimitError(
+            "Rate limit exceeded. Please wait before retrying.",
+            status_code=status_code,
+        )
+
+    if status_code >= 500:
+        return BPAServerError(
+            f"BPA server error ({status_code}): {response_text}".strip(),
+            status_code=status_code,
+        )
+
+    # Generic error for other status codes
+    return BPAClientError(
+        f"BPA API error ({status_code}): {response_text}".strip(),
+        status_code=status_code,
+    )
+
+
+def translate_error(
+    error: Exception,
+    *,
+    resource_type: str | None = None,
+    resource_id: str | int | None = None,
+) -> ToolError:
+    """Translate any BPA client error to AI-friendly ToolError.
+
+    This is the main entry point for error translation. It handles
+    all exception types and produces consistent AI-friendly messages.
+
+    Error message format:
+        "[What happened]: [Why it matters]. [Suggested action]"
+
+    Args:
+        error: The exception to translate.
+        resource_type: Optional resource type for context.
+        resource_id: Optional resource ID for context.
+
+    Returns:
+        ToolError with AI-friendly message.
+    """
+    import httpx
+
+    # First translate httpx errors to BPA-specific errors
+    if isinstance(error, httpx.HTTPStatusError):
+        error = translate_http_error(
+            error, resource_type=resource_type, resource_id=resource_id
+        )
+
+    # Now translate to ToolError with AI-friendly message
+    if isinstance(error, BPAConnectionError):
+        return ToolError(
+            "Failed to connect to BPA API: Network or server may be unreachable. "
+            "Check your connection and BPA_INSTANCE_URL configuration."
+        )
+
+    if isinstance(error, BPATimeoutError):
+        return ToolError(
+            "BPA API request timed out: The server took too long to respond. "
+            "Try again or check if the BPA instance is healthy."
+        )
+
+    if isinstance(error, BPAAuthenticationError):
+        return ToolError(
+            "BPA authentication failed: Your session may have expired. "
+            "Run auth_login to re-authenticate."
+        )
+
+    if isinstance(error, BPAPermissionError):
+        return ToolError(
+            f"Permission denied: {error}. "
+            "Contact your administrator if you need access."
+        )
+
+    if isinstance(error, BPANotFoundError):
+        return ToolError(
+            f"Resource not found: {error}. "
+            "Verify the resource exists and you have access."
+        )
+
+    if isinstance(error, BPAValidationError):
+        return ToolError(f"Invalid request: {error}. Check your input parameters.")
+
+    if isinstance(error, BPARateLimitError):
+        return ToolError(
+            "Rate limit exceeded: Too many requests to BPA API. "
+            "Wait a moment and try again."
+        )
+
+    if isinstance(error, BPAServerError):
+        return ToolError(
+            f"BPA server error: {error}. "
+            "The BPA service may be experiencing issues. Try again later."
+        )
+
+    if isinstance(error, BPAClientError):
+        return ToolError(f"BPA API error: {error}")
+
+    # Handle httpx connection errors
+    if isinstance(error, httpx.ConnectError):
+        return ToolError(
+            "Failed to connect to BPA API: Network or server may be unreachable. "
+            "Check your connection and BPA_INSTANCE_URL configuration."
+        )
+
+    if isinstance(error, httpx.TimeoutException):
+        return ToolError(
+            "BPA API request timed out: The server took too long to respond. "
+            "Try again or check if the BPA instance is healthy."
+        )
+
+    # Generic fallback
+    return ToolError(f"BPA API error: {error}")

mcp_eregistrations_bpa/bpa_client/models.py

@@ -0,0 +1,203 @@
+"""Pydantic models for BPA API responses.
+
+These models provide type-safe representations of BPA API entities.
+All models use Pydantic v2 conventions.
+
+Note: These are base models for the most common entities. Additional
+models for specific endpoints may be added in future stories.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = [
+    "BPABaseModel",
+    "Service",
+    "Registration",
+    "FormField",
+    "Determinant",
+    "Role",
+    "Cost",
+    "Document",
+    "Action",
+    "Form",
+    "PaginatedResponse",
+]
+
+
+class BPABaseModel(BaseModel):
+    """Base model for all BPA entities.
+
+    Provides common configuration for all models.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",  # Allow unknown fields from API
+        populate_by_name=True,  # Support field aliases
+        str_strip_whitespace=True,  # Clean string values
+    )
+
+
+class Service(BPABaseModel):
+    """BPA Service entity.
+
+    A service represents a government procedure or registration type.
+    Services contain registrations, forms, fields, determinants, and roles.
+    """
+
+    id: int = Field(description="Unique service identifier")
+    name: str = Field(description="Service name")
+    short_name: str | None = Field(
+        default=None, alias="shortName", description="Short name abbreviation"
+    )
+    description: str | None = Field(default=None, description="Service description")
+    status: str | None = Field(default=None, description="Service status")
+    category: str | None = Field(default=None, description="Service category")
+
+
+class Registration(BPABaseModel):
+    """BPA Registration entity.
+
+    A registration is a concrete instance of a service procedure.
+    Registrations can link to fields, determinants, costs, and documents.
+    """
+
+    id: int = Field(
+        description="Unique registration identifier", alias="registration_id"
+    )
+    name: str = Field(description="Registration name")
+    service_id: int | None = Field(
+        default=None, alias="serviceId", description="Parent service ID"
+    )
+    description: str | None = Field(
+        default=None, description="Registration description"
+    )
+    status: str | None = Field(default=None, description="Registration status")
+
+
+class FormField(BPABaseModel):
+    """BPA Form Field entity.
+
+    A field is a data input element in a form. Fields have many-to-many
+    relationships with determinants and registrations.
+    """
+
+    id: int = Field(description="Unique field identifier", alias="field_id")
+    name: str = Field(description="Field name")
+    label: str | None = Field(default=None, description="Field label for display")
+    type: str | None = Field(default=None, description="Field data type")
+    required: bool = Field(default=False, description="Whether field is required")
+    description: str | None = Field(default=None, description="Field description")
+    service_id: int | None = Field(
+        default=None, alias="serviceId", description="Parent service ID"
+    )
+
+
+class Determinant(BPABaseModel):
+    """BPA Determinant entity.
+
+    A determinant controls conditional logic and field visibility.
+    Determinants have many-to-many relationships with fields and registrations.
+    """
+
+    id: int = Field(description="Unique determinant identifier", alias="determinant_id")
+    name: str = Field(description="Determinant name")
+    type: str | None = Field(default=None, description="Determinant type")
+    description: str | None = Field(default=None, description="Determinant description")
+    service_id: int | None = Field(
+        default=None, alias="serviceId", description="Parent service ID"
+    )
+
+
+class Role(BPABaseModel):
+    """BPA Role entity.
+
+    A role represents an actor in the registration process.
+    """
+
+    id: int = Field(description="Unique role identifier", alias="role_id")
+    name: str = Field(description="Role name")
+    description: str | None = Field(default=None, description="Role description")
+    service_id: int | None = Field(
+        default=None, alias="serviceId", description="Parent service ID"
+    )
+
+
+class Cost(BPABaseModel):
+    """BPA Cost entity.
+
+    A cost represents a fee associated with a registration.
+    """
+
+    id: int = Field(description="Unique cost identifier", alias="cost_id")
+    name: str = Field(description="Cost name")
+    amount: float | None = Field(default=None, description="Cost amount")
+    currency: str | None = Field(default=None, description="Currency code")
+    description: str | None = Field(default=None, description="Cost description")
+    registration_id: int | None = Field(
+        default=None, alias="registrationId", description="Parent registration ID"
+    )
+
+
+class Document(BPABaseModel):
+    """BPA Document entity.
+
+    A document is a file or attachment required for a registration.
+    """
+
+    id: int = Field(description="Unique document identifier", alias="document_id")
+    name: str = Field(description="Document name")
+    type: str | None = Field(default=None, description="Document type/format")
+    required: bool = Field(default=False, description="Whether document is required")
+    description: str | None = Field(default=None, description="Document description")
+    registration_id: int | None = Field(
+        default=None, alias="registrationId", description="Parent registration ID"
+    )
+
+
+class Action(BPABaseModel):
+    """BPA Action entity.
+
+    An action represents a step or operation in a workflow.
+    """
+
+    id: int = Field(description="Unique action identifier", alias="action_id")
+    name: str = Field(description="Action name")
+    type: str | None = Field(default=None, description="Action type")
+    description: str | None = Field(default=None, description="Action description")
+
+
+class Form(BPABaseModel):
+    """BPA Form entity.
+
+    A form is a collection of fields presented as a UI screen.
+    """
+
+    id: int = Field(description="Unique form identifier", alias="form_id")
+    name: str = Field(description="Form name")
+    description: str | None = Field(default=None, description="Form description")
+    service_id: int | None = Field(
+        default=None, alias="serviceId", description="Parent service ID"
+    )
+
+
+class PaginatedResponse(BPABaseModel):
+    """Generic paginated response wrapper.
+
+    Used for API responses that return lists with pagination.
+    """
+
+    items: list[dict[str, Any]] = Field(
+        default_factory=list, description="List of items"
+    )
+    total: int | None = Field(default=None, description="Total number of items")
+    page: int | None = Field(default=None, description="Current page number")
+    page_size: int | None = Field(
+        default=None, alias="pageSize", description="Items per page"
+    )
+    has_more: bool | None = Field(
+        default=None, alias="hasMore", description="Whether more pages exist"
+    )