codespar 0.10.2__tar.gz → 0.12.0__tar.gz

{codespar-0.10.2 → codespar-0.12.0}/CHANGELOG.md

@@ -1,5 +1,51 @@
 # codespar (Python SDK) — CHANGELOG
 
+## 0.12.0
+
+`codespar.mandate` is strict, in parity with `@codespar/sdk/mandate` 0.16.11
+and `codespar mandate verify` 0.17.0 (codespar-core#123, p2-identity#6).
+
+### Changed
+
+- `verify_mandate_token(...).verified` is `True` only when both Ed25519
+  signatures are carried and verify, the agent's under the key the token
+  names, and the token is not expired. It used to be `True` with the agent
+  signature stripped, with a signature left unchecked (no key given), and
+  after `expires_at`. `verify_mandate_token(t, agent_public_key=...)` alone is
+  now `verified=False` with `failures == ["issuer_sig_unchecked"]`.
+- The key is the one the signed `agent_kid` names; an envelope `kid` that
+  differs is refused (`kid_mismatch`).
+- `__version__` says `0.12.0`; it had said `0.10.2` through 0.11.0.
+
+### Added
+
+- `agent_did_document=`: the agent's parsed did:web document; only the
+  `verificationMethod` whose `id` equals the signed `agent_kid` is used, so a
+  retired key listed beside the active one does not verify a token naming the
+  active one. Mutually exclusive with `agent_public_key` (`TypeError`).
+- `now=` (UNIX seconds) for the expiry check; default is the current time.
+- `MandateVerification.failures`, `.expired`, `.issued_at`.
+- V4 tokens (`format_version: 4`, signed `issued_at`), byte-locked against the
+  enterprise fixture. An unknown later format raises
+  `MandateDecodeError("mandate_format_unsupported")`.
+
+## 0.11.0
+
+Offline V3 mandate verification lands as the `codespar.mandate`
+submodule, in parity with `@codespar/sdk/mandate` and the CLI. See
+[codespar/codespar-core#114](https://github.com/codespar/codespar-core/pull/114).
+
+### Added
+
+- `codespar.mandate`: `decode_mandate_token` and
+  `reconstruct_signing_string` are pure stdlib; `verify_ed25519` and
+  `verify_mandate_token` verify the V3 dual Ed25519 signatures and
+  lazily import `cryptography`, raising a clear install hint when it is
+  absent. New optional extra: `pip install codespar[verify]`. The base
+  package keeps its single runtime dependency (httpx).
+- The canonical signing string is byte-locked against the platform's
+  frozen fixture, shared with the TS SDK and CLI tests.
+
 ## 0.10.0
 
 The hosted test-mode SDK surface lands across the `codespar` Python

{codespar-0.10.2 → codespar-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: codespar
-Version: 0.10.2
+Version: 0.12.0
 Summary: Python SDK for CodeSpar — commerce infrastructure for AI agents in Latin America.
 Project-URL: Homepage, https://codespar.dev
 Project-URL: Documentation, https://docs.codespar.dev
@@ -22,11 +22,14 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27.0
 Provides-Extra: dev
+Requires-Dist: cryptography>=42; extra == 'dev'
 Requires-Dist: mypy>=1.11; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: verify
+Requires-Dist: cryptography>=42; extra == 'verify'
 Description-Content-Type: text/markdown
 
 # codespar — Python SDK

{codespar-0.10.2 → codespar-0.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codespar"
-version = "0.10.2"
+version = "0.12.0"
 description = "Python SDK for CodeSpar — commerce infrastructure for AI agents in Latin America."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -30,10 +30,17 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+# Offline V3 mandate verification (codespar.mandate) needs Ed25519, which is
+# not in the stdlib. Opt in with `pip install codespar[verify]`; the base
+# package keeps its single runtime dependency (httpx).
+verify = [
+    "cryptography>=42",
+]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "pytest-httpx>=0.30",
+    "cryptography>=42",
     "ruff>=0.6",
     "mypy>=1.11",
 ]

{codespar-0.10.2 → codespar-0.12.0}/src/codespar/__init__.py

@@ -35,6 +35,7 @@ from .errors import (
     ConfigError,
     NotConnectedError,
     StreamError,
+    TimeoutError,
 )
 from .tool_result_codes import (
     APPROVAL_REQUIRED,
@@ -140,7 +141,7 @@ from .types import (
     WizardAction,
 )
 
-__version__ = "0.10.2"
+__version__ = "0.12.0"
 
 __all__ = [
     "APPROVAL_REQUIRED",
@@ -249,6 +250,7 @@ __all__ = [
     "StreamError",
     # Streaming events
     "StreamEvent",
+    "TimeoutError",
     "Tool",
     "ToolCallRecord",
     "ToolNotMockedOutput",

{codespar-0.10.2 → codespar-0.12.0}/src/codespar/_async_client.py

@@ -21,7 +21,7 @@ from ._async_session import (
     build_session_info,
     wait_for_connections,
 )
-from ._http import DEFAULT_BASE_URL, request_json
+from ._http import DEFAULT_BASE_URL, normalize_timeout, request_json
 from ._presets import preset_to_servers
 from .errors import ApiError, ConfigError
 from .types import SessionConfig
@@ -57,6 +57,18 @@ class AsyncCodeSpar:
             session = await cs.create("user_123", preset="brazilian")
             result = await session.send("charge R$500 via Pix")
             print(result.message)
+
+    Timeout UNIT: every ``timeout`` here is in **seconds** (httpx
+    convention) — e.g. ``timeout=30`` is 30 seconds. The TypeScript SDK
+    (``@codespar/sdk``) uses **milliseconds** for the equivalent option.
+    Do not copy a numeric timeout between the two SDKs without
+    converting (30s in Python == ``timeout: 30000`` in TS).
+
+    Cancellation: there is no AbortSignal in Python. Cancel an in-flight
+    call by cancelling the awaiting asyncio task (e.g. asyncio.timeout()
+    or task.cancel()); httpx tears the connection down. Note this only
+    closes the connection — it does not undo an upstream side effect the
+    backend already dispatched.
     """
 
     def __init__(
@@ -77,6 +89,9 @@ class AsyncCodeSpar:
             raise ConfigError(
                 "project_id must match ^prj_[A-Za-z0-9]{16}$ (e.g. 'prj_...')."
             )
+        # Fail fast on a misconfigured client-default timeout, same
+        # rule the per-call paths use (parity with TS validateTimeout).
+        timeout = normalize_timeout(timeout) or 60.0
         self._api_key = api_key
         self._base_url = _resolve_base_url(base_url).rstrip("/")
         self._project_id = project_id
@@ -112,6 +127,18 @@ class AsyncCodeSpar:
             await cs.create("user_123", preset="brazilian")
             await cs.create("user_123", SessionConfig(preset="brazilian"))
         """
+        # Extract before _resolve_config so it doesn't reach the allowed-kwarg check.
+        raw_timeout = kwargs.pop("timeout", None)
+        timeout: float | None
+        if raw_timeout is None:
+            timeout = None
+        elif isinstance(raw_timeout, bool) or not isinstance(raw_timeout, (int, float)):
+            raise ConfigError(
+                f"create(): 'timeout' must be a number of seconds, got {type(raw_timeout).__name__}"
+            )
+        else:
+            timeout = float(raw_timeout)
+
         resolved = self._resolve_config(config, kwargs)
         servers = resolved.servers or preset_to_servers(resolved.preset)
         project_id = resolved.project_id or self._project_id
@@ -133,6 +160,7 @@ class AsyncCodeSpar:
             api_key=self._api_key,
             project_id=project_id,
             body=body,
+            timeout=timeout,
         )
         if not isinstance(data, dict):
             raise ApiError("create: malformed response", status=0, body=data)

{codespar-0.10.2 → codespar-0.12.0}/src/codespar/_async_session.py

@@ -18,7 +18,7 @@ from typing import Any
 import httpx
 
 from ._http import request_json, stream_sse, stream_sse_get
-from .errors import ApiError, ConfigError
+from .errors import ApiError, ConfigError, TimeoutError
 from .types import (
     AssistantTextEvent,
     AuthConfig,
@@ -397,7 +397,13 @@ class AsyncSession:
 
     # ── execution ───────────────────────────────────────────────────────
 
-    async def execute(self, tool_name: str, params: dict[str, Any]) -> ToolResult:
+    async def execute(
+        self,
+        tool_name: str,
+        params: dict[str, Any],
+        *,
+        timeout: float | None = None,
+    ) -> ToolResult:
         """Call a specific tool by name. Always returns a ToolResult, even on error."""
         start = _now_ms()
         try:
@@ -408,6 +414,7 @@ class AsyncSession:
                 api_key=self._api_key,
                 project_id=self._project_id,
                 body={"tool": tool_name, "input": params},
+                timeout=timeout,
             )
         except ApiError as exc:
             return ToolResult(
@@ -444,6 +451,8 @@ class AsyncSession:
         self,
         use_case: str,
         options: DiscoverOptions | None = None,
+        *,
+        timeout: float | None = None,
     ) -> DiscoverResult:
         """
         Search the catalog for a tool that matches a free-form use case.
@@ -459,7 +468,7 @@ class AsyncSession:
                 params["country"] = options.country
             if options.limit is not None:
                 params["limit"] = options.limit
-        result = await self.execute("codespar_discover", params)
+        result = await self.execute("codespar_discover", params, timeout=timeout)
         if not result.success:
             raise ApiError(
                 f"discover failed: {result.error or 'unknown'}",
@@ -473,6 +482,8 @@ class AsyncSession:
     async def connection_wizard(
         self,
         options: ConnectionWizardOptions,
+        *,
+        timeout: float | None = None,
     ) -> ConnectionWizardResult:
         """
         Surface the connection wizard for a server (or list every
@@ -497,7 +508,7 @@ class AsyncSession:
             params["environment"] = options.environment
         if options.return_to is not None:
             params["return_to"] = options.return_to
-        result = await self.execute("codespar_manage_connections", params)
+        result = await self.execute("codespar_manage_connections", params, timeout=timeout)
         if not result.success:
             raise ApiError(
                 f"connection_wizard failed: {result.error or 'unknown'}",
@@ -512,7 +523,7 @@ class AsyncSession:
             )
         return _parse_wizard_result(result.data)
 
-    async def charge(self, args: ChargeArgs) -> ChargeResult:
+    async def charge(self, args: ChargeArgs, *, timeout: float | None = None) -> ChargeResult:
         """
         Create an INBOUND charge — the buyer pays the merchant. Typed
         wrapper around ``execute("codespar_charge", {...})``. Distinct
@@ -538,7 +549,7 @@ class AsyncSession:
         }
         if args.due_date is not None:
             params["due_date"] = args.due_date
-        result = await self.execute("codespar_charge", params)
+        result = await self.execute("codespar_charge", params, timeout=timeout)
         if not result.success:
             raise ApiError(
                 f"charge failed: {result.error or 'unknown'}",
@@ -549,7 +560,7 @@ class AsyncSession:
             raise ApiError("charge: malformed response", status=0, body=result.data)
         return _parse_charge_result(result.data)
 
-    async def ship(self, args: ShipArgs) -> ShipResult:
+    async def ship(self, args: ShipArgs, *, timeout: float | None = None) -> ShipResult:
         """
         Generate a shipping label OR fetch tracking status. Typed
         wrapper around ``execute("codespar_ship", {...})``. Routes to
@@ -606,7 +617,7 @@ class AsyncSession:
             params["tracking_code"] = args.tracking_code
         if args.metadata is not None:
             params["metadata"] = args.metadata
-        result = await self.execute("codespar_ship", params)
+        result = await self.execute("codespar_ship", params, timeout=timeout)
         if not result.success:
             raise ApiError(
                 f"ship failed: {result.error or 'unknown'}",
@@ -617,7 +628,7 @@ class AsyncSession:
             raise ApiError("ship: malformed response", status=0, body=result.data)
         return _parse_ship_result(result.data)
 
-    async def ledger(self, args: LedgerArgs) -> LedgerResult:
+    async def ledger(self, args: LedgerArgs, *, timeout: float | None = None) -> LedgerResult:
         """
         Post a double-entry journal entry, read an account's balances,
         or create an account on the tenant's self-hosted Lerian Midaz
@@ -657,7 +668,7 @@ class AsyncSession:
             params["type"] = args.type
         if args.metadata is not None:
             params["metadata"] = args.metadata
-        result = await self.execute("codespar_ledger", params)
+        result = await self.execute("codespar_ledger", params, timeout=timeout)
         if not result.success:
             raise ApiError(
                 f"ledger failed: {result.error or 'unknown'}",
@@ -668,7 +679,7 @@ class AsyncSession:
             raise ApiError("ledger: malformed response", status=0, body=result.data)
         return _parse_ledger_result(result.data)
 
-    async def issue(self, args: IssueArgs) -> IssueResult:
+    async def issue(self, args: IssueArgs, *, timeout: float | None = None) -> IssueResult:
         """
         Issue a virtual/physical card, control (freeze/unfreeze/cancel)
         one, or read its status on the tenant's Pomelo card-issuing
@@ -694,7 +705,7 @@ class AsyncSession:
             params["shipping_address"] = args.shipping_address
         if args.metadata is not None:
             params["metadata"] = args.metadata
-        result = await self.execute("codespar_issue", params)
+        result = await self.execute("codespar_issue", params, timeout=timeout)
         if not result.success:
             raise ApiError(
                 f"issue failed: {result.error or 'unknown'}",
@@ -705,7 +716,7 @@ class AsyncSession:
             raise ApiError("issue: malformed response", status=0, body=result.data)
         return _parse_issue_result(result.data)
 
-    async def shop(self, args: ShopArgs) -> ShopResult:
+    async def shop(self, args: ShopArgs, *, timeout: float | None = None) -> ShopResult:
         """
         Buy-side shopping: catalog search → async checkout → Pix mint.
         Typed wrapper around ``execute("codespar_shop", {...})``. The
@@ -778,7 +789,7 @@ class AsyncSession:
         else:  # checkout_status
             if args.checkout_session_id is not None:
                 params["checkout_session_id"] = args.checkout_session_id
-        result = await self.execute("codespar_shop", params)
+        result = await self.execute("codespar_shop", params, timeout=timeout)
         if not result.success:
             raise ApiError(
                 f"shop failed: {result.error or 'unknown'}",
@@ -790,7 +801,10 @@ class AsyncSession:
         return _parse_shop_result(result.data, args.action)
 
     async def verification_status(
-        self, tool_call_id: str
+        self,
+        tool_call_id: str,
+        *,
+        timeout: float | None = None,
     ) -> VerificationStatusResult:
         """
         Async KYC poll for a meta-tool ``codespar_kyc`` call. Correlates
@@ -817,6 +831,7 @@ class AsyncSession:
             f"/v1/tool-calls/{quote(tool_call_id, safe='')}/verification-status",
             api_key=self._api_key,
             project_id=self._project_id,
+            timeout=timeout,
         )
         if not isinstance(data, dict):
             raise ApiError(
@@ -847,6 +862,7 @@ class AsyncSession:
         *,
         on_update: Callable[[VerificationStatusResult], Awaitable[None] | None]
         | None = None,
+        timeout: float | None = None,
     ) -> VerificationStatusResult:
         """
         SSE-streamed sibling of ``verification_status``. Opens
@@ -872,6 +888,7 @@ class AsyncSession:
             f"/v1/tool-calls/{quote(tool_call_id, safe='')}/verification-status/stream",
             api_key=self._api_key,
             project_id=self._project_id,
+            timeout=timeout,
         ):
             if event_name in ("snapshot", "update"):
                 if not isinstance(raw, dict):
@@ -908,7 +925,12 @@ class AsyncSession:
             )
         return last
 
-    async def payment_status(self, tool_call_id: str) -> PaymentStatusResult:
+    async def payment_status(
+        self,
+        tool_call_id: str,
+        *,
+        timeout: float | None = None,
+    ) -> PaymentStatusResult:
         """
         Async settlement check for a meta-tool payment call. Correlates
         a ``tool_call_id`` (the ``tc_xxx`` returned by ``execute``) back
@@ -927,6 +949,7 @@ class AsyncSession:
             f"/v1/tool-calls/{quote(tool_call_id, safe='')}/payment-status",
             api_key=self._api_key,
             project_id=self._project_id,
+            timeout=timeout,
         )
         if not isinstance(data, dict):
             raise ApiError(
@@ -957,6 +980,7 @@ class AsyncSession:
         *,
         on_update: Callable[[PaymentStatusResult], Awaitable[None] | None]
         | None = None,
+        timeout: float | None = None,
     ) -> PaymentStatusResult:
         """
         SSE-streamed sibling of ``payment_status``. Opens
@@ -978,6 +1002,7 @@ class AsyncSession:
             f"/v1/tool-calls/{quote(tool_call_id, safe='')}/payment-status/stream",
             api_key=self._api_key,
             project_id=self._project_id,
+            timeout=timeout,
         ):
             if event_name in ("snapshot", "update"):
                 if not isinstance(raw, dict):
@@ -1016,7 +1041,12 @@ class AsyncSession:
 
     # ── proxy ───────────────────────────────────────────────────────────
 
-    async def proxy_execute(self, request: ProxyRequest) -> ProxyResult:
+    async def proxy_execute(
+        self,
+        request: ProxyRequest,
+        *,
+        timeout: float | None = None,
+    ) -> ProxyResult:
         """
         Raw HTTP proxy to a connected server's upstream API. Auth is
         injected by the backend — never send provider keys here.
@@ -1035,6 +1065,7 @@ class AsyncSession:
                 "params": request.params,
                 "headers": request.headers,
             },
+            timeout=timeout,
         )
         if not isinstance(data, dict):
             raise ApiError("proxy_execute: malformed response", status=0, body=data)
@@ -1048,7 +1079,12 @@ class AsyncSession:
 
     # ── natural-language ────────────────────────────────────────────────
 
-    async def send(self, message: str) -> SendResult:
+    async def send(
+        self,
+        message: str,
+        *,
+        timeout: float | None = None,
+    ) -> SendResult:
         """Send a natural-language message. Blocks until the agent loop finishes."""
         data = await request_json(
             self._client,
@@ -1057,12 +1093,18 @@ class AsyncSession:
             api_key=self._api_key,
             project_id=self._project_id,
             body={"message": message},
+            timeout=timeout,
         )
         if not isinstance(data, dict):
             raise ApiError("send: malformed response", status=0, body=data)
         return _parse_send_result(data)
 
-    async def send_stream(self, message: str) -> AsyncIterator[StreamEvent]:
+    async def send_stream(
+        self,
+        message: str,
+        *,
+        timeout: float | None = None,
+    ) -> AsyncIterator[StreamEvent]:
         """
         Stream a natural-language turn. Yields events as they arrive.
 
@@ -1081,6 +1123,7 @@ class AsyncSession:
             api_key=self._api_key,
             project_id=self._project_id,
             body={"message": message},
+            timeout=timeout,
         ):
             event = _parse_stream_event(raw)
             if event is not None:
@@ -1088,7 +1131,13 @@ class AsyncSession:
 
     # ── Connect Links ───────────────────────────────────────────────────
 
-    async def authorize(self, server_id: str, config: AuthConfig) -> AuthResult:
+    async def authorize(
+        self,
+        server_id: str,
+        config: AuthConfig,
+        *,
+        timeout: float | None = None,
+    ) -> AuthResult:
         """
         Start a Connect Link OAuth flow. Returns the URL your UI should
         open for the end user; CodeSpar's callback stores tokens and
@@ -1106,6 +1155,7 @@ class AsyncSession:
                 "redirect_uri": config.redirect_uri,
                 "scopes": config.scopes,
             },
+            timeout=timeout,
         )
         if not isinstance(data, dict):
             raise ApiError("authorize: malformed response", status=0, body=data)
@@ -1117,7 +1167,11 @@ class AsyncSession:
 
     # ── connections ─────────────────────────────────────────────────────
 
-    async def connections(self) -> list[ServerConnection]:
+    async def connections(
+        self,
+        *,
+        timeout: float | None = None,
+    ) -> list[ServerConnection]:
         """List server connections and refresh the internal tools cache."""
         try:
             data = await request_json(
@@ -1126,8 +1180,9 @@ class AsyncSession:
                 f"/v1/sessions/{self.id}/connections",
                 api_key=self._api_key,
                 project_id=self._project_id,
+                timeout=timeout,
             )
-        except ApiError:
+        except (ApiError, TimeoutError):
             return list(self._cached_connections or [])
         if not isinstance(data, dict):
             return list(self._cached_connections or [])
@@ -1162,17 +1217,23 @@ class AsyncSession:
 
     # ── lifecycle ───────────────────────────────────────────────────────
 
-    async def close(self) -> None:
+    async def close(
+        self,
+        *,
+        timeout: float | None = None,
+    ) -> None:
         """Close the session on the backend. Safe to call multiple times.
-        Best-effort — a 4xx/5xx here shouldn't crash the caller. The
-        backend cleans up stale sessions on a timer anyway."""
-        with contextlib.suppress(ApiError):
+        Best-effort — a 4xx/5xx OR a backend timeout here shouldn't
+        crash the caller. The backend cleans up stale sessions on a
+        timer anyway."""
+        with contextlib.suppress(ApiError, TimeoutError):
             await request_json(
                 self._client,
                 "DELETE",
                 f"/v1/sessions/{self.id}",
                 api_key=self._api_key,
                 project_id=self._project_id,
+                timeout=timeout,
             )