prcpy-erlc 0.1.0__tar.gz

prcpy_erlc-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Report a reproducible problem
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Description
+
+## Reproduction
+
+## Expected behavior
+
+## Actual behavior
+
+## Environment
+
+- prcpy-erlc version:
+- Python version:
+- OS:
+
+Do not include API keys or private server credentials.

prcpy_erlc-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature request
+about: Suggest an improvement
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## What would you like to add?
+
+## Why is it useful?
+
+## Proposed API
+
+## Additional context

prcpy_erlc-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## Summary
+
+## Changes
+
+## Testing
+
+- [ ] ruff check .
+- [ ] pytest
+
+## Notes
+
+Do not include credentials or private server data.

prcpy_erlc-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Lint
+        run: python -m ruff check .
+      - name: Test
+        run: python -m pytest
+      - name: Build
+        run: python -m build

prcpy_erlc-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.env
+.env.*

prcpy_erlc-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,144 @@
+# Contributing
+
+Thanks for contributing to prcpy.
+
+prcpy is a small, typed Python client for the ER:LC Private Server API. The project aims to keep its public API predictable, its dependencies small, and its implementation easy to maintain.
+
+## Before you start
+
+For a bug fix, documentation change, or small improvement, open an issue first when the change is likely to affect the public API or overall project direction. For straightforward fixes, you can open a pull request directly.
+
+Please search existing issues and pull requests before opening a new one.
+
+## Development setup
+
+prcpy supports Python 3.10 and newer.
+
+```bash
+python -m venv .venv
+```
+
+Windows:
+```powershell
+.venv\Scripts\Activate.ps1
+```
+
+macOS/Linux:
+```bash
+source .venv/bin/activate
+```
+
+Install development dependencies:
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Running checks
+```bash
+ruff check .
+pytest
+```
+
+Run both commands before opening a pull request. Changes to webhook verification, HTTP behavior, models, error handling, or other public behavior should include tests.
+
+## Project structure
+```text
+src/prcpy/       Package source
+tests/            Test suite
+examples/         Usage examples
+docs/             API and design documentation
+.github/          CI and repository templates
+```
+
+Keep implementation code in `src/prcpy`. Avoid adding scripts or files without a clear maintenance or user-facing purpose.
+
+## Code style
+- Follow the existing project structure.
+- Keep functions and classes focused.
+- Prefer explicit, readable code over clever abstractions.
+- Preserve type annotations.
+- Keep the public API small and intentional.
+- Use the standard library where it is sufficient.
+- Avoid unnecessary dependencies.
+- Keep error messages useful without exposing credentials or private data.
+- Do not silently change existing public behavior.
+- Do not add automatic retries to commands unless explicitly designed and documented; repeating a command can have side effects.
+
+Ruff is the project's source of truth for linting.
+
+## API changes
+
+For public API changes:
+1. Update the implementation.
+2. Add or update tests.
+3. Update documentation.
+4. Update affected examples.
+5. Consider backward compatibility.
+6. Keep the change aligned with the official ER:LC API documentation.
+
+If the ER:LC API itself changes, link the relevant official documentation in the pull request description. Do not invent undocumented API behavior when a documented alternative exists.
+
+## Models
+
+Keep API models typed and predictable. Match official API fields closely, handle missing optional data safely, preserve useful raw API data where the existing pattern does so, and add tests for new fields.
+
+Avoid restrictive enums for API values unless the API guarantees those values are stable.
+
+## HTTP behavior
+
+Preserve useful HTTP status information, documented error details, authentication failures, and rate-limit information when changing request handling.
+
+Be especially careful with retries: POST requests execute in-game commands and should not be automatically repeated without an explicit design.
+
+Never log authenticated request headers.
+
+## Webhooks
+
+Webhook changes require tests for valid and invalid signatures.
+
+Use synthetic keys and payloads in tests. Never use production webhook credentials.
+
+Verify changes against the current ER:LC documentation before submitting them.
+
+## Tests
+
+Tests should be deterministic, fast, independent of a live ER:LC server, free of credentials, and focused on observable behavior.
+
+Use mocked HTTP responses for API client tests. The normal test suite must not require a real ER:LC private server.
+
+## Documentation
+
+Document behavior users can actually rely on. Keep examples short and runnable. When a public API changes, update the README or the appropriate page under `docs/`.
+
+## Commits
+
+Use short, descriptive commit messages.
+
+```text
+Add queue endpoint
+Fix rate limit parsing
+Update webhook docs
+Test command errors
+```
+
+Avoid commit messages that contain unnecessary detail or references to tools used to make the change.
+
+## Pull requests
+
+A good pull request should explain what changed, why it changed, any public API changes, how it was tested, and compatibility or migration considerations.
+
+Keep pull requests focused.
+
+Before opening a pull request:
+- [ ] Tests pass.
+- [ ] Ruff passes.
+- [ ] Documentation is updated when needed.
+- [ ] Examples still make sense when affected.
+- [ ] No credentials or private server data are included.
+- [ ] Public API changes are clearly described.
+
+## Security
+
+Never include ER:LC server keys, global API keys, webhook secrets, access tokens, or private server data in commits, issues, pull requests, examples, or tests.
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting and security guidance.

prcpy_erlc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sidhak Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

prcpy_erlc-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.5
+Name: prcpy-erlc
+Version: 0.1.0
+Summary: A typed Python client for the ER:LC Private Server API.
+Project-URL: Documentation, https://apidocs.erlc.gg/
+Project-URL: Repository, https://github.com/Metolix/erlcpy
+Project-URL: Issues, https://github.com/Metolix/erlcpy/issues
+Author: Sidhak Singh
+License: MIT License
+        
+        Copyright (c) 2026 Sidhak Singh
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: api,erlc,private-server,python,roblox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: cryptography>=42; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: webhooks
+Requires-Dist: cryptography>=42; extra == 'webhooks'
+Description-Content-Type: text/markdown
+
+# prcpy
+
+A typed Python client for the ER:LC Private Server API.
+
+prcpy provides synchronous and asynchronous clients, typed response models, rate-limit metadata, structured exceptions, webhook helpers, and a low-level request interface for endpoints that are added to the API later.
+
+> prcpy is an independent open-source project and is not affiliated with or endorsed by ER:LC or PRC.
+
+## Requirements
+
+- Python 3.10+
+- An ER:LC private server with API access
+- A server key from the server's API settings
+
+## Installation
+
+```bash
+pip install prcpy-erlc
+```
+
+For webhook signature verification:
+
+```bash
+pip install "prcpy-erlc[webhooks]"
+```
+
+## Quick start
+
+```python
+from prcpy import Client
+
+with Client("your-server-key") as client:
+    server = client.get_server(players=True)
+
+    print(server.name)
+    print(f"{server.current_players}/{server.max_players}")
+
+    for player in server.players or []:
+        print(player.username, player.team)
+```
+
+## Async
+
+```python
+from prcpy import AsyncClient
+
+async with AsyncClient("your-server-key") as client:
+    server = await client.get_server(players=True)
+    print(server.name)
+```
+
+## Available server data
+
+The v2 server endpoint supports these optional resources:
+
+- `players`
+- `staff`
+- `join_logs`
+- `queue`
+- `kill_logs`
+- `command_logs`
+- `mod_calls`
+- `emergency_calls`
+- `vehicles`
+
+Only request the data an application needs.
+
+```python
+server = client.get_server(
+    players=True,
+    staff=True,
+    vehicles=True,
+    emergency_calls=True,
+)
+```
+
+## Convenience methods
+
+```python
+players = client.get_players()
+staff = client.get_staff()
+join_logs = client.get_join_logs()
+queue = client.get_queue()
+kill_logs = client.get_kill_logs()
+command_logs = client.get_command_logs()
+mod_calls = client.get_mod_calls()
+vehicles = client.get_vehicles()
+bans = client.get_bans()
+```
+
+## Commands
+
+```python
+result = client.send_command(":h Hello from prcpy")
+print(result.message)
+```
+
+The API documents a `commandId` on command failures. prcpy exposes it as `CommandError.command_id` or `ServerOfflineError.command_id` when supplied by the API.
+
+## Authentication
+
+All API requests use the `server-key` header.
+
+Public applications may also provide a global API key:
+
+```python
+client = Client(
+    "server-key",
+    global_api_key="global-api-key",
+)
+```
+
+Environment variables are supported:
+
+```text
+ERLC_SERVER_KEY=...
+ERLC_GLOBAL_API_KEY=...
+```
+
+```python
+client = Client.from_env()
+```
+
+Never commit keys to source control.
+
+## Rate limits
+
+The client reads the API's `X-RateLimit-Bucket`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` response headers.
+
+```python
+client.get_server()
+print(client.rate_limit)
+```
+
+A 429 response raises `RateLimitError` with `retry_after` when the server provides a `Retry-After` header.
+
+prcpy does not silently retry commands. This avoids accidentally executing an in-game command more than once.
+
+## Raw API access
+
+The typed methods cover the documented API, but the API can grow independently of this package.
+
+```python
+data = client.request("GET", "/v2/server", params={"Players": "true"})
+```
+
+## Webhooks
+
+prcpy includes a small helper for Ed25519 webhook verification:
+
+```python
+from prcpy.webhooks import verify_signature
+
+verify_signature(
+    timestamp=request.headers["X-Signature-Timestamp"],
+    signature=request.headers["X-Signature-Ed25519"],
+    body=raw_request_body,
+    public_key="your-webhook-public-key",
+)
+```
+
+Always verify the raw request body before parsing JSON.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+pytest
+```
+
+## Project structure
+
+```text
+prcpy/
+├── docs/
+├── examples/
+├── src/prcpy/
+│   ├── client.py
+│   ├── errors.py
+│   ├── models.py
+│   ├── rate_limits.py
+│   └── webhooks.py
+├── tests/
+├── .github/workflows/
+├── CONTRIBUTING.md
+├── LICENSE
+├── pyproject.toml
+└── README.md
+```
+
+## License
+
+MIT

prcpy_erlc-0.1.0/README.md

@@ -0,0 +1,194 @@
+# prcpy
+
+A typed Python client for the ER:LC Private Server API.
+
+prcpy provides synchronous and asynchronous clients, typed response models, rate-limit metadata, structured exceptions, webhook helpers, and a low-level request interface for endpoints that are added to the API later.
+
+> prcpy is an independent open-source project and is not affiliated with or endorsed by ER:LC or PRC.
+
+## Requirements
+
+- Python 3.10+
+- An ER:LC private server with API access
+- A server key from the server's API settings
+
+## Installation
+
+```bash
+pip install prcpy-erlc
+```
+
+For webhook signature verification:
+
+```bash
+pip install "prcpy-erlc[webhooks]"
+```
+
+## Quick start
+
+```python
+from prcpy import Client
+
+with Client("your-server-key") as client:
+    server = client.get_server(players=True)
+
+    print(server.name)
+    print(f"{server.current_players}/{server.max_players}")
+
+    for player in server.players or []:
+        print(player.username, player.team)
+```
+
+## Async
+
+```python
+from prcpy import AsyncClient
+
+async with AsyncClient("your-server-key") as client:
+    server = await client.get_server(players=True)
+    print(server.name)
+```
+
+## Available server data
+
+The v2 server endpoint supports these optional resources:
+
+- `players`
+- `staff`
+- `join_logs`
+- `queue`
+- `kill_logs`
+- `command_logs`
+- `mod_calls`
+- `emergency_calls`
+- `vehicles`
+
+Only request the data an application needs.
+
+```python
+server = client.get_server(
+    players=True,
+    staff=True,
+    vehicles=True,
+    emergency_calls=True,
+)
+```
+
+## Convenience methods
+
+```python
+players = client.get_players()
+staff = client.get_staff()
+join_logs = client.get_join_logs()
+queue = client.get_queue()
+kill_logs = client.get_kill_logs()
+command_logs = client.get_command_logs()
+mod_calls = client.get_mod_calls()
+vehicles = client.get_vehicles()
+bans = client.get_bans()
+```
+
+## Commands
+
+```python
+result = client.send_command(":h Hello from prcpy")
+print(result.message)
+```
+
+The API documents a `commandId` on command failures. prcpy exposes it as `CommandError.command_id` or `ServerOfflineError.command_id` when supplied by the API.
+
+## Authentication
+
+All API requests use the `server-key` header.
+
+Public applications may also provide a global API key:
+
+```python
+client = Client(
+    "server-key",
+    global_api_key="global-api-key",
+)
+```
+
+Environment variables are supported:
+
+```text
+ERLC_SERVER_KEY=...
+ERLC_GLOBAL_API_KEY=...
+```
+
+```python
+client = Client.from_env()
+```
+
+Never commit keys to source control.
+
+## Rate limits
+
+The client reads the API's `X-RateLimit-Bucket`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` response headers.
+
+```python
+client.get_server()
+print(client.rate_limit)
+```
+
+A 429 response raises `RateLimitError` with `retry_after` when the server provides a `Retry-After` header.
+
+prcpy does not silently retry commands. This avoids accidentally executing an in-game command more than once.
+
+## Raw API access
+
+The typed methods cover the documented API, but the API can grow independently of this package.
+
+```python
+data = client.request("GET", "/v2/server", params={"Players": "true"})
+```
+
+## Webhooks
+
+prcpy includes a small helper for Ed25519 webhook verification:
+
+```python
+from prcpy.webhooks import verify_signature
+
+verify_signature(
+    timestamp=request.headers["X-Signature-Timestamp"],
+    signature=request.headers["X-Signature-Ed25519"],
+    body=raw_request_body,
+    public_key="your-webhook-public-key",
+)
+```
+
+Always verify the raw request body before parsing JSON.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+pytest
+```
+
+## Project structure
+
+```text
+prcpy/
+├── docs/
+├── examples/
+├── src/prcpy/
+│   ├── client.py
+│   ├── errors.py
+│   ├── models.py
+│   ├── rate_limits.py
+│   └── webhooks.py
+├── tests/
+├── .github/workflows/
+├── CONTRIBUTING.md
+├── LICENSE
+├── pyproject.toml
+└── README.md
+```
+
+## License
+
+MIT