Skip to content

[DO NOT MERGE before enterprise #2520 is deployed] feat(shop): data calls in the SDKs, the CLI and the MCP package - #244

Merged
fabianocruz merged 10 commits into
mainfrom
feat/shop-data-calls
Nov 19, 2026
Merged

fabianocruz merged 10 commits into
mainfrom
feat/shop-data-calls

Conversation

@fabianocruz

@fabianocruz fabianocruz commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

Shop data calls in the SDKs, the CLI and the MCP package.

A data call is a per-call data service found by a research of task_kind: "data_service". An API key drafts one from an offer and reads it. It never runs one: running it is the person's authorization. While the call waits for the person, the API answers next_action, a link to the call's card on the dashboard behind the person's own sign-in.

Status (2026-11-17)

  • Merged with main at 3373434 (zod 4, fix(security): zod 4 in api-types, sdk and langchain; GHSA-mrhx exception withdrawn (#214) #249). No code here uses zod, so the zod 4 move needed no source change.
  • Blocked by a technical dependency, not by G1: codespar-enterprise #2520 has to be deployed first. The client calls routes that only #2520 serves:
    • POST /v1/shop/agent/data-calls (agent_id, offer_id, idempotency_key; answers data_call, next_action and idempotent_replay);
    • GET /v1/shop/agent/data-calls/{id} (data_call, next_action);
    • POST /v1/shop/agent/data-calls/{id}/execute (always 403 person_required, with error.details.next_action);
    • on POST /v1/shop/agent/research, task_kind: "data_service", the data source and criteria.data_service { params, sku? }.
  • spec-freshness is red until then, and it says exactly that: the served document lacks those three operations and the research change. Nothing else differs. It is not a required check; ci is green.
  • The OpenAPI snapshot is the document served on 2026-11-17 (390 operations, G1 included) plus those four entries, taken from #2520 at 3bcd53dcb (buildOpenApiSpec). src/generated/ is regenerated from it (393 operations).
  • Versions are past what npm and main hold: @codespar/sdk 0.16.31, @codespar/cli 0.22.8 (SDK floor ^0.16.31), @codespar/mcp 0.5.21, @codespar/types 0.11.8. The Python changelog stays "Unreleased" (codespar 0.16.2 on PyPI). Nothing is published here. Publishing happens after merge and after #2520 is deployed, with spec:check green against the served document.

What changes

  • TypeScript:
    • cs.dataCalls and session.dataCalls: create, get ({ data_call, next_action }) and execute. A key's execute throws DataCallNeedsPersonError with nextAction.
    • dataCallOutcome(view) turns the four states into one word.
    • session.research.create takes taskKind and criteria.dataService.
    • The types live in @codespar/types.
  • Python: cs.research and cs.data_calls (async and sync), with data_call_outcome and next_action_of.
  • CLI:
    • Derived commands shop create-data-calls, shop get-data-calls and shop data-calls-execute.
    • These commands exit with the outcome: 0 confirmed, 10 pending, 20 refused, 30 failure, 40 uncertain.
    • A key's execute prints the person's link and exits 10.
    • Every other command keeps exit 1.
  • MCP package: codespar_shop_data_call_draft, codespar_shop_data_call_request_authorization (answers the person's link) and codespar_shop_data_call_status. No tool runs a call.
  • OpenAPI snapshot: the three data-call operations and the research body.

Tests

  • Remote CI on 0a31927: ci green (build, typecheck, lint, the unit suites, audit gate), plus gitleaks, kit-templates and the example validations.
  • Earlier head: core 261, cli 359, mcp 52, types 178, python 173; ruff, mypy, and turbo typecheck and lint.

🤖 Generated with Claude Code

fabianocruz and others added 8 commits November 7, 2026 19:18
The core side of Shop G3.1 (CONTRATO-G3 §7A item 2), over the enterprise
routes /v1/shop/agent/data-calls (key: draft, read; run is always
person_required) and the research's task_kind data_service.

- TS: cs.dataCalls / session.dataCalls (create, get, execute) and
  dataCallOutcome; session.research.create takes taskKind and
  criteria.dataService. Types in @codespar/types.
- Python: cs.research and cs.data_calls (async and sync) with
  data_call_outcome; the same names and states.
- CLI: derived shop create-data-calls / get-data-calls /
  data-calls-execute; these commands exit with the outcome (0 confirmed,
  10 pending, 20 refused, 30 failure, 40 uncertain); every other command
  keeps exit 1.
- MCP package: codespar_shop_data_call_draft / _status and the
  data_service research; no run tool.
- OpenAPI snapshot: the three data-call operations and the research body,
  from the enterprise routes (served once deployed).

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

The API's view follows lane B's state map: error.code names the provider's,
the mandate's or the Wallet's code. The snapshot picks up the draft route's
409 idempotency_key_reused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ected action and resumes by id

A key still never runs a data call; the API's person_required now carries
next_action (the call's card on the dashboard, behind the person's
sign-in, only the id in the url).

- TS: execute throws DataCallNeedsPersonError with nextAction;
  nextActionOfError; get answers { data_call, next_action } (create too).
- Python: next_action_of(ApiError); get answers the same read.
- CLI: a data-call command refused with the protected action exits 10
  (pending) and prints the url; create/get print it while pending.
- MCP package: codespar_shop_data_call_request_authorization answers the
  link for the person; still no tool runs a call.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Baaitxfwpx5yJ8xhz6nNhT
…0.11.8 for the data-call changes

npm versions are immutable, so changed packages carry a new version. No
release here: publishing is a tag push, done separately. The CLI's floor
on the SDK rises to the version that exports dataCallOutcome and
nextActionOfError.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Baaitxfwpx5yJ8xhz6nNhT
…e (0.11.8)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Baaitxfwpx5yJ8xhz6nNhT
…s) into feat/shop-data-calls

- Versions move past what main already holds or npm already has: sdk 0.16.31
  (main is 0.16.30, npm 0.16.29), cli 0.22.8 with the SDK floor at ^0.16.31
  (npm has 0.22.7); mcp 0.5.21 and types 0.11.8 stay (npm 0.5.20, 0.11.7).
- The OpenAPI snapshot is the document served today (2026-11-17, 390
  operations, G1 research body included) plus the three data-call operations
  and the research body's data_service, taken from enterprise #2520 at
  3bcd53dcb built with buildOpenApiSpec. Nothing else of #2520 differs from
  the served document except routes that #2520 is behind main on.
- src/generated/ regenerated from it (393 operations); the CLI's pinned
  commands keep both sides (data calls, then capabilities, in document order).
- No PR code uses zod; the zod 4 move needs no source change here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fabianocruz fabianocruz changed the title [DO NOT MERGE before the API routes are served] feat(shop): data calls in the SDKs, CLI and MCP package [DO NOT MERGE before enterprise #2520 is deployed] feat(shop): data calls in the SDKs, the CLI and the MCP package Nov 18, 2026
fabianocruz and others added 2 commits November 19, 2026 19:56
… v0.7 served)

`npm run sdk:spec:refresh` against https://api.codespar.dev/openapi.json after
enterprise #2535 (740313cae) was served: 397 operations (was 393). It adds the
offer image route of #2535 and the OAuth consent routes already in production
from other PRs, and picks up description-only changes in triggers and
webhook-endpoints. Generated files only; no hand-written code changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The refreshed snapshot adds GET /v1/shop/agent/offers/{id}/image/{n} (enterprise
#2535, key scope shop:purchases:read). The CLI derives it as `shop
offers-image`, after `shop data-calls-execute`. The OAuth routes the refresh
also brought are outside /v1 and derive no command. Pinned in the resource
commands test and named in the 0.22.8 changelog.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@fabianocruz
fabianocruz merged commit 790f787 into main Nov 19, 2026
12 checks passed
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