Metadata-Version: 2.4
Name: prc-api-wrapper
Version: 0.2.0
Summary: Typed Python wrapper for the Police Roleplay Community private server API v1 and v2.
License-Expression: MIT
Project-URL: PRC API Documentation, https://apidocs.policeroleplay.community
Keywords: erlc,prc,api,wrapper
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# PRC API Wrapper

Typed Python wrapper for the Police Roleplay Community private server API with support for both `v1` and `v2`.

The wrapper is dependency-free and uses the Python standard library for HTTP requests.

## Disclaimer

This project is a third-party Python wrapper for the Police Roleplay Community API. It is not an official PRC product.

This project is not affiliated with, associated with, authorized by, endorsed by, or sponsored by Police Roleplay Community, Emergency Response: Liberty County, or ER:LC.

This package does not include, modify, distribute, or claim ownership of the Emergency Response: Liberty County game, Police Roleplay Community services, or any related assets, branding, logos, or trademarks.

All product names, trademarks, service marks, logos, and brand references used in this project remain the property of their respective owners and are used only to identify compatibility with the public PRC API.

Use of the PRC API, server keys, global API keys, and any related PRC or ER:LC services remains subject to the official terms, policies, and rules published by their respective owners. This package is only a software wrapper for interacting with that API.

## Features

- Shared authenticated client for both API versions
- Pythonic, typed dataclass responses
- Optional support for PRC global API keys via the `Authorization` header
- Automatic rate-limit tracking using PRC's `X-RateLimit-*` headers
- Convenience methods for `v1` and `v2`
- Last-response metadata for monitoring rate limits and latency
- Structured exceptions with PRC HTTP status and API error code support

## Installation

```bash
pip install prc-api-wrapper
```

## Quick Start

```python
from prc_api import PRCAPI

api = PRCAPI(server_key="YOUR_SERVER_KEY")

server = api.v1.get_server()
print(server.name, server.current_players)

players = api.v1.get_players()
for player in players:
    print(player.player, player.team, player.callsign)

full_server = api.v2.get_server(
    players=True,
    vehicles=True,
    emergency_calls=True,
)
print(full_server.players)
print(full_server.vehicles)

result = api.v2.run_command(":h Hello from Python!")
print(result.message)
```

## Client Configuration

```python
from prc_api import PRCAPI

api = PRCAPI(
    server_key="YOUR_SERVER_KEY",
    global_api_key="YOUR_GLOBAL_API_KEY",   # optional
    timeout=10.0,
    respect_rate_limits=True,
    retry_on_rate_limit=True,
    max_rate_limit_retries=1,
)
```

## Versioned Clients

```python
from prc_api import PRCClientV1, PRCClientV2

v1 = PRCClientV1(server_key="YOUR_SERVER_KEY", global_api_key="YOUR_GLOBAL_API_KEY")
v2 = PRCClientV2(server_key="YOUR_SERVER_KEY", global_api_key="YOUR_GLOBAL_API_KEY")
```

## v1 Methods

```python
server = v1.get_server()
players = v1.get_players()
join_logs = v1.get_join_logs()
queue = v1.get_queue()
kill_logs = v1.get_kill_logs()
command_logs = v1.get_command_logs()
mod_calls = v1.get_mod_calls()
bans = v1.get_bans()
vehicles = v1.get_vehicles()
staff = v1.get_staff()

v1.run_command(":h Hello from Python!")
```

## v2 Methods

```python
server = v2.get_server()
full_server = v2.get_server(
    players=True,
    staff=True,
    join_logs=True,
    queue=True,
    kill_logs=True,
    command_logs=True,
    mod_calls=True,
    emergency_calls=True,
    vehicles=True,
)

players = v2.get_players()
staff = v2.get_staff()
join_logs = v2.get_join_logs()
queue = v2.get_queue()
kill_logs = v2.get_kill_logs()
command_logs = v2.get_command_logs()
mod_calls = v2.get_mod_calls()
emergency_calls = v2.get_emergency_calls()
vehicles = v2.get_vehicles()

result = v2.run_command(":h Hello from Python!")
print(result.message)
```

## Rate Limit Metadata

The wrapper tracks PRC's rate-limit headers and exposes them on the last response:

```python
api.v2.get_players()

response = api.last_response
if response is not None:
    print(response.status_code)
    print(response.elapsed_seconds)
    print(response.rate_limit.bucket)
    print(response.rate_limit.remaining)
    print(response.rate_limit.reset_at)
```

If PRC returns a rate limit response, the raised exception also includes the parsed metadata:

```python
from prc_api import PRCAPI, RateLimitError

api = PRCAPI(server_key="YOUR_SERVER_KEY")

try:
    api.v2.run_command(":h Hello")
except RateLimitError as exc:
    print(exc.retry_after)
    print(exc.rate_limit.bucket if exc.rate_limit else None)
```

## Event Signature Verification

The package includes helpers for verifying PRC event webhook signatures:

```python
from prc_api import verify_prc_event_signature

is_valid = verify_prc_event_signature(
    timestamp=timestamp_header,
    raw_body=raw_request_body,
    signature_hex=signature_header,
)
```

## Notes

- `v1` exposes separate methods for each endpoint.
- `v2` keeps `run_command()` and provides `get_server()` with optional query flags like `players=True` and `vehicles=True`.
- Convenience methods such as `v2.get_players()` and `v2.get_vehicles()` call `GET /v2/server` with the correct flags for you.
- The wrapper sends browser-like default request headers because the PRC edge may reject the stock `Python-urllib` signature with a Cloudflare `403/1010` block.
- If you have a PRC global API key, pass it as `global_api_key` so requests include the `Authorization` header recommended by PRC for large apps.
- The transport respects PRC rate-limit headers and, by default, will retry a `429` once after the server-provided `retry_after` delay.
- Command routes are rate-limited separately by PRC. Their docs currently note a `1 request / 5 seconds` bucket for command execution.
- This package is an HTTP wrapper and signature-verification helper. It does not host webhook listeners or implement general-purpose application caching.
