最小示例

這些示例刻意寫得很小。它們還不是 SDK，而是可直接複製貼上的骨架，用來在正式封裝之前先證明整合真的能跑通。

密鑰不要出現在聊天、版本控制、瀏覽器日誌、伺服器日誌和問題追蹤系統裡。 client_id 是公開的；client_secret、存取權杖、刷新權杖和 webhook 密鑰都不是。

環境變數

創建一個不提交的本地 .env：

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

做發佈實驗時，優先用測試模式客戶端（它的發佈不會進入真實價值池），並申請：

bash

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

Node：OAuth + 第一次 API 調用

安裝：

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"));

運行：

bash

node server.mjs

Python：OAuth 換取權杖 + 讀取目錄

安裝：

bash

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

read_recipes.py 假設你已經從 web 應用那邊拿到了回調的 code 和當初的 PKCE verifier：

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())

測試發佈的請求形狀

先用測試模式。寫入類調用都要帶上 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

測試憑證的響應應當包含 livemode: false。如果你用同一個冪等鍵配了不同的請求體，EvoMap 會返回衝突。

Webhook 簽名驗證

你的伺服器必須先驗證原始請求體，再去解析和信任負載。當前使用的標頭是 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);
}

自動生成客戶端骨架

在官方 SDK 發佈之前，先用線上的 OpenAPI 規範生成一個帶類型的客戶端：

bash

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

生成的程式碼交給 CI 產出，不要手改。生產構建請把 OpenAPI 版本或 commit 哈希鎖定下來。

常見的後續加固步驟

按瀏覽器會話分別持久化 PKCE verifier 和 state。
對靜態存放的刷新權杖加密。
命中 invalid_grant / 刷新權杖重用時停止重試循環，強制重新登入。
對 429 和瞬時 5xx 響應採用指數退避。
把公開客戶端當作無法保管密鑰來對待；不要從公開客戶端調用僅限機密客戶端的端點（例如權杖內省）。
記錄 request id、狀態碼、端點和延遲 —— 永遠不要記錄權杖內容或密鑰。

最小示例

這些示例刻意寫得很小。它們還不是 SDK，而是可直接複製貼上的骨架，用來在正式封裝之前先證明整合真的能跑通。

密鑰不要出現在聊天、版本控制、瀏覽器日誌、伺服器日誌和問題追蹤系統裡。 client_id 是公開的；client_secret、存取權杖、刷新權杖和 webhook 密鑰都不是。

環境變數

創建一個不提交的本地 .env：

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

做發佈實驗時，優先用測試模式客戶端（它的發佈不會進入真實價值池），並申請：

bash

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

Node：OAuth + 第一次 API 調用

安裝：

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"));

運行：

bash

node server.mjs

Python：OAuth 換取權杖 + 讀取目錄

安裝：

bash

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

read_recipes.py 假設你已經從 web 應用那邊拿到了回調的 code 和當初的 PKCE verifier：

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())

測試發佈的請求形狀

先用測試模式。寫入類調用都要帶上 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

測試憑證的響應應當包含 livemode: false。如果你用同一個冪等鍵配了不同的請求體，EvoMap 會返回衝突。

Webhook 簽名驗證

你的伺服器必須先驗證原始請求體，再去解析和信任負載。當前使用的標頭是 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);
}

自動生成客戶端骨架

在官方 SDK 發佈之前，先用線上的 OpenAPI 規範生成一個帶類型的客戶端：

bash

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

生成的程式碼交給 CI 產出，不要手改。生產構建請把 OpenAPI 版本或 commit 哈希鎖定下來。

常見的後續加固步驟

按瀏覽器會話分別持久化 PKCE verifier 和 state。
對靜態存放的刷新權杖加密。
命中 invalid_grant / 刷新權杖重用時停止重試循環，強制重新登入。
對 429 和瞬時 5xx 響應採用指數退避。
把公開客戶端當作無法保管密鑰來對待；不要從公開客戶端調用僅限機密客戶端的端點（例如權杖內省）。
記錄 request id、狀態碼、端點和延遲 —— 永遠不要記錄權杖內容或密鑰。

開發者文件

最小示例

環境變數

Node：OAuth + 第一次 API 調用

Python：OAuth 換取權杖 + 讀取目錄

測試發佈的請求形狀

Webhook 簽名驗證

自動生成客戶端骨架

常見的後續加固步驟

開發者文件

最小示例

環境變數

Node：OAuth + 第一次 API 調用

Python：OAuth 換取權杖 + 讀取目錄

測試發佈的請求形狀

Webhook 簽名驗證

自動生成客戶端骨架

常見的後續加固步驟