Metadata-Version: 2.2
Name: villa-market-backend-sdk
Version: 0.2.0
Summary: Python SDK and CLI for interacting with the Villa Market backend server
Author-email: Villa Market <nwanavit@hatari.cc>
License: MIT
Project-URL: Homepage, https://github.com/villa-market/villa-backend-sdk-1
Project-URL: Repository, https://github.com/villa-market/villa-backend-sdk-1
Project-URL: Issues, https://github.com/villa-market/villa-backend-sdk-1/issues
Keywords: villa,villamarket,payment,ordering,sdk,cli,cognito
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.1
Requires-Dist: pydantic>=2.6.1
Requires-Dist: click>=8.1.0
Requires-Dist: boto3>=1.34.0
Requires-Dist: jsonschema>=4.21.0
Requires-Dist: PyYAML>=6.0.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: moto[cognitoidp]>=5.0.0; extra == "dev"
Requires-Dist: responses>=0.25.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"

# Villa Market Backend SDK

Python SDK and CLI for the [Villa Market](https://shop.villamarket.com) backend: Cognito authentication, order building, validation, and card payment.

## User Manual (hosted)

**[Read the full manual on S3](http://villa-market-backend-sdk-manual.s3-website-ap-southeast-1.amazonaws.com/latest/index.html)**

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

```bash
pip install villa-market-backend-sdk
```

### 2. Configure Cognito

```bash
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

```python
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:

```bash
python3 scripts/smoke_test_cognito_login.py
```

---

## CLI

```bash
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](http://villa-market-backend-sdk-manual.s3-website-ap-southeast-1.amazonaws.com/latest/index.html) for the full CLI reference.

---

## Documentation

| Document | Contents |
| --- | --- |
| **[Manual (S3)](http://villa-market-backend-sdk-manual.s3-website-ap-southeast-1.amazonaws.com/latest/index.html)** | Complete usage guide |
| [docs/MANUAL.md](docs/MANUAL.md) | Manual source (repo) |
| [docs/DESIGN.md](docs/DESIGN.md) | Architecture and data flow |
| [docs/TESTING.md](docs/TESTING.md) | Test strategy |
| [docs/COGNITO_TEST.md](docs/COGNITO_TEST.md) | Shared test account |
| [docs/CI_CD.md](docs/CI_CD.md) | CI/CD and deployment |

---

## Development

```bash
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:

```bash
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
