vatly-api-python 0.1.0a2__tar.gz

vatly_api_python-0.1.0a2/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.amp/portals/*
+.env

vatly_api_python-0.1.0a2/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0a2 — Unreleased
+
+- Use the PyPI distribution name `vatly-api-python`; imports remain `vatly`.
+- Preserve enabled currency/precision intersections in generated Money models.
+- Reject empty successful resource responses instead of returning untyped None.
+- Include request method and URL in timeout/connection errors in both clients.
+
+## 0.1.0a1 — Unreleased
+
+> Alpha — under active development. Every alpha release may include breaking changes. Pin exact versions during alpha.
+
+- Initial typed Python SDK covering all 50 production OpenAPI operations.
+- Pydantic models, sync/async httpx clients, cursor iterators, retries, idempotency,
+  per-request timeouts, typed errors and raw-body webhook verification.
+- Documentation, reproducible code generation, CI, trusted-publishing workflow,
+  and cached orb development setup. Nothing published or tagged.

vatly_api_python-0.1.0a2/LICENSE

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

vatly_api_python-0.1.0a2/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: vatly-api-python
+Version: 0.1.0a2
+Summary: Python SDK for Vatly, the merchant of record for AI, software and digital products
+Project-URL: Homepage, https://github.com/vatly/vatly-api-python
+Project-URL: Documentation, https://docs.vatly.com
+Project-URL: Issues, https://github.com/vatly/vatly-api-python/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: typing-extensions<5,>=4.12
+Description-Content-Type: text/markdown
+
+# Vatly Python SDK
+
+> **Alpha — under active development. Every alpha release may include breaking changes. Pin exact versions during alpha.**
+
+Python SDK for Vatly, the merchant of record for AI, software and digital products.
+Python 3.10+, Pydantic v2 models, and pooled httpx sync/async clients. All 50 production
+OpenAPI operations are covered. No package has been published yet.
+
+## Installation
+
+Once published:
+
+```bash
+pip install vatly-api-python==0.1.0a2
+```
+
+For local development: `uv sync --locked`.
+
+## Quick start
+
+Get a test or live API key from [the dashboard](https://my.vatly.com), under Settings > API.
+Keep keys server-side. The client reads `VATLY_API_KEY` by default.
+
+```python
+from vatly import VatlyClient
+from vatly.models import CreateCheckoutRequest
+
+with VatlyClient() as vatly:
+    checkout = vatly.checkouts.create(
+        CreateCheckoutRequest(
+            redirect_url_success="https://example.com/success",
+            redirect_url_canceled="https://example.com/canceled",
+            products=[{"id": "subscription_plan_abc123", "quantity": 1}],
+        )
+    )
+    print(checkout.links.checkout_url.href)
+```
+
+```python
+from vatly import AsyncVatlyClient
+
+
+async def read_orders():
+    async with AsyncVatlyClient() as vatly:
+        async for order in vatly.orders.list_all({"limit": 100}):
+            print(order.id, order.total)
+```
+
+Pydantic models use snake_case attributes and accept Vatly's camelCase aliases.
+Dictionary inputs use **wire-format camelCase keys**. Model requests serialize with
+aliases and omit unset fields; explicitly supplied `None` is sent as JSON null.
+Money values remain decimal **strings**, never floats.
+
+## Configuration and reliability
+
+```python
+from vatly import VatlyClient, RequestOptions
+
+with VatlyClient(timeout=30, max_retries=2) as vatly:
+    page = vatly.customers.list({"limit": 25}, options=RequestOptions(timeout=10))
+```
+
+Timeouts are **seconds per httpx network phase per attempt**, not a total request deadline;
+zero disables timeouts. Default base URL: `https://api.vatly.com/v1`.
+`base_url`, `default_headers`, and `transport` (an httpx transport) can be overridden.
+`mode` exposes `test` or `live`. Test helpers reject live keys before sending.
+
+POST/PATCH/PUT/DELETE receive a UUID idempotency key, reused across retries.
+Set `RequestOptions(idempotency_key="your-operation-id")` to reuse a business-operation key
+across separate SDK calls. Set `idempotency_key_generator=None` to disable auto-keys.
+GETs and keyed mutations retry 429, 5xx, timeouts and connection errors with exponential
+backoff (250ms to 8s plus jitter), honoring numeric or HTTP-date `Retry-After`.
+Keyed 409 retries **only** `details.idempotency_outcome == "in_progress"`.
+Never blindly retry an `unknown` idempotency outcome: read/reconcile the resource first.
+Unkeyed mutations do not retry. Redirects are not followed.
+
+`Vatly-Client-Info` identifies SDK/runtime/OS/architecture. Pass
+`client_info={"app": "MyApp/1.0", "framework": "Django/5"}` to add sanitized identifiers,
+or `client_info=False` to suppress the SDK-generated header.
+
+## Errors
+
+All API/transport errors extend `VatlyError`, with `status`, `body`, `url`, `method`,
+`details`, `errors` and `retry_after`. Network errors retain the httpx exception as `__cause__`.
+
+| Status | Error |
+| --- | --- |
+| 401 | `VatlyAuthError` |
+| 403 | `VatlyForbiddenError` |
+| 404 | `VatlyNotFoundError` |
+| 409 | `VatlyConflictError` |
+| 422 | `VatlyValidationError` |
+| 429 | `VatlyRateLimitError` |
+| Other / invalid response | `VatlyApiError` |
+| Network / timeout | `VatlyConnectionError` / `VatlyTimeoutError` |
+
+```python
+from vatly import VatlyValidationError
+
+try:
+    # Your API call here
+    pass
+except VatlyValidationError as error:
+    print(error.errors)
+```
+
+See [getting started and resource guides](docs/README.md), the generated
+[method inventory](docs/API.md), [webhook guide](docs/Webhooks.md), and
+[production API reference](https://docs.vatly.com/api-reference).
+
+## Development
+
+Run `.agents/setup` in a fresh orb. It installs uv if missing, provisions Python 3.12,
+syncs locked dependencies and runs an import sanity check. Warm runs reuse uv's caches.
+
+```bash
+uv run python scripts/generate.py --check
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv build
+uv run twine check dist/*
+```
+
+See [maintainer notes](docs/Development.md) for spec regeneration, docs sync, and trusted publishing.

vatly_api_python-0.1.0a2/README.md

@@ -0,0 +1,126 @@
+# Vatly Python SDK
+
+> **Alpha — under active development. Every alpha release may include breaking changes. Pin exact versions during alpha.**
+
+Python SDK for Vatly, the merchant of record for AI, software and digital products.
+Python 3.10+, Pydantic v2 models, and pooled httpx sync/async clients. All 50 production
+OpenAPI operations are covered. No package has been published yet.
+
+## Installation
+
+Once published:
+
+```bash
+pip install vatly-api-python==0.1.0a2
+```
+
+For local development: `uv sync --locked`.
+
+## Quick start
+
+Get a test or live API key from [the dashboard](https://my.vatly.com), under Settings > API.
+Keep keys server-side. The client reads `VATLY_API_KEY` by default.
+
+```python
+from vatly import VatlyClient
+from vatly.models import CreateCheckoutRequest
+
+with VatlyClient() as vatly:
+    checkout = vatly.checkouts.create(
+        CreateCheckoutRequest(
+            redirect_url_success="https://example.com/success",
+            redirect_url_canceled="https://example.com/canceled",
+            products=[{"id": "subscription_plan_abc123", "quantity": 1}],
+        )
+    )
+    print(checkout.links.checkout_url.href)
+```
+
+```python
+from vatly import AsyncVatlyClient
+
+
+async def read_orders():
+    async with AsyncVatlyClient() as vatly:
+        async for order in vatly.orders.list_all({"limit": 100}):
+            print(order.id, order.total)
+```
+
+Pydantic models use snake_case attributes and accept Vatly's camelCase aliases.
+Dictionary inputs use **wire-format camelCase keys**. Model requests serialize with
+aliases and omit unset fields; explicitly supplied `None` is sent as JSON null.
+Money values remain decimal **strings**, never floats.
+
+## Configuration and reliability
+
+```python
+from vatly import VatlyClient, RequestOptions
+
+with VatlyClient(timeout=30, max_retries=2) as vatly:
+    page = vatly.customers.list({"limit": 25}, options=RequestOptions(timeout=10))
+```
+
+Timeouts are **seconds per httpx network phase per attempt**, not a total request deadline;
+zero disables timeouts. Default base URL: `https://api.vatly.com/v1`.
+`base_url`, `default_headers`, and `transport` (an httpx transport) can be overridden.
+`mode` exposes `test` or `live`. Test helpers reject live keys before sending.
+
+POST/PATCH/PUT/DELETE receive a UUID idempotency key, reused across retries.
+Set `RequestOptions(idempotency_key="your-operation-id")` to reuse a business-operation key
+across separate SDK calls. Set `idempotency_key_generator=None` to disable auto-keys.
+GETs and keyed mutations retry 429, 5xx, timeouts and connection errors with exponential
+backoff (250ms to 8s plus jitter), honoring numeric or HTTP-date `Retry-After`.
+Keyed 409 retries **only** `details.idempotency_outcome == "in_progress"`.
+Never blindly retry an `unknown` idempotency outcome: read/reconcile the resource first.
+Unkeyed mutations do not retry. Redirects are not followed.
+
+`Vatly-Client-Info` identifies SDK/runtime/OS/architecture. Pass
+`client_info={"app": "MyApp/1.0", "framework": "Django/5"}` to add sanitized identifiers,
+or `client_info=False` to suppress the SDK-generated header.
+
+## Errors
+
+All API/transport errors extend `VatlyError`, with `status`, `body`, `url`, `method`,
+`details`, `errors` and `retry_after`. Network errors retain the httpx exception as `__cause__`.
+
+| Status | Error |
+| --- | --- |
+| 401 | `VatlyAuthError` |
+| 403 | `VatlyForbiddenError` |
+| 404 | `VatlyNotFoundError` |
+| 409 | `VatlyConflictError` |
+| 422 | `VatlyValidationError` |
+| 429 | `VatlyRateLimitError` |
+| Other / invalid response | `VatlyApiError` |
+| Network / timeout | `VatlyConnectionError` / `VatlyTimeoutError` |
+
+```python
+from vatly import VatlyValidationError
+
+try:
+    # Your API call here
+    pass
+except VatlyValidationError as error:
+    print(error.errors)
+```
+
+See [getting started and resource guides](docs/README.md), the generated
+[method inventory](docs/API.md), [webhook guide](docs/Webhooks.md), and
+[production API reference](https://docs.vatly.com/api-reference).
+
+## Development
+
+Run `.agents/setup` in a fresh orb. It installs uv if missing, provisions Python 3.12,
+syncs locked dependencies and runs an import sanity check. Warm runs reuse uv's caches.
+
+```bash
+uv run python scripts/generate.py --check
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+uv build
+uv run twine check dist/*
+```
+
+See [maintainer notes](docs/Development.md) for spec regeneration, docs sync, and trusted publishing.

vatly_api_python-0.1.0a2/docs/API.md

@@ -0,0 +1,110 @@
+# API reference
+
+Generated from `openapi.yaml`. Sync and async clients expose the same methods.
+Pass a Pydantic request/params model or a wire-format dictionary. All methods accept keyword-only `options=RequestOptions(...)`.
+
+## `checkouts`
+
+| Method | HTTP endpoint | Returns |
+| --- | --- | --- |
+| `list(params=None)` | `GET /checkouts` | `Page[Checkout]` |
+| `create(body)` | `POST /checkouts` | `Checkout` |
+| `get(checkout_id)` | `GET /checkouts/{checkoutId}` | `Checkout` |
+
+## `customers`
+
+| Method | HTTP endpoint | Returns |
+| --- | --- | --- |
+| `list(params=None)` | `GET /customers` | `Page[Customer]` |
+| `create(body)` | `POST /customers` | `Customer` |
+| `get(customer_id)` | `GET /customers/{customerId}` | `Customer` |
+| `update(customer_id, body)` | `PATCH /customers/{customerId}` | `Customer` |
+| `create_portal_session(customer_id, body)` | `POST /customers/{customerId}/portal-sessions` | `PortalSession` |
+| `list_subscriptions(customer_id, params=None)` | `GET /customers/{customerId}/subscriptions` | `Page[Subscription]` |
+| `get_subscription(customer_id, subscription_id)` | `GET /customers/{customerId}/subscriptions/{subscriptionId}` | `Subscription` |
+
+## `one_off_products`
+
+| Method | HTTP endpoint | Returns |
+| --- | --- | --- |
+| `list(params=None)` | `GET /one-off-products` | `Page[OneOffProduct]` |
+| `create(body)` | `POST /one-off-products` | `OneOffProduct` |
+| `get(one_off_product_id)` | `GET /one-off-products/{oneOffProductId}` | `OneOffProduct` |
+| `update(one_off_product_id, body)` | `PATCH /one-off-products/{oneOffProductId}` | `OneOffProduct` |
+| `archive(one_off_product_id)` | `POST /one-off-products/{oneOffProductId}/archive` | `None` |
+| `unarchive(one_off_product_id)` | `DELETE /one-off-products/{oneOffProductId}/archive` | `OneOffProduct` |
+
+## `subscription_plans`
+
+| Method | HTTP endpoint | Returns |
+| --- | --- | --- |
+| `list(params=None)` | `GET /subscription-plans` | `Page[SubscriptionPlan]` |
+| `create(body)` | `POST /subscription-plans` | `SubscriptionPlan` |
+| `get(subscription_plan_id)` | `GET /subscription-plans/{subscriptionPlanId}` | `SubscriptionPlan` |
+| `update(subscription_plan_id, body)` | `PATCH /subscription-plans/{subscriptionPlanId}` | `SubscriptionPlan` |
+| `archive(subscription_plan_id)` | `POST /subscription-plans/{subscriptionPlanId}/archive` | `None` |
+| `unarchive(subscription_plan_id)` | `DELETE /subscription-plans/{subscriptionPlanId}/archive` | `SubscriptionPlan` |
+
+## `orders`
+
+| Method | HTTP endpoint | Returns |
+| --- | --- | --- |
+| `list(params=None)` | `GET /orders` | `Page[Order]` |
+| `get(order_id)` | `GET /orders/{orderId}` | `Order` |
+| `create_invoice_update_link(order_id)` | `POST /orders/{orderId}/invoice-update-link` | `InvoiceUpdateLink` |
+| `list_refunds(order_id, params=None)` | `GET /orders/{orderId}/refunds` | `Page[Refund]` |
+| `create_refund(order_id, body)` | `POST /orders/{orderId}/refunds` | `Refund` |
+| `create_full_refund(order_id, body)` | `POST /orders/{orderId}/refunds/full` | `Refund` |
+| `get_refund(order_id, refund_id)` | `GET /orders/{orderId}/refunds/{refundId}` | `Refund` |
+| `cancel_refund(order_id, refund_id)` | `DELETE /orders/{orderId}/refunds/{refundId}` | `None` |
+| `list_chargebacks(order_id, params=None)` | `GET /orders/{orderId}/chargebacks` | `Page[Chargeback]` |
+| `get_chargeback(order_id, chargeback_id)` | `GET /orders/{orderId}/chargebacks/{chargebackId}` | `Chargeback` |
+
+## `refunds`
+
+| Method | HTTP endpoint | Returns |
+| --- | --- | --- |
+| `list(params=None)` | `GET /refunds` | `Page[Refund]` |
+| `get(refund_id)` | `GET /refunds/{refundId}` | `Refund` |
+
+## `chargebacks`
+
+| Method | HTTP endpoint | Returns |
+| --- | --- | --- |
+| `list(params=None)` | `GET /chargebacks` | `Page[Chargeback]` |
+| `get(chargeback_id)` | `GET /chargebacks/{chargebackId}` | `Chargeback` |
+
+## `webhook_events`
+
+| Method | HTTP endpoint | Returns |
+| --- | --- | --- |
+| `get(event_id)` | `GET /webhook-events/{eventId}` | `WebhookEvent` |
+
+## `webhook_endpoints`
+
+| Method | HTTP endpoint | Returns |
+| --- | --- | --- |
+| `list(params=None)` | `GET /webhook-endpoints` | `Page[WebhookEndpoint]` |
+| `create(body)` | `POST /webhook-endpoints` | `WebhookEndpoint` |
+| `get(webhook_endpoint_id)` | `GET /webhook-endpoints/{webhookEndpointId}` | `WebhookEndpoint` |
+| `update(webhook_endpoint_id, body)` | `PATCH /webhook-endpoints/{webhookEndpointId}` | `WebhookEndpoint` |
+| `delete(webhook_endpoint_id)` | `DELETE /webhook-endpoints/{webhookEndpointId}` | `None` |
+
+## `subscriptions`
+
+| Method | HTTP endpoint | Returns |
+| --- | --- | --- |
+| `list(params=None)` | `GET /subscriptions` | `Page[Subscription]` |
+| `get(subscription_id)` | `GET /subscriptions/{subscriptionId}` | `Subscription` |
+| `update(subscription_id, body)` | `PATCH /subscriptions/{subscriptionId}` | `Subscription` |
+| `cancel(subscription_id, params=None)` | `DELETE /subscriptions/{subscriptionId}` | `None` |
+| `create_billing_update_link(subscription_id, body)` | `POST /subscriptions/{subscriptionId}/billing-update-link` | `CreateSubscriptionBillingUpdateLinkResponse` |
+| `resume(subscription_id)` | `POST /subscriptions/{subscriptionId}/resume` | `Subscription` |
+
+## `test_helpers`
+
+| Method | HTTP endpoint | Returns |
+| --- | --- | --- |
+| `fast_forward_renewal(subscription_id, body)` | `POST /test-helpers/subscriptions/{subscriptionId}/fast-forward-renewal` | `Subscription` |
+| `simulate_order_payment(order_id, body)` | `POST /test-helpers/orders/{orderId}/simulate-payment` | `Order` |
+

vatly_api_python-0.1.0a2/docs/Chargebacks.md

@@ -0,0 +1,11 @@
+# Chargebacks
+
+Read disputes via `client.chargebacks.list`, `list_all`, and `get`, or the
+order-scoped `orders.list_chargebacks`, `list_all_chargebacks`, and `get_chargeback`.
+All are read-only. Preserve the signed financial snapshot for accounting.
+
+`order.chargeback_received` and `order.chargeback_reversed` webhook deliveries
+carry a Chargeback in `object` even though `entity_type` is `order`.
+Use `object.resource`, not the envelope entity type, to inspect the resource.
+
+See [method inventory](API.md#chargebacks) and [chargeback fields](https://docs.vatly.com/api-reference/chargebacks).

vatly_api_python-0.1.0a2/docs/Checkouts.md

@@ -0,0 +1,14 @@
+# Checkouts
+
+Use `client.checkouts.create(CreateCheckoutRequest(...))` to create a hosted payment
+page. Redirect to `checkout.links.checkout_url.href`. Products use Vatly catalogue
+IDs and quantities. Both success/cancellation redirect URLs are required. Use
+`customer_id` for an existing authorized customer, or omit it for an anonymous flow.
+
+Read one checkout with `get(id)`, one page with `list(params)`, or iterate with
+`list_all(params)`. Async clients use `await` and `async for` respectively.
+Reuse a business-operation idempotency key across caller retries. Confirm payment
+through signed webhooks, not a browser redirect. A checkout's `order_id` links to
+the order; the checkout itself intentionally has no products array.
+
+See [method inventory](API.md#checkouts) and [production checkout fields](https://docs.vatly.com/api-reference/checkouts).

vatly_api_python-0.1.0a2/docs/Customers.md

@@ -0,0 +1,12 @@
+# Customers
+
+`client.customers` provides `create`, `get`, `update`, `list`, `list_all`,
+`create_portal_session`, `list_subscriptions`, `list_all_subscriptions`, and
+`get_subscription`. Filter by email via `ListCustomersParams(email=...)` or
+`{"email": "person@example.com"}`. Email identity is storefront- and mode-scoped.
+
+`update` changes identity name/email, not billing-address details. Portal sessions
+are short-lived and single-use: redirect to the returned `url`; do not store it as
+a permanent link. Pass `{}` for an empty portal-session request body.
+
+See [method inventory](API.md#customers) and [customer fields](https://docs.vatly.com/api-reference/customers).

vatly_api_python-0.1.0a2/docs/Development.md

@@ -0,0 +1,55 @@
+# Development and release
+
+## Sources
+
+`openapi.yaml` was fetched on 2026-11-09 from https://docs.vatly.com/openapi.yaml,
+byte-identical to `vatly/vatly-docs/public/openapi.yaml` at
+`7e71ade32d311b10f79e10c15d0ac03ae32bde97`.
+SHA-256: `69640ac82bbba8d101e6aa882facd5f13aa5cf67f38508e5cea18abef03c4940`.
+The spec's generated-at date is not the retrieval date.
+JS design reference: `vatly/vatly-api-js` at `8b0b920c29f7e7b30bf71b9e379ec0a8a1a22028`.
+
+To update, deliberately replace the pinned spec from that production URL, update
+this provenance, run `uv run python scripts/generate.py`, inspect the diff, and
+run all README checks. CI checks regeneration offline. Do not edit generated files.
+
+Output objects preserve extra fields. URLs/emails remain strings. Input enums
+and constraints are generated from the spec. Two observed production differences
+are handled explicitly: empty metadata `[]` normalizes to `{}`, and the output
+OneOffProduct.productType is an open string (production returns `digital_download`).
+The checked-in spec is not patched. Response validation failures surface as
+`VatlyApiError` with the Pydantic cause; response bodies may contain personal data.
+Do not log them indiscriminately.
+
+## Documentation sync
+
+`docs/README.md`, `API.md`, and the resource guides mirror the JS SDK's layout.
+They are self-contained Markdown for a future vatly-docs Python SDK sync; no sync
+job or changes to the docs repository are made here. Keep relative links portable.
+`API.md` is generated; prose guides are maintained manually.
+
+## Orb setup
+
+`.agents/setup` is executable, provisions uv 0.12.9 and Python 3.12, syncs the
+lockfile, and checks imports. It does not read API credentials or make API calls.
+Run twice to check warm behavior. No services or resume repairs are needed.
+It will become available to project orbs once pushed to the default branch and
+the repository is connected as an Amp project.
+
+## Future PyPI release (not executed)
+
+The distribution name `vatly-api-python` returned 404 from PyPI's JSON API on 2026-11-12.
+Availability is not a reservation or guarantee of PyPI name approval.
+
+1. Push reviewed code to the private `vatly/vatly-api-python` repository's main branch.
+2. Configure a PyPI pending trusted publisher for project `vatly-api-python`, owner `vatly`,
+   repository `vatly-api-python`, workflow `release.yml`; leave the environment field blank.
+   No GitHub environment or PyPI token is needed.
+3. Update both package-version sources and changelog, run CI, and only with approval
+   create a `v0.1.0a2` tag and publish its GitHub release (mark it a prerelease).
+4. The release workflow validates/builds first, then exchanges GitHub OIDC for PyPI
+   credentials. Anyone able to publish a matching GitHub release can initiate publication;
+   restrict repository release access accordingly. Publish the SDK before Fluent.
+
+**A private GitHub repository does not make PyPI artifacts private.** Publishing
+uploads the wheel and sdist publicly, including their source and packaged docs.

vatly_api_python-0.1.0a2/docs/OneOffProducts.md

@@ -0,0 +1,12 @@
+# One-off products
+
+`client.one_off_products` provides `list`, `list_all`, `get`, `create`, `update`,
+`archive`, and `unarchive`. Use `CreateOneOffProductRequest` and
+`UpdateOneOffProductRequest` from `vatly.models`. `archive` returns `None`;
+`unarchive` returns the resource. Mode and approval behavior follow the API key.
+
+The output `product_type` preserves catalogue strings not yet listed in the
+production spec (including observed `digital_download`). Request validation still
+follows the production request schema. Unknown response fields are preserved.
+
+See [method inventory](API.md#one_off_products) and [product fields](https://docs.vatly.com/api-reference/one-off-products).

vatly_api_python-0.1.0a2/docs/Orders.md

@@ -0,0 +1,15 @@
+# Orders
+
+`client.orders` provides read/pagination plus nested refunds and chargebacks.
+`create_invoice_update_link(order_id)` returns a hosted billing-details update
+link. Financial money values remain decimal strings. Tax and metadata fields are
+retained; do not reconstruct invoices from rounded float calculations.
+
+An order line's `product_type` selects what `product_id` refers to. Readers must
+support historical `subscription_plan` lines (plan IDs) and `subscription` lines
+(subscription IDs). Pending core PR #2910 also stamps initial checkout lines with
+the intended subscription ID. An intended ID may temporarily 404 or never resolve
+for a skipped trial start: use bounded recovery and inspect status, not ID presence,
+before granting access. One-off lines are unaffected.
+
+See [method inventory](API.md#orders) and [order fields](https://docs.vatly.com/api-reference/orders).

vatly_api_python-0.1.0a2/docs/README.md

@@ -0,0 +1,25 @@
+# Getting started
+
+> **Alpha — under active development. Every alpha release may include breaking changes. Pin exact versions during alpha.**
+
+Use `vatly-api-python==0.1.0a2` (once published), imported as `vatly`. Requires Python 3.10+.
+Create `VatlyClient` inside `with`, or `AsyncVatlyClient` inside `async with`, to
+close the connection pool. Both accept an explicit API key or `VATLY_API_KEY`.
+Test and live modes use the same API host; keys select the mode.
+
+See the [SDK README](../README.md) for runnable initialization, checkout,
+pagination, retries, configuration, errors and development commands.
+
+| Guide | Purpose |
+| --- | --- |
+| [API](API.md) | Every method, endpoint and response |
+| [Checkouts](Checkouts.md) | Hosted payment pages |
+| [Customers](Customers.md) | Customer identity and portal sessions |
+| [Subscriptions](Subscriptions.md) | Recurring billing |
+| [Subscription Plans](SubscriptionPlans.md) | Subscription catalogue |
+| [One-Off Products](OneOffProducts.md) | One-time catalogue |
+| [Orders](Orders.md) | Transactions and nested financial operations |
+| [Refunds](Refunds.md) | Reversals |
+| [Chargebacks](Chargebacks.md) | Disputes |
+| [Webhooks](Webhooks.md) | Signatures, events and endpoints |
+| [Development](Development.md) | Spec/docs sync, setup, release |

vatly_api_python-0.1.0a2/docs/Refunds.md

@@ -0,0 +1,13 @@
+# Refunds
+
+Read refunds via `client.refunds.list`, `list_all`, and `get`. Order-scoped
+operations are `orders.list_refunds`, `list_all_refunds`, `get_refund`,
+`create_refund`, `create_full_refund`, and `cancel_refund`.
+
+Partial refunds use `CreateRefundRequest` with order lines and amounts; full
+refunds accept `CreateFullRefundRequest` or `{}`. A cancellation returns `None`.
+Use stable idempotency keys for business operations; a timeout does not prove
+that a refund failed. Read/reconcile before issuing another mutation when the
+server reports an unknown outcome. Webhooks confirm completion/failure/cancellation.
+
+See [method inventory](API.md#refunds) and [refund fields](https://docs.vatly.com/api-reference/refunds).

vatly_api_python-0.1.0a2/docs/SubscriptionPlans.md

@@ -0,0 +1,13 @@
+# Subscription plans
+
+`client.subscription_plans` provides `list`, `list_all`, `get`, `create`, `update`,
+`archive`, and `unarchive`. Use `CreateSubscriptionPlanRequest` and
+`UpdateSubscriptionPlanRequest` from `vatly.models`. Money is a decimal string
+plus currency; preserve both. Archiving returns `None`, unarchiving the plan.
+
+Test-mode catalogue changes are auto-approved; live changes may await approval.
+Archive prevents new sales, not existing subscription renewals. Select
+`includeArchived` in dictionary filters when needed, or the corresponding model's
+`include_archived` field.
+
+See [method inventory](API.md#subscription_plans) and [plan fields](https://docs.vatly.com/api-reference/subscription-plans).

vatly_api_python-0.1.0a2/docs/Subscriptions.md

@@ -0,0 +1,21 @@
+# Subscriptions
+
+Use `client.subscriptions.get(id)`, `list(params)`, or `list_all(params)` to read.
+Create a subscription through a checkout containing a subscription-plan ID.
+
+`update(id, body)` changes plan, price or quantity. At least one is required;
+`trial_until` cannot be sent alone. By default updates are scheduled; request
+`apply_immediately` and the relevant invoice/proration flags deliberately.
+`cancel(id, {"immediately": True})` encodes the boolean as `1`, as the server expects.
+`resume(id)` is only valid during the cancellation grace period.
+
+`create_billing_update_link(id, body)` returns a hosted link for billing details;
+both redirect URLs are required. Check remote status before granting entitlements.
+The signed subscription events carry full snapshots, including scheduled changes,
+mandate, cancellation reason, and renewal periods.
+
+Test-only helpers live under `client.test_helpers`: `fast_forward_renewal` and
+`simulate_order_payment`. They mutate remote data and must never run in CI/live
+verification without explicit intent. This repository's tests use mocks only.
+
+See [method inventory](API.md#subscriptions) and [subscription fields](https://docs.vatly.com/api-reference/subscriptions).