The Complete Loop in 5 Lines of Code

Before CodeSpar: 6 manual steps, 45 minutes, 3 people. After: 1 agent call, 12 seconds, zero humans.

npm install @codespar/sdk @codespar/vercel ai @ai-sdk/anthropic

# CodeSpar API key (get one at codespar.dev/dashboard/settings)
CODESPAR_API_KEY=csk_live_your_key_here

# Anthropic API key (for the LLM that orchestrates the loop)
ANTHROPIC_API_KEY=sk-ant-your_key_here

# Optional: Override the CodeSpar API endpoint (default: https://api.codespar.dev)
# CODESPAR_BASE_URL=https://api.codespar.dev

# Optional: Enable debug logging for development
# CODESPAR_DEBUG=true

import { CodeSpar } from "@codespar/sdk";
import { getTools } from "@codespar/vercel";
import { generateText } from "ai";
import { anthropic } from "@ai-sdk/anthropic";

// Initialize the SDK
const codespar = new CodeSpar({
  apiKey: process.env.CODESPAR_API_KEY!,
  // baseUrl: process.env.CODESPAR_BASE_URL, // optional override
});

// Create a session scoped to this user
const session = await codespar.create("user_123", {
  preset: "brazilian",    // connects 6 MCP servers for Brazil commerce
  budgetLimit: 5000,      // max R$ per session (policy enforcement)
});

// Get tools formatted for Vercel AI SDK
// This returns 6 meta tools with execute() functions built in
const tools = await getTools(session);

console.log(`Session created: ${session.id}`);
console.log(`Loaded ${Object.keys(tools).length} meta tools`);
// Output: Loaded 6 meta tools
// codespar_discover, codespar_checkout, codespar_pay,
// codespar_invoice, codespar_ship, codespar_notify

// Subscribe to events before sending
codespar.on("payment.completed", (e) => {
  console.log("Payment confirmed:", e.data.amount, e.data.currency);
});
codespar.on("nfe.issued", (e) => {
  console.log("NF-e authorized:", e.data.number, "SEFAZ:", e.data.sefaz);
});
codespar.on("shipping.label_created", (e) => {
  console.log("Label:", e.data.carrier, "Tracking:", e.data.tracking);
});

// Run the Complete Loop
const result = await generateText({
  model: anthropic("claude-sonnet-4-5-20250514"),
  tools,
  maxSteps: 10,
  prompt: `
    Process order #7721 for customer Joao Silva (CPF: 123.456.789-00):
    - Charge R$1,249.00 via Pix
    - Issue NF-e for: 1x MacBook Air M3 (NCM 8471.30.19, CFOP 5102)
    - Generate shipping label (Correios PAC, CEP 01310-100 to 20040-020)
    - Notify customer on WhatsApp (+5511999999999)
    - Register sale in Omie ERP
    - Reconcile payment in Stark Bank
  `,
});

console.log(result.text);

const loop = await session.loop({
  steps: [
    {
      server: "mcp-zoop",
      tool: "create_transaction",
      params: {
        amount: 124900,  // centavos
        currency: "BRL",
        payment_type: "pix",
        customer: {
          name: "Joao Silva",
          cpf: "12345678900",
          email: "joao@example.com",
        },
        description: "Order #7721 - MacBook Air M3",
        expiration_seconds: 1800,  // 30 min Pix expiration
      },
    },
    {
      server: "mcp-nuvem-fiscal",
      tool: "create_nfe",
      params: {
        natureza_operacao: "Venda de mercadoria",
        items: [{
          descricao: "MacBook Air M3",
          ncm: "84713019",
          cfop: "5102",
          quantidade: 1,
          valor_unitario: 124900,
          icms: { cst: "00", aliquota: 18 },
          pis: { cst: "01", aliquota: 1.65 },
          cofins: { cst: "01", aliquota: 7.6 },
        }],
        destinatario: {
          cpf: "12345678900",
          nome: "Joao Silva",
          endereco: { cep: "20040020", uf: "RJ" },
        },
      },
      // Use output from step 0 (payment) as input
      mapInput: (prevResults) => ({
        payment_id: prevResults[0].data.transaction_id,
      }),
    },
    {
      server: "mcp-melhor-envio",
      tool: "create_shipment",
      params: {
        service: "PAC",
        from: { postal_code: "01310100" },
        to: { postal_code: "20040020" },
        package: { weight: 1.5, width: 35, height: 5, length: 25 },
      },
      mapInput: (prevResults) => ({
        invoice_key: prevResults[1].data.chave_nfe,
      }),
    },
    {
      server: "mcp-z-api",
      tool: "send_message",
      params: { phone: "5511999999999" },
      mapInput: (prevResults) => ({
        message: [
          "Pedido #7721 confirmado!",
          `Pagamento: R$ 1.249,00 via Pix`,
          `NF-e: ${prevResults[1].data.number}`,
          `Rastreio: ${prevResults[2].data.tracking_code}`,
          `Previsao de entrega: ${prevResults[2].data.estimated_delivery}`,
        ].join("\n"),
      }),
    },
    {
      server: "mcp-omie",
      tool: "create_order",
      mapInput: (prevResults) => ({
        order_number: "7721",
        customer_cpf: "12345678900",
        payment_id: prevResults[0].data.transaction_id,
        nfe_number: prevResults[1].data.number,
        tracking_code: prevResults[2].data.tracking_code,
        total: 124900,
      }),
    },
    {
      server: "mcp-stark-bank",
      tool: "get_balance",
      mapInput: (prevResults) => ({
        reference: prevResults[0].data.transaction_id,
        expected_amount: 124900,
      }),
    },
  ],

  // Retry policy for transient failures
  retryPolicy: {
    maxRetries: 3,
    backoff: "exponential",   // 1s, 2s, 4s
    retryableErrors: ["TIMEOUT", "RATE_LIMITED", "SERVER_ERROR"],
  },

  // Called after each step completes
  onStepComplete: (step, result) => {
    console.log(`[${step.server}] ${step.tool}: ${result.status}`);
  },

  // Called if a step fails after all retries
  onStepFailed: (step, error) => {
    console.error(`[${step.server}] ${step.tool} FAILED:`, error.code);
  },
});

console.log(`Complete Loop finished in ${loop.durationMs}ms`);
console.log(`Steps: ${loop.results.length}/6 succeeded`);

try {
  const payment = await session.execute("ZOOP_CREATE_CHARGE", {
    amount: 124900,
    payment_type: "pix",
    expiration_seconds: 1800,
  });
} catch (error) {
  if (error.code === "PIX_EXPIRED") {
    // Generate a new Pix QR code with extended expiration
    const retry = await session.execute("ZOOP_CREATE_CHARGE", {
      amount: 124900,
      payment_type: "pix",
      expiration_seconds: 3600,  // extend to 1 hour
    });

    // Notify the customer that a new QR code is available
    await session.execute("ZAPI_SEND_MESSAGE", {
      phone: "5511999999999",
      message: "Seu Pix expirou. Geramos um novo QR code. Escaneie para pagar.",
    });
  }

  if (error.code === "PSP_UNAVAILABLE") {
    // Zoop is down - fall back to Asaas or queue for retry
    console.error("PSP unavailable. Queuing order for retry.");
    await queueForRetry("payment", orderData, {
      maxAttempts: 5,
      backoffMs: 30000,  // retry every 30 seconds
    });
  }
}

try {
  const nfe = await session.execute("NUVEM_FISCAL_CREATE_NFE", {
    natureza_operacao: "Venda de mercadoria",
    items: [/* ... */],
  });
} catch (error) {
  if (error.code === "SEFAZ_REJECTION") {
    // SEFAZ returned a specific rejection code
    // Common: 301 (IE destinatario), 539 (NCM), 694 (CFOP/CST)
    console.error(`SEFAZ rejection ${error.data.cStat}: ${error.data.xMotivo}`);

    // Log for manual review - do NOT auto-retry rejected NF-e
    // Rejections are typically data errors that require human correction
    await alertOps("nfe_rejected", {
      order: "7721",
      rejection_code: error.data.cStat,
      reason: error.data.xMotivo,
    });
  }

  if (error.code === "SEFAZ_TIMEOUT" || error.code === "SEFAZ_UNAVAILABLE") {
    // SEFAZ is down - switch to contingencia mode (NFC-e offline)
    console.warn("SEFAZ unavailable. Issuing in contingencia mode.");
    const nfeContingencia = await session.execute("NUVEM_FISCAL_CREATE_NFE", {
      // Same params, but with contingencia flag
      contingencia: true,
      justificativa: "SEFAZ indisponivel",
      // The NF-e will be transmitted when SEFAZ is back online
    });

    // Schedule automatic retransmission check
    await scheduleRetransmission(nfeContingencia.data.chave_nfe, {
      checkIntervalMs: 300000,  // check every 5 minutes
      maxDurationHours: 24,     // give up after 24 hours
    });
  }
}

const CARRIER_FALLBACK = ["PAC", "SEDEX", "jadlog_package", "azul_amanha"];

async function createShipmentWithFallback(
  session: Session,
  params: ShipmentParams
): Promise<ShipmentResult> {
  for (const service of CARRIER_FALLBACK) {
    try {
      return await session.execute("MELHOR_ENVIO_CREATE_SHIPMENT", {
        ...params,
        service,
      });
    } catch (error) {
      if (error.code === "CARRIER_UNAVAILABLE" || error.code === "SERVICE_AREA") {
        console.warn(`${service} unavailable, trying next carrier...`);
        continue;  // try next carrier
      }
      throw error;  // unexpected error - don't swallow it
    }
  }
  throw new Error("All carriers unavailable. Manual intervention required.");
}

async function notifyCustomer(
  session: Session,
  customer: { phone: string; email: string },
  message: string
): Promise<void> {
  try {
    // Primary: WhatsApp via Z-API
    await session.execute("ZAPI_SEND_MESSAGE", {
      phone: customer.phone,
      message,
    });
    return;
  } catch (error) {
    console.warn("WhatsApp failed:", error.code);
  }

  try {
    // Fallback 1: SMS via Twilio (or similar)
    await session.execute("TWILIO_SEND_SMS", {
      to: `+${customer.phone}`,
      body: message.substring(0, 160),  // SMS character limit
    });
    return;
  } catch (error) {
    console.warn("SMS failed:", error.code);
  }

  // Fallback 2: Email (always available)
  await session.execute("SENDGRID_SEND_EMAIL", {
    to: customer.email,
    subject: "Pedido #7721 confirmado",
    body: message,
  });
}

async function syncToERP(session: Session, orderData: OrderData): Promise<void> {
  try {
    await session.execute("OMIE_CREATE_ORDER", {
      order_number: orderData.orderId,
      customer_cpf: orderData.customerCpf,
      total: orderData.total,
      nfe_number: orderData.nfeNumber,
    });
  } catch (error) {
    if (error.code === "RATE_LIMITED" || error.code === "ERP_UNAVAILABLE") {
      // Queue for async retry - the order is already paid and shipped
      // ERP sync is important but not blocking
      await enqueueERPSync(orderData, {
        maxRetries: 10,
        backoff: "exponential",
        initialDelayMs: 60000,  // first retry in 1 minute
      });

      console.warn(`ERP sync queued for order ${orderData.orderId}`);
      return;
    }

    // Data errors (invalid CPF, duplicate order) need human review
    await alertOps("erp_sync_failed", {
      order: orderData.orderId,
      error: error.code,
      message: error.message,
    });
  }
}

// SSE stream for real-time UI updates
const stream = await session.sendStream(
  "Process order #7721: charge R$1,249 via Pix, issue NF-e, ship, notify."
);

for await (const event of stream) {
  switch (event.type) {
    case "tool_call_start":
      console.log(`Starting: ${event.data.tool_name}...`);
      // UI: show spinner on current step
      break;
    case "tool_call_complete":
      console.log(`Done: ${event.data.tool_name} (${event.data.duration_ms}ms)`);
      // UI: check mark on completed step
      break;
    case "text_delta":
      process.stdout.write(event.data.text);
      // UI: stream the agent's reasoning
      break;
    case "error":
      console.error(`Error: ${event.data.code} - ${event.data.message}`);
      break;
    case "done":
      console.log("Complete Loop finished.");
      break;
  }
}

const loop = await session.loop({
  steps: [
    { server: "mcp-zoop", tool: "create_transaction", params: { /* ... */ } },
    { server: "mcp-nuvem-fiscal", tool: "create_nfe", params: { /* ... */ } },
    { server: "mcp-melhor-envio", tool: "create_shipment", params: { /* ... */ } },
    // Steps 4-6 run in parallel (no dependencies between them)
    {
      parallel: [
        { server: "mcp-z-api", tool: "send_message", params: { /* ... */ } },
        { server: "mcp-omie", tool: "create_order", params: { /* ... */ } },
        { server: "mcp-stark-bank", tool: "get_balance", params: { /* ... */ } },
      ],
    },
  ],
  retryPolicy: { maxRetries: 3, backoff: "exponential" },
});

// With parallel optimization: ~6s P50 vs ~8s sequential

// Production configuration example
const codespar = new CodeSpar({
  apiKey: process.env.CODESPAR_API_KEY!,  // csk_live_...
});

const session = await codespar.create(userId, {
  preset: "brazilian",
  budgetLimit: 100000,  // R$100K - set based on your AOV
  policies: [
    { name: "rate-limit", type: "rate-limit", config: { maxPerMinute: 60 } },
    { name: "business-hours", type: "time-window", config: { startHour: 6, endHour: 23 } },
  ],
});

// Connect provider credentials (typically done once per org)
await session.authorize("zoop", { token: process.env.ZOOP_API_KEY! });
await session.authorize("nuvem_fiscal", { token: process.env.NUVEM_FISCAL_KEY! });
await session.authorize("melhor_envio", { token: process.env.MELHOR_ENVIO_TOKEN! });
await session.authorize("z_api", { token: process.env.ZAPI_TOKEN! });
await session.authorize("omie", {
  appKey: process.env.OMIE_APP_KEY!,
  appSecret: process.env.OMIE_APP_SECRET!,
});
await session.authorize("stark_bank", {
  privateKey: process.env.STARK_BANK_PRIVATE_KEY!,
  projectId: process.env.STARK_BANK_PROJECT_ID!,
});

[mcp-zoop] create_transaction: completed (1,247ms)
  Payment: { amount: 1249, currency: "BRL", method: "pix", status: "confirmed" }

[mcp-nuvem-fiscal] create_nfe: completed (2,103ms)
  NF-e: { number: "NF-4421", status: "authorized", sefaz: "SP", chave: "3526..." }

[mcp-melhor-envio] create_shipment: completed (1,812ms)
  Shipping: { carrier: "Correios PAC", tracking: "BR123456789", eta: "2026-04-21" }

[mcp-z-api] send_message: completed (834ms)
  WhatsApp: { to: "+5511999999999", status: "delivered" }

[mcp-omie] create_order: completed (1,523ms)
  ERP: { orderId: "7721", status: "registered", nfe: "NF-4421" }

[mcp-stark-bank] get_balance: completed (612ms)
  Banking: { transaction: "matched", settled: true, balance: "updated" }

Complete Loop finished in 8,131ms. 6 APIs. 6 tool calls. 0 human steps.

Full source code for this tutorial is available on GitHub. Questions? Open an issue or reach us at team@codespar.dev.