prava-sdk 0.1.0__tar.gz

prava_sdk-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+node_modules/
+build/
+dist/
+site/

prava_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prava Payments
+
+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.

prava_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: prava-sdk
+Version: 0.1.0
+Summary: Official Python server-side SDK for Prava Payments
+Project-URL: Documentation, https://prava-sdk.prajwalsuryawanshi.in
+Project-URL: Homepage, https://www.prava.space
+Project-URL: Issues, https://github.com/prajwalsuryawanshi/prava-payments/issues
+Project-URL: Source, https://github.com/prajwalsuryawanshi/prava-payments
+Author-email: Prava Payments <support@prava.space>
+License: MIT License
+        
+        Copyright (c) 2026 Prava Payments
+        
+        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: agentic-commerce,payments,prava,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic[email]<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: build!=1.5.1,<2,>=1.2; extra == 'dev'
+Requires-Dist: hatchling<2,>=1.25; extra == 'dev'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'dev'
+Requires-Dist: mypy<2,>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: respx<1,>=0.21; extra == 'dev'
+Requires-Dist: ruff<1,>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Prava Python SDK
+
+Typed server-side Python SDK for [Prava Payments](https://www.prava.space).
+
+[Documentation](https://prava-sdk.prajwalsuryawanshi.in) ·
+[Source](https://github.com/prajwalsuryawanshi/prava-payments)
+
+The SDK creates payment sessions, manages enrolled cards, retrieves one-time payment
+credentials, and reports checkout outcomes. Card collection still happens on Prava's hosted
+surface or through the browser [`@prava-sdk/core`](https://www.npmjs.com/package/@prava-sdk/core)
+package—your Python server must never collect a cardholder's raw card number.
+
+## Installation
+
+```bash
+pip install prava-sdk
+```
+
+Python 3.10 or newer is required.
+
+The complete SDK guide is available in [docs/](docs/index.md), with runnable programs in
+[examples/](examples/).
+
+## Quick start
+
+```python
+from decimal import Decimal
+
+from prava_sdk import PravaClient
+
+client = PravaClient("sk_test_xxx")
+
+session = client.sessions.create(
+    user_id="user_123",
+    user_email="buyer@example.com",
+    total_amount=Decimal("49.99"),
+    currency="USD",
+    purchase_context=[
+        {
+            "merchant_details": {
+                "name": "Example Store",
+                "url": "https://merchant.example",
+                "country_code_iso2": "US",
+            },
+            "product_details": [
+                {
+                    "description": "Example product",
+                    "unit_price": "49.99",
+                    "product_id": "sku_123",
+                    "quantity": 1,
+                }
+            ],
+        }
+    ],
+    integration_type="full_checkout",
+    callback_url="https://app.example/payments/complete",
+)
+
+# Send the cardholder to session.iframe_url. After card entry and passkey approval:
+result = client.sessions.wait_for_payment_result(session.session_id)
+line_item = result.transactions[0].line_items[0]
+
+card_number = line_item.token.get_secret_value() if line_item.token else None
+dynamic_cvv = line_item.dynamic_cvv.get_secret_value() if line_item.dynamic_cvv else None
+
+# Use the one-time credentials at the merchant checkout, then always report the outcome.
+client.sessions.report_status(
+    session.session_id,
+    txn_ref_id=line_item.txn_ref_id,
+    txn_status="APPROVED",
+)
+
+client.close()
+```
+
+The secret key can instead be supplied through `PRAVA_SECRET_KEY`. `sk_test_*` keys automatically
+use `https://sandbox.api.prava.space`; `sk_live_*` keys use `https://api.prava.space`.
+
+Use the client as a context manager to guarantee cleanup:
+
+```python
+from prava_sdk import PravaClient
+
+with PravaClient("sk_test_xxx") as client:
+    cards = client.cards.list(customer_id="user_123")
+```
+
+## Async client
+
+`AsyncPravaClient` exposes the same grouped resources and method arguments:
+
+```python
+from prava_sdk import AsyncPravaClient
+
+async with AsyncPravaClient("sk_test_xxx") as client:
+    result = await client.sessions.wait_for_payment_result(
+        "ses_123",
+        timeout=300,
+        poll_interval=2,
+    )
+```
+
+## API
+
+### Sessions
+
+- `client.sessions.create(...)`
+- `client.sessions.revoke(session_id)`
+- `client.sessions.get_payment_result(session_id)`
+- `client.sessions.wait_for_payment_result(session_id, timeout=300, poll_interval=2)`
+- `client.sessions.report_status(session_id, ...)`
+
+The polling helper returns as soon as the result status becomes `awaiting_result`, `completed`, or
+`failed`. It raises `PravaPollingTimeoutError` if the session remains `pending` past the timeout.
+
+### Cards
+
+- `client.cards.list(customer_id=..., status="active", include_card_art=False)`
+- `client.cards.delete(customer_id=..., card_id=..., reason="OTHER")`
+
+Only non-sensitive card metadata is returned by card-management endpoints.
+
+## Errors
+
+All failures derive from `PravaError`. API exceptions expose `code`, `message`, `status_code`,
+`details`, and `response_id` (from the `X-Response-ID` response header):
+
+```python
+from prava_sdk import PravaError
+
+try:
+    client.sessions.revoke("ses_missing")
+except PravaError as exc:
+    print(exc.code, exc.response_id)
+```
+
+The SDK provides dedicated authentication, validation, not-found, invalid-state, rate-limit,
+transport, request-timeout, and polling-timeout exception types. Requests are not retried
+automatically because the API does not currently document idempotency keys.
+
+## Security
+
+- Never use `sk_test_*` or `sk_live_*` keys in browsers, mobile apps, logs, or version control.
+- Never collect or send a cardholder's underlying card number through this SDK.
+- Payment-result `token` and `dynamic_cvv` values are Pydantic `SecretStr` fields and are redacted
+  from normal model representations. Retrieve them only immediately before checkout.
+- Always call `report_status` with `APPROVED` or `DECLINED` after attempting checkout.
+
+See the [API reference](https://docs.prava.space/api-reference/overview),
+[error catalog](https://docs.prava.space/api-reference/errors), and
+[sandbox guide](https://docs.prava.space/api-reference/testing) for the complete server contract.
+
+## Package architecture
+
+The SDK is organized as a standalone Python library:
+
+```text
+prava_sdk/
+├── client.py          # Small public sync and async client facades
+├── resources/         # Session and card endpoint groups
+│   └── _base.py       # Shared resource contracts and validation boundary
+├── models/            # Pydantic requests, responses, and enums
+├── _config.py         # Secret-key and environment resolution
+├── _transport.py      # Shared HTTP, JSON, and response handling
+└── errors.py          # Public exception hierarchy
+```
+
+The JavaScript SDK is not a runtime or build dependency. It only handles browser-side card
+collection and is excluded from Python source and wheel distributions.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv run mkdocs build --strict
+uv run python -m build
+```

prava_sdk-0.1.0/README.md

@@ -0,0 +1,180 @@
+# Prava Python SDK
+
+Typed server-side Python SDK for [Prava Payments](https://www.prava.space).
+
+[Documentation](https://prava-sdk.prajwalsuryawanshi.in) ·
+[Source](https://github.com/prajwalsuryawanshi/prava-payments)
+
+The SDK creates payment sessions, manages enrolled cards, retrieves one-time payment
+credentials, and reports checkout outcomes. Card collection still happens on Prava's hosted
+surface or through the browser [`@prava-sdk/core`](https://www.npmjs.com/package/@prava-sdk/core)
+package—your Python server must never collect a cardholder's raw card number.
+
+## Installation
+
+```bash
+pip install prava-sdk
+```
+
+Python 3.10 or newer is required.
+
+The complete SDK guide is available in [docs/](docs/index.md), with runnable programs in
+[examples/](examples/).
+
+## Quick start
+
+```python
+from decimal import Decimal
+
+from prava_sdk import PravaClient
+
+client = PravaClient("sk_test_xxx")
+
+session = client.sessions.create(
+    user_id="user_123",
+    user_email="buyer@example.com",
+    total_amount=Decimal("49.99"),
+    currency="USD",
+    purchase_context=[
+        {
+            "merchant_details": {
+                "name": "Example Store",
+                "url": "https://merchant.example",
+                "country_code_iso2": "US",
+            },
+            "product_details": [
+                {
+                    "description": "Example product",
+                    "unit_price": "49.99",
+                    "product_id": "sku_123",
+                    "quantity": 1,
+                }
+            ],
+        }
+    ],
+    integration_type="full_checkout",
+    callback_url="https://app.example/payments/complete",
+)
+
+# Send the cardholder to session.iframe_url. After card entry and passkey approval:
+result = client.sessions.wait_for_payment_result(session.session_id)
+line_item = result.transactions[0].line_items[0]
+
+card_number = line_item.token.get_secret_value() if line_item.token else None
+dynamic_cvv = line_item.dynamic_cvv.get_secret_value() if line_item.dynamic_cvv else None
+
+# Use the one-time credentials at the merchant checkout, then always report the outcome.
+client.sessions.report_status(
+    session.session_id,
+    txn_ref_id=line_item.txn_ref_id,
+    txn_status="APPROVED",
+)
+
+client.close()
+```
+
+The secret key can instead be supplied through `PRAVA_SECRET_KEY`. `sk_test_*` keys automatically
+use `https://sandbox.api.prava.space`; `sk_live_*` keys use `https://api.prava.space`.
+
+Use the client as a context manager to guarantee cleanup:
+
+```python
+from prava_sdk import PravaClient
+
+with PravaClient("sk_test_xxx") as client:
+    cards = client.cards.list(customer_id="user_123")
+```
+
+## Async client
+
+`AsyncPravaClient` exposes the same grouped resources and method arguments:
+
+```python
+from prava_sdk import AsyncPravaClient
+
+async with AsyncPravaClient("sk_test_xxx") as client:
+    result = await client.sessions.wait_for_payment_result(
+        "ses_123",
+        timeout=300,
+        poll_interval=2,
+    )
+```
+
+## API
+
+### Sessions
+
+- `client.sessions.create(...)`
+- `client.sessions.revoke(session_id)`
+- `client.sessions.get_payment_result(session_id)`
+- `client.sessions.wait_for_payment_result(session_id, timeout=300, poll_interval=2)`
+- `client.sessions.report_status(session_id, ...)`
+
+The polling helper returns as soon as the result status becomes `awaiting_result`, `completed`, or
+`failed`. It raises `PravaPollingTimeoutError` if the session remains `pending` past the timeout.
+
+### Cards
+
+- `client.cards.list(customer_id=..., status="active", include_card_art=False)`
+- `client.cards.delete(customer_id=..., card_id=..., reason="OTHER")`
+
+Only non-sensitive card metadata is returned by card-management endpoints.
+
+## Errors
+
+All failures derive from `PravaError`. API exceptions expose `code`, `message`, `status_code`,
+`details`, and `response_id` (from the `X-Response-ID` response header):
+
+```python
+from prava_sdk import PravaError
+
+try:
+    client.sessions.revoke("ses_missing")
+except PravaError as exc:
+    print(exc.code, exc.response_id)
+```
+
+The SDK provides dedicated authentication, validation, not-found, invalid-state, rate-limit,
+transport, request-timeout, and polling-timeout exception types. Requests are not retried
+automatically because the API does not currently document idempotency keys.
+
+## Security
+
+- Never use `sk_test_*` or `sk_live_*` keys in browsers, mobile apps, logs, or version control.
+- Never collect or send a cardholder's underlying card number through this SDK.
+- Payment-result `token` and `dynamic_cvv` values are Pydantic `SecretStr` fields and are redacted
+  from normal model representations. Retrieve them only immediately before checkout.
+- Always call `report_status` with `APPROVED` or `DECLINED` after attempting checkout.
+
+See the [API reference](https://docs.prava.space/api-reference/overview),
+[error catalog](https://docs.prava.space/api-reference/errors), and
+[sandbox guide](https://docs.prava.space/api-reference/testing) for the complete server contract.
+
+## Package architecture
+
+The SDK is organized as a standalone Python library:
+
+```text
+prava_sdk/
+├── client.py          # Small public sync and async client facades
+├── resources/         # Session and card endpoint groups
+│   └── _base.py       # Shared resource contracts and validation boundary
+├── models/            # Pydantic requests, responses, and enums
+├── _config.py         # Secret-key and environment resolution
+├── _transport.py      # Shared HTTP, JSON, and response handling
+└── errors.py          # Public exception hierarchy
+```
+
+The JavaScript SDK is not a runtime or build dependency. It only handles browser-side card
+collection and is excluded from Python source and wheel distributions.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run mypy
+uv run pytest
+uv run mkdocs build --strict
+uv run python -m build
+```

prava_sdk-0.1.0/docs/architecture.md

@@ -0,0 +1,44 @@
+# Architecture
+
+The project is a standalone Python library. Browser SDK files are reference material only and are
+not runtime dependencies or package inputs.
+
+```text
+src/prava_sdk/
+├── client.py
+├── resources/
+│   ├── _base.py
+│   ├── sessions.py
+│   └── cards.py
+├── models/
+│   ├── sessions.py
+│   ├── cards.py
+│   ├── enums.py
+│   └── _base.py
+├── _config.py
+├── _transport.py
+└── errors.py
+```
+
+## Responsibilities
+
+- `client.py` owns lifecycle and exposes grouped resources.
+- `resources/` maps Python methods to REST paths and builds request models. Its internal base layer
+  defines structural transport protocols, so endpoint groups are independent of `httpx` and the
+  concrete transport implementation.
+- `models/` validates requests and parses typed responses.
+- `_config.py` resolves secret keys, environments, and base URLs.
+- `_transport.py` owns `httpx` pools, authentication headers, JSON parsing, and transport failures.
+- `errors.py` maps the common Prava error envelope into public exceptions.
+
+Sync and async resources share model-building helpers but use distinct transport types. This keeps
+the public APIs symmetrical without hiding blocking I/O inside async methods.
+
+Resource methods translate local model errors into `PravaValidationError`; direct use of a public
+Pydantic model still raises Pydantic's `ValidationError`. This keeps the client boundary consistent
+while preserving normal Pydantic behavior for applications that use the schemas independently.
+
+## Compatibility boundary
+
+Supported public imports live in `prava_sdk`, `prava_sdk.models`, and the documented client resource
+methods. Underscore-prefixed modules are internal and may change between releases.

prava_sdk-0.1.0/docs/assets/prava-payments-logo.svg

@@ -0,0 +1,4 @@
+<svg width="262" height="98" viewBox="0 0 262 98" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M68.452 42.6934L63.6249 39.4767C62.8242 36.9521 61.2403 34.7481 59.1028 33.1841C56.9654 31.6202 54.3854 30.7775 51.7369 30.7783H51.6766C44.8359 30.8116 39.269 36.4865 39.269 43.4311V47.533L21.7372 68.5724L21.7164 68.5974C21.3252 69.086 21.0798 69.6753 21.0086 70.2972C20.9374 70.9192 21.0433 71.5486 21.314 72.1131C21.5847 72.6776 22.0093 73.1541 22.5389 73.488C23.0685 73.8218 23.6816 73.9993 24.3077 74.0001H42.5938C48.3235 73.994 53.8168 71.7152 57.8683 67.6637C61.9198 63.6122 64.1986 58.1189 64.2047 52.3892V48.2914L68.452 45.4612C68.6801 45.3095 68.8671 45.1038 68.9964 44.8623C69.1257 44.6209 69.1934 44.3512 69.1934 44.0773C69.1934 43.8034 69.1257 43.5338 68.9964 43.2923C68.8671 43.0509 68.6801 42.8451 68.452 42.6934ZM45.5341 55.1155L33.0663 70.0769C32.9282 70.2494 32.757 70.3927 32.5628 70.4983C32.3686 70.6039 32.1553 70.6698 31.9354 70.692C31.7155 70.7141 31.4933 70.6922 31.2819 70.6275C31.0706 70.5628 30.8742 70.4566 30.7044 70.3151C30.5346 70.1736 30.3947 69.9997 30.2929 69.8035C30.1911 69.6073 30.1295 69.3927 30.1116 69.1724C30.0937 68.9521 30.12 68.7304 30.1888 68.5203C30.2576 68.3103 30.3677 68.116 30.5125 67.949L42.9803 52.9877C43.1184 52.8151 43.2896 52.6718 43.4838 52.5662C43.678 52.4606 43.8913 52.3948 44.1112 52.3726C44.3311 52.3504 44.5533 52.3723 44.7646 52.437C44.976 52.5017 45.1724 52.6079 45.3422 52.7494C45.512 52.8909 45.6519 53.0648 45.7537 53.2611C45.8555 53.4573 45.9171 53.6718 45.935 53.8921C45.9529 54.1125 45.9266 54.3341 45.8578 54.5442C45.7889 54.7543 45.6789 54.9485 45.5341 55.1155ZM53.3992 44.0773C52.906 44.0773 52.4239 43.9311 52.0139 43.6571C51.6038 43.3831 51.2842 42.9936 51.0955 42.538C50.9067 42.0824 50.8574 41.581 50.9536 41.0973C51.0498 40.6136 51.2873 40.1693 51.636 39.8205C51.9847 39.4718 52.4291 39.2343 52.9128 39.1381C53.3965 39.0419 53.8978 39.0913 54.3535 39.28C54.8091 39.4687 55.1986 39.7883 55.4725 40.1984C55.7465 40.6085 55.8928 41.0906 55.8928 41.5838C55.8928 42.2451 55.6301 42.8793 55.1624 43.347C54.6948 43.8146 54.0606 44.0773 53.3992 44.0773Z" fill="black"/>
+<path d="M110.312 74V26.32H127.144C130.301 26.32 133.075 26.9173 135.464 28.112C137.853 29.3067 139.709 31.0133 141.032 33.232C142.397 35.4507 143.08 38.0533 143.08 41.04C143.08 44.0267 142.397 46.6293 141.032 48.848C139.709 51.024 137.853 52.7307 135.464 53.968C133.117 55.1627 130.344 55.76 127.144 55.76H116.584V74H110.312ZM116.584 50H127.336C129.256 50 130.92 49.6373 132.328 48.912C133.736 48.1867 134.824 47.1413 135.592 45.776C136.36 44.4107 136.744 42.832 136.744 41.04C136.744 39.2053 136.36 37.6267 135.592 36.304C134.824 34.9387 133.736 33.8933 132.328 33.168C130.92 32.4427 129.256 32.08 127.336 32.08H116.584V50ZM147.658 74V39.504H153.482V45.84L152.842 44.944C153.653 42.9813 154.89 41.5307 156.554 40.592C158.218 39.6107 160.245 39.12 162.634 39.12H164.746V44.752H161.738C159.306 44.752 157.343 45.52 155.85 47.056C154.357 48.5493 153.61 50.6827 153.61 53.456V74H147.658ZM176.945 74.768C174.684 74.768 172.678 74.3627 170.929 73.552C169.222 72.6987 167.878 71.5467 166.897 70.096C165.916 68.6027 165.425 66.896 165.425 64.976C165.425 63.1413 165.809 61.4987 166.577 60.048C167.388 58.5547 168.625 57.296 170.289 56.272C171.996 55.248 174.129 54.5227 176.689 54.096L189.489 51.984V56.976L178.033 58.896C175.814 59.28 174.193 59.984 173.169 61.008C172.188 62.032 171.697 63.2907 171.697 64.784C171.697 66.192 172.252 67.3653 173.361 68.304C174.513 69.2427 175.942 69.712 177.649 69.712C179.825 69.712 181.702 69.264 183.281 68.368C184.902 67.4293 186.161 66.1707 187.057 64.592C187.996 63.0133 188.465 61.264 188.465 59.344V50.576C188.465 48.6987 187.761 47.184 186.353 46.032C184.988 44.8373 183.174 44.24 180.913 44.24C178.95 44.24 177.201 44.752 175.665 45.776C174.172 46.7573 173.062 48.08 172.337 49.744L167.153 47.056C167.793 45.4773 168.817 44.0693 170.225 42.832C171.633 41.552 173.276 40.5493 175.153 39.824C177.03 39.0987 178.993 38.736 181.041 38.736C183.686 38.736 186.012 39.248 188.017 40.272C190.022 41.2533 191.58 42.64 192.689 44.432C193.841 46.1813 194.417 48.2293 194.417 50.576V74H188.593V67.472L189.681 67.856C188.956 69.2213 187.974 70.416 186.737 71.44C185.5 72.464 184.049 73.2747 182.385 73.872C180.721 74.4693 178.908 74.768 176.945 74.768ZM209.421 74L195.917 39.504H202.573L213.389 68.688H211.085L221.965 39.504H228.621L215.053 74H209.421ZM239.607 74.768C237.346 74.768 235.341 74.3627 233.591 73.552C231.885 72.6987 230.541 71.5467 229.559 70.096C228.578 68.6027 228.087 66.896 228.087 64.976C228.087 63.1413 228.471 61.4987 229.239 60.048C230.05 58.5547 231.287 57.296 232.951 56.272C234.658 55.248 236.791 54.5227 239.351 54.096L252.151 51.984V56.976L240.695 58.896C238.477 59.28 236.855 59.984 235.831 61.008C234.85 62.032 234.359 63.2907 234.359 64.784C234.359 66.192 234.914 67.3653 236.023 68.304C237.175 69.2427 238.605 69.712 240.311 69.712C242.487 69.712 244.365 69.264 245.943 68.368C247.565 67.4293 248.823 66.1707 249.719 64.592C250.658 63.0133 251.127 61.264 251.127 59.344V50.576C251.127 48.6987 250.423 47.184 249.015 46.032C247.65 44.8373 245.837 44.24 243.575 44.24C241.613 44.24 239.863 44.752 238.327 45.776C236.834 46.7573 235.725 48.08 234.999 49.744L229.815 47.056C230.455 45.4773 231.479 44.0693 232.887 42.832C234.295 41.552 235.938 40.5493 237.815 39.824C239.693 39.0987 241.655 38.736 243.703 38.736C246.349 38.736 248.674 39.248 250.679 40.272C252.685 41.2533 254.242 42.64 255.351 44.432C256.503 46.1813 257.079 48.2293 257.079 50.576V74H251.255V67.472L252.343 67.856C251.618 69.2213 250.637 70.416 249.399 71.44C248.162 72.464 246.711 73.2747 245.047 73.872C243.383 74.4693 241.57 74.768 239.607 74.768Z" fill="black"/>
+</svg>

prava_sdk-0.1.0/docs/examples.md

@@ -0,0 +1,31 @@
+# Examples
+
+The repository includes task-focused programs under `examples/`:
+
+| File | Demonstrates |
+| --- | --- |
+| `create_hosted_session.py` | Create a hosted cardholder redirect. |
+| `create_embedded_session.py` | Build the payload returned by a backend to its frontend. |
+| `complete_payment.py` | Poll, invoke application checkout logic, and always report status. |
+| `async_payment_flow.py` | Perform the payment orchestration with `AsyncPravaClient`. |
+| `manage_cards.py` | List or delete enrolled cards from a CLI. |
+
+Set a sandbox key before running an example:
+
+```bash
+export PRAVA_SECRET_KEY=sk_test_xxx
+python examples/create_hosted_session.py \
+  --user-id user_123 \
+  --email buyer@example.com \
+  --callback-url https://app.example/payments/complete
+```
+
+Display each program's arguments with `--help`:
+
+```bash
+python examples/manage_cards.py --help
+```
+
+The complete-payment examples intentionally require an application-provided merchant checkout
+callback. Prava provides the one-time credential; submitting it to a specific merchant remains the
+application's responsibility.

prava_sdk-0.1.0/docs/getting-started.md

@@ -0,0 +1,67 @@
+# Getting started
+
+## Install
+
+```bash
+pip install prava-sdk
+```
+
+The package requires Python 3.10 or newer.
+
+## Configure a secret key
+
+Pass the key directly when constructing a client:
+
+```python
+from prava_sdk import PravaClient
+
+client = PravaClient("sk_test_xxx")
+```
+
+Or set `PRAVA_SECRET_KEY` and omit the argument:
+
+```bash
+export PRAVA_SECRET_KEY=sk_test_xxx
+```
+
+```python
+from prava_sdk import PravaClient
+
+client = PravaClient()
+```
+
+Key prefixes select the API environment automatically:
+
+| Prefix | Environment | Base URL |
+| --- | --- | --- |
+| `sk_test_*` | Sandbox | `https://sandbox.api.prava.space` |
+| `sk_live_*` | Production | `https://api.prava.space` |
+
+Passing a conflicting `environment` raises `PravaValidationError` before any network request.
+
+## Manage the connection lifecycle
+
+Prefer a context manager so the HTTP connection pool is always closed:
+
+```python
+from prava_sdk import PravaClient
+
+with PravaClient() as client:
+    response = client.cards.list(customer_id="user_123")
+```
+
+Long-running applications can create one client at startup, reuse it for requests, and call
+`close()` during shutdown. Do not create a new client for every operation.
+
+For async services, use `AsyncPravaClient` with `async with` or call `aclose()` during shutdown.
+
+## Timeouts and custom transports
+
+Set the HTTP timeout at client construction:
+
+```python
+client = PravaClient(timeout=20.0)
+```
+
+The `base_url` and `transport` options exist for local testing and custom `httpx` transports. Normal
+integrations should rely on key-based environment selection.

prava_sdk-0.1.0/docs/guides/async.md

@@ -0,0 +1,50 @@
+# Async applications
+
+`AsyncPravaClient` mirrors the synchronous API. It is appropriate for FastAPI, Starlette, aiohttp,
+and other asyncio-based services.
+
+```python
+from prava_sdk import AsyncPravaClient
+
+
+async def retrieve_payment(session_id: str) -> None:
+    async with AsyncPravaClient() as client:
+        result = await client.sessions.wait_for_payment_result(
+            session_id,
+            timeout=300,
+            poll_interval=2,
+        )
+        print(result.status)
+```
+
+## Application lifecycle
+
+Create one client during application startup and close it during shutdown. For example, the relevant
+FastAPI lifecycle pattern is:
+
+```python
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from prava_sdk import AsyncPravaClient
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    app.state.prava = AsyncPravaClient()
+    try:
+        yield
+    finally:
+        await app.state.prava.aclose()
+
+
+app = FastAPI(lifespan=lifespan)
+```
+
+FastAPI is not an SDK dependency; this snippet only demonstrates lifecycle management.
+
+## Cancellation and polling
+
+Async polling uses `asyncio.sleep`, so task cancellation is propagated normally. A
+`PravaPollingTimeoutError` is raised when the configured overall timeout expires. The per-request
+HTTP timeout is configured separately on `AsyncPravaClient(timeout=...)`.