A zero-dependency client for the Truemoney-Voucher API family — three backend ports share the same HTTP contract, and the client picks the fastest healthy one for you:

Features

Quick Start

Install with any Python package manager:

pip install truemoney-voucher
# or
uv add truemoney-voucher
# or
poetry add truemoney-voucher

No setup needed — Client is a ready-to-use static wrapper around an auto-configured instance:

from truemoney_voucher import Client

# auto: probes the three hosted backends and uses the fastest healthy one
result = Client.redeem("12345678901234", "0812345678")
print(result.status.code)  # e.g. "VOUCHER_NOT_FOUND", "TARGET_USER_REDEEMED"

# Liveness probe:
alive = Client.status()

# Service info:
info = Client.info()

Pin a provider (or configure your own)

from truemoney_voucher import create_client

# Pin one backend explicitly:
client = create_client(provider="nestjs")  # "go" | "nestjs" | "fastapi"

# Or bring your own deployment (overrides `provider`):
custom = create_client(
    base_url="https://api.example.com",
    timeout_ms=15_000,
)

# Client.configure() re-creates the shared instance the same way:
Client.configure(provider="fastapi")

API Reference

Static Client (no construction)

create_client(**kwargs) => TruemoneyClient

Auto provider

• On the first call (or after a 60 s cache TTL) all three backends are probed in parallel (thread pool, GET /status, 3 s probe timeout) and ranked by latency.
• Redeem, status() and info() go to the fastest healthy backend; the ranking is cached for 60 seconds.
• If a redeem fails with a network error, the client automatically retries the next healthy backend. Validation errors (TruemoneyApiError) never trigger failover — a failed redeem can't be double-redeemed, so the worst case is TARGET_USER_REDEEMED.
• client.explicit_base_url returns the base URL of an explicitly selected backend (None for auto).

client.redeem(code, mobile) => RedeemResult

Accepts a raw gift code or a full campaign URL (percent-encoded into the path — the backends preserve %2F, matching the reference CLI).

• Returns RedeemResult(ok=True, status=TrueMoneyStatus(message, code), data=...) when the upstream call succeeds.
• Raises TruemoneyApiError on validation/routing errors ({ code, message } envelopes, or upstream Spring-style error bodies, which are normalized).

client.status() => bool

True on any 2xx, False otherwise — never raises, safe for uptime checks. In auto mode, True when at least one backend is healthy.

client.info() => dict

Service name, deployed version (where exposed), and the route list.

Errors

All errors extend TruemoneyError:

from truemoney_voucher import TruemoneyApiError

try:
    Client.redeem(code, mobile)
except TruemoneyApiError as err:
    print(err.code, err.message)  # 400 "Bad Request"

TrueMoney status codes

When the upstream call succeeds, result.status.code carries TrueMoney's answer:

Testing

pip install -e ".[dev]"
pytest tests/test_client.py tests/test_auto_client.py   # offline unit tests
set LIVE=1 && pytest tests/test_live.py                 # live checks against the three hosted backends

The live suite runs status/info and an invalid-voucher check against all three Vercel deployments, plus a real upstream call.

Contributing

Contributions are welcome! Please:

1. Open an issue first for significant changes
2. Keep pytest tests green
3. Bump version in pyproject.toml together with src/truemoney_voucher/version.py

Disclaimer

For educational use or where the provider permits it. Redeeming is irreversible and governed by TrueMoney's Terms of Service. Voucher codes are cash-equivalent — never log full codes.

License

Licensed under the MIT License © 2026 ByteInDev