Metadata-Version: 2.4
Name: hh-api-client
Version: 0.1.6
Summary: Synchronous, typed HeadHunter (hh.uz / hh.ru) API client with safe token handling and Django integration.
Author-email: Firdavs <jalolov.firdavs0809@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/your-username/hh-api-client
Project-URL: Repository, https://github.com/your-username/hh-api-client
Project-URL: Issues, https://github.com/your-username/hh-api-client/issues
Keywords: headhunter,hh.ru,hh.uz,api,client,recruitment
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Provides-Extra: django
Requires-Dist: django>=3.2; extra == "django"

# hh-api-client

Synchronous, typed HeadHunter (hh.uz / hh.ru) API client with safe token handling and first‑class Django support.

**Short overview (EN)**  
- Lightweight client on top of `requests` (no async, no heavy deps).  
- Works with both raw OAuth2 access tokens and pluggable token providers.  
- Designed to integrate cleanly with Django models like `OrganizationHHAccount`.  
- Helpful high‑level methods for vacancies, resumes, negotiations, and employer metadata.

**Кратко по‑русски (RU)**  
`hh-api-client` — это простой синхронный Python‑клиент для HeadHunter (hh.uz / hh.ru) на базе `requests`,  
который безопасно работает с OAuth2‑токенами и легко встраивается в Django‑проекты.

**Qisqacha tavsif (UZ)**  
`hh-api-client` — bu HeadHunter (hh.uz / hh.ru) bilan ishlash uchun `requests` asosida yozilgan oddiy va ishonchli Python kliеnti.  
Django loyihalaringizda HH hisoblari va tokenlarini boshqarish uchun qulay.

## Requirements

- Python **3.9+**
- `requests>=2.31.0` (installed automatically with `pip install hh-api-client`)
- Optional: `django>=3.2` if you want to use the Django integration pattern

## Installation

```bash
pip install hh-api-client
```

From a Git repository (for example, the main GitHub repo):

```bash
pip install git+https://github.com/your-username/hh-api-client.git
```

For local development:

```bash
pip install -e .
```

## Quick start

```python
from hh_api_client import HHAPIClient

client = HHAPIClient(access_token="YOUR_HH_ACCESS_TOKEN")

employer = client.get_employer_info()
print(employer["id"], employer["name"])
```

### With a token provider (recommended)

You can pass any object that implements:

- `get_valid_access_token() -> str`
- `refresh_access_token() -> str`

This matches your existing `OrganizationHHAccount` pattern.

```python
from hh_api_client import HHAPIClient

client = HHAPIClient(organization_hh_account=my_hh_account_instance)

# Example: create vacancy
vacancy_data = {
    "name": "Python Developer",
    "description": "<p>We are looking for a Python developer...</p>",
    "area": {"id": "2759"},  # e.g. Tashkent
    "employment": {"id": "full"},
    "schedule": {"id": "fullDay"},
}

response = client.create_vacancy(vacancy_data)
print(response["id"])
```

## Django integration example

Assuming you have a model like `OrganizationHHAccount` with methods:

- `get_valid_access_token()`
- `refresh_access_token()`

and you store it per organization:

```python
from hh_api_client import HHAPIClient
from organization_app.models import OrganizationHHAccount


def get_hh_client_for_organization(organization) -> HHAPIClient:
    hh_account = OrganizationHHAccount.objects.get(organization=organization, archived=False)
    return HHAPIClient(organization_hh_account=hh_account)
```

### Configuring base URL (hh.uz vs hh.ru)

By default this client uses the Uzbekistan API base URL `https://api.hh.uz`
because that is a common production setup.

If you need to change it (for example to `https://api.hh.ru`), use `HHAPIClientConfig`:

```python
from django.conf import settings
from hh_api_client import HHAPIClient, HHAPIClientConfig
from organization_app.models import OrganizationHHAccount


def get_hh_client_for_organization(organization) -> HHAPIClient:
    hh_account = OrganizationHHAccount.objects.get(organization=organization, archived=False)
    config = HHAPIClientConfig(base_url=getattr(settings, "HH_API_BASE_URL", "https://api.hh.uz"))
    return HHAPIClient(organization_hh_account=hh_account, config=config)
```

You can wire it to your existing settings:

```python
# settings/base.py
HH_CLIENT_ID = env.str("HH_CLIENT_ID", default="")
HH_CLIENT_SECRET = env.str("HH_CLIENT_SECRET", default="")
HH_REDIRECT_URI = env.str("HH_REDIRECT_URI", default="")
HH_API_BASE_URL = "https://api.hh.uz"  # or api.hh.ru
HH_OAUTH_BASE_URL = "https://hh.uz"
```

Then your existing usage in signal handlers and DRF views can stay almost the same, just update the import:

```python
from hh_api_client import HHAPIClient
```

## Safety and error handling

- No secrets (tokens) are ever logged.
- Network errors raise `requests.RequestException`.
- API-level errors raise `hh_api_client.HHAPIError` with a sanitized message.
- Automatic token refresh is attempted once on `401` responses when a token provider is used.

## Endpoints covered

High-level helpers currently implemented:

- `get_user_info()`
- `get_employer_info()`
- `get_managers()`
- `get_default_manager_id()`
- `get_employer_services()`
- `get_publication_status()`
- `test_connection()`

Vacancies:

- `create_vacancy()`
- `update_vacancy()`
- `archive_vacancy()`
- `publish_vacancy()`
- `extend_vacancy()`
- `get_vacancy()`
- `get_vacancies()`

Resumes:

- `search_resumes()`
- `get_resume()`

Negotiations:

- `get_negotiations()`
- `get_vacancy_candidates()`

## Releasing (for maintainers)

This project is configured to publish using GitHub Actions and PyPI's OpenID Connect (OIDC) publisher.

- A GitHub Actions workflow lives at `.github/workflows/workflow.yml`.
- When you push a tag like `v0.1.0` to the `hh-api-client` repository on GitHub, the workflow:
  - Builds the package with `python -m build`.
  - Publishes the distributions to **TestPyPI** (environment `testpypi`).
  - Then publishes the same build to **PyPI** (environment `pypi`).

To cut a new release:

1. Bump the version in `pyproject.toml`.
2. Commit and push to `main`.
3. Create and push a tag, e.g.:

   ```bash
   git tag v0.1.2
   git push origin v0.1.2
   ```

4. Wait for the GitHub Actions workflow to complete; the new version will appear on both TestPyPI and PyPI (assuming both publishers are configured).
