Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 15 additions & 17 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,24 +5,23 @@
The public, MIT-licensed SDK layer of CodeSpar: the TypeScript
`@codespar/sdk` npm package, the `codespar` Python package on PyPI,
and the framework adapters that wrap them (Vercel AI SDK, Claude Agent
SDK, OpenAI Agents SDK, MCP, CLI). Everything here is a client-side
adapter over the managed-tier backend at `api.codespar.dev`; the
backend lives in `codespar-enterprise` (private).
SDK, OpenAI Agents SDK, MCP, CLI). Everything here is a client over
the CodeSpar API (default endpoint `api.codespar.dev`); the same SDK
also runs against a self-hosted runtime — `baseUrl` is a configuration
change.

Post-pivot (April 2026), CodeSpar is **commerce infrastructure for AI
agents in Latin America**. These SDKs encode the wire contract that
lets developers ship commerce agents (Pix + NF-e + WhatsApp + PSPs)
without rebuilding the plumbing. See
[`VISION-codespar.md`](https://github.com/codespar/codespar-web/blob/main/docs/visions/VISION-codespar.md)
for the strategic context.
without rebuilding the plumbing. Read the project VISION for the
strategic context.

## Authoritative context

- **Strategy**: VISION-codespar.md (in `codespar-web`, Accepted
2026-04-19). Read it before making strategic decisions.
- **Wire contract**: every SDK method here maps 1:1 to a Fastify route
in `codespar-enterprise/packages/api/src/routes/`. Do not edit the
TS types without updating the Python package and backend together —
- **Strategy**: read the project VISION before making strategic
decisions.
- **Wire contract**: every SDK method here maps 1:1 to a backend route.
Keep the TS types, the Python package, and the backend in lockstep —
drift between SDKs is the loudest way to break trust.
- **Current SDK shape**: `CodeSpar.create(userId, { preset, servers,
manageConnections, projectId, metadata })` returns a `Session`
Expand All @@ -40,8 +39,8 @@ for the strategic context.
| **`codespar-core`** (this repo, public MIT) | SDK + adapters (TS + Python) |
| `codespar/codespar` (public, MIT) | Self-hostable runtime + channel adapters |
| `codespar/mcp-dev-latam` (public, MIT) | LATAM MCP server catalog |
| `codespar/codespar-enterprise` (private) | Managed-tier backend + governance |
| `codespar/codespar-web` (private) | Marketing site + dashboard UI |

A private managed tier serves the same session contract.

## Package Inventory (monorepo under `packages/`)

Expand All @@ -52,7 +51,8 @@ for the strategic context.
using PyPI trusted publishing (OIDC).
- **`types/`** → `@codespar/types`. Zero-dependency
`SessionBase`/`Session` interface hierarchy + conformance tests.
Shared contract between opensource runtime and managed-tier adapter.
Shared contract between the open-source runtime and the managed
backend.
- **`managed-agents-adapter/`** → `@codespar/managed-agents-adapter`.
Runs `SessionBase` tools against Anthropic Managed Agents sessions.
- **`vercel/` / `claude/` / `openai/`** — framework adapters.
Expand Down Expand Up @@ -102,8 +102,7 @@ schema in `packages/core/src/types.ts` validates on create.
- Public types in `packages/core/src/types.ts` are the source of truth
for wire shapes. Adding a new field requires matching updates in:
(1) TS `types.ts`, (2) Python `src/codespar/types.py`, (3) Zod
schema if the field is validated on client, (4) backend Fastify
route in `codespar-enterprise`.
schema if the field is validated on client, (4) the backend route.
- File names: kebab-case. Classes / types: PascalCase. Functions:
camelCase in TS, snake_case in Python.
- No comments explaining WHAT the code does; reserve for non-obvious
Expand Down Expand Up @@ -146,7 +145,6 @@ schema in `packages/core/src/types.ts` validates on create.

- `docs/tool-router.md` — Tool Router concept (public).
- `docs/custom-session-runtime.md` — `SessionBase` implementation guide (public).
- `docs/daniel-onboarding.md` (if present) — co-dev onboarding.
- `docs/repo-map.md` — cross-repo architecture.

## What NOT to do
Expand Down
2 changes: 1 addition & 1 deletion packages/api-types/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Shared REST wire contract for the CodeSpar managed-tier API at `api.codespar.dev`.

Every request body and response shape is defined once, as a Zod schema, and the matching TypeScript type is inferred from it. Both the backend (`codespar-enterprise`) and the dashboard (`codespar-web`) import from here — no more hand-rolled mirror types.
Every request body and response shape is defined once, as a Zod schema, and the matching TypeScript type is inferred from it. Both the backend and the dashboard import from here — no more hand-rolled mirror types.

## Why

Expand Down
Loading