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.

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 across nine meta-tools and six LATAM countries (BR, MX, AR, CO, CL, PE).
• 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

const result = await session.execute("codespar_discover", {
  query: "issue an invoice for a Brazilian customer",
});

After

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

const wiz = await session.execute("codespar_manage_connections", {
  server_id: "asaas",
});

After

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

const result = await session.execute("codespar_charge", {
  amount: 14900,
  currency: "BRL",
  method: "pix",
  customer: { name: "...", document: "..." },
});

After

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

const label = await session.execute("codespar_ship", {
  action: "label",
  origin: { cep: "04538-132" },
  destination: { cep: "01310-100" },
  package: { weight_kg: 0.5 },
});

After

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

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.

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.

const v = await session.verificationStatus(kycResult.tool_call_id);
// v.state, v.provider, v.external_reference

8. session.verificationStatusStream(toolCallId, opts?) — SSE

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

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)

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 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:

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:

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:

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).

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