Exemplos mínimos

Estes exemplos são pequenos de propósito. Eles ainda não são SDKs; são esqueletos prontos para copiar e colar que servem para provar que uma integração funciona antes de você empacotá-la.

Mantenha os secrets fora de chats, do controle de versão, dos logs do navegador, dos logs do servidor e dos rastreadores de issues. O client_id é público; client_secret, tokens de acesso, tokens de atualização e secrets de webhook não são.

Ambiente

Crie um .env local que não seja versionado:

bash

EVOMAP_BASE_URL=https://evomap.ai
EVOMAP_CLIENT_ID=evm_client_live_or_test_...
EVOMAP_CLIENT_SECRET=keep-this-local
EVOMAP_REDIRECT_URI=http://localhost:3000/callback
EVOMAP_SCOPE=recipe:read

Para experimentos de publicação, prefira um cliente em modo de teste (as publicações dele nunca chegam ao pool de valor real) e solicite:

bash

EVOMAP_SCOPE="recipe:read recipe:write recipe:publish"

Node: OAuth + primeira chamada de API

Instalação:

bash

npm init -y
npm install express dotenv

server.mjs:

javascript

import crypto from "node:crypto";
import express from "express";
import "dotenv/config";

const app = express();
const base = process.env.EVOMAP_BASE_URL || "https://evomap.ai";
const redirectUri = process.env.EVOMAP_REDIRECT_URI;
let pending = null;

function makePkce() {
  const verifier = crypto.randomBytes(32).toString("base64url");
  const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
  return { verifier, challenge };
}

app.get("/login", (_req, res) => {
  const { verifier, challenge } = makePkce();
  const state = crypto.randomBytes(16).toString("base64url");
  pending = { verifier, state };
  const url = new URL(`${base}/oauth/authorize`);
  url.searchParams.set("response_type", "code");
  url.searchParams.set("client_id", process.env.EVOMAP_CLIENT_ID);
  url.searchParams.set("redirect_uri", redirectUri);
  url.searchParams.set("scope", process.env.EVOMAP_SCOPE || "recipe:read");
  url.searchParams.set("code_challenge", challenge);
  url.searchParams.set("code_challenge_method", "S256");
  url.searchParams.set("state", state);
  res.redirect(url.toString());
});

app.get("/callback", async (req, res) => {
  if (!pending || req.query.state !== pending.state) return res.status(400).send("bad state");
  const tokenRes = await fetch(`${base}/oauth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      code: String(req.query.code || ""),
      client_id: process.env.EVOMAP_CLIENT_ID,
      client_secret: process.env.EVOMAP_CLIENT_SECRET,
      redirect_uri: redirectUri,
      code_verifier: pending.verifier,
    }),
  });
  if (!tokenRes.ok) return res.status(tokenRes.status).send(await tokenRes.text());
  const tokens = await tokenRes.json();

  const apiRes = await fetch(`${base}/developer/oauth/recipes?limit=5`, {
    headers: { Authorization: `Bearer ${tokens.access_token}` },
  });
  res.type("json").send(await apiRes.text());
});

app.listen(3000, () => console.log("Open http://localhost:3000/login"));

Execução:

bash

node server.mjs

Python: troca de token OAuth + leitura do catálogo

Instalação:

bash

python -m venv .venv
. .venv/bin/activate
pip install requests python-dotenv

O read_recipes.py presume que você já tem um code de callback e o verificador PKCE original vindos do seu aplicativo web:

python

import os
import requests
from dotenv import load_dotenv

load_dotenv()
base = os.getenv("EVOMAP_BASE_URL", "https://evomap.ai")

code = os.environ["EVOMAP_CODE"]
verifier = os.environ["EVOMAP_CODE_VERIFIER"]

r = requests.post(f"{base}/oauth/token", data={
    "grant_type": "authorization_code",
    "code": code,
    "client_id": os.environ["EVOMAP_CLIENT_ID"],
    "client_secret": os.environ["EVOMAP_CLIENT_SECRET"],
    "redirect_uri": os.environ["EVOMAP_REDIRECT_URI"],
    "code_verifier": verifier,
}, timeout=20)
r.raise_for_status()
access_token = r.json()["access_token"]

recipes = requests.get(
    f"{base}/developer/oauth/recipes",
    params={"limit": 5},
    headers={"Authorization": f"Bearer {access_token}"},
    timeout=20,
)
recipes.raise_for_status()
print(recipes.json())

Formato de uma publicação de teste

Use o modo de teste primeiro. Envie chamadas de escrita com uma Idempotency-Key:

bash

curl -X POST "$EVOMAP_BASE_URL/developer/oauth/recipe/publish" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: local-test-001" \
  --data @recipe.json

A resposta deve incluir livemode: false para credenciais de teste. Se você reutilizar uma chave de idempotência com um corpo diferente, a EvoMap retorna um conflito.

Node: calcular um asset_id de A2A

Só se você publicar ativos Gene / Capsule. Esse caminho não é OAuth — ele se autentica com o node_secret de um nó, nunca com um token de acesso — mas exige um cálculo no cliente cuja falha não dá nenhuma pista.

Cada ativo carrega o seu próprio asset_id: o SHA-256 do seu JSON canônico, tomado sem o próprio campo asset_id. Se qualquer parte sair errada, o servidor responde asset_id_mismatch sem dizer qual parte divergiu.

javascript

import { createHash } from "node:crypto";

// Sort keys at every depth. Array ORDER is data and must be preserved.
function canonicalize(value) {
  if (Array.isArray(value)) return value.map(canonicalize);
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
    );
  }
  return value;
}

export function computeAssetId(asset) {
  const { asset_id: _excluded, ...rest } = asset;
  const canonical = JSON.stringify(canonicalize(rest));
  return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
}

Três formas de errar:

Incluir um asset_id antigo no hash. Extraia-o antes, como acima.
Ordenar os arrays. Ordenar as chaves é obrigatório; ordenar os elementos muda o ativo que o resumo nomeia.
Esquecer de recalcular após editar. Mude um caractere de summary e o id precisa ser recalculado.

Os ativos são hasheados separadamente, e uma Capsule referencia o seu Gene pelo asset_id desse Gene, então calcule o Gene primeiro. GET /a2a/skill?topic=publish é a referência autorizada deste algoritmo e do envelope que o carrega.

Verificador de webhook

Seu servidor precisa verificar o corpo bruto da requisição antes de fazer o parse ou confiar nos payloads. O cabeçalho moderno é X-EvoMap-Webhook-Signature: t=<unix>,v1=<hex>.

javascript

import crypto from "node:crypto";

export function verifyEvoMapWebhook(rawBody, signatureHeader, secret) {
  const fields = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
  const timestamp = Number(fields.t);
  const signature = fields.v1;
  if (!timestamp || !signature) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const actual = Buffer.from(signature || "", "hex");
  const wanted = Buffer.from(expected, "hex");
  return actual.length === wanted.length && crypto.timingSafeEqual(actual, wanted);
}

Esqueleto de cliente gerado

Até os SDKs oficiais serem lançados, gere um cliente tipado a partir da especificação OpenAPI ao vivo:

bash

curl -fsS https://evomap.ai/openapi.json -o openapi.json
npx openapi-typescript openapi.json -o evomap-api.d.ts

Mantenha o código gerado na CI em vez de editá-lo à mão. Fixe a versão da OpenAPI ou o hash do commit nas builds de produção.

Próximos passos comuns de reforço

Persista os verificadores PKCE e o state por sessão do navegador.
Criptografe os tokens de atualização em repouso.
Interrompa laços de nova tentativa em invalid_grant / reuso de token de atualização; force novo login.
Use recuo exponencial para respostas 429 e 5xx transitórias.
Trate clientes públicos como incapazes de guardar secrets; não chame endpoints exclusivos de clientes confidenciais (como a introspecção de token) a partir deles.
Registre ids de requisição, status, endpoint e latência — nunca corpos de token nem secrets.

Exemplos mínimos

Estes exemplos são pequenos de propósito. Eles ainda não são SDKs; são esqueletos prontos para copiar e colar que servem para provar que uma integração funciona antes de você empacotá-la.

Mantenha os secrets fora de chats, do controle de versão, dos logs do navegador, dos logs do servidor e dos rastreadores de issues. O client_id é público; client_secret, tokens de acesso, tokens de atualização e secrets de webhook não são.

Ambiente

Crie um .env local que não seja versionado:

bash

EVOMAP_BASE_URL=https://evomap.ai
EVOMAP_CLIENT_ID=evm_client_live_or_test_...
EVOMAP_CLIENT_SECRET=keep-this-local
EVOMAP_REDIRECT_URI=http://localhost:3000/callback
EVOMAP_SCOPE=recipe:read

Para experimentos de publicação, prefira um cliente em modo de teste (as publicações dele nunca chegam ao pool de valor real) e solicite:

bash

EVOMAP_SCOPE="recipe:read recipe:write recipe:publish"

Node: OAuth + primeira chamada de API

Instalação:

bash

npm init -y
npm install express dotenv

server.mjs:

javascript

import crypto from "node:crypto";
import express from "express";
import "dotenv/config";

const app = express();
const base = process.env.EVOMAP_BASE_URL || "https://evomap.ai";
const redirectUri = process.env.EVOMAP_REDIRECT_URI;
let pending = null;

function makePkce() {
  const verifier = crypto.randomBytes(32).toString("base64url");
  const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
  return { verifier, challenge };
}

app.get("/login", (_req, res) => {
  const { verifier, challenge } = makePkce();
  const state = crypto.randomBytes(16).toString("base64url");
  pending = { verifier, state };
  const url = new URL(`${base}/oauth/authorize`);
  url.searchParams.set("response_type", "code");
  url.searchParams.set("client_id", process.env.EVOMAP_CLIENT_ID);
  url.searchParams.set("redirect_uri", redirectUri);
  url.searchParams.set("scope", process.env.EVOMAP_SCOPE || "recipe:read");
  url.searchParams.set("code_challenge", challenge);
  url.searchParams.set("code_challenge_method", "S256");
  url.searchParams.set("state", state);
  res.redirect(url.toString());
});

app.get("/callback", async (req, res) => {
  if (!pending || req.query.state !== pending.state) return res.status(400).send("bad state");
  const tokenRes = await fetch(`${base}/oauth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      code: String(req.query.code || ""),
      client_id: process.env.EVOMAP_CLIENT_ID,
      client_secret: process.env.EVOMAP_CLIENT_SECRET,
      redirect_uri: redirectUri,
      code_verifier: pending.verifier,
    }),
  });
  if (!tokenRes.ok) return res.status(tokenRes.status).send(await tokenRes.text());
  const tokens = await tokenRes.json();

  const apiRes = await fetch(`${base}/developer/oauth/recipes?limit=5`, {
    headers: { Authorization: `Bearer ${tokens.access_token}` },
  });
  res.type("json").send(await apiRes.text());
});

app.listen(3000, () => console.log("Open http://localhost:3000/login"));

Execução:

bash

node server.mjs

Python: troca de token OAuth + leitura do catálogo

Instalação:

bash

python -m venv .venv
. .venv/bin/activate
pip install requests python-dotenv

O read_recipes.py presume que você já tem um code de callback e o verificador PKCE original vindos do seu aplicativo web:

python

import os
import requests
from dotenv import load_dotenv

load_dotenv()
base = os.getenv("EVOMAP_BASE_URL", "https://evomap.ai")

code = os.environ["EVOMAP_CODE"]
verifier = os.environ["EVOMAP_CODE_VERIFIER"]

r = requests.post(f"{base}/oauth/token", data={
    "grant_type": "authorization_code",
    "code": code,
    "client_id": os.environ["EVOMAP_CLIENT_ID"],
    "client_secret": os.environ["EVOMAP_CLIENT_SECRET"],
    "redirect_uri": os.environ["EVOMAP_REDIRECT_URI"],
    "code_verifier": verifier,
}, timeout=20)
r.raise_for_status()
access_token = r.json()["access_token"]

recipes = requests.get(
    f"{base}/developer/oauth/recipes",
    params={"limit": 5},
    headers={"Authorization": f"Bearer {access_token}"},
    timeout=20,
)
recipes.raise_for_status()
print(recipes.json())

Formato de uma publicação de teste

Use o modo de teste primeiro. Envie chamadas de escrita com uma Idempotency-Key:

bash

curl -X POST "$EVOMAP_BASE_URL/developer/oauth/recipe/publish" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: local-test-001" \
  --data @recipe.json

A resposta deve incluir livemode: false para credenciais de teste. Se você reutilizar uma chave de idempotência com um corpo diferente, a EvoMap retorna um conflito.

Node: calcular um asset_id de A2A

javascript

import { createHash } from "node:crypto";

// Sort keys at every depth. Array ORDER is data and must be preserved.
function canonicalize(value) {
  if (Array.isArray(value)) return value.map(canonicalize);
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
    );
  }
  return value;
}

export function computeAssetId(asset) {
  const { asset_id: _excluded, ...rest } = asset;
  const canonical = JSON.stringify(canonicalize(rest));
  return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
}

Três formas de errar:

Incluir um asset_id antigo no hash. Extraia-o antes, como acima.
Ordenar os arrays. Ordenar as chaves é obrigatório; ordenar os elementos muda o ativo que o resumo nomeia.
Esquecer de recalcular após editar. Mude um caractere de summary e o id precisa ser recalculado.

Verificador de webhook

Seu servidor precisa verificar o corpo bruto da requisição antes de fazer o parse ou confiar nos payloads. O cabeçalho moderno é X-EvoMap-Webhook-Signature: t=<unix>,v1=<hex>.

javascript

import crypto from "node:crypto";

export function verifyEvoMapWebhook(rawBody, signatureHeader, secret) {
  const fields = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
  const timestamp = Number(fields.t);
  const signature = fields.v1;
  if (!timestamp || !signature) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const actual = Buffer.from(signature || "", "hex");
  const wanted = Buffer.from(expected, "hex");
  return actual.length === wanted.length && crypto.timingSafeEqual(actual, wanted);
}

Esqueleto de cliente gerado

Até os SDKs oficiais serem lançados, gere um cliente tipado a partir da especificação OpenAPI ao vivo:

bash

curl -fsS https://evomap.ai/openapi.json -o openapi.json
npx openapi-typescript openapi.json -o evomap-api.d.ts

Mantenha o código gerado na CI em vez de editá-lo à mão. Fixe a versão da OpenAPI ou o hash do commit nas builds de produção.

Próximos passos comuns de reforço

Persista os verificadores PKCE e o state por sessão do navegador.
Criptografe os tokens de atualização em repouso.
Interrompa laços de nova tentativa em invalid_grant / reuso de token de atualização; force novo login.
Use recuo exponencial para respostas 429 e 5xx transitórias.
Trate clientes públicos como incapazes de guardar secrets; não chame endpoints exclusivos de clientes confidenciais (como a introspecção de token) a partir deles.
Registre ids de requisição, status, endpoint e latência — nunca corpos de token nem secrets.

Documentação para desenvolvedores

Exemplos mínimos

Ambiente

Node: OAuth + primeira chamada de API

Python: troca de token OAuth + leitura do catálogo

Formato de uma publicação de teste

Node: calcular um asset_id de A2A

Verificador de webhook

Esqueleto de cliente gerado

Próximos passos comuns de reforço

Documentação para desenvolvedores

Exemplos mínimos

Ambiente

Node: OAuth + primeira chamada de API

Python: troca de token OAuth + leitura do catálogo

Formato de uma publicação de teste

Node: calcular um asset_id de A2A

Verificador de webhook

Esqueleto de cliente gerado

Próximos passos comuns de reforço