Villa Market Backend SDK

Python SDK and CLI for the Villa Market backend: Cognito authentication, order building, validation, and card payment.

User Manual (hosted)

Read the full manual on S3

The manual covers installation, Cognito login/SignUp, order building, pre-payment validation, card payment, CLI commands, environment variables, and troubleshooting. It is rebuilt and deployed to S3 automatically when docs change on main.

Quick start

1. Install

pip install villa-market-backend-sdk

Python import: from villa_backend_sdk import VillaClient

2. Configure Cognito

cp .env.example .env
# Set VILLA_COGNITO_CLIENT_SECRET from Cognito → Show client secret
set -a && source .env && set +a

3. Login and call APIs

from villa_backend_sdk import VillaClient, OrderBuilder

client = VillaClient.from_env()
client.login("user@example.com", "password")  # attaches JWT to all requests

order = (
    OrderBuilder()
    .with_ids(order_id="order-1", owner_id="owner-1", basket_id="basket-1")
    .with_branch("1000")
    .add_product(cprcode=25281, quantity=1)
    .with_payment_totals(grand_total=174.0)
    .build()
)

result = client.pre_payment.validate(order, expected_grand_total=174.0)
print(result.valid)

Verify login:

python3 scripts/smoke_test_cognito_login.py

CLI

villa auth login --username user@example.com --password 'secret'
villa health
villa order validate-schema --file tests/fixtures/goodSample.json
villa validate pre-payment --file tests/fixtures/goodSample.json --expected-grand-total 500

See the manual for the full CLI reference.

Documentation

Development

git clone https://github.com/villa-market/villa-backend-sdk-1.git
cd villa-backend-sdk-1
pip install -e ".[dev]"
set -a && source .env && set +a
pytest

Build and deploy the manual locally:

python3 scripts/build_manual_site.py
python3 scripts/deploy_manual_s3.py

Architecture

License

MIT