claudetools/api/routers/clients.py

"""
Client API router for ClaudeTools.

This module defines all REST API endpoints for managing clients, including
CRUD operations with proper authentication, validation, and error handling.
"""

from uuid import UUID

from fastapi import APIRouter, Depends, HTTPException, Query, status
from sqlalchemy.orm import Session

from api.database import get_db
from api.middleware.auth import get_current_user
from api.schemas.client import (
    ClientCreate,
    ClientResponse,
    ClientUpdate,
)
from api.services import client_service

# Create router with prefix and tags
router = APIRouter()


@router.get(
    "",
    response_model=dict,
    summary="List all clients",
    description="Retrieve a paginated list of all clients with optional filtering",
    status_code=status.HTTP_200_OK,
)
def list_clients(
    skip: int = Query(
        default=0,
        ge=0,
        description="Number of records to skip for pagination"
    ),
    limit: int = Query(
        default=100,
        ge=1,
        le=1000,
        description="Maximum number of records to return (max 1000)"
    ),
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    List all clients with pagination.

    - **skip**: Number of clients to skip (default: 0)
    - **limit**: Maximum number of clients to return (default: 100, max: 1000)

    Returns a list of clients with pagination metadata.

    **Example Request:**
    ```
    GET /api/clients?skip=0&limit=50
    Authorization: Bearer <token>
    ```

    **Example Response:**
    ```json
    {
        "total": 5,
        "skip": 0,
        "limit": 50,
        "clients": [
            {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "name": "Acme Corporation",
                "type": "msp_client",
                "network_subnet": "192.168.0.0/24",
                "domain_name": "acme.local",
                "m365_tenant_id": "abc12345-6789-0def-1234-56789abcdef0",
                "primary_contact": "John Doe",
                "notes": "Main MSP client",
                "is_active": true,
                "created_at": "2024-01-15T10:30:00Z",
                "updated_at": "2024-01-15T10:30:00Z"
            }
        ]
    }
    ```
    """
    try:
        clients, total = client_service.get_clients(db, skip, limit)

        return {
            "total": total,
            "skip": skip,
            "limit": limit,
            "clients": [ClientResponse.model_validate(client) for client in clients]
        }

    except Exception as e:
        raise HTTPException(
            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
            detail=f"Failed to retrieve clients: {str(e)}"
        )


@router.get(
    "/{client_id}",
    response_model=ClientResponse,
    summary="Get client by ID",
    description="Retrieve a single client by its unique identifier",
    status_code=status.HTTP_200_OK,
    responses={
        200: {
            "description": "Client found and returned",
            "model": ClientResponse,
        },
        404: {
            "description": "Client not found",
            "content": {
                "application/json": {
                    "example": {"detail": "Client with ID 123e4567-e89b-12d3-a456-426614174000 not found"}
                }
            },
        },
    },
)
def get_client(
    client_id: UUID,
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    Get a specific client by ID.

    - **client_id**: UUID of the client to retrieve

    Returns the complete client details.

    **Example Request:**
    ```
    GET /api/clients/123e4567-e89b-12d3-a456-426614174000
    Authorization: Bearer <token>
    ```

    **Example Response:**
    ```json
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Acme Corporation",
        "type": "msp_client",
        "network_subnet": "192.168.0.0/24",
        "domain_name": "acme.local",
        "m365_tenant_id": "abc12345-6789-0def-1234-56789abcdef0",
        "primary_contact": "John Doe",
        "notes": "Main MSP client",
        "is_active": true,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
    }
    ```
    """
    client = client_service.get_client_by_id(db, client_id)
    return ClientResponse.model_validate(client)


@router.post(
    "",
    response_model=ClientResponse,
    summary="Create new client",
    description="Create a new client with the provided details",
    status_code=status.HTTP_201_CREATED,
    responses={
        201: {
            "description": "Client created successfully",
            "model": ClientResponse,
        },
        409: {
            "description": "Client with name already exists",
            "content": {
                "application/json": {
                    "example": {"detail": "Client with name 'Acme Corporation' already exists"}
                }
            },
        },
        422: {
            "description": "Validation error",
            "content": {
                "application/json": {
                    "example": {
                        "detail": [
                            {
                                "loc": ["body", "name"],
                                "msg": "field required",
                                "type": "value_error.missing"
                            }
                        ]
                    }
                }
            },
        },
    },
)
def create_client(
    client_data: ClientCreate,
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    Create a new client.

    Requires a valid JWT token with appropriate permissions.

    **Example Request:**
    ```json
    POST /api/clients
    Authorization: Bearer <token>
    Content-Type: application/json

    {
        "name": "Acme Corporation",
        "type": "msp_client",
        "network_subnet": "192.168.0.0/24",
        "domain_name": "acme.local",
        "m365_tenant_id": "abc12345-6789-0def-1234-56789abcdef0",
        "primary_contact": "John Doe",
        "notes": "Main MSP client",
        "is_active": true
    }
    ```

    **Example Response:**
    ```json
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Acme Corporation",
        "type": "msp_client",
        "network_subnet": "192.168.0.0/24",
        "domain_name": "acme.local",
        "m365_tenant_id": "abc12345-6789-0def-1234-56789abcdef0",
        "primary_contact": "John Doe",
        "notes": "Main MSP client",
        "is_active": true,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
    }
    ```
    """
    client = client_service.create_client(db, client_data)
    return ClientResponse.model_validate(client)


@router.put(
    "/{client_id}",
    response_model=ClientResponse,
    summary="Update client",
    description="Update an existing client's details",
    status_code=status.HTTP_200_OK,
    responses={
        200: {
            "description": "Client updated successfully",
            "model": ClientResponse,
        },
        404: {
            "description": "Client not found",
            "content": {
                "application/json": {
                    "example": {"detail": "Client with ID 123e4567-e89b-12d3-a456-426614174000 not found"}
                }
            },
        },
        409: {
            "description": "Conflict with existing client",
            "content": {
                "application/json": {
                    "example": {"detail": "Client with name 'Acme Corporation' already exists"}
                }
            },
        },
    },
)
def update_client(
    client_id: UUID,
    client_data: ClientUpdate,
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    Update an existing client.

    - **client_id**: UUID of the client to update

    Only provided fields will be updated. All fields are optional.

    **Example Request:**
    ```json
    PUT /api/clients/123e4567-e89b-12d3-a456-426614174000
    Authorization: Bearer <token>
    Content-Type: application/json

    {
        "primary_contact": "Jane Smith",
        "is_active": false,
        "notes": "Client moved to inactive status"
    }
    ```

    **Example Response:**
    ```json
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Acme Corporation",
        "type": "msp_client",
        "network_subnet": "192.168.0.0/24",
        "domain_name": "acme.local",
        "m365_tenant_id": "abc12345-6789-0def-1234-56789abcdef0",
        "primary_contact": "Jane Smith",
        "notes": "Client moved to inactive status",
        "is_active": false,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T14:20:00Z"
    }
    ```
    """
    client = client_service.update_client(db, client_id, client_data)
    return ClientResponse.model_validate(client)


@router.delete(
    "/{client_id}",
    response_model=dict,
    summary="Delete client",
    description="Delete a client by its ID",
    status_code=status.HTTP_200_OK,
    responses={
        200: {
            "description": "Client deleted successfully",
            "content": {
                "application/json": {
                    "example": {
                        "message": "Client deleted successfully",
                        "client_id": "123e4567-e89b-12d3-a456-426614174000"
                    }
                }
            },
        },
        404: {
            "description": "Client not found",
            "content": {
                "application/json": {
                    "example": {"detail": "Client with ID 123e4567-e89b-12d3-a456-426614174000 not found"}
                }
            },
        },
    },
)
def delete_client(
    client_id: UUID,
    db: Session = Depends(get_db),
    current_user: dict = Depends(get_current_user),
):
    """
    Delete a client.

    - **client_id**: UUID of the client to delete

    This is a permanent operation and cannot be undone.

    **Example Request:**
    ```
    DELETE /api/clients/123e4567-e89b-12d3-a456-426614174000
    Authorization: Bearer <token>
    ```

    **Example Response:**
    ```json
    {
        "message": "Client deleted successfully",
        "client_id": "123e4567-e89b-12d3-a456-426614174000"
    }
    ```
    """
    return client_service.delete_client(db, client_id)