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

solvapay_python-0.8.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.8.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.8.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.8.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.7.2 → solvapay_python-0.8.0}/.github/workflows/ci.yml

@@ -20,5 +20,8 @@ jobs:
         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

{solvapay_python-0.7.2 → solvapay_python-0.8.0}/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 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.

solvapay_python-0.8.0/CODEOWNERS

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

solvapay_python-0.8.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.8.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# 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`.
+
+## PR checklist
+
+- [ ] Tests added for new behavior
+- [ ] `CHANGELOG.md` updated
+- [ ] `docs/` updated if public API changed
+- [ ] Layer DAG respected (`uv run lint-imports` passes)
+- [ ] Stability manifest updated if new public exports added
+
+## 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/`

solvapay_python-0.8.0/PKG-INFO

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: solvapay-python
+Version: 0.8.0
+Summary: Community Python SDK for SolvaPay (agent-native payment rails)
+Project-URL: Homepage, https://github.com/dhruv-sanan/solvapay-python
+Project-URL: Issues, https://github.com/dhruv-sanan/solvapay-python/issues
+Project-URL: Official TS SDK, https://github.com/solvapay/solvapay-sdk
+Author: Dhruv Sanan
+License: MIT
+License-File: LICENSE
+Keywords: agents,fintech,mcp,payments,solvapay
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic<2.13,>=2.6
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Provides-Extra: langchain
+Requires-Dist: langchain-core<0.4,>=0.3; extra == 'langchain'
+Provides-Extra: mcp
+Requires-Dist: fastmcp<0.5,>=0.4; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# solvapay-python
+
+Community Python SDK for [SolvaPay](https://solvapay.com) — agentic payment rails.  
+`pip install solvapay-python` · Python 3.10+ · Fully typed (py.typed) · [PyPI](https://pypi.org/project/solvapay-python/)
+
+[![CI](https://github.com/dhruv-sanan/solvapay-python/actions/workflows/ci.yml/badge.svg)](https://github.com/dhruv-sanan/solvapay-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/solvapay-python.svg)](https://pypi.org/project/solvapay-python/)
+
+---
+
+## One tool. Three runtimes. One paywall.
+
+`@payable_tool` stamps a function with payment metadata once. Any framework reads it — no per-framework wiring.
+
+```python
+# Define once
+from solvapay.adapters.mcp import payable_tool
+
+@payable_tool(product="prd_search")
+def web_search(*, customer_ref: str, query: str) -> list[str]:
+    """Search the web."""
+    return do_real_search(query)
+```
+
+```python
+# Run on MCP (Claude Desktop / Claude Code)
+from solvapay.adapters.mcp import register_payable_tool_fastmcp
+from fastmcp import FastMCP
+
+mcp = FastMCP("My App")
+register_payable_tool_fastmcp(mcp, web_search)
+mcp.run()
+```
+
+```python
+# Run on LangChain
+from solvapay.adapters.langchain import monetize_tool
+
+paid = monetize_tool(web_search, product="prd_search")
+# Blocked callers get {"paywall_required": True, "checkout_url": "..."}
+```
+
+```python
+# Run raw async
+async with AsyncSolvaPay() as sv:
+    limits = await sv.limits.acheck(customer_ref="cus_123", product_ref="prd_search")
+    if limits.within_limits:
+        result = await web_search(customer_ref="cus_123", query="hello")
+```
+
+`pip install 'solvapay-python[mcp]'` · `pip install 'solvapay-python[langchain]'`
+
+---
+
+## Quickstart
+
+```bash
+pip install solvapay-python
+export SOLVAPAY_SECRET_KEY=sk_...
+```
+
+```python
+from solvapay import SolvaPay
+
+sv = SolvaPay()
+
+# Ensure customer exists
+customer_ref = sv.customers.ensure("user_alice")
+
+# Create checkout session
+session = sv.checkout.create_session(customer_ref=customer_ref, product_ref="prd_0QKI8NHF")
+print(session.checkout_url)
+
+# Check limits and track usage
+limits = sv.limits.check(customer_ref=customer_ref, product_ref="prd_0QKI8NHF")
+if limits.within_limits:
+    sv.usage.track(
+        customer_ref=customer_ref,
+        product_ref="prd_0QKI8NHF",
+        meter_name="requests",
+        units=1.0,
+        idempotency_key="req_abc123",   # idempotent — safe to retry
+    )
+```
+
+---
+
+## Stable API
+
+| Namespace | Sync | Async |
+|-----------|------|-------|
+| `sv.customers` | `ensure`, `get`, `update`, `balance` | `aensure`, `aget`, `aupdate`, `abalance` |
+| `sv.checkout` | `create_session` | `acreate_session` |
+| `sv.limits` | `check` | `acheck` |
+| `sv.purchases` | `cancel`, `reactivate` | `acancel`, `areactivate` |
+| `sv.usage` | `track` | `atrack` |
+| `sv.products` | `list`, `get`, `create`, `delete`, `clone` | `a` prefix on each |
+| `sv.plans` | `list`, `create`, `update`, `delete` | `a` prefix on each |
+| `sv.merchant` | `get`, `get_platform_config` | `aget`, `aget_platform_config` |
+
+---
+
+## Idempotency
+
+All mutating ops accept `idempotency_key`. Use `solvapay.idempotency.from_payload` to derive deterministic keys from request content:
+
+```python
+from solvapay.idempotency import from_payload
+
+key = from_payload("track_usage", customer_ref, product_ref, "requests", units)
+sv.usage.track(..., idempotency_key=key)   # retry-safe
+```
+
+Retried POSTs **must reuse the same key**. Key should change only when the logical request changes.
+
+---
+
+## Errors and retries
+
+```python
+from solvapay import (
+    AuthenticationError, PermissionError, NotFoundError,
+    RateLimitError, InvalidRequestError, APIServerError,
+    APIConnectionError, APITimeoutError, SolvaPayError,
+)
+
+try:
+    sv.customers.ensure("cus_123")
+except AuthenticationError:
+    ...  # 401 — bad key
+except RateLimitError as e:
+    ...  # 429 — retry after e.retry_after seconds
+except APIConnectionError:
+    ...  # network failure
+except APITimeoutError:
+    ...  # request timed out (default 30s)
+except SolvaPayError as e:
+    ...  # catch-all
+```
+
+No built-in retries by design. Layer `tenacity` manually. `solvapay[retry]` RetryTransport ships in v0.9.
+
+---
+
+## Webhooks
+
+```python
+import os
+from solvapay.webhooks import WebhookPipeline
+
+pipeline = WebhookPipeline(
+    [os.environ["SOLVAPAY_WEBHOOK_SECRET"]],
+    max_clock_skew_seconds=300,
+    replay_ttl_seconds=600,
+)
+
+envelope = pipeline.process(body=request.body, signature=request.headers["sv-signature"])
+```
+
+**Typed events** — discriminated union over 13 event types:
+
+```python
+from solvapay import WebhookEvent, PurchaseCreated, PaymentSucceeded
+from pydantic import TypeAdapter
+
+event = TypeAdapter(WebhookEvent).validate_python(envelope.event)
+
+match event:
+    case PurchaseCreated():
+        print(f"New purchase: {event.data['purchaseRef']}")
+    case PaymentSucceeded():
+        print(f"Payment: {event.data['amount']}")
+```
+
+---
+
+## Paywall decorator
+
+```python
+from solvapay.paywall import require, PaywallRequired
+
+@require(product="prd_0QKI8NHF", client=sv)
+def run_query(*, customer_ref: str, query: str) -> str:
+    return expensive_query(query)
+
+try:
+    result = run_query(customer_ref="cus_123", query="hello")
+except PaywallRequired as e:
+    print(f"Upgrade at: {e.checkout_url}")
+    if e.checkout_mint_error:
+        print(f"Could not auto-mint checkout URL: {e.checkout_mint_error}")
+```
+
+Async version: `@require_async`. For MCP/LangChain: `@payable_tool` (see above).
+
+---
+
+## Async
+
+`AsyncSolvaPay` is the supported async pattern. Always use `async with` — it guarantees `aclose()`:
+
+```python
+from solvapay import AsyncSolvaPay
+
+async with AsyncSolvaPay() as sv:
+    customer_ref = await sv.customers.aensure("user_alice")
+    limits = await sv.limits.acheck(customer_ref=customer_ref, product_ref="prd_0QKI8NHF")
+    if limits.within_limits:
+        await sv.usage.atrack(
+            customer_ref=customer_ref,
+            product_ref="prd_0QKI8NHF",
+            meter_name="requests",
+            units=1.0,
+        )
+```
+
+---
+
+## Migrating from v0.7.x
+
+Flat methods still work but emit `DeprecationWarning`. Removed in v2.0.
+
+| v0.7.x | v0.8+ |
+|--------|-------|
+| `sv.ensure_customer(ref)` | `sv.customers.ensure(ref)` |
+| `sv.get_customer(ref)` | `sv.customers.get(ref)` |
+| `sv.check_limits(...)` | `sv.limits.check(...)` |
+| `sv.track_usage(...)` | `sv.usage.track(...)` |
+| `sv.create_checkout_session(...)` | `sv.checkout.create_session(...)` |
+| `sv.cancel_purchase(ref)` | `sv.purchases.cancel(ref)` |
+| `sv.reactivate_purchase(ref)` | `sv.purchases.reactivate(ref)` |
+| `sv.get_customer_balance(ref)` | `sv.customers.balance(ref)` |
+| `sv.list_products()` | `sv.products.list()` |
+| `sv.create_plan(prd, ...)` | `sv.plans.create(prd, ...)` |
+| `sv.get_merchant()` | `sv.merchant.get()` |
+
+---
+
+## Installation
+
+```bash
+pip install solvapay-python                   # core
+pip install 'solvapay-python[mcp]'            # + FastMCP adapter (FastMCP ≥0.4)
+pip install 'solvapay-python[langchain]'      # + LangChain adapter (langchain-core ≥0.3)
+pip install 'solvapay-python[fastapi]'        # + FastAPI webhook router
+```
+
+## Environment variables
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `SOLVAPAY_SECRET_KEY` | Yes | — |
+| `SOLVAPAY_API_BASE_URL` | No | `https://api.solvapay.com` |
+| `SOLVAPAY_WEBHOOK_SECRET` | For webhooks | — |
+
+---
+
+## Examples
+
+| Path | What |
+|------|------|
+| `examples/multi-framework-paywall/` | One `@payable_tool` → FastMCP + LangChain + raw async |
+| `examples/marketplace/` | Streamlit AI-agent marketplace — real SolvaPay sandbox + Gemini LLM |
+| `examples/fastmcp-paywall/` | FastMCP server gated by `@paywall.require` |
+| `examples/langchain-paywall/` | LangChain agent with `monetize_tool` |
+
+---
+
+## Roadmap
+
+| Version | Theme |
+|---------|-------|
+| v0.8 ✅ | V1 architecture spine — Transport kernel, OpSpec registry, paywall/webhook packages, `@payable_tool`, stability manifest, layer DAG CI gate |
+| v0.9 | Production polish — API-version pinning, idempotency TTL, `RetryTransport`, `RecordingTransport`, contract tests, lint automation, doc site (MkDocs Material), supply-chain hygiene |
+| v1.0 | Gated on founder signal — OpenAPI-generated models, full secret rotation, production hardening |
+
+---
+
+## Status
+
+**v0.8.0** — V1 architecture spine + AI-agent moat. `mypy --strict` clean (43 files). 261 tests. 89% line coverage.  
+Community SDK, not official. Proposal: [solvapay/solvapay-sdk#187](https://github.com/solvapay/solvapay-sdk/issues/187).