Metadata-Version: 2.4
Name: robot-wrapper-sdk
Version: 0.2.10
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.

## 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
login_tasks = sdk.acquire_need_login(limit=20, lock_minutes=30)

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

# Acquire hardening tasks
hardening_tasks = sdk.acquire_unhardened(limit=20, lock_minutes=30, min_age_days=0)

# 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()
```

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

    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 endpoints return:

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

---

## Main API

### `RobotPlatformModule` (sync)
- `list_robots(platform=None, 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)`
- `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)
Async equivalents of all methods above, plus `await close()`.

---

## 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).
