"""Lista las propiedades de Google Search Console accesibles por una cuenta de servicio.

Verificacion de acceso del capability group ``seo``: tras dar de alta la
service account y anadir su email como usuario en Search Console, esta funcion
confirma que el acceso funciona y muestra que ``site_url`` usar (y con que
nivel de permiso).
"""


def gsc_list_sites(credentials_path: str = "") -> list:
    """Lista las propiedades de Search Console accesibles por la service account.

    Autentica con ``gsc_auth`` del registry (que ya resuelve ``credentials_path``
    o, si esta vacio, la env var ``GSC_SA_JSON``) y llama a
    ``service.sites().list().execute()``. Aplana la respuesta a una lista de
    dicts con ``site_url`` y ``permission_level``.

    Es la forma de comprobar, antes de ingerir nada, que (a) la service account
    autentica y (b) tiene acceso a la propiedad esperada y con que nivel de
    permiso.

    Args:
        credentials_path: ruta al JSON de la service account. Si esta vacio, se
            delega en ``gsc_auth``, que lo lee de la env var ``GSC_SA_JSON``.

    Returns:
        Lista de dicts ``[{"site_url": <siteUrl>, "permission_level":
        <permissionLevel>}, ...]``. Lista vacia si la cuenta no tiene
        propiedades accesibles (no lanza en ese caso).

    Raises:
        ValueError: si no se proporciona ``credentials_path`` ni la env var
            ``GSC_SA_JSON`` (propagado desde ``gsc_auth``).
    """
    # Import diferido del registry: mantiene barata la importacion del modulo y
    # permite mockear el simbolo en tests sin tocar la red.
    from infra import gsc_auth

    service = gsc_auth(credentials_path)
    response = service.sites().list().execute()
    return [
        {
            "site_url": entry.get("siteUrl"),
            "permission_level": entry.get("permissionLevel"),
        }
        for entry in response.get("siteEntry", [])
    ]
