selectwin 0.1.0__tar.gz

selectwin-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# env & misc
+.env
+.env*.local
+.DS_Store
+
+# NOTE: src/selectwin/_core IS committed — it's the generated core synced from
+# selectwin-sdks (scripts/sync_core.py). Do not ignore it.

selectwin-0.1.0/LICENSE

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

selectwin-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: selectwin
+Version: 0.1.0
+Summary: Official Selectwin Python SDK — payments (card, PIX, boleto), subscriptions, webhooks.
+Project-URL: Homepage, https://docs.selectwin.io
+Project-URL: Repository, https://github.com/selectwin/sdk-python
+Author-email: Selectwin <help@selectwin.io>
+License: MIT
+License-File: LICENSE
+Keywords: api,boleto,payments,pix,sdk,selectwin,subscriptions,webhooks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: attrs>=21.3.0
+Requires-Dist: httpx>=0.23
+Requires-Dist: python-dateutil>=2.8.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.6; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# selectwin (Python)
+
+Official **Selectwin** Python SDK — payments (credit card, PIX, boleto),
+subscriptions, wallets, webhooks and more. Sync **and** async, fully typed.
+
+> Status: **early / work in progress** (`0.1.0`). Generated core (openapi-python-client,
+> httpx sync+async) + a hand-written DX shell (typed errors, retries, idempotency,
+> pagination, webhook verification).
+
+```bash
+pip install selectwin
+```
+
+## Quickstart
+
+```python
+import os
+from selectwin import Selectwin, CardError
+
+sw = Selectwin(api_key=os.environ["SELECTWIN_API_KEY"])  # sk_test_… / sk_live_…
+
+# Create a PIX transaction (amounts in cents)
+tx = sw.transactions.create({"amount": 9990, "payment": {"method": "pix", "currency": "BRL"}})
+
+# id / id+body aliases
+one = sw.transactions.retrieve("tra_…")
+sw.subscriptions.pause("subs_…")
+
+# Typed errors — branch on the class / error.code, never the message
+try:
+    sw.transactions.create({...})
+except CardError as e:
+    print(e.display_message, e.reversible)  # buyer-facing + retryable
+```
+
+### Async
+
+```python
+import asyncio
+from selectwin import AsyncSelectwin
+
+async def main():
+    async with AsyncSelectwin(api_key="sk_test_…") as sw:
+        tx = await sw.transactions.create({"amount": 9990, "payment": {"method": "pix", "currency": "BRL"}})
+        async for t in sw.transactions.list(limit=100):
+            ...
+
+asyncio.run(main())
+```
+
+### Pagination
+
+Top-level `list()` methods return a pager that is both a page fetcher and an iterator:
+
+```python
+# sync — stream every transaction across all pages
+for tx in sw.transactions.list(limit=100):
+    ...
+
+first_page = sw.transactions.list(limit=20).first()   # a page object (.data, .has_more, …)
+some = sw.customers.list().to_list(max=500)            # collect, optionally capped
+
+# async
+async for tx in sw.transactions.list(limit=100):
+    ...
+```
+
+The full generated API (every `operation_id`) is always reachable via `.raw`:
+
+```python
+from selectwin._core.api.transactions import create_transaction
+# or the bound escape hatch:
+sw.transactions.raw  # the generated module for this resource
+```
+
+### Webhooks
+
+```python
+# raw_body MUST be the exact bytes/str received (do not re-serialize)
+event = sw.webhooks.construct_event(
+    raw_body,
+    request.headers["x-selectwin-signature"],
+    os.environ["SELECTWIN_WEBHOOK_SECRET"],  # whsec_…
+)
+if event.type == "transaction.approved":
+    obj = event.payload.object
+```
+
+`WEBHOOK_EVENT_TYPES` (the authoritative catalog) and `is_webhook_event_type()` are
+exported for validation; `WebhookEventType` is a `typing.Literal` of every event type.
+
+## What the SDK adds over the raw generated client
+
+The package is a **generated core** (openapi-python-client, from the OpenAPI v2.0.0
+spec) + a **hand-written DX shell**:
+
+- **Typed clients** — `Selectwin(api_key=…)` (sync) and `AsyncSelectwin(api_key=…)`
+  (async context manager) exposing `sw.transactions`, `sw.subscriptions`, `sw.customers`, …
+- **Stripe-style aliases** per resource (`create` / `retrieve` / `update` / `list` /
+  `delete` + custom verbs), accepting a dict or the generated body model; `.raw` exposes
+  the full generated surface.
+- **Typed errors** by HTTP status / `error.code`: `CardError` (402, `display_message`/
+  `reversible`), `ValidationError` (`params`), `RateLimitError` (`retry_after`),
+  `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`,
+  `APIError`, `APIConnectionError`.
+- **Auto-retries** (429/5xx/network) with exponential backoff, honouring `Retry-After`.
+- **Idempotency** — an `X-Idempotency-Key` is added to every mutation (override per call).
+- **Timeouts** and one shared, pre-authenticated `httpx` client per SDK client.
+- **Auto-pagination** — sync (`for …`) and async (`async for …`) iterators, `.first()`,
+  `.to_list(max=…)`, `.pages()`.
+- **Webhook verification** — `construct_event` (HMAC-SHA256 of the raw body, constant-time).
+
+Auth is the `SelectKey` header; the environment (sandbox/production) is resolved from the
+key prefix (`sk_test_` / `sk_live_`).
+
+## Architecture
+
+```
+src/selectwin/
+  _core/            # openapi-python-client output — DO NOT edit; synced from selectwin-sdks
+  resources.py      # GENERATED Stripe-style namespaces (sync + async) — DO NOT edit
+  webhook_events.py # GENERATED webhook Event Catalog (types + guard) — DO NOT edit
+  errors.py         # typed error hierarchy
+  http.py           # httpx transport (retries/timeout) + hooks (idempotency, UA) + error mapping
+  pagination.py     # SyncPager / AsyncPager
+  webhooks.py       # construct_event (signature verification)
+  client.py         # Selectwin / AsyncSelectwin — wire auth + the custom httpx client
+```
+
+Cross-cutting concerns are injected **once** into the httpx client shared by the generated
+core, so every endpoint inherits them and new endpoints work automatically on regen.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python scripts/sync_core.py          # copy the generated core from selectwin-sdks + regen
+python scripts/gen_resources.py      # regenerate src/selectwin/resources.py
+python scripts/gen_webhook_events.py # regenerate src/selectwin/webhook_events.py
+pytest                               # unit suite
+pytest -m integration                # sandbox suite (needs SELECTWIN_SANDBOX_KEY; see tests/integration)
+mypy src/selectwin                   # type-check the DX shell
+```
+
+## Roadmap
+
+- Publish to PyPI (Trusted Publishing / OIDC) once the API stabilises; CI on PRs.

selectwin-0.1.0/README.md

@@ -0,0 +1,147 @@
+# selectwin (Python)
+
+Official **Selectwin** Python SDK — payments (credit card, PIX, boleto),
+subscriptions, wallets, webhooks and more. Sync **and** async, fully typed.
+
+> Status: **early / work in progress** (`0.1.0`). Generated core (openapi-python-client,
+> httpx sync+async) + a hand-written DX shell (typed errors, retries, idempotency,
+> pagination, webhook verification).
+
+```bash
+pip install selectwin
+```
+
+## Quickstart
+
+```python
+import os
+from selectwin import Selectwin, CardError
+
+sw = Selectwin(api_key=os.environ["SELECTWIN_API_KEY"])  # sk_test_… / sk_live_…
+
+# Create a PIX transaction (amounts in cents)
+tx = sw.transactions.create({"amount": 9990, "payment": {"method": "pix", "currency": "BRL"}})
+
+# id / id+body aliases
+one = sw.transactions.retrieve("tra_…")
+sw.subscriptions.pause("subs_…")
+
+# Typed errors — branch on the class / error.code, never the message
+try:
+    sw.transactions.create({...})
+except CardError as e:
+    print(e.display_message, e.reversible)  # buyer-facing + retryable
+```
+
+### Async
+
+```python
+import asyncio
+from selectwin import AsyncSelectwin
+
+async def main():
+    async with AsyncSelectwin(api_key="sk_test_…") as sw:
+        tx = await sw.transactions.create({"amount": 9990, "payment": {"method": "pix", "currency": "BRL"}})
+        async for t in sw.transactions.list(limit=100):
+            ...
+
+asyncio.run(main())
+```
+
+### Pagination
+
+Top-level `list()` methods return a pager that is both a page fetcher and an iterator:
+
+```python
+# sync — stream every transaction across all pages
+for tx in sw.transactions.list(limit=100):
+    ...
+
+first_page = sw.transactions.list(limit=20).first()   # a page object (.data, .has_more, …)
+some = sw.customers.list().to_list(max=500)            # collect, optionally capped
+
+# async
+async for tx in sw.transactions.list(limit=100):
+    ...
+```
+
+The full generated API (every `operation_id`) is always reachable via `.raw`:
+
+```python
+from selectwin._core.api.transactions import create_transaction
+# or the bound escape hatch:
+sw.transactions.raw  # the generated module for this resource
+```
+
+### Webhooks
+
+```python
+# raw_body MUST be the exact bytes/str received (do not re-serialize)
+event = sw.webhooks.construct_event(
+    raw_body,
+    request.headers["x-selectwin-signature"],
+    os.environ["SELECTWIN_WEBHOOK_SECRET"],  # whsec_…
+)
+if event.type == "transaction.approved":
+    obj = event.payload.object
+```
+
+`WEBHOOK_EVENT_TYPES` (the authoritative catalog) and `is_webhook_event_type()` are
+exported for validation; `WebhookEventType` is a `typing.Literal` of every event type.
+
+## What the SDK adds over the raw generated client
+
+The package is a **generated core** (openapi-python-client, from the OpenAPI v2.0.0
+spec) + a **hand-written DX shell**:
+
+- **Typed clients** — `Selectwin(api_key=…)` (sync) and `AsyncSelectwin(api_key=…)`
+  (async context manager) exposing `sw.transactions`, `sw.subscriptions`, `sw.customers`, …
+- **Stripe-style aliases** per resource (`create` / `retrieve` / `update` / `list` /
+  `delete` + custom verbs), accepting a dict or the generated body model; `.raw` exposes
+  the full generated surface.
+- **Typed errors** by HTTP status / `error.code`: `CardError` (402, `display_message`/
+  `reversible`), `ValidationError` (`params`), `RateLimitError` (`retry_after`),
+  `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`,
+  `APIError`, `APIConnectionError`.
+- **Auto-retries** (429/5xx/network) with exponential backoff, honouring `Retry-After`.
+- **Idempotency** — an `X-Idempotency-Key` is added to every mutation (override per call).
+- **Timeouts** and one shared, pre-authenticated `httpx` client per SDK client.
+- **Auto-pagination** — sync (`for …`) and async (`async for …`) iterators, `.first()`,
+  `.to_list(max=…)`, `.pages()`.
+- **Webhook verification** — `construct_event` (HMAC-SHA256 of the raw body, constant-time).
+
+Auth is the `SelectKey` header; the environment (sandbox/production) is resolved from the
+key prefix (`sk_test_` / `sk_live_`).
+
+## Architecture
+
+```
+src/selectwin/
+  _core/            # openapi-python-client output — DO NOT edit; synced from selectwin-sdks
+  resources.py      # GENERATED Stripe-style namespaces (sync + async) — DO NOT edit
+  webhook_events.py # GENERATED webhook Event Catalog (types + guard) — DO NOT edit
+  errors.py         # typed error hierarchy
+  http.py           # httpx transport (retries/timeout) + hooks (idempotency, UA) + error mapping
+  pagination.py     # SyncPager / AsyncPager
+  webhooks.py       # construct_event (signature verification)
+  client.py         # Selectwin / AsyncSelectwin — wire auth + the custom httpx client
+```
+
+Cross-cutting concerns are injected **once** into the httpx client shared by the generated
+core, so every endpoint inherits them and new endpoints work automatically on regen.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python scripts/sync_core.py          # copy the generated core from selectwin-sdks + regen
+python scripts/gen_resources.py      # regenerate src/selectwin/resources.py
+python scripts/gen_webhook_events.py # regenerate src/selectwin/webhook_events.py
+pytest                               # unit suite
+pytest -m integration                # sandbox suite (needs SELECTWIN_SANDBOX_KEY; see tests/integration)
+mypy src/selectwin                   # type-check the DX shell
+```
+
+## Roadmap
+
+- Publish to PyPI (Trusted Publishing / OIDC) once the API stabilises; CI on PRs.

selectwin-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "selectwin"
+version = "0.1.0"
+description = "Official Selectwin Python SDK — payments (card, PIX, boleto), subscriptions, webhooks."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Selectwin", email = "help@selectwin.io" }]
+keywords = ["selectwin", "payments", "pix", "boleto", "subscriptions", "webhooks", "api", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.23",
+  "attrs>=21.3.0",
+  "python-dateutil>=2.8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-asyncio>=0.21",
+  "respx>=0.20",
+  "mypy>=1.6",
+]
+
+[project.urls]
+Homepage = "https://docs.selectwin.io"
+Repository = "https://github.com/selectwin/sdk-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/selectwin"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/selectwin", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+markers = ["integration: sandbox integration tests (need SELECTWIN_SANDBOX_KEY)"]
+
+[tool.mypy]
+ignore_missing_imports = true
+# The generated core is checked by its own generator; focus mypy on the DX shell.
+exclude = ['^src/selectwin/_core/']

selectwin-0.1.0/src/selectwin/__init__.py

@@ -0,0 +1,59 @@
+"""Official Selectwin Python SDK.
+
+A generated core (openapi-python-client, httpx sync + async) plus a hand-written
+DX shell: typed client, typed errors, auto-retries, idempotency, sync/async
+pagination and webhook signature verification.
+"""
+
+from __future__ import annotations
+
+from .client import AsyncSelectwin, Selectwin, SDK_VERSION
+from .errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    CardError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    SelectwinError,
+    SignatureVerificationError,
+    ValidationError,
+    error_from_status,
+)
+from .pagination import AsyncPager, SyncPager
+from .webhook_events import WEBHOOK_EVENT_TYPES, WebhookEventType, is_webhook_event_type
+from .webhooks import SelectwinEvent, construct_event
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "__version__",
+    # clients
+    "Selectwin",
+    "AsyncSelectwin",
+    # errors
+    "SelectwinError",
+    "APIConnectionError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "ValidationError",
+    "CardError",
+    "RateLimitError",
+    "SignatureVerificationError",
+    "error_from_status",
+    # pagination
+    "SyncPager",
+    "AsyncPager",
+    # webhooks
+    "construct_event",
+    "SelectwinEvent",
+    # webhook event catalog
+    "WEBHOOK_EVENT_TYPES",
+    "WebhookEventType",
+    "is_webhook_event_type",
+]

selectwin-0.1.0/src/selectwin/_core/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing Selectwin Public API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

selectwin-0.1.0/src/selectwin/_core/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

selectwin-0.1.0/src/selectwin/_core/api/addresses/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

selectwin-0.1.0/src/selectwin/_core/api/addresses/create_address.py

@@ -0,0 +1,160 @@
+from http import HTTPStatus
+from typing import Any
+
+import httpx
+
+from ... import errors
+from ...client import AuthenticatedClient, Client
+from ...models.create_address_body import CreateAddressBody
+from ...models.create_address_response_201 import CreateAddressResponse201
+from ...types import Response
+
+
+def _get_kwargs(
+    *,
+    body: CreateAddressBody,
+) -> dict[str, Any]:
+    headers: dict[str, Any] = {}
+
+    _kwargs: dict[str, Any] = {
+        "method": "post",
+        "url": "/v1/addresses",
+    }
+
+    _kwargs["json"] = body.to_dict()
+
+    headers["Content-Type"] = "application/json"
+
+    _kwargs["headers"] = headers
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> CreateAddressResponse201 | None:
+    if response.status_code == 201:
+        response_201 = CreateAddressResponse201.from_dict(response.json())
+
+        return response_201
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[CreateAddressResponse201]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    *,
+    client: AuthenticatedClient | Client,
+    body: CreateAddressBody,
+) -> Response[CreateAddressResponse201]:
+    """Create an address
+
+    Args:
+        body (CreateAddressBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[CreateAddressResponse201]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    *,
+    client: AuthenticatedClient | Client,
+    body: CreateAddressBody,
+) -> CreateAddressResponse201 | None:
+    """Create an address
+
+    Args:
+        body (CreateAddressBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        CreateAddressResponse201
+    """
+
+    return sync_detailed(
+        client=client,
+        body=body,
+    ).parsed
+
+
+async def asyncio_detailed(
+    *,
+    client: AuthenticatedClient | Client,
+    body: CreateAddressBody,
+) -> Response[CreateAddressResponse201]:
+    """Create an address
+
+    Args:
+        body (CreateAddressBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[CreateAddressResponse201]
+    """
+
+    kwargs = _get_kwargs(
+        body=body,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    *,
+    client: AuthenticatedClient | Client,
+    body: CreateAddressBody,
+) -> CreateAddressResponse201 | None:
+    """Create an address
+
+    Args:
+        body (CreateAddressBody):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        CreateAddressResponse201
+    """
+
+    return (
+        await asyncio_detailed(
+            client=client,
+            body=body,
+        )
+    ).parsed