robot-wrapper-sdk 0.2.6__tar.gz → 0.2.8__tar.gz

{robot_wrapper_sdk-0.2.6 → robot_wrapper_sdk-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robot-wrapper-sdk
-Version: 0.2.6
+Version: 0.2.8
 Summary: Robot Platform API SDK
 Author-email: GH Robot Platform Team <team@ghrobot.com>
 License: MIT
@@ -38,7 +38,7 @@ Or pass values directly when creating the module.
 ## Quick Start (Sync)
 
 ```python
-from robot_sdk import RobotPlatformModule
+from robot_sdk import RobotPlatformModule, RobotStatus, RobotAuthStatus
 
 sdk = RobotPlatformModule(
     base_url="http://localhost:8085",
@@ -51,14 +51,14 @@ sdk = RobotPlatformModule(
 robot = sdk.get_robot("2047631542552334336")
 print(robot.platform if robot else "not found")
 
-# Update lifecycle status
-sdk.update_status("2047631542552334336", "live")
+# Update lifecycle status (prefer enum)
+sdk.update_status("2047631542552334336", RobotStatus.LIVE)
 
 # Acquire login tasks
 login_tasks = sdk.acquire_need_login(limit=20, lock_minutes=30)
 
-# Update auth status after worker result
-sdk.update_auth_status("2047631542552334336", "authorized")
+# Update auth status after worker result (prefer enum)
+sdk.update_auth_status("2047631542552334336", RobotAuthStatus.AUTHORIZED)
 # allowed values: authorized | unauthorized | logged_out
 
 # Acquire hardening tasks
@@ -67,6 +67,12 @@ hardening_tasks = sdk.acquire_unhardened(limit=20, lock_minutes=30, min_age_days
 # Update hardening status after worker result
 sdk.update_security_hardened("2047631542552334336", True)
 
+# Update metadata (partial patch)
+sdk.update_metadata("2047631542552334336", {
+    "country_code": "VN",
+    "note": "updated by sdk"
+})
+
 sdk.close()
 ```
 
@@ -74,7 +80,7 @@ sdk.close()
 
 ```python
 import asyncio
-from robot_sdk import AsyncRobotPlatformModule
+from robot_sdk import AsyncRobotPlatformModule, RobotAuthStatus
 
 async def main():
     sdk = AsyncRobotPlatformModule(
@@ -86,8 +92,12 @@ async def main():
     robot = await sdk.get_robot("2047631542552334336")
     print(robot.platform if robot else "not found")
 
-    await sdk.update_auth_status("2047631542552334336", "authorized")
+    await sdk.update_auth_status("2047631542552334336", RobotAuthStatus.AUTHORIZED)
     await sdk.update_security_hardened("2047631542552334336", True)
+    await sdk.update_metadata("2047631542552334336", {
+        "country_code": "VN",
+        "note": "updated by async sdk"
+    })
 
     await sdk.close()
 
@@ -145,6 +155,7 @@ Update endpoints return:
 - `acquire_unhardened(limit=20, lock_minutes=30, min_age_days=0)`
 - `update_auth_status(robot_id, auth_status)`
 - `update_security_hardened(robot_id, security_hardened)`
+- `update_metadata(robot_id, metadata)`
 - `close()`
 
 ### `AsyncRobotPlatformModule` (async)

{robot_wrapper_sdk-0.2.6 → robot_wrapper_sdk-0.2.8}/README.md

@@ -28,7 +28,7 @@ Or pass values directly when creating the module.
 ## Quick Start (Sync)
 
 ```python
-from robot_sdk import RobotPlatformModule
+from robot_sdk import RobotPlatformModule, RobotStatus, RobotAuthStatus
 
 sdk = RobotPlatformModule(
     base_url="http://localhost:8085",
@@ -41,14 +41,14 @@ sdk = RobotPlatformModule(
 robot = sdk.get_robot("2047631542552334336")
 print(robot.platform if robot else "not found")
 
-# Update lifecycle status
-sdk.update_status("2047631542552334336", "live")
+# Update lifecycle status (prefer enum)
+sdk.update_status("2047631542552334336", RobotStatus.LIVE)
 
 # Acquire login tasks
 login_tasks = sdk.acquire_need_login(limit=20, lock_minutes=30)
 
-# Update auth status after worker result
-sdk.update_auth_status("2047631542552334336", "authorized")
+# Update auth status after worker result (prefer enum)
+sdk.update_auth_status("2047631542552334336", RobotAuthStatus.AUTHORIZED)
 # allowed values: authorized | unauthorized | logged_out
 
 # Acquire hardening tasks
@@ -57,6 +57,12 @@ hardening_tasks = sdk.acquire_unhardened(limit=20, lock_minutes=30, min_age_days
 # Update hardening status after worker result
 sdk.update_security_hardened("2047631542552334336", True)
 
+# Update metadata (partial patch)
+sdk.update_metadata("2047631542552334336", {
+    "country_code": "VN",
+    "note": "updated by sdk"
+})
+
 sdk.close()
 ```
 
@@ -64,7 +70,7 @@ sdk.close()
 
 ```python
 import asyncio
-from robot_sdk import AsyncRobotPlatformModule
+from robot_sdk import AsyncRobotPlatformModule, RobotAuthStatus
 
 async def main():
     sdk = AsyncRobotPlatformModule(
@@ -76,8 +82,12 @@ async def main():
     robot = await sdk.get_robot("2047631542552334336")
     print(robot.platform if robot else "not found")
 
-    await sdk.update_auth_status("2047631542552334336", "authorized")
+    await sdk.update_auth_status("2047631542552334336", RobotAuthStatus.AUTHORIZED)
     await sdk.update_security_hardened("2047631542552334336", True)
+    await sdk.update_metadata("2047631542552334336", {
+        "country_code": "VN",
+        "note": "updated by async sdk"
+    })
 
     await sdk.close()
 
@@ -135,6 +145,7 @@ Update endpoints return:
 - `acquire_unhardened(limit=20, lock_minutes=30, min_age_days=0)`
 - `update_auth_status(robot_id, auth_status)`
 - `update_security_hardened(robot_id, security_hardened)`
+- `update_metadata(robot_id, metadata)`
 - `close()`
 
 ### `AsyncRobotPlatformModule` (async)

{robot_wrapper_sdk-0.2.6 → robot_wrapper_sdk-0.2.8}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "robot-wrapper-sdk"
-version = "0.2.6"
+version = "0.2.8"
 description = "Robot Platform API SDK"
 readme = "README.md"
 requires-python = ">=3.10"

{robot_wrapper_sdk-0.2.6 → robot_wrapper_sdk-0.2.8}/robot_sdk/__init__.py

@@ -2,7 +2,7 @@ from typing import Optional, List, Dict, Any, Tuple
 from .infrastructure.api_client import HTTPClient, AsyncHTTPClient
 from .infrastructure.robot_api_repository import RobotAPIRepository, AsyncRobotAPIRepository
 from .application.usecases import RobotUsecase, AsyncRobotUsecase
-from .domain.entities import Robot, RobotSecrets
+from .domain.entities import Robot, RobotSecrets, RobotStatus, RobotAuthStatus
 
 __version__ = "0.2.1"
 
@@ -28,7 +28,7 @@ class RobotPlatformModule:
     def get_secrets(self, robot_id: str) -> Optional[RobotSecrets]:
         return self.robot_usecase.get_secrets(robot_id)
 
-    def update_status(self, robot_id: str, status: str) -> None:
+    def update_status(self, robot_id: str, status: str | RobotStatus) -> None:
         self.robot_usecase.update_status(robot_id, status)
 
     def acquire_need_login(self, limit: int = 20, lock_minutes: int = 30):
@@ -37,12 +37,15 @@ class RobotPlatformModule:
     def acquire_unhardened(self, limit: int = 20, lock_minutes: int = 30, min_age_days: int = 0):
         return self.robot_usecase.acquire_unhardened(limit, lock_minutes, min_age_days)
 
-    def update_auth_status(self, robot_id: str, auth_status: str) -> None:
+    def update_auth_status(self, robot_id: str, auth_status: str | RobotAuthStatus) -> None:
         self.robot_usecase.update_auth_status(robot_id, auth_status)
 
     def update_security_hardened(self, robot_id: str, security_hardened: bool) -> None:
         self.robot_usecase.update_security_hardened(robot_id, security_hardened)
 
+    def update_metadata(self, robot_id: str, metadata: Dict[str, Any]) -> None:
+        self.robot_usecase.update_metadata(robot_id, metadata)
+
 
 class AsyncRobotPlatformModule:
     """Asynchronous Facade for the Robot Platform SDK."""
@@ -66,7 +69,7 @@ class AsyncRobotPlatformModule:
     async def get_secrets(self, robot_id: str) -> Optional[RobotSecrets]:
         return await self.robot_usecase.get_secrets(robot_id)
 
-    async def update_status(self, robot_id: str, status: str) -> None:
+    async def update_status(self, robot_id: str, status: str | RobotStatus) -> None:
         await self.robot_usecase.update_status(robot_id, status)
 
     async def acquire_need_login(self, limit: int = 20, lock_minutes: int = 30):
@@ -75,10 +78,20 @@ class AsyncRobotPlatformModule:
     async def acquire_unhardened(self, limit: int = 20, lock_minutes: int = 30, min_age_days: int = 0):
         return await self.robot_usecase.acquire_unhardened(limit, lock_minutes, min_age_days)
 
-    async def update_auth_status(self, robot_id: str, auth_status: str) -> None:
+    async def update_auth_status(self, robot_id: str, auth_status: str | RobotAuthStatus) -> None:
         await self.robot_usecase.update_auth_status(robot_id, auth_status)
 
     async def update_security_hardened(self, robot_id: str, security_hardened: bool) -> None:
         await self.robot_usecase.update_security_hardened(robot_id, security_hardened)
 
-__all__ = ["RobotPlatformModule", "AsyncRobotPlatformModule", "Robot", "RobotSecrets"]
+    async def update_metadata(self, robot_id: str, metadata: Dict[str, Any]) -> None:
+        await self.robot_usecase.update_metadata(robot_id, metadata)
+
+__all__ = [
+    "RobotPlatformModule",
+    "AsyncRobotPlatformModule",
+    "Robot",
+    "RobotSecrets",
+    "RobotStatus",
+    "RobotAuthStatus",
+]

{robot_wrapper_sdk-0.2.6 → robot_wrapper_sdk-0.2.8}/robot_sdk/application/usecases.py

@@ -1,6 +1,6 @@
 from typing import Optional, List, Tuple, Any, Dict
 from ..domain.repositories import RobotRepository, AsyncRobotRepository
-from ..domain.entities import Robot, RobotSecrets
+from ..domain.entities import Robot, RobotSecrets, RobotStatus, RobotAuthStatus
 
 class RobotUsecase:
     def __init__(self, repo: RobotRepository):
@@ -15,7 +15,7 @@ class RobotUsecase:
     def get_secrets(self, robot_id: str) -> Optional[RobotSecrets]:
         return self.repo.get_secrets(robot_id)
 
-    def update_status(self, robot_id: str, status: str) -> None:
+    def update_status(self, robot_id: str, status: str | RobotStatus) -> None:
         self.repo.update_status(robot_id, status)
 
     def list_robots(self, platform: Optional[str] = None, status: Optional[str] = None, project_id: Optional[int] = None, page: int = 1, limit: int = 20) -> Dict[str, Any]:
@@ -33,12 +33,15 @@ class RobotUsecase:
     def acquire_unhardened(self, limit: int = 20, lock_minutes: int = 30, min_age_days: int = 0) -> List[Robot]:
         return self.repo.acquire_unhardened(limit, lock_minutes, min_age_days)
 
-    def update_auth_status(self, robot_id: str, auth_status: str) -> None:
+    def update_auth_status(self, robot_id: str, auth_status: str | RobotAuthStatus) -> None:
         self.repo.update_auth_status(robot_id, auth_status)
 
     def update_security_hardened(self, robot_id: str, security_hardened: bool) -> None:
         self.repo.update_security_hardened(robot_id, security_hardened)
 
+    def update_metadata(self, robot_id: str, metadata: Dict[str, Any]) -> None:
+        self.repo.update_metadata(robot_id, metadata)
+
 
 class AsyncRobotUsecase:
     def __init__(self, repo: AsyncRobotRepository):
@@ -53,7 +56,7 @@ class AsyncRobotUsecase:
     async def get_secrets(self, robot_id: str) -> Optional[RobotSecrets]:
         return await self.repo.get_secrets(robot_id)
 
-    async def update_status(self, robot_id: str, status: str) -> None:
+    async def update_status(self, robot_id: str, status: str | RobotStatus) -> None:
         await self.repo.update_status(robot_id, status)
 
     async def list_robots(self, platform: Optional[str] = None, status: Optional[str] = None, project_id: Optional[int] = None, page: int = 1, limit: int = 20) -> Dict[str, Any]:
@@ -71,8 +74,11 @@ class AsyncRobotUsecase:
     async def acquire_unhardened(self, limit: int = 20, lock_minutes: int = 30, min_age_days: int = 0) -> List[Robot]:
         return await self.repo.acquire_unhardened(limit, lock_minutes, min_age_days)
 
-    async def update_auth_status(self, robot_id: str, auth_status: str) -> None:
+    async def update_auth_status(self, robot_id: str, auth_status: str | RobotAuthStatus) -> None:
         await self.repo.update_auth_status(robot_id, auth_status)
 
     async def update_security_hardened(self, robot_id: str, security_hardened: bool) -> None:
         await self.repo.update_security_hardened(robot_id, security_hardened)
+
+    async def update_metadata(self, robot_id: str, metadata: Dict[str, Any]) -> None:
+        await self.repo.update_metadata(robot_id, metadata)

robot_wrapper_sdk-0.2.8/robot_sdk/domain/entities.py

@@ -0,0 +1,118 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional, Any, Dict
+
+
+class RobotStatus(str, Enum):
+    LIVE = "live"
+    DEAD = "dead"
+    RUNNING = "running"
+    CHECKPOINT = "checkpoint"
+
+
+class RobotAuthStatus(str, Enum):
+    AUTHORIZED = "authorized"
+    UNAUTHORIZED = "unauthorized"
+    LOGGED_OUT = "logged_out"
+    LOGIN_ERROR = "login_error"
+
+
+def normalize_robot_status(status: str | RobotStatus) -> str:
+    if isinstance(status, RobotStatus):
+        return status.value
+    return str(status).strip().lower()
+
+
+def normalize_robot_auth_status(status: str | RobotAuthStatus) -> str:
+    if isinstance(status, RobotAuthStatus):
+        return status.value
+    return str(status).strip().lower()
+
+
+def ensure_valid_robot_status(status: str) -> None:
+    allowed = {s.value for s in RobotStatus}
+    if status not in allowed:
+        raise ValueError(f"invalid status: {status}. allowed={sorted(allowed)}")
+
+
+def ensure_valid_robot_auth_status(status: str) -> None:
+    allowed = {s.value for s in RobotAuthStatus}
+    if status not in allowed:
+        raise ValueError(f"invalid auth_status: {status}. allowed={sorted(allowed)}")
+
+
+def ensure_valid_worker_robot_auth_status(status: str) -> None:
+    ensure_valid_robot_auth_status(status)
+    if status == RobotAuthStatus.LOGIN_ERROR.value:
+        raise ValueError("auth_status login_error is not allowed for this endpoint")
+
+
+def ensure_valid_worker_robot_status(status: str) -> None:
+    ensure_valid_robot_status(status)
+    if status == RobotStatus.CHECKPOINT.value:
+        raise ValueError("status checkpoint is not allowed for this endpoint")
+
+
+def ensure_valid_metadata(metadata: Dict[str, Any]) -> None:
+    if not isinstance(metadata, dict):
+        raise ValueError("metadata must be a dict")
+
+    for key in metadata.keys():
+        if not isinstance(key, str):
+            raise ValueError("metadata keys must be strings")
+
+    try:
+        import json
+        json.dumps(metadata)
+    except Exception as e:
+        raise ValueError(f"metadata must be JSON-serializable: {e}") from e
+
+
+@dataclass
+class Robot:
+    id: str
+    username: str
+    platform: str
+    status: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    project_id: Optional[str] = None
+    primary_environment: Optional[str] = None
+    created_at: Optional[str] = None
+
+@dataclass
+class RobotSecrets:
+    password: str
+    two_fa_secret: str
+
+@dataclass
+class RobotActivity:
+    id: str
+    activity_type: str
+    status: str
+    message: str
+
+@dataclass
+class AcquireNeedLoginRequest:
+    limit: int = 20
+    lock_minutes: int = 30
+
+@dataclass
+class AcquireUnhardenedRequest:
+    limit: int = 20
+    lock_minutes: int = 30
+    min_age_days: int = 0
+
+@dataclass
+class UpdateAuthStatusRequest:
+    auth_status: str
+
+@dataclass
+class UpdateSecurityHardenedRequest:
+    security_hardened: bool
+
+@dataclass
+class StandardResponse:
+    status: str
+    code: int
+    message: str
+    data: Any = None

{robot_wrapper_sdk-0.2.6 → robot_wrapper_sdk-0.2.8}/robot_sdk/domain/repositories.py

@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 from typing import Optional, List, Tuple
-from .entities import Robot, RobotSecrets
+from .entities import Robot, RobotSecrets, RobotStatus, RobotAuthStatus
 
 class RobotRepository(ABC):
     @abstractmethod
@@ -8,7 +8,7 @@ class RobotRepository(ABC):
         pass
 
     @abstractmethod
-    def update_status(self, robot_id: str, status: str) -> None:
+    def update_status(self, robot_id: str, status: str | RobotStatus) -> None:
         pass
 
     @abstractmethod
@@ -32,20 +32,24 @@ class RobotRepository(ABC):
         pass
 
     @abstractmethod
-    def update_auth_status(self, robot_id: str, auth_status: str) -> None:
+    def update_auth_status(self, robot_id: str, auth_status: str | RobotAuthStatus) -> None:
         pass
 
     @abstractmethod
     def update_security_hardened(self, robot_id: str, security_hardened: bool) -> None:
         pass
 
+    @abstractmethod
+    def update_metadata(self, robot_id: str, metadata: dict) -> None:
+        pass
+
 class AsyncRobotRepository(ABC):
     @abstractmethod
     async def find_by_id(self, robot_id: str) -> Optional[Robot]:
         pass
 
     @abstractmethod
-    async def update_status(self, robot_id: str, status: str) -> None:
+    async def update_status(self, robot_id: str, status: str | RobotStatus) -> None:
         pass
 
     @abstractmethod
@@ -69,9 +73,13 @@ class AsyncRobotRepository(ABC):
         pass
 
     @abstractmethod
-    async def update_auth_status(self, robot_id: str, auth_status: str) -> None:
+    async def update_auth_status(self, robot_id: str, auth_status: str | RobotAuthStatus) -> None:
         pass
 
     @abstractmethod
     async def update_security_hardened(self, robot_id: str, security_hardened: bool) -> None:
         pass
+
+    @abstractmethod
+    async def update_metadata(self, robot_id: str, metadata: dict) -> None:
+        pass

{robot_wrapper_sdk-0.2.6 → robot_wrapper_sdk-0.2.8}/robot_sdk/infrastructure/api_client.py

@@ -1,6 +1,7 @@
 import httpx
 import os
 from typing import Dict, Any, Optional
+from httpx import RemoteProtocolError
 
 def _extract_tokens(payload: Dict[str, Any]) -> tuple[Optional[str], Optional[str]]:
     data = payload.get("data") if isinstance(payload, dict) else None
@@ -132,7 +133,30 @@ class HTTPClient:
             full_path = f"/api/v1/developer{path}"
 
         print(f"🚀 Requesting: {self.base_url}{full_path}")
-        resp = self.client.request(method, full_path, **kwargs)
+        last_err: Optional[Exception] = None
+        resp = None
+        for attempt in range(2):
+            try:
+                resp = self.client.request(method, full_path, **kwargs)
+                break
+            except Exception as err:
+                msg = str(err)
+                is_disconnect = isinstance(err, RemoteProtocolError) or "Server disconnected without sending a response" in msg
+                if not is_disconnect or attempt == 1:
+                    raise
+                last_err = err
+                self.client.close()
+                self.client = httpx.Client(
+                    base_url=self.base_url,
+                    auth=RobotAuth(self._get_or_login, self._refresh),
+                    proxy=self.proxy_url,
+                )
+
+        if resp is None:
+            if last_err is not None:
+                raise last_err
+            raise RuntimeError("Request failed without response")
+
         resp.raise_for_status()
         try:
             return dict(resp.json())

{robot_wrapper_sdk-0.2.6 → robot_wrapper_sdk-0.2.8}/robot_sdk/infrastructure/robot_api_repository.py

@@ -1,7 +1,43 @@
 from typing import Optional, List, Tuple, Dict, Any
 from .api_client import HTTPClient, AsyncHTTPClient
 from ..domain.repositories import RobotRepository, AsyncRobotRepository
-from ..domain.entities import Robot, RobotSecrets
+from ..domain.entities import (
+    Robot,
+    RobotSecrets,
+    RobotStatus,
+    RobotAuthStatus,
+    normalize_robot_status,
+    normalize_robot_auth_status,
+    ensure_valid_worker_robot_status,
+    ensure_valid_worker_robot_auth_status,
+)
+
+
+def _extract_list_payload(resp: Dict[str, Any]) -> Tuple[List[Dict[str, Any]], int]:
+    container = resp.get("data") if isinstance(resp, dict) else None
+    if isinstance(container, dict):
+        items = container.get("data")
+        total = container.get("total", 0)
+    else:
+        items = container
+        total = resp.get("total", 0) if isinstance(resp, dict) else 0
+
+    if not isinstance(items, list):
+        return [], int(total) if isinstance(total, int) else 0
+
+    mapped = [item for item in items if isinstance(item, dict)]
+    return mapped, int(total) if isinstance(total, int) else 0
+
+
+def _extract_items(resp: Dict[str, Any]) -> List[Dict[str, Any]]:
+    container = resp.get("data") if isinstance(resp, dict) else None
+    if isinstance(container, list):
+        return [item for item in container if isinstance(item, dict)]
+    if isinstance(container, dict):
+        nested = container.get("data")
+        if isinstance(nested, list):
+            return [item for item in nested if isinstance(item, dict)]
+    return []
 
 class RobotAPIRepository(RobotRepository):
     def __init__(self, client: HTTPClient):
@@ -11,8 +47,10 @@ class RobotAPIRepository(RobotRepository):
         resp = self.client.request("GET", f"/robots/{robot_id}")
         return Robot(**resp) if resp else None
 
-    def update_status(self, robot_id: str, status: str) -> None:
-        self.client.request("PATCH", f"/robots/{robot_id}/status", json={"status": status})
+    def update_status(self, robot_id: str, status: str | RobotStatus) -> None:
+        normalized_status = normalize_robot_status(status)
+        ensure_valid_worker_robot_status(normalized_status)
+        self.client.request("PATCH", f"/robots/{robot_id}/status", json={"status": normalized_status})
 
     def delete_robot(self, robot_id: str) -> None:
         self.client.request("DELETE", f"/robots/{robot_id}")
@@ -28,8 +66,7 @@ class RobotAPIRepository(RobotRepository):
         if project_id: params["project_id"] = project_id
 
         resp = self.client.request("GET", "/robots", params=params)
-        data = resp.get("data", [])
-        total = resp.get("total", 0)
+        data, total = _extract_list_payload(resp)
         return [Robot(**r) for r in data], total
 
     def acquire_need_login(self, limit: int = 20, lock_minutes: int = 30) -> List[Robot]:
@@ -38,7 +75,7 @@ class RobotAPIRepository(RobotRepository):
             "/robots/login/acquire",
             json={"limit": limit, "lock_minutes": lock_minutes},
         )
-        data = resp.get("data", [])
+        data = _extract_items(resp)
         return [Robot(**r) for r in data]
 
     def acquire_unhardened(self, limit: int = 20, lock_minutes: int = 30, min_age_days: int = 0) -> List[Robot]:
@@ -47,14 +84,16 @@ class RobotAPIRepository(RobotRepository):
             "/robots/security-hardened/acquire",
             json={"limit": limit, "lock_minutes": lock_minutes, "min_age_days": min_age_days},
         )
-        data = resp.get("data", [])
+        data = _extract_items(resp)
         return [Robot(**r) for r in data]
 
-    def update_auth_status(self, robot_id: str, auth_status: str) -> None:
+    def update_auth_status(self, robot_id: str, auth_status: str | RobotAuthStatus) -> None:
+        normalized_auth_status = normalize_robot_auth_status(auth_status)
+        ensure_valid_worker_robot_auth_status(normalized_auth_status)
         self.client.request(
             "PATCH",
             f"/robots/{robot_id}/auth-status",
-            json={"auth_status": auth_status},
+            json={"auth_status": normalized_auth_status},
         )
 
     def update_security_hardened(self, robot_id: str, security_hardened: bool) -> None:
@@ -64,6 +103,13 @@ class RobotAPIRepository(RobotRepository):
             json={"security_hardened": security_hardened},
         )
 
+    def update_metadata(self, robot_id: str, metadata: Dict[str, Any]) -> None:
+        self.client.request(
+            "PATCH",
+            f"/robots/{robot_id}",
+            json={"metadata": metadata},
+        )
+
 class AsyncRobotAPIRepository(AsyncRobotRepository):
     def __init__(self, client: AsyncHTTPClient):
         self.client = client
@@ -72,8 +118,10 @@ class AsyncRobotAPIRepository(AsyncRobotRepository):
         resp = await self.client.request("GET", f"/robots/{robot_id}")
         return Robot(**resp) if resp else None
 
-    async def update_status(self, robot_id: str, status: str) -> None:
-        await self.client.request("PATCH", f"/robots/{robot_id}/status", json={"status": status})
+    async def update_status(self, robot_id: str, status: str | RobotStatus) -> None:
+        normalized_status = normalize_robot_status(status)
+        ensure_valid_worker_robot_status(normalized_status)
+        await self.client.request("PATCH", f"/robots/{robot_id}/status", json={"status": normalized_status})
 
     async def delete_robot(self, robot_id: str) -> None:
         await self.client.request("DELETE", f"/robots/{robot_id}")
@@ -89,8 +137,7 @@ class AsyncRobotAPIRepository(AsyncRobotRepository):
         if project_id: params["project_id"] = project_id
 
         resp = await self.client.request("GET", "/robots", params=params)
-        data = resp.get("data", [])
-        total = resp.get("total", 0)
+        data, total = _extract_list_payload(resp)
         return [Robot(**r) for r in data], total
 
     async def acquire_need_login(self, limit: int = 20, lock_minutes: int = 30) -> List[Robot]:
@@ -99,7 +146,7 @@ class AsyncRobotAPIRepository(AsyncRobotRepository):
             "/robots/login/acquire",
             json={"limit": limit, "lock_minutes": lock_minutes},
         )
-        data = resp.get("data", [])
+        data = _extract_items(resp)
         return [Robot(**r) for r in data]
 
     async def acquire_unhardened(self, limit: int = 20, lock_minutes: int = 30, min_age_days: int = 0) -> List[Robot]:
@@ -108,14 +155,16 @@ class AsyncRobotAPIRepository(AsyncRobotRepository):
             "/robots/security-hardened/acquire",
             json={"limit": limit, "lock_minutes": lock_minutes, "min_age_days": min_age_days},
         )
-        data = resp.get("data", [])
+        data = _extract_items(resp)
         return [Robot(**r) for r in data]
 
-    async def update_auth_status(self, robot_id: str, auth_status: str) -> None:
+    async def update_auth_status(self, robot_id: str, auth_status: str | RobotAuthStatus) -> None:
+        normalized_auth_status = normalize_robot_auth_status(auth_status)
+        ensure_valid_worker_robot_auth_status(normalized_auth_status)
         await self.client.request(
             "PATCH",
             f"/robots/{robot_id}/auth-status",
-            json={"auth_status": auth_status},
+            json={"auth_status": normalized_auth_status},
         )
 
     async def update_security_hardened(self, robot_id: str, security_hardened: bool) -> None:
@@ -124,3 +173,10 @@ class AsyncRobotAPIRepository(AsyncRobotRepository):
             f"/robots/{robot_id}/security-hardened",
             json={"security_hardened": security_hardened},
         )
+
+    async def update_metadata(self, robot_id: str, metadata: Dict[str, Any]) -> None:
+        await self.client.request(
+            "PATCH",
+            f"/robots/{robot_id}",
+            json={"metadata": metadata},
+        )

{robot_wrapper_sdk-0.2.6 → robot_wrapper_sdk-0.2.8}/robot_wrapper_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robot-wrapper-sdk
-Version: 0.2.6
+Version: 0.2.8
 Summary: Robot Platform API SDK
 Author-email: GH Robot Platform Team <team@ghrobot.com>
 License: MIT
@@ -38,7 +38,7 @@ Or pass values directly when creating the module.
 ## Quick Start (Sync)
 
 ```python
-from robot_sdk import RobotPlatformModule
+from robot_sdk import RobotPlatformModule, RobotStatus, RobotAuthStatus
 
 sdk = RobotPlatformModule(
     base_url="http://localhost:8085",
@@ -51,14 +51,14 @@ sdk = RobotPlatformModule(
 robot = sdk.get_robot("2047631542552334336")
 print(robot.platform if robot else "not found")
 
-# Update lifecycle status
-sdk.update_status("2047631542552334336", "live")
+# Update lifecycle status (prefer enum)
+sdk.update_status("2047631542552334336", RobotStatus.LIVE)
 
 # Acquire login tasks
 login_tasks = sdk.acquire_need_login(limit=20, lock_minutes=30)
 
-# Update auth status after worker result
-sdk.update_auth_status("2047631542552334336", "authorized")
+# Update auth status after worker result (prefer enum)
+sdk.update_auth_status("2047631542552334336", RobotAuthStatus.AUTHORIZED)
 # allowed values: authorized | unauthorized | logged_out
 
 # Acquire hardening tasks
@@ -67,6 +67,12 @@ hardening_tasks = sdk.acquire_unhardened(limit=20, lock_minutes=30, min_age_days
 # Update hardening status after worker result
 sdk.update_security_hardened("2047631542552334336", True)
 
+# Update metadata (partial patch)
+sdk.update_metadata("2047631542552334336", {
+    "country_code": "VN",
+    "note": "updated by sdk"
+})
+
 sdk.close()
 ```
 
@@ -74,7 +80,7 @@ sdk.close()
 
 ```python
 import asyncio
-from robot_sdk import AsyncRobotPlatformModule
+from robot_sdk import AsyncRobotPlatformModule, RobotAuthStatus
 
 async def main():
     sdk = AsyncRobotPlatformModule(
@@ -86,8 +92,12 @@ async def main():
     robot = await sdk.get_robot("2047631542552334336")
     print(robot.platform if robot else "not found")
 
-    await sdk.update_auth_status("2047631542552334336", "authorized")
+    await sdk.update_auth_status("2047631542552334336", RobotAuthStatus.AUTHORIZED)
     await sdk.update_security_hardened("2047631542552334336", True)
+    await sdk.update_metadata("2047631542552334336", {
+        "country_code": "VN",
+        "note": "updated by async sdk"
+    })
 
     await sdk.close()
 
@@ -145,6 +155,7 @@ Update endpoints return:
 - `acquire_unhardened(limit=20, lock_minutes=30, min_age_days=0)`
 - `update_auth_status(robot_id, auth_status)`
 - `update_security_hardened(robot_id, security_hardened)`
+- `update_metadata(robot_id, metadata)`
 - `close()`
 
 ### `AsyncRobotPlatformModule` (async)

robot_wrapper_sdk-0.2.6/robot_sdk/domain/entities.py

@@ -1,51 +0,0 @@
-from dataclasses import dataclass, field
-from typing import Optional, Any, Dict
-
-@dataclass
-class Robot:
-    id: str
-    username: str
-    platform: str
-    status: str
-    metadata: Dict[str, Any] = field(default_factory=dict)
-    project_id: Optional[str] = None
-    primary_environment: Optional[str] = None
-    created_at: Optional[str] = None
-
-@dataclass
-class RobotSecrets:
-    password: str
-    two_fa_secret: str
-
-@dataclass
-class RobotActivity:
-    id: str
-    activity_type: str
-    status: str
-    message: str
-
-@dataclass
-class AcquireNeedLoginRequest:
-    limit: int = 20
-    lock_minutes: int = 30
-
-@dataclass
-class AcquireUnhardenedRequest:
-    limit: int = 20
-    lock_minutes: int = 30
-    min_age_days: int = 0
-
-@dataclass
-class UpdateAuthStatusRequest:
-    auth_status: str
-
-@dataclass
-class UpdateSecurityHardenedRequest:
-    security_hardened: bool
-
-@dataclass
-class StandardResponse:
-    status: str
-    code: int
-    message: str
-    data: Any = None