@codespar/sdk 0.9.0 → 0.10.1

package/README.md

@@ -2,19 +2,38 @@
 
 Commerce SDK for AI agents — sessions, managed auth, Complete Loop orchestration for Latin American commercial APIs.
 
-## What's new in 0.5.0
+## What's new in 0.9.0
 
-Typed wrappers for the F3.M2 meta-tool router:
+Eight new typed methods on `Session`, grouped by capability:
 
-- `session.discover(query, options?)` — find the right tool for a free-form use case (`codespar_discover`).
-- `session.connectionWizard(options)` — surface the connect deep-link when a needed server is disconnected (`codespar_manage_connections`). Credentials never travel through this method.
-- `session.paymentStatus(toolCallId)` — correlate webhook settlement back to the originating `codespar_pay` call via the response idempotency key.
+**Meta-tool wrappers** — neutral input shape, typed payload back, same wire as `session.execute(...)`:
 
-All three call into the same managed runtime as `session.execute(...)`; the wrappers just give you the typed payload shape without hand-rolling the meta-tool envelope.
+- `session.charge(args)` — INBOUND charges (`codespar_charge`). Buyer pays merchant. Pix BRL via Asaas / MP / iugu / Stone; card USD via Stripe. Distinct from `codespar_pay` (outbound transfers).
+- `session.ship(args)` — shipping (`codespar_ship`). One typed entry into Melhor Envio's 3 rails (`action: "label" | "quote" | "track"`).
+- `session.shop(args)` — buy-side shopping (`codespar_shop`). Catalog search → async checkout → Pix mint (`action: "search" | "checkout" | "checkout_status"`). Discriminated `ShopArgs`/`ShopResult` give the action-correct result type. Checkout is async: start, then poll `checkout_status` until `ready_for_payment` (carries `pix_copia_e_cola`) or `canceled`. Settle the returned Pix via a separate payment tool — settlement and governance are out of this contract. Full spec: [`docs/codespar-shop-contract.md`](../../docs/codespar-shop-contract.md).
 
-### Crypto + KYC meta-tools (raw `execute()` only)
+**Async settlement** — `codespar_charge` / `codespar_pay` return synchronously, but real settlement lands via webhook:
 
-Two newer meta-tools — `codespar_crypto_pay` (USDC/USDT/BTC across mainnet + L2s) and `codespar_kyc` (Persona / Sift / etc identity + risk verification) — are callable today via raw `session.execute(...)`. Typed SDK wrappers will land in a future release once at least 2 transforms per meta-tool are live in prod.
+- `session.paymentStatus(toolCallId)` — poll the latest known status (pending → succeeded / failed / refunded). Correlates via the response idempotency_key ↔ provider external_reference.
+- `session.paymentStatusStream(toolCallId, { onUpdate?, signal? })` — SSE variant. Snapshot on open, an envelope per state change, heartbeat every 15s, auto-closes 5s after a terminal state. `signal` aborts from the caller side.
+
+**Async verification** — `codespar_kyc` returns the inquiry id; the buyer finishes the hosted flow off-platform:
+
+- `session.verificationStatus(toolCallId)` — poll the disposition (pending → approved / rejected / review / expired).
+- `session.verificationStatusStream(toolCallId, { onUpdate?, signal? })` — SSE variant. Same lifecycle as `paymentStatusStream`.
+
+**Tool discovery + connection wizard** (already in 0.4.0, restated for completeness):
+
+- `session.discover(query, options?)` — semantic + lexical tool search across the catalog (`codespar_discover`, pgvector + pg_trgm).
+- `session.connectionWizard(options)` — connect deep-link backend (`codespar_manage_connections`). Credentials never travel through this method.
+
+All wrappers call into the same runtime as `session.execute(...)`; you get typed payloads instead of hand-rolling the meta-tool envelope.
+
+> **The typed meta-tool facades (`shop()`, `charge()`, `ship()`, …) are clients, not implementations.** Each is a thin wrapper over `execute("codespar_<tool>", args)` and requires a runtime that **implements** that meta-tool (a registered implementation behind the contract). Against a self-hosted runtime with no registered implementation, the call returns `Tool not registered`. The contract + the typed facade ship here MIT; the implementation is registered by the runtime you point `baseUrl` at.
+
+### Crypto + KYC meta-tools
+
+`codespar_crypto_pay` (Coinbase Commerce + Bitso + UnblockPay + Foxbit) and `codespar_kyc` (Persona, Sift, Konduto, Truora) are routable today. The verification half now has a typed wrapper (`session.verificationStatus` / `verificationStatusStream`); a `session.cryptoPay(...)` typed wrapper is not in 0.9.0 — call via raw `session.execute("codespar_crypto_pay", {...})` for now.
 
 ```typescript
 // Crypto: receive a USDC payment via Coinbase Commerce hosted checkout
@@ -26,12 +45,26 @@ const charge = await session.execute("codespar_crypto_pay", {
 });
 // charge.output.hosted_url → redirect buyer here
 
-// KYC: kick off a Persona identity verification
+// Crypto: send a USDC payout to an external wallet (UnblockPay stablecoin-payout)
+const payout = await session.execute("codespar_crypto_pay", {
+  rail: "stablecoin-payout",
+  amount: 100,
+  currency: "USDC",
+  direction: "send",
+  counterparty: {
+    address: "0xRecipientWalletAddress...",
+    country: "MX", // ISO 3166-1 alpha-2 — required when direction is "send"
+  },
+});
+// payout.output.id / .status → poll via session.paymentStatus(payout.tool_call_id)
+
+// KYC: kick off a Persona identity verification, then poll typed
 const inquiry = await session.execute("codespar_kyc", {
   buyer: { email: "alice@example.com", first_name: "Alice", last_name: "Smith" },
   check_type: "identity",
 });
-// inquiry.output.verification_id → poll for completion
+const v = await session.verificationStatus(inquiry.tool_call_id);
+//        ^^ approved | rejected | review | expired | pending
 ```
 
 ## Install
@@ -57,9 +90,10 @@ const session = await cs.create("user_123", {
 const result = await session.send("Charge R$150 via Pix and issue the NF-e");
 
 // Direct tool execution
-const charge = await session.execute("ZOOP_CREATE_CHARGE", {
-  amount: 150.0,
-  payment_type: "pix",
+const charge = await session.execute("asaas/create_payment", {
+  customer: "cus_xxx",
+  billingType: "PIX",
+  value: 150,
 });
 
 // Complete Loop — tools, findTools, and loop are free functions
@@ -70,10 +104,10 @@ const payments = await findTools(session, "payment");
 
 const result = await loop(session, {
   steps: [
-    { tool: "ZOOP_CREATE_CHARGE", params: { amount: 150, payment_type: "pix" } },
-    { tool: "NUVEMFISCAL_EMITIR_NFE", params: (prev) => ({ chargeId: prev[0].data }) },
-    { tool: "MELHORENVIO_GENERATE_LABEL", params: {} },
-    { tool: "ZAPI_SEND_MESSAGE", params: { text: "Your order is on the way!" } },
+    { tool: "codespar_charge", params: { amount: 150, currency: "BRL", method: "pix", buyer: { name, document: cpf } } },
+    { tool: "codespar_invoice", params: (prev) => ({ rail: "nfe", company_id, payment_id: prev[0].data.id }) },
+    { tool: "codespar_ship", params: { action: "label", origin, destination, items } },
+    { tool: "codespar_notify", params: { recipient: phone, message: "Your order is on the way!" } },
   ],
   onStepComplete: (step, r) => console.log(`✓ ${step.tool}`),
   retryPolicy: { maxRetries: 3, backoff: "exponential" },
@@ -87,7 +121,7 @@ const result = await loop(session, {
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `apiKey` | `string` | `CODESPAR_API_KEY` env | Your API key |
-| `baseUrl` | `string` | `https://api.codespar.dev` | API base URL |
+| `baseUrl` | `string` | `CODESPAR_BASE_URL` env, else `https://api.codespar.dev` | API base URL. Set `CODESPAR_BASE_URL=http://localhost:8000` to point the SDK at a [local OSS runtime](https://github.com/codespar/codespar); the managed backend is the default. |
 | `managed` | `boolean` | `true` | Enable managed billing/logging |
 | `projectId` | `string` | — | Optional `prj_<16alphanum>`. Client-wide default project; sent as `x-codespar-project`. Falls back to the org's default project when omitted. |
 
@@ -99,6 +133,7 @@ const result = await loop(session, {
 | `preset` | `string` | `"brazilian"`, `"mexican"`, `"argentinian"`, `"colombian"`, `"all"` |
 | `manageConnections.waitForConnections` | `boolean` | Block until all servers connected |
 | `projectId` | `string` | Optional `prj_<16alphanum>`. Overrides the client-level `projectId`; falls back to the org's default project when both are unset. |
+| `mocks` | `Record<string, MockValue>` | Optional test-mode mocks. See [Test-mode mocks](#test-mode-mocks). |
 
 ### Session methods
 
@@ -112,7 +147,12 @@ const result = await loop(session, {
 | `session.connections()` | List connected servers |
 | `session.discover(query, options?)` | Tool search via `codespar_discover` (typed) |
 | `session.connectionWizard(options)` | Connect deep-link via `codespar_manage_connections` (typed) |
-| `session.paymentStatus(toolCallId)` | Async settlement status for a `codespar_pay` call |
+| `session.charge(args)` | Inbound charge via `codespar_charge` (typed) — buyer pays merchant |
+| `session.ship(args)` | Shipping via `codespar_ship` (typed) — `action: "label" \| "quote" \| "track"` |
+| `session.paymentStatus(toolCallId)` | Async settlement status for a `codespar_charge` / `codespar_pay` call |
+| `session.paymentStatusStream(toolCallId, opts)` | SSE variant of `paymentStatus`; resolves on terminal |
+| `session.verificationStatus(toolCallId)` | Async KYC disposition for a `codespar_kyc` call |
+| `session.verificationStatusStream(toolCallId, opts)` | SSE variant of `verificationStatus`; resolves on terminal |
 | `session.mcp` | MCP transport URL and headers (when using managed runtime) |
 | `session.close()` | Close session |
 
@@ -167,6 +207,129 @@ const session = await cs.create("user_123", {
 
 Precedence: `sessionConfig.projectId` > `clientConfig.projectId` > backend's org default. Format is validated at construction via Zod (`/^prj_[A-Za-z0-9]{16}$/`) so typos fail fast. See the [Projects concept doc](https://docs.codespar.dev/concepts/projects) for the full tenancy model.
 
+## Test-mode mocks
+
+Skip live providers in tests by passing a `mocks` map to `cs.create`. Keys are canonical tool names in slash form (`asaas/create_payment`, `melhor-envio/calculate_shipping`, …). Values are either a single object — used as the response on every matching call — or an array of objects consumed in order, returning `mocks_exhausted` once the list drains.
+
+```typescript
+import { CodeSpar } from "@codespar/sdk";
+
+const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY });
+
+const session = await cs.create("user_test", {
+  servers: ["asaas"],
+  mocks: {
+    "asaas/create_payment": { id: "pay_test", status: "PENDING" },
+  },
+});
+
+const result = await session.execute("asaas/create_payment", { value: 100 });
+// result.data === { id: "pay_test", status: "PENDING" }
+```
+
+Pass an array for stateful mocks:
+
+```typescript
+mocks: {
+  "asaas/create_payment": [
+    { id: "pay_1", status: "PENDING" },
+    { id: "pay_1", status: "RECEIVED" },
+  ],
+}
+```
+
+Mocks live behind the managed backend's test-mode gate — a `csk_test_*` API key against a `test`-environment project. Live keys against the same map return `mocks_not_permitted`. The SDK forwards keys verbatim; if you send the OSS double-underscore form (`asaas__create_payment`) the backend rejects with `mocks_invalid` rather than the SDK silently rewriting.
+
+The OSS runtime accepts the same `mocks` shape on its session API (see [codespar/codespar#113](https://github.com/codespar/codespar/pull/113)), so the same test fixtures work whether you point at `api.codespar.dev` or a self-hosted instance via `CODESPAR_BASE_URL`. Self-hosted runtimes must additionally set `CODESPAR_TEST_MODE_ENABLED=true` on the server process; without it, the SDK receives `mocks_not_permitted` / HTTP 501 instead of fixture responses.
+
+Storage shape differs by runtime — the wire contract does not. The managed backend persists mocks and per-tool consume counters; sessions and their fixtures survive restarts and multi-replica deployments. The OSS runtime holds both in process memory; they are scoped to the HTTP-session process and are lost on restart, and channel-bridge sessions (WhatsApp, Slack, Telegram, Discord) cannot carry mocks under the OSS shape. Response envelopes, status codes, sibling fields, and gate ordering are byte-identical between runtimes regardless. See [the test-mode concept doc](https://docs.codespar.dev/concepts/test-mode) for the full per-runtime split.
+
+Test mode is a property of the runtime, not the session. On the managed backend it's `project.environment === 'test'`; on a self-hosted OSS runtime it's `CODESPAR_TEST_MODE_ENABLED=true` on the server process. When the runtime is in test mode, every external tool call your code or LLM dispatches must match a declared mock — unmatched calls return `tool_not_mocked` (HTTP 422 on the catalog-routed `/execute` path; a `tool_result` block on the chat-loop) and no upstream provider runs. The envelope covers three failure modes: the `mocks` map has no entry for the canonical name, the session was created with no `mocks` field, or the canonical name has an unknown server prefix. A session that doesn't declare `mocks` can't dispatch any tools in test mode; declare the mocks the test will exercise, or run the same code against a live-mode runtime where the real providers handle dispatch. Built-in metadata tools — `codespar_list_tools` on OSS, `codespar_discover` and `codespar_manage_connections` on the managed backend — bypass this gate.
+
+### Type aliases
+
+`MockObject` (`Record<string, unknown>`) and `MockValue` (`MockObject | MockObject[]`) ship from `@codespar/types` and re-export through `@codespar/sdk`. Use them when you want to define mock fixtures separately from the `create` call site.
+
+```typescript
+import type { MockValue } from "@codespar/sdk";
+
+const fixtures: Record<string, MockValue> = {
+  "asaas/create_payment": { id: "pay_test", status: "PENDING" },
+};
+```
+
+## Typed errors
+
+Every transport failure from `createSession`, `proxyExecute`, `send`, `sendStream`, `paymentStatus(Stream)`, `verificationStatus(Stream)`, and `authorize` throws a `CodesparApiError` with a structured `code` field. The old `e.message.includes("foo")` pattern is gone — branch on `e.code` instead.
+
+```typescript
+import { CodesparApiError } from "@codespar/sdk";
+
+try {
+  await cs.create("user_test", { mocks: { "asaas/create_payment": {} } });
+} catch (err) {
+  if (err instanceof CodesparApiError) {
+    if (err.code === "mocks_not_permitted") {
+      // Live key against a mocks map. Swap to csk_test_*.
+    } else if (err.code === "mocks_invalid") {
+      // Backend rejected a tool-name key. Check the slash form.
+    } else if (err.status === 0) {
+      // Network never reached the backend; err.cause has the fetch rejection.
+    }
+    throw err;
+  }
+}
+```
+
+`session.execute` keeps its returns-vs-throws asymmetry: tool failures come back as `ToolResult.success === false` with the body on `error`. Only transport-level failures throw.
+
+### Tool-result guards
+
+The five reserved tool-result codes (`policy_denied`, `approval_required`, `mocks_exhausted`, `mocks_engine_error`, `tool_not_mocked`) ship typed guards plus an exhaustive-match helper. Guards run against any `unknown` payload — both `ToolResult.data` from `session.execute` and `ToolCallRecord.output` from `send` / `sendStream`. Each guard checks the `code` discriminant AND the variant's required sibling fields, so a malformed payload returns false rather than narrowing positive on the code alone.
+
+```typescript
+import {
+  isApprovalRequired,
+  isMocksEngineError,
+  isMocksExhausted,
+  isPolicyDenied,
+  isToolNotMocked,
+  assertExhaustiveToolResult,
+  ToolResultCode,
+} from "@codespar/sdk";
+
+const result = await session.execute("asaas/create_payment", { value: 100 });
+
+if (isPolicyDenied(result.data)) {
+  console.warn(`blocked by ${result.data.rule_id}: ${result.data.message}`);
+} else if (isApprovalRequired(result.data)) {
+  console.log(`needs approval ${result.data.approval_id} by ${result.data.expires_at}`);
+} else if (isMocksExhausted(result.data)) {
+  // Stateful mock array drained — pad it or extend the test.
+} else if (isMocksEngineError(result.data)) {
+  // Backend-side mocks engine failure; usually a malformed fixture.
+} else if (isToolNotMocked(result.data)) {
+  console.warn(`no mock for ${result.data.tool_name}`);
+}
+```
+
+The same guards apply inside a `sendStream` loop against `event.toolCall.output`.
+
+When a `switch` over `ToolResultCode` covers every variant, call `assertExhaustiveToolResult` in the default branch. TypeScript fails to compile if a sixth code lands without a matching arm.
+
+```typescript
+function handle(outcome: ToolResultOutcome): string {
+  switch (outcome.code) {
+    case ToolResultCode.PolicyDenied: return outcome.rule_id;
+    case ToolResultCode.ApprovalRequired: return outcome.approval_id;
+    case ToolResultCode.MocksExhausted: return "exhausted";
+    case ToolResultCode.MocksEngineError: return "engine";
+    case ToolResultCode.ToolNotMocked: return outcome.tool_name;
+    default: return assertExhaustiveToolResult(outcome);
+  }
+}
+```
+
 ## Need more?
 
 Need governance, budget limits, and audit trails for agent payments? **[CodeSpar Enterprise](https://codespar.dev/enterprise)** adds policy engine, payment routing, and compliance templates on top of these MCP servers.

package/dist/__tests__/base-url-resolution.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `CODESPAR_BASE_URL` env-var resolution for the TS client.
+ *
+ * The constructor cascade is: explicit `baseUrl` option, then the
+ * `CODESPAR_BASE_URL` env var, then the production default. The env
+ * var lets a caller point the same client wiring at a local OSS
+ * runtime or at `api.codespar.dev` without rebuilding the call sites.
+ */
+export {};
+//# sourceMappingURL=base-url-resolution.test.d.ts.map

package/dist/__tests__/base-url-resolution.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-url-resolution.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/base-url-resolution.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/__tests__/base-url-resolution.test.js

@@ -0,0 +1,57 @@
+/**
+ * `CODESPAR_BASE_URL` env-var resolution for the TS client.
+ *
+ * The constructor cascade is: explicit `baseUrl` option, then the
+ * `CODESPAR_BASE_URL` env var, then the production default. The env
+ * var lets a caller point the same client wiring at a local OSS
+ * runtime or at `api.codespar.dev` without rebuilding the call sites.
+ */
+import { describe, it, expect } from "vitest";
+import { CodeSpar } from "../index.js";
+describe("CODESPAR_BASE_URL env-var fallback", () => {
+    it("uses CODESPAR_BASE_URL when no explicit baseUrl is passed", () => {
+        const prevBase = process.env.CODESPAR_BASE_URL;
+        const prevKey = process.env.CODESPAR_API_KEY;
+        process.env.CODESPAR_BASE_URL = "https://oss.codespar.local";
+        process.env.CODESPAR_API_KEY = "csk_live_test";
+        try {
+            const cs = new CodeSpar();
+            // baseUrl is private; the smoke test is that construction
+            // succeeds and the default does NOT override an env override.
+            // The behavior is exercised via createSession's URL prefix in
+            // the integration tests.
+            expect(cs).toBeDefined();
+        }
+        finally {
+            if (prevBase === undefined)
+                delete process.env.CODESPAR_BASE_URL;
+            else
+                process.env.CODESPAR_BASE_URL = prevBase;
+            if (prevKey === undefined)
+                delete process.env.CODESPAR_API_KEY;
+            else
+                process.env.CODESPAR_API_KEY = prevKey;
+        }
+    });
+    it("explicit baseUrl wins over CODESPAR_BASE_URL env var", () => {
+        const prev = process.env.CODESPAR_BASE_URL;
+        process.env.CODESPAR_BASE_URL = "https://oss.codespar.local";
+        try {
+            const cs = new CodeSpar({
+                apiKey: "csk_live_x",
+                baseUrl: "https://override.example.com",
+            });
+            // Smoke — construction succeeds with both set. The wire-level
+            // behavior is covered by createSession tests that fetch-mock
+            // the URL prefix directly.
+            expect(cs).toBeDefined();
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.CODESPAR_BASE_URL;
+            else
+                process.env.CODESPAR_BASE_URL = prev;
+        }
+    });
+});
+//# sourceMappingURL=base-url-resolution.test.js.map

package/dist/__tests__/base-url-resolution.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-url-resolution.test.js","sourceRoot":"","sources":["../../src/__tests__/base-url-resolution.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,QAAQ,CAAC,oCAAoC,EAAE,GAAG,EAAE;IAClD,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAC/C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;QAC7C,OAAO,CAAC,GAAG,CAAC,iBAAiB,GAAG,4BAA4B,CAAC;QAC7D,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,eAAe,CAAC;QAC/C,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC1B,0DAA0D;YAC1D,8DAA8D;YAC9D,8DAA8D;YAC9D,yBAAyB;YACzB,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAC3B,CAAC;gBAAS,CAAC;YACT,IAAI,QAAQ,KAAK,SAAS;gBAAE,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;;gBAC5D,OAAO,CAAC,GAAG,CAAC,iBAAiB,GAAG,QAAQ,CAAC;YAC9C,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;;gBAC1D,OAAO,CAAC,GAAG,CAAC,gBAAgB,GAAG,OAAO,CAAC;QAC9C,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;QAC3C,OAAO,CAAC,GAAG,CAAC,iBAAiB,GAAG,4BAA4B,CAAC;QAC7D,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC;gBACtB,MAAM,EAAE,YAAY;gBACpB,OAAO,EAAE,8BAA8B;aACxC,CAAC,CAAC;YACH,8DAA8D;YAC9D,6DAA6D;YAC7D,2BAA2B;YAC3B,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAC3B,CAAC;gBAAS,CAAC;YACT,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;;gBACxD,OAAO,CAAC,GAAG,CAAC,iBAAiB,GAAG,IAAI,CAAC;QAC5C,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/errors.test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tests for CodesparApiError + the throwFromResponse helper that
+ * collapses all transport-failure throw sites in session.ts.
+ *
+ * Asserts:
+ *   - Every transport throw site surfaces a CodesparApiError (not
+ *     a plain Error) carrying status + code + body.
+ *   - Network errors wrap fetch rejections into CodesparApiError
+ *     with status: 0 and preserve the underlying cause.
+ *   - The session.execute non-ok branch is untouched — it still
+ *     returns ToolResult.success === false rather than throwing.
+ *   - instanceof CodesparApiError works across realms (prototype
+ *     chain is restored via Object.setPrototypeOf).
+ */
+export {};
+//# sourceMappingURL=errors.test.d.ts.map

package/dist/__tests__/errors.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/errors.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/__tests__/errors.test.js

@@ -0,0 +1,163 @@
+/**
+ * Tests for CodesparApiError + the throwFromResponse helper that
+ * collapses all transport-failure throw sites in session.ts.
+ *
+ * Asserts:
+ *   - Every transport throw site surfaces a CodesparApiError (not
+ *     a plain Error) carrying status + code + body.
+ *   - Network errors wrap fetch rejections into CodesparApiError
+ *     with status: 0 and preserve the underlying cause.
+ *   - The session.execute non-ok branch is untouched — it still
+ *     returns ToolResult.success === false rather than throwing.
+ *   - instanceof CodesparApiError works across realms (prototype
+ *     chain is restored via Object.setPrototypeOf).
+ */
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { CodesparApiError } from "../errors.js";
+import { CodeSpar } from "../index.js";
+describe("CodesparApiError", () => {
+    it("constructs with status + message", () => {
+        const err = new CodesparApiError("boom", { status: 500 });
+        expect(err.status).toBe(500);
+        expect(err.message).toBe("boom");
+        expect(err.code).toBeUndefined();
+        expect(err.body).toBeUndefined();
+    });
+    it("carries the structured code + body + cause", () => {
+        const cause = new Error("underlying");
+        const err = new CodesparApiError("boom", {
+            status: 403,
+            code: "mocks_not_permitted",
+            body: { error: "mocks_not_permitted", message: "test mode key required" },
+            cause,
+        });
+        expect(err.status).toBe(403);
+        expect(err.code).toBe("mocks_not_permitted");
+        expect(err.body).toEqual({
+            error: "mocks_not_permitted",
+            message: "test mode key required",
+        });
+        expect(err.cause).toBe(cause);
+    });
+    it("instanceof CodesparApiError works after prototype-chain repair", () => {
+        const err = new CodesparApiError("x", { status: 1 });
+        expect(err instanceof CodesparApiError).toBe(true);
+        expect(err instanceof Error).toBe(true);
+        expect(err.name).toBe("CodesparApiError");
+    });
+});
+describe("session transport-failure call sites throw CodesparApiError", () => {
+    const originalFetch = globalThis.fetch;
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    it("createSession throws CodesparApiError on 4xx with structured body", async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue({
+            ok: false,
+            status: 403,
+            text: async () => JSON.stringify({
+                error: "mocks_not_permitted",
+                message: "csk_test_* key required",
+            }),
+        });
+        const cs = new CodeSpar({
+            apiKey: "csk_live_test",
+            baseUrl: "https://api.example.com",
+        });
+        try {
+            await cs.create("user_42");
+            expect.fail("expected createSession to throw");
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(CodesparApiError);
+            const apiErr = err;
+            expect(apiErr.status).toBe(403);
+            expect(apiErr.code).toBe("mocks_not_permitted");
+        }
+    });
+    it("createSession wraps fetch rejection as CodesparApiError status 0", async () => {
+        const underlying = new TypeError("Network failure");
+        globalThis.fetch = vi
+            .fn()
+            .mockRejectedValue(underlying);
+        const cs = new CodeSpar({
+            apiKey: "csk_live_test",
+            baseUrl: "https://api.example.com",
+        });
+        try {
+            await cs.create("user_42");
+            expect.fail("expected createSession to throw");
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(CodesparApiError);
+            const apiErr = err;
+            expect(apiErr.status).toBe(0);
+            expect(apiErr.cause).toBe(underlying);
+        }
+    });
+    it("send throws CodesparApiError on 5xx", async () => {
+        const sessionCreate = {
+            ok: true,
+            status: 201,
+            text: async () => "",
+            json: async () => ({
+                id: "ses_err",
+                org_id: "o",
+                user_id: "u",
+                servers: [],
+                status: "active",
+                created_at: new Date().toISOString(),
+                closed_at: null,
+            }),
+        };
+        const sendFail = {
+            ok: false,
+            status: 502,
+            text: async () => JSON.stringify({ code: "upstream_unavailable" }),
+        };
+        globalThis.fetch = vi
+            .fn()
+            .mockResolvedValueOnce(sessionCreate)
+            .mockResolvedValueOnce(sendFail);
+        const cs = new CodeSpar({
+            apiKey: "csk_live_test",
+            baseUrl: "https://api.example.com",
+        });
+        const session = await cs.create("u");
+        await expect(session.send("hi")).rejects.toBeInstanceOf(CodesparApiError);
+    });
+    it("session.execute does NOT throw on non-ok — returns ToolResult.success=false", async () => {
+        const sessionCreate = {
+            ok: true,
+            status: 201,
+            text: async () => "",
+            json: async () => ({
+                id: "ses_ok",
+                org_id: "o",
+                user_id: "u",
+                servers: [],
+                status: "active",
+                created_at: new Date().toISOString(),
+                closed_at: null,
+            }),
+        };
+        const execFail = {
+            ok: false,
+            status: 422,
+            text: async () => "validation failed",
+        };
+        globalThis.fetch = vi
+            .fn()
+            .mockResolvedValueOnce(sessionCreate)
+            .mockResolvedValueOnce(execFail);
+        const cs = new CodeSpar({
+            apiKey: "csk_live_test",
+            baseUrl: "https://api.example.com",
+        });
+        const session = await cs.create("u");
+        const result = await session.execute("asaas/create_payment", {});
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("422");
+    });
+});
+//# sourceMappingURL=errors.test.js.map

package/dist/__tests__/errors.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.js","sourceRoot":"","sources":["../../src/__tests__/errors.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/forward-mocks.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tests for the createSession body builder's `mocks` forwarding.
+ *
+ * Asserts:
+ *   - Wire-neutrality: a cs.create without `mocks` produces a body
+ *     byte-identical to today's shape (R18).
+ *   - Forwarded shape: a cs.create with `mocks` includes the field
+ *     verbatim — no SDK-side rewriting of canonical names.
+ *   - Empty `mocks: {}` is forwarded (the backend accepts; strict-
+ *     mode R3a activates only on non-empty maps).
+ *   - Double-underscore key form reaches the backend unrewritten
+ *     so the canonical-form rejection surfaces at the right layer.
+ */
+export {};
+//# sourceMappingURL=forward-mocks.test.d.ts.map

package/dist/__tests__/forward-mocks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forward-mocks.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/forward-mocks.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}