"""PaginatedResponse - a list subclass that carries API pagination metadata."""

from typing import Any


class PaginatedResponse(list):
    """A list that also carries pagination metadata from the API response.

    Backward-compatible: works exactly like a list, but also exposes
    a `.meta` attribute with the full `meta` object from the API envelope.

    Example:
        result = client.v1.image_sets.list(page=1)
        for image_set in result:
            print(image_set["name"])

        total = result.meta["pagination"]["total"]
        print(f"Total: {total}")
    """

    def __init__(self, items: list, *, meta: dict[str, Any] | None = None):
        super().__init__(items)
        self.meta: dict[str, Any] = meta or {}
