"""Lightweight dataclasses shared across the storage_core package."""

from dataclasses import dataclass, field
from datetime import datetime
from typing import Any


@dataclass
class StorageObject:
    """Represents an object stored in a bucket.

    Attributes:
        key: Object key (path) within the bucket.
        data: Raw bytes content.  May be ``None`` for head/listing responses.
        metadata: Optional user-supplied metadata dict (deserialized).
        content_type: MIME type (e.g. ``"application/json"``).
        size: Object size in bytes.
        last_modified: Timestamp of last modification.
        etag: Entity tag (content hash) from the backend.
    """

    key: str
    data: bytes | None = None
    metadata: dict[str, Any] | None = None
    content_type: str | None = None
    size: int | None = None
    last_modified: datetime | None = None
    etag: str | None = None


@dataclass
class ObjectListing:
    """Result of a list-objects operation.

    Attributes:
        prefix: The prefix used for the listing.
        objects: List of :class:`StorageObject` entries (``data`` is always ``None``).
        is_truncated: ``True`` if there are more results beyond this page.
        next_token: Pagination token for the next page, if any.
    """

    prefix: str
    objects: list[StorageObject] = field(default_factory=list)
    is_truncated: bool = False
    next_token: str | None = None
