Building a Python client library for the OpenClaw Plugin Rating API

import os
import logging
from typing import List, Optional

import requests
from pydantic import BaseModel, Field, ValidationError

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

API_BASE_URL = "https://api.openclaw.io/v1"


class Rating(BaseModel):
    id: int
    plugin_id: str = Field(..., alias="pluginId")
    user_id: str = Field(..., alias="userId")
    score: int
    comment: Optional[str] = None
    created_at: str = Field(..., alias="createdAt")


class OpenClawClient:
    def __init__(self, api_token: str, base_url: str = API_BASE_URL):
        self.base_url = base_url.rstrip("/")
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_token}",
            "Content-Type": "application/json",
            "Accept": "application/json"
        })
        logger.info("OpenClawClient initialized with base URL %s", self.base_url)

    def _handle_response(self, response: requests.Response):
        try:
            response.raise_for_status()
            return response.json()
        except requests.HTTPError as exc:
            logger.error("HTTP error %s: %s", response.status_code, response.text)
            raise exc

    def submit_rating(self, plugin_id: str, score: int, comment: Optional[str] = None) -> Rating:
        payload = {"pluginId": plugin_id, "score": score, "comment": comment}
        logger.debug("Submitting rating payload: %s", payload)
        resp = self.session.post(f"{self.base_url}/ratings", json=payload)
        data = self._handle_response(resp)
        try:
            rating = Rating(**data)
            logger.info("Rating submitted with ID %s", rating.id)
            return rating
        except ValidationError as ve:
            logger.error("Response validation failed: %s", ve)
            raise ve

    def get_ratings(self, plugin_id: str, limit: int = 10, offset: int = 0) -> List[Rating]:
        params = {"pluginId": plugin_id, "limit": limit, "offset": offset}
        logger.debug("Fetching ratings with params: %s", params)
        resp = self.session.get(f"{self.base_url}/ratings", params=params)
        data = self._handle_response(resp)
        ratings = []
        for item in data.get("items", []):
            try:
                ratings.append(Rating(**item))
            except ValidationError as ve:
                logger.warning("Skipping invalid rating entry: %s", ve)
        logger.info("Retrieved %d ratings", len(ratings))
        return ratings

    def delete_rating(self, rating_id: int) -> bool:
        logger.debug("Deleting rating ID %s", rating_id)
        resp = self.session.delete(f"{self.base_url}/ratings/{rating_id}")
        if resp.status_code == 204:
            logger.info("Rating %s deleted successfully", rating_id)
            return True
        else:
            self._handle_response(resp)
            return False


# Helper to load token from environment
def get_client_from_env() -> OpenClawClient:
    token = os.getenv("OPENCLAW_API_TOKEN")
    if not token:
        raise EnvironmentError("OPENCLAW_API_TOKEN not set in environment")
    return OpenClawClient(api_token=token)

from setuptools import setup, find_packages

setup(
    name="openclaw-client",
    version="0.1.0",
    description="Python client for the OpenClaw Plugin Rating API",
    author="Your Name",
    packages=find_packages(),
    install_requires=[
        "requests>=2.28.0",
        "pydantic>=1.10.0"
    ],
    python_requires=">=3.9",
    url="https://github.com/yourusername/openclaw-client",
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
)

python -m pip install --upgrade build twine
python -m build
twine upload dist/*

from openclaw_client import get_client_from_env

def main():
    client = get_client_from_env()

    # Submit a new rating
    new_rating = client.submit_rating(
        plugin_id="com.example.myplugin",
        score=5,
        comment="Excellent functionality and great docs!"
    )
    print(f"Submitted rating ID: {new_rating.id}")

    # Retrieve the most recent 5 ratings
    recent = client.get_ratings(plugin_id="com.example.myplugin", limit=5)
    for r in recent:
        print(f"[{r.score}] {r.comment or 'No comment'} (by {r.user_id})")

if __name__ == "__main__":
    main()

pip install pytest responses

import os
import json
import pytest
import responses
from openclaw_client import OpenClawClient

API_TOKEN = "test-token"
client = OpenClawClient(api_token=API_TOKEN, base_url="https://api.openclaw.io/v1")

@responses.activate
def test_submit_rating_success():
    responses.add(
        responses.POST,
        "https://api.openclaw.io/v1/ratings",
        json={"id": 123, "pluginId": "p1", "userId": "u1", "score": 4, "comment": "Good", "createdAt": "2024-01-01T00:00:00Z"},
        status=201
    )
    rating = client.submit_rating("p1", 4, "Good")
    assert rating.id == 123
    assert rating.score == 4

@responses.activate
def test_get_ratings_pagination():
    payload = {
        "items": [
            {"id": 1, "pluginId": "p1", "userId": "u1", "score": 5, "comment": "Great", "createdAt": "2024-01-02T00:00:00Z"},
            {"id": 2, "pluginId": "p1", "userId": "u2", "score": 3, "comment": None, "createdAt": "2024-01-03T00:00:00Z"}
        ]
    }
    responses.add(
        responses.GET,
        "https://api.openclaw.io/v1/ratings",
        json=payload,
        status=200
    )
    ratings = client.get_ratings("p1", limit=2)
    assert len(ratings) == 2
    assert ratings[0].score == 5