robin-cloud-client 0.1.0__py3-none-any.whl

robin_cloud_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: robin-cloud-client
+Version: 0.1.0
+Summary: Python client for Robin-Cloud storage and logs (X-Api-Key auth)
+Project-URL: Homepage, https://github.com/robintech-seoul/robin-cloud-client
+Project-URL: Repository, https://github.com/robintech-seoul/robin-cloud-client
+Author: RobinTech
+License: MIT
+Keywords: logs,robin-cloud,s3,sdk,storage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# robin-cloud-client (Python)
+
+Robin-Cloud 스토리지·로그를 API 키로 이용하는 Python SDK.
+
+```bash
+pip install robin-cloud-client
+```
+
+## 사용
+
+```python
+from robincloud import RobinCloud
+
+rc = RobinCloud(api_key="rbk_…", project="raxis")
+# 또는 환경변수: ROBIN_CLOUD_API_KEY, ROBIN_CLOUD_BASE_URL
+
+# 스토리지
+rc.storage.create_bucket("assets")                       # storage:admin 스코프 필요
+rc.storage.upload("assets", "img/logo.png", data)        # presign→PUT→complete 자동
+raw = rc.storage.download("assets", "img/logo.png")      # -> bytes
+listing = rc.storage.list_objects("assets", prefix="img/")
+rc.storage.delete("assets", keys=["img/logo.png"])
+
+# 로그
+for src in rc.logs.sources():
+    print(src.pod, src.containers)
+print(rc.logs.tail(source="web-1", lines=200))
+
+rc.close()   # 또는 with RobinCloud(...) as rc:
+```
+
+## 에러
+
+상태코드가 타입 예외로 매핑된다: `AuthenticationError`(401), `PermissionDeniedError`(403),
+`NotFoundError`(404), `ConflictError`(409), `PayloadTooLargeError`(413), `ValidationError`(422),
+`ServiceUnavailableError`(503), 그 외 `ApiError`. 모두 `RobinCloudError` 하위.
+
+```python
+from robincloud import PermissionDeniedError
+try:
+    rc.storage.create_bucket("x")
+except PermissionDeniedError as e:
+    print(e.status_code, e.message)   # 403 "key is missing required scope 'storage:admin'"
+```
+
+## 범위
+
+- 스토리지(버킷·오브젝트·업로드/다운로드·이동·삭제·public URL) + 로그(소스·tail).
+- 키 발급/폐기는 세션 인증이라 SDK 범위 밖(콘솔 UI).
+- 업로드는 단일 presigned PUT(~5GB 상한). 멀티파트는 백로그.
+
+## 개발
+
+```bash
+cd python
+uv venv && uv pip install -e ".[dev]"
+uv run pytest          # respx 모킹, 실 네트워크 없음
+uv run ruff check .
+```

robin_cloud_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+robincloud/__init__.py,sha256=ctGNDY58Nv_m4UE-2bH9vLMsQmOJ3YquizALj4Krn4k,844
+robincloud/client.py,sha256=J_8LBJNhIEikzngI5DXWMY0YaTYWf80PkqlN_eScXg8,3343
+robincloud/errors.py,sha256=mdu0SRPqHRAUvwnIZaqay5DPz9dMDB63w4OyFPdK2ds,2610
+robincloud/logs.py,sha256=e9kV773O1xrfMo-pO40zy5Qo84J4evKVUpgGMb059RY,1709
+robincloud/models.py,sha256=jgENJ9o8dqkeW4xlHQNZKLoN8Rf70GuDN30MqQBBzTQ,2627
+robincloud/storage.py,sha256=RmaNopAoqJfmY7U1DA0ccGTNfX-6vS4QNHCfwhtEfIA,8378
+robin_cloud_client-0.1.0.dist-info/METADATA,sha256=FdXmBOg7ZkqhcHdb7pWvZwcbD9rWnJ2Aqc67XvbgQnk,2942
+robin_cloud_client-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+robin_cloud_client-0.1.0.dist-info/RECORD,,

robin_cloud_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

robincloud/__init__.py

@@ -0,0 +1,38 @@
+"""robin-cloud-client — Robin-Cloud 스토리지·로그 Python SDK (X-Api-Key 인증)."""
+
+from .client import RobinCloud
+from .errors import (
+    ApiError,
+    AuthenticationError,
+    ConflictError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PermissionDeniedError,
+    RobinCloudError,
+    ServiceUnavailableError,
+    ValidationError,
+)
+from .models import Bucket, Folder, LogSource, ObjectEntry, ObjectListing, UploadResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RobinCloud",
+    # errors
+    "RobinCloudError",
+    "ApiError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "PayloadTooLargeError",
+    "ValidationError",
+    "ServiceUnavailableError",
+    # models
+    "Bucket",
+    "Folder",
+    "ObjectEntry",
+    "ObjectListing",
+    "UploadResult",
+    "LogSource",
+]

robincloud/client.py

@@ -0,0 +1,91 @@
+"""RobinCloud — 진입 클라이언트. api-key 인증 + 프로젝트 기본값 + HTTP 계층."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+import httpx
+
+from .errors import RobinCloudError, error_for_response
+from .logs import LogsClient
+from .storage import StorageClient
+
+DEFAULT_BASE_URL = "https://console.robintech.cloud"
+_API_PREFIX = "/api/v1"
+
+
+class RobinCloud:
+    """Robin-Cloud 스토리지·로그 동기 클라이언트.
+
+    사용:
+        rc = RobinCloud(api_key="rbk_…", project="raxis")
+        rc.storage.upload("assets", "img/logo.png", data)
+        rc.logs.tail(source="web-1")
+
+    Args:
+        api_key: `rbk_…` 형식 API 키. 생략 시 환경변수 `ROBIN_CLOUD_API_KEY`.
+        project: 스토리지·로그 호출의 기본 프로젝트명. 호출별로 override 가능.
+        base_url: 콘솔 호스트. 생략 시 `ROBIN_CLOUD_BASE_URL` 또는
+            `https://console.robintech.cloud`.
+        timeout: 초 단위 요청 타임아웃(기본 30). 대용량 업로드/다운로드는 늘려라.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        project: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        key = api_key or os.environ.get("ROBIN_CLOUD_API_KEY")
+        if not key:
+            raise RobinCloudError(
+                "api_key is required (pass api_key=… or set ROBIN_CLOUD_API_KEY)"
+            )
+        base = (base_url or os.environ.get("ROBIN_CLOUD_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+        self._project = project
+        self._base_url = base
+        self._api_key = key
+        # BFF 호출용 인증 클라이언트. presigned S3 호출은 별도(api-key 미첨부).
+        self._http = httpx.Client(
+            base_url=base + _API_PREFIX,
+            headers={"X-Api-Key": key},
+            timeout=timeout,
+        )
+        self.storage = StorageClient(self)
+        self.logs = LogsClient(self)
+
+    # ── 내부 ───────────────────────────────────────────────────────────
+
+    def _resolve_project(self, project: Optional[str]) -> str:
+        p = project or self._project
+        if not p:
+            raise RobinCloudError(
+                "project is required — pass project=… to the call or set it on the client"
+            )
+        return p
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """BFF 요청(api-key 자동 첨부). 4xx/5xx는 타입 예외로 변환."""
+        resp = self._http.request(method, path, **kwargs)
+        if resp.is_error:
+            try:
+                body: Any = resp.json()
+            except Exception:
+                body = resp.text
+            raise error_for_response(resp.status_code, body)
+        return resp
+
+    # ── 수명주기 ───────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "RobinCloud":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

robincloud/errors.py

@@ -0,0 +1,80 @@
+"""예외 계층 — HTTP 상태코드를 타입 있는 예외로 매핑한다 (docs/api-surface.md 에러 규약).
+
+상태코드가 계약이고 응답 바디 셰이프는 보장 대상이 아니므로(spec §7.3), 메시지는
+`detail`(FastAPI 기본)과 `error.message`(도메인 핸들러) 양쪽에서 관대하게 뽑는다.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class RobinCloudError(Exception):
+    """모든 SDK 예외의 베이스."""
+
+
+class ApiError(RobinCloudError):
+    """HTTP 에러 응답 — status_code와 서버 메시지를 담는다."""
+
+    def __init__(self, status_code: int, message: str, *, body: Any = None) -> None:
+        self.status_code = status_code
+        self.message = message
+        self.body = body
+        super().__init__(f"[{status_code}] {message}")
+
+
+class AuthenticationError(ApiError):
+    """401 — 키가 없거나 무효·폐기·만료."""
+
+
+class PermissionDeniedError(ApiError):
+    """403 — 스코프/프로젝트 바인딩/발급자 레벨 부족."""
+
+
+class NotFoundError(ApiError):
+    """404 — 버킷·오브젝트 없음(존재 은닉 포함)."""
+
+
+class ConflictError(ApiError):
+    """409 — 버킷 이름 중복, 비어있지 않은 버킷 삭제, 이동 대상 충돌 등."""
+
+
+class PayloadTooLargeError(ApiError):
+    """413 — 오브젝트가 max_object_bytes 초과 또는 버킷 쿼터 초과."""
+
+
+class ValidationError(ApiError):
+    """422 — 요청 검증 실패(잘못된 키·버킷명 등)."""
+
+
+class ServiceUnavailableError(ApiError):
+    """503 — 스토리지 기능 휴면(서버에 ROBIN_STORAGE_BUCKET 미설정) 또는 백엔드 일시 불가."""
+
+
+_STATUS_MAP = {
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    413: PayloadTooLargeError,
+    422: ValidationError,
+    503: ServiceUnavailableError,
+}
+
+
+def _extract_message(body: Any, fallback: str) -> str:
+    if isinstance(body, dict):
+        # FastAPI 기본: {"detail": "..."}. 도메인 핸들러: {"error": {"message": "..."}}.
+        detail = body.get("detail")
+        if isinstance(detail, str):
+            return detail
+        err = body.get("error")
+        if isinstance(err, dict) and isinstance(err.get("message"), str):
+            return err["message"]
+    return fallback
+
+
+def error_for_response(status_code: int, body: Any, fallback: Optional[str] = None) -> ApiError:
+    message = _extract_message(body, fallback or f"HTTP {status_code}")
+    cls = _STATUS_MAP.get(status_code, ApiError)
+    return cls(status_code, message, body=body)

robincloud/logs.py

@@ -0,0 +1,50 @@
+"""로그 네임스페이스 — `rc.logs.*`. 컴포넌트 파드의 최근 로그 tail 조회.
+
+서버는 serve의 `{status, data}` 봉투를 전달한다. SDK는 `data` 안쪽을 꺼내 준다.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Optional
+
+from .models import LogSource
+
+if TYPE_CHECKING:
+    from .client import RobinCloud
+
+_MAX_TAIL = 5000
+
+
+class LogsClient:
+    def __init__(self, rc: "RobinCloud") -> None:
+        self._rc = rc
+
+    def _base(self, project: Optional[str]) -> str:
+        return f"/projects/{self._rc._resolve_project(project)}"
+
+    def sources(self, *, project: Optional[str] = None) -> List[LogSource]:
+        """로그를 볼 수 있는 소스(파드+컨테이너) 목록."""
+        resp = self._rc._request("GET", f"{self._base(project)}/log-sources")
+        data = resp.json().get("data", {})
+        return [LogSource.from_api(s) for s in data.get("sources", [])]
+
+    def tail(
+        self,
+        source: str,
+        *,
+        container: Optional[str] = None,
+        lines: int = 1000,
+        project: Optional[str] = None,
+    ) -> str:
+        """선택한 파드/컨테이너의 최근 로그 tail 문자열.
+
+        Args:
+            source: 파드 이름(`sources()`의 `pod`).
+            container: 멀티컨테이너 파드에서 지정(생략 시 첫 컨테이너).
+            lines: 최근 N줄(서버 상한 5000).
+        """
+        params = {"source": source, "tail": min(lines, _MAX_TAIL)}
+        if container:
+            params["container"] = container
+        resp = self._rc._request("GET", f"{self._base(project)}/logs", params=params)
+        return resp.json().get("data", {}).get("content", "")

robincloud/models.py

@@ -0,0 +1,105 @@
+"""응답 데이터 모델 — 서버 JSON을 감싸는 얇은 dataclass.
+
+미지 필드는 무시(관대한 파싱)해 서버가 필드를 추가해도 SDK가 깨지지 않는다.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Bucket:
+    name: str
+    public: bool
+    used_bytes: int
+    quota_bytes: Optional[int]
+    object_count: int
+    created_at: Optional[str]
+
+    @classmethod
+    def from_api(cls, d: Dict[str, Any]) -> "Bucket":
+        return cls(
+            name=d["name"],
+            public=bool(d.get("public", False)),
+            used_bytes=int(d.get("used_bytes", 0) or 0),
+            quota_bytes=d.get("quota_bytes"),
+            object_count=int(d.get("object_count", 0) or 0),
+            created_at=d.get("created_at"),
+        )
+
+
+@dataclass
+class ObjectEntry:
+    name: str
+    key: Optional[str] = None
+    size_bytes: Optional[int] = None
+    content_type: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @classmethod
+    def from_api(cls, d: Dict[str, Any]) -> "ObjectEntry":
+        return cls(
+            name=d.get("name") or d.get("key", ""),
+            key=d.get("key"),
+            size_bytes=d.get("size_bytes"),
+            content_type=d.get("content_type"),
+            updated_at=d.get("updated_at"),
+        )
+
+
+@dataclass
+class Folder:
+    name: str
+
+    @classmethod
+    def from_api(cls, d: Dict[str, Any]) -> "Folder":
+        return cls(name=d["name"])
+
+
+@dataclass
+class ObjectListing:
+    objects: List[ObjectEntry]
+    folders: List[Folder]
+    next_cursor: Optional[str]
+
+    @classmethod
+    def from_api(cls, d: Dict[str, Any]) -> "ObjectListing":
+        return cls(
+            objects=[ObjectEntry.from_api(o) for o in d.get("objects", [])],
+            folders=[Folder.from_api(f) for f in d.get("folders", [])],
+            next_cursor=d.get("next_cursor"),
+        )
+
+
+@dataclass
+class UploadResult:
+    key: str
+    size_bytes: int
+    etag: Optional[str]
+    status: str
+
+    @classmethod
+    def from_api(cls, d: Dict[str, Any]) -> "UploadResult":
+        return cls(
+            key=d["key"],
+            size_bytes=int(d.get("size_bytes", 0) or 0),
+            etag=d.get("etag"),
+            status=d.get("status", "READY"),
+        )
+
+
+@dataclass
+class LogSource:
+    pod: str
+    status: Optional[str]
+    containers: List[str]
+
+    @classmethod
+    def from_api(cls, d: Dict[str, Any]) -> "LogSource":
+        return cls(
+            pod=d["pod"],
+            status=d.get("status"),
+            containers=list(d.get("containers", [])),
+        )

robincloud/storage.py

@@ -0,0 +1,221 @@
+"""스토리지 네임스페이스 — `rc.storage.*`.
+
+핵심은 업로드 3콜(presign → S3 PUT → complete)과 다운로드 2콜(presign → S3 GET)을
+`upload()`/`download()` 한 줄로 감추는 것. 바이트는 BFF를 거치지 않고 presigned URL로
+S3에 직행하며, 그 요청에는 api-key를 붙이지 않는다.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+from typing import TYPE_CHECKING, List, Optional
+from urllib.parse import quote
+
+import httpx
+
+from .models import Bucket, ObjectListing, UploadResult
+
+if TYPE_CHECKING:
+    from .client import RobinCloud
+
+_DEFAULT_CONTENT_TYPE = "application/octet-stream"
+
+
+class StorageClient:
+    def __init__(self, rc: "RobinCloud") -> None:
+        self._rc = rc
+
+    def _base(self, project: Optional[str]) -> str:
+        return f"/projects/{self._rc._resolve_project(project)}/storage"
+
+    # ── 버킷 ───────────────────────────────────────────────────────────
+
+    def list_buckets(self, *, project: Optional[str] = None) -> List[Bucket]:
+        resp = self._rc._request("GET", f"{self._base(project)}/buckets")
+        return [Bucket.from_api(b) for b in resp.json()]
+
+    def create_bucket(
+        self,
+        name: str,
+        *,
+        public: bool = False,
+        quota_bytes: Optional[int] = None,
+        project: Optional[str] = None,
+    ) -> Bucket:
+        body = {"name": name, "public": public}
+        if quota_bytes is not None:
+            body["quota_bytes"] = quota_bytes
+        resp = self._rc._request("POST", f"{self._base(project)}/buckets", json=body)
+        return Bucket.from_api(resp.json())
+
+    def update_bucket(
+        self,
+        name: str,
+        *,
+        public: Optional[bool] = None,
+        quota_bytes: Optional[int] = None,
+        max_object_bytes: Optional[int] = None,
+        project: Optional[str] = None,
+    ) -> Bucket:
+        body = {
+            k: v
+            for k, v in {
+                "public": public,
+                "quota_bytes": quota_bytes,
+                "max_object_bytes": max_object_bytes,
+            }.items()
+            if v is not None
+        }
+        resp = self._rc._request("PATCH", f"{self._base(project)}/buckets/{name}", json=body)
+        return Bucket.from_api(resp.json())
+
+    def delete_bucket(
+        self, name: str, *, force: bool = False, project: Optional[str] = None
+    ) -> None:
+        # confirm은 서버가 요구하는 안전장치 — 버킷명 정확히 타이핑. SDK가 채워준다.
+        params = {"confirm": name, "force": str(force).lower()}
+        self._rc._request("DELETE", f"{self._base(project)}/buckets/{name}", params=params)
+
+    # ── 목록 ───────────────────────────────────────────────────────────
+
+    def list_objects(
+        self,
+        bucket: str,
+        *,
+        prefix: str = "",
+        limit: int = 100,
+        cursor: Optional[str] = None,
+        search: Optional[str] = None,
+        project: Optional[str] = None,
+    ) -> ObjectListing:
+        params = {"prefix": prefix, "limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+        if search:
+            params["search"] = search
+        resp = self._rc._request(
+            "GET", f"{self._base(project)}/buckets/{bucket}/objects", params=params
+        )
+        return ObjectListing.from_api(resp.json())
+
+    # ── 업로드 / 다운로드 (멀티콜 래핑) ───────────────────────────────
+
+    def upload(
+        self,
+        bucket: str,
+        key: str,
+        data: bytes,
+        *,
+        content_type: Optional[str] = None,
+        project: Optional[str] = None,
+    ) -> UploadResult:
+        """오브젝트 업로드 — presign → S3 PUT → complete 3콜을 한 번에.
+
+        Args:
+            data: 업로드할 바이트.
+            content_type: 생략 시 key 확장자로 추정, 실패하면 octet-stream.
+        """
+        base = self._base(project)
+        ctype = content_type or mimetypes.guess_type(key)[0] or _DEFAULT_CONTENT_TYPE
+
+        # 1) presign
+        presign = self._rc._request(
+            "POST",
+            f"{base}/buckets/{bucket}/presign-upload",
+            json={"key": key, "content_type": ctype, "size_bytes": len(data)},
+        ).json()
+
+        # 2) S3 직행 PUT (api-key 미첨부 — presigned URL 자체가 자격증명)
+        put = httpx.request(
+            presign.get("method", "PUT"),
+            presign["url"],
+            content=data,
+            headers=presign.get("headers") or {},
+            timeout=self._rc._http.timeout,
+        )
+        put.raise_for_status()
+
+        # 3) complete (S3 HEAD 실측 검증 → READY)
+        done = self._rc._request(
+            "POST",
+            f"{base}/buckets/{bucket}/complete",
+            json={"object_id": presign["object_id"]},
+        ).json()
+        return UploadResult.from_api(done)
+
+    def download(self, bucket: str, key: str, *, project: Optional[str] = None) -> bytes:
+        """오브젝트 다운로드 — presign → S3 GET. 바이트 반환."""
+        presign = self._rc._request(
+            "POST",
+            f"{self._base(project)}/buckets/{bucket}/presign-download",
+            json={"key": key},
+        ).json()
+        got = httpx.get(presign["url"], timeout=self._rc._http.timeout, follow_redirects=True)
+        got.raise_for_status()
+        return got.content
+
+    # ── 폴더 / 이동 / 삭제 ─────────────────────────────────────────────
+
+    def create_folder(self, bucket: str, key: str, *, project: Optional[str] = None) -> None:
+        folder_key = key if key.endswith("/") else key + "/"
+        self._rc._request(
+            "POST", f"{self._base(project)}/buckets/{bucket}/folders", json={"key": folder_key}
+        )
+
+    def move(
+        self,
+        bucket: str,
+        *,
+        from_key: Optional[str] = None,
+        to_key: Optional[str] = None,
+        from_prefix: Optional[str] = None,
+        to_prefix: Optional[str] = None,
+        project: Optional[str] = None,
+    ) -> int:
+        """오브젝트/폴더 이동·이름변경. `from_key/to_key`(단건) 또는 `from_prefix/to_prefix`(폴더).
+
+        Returns: 이동된 오브젝트 수.
+        """
+        body = {
+            k: v
+            for k, v in {
+                "from_key": from_key,
+                "to_key": to_key,
+                "from_prefix": from_prefix,
+                "to_prefix": to_prefix,
+            }.items()
+            if v is not None
+        }
+        resp = self._rc._request("POST", f"{self._base(project)}/buckets/{bucket}/move", json=body)
+        return int(resp.json().get("moved_count", 0))
+
+    def delete(
+        self,
+        bucket: str,
+        *,
+        keys: Optional[List[str]] = None,
+        prefix: Optional[str] = None,
+        project: Optional[str] = None,
+    ) -> int:
+        """오브젝트 삭제 — 키 목록(`keys`) 또는 접두사(`prefix`). Returns: 삭제 수."""
+        body = {}
+        if keys is not None:
+            body["keys"] = keys
+        if prefix is not None:
+            body["prefix"] = prefix
+        resp = self._rc._request(
+            "DELETE", f"{self._base(project)}/buckets/{bucket}/objects", json=body
+        )
+        return int(resp.json().get("deleted_count", 0))
+
+    # ── public URL ─────────────────────────────────────────────────────
+
+    def public_url(self, bucket: str, key: str, *, project: Optional[str] = None) -> str:
+        """public 버킷 오브젝트의 무인증 공개 URL(302 presigned로 리다이렉트)을 만든다.
+
+        네트워크 호출 없음 — URL 문자열만 조립한다. 실제 접근 가능 여부(버킷이 public
+        인지)는 이 URL을 GET할 때 서버가 판정한다.
+        """
+        proj = self._rc._resolve_project(project)
+        enc_key = quote(key)
+        return f"{self._rc._base_url}/api/v1/storage/public/{proj}/{bucket}/{enc_key}"