Metadata-Version: 2.5
Name: petcareers-sdk
Version: 0.2.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.

## Prepared 0.2.0 / Przygotowana wersja 0.2.0

0.1.0 is already published on npm and PyPI. 0.2.0 is prepared locally and is NOT published; install its local tarball/wheel to use the APIs below. Build with `npm run build` and `npm pack --workspace @petcareers/sdk --pack-destination dist`. Ordinary identity calls remain read-only.

0.1.0 jest już opublikowana w npm i PyPI. 0.2.0 jest przygotowana lokalnie i NIE jest opublikowana; nowe API wymagają instalacji lokalnego tgz/wheel. Budowanie: `npm run build` i `npm pack --workspace @petcareers/sdk --pack-destination dist`. Zwykłe wywołanie identity wykonuje wyłącznie odczyt.

The SDK automatically sends `X-PetCareers-SDK: typescript/0.2.0` or `python/0.2.0` from package metadata. Optional `sandboxRunId` / `sandbox_run_id` must be a UUID and is rejected in production; `X-PetCareers-Test-Run` is correlation metadata and grants no authority. Custom fetch/HTTPX transports, credentials, retries and idempotency behavior are preserved.

SDK automatycznie wysyła wersję z metadanych pakietu. Opcjonalne `sandboxRunId` / `sandbox_run_id` musi być UUID i jest odrzucane w produkcji; nagłówek przebiegu służy tylko korelacji i nie nadaje uprawnień. Własne transporty fetch/HTTPX, klucze, ponowienia i idempotencja zachowują dotychczasowe działanie.

```ts
const client = new PetCareers({ apiKey, sandboxRunId: runId });
await client.acknowledgeConsentCallback({ receipt });
```

```python
with PetCareers(api_key=api_key, sandbox_run_id=run_id) as client:
    client.acknowledge_consent_callback(receipt=receipt)
# AsyncPetCareers exposes the same keyword method, awaited.
```

Acknowledgement sends strict `{receipt}` to `POST /api/partner/v1/{environment}/consents/acknowledge` with `clinics:write`. Read the 64 lowercase hex token from your own registered callback's `receipt` query parameter, validate your initiating consent state, and acknowledge within 10 minutes. Never log the token, callback URL or state. A valid replay is 200; invalid/expired/stale/wrong-scope receipts are409 after authentication; malformed input is400. SDK validation rejects malformed receipt input locally. This POST does not automatically retry; a caller may explicitly repeat the same receipt after a lost response. Success retains `{data:{acknowledged:true},requestId}`. Denied consent is not successful activation.

Potwierdzenie wysyła ścisłe `{receipt}` do tego endpointu z `clinics:write`. Odczytaj token64 małych znaków hex z parametru `receipt` własnego zarejestrowanego callback, sprawdź stan rozpoczętej zgody i potwierdź w ciągu10 minut. Nie loguj tokenu, adresu callback ani stanu. Poprawne powtórzenie zwraca200; błędny/wygasły/nieaktualny token lub zakres zwraca409 po uwierzytelnieniu; błędny format400. SDK odrzuca błędny format lokalnie. POST nie ponawia automatycznie; po utracie odpowiedzi można jawnie powtórzyć ten sam token. Odmowa zgody nie oznacza aktywacji.
