TypeScript SDK

The official TypeScript SDK for the ARQERA governance API.

npm install @arqera/sdk

Requirements: Node.js 18+ or any modern runtime (Deno, Bun)

Quick Start

import { ArqeraClient } from "@arqera/sdk";

const client = new ArqeraClient({ apiKey: "ak_your_key_here" });

const result = await client.governance.evaluate({
  action: "email.send",
  description: "Send welcome email to new user",
});

if (result.passed) {
  console.log("Safe to proceed");
  await sendEmail();
} else if (result.needsApproval) {
  console.log(`Needs review: ${result.explanation}`);
  await queueForApproval();
} else {
  console.log(`Blocked: ${result.explanation}`);
  logBlocked();
}

Installation

npm install @arqera/sdk

Or with your preferred package manager:

# Yarn
yarn add @arqera/sdk

# pnpm
pnpm add @arqera/sdk

# Bun
bun add @arqera/sdk

Client Configuration

import { ArqeraClient } from "@arqera/sdk";

const client = new ArqeraClient({
  apiKey: "ak_your_key_here",            // Required
  baseUrl: "https://api.arqera.io",       // Optional (default)
  timeout: 30000,                         // Request timeout in ms
});

Environment Variable

The client reads ARQERA_API_KEY from the environment if no key is provided:

const client = new ArqeraClient(); // Reads from process.env.ARQERA_API_KEY

Governance Evaluation

Basic Evaluation

const result = await client.governance.evaluate({
  action: "data.read",
  description: "Read dashboard metrics",
});

console.log(result.verdict);     // "proceed" | "escalate" | "block"
console.log(result.explanation); // Human-readable explanation
console.log(result.durationMs);  // Evaluation time in milliseconds
console.log(result.passed);      // true if verdict is "proceed"

With Context

const result = await client.governance.evaluate({
  action: "payment.process",
  description: "Process $4,200 vendor payment",
  context: {
    risk_level: "medium",
    is_irreversible: true,
    has_approval: true,
    estimated_cost_usd: 4200,
  },
});

Inspecting Law Evaluations

const result = await client.governance.evaluate({
  action: "data.delete",
  description: "Delete user data",
});

for (const evaluation of result.evaluations) {
  console.log(`${evaluation.lawName}: ${evaluation.result}`);
  console.log(`  Reason: ${evaluation.reason}`);
  console.log(`  Time: ${evaluation.durationMs.toFixed(2)}ms`);
}

Type Definitions

interface GovernanceResult {
  verdict: "proceed" | "escalate" | "block";
  action: string;
  explanation: string;
  durationMs: number;
  evaluatedAt: string;
  evaluations: LawEvaluation[];

  // Convenience getters
  passed: boolean;
  needsApproval: boolean;
  blocked: boolean;
}

interface LawEvaluation {
  lawId: string;
  lawName: string;
  result: "pass" | "warn" | "fail";
  reason: string;
  details: Record<string, unknown>;
  durationMs: number;
}

interface EvaluateRequest {
  action: string;
  description?: string;
  context?: Record<string, unknown>;
}

Middleware Pattern

Use ARQERA as Express/Fastify middleware:

import { ArqeraClient } from "@arqera/sdk";
import type { Request, Response, NextFunction } from "express";

const arqera = new ArqeraClient();

function governanceGate(action: string) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const result = await arqera.governance.evaluate({
      action,
      description: `${req.method} ${req.path}`,
      context: {
        user_id: req.user?.id,
        ip: req.ip,
      },
    });

    if (result.blocked) {
      return res.status(403).json({
        error: "Action blocked by governance",
        explanation: result.explanation,
      });
    }

    if (result.needsApproval) {
      return res.status(202).json({
        error: "Action requires approval",
        explanation: result.explanation,
      });
    }

    next();
  };
}

// Usage
app.delete("/users/:id", governanceGate("user.delete"), async (req, res) => {
  // Only reached if governance allows it
  await deleteUser(req.params.id);
  res.json({ deleted: true });
});

Error Handling

import {
  ArqeraAuthError,
  ArqeraRateLimitError,
  ArqeraValidationError,
  ArqeraError,
} from "@arqera/sdk";

try {
  const result = await client.governance.evaluate({
    action: "data.delete",
  });
} catch (error) {
  if (error instanceof ArqeraAuthError) {
    console.error("Invalid or expired API key");
  } else if (error instanceof ArqeraRateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof ArqeraValidationError) {
    console.error(`Invalid request: ${error.detail}`);
  } else if (error instanceof ArqeraError) {
    console.error(`API error: ${error.message}`);
  }
}

Next.js Integration

// app/api/ai/generate/route.ts
import { ArqeraClient } from "@arqera/sdk";
import { NextResponse } from "next/server";

const arqera = new ArqeraClient();

export async function POST(request: Request) {
  const { prompt } = await request.json();

  // Check governance before generating
  const governance = await arqera.governance.evaluate({
    action: "ai.generate",
    description: prompt,
    context: { estimated_cost_usd: 0.05 },
  });

  if (!governance.passed) {
    return NextResponse.json(
      { error: governance.explanation },
      { status: governance.blocked ? 403 : 202 }
    );
  }

  // Governance passed — safe to generate
  const aiResponse = await generateWithAI(prompt);
  return NextResponse.json({ response: aiResponse });
}

Full Example

See the Governed AI Agent guide for a complete working example.