# 🎨 CreatorsArea.fr Python SDK

> Python client library for the CreatorsArea.fr job marketplace API

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 📋 Overview

**creatorsarea-py** is an unofficial Python SDK for the [CreatorsArea.fr](https://creatorsarea.fr) job marketplace API. It provides a simple and intuitive interface to fetch and interact with job offers for developers, designers, and teams in the French gaming community.

## ✨ Features

- 🔍 **Job Search** - Fetch jobs by category (Developer, Graphism, Team)
- 📊 **Filtering** - Filter by tags, budget, deadline, status
- 🎯 **Job Details** - Get complete information about specific jobs
- 🔄 **Pagination** - Handle large result sets efficiently
- 🛡️ **Error Handling** - Comprehensive exception handling
- 📝 **Type Hints** - Full typing support for better IDE integration
- ⚡ **Async Support** - (Coming soon) Async/await support

## 📦 Installation

```bash
pip install creatorsarea-py
```

### Development Installation

```bash
git clone https://github.com/Sycatle/creatorsarea-py.git
cd creatorsarea-py
pip install -e .
```

## 🚀 Quick Start

```python
from creatorsarea import CreatorsAreaClient

# Initialize the client
client = CreatorsAreaClient()

# Fetch developer jobs
jobs = client.get_jobs(category="DEVELOPER", limit=10)

for job in jobs:
    print(f"{job.title} - {job.budget}")
    print(f"URL: {job.url}")
    print(f"Tags: {', '.join(job.tags)}")
    print("---")

# Get specific job details
job = client.get_job_by_id("675d123...")
if job:
    print(f"Title: {job.title}")
    print(f"Description: {job.description}")
    print(f"Budget: {job.budget}")
    print(f"Deadline: {job.deadline}")
```

## 📚 Usage Examples

### Fetch Jobs by Category

```python
from creatorsarea import CreatorsAreaClient, Category

client = CreatorsAreaClient()

# Developer jobs
dev_jobs = client.get_jobs(category=Category.DEVELOPER)

# Graphism jobs
design_jobs = client.get_jobs(category=Category.GRAPHISM)

# Team/server jobs
team_jobs = client.get_jobs(category=Category.TEAM)
```

### Filter Jobs

```python
# Filter by minimum budget
high_budget_jobs = client.get_jobs(
    category="DEVELOPER",
    min_budget=100.0
)

# Filter non-volunteer jobs
paid_jobs = client.get_jobs(
    category="DEVELOPER",
    exclude_volunteer=True
)

# Filter by tags
lua_jobs = client.get_jobs(
    category="DEVELOPER",
    tags=["lua", "gmod"]
)
```

### Get Job Details

```python
# By ID
job = client.get_job_by_id("675d123...")

# By slug
job = client.get_job_by_slug("developpeur-lua-gmod")

if job:
    print(f"Applications: {job.applications}")
    print(f"Author: {job.author}")
    print(f"Status: {job.status}")
```

### Pagination

```python
# Get all jobs (automatic pagination)
all_jobs = client.get_all_jobs(category="DEVELOPER")

# Manual pagination
page_1 = client.get_jobs(category="DEVELOPER", page=1, per_page=20)
page_2 = client.get_jobs(category="DEVELOPER", page=2, per_page=20)
```

## 🏗️ API Reference

### `CreatorsAreaClient`

Main client class for interacting with the API.

#### Methods

##### `get_jobs(category, limit=None, **filters) -> List[Job]`

Fetch a list of jobs.

**Parameters:**
- `category` (str): Job category ("DEVELOPER", "GRAPHISM", "TEAM")
- `limit` (int, optional): Maximum number of jobs to return
- `min_budget` (float, optional): Minimum budget filter
- `max_budget` (float, optional): Maximum budget filter
- `exclude_volunteer` (bool, optional): Exclude volunteer jobs
- `tags` (List[str], optional): Filter by tags
- `status` (str, optional): Filter by status

**Returns:** List of `Job` objects

##### `get_job_by_id(job_id) -> Optional[Job]`

Fetch a specific job by its ID.

**Parameters:**
- `job_id` (str): The job ID

**Returns:** `Job` object or None

##### `get_job_by_slug(slug) -> Optional[Job]`

Fetch a specific job by its slug.

**Parameters:**
- `slug` (str): The job slug (URL-friendly identifier)

**Returns:** `Job` object or None

##### `get_all_jobs(category, **filters) -> List[Job]`

Fetch all jobs with automatic pagination.

**Parameters:**
- `category` (str): Job category
- `**filters`: Same filters as `get_jobs()`

**Returns:** List of all `Job` objects

### `Job`

Job data model.

#### Attributes

```python
job.id              # str: Unique job ID
job.title           # str: Job title
job.slug            # str: URL slug
job.url             # str: Full URL to job posting
job.description     # str: Job description
job.content         # str: Full content/details
job.category        # str: Job category
job.kind            # str: Raw kind from API
job.status          # str: Job status (ACTIVE, CLOSED, etc.)
job.budget          # str: Formatted budget string
job.budget_value    # float: Numeric budget value
job.is_volunteer    # bool: Is volunteer work
job.budget_negotiable # bool: Is budget negotiable
job.tags            # List[str]: Job tags
job.applications    # str: Application count info
job.deadline        # datetime: Application deadline
job.author          # dict: Author information
job.created_at      # datetime: Creation timestamp
job.updated_at      # datetime: Last update timestamp
```

### `Category`

Enum for job categories.

```python
Category.DEVELOPER  # Development jobs
Category.GRAPHISM   # Design/graphics jobs
Category.TEAM       # Team/server jobs
```

### Exceptions

```python
from creatorsarea import (
    CreatorsAreaException,    # Base exception
    APIError,                 # API request failed
    NotFoundError,            # Job not found
    ValidationError,          # Invalid parameters
)
```

## 🔧 Configuration

### Custom User-Agent

```python
client = CreatorsAreaClient(
    user_agent="MyBot/1.0 (contact@example.com)"
)
```

### Request Timeout

```python
client = CreatorsAreaClient(timeout=30)
```

### Base URL Override

```python
# For testing or custom endpoints
client = CreatorsAreaClient(
    base_url="https://api.creatorsarea.fr"
)
```

## 🧪 Testing

```bash
# Run tests
pytest

# Run with coverage
pytest --cov=creatorsarea

# Run specific test file
pytest tests/test_client.py
```

## 📊 Examples

See the [examples/](examples/) directory for more usage examples:

- `basic_usage.py` - Simple job fetching
- `filtering.py` - Advanced filtering examples
- `monitoring.py` - Job monitoring bot
- `discord_bot.py` - Discord integration example

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 👤 Author

**Sycatle**

- GitHub: [@Sycatle](https://github.com/Sycatle)

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## ⚠️ Disclaimer

This is an **unofficial** SDK and is not affiliated with or endorsed by CreatorsArea.fr. Use at your own risk.

## 🔗 Links

- [CreatorsArea.fr](https://creatorsarea.fr)
- [Documentation](https://creatorsarea-py.readthedocs.io) (Coming soon)
- [PyPI Package](https://pypi.org/project/creatorsarea-py/) (Coming soon)
- [Issue Tracker](https://github.com/Sycatle/creatorsarea-py/issues)

## 💬 Support

- 🐛 [Report a bug](https://github.com/Sycatle/creatorsarea-py/issues)
- 💡 [Request a feature](https://github.com/Sycatle/creatorsarea-py/issues)
- 💬 [Discussions](https://github.com/Sycatle/creatorsarea-py/discussions)

---

Made with ❤️ for the French gaming community
