Metadata-Version: 2.4
Name: ffdata-client
Version: 1.0.0
Summary: Professional Python SDK for FFData API
Author: FFData Team
License-Expression: 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

# FFData Python SDK

<p align="center">
  <a href="https://ffdata-web.vercel.app/docs">
    <img src="https://img.shields.io/badge/Docs-FFData-FFD700?style=for-the-badge" alt="Docs">
  </a>
  <a href="https://discord.gg/notfound">
    <img src="https://img.shields.io/badge/Discord-FFData-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord">
  </a>
  <a href="https://github.com/str-atif/ffdata-client">
    <img src="https://img.shields.io/badge/GitHub-Repository-black?style=for-the-badge&logo=github" alt="GitHub">
  </a>
  <a href="https://guns.lol/str_atif">
    <img src="https://img.shields.io/badge/Built%20by-FFData-purple?style=for-the-badge" alt="Built by FFData">
  </a>
</p>

<p align="center">
  <img src="https://img.shields.io/pypi/v/ffdata-client?style=flat-square" />
  <img src="https://img.shields.io/pypi/pyversions/ffdata-client?style=flat-square" />
  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" />
</p>

---

Python SDK for accessing Free Fire player data and Craftland information via the professional FFData API.

---

## Installation

```bash
pip install ffdata-client
```

---

## Quick Start

```python
from ffclient import FFClient

# Initialize client (Default points to https://ffdata-api.onrender.com)
client = FFClient(api_key="your_api_key")

# Fetch player data with specific detail level
# Supported detail_levels: "basic", "detailed", "full"
player = client.get_player(uid=1738283841, detail_level="detailed")

# Fetch workshop author info (Craftland)
author = client.get_workshop_author(uid=1738283841, detail_level="full")

# Fetch clan info (Guild)
clan = client.get_clan(clan_id=3022208474, detail_level="basic")

print(player["data"]["nickname"])
print(author["data"])
print(clan["data"]["clan_name"])

# Check cached credit balance
print(f"Remaining balance: {client.credits_left}")
```

---

## Detailed Usage

### Player API
Retrieve real-time player statistics and regional data.

```python
player = client.get_player(
    uid=2726416993,
    detail_level="detailed" # options: "basic", "detailed", "full"
)

# Access primary data
print(player["data"])

# Access metadata (Time, Request ID, Version, Credits Left)
print(player["meta"]["time_ms"])
print(player["meta"]["request_id"])
print(player["meta"]["credits_left"])
```

### Workshop (Craftland)
Retrieve creator statistics and map information.

```python
author = client.get_workshop_author(uid=2726416993, detail_level="basic")
print(author["data"]["likes"])
```

### Clan Info (Guild)
Retrieve clan standings, rosters, and levels.

```python
clan = client.get_clan(clan_id=3022208474, detail_level="detailed")
print(clan["data"]["clan_name"])
```

---

## Configuration

Custom configuration for private endpoints or specialized debugging.

```python
client = FFClient(
    api_key="your_api_key",
    base_url="https://ffdata-api.onrender.com",  # optional override
    debug="basic",  # options: "off", "basic", "verbose"
    timeout=15,
    max_retries=3
)
```

---

## Response Format

The SDK returns a unified response structure for all endpoints:

```json
{
  "data": { 
    "uid": 2726416993,
    "nickname": "...",
    ...
  },
  "meta": {
    "time_ms": 120,      // Latency in milliseconds
    "request_id": "...", // Global tracing ID
    "fallback": false,   // True if served from circuit-breaker cache
    "version": "1.0.0",  // SDK Version
    "credits_left": 490, // Account credits left
    "credits_used": 5    // Request cost
  }
}
```

---

## Error Handling

The SDK maps HTTP errors to descriptive Python exceptions.

```python
from ffclient import AuthError, RateLimitError, InsufficientCreditsError

try:
    client.get_player(uid=2726416993)

except AuthError:
    print("Invalid API key or session expired")

except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")

except InsufficientCreditsError:
    print("Your account balance is 0. Please top up.")

except Exception as e:
    print(f"An unexpected error occurred: {e}")
```

---

## Features

* **Resilience**: Built-in adaptive circuit breakers and jiterred retries.
* **Unified Schema**: Consistent `data` + `meta` structure across all calls.
* **Metadata Insight**: High-resolution latency tracking (`time_ms`) and `request_id` for debugging.
* **Performance**: Persistent connection pooling and memory-safe LRU caching.
* **Detail Levels**: Granular control over response payload size.

---

## License

MIT
