deerdawn

DeerDawn Node.js SDK

Official Node.js client library for DeerDawn - AI governance and decision control platform.

Installation

npm install deerdawn

Quick Start

const { Deerdawn } = require('deerdawn');

// Initialize client
const deerdawn = new Deerdawn({
  apiKey: 'dd_prod_xxxxx' // Get from https://app.deerdawn.com/api-keys
});

// Evaluate a decision
const result = await deerdawn.evaluateDecision({
  action_type: 'send_email',
  trace_id: 'user-123-action-456',
  payload: {
    recipient: '[e-mail]',
    subject: 'Hello World'
  }
});

if (result.decision === 'allow') {
  console.log('Action allowed');
  // Proceed with sending email
} else {
  console.log('Action blocked:', result.reason);
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { Deerdawn, EvaluateDecisionRequest, EvaluateDecisionResponse } from 'deerdawn';

const deerdawn = new Deerdawn({
  apiKey: process.env.DEERDAWN_API_KEY!
});

const request: EvaluateDecisionRequest = {
  action_type: 'database_write',
  trace_id: 'req-789',
  payload: { table: 'users', operation: 'delete' }
};

const response: EvaluateDecisionResponse = await deerdawn.evaluateDecision(request);

Configuration

const deerdawn = new Deerdawn({
  apiKey: 'dd_prod_xxxxx',      // Required: Your API key
  baseUrl: 'https://api.deerdawn.com', // Optional: API base URL (default shown)
  timeout: 5000,                // Optional: Request timeout in ms (default: 5000)
  maxRetries: 3,                // Optional: Max retry attempts (default: 3)
  debug: false                  // Optional: Enable debug logging (default: false)
});

API Reference

evaluateDecision(request)

Evaluate an action against your policies.

Parameters:

• action_type (string, required): Type of action (e.g., "send_email", "database_write")
• trace_id (string, required): Unique trace identifier for correlation
• payload (object, optional): Additional context data

Returns: Promise<EvaluateDecisionResponse>

• decision: "allow" | "deny" | "escalate"
• reason: Human-readable explanation
• policy_id: ID of matched policy (if any)
• latency_ms: Evaluation latency
• decision_id: Decision log ID

Example:

const result = await deerdawn.evaluateDecision({
  action_type: 'refund_payment',
  trace_id: 'order-12345',
  payload: {
    amount: 99.99,
    currency: 'USD',
    reason: 'customer_request'
  }
});

console.log(`Decision: ${result.decision}`);
console.log(`Reason: ${result.reason}`);
console.log(`Latency: ${result.latency_ms}ms`);

listPolicies()

Get all policies for your organization.

Returns: Promise<Policy[]>

Example:

const policies = await deerdawn.listPolicies();

policies.forEach(policy => {
  console.log(`${policy.name}: ${policy.decision} (priority: ${policy.priority})`);
});

createPolicy(policy)

Create a new policy.

Parameters:

• name (string): Policy name
• action_types (string[]): Action types this policy applies to
• conditions (array): Condition expressions
• decision (string): "allow", "deny", or "escalate"
• priority (number): Evaluation priority (lower = higher priority)
• enabled (boolean): Whether policy is active
• description (string, optional): Policy description

Returns: Promise<Policy>

Example:

const policy = await deerdawn.createPolicy({
  name: 'Auto-approve refunds under $100',
  action_types: ['refund_payment'],
  conditions: [
    {
      field: 'payload.amount',
      operator: 'lt',
      value: 100
    }
  ],
  decision: 'allow',
  priority: 10,
  enabled: true,
  description: 'Automatically approve small refunds'
});

deletePolicy(policyId)

Delete a policy.

Parameters:

• policyId (string): Policy ID to delete

Returns: Promise<void>

Example:

await deerdawn.deletePolicy('pol_abc123');

listDecisions(filters?)

Get decision logs with optional filters.

Parameters:

• decision (string, optional): Filter by decision type ("allow", "deny", "escalate")
• trace_id (string, optional): Filter by trace ID

Returns: Promise<Decision[]>

Example:

// Get all denied decisions
const deniedDecisions = await deerdawn.listDecisions({ decision: 'deny' });

// Get decisions for a specific trace
const traceDecisions = await deerdawn.listDecisions({ trace_id: 'user-123' });

getDecision(decisionId)

Get a specific decision by ID.

Parameters:

• decisionId (string): Decision ID

Returns: Promise<Decision>

Example:

const decision = await deerdawn.getDecision('dec_xyz789');
console.log(decision.payload);

Error Handling

The SDK throws DeerDawnAPIError for API errors:

import { Deerdawn, DeerDawnAPIError } from 'deerdawn';

try {
  const result = await deerdawn.evaluateDecision({
    action_type: 'send_email',
    trace_id: 'test-123'
  });
} catch (error) {
  if (error instanceof DeerDawnAPIError) {
    console.error(`API Error (${error.status}): ${error.message}`);
    console.error(`Error code: ${error.code}`);
  } else {
    console.error('Unexpected error:', error);
  }
}

Common Error Codes

• 401 Unauthorized: Invalid API key
• 402 Payment Required: Plan limit exceeded
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error (automatically retried)

Retry Logic

The SDK automatically retries failed requests with exponential backoff:

• Retries on 5xx errors and network failures
• Default: 3 retry attempts
• Backoff: 1s, 2s, 4s

Configure retry behavior:

const deerdawn = new Deerdawn({
  apiKey: 'dd_prod_xxxxx',
  maxRetries: 5  // More aggressive retries
});

Debug Mode

Enable debug logging to troubleshoot issues:

const deerdawn = new Deerdawn({
  apiKey: 'dd_prod_xxxxx',
  debug: true
});

// Outputs:
// [DeerDawn] POST https://api.deerdawn.com/api/v1/decisions:evaluate
// [DeerDawn] Request body: { action_type: 'send_email', ... }
// [DeerDawn] Response status: 200
// [DeerDawn] Response body: { decision: 'allow', ... }

Examples

AI Agent with DeerDawn Guardrails

const { Deerdawn } = require('deerdawn');
const deerdawn = new Deerdawn({ apiKey: process.env.DEERDAWN_API_KEY });

async function executeAgentAction(actionType, params) {
  // Check permission before executing
  const decision = await deerdawn.evaluateDecision({
    action_type: actionType,
    trace_id: `agent-${Date.now()}`,
    payload: params
  });

  if (decision.decision === 'deny') {
    throw new Error(`Action blocked: ${decision.reason}`);
  }

  if (decision.decision === 'escalate') {
    console.log('Action requires human approval');
    // Queue for manual review
    return { status: 'pending', reason: decision.reason };
  }

  // Proceed with action
  return performAction(actionType, params);
}

// Use in your agent
await executeAgentAction('send_email', {
  recipient: '[e-mail]',
  subject: 'AI-generated report'
});

Express.js Middleware

const express = require('express');
const { Deerdawn } = require('deerdawn');

const app = express();
const deerdawn = new Deerdawn({ apiKey: process.env.DEERDAWN_API_KEY });

async function checkPermission(actionType) {
  return async (req, res, next) => {
    try {
      const decision = await deerdawn.evaluateDecision({
        action_type: actionType,
        trace_id: req.headers['x-trace-id'] || `req-${Date.now()}`,
        payload: {
          user: req.user,
          ...req.body
        }
      });

      if (decision.decision !== 'allow') {
        return res.status(403).json({
          error: 'forbidden',
          reason: decision.reason
        });
      }

      next();
    } catch (error) {
      res.status(500).json({ error: 'decision_check_failed' });
    }
  };
}

// Protect routes
app.post('/api/refunds', checkPermission('refund_payment'), (req, res) => {
  // Process refund
});

Support

• Documentation: https://deerdawn.com/docs
• API Reference: https://deerdawn.com/docs/api-reference
• Issues: https://github.com/deerdawn/deerdawn-sdk-node/issues
• Email: [e-mail]

License

MIT