---
title: SDK v0.3 → v0.9
description: Upgrading from @codespar/sdk@0.3.0 to 0.9.0. Additive release — eight new typed wrappers, two new auth types, async settlement and verification correlation, SSE streaming. No breaking changes to the 0.3 surface.
---
import { Callout } from "fumadocs-ui/components/callout";
# Migration — SDK v0.3 → v0.9
`@codespar/sdk@0.9.0` is an **additive** release. Everything that worked on 0.3 still works on 0.9 — the 0.3 surface (`create`, `tools`, `findTools`, `execute`, `send`, `sendStream`, `connections`, `authorize`, `close`, `loop`) is untouched. The point of this guide is to teach the new shape of the SDK, not to fix breakage.
Eight new methods landed on `Session` between 0.4 and 0.9 — typed wrappers for the meta-tools, polling and SSE variants for async settlement, and a typed wrapper for the connection wizard. You can keep calling `session.execute("codespar_charge", …)` if you prefer raw strings; the wrappers are an ergonomic layer on top.
## What's new since 0.3
- **Eight typed wrappers on `Session`** — `discover`, `connectionWizard`, `paymentStatus`, `paymentStatusStream`, `verificationStatus`, `verificationStatusStream`, `charge`, `ship`.
- **Two new auth types** — `cert` (mTLS for BR open-banking pilots like Banco do Brasil) and `hmac_signed` (per-request signing for Foxbit + LATAM crypto). Six total: `api_key`, `path_secret`, `oauth`, `cert`, `hmac_signed`, `none`.
- **53 routing rails** at the time, across the nine meta-tools that existed as of the 0.9 release, in six LATAM countries (BR, MX, AR, CO, CL, PE). The catalog has since grown; see [Tools and Meta-Tools](/docs/concepts/tools) for the current surface.
- **SSE streaming** for long-running async settlements — `paymentStatusStream` and `verificationStatusStream` push updates over an EventSource with a 15-second heartbeat and auto-close 5 seconds after a terminal state.
- **Async settlement correlation** — `tool_call_id` returned from `charge` / `pay` correlates with the provider's `external_reference` from webhook events, so the SDK can poll or stream the settlement status of an inbound charge or KYC inquiry without you wiring up the webhook plumbing.
## Method-by-method walkthrough
Each section shows the raw `execute()` form (which still works) and the typed wrapper (which is what 0.9 lands).
### 1. `session.discover(query)`
Semantic + lexical tool search backed by pgvector + pg_trgm.
**Before**
```typescript
const result = await session.execute("codespar_discover", {
query: "issue an invoice for a Brazilian customer",
});
```
**After**
```typescript
const result = await session.discover("issue an invoice for a Brazilian customer");
// result.matches: { tool, score, server }[]
```
### 2. `session.connectionWizard(serverId)`
Returns the connection-wizard backend payload — what auth fields the operator needs, the deep-link target, and current connection status.
**Before**
```typescript
const wiz = await session.execute("codespar_manage_connections", {
server_id: "asaas",
});
```
**After**
```typescript
const wiz = await session.connectionWizard("asaas");
// wiz.dashboard_url, wiz.required_fields, wiz.current_status
```
### 3. `session.charge(args)` — inbound (buyer pays merchant)
Typed wrapper for `codespar_charge`. Distinct from `codespar_pay` (which is outbound). Routes Pix BRL to Asaas / MP / iugu / Stone, and card USD to Stripe.
**Before**
```typescript
const result = await session.execute("codespar_charge", {
amount: 14900,
currency: "BRL",
method: "pix",
customer: { name: "...", document: "..." },
});
```
**After**
```typescript
const result = await session.charge({
amount: 14900,
currency: "BRL",
method: "pix",
customer: { name: "...", document: "..." },
});
// result.tool_call_id is what you pass to paymentStatus()
```
### 4. `session.ship(args)` — Melhor Envio
Typed wrapper for `codespar_ship`. Three rails: `domestic-label`, `domestic-quote`, `domestic-track`.
**Before**
```typescript
const label = await session.execute("codespar_ship", {
action: "label",
origin: { cep: "04538-132" },
destination: { cep: "01310-100" },
package: { weight_kg: 0.5 },
});
```
**After**
```typescript
const label = await session.ship({
action: "label",
origin: { cep: "04538-132" },
destination: { cep: "01310-100" },
package: { weight_kg: 0.5 },
});
```
### 5. `session.paymentStatus(toolCallId)` — polling
Poll the settlement state of an inbound charge or outbound transfer. Returns `pending`, `succeeded`, or `failed`.
**Before**
You wired up the webhook adapter yourself, parsed the provider's payload, and reconciled `external_reference` back to your record.
**After**
```typescript
const status = await session.paymentStatus(result.tool_call_id);
// status.state, status.provider, status.external_reference, status.events
```
### 6. `session.paymentStatusStream(toolCallId, opts?)` — SSE
Same correlation, lower latency. Emits each transition as it happens.
```typescript
await session.paymentStatusStream(result.tool_call_id, {
onUpdate: (s) => console.log(s.state, s.events.at(-1)),
signal: abortController.signal,
});
// Heartbeat every 15s. Auto-closes 5s after a terminal state.
```
### 7. `session.verificationStatus(toolCallId)` — polling
Mirror of `paymentStatus` for `codespar_kyc` inquiries (Persona, Sift, Konduto, Truora). States priority-ordered: `approved` > `rejected` > `review` > `expired` > `pending`.
```typescript
const v = await session.verificationStatus(kycResult.tool_call_id);
// v.state, v.provider, v.external_reference
```
### 8. `session.verificationStatusStream(toolCallId, opts?)` — SSE
```typescript
await session.verificationStatusStream(kycResult.tool_call_id, {
onUpdate: (v) => console.log(v.state),
});
```
## Async settlement: polling vs SSE
Both shapes correlate `tool_call_id` ↔ provider `external_reference` on the backend. Pick polling for one-off checks, SSE for long-running pending → settled flows.
**Polling**
```typescript
const charge = await session.charge({ amount: 14900, currency: "BRL", method: "pix", ... });
let status;
do {
await new Promise((r) => setTimeout(r, 2000));
status = await session.paymentStatus(charge.tool_call_id);
} while (status.state === "pending");
```
**SSE (recommended for long-running flows)**
```typescript
const charge = await session.charge({ amount: 14900, currency: "BRL", method: "pix", ... });
await session.paymentStatusStream(charge.tool_call_id, {
onUpdate: (s) => {
if (s.state === "succeeded") issueInvoice(charge);
},
});
```
SSE keeps a single connection open with a 15-second heartbeat, auto-closes 5 seconds after the terminal state, and avoids the polling cost when settlement takes minutes (Pix usually settles in seconds; cards and KYC review can take longer).
## New auth types
Two auth types shipped since 0.3. Both are catalog-driven — operators wire them up in the dashboard, agents don't see auth details at runtime.
- **`cert`** — mTLS for Brazilian open-banking. Operator uploads cert + key + CA via the Provider Connect modal. Banco do Brasil is the pilot; Itaú / Santander / Bradesco / Caixa next batch.
- **`hmac_signed`** — per-request signing (timestamp + method + path + body). Used by Foxbit and future LATAM crypto exchanges.
See [Authentication](/docs/concepts/authentication) for the full list (`api_key`, `path_secret`, `oauth`, `cert`, `hmac_signed`, `none`).
## Adapter peerDeps
All twelve framework adapters were lockstep-bumped to `0.4.0` with `peerDependencies: { "@codespar/sdk": "^0.9.0" }`. Upgrade both together:
```bash
npm install @codespar/sdk@latest @codespar/claude@latest
# or
npm install @codespar/sdk@latest @codespar/openai@latest
# … same for vercel, langchain, google-genai, mastra, crewai, autogen,
# llama-index, letta, camel, mcp
```
The adapter surfaces (`getTools`, `handleToolUse`, `handleToolCall`, `toClaudeTool`, `toOpenAITool`, etc.) did not change since 0.3 — the bump is purely to align the peer-dep range.
## Python parity
Every new method ships on `AsyncSession` (async) and the synchronous `Session` wrapper, in `snake_case`:
```python
from codespar import CodeSpar
cs = CodeSpar()
with cs.create("user_123", servers=["asaas"]) as session:
charge = session.charge(
amount=14900,
currency="BRL",
method="pix",
customer={"name": "...", "document": "..."},
)
status = session.payment_status(charge.tool_call_id)
```
The streaming variants take a keyword-only `on_update` callback:
```python
session.payment_status_stream(charge.tool_call_id, on_update=lambda s: print(s.state))
```
`AsyncCodeSpar` / `AsyncSession` mirror the same surface with `await` — see [Quickstart (Python)](/docs/quickstart-python).
## Upgrade checklist
- [ ] Bump `@codespar/sdk` to `^0.9.0` and every `@codespar/*` adapter to `^0.4.0` in `package.json`
- [ ] Regenerate the lockfile (`npm install`) so the adapter peerDep resolves to the new SDK
- [ ] (Optional) Replace `session.execute("codespar_charge", …)` calls with `session.charge(…)` for typed args + return types
- [ ] (Optional) Replace `session.execute("codespar_ship", …)` calls with `session.ship(…)`
- [ ] (Optional) Replace `session.execute("codespar_discover", …)` calls with `session.discover(…)`
- [ ] (Optional) Replace `session.execute("codespar_manage_connections", …)` calls with `session.connectionWizard(…)`
- [ ] For inbound charges and KYC inquiries: switch from manual webhook reconciliation to `paymentStatus` / `verificationStatus` (polling) or `*Stream` (SSE)
- [ ] If you use Brazilian open-banking or Foxbit, ask your operator to wire up `cert` / `hmac_signed` connections in the dashboard
- [ ] Run the test suite against a sandbox `csk_test_` key before swapping production keys
## Next steps