Repository navigation
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
Draft
fabianocruz wants to merge 12 commits into
fabianocruz wants to merge 12 commits into
Conversation
…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>
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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(), Pythonissue()andcodespar issueare 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/types0.12.0CARD_INPUT/CARD_DEFINITION(codespar_card) is inSHARED_META_TOOL_DEFINITIONS, so an agent is shown a single card tool.actionissue | get | list | freeze | unfreeze | cancelcurrencyprovidermandate_id,consumer_id,idempotency_keyholder_consumer_idholdercard_idissuerreasonrequiredis["action"]. The server enforces the fields that are required onissue.Session.card(args: CardArgs): Promise<CardResult>:CardArgs=CardIssueArgs | CardGetArgs | CardListArgs | CardControlArgs.CardResultnarrows onstate:issued:{ issue_request_id, issuer, program, selection, card: CardView, authorization_id, authorization_active }.CardViewhasnetwork: visa | mastercard | null.funding: { source: "wallet", currency: "BRL" }: the account's CodeSpar BRL wallet, priced in BRL at authorization.payment_token: ready | pending | not_configured.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 }.processinganduncertain:retry_after_seconds;uncertainalso hasnoteandissuer_code.refused.state: a card view (get and the controls) or{ cards }(list).card_issue_refused, orcard_issue_request_failedwithfailure_codeandissue_request_idon a later call with the same key.card_oauth_not_bound,card_holder_not_eligible,card_control_failedandcard_control_uncertain(read the card again).holder_consumer_idon issue: required for a company's pomelo_brl card.available_actionsallows. Cancel is permanent.mode(automated | person); the kindsissuer_capability_pendingandverify_company_representative;missing_fieldsoncomplete_holder_profile.CardReadiness/CardProgramReadiness/CardRequirement(GET /v1/cards/readiness).Tests pin:
holderkeys and thereasonenum;codespar_issueabsent from the shared surface.@codespar/sdk0.17.0session.card(args)callscodespar_card.issue, a missingidempotency_keyis refused before anything is sent.CardRefusal, not thrown. Three shapes are read:{ error: { code, message, details }, http_status }inside the tool result (the body'shttp_statusis used);{ error, code, details };issued,pending_human,processingoruncertainthrows. A flat card view with no state also throws.cs.cards.readiness()→GET /v1/cards/readiness.spec:refresh --from-file <dir>/<ent-sha>/openapi-candidate.json(§8.6) recordssource: "candidate:<sha>/openapi-candidate.json". A new mode,assert-served, fails on a candidate snapshot, andpublish.ymlruns it before publishing.@codespar/cli0.23.0New commands:
-i/-ftake JSON, and flags win over it. The vocabularies come from the published definition.apierror document carriescode,statusand the whole refusal asbody.pending_human,processinganduncertainexit 0.processingsays to run it again with the same--idempotency-keyin N s, never a new key.uncertainsays the card MAY exist, that it reconciles on the SAME--idempotency-key, and "Do not use a new key".surface.ts: thecardsREST-family exception keeps its date. Its wording now points tocodespar card ….@codespar/mcp0.6.0Copy 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_cardonly; a call tocodespar_issueis an unknown tool. It accepts sdk^0.17.0.Python
codespar0.17.0In parity with the SDK, async and sync:
card(CardArgs(...))returnsCardIssued | CardPendingHuman | CardProcessing | CardUncertain | CardView | CardList | CardRefusal.cs.cards.readiness().issue(),IssueArgs,IssueResultandIssueActionare 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(), Pythonissue(),IssueArgs/IssueResultandcodespar issueare removed. A call tocodespar_issuereaches the server as an unknown tool.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? })session.issue(IssueArgs(...))session.card(CardArgs(...))codespar issue -i '<json>'codespar card issue|get|list|freeze|unfreeze|cancelIssueArgs/IssueResult/ISSUE_DEFINITIONCardArgs/CardResult/CARD_DEFINITIONSessionimplementers (the OSS runtime, users of the managed-agents adapter) replaceissue()withcard().Version bumps (by hand; a minor bump is breaking in 0.x)
@codespar/types ^0.12.0)@codespar/sdk ^0.17.0)… || ^0.17.0)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.0is safe and a patch bump is enough. Their test stubs change fromissue()tocard().package-lock.jsonis synced by hand, workspace versions and ranges only, and the CI lock-file drift check passes.Generated OpenAPI: from final enterprise candidate
f6fd2931f208115d26892f24b9f5562547b32bcbpackages/core/openapi-snapshot.jsonandsrc/generated/*are regenerated withspec:refresh --from-file <candidate>/f6fd2931f208115d26892f24b9f5562547b32bcb/openapi-candidate.json. The candidate document's sha256 is6f75bed7777b300697209af6c7094bda9bd7ed8f9562f3ee702295e99c386a8e, and the snapshot is sealed as3dfc154cf3a5…. The snapshot recordssource: "candidate:f6fd2931f208115d26892f24b9f5562547b32bcb/openapi-candidate.json". Its OpenAPI is byte-identical to the earlier candidate05f75845c: the final head changed only agent-facing catalog prose. Moving to it changed onlysourceandfetched_atin the snapshot and in the two generated headers. The publish workflow'sassert-servedstep 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):
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.GET /v1/issuer/cards/{id},POST /v1/issuer/cards. These are the old Pomelo-only routes.GET|POST /v1/cards,GET /v1/cards/{id};POST /v1/webhook-endpoints,POST /v1/triggers;GET /v1/account/balances;/v1/ofb/sweeping/consentsoperations;POST /v1/shop/agent/research.openapi-snapshot.json,src/generated/openapi.tsandsrc/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 readinessmodeand kinds) are pinned to the types generated from this document bypackages/core/src/__tests__/card-wire.test.ts, whichtscchecks. 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:
npm run spec:refreshagainst the served document. This replaces the candidate snapshot. Until it runs, the publish workflow'sassert-servedstep refuses to publish.v*tag.publish.ymlruns build, test, the drift guard andassert-served, then publishes the packages whose versions are not yet on the registry.publish-python.ymldispatch, or apython-v0.17.0release.Contract points confirmed by enterprise (18/11)
holder(optional, Pomelo only; Rain answers 400invalid_body) andreasonas an enum.required: ["action"].funding,settlement,payment_token).listis{ cards }.authorization_id/authorization_active.pending_human,processinganduncertain, andpending_actionappears only onpending_human.failedissue state.{ error: { code, message, details }, http_status }.available_programsitems are{ program, issuer, currency }.codespar_issueis absent from discovery and answers as an unknown tool.Still assumed
programsis an array (Python).GET /v1/cards/{cir_id}is not reachable throughcodespar_card. Itsfailedandreceivedstates are REST-only and are not modelled inCardResult.Open decision: where the Pomelo holder identity comes from when the caller does not send it. Until that is decided, a Pomelo issue without
holderanswerspending_human/complete_holder_profile. API, SDK, CLI (--holder <json>) and MCP callers can send it.Tests
Head
0191503a55b05601743c39b87764bb550356bd51, generated from candidate05f75845c(303dd8f4c737145d5751f623a136bfad4916368dthen re-points the snapshot source to the finalf6fd2931f, with the same document. Its CI is the same:cipasses in run 44454844939, every other job passes, and spec-freshness fails as expected in run 44454844974):ci(run 44454028852): pass.npx turbo run build typecheck test: all tasks successful. This includescard-wire.test.tsundertsc.codespar card --helplists the seven subcommands, andcodespar issueexits non-zero with "unknown command 'issue'".hosted-runtime smoke / spec-freshness(run 44454028831): fails, as expected. The snapshot is the candidate's (3dfc154cf3a5, 399 operations). Production serves53ddbefb5783(393 operations). It clears on publish day, after the enterprise deploy andspec:refreshagainst the served document.assert-servedblocks publishing before that.validate-example-*jobs.turbo run build typecheckfor 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.pytest -qgives 190 passed and 1 skipped.ruff check src/ tests/is clean, andmypy src/codesparreports no issues.codespar_issueis 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