robot-wrapper-sdk 0.2.18

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,
• developer browser node open/close 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"
})

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

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:

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

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

Browser open returns:

{
  "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.17] - 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
• Package code: robot_sdk/

---

Build & Publish (Maintainers)

make venv
make install
make build
make publish

Requires valid PyPI credentials (Twine).