Metron

def get_arc(self, arc_id: int) -> Arc:
    """Retrieve detailed information about a story arc by ID.

    Args:
        arc_id: The unique identifier of the arc.

    Returns:
        An Arc object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/arc/{arc_id}")
        return TypeAdapter(Arc).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_character(self, character_id: int) -> Character:
    """Retrieve detailed information about a character by ID.

    Args:
        character_id: The unique identifier of the character.

    Returns:
        A Character object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/character/{character_id}")
        return TypeAdapter(Character).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_collection(self, collection_id: int) -> Collection:
    """Retrieve detailed information about a collection item by ID.

    Note: This endpoint requires authentication.
    Users can only access their own collection items.

    Args:
        collection_id: The unique identifier of the collection entry.

    Returns:
        A Collection object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/collection/{collection_id}")
        return TypeAdapter(Collection).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_collection_stats(self) -> CollectionStats:
    """Retrieve statistics about the authenticated user's collection.

    Returns comprehensive statistics including total items, total value, read/unread counts,
    and breakdowns by format.
    Note: This endpoint requires authentication.

    Returns:
        A CollectionStats object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint="/collection/stats")
        return TypeAdapter(CollectionStats).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_creator(self, creator_id: int) -> Creator:
    """Retrieve detailed information about a creator by ID.

    Args:
        creator_id: The unique identifier of the creator.

    Returns:
        A Creator object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/creator/{creator_id}")
        return TypeAdapter(Creator).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_imprint(self, imprint_id: int) -> Imprint:
    """Retrieve detailed information about an imprint by ID.

    Args:
        imprint_id: The unique identifier of the imprint.

    Returns:
        An Imprint object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/imprint/{imprint_id}")
        return TypeAdapter(Imprint).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_issue(self, issue_id: int) -> Issue:
    """Retrieve detailed information about an issue by ID.

    Args:
        issue_id: The unique identifier of the issue.

    Returns:
        An Issue object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/issue/{issue_id}")
        return TypeAdapter(Issue).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_publisher(self, publisher_id: int) -> Publisher:
    """Retrieve detailed information about a publisher by ID.

    Args:
        publisher_id: The unique identifier of the publisher.

    Returns:
        A Publisher object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/publisher/{publisher_id}")
        return TypeAdapter(Publisher).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_reading_list(self, reading_list_id: int) -> ReadingList:
    """Retrieve detailed information about a reading list by ID.

    Args:
        reading_list_id: The unique identifier of the reading list.

    Returns:
        A ReadingList object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/reading_list/{reading_list_id}")
        return TypeAdapter(ReadingList).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_series(self, series_id: int) -> Series:
    """Retrieve detailed information about a series by ID.

    Args:
        series_id: The unique identifier of the series.

    Returns:
        A Series object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/series/{series_id}")
        return TypeAdapter(Series).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_team(self, team_id: int) -> Team:
    """Retrieve detailed information about a team by ID.

    Args:
        team_id: The unique identifier of the team.

    Returns:
        A Team object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/team/{team_id}")
        return TypeAdapter(Team).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def get_universe(self, universe_id: int) -> Universe:
    """Retrieve detailed information about a universe by ID.

    Args:
        universe_id: The unique identifier of the universe.

    Returns:
        A Universe object.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        result = self._fetch_item(endpoint=f"/universe/{universe_id}")
        return TypeAdapter(Universe).validate_python(result)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_arc_issues(self, arc_id: int) -> list[CommonIssue]:
    """Retrieve a list of issues that are part of a specific story arc.

    Args:
        arc_id: The unique identifier of the arc.

    Returns:
        A list of CommonIssue objects.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        results = self._fetch_list(endpoint=f"/arc/{arc_id}/issue_list")
        return TypeAdapter(list[CommonIssue]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_arcs(
    self,
    cv_id: int | None = None,
    gcd_id: int | None = None,
    modified_gt: datetime | None = None,
    name: str | None = None,
) -> list[CommonResource]:
    """Retrieve a list of story arcs with optional filtering.

    Args:
        cv_id: Filter by Comic Vine ID.
        gcd_id: Filter by Grand Comics Database ID.
        modified_gt: Return arcs modified after this datetime.
        name: Filter arcs by name (partial match).

    Returns:
        A list of CommonResource objects representing arcs.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    params = filter_params(
        data={"cv_id": cv_id, "gcd_id": gcd_id, "modified_gt": modified_gt, "name": name}
    )
    try:
        results = self._fetch_list(endpoint="/arc", params=params)
        return TypeAdapter(list[CommonResource]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_character_issues(self, character_id: int) -> list[CommonIssue]:
    """Retrieve a list of issues featuring a specific character.

    Args:
        character_id: The unique identifier of the character.

    Returns:
        A list of CommonIssue objects.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        results = self._fetch_list(endpoint=f"/character/{character_id}/issue_list")
        return TypeAdapter(list[CommonIssue]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_characters(
    self,
    cv_id: int | None = None,
    gcd_id: int | None = None,
    modified_gt: datetime | None = None,
    name: str | None = None,
) -> list[CommonResource]:
    """Retrieve a list of characters with optional filtering.

    Args:
        cv_id: Filter by Comic Vine ID.
        gcd_id: Filter by Grand Comics Database ID.
        modified_gt: Return characters modified after this datetime.
        name: Filter characters by name (partial match).

    Returns:
        A list of CommonResource objects representing characters.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    params = filter_params(
        data={"cv_id": cv_id, "gcd_id": gcd_id, "modified_gt": modified_gt, "name": name}
    )
    try:
        results = self._fetch_list(endpoint="/character", params=params)
        return TypeAdapter(list[CommonResource]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_collection_missing_issues(self, series_id: int) -> list[BaseIssue]:
    """Retrieve a list of missing issues for a specific series.

    Returns issues from a series that are not in the authenticated user's collection.
    Note: This endpoint requires authentication.

    Args:
        series_id: The unique identifier of the series.

    Returns:
        A list of BaseIssue objects representing missing issues.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        results = self._fetch_list(endpoint=f"/collection/missing_issues/{series_id}")
        return TypeAdapter(list[BaseIssue]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_collection_missing_series(self) -> list[MissingSeries]:
    """Retrieve a list of series where the user has some issues but is missing others.

    Returns series where the authenticated user owns at least one issue but not all issues in
    the series.
    Note: This endpoint requires authentication.

    Returns:
        A list of MissingSeries objects.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        results = self._fetch_list(endpoint="/collection/missing_series")
        return TypeAdapter(list[MissingSeries]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_collections(
    self,
    book_format: BookFormat | None = None,
    date_read: date | None = None,
    date_read_gt: date | None = None,
    date_read_gte: date | None = None,
    date_read_lt: date | None = None,
    date_read_lte: date | None = None,
    grade: Grade | None = None,
    grading_company: GradingCompany | None = None,
    is_read: bool | None = None,
    modified_gt: datetime | None = None,
    purchase_date: date | None = None,
    purchase_date_gt: date | None = None,
    purchase_date_gte: date | None = None,
    purchase_date_lt: date | None = None,
    purchase_date_lte: date | None = None,
    purchase_store: str | None = None,
    rating: Rating | None = None,
    series_id: int | None = None,
    storage_location: str | None = None,
) -> list[BaseCollection]:
    """Retrieve a list of collection items with optional filtering.

    Note: This endpoint requires authentication.
    Users can only access their own collection items.

    Args:
        book_format: Filter by the format of the book.
        date_read: Filter by an exact read date.
        date_read_gt: Filter for items read after the given date.
        date_read_gte: Filter for items read on or after the given date.
        date_read_lt: Filter for items read before the given date.
        date_read_lte: Filter for items read on or before the given date.
        grade: Filter by the assigned grade value.
        grading_company: Filter by the grading company that issued the grade.
        is_read: Filter by read status.
        modified_gt: Return collections modified after this datetime.
        purchase_date: Filter by an exact purchase date.
        purchase_date_gt: Filter for items purchased after the given date.
        purchase_date_gte: Filter for items purchased on or after the given date.
        purchase_date_lt: Filter for items purchased before the given date.
        purchase_date_lte: Filter for items purchased on or before the given date.
        purchase_store: Filter by the name of the purchase store.
        rating: Filter by the assigned rating value.
        series_id: Filter by series id.
        storage_location: Filter by the storage location of the item.

    Returns:
        A list of BaseCollection objects.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    params = filter_params(
        data={
            "book_format": book_format,
            "date_read": date_read,
            "date_read_gt": date_read_gt,
            "date_read_gte": date_read_gte,
            "date_read_lt": date_read_lt,
            "date_read_lte": date_read_lte,
            "grade": grade,
            "grading_company": grading_company,
            "is_read": is_read,
            "issue__series": series_id,
            "modified_gt": modified_gt,
            "purchase_date": purchase_date,
            "purchase_date_gt": purchase_date_gt,
            "purchase_date_gte": purchase_date_gte,
            "purchase_date_lt": purchase_date_lt,
            "purchase_date_lte": purchase_date_lte,
            "purchase_store": purchase_store,
            "rating": rating,
            "storage_location": storage_location,
        }
    )
    try:
        results = self._fetch_list(endpoint="/collection", params=params)
        return TypeAdapter(list[BaseCollection]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_creators(
    self,
    cv_id: int | None = None,
    gcd_id: int | None = None,
    modified_gt: datetime | None = None,
    name: str | None = None,
) -> list[CommonResource]:
    """Retrieve a list of creators with optional filtering.

    Args:
        cv_id: Filter by Comic Vine ID.
        gcd_id: Filter by Grand Comics Database ID.
        modified_gt: Return creators modified after this datetime.
        name: Filter creators by name (partial match).

    Returns:
        A list of CommonResource objects representing creators.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    params = filter_params(
        data={"cv_id": cv_id, "gcd_id": gcd_id, "modified_gt": modified_gt, "name": name}
    )
    try:
        results = self._fetch_list(endpoint="/creator", params=params)
        return TypeAdapter(list[CommonResource]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_imprints(
    self,
    cv_id: int | None = None,
    gcd_id: int | None = None,
    modified_gt: datetime | None = None,
    name: str | None = None,
) -> list[CommonResource]:
    """Retrieve a list of imprints with optional filtering.

    Args:
        cv_id: Filter by Comic Vine ID.
        gcd_id: Filter by Grand Comics Database ID.
        modified_gt: Return imprints modified after this datetime.
        name: Filter imprints by name (partial match).

    Returns:
        A list of CommonResource objects representing imprints.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    params = filter_params(
        data={"cv_id": cv_id, "gcd_id": gcd_id, "modified_gt": modified_gt, "name": name}
    )
    try:
        results = self._fetch_list(endpoint="/imprint", params=params)
        return TypeAdapter(list[CommonResource]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_issues(
    self,
    alt_number: str | None = None,
    character_id: int | None = None,
    cover_hash: str | None = None,
    cover_month: int | None = None,
    cover_year: int | None = None,
    creator_id: int | None = None,
    cv_id: int | None = None,
    foc_date: date | None = None,
    foc_date_range_after: date | None = None,
    foc_date_range_before: date | None = None,
    gcd_id: int | None = None,
    imprint_id: int | None = None,
    imprint_name: str | None = None,
    missing_cv_id: bool | None = None,
    missing_gcd_id: bool | None = None,
    modified_gt: datetime | None = None,
    number: str | None = None,
    publisher_id: int | None = None,
    publisher_name: str | None = None,
    rating: str | None = None,
    role_ids: list[int] | None = None,
    series_id: int | None = None,
    series_name: str | None = None,
    series_volume: int | None = None,
    series_year_began: int | None = None,
    sku: str | None = None,
    store_date: date | None = None,
    store_date_range_after: date | None = None,
    store_date_range_before: date | None = None,
    team_id: int | None = None,
    universe_id: int | None = None,
    upc: str | None = None,
) -> list[CommonIssue]:
    """Retrieve a list of issues with optional filtering.

    Args:
        alt_number: Filter by the issue's alternate number.
        character_id: Filter by the creator ID.
        cover_hash: Filter by the hash value of the issue's cover image.
        cover_month: Filter by the cover month (1-12).
        cover_year: Filter by the cover year.
        creator_id: Filter by the creator ID.
        cv_id: Filter by Comic Vine ID.
        foc_date: Filter by an exact Final Order Cutoff (FOC) date.
        foc_date_range_after: Filter for issues with an FOC date after the given date.
        foc_date_range_before: Filter for issues with an FOC date before the given date.
        gcd_id: Filter by Grand Comics Database ID.
        imprint_id: Filter by the associated imprint ID.
        imprint_name: Filter by the associated imprint name.
        missing_cv_id: If True, return only issues missing a Comic Vine ID.
        missing_gcd_id: If True, return only issues missing a Grand Comics Database ID.
        modified_gt: Return issues modified after this datetime.
        number: Filter by the issue number.
        publisher_id: Filter by the publisher ID.
        publisher_name: Filter by the publisher name.
        rating: Filter by the issue rating.
        role_ids: Filter by a list of role IDs.
        series_id: Filter by the series ID.
        series_name: Filter by the series name.
        series_volume: Filter by the series volume number.
        series_year_began: Filter by the year the series began.
        sku: Filter by the distributor SKU.
        store_date: Filter by an exact store date.
        store_date_range_after: Filter for issues with a store date after the given date.
        store_date_range_before: Filter for issues with a store date before the given date.
        team_id: Filter by the team ID.
        universe_id: Filter by the universe ID.
        upc: Filter by the issue's UPC barcode.

    Returns:
        A list of CommonIssue objects.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    params = filter_params(
        data={
            "alt_number": alt_number,
            "character_id": character_id,
            "cover_hash": cover_hash,
            "cover_month": cover_month,
            "cover_year": cover_year,
            "creator_id": creator_id,
            "cv_id": cv_id,
            "foc_date": foc_date,
            "foc_date_range_after": foc_date_range_after,
            "foc_date_range_before": foc_date_range_before,
            "gcd_id": gcd_id,
            "imprint_id": imprint_id,
            "imprint_name": imprint_name,
            "missing_cv_id": missing_cv_id,
            "missing_gcd_id": missing_gcd_id,
            "modified_gt": modified_gt,
            "number": number,
            "publisher_id": publisher_id,
            "publisher_name": publisher_name,
            "rating": rating,
            "role_id": ",".join(str(x) for x in role_ids) if role_ids else None,
            "series_id": series_id,
            "series_name": series_name,
            "series_volume": series_volume,
            "series_year_began": series_year_began,
            "sku": sku,
            "store_date": store_date,
            "store_date_range_after": store_date_range_after,
            "store_date_range_before": store_date_range_before,
            "team_id": team_id,
            "universe_id": universe_id,
            "upc": upc,
        }
    )
    try:
        results = self._fetch_list(endpoint="/issue", params=params)
        return TypeAdapter(list[CommonIssue]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_publisher_series(self, publisher_id: int) -> list[CommonSeries]:
    """Retrieve a list of series that are part of a specific publisher.

    Args:
        publisher_id: The unique identifier of the publisher.

    Returns:
        A list of CommonSeries objects.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        results = self._fetch_list(endpoint=f"/publisher/{publisher_id}/series_list")
        return TypeAdapter(list[CommonSeries]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_publishers(
    self,
    cv_id: int | None = None,
    gcd_id: int | None = None,
    modified_gt: datetime | None = None,
    name: str | None = None,
) -> list[CommonResource]:
    """Retrieve a list of publishers with optional filtering.

    Args:
        cv_id: Filter by Comic Vine ID.
        gcd_id: Filter by Grand Comics Database ID.
        modified_gt: Return publishers modified after this datetime.
        name: Filter publishers by name (partial match).

    Returns:
        A list of CommonResource objects representing publishers.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    params = filter_params(
        data={"cv_id": cv_id, "gcd_id": gcd_id, "modified_gt": modified_gt, "name": name}
    )
    try:
        results = self._fetch_list(endpoint="/publisher", params=params)
        return TypeAdapter(list[CommonResource]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_reading_list_items(self, reading_list_id: int) -> list[ReadingListItem]:
    """Retrieve a list of items that are part of a specific reading list.

    Args:
        reading_list_id: The unique identifier of the reading list.

    Returns:
        A list of ReadingListItem objects.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    try:
        results = self._fetch_list(endpoint=f"/reading_list/{reading_list_id}/items")
        return TypeAdapter(list[ReadingListItem]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_reading_lists(
    self,
    attribution_source: AttributionSource | None = None,
    average_rating_gte: int | None = None,
    is_private: bool | None = None,
    list_type: EventType | None = None,
    modified_gt: datetime | None = None,
    name: str | None = None,
    publisher_name: str | None = None,
    user_id: int | None = None,
    username: str | None = None,
) -> list[BaseReadingList]:
    """Retrieve a list of reading lists with optional filtering.

    Args:
        attribution_source: Filter by the source of attribution.
        average_rating_gte: Filter for reading lists with an average rating greater than or
            equal to this value.
        is_private: Filter by privacy status.
        list_type: Filter by the type of reading list.
        modified_gt: Return reading lists modified after this datetime.
        name: Filter reading lists by name (partial match).
        publisher_name: Filter by the publisher name.
        user_id: Filter by the owner user's ID.
        username: Filter by the owner user's username.

    Returns:
        A list of BaseReadingList objects.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    params = filter_params(
        data={
            "attribution_source": attribution_source,
            "average_rating_gte": average_rating_gte,
            "is_private": is_private,
            "list_type": list_type,
            "modified_gt": modified_gt,
            "name": name,
            "publisher": publisher_name,
            "user": user_id,
            "username": username,
        }
    )
    try:
        results = self._fetch_list(endpoint="/reading_list", params=params)
        return TypeAdapter(list[BaseReadingList]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err

def list_roles(
    self, modified_gt: datetime | None = None, name: str | None = None
) -> list[GenericResource]:
    """Retrieve a list of roles with optional filtering.

    Args:
        modified_gt: Return roles modified after this datetime.
        name: Filter roles by name (partial match).

    Returns:
        A list of GenericResource objects representing roles.

    Raises:
        ServiceError: If the API response is invalid or validation fails.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If the API rate limit is exceeded.
    """
    params = filter_params(data={"modified_gt": modified_gt, "name": name})
    try:
        results = self._fetch_list(endpoint="/role", params=params)
        return TypeAdapter(list[GenericResource]).validate_python(results)
    except ValidationError as err:
        raise ServiceError(err) from err