Metadata-Version: 2.4
Name: wex-health-sdk
Version: 0.1.0a4
Summary: Python SDK for Wex Health and Benefits Platform APIs. Provides comprehensive access to claims, business, consumer, and administrative APIs with built-in authentication, logging, and error handling.
Author-email: "Wex Inc." <gl-sdk-support@wexinc.com>
Project-URL: Homepage, https://developers.wexhealth.com
Project-URL: Documentation, https://developers.wexhealth.com/wex-health-api/sdks
Project-URL: Support, https://developers.wexhealth.com/wex-health-api/sdks/support
Keywords: OpenAPI,OpenAPI-Generator,Benefits Platform Claims API
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: urllib3<4.0.0,>=2.6.3
Requires-Dist: aiohttp>=3.13.3
Requires-Dist: aiohttp-retry>=2.8.3
Requires-Dist: pydantic<3,>=2.4.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: typing-extensions>=4.7.1
Provides-Extra: dev
Requires-Dist: pytest>=7.2.1; extra == "dev"
Requires-Dist: pytest-cov>=2.8.1; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: tox>=3.9.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Requires-Dist: types-python-dateutil>=2.8.19.14; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# wex-health-sdk

[![PyPI version](https://img.shields.io/pypi/v/wex-health-sdk.svg)](https://pypi.org/project/wex-health-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/wex-health-sdk.svg)](https://pypi.org/project/wex-health-sdk/)
[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](https://developers.wexhealth.com/wex-health-api/sdks/license-agreement)

Official Python SDK for the WEX Health and Benefits Platform APIs. Provides programmatic access to HSA, FSA, HRA management, COBRA coverage, and claims processing.

## Features

- **Async-first**: Built on `aiohttp` for high-performance async operations
- **Type-safe**: Full type hints for IDE autocompletion and static analysis
- **Resilient**: Automatic retries with exponential backoff and jitter
- **Secure**: OAuth2 Client Credentials and Bearer token authentication
- **Observable**: Structured logging with request correlation IDs

## Requirements

Python 3.9+

## Installation

```sh
pip install wex-health-sdk
```

### Primary dependencies

The SDK's primary runtime dependencies include:
- `aiohttp` >= 3.13.3
- `aiohttp-retry` >= 2.8.3
- `pydantic` >= 2.4.0

These and any additional runtime dependencies declared by the package are installed automatically when you install the SDK.

## Quick Start

```python
import os
import asyncio
from uuid import UUID
from wex_health import Configuration, ApiClient, ClaimsApi

async def main():
    config = Configuration(
        host=os.environ['WEX_API_HOST'],
        access_token=os.environ['WEX_ACCESS_TOKEN']
    )
    async with ApiClient(config) as client:
        api = ClaimsApi(client)
        # person_id must be a UUID
        person_id = UUID(os.environ['PERSON_ID'])
        claims = await api.get_claims_for_participant(person_id)
        print(f"Found {len(claims.claims)} claims")

asyncio.run(main())
```

## Authentication

The SDK supports multiple authentication methods:

### OAuth2 Client Credentials (Recommended)

```python
import os
import wex_health

configuration = wex_health.Configuration(
    host=os.environ['WEX_API_HOST'],
    oauth2_credentials={
        'client_id': os.environ['WEX_CLIENT_ID'],
        'client_secret': os.environ['WEX_CLIENT_SECRET'],
        'access_token_url': os.environ['WEX_TOKEN_URL'],
        'audience': os.environ.get('WEX_AUDIENCE')  # Optional
    }
)
```

### Bearer Token

```python
import os
import wex_health

configuration = wex_health.Configuration(
    host=os.environ['WEX_API_HOST'],
    access_token=os.environ['WEX_ACCESS_TOKEN']
)
```

## Retry Logic

The SDK implements a **layered resilience strategy** with automatic retry handling for transient failures:

### Key Features

- **Exponential Backoff with Jitter**: 500ms initial delay, 2s maximum cap
- **Smart 429 Handling**: Only retries rate limits when `Retry-After` header is present
- **Automatic Retry**: Handles 5xx errors, 408 Request Timeout automatically
- **Three-Layer Protection**: Global timeout → Retry policy → Per-request timeout
- **Server-Aware**: Respects `Retry-After` headers (capped at 30 seconds)

### Default Configuration

```python
configuration = wex_health.Configuration(
    retries=3,              # Maximum retry attempts for transient failures
    request_timeout=30.0,   # Timeout per individual HTTP request (seconds)
    overall_timeout=30.0    # Hard limit for entire operation including all retries (seconds)
)
```

> **Note**: `overall_timeout` is a hard cap. If retries would exceed this limit, the operation fails with `asyncio.TimeoutError`. For example, with `overall_timeout=30.0` and `retries=3`, if the first two attempts take 12 seconds each, the third attempt will be cancelled after 6 seconds.

### Retry Behavior

The SDK automatically retries the following scenarios:

1. **5xx Server Errors**: 500, 502, 503, 504, 507, etc.
2. **408 Request Timeout**: Client timeout waiting for response
3. **429 Rate Limiting**: Only when `Retry-After` header is present
4. **Retry-After Header**: Any response with server-provided retry guidance

**Backoff Strategy**: Exponential backoff with full jitter
- Initial delay: 500ms
- Maximum delay: 2 seconds
- Algorithm: Full jitter (randomized across entire backoff window) to prevent thundering herd

## Error Handling

The SDK raises specific exceptions for different HTTP error responses:

| Exception | HTTP Status | Description |
|-----------|-------------|-------------|
| `BadRequestException` | 400 | Invalid request parameters |
| `UnauthorizedException` | 401 | Authentication failed |
| `ForbiddenException` | 403 | Access denied |
| `NotFoundException` | 404 | Resource not found |
| `ConflictException` | 409 | Resource conflict |
| `UnprocessableEntityException` | 422 | Validation error |
| `ServiceException` | 5xx | Server error |
| `ApiException` | Other | Base exception for all API errors |

```python
from wex_health.exceptions import (
    ApiException,
    NotFoundException,
    UnauthorizedException,
    ServiceException,
)

try:
    claim = await claims_api.get_claim(person_id, claim_number)
except NotFoundException:
    print("Claim not found")
except UnauthorizedException:
    print("Check your credentials")
except ServiceException as e:
    print(f"Server error: {e.status} - retry later")
except ApiException as e:
    print(f"API Error: {e.status} - {e.reason}")
```

## Best Practices

- **Use environment variables** for credentials—never hardcode secrets
- **Use context managers** (`async with ApiClient(...)`) for automatic resource cleanup
- **Pass correlation IDs** via `x_request_id` parameter for request tracking
- **Reuse ApiClient instances** across multiple API calls for connection pooling
- **Enable debug logging** with `logging.basicConfig(level=logging.DEBUG)` when troubleshooting

## API Endpoints

All URIs are relative to the host URL you configure when creating the Configuration object.

| Class | Method | HTTP request | Description |
|-------|--------|--------------|-------------|
| *ClaimsApi* | **get_claim** | **GET** /claims/v1/consumers/{person_id}/claims/{claim_number} | Get Claim |
| *ClaimsApi* | **get_claims_for_business** | **GET** /claims/v1/businesses/{business_id}/claims | Get Claims for Business |
| *ClaimsApi* | **get_claims_for_participant** | **GET** /claims/v1/consumers/{person_id}/claims | Get Claims for Participant |
| *ClaimsApi* | **get_payees_for_participant** | **GET** /claims/v1/consumers/{person_id}/payees | Get Payees |
| *ClaimsApi* | **get_receipt_for_participant** | **GET** /claims/v1/consumers/{person_id}/receipts/{receipt_id} | Get Receipt |
| *ClaimsApi* | **get_receipts_for_participant** | **GET** /claims/v1/consumers/{person_id}/receipts | Get Receipts |
| *HealthApi* | **get_liveness** | **GET** /claims/health/liveness | Get Liveness |

## Models

- `ClaimDTO`
- `ClaimsDTO`
- `DenialReasonDTO`
- `PayeeDTO`
- `PayeesDTO`
- `ProblemDetails`
- `ReceiptDTO`
- `ReceiptsDTO`
- `RmiDTO`


## Support

To report bugs, request features, or get help with SDK integration:

- **Support Portal**: [https://developers.wexhealth.com/wex-health-api/sdks/support](https://developers.wexhealth.com/wex-health-api/sdks/support)
- **Email**: gl-sdk-support@wexinc.com

## License

Copyright (c) 2025 Wex Inc. All rights reserved. This software is proprietary and confidential.

See the [LICENSE](https://developers.wexhealth.com/wex-health-api/sdks/license-agreement) for full license terms.

