checkbox-site 0.1.0__tar.gz

checkbox_site-0.1.0/LICENSE

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

checkbox_site-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: checkbox-site
+Version: 0.1.0
+Summary: Checkbox: automatic-renewal-law compliance (ROSCA, California ARL, New York and other state laws) for subscription businesses. Official Python SDK.
+Author-email: Checkbox <support@checkbox.site>
+License-Expression: MIT
+Project-URL: Homepage, https://checkbox.site
+Project-URL: Documentation, https://checkbox.site/docs
+Project-URL: Repository, https://github.com/checkbox-site/checkbox
+Project-URL: Source, https://github.com/checkbox-site/checkbox/tree/main/python
+Project-URL: Issues, https://github.com/checkbox-site/checkbox/issues
+Keywords: subscription,auto-renewal,automatic renewal,compliance,ROSCA,click to cancel,stripe,checkout
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Checkbox Python SDK
+
+Automatic-renewal-law compliance (ROSCA, California Bus. & Prof. Code § 17600, New York GBL § 527-a and ~26 other state
+laws) for subscription businesses, as an API. Standard library only (`urllib`), Python 3.9+. Free to use.
+
+> **Package name.** `pip install checkbox-site` (the name in `pyproject.toml`; never install the unrelated `checkbox` or
+> `checkbox-sdk` packages). The import name is `checkbox`.
+
+## Quickstart
+
+```python
+from checkbox import Checkbox
+cb = Checkbox()  # reads CHECKBOX_API_KEY, then CHECKBOX_SECRET_KEY (ck_test_… written by `checkbox init`)
+check = cb.checks.stripe_checkout_session(params=session_params, merchant={"merchant_name": "Acme", "price": 19.99, "interval": "month"})
+print(check["verdict"], check["next_action"]["message"])
+params = check["correction"]["corrected_params"] if check["verdict"] == "fail" else session_params  # engine-verified fix
+```
+
+No key yet? Connect the MCP server (`setup_checkbox`) or call `POST /v1/device/authorize`: one browser approval creates the account and test keys. Test keys
+(`ck_test_…`) act on an isolated sandbox and never need activation.
+
+## What you get
+
+- **Every `/v1` operation** as `cb.<namespace>.<method>()`: `sites`, `checks`, `plans`, `tasks`, `verifications`,
+  `findings`, `fixes`, `scans`, `evaluations`, `evidence`, `certificates`, `notice_settings`, `law_updates`,
+  `test_runs`, `test_credentials`, `stripe_checkout_configs`, `disclosures`, `consents`, `elements`,
+  `domain_verifications`, `setup_sessions`, `device`, `webhook_endpoints`, `events`, `account`. Ids are positional;
+  parameters are keyword arguments or a dict: `cb.sites.update("site_…", name="Acme")` or
+  `cb.sites.update("site_…", {"name": "Acme"})`.
+- **Plain dict responses** with `TypedDict` hints for every object, request and webhook event (`checkbox.types`,
+  generated from the OpenAPI spec). `obj.last_response` holds `status_code`, `request_id`, `idempotent_replayed`,
+  `headers`.
+- **Pagination:** `for f in cb.findings.list(site=site_id).auto_paging_iter(): ...`
+- **Retries** on network errors, 409 `idempotency_key_in_use`, 429 (honours `Retry-After`) and 5xx with exponential
+  backoff (`max_network_retries`, default 2). **Idempotency keys** are generated for every POST that changes something
+  and reused across retries; pass your own with `request_options={"idempotency_key": "…"}`.
+- **Versioning:** sends `Checkbox-Version: 2026-10-30`; override with `Checkbox(api_version=…)` or per request.
+- **Mode:** `cb.mode` is `"test"` or `"live"` from the key prefix.
+- **Typed errors:** `InvalidRequestError`, `AuthenticationError`, `PermissionError`, `RateLimitError`,
+  `IdempotencyError`, `APIError`, `APIConnectionError` (all `CheckboxError`) with `code`, `param`, `status_code`,
+  `request_id`, `doc_url` and `next_action` (what an agent should do next).
+- **Webhooks:** `from checkbox import webhook; webhook.construct_event(raw_body, signature_header, secret)` (as in the docs), or the Stripe-style alias `checkbox.Webhook.construct_event(...)`.
+- **Agents / MCP:** `cb.call("verifyTask", {"task": "task_…", "wait": 30})` calls any operation by its operationId with
+  flat arguments.
+
+## Usage
+
+```python
+from checkbox import Checkbox, CheckboxError
+
+cb = Checkbox(max_network_retries=2, timeout=80, app_info={"name": "my-app", "version": "1.0.0"})
+
+site = cb.sites.create(url="https://acme.example", request_options={"idempotency_key": "site:acme.example"})
+plan = cb.plans.retrieve(site["id"])
+for task in plan["tasks"]:
+    print(task["id"], task["title"], task["next_action"]["description"])
+
+for finding in cb.findings.list(site=site["id"], status="fail").auto_paging_iter():
+    print(finding["check_id"], finding["requirements"][0]["citation"] if finding["requirements"] else "")
+
+# Errors carry a stable code and, for agents, next_action.
+try:
+    cb.certificates.create(site["id"])
+except CheckboxError as err:
+    # resource_conflict: not eligible yet (verify the domain, keep the site compliant for 7 days);
+    # account_not_activated: a live key before any domain is verified.
+    print(err.code, err.message, err.next_action)
+```
+
+## Webhooks
+
+```python
+# Flask
+@app.post("/webhooks/checkbox")
+def checkbox_webhook():
+    try:
+        event = checkbox.Webhook.construct_event(request.get_data(), request.headers.get("Checkbox-Signature"), os.environ["CHECKBOX_WEBHOOK_SECRET"])
+    except checkbox.SignatureVerificationError as err:
+        return {"error": err.message}, 400
+    print(event["type"], event["data"]["object"]["id"])
+    return {"received": True}
+```
+
+Pass the **raw** body (Django `request.body`, FastAPI `await request.body()`). Signatures older than 5 minutes are
+rejected (`tolerance=`).
+
+## Examples
+
+[`examples/`](examples/): [preflight a Stripe Checkout Session](examples/compliant_checkout.py) in a
+[Flask app](examples/flask_app.py) (with the webhook receiver), and [register a site](examples/register_site.py). The
+tests run them against the real API.
+
+## Development
+
+- `checkbox/types.py` and `checkbox/_resources.py` are generated from
+  [`openapi/checkbox.v1.json`](../openapi/checkbox.v1.json) in Checkbox's main codebase and mirrored here with each
+  release; see [CONTRIBUTING.md](../CONTRIBUTING.md).
+- Tests: `cd python && python -m pytest` (a local fake HTTP server; no network). Build: `python -m build`.
+- Releases: [RELEASING.md](../RELEASING.md).

checkbox_site-0.1.0/README.md

@@ -0,0 +1,99 @@
+# Checkbox Python SDK
+
+Automatic-renewal-law compliance (ROSCA, California Bus. & Prof. Code § 17600, New York GBL § 527-a and ~26 other state
+laws) for subscription businesses, as an API. Standard library only (`urllib`), Python 3.9+. Free to use.
+
+> **Package name.** `pip install checkbox-site` (the name in `pyproject.toml`; never install the unrelated `checkbox` or
+> `checkbox-sdk` packages). The import name is `checkbox`.
+
+## Quickstart
+
+```python
+from checkbox import Checkbox
+cb = Checkbox()  # reads CHECKBOX_API_KEY, then CHECKBOX_SECRET_KEY (ck_test_… written by `checkbox init`)
+check = cb.checks.stripe_checkout_session(params=session_params, merchant={"merchant_name": "Acme", "price": 19.99, "interval": "month"})
+print(check["verdict"], check["next_action"]["message"])
+params = check["correction"]["corrected_params"] if check["verdict"] == "fail" else session_params  # engine-verified fix
+```
+
+No key yet? Connect the MCP server (`setup_checkbox`) or call `POST /v1/device/authorize`: one browser approval creates the account and test keys. Test keys
+(`ck_test_…`) act on an isolated sandbox and never need activation.
+
+## What you get
+
+- **Every `/v1` operation** as `cb.<namespace>.<method>()`: `sites`, `checks`, `plans`, `tasks`, `verifications`,
+  `findings`, `fixes`, `scans`, `evaluations`, `evidence`, `certificates`, `notice_settings`, `law_updates`,
+  `test_runs`, `test_credentials`, `stripe_checkout_configs`, `disclosures`, `consents`, `elements`,
+  `domain_verifications`, `setup_sessions`, `device`, `webhook_endpoints`, `events`, `account`. Ids are positional;
+  parameters are keyword arguments or a dict: `cb.sites.update("site_…", name="Acme")` or
+  `cb.sites.update("site_…", {"name": "Acme"})`.
+- **Plain dict responses** with `TypedDict` hints for every object, request and webhook event (`checkbox.types`,
+  generated from the OpenAPI spec). `obj.last_response` holds `status_code`, `request_id`, `idempotent_replayed`,
+  `headers`.
+- **Pagination:** `for f in cb.findings.list(site=site_id).auto_paging_iter(): ...`
+- **Retries** on network errors, 409 `idempotency_key_in_use`, 429 (honours `Retry-After`) and 5xx with exponential
+  backoff (`max_network_retries`, default 2). **Idempotency keys** are generated for every POST that changes something
+  and reused across retries; pass your own with `request_options={"idempotency_key": "…"}`.
+- **Versioning:** sends `Checkbox-Version: 2026-10-30`; override with `Checkbox(api_version=…)` or per request.
+- **Mode:** `cb.mode` is `"test"` or `"live"` from the key prefix.
+- **Typed errors:** `InvalidRequestError`, `AuthenticationError`, `PermissionError`, `RateLimitError`,
+  `IdempotencyError`, `APIError`, `APIConnectionError` (all `CheckboxError`) with `code`, `param`, `status_code`,
+  `request_id`, `doc_url` and `next_action` (what an agent should do next).
+- **Webhooks:** `from checkbox import webhook; webhook.construct_event(raw_body, signature_header, secret)` (as in the docs), or the Stripe-style alias `checkbox.Webhook.construct_event(...)`.
+- **Agents / MCP:** `cb.call("verifyTask", {"task": "task_…", "wait": 30})` calls any operation by its operationId with
+  flat arguments.
+
+## Usage
+
+```python
+from checkbox import Checkbox, CheckboxError
+
+cb = Checkbox(max_network_retries=2, timeout=80, app_info={"name": "my-app", "version": "1.0.0"})
+
+site = cb.sites.create(url="https://acme.example", request_options={"idempotency_key": "site:acme.example"})
+plan = cb.plans.retrieve(site["id"])
+for task in plan["tasks"]:
+    print(task["id"], task["title"], task["next_action"]["description"])
+
+for finding in cb.findings.list(site=site["id"], status="fail").auto_paging_iter():
+    print(finding["check_id"], finding["requirements"][0]["citation"] if finding["requirements"] else "")
+
+# Errors carry a stable code and, for agents, next_action.
+try:
+    cb.certificates.create(site["id"])
+except CheckboxError as err:
+    # resource_conflict: not eligible yet (verify the domain, keep the site compliant for 7 days);
+    # account_not_activated: a live key before any domain is verified.
+    print(err.code, err.message, err.next_action)
+```
+
+## Webhooks
+
+```python
+# Flask
+@app.post("/webhooks/checkbox")
+def checkbox_webhook():
+    try:
+        event = checkbox.Webhook.construct_event(request.get_data(), request.headers.get("Checkbox-Signature"), os.environ["CHECKBOX_WEBHOOK_SECRET"])
+    except checkbox.SignatureVerificationError as err:
+        return {"error": err.message}, 400
+    print(event["type"], event["data"]["object"]["id"])
+    return {"received": True}
+```
+
+Pass the **raw** body (Django `request.body`, FastAPI `await request.body()`). Signatures older than 5 minutes are
+rejected (`tolerance=`).
+
+## Examples
+
+[`examples/`](examples/): [preflight a Stripe Checkout Session](examples/compliant_checkout.py) in a
+[Flask app](examples/flask_app.py) (with the webhook receiver), and [register a site](examples/register_site.py). The
+tests run them against the real API.
+
+## Development
+
+- `checkbox/types.py` and `checkbox/_resources.py` are generated from
+  [`openapi/checkbox.v1.json`](../openapi/checkbox.v1.json) in Checkbox's main codebase and mirrored here with each
+  release; see [CONTRIBUTING.md](../CONTRIBUTING.md).
+- Tests: `cd python && python -m pytest` (a local fake HTTP server; no network). Build: `python -m build`.
+- Releases: [RELEASING.md](../RELEASING.md).

checkbox_site-0.1.0/checkbox/__init__.py

@@ -0,0 +1,61 @@
+"""Checkbox Python SDK: automatic-renewal-law compliance for subscription businesses.
+
+    from checkbox import Checkbox
+
+    checkbox = Checkbox()  # reads CHECKBOX_API_KEY, then CHECKBOX_SECRET_KEY (written by `checkbox init`)
+    result = checkbox.checks.stripe_checkout_session(params=session_params)
+    print(result["verdict"], result["next_action"])
+
+Stdlib only. Responses are plain dicts (see ``checkbox.types`` for their shape).
+"""
+from . import types, webhook
+from ._client import DEFAULT_BASE_URL, DEFAULT_MAX_NETWORK_RETRIES, DEFAULT_TIMEOUT, Checkbox, mode_of_key
+from ._resource import CheckboxFile, CheckboxObject, ListObject, RequestOptions, ResponseMeta
+from ._resources import OPERATIONS
+from ._version import VERSION
+from .errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    CheckboxError,
+    IdempotencyError,
+    InvalidRequestError,
+    PermissionError,
+    RateLimitError,
+    SignatureVerificationError,
+)
+from .types import API_VERSION, ERROR_CODES, WEBHOOK_EVENT_TYPES
+from .webhook import Webhook, construct_event
+
+__version__ = VERSION
+
+__all__ = [
+    "Checkbox",
+    "mode_of_key",
+    "types",
+    "webhook",
+    "Webhook",
+    "construct_event",
+    "OPERATIONS",
+    "API_VERSION",
+    "ERROR_CODES",
+    "WEBHOOK_EVENT_TYPES",
+    "VERSION",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_MAX_NETWORK_RETRIES",
+    "DEFAULT_TIMEOUT",
+    "CheckboxFile",
+    "CheckboxObject",
+    "ListObject",
+    "RequestOptions",
+    "ResponseMeta",
+    "CheckboxError",
+    "InvalidRequestError",
+    "AuthenticationError",
+    "PermissionError",
+    "RateLimitError",
+    "IdempotencyError",
+    "APIError",
+    "APIConnectionError",
+    "SignatureVerificationError",
+]

checkbox_site-0.1.0/checkbox/_client.py

@@ -0,0 +1,301 @@
+"""The Checkbox client (stdlib only: urllib)."""
+import json
+import os
+import platform
+import random
+import re
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, Mapping, Optional, Tuple
+
+from . import webhook as _webhook
+from ._resource import CheckboxFile, CheckboxObject, ListObject, RequestOptions, ResponseMeta
+from ._resources import OPERATIONS, RESOURCES, ResourceNamespaces
+from ._version import VERSION
+from .errors import APIConnectionError, AuthenticationError, CheckboxError, InvalidRequestError, error_from_response
+from .types import API_VERSION
+
+DEFAULT_BASE_URL = "https://app.checkbox.site"
+DEFAULT_TIMEOUT = 80.0
+DEFAULT_MAX_NETWORK_RETRIES = 2
+MAX_RETRY_DELAY = 20.0
+
+_KEY_MODE = re.compile(r"^(?:ck|rk|sk|pk)_(test|live)_")
+
+#: (method, url, headers, body, timeout) -> (status, headers, body bytes). Raise OSError/URLError on network failure.
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], Tuple[int, Dict[str, str], bytes]]
+
+
+def mode_of_key(key: Optional[str]) -> Optional[str]:
+    """``"test"`` for ck_test_/rk_test_/pk_test_ keys, ``"live"`` for live keys, None otherwise."""
+    m = _KEY_MODE.match(key or "")
+    return m.group(1) if m else None
+
+
+def _urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float) -> Tuple[int, Dict[str, str], bytes]:
+    req = urllib.request.Request(url, data=body, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:  # noqa: S310 - URL is built from the configured base
+            return res.status, {k.lower(): v for k, v in res.headers.items()}, res.read()
+    except urllib.error.HTTPError as e:
+        return e.code, {k.lower(): v for k, v in (e.headers or {}).items()}, e.read() or b""
+
+
+class _Webhooks:
+    construct_event = staticmethod(_webhook.construct_event)
+    verify_header = staticmethod(_webhook.verify_header)
+    generate_test_header = staticmethod(_webhook.generate_test_header)
+
+
+class Checkbox(ResourceNamespaces):
+    """Checkbox API client.
+
+    >>> from checkbox import Checkbox
+    >>> checkbox = Checkbox()  # reads CHECKBOX_API_KEY
+    >>> site = checkbox.sites.create(url="https://acme.example")
+    >>> for finding in checkbox.findings.list(site=site["id"]).auto_paging_iter():
+    ...     print(finding["check_id"], finding["status"])
+    """
+
+    VERSION = VERSION
+    API_VERSION = API_VERSION
+    webhooks = _Webhooks()
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        api_version: Optional[str] = None,
+        max_network_retries: int = DEFAULT_MAX_NETWORK_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT,
+        app_info: Optional[Mapping[str, str]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        """
+        :param api_key: secret (``ck_test_…`` / ``ck_live_…``), restricted (``rk_…``) or legacy (``sk_live_…``) key.
+            Defaults to the ``CHECKBOX_API_KEY`` environment variable, then ``CHECKBOX_SECRET_KEY`` (written by ``checkbox init``).
+        :param base_url: API origin (default ``CHECKBOX_API_BASE`` or https://app.checkbox.site).
+        :param api_version: ``Checkbox-Version`` to pin (default: the version this SDK was generated for).
+        :param max_network_retries: retries on network errors, 409 idempotency_key_in_use, 429 and 5xx (default 2).
+        :param timeout: per-attempt timeout in seconds (default 80).
+        :param app_info: ``{"name": ..., "version": ..., "url": ...}`` added to the User-Agent.
+        :param transport: replaces urllib (tests, custom proxies).
+        """
+        key = api_key if api_key is not None else (os.environ.get("CHECKBOX_API_KEY") or os.environ.get("CHECKBOX_SECRET_KEY"))
+        self._api_key: Optional[str] = key.strip() if key and key.strip() else None
+        self.base_url = (base_url or os.environ.get("CHECKBOX_API_BASE") or DEFAULT_BASE_URL).rstrip("/")
+        self.api_version = api_version or API_VERSION
+        self.max_network_retries = max(0, int(max_network_retries))
+        self.timeout = float(timeout)
+        self._headers = dict(headers or {})
+        self._transport: Transport = transport or _urllib_transport
+        #: ``"test"`` or ``"live"`` from the key prefix (None without a recognised key).
+        self.mode = mode_of_key(self._api_key)
+        ua = f"checkbox-python/{VERSION} python/{platform.python_version()}"
+        if app_info and app_info.get("name"):
+            ua += f" {app_info['name']}" + (f"/{app_info['version']}" if app_info.get("version") else "")
+            if app_info.get("url"):
+                ua += f" ({app_info['url']})"
+        self._user_agent = ua
+        for namespace, cls in RESOURCES.items():
+            setattr(self, namespace, cls(self))
+
+    def __repr__(self) -> str:
+        return f"Checkbox(mode={self.mode!r}, base_url={self.base_url!r}, api_version={self.api_version!r})"
+
+    @property
+    def livemode(self) -> Optional[bool]:
+        return None if self.mode is None else self.mode == "live"
+
+    # ---- generic calls ---------------------------------------------------------------------------------------------
+
+    def call(self, operation_id: str, args: Optional[Mapping[str, Any]] = None, *, request_options: Optional[RequestOptions] = None, **kwargs: Any) -> Any:
+        """Calls any operation by its operationId with flat arguments (path parameters and params together), the
+        shape MCP tools and agents use: ``checkbox.call("retrieveSite", {"site": "site_…"})``."""
+        op = OPERATIONS.get(operation_id)
+        if op is None:
+            raise InvalidRequestError(f'Unknown operation "{operation_id}".', type="invalid_request_error", code="route_not_found", param="operation_id")
+        rest: Dict[str, Any] = dict(args or {})
+        rest.update(kwargs)
+        path_args = tuple(rest.pop(name, None) for name in op["path_params"])
+        return self._send(operation_id, path_args, rest, request_options)  # type: ignore[arg-type]
+
+    def request(self, method: str, path: str, params: Optional[Mapping[str, Any]] = None, *, request_options: Optional[RequestOptions] = None) -> Any:
+        """Raw request to any API path (escape hatch for endpoints newer than this SDK). ``params`` go to the query
+        string for GET/DELETE and to the JSON body for POST."""
+        op = {
+            "operation_id": "request",
+            "http_method": method.upper(),
+            "path": path if path.startswith("/") else "/" + path,
+            "path_params": (),
+            "query_params": (),
+            "body": method.upper() == "POST",
+            "idempotent": method.upper() == "POST",
+            "auth": True,
+            "response": "json",
+            "list": False,
+            "paginated": False,
+        }
+        return self._send_op(op, (), dict(params or {}), request_options)
+
+    # ---- transport -------------------------------------------------------------------------------------------------
+
+    def _send(self, operation_id: str, path_args: Tuple[Any, ...], params: Dict[str, Any], request_options: Optional[RequestOptions]) -> Any:
+        return self._send_op(OPERATIONS[operation_id], path_args, params, request_options)
+
+    def _send_op(self, op: Mapping[str, Any], path_args: Tuple[Any, ...], params: Dict[str, Any], request_options: Optional[RequestOptions]) -> Any:
+        options: Dict[str, Any] = dict(request_options or {})
+        api_key = options.get("api_key") or self._api_key
+        if op["auth"] and not api_key:
+            raise AuthenticationError(
+                "No API key provided. Pass it to Checkbox(api_key) or set CHECKBOX_API_KEY (or CHECKBOX_SECRET_KEY, which `checkbox init` writes).",
+                type="authentication_error",
+                code="api_key_missing",
+                next_action={
+                    "type": "get_api_key",
+                    "message": "Get a free test key: POST /v1/device/authorize (one browser approval creates an account and test keys), the remote MCP server https://app.checkbox.site/mcp (setup_checkbox), "
+                    "or create a key at https://app.checkbox.site/settings/api-keys.",
+                    "url": "https://app.checkbox.site/settings/api-keys",
+                },
+            )
+        path = op["path"]
+        for name, value in zip(op["path_params"], path_args + (None,) * (len(op["path_params"]) - len(path_args))):
+            if not isinstance(value, str) or not value.strip():
+                raise InvalidRequestError(
+                    f'Missing required path parameter "{name}" for {op["operation_id"]}.',
+                    type="invalid_request_error",
+                    code="parameter_missing",
+                    param=name,
+                )
+            path = path.replace("{" + name + "}", urllib.parse.quote(value, safe=""))
+
+        query: list = []  # type: ignore[type-arg]
+        body: Dict[str, Any] = {}
+        query_names = set(op["query_params"])
+        for k, v in params.items():
+            if v is None:
+                continue
+            in_query = op["http_method"] != "POST" or k in query_names
+            if not in_query:
+                body[k] = v
+                continue
+            if k in ("expand", "expand[]"):
+                for e in v if isinstance(v, (list, tuple)) else [v]:
+                    query.append(("expand[]", str(e)))
+            elif isinstance(v, (list, tuple)):
+                for e in v:
+                    query.append((f"{k}[]", _q(e)))
+            elif isinstance(v, dict):
+                query.append((k, json.dumps(v)))
+            else:
+                query.append((k, _q(v)))
+        url = self.base_url + path + ("?" + urllib.parse.urlencode(query) if query else "")
+
+        headers: Dict[str, str] = {
+            "Accept": "application/json" if op["response"] == "json" else "*/*",
+            "Checkbox-Version": options.get("api_version") or self.api_version,
+            "User-Agent": self._user_agent,
+        }
+        headers.update(self._headers)
+        headers.update(options.get("headers") or {})
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        data: Optional[bytes] = None
+        idempotency_key: Optional[str] = None
+        if op["http_method"] == "POST":
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+            if op["idempotent"] or options.get("idempotency_key"):
+                idempotency_key = options.get("idempotency_key") or f"sdk_{uuid.uuid4()}"
+                headers["Idempotency-Key"] = idempotency_key
+
+        max_retries = max(0, int(options.get("max_network_retries", self.max_network_retries)))
+        timeout = float(options.get("timeout", self.timeout))
+        attempt = 0
+        while True:
+            try:
+                status, res_headers, raw = self._transport(op["http_method"], url, headers, data, timeout)
+            except (urllib.error.URLError, OSError, socket.timeout) as e:
+                if attempt < max_retries:
+                    time.sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                timed_out = isinstance(e, socket.timeout) or "timed out" in str(e)
+                raise APIConnectionError(
+                    f"Request to {self.base_url} timed out after {timeout:g} s ({attempt + 1} attempts)."
+                    if timed_out
+                    else f"Could not reach {self.base_url}: {e} ({attempt + 1} attempts).",
+                    type="connection_error",
+                    code="timeout" if timed_out else "connection_failed",
+                    next_action={"type": "retry", "message": "Check the network and CHECKBOX_API_BASE, then retry; POSTs are safe to retry with the same idempotency_key."},
+                ) from e
+            res_headers = {k.lower(): v for k, v in res_headers.items()}
+            if status >= 400:
+                text = raw.decode("utf-8", "replace")
+                try:
+                    parsed: Any = json.loads(text) if text else None
+                except ValueError:
+                    parsed = {"error": text[:300]} if text else None
+                err = error_from_response(status, parsed, res_headers)
+                if attempt < max_retries and _should_retry(status, err.code):
+                    time.sleep(_retry_delay(attempt, res_headers.get("retry-after")))
+                    attempt += 1
+                    continue
+                raise err
+            meta = ResponseMeta(status, res_headers, idempotency_key)
+            if op["response"] == "binary":
+                disposition = res_headers.get("content-disposition", "")
+                m = re.search(r'filename="?([^";]+)"?', disposition, re.I)
+                f = CheckboxFile(raw, res_headers.get("content-type"), m.group(1) if m else None)
+                f.last_response = meta
+                return f
+            text = raw.decode("utf-8")
+            if op["response"] == "text":
+                return text
+            try:
+                value = json.loads(text) if text else {}
+            except ValueError:
+                raise CheckboxError(f"Invalid JSON from the API (HTTP {status}).", type="api_error", code="invalid_response", status_code=status, request_id=meta.request_id) from None
+            if not isinstance(value, dict):
+                return value
+            if op.get("list") and op.get("paginated"):
+                page: ListObject[Any] = ListObject(value)
+                page.last_response = meta
+                page._params = dict(params)
+                page._fetch_page = lambda p, _op=op, _a=path_args, _o=request_options: self._send_op(_op, _a, p, _o)
+                return page
+            obj = CheckboxObject(value)
+            obj.last_response = meta
+            return obj
+
+
+def _q(v: Any) -> str:
+    if v is True:
+        return "true"
+    if v is False:
+        return "false"
+    return str(v)
+
+
+def _should_retry(status: int, code: Optional[str]) -> bool:
+    return status == 429 or status >= 500 or (status == 409 and code == "idempotency_key_in_use")
+
+
+def _backoff(attempt: int) -> float:
+    """0.5 s, 1 s, 2 s, ... capped at 20 s, with jitter (75-100 %)."""
+    base = min(0.5 * (2**attempt), MAX_RETRY_DELAY)
+    return base * (0.75 + random.random() * 0.25)
+
+
+def _retry_delay(attempt: int, retry_after: Optional[str]) -> float:
+    try:
+        s = float(retry_after) if retry_after is not None else 0.0
+    except ValueError:
+        s = 0.0
+    return min(s, MAX_RETRY_DELAY) if s > 0 else _backoff(attempt)