@codespar/sdk

Commerce SDK for AI agents — sessions, managed auth, Complete Loop orchestration for Latin American commercial APIs.

What's new in 0.5.0

Typed wrappers for the F3.M2 meta-tool router:

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

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.

Crypto + KYC meta-tools (raw execute() only)

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.

// Crypto: receive a USDC payment via Coinbase Commerce hosted checkout
const charge = await session.execute("codespar_crypto_pay", {
  amount: 29.9,
  currency: "USDC",
  direction: "receive",
  description: "Order #42",
});
// charge.output.hosted_url → redirect buyer here

// KYC: kick off a Persona identity verification
const inquiry = await session.execute("codespar_kyc", {
  buyer: { email: "[email protected]", first_name: "Alice", last_name: "Smith" },
  check_type: "identity",
});
// inquiry.output.verification_id → poll for completion

Install

npm install @codespar/sdk

Usage

import { CodeSpar } from "@codespar/sdk";

const cs = new CodeSpar({ apiKey: "ak_..." });

const session = await cs.create("user_123", {
  preset: "brazilian",
  manageConnections: { waitForConnections: true },
  // projectId: "prj_a1b2c3d4e5f6g7h8", // optional — overrides client default, falls back to org's default project
});

// Natural language
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",
});

// Complete Loop — tools, findTools, and loop are free functions
import { tools, findTools, loop } from "@codespar/sdk";

const available = await tools(session);
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!" } },
  ],
  onStepComplete: (step, r) => console.log(`✓ ${step.tool}`),
  retryPolicy: { maxRetries: 3, backoff: "exponential" },
});

API

new CodeSpar(config)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | CODESPAR_API_KEY env | Your API key | | baseUrl | string | https://api.codespar.dev | API base URL | | 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. |

cs.create(userId, config)

| Option | Type | Description | |--------|------|-------------| | servers | string[] | MCP servers to connect | | 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. |

Session methods

| Method | Description | |--------|-------------| | session.execute(tool, params) | Execute a specific tool | | session.send(message) | Send natural language message | | session.sendStream(message) | Stream events from a natural language message | | session.authorize(serverId) | Start OAuth flow for a server | | session.proxyExecute(request) | Proxy a raw HTTP call through the 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.mcp | MCP transport URL and headers (when using managed runtime) | | session.close() | Close session |

Free functions

tools, findTools, and loop are free functions that accept any SessionBase — they work with the managed runtime, Managed Agents sessions, and custom runtimes alike.

| Function | Description | |----------|-------------| | tools(session) | Get all available tools from the session | | findTools(session, query) | Search tools by name or description | | loop(session, config) | Run a Complete Loop workflow |

Migrating from 0.2.x

tools, findTools, and loop moved from session instance methods to free functions in 0.3.0.

// 0.2.x
const tools = await session.tools();
const found = await session.findTools("payment");
const result = await session.loop({ steps: [...] });

// 0.3.0
import { tools, findTools, loop } from "@codespar/sdk";
const available = await tools(session);
const found = await findTools(session, "payment");
const result = await loop(session, { steps: [...] });

Multi-environment (projects)

CodeSpar orgs have a second tenancy tier — projects — so dev / staging / prod each get isolated API keys, connected accounts, triggers, and sessions while billing stays at the org level. Every request accepts an optional x-codespar-project: prj_<16 hex> header; omit it and the backend resolves the org's default project (self-healed on first read).

Pin the whole client to one environment:

const cs = new CodeSpar({
  apiKey: process.env.CODESPAR_API_KEY!,
  projectId: "prj_staging0123abcd", // every session this client spawns scopes here
});

Or override per session:

const session = await cs.create("user_123", {
  preset: "brazilian",
  projectId: "prj_prod0123abcd", // overrides the client default
});

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 for the full tenancy model.

Need more?

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

License

MIT — codespar.dev