codespar 0.1.0__tar.gz → 0.3.0__tar.gz

{codespar-0.1.0 → codespar-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codespar
-Version: 0.1.0
+Version: 0.3.0
 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
@@ -179,6 +179,10 @@ This package mirrors [`@codespar/sdk`](https://www.npmjs.com/package/@codespar/s
 method-for-method. Same backend, same payloads, same preset names — pick
 the language that fits your stack without giving anything up.
 
+## Need more?
+
+Need governance, budget limits, and audit trails for agent payments? **[CodeSpar Enterprise](https://codespar.dev/enterprise)** adds policy engine, payment routing, and compliance templates on top of these MCP servers.
+
 ## Links
 
 - [Documentation](https://docs.codespar.dev)

{codespar-0.1.0 → codespar-0.3.0}/README.md

@@ -148,6 +148,10 @@ This package mirrors [`@codespar/sdk`](https://www.npmjs.com/package/@codespar/s
 method-for-method. Same backend, same payloads, same preset names — pick
 the language that fits your stack without giving anything up.
 
+## Need more?
+
+Need governance, budget limits, and audit trails for agent payments? **[CodeSpar Enterprise](https://codespar.dev/enterprise)** adds policy engine, payment routing, and compliance templates on top of these MCP servers.
+
 ## Links
 
 - [Documentation](https://docs.codespar.dev)

codespar-0.3.0/examples/README.md

@@ -0,0 +1,37 @@
+# codespar Python SDK — examples
+
+Runnable scripts demonstrating the CodeSpar Python SDK end-to-end.
+Each file is standalone — just `pip install codespar`, set
+`CODESPAR_API_KEY`, and run.
+
+## Setup
+
+```bash
+pip install codespar
+export CODESPAR_API_KEY="csk_live_..."  # get one at dashboard.codespar.dev
+```
+
+Optionally pin a specific project (staging, prod, etc.):
+
+```bash
+export CODESPAR_PROJECT_ID="prj_a1b2c3d4e5f6g7h8"
+```
+
+## Examples
+
+| File | What it does | SDK surface |
+|------|--------------|-------------|
+| [`ecommerce_checkout.py`](./ecommerce_checkout.py) | Full Complete Loop: checkout → NF-e → ship → notify via WhatsApp | `send_stream`, typed events |
+| [`pix_payment.py`](./pix_payment.py) | Create a Pix charge and notify the customer | `send`, `tool_calls` |
+| [`proxy_execute.py`](./proxy_execute.py) | Raw HTTP proxy to a provider API with server-side auth injection | `proxy_execute` |
+| [`connect_link.py`](./connect_link.py) | Generate an OAuth Connect Link for an end user | `authorize` |
+| [`async_basic.py`](./async_basic.py) | Same flow using `AsyncCodeSpar` for FastAPI / asyncio stacks | `AsyncCodeSpar` |
+
+## Running
+
+```bash
+python examples/ecommerce_checkout.py
+```
+
+All examples use `preset="brazilian"` by default. Change to
+`mexican` / `argentinian` / `colombian` to run the LatAm-wide stack.

codespar-0.3.0/examples/async_basic.py

@@ -0,0 +1,46 @@
+"""
+Same Pix flow as ``pix_payment.py``, but with ``AsyncCodeSpar`` —
+the canonical shape for FastAPI, LangChain, or anything already on
+asyncio. The SDK's async client is the primary implementation; the
+sync ``CodeSpar`` is a thin wrapper on top.
+
+Usage:
+    export CODESPAR_API_KEY="csk_live_..."
+    python examples/async_basic.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+from codespar import AsyncCodeSpar
+
+PROMPT = "Crie um Pix de R$200 e envie o QR code para +5511999887766."
+
+
+async def run() -> int:
+    api_key = os.environ.get("CODESPAR_API_KEY")
+    if not api_key:
+        print("error: set CODESPAR_API_KEY first", file=sys.stderr)
+        return 1
+
+    async with AsyncCodeSpar(api_key=api_key) as cs:
+        session = await cs.create("demo_user", preset="brazilian")
+        try:
+            async for event in session.send_stream(PROMPT):
+                if event.type == "assistant_text":
+                    print(event.content, end="", flush=True)
+                elif event.type == "tool_use":
+                    print(f"\n→ {event.name}")
+                elif event.type == "done":
+                    print(f"\n✓ done · {event.result.iterations} iterations")
+        finally:
+            await session.close()
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(run()))

codespar-0.3.0/examples/connect_link.py

@@ -0,0 +1,46 @@
+"""
+Connect Links example — generate the OAuth URL your end user opens
+to grant provider access. CodeSpar stores the tokens in the
+per-project vault once the user completes the flow, then forwards
+them back to ``redirect_uri`` with ``?status=connected`` appended.
+
+Usage:
+    export CODESPAR_API_KEY="csk_live_..."
+    python examples/connect_link.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from codespar import AuthConfig, CodeSpar
+
+
+def main() -> int:
+    api_key = os.environ.get("CODESPAR_API_KEY")
+    if not api_key:
+        print("error: set CODESPAR_API_KEY first", file=sys.stderr)
+        return 1
+
+    with CodeSpar(api_key=api_key) as cs:
+        session = cs.create("demo_user", servers=["stripe-acp"])
+        try:
+            link = session.authorize(
+                "stripe-acp",
+                AuthConfig(
+                    redirect_uri="https://your-app.example/connected",
+                ),
+            )
+            print("Open this URL to connect Stripe:")
+            print(f"  {link.authorize_url}")
+            print(f"\nLink token: {link.link_token}")
+            print(f"Expires at: {link.expires_at}")
+        finally:
+            session.close()
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codespar-0.3.0/examples/ecommerce_checkout.py

@@ -0,0 +1,73 @@
+"""
+End-to-end e-commerce checkout — the canonical Complete Loop demo.
+
+Drives a single natural-language turn through four tools:
+  codespar_checkout → codespar_invoice → codespar_ship → codespar_notify
+
+Exactly what the dashboard's Sandbox / E-Commerce Checkout runs, just
+from Python instead of the browser. Streams events so you can watch
+the agent progress through each step in real time.
+
+Usage:
+    export CODESPAR_API_KEY="csk_live_..."
+    python examples/ecommerce_checkout.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from codespar import CodeSpar
+
+PROMPT = (
+    "Quero comprar o Starter Kit por R$149,00. "
+    "Meu CEP é 01310-100. Pode processar tudo: "
+    "checkout via Stripe, NF-e via Nuvem Fiscal, "
+    "frete via Correios, e me avise pelo WhatsApp."
+)
+
+
+def main() -> int:
+    api_key = os.environ.get("CODESPAR_API_KEY")
+    if not api_key:
+        print("error: set CODESPAR_API_KEY first — see dashboard.codespar.dev", file=sys.stderr)
+        return 1
+
+    with CodeSpar(
+        api_key=api_key,
+        project_id=os.environ.get("CODESPAR_PROJECT_ID"),
+    ) as cs:
+        session = cs.create("demo_user", preset="brazilian")
+        try:
+            print(f"→ session {session.id}")
+            print(f"→ servers: {', '.join(session.servers)}\n")
+
+            for event in session.send_stream(PROMPT):
+                # Stream type is a discriminated union — pattern match
+                # on the event.type literal so mypy can narrow the
+                # attributes each branch touches.
+                if event.type == "assistant_text":
+                    print(event.content, end="", flush=True)
+                elif event.type == "tool_use":
+                    print(f"\n\n  → calling {event.name}")
+                elif event.type == "tool_result":
+                    tc = event.tool_call
+                    status = "ok" if tc.status == "success" else f"error ({tc.error_code})"
+                    print(f"    {status} · {tc.duration_ms}ms")
+                elif event.type == "done":
+                    tool_count = len(event.result.tool_calls)
+                    iterations = event.result.iterations
+                    print("\n\n✓ complete")
+                    print(f"  {tool_count} tools · {iterations} iterations")
+                elif event.type == "error":
+                    print(f"\n✗ error: {event.error}", file=sys.stderr)
+                    return 2
+        finally:
+            session.close()
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codespar-0.3.0/examples/pix_payment.py

@@ -0,0 +1,48 @@
+"""
+Minimal Pix example — create a charge, send the QR code via WhatsApp.
+
+Uses ``send`` (blocking) instead of ``send_stream`` because this flow
+is short enough that streaming would be overkill; you get the full
+transcript back in one call.
+
+Usage:
+    export CODESPAR_API_KEY="csk_live_..."
+    python examples/pix_payment.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from codespar import CodeSpar
+
+PROMPT = (
+    "Crie uma cobrança Pix de R$500,00 e envie o QR code "
+    "pelo WhatsApp para +5511999887766."
+)
+
+
+def main() -> int:
+    api_key = os.environ.get("CODESPAR_API_KEY")
+    if not api_key:
+        print("error: set CODESPAR_API_KEY first", file=sys.stderr)
+        return 1
+
+    with CodeSpar(api_key=api_key) as cs:
+        session = cs.create("demo_user", preset="brazilian")
+        try:
+            result = session.send(PROMPT)
+            print(result.message)
+            print(f"\n{len(result.tool_calls)} tools called over {result.iterations} iterations:")
+            for tc in result.tool_calls:
+                marker = "✓" if tc.status == "success" else "✗"
+                print(f"  {marker} {tc.tool_name} · {tc.server_id} · {tc.duration_ms}ms")
+        finally:
+            session.close()
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codespar-0.3.0/examples/proxy_execute.py

@@ -0,0 +1,53 @@
+"""
+Raw HTTP proxy example — bypass the agent loop and call a provider
+endpoint directly through CodeSpar's credential vault.
+
+CodeSpar injects the Stripe API key server-side; your code never
+sees it. Same pattern works for every connected server — swap
+``server="stripe-acp"`` for ``"asaas"``, ``"nuvem-fiscal"``, etc.
+
+Usage:
+    export CODESPAR_API_KEY="csk_live_..."
+    python examples/proxy_execute.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from codespar import CodeSpar, ProxyRequest
+
+
+def main() -> int:
+    api_key = os.environ.get("CODESPAR_API_KEY")
+    if not api_key:
+        print("error: set CODESPAR_API_KEY first", file=sys.stderr)
+        return 1
+
+    with CodeSpar(api_key=api_key) as cs:
+        session = cs.create("demo_user", servers=["stripe-acp"])
+        try:
+            response = session.proxy_execute(
+                ProxyRequest(
+                    server="stripe-acp",
+                    endpoint="/v1/charges",
+                    method="POST",
+                    body={
+                        "amount": 14900,  # R$149.00 in cents
+                        "currency": "brl",
+                        "description": "Starter Kit",
+                    },
+                )
+            )
+            print(f"HTTP {response.status} · {response.duration}ms")
+            print(json.dumps(response.data, indent=2, ensure_ascii=False))
+        finally:
+            session.close()
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{codespar-0.1.0 → codespar-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codespar"
-version = "0.1.0"
+version = "0.3.0"
 description = "Python SDK for CodeSpar — commerce infrastructure for AI agents in Latin America."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -47,6 +47,13 @@ Issues = "https://github.com/codespar/codespar/issues"
 [tool.hatch.build.targets.wheel]
 packages = ["src/codespar"]
 
+# PEP 561 — the empty `py.typed` marker signals to mypy / pyright /
+# pyrefly that this package ships inline type hints. Without it,
+# downstream projects lose type info even though every public fn
+# is annotated.
+[tool.hatch.build.targets.wheel.force-include]
+"src/codespar/py.typed" = "codespar/py.typed"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 asyncio_mode = "auto"

{codespar-0.1.0 → codespar-0.3.0}/src/codespar/__init__.py

@@ -61,7 +61,7 @@ from .types import (
     UserMessageEvent,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "ApiError",

{codespar-0.1.0 → codespar-0.3.0}/src/codespar/_http.py

@@ -28,7 +28,7 @@ def build_headers(
     headers = {
         "Content-Type": "application/json",
         "Authorization": f"Bearer {api_key}",
-        "User-Agent": "codespar-python/0.1.0",
+        "User-Agent": "codespar-python/0.1.1",
     }
     if project_id:
         headers["x-codespar-project"] = project_id