A. McDermott e9d9b3a5ba
feat: Payment Identifier Extension SDK - Python (#1111)
* feat(python): add payment-identifier extension types and constants

- Add PaymentIdentifierInfo and PaymentIdentifierExtension Pydantic models
- Add constants: PAYMENT_IDENTIFIER, PAYMENT_ID_MIN_LENGTH, PAYMENT_ID_MAX_LENGTH, PAYMENT_ID_PATTERN
- Define PaymentIdentifierSchema type alias

* feat(python): add payment-identifier utility functions

- Add generate_payment_id() to create UUID v4-based payment IDs
- Add is_valid_payment_id() to validate ID format (16-128 chars, alphanumeric + hyphens/underscores)

* feat(python): add payment-identifier JSON Schema definition

- Add payment_identifier_schema compliant with JSON Schema Draft 2020-12
- Schema validates required boolean and optional id string field

* feat(python): add payment-identifier validation and extraction functions

- Add ValidationResult dataclass for validation results
- Add is_payment_identifier_extension() type guard
- Add validate_payment_identifier() for full extension validation
- Add extract_payment_identifier() to extract ID from PaymentPayload
- Add extract_and_validate_payment_identifier() combined function
- Add has_payment_identifier() to check extension presence
- Add is_payment_identifier_required() to check requirement flag
- Add validate_payment_identifier_requirement() for requirement compliance

* feat(python): add payment-identifier client utilities

- Add append_payment_identifier_to_extensions() to append payment ID to extensions dict
- Only appends if server declared the extension
- Generates new ID if not provided

* feat(python): add payment-identifier resource server utilities

- Add declare_payment_identifier_extension() to create extension declaration
- Add PaymentIdentifierResourceServerExtension class implementing ResourceServerExtension protocol
- Add payment_identifier_resource_server_extension singleton instance

* feat(python): add payment-identifier extension main module

- Export all public APIs from payment-identifier extension
- Add comprehensive usage documentation with examples for servers, clients, and idempotency

* feat(python): export payment-identifier extension from extensions module

- Add payment-identifier imports and exports to main extensions __init__.py
- Export all constants, types, functions, and classes for public API

* fix(python): resolve ValidationResult type mismatch in extensions module

- Export payment_identifier.ValidationResult as ValidationResult (matches payment_identifier function return types)
- Export bazaar.ValidationResult as BazaarValidationResult for explicit bazaar usage
- Both ValidationResult classes are structurally equivalent (same dataclass fields)
- Fixes type mismatch where payment_identifier functions returned payment_identifier.ValidationResult but ValidationResult imported from x402.extensions was bazaar.ValidationResult

* refactor(python): rename payment_identifier ValidationResult to PaymentIdentifierValidationResult

- Rename ValidationResult class to PaymentIdentifierValidationResult in payment_identifier/validation.py
- Update all function return types and usages throughout validation.py
- Update exports in payment_identifier/__init__.py
- Update imports/exports in extensions/__init__.py
- Keep ValidationResult from bazaar as default export for backward compatibility
- Export PaymentIdentifierValidationResult separately for explicit payment_identifier usage
- Makes naming consistent with BazaarValidationResult pattern

* test(python): add comprehensive test suite for payment_identifier extension

- Add test_types.py: Test constants and Pydantic models
- Add test_utils.py: Test ID generation and validation functions
- Add test_validation.py: Test all validation and extraction functions
- Add test_client.py: Test client-side utilities
- Add test_server.py: Test server-side utilities
- Tests cover all major functionality including edge cases and error handling
- Follows same structure as bazaar extension tests

* fix(python): fix payment_identifier test helper and assertions

- Fix create_extension_with_id helper to handle invalid IDs for testing
- Update test assertion to check for 'identifier' in error message
- All 67 tests now passing

* fix(python): add ValidationResult alias for backward compatibility

- Add ValidationResult = BazaarValidationResult alias after bazaar import
- Fixes AttributeError when importing ValidationResult from x402.extensions
- ValidationResult was imported as BazaarValidationResult but exported in __all__
- Now both ValidationResult and BazaarValidationResult are available

* test(python): add test to verify __all__ exports are importable

- Add test_exports.py to verify all items in __all__ can be imported
- Tests that ValidationResult alias works correctly
- Tests that 'import *' works as expected
- This would have caught the ValidationResult AttributeError bug

* fix(python): make jsonschema import lazy in payment_identifier validation

- Remove module-level jsonschema import that raised ImportError
- Import jsonschema lazily only when schema validation is needed
- Return validation error instead of raising ImportError at module level
- Allows payment_identifier extension to be imported without jsonschema
- Users can still use non-validation functions without optional dependency

* fix(python): fix linting errors

- Remove unused variable in test_types.py
- Fix import sorting in extensions/__init__.py
- Add noqa comment for intentional E402 (import after alias)

* Lint

* docs(python): add payment-identifier extension examples

Add client and server examples demonstrating how to use the
payment-identifier extension for idempotent payment processing.

Client example shows:
- Generating payment IDs with generate_payment_id()
- Using on_before_payment_creation hook to inject the ID
- Making duplicate requests to demonstrate cache behavior

Server example shows:
- Declaring extension support with declare_payment_identifier_extension()
- Extracting payment IDs with extract_payment_identifier()
- Caching responses after settlement for idempotency

* Lint

* Format

* Changelog
2026-02-11 18:46:46 -05:00

51 lines
1.3 KiB
Python

import os
from dotenv import load_dotenv
from fastapi import FastAPI
from fastapi.responses import FileResponse
from fastapi.staticfiles import StaticFiles
from x402.fastapi.middleware import require_payment
from x402.types import PaywallConfig
# Load environment variables
load_dotenv()
# Get configuration from environment
NETWORK = os.getenv("NETWORK", "base-sepolia")
ADDRESS = os.getenv("ADDRESS")
CDP_CLIENT_KEY = os.getenv("CDP_CLIENT_KEY")
if not ADDRESS:
raise ValueError("Missing required environment variables")
app = FastAPI()
# Mount static files directory
app.mount("/static", StaticFiles(directory="static"), name="static")
# Apply payment middleware to browser-accessible paywalled routes
app.middleware("http")(
require_payment(
price="$0.01",
pay_to_address=ADDRESS,
path="/premium/*",
network=NETWORK,
paywall_config=PaywallConfig(
cdp_client_key=CDP_CLIENT_KEY or "",
app_name="x402 Python Example",
app_logo="/static/x402.png",
),
)
)
@app.get("/premium/content")
async def get_premium_content() -> FileResponse:
return FileResponse("static/premium.html")
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=4021)