# eBay REST Client

This workspace contains a Python-first eBay REST client foundation with:

- a shared OAuth 2.0 core
- a shared HTTP transport layer
- public API wrappers per eBay REST domain
- an isolated Pydantic model generation script for each contract in this folder

Currently wired API domains include Notification, Inventory, Fulfillment, Account, Feed, and Media.

## Media Helpers

The Media wrapper includes workflow helpers on top of the raw endpoints:

- `VideoWorkflowResult` and `DocumentWorkflowResult` to return structured data from the higher-level workflows
- `extract_resource_id()` to pull a media resource ID from a `Location` header
- `guess_media_content_type()` to infer a content type from a file name when possible
- `wait_for_video()` to poll until a video reaches `LIVE` or a terminal failure state
- `wait_for_document()` to poll until a document reaches `ACCEPTED` or a terminal failure state
- `create_upload_and_wait_video()` to stage, upload, and poll a video in one call
- `create_upload_and_wait_video_from_path()` to do the same directly from a local file path
- `create_upload_and_wait_document()` to stage, upload, and poll a document in one call
- `create_upload_and_wait_document_from_path()` to do the same directly from a local file path
- `create_document_from_url_and_wait()` to create a document from a URL and poll until it is accepted
- `create_image_from_path()` and `upload_document_from_path()` for path-based local file uploads

A concrete workflow example is available in `examples/media_workflows.py` for:

- uploading an image from a file
- creating an image from a URL
- staging, uploading, and polling a document
- staging, uploading, and polling a video

## Generate Low-Level Clients

The project uses a dedicated code generation environment because the main runtime is currently on Python 3.14 while the model generator still targets earlier Python versions.

Run the generator script from the project root:

```powershell
& .\.venv\Scripts\python.exe .\scripts\generate_clients.py
```

To generate only one API package:

```powershell
& .\.venv\Scripts\python.exe .\scripts\generate_clients.py --api notification
```

This regenerates Pydantic v2 models into `ebay_client/generated/<api>/models.py`.

## Webhook Helpers

The Notification package also includes framework-agnostic webhook utilities for:

- responding to eBay challenge requests
- parsing and validating the `X-EBAY-SIGNATURE` header
- verifying signed notification payloads against the cached public key
- turning a verified notification body into a normalized `WebhookEventEnvelope`

A concrete FastAPI integration example is available in `examples/fastapi_notification_webhook.py`.