@codespar/cli 0.2.0

package/templates/ecommerce-checkout/src/index.ts

@@ -0,0 +1,73 @@
+/**
+ * {{name}} — End-to-end e-commerce checkout agent.
+ *
+ * Full Complete Loop: checkout → invoice → ship → notify, in one
+ * conversation, powered by Claude.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { CodeSpar } from "@codespar/sdk";
+import { getTools, handleToolUse, toToolResultBlock } from "@codespar/claude";
+
+const claude = new Anthropic();
+const codespar = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY });
+
+export async function checkoutAgent(userMessage: string): Promise<string> {
+  const session = await codespar.create("cli-user", {
+    servers: ["stripe", "nuvem-fiscal", "correios"],
+  });
+
+  try {
+    const tools = await getTools(session);
+
+    const messages: Anthropic.MessageParam[] = [{ role: "user", content: userMessage }];
+
+    let response = await claude.messages.create({
+      model: "claude-opus-4-6",
+      max_tokens: 4096,
+      system: `You are a commerce assistant for a Brazilian e-commerce store.
+
+Products:
+- Pro Plan: R$49.90/month
+- Enterprise Plan: R$199.90/month
+- Starter Kit: R$149.00 (one-time)
+
+Flow: confirm → checkout → invoice → ship → notify. Respond in Portuguese.`,
+      tools,
+      messages,
+    });
+
+    let iterations = 0;
+    while (response.stop_reason === "tool_use" && iterations < 10) {
+      const toolBlocks = response.content.filter(
+        (b): b is Anthropic.ToolUseBlock => b.type === "tool_use",
+      );
+
+      const resultBlocks = [];
+      for (const block of toolBlocks) {
+        const result = await handleToolUse(session, block);
+        resultBlocks.push(toToolResultBlock(block.id, result));
+      }
+
+      messages.push({ role: "assistant", content: response.content });
+      messages.push({ role: "user", content: resultBlocks });
+
+      response = await claude.messages.create({
+        model: "claude-opus-4-6",
+        max_tokens: 4096,
+        tools,
+        messages,
+      });
+      iterations += 1;
+    }
+
+    const text = response.content.find((b): b is Anthropic.TextBlock => b.type === "text");
+    return text?.text ?? "";
+  } finally {
+    await session.close();
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const reply = await checkoutAgent("Quero comprar o Starter Kit. Meu CEP é 01310-100.");
+  console.log(reply);
+}

package/templates/ecommerce-checkout/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"]
+}

package/templates/multi-tenant/.env.example

@@ -0,0 +1,2 @@
+CODESPAR_API_KEY=csk_live_...
+OPENAI_API_KEY=sk-...

package/templates/multi-tenant/README.md

@@ -0,0 +1,31 @@
+# {{name}}
+
+Multi-tenant SaaS commerce agent scaffolded by `codespar init`.
+
+## Setup
+
+```bash
+cp .env.example .env
+# Fill in CODESPAR_API_KEY and OPENAI_API_KEY
+
+npm install
+npm run dev
+# → http://localhost:3000
+```
+
+## What it does
+
+One codespar API key, N tenants. Each tenant has its own session, servers, and credentials. Every tool call is tagged with `metadata.tenant_id` for per-tenant billing.
+
+Try it:
+
+```bash
+curl -X POST http://localhost:3000/api/commerce/tenant_acme \
+  -H "Content-Type: application/json" \
+  -d '{"message":"Create a Pix charge of R$50"}'
+```
+
+## Learn more
+
+- [Multi-Tenant Agent cookbook](https://codespar.dev/docs/cookbooks/multi-tenant)
+- [Sessions reference](https://codespar.dev/docs/concepts/sessions)

package/templates/multi-tenant/app/api/commerce/[tenantId]/route.ts

@@ -0,0 +1,55 @@
+import { NextResponse } from "next/server";
+import OpenAI from "openai";
+import { getTools, handleToolCall } from "@codespar/openai";
+import { createTenantSession } from "@/lib/commerce";
+
+const openai = new OpenAI();
+
+// In production, fetch tenant config from your database instead.
+const TENANTS: Record<string, { servers: string[] }> = {
+  tenant_acme: { servers: ["stripe", "correios", "nuvem-fiscal"] },
+  tenant_loja: { servers: ["asaas", "melhor-envio", "z-api"] },
+};
+
+export async function POST(
+  req: Request,
+  { params }: { params: Promise<{ tenantId: string }> },
+) {
+  const { tenantId } = await params;
+  const tenant = TENANTS[tenantId];
+  if (!tenant) return NextResponse.json({ error: "Tenant not found" }, { status: 404 });
+
+  const { message } = await req.json();
+
+  const session = await createTenantSession({
+    id: tenantId,
+    servers: tenant.servers,
+    metadata: { source: "api" },
+  });
+
+  try {
+    const tools = await getTools(session);
+    const messages: OpenAI.ChatCompletionMessageParam[] = [
+      { role: "system", content: `You are a commerce assistant for tenant ${tenantId}.` },
+      { role: "user", content: message },
+    ];
+
+    let response = await openai.chat.completions.create({ model: "gpt-4o", tools, messages });
+    let iterations = 0;
+
+    while (response.choices[0].message.tool_calls?.length && iterations < 10) {
+      const msg = response.choices[0].message;
+      messages.push(msg);
+      for (const toolCall of msg.tool_calls) {
+        const result = await handleToolCall(session, toolCall);
+        messages.push({ role: "tool", tool_call_id: toolCall.id, content: JSON.stringify(result) });
+      }
+      response = await openai.chat.completions.create({ model: "gpt-4o", tools, messages });
+      iterations += 1;
+    }
+
+    return NextResponse.json({ reply: response.choices[0].message.content });
+  } finally {
+    await session.close();
+  }
+}

package/templates/multi-tenant/lib/commerce.ts

@@ -0,0 +1,24 @@
+import { CodeSpar } from "@codespar/sdk";
+
+const codespar = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY! });
+
+export interface TenantConfig {
+  id: string;
+  servers: string[];
+  metadata?: Record<string, string>;
+}
+
+/**
+ * Wraps sessions.create() to inject tenant_id metadata on every session,
+ * so tool-call logs are automatically attributable per tenant — no extra
+ * code needed at call sites.
+ */
+export async function createTenantSession(tenant: TenantConfig) {
+  return codespar.create(tenant.id, {
+    servers: tenant.servers,
+    metadata: {
+      tenant_id: tenant.id,
+      ...(tenant.metadata ?? {}),
+    },
+  });
+}

package/templates/multi-tenant/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@codespar/sdk": "^0.2.0",
+    "@codespar/openai": "^0.2.0",
+    "openai": "^4.0.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/multi-tenant/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "paths": { "@/*": ["./*"] },
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}

package/templates/pix-agent/.env.example

@@ -0,0 +1,2 @@
+CODESPAR_API_KEY=csk_live_...
+OPENAI_API_KEY=sk-...

package/templates/pix-agent/README.md

@@ -0,0 +1,22 @@
+# {{name}}
+
+Pix payment agent scaffolded by `codespar init`.
+
+## Setup
+
+```bash
+cp .env.example .env
+# Fill in CODESPAR_API_KEY and OPENAI_API_KEY
+
+npm install
+npm run dev
+```
+
+## What it does
+
+Creates a Pix charge on Asaas and sends the QR code to a customer's WhatsApp via Twilio. See `src/index.ts` for the agent loop.
+
+## Learn more
+
+- [Pix Payment Agent cookbook](https://codespar.dev/docs/cookbooks/pix-payment-agent)
+- [OpenAI provider reference](https://codespar.dev/docs/providers/openai)

package/templates/pix-agent/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@codespar/sdk": "^0.2.0",
+    "@codespar/openai": "^0.2.0",
+    "openai": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/pix-agent/src/index.ts

@@ -0,0 +1,66 @@
+/**
+ * {{name}} — Pix payment agent.
+ *
+ * Usage:
+ *   pnpm dev  (or: npm run dev)
+ *   pixAgent("+5511999887766", 15000, "Pro Plan")
+ */
+import OpenAI from "openai";
+import { CodeSpar } from "@codespar/sdk";
+import { getTools, handleToolCall } from "@codespar/openai";
+
+const openai = new OpenAI();
+const codespar = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY });
+
+export async function pixAgent(
+  customerPhone: string,
+  amount: number,
+  description: string,
+): Promise<string | null> {
+  const session = await codespar.create("cli-user", { servers: ["asaas", "twilio"] });
+
+  try {
+    const tools = await getTools(session);
+
+    const messages: OpenAI.ChatCompletionMessageParam[] = [
+      {
+        role: "system",
+        content: `You are a payment assistant for a Brazilian e-commerce store.
+When asked to create a Pix payment:
+1. Use codespar_pay to create the Pix charge on asaas
+2. Use codespar_notify to send the QR code link via WhatsApp on twilio
+Always confirm amount and phone before processing. Respond in Portuguese.`,
+      },
+      {
+        role: "user",
+        content: `Create Pix of R$${(amount / 100).toFixed(2)} for "${description}", send to ${customerPhone}`,
+      },
+    ];
+
+    let response = await openai.chat.completions.create({ model: "gpt-4o", tools, messages });
+    let iterations = 0;
+
+    while (response.choices[0].message.tool_calls?.length && iterations < 10) {
+      const msg = response.choices[0].message;
+      messages.push(msg);
+
+      for (const toolCall of msg.tool_calls) {
+        const result = await handleToolCall(session, toolCall);
+        messages.push({ role: "tool", tool_call_id: toolCall.id, content: JSON.stringify(result) });
+      }
+
+      response = await openai.chat.completions.create({ model: "gpt-4o", tools, messages });
+      iterations += 1;
+    }
+
+    return response.choices[0].message.content;
+  } finally {
+    await session.close();
+  }
+}
+
+// Demo run when executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const reply = await pixAgent("+5511999887766", 15000, "Pro Plan");
+  console.log(reply);
+}

package/templates/pix-agent/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"]
+}

package/templates/streaming-chat/.env.example

@@ -0,0 +1,2 @@
+CODESPAR_API_KEY=csk_live_...
+OPENAI_API_KEY=sk-...

package/templates/streaming-chat/README.md

@@ -0,0 +1,23 @@
+# {{name}}
+
+Real-time streaming commerce chat scaffolded by `codespar init`.
+
+## Setup
+
+```bash
+cp .env.example .env
+# Fill in CODESPAR_API_KEY and OPENAI_API_KEY
+
+npm install
+npm run dev
+# → http://localhost:3000
+```
+
+## What it does
+
+Next.js 15 App Router + Vercel AI SDK + CodeSpar. Token-by-token streaming chat where tool calls happen automatically and appear live in the UI.
+
+## Learn more
+
+- [Streaming Chat cookbook](https://codespar.dev/docs/cookbooks/streaming-chat)
+- [Vercel AI SDK provider reference](https://codespar.dev/docs/providers/vercel)

package/templates/streaming-chat/app/api/chat/route.ts

@@ -0,0 +1,29 @@
+import { streamText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { CodeSpar } from "@codespar/sdk";
+import { getTools } from "@codespar/vercel";
+
+const codespar = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY! });
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const session = await codespar.create("cli-user", {
+    servers: ["stripe", "asaas", "correios"],
+  });
+
+  const tools = await getTools(session);
+
+  const result = streamText({
+    model: openai("gpt-4o"),
+    tools,
+    maxSteps: 10,
+    system: "Commerce assistant for a Brazilian store. Be concise and respond in Portuguese when asked.",
+    messages,
+    onFinish: async () => {
+      await session.close();
+    },
+  });
+
+  return result.toDataStreamResponse();
+}

package/templates/streaming-chat/app/layout.tsx

@@ -0,0 +1,12 @@
+export const metadata = {
+  title: "{{name}}",
+  description: "Streaming commerce chat powered by CodeSpar + Vercel AI SDK",
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/streaming-chat/app/page.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+
+export default function Chat() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({ api: "/api/chat" });
+
+  return (
+    <main style={{ maxWidth: 720, margin: "40px auto", fontFamily: "system-ui", padding: "0 20px" }}>
+      <h1 style={{ fontSize: 24, marginBottom: 24 }}>{{name}}</h1>
+
+      <div style={{ display: "flex", flexDirection: "column", gap: 12, minHeight: 400 }}>
+        {messages.map((m) => (
+          <div
+            key={m.id}
+            style={{
+              padding: "10px 14px",
+              borderRadius: 8,
+              background: m.role === "user" ? "#EFF6FF" : "#F4F4F5",
+              alignSelf: m.role === "user" ? "flex-end" : "flex-start",
+              maxWidth: "80%",
+            }}
+          >
+            {m.content}
+            {m.toolInvocations?.map((tool) => (
+              <div key={tool.toolCallId} style={{ marginTop: 6, fontSize: 12, color: "#6B7280" }}>
+                {tool.state === "result"
+                  ? `✓ ${tool.toolName} completed`
+                  : `⏳ Calling ${tool.toolName}...`}
+              </div>
+            ))}
+          </div>
+        ))}
+      </div>
+
+      <form onSubmit={handleSubmit} style={{ marginTop: 24, display: "flex", gap: 8 }}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Ask about payments, shipping, invoices..."
+          style={{
+            flex: 1,
+            padding: "10px 14px",
+            borderRadius: 8,
+            border: "1px solid #E5E7EB",
+            fontSize: 14,
+          }}
+        />
+        <button
+          type="submit"
+          style={{
+            padding: "10px 18px",
+            borderRadius: 8,
+            background: "#3B82F6",
+            color: "white",
+            border: "none",
+            fontWeight: 600,
+            cursor: "pointer",
+          }}
+        >
+          Send
+        </button>
+      </form>
+    </main>
+  );
+}

package/templates/streaming-chat/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@codespar/sdk": "^0.2.0",
+    "@codespar/vercel": "^0.2.0",
+    "@ai-sdk/openai": "^1.0.0",
+    "@ai-sdk/react": "^1.0.0",
+    "ai": "^4.0.0",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/templates/streaming-chat/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "paths": { "@/*": ["./*"] },
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}