ebay_client/README.md

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:

• extract_resource_id() to pull a media resource ID from a Location header
• 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

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:

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

To generate only one API package:

& .\.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.