Skip to content

feat!: codespar_card for Pomelo and Rain, no alias; issue() and codespar issue removed (SDK, CLI, MCP, Python; coordinated 0.x release) - #250

Draft
fabianocruz wants to merge 12 commits into
mainfrom
feat/codespar-card
Draft

fabianocruz wants to merge 12 commits into
mainfrom
feat/codespar-card

Conversation

@fabianocruz

@fabianocruz fabianocruz commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

This is the client side of the coordinated Cards delivery. One contract, codespar_card, covers Pomelo (BRL, pomelo_brl) and Rain (USD, rain_usd). It follows the cards contract, whose decisions of 18/11 make this a coordinated breaking change with no alias. codespar_issue, session.issue(), Python issue() and codespar issue are removed, and the bumps are breaking under the repo's 0.x rule (a minor bump is breaking in 0.x). The shapes are the ones the enterprise implementation answers.

Draft. Do not merge, tag or publish. A v* tag publishes to npm, and the release is coordinated with enterprise and web after Fabiano's OK.

What changed

@codespar/types 0.12.0

CARD_INPUT / CARD_DEFINITION (codespar_card) is in SHARED_META_TOOL_DEFINITIONS, so an agent is shown a single card tool.

Field Values
action issue | get | list | freeze | unfreeze | cancel
currency BRL | USD
provider pomelo | rain
mandate_id, consumer_id, idempotency_key
holder_consumer_id a company's pomelo_brl card only, required there
holder object: the Pomelo cardholder identity, pomelo_brl only; Rain refuses it
card_id
issuer pomelo | rain
reason client_request | lost | stolen | broken | upgrade

required is ["action"]. The server enforces the fields that are required on issue.

Session.card(args: CardArgs): Promise<CardResult>:

  • CardArgs = CardIssueArgs | CardGetArgs | CardListArgs | CardControlArgs.
  • CardResult narrows on state:
    • issued: { issue_request_id, issuer, program, selection, card: CardView, authorization_id, authorization_active }.
      • CardView has network: visa | mastercard | null.
      • Rain cards carry funding: { source: "wallet", currency: "BRL" }: the account's CodeSpar BRL wallet, priced in BRL at authorization.
      • Pomelo cards carry payment_token: ready | pending | not_configured.
      • Programs carry settlement: { asset: "USDC", by: "codespar" }, a program fact and never what a card spends.
    • pending_human: pending_action { id, kind, actor: holder | company_signatory | org_admin, url }.
    • processing and uncertain: retry_after_seconds; uncertain also has note and issuer_code.
    • refused.
    • No state: a card view (get and the controls) or { cards } (list).
  • A definitive issuer failure is never a state. It is a refusal: card_issue_refused, or card_issue_request_failed with failure_code and issue_request_id on a later call with the same key.
  • Refusal codes also include card_oauth_not_bound, card_holder_not_eligible, card_control_failed and card_control_uncertain (read the card again).
  • holder_consumer_id on issue: required for a company's pomelo_brl card.
  • Freeze, unfreeze and cancel work on both programs, as each card's available_actions allows. Cancel is permanent.
  • Readiness: mode (automated | person); the kinds issuer_capability_pending and verify_company_representative; missing_fields on complete_holder_profile.
  • Also added: CardReadiness / CardProgramReadiness / CardRequirement (GET /v1/cards/readiness).

Tests pin:

  • the §6 property list, the nested holder keys and the reason enum;
  • the enums against the TS unions;
  • codespar_issue absent from the shared surface.

@codespar/sdk 0.17.0

session.card(args) calls codespar_card.

  • On issue, a missing idempotency_key is refused before anything is sent.
  • A refusal with a stable code is returned as CardRefusal, not thrown. Three shapes are read:
    • enterprise's { error: { code, message, details }, http_status } inside the tool result (the body's http_status is used);
    • the flat { error, code, details };
    • a non-2xx body.
  • An issue answer in any state other than issued, pending_human, processing or uncertain throws. A flat card view with no state also throws.
  • The docs and messages say that processing and uncertain resolve on the same key and never on a new one (§8.3).
  • cs.cards.readiness() → GET /v1/cards/readiness.
  • spec:refresh --from-file <dir>/<ent-sha>/openapi-candidate.json (§8.6) records source: "candidate:<sha>/openapi-candidate.json". A new mode, assert-served, fails on a candidate snapshot, and publish.yml runs it before publishing.

@codespar/cli 0.23.0

New commands:

codespar card issue --currency --mandate-id --consumer-id --idempotency-key [--provider] [--holder-consumer-id] [--holder <json>]
codespar card get <card-id>
codespar card list [--issuer] [--mandate-id] [--consumer-id]
codespar card freeze|unfreeze|cancel <card-id> [--reason]
codespar card readiness
  • -i / -f take JSON, and flags win over it. The vocabularies come from the published definition.
  • Output shows id, issuer, program, currency, status (with the issuer's raw status) and available actions.
  • Exit codes:
    • A refusal exits 1, definitive issuer failures included. The api error document carries code, status and the whole refusal as body.
    • pending_human, processing and uncertain exit 0.
    • processing says to run it again with the same --idempotency-key in N s, never a new key.
    • uncertain says the card MAY exist, that it reconciles on the SAME --idempotency-key, and "Do not use a new key".
  • surface.ts: the cards REST-family exception keeps its date. Its wording now points to codespar card ….

@codespar/mcp 0.6.0

Copy only. The README and package description now say spend cards, BRL on Pomelo and USD on Rain. Discovery relays the hosted catalog, which lists codespar_card only; a call to codespar_issue is an unknown tool. It accepts sdk ^0.17.0.

Python codespar 0.17.0

In parity with the SDK, async and sync:

  • card(CardArgs(...)) returns CardIssued | CardPendingHuman | CardProcessing | CardUncertain | CardView | CardList | CardRefusal.
  • cs.cards.readiness().
  • issue(), IssueArgs, IssueResult and IssueAction are removed.

READMEs

The root table, the CLI table, the SDK README and the Python README.

Breaking: migration

There is no alias. codespar_issue, session.issue(), Python issue(), IssueArgs / IssueResult and codespar issue are removed. A call to codespar_issue reaches the server as an unknown tool.

Before Now
session.issue({ action: "card-virtual", cardholder_id, program_id }) session.card({ action: "issue", currency, mandate_id, consumer_id, idempotency_key, provider? })
session.issue({ action: "card-get", card_id }) session.card({ action: "get", card_id })
session.issue({ action: "card-control", card_id, control }) session.card({ action: "freeze" | "unfreeze" | "cancel", card_id, reason? })
Python session.issue(IssueArgs(...)) session.card(CardArgs(...))
codespar issue -i '<json>' codespar card issue|get|list|freeze|unfreeze|cancel
IssueArgs / IssueResult / ISSUE_DEFINITION CardArgs / CardResult / CARD_DEFINITION

Session implementers (the OSS runtime, users of the managed-agents adapter) replace issue() with card().

Version bumps (by hand; a minor bump is breaking in 0.x)

package from to
@codespar/types 0.11.7 0.12.0, breaking (scenario manifest follows)
@codespar/sdk 0.16.30 0.17.0, breaking (dep @codespar/types ^0.12.0)
@codespar/cli 0.22.7 0.23.0, breaking (dep @codespar/sdk ^0.17.0)
@codespar/mcp 0.5.20 0.6.0, breaking (dep/peer … || ^0.17.0)
codespar (PyPI) 0.16.2 0.17.0, breaking
autogen, camel, crewai, google-genai, letta, llama-index, mastra 0.4.6 0.4.7
claude 0.4.8 0.4.9
hermes 0.4.5 0.4.6
langchain 0.5.2 0.5.3
openai, vercel 0.4.7 0.4.8
@codespar/api-types 0.6.0 unchanged (hand-written; nothing in it moved)

The adapter patch bumps follow from the sdk minor. Their peer ranges stopped at ^0.16.0, and a peer range is packed content, so the drift guard requires the bump. None of them calls the card method, so widening their peer range to ^0.17.0 is safe and a patch bump is enough. Their test stubs change from issue() to card(). package-lock.json is synced by hand, workspace versions and ranges only, and the CI lock-file drift check passes.

Generated OpenAPI: from final enterprise candidate f6fd2931f208115d26892f24b9f5562547b32bcb

packages/core/openapi-snapshot.json and src/generated/* are regenerated with spec:refresh --from-file <candidate>/f6fd2931f208115d26892f24b9f5562547b32bcb/openapi-candidate.json. The candidate document's sha256 is 6f75bed7777b300697209af6c7094bda9bd7ed8f9562f3ee702295e99c386a8e, and the snapshot is sealed as 3dfc154cf3a5…. The snapshot records source: "candidate:f6fd2931f208115d26892f24b9f5562547b32bcb/openapi-candidate.json". Its OpenAPI is byte-identical to the earlier candidate 05f75845c: the final head changed only agent-facing catalog prose. Moving to it changed only source and fetched_at in the snapshot and in the two generated headers. The publish workflow's assert-served step refuses this source, so publish day refreshes from the served document first. The web docs are generated from the same candidate.

Operation diff against main's snapshot (390 → 399 operations):

  • Added (11):
    • GET /v1/cards/programs, GET /v1/cards/readiness;
    • POST /v1/cards/{id}/freeze|unfreeze|cancel;
    • GET|PUT /v1/cards/holder-profiles/{consumer_id};
    • GET /v1/integrations/card-issuing;
    • GET /.well-known/oauth-protected-resource/mcp, GET /oauth/pending/{handle}, POST /oauth/pending/{handle}/decide.
  • Removed (2): GET /v1/issuer/cards/{id}, POST /v1/issuer/cards. These are the old Pomelo-only routes.
  • Changed (16):
    • GET|POST /v1/cards, GET /v1/cards/{id};
    • the OAuth discovery and authorize/token operations;
    • POST /v1/webhook-endpoints, POST /v1/triggers;
    • GET /v1/account/balances;
    • the four /v1/ofb/sweeping/consents operations;
    • POST /v1/shop/agent/research.
  • Generated files: openapi-snapshot.json, src/generated/openapi.ts and src/generated/operations.ts, together +9,825/−5,366 lines.

The hand-written card types in @codespar/types (CardFunding, CardProgramSettlement, CardPaymentToken, the card view's vocabularies, the readiness mode and kinds) are pinned to the types generated from this document by packages/core/src/__tests__/card-wire.test.ts, which tsc checks. A change on either side fails the typecheck.

The CLI derives a new group from it, codespar integrations card-issuing (GET /v1/integrations/card-issuing). The coverage gate requires a command or a written exception for every served family, and a derived command is the rule.

Publish-day sequence (all after Fabiano's OK, none of it in this PR)

The release is one coordinated publish, never partial:

  1. An isolated Test environment (deployed by Fabiano) serves the final enterprise candidate head, and the acceptance runs there.
  2. Enterprise production deploy.
  3. Here, npm run spec:refresh against the served document. This replaces the candidate snapshot. Until it runs, the publish workflow's assert-served step refuses to publish.
  4. The v* tag. publish.yml runs build, test, the drift guard and assert-served, then publishes the packages whose versions are not yet on the registry.
  5. Python: the publish-python.yml dispatch, or a python-v0.17.0 release.
  6. The web merge.

Contract points confirmed by enterprise (18/11)

  • Input: the schema with holder (optional, Pomelo only; Rain answers 400 invalid_body) and reason as an enum. required: ["action"].
  • Card view and programs: as listed above (funding, settlement, payment_token).
  • Answers:
    • list is { cards }.
    • Issued nests the card and adds authorization_id / authorization_active.
    • The non-final states are pending_human, processing and uncertain, and pending_action appears only on pending_human.
    • There is no failed issue state.
  • Refusals: { error: { code, message, details }, http_status }. available_programs items are { program, issuer, currency }.
  • No alias: codespar_issue is absent from discovery and answers as an unknown tool.

Still assumed

  1. The readiness body is exactly §9. The clients validate no more than that programs is an array (Python).
  2. GET /v1/cards/{cir_id} is not reachable through codespar_card. Its failed and received states are REST-only and are not modelled in CardResult.

Open decision: where the Pomelo holder identity comes from when the caller does not send it. Until that is decided, a Pomelo issue without holder answers pending_human / complete_holder_profile. API, SDK, CLI (--holder <json>) and MCP callers can send it.

Tests

Head 0191503a55b05601743c39b87764bb550356bd51, generated from candidate 05f75845c (303dd8f4c737145d5751f623a136bfad4916368d then re-points the snapshot source to the final f6fd2931f, with the same document. Its CI is the same: ci passes in run 44454844939, every other job passes, and spec-freshness fails as expected in run 44454844974):

  • CI ci (run 44454028852): pass.
    • npx turbo run build typecheck test: all tasks successful. This includes card-wire.test.ts under tsc.
    • The publish drift guard passes, and so do the lock-file and SDK-range checks.
    • The CLI process test runs the built binary: codespar card --help lists the seven subcommands, and codespar issue exits non-zero with "unknown command 'issue'".
  • CI hosted-runtime smoke / spec-freshness (run 44454028831): fails, as expected. The snapshot is the candidate's (3dfc154cf3a5, 399 operations). Production serves 53ddbefb5783 (393 operations). It clears on publish day, after the enterprise deploy and spec:refresh against the served document. assert-served blocks publishing before that.
  • Every other check passes: gitleaks, smoke, kit-templates and the eight validate-example-* jobs.
  • Local (heavy), same head:
    • turbo run build typecheck for types, sdk, cli and mcp: 8/8.
    • turbo run test: types 180/180, sdk 279/279, cli 366 passed and 5 skipped, mcp 52/52.
  • Python (local 3.12 venv): pytest -q gives 190 passed and 1 skipped. ruff check src/ tests/ is clean, and mypy src/codespar reports no issues.
  • codespar_issue is absent from the TS SDK, types, CLI, MCP and Python SDK sources, generated files included. The only hits are the tests that assert its absence.

Not run: the live LLM smoke (examples/* validate:live, CLAUDE.md step 5). It needs a real Anthropic key, and this work keeps credentials out of the run. The chat loop and the system prompt are unchanged.

🤖 Generated with Claude Code

fabianocruz and others added 8 commits November 18, 2026 01:10
…DK, CLI, MCP, Python)

One card contract across issuers (cards contract §1-§9): BRL on
pomelo_brl, USD on rain_usd.

- types 0.12.0: CARD_DEFINITION/CARD_INPUT (codespar_card) in the shared
  surface; CardArgs/CardResult with issued, pending_human, processing,
  uncertain, failed and refused; CardReadiness. ISSUE_DEFINITION,
  IssueArgs, IssueResult and Session.issue() stay as deprecated aliases.
- sdk 0.17.0: session.card(), cs.cards.readiness(); session.issue() is a
  deprecated wrapper over card() with the same validations; an old
  Pomelo-shaped call throws CardContractMigrationError before sending.
  spec:refresh --from-file for an enterprise candidate document, and an
  assert-served gate in the publish workflow.
- cli 0.23.0: codespar card issue|get|list|freeze|unfreeze|cancel|readiness;
  codespar issue deprecated over it.
- mcp 0.6.0: copy; python 0.17.0: card(), cards.readiness(), issue()
  deprecated. Adapters: sdk peer range accepts ^0.17.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… holder, reason enum, retry hints

A definitive issuer failure is a refusal (card_issue_refused, or
card_issue_request_failed with failure_code), never an issue state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… a new one

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Decision of 18/11 (cards contract §10.1): a coordinated breaking change.
Removed: ISSUE_DEFINITION, IssueArgs/IssueResult, Session.issue (types,
SDK, fake session), Python issue()/IssueArgs/IssueResult/IssueAction,
CLI `codespar issue`, the deprecation warnings and
CardContractMigrationError / card_contract_migration_required. Changelogs
carry a Breaking section with the migration table.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…didate ffa66ce78

spec:refresh --from-file <candidate>/ffa66ce789ab6284cab9f831ba73025f0a5afeae/openapi-candidate.json
(sha256 c93989a6…, 399 operations). The snapshot records
source "candidate:ffa66ce789ab…/openapi-candidate.json"; the publish
workflow's assert-served step refuses it until publish day refreshes
from the served document.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ssuing) from the candidate document

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fabianocruz fabianocruz changed the title feat: codespar_card for Pomelo and Rain, codespar_issue deprecated (SDK, CLI, MCP, Python; coordinated release) feat!: codespar_card for Pomelo and Rain, no alias; issue() and codespar issue removed (SDK, CLI, MCP, Python; coordinated 0.x release) Nov 19, 2026
fabianocruz and others added 4 commits November 18, 2026 23:51
…served

CardFunding is open (Record<string, unknown>) in TS and a plain dict in
Python; the CLI no longer prints a funding asset. The served contract
(generated types) is the only place its fields are stated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Snapshot + src/generated regenerated from candidate
  05f75845c051e7e8cba908547a9a2327cd1286e4 (sha256 6f75bed7…, 399 operations).
- CardFunding { source: "wallet", currency: "BRL" } and
  CardProgramSettlement { asset: "USDC", by: "codespar" } typed exactly,
  pinned to the generated schema by card-wire.test.ts; no loose Record.
- CardView.payment_token, network visa|mastercard; holder_consumer_id on
  issue (TS, Python, CLI --holder-consumer-id); readiness mode, kinds
  issuer_capability_pending / verify_company_representative,
  missing_fields; refusal codes card_control_failed / card_control_uncertain.
- Freeze/unfreeze/cancel on both programs in the codespar_card description
  and docs (cancel permanent).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…2931f

The OpenAPI document is byte-identical to 05f75845c (same sha256
3dfc154cf3a5 sealed in the snapshot); only source/fetched_at change in
the snapshot and the two generated headers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant