TypeScript SDK

@confirm/sdk is the fastest way to add human approvals to a TypeScript or JavaScript agent. It ships the policy engine, a single-tool wrapper, the API client, and webhook verification. Zero runtime dependencies, ESM, Node 18+.

terminal

npm i @confirm/sdk

Set CONFIRM_API_KEY in your environment (create a key under Dashboard → API Keys).

Guard your whole tool layer

Don't hand-wrap every risky tool. Wrap the toolset once and let policies decide what needs a human. With default: "require" it is fail-closed: a tool nobody wrote a rule for is still gated, so nothing slips through unwrapped.

guard.ts

import { guard } from "@confirm/sdk";

const tools = guard(agentTools, {
  policies: [
    { when: (t) => t.name.startsWith("delete_"),                     notify: "security@acme.com" },
    { when: (t) => t.name === "refund" && t.args.amount > 500,       notify: "finance@acme.com" },
    { when: (t) => t.name === "send_email" && isExternal(t.args.to), notify: "me@acme.com" },
    { when: (t) => t.name === "search", decision: "allow" }, // read-only, never gated
  ],
  default: "require", // fail-closed
});

Policies are evaluated in order and the first match wins. A matched policy gates the call by default (decision: "require"); use decision: "allow" to exempt safe tools. When a human edits the payload, the tool runs with the edited version.

WORKS ON HOBBY

guard() and withApproval() work on every plan, including the free Hobby tier — they just create approval requests. Notify a single email address (Hobby includes 100 approvals/month). The one thing that needs Pro is a policy that routes to an approver group (notify: "group:..."); see plans.

WHY POLICIES

The model is the thing you are guarding. Deterministic policies are the security floor: they cannot be forgotten or prompt-injected away. Use the MCP server and the agent skill on top for long-tail coverage, but keep the boundary deterministic.

Gate a single function

with-approval.ts

import { withApproval } from "@confirm/sdk";

const safeRefund = withApproval(refund, {
  notify: "finance@acme.com",
  summary: (a) => `Refund $${a.amount} to ${a.customerId}`,
  reasoning: (a) => a.reason,
});

await safeRefund({ amount: 10000, customerId: "4821", reason: "double charge" });
// pauses -> human approves/edits -> runs with the approved payload
// throws ApprovalRejectedError / ApprovalExpiredError otherwise

By default the call arguments are the payload the approver sees and edits, so edits flow straight back into the call. Set a custom payload (and applyEdits) when your action shape differs from your function signature.

Low-level client

client.ts

import { ConfirmClient } from "@confirm/sdk";

const confirm = new ConfirmClient(); // reads CONFIRM_API_KEY

const req = await confirm.requests.create({
  summary: "Deploy api@9f2a1c to production",
  notify: "group:platform",           // escalate to an approver group
  payload: { service: "api", sha: "9f2a1c" },
  agentState: { threadId, step: 7 },  // rehydrate from the webhook later
  ttlMinutes: 60,
});

const resolved = await confirm.requests.wait(req.id, { timeoutMs: 3_600_000 });
if (resolved.status === "APPROVED") execute(resolved.effectivePayload);

For long waits, prefer webhooks over polling: let the agent yield and resume when the signed webhook arrives.

Verify webhooks

route.ts

import { constructEvent } from "@confirm/sdk";

// Read the RAW request body (do not re-serialize).
const event = constructEvent({
  payload: rawBody,
  signature: req.headers["x-confirm-signature"],
  secret: process.env.CONFIRM_WEBHOOK_SECRET,
});

if (event.event === "request.approved") {
  execute(event.data.effectivePayload); // the human-edited action
}

constructEvent verifies the HMAC-SHA256 signature in constant time and rejects stale timestamps, throwing WebhookVerificationError on any mismatch.

Frameworks

guard() works with any framework. See the Vercel AI SDK guide for wrapping tool() definitions, and the frameworks overview for LangChain, LangGraph, OpenAI Agents, and CrewAI. For MCP agents (Claude Desktop, Cursor), the MCP server adds an approval tool with no code.