From dd4f961f16c4e6edcb1d5a655b3d1bdfe2e7ef3e Mon Sep 17 00:00:00 2001 From: Fabiano Cruz Date: Sat, 4 Jul 2026 14:37:42 -0300 Subject: [PATCH] docs(readme): 14-tool roster by side, 0.10 line, wallet story, honest hermes The main SDK README was the stalest developer surface: install snippet pinned "currently 0.9.0", the meta-tools table listed 9 of 14 (no shop/wallet/ledger/issue/checkout), zero mention of the mandate/wallet surface the CLI ships, and hermes + managed-agents-adapter presented as installable when one is unpublished and the other private. - meta-tools table rebuilt: 14 tools in three groups (buy/sell/shared) with purposes mirroring the docs' platform-facts roster - new "Mandates and the consumer wallet" section: multi-slot mandate (BRL + USDC under one signature, per-currency caps, no FX) + the CLI one-liners, consistent with packages/cli/README.md - install comment depins to "0.10 line"; hermes marked coming-soon (not on npm); managed-agents-adapter marked private/source-only - packages/hermes/README.md: not-yet-published notice up top - packages/core/README.md: "What's new in 0.9.0" retitled historical Vendor names removed from the README per the 2026-07-03 decision. Co-Authored-By: Claude Fable 5 --- README.md | 64 ++++++++++++++++++++++++++++++--------- packages/core/README.md | 4 ++- packages/hermes/README.md | 2 ++ 3 files changed, 54 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 1c4c2e5..ec44afa 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ LATAM-first by design: Pix + NF-e + WhatsApp + PSP routing are first-class, with | [`codespar` (PyPI)](packages/python) | Python SDK — same surface as `@codespar/sdk`, sync + async | | [`@codespar/types`](packages/types) | Zero-dependency `SessionBase`/`Session` interface hierarchy and conformance test suite | | [`@codespar/api-types`](packages/api-types) | Shared REST wire contract — Zod schemas + inferred TypeScript types for `api.codespar.dev` | -| [`@codespar/managed-agents-adapter`](packages/managed-agents-adapter) | Anthropic Managed Agents adapter — runs `SessionBase` tools against Managed Agents sessions | +| [`@codespar/managed-agents-adapter`](packages/managed-agents-adapter) | Anthropic Managed Agents adapter — runs `SessionBase` tools against Managed Agents sessions (private package, source-only, not installable from npm) | | [`@codespar/cli`](packages/cli) | Command-line interface — auth, execute, sessions, scaffolding | | [`@codespar/mcp`](packages/mcp) | MCP transport for Claude Desktop, Cursor, VS Code | @@ -33,12 +33,12 @@ LATAM-first by design: Pix + NF-e + WhatsApp + PSP routing are first-class, with | [`@codespar/autogen`](packages/autogen) | Microsoft AutoGen | | [`@codespar/camel`](packages/camel) | CAMEL-AI | | [`@codespar/letta`](packages/letta) | Letta (MemGPT) | -| [`@codespar/hermes`](packages/hermes) | Hermes Agent (Nous Research) | +| [`@codespar/hermes`](packages/hermes) | Hermes Agent (Nous Research) (coming soon, not yet on npm) | ## Quick Start ```bash -npm install @codespar/sdk # currently 0.9.0 +npm install @codespar/sdk # 0.10 line ``` ```typescript @@ -140,21 +140,40 @@ const result = await loop(session, { ### Meta-tools -Beyond direct canonical-tool calls, the SDK exposes commerce-grade -**meta-tools** that route to the best provider per request, with -failover, idempotency, and per-tenant connection config: +Beyond direct canonical-tool calls, the platform registers 14 +commerce-grade **meta-tools** that route to the best provider per +request, with failover, idempotency, and per-tenant connection config. +They split into a buy side (the agent spends), a sell side (the agent +sells), and shared infrastructure: + +**Buy side** + +| Meta-tool | What it does | +|---|---| +| `codespar_shop` | Search and buy from real stores; async checkout session to the store's payable Pix | +| `codespar_wallet` | The agent's governed funds: balance, statement, top-up; per-currency slots | +| `codespar_pay` | Outbound spend: money leaves the wallet the agent governs | +| `codespar_crypto_pay` | On-chain spend and cross-border ramps (testnet today) | +| `codespar_issue` | Spend cards bound to the same mandate governance | + +**Sell side** + +| Meta-tool | What it does | +|---|---| +| `codespar_checkout` | Assemble a cart and dispatch it as a charge with a hosted payment page | +| `codespar_charge` | Inbound charges: the buyer pays you | +| `codespar_invoice` | Fiscal documents (NFS-e default; NF-e, CFDI, Factura AR) | +| `codespar_ship` | Quote, label, and track shipments | +| `codespar_notify` | Messages via WhatsApp, SMS, email | +| `codespar_kyc` | Verify counterparties before money moves | + +**Shared** | Meta-tool | What it does | |---|---| -| `codespar_pay` | Outbound transfers / payouts (Asaas, Mercado Pago). | -| `codespar_charge` | INBOUND charges — buyer pays merchant. Pix BRL via Asaas / MP / iugu / Stone; card USD via Stripe. | -| `codespar_invoice` | Fiscal invoices. Defaults to NFS-e (services); pass `rail: "nfe"` for product NF-e via NFe.io. Also `nfci` (CFDI MX, Facturapi) and Factura AR (AFIP). | -| `codespar_notify` | Messaging — WhatsApp via Z-API / Twilio, SMS via Twilio, email via SendGrid. | -| `codespar_ship` | Melhor Envio with 3 rails (`action: "label" \| "quote" \| "track"`). | -| `codespar_crypto_pay` | Crypto payments via Coinbase Commerce + Bitso. | -| `codespar_kyc` | Identity / risk verification — Persona, Sift, Konduto, Truora. | -| `codespar_discover` | Find a tool for a free-form use case (`session.discover("...")`). | -| `codespar_manage_connections` | Surface the connection wizard (`session.connectionWizard({...})`). | +| `codespar_ledger` | Double-entry books plus the signed agentic receipts | +| `codespar_discover` | Semantic search across the catalog (`session.discover("...")`) | +| `codespar_manage_connections` | Providers, credentials, and shopper identity (`session.connectionWizard({...})`) | Use `session.execute("codespar_pay", { amount, currency, recipient })` or the typed wrappers (`session.discover`, `session.connectionWizard`). @@ -162,6 +181,21 @@ The router picks the best provider per call based on the tenant's connections + cost/latency telemetry. See [`docs/tool-router.md`](docs/tool-router.md) for how the router selects a provider per call. +### Mandates and the consumer wallet + +Buy-side spending is governed by a signed mandate that backs a unified +multi-currency wallet: one signature mints per-currency slots (for +example BRL via Pix plus USDC), each with its own total cap and per-tx +cap. There is no FX inside the wallet; the payee routes the spend to the +matching currency slot, and a cross-currency move is a real ramp trade +at the real rate. From [`@codespar/cli`](packages/cli): + +```bash +codespar mandate create --slot BRL:pix:50000:10000 --slot USDC:usdc:100:25 +codespar wallet # rolled up per currency +codespar transfer --from BRL --to USDC --amount 15000 +``` + ## Framework Adapters Each adapter exposes `getTools(session)` returning tools shaped for that framework. Same session, any framework — pick one or compose several. diff --git a/packages/core/README.md b/packages/core/README.md index cdfd1d4..6975182 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -2,7 +2,9 @@ Commerce SDK for AI agents — sessions, managed auth, Complete Loop orchestration for Latin American commercial APIs. -## What's new in 0.9.0 +## What shipped in 0.9 + +The current release line is 0.10; the notes below are the 0.9 changelog, kept for reference. Eight new typed methods on `Session`, grouped by capability: diff --git a/packages/hermes/README.md b/packages/hermes/README.md index 9a79bbc..7f3e3fa 100644 --- a/packages/hermes/README.md +++ b/packages/hermes/README.md @@ -1,5 +1,7 @@ # @codespar/hermes +> **Not yet published to npm.** This package builds from source in this repo; the install command below will not resolve until the first npm release lands. + Hermes Agent (Nous Research) adapter for CodeSpar — convert session tools to Hermes's MCP/plugin tool format. Hermes agents ship with a Privy-secured embedded wallet and credit billing but **no commerce rail**. This adapter gives them LATAM commerce (pay / charge / invoice / ship / notify) routed through a CodeSpar session for billing and audit.