@auxdynamics/mastguard-sdk

Official TypeScript SDK for the MastGuard AI Governance Platform.

Wrap the MastGuard REST API in a clean, fully-typed, zero-dependency client.

Installation

npm install @auxdynamics/mastguard-sdk

Quick Start

import { MastGuardClient } from "@auxdynamics/mastguard-sdk";

const client = new MastGuardClient({ apiKey: process.env.MASTGUARD_API_KEY! });

const decision = await client.governance.ingest({
  agentId: "trade-agent-01",
  actionType: "PAYMENT_APPROVE",
  payload: { symbol: "AAPL", quantity: 100 },
});

if (decision.decision === "BLOCK") {
  throw new Error("Action blocked by governance policy");
}

Authentication

Issue an API key from your MastGuard dashboard → Developer page. The SDK sends it as the X-API-Key header on every request.

Configuration

| Option | Default | Description | | ------------ | ----------------------------- | ----------------------------------------------- | | apiKey | (required) | Your MastGuard API key. | | baseUrl | https://api.mastguard.io | Override for self-hosted / staging environments.| | timeout | 30000 | Per-request timeout in milliseconds. | | retries | 3 | Retry attempts for 429 / 5xx / network errors. | | retryDelay | 1000 | Base delay for exponential backoff. | | onError | undefined | Hook fired on every error (including retries). | | fetch | globalThis.fetch | Inject a custom fetch (mostly for tests). |

Resources

client.governance.ingest({...})        // POST /api/v1/governance/ingest
client.governance.getDashboard()       // GET  /api/v1/governance/dashboard
client.governance.getAgents()          // GET  /api/v1/governance/agents
client.governance.getPolicies()        // GET  /api/v1/governance/policies

client.hitl.getQueue({ status, page, limit })           // GET  /api/v1/hitl/queue
client.hitl.getTask(taskId)                             // GET  /api/v1/hitl/queue/:id
client.hitl.approve(taskId, { rationale })              // POST /api/v1/hitl/queue/:id/approve
client.hitl.reject(taskId, { rationale })               // POST /api/v1/hitl/queue/:id/reject
client.hitl.getAuditLog({ agentId, decision, ... })     // GET  /api/v1/hitl/audit

client.webhooks.list()
client.webhooks.create({ name, url, eventTypes })
client.webhooks.delete(webhookId)

Webhook Signature Verification

MastGuard signs every outbound webhook with HMAC-SHA256 in the X-MastGuard-Signature header (format: sha256=<hex>).

import { MastGuardWebhooks } from "@auxdynamics/mastguard-sdk";

const valid = await MastGuardWebhooks.verifySignature(
  rawBody,                         // raw request body (string or Uint8Array)
  request.headers["x-mastguard-signature"],
  process.env.WEBHOOK_SIGNING_SECRET!,
);
if (!valid) return new Response("invalid signature", { status: 401 });

Works in Node.js 18+ and Edge runtimes (Cloudflare Workers, Vercel Edge).

Error Handling

All errors extend MastGuardError. Catch the base class for blanket handling or use instanceof for specific responses.

import { ConflictError, RateLimitError } from "@auxdynamics/mastguard-sdk";

try {
  await client.hitl.approve(id, { rationale: "Verified by treasury." });
} catch (err) {
  if (err instanceof ConflictError) {
    // Already approved, expired, or in a non-actionable state.
  } else if (err instanceof RateLimitError) {
    // Honour err.retryAfterSeconds.
  } else {
    throw err;
  }
}

| HTTP status | Class | | ----------- | --------------------- | | 401 | AuthenticationError | | 403 | AuthorizationError | | 404 | NotFoundError | | 409 | ConflictError | | 422 | ValidationError | | 429 | RateLimitError | | 5xx | ServerError | | (network) | NetworkError | | (timeout) | TimeoutError |

Requirements

• Node.js 18+ (uses native fetch).
• For Node 16, install a fetch polyfill (e.g. undici) and pass it via the fetch config option.

TypeScript

Full TypeScript support is included — no @types package needed. CJS and ESM builds are both shipped.

License

MIT © MAST Guard Inc.