TypeScript SDK

SDK Guide

The @drd/sdk package provides a TypeScript-first client for integrating DRD governance into your AI agents.

Installation

Install the @drd/sdk package from npm, yarn, or pnpm.

terminal

npm install @drd/sdk
# or
yarn add @drd/sdk
# or
pnpm add @drd/sdk

Initialization

Create a DRD client instance with your API key. The SDK handles token exchange, batching, and retries automatically.

init.ts

import { DRD } from '@drd/sdk';

const drd = new DRD({
  apiKey: process.env.DRD_API_KEY,
  // Optional: override base URL
  // baseUrl: 'https://api.drd.io/api/v1',
});

Guard — Check Permissions

Before performing any action, call guard() to check if the action is allowed by your policies.

guard.ts

const result = await drd.guard('send_email', {
  to: '[email protected]',
  subject: 'Weekly digest',
});

if (result.allowed) {
  // Action is permitted — proceed
  await sendEmail(result.context);
} else {
  // Action denied — check result.reason
  console.log('Denied:', result.reason);
  console.log('Policy:', result.policyId);
}

// If approval is required
if (result.requiresApproval) {
  const approval = await drd.waitForApproval(result.approvalId);
  if (approval.decision === 'approved') {
    await sendEmail(result.context);
  }
}

Report — Log Events

After performing an action, report it to build your agent's reputation and maintain the audit trail.

report.ts

// Report a single event
await drd.report('email.sent', {
  to: '[email protected]',
  subject: 'Weekly digest',
});

// Events are batched automatically
// Flush happens every 5 seconds or when batch reaches 50 events
// Call shutdown() to flush remaining events
await drd.shutdown();

Trust Score

Retrieve your agent's current trust score, component breakdown, and badge tier.

trust-score.ts

const score = await drd.getTrustScore();
console.log(score.overall);     // 0-100
console.log(score.components);  // { reliability, compliance, efficiency, consistency, tenure }
console.log(score.badge);       // 'bronze' | 'silver' | 'gold' | 'government' | null

Error Handling

The SDK provides typed error classes for common failure modes.

errors.ts

import { DRDDeniedError, DRDTimeoutError, DRDNetworkError } from '@drd/sdk';

try {
  await drd.guard('transfer_funds', { amount: 10000 });
} catch (error) {
  if (error instanceof DRDDeniedError) {
    // Policy explicitly denied this action
    console.log('Denied by policy:', error.policyId);
  } else if (error instanceof DRDTimeoutError) {
    // Request timed out
  } else if (error instanceof DRDNetworkError) {
    // Network connectivity issue
  }
}

Lifecycle

Always call shutdown() when your agent is done to flush any remaining batched events and clean up resources.

lifecycle.ts

process.on('SIGTERM', async () => {
  await drd.shutdown();
  process.exit(0);
});

Next Steps

API Reference

All REST endpoints and response formats

Learn more →

Webhooks

Subscribe to governance events in real-time

Learn more →

Trust Badges

Earn certification through compliance

Learn more →

// Report a single event await drd.report('email.sent', { to: '[email protected]', subject: 'Weekly digest', }); // Events are batched automatically // Flush happens every 5 seconds or when batch reaches 50 events // Call shutdown() to flush remaining events await drd.shutdown();

const score = await drd.getTrustScore(); console.log(score.overall); // 0-100 console.log(score.components); // { reliability, compliance, efficiency, consistency, tenure } console.log(score.badge); // 'bronze' | 'silver' | 'gold' | 'government' | null

import { DRDDeniedError, DRDTimeoutError, DRDNetworkError } from '@drd/sdk'; try { await drd.guard('transfer_funds', { amount: 10000 }); } catch (error) { if (error instanceof DRDDeniedError) { // Policy explicitly denied this action console.log('Denied by policy:', error.policyId); } else if (error instanceof DRDTimeoutError) { // Request timed out } else if (error instanceof DRDNetworkError) { // Network connectivity issue } }