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:

• 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:

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