Overview

The official EasyRAG JavaScript/TypeScript SDK makes it simple to integrate RAG capabilities into your application.

Installation

bash
npm install @easyrag/sdk

Quick Example

javascript
import { EasyRAG } from '@easyrag/sdk';

const client = new EasyRAG(process.env.EASYRAG_API_KEY);

// Upload files
await client.upload('my-dataset', [file1, file2]);

// Search
const results = await client.search('my-dataset', 'refund policy');

// Query
const answer = await client.query('my-dataset', 'Summarize the key points');

Why Use the SDK?

The SDK provides several advantages over direct API calls:

Developer Experience

• TypeScript Support - Full type definitions with autocomplete
• Streaming Made Easy - Async generators for real-time responses
• Simple API - Intuitive methods instead of raw HTTP
• Error Handling - Custom error class with detailed information

Convenience

• No Manual FormData - File uploads handled automatically
• Automatic Headers - Authentication managed for you
• Timeout Management - Configurable request timeouts
• Clean Code - Write less boilerplate

Example Comparison

Without SDK:

javascript
const formData = new FormData();
formData.append('datasetId', 'my-dataset');
formData.append('file', file);

const response = await fetch('https://api.easyrag.com/v1/files/upload', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`
  },
  body: formData
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const result = await response.json();

With SDK:

javascript
const result = await client.upload('my-dataset', file);

Features

All Endpoints Covered

• ✅ File upload (single/multiple, with metadata)
• ✅ File management (list, get, delete)
• ✅ Semantic search (with filters)
• ✅ AI queries (streaming and non-streaming)
• ✅ Frontend token creation

Production Ready

• ✅ Zero runtime dependencies
• ✅ Works in Node.js and browsers
• ✅ TypeScript support
• ✅ Error handling
• ✅ Request timeouts
• ✅ 8KB compressed

Platform Support

Node.js (18+)

javascript
import { EasyRAG } from '@easyrag/sdk';
import fs from 'fs';

const client = new EasyRAG(process.env.EASYRAG_API_KEY);

// Upload from filesystem
const file = new File(
  [fs.readFileSync('document.pdf')],
  'document.pdf',
  { type: 'application/pdf' }
);

await client.upload('dataset', file);

Browser (with Token)

javascript
// Backend generates token
const { token } = await client.createToken('user-dataset', { 
  ttlSeconds: 3600 
});

// Frontend uses token
const frontendClient = new EasyRAG(token);
await frontendClient.search('user-dataset', 'query');

⚠️ Never use API keys in the browser. Use frontend tokens generated from your backend.

TypeScript Support

Full TypeScript support with autocomplete:

typescript
import { EasyRAG, type SearchResponse, type UploadResponse } from '@easyrag/sdk';

const client = new EasyRAG(apiKey);

const upload: UploadResponse = await client.upload('dataset', files);
const results: SearchResponse = await client.search('dataset', 'query');

Error Handling

The SDK provides a custom error class with detailed information:

javascript
import { EasyRAGError } from '@easyrag/sdk';

try {
  await client.upload('dataset', file);
} catch (error) {
  if (error instanceof EasyRAGError) {
    console.log('Status:', error.status);    // 402
    console.log('Code:', error.code);        // "INSUFFICIENT_CREDITS"
    console.log('Message:', error.message);  // "Out of credits"
    console.log('Details:', error.details);  // { required: 10, available: 5 }
  }
}

Initialization Options

javascript
// Simple
const client = new EasyRAG('YOUR_API_KEY');

// With custom options
const client = new EasyRAG({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://api.easyrag.com',  // Optional
  timeout: 30000                        // Optional (default: 30s)
});

Cost Overview

Method Overview

Next Steps

• Quick Start - Get started in 5 minutes
• Methods - Complete method reference
• Examples - Common usage patterns

Resources

• GitHub - Source code
• NPM - Package
• Changelog - Release notes