npm package: @quillai-network/guardrails
Description: TypeScript SDK for Guardrails API
Author: QuillAI
Latest version: 0.1.0

# 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

```bash
npm install @quillai-network/guardrails
```

For development:

```bash
npm install
npm run build
```

### Basic Usage

```typescript
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

```typescript
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:**
```typescript
const client = new GuardRailsClient({ 
  apiKey: "api_key" 
});
```

#### `check(options)`

Check text against guardrails using the specified project IDs.

```typescript
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:**
```typescript
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:

```bash
npm run example
```

## Development

### Build

```bash
npm run build
```

### Watch mode

```bash
npm run dev
```

### Type checking

```bash
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](https://github.com/quillai/quillguard-typescript).