codespar 0.10.0__tar.gz → 0.10.2__tar.gz

{codespar-0.10.0 → codespar-0.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespar
-Version: 0.10.0
+Version: 0.10.2
 Summary: Python SDK for CodeSpar — commerce infrastructure for AI agents in Latin America.
 Project-URL: Homepage, https://codespar.dev
 Project-URL: Documentation, https://docs.codespar.dev

{codespar-0.10.0 → codespar-0.10.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codespar"
-version = "0.10.0"
+version = "0.10.2"
 description = "Python SDK for CodeSpar — commerce infrastructure for AI agents in Latin America."
 readme = "README.md"
 requires-python = ">=3.10"

{codespar-0.10.0 → codespar-0.10.2}/src/codespar/__init__.py

@@ -58,6 +58,7 @@ from .tool_result_codes import (
     is_tool_not_mocked,
 )
 from .types import (
+    AgenticReceipt,
     AssistantTextEvent,
     AuthConfig,
     AuthResult,
@@ -78,6 +79,15 @@ from .types import (
     DoneEvent,
     ErrorEvent,
     HttpMethod,
+    IssueAction,
+    IssueArgs,
+    IssueResult,
+    LedgerAction,
+    LedgerArgs,
+    LedgerLeg,
+    LedgerReceiptResult,
+    LedgerReceiptsResult,
+    LedgerResult,
     ManageConnections,
     MockObject,
     MockValue,
@@ -87,6 +97,11 @@ from .types import (
     Preset,
     ProxyRequest,
     ProxyResult,
+    ReceiptDelivery,
+    ReceiptException,
+    ReceiptMandate,
+    ReceiptPayment,
+    ReceiptQuote,
     RequiredSecret,
     SearchStrategy,
     SendResult,
@@ -100,6 +115,18 @@ from .types import (
     ShipItem,
     ShipResult,
     ShipServiceLevel,
+    ShopAction,
+    ShopAddress,
+    ShopArgs,
+    ShopBuyer,
+    ShopCheckoutItem,
+    ShopCheckoutResult,
+    ShopCheckoutStatus,
+    ShopOffer,
+    ShopResult,
+    ShopSearchResult,
+    ShopStatusResult,
+    ShopVariant,
     StreamEvent,
     Tool,
     ToolCallRecord,
@@ -113,7 +140,7 @@ from .types import (
     WizardAction,
 )
 
-__version__ = "0.10.0"
+__version__ = "0.10.2"
 
 __all__ = [
     "APPROVAL_REQUIRED",
@@ -122,6 +149,8 @@ __all__ = [
     "POLICY_DENIED",
     "TOOL_NOT_MOCKED",
     "TOOL_RESULT_CODES",
+    # Agentic receipt (the Control Record)
+    "AgenticReceipt",
     "ApiError",
     "ApprovalRequiredOutput",
     "AssistantTextEvent",
@@ -155,6 +184,17 @@ __all__ = [
     "DoneEvent",
     "ErrorEvent",
     "HttpMethod",
+    # Issue (codespar_issue)
+    "IssueAction",
+    "IssueArgs",
+    "IssueResult",
+    # Ledger (codespar_ledger)
+    "LedgerAction",
+    "LedgerArgs",
+    "LedgerLeg",
+    "LedgerReceiptResult",
+    "LedgerReceiptsResult",
+    "LedgerResult",
     "ManageConnections",
     # Test-mode mocks
     "MockObject",
@@ -171,6 +211,11 @@ __all__ = [
     # Proxy
     "ProxyRequest",
     "ProxyResult",
+    "ReceiptDelivery",
+    "ReceiptException",
+    "ReceiptMandate",
+    "ReceiptPayment",
+    "ReceiptQuote",
     "RequiredSecret",
     "SearchStrategy",
     "SendResult",
@@ -188,6 +233,19 @@ __all__ = [
     "ShipItem",
     "ShipResult",
     "ShipServiceLevel",
+    # Shopping (codespar_shop)
+    "ShopAction",
+    "ShopAddress",
+    "ShopArgs",
+    "ShopBuyer",
+    "ShopCheckoutItem",
+    "ShopCheckoutResult",
+    "ShopCheckoutStatus",
+    "ShopOffer",
+    "ShopResult",
+    "ShopSearchResult",
+    "ShopStatusResult",
+    "ShopVariant",
     "StreamError",
     # Streaming events
     "StreamEvent",

{codespar-0.10.0 → codespar-0.10.2}/src/codespar/_async_client.py

@@ -11,6 +11,7 @@ having to write ``async def``.
 from __future__ import annotations
 
 import os
+import re
 from types import TracebackType
 
 import httpx
@@ -25,6 +26,11 @@ from ._presets import preset_to_servers
 from .errors import ApiError, ConfigError
 from .types import SessionConfig
 
+# Wire format for a project scope. Kept in sync with the TS SDK
+# (`PROJECT_ID_REGEX` in packages/core/src/types.ts) so both clients
+# reject the same project_id inputs.
+_PROJECT_ID_RE = re.compile(r"^prj_[A-Za-z0-9]{16}$")
+
 
 def _resolve_base_url(explicit: str | None) -> str:
     """Resolve the effective base URL.
@@ -67,6 +73,10 @@ class AsyncCodeSpar:
                 "api_key is required and must start with 'csk_'. "
                 "Get one from https://dashboard.codespar.dev."
             )
+        if project_id is not None and not _PROJECT_ID_RE.match(project_id):
+            raise ConfigError(
+                "project_id must match ^prj_[A-Za-z0-9]{16}$ (e.g. 'prj_...')."
+            )
         self._api_key = api_key
         self._base_url = _resolve_base_url(base_url).rstrip("/")
         self._project_id = project_id

{codespar-0.10.0 → codespar-0.10.2}/src/codespar/_async_session.py

@@ -35,6 +35,10 @@ from .types import (
     DiscoverToolMatch,
     DoneEvent,
     ErrorEvent,
+    IssueArgs,
+    IssueResult,
+    LedgerArgs,
+    LedgerResult,
     PaymentStatusEvent,
     PaymentStatusResult,
     ProxyRequest,
@@ -45,6 +49,13 @@ from .types import (
     SessionInfo,
     ShipArgs,
     ShipResult,
+    ShopArgs,
+    ShopCheckoutResult,
+    ShopOffer,
+    ShopResult,
+    ShopSearchResult,
+    ShopStatusResult,
+    ShopVariant,
     StreamEvent,
     Tool,
     ToolCallRecord,
@@ -196,6 +207,91 @@ def _parse_ship_result(raw: dict[str, Any]) -> ShipResult:
     )
 
 
+def _parse_ledger_result(raw: dict[str, Any]) -> LedgerResult:
+    return LedgerResult(
+        id=raw.get("id"),
+        status=raw.get("status"),
+        account_id=raw.get("account_id"),
+        alias=raw.get("alias"),
+        balances=raw.get("balances"),
+        raw=raw.get("raw"),
+    )
+
+
+def _parse_issue_result(raw: dict[str, Any]) -> IssueResult:
+    return IssueResult(
+        id=raw.get("id"),
+        status=raw.get("status"),
+        card_type=raw.get("card_type"),
+        last_four=raw.get("last_four"),
+        cardholder_id=raw.get("cardholder_id"),
+        program_id=raw.get("program_id"),
+        raw=raw.get("raw"),
+    )
+
+
+def _parse_shop_variant(raw: dict[str, Any]) -> ShopVariant:
+    return ShopVariant(
+        sku_id=str(raw.get("sku_id", "")),
+        available=bool(raw.get("available", False)),
+        title=raw.get("title"),
+        price_minor=raw.get("price_minor"),
+        currency=raw.get("currency"),
+    )
+
+
+def _parse_shop_offer(raw: dict[str, Any]) -> ShopOffer:
+    variants_raw = raw.get("variants") or []
+    return ShopOffer(
+        product_id=str(raw.get("product_id", "")),
+        available=bool(raw.get("available", False)),
+        variants=[
+            _parse_shop_variant(v) for v in variants_raw if isinstance(v, dict)
+        ],
+        sku_id=raw.get("sku_id"),
+        title=raw.get("title"),
+        price_minor=raw.get("price_minor"),
+        currency=raw.get("currency"),
+        image=raw.get("image"),
+        url=raw.get("url"),
+    )
+
+
+def _parse_shop_result(raw: dict[str, Any], action: str) -> ShopResult:
+    """Map the wire payload to the action-correct dataclass.
+
+    The wire shape is discriminated by the call's ``action`` (search →
+    products, checkout → in_progress session, checkout_status → terminal
+    poll), mirroring the TS discriminated ``ShopResult`` union.
+    """
+    if action == "search":
+        products_raw = raw.get("products") or []
+        return ShopSearchResult(
+            rail=str(raw.get("rail", "")),
+            products=[
+                _parse_shop_offer(p)
+                for p in products_raw
+                if isinstance(p, dict)
+            ],
+        )
+    if action == "checkout":
+        return ShopCheckoutResult(
+            checkout_session_id=str(raw.get("checkout_session_id", "")),
+            status="in_progress",
+            message=raw.get("message"),
+        )
+    # checkout_status
+    return ShopStatusResult(
+        checkout_session_id=str(raw.get("checkout_session_id", "")),
+        status=raw.get("status", "in_progress"),
+        rail=raw.get("rail"),
+        total_minor=raw.get("total_minor"),
+        pix_copia_e_cola=raw.get("pix_copia_e_cola"),
+        order_status=raw.get("order_status"),
+        error=raw.get("error"),
+    )
+
+
 def _parse_stream_event(raw: dict[str, Any]) -> StreamEvent | None:
     """
     Normalize a raw SSE payload into a typed ``StreamEvent``.
@@ -521,6 +617,178 @@ class AsyncSession:
             raise ApiError("ship: malformed response", status=0, body=result.data)
         return _parse_ship_result(result.data)
 
+    async def ledger(self, args: LedgerArgs) -> LedgerResult:
+        """
+        Post a double-entry journal entry, read an account's balances,
+        or create an account on the tenant's self-hosted Lerian Midaz
+        ledger. Typed wrapper around ``execute("codespar_ledger", {...})``.
+
+        ``args.action`` is one of ``entry`` | ``balance`` | ``account``.
+        For ``entry``: asset + source + destination are required (source
+        debits must equal destination credits, same asset). For
+        ``balance``: ``account`` (id) is required. For ``account``:
+        ``asset`` is required. Amounts are in MINOR units (cents). The
+        connection (base_url + org_id + ledger_id) is operator-seeded.
+        """
+        params: dict[str, Any] = {"action": args.action}
+        if args.asset is not None:
+            params["asset"] = args.asset
+        if args.scale is not None:
+            params["scale"] = args.scale
+        if args.source is not None:
+            params["source"] = [
+                {"account": leg.account, "amount": leg.amount}
+                for leg in args.source
+            ]
+        if args.destination is not None:
+            params["destination"] = [
+                {"account": leg.account, "amount": leg.amount}
+                for leg in args.destination
+            ]
+        if args.description is not None:
+            params["description"] = args.description
+        if args.account is not None:
+            params["account"] = args.account
+        if args.alias is not None:
+            params["alias"] = args.alias
+        if args.name is not None:
+            params["name"] = args.name
+        if args.type is not None:
+            params["type"] = args.type
+        if args.metadata is not None:
+            params["metadata"] = args.metadata
+        result = await self.execute("codespar_ledger", params)
+        if not result.success:
+            raise ApiError(
+                f"ledger failed: {result.error or 'unknown'}",
+                status=0,
+                body=result.error,
+            )
+        if not isinstance(result.data, dict):
+            raise ApiError("ledger: malformed response", status=0, body=result.data)
+        return _parse_ledger_result(result.data)
+
+    async def issue(self, args: IssueArgs) -> IssueResult:
+        """
+        Issue a virtual/physical card, control (freeze/unfreeze/cancel)
+        one, or read its status on the tenant's Pomelo card-issuing
+        program. Typed wrapper around ``execute("codespar_issue", {...})``.
+
+        ``args.action`` is one of ``card-virtual`` | ``card-physical`` |
+        ``card-control`` | ``card-get``. cardholder_id + program_id are
+        required to issue; card_id is required for control + get;
+        card-physical needs shipping_address.
+        """
+        params: dict[str, Any] = {"action": args.action}
+        if args.cardholder_id is not None:
+            params["cardholder_id"] = args.cardholder_id
+        if args.program_id is not None:
+            params["program_id"] = args.program_id
+        if args.card_id is not None:
+            params["card_id"] = args.card_id
+        if args.control is not None:
+            params["control"] = args.control
+        if args.reason is not None:
+            params["reason"] = args.reason
+        if args.shipping_address is not None:
+            params["shipping_address"] = args.shipping_address
+        if args.metadata is not None:
+            params["metadata"] = args.metadata
+        result = await self.execute("codespar_issue", params)
+        if not result.success:
+            raise ApiError(
+                f"issue failed: {result.error or 'unknown'}",
+                status=0,
+                body=result.error,
+            )
+        if not isinstance(result.data, dict):
+            raise ApiError("issue: malformed response", status=0, body=result.data)
+        return _parse_issue_result(result.data)
+
+    async def shop(self, args: ShopArgs) -> ShopResult:
+        """
+        Buy-side shopping: catalog search → async checkout → Pix mint.
+        Typed wrapper around ``execute("codespar_shop", {...})``. The
+        result type is action-correct: ``search`` → ``ShopSearchResult``,
+        ``checkout`` → ``ShopCheckoutResult``, ``checkout_status`` →
+        ``ShopStatusResult`` (version-locked to the TS discriminated
+        ``ShopResult`` union).
+
+        Checkout is async: ``action="checkout"`` returns
+        ``{checkout_session_id, status:"in_progress"}``; poll
+        ``action="checkout_status"`` until ``ready_for_payment`` (carries
+        ``pix_copia_e_cola``) or ``canceled`` (carries ``error``). Settle
+        the returned Pix via a separate payment tool — settlement and
+        governance are out of this contract.
+
+        Requires a runtime that implements the ``codespar_shop``
+        meta-tool; a self-hosted OSS runtime with no registered
+        implementation returns "Tool not registered".
+        """
+        params: dict[str, Any] = {"action": args.action}
+        if args.action == "search":
+            if args.query is not None:
+                params["query"] = args.query
+            if args.limit is not None:
+                params["limit"] = args.limit
+            if args.merchant is not None:
+                params["merchant"] = args.merchant
+        elif args.action == "checkout":
+            if args.merchant is not None:
+                params["merchant"] = args.merchant
+            if args.items is not None:
+                params["items"] = [
+                    {
+                        "variant_id": it.variant_id,
+                        **(
+                            {"quantity": it.quantity}
+                            if it.quantity is not None
+                            else {}
+                        ),
+                        **({"seller": it.seller} if it.seller else {}),
+                    }
+                    for it in args.items
+                ]
+            if args.url is not None:
+                params["url"] = args.url
+            if args.consumer_id is not None:
+                params["consumer_id"] = args.consumer_id
+            if args.buyer is not None:
+                params["buyer"] = {
+                    **({"name": args.buyer.name} if args.buyer.name else {}),
+                    **({"email": args.buyer.email} if args.buyer.email else {}),
+                    **({"cpf": args.buyer.cpf} if args.buyer.cpf else {}),
+                    **({"phone": args.buyer.phone} if args.buyer.phone else {}),
+                }
+            if args.address is not None:
+                a = args.address
+                params["address"] = {
+                    "cep": a.cep,
+                    **({"street": a.street} if a.street else {}),
+                    **({"number": a.number} if a.number else {}),
+                    **({"complement": a.complement} if a.complement else {}),
+                    **(
+                        {"neighborhood": a.neighborhood}
+                        if a.neighborhood
+                        else {}
+                    ),
+                    **({"city": a.city} if a.city else {}),
+                    **({"state": a.state} if a.state else {}),
+                }
+        else:  # checkout_status
+            if args.checkout_session_id is not None:
+                params["checkout_session_id"] = args.checkout_session_id
+        result = await self.execute("codespar_shop", params)
+        if not result.success:
+            raise ApiError(
+                f"shop failed: {result.error or 'unknown'}",
+                status=0,
+                body=result.error,
+            )
+        if not isinstance(result.data, dict):
+            raise ApiError("shop: malformed response", status=0, body=result.data)
+        return _parse_shop_result(result.data, args.action)
+
     async def verification_status(
         self, tool_call_id: str
     ) -> VerificationStatusResult:

{codespar-0.10.0 → codespar-0.10.2}/src/codespar/_sync_client.py

@@ -31,6 +31,10 @@ from .types import (
     ConnectionWizardResult,
     DiscoverOptions,
     DiscoverResult,
+    IssueArgs,
+    IssueResult,
+    LedgerArgs,
+    LedgerResult,
     PaymentStatusResult,
     ProxyRequest,
     ProxyResult,
@@ -40,6 +44,8 @@ from .types import (
     SessionInfo,
     ShipArgs,
     ShipResult,
+    ShopArgs,
+    ShopResult,
     StreamEvent,
     Tool,
     ToolResult,
@@ -173,6 +179,18 @@ class Session:
         """Sync wrapper around ``AsyncSession.ship``. See that for docs."""
         return self._runner.run(self._async.ship(args))
 
+    def ledger(self, args: LedgerArgs) -> LedgerResult:
+        """Sync wrapper around ``AsyncSession.ledger``. See that for docs."""
+        return self._runner.run(self._async.ledger(args))
+
+    def issue(self, args: IssueArgs) -> IssueResult:
+        """Sync wrapper around ``AsyncSession.issue``. See that for docs."""
+        return self._runner.run(self._async.issue(args))
+
+    def shop(self, args: ShopArgs) -> ShopResult:
+        """Sync wrapper around ``AsyncSession.shop``. See that for docs."""
+        return self._runner.run(self._async.shop(args))
+
     def proxy_execute(self, request: ProxyRequest) -> ProxyResult:
         return self._runner.run(self._async.proxy_execute(request))
 

{codespar-0.10.0 → codespar-0.10.2}/src/codespar/types.py

@@ -459,6 +459,329 @@ class ShipResult:
     raw: Any = None
 
 
+# ── codespar_ledger wire shape ─────────────────────────────────────
+
+
+LedgerAction = Literal["entry", "balance", "account", "receipt", "receipts"]
+
+
+@dataclass(slots=True)
+class LedgerLeg:
+    """One side of a journal entry. ``account`` is a Midaz account alias
+    (e.g. ``@wallet/user_123``); ``amount`` is in minor units (cents)."""
+
+    account: str
+    amount: int
+
+
+@dataclass(slots=True)
+class LedgerArgs:
+    """Input shape for ``Session.ledger``.
+
+    Three actions over a tenant's self-hosted double-entry ledger
+    (Lerian Midaz). Mirrors the backend's MetaLedgerArgs so the wire
+    payload matches byte-for-byte. The connection (base_url + org_id +
+    ledger_id) is operator-seeded, never passed by the agent. Amounts
+    are in MINOR units (cents).
+      - ``entry``    Post an n:n journal transaction (source debits must
+                     equal destination credits, same asset)
+      - ``balance``  Read an account's balances
+      - ``account``  Create an account for an asset
+    """
+
+    action: LedgerAction
+    asset: str | None = None
+    scale: int | None = None
+    source: list[LedgerLeg] | None = None
+    destination: list[LedgerLeg] | None = None
+    description: str | None = None
+    account: str | None = None
+    alias: str | None = None
+    name: str | None = None
+    type: str | None = None
+    receipt_id: str | None = None
+    consumer_id: str | None = None
+    limit: int | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@dataclass(slots=True)
+class LedgerResult:
+    id: str | None = None
+    status: str | None = None
+    account_id: str | None = None
+    alias: str | None = None
+    balances: Any = None
+    raw: Any = None
+
+
+# ── Agentic receipt (the Control Record) ───────────────────────────
+
+
+@dataclass(slots=True)
+class ReceiptException:
+    """A settle-time policy divergence recorded on a receipt (OBSERVE mode) —
+    e.g. the settled amount/payee diverging from the bound quote."""
+
+    code: str
+    detail: str
+    at: str
+
+
+@dataclass(slots=True)
+class ReceiptMandate:
+    id: str
+    nonce: str
+    scope: str
+    currency: str
+    sig: str
+
+
+@dataclass(slots=True)
+class ReceiptQuote:
+    seller: str | None = None
+    resource: str | None = None
+    price_minor: int | None = None
+    payee: str | None = None
+    session_id: str | None = None
+    sig: str | None = None
+    at: str | None = None
+
+
+@dataclass(slots=True)
+class ReceiptPayment:
+    rail: str
+    amount_minor: int
+    attempt_id: str
+    money_moved: bool
+    provider: str | None = None
+    tx_id: str | None = None
+    at: str | None = None
+
+
+@dataclass(slots=True)
+class ReceiptDelivery:
+    result: str | None = None
+    proof: str | None = None
+    kind: str | None = None
+    nfe_chave: str | None = None
+    at: str | None = None
+
+
+@dataclass(slots=True)
+class AgenticReceipt:
+    """The canonical agentic receipt — the Control Record of one spend.
+
+    Binds mandate -> quote -> payment -> delivery into a tamper-evident
+    chain (SHA-256 over the RFC 8785 canonical JSON of the records
+    present); ``receipt_sig`` is the consumer HMAC over ``chain``. The
+    structure is rail-agnostic; only the delivery proof artifact differs
+    (NF-e + Pix endToEndId for the fiscal path, the x402 resource
+    response for crypto). Returned by ``codespar_ledger`` action=receipt.
+    """
+
+    receipt_id: str
+    state: Literal["paid", "exception", "delivered", "voided"]
+    mandate: ReceiptMandate
+    payment: ReceiptPayment
+    chain: str
+    receipt_sig: str
+    quote: ReceiptQuote | None = None
+    delivery: ReceiptDelivery | None = None
+    exceptions: list[ReceiptException] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class LedgerReceiptResult:
+    """Result of ``codespar_ledger`` action=receipt. A missing receipt
+    returns ``found=False`` (not an error)."""
+
+    found: bool
+    receipt: AgenticReceipt | None = None
+    receipt_id: str | None = None
+
+
+@dataclass(slots=True)
+class LedgerReceiptsResult:
+    """Result of ``codespar_ledger`` action=receipts."""
+
+    receipts: list[AgenticReceipt] = field(default_factory=list)
+    count: int = 0
+
+
+# ── codespar_issue wire shape ──────────────────────────────────────
+
+
+IssueAction = Literal["card-virtual", "card-physical", "card-control", "card-get"]
+
+
+@dataclass(slots=True)
+class IssueArgs:
+    """Input shape for ``Session.issue`` (Pomelo card issuing).
+
+    Mirrors the backend's MetaIssueArgs. Asset-agnostic — the program
+    currency is set on the card program, not per call.
+      - ``card-virtual``   Issue a virtual card (active immediately)
+      - ``card-physical``  Issue a physical card (needs shipping_address)
+      - ``card-control``   Freeze / unfreeze / cancel an existing card
+      - ``card-get``       Read a card's status
+    """
+
+    action: IssueAction
+    cardholder_id: str | None = None
+    program_id: str | None = None
+    card_id: str | None = None
+    control: Literal["freeze", "unfreeze", "cancel"] | None = None
+    reason: str | None = None
+    shipping_address: dict[str, Any] | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@dataclass(slots=True)
+class IssueResult:
+    id: str | None = None
+    status: str | None = None
+    card_type: str | None = None
+    last_four: str | None = None
+    cardholder_id: str | None = None
+    program_id: str | None = None
+    raw: Any = None
+
+
+# ── codespar_shop wire shape ───────────────────────────────────────
+
+ShopAction = Literal["search", "checkout", "checkout_status"]
+ShopCheckoutStatus = Literal["in_progress", "ready_for_payment", "canceled"]
+
+
+@dataclass(slots=True)
+class ShopVariant:
+    """One buyable SKU under a ``ShopOffer``.
+
+    Note the field-name asymmetry the contract documents (not a bug):
+    pass this ``sku_id`` as the checkout item's ``variant_id``. The
+    product id is NOT buyable — only the SKU is.
+    """
+
+    sku_id: str
+    available: bool
+    title: str | None = None
+    price_minor: int | None = None  # integer minor units (centavos)
+    currency: str | None = None  # ISO-4217, default "BRL"
+
+
+@dataclass(slots=True)
+class ShopOffer:
+    """A flattened catalog offer returned by ``search``."""
+
+    product_id: str
+    available: bool
+    variants: list[ShopVariant]
+    sku_id: str | None = None
+    title: str | None = None
+    price_minor: int | None = None
+    currency: str | None = None
+    image: str | None = None
+    url: str | None = None
+
+
+@dataclass(slots=True)
+class ShopCheckoutItem:
+    """A line item for a VTEX-rail ``checkout``."""
+
+    variant_id: str  # pass ShopVariant.sku_id here
+    quantity: int | None = None  # defaults to 1 when omitted
+    seller: str | None = None  # VTEX marketplace sub-seller id
+
+
+@dataclass(slots=True)
+class ShopBuyer:
+    """Optional vaulted buyer profile, merged with the saved profile."""
+
+    name: str | None = None
+    email: str | None = None
+    cpf: str | None = None
+    phone: str | None = None
+
+
+@dataclass(slots=True)
+class ShopAddress:
+    """Optional vaulted delivery address; ``cep`` required when present."""
+
+    cep: str
+    street: str | None = None
+    number: str | None = None
+    complement: str | None = None
+    neighborhood: str | None = None
+    city: str | None = None
+    state: str | None = None
+
+
+@dataclass(slots=True)
+class ShopArgs:
+    """Input shape for ``Session.shop``.
+
+    The closed action set is ``search | checkout | checkout_status``
+    (default ``search``). Per-action field requirements:
+      - ``search``: ``query`` required; ``limit`` clamped 1..20.
+      - ``checkout``: ``items`` XOR ``url``, gated by rail (``items``
+        for VTEX, ``url`` for the Mercado Livre PDP path).
+      - ``checkout_status``: ``checkout_session_id`` required.
+
+    Mirrors the TS ``ShopArgs`` discriminated union as a single
+    dataclass; the ``shop()`` wrapper serializes only the fields the
+    given action uses, matching the TS facade's wire payload.
+    """
+
+    action: ShopAction
+    query: str | None = None
+    limit: int | None = None
+    merchant: str | None = None
+    items: list[ShopCheckoutItem] | None = None
+    url: str | None = None
+    consumer_id: str | None = None
+    buyer: ShopBuyer | None = None
+    address: ShopAddress | None = None
+    checkout_session_id: str | None = None
+
+
+@dataclass(slots=True)
+class ShopSearchResult:
+    """Result of ``search``. Zero results is ``products=[]``, not error."""
+
+    rail: str
+    products: list[ShopOffer]
+
+
+@dataclass(slots=True)
+class ShopCheckoutResult:
+    """Result of ``checkout`` — always async, status ``in_progress``."""
+
+    checkout_session_id: str
+    status: Literal["in_progress"]
+    message: str | None = None
+
+
+@dataclass(slots=True)
+class ShopStatusResult:
+    """Result of ``checkout_status``.
+
+    ``pix_copia_e_cola`` + ``total_minor`` are present only at
+    ``ready_for_payment``; ``error`` only at ``canceled``.
+    """
+
+    checkout_session_id: str
+    status: ShopCheckoutStatus
+    rail: str | None = None
+    total_minor: int | None = None
+    pix_copia_e_cola: str | None = None
+    order_status: str | None = None
+    error: str | None = None
+
+
+ShopResult = ShopSearchResult | ShopCheckoutResult | ShopStatusResult
+
+
 # ── /v1/tool-calls/:id/payment-status wire shape ───────────────────
 
 

codespar-0.10.2/tests/_fixtures/shop_canonical.json

@@ -0,0 +1,52 @@
+{
+  "search": {
+    "rail": "vtex",
+    "products": [
+      {
+        "product_id": "prod_1",
+        "sku_id": "sku_1",
+        "title": "Ração para gato 1kg",
+        "price_minor": 4990,
+        "currency": "BRL",
+        "image": "https://example.test/img/sku_1.jpg",
+        "url": "https://cobasi.test/p/sku_1",
+        "available": true,
+        "variants": [
+          {
+            "sku_id": "sku_1",
+            "title": "1kg",
+            "price_minor": 4990,
+            "currency": "BRL",
+            "available": true
+          }
+        ]
+      }
+    ]
+  },
+  "search_empty": {
+    "rail": "vtex",
+    "products": []
+  },
+  "checkout": {
+    "checkout_session_id": "cks_abc123",
+    "status": "in_progress",
+    "message": "checkout started"
+  },
+  "status_in_progress": {
+    "checkout_session_id": "cks_abc123",
+    "status": "in_progress"
+  },
+  "status_ready_for_payment": {
+    "checkout_session_id": "cks_abc123",
+    "status": "ready_for_payment",
+    "rail": "vtex",
+    "total_minor": 4990,
+    "pix_copia_e_cola": "00020126580014br.gov.bcb.pix0136cks-fixture5204000053039865802BR6304ABCD",
+    "order_status": "pending"
+  },
+  "status_canceled": {
+    "checkout_session_id": "cks_def456",
+    "status": "canceled",
+    "error": "browser_worker_checkout_failed"
+  }
+}

{codespar-0.10.0 → codespar-0.10.2}/tests/test_config.py

@@ -34,6 +34,16 @@ def test_async_client_stores_project_id() -> None:
     assert cs.project_id == "prj_0123456789abcdef"
 
 
+def test_async_client_rejects_bad_project_id_format() -> None:
+    with pytest.raises(ConfigError):
+        AsyncCodeSpar(api_key="csk_live_abc", project_id="not-a-project-id")
+
+
+def test_sync_client_rejects_bad_project_id_format() -> None:
+    with pytest.raises(ConfigError):
+        CodeSpar(api_key="csk_live_abc", project_id="prj_tooshort")
+
+
 def test_sync_client_requires_api_key() -> None:
     with pytest.raises(ConfigError):
         CodeSpar(api_key="")

{codespar-0.10.0 → codespar-0.10.2}/tests/test_session.py

@@ -87,14 +87,14 @@ async def test_session_level_project_id_wins(httpx_mock: HTTPXMock) -> None:
     )
 
     async with AsyncCodeSpar(
-        api_key="csk_test_x", project_id="prj_clientlevel000000"
+        api_key="csk_test_x", project_id="prj_clientlevel00000"
     ) as cs:
-        await cs.create("user_123", preset="brazilian", project_id="prj_sessionlevel00000")
+        await cs.create("user_123", preset="brazilian", project_id="prj_sessionlevel0000")
 
     request = httpx_mock.get_request()
     assert request is not None
     # session override wins
-    assert request.headers["x-codespar-project"] == "prj_sessionlevel00000"
+    assert request.headers["x-codespar-project"] == "prj_sessionlevel0000"
 
 
 async def test_send_returns_tool_calls(httpx_mock: HTTPXMock) -> None:

codespar-0.10.2/tests/test_shop.py

@@ -0,0 +1,212 @@
+"""
+codespar_shop Python parity tests.
+
+Two layers:
+  1. Round-trip: parse each canonical wire fixture
+     (tests/_fixtures/shop_canonical.json — mirrored from the TS
+     packages/types/src/testing/shop-fixtures.ts) into the dataclass
+     result and assert every field maps one-to-one. This is the
+     dict->dataclass parse-helper round-trip the contract requires
+     and the guard against TS<->Python wire drift.
+  2. Dispatch: drive ``session.shop(...)`` over a mocked backend and
+     assert the action-correct result type + the wire params the
+     facade sends.
+
+The fixtures are the same JSON the TS conformance fixtures encode, so
+both language surfaces are proven behaviorally identical for the same
+wire payload.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+from pytest_httpx import HTTPXMock
+
+from codespar import (
+    AsyncCodeSpar,
+    ShopArgs,
+    ShopCheckoutItem,
+    ShopCheckoutResult,
+    ShopSearchResult,
+    ShopStatusResult,
+)
+from codespar._async_session import _parse_shop_result
+
+FIXTURE_PATH = Path(__file__).parent / "_fixtures" / "shop_canonical.json"
+FIXTURES: dict[str, Any] = json.loads(FIXTURE_PATH.read_text(encoding="utf-8"))
+
+
+def test_search_fixture_round_trips() -> None:
+    result = _parse_shop_result(FIXTURES["search"], "search")
+    assert isinstance(result, ShopSearchResult)
+    assert result.rail == "vtex"
+    assert len(result.products) == 1
+    offer = result.products[0]
+    assert offer.product_id == "prod_1"
+    assert offer.sku_id == "sku_1"
+    assert offer.price_minor == 4990
+    assert offer.currency == "BRL"
+    assert offer.available is True
+    assert len(offer.variants) == 1
+    # The buyable SKU is on the variant — pass it as checkout variant_id.
+    assert offer.variants[0].sku_id == "sku_1"
+    assert offer.variants[0].available is True
+
+
+def test_empty_search_is_success_not_error() -> None:
+    result = _parse_shop_result(FIXTURES["search_empty"], "search")
+    assert isinstance(result, ShopSearchResult)
+    assert result.products == []
+
+
+def test_checkout_fixture_round_trips() -> None:
+    result = _parse_shop_result(FIXTURES["checkout"], "checkout")
+    assert isinstance(result, ShopCheckoutResult)
+    assert result.checkout_session_id == "cks_abc123"
+    assert result.status == "in_progress"
+    assert result.message == "checkout started"
+
+
+def test_status_ready_for_payment_exposes_typed_pix() -> None:
+    result = _parse_shop_result(
+        FIXTURES["status_ready_for_payment"], "checkout_status"
+    )
+    assert isinstance(result, ShopStatusResult)
+    assert result.status == "ready_for_payment"
+    assert result.total_minor == 4990
+    assert result.pix_copia_e_cola is not None
+    assert "br.gov.bcb.pix" in result.pix_copia_e_cola
+    assert result.order_status == "pending"
+    assert result.error is None
+
+
+def test_status_canceled_exposes_typed_error() -> None:
+    result = _parse_shop_result(
+        FIXTURES["status_canceled"], "checkout_status"
+    )
+    assert isinstance(result, ShopStatusResult)
+    assert result.status == "canceled"
+    assert result.error == "browser_worker_checkout_failed"
+    assert result.pix_copia_e_cola is None
+
+
+def _session_json(**overrides: Any) -> dict[str, Any]:
+    return {
+        "id": "ses_shop",
+        "org_id": "org_test",
+        "user_id": "consumer_123",
+        "servers": ["cobasi"],
+        "status": "active",
+        "created_at": "2026-04-21T12:00:00Z",
+        "closed_at": None,
+        **overrides,
+    }
+
+
+def _execute_response_json(data: Any) -> dict[str, Any]:
+    return {
+        "success": True,
+        "data": data,
+        "error": None,
+        "duration": 5,
+        "server": "_codespar",
+        "tool": "codespar_shop",
+    }
+
+
+@pytest.mark.asyncio
+async def test_shop_search_dispatch(httpx_mock: HTTPXMock) -> None:
+    httpx_mock.add_response(
+        url="https://api.codespar.dev/v1/sessions",
+        method="POST",
+        json=_session_json(),
+    )
+    httpx_mock.add_response(
+        url="https://api.codespar.dev/v1/sessions/ses_shop/execute",
+        method="POST",
+        json=_execute_response_json(FIXTURES["search"]),
+    )
+
+    async with AsyncCodeSpar(api_key="csk_test_x") as cs:
+        session = await cs.create("consumer_123", preset="brazilian")
+        result = await session.shop(
+            ShopArgs(action="search", query="ração para gato", merchant="cobasi", limit=10)
+        )
+        assert isinstance(result, ShopSearchResult)
+        assert result.products[0].variants[0].sku_id == "sku_1"
+
+    # The facade serialized only the search fields.
+    requests = httpx_mock.get_requests()
+    exec_req = next(r for r in requests if r.url.path.endswith("/execute"))
+    body = json.loads(exec_req.content)
+    assert body["tool"] == "codespar_shop"
+    assert body["input"] == {
+        "action": "search",
+        "query": "ração para gato",
+        "limit": 10,
+        "merchant": "cobasi",
+    }
+
+
+@pytest.mark.asyncio
+async def test_shop_checkout_serializes_items(httpx_mock: HTTPXMock) -> None:
+    httpx_mock.add_response(
+        url="https://api.codespar.dev/v1/sessions",
+        method="POST",
+        json=_session_json(),
+    )
+    httpx_mock.add_response(
+        url="https://api.codespar.dev/v1/sessions/ses_shop/execute",
+        method="POST",
+        json=_execute_response_json(FIXTURES["checkout"]),
+    )
+
+    async with AsyncCodeSpar(api_key="csk_test_x") as cs:
+        session = await cs.create("consumer_123", preset="brazilian")
+        result = await session.shop(
+            ShopArgs(
+                action="checkout",
+                merchant="cobasi",
+                items=[ShopCheckoutItem(variant_id="sku_1", quantity=1)],
+                consumer_id="consumer_123",
+            )
+        )
+        assert isinstance(result, ShopCheckoutResult)
+        assert result.status == "in_progress"
+
+    requests = httpx_mock.get_requests()
+    exec_req = next(r for r in requests if r.url.path.endswith("/execute"))
+    body = json.loads(exec_req.content)
+    assert body["input"]["action"] == "checkout"
+    assert body["input"]["items"] == [{"variant_id": "sku_1", "quantity": 1}]
+    assert body["input"]["consumer_id"] == "consumer_123"
+
+
+@pytest.mark.asyncio
+async def test_shop_failure_raises(httpx_mock: HTTPXMock) -> None:
+    httpx_mock.add_response(
+        url="https://api.codespar.dev/v1/sessions",
+        method="POST",
+        json=_session_json(),
+    )
+    httpx_mock.add_response(
+        url="https://api.codespar.dev/v1/sessions/ses_shop/execute",
+        method="POST",
+        json={
+            "success": False,
+            "data": None,
+            "error": "invalid_args",
+            "duration": 1,
+            "server": "_codespar",
+            "tool": "codespar_shop",
+        },
+    )
+
+    async with AsyncCodeSpar(api_key="csk_test_x") as cs:
+        session = await cs.create("consumer_123", preset="brazilian")
+        with pytest.raises(Exception, match="shop failed: invalid_args"):
+            await session.shop(ShopArgs(action="search", query="x"))