62 lines
2.6 KiB
Markdown
62 lines
2.6 KiB
Markdown
# 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`.
|