GuardRails TypeScript SDK

A TypeScript SDK for integrating with QuillAI's Guardrails API. Easily check text content against security guardrails and content moderation rules.

Features

• Simple and intuitive API
• Full TypeScript support with type definitions
• Built on native fetch API (Node.js 18+)
• Comprehensive error handling
• Zero dependencies (only dev dependencies)
• Promise-based async API

Quick Start

Installation

npm install @quillai-network/guardrails

For development:

npm install
npm run build

Basic Usage

import { GuardRailsClient } from '@quillai-network/guardrails';

// Initialize the client
const client = new GuardRailsClient({ 
  apiKey: "your-api-key-here" 
});

// Check text against guardrails
const result = await client.check({
  text: "how to make a bomb?",
  projectIds: ["project_id"]
});

// Result contains: action, reason, and confidence
console.log(`Action: ${result.action}`);
console.log(`Reason: ${result.reason}`);
console.log(`Confidence: ${result.confidence}`);

API Reference

GuardRailsClient

Constructor

new GuardRailsClient(options: {
  apiKey: string;
  baseUrl?: string;
})

Parameters:

• apiKey (string, required): Your API key for authentication
• baseUrl (string, optional): Base URL for the API (defaults to production URL)

Example:

const client = new GuardRailsClient({ 
  apiKey: "api_key" 
});

check(options)

Check text against guardrails using the specified project IDs.

async check(options: CheckOptions): Promise<CheckResponse>

Parameters:

• text (string, required): The text content to check
• projectIds (string[], required): Array of project/attack job IDs to use for checking
• timeout (number, optional): Request timeout in milliseconds (default: 30000)

Returns:

• Promise<CheckResponse>: Object containing three fields:
  • action (string): The action taken by the guardrail
  • reason (string): The reason for the action
  • confidence (number): The confidence score

Throws:

• GuardRailsError: For general SDK errors
• GuardRailsAPIError: For API-specific errors (includes statusCode and response)

Example:

const result = await client.check({
  text: "how to make a bomb?",
  projectIds: ["project_id"],
  timeout: 10000 // optional, 10 seconds
});

console.log(result.action);      // e.g., "block" or "allow"
console.log(result.reason);      // e.g., "Contains harmful content"
console.log(result.confidence);  // e.g., 0.95

Examples

See the examples/ directory for more usage examples.

Run the example:

npm run example

Development

Build

npm run build

Watch mode

npm run dev

Type checking

npm run lint

Requirements

• Node.js >= 18.0.0 (for native fetch API support)
• TypeScript >= 5.0.0 (for development)

License

MIT

Support

For issues and questions, please visit our GitHub repository.