@riv-io/sdk

SDK TypeScript do Riv — governança financeira para agentes de IA. Embrulha a API pública do Riv (POST /api/v1/authorize e GET /api/v1/activities) num client tipado, autenticado pela chave riv_ do agente.

É uma casca fina: autenticação, motor de decisão e ledger vivem no servidor do Riv. O SDK só dá tipos, ergonomia e erros bem definidos.

Quickstart

npm install @riv-io/sdk

import { Riv } from "@riv-io/sdk";

const riv = new Riv({ apiKey: process.env.RIV_API_KEY! });
const r = await riv.authorize({ amount: 49.9, currency: "BRL", description: "API OpenAI" });
if (r.decision === "allow") {
  // execute o gasto
}

Cinco linhas até a primeira autorização. A RIV_API_KEY é a credencial riv_ emitida ao conectar o agente no painel do Riv.

API

new Riv(options)

• apiKey (obrigatória) — credencial riv_ do agente.
• baseUrl (opcional) — base da API do Riv. Default: http://localhost:3000 (dev local); em produção, https://riv-io.vercel.app.
• timeoutMs (opcional) — timeout por chamada. Sem default (sem timeout).

riv.authorize({ amount, currency, description?, category? })

Pergunta ao Riv se uma transação é permitida antes de executá-la. Retorna:

{ decision: "allow" | "block" | "require_approval", reason: string, activityId: string }

block e require_approval são decisões válidas, não exceções — o agente decide o que fazer (parar, ou aguardar aprovação humana). O SDK nunca faz retry automático de authorize: cada chamada grava uma entrada no ledger.

category (opcional) classifica o gasto (ex.: "inference", "saas") — mandatos por categoria limitam o acumulado daquela categoria. Normalizada (lowercase) no servidor.

riv.activity(activityId)

Consulta pontual: o registro de uma autorização no ledger (use o activityId retornado por authorize). Lança RivNotFoundError se não existir ou pertencer a outro agente.

riv.activities({ limit? })

Extrato: as atividades mais recentes do agente (padrão 10, máx. 50).

Valores de status nas atividades: approved (conta no gasto acumulado), pending (aguardando humano), blocked (veredito do motor) e rejected (humano negou a aprovação — não conta no gasto). Um pending muda para approved ou rejected quando alguém resolve no painel do Riv — consulte a atividade de novo para ver o desfecho.

Erros

Falhas reais da chamada lançam subclasses de RivError (com .code e .status); decisões de governança nunca lançam.

| Erro | Quando | |---|---| | RivAuthError | credencial inválida (401) | | RivInputError | input rejeitado pelo servidor (400) | | RivNotFoundError | atividade inexistente / de outro agente (404) | | RivNetworkError | falha de rede ou timeout |

import { RivAuthError } from "@riv-io/sdk";

try {
  await riv.authorize({ amount: 10, currency: "BRL" });
} catch (e) {
  if (e instanceof RivAuthError) {
    // rotacione/configure a RIV_API_KEY
  }
}

Frameworks

• LangChain.js — use o @riv-io/langchain. Caminho recomendado: withRivGuard, que embrulha sua tool de pagamento e consulta o Riv antes de cada execução (determinístico, fail-closed). As tools riv_authorize/riv_get_activity são o complemento para consulta ao ledger e fluxos sem tool de pagamento.

• CrewAI (Python) — use o MCP server do Riv (mcp/ neste repo): o CrewAI suporta MCP nativamente, então o agente ganha as tools authorize e get_activity sem SDK Python. Configure o server stdio com a RIV_API_KEY do agente — instruções em mcp/README.md. Exemplo com crewai-tools:

  from crewai_tools import MCPServerAdapter
  from mcp import StdioServerParameters
  
  riv_mcp = StdioServerParameters(
      command="node",
      args=["/caminho/para/riv/mcp/dist/index.js"],
      env={"RIV_API_KEY": "riv_...", "RIV_API_URL": "https://riv-io.vercel.app"},
  )
  
  with MCPServerAdapter(riv_mcp) as tools:
      # tools contém authorize e get_activity, prontas para os agents da crew
      ...

Desenvolvimento

cd sdk
npm install
npm run build        # tsup → dist/ (ESM + CJS + d.ts)
npm run typecheck
npm run test         # unitários (fetch mockado)

# E2E (a partir da raiz do repo; sobe a app em porta efêmera):
#   node --env-file=.env scripts/verify-sdk.mjs