@riv-io/sdk 0.1.0

package/README.md

@@ -0,0 +1,122 @@
+# @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
+
+```bash
+npm install @riv-io/sdk
+```
+
+```ts
+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`.
+- `timeoutMs` (opcional) — timeout por chamada. Sem default (sem timeout).
+
+### `riv.authorize({ amount, currency, description? })`
+
+Pergunta ao Riv se uma transação é permitida **antes** de executá-la. Retorna:
+
+```ts
+{ 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.
+
+### `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).
+
+## 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 |
+
+```ts
+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`](../adapters/langchain/README.md).
+  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`](../mcp/README.md). Exemplo com
+  `crewai-tools`:
+
+  ```python
+  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://sua-instancia-riv"},
+  )
+
+  with MCPServerAdapter(riv_mcp) as tools:
+      # tools contém authorize e get_activity, prontas para os agents da crew
+      ...
+  ```
+
+## Desenvolvimento
+
+```bash
+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
+```

package/dist/index.cjs

@@ -0,0 +1,142 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Riv: () => Riv,
+  RivAuthError: () => RivAuthError,
+  RivError: () => RivError,
+  RivInputError: () => RivInputError,
+  RivNetworkError: () => RivNetworkError,
+  RivNotFoundError: () => RivNotFoundError
+});
+module.exports = __toCommonJS(index_exports);
+var RivError = class extends Error {
+  code;
+  status;
+  constructor(code, message, status) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.status = status;
+  }
+};
+var RivAuthError = class extends RivError {
+  constructor(message = "Credencial inv\xE1lida.") {
+    super("unauthorized", message, 401);
+  }
+};
+var RivInputError = class extends RivError {
+  constructor(message) {
+    super("invalid_input", message, 400);
+  }
+};
+var RivNotFoundError = class extends RivError {
+  constructor(message = "Atividade n\xE3o encontrada.") {
+    super("not_found", message, 404);
+  }
+};
+var RivNetworkError = class extends RivError {
+  constructor(message) {
+    super("network_error", message);
+  }
+};
+var Riv = class {
+  #apiKey;
+  #baseUrl;
+  #timeoutMs;
+  constructor(options) {
+    if (!options?.apiKey) {
+      throw new RivAuthError("apiKey \xE9 obrigat\xF3ria (credencial riv_ do agente).");
+    }
+    this.#apiKey = options.apiKey;
+    this.#baseUrl = (options.baseUrl ?? "http://localhost:3000").replace(/\/+$/, "");
+    this.#timeoutMs = options.timeoutMs;
+  }
+  /**
+   * Pergunta ao Riv se uma transação é permitida ANTES de executá-la.
+   * Sem retry automático: cada chamada grava uma entrada no ledger.
+   */
+  async authorize(input) {
+    const data = await this.#request("POST", "/api/v1/authorize", input);
+    return data;
+  }
+  /** Consulta pontual: o registro de uma autorização pelo activityId. */
+  async activity(activityId) {
+    const qs = new URLSearchParams({ id: activityId });
+    const data = await this.#request("GET", `/api/v1/activities?${qs}`);
+    return data.activities[0];
+  }
+  /** Extrato: as atividades mais recentes do agente (padrão 10, máx. 50). */
+  async activities(options) {
+    const qs = new URLSearchParams();
+    if (options?.limit !== void 0) qs.set("limit", String(options.limit));
+    const suffix = qs.size > 0 ? `?${qs}` : "";
+    const data = await this.#request("GET", `/api/v1/activities${suffix}`);
+    return data.activities;
+  }
+  async #request(method, path, body) {
+    const controller = this.#timeoutMs !== void 0 ? new AbortController() : null;
+    const timer = controller && setTimeout(() => controller.abort(), this.#timeoutMs);
+    let res;
+    try {
+      res = await fetch(`${this.#baseUrl}${path}`, {
+        method,
+        headers: {
+          authorization: `Bearer ${this.#apiKey}`,
+          ...body !== void 0 ? { "content-type": "application/json" } : {}
+        },
+        ...body !== void 0 ? { body: JSON.stringify(body) } : {},
+        ...controller ? { signal: controller.signal } : {}
+      });
+    } catch (err) {
+      const aborted = err instanceof Error && err.name === "AbortError";
+      throw new RivNetworkError(
+        aborted ? `Timeout de ${this.#timeoutMs}ms ao chamar o Riv em ${this.#baseUrl}.` : `Erro de rede ao chamar o Riv em ${this.#baseUrl}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      const message = data?.message ?? `HTTP ${res.status}`;
+      switch (res.status) {
+        case 401:
+          throw new RivAuthError(message);
+        case 400:
+          throw new RivInputError(message);
+        case 404:
+          throw new RivNotFoundError(message);
+        default:
+          throw new RivError(data?.error ?? "api_error", message, res.status);
+      }
+    }
+    return data;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Riv,
+  RivAuthError,
+  RivError,
+  RivInputError,
+  RivNetworkError,
+  RivNotFoundError
+});

package/dist/index.d.cts

@@ -0,0 +1,73 @@
+type Decision = "allow" | "block" | "require_approval";
+type AuthorizeInput = {
+    /** Valor da transação (> 0, até 2 casas decimais — validado no servidor). */
+    amount: number;
+    /** Moeda da transação, ex.: "BRL", "USD". */
+    currency: string;
+    /** Descrição opcional, registrada no ledger para auditoria. */
+    description?: string;
+};
+type AuthorizeResult = {
+    decision: Decision;
+    reason: string;
+    /** Id do registro no ledger — use riv.activity(activityId) para consultar. */
+    activityId: string;
+};
+type Activity = {
+    id: string;
+    type: string;
+    amount: number;
+    currency: string;
+    rail: string | null;
+    status: string;
+    description: string | null;
+    /** ISO 8601. */
+    createdAt: string;
+};
+type RivOptions = {
+    /** Credencial riv_ do agente, emitida ao conectá-lo no Riv. */
+    apiKey: string;
+    /** Base da API do Riv. Default: http://localhost:3000. */
+    baseUrl?: string;
+    /** Timeout por chamada em ms. Sem default: sem timeout. */
+    timeoutMs?: number;
+};
+/** Base de todos os erros do SDK. Decisões (block/require_approval) NÃO lançam. */
+declare class RivError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    constructor(code: string, message: string, status?: number);
+}
+/** Credencial inválida (401). */
+declare class RivAuthError extends RivError {
+    constructor(message?: string);
+}
+/** Input rejeitado pelo servidor (400). */
+declare class RivInputError extends RivError {
+    constructor(message: string);
+}
+/** Atividade não encontrada — ou pertence a outro agente (404). */
+declare class RivNotFoundError extends RivError {
+    constructor(message?: string);
+}
+/** Falha de rede ou timeout — a chamada pode nem ter chegado ao Riv. */
+declare class RivNetworkError extends RivError {
+    constructor(message: string);
+}
+declare class Riv {
+    #private;
+    constructor(options: RivOptions);
+    /**
+     * Pergunta ao Riv se uma transação é permitida ANTES de executá-la.
+     * Sem retry automático: cada chamada grava uma entrada no ledger.
+     */
+    authorize(input: AuthorizeInput): Promise<AuthorizeResult>;
+    /** Consulta pontual: o registro de uma autorização pelo activityId. */
+    activity(activityId: string): Promise<Activity>;
+    /** Extrato: as atividades mais recentes do agente (padrão 10, máx. 50). */
+    activities(options?: {
+        limit?: number;
+    }): Promise<Activity[]>;
+}
+
+export { type Activity, type AuthorizeInput, type AuthorizeResult, type Decision, Riv, RivAuthError, RivError, RivInputError, RivNetworkError, RivNotFoundError, type RivOptions };

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+type Decision = "allow" | "block" | "require_approval";
+type AuthorizeInput = {
+    /** Valor da transação (> 0, até 2 casas decimais — validado no servidor). */
+    amount: number;
+    /** Moeda da transação, ex.: "BRL", "USD". */
+    currency: string;
+    /** Descrição opcional, registrada no ledger para auditoria. */
+    description?: string;
+};
+type AuthorizeResult = {
+    decision: Decision;
+    reason: string;
+    /** Id do registro no ledger — use riv.activity(activityId) para consultar. */
+    activityId: string;
+};
+type Activity = {
+    id: string;
+    type: string;
+    amount: number;
+    currency: string;
+    rail: string | null;
+    status: string;
+    description: string | null;
+    /** ISO 8601. */
+    createdAt: string;
+};
+type RivOptions = {
+    /** Credencial riv_ do agente, emitida ao conectá-lo no Riv. */
+    apiKey: string;
+    /** Base da API do Riv. Default: http://localhost:3000. */
+    baseUrl?: string;
+    /** Timeout por chamada em ms. Sem default: sem timeout. */
+    timeoutMs?: number;
+};
+/** Base de todos os erros do SDK. Decisões (block/require_approval) NÃO lançam. */
+declare class RivError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    constructor(code: string, message: string, status?: number);
+}
+/** Credencial inválida (401). */
+declare class RivAuthError extends RivError {
+    constructor(message?: string);
+}
+/** Input rejeitado pelo servidor (400). */
+declare class RivInputError extends RivError {
+    constructor(message: string);
+}
+/** Atividade não encontrada — ou pertence a outro agente (404). */
+declare class RivNotFoundError extends RivError {
+    constructor(message?: string);
+}
+/** Falha de rede ou timeout — a chamada pode nem ter chegado ao Riv. */
+declare class RivNetworkError extends RivError {
+    constructor(message: string);
+}
+declare class Riv {
+    #private;
+    constructor(options: RivOptions);
+    /**
+     * Pergunta ao Riv se uma transação é permitida ANTES de executá-la.
+     * Sem retry automático: cada chamada grava uma entrada no ledger.
+     */
+    authorize(input: AuthorizeInput): Promise<AuthorizeResult>;
+    /** Consulta pontual: o registro de uma autorização pelo activityId. */
+    activity(activityId: string): Promise<Activity>;
+    /** Extrato: as atividades mais recentes do agente (padrão 10, máx. 50). */
+    activities(options?: {
+        limit?: number;
+    }): Promise<Activity[]>;
+}
+
+export { type Activity, type AuthorizeInput, type AuthorizeResult, type Decision, Riv, RivAuthError, RivError, RivInputError, RivNetworkError, RivNotFoundError, type RivOptions };

package/dist/index.js

@@ -0,0 +1,112 @@
+// src/index.ts
+var RivError = class extends Error {
+  code;
+  status;
+  constructor(code, message, status) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.status = status;
+  }
+};
+var RivAuthError = class extends RivError {
+  constructor(message = "Credencial inv\xE1lida.") {
+    super("unauthorized", message, 401);
+  }
+};
+var RivInputError = class extends RivError {
+  constructor(message) {
+    super("invalid_input", message, 400);
+  }
+};
+var RivNotFoundError = class extends RivError {
+  constructor(message = "Atividade n\xE3o encontrada.") {
+    super("not_found", message, 404);
+  }
+};
+var RivNetworkError = class extends RivError {
+  constructor(message) {
+    super("network_error", message);
+  }
+};
+var Riv = class {
+  #apiKey;
+  #baseUrl;
+  #timeoutMs;
+  constructor(options) {
+    if (!options?.apiKey) {
+      throw new RivAuthError("apiKey \xE9 obrigat\xF3ria (credencial riv_ do agente).");
+    }
+    this.#apiKey = options.apiKey;
+    this.#baseUrl = (options.baseUrl ?? "http://localhost:3000").replace(/\/+$/, "");
+    this.#timeoutMs = options.timeoutMs;
+  }
+  /**
+   * Pergunta ao Riv se uma transação é permitida ANTES de executá-la.
+   * Sem retry automático: cada chamada grava uma entrada no ledger.
+   */
+  async authorize(input) {
+    const data = await this.#request("POST", "/api/v1/authorize", input);
+    return data;
+  }
+  /** Consulta pontual: o registro de uma autorização pelo activityId. */
+  async activity(activityId) {
+    const qs = new URLSearchParams({ id: activityId });
+    const data = await this.#request("GET", `/api/v1/activities?${qs}`);
+    return data.activities[0];
+  }
+  /** Extrato: as atividades mais recentes do agente (padrão 10, máx. 50). */
+  async activities(options) {
+    const qs = new URLSearchParams();
+    if (options?.limit !== void 0) qs.set("limit", String(options.limit));
+    const suffix = qs.size > 0 ? `?${qs}` : "";
+    const data = await this.#request("GET", `/api/v1/activities${suffix}`);
+    return data.activities;
+  }
+  async #request(method, path, body) {
+    const controller = this.#timeoutMs !== void 0 ? new AbortController() : null;
+    const timer = controller && setTimeout(() => controller.abort(), this.#timeoutMs);
+    let res;
+    try {
+      res = await fetch(`${this.#baseUrl}${path}`, {
+        method,
+        headers: {
+          authorization: `Bearer ${this.#apiKey}`,
+          ...body !== void 0 ? { "content-type": "application/json" } : {}
+        },
+        ...body !== void 0 ? { body: JSON.stringify(body) } : {},
+        ...controller ? { signal: controller.signal } : {}
+      });
+    } catch (err) {
+      const aborted = err instanceof Error && err.name === "AbortError";
+      throw new RivNetworkError(
+        aborted ? `Timeout de ${this.#timeoutMs}ms ao chamar o Riv em ${this.#baseUrl}.` : `Erro de rede ao chamar o Riv em ${this.#baseUrl}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      const message = data?.message ?? `HTTP ${res.status}`;
+      switch (res.status) {
+        case 401:
+          throw new RivAuthError(message);
+        case 400:
+          throw new RivInputError(message);
+        case 404:
+          throw new RivNotFoundError(message);
+        default:
+          throw new RivError(data?.error ?? "api_error", message, res.status);
+      }
+    }
+    return data;
+  }
+};
+export {
+  Riv,
+  RivAuthError,
+  RivError,
+  RivInputError,
+  RivNetworkError,
+  RivNotFoundError
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@riv-io/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "SDK TypeScript do Riv — autorização de gastos e consulta do ledger para agentes de IA.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build",
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsup": "^8",
+    "typescript": "^5",
+    "vitest": "^4.1.8"
+  }
+}