spaps 0.1.0__tar.gz

spaps-0.1.0/.gitignore

@@ -0,0 +1,130 @@
+# Dependencies
+node_modules/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Testing
+coverage/
+*.lcov
+.nyc_output
+
+# Production builds
+dist/
+build/
+out/
+*.tsbuildinfo
+
+# Environment files
+.env
+.env.*
+*.env
+**/.env
+**/.env.*
+.env.development
+.env.production
+.env.staging
+.env.deploy
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+# Allow committed templates/examples
+!*.env.example
+!*.env.sample
+!*.env.template
+!**/.env.example
+!**/.env.sample
+!**/.env.template
+!**/.env.*.example
+!**/.env.*.sample
+!**/.env.*.template
+!**/*.env.example
+!**/*.env.sample
+!**/*.env.template
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*.swn
+.DS_Store
+
+# Debug
+debug.log
+*.log
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+# Package manager files
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Next.js specific
+.next/
+next-env.d.ts
+.vercel/
+
+# Example projects - ignore build artifacts
+examples/**/.next/
+examples/**/node_modules/
+examples/**/dist/
+examples/**/build/
+examples/**/*.log
+examples/**/.env
+examples/**/.env.local
+
+# MCP/Sweetpotato docs build
+mcp-sweetpotato-docs/node_modules/
+mcp-sweetpotato-docs/dist/
+mcp-sweetpotato-docs/build/
+mcp-sweetpotato-docs/.next/
+
+# Large test files
+*.jpg
+*.jpeg
+*.png
+*.gif
+*.bmp
+*.mp4
+*.mov
+*.avi
+*.zip
+*.tar
+*.gz
+*.rar
+
+# Database files
+*.sqlite
+*.sqlite3
+*.db
+
+# OS files
+Thumbs.db
+Desktop.ini
+
+# Backup files
+*.bak
+*.backup
+*.old
+
+# Test output
+test-results/
+playwright-report/
+playwright/.cache/
+
+# Lock files that shouldn't be committed for libraries
+# (keep package-lock.json for applications)
+# yarn.lock
+# pnpm-lock.yaml*.tgz

spaps-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 - 2025-02-14
+
+- First public release on PyPI under the name `spaps`.
+- Adds synchronous and asynchronous clients mirroring the TypeScript SDK, including
+  sessions, payments (crypto included), usage, whitelist, secure messages, and metrics helpers.
+- Provides configurable retry/backoff handling, structured logging hooks, and token storage
+  abstractions (in-memory & file-backed).
+- Ships lint (`ruff`), type checking (`mypy`), coverage enforcement, and integration smoke
+  tests wired into the release workflow.
+- Updates documentation with Python quickstart examples and a dedicated backend guide.

spaps-0.1.0/FULL_CHECKLIST.md

@@ -0,0 +1,66 @@
+# Python Client Completion Checklist
+
+## Feature Parity
+- [x] Auth: email/password login & signup helpers
+- [x] Auth: magic link flow
+- [x] Auth: logout & token revocation
+- [x] Auth: whitelist queries/mutations
+- [x] Sessions: list sessions
+- [x] Sessions: touch session endpoint
+- [x] Sessions: delete session / revoke
+- [x] Payments: usage balance/history endpoints
+- [x] Payments: update payment method
+- [x] Payments: Stripe checkout (existing)
+- [x] Payments: Stripe payment intent (existing)
+- [x] Payments: wallet deposit/status (existing)
+- [x] Payments: subscription details/cancel (existing)
+- [x] Payments: crypto invoices (create/get/reconcile)
+- [x] Payments: crypto webhooks signature helper
+- [x] Usage API: feature list/record/history wrappers
+- [x] Admin: secure messages routes
+- [x] Admin: whitelist management
+- [x] Admin: metrics endpoints
+- [ ] Docs/search/openapi utilities (if applicable)
+
+## SDK Ergonomics
+- [x] Token storage abstraction (file/memory/extensible)
+- [x] Retry/backoff policy with configurable strategy
+- [x] Logging hooks & structured errors
+- [x] Async client variants (optional dependency)
+- [x] Type hints/completion for all public APIs
+- [x] Rich README with quickstart & API reference
+- [ ] CHANGELOG.md with semantic version entries
+
+## Testing & Quality
+- [x] Integration smoke tests using mock server
+- [x] Coverage tracking / threshold enforcement
+- [x] Type checking (mypy or pyright)
+- [x] Lint/format (ruff or black) configuration
+- [x] Twine check in release flow
+- [x] CI matrix for Python 3.9-3.12
+
+## Documentation Sync
+- [x] Update SDK_QUICKSTART with Python section
+- [x] Add dedicated guide `docs/guides/python-backend.md`
+- [x] Ensure API docs link to Python examples (in progress)
+- [x] Update docs/manifest entries for all endpoints
+- [x] Reference Python client in AGENTS documentation
+
+## Automation & CI/CD
+- [x] Add `prepush` hook entry for `npm run test:python-client`
+- [x] Add npm scripts for build/release (`build:python-client`, `publish:python-client`)
+- [x] GitHub Actions workflow for lint/test/build (`.github/workflows/python-client.yml`)
+- [x] Release workflow with PyPI token (manual trigger)
+- [ ] Dependabot/Renovate rules for Python deps (optional)
+- [ ] Release checklist enforced (link in docs)
+
+## Release Readiness
+- [ ] Decide package registry (PyPI vs internal)
+- [ ] Configure credentials/secrets for publishing
+- [ ] Version compatibility policy with backend
+- [ ] Beta release announcement plan
+- [ ] Support channel / issue templates updated
+
+## Post-Launch
+- [ ] Monitor downloads/errors
+- [ ] Collect feedback for next iteration

spaps-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Sweet Potato Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

spaps-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: spaps
+Version: 0.1.0
+Summary: Sweet Potato Authentication & Payment Service Python client
+Project-URL: Homepage, https://api.sweetpotato.dev
+Project-URL: Repository, https://github.com/sweet-potato/spaps
+Author-email: Sweet Potato Team <support@sweetpotato.dev>
+License: MIT License
+        
+        Copyright (c) 2025 Sweet Potato Team
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+License-File: LICENSE
+Keywords: authentication,payments,spaps,sweet-potato
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.9
+Requires-Dist: httpx<0.28.0,>=0.27.0
+Requires-Dist: pydantic<3.0.0,>=2.7.0
+Provides-Extra: dev
+Requires-Dist: build<2.0.0,>=1.2.1; extra == 'dev'
+Requires-Dist: httpx<0.28.0,>=0.27.0; extra == 'dev'
+Requires-Dist: mypy<2.0.0,>=1.10.0; extra == 'dev'
+Requires-Dist: pydantic<3.0.0,>=2.7.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx<0.23.0,>=0.22.0; extra == 'dev'
+Requires-Dist: ruff<1.0.0,>=0.5.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+---
+id: spaps-python-sdk
+title: Sweet Potato Python Client
+category: sdk
+tags:
+  - sdk
+  - python
+  - client
+ai_summary: |
+  Explains installation, configuration, and usage patterns for the spaps Python
+  SDK, including environment setup, async support, and integration guidance for
+  backend services.
+last_updated: 2025-02-14
+---
+
+# Sweet Potato Python Client
+
+> Python SDK for the Sweet Potato Authentication & Payment Service (SPAPS).
+
+This package is under active development. Follow the TDD plan in `TDD_PLAN.md`
+to track progress and upcoming milestones.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install spaps
+```
+
+For local development inside this repository:
+
+```bash
+pip install -e .[dev]
+```
+
+## Development
+
+```bash
+pytest
+```
+
+### Available clients
+
+- `AuthClient` – wallet, email/password, and magic link flows
+- `SessionsClient` – current session, validation, listing, revocation
+- `PaymentsClient` – checkout sessions, wallet deposits, crypto invoices
+- `UsageClient` – feature usage snapshots, recording, aggregated history
+- `SecureMessagesClient` – encrypted message creation and retrieval
+- `MetricsClient` – health and metrics convenience helpers
+
+### Quickstart
+
+```python
+from spaps_client import SpapsClient
+
+spaps = SpapsClient(base_url="http://localhost:3300", api_key="test_key_local_dev_only")
+
+# Authenticate (tokens are persisted automatically)
+spaps.auth.sign_in_with_password(email="user@example.com", password="Secret123!")
+
+# Call downstream services using the stored access token
+current = spaps.sessions.get_current_session()
+print(current.session_id)
+
+checkout = spaps.payments.create_checkout_session(
+    price_id="price_123",
+    mode="subscription",
+    success_url="https://example.com/success",
+    cancel_url="https://example.com/cancel",
+)
+print(checkout.checkout_url)
+
+spaps.close()
+```
+
+Configure retry/backoff and structured logging when constructing the client:
+
+```python
+from spaps_client import SpapsClient, RetryConfig, default_logging_hooks
+
+spaps = SpapsClient(
+    base_url="http://localhost:3300",
+    api_key="test_key_local_dev_only",
+    retry_config=RetryConfig(max_attempts=4, backoff_factor=0.2),
+    logging_hooks=default_logging_hooks(),
+)
+```
+
+### Async Quickstart
+
+```python
+import asyncio
+from spaps_client import AsyncSpapsClient
+
+async def main():
+    client = AsyncSpapsClient(base_url="http://localhost:3300", api_key="test_key_local_dev_only")
+    try:
+        await client.auth.sign_in_with_password(email="user@example.com", password="Secret123!")
+        current = await client.sessions.list_sessions()
+        print(len(current.sessions))
+    finally:
+        await client.aclose()
+
+asyncio.run(main())
+```
+
+### Useful Scripts
+
+```bash
+npm run test:python-client   # run pytest from repo root
+npm run lint:python-client   # ruff linting
+npm run typecheck:python-client # mypy type checking
+npm run build:python-client  # build wheel/sdist and run twine check
+npm run publish:python-client # build and upload via twine (requires PYPI_TOKEN)
+```
+
+Refer to `docs/RELEASE_CHECKLIST.md` for the full release process.
+
+Refer to the repository root documentation for integration details.
+
+## Documentation
+
+- [Quickstart (Python section)](../../docs/getting-started/quickstart.md#python-example---using-spaps)
+- [Python Backend Integration Guide](../../docs/guides/python-backend.md)
+- API references under `docs/api/` include Python usage snippets for sessions, payments, usage, whitelist, and secure messages.

spaps-0.1.0/README.md

@@ -0,0 +1,126 @@
+---
+id: spaps-python-sdk
+title: Sweet Potato Python Client
+category: sdk
+tags:
+  - sdk
+  - python
+  - client
+ai_summary: |
+  Explains installation, configuration, and usage patterns for the spaps Python
+  SDK, including environment setup, async support, and integration guidance for
+  backend services.
+last_updated: 2025-02-14
+---
+
+# Sweet Potato Python Client
+
+> Python SDK for the Sweet Potato Authentication & Payment Service (SPAPS).
+
+This package is under active development. Follow the TDD plan in `TDD_PLAN.md`
+to track progress and upcoming milestones.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install spaps
+```
+
+For local development inside this repository:
+
+```bash
+pip install -e .[dev]
+```
+
+## Development
+
+```bash
+pytest
+```
+
+### Available clients
+
+- `AuthClient` – wallet, email/password, and magic link flows
+- `SessionsClient` – current session, validation, listing, revocation
+- `PaymentsClient` – checkout sessions, wallet deposits, crypto invoices
+- `UsageClient` – feature usage snapshots, recording, aggregated history
+- `SecureMessagesClient` – encrypted message creation and retrieval
+- `MetricsClient` – health and metrics convenience helpers
+
+### Quickstart
+
+```python
+from spaps_client import SpapsClient
+
+spaps = SpapsClient(base_url="http://localhost:3300", api_key="test_key_local_dev_only")
+
+# Authenticate (tokens are persisted automatically)
+spaps.auth.sign_in_with_password(email="user@example.com", password="Secret123!")
+
+# Call downstream services using the stored access token
+current = spaps.sessions.get_current_session()
+print(current.session_id)
+
+checkout = spaps.payments.create_checkout_session(
+    price_id="price_123",
+    mode="subscription",
+    success_url="https://example.com/success",
+    cancel_url="https://example.com/cancel",
+)
+print(checkout.checkout_url)
+
+spaps.close()
+```
+
+Configure retry/backoff and structured logging when constructing the client:
+
+```python
+from spaps_client import SpapsClient, RetryConfig, default_logging_hooks
+
+spaps = SpapsClient(
+    base_url="http://localhost:3300",
+    api_key="test_key_local_dev_only",
+    retry_config=RetryConfig(max_attempts=4, backoff_factor=0.2),
+    logging_hooks=default_logging_hooks(),
+)
+```
+
+### Async Quickstart
+
+```python
+import asyncio
+from spaps_client import AsyncSpapsClient
+
+async def main():
+    client = AsyncSpapsClient(base_url="http://localhost:3300", api_key="test_key_local_dev_only")
+    try:
+        await client.auth.sign_in_with_password(email="user@example.com", password="Secret123!")
+        current = await client.sessions.list_sessions()
+        print(len(current.sessions))
+    finally:
+        await client.aclose()
+
+asyncio.run(main())
+```
+
+### Useful Scripts
+
+```bash
+npm run test:python-client   # run pytest from repo root
+npm run lint:python-client   # ruff linting
+npm run typecheck:python-client # mypy type checking
+npm run build:python-client  # build wheel/sdist and run twine check
+npm run publish:python-client # build and upload via twine (requires PYPI_TOKEN)
+```
+
+Refer to `docs/RELEASE_CHECKLIST.md` for the full release process.
+
+Refer to the repository root documentation for integration details.
+
+## Documentation
+
+- [Quickstart (Python section)](../../docs/getting-started/quickstart.md#python-example---using-spaps)
+- [Python Backend Integration Guide](../../docs/guides/python-backend.md)
+- API references under `docs/api/` include Python usage snippets for sessions, payments, usage, whitelist, and secure messages.

spaps-0.1.0/TDD_PLAN.md

@@ -0,0 +1,103 @@
+# Sweet Potato Python Client – TDD Plan
+
+## Objectives
+- Deliver a first-party Python package that mirrors the developer experience of the JavaScript `spaps-sdk`, optimized for backend/server use.
+- Ship production-ready wheels (PyPI-compatible) with type hints, deterministic tests, and docs that stay aligned with SPAPS API changes.
+- Follow SPAPS workflow: tests first, minimal implementation, docs/manifest updates.
+
+## Target Package Layout
+```
+packages/python-client/
+├── pyproject.toml            # Build metadata (PEP 621), poetry/pdm backend TBD
+├── README.md                 # Usage, examples, API docs
+├── src/
+│   └── spaps_client/
+│       ├── __init__.py
+│       ├── config.py         # Env + settings management
+│       ├── http.py           # HTTP client abstraction (requests/httpx)
+│       ├── auth.py           # Token lifecycle helpers
+│       ├── sessions.py       # Session validation helpers
+│       ├── payments/         # Future Stripe/crypto modules
+│       └── errors.py         # Rich exceptions mapped from SPAPS error payloads
+├── tests/
+│   ├── conftest.py
+│   ├── fixtures/             # Shared mocks (responses/httpx respx)
+│   ├── unit/
+│   └── integration/
+└── docs/
+    └── python-client.md      # Mirrors JS SDK quickstart, with “Related Internals”
+```
+
+## Tooling Decisions (to validate with TDD)
+- **HTTP**: `httpx` (sync + async) for flexible usage. Mock with `respx`.
+- **Serialization**: `pydantic` models for typed responses & validation.
+- **Testing**: `pytest` with `pytest-asyncio`, `respx`, and `pytest-cov`.
+- **Packaging**: `pyproject.toml` + `hatchling` (lightweight) or `poetry` backend.
+- **CI hooks**: ensure compatibility with existing npm scripts (`npm run verify:deps`, `npm run docs:validate-all`).
+
+## Milestones & TDD Steps
+
+### Milestone 0 – Scaffolding Tests
+1. Write failing tests asserting package metadata exists (`pyproject.toml`, version exposed in `spaps_client.__version__`).
+2. Add failing doc-validation test ensuring README code snippets compile (use doctest/pytest).
+
+### Milestone 1 – Auth Token Lifecycle
+- **Tests first**:
+  - `tests/unit/test_auth_nonce.py`: expects `AuthClient.request_nonce` to POST `/api/auth/nonce` with API key headers and return nonce/message/expiry.
+  - `tests/unit/test_auth_verify.py`: ensures `verify_wallet` sends signature payload, handles success/failure, raises custom exceptions on 4xx/5xx.
+  - `tests/unit/test_auth_refresh.py`: covers refresh flow and token storage abstraction.
+  - Mock HTTP responses via `respx` fixtures; assert request payloads match SPAPS API schemas (see `src/routes/auth.ts` & `docs/api/wallet-authentication.md`).
+- **Implementation**: minimal code to satisfy tests; introduce data models (`NonceResponse`, `TokenPair`).
+- **Docs**: update `docs/api/wallet-authentication.md` “Related Internals” with Python package reference once tests pass.
+
+### Milestone 2 – Session Validation
+- Tests:
+  - `tests/unit/test_sessions_validate.py`: `SessionsClient.validate()` hitting `/api/sessions/validate`; returns structured session metadata.
+  - `tests/unit/test_sessions_current.py`: ensures caching of current session call and error translation.
+  - Negative tests for expired/invalid JWT (anticipate `401` with `INVALID_SESSION` code).
+- Implementation: add module sto stub for session operations.
+- Docs: extend `docs/api/sessions.md` with Python snippets; update `docs/manifest.json` entries for `/api/sessions/*` to include new tests.
+
+### Milestone 3 – Configuration & Environment
+- Tests:
+  - `tests/unit/test_config.py`: default API URL/key from env (`SPAPS_API_URL`, `SPAPS_API_KEY`), fallback to local defaults.
+  - `tests/unit/test_http_client.py`: HTTP timeout, retry/backoff configuration.
+- Implementation: config objects, HTTP wrapper (sync), optional async variant (guarded by extra dependency `httpx[http2]`).
+- Docs: add Python-specific environment guidance to `.env.example` (commented) & new doc page `docs/guides/python-backend.md`.
+
+### Milestone 4 – Packaging & Distribution
+- Tests:
+  - `tests/integration/test_build.py`: invokes `python -m build` (or backend equivalent) and asserts wheel/sdist produced in `dist/`.
+  - `tests/integration/test_installation.py`: installs built wheel into temp venv to ensure imports succeed.
+- Implementation: finalize `pyproject.toml`, include license classifiers, add `__version__`.
+- Docs: README badges, release checklist in `docs/AGENTS_CC.md`.
+
+### Milestone 5 – Optional Features
+- Payments (Stripe, crypto), admin methods, usage tracking—mirror JavaScript SDK priorities. Each feature enters with:
+  - Route-level tests hitting recorded JSON fixtures.
+  - Error regression tests (403, rate limits).
+  - Docs updates (API refs + manifest).
+
+## Testing Strategy
+- Run targeted suites via `pytest tests/unit` within package.
+- Add npm script wrapper (`"test:python-client": "cd packages/python-client && pytest -q"` ) so CI integrates seamlessly.
+- Ensure no live network calls: respx strictly intercepts HTTPX; add guard test (`respx.assert_all_called()`).
+- For crypto/webhook features, snapshot expected request bodies (JSON fixtures under `tests/fixtures`).
+
+## Documentation & Manifest Updates
+- When features land, update:
+  - `docs/manifest.json`: add Python client tests under relevant endpoints.
+  - `docs/api/*`: include “Python Backend Example” sections.
+  - `SDK_QUICKSTART.md`: cross-link to new Python Quickstart.
+- Maintain changelog (`packages/python-client/CHANGELOG.md`) aligned with releases.
+
+## Outstanding Questions / Follow-ups
+1. Packaging backend: prefer `hatchling` (minimal) vs `poetry`? Decide before Milestone 0 tests.
+2. Async support: ship in v0.1 or defer?
+3. Token storage interface: simple return dict vs pluggable storage (Redis, DB). Align with backend needs.
+4. Release automation: integrate with existing release scripts (`scripts/`) or add GitHub workflow?
+
+## Next Steps
+1. Confirm tooling choices (httpx, hatchling) with project maintainers.
+2. Create initial test scaffolding (Milestone 0) and fail CI intentionally to drive implementation.
+3. Schedule documentation tasks to coincide with feature milestones so manifest stays accurate.

spaps-0.1.0/TODO.md

@@ -0,0 +1,39 @@
+# Python Client TODO
+
+## Milestone 0 – Scaffolding
+- [x] Confirm packaging backend choice (`hatchling`) and document rationale
+- [x] Add initial failing metadata tests (`pyproject` presence, `__version__` export)
+- [x] Implement minimal scaffolding to satisfy metadata tests (pyproject, version module)
+
+## Milestone 1 – Auth Token Lifecycle
+- [x] Design response models for nonce/token flows (pydantic)
+- [x] Add failing auth tests (`request_nonce`, `verify_wallet`, `refresh_tokens`)
+- [x] Implement auth client to satisfy tests using `httpx`
+- [x] Document Python auth flow examples in `docs/api/wallet-authentication.md`
+
+## Milestone 2 – Session Validation
+- [x] Add failing session validation tests (`validate`, `current`)
+- [x] Implement sessions module with structured responses
+- [x] Update Sessions docs and manifest entries with Python references
+
+## Milestone 3 – Configuration & Environment
+- [x] Add failing config tests (env defaults, timeouts, retries)
+- [x] Implement configuration module and HTTP client abstraction
+- [x] Extend `.env.example` tips + add new Python backend doc
+
+## Milestone 4 – Packaging & Distribution
+- [x] Add build/install integration tests (`python -m build`, temp venv)
+- [x] Finalize metadata (classifiers, dependencies, extras)
+- [x] Draft release checklist in docs
+
+## Milestone 5 – Payments & Usage
+- [x] Identify priority routes (Stripe checkout, balance, usage reporting)
+- [x] Add failing tests for `PaymentsClient.create_checkout_session`
+- [x] Add failing tests for balance/usage endpoints
+- [x] Implement payments client with models & error handling
+- [x] Update payments docs/manifest with Python references
+
+## Ongoing
+- [ ] Keep changelog up to date (`packages/python-client/CHANGELOG.md`)
+- [ ] Wire pytest command into repo scripts/CI
+- [ ] Align SDK and Python docs for every new feature