utils

async def create_entity_link(
    project_name: str,
    user: "UserEntity",
    ayon_server_url: str,
    input_id: str,
    output_id: str,
    link_type: str,
    data: dict[str, Any] | None = None,
) -> str | None:
    """Create an entity link via AYON REST API.

    Create a link between two folders (input and output) with the specified
    link type. Multiple links with the same input/output/type are allowed
    (e.g., for multi-occurence casting).

    Args:
        project_name: AYON project name.
        user: User entity for authentication.
        ayon_server_url: Base URL of the AYON server.
        input_id: AYON folder ID of the link input (source).
        output_id: AYON folder ID of the link output (target).
        link_type: Link type identifier in format "name|input_type|output_type"
            (e.g., "breakdown|folder|folder").
        data: Optional dictionary containing link metadata (e.g., kitsuAssetId,
            kitsuTargetId,             occurence).

    Returns:
        Created link ID string if successful, None otherwise. Warnings
        on failure.
    """
    session = await Session.create(user)
    headers = {"Authorization": f"Bearer {session.token}"}
    payload: dict = {
        "input": input_id,
        "output": output_id,
        "linkType": link_type,
    }
    if data:
        payload["data"] = data

    async with httpx.AsyncClient() as client:
        res = await client.post(
            f"{ayon_server_url}/api/projects/{project_name}/links",
            json=payload,
            headers=headers,
        )
    if res.status_code not in (200, 201):
        logging.warning(
            f"Failed to create link {input_id}->{output_id} "
            f"type '{link_type}': {res.status_code} {res.text}"
        )
        return
    try:
        return res.json().get("id")
    except Exception:
        return None

async def create_folder(
    project_name: str,
    name: str,
    **kwargs,
) -> FolderEntity:
    """
    TODO: This is a re-implementation of create folder, which does not
    require background tasks. Maybe just use the similar function from
    api.folders.folders.py?
    """
    payload = {**kwargs, **create_name_and_label(name)}

    folder = FolderEntity(
        project_name=project_name,
        payload=payload,
    )
    await folder.save()
    event = {
        "topic": "entity.folder.created",
        "description": f"Folder {folder.name} created",
        "summary": {"entityId": folder.id, "parentId": folder.parent_id},
        "project": project_name,
    }

    await dispatch_event(**event)
    return folder

def create_name_and_label(kitsu_name: str) -> dict[str, str]:
    """From a name coming from kitsu, create a name and label"""
    name_slug = slugify(kitsu_name, separator="_")
    return {"name": name_slug, "label": kitsu_name}

async def delete_entity_link(
    project_name: str,
    user: "UserEntity",
    ayon_server_url: str,
    link_id: str,
) -> None:
    """Delete an entity link via AYON REST API.

    Delete a link by its ID. Log warnings if the deletion fails.

    Args:
        project_name: AYON project name.
        user: User entity for authentication.
        ayon_server_url: Base URL of the AYON server.
        link_id: ID of the link to delete.

    Returns:
        None. Warnings on failure.
    """
    session = await Session.create(user)
    headers = {"Authorization": f"Bearer {session.token}"}

    async with httpx.AsyncClient() as client:
        res = await client.delete(
            f"{ayon_server_url}/api/projects/{project_name}/links/{link_id}",
            headers=headers,
        )

    if res.status_code not in (200, 204):
        logging.warning(
            f"Failed to delete link {link_id}: {res.status_code} {res.text}"
        )

async def get_folder_by_kitsu_id(
    project_name: str,
    kitsu_id: str,
    existing_folders: dict[str, str] | None = None,
) -> FolderEntity | None:
    """Get an Ayon FolderEndtity by its Kitsu ID"""

    if existing_folders and (kitsu_id in existing_folders):
        folder_id = existing_folders[kitsu_id]

    else:
        res = await Postgres.fetch(
            f"""
            SELECT id FROM project_{project_name}.folders
            WHERE data->>'kitsuId' = $1
            """,
            kitsu_id,
        )
        if not res:
            return None
        folder_id = res[0]["id"]

    return await FolderEntity.load(project_name, folder_id)

async def get_link_by_io(
    project_name: str,
    input_id: str,
    output_id: str,
    link_type: str,
) -> str | None:
    """Get a link ID by input/output IDs and link type.

    Query the database for an existing link matching the given input,
    output, and link type. Return the first matching link's ID, or None
    if no link exists.

    Args:
        project_name: AYON project name (validated for SQL safety).
        input_id: AYON folder ID of the link input (source).
        output_id: AYON folder ID of the link output (target).
        link_type: Link type identifier (e.g., "breakdown|folder|folder").

    Returns:
        Link ID string if found, None otherwise.
    """
    _ensure_safe_project_name(project_name)
    res = await Postgres.fetch(
        f"""
        SELECT id FROM project_{project_name}.links
        WHERE input_id = $1 AND output_id = $2 AND link_type = $3
        """,
        input_id,
        output_id,
        link_type,
    )
    if not res:
        return None
    return res[0]["id"]

async def get_links_for_output(
    project_name: str,
    output_id: str,
    link_type: str,
) -> list[dict[str, Any]]:
    """Get all links for a given output folder and link type.

    Query the database for all links where the specified folder is the
    output (target). Return link metadata including ID, input_id, and data.

    Args:
        project_name: AYON project name (validated for SQL safety).
        output_id: AYON folder ID of the link output (target).
        link_type: Link type identifier (e.g., "breakdown|folder|folder").

    Returns:
        List of link dictionaries, each containing:
            - id: Link ID
            - input_id: AYON folder ID of the link input (source)
            - data: Link data dictionary (may contain kitsuAssetId, etc.)
    """
    _ensure_safe_project_name(project_name)
    return await Postgres.fetch(
        f"""
        SELECT id, input_id, data FROM project_{project_name}.links
        WHERE output_id = $1 AND link_type = $2
        """,
        output_id,
        link_type,
    )

async def get_task_by_kitsu_id(
    project_name: str,
    kitsu_id: str,
    existing_tasks: dict[str, str] | None = None,
) -> TaskEntity | None:
    """Get an Ayon TaskEntity by its Kitsu ID"""

    if existing_tasks and (kitsu_id in existing_tasks):
        folder_id = existing_tasks[kitsu_id]

    else:
        res = await Postgres.fetch(
            f"""
            SELECT id FROM project_{project_name}.tasks
            WHERE data->>'kitsuId' = $1
            """,
            kitsu_id,
        )
        if not res:
            return None
        folder_id = res[0]["id"]

    return await TaskEntity.load(project_name, folder_id)

async def get_user_by_kitsu_id(
    kitsu_id: str,
) -> UserEntity | None:
    """Get an Ayon UserEndtity by its Kitsu ID"""
    res = await Postgres.fetch(
        "SELECT name FROM public.users WHERE data->>'kitsuId' = $1",
        kitsu_id,
    )
    if not res:
        return None
    user = await UserEntity.load(res[0]["name"])
    return user

async def update_entity(
    project_name, entity, kwargs, attr_whitelist: list[str] | None = None
):
    """Updates the entity for given attribute whitelist.

    Saves changes and dispatches an update event.
    """

    if attr_whitelist is None:
        attr_whitelist = []

    changed = False

    # keys that can be updated
    for key in attr_whitelist:
        if key in kwargs and getattr(entity, key) != kwargs[key]:
            setattr(entity, key, kwargs[key])
            logging.info(f"setattr {key}")
            changed = True
    if "attrib" in kwargs:
        for key, value in kwargs["attrib"].items():
            if getattr(entity.attrib, key) != value:
                setattr(entity.attrib, key, value)
                if key not in entity.own_attrib:
                    entity.own_attrib.append(key)
                logging.info(
                    f"setattr attrib.{key}"
                    f" {getattr(entity.attrib, key)} => {value}"
                )
                changed = True
    if changed:
        await entity.save()

        summary = {}
        if hasattr(entity, "id"):
            summary["id"] = entity.id
        if hasattr(entity, "parent_id"):
            summary["parent_id"] = entity.parent_id
        if hasattr(entity, "name"):
            summary["name"] = entity.name

        event = {
            "topic": f"entity.{entity.entity_type}.updated",
            "description": f"{entity.entity_type} {entity.name} updated",
            "summary": summary,
            "project": project_name,
        }
        logging.info(f"dispatch_event: {event}")
        await dispatch_event(**event)
    return changed