Metadata-Version: 2.4
Name: robot-wrapper-sdk
Version: 0.2.19
Summary: Robot Platform API SDK
Author-email: GH Robot Platform Team <team@ghrobot.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx[socks]>=0.24.1

# Robot Platform SDK (Python)

Python SDK for Robot Platform with:

- develop-app authentication (`app_id`/`app_secret`),
- sync + async clients,
- auto token refresh,
- robot operations and login/hardening task flow,
- developer browser node open/close flow.

## Installation

```bash
pip install robot-wrapper-sdk
```

## Configuration

Set environment variables (recommended):

- `ROBOT_PLATFORM_BASE_URL`
- `ROBOT_PLATFORM_APP_ID`
- `ROBOT_PLATFORM_APP_SECRET`
- `ROBOT_PLATFORM_PROXY_URL` (optional)

Or pass values directly when creating the module.

---

## Quick Start (Sync)

```python
from robot_sdk import RobotPlatformModule, RobotStatus, RobotAuthStatus

sdk = RobotPlatformModule(
    base_url="http://localhost:8085",
    app_id="your_app_id",
    app_secret="your_app_secret",
    # proxy_url="socks5h://192.168.3.100:1080",  # optional
)

# Read robot
robot = sdk.get_robot("2047631542552334336")
print(robot.platform if robot else "not found")

# Update lifecycle status (prefer enum)
sdk.update_status("2047631542552334336", RobotStatus.LIVE)

# Acquire login tasks (optionally filter by platform)
login_tasks = sdk.acquire_need_login(
    limit=20,
    lock_minutes=30,
    platforms=["facebook", "instagram"],
)

# Unlock login task robots when worker must release locks
sdk.unlock_login_tasks(["2047631542552334336"])

# Update auth status after worker result (prefer enum)
sdk.update_auth_status("2047631542552334336", RobotAuthStatus.AUTHORIZED)
# allowed values: authorized | unauthorized | logged_out

# Acquire hardening tasks (optionally filter by platform)
hardening_tasks = sdk.acquire_unhardened(
    limit=20,
    lock_minutes=30,
    min_age_days=0,
    platforms=["facebook", "instagram"],
)

# Unlock hardening task robots when worker must release locks
sdk.unlock_hardening_tasks(["2047631542552334336"])

# 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"
})

# Open/close browser node (requires developer app scope: open:browser)
session = sdk.open_browser(robot_id="2047631542552334336")
# Or override manually when no robot_id is available:
# session = sdk.open_browser(username="example_user_1", proxy="socks5://127.0.0.1:1080", country_code="VN")
print(session.pod_name, session.status)
sdk.close_browser(session.pod_name, robot_id="2047631542552334336")

sdk.close()
```

## Quick Start (Async)

```python
import asyncio
from robot_sdk import AsyncRobotPlatformModule, RobotAuthStatus

async def main():
    sdk = AsyncRobotPlatformModule(
        base_url="http://localhost:8085",
        app_id="your_app_id",
        app_secret="your_app_secret",
    )

    robot = await sdk.get_robot("2047631542552334336")
    print(robot.platform if robot else "not found")

    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"
    })

    session = await sdk.open_browser(robot_id="2047631542552334336")
    await sdk.close_browser(session.pod_name, robot_id="2047631542552334336")

    await sdk.close()

asyncio.run(main())
```

---

## Response Shape (Placeholder)

Acquire endpoints return:

```json
{
  "status": "success",
  "code": 200,
  "message": "OK",
  "data": [
    {
      "id": "2047631542552334336",
      "username": "example_user_1",
      "platform": "facebook",
      "status": "live",
      "auth_status": "unauthorized",
      "metadata": {
        "security_hardened": false
      }
    }
  ]
}
```

Update/close endpoints return:

```json
{
  "status": "success",
  "code": 200,
  "message": "OK",
  "data": null
}
```

Browser open returns:

```json
{
  "status": "success",
  "code": 200,
  "message": "OK",
  "data": {
    "pod_name": "selenium-node-abc123",
    "session_id": "selenium-node-abc123",
    "status": "running"
  }
}
```

---

## Main API

### `RobotPlatformModule` (sync)

- `list_robots(platform=None, status=None, auth_status=None, project_id=None, page=1, limit=20)`
- `get_robot(robot_id)`
- `delete_robot(robot_id)`
- `get_secrets(robot_id)`
- `update_status(robot_id, status)`
- `acquire_need_login(limit=20, lock_minutes=30, platforms=None)`
- `acquire_unhardened(limit=20, lock_minutes=30, min_age_days=0, platforms=None)`
- `unlock_login_tasks(robot_ids)`
- `unlock_hardening_tasks(robot_ids)`
- `update_auth_status(robot_id, auth_status)`
- `update_security_hardened(robot_id, security_hardened)`
- `update_metadata(robot_id, metadata)`
- `open_browser(robot_id=None, username="", proxy="", country_code="")`
- `close_browser(pod_name, robot_id=None)`
- `close()`

### `AsyncRobotPlatformModule` (async)

Async equivalents of all methods above, plus `await close()`.

---

## Changelog

### [0.2.19] - 2026-05-25

#### Added

- Added browser node helpers for developer apps with `open:browser` scope:
  - `open_browser(robot_id=None, username="", proxy="", country_code="")`
  - `close_browser(pod_name, robot_id=None)`
- Added sync and async support for `POST /api/v1/developer/browser/open` and `DELETE /api/v1/developer/browser/close`.
- Added `BrowserSession` return type with `pod_name`, `session_id`, and `status`.

#### Changed

- Updated PyPI README with browser open/close examples and response schema.

### [0.2.5] - 2026-04-24

#### Added

- Added login/hardening worker methods for both sync and async modules.
- Added repository contracts and implementations for login/hardening acquire + update flows.

#### Changed

- Updated README with develop-app auth setup, sync/async quick start, response schema, and task flow API list.

---

## Documentation

- Usage guide: [`docs/guide.md`](docs/guide.md)
- Package code: `robot_sdk/`

---

## Build & Publish (Maintainers)

```bash
make venv
make install
make build
make publish
```

Requires valid PyPI credentials (Twine).
