Metadata-Version: 2.4
Name: ffdata-client
Version: 0.1.0
Summary: Professional Python SDK for FFData API
Author: FFData Team
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0

# ffclient

A professional Python SDK for the FFData API, providing easy access to player statistics and management with built-in credit handling and error mapping.

## Installation

```bash
pip install ffclient
```

## Quick Start

```python
import os
from ffclient import FFClient, AuthenticationError, InsufficientCreditsError

# Initialize the client with explicit configuration
client = FFClient(
    api_key="your_secret_api_key",
    base_url="https://api.ffdata.io"
)

# Alternatively, use environment variables:
# FFCLIENT_BASE_URL=https://api.ffdata.io
# client = FFClient(api_key="your_secret_api_key")

try:
    # Get basic player info
    player = client.get_player_basic("10001")
    print(f"Nickname: {player['data']['nickname']}")
    print(f"Credits Left: {player['credits_left']}")

except AuthenticationError:
    print("Invalid API Key!")
except InsufficientCreditsError:
    print("Top up your credits to continue.")
except Exception as e:
    print(f"An error occurred: {e}")
```

## Configuration

The SDK requires two main configuration points:
1. **API Key**: Passed directly to the `FFClient` constructor.
2. **Base URL**: Can be passed via the `base_url` parameter or set via the `FFCLIENT_BASE_URL` environment variable. The URL must start with `http://` or `https://`.

## Features

- **Automatic Authentication**: Headers are managed automatically via the API key.
- **Credit Tracking**: Every response includes `credits_used` and `credits_left`.
- **Exception Mapping**: HTTP errors are converted into descriptive Python exceptions.
- **Validation**: Local validation for UIDs and URLs to prevent unnecessary API calls.
- **Session Reuse**: Uses `requests.Session` for high-performance persistent connections.

## License

MIT
