maskanx_crm_backend/app/api/properties.py

"""Custom property definitions — fields added without a migration.

Two ways in, on purpose:

- `/properties` for a logged-in person, from the CRM's own settings screen.
- `/integrations/properties` for MaskanX, authenticated by an integration
  key. That is what an agent reaches through MCP when a conversation asks
  for a new field.

Both go through the same validation. An agent gets no shortcut around the
rules a person is held to — if anything it needs them more, since it will
happily invent a property name from a half-sentence.
"""

from typing import Annotated

from fastapi import APIRouter, Header, HTTPException, status
from sqlalchemy import select
from sqlalchemy.exc import IntegrityError

from app.core.security import CurrentUser, Database
from app.models import CustomProperty
from app.properties import PropertyError, validate_definition
from app.schemas import (
    CustomPropertyCreate,
    CustomPropertyOut,
    CustomPropertyUpdate,
)

router = APIRouter(prefix="/properties", tags=["Properties"])
integration_router = APIRouter(prefix="/integrations", tags=["Integrations"])


def _list_for(db, tenant_id: str, object_type: str | None) -> list[CustomProperty]:
    query = select(CustomProperty).where(CustomProperty.tenant_id == tenant_id)
    if object_type:
        query = query.where(CustomProperty.object_type == object_type)
    return list(db.scalars(query.order_by(CustomProperty.label)))


def _create(
    db,
    tenant_id: str,
    payload: CustomPropertyCreate,
    created_by: str,
) -> CustomProperty:
    try:
        validate_definition(
            name=payload.name,
            object_type=payload.object_type,
            data_type=payload.data_type,
            options=payload.options,
        )
    except PropertyError as exc:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail=str(exc),
        ) from exc

    prop = CustomProperty(
        tenant_id=tenant_id,
        object_type=payload.object_type,
        name=payload.name,
        label=payload.label,
        description=payload.description,
        data_type=payload.data_type,
        options=payload.options,
        is_required=payload.is_required,
        created_by=created_by,
    )
    db.add(prop)
    try:
        db.commit()
    except IntegrityError as exc:
        db.rollback()
        # Told plainly rather than as a constraint name: an agent that
        # re-runs a request needs to know the field already exists, not
        # that a unique index fired.
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail=(
                f"A property named {payload.name!r} already exists on "
                f"{payload.object_type}."
            ),
        ) from exc
    return prop


@router.get("", response_model=list[CustomPropertyOut])
def list_properties(
    user: CurrentUser,
    db: Database,
    object_type: str | None = None,
) -> list[CustomProperty]:
    return _list_for(db, user.tenant_id, object_type)


@router.post("", response_model=CustomPropertyOut, status_code=status.HTTP_201_CREATED)
def create_property(
    payload: CustomPropertyCreate,
    user: CurrentUser,
    db: Database,
) -> CustomProperty:
    return _create(db, user.tenant_id, payload, created_by=user.email)


@router.patch("/{property_id}", response_model=CustomPropertyOut)
def update_property(
    property_id: str,
    payload: CustomPropertyUpdate,
    user: CurrentUser,
    db: Database,
) -> CustomProperty:
    """Update a property's presentation, never its identity or type.

    `name` and `data_type` are not updatable — see `CustomPropertyUpdate`.
    Narrowing an enumeration is allowed even though records may already
    hold a value that is no longer offered: those values stay readable and
    simply cannot be chosen again, which is the behaviour an operator
    retiring an option expects.
    """
    prop = db.scalar(
        select(CustomProperty).where(
            CustomProperty.id == property_id,
            CustomProperty.tenant_id == user.tenant_id,
        ),
    )
    if prop is None:
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)

    if payload.options is not None and prop.data_type != "enumeration":
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail=f"Options only apply to an enumeration, not to a {prop.data_type}.",
        )
    if payload.options is not None and not payload.options:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
            detail="An enumeration needs at least one option.",
        )

    for field, value in payload.model_dump(exclude_unset=True).items():
        if value is not None:
            setattr(prop, field, value)
    db.commit()
    return prop


@router.delete("/{property_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_property(property_id: str, user: CurrentUser, db: Database) -> None:
    """Remove a definition.

    Values already written into records are left where they are. Rewriting
    every record to strip a key would be a large, silent, irreversible
    write in response to a small request; leaving them means undoing a
    mistaken delete is just recreating the property.
    """
    prop = db.scalar(
        select(CustomProperty).where(
            CustomProperty.id == property_id,
            CustomProperty.tenant_id == user.tenant_id,
        ),
    )
    if prop is None:
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
    db.delete(prop)
    db.commit()


# --- integration key access, for MaskanX and its MCP tools ---


@integration_router.get("/properties", response_model=list[CustomPropertyOut])
def list_properties_via_integration(
    db: Database,
    object_type: str | None = None,
    integration_key: Annotated[str | None, Header(alias="X-Integration-Key")] = None,
) -> list[CustomProperty]:
    from app.api.integrations import _authenticate_integration

    credential = _authenticate_integration(db, integration_key)
    properties = _list_for(db, credential.tenant_id, object_type)
    db.commit()
    return properties


@integration_router.post(
    "/properties",
    response_model=CustomPropertyOut,
    status_code=status.HTTP_201_CREATED,
)
def create_property_via_integration(
    payload: CustomPropertyCreate,
    db: Database,
    integration_key: Annotated[str | None, Header(alias="X-Integration-Key")] = None,
) -> CustomProperty:
    from app.api.integrations import _authenticate_integration

    credential = _authenticate_integration(db, integration_key)
    return _create(
        db,
        credential.tenant_id,
        payload,
        created_by=f"integration:{credential.name}",
    )