Metadata-Version: 2.5
Name: petcareers-sdk
Version: 0.1.0
Summary: Typed synchronous and asynchronous PetCareers Partner API clients
Project-URL: Homepage, https://pet.careers/developer
Project-URL: Repository, https://github.com/PetCareers/petcareers-sdk
Project-URL: Issues, https://github.com/PetCareers/petcareers-sdk/issues
License-Expression: MIT
License-File: LICENSE
Keywords: jobs,partner-api,petcareers,sdk,veterinary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.28.1
Description-Content-Type: text/markdown

# PetCareers Python SDK

Typed synchronous and asynchronous clients for the [PetCareers Partner API](https://pet.careers/developer). Requires Python 3.11+. Distributed under MIT; see the included LICENSE.

## Install

```sh
python -m pip install petcareers-sdk
```

The package name is `petcareers-sdk`; the import name is `petcareers`.

## Synchronous client

```python
import os
from petcareers import PetCareers, PetCareersError

with PetCareers(
    api_key=os.environ["PARTNER_API_KEY"],
    environment="sandbox",
    locale="en",
) as client:
    identity = client.get_identity("clinics:read")
    clinics = client.list_clinics(limit=10)
    for clinic in client.iterate_clinics(limit=100):
        profile = client.get_clinic(clinic["connectionId"])
        # Process the authorized clinic without logging personal data.
```

## Asynchronous client

```python
import asyncio
import os
from petcareers import AsyncPetCareers

async def main():
    async with AsyncPetCareers(api_key=os.environ["PARTNER_API_KEY"]) as client:
        offers = await client.list_offers(limit=10)
        async for offer in client.iterate_offers(limit=100):
            pass  # Process each offer.

asyncio.run(main())
```

Responses preserve the wire envelope: `response["data"]` and `response["requestId"]`. List data contains `items` and `nextCursor`. Keep API keys server-side. Your key needs the scopes and clinic connections required by each operation. Use a separate production application/key with `environment="production"` when ready.

Both clients expose `get_clinic`, `get_offer`, `get_logo`, mutation operations and webhook management. `verify_webhook` verifies signed raw webhook bytes; your receiver must persist event IDs for deduplication. Catch `PetCareersError` and inspect sanitized `code`, `status`, `request_id`, `retry_after` and `current_version` rather than logging raw payloads. Reads have bounded retries; eligible idempotent writes require explicit retry opt-in. Always close clients using context managers or `close()` / `aclose()`. The SDK sends no telemetry.

## Polski

SDK wymaga Python 3.11+. Instalacja: `python -m pip install petcareers-sdk`; import: `from petcareers import PetCareers`. Licencja MIT obejmuje SDK, a dostęp do API wymaga osobnej autoryzacji.

`PetCareers` działa synchronicznie, a `AsyncPetCareers` obsługuje asyncio. Używaj `with` lub `async with`, aby zamknąć połączenia. Domyślne środowisko to sandbox; ustaw `locale="pl"` dla języka polskiego. Klucz przechowuj wyłącznie na serwerze i nadaj mu wymagane zakresy dostępu.

Odpowiedzi zawierają `data` i `requestId`; listy mają `data.items` i `data.nextCursor`. Iteratory automatycznie obsługują strony. Błędy mają typ `PetCareersError` i oczyszczone pola diagnostyczne. Nie loguj danych osobowych ani kluczy. Zapis wymaga osobnego klucza idempotencji i jawnego włączenia ponowień dla obsługiwanych operacji. `verify_webhook` weryfikuje podpis oryginalnych bajtów; odbiorca musi zapisywać identyfikatory zdarzeń, aby zapobiegać duplikatom. SDK nie wysyła telemetrii.

[English guide](https://github.com/PetCareers/petcareers-sdk/blob/main/docs/quickstart.en.md) · [Polski poradnik](https://github.com/PetCareers/petcareers-sdk/blob/main/docs/quickstart.pl.md)

Repository guides require access while the GitHub repository is private.
