robot-wrapper-sdk 0.2.16

Robot Platform API SDK

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

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)

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

sdk.close()

Quick Start (Async)

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:

{
  "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:

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

---

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)
• close()

AsyncRobotPlatformModule (async)

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

---

Documentation

• Usage guide: docs/guide.md
• Package code: robot_sdk/

---

Build & Publish (Maintainers)

make venv
make install
make build
make publish

Requires valid PyPI credentials (Twine).