solvapay-python 0.7.2__tar.gz → 0.9.0__tar.gz

solvapay_python-0.9.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,27 @@
+name: Bug Report
+description: Something broken in the SDK
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: Please fill in the details below.
+  - type: input
+    id: version
+    attributes:
+      label: SDK version
+      placeholder: "0.8.0"
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: What did you expect vs what actually happened?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal repro
+      description: Minimal Python snippet to reproduce
+      render: python

solvapay_python-0.9.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,23 @@
+name: Feature Request
+description: Suggest a new capability
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+    validations:
+      required: true
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      options:
+        - Nice to have
+        - Blocking a use-case

solvapay_python-0.9.0/.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,14 @@
+name: Question
+description: How do I...?
+labels: [question]
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: What are you trying to do?
+    validations:
+      required: true
+  - type: textarea
+    id: tried
+    attributes:
+      label: What have you tried?

solvapay_python-0.9.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## What
+
+<!-- Brief description of the change -->
+
+## Why
+
+<!-- Problem it solves or feature it adds -->
+
+## Checklist
+
+- [ ] Tests added / updated
+- [ ] `CHANGELOG.md` entry added
+- [ ] Layer DAG respected (`uv run lint-imports` passes)
+- [ ] If new public exports: `tools/api_baseline.json` updated
+- [ ] Docs updated (if public API changed)

solvapay_python-0.9.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - ci

solvapay_python-0.9.0/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        include:
+          # Linux — full Python matrix
+          - os: ubuntu-latest
+            python-version: "3.10"
+          - os: ubuntu-latest
+            python-version: "3.11"
+          - os: ubuntu-latest
+            python-version: "3.12"
+          # macOS — 3.12 only
+          - os: macos-latest
+            python-version: "3.12"
+          # Windows — 3.12 only
+          - os: windows-latest
+            python-version: "3.12"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - name: Set Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --all-extras --dev
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+      - run: uv run mypy src
+      - run: uv run pytest -v
+      - run: uv run python tools/api_diff.py
+      - run: uv run lint-imports --config tools/importlinter.cfg
+      - run: uv run python tools/lint_invariants.py
+      - name: pip-audit
+        run: uv run pip-audit
+      - name: Check changelog fragment on PRs touching src/
+        if: github.event_name == 'pull_request'
+        run: |
+          changed=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
+          if echo "$changed" | grep -q "^src/"; then
+            if ! echo "$changed" | grep -q "^changelog.d/"; then
+              echo "ERROR: src/ modified without a changelog.d/ fragment. Add one — see changelog.d/README.md"
+              exit 1
+            fi
+          fi

solvapay_python-0.9.0/.github/workflows/contract.yml

@@ -0,0 +1,22 @@
+name: contract
+
+on:
+  schedule:
+    - cron: "0 2 * * *"  # nightly at 02:00 UTC
+  workflow_dispatch:
+
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - run: uv sync --all-extras --dev
+      - name: Run contract tests
+        run: uv run pytest tests/contract/ -m contract -v
+        env:
+          SOLVAPAY_SANDBOX_KEY: ${{ secrets.SOLVAPAY_SANDBOX_KEY }}
+          SOLVAPAY_TEST_CUSTOMER_REF: ${{ secrets.SOLVAPAY_TEST_CUSTOMER_REF }}
+          SOLVAPAY_TEST_PRODUCT_REF: ${{ secrets.SOLVAPAY_TEST_PRODUCT_REF }}

solvapay_python-0.9.0/.github/workflows/docs.yml

@@ -0,0 +1,21 @@
+name: docs
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      - run: uv sync --group docs
+      - name: Deploy to GitHub Pages
+        run: uv run mkdocs gh-deploy --force

{solvapay_python-0.7.2 → solvapay_python-0.9.0}/.gitignore

@@ -12,3 +12,4 @@ htmlcov/
 .env
 .env.local
 *.egg
+.DS_Store

solvapay_python-0.9.0/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+## 0.9.0 — 2026-05-23
+
+Production polish + C1 adversarial-review closure. API-version pinning, idempotency TTL, webhook secret rotation, ASGI adapter, retry/recording transports, contract tests, lint automation, doc site, supply-chain hardening.
+
+### Added
+- **API-version pinning**: `SolvaPay(api_version="2026-05-22")` and `AsyncSolvaPay(api_version=...)` send `Solvapay-Version` header. Default pinned to `"2026-05-22"`. `api_version=None` omits the header. (HLD V1.13)
+- **Idempotency time-bucket encoding**: `from_payload(*parts, time_bucket="day"|"hour"|None)`. Default `"day"` appends UTC date so keys roll at midnight, bounding replay ambiguity past server TTL. (HLD V1.14)
+- **Webhook secret rotation**: `MultiSecretVerifier` full implementation — tries primary then secondary on signature mismatch; both comparisons constant-time. (HLD V1.7)
+- **`AsyncInMemorySeenEventCache`**: async replay-dedup cache using `asyncio.Lock` for async webhook pipelines. (HLD V1.7)
+- **`sign_webhook(body, secret, *, timestamp)`**: public helper to produce a valid `sv-signature` header for testing and outbound webhook fanout.
+- **ASGI webhook adapter** (`solvapay[asgi]`): `webhook_app(pipeline, on_event, path)` returns a raw ASGI app mountable in Starlette, FastAPI, Litestar, or BlackSheep. (HLD V1.10)
+- **`RetryTransport`**: middleware that retries `APIConnectionError`, `APITimeoutError`, `APIServerError`, `RateLimitError` — exponential backoff with jitter, max 3 attempts. Consults `OpSpec.retry_safety`; refuses to retry `NEVER` ops. (HLD V1.4, `solvapay[retry]`)
+- **`RecordingTransport`**: records `(RequestSpec, ResponseSpec)` pairs to JSON cassettes; replays on subsequent runs. Enables offline contract tests. (HLD V1.4)
+- **Sandbox contract tests** (`tests/contract/`): one test per op against real sandbox via `RecordingTransport`. Nightly CI workflow (`contract.yml`).
+- **Lint invariants** (`tools/lint_invariants.py`): AST checks for 10 gotchas (future annotations, `hmac.compare_digest`, no `logging.basicConfig`, no `asyncio.run()`, alias discipline, etc.). Run in CI on every push.
+- **Towncrier changelog automation**: `changelog.d/` fragments, PR gate requiring a fragment when `src/` changes, `towncrier>=23` dev dep.
+- **MkDocs Material doc site**: `mkdocs.yml` + `docs/` skeleton (Quickstart, Reference, Architecture, Guides, Errors, Idempotency, Webhooks, Migration). Deploys to GitHub Pages on tag. (HLD V1.12)
+- **Dependabot**: weekly Python + GitHub Actions dependency updates (`.github/dependabot.yml`).
+- **`pip-audit` in CI**: dependency CVE scan on every push.
+- **CI matrix expanded**: Ubuntu 3.10/3.11/3.12 + macOS 3.12 + Windows 3.12. (HLD V1.15)
+- **`ResourceWarning` on unclosed `AsyncSolvaPay`**: `__del__` emits `ResourceWarning` if client is not closed and event loop is still running.
+- **OpenAPI investigation RFC**: `docs/rfcs/0002-openapi-investigation.md`.
+
+### Changed
+- `pytest.ini_options.filterwarnings`: adds `ignore::DeprecationWarning:solvapay` so tests exercising deprecated flat-shim API do not fail on expected warnings.
+
+---
+
+## 0.8.0 — 2026-05-23
+
+V1 architecture spine + AI-agent moat. 10 atomic commits establishing locked architecture invariants per HLD §V1.1–V1.19.
+
+### Added
+- **Transport Protocol kernel** (`solvapay._transport`): `Transport`/`AsyncTransport` Protocol shapes, `RequestSpec`/`ResponseSpec` frozen dataclasses, case-insensitive `Headers`, canonical middleware stack (`Redacting` → `Logging` → `IdempotencyHeader` → `ContextPropagating`), `default_stack()` recipe.
+- **Operations registry + resource-namespace API**: `OpSpec` + `RetrySafety` enum, `REGISTRY`, path interpolation with `urllib.parse.quote`. All clients gain eager namespace attrs: `sv.customers`, `sv.checkout`, `sv.limits`, `sv.purchases`, `sv.usage`, `sv.products`, `sv.plans`, `sv.merchant`.
+- **Paywall package** (`solvapay.paywall`): `Paywall`/`AsyncPaywall` split with type-narrowed construction, `PaywallRequired.checkout_mint_error`, `PayableToolMeta(_meta_version=1)`, `KwargsResolver`/`PositionalResolver`/`PydanticBodyResolver`, `@require`/`@require_async`/`@payable_tool` decorators.
+- **Webhook pipeline** (`solvapay.webhooks`): `WebhookPipeline` with two-knob config (`max_clock_skew_seconds`, `replay_ttl_seconds`), atomic `SeenEventCache.try_claim` (`threading.Lock`), `MultiSecretVerifier` interface, `WebhookEnvelope` dataclass.
+- **`solvapay.adapters.mcp`** (optional `solvapay[mcp]`): `@payable_tool` decorator + four schema flavors (`payable_tool_mcp_schema`, `payable_tool_openai_function`, `payable_tool_anthropic_tool`, `payable_tool_langchain_args_schema`), `register_payable_tool_fastmcp`.
+- **Stability manifest** (`solvapay._stability`): `stable(X)→X` identity decorator registers in `MANIFEST`; `experimental` emits once-per-process `RuntimeWarning`; `deprecated(removed_in=)`. CI gate: `tools/api_diff.py` fails on `@stable` symbol removal without prior `@deprecated`.
+- **Import-linter DAG gate**: `tools/importlinter.cfg` (3 contracts), `docs/architecture/layers.md`. CI fails on layer violation.
+- **LangChain adapter refactor** (`solvapay.adapters.langchain`): Protocol duck-typing — no hard `langchain_core` import at module level; absorbs 0.3→0.4 churn.
+- **Multi-framework demo** (`examples/multi-framework-paywall/`): one `@payable_tool`-decorated function runs across FastMCP, LangChain, and raw async — "one tool, three runtimes, one paywall."
+- **Governance scaffold**: `CODEOWNERS`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, `SUPPORT.md`, `CONTRIBUTING.md`, GitHub issue templates, PR template, `docs/rfcs/0001-spending-policy.md`.
+
+### Changed
+- **Flat methods deprecated**: `sv.ensure_customer()`, `sv.check_limits()`, etc. now emit `DeprecationWarning(stacklevel=2)` per call. Use `sv.customers.ensure()`, `sv.limits.check()`, etc. Flat shims removed in v2.0.
+- **`langchain-core` upper bound**: `langchain-core>=0.3,<0.4` now enforced in both dev and optional deps.
+- **`solvapay.langchain`** replaced by `solvapay.adapters.langchain`; old path is a deprecated shim.
+
+### Deprecated
+- `SolvaPayAPIError` — use `APIError`. Alias fires `DeprecationWarning`; removed in v2.0.
+- All flat client methods (`sv.ensure_customer`, `sv.check_limits`, etc.) — use resource-namespace API.
+
+## 0.7.2 — 2026-05-18
+
+Bug fixes and documentation update.
+
+### Fixed
+- **`paywall.require_async`**: `AsyncSolvaPay()` instantiated without a caller-supplied `client=` was not closed after the decorated function returned, leaking the underlying `httpx.AsyncClient` connection pool. Wrapped in `try/finally`; `await sv.aclose()` called when the decorator owns the client.
+- **`examples/fastmcp-paywall/pyproject.toml`**: dependency used wrong PyPI dist name (`solvapay`) and a stale `@v0.3.0` pin. Updated to `solvapay-python>=0.7.2`.
+- **`examples/langchain-paywall/pyproject.toml`**: same wrong dist name and stale `@v0.5.0` pin. Updated to `solvapay-python[langchain]>=0.7.2`.
+
+### Docs
+- **README** updated to v0.7.1 surface: `paywall_state.gate()`, error hierarchy, idempotency keys, admin ops table, marketplace example, roadmap entries for v0.7.0 and v0.7.1.
+
+### Internal
+- `tests/test_lifecycle.py` reformatted (ruff format compliance)
+
+## 0.7.1 — 2026-05-17
+
+Payments-grade hardening: structured errors, idempotency keys, py.typed, structured logging.
+
+### Added
+- **Structured error hierarchy** (`exceptions.py`): `APIError` base with `status_code`, `request_id`, `error_code`, `error_message`. Subclasses: `AuthenticationError` (401), `PermissionError` (403), `NotFoundError` (404), `RateLimitError` (429, adds `.retry_after`), `InvalidRequestError` (4xx), `APIServerError` (5xx), `APIConnectionError`, `APITimeoutError`. `SolvaPayAPIError` aliased to `APIError` for back-compat.
+- **Idempotency keys** on all mutating ops: `create_checkout_session`, `ensure_customer`, `track_usage`, `cancel_purchase`, `reactivate_purchase`, `create_product`, `clone_product`, `create_plan` all accept `idempotency_key: str | None = None`. Header casing: `Idempotency-Key` (matches TS SDK).
+- **`solvapay.idempotency.from_payload(*parts)`** — SHA256 of stable-serialized payload parts → 32-hex-char deterministic key.
+- **PEP 561 `py.typed` marker** — downstream mypy users no longer see `Any` on `solvapay.*` imports.
+- **Structured logging** at `solvapay.http` logger: INFO on success (method, path, status, request_id, duration_ms), WARNING on 4xx/5xx (adds body_excerpt ≤200 chars). Never calls `logging.basicConfig`. Optional `logger=` injection on `SolvaPay`/`AsyncSolvaPay` constructors for `loguru`/`structlog`.
+- **Secret redaction**: `Authorization` header never appears in logs. Verified by `tests/test_redaction.py`.
+- **pyproject classifiers**: `Development Status :: 4 - Beta`, `Framework :: AsyncIO`, `Topic :: Office/Business :: Financial`, `Typing :: Typed`.
+
+### Internal
+- User-Agent bumped to `solvapay-python/0.7.1`
+- 142 tests (up from 125), `mypy --strict` clean, `ruff` clean
+
+## 0.7.0 — 2026-05-17
+
+Real-API alignment after testing against the SolvaPay sandbox revealed wire-format mismatches.
+
+### Fixed
+- **`Customer.customer_ref`** now accepts `reference` (real API) in addition to `customerRef` via `validation_alias=AliasChoices(...)`.
+- **`ensure_customer()`** reads `reference` from API response; falls back to `customerRef`. Raises if neither present.
+- **`BalanceResponse`** rewritten: `credits`, `display_currency`, `credits_per_minor_unit`, `display_exchange_rate`; `balance` and `currency` kept as computed properties.
+
+### Added
+- **`paywall_state.gate()`** — one-call enrichment helper (limits + checkout URL + plan via `get_customer`).
+- **`paywall.require` / `require_async`**: auto-mints checkout URL when `LimitResponse.checkout_url is None`.
+- **`examples/marketplace/`** — Streamlit demo with 4 paywalled AI agents (Google Gemini) against real SolvaPay sandbox.
+
+### Internal
+- User-Agent `solvapay-python/0.7.0`. 125 tests (up from 121). `mypy --strict` clean.
+
+## 0.6.0
+- Admin endpoints (products, plans, merchant config). GitHub Actions trusted-publish to PyPI.
+
+## 0.5.0
+- `paywall_state` classifier (ACTIVATION_REQUIRED / TOPUP_REQUIRED / UPGRADE_REQUIRED). LangChain `monetize_tool`.
+
+## 0.4.0
+- Full async client. 5 lifecycle operations. 13 typed webhook event classes.
+
+## 0.3.0
+- FastMCP example: AI agent with two paywalled tools.
+
+## 0.2.0
+- `@paywall.require` decorator. FastAPI webhook router.
+
+## 0.1.0
+- Sync client, HMAC-SHA256 webhook verification, Pydantic v2 models, CI on 3 Python versions.

solvapay_python-0.9.0/CODEOWNERS

@@ -0,0 +1 @@
+* @dhruv-sanan

solvapay_python-0.9.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in our community a harassment-free experience for everyone.
+
+## Our Standards
+
+**Positive behavior:**
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+**Unacceptable behavior:**
+- Harassment, trolling, or personal attacks
+- Publishing others' private information without permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Community leaders may remove, edit, or reject contributions that violate this Code of Conduct.
+Report issues to `dhruv.sanan@greyorange.com`.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

solvapay_python-0.9.0/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+## Local development
+
+```bash
+git clone https://github.com/dhruv-sanan/solvapay-python
+cd solvapay-python
+uv sync --all-extras --dev
+```
+
+## Running checks
+
+```bash
+uv run ruff check src tests        # lint
+uv run ruff format --check src tests  # format gate
+uv run mypy src                    # type check
+uv run pytest -v                   # tests
+uv run python tools/api_diff.py    # stability manifest gate
+uv run lint-imports --config tools/importlinter.cfg  # layer DAG gate
+```
+
+## Layer DAG rules
+
+The SDK has a strict layer hierarchy — see [docs/architecture/layers.md](docs/architecture/layers.md).
+
+**Hard rules:**
+- `_transport` must not import `client`, `paywall`, `adapters`, or `operations`
+- `operations` must not import `paywall` or `adapters`
+- `client` must not import `adapters` or `experimental`
+
+CI fails on violations via `import-linter`.
+
+## Changelog fragment (required)
+
+Every PR that modifies `src/` must include a towncrier fragment in `changelog.d/`.
+
+```bash
+# Create a fragment (replace 42 with your issue/PR number)
+echo "Add RetryTransport middleware for automatic retry on transient errors." > changelog.d/42.feature
+```
+
+See `changelog.d/README.md` for naming conventions and types.
+
+PRs that touch `src/` without a `changelog.d/` entry will fail CI.
+
+## PR checklist
+
+- [ ] Tests added for new behavior
+- [ ] `changelog.d/<issue>.<type>` fragment added (required for `src/` changes)
+- [ ] `docs/` updated if public API changed
+- [ ] Layer DAG respected (`uv run lint-imports` passes)
+- [ ] Stability manifest updated if new public exports added (`uv run python tools/api_diff.py`)
+
+## Commit style
+
+[Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add AsyncPaywall class
+fix(webhooks): set replay_ttl_seconds default correctly
+refactor: extract _transport package
+docs: update README with MCP quickstart
+```
+
+## Adding a new resource namespace
+
+1. Add `OpSpec` entries to `src/solvapay/operations/_registry.py`
+2. Create `src/solvapay/operations/<resource>.py` with sync + async methods
+3. Wire namespace attr in `SolvaPay.__init__` and `AsyncSolvaPay.__init__`
+4. Add deprecated flat shim in `client.py` / `_async_client.py`
+5. Tests in `tests/operations/`