# Usage Guide

## Authentication

### Login with credentials

```python
from kwork_api import KworkClient

async with await KworkClient.login("username", "password") as client:
    # Your code here
    pass
```

### Restore session from token

```python
from kwork_api import KworkClient

# Save token after first login
client = await KworkClient.login("username", "password")
token = client.token  # Save this

# Later, restore session
client = KworkClient(token="saved_token")
user = await client.user.get_info()
```

## API Groups

### Catalog API

```python
# Get catalog list
catalog = await client.catalog.get_list(page=1, category_id=1)

# Get kwork details
kwork = await client.catalog.get_details(kwork_id=123)
```

### Projects API (Freelance)

```python
# Get projects list
projects = await client.projects.get_list(page=1)

# Get your orders
my_orders = await client.projects.get_payer_orders()
```

### User API

```python
# Get user info
user = await client.user.get_info()

# Get reviews
reviews = await client.user.get_reviews(user_id=123)
```

### Reference API

```python
# Get cities
cities = await client.reference.get_cities()

# Get countries
countries = await client.reference.get_countries()

# Get categories
categories = await client.reference.get_categories()
```

### Notifications API

```python
# Get notifications
notifications = await client.notifications.get_list()

# Get dialogs
dialogs = await client.notifications.get_dialogs()
```

## Error Handling

```python
from kwork_api import KworkApiError, KworkAuthError

try:
    catalog = await client.catalog.get_list()
except KworkAuthError as e:
    print(f"Authentication failed: {e}")
except KworkApiError as e:
    print(f"API error: {e.status_code} - {e.message}")
```

## Best Practices

### Rate Limiting

Kwork doesn't have official rate limits, but be respectful:

```python
import asyncio

for page in range(1, 11):
    catalog = await client.catalog.get_list(page=page)
    await asyncio.sleep(0.5)  # 500ms delay
```

### Session Management

Always use context manager for automatic cleanup:

```python
async with await KworkClient.login("user", "pass") as client:
    # Client automatically closed
    pass
```

### Save Token

Save token after first login to avoid repeated authentication:

```python
# First login
client = await KworkClient.login("user", "pass")
save_token(client.token)  # Save to secure storage

# Later
client = KworkClient(token=load_token())
```