villa-market-backend-sdk 0.2.0

Python SDK and CLI for interacting with the Villa Market backend server

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

2. Configure Cognito

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

Variable	Description
VILLA_COGNITO_CLIENT_ID	Cognito app client ID
VILLA_COGNITO_USER_POOL_ID	Cognito user pool ID
VILLA_COGNITO_CLIENT_SECRET	App client secret
VILLA_COGNITO_REGION	AWS region (default ap-southeast-1)

3. Login and call APIs

from villa_backend_sdk import VillaClient, OrderBuilder

client = VillaClient.from_env()
client.login("[e-mail]", "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 [e-mail] --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

Document	Contents
Manual (S3)	Complete usage guide
docs/MANUAL.md	Manual source (repo)
docs/DESIGN.md	Architecture and data flow
docs/TESTING.md	Test strategy
docs/COGNITO_TEST.md	Shared test account
docs/CI_CD.md	CI/CD and deployment

---

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

Suite	Command
Unit	pytest tests/unit -m unit
Integration (real Cognito JWT)	pytest tests/integration -m integration
Full	pytest (72 tests)

Build and deploy the manual locally:

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

---

Architecture

Module	Responsibility
villa_backend_sdk.auth	Cognito login, SignUp, confirm
villa_backend_sdk.orders	Order builder, create/get/generate ID
villa_backend_sdk.validation	Schema + remote pricing validation
villa_backend_sdk.payments	Card token, card payment, verify
villa_backend_sdk.cli	villa command-line tool

---

License

MIT