codespar · dangazineu · May 24, 2026 · May 24, 2026 · May 24, 2026
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/autogen/package.json b/packages/autogen/package.json
@@ -38,7 +38,7 @@
     "directory": "packages/autogen"
   },
   "peerDependencies": {
-    "@codespar/sdk": "^0.9.0"
+    "@codespar/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@codespar/sdk": "*",

diff --git a/packages/camel/package.json b/packages/camel/package.json
@@ -38,7 +38,7 @@
     "directory": "packages/camel"
   },
   "peerDependencies": {
-    "@codespar/sdk": "^0.9.0"
+    "@codespar/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@codespar/sdk": "*",

diff --git a/packages/claude/package.json b/packages/claude/package.json
@@ -37,7 +37,7 @@
     "directory": "packages/claude"
   },
   "peerDependencies": {
-    "@codespar/sdk": "^0.9.0"
+    "@codespar/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@codespar/sdk": "*",

diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -45,7 +45,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@codespar/sdk": "^0.9.0",
+    "@codespar/sdk": "^0.10.0",
     "commander": "^13.0.0"
   },
   "devDependencies": {

diff --git a/packages/core/CHANGELOG.md b/packages/core/CHANGELOG.md
@@ -1,22 +1,22 @@
 # @codespar/sdk — CHANGELOG
 
-## Unreleased
+## 0.10.0
 
 The hosted test-mode SDK surface lands across `@codespar/sdk`, `@codespar/types`, and the `codespar` Python package. See [codespar/codespar-core#54](https://github.com/codespar/codespar-core/pull/54).
 
 ### Added
 
-- `cs.create(userId, { mocks: {...} })` (TypeScript) and `cs.create("u", mocks={...})` (Python). Keys are canonical tool names in slash form (`asaas/create_payment`); values are a `MockObject` for a static mock or a `MockObject[]` for a stateful mock consumed in order. Forwarded verbatim on `POST /v1/sessions` — the SDK does not rewrite tool names, so the OSS double-underscore form (`asaas__create_payment`) surfaces as `mocks_invalid` rather than being silently rewritten. Absent case stays wire-neutral (no `mocks` key on the body).
-- `MockObject` and `MockValue` type aliases in `@codespar/types` (re-exported through `@codespar/sdk`) and in the `codespar` Python package. `SessionConfig` widens in both languages to accept the optional `mocks` field.
+- `cs.create(userId, { mocks: {...} })`. Keys are canonical tool names in slash form (`asaas/create_payment`); values are a `MockObject` for a static mock or a `MockObject[]` for a stateful mock consumed in order. Forwarded verbatim on `POST /v1/sessions` — the SDK does not rewrite tool names, so the double-underscore form (`asaas__create_payment`) surfaces as `mocks_invalid` rather than being silently rewritten. Absent case stays wire-neutral (no `mocks` key on the body).
+- `MockObject` and `MockValue` type aliases re-exported from `@codespar/types`. `SessionConfig` widens to accept the optional `mocks` field.
 - `CodesparApiError` — structured exception class shared by every transport-failure throw site in `session.ts`. Constructor signature `new CodesparApiError(message, { status, code?, body?, cause? })`. Network errors that never reach the backend surface as `status: 0` with the underlying `fetch` rejection preserved as `cause`.
-- Tool-result type-narrowed guards in `packages/core/src/tool-result-codes.ts` and `packages/python/src/codespar/tool_result_codes.py`. Five variants — `PolicyDenied`, `ApprovalRequired`, `MocksExhausted`, `MocksEngineError`, `ToolNotMocked` — plus matching `*Output` interfaces / dataclasses, narrowed `*ToolCall` aliases (TS), the `ToolResultCode` union, the `TOOL_RESULT_CODES` set, five predicate guards (`isPolicyDenied` / `is_policy_denied`, etc.), and an exhaustive-match helper (`assertExhaustiveToolResult` / `assert_exhaustive_tool_result`) that makes a `switch` over `ToolResultCode` fail to compile (TS) or trip at runtime (Python) when a sixth variant lands without a handler. Each guard checks the `code` discriminant AND its required sibling fields, so a payload with a well-formed `code` but a missing `rule_id` / `approval_id` / `tool_name` returns false rather than narrowing positive.
-- `CODESPAR_BASE_URL` environment variable resolution. The TypeScript `CodeSpar` constructor already read the env var; the Python `CodeSpar` and `AsyncCodeSpar` constructors now do too. The cascade in both languages is explicit `baseUrl` / `base_url` option, then `CODESPAR_BASE_URL`, then `https://api.codespar.dev`. Point the same client wiring at a [local OSS runtime](https://github.com/codespar/codespar) without rebuilding call sites.
+- `tool-result-codes` module (`packages/core/src/tool-result-codes.ts`). Five variants — `PolicyDenied`, `ApprovalRequired`, `MocksExhausted`, `MocksEngineError`, `ToolNotMocked` — plus matching `*Output` interfaces, narrowed `*ToolCall` aliases, the `ToolResultCode` union, the `TOOL_RESULT_CODES` set, five predicate guards (`isPolicyDenied`, `isApprovalRequired`, `isMocksExhausted`, `isMocksEngineError`, `isToolNotMocked`), and the `assertExhaustiveToolResult` helper that makes a `switch` over `ToolResultCode` fail to compile when a sixth variant lands without a handler. Each guard checks the `code` discriminant AND its required sibling fields, so a payload with a well-formed `code` but a missing `rule_id` / `approval_id` / `tool_name` returns false rather than narrowing positive.
+- `CODESPAR_BASE_URL` environment variable resolved at client construction. Cascade: explicit `baseUrl` option, then `CODESPAR_BASE_URL`, then `https://api.codespar.dev`. Point the same client wiring at a [local OSS runtime](https://github.com/codespar/codespar) without rebuilding call sites.
+- Bumped `@codespar/types` dependency range to `^0.10.0`.
 
 ### Changed
 
 - **SemVer-minor break for callers parsing `e.message` strings.** The generic `throw new Error("send failed: 500 ...")` shape is gone — every transport call site (`createSession`, `proxyExecute`, `send`, `sendStream`, `paymentStatus(Stream)`, `verificationStatus(Stream)`, `authorize`) now throws `CodesparApiError`. Migration recipe: `e.message.includes("foo")` becomes `e.code === "foo"`.
 - `session.execute(...)` keeps its existing returns-vs-throws asymmetry — non-ok responses still come back as `ToolResult.success === false` with the body in `error`. Only transport exceptions change shape.
-- Python `_http.py` honors `code` over `error` when both are present on a non-success response body. The new test-mode envelopes (`mocks_not_permitted`, `mocks_invalid`, `mocks_payload_too_large`) carry `code`; pre-test-mode responses that only set `error` remain compatible.
 
 ## 0.9.0
 

diff --git a/packages/core/package.json b/packages/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@codespar/sdk",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Commerce SDK for AI agents — sessions, managed auth, Complete Loop orchestration for Latin American APIs",
   "type": "module",
   "main": "./dist/index.js",
@@ -52,7 +52,7 @@
   },
   "dependencies": {
     "zod": "^3.24.0",
-    "@codespar/types": "*"
+    "@codespar/types": "^0.10.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

diff --git a/packages/crewai/package.json b/packages/crewai/package.json
@@ -37,7 +37,7 @@
     "directory": "packages/crewai"
   },
   "peerDependencies": {
-    "@codespar/sdk": "^0.9.0"
+    "@codespar/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@codespar/sdk": "*",

diff --git a/packages/google-genai/package.json b/packages/google-genai/package.json
@@ -38,7 +38,7 @@
     "directory": "packages/google-genai"
   },
   "peerDependencies": {
-    "@codespar/sdk": "^0.9.0"
+    "@codespar/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@codespar/sdk": "*",

diff --git a/packages/langchain/package.json b/packages/langchain/package.json
@@ -37,7 +37,7 @@
     "directory": "packages/langchain"
   },
   "peerDependencies": {
-    "@codespar/sdk": "^0.9.0",
+    "@codespar/sdk": "^0.10.0",
     "zod": ">=3.0.0"
   },
   "devDependencies": {

diff --git a/packages/letta/package.json b/packages/letta/package.json
@@ -37,7 +37,7 @@
     "directory": "packages/letta"
   },
   "peerDependencies": {
-    "@codespar/sdk": "^0.9.0"
+    "@codespar/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@codespar/sdk": "*",

diff --git a/packages/llama-index/package.json b/packages/llama-index/package.json
@@ -38,7 +38,7 @@
     "directory": "packages/llama-index"
   },
   "peerDependencies": {
-    "@codespar/sdk": "^0.9.0"
+    "@codespar/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@codespar/sdk": "*",

diff --git a/packages/mastra/package.json b/packages/mastra/package.json
@@ -37,7 +37,7 @@
     "directory": "packages/mastra"
   },
   "peerDependencies": {
-    "@codespar/sdk": "^0.9.0"
+    "@codespar/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@codespar/sdk": "*",

diff --git a/packages/mcp/package.json b/packages/mcp/package.json
@@ -37,7 +37,7 @@
     "directory": "packages/mcp"
   },
   "peerDependencies": {
-    "@codespar/sdk": "^0.9.0"
+    "@codespar/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@codespar/sdk": "*",

diff --git a/packages/openai/package.json b/packages/openai/package.json
@@ -36,7 +36,7 @@
     "directory": "packages/openai"
   },
   "peerDependencies": {
-    "@codespar/sdk": "^0.9.0"
+    "@codespar/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@codespar/sdk": "*",

diff --git a/packages/python/CHANGELOG.md b/packages/python/CHANGELOG.md
@@ -1,5 +1,61 @@
 # codespar (Python SDK) — CHANGELOG
 
+## 0.10.0
+
+The hosted test-mode SDK surface lands across the `codespar` Python
+package alongside `@codespar/sdk` and `@codespar/types`. See
+[codespar/codespar-core#54](https://github.com/codespar/codespar-core/pull/54).
+
+### Added
+
+- `cs.create("user", mocks={...})` — optional mocks map forwarded
+  verbatim on `POST /v1/sessions`. Keys are canonical tool names in
+  slash form (`asaas/create_payment`); values follow `MockValue` —
+  a single `MockObject` for a static mock or a `list[MockObject]`
+  for a stateful mock consumed in order, then `mocks_exhausted` once
+  the list is drained. Absent case stays wire-neutral (no `mocks`
+  key on the body). The SDK does not rewrite tool names, so the
+  double-underscore form (`asaas__create_payment`) surfaces as
+  `mocks_invalid` from the backend rather than being silently
+  rewritten.
+- `MockObject` and `MockValue` type aliases re-exported from
+  `codespar`. `SessionConfig` widens to accept the optional
+  `mocks: dict[str, MockValue] | None` field.
+- `CodesparApiError` exception (TypeScript parallel); Python's
+  `ApiError` retains its existing shape, and the new test-mode
+  envelopes (`mocks_not_permitted`, `mocks_invalid`,
+  `mocks_payload_too_large`) flow through it with the `code`
+  discriminant preserved.
+- `tool_result_codes` module (`src/codespar/tool_result_codes.py`).
+  Five frozen dataclasses — `PolicyDeniedOutput`,
+  `ApprovalRequiredOutput`, `MocksExhaustedOutput`,
+  `MocksEngineErrorOutput`, `ToolNotMockedOutput` — plus the
+  `ToolResultCode` `Literal` union, the `TOOL_RESULT_CODES`
+  `frozenset`, five `TypeGuard` predicates (`is_policy_denied`,
+  `is_approval_required`, `is_mocks_exhausted`,
+  `is_mocks_engine_error`, `is_tool_not_mocked`), and
+  `assert_exhaustive_tool_result` for exhaustive `match` over the
+  union. Each guard checks the `code` discriminant AND its required
+  sibling fields, so a payload with a well-formed `code` but a
+  missing `rule_id` / `approval_id` / `tool_name` returns `False`
+  rather than narrowing positive.
+- `CODESPAR_BASE_URL` environment variable resolved in both the
+  `CodeSpar` and `AsyncCodeSpar` constructors. Cascade: explicit
+  `base_url` option, then `CODESPAR_BASE_URL`, then
+  `https://api.codespar.dev`. Point the same client wiring at a
+  [local OSS runtime](https://github.com/codespar/codespar) without
+  rebuilding call sites.
+- Test fixture `tests/_fixtures/mocks_canonical.json` for wire
+  parity between languages.
+
+### Changed
+
+- `_http.py` honors `code` over `error` when both are present on a
+  non-success response body. The new test-mode envelopes carry
+  `code`; pre-test-mode responses that only set `error` remain
+  compatible.
+- User-Agent bumped to `codespar-python/0.10.0`.
+
 ## 0.9.0
 
 - New: `AsyncSession.payment_status_stream(tool_call_id, *, on_update=None)`.

diff --git a/packages/python/pyproject.toml b/packages/python/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codespar"
-version = "0.9.0"
+version = "0.10.0"
 description = "Python SDK for CodeSpar — commerce infrastructure for AI agents in Latin America."
 readme = "README.md"
 requires-python = ">=3.10"

diff --git a/packages/python/src/codespar/__init__.py b/packages/python/src/codespar/__init__.py
@@ -113,7 +113,7 @@
     WizardAction,
 )
 
-__version__ = "0.9.0"
+__version__ = "0.10.0"
 
 __all__ = [
     "APPROVAL_REQUIRED",

diff --git a/packages/python/src/codespar/_http.py b/packages/python/src/codespar/_http.py
@@ -28,7 +28,7 @@ def build_headers(
     headers = {
         "Content-Type": "application/json",
         "Authorization": f"Bearer {api_key}",
-        "User-Agent": "codespar-python/0.9.0",
+        "User-Agent": "codespar-python/0.10.0",
     }
     if project_id:
         headers["x-codespar-project"] = project_id

diff --git a/packages/types/CHANGELOG.md b/packages/types/CHANGELOG.md
@@ -1,5 +1,23 @@
 # @codespar/types — CHANGELOG
 
+## 0.10.0
+
+- Added `MockObject` and `MockValue` type aliases for the hosted
+  test-mode surface. `MockObject` is a `Record<string, unknown>`
+  representing a single mock response payload; `MockValue` is a
+  `MockObject | MockObject[]` union — a single object is a static
+  mock (same response every call), an array is a stateful mock
+  consumed in order with `mocks_exhausted` once the list is drained.
+- Widened `CreateSessionRequest` with an optional
+  `mocks?: Record<string, MockValue>` field. Keys are canonical tool
+  names in slash form (`asaas/create_payment`); the SDK forwards them
+  verbatim so the OSS double-underscore form
+  (`asaas__create_payment`) surfaces as `mocks_invalid` from the
+  backend rather than being silently rewritten.
+- Note: 0.8.0 and 0.9.0 were not released; this jump aligns
+  `@codespar/types` with the `@codespar/sdk` and `codespar` Python
+  package versions.
+
 ## 0.7.0
 
 - Added `Session.paymentStatusStream` and `Session.verificationStatusStream`

diff --git a/packages/types/package.json b/packages/types/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@codespar/types",
-  "version": "0.7.0",
+  "version": "0.10.0",
   "description": "Shared session interface contract for codespar runtimes",
   "type": "module",
   "main": "./dist/index.js",

diff --git a/packages/vercel/package.json b/packages/vercel/package.json
@@ -36,7 +36,7 @@
     "directory": "packages/vercel"
   },
   "peerDependencies": {
-    "@codespar/sdk": "^0.9.0",
+    "@codespar/sdk": "^0.10.0",
     "ai": ">=3.0.0"
   },
   "devDependencies": {

diff --git a/scripts/publish.sh b/scripts/publish.sh
@@ -21,9 +21,9 @@ set -euo pipefail
 # Versions — keep in sync with package.json / pyproject.toml. The script
 # does NOT bump these; it asserts they match what's on disk before publishing.
 # ---------------------------------------------------------------------------
-TYPES_VERSION="0.7.0"
-SDK_VERSION="0.9.0"
-PYTHON_VERSION="0.9.0"
+TYPES_VERSION="0.10.0"
+SDK_VERSION="0.10.0"
+PYTHON_VERSION="0.10.0"
 
 # ---------------------------------------------------------------------------
 # CLI flags — set by parse_args, consumed everywhere.
@@ -152,30 +152,45 @@ read_otp() {
 
 generate_changelog() {
   cat <<'EOF'
-## codespar 0.9.0 (Python) / @codespar/sdk 0.9.0 / @codespar/types 0.7.0
+## codespar 0.10.0 (Python) / @codespar/sdk 0.10.0 / @codespar/types 0.10.0
 
-SSE streaming for async settlement + verification status, replacing
-polling for long-running pending → settled flows.
+Hosted test-mode SDK surface — mocks forwarding on session create,
+structured `CodesparApiError`, five type-narrowed tool-result guards,
+and `CODESPAR_BASE_URL` env-var resolution so the same client wiring
+targets the managed backend or a self-hosted OSS runtime.
 
 ### Added
-- `session.paymentStatusStream(toolCallId, { onUpdate?, signal? })` —
-  Server-Sent Events stream over `GET /v1/tool-calls/:id/payment-status/stream`.
-  Pushes initial snapshot + every state change; resolves on terminal.
-  AbortSignal cancels.
-- `session.verificationStatusStream(toolCallId, { onUpdate?, signal? })`
-  — KYC sibling with the same lifecycle.
-- Python paridade: `AsyncSession.payment_status_stream` /
-  `verification_status_stream` (sync wrappers on the blocking client).
-
-### Types (@codespar/types 0.7.0)
-- `PaymentStatusStreamOptions`, `VerificationStatusStreamOptions`.
-- New `Session.paymentStatusStream` + `verificationStatusStream`
-  signatures.
-
-### Compat
-- Polling siblings (`paymentStatus` / `verificationStatus`) stay live
-  — additive change only. Adapter packages remain on `^0.3.0` ranges
-  for `@codespar/sdk` (method additions, no breaking changes).
+- `cs.create(userId, { mocks })` (TS) and `cs.create("u", mocks=...)`
+  (Python). Keys are canonical tool names in slash form
+  (`asaas/create_payment`); values are a `MockObject` for a static
+  mock or a `MockObject[]` for a stateful mock consumed in order.
+  Forwarded verbatim — the SDK does not rewrite tool names.
+- `CodesparApiError` (TS) — typed envelope for transport failures
+  carrying `{ status, code?, body?, cause? }`. Migration recipe for
+  callers parsing `e.message`: use `e.code === "foo"`.
+- `tool-result-codes` module — `isPolicyDenied`, `isApprovalRequired`,
+  `isMocksExhausted`, `isMocksEngineError`, `isToolNotMocked`,
+  `ToolResultCode` union, `TOOL_RESULT_CODES` set, and
+  `assertExhaustiveToolResult` exhaustive-match helper. Each guard
+  checks the `code` discriminant AND its required sibling fields.
+- `CODESPAR_BASE_URL` env-var resolution in the Python `CodeSpar` /
+  `AsyncCodeSpar` constructors (the TS constructor already did this).
+  Cascade: explicit option, then env var, then `https://api.codespar.dev`.
+
+### Types (@codespar/types 0.10.0)
+- `MockObject` and `MockValue` aliases; `CreateSessionRequest` widened
+  with optional `mocks` field.
+- Note: 0.8.0 and 0.9.0 were not released for `@codespar/types`; this
+  jump aligns it with the SDK and Python package versions.
+
+### Changed
+- Every transport call site now throws `CodesparApiError` instead of
+  the legacy `Error("send failed: 500 ...")`. `session.execute(...)`
+  keeps its returns-vs-throws asymmetry — only transport exceptions
+  change shape.
+- Python `_http.py` honors `code` over `error` when both are present
+  on a non-success response body.
+- Python `User-Agent` bumped to `codespar-python/0.10.0`.
 EOF
 }