@creed-space/sdk

Official TypeScript SDK for Creed Space - governance infrastructure for AI agents.

Installation

npm install @creed-space/sdk
# or
yarn add @creed-space/sdk
# or
pnpm add @creed-space/sdk

Quick Start

import { createClient } from '@creed-space/sdk';

const client = createClient({
  apiKey: process.env.CREED_API_KEY!,
});

// Get a governance decision for a tool call
const result = await client.decide({
  toolName: 'send_email',
  arguments: {
    to: '[email protected]',
    subject: 'Hello',
  },
  onAllow: (decision) => {
    console.log('Authorized:', decision.decisionToken);
    // Execute the tool with the signed token
  },
  onDeny: (decision) => {
    console.log('Denied:', decision.reasons);
  },
});

Features

• Governance Decisions - Get ALLOW/DENY decisions for tool calls
• Cryptographic Tokens - Signed JWT tokens for authorization proof
• Callback Flow Control - onAllow, onDeny, onRequireHuman callbacks
• Audit Trail - Query tamper-evident hash-chain audit logs
• TypeScript Native - Full type definitions included

API Reference

createClient(options)

Create a new Creed Space client.

const client = createClient({
  apiKey: 'crd_live_...', // Required: Your API key
  baseUrl: 'https://api.creed.space', // Optional: Custom API URL
  timeoutMs: 30000, // Optional: Request timeout (default: 30s)
  fetch: customFetch, // Optional: Custom fetch implementation
});

client.decide(request)

Get a governance decision for a tool call.

interface DecideRequest {
  toolName: string; // Tool to execute
  arguments: Record<string, unknown>; // Tool arguments
  constitutionId?: string; // Constitution ID (default: 'default')
  context?: {
    tenantId?: string;
    projectId?: string;
    userId?: string;
    sessionId?: string;
  };
  onAllow?: (decision: AllowDecision) => void | Promise<void>;
  onDeny?: (decision: DenyDecision) => void | Promise<void>;
  onRequireHuman?: (decision: RequireHumanDecision) => void | Promise<void>;
}

const result = await client.decide({
  toolName: 'send_email',
  arguments: { to: '[email protected]' },
  onAllow: async (decision) => {
    // Execute the tool
    await sendEmail(decision.decisionToken);
  },
});

client.authorize(request)

Verify a decision token before execution.

const auth = await client.authorize({
  decisionToken: result.decisionToken,
  toolName: 'send_email', // Optional: verify tool name matches
});

if (auth.authorized) {
  console.log('Token valid until:', auth.claims?.expiresAt);
}

client.audit(request)

Query the audit trail for a run.

const audit = await client.audit({
  runId: 'run_123',
  limit: 50,
});

console.log('Events:', audit.events);
console.log('Integrity verified:', audit.integrity.verified);

client.status()

Get service status and feature availability.

const status = await client.status();
console.log('Service:', status.service);
console.log('Features:', status.features);

Utilities

computeArgsHash(args)

Compute SHA-256 hash of arguments for verification.

import { computeArgsHash } from '@creed-space/sdk';

const hash = await computeArgsHash({ to: '[email protected]' });
// 'sha256:...'

isTokenExpired(token)

Check if a decision token is expired.

import { isTokenExpired } from '@creed-space/sdk';

if (isTokenExpired(token)) {
  // Request a new decision
}

Error Handling

import { createClient, CreedError } from '@creed-space/sdk';

try {
  await client.decide({ ... });
} catch (error) {
  if (error instanceof CreedError) {
    console.error('Code:', error.code);
    console.error('Status:', error.statusCode);
  }
}

Error codes:

• MISSING_API_KEY - API key not provided
• REQUEST_FAILED - API request failed
• NETWORK_ERROR - Network connectivity issue
• TIMEOUT - Request timed out

Decision Types

| Decision | Status | Description | |----------|--------|-------------| | ALLOW | Active | Tool execution authorized | | DENY | Active | Tool execution blocked | | REQUIRE_HUMAN | Planned | Human review required | | REQUIRE_STEPUP | Planned | Step-up authentication required |

Requirements

• Node.js 18+
• TypeScript 5.0+ (for type definitions)

License

MIT