from typing import Any


class S3Client:
    """Thin typed wrapper around a boto3 S3 client bound to a single bucket.

    The class is deliberately small: it exposes only the byte-level
    operations needed by the wider infrastructure layer. Serialisation
    (CSV, JSON, etc.) lives in subclasses such as :class:`CsvS3Client`.
    """

    def __init__(self, boto_s3_client: Any, bucket: str) -> None:
        self._client = boto_s3_client
        self._bucket = bucket

    @property
    def bucket(self) -> str:
        return self._bucket

    def get_object(self, key: str) -> bytes:
        """Return the raw bytes stored at ``key`` in this client's bucket."""
        response: dict[str, Any] = self._client.get_object(
            Bucket=self._bucket, Key=key
        )
        body: bytes = response["Body"].read()
        return body

    def put_object(self, key: str, body: bytes) -> str:
        """Write ``body`` to ``key`` and return the canonical ``s3://`` URI."""
        self._client.put_object(Bucket=self._bucket, Key=key, Body=body)
        return f"s3://{self._bucket}/{key}"