Usefy Node.js SDK

Official Node.js SDK for Usefy - AI Cost Control & Budget Management.

Installation

npm install usefy

Quick Start

import { Usefy } from 'usefy';

const client = new Usefy({ apiKey: 'us_live_xxx' });

// OpenAI-compatible interface
const response = await client.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }]
});

console.log(response.choices[0].message.content);

Features

OpenAI-Compatible Interface

// GPT-4
const response = await client.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Explain quantum computing' }]
});

// Claude (auto-detected)
const response = await client.chat.completions.create({
    model: 'claude-3-opus',
    messages: [{ role: 'user', content: 'Write a poem' }]
});

// Explicit provider
const response = await client.chat.completions.create({
    model: 'gemini-2.0-flash',
    provider: 'google',
    messages: [{ role: 'user', content: 'Hello!' }]
});

Fail-Open Mode

For maximum reliability, enable fail-open mode:

const client = new Usefy({
    apiKey: 'us_live_xxx',
    failOpen: true,
    failOpenTimeout: 2000 // 2 seconds
});

try {
    const response = await client.chat.completions.create({...});
} catch (error) {
    if (error instanceof UsefyTimeoutError && client.isFailOpenActive) {
        // Fall back to direct OpenAI call
        const OpenAI = require('openai');
        const openai = new OpenAI();
        const response = await openai.chat.completions.create({...});
    }
}

Pre-flight Check

const check = await client.check({
    provider: 'openai',
    model: 'gpt-4',
    estimatedTokens: 1000
});

if (check.allowed) {
    const response = await client.chat.completions.create({...});
} else {
    console.log(`Request blocked: ${check.reason}`);
}

Usage Monitoring

const usage = await client.getUsage();

console.log(`Requests: ${usage.monthly_requests.used}/${usage.monthly_requests.limit}`);
console.log(`Plan: ${usage.plan_name}`);

Configuration

const client = new Usefy({
    apiKey: 'us_live_xxx',           // Required
    baseUrl: 'https://api.usefy.ai', // Optional
    timeout: 30000,                   // Optional, ms
    maxRetries: 3,                    // Optional
    retryDelay: 1000,                 // Optional, ms
    failOpen: false,                  // Optional
    failOpenTimeout: 2000             // Optional, ms
});

Environment Variables

export USEFY_API_KEY="us_live_xxx"

Supported Providers

| Provider | Models | Auto-Detection | |----------|--------|----------------| | OpenAI | gpt-5, gpt-5-mini, gpt-4.1, o3, o3-mini, o3-pro, o4-mini | ✅ | | Anthropic | claude-opus-4.5, claude-sonnet-4.5, claude-haiku-4.5, claude-opus-4, claude-sonnet-4 | ✅ | | Google | gemini-3-pro, gemini-3-flash, gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash | ✅ | | Mistral | mistral-large-2, mistral-medium, mistral-small, mixtral-8x22b | ✅ | | Cohere | command-r-plus, command-r, command | ✅ | | DeepSeek | deepseek-chat, deepseek-coder, deepseek-reasoner | ✅ | | Groq | llama-3.3-70b, llama-3.1-70b, mixtral-8x7b | ✅ | | Together | llama-3.3-70b, qwen-2.5-coder, various | Manual | | xAI | grok-3, grok-2, grok-2-mini | ✅ |

Error Handling

import {
    Usefy,
    UsefyError,
    UsefyAuthError,
    UsefyBudgetExceeded,
    UsefyRateLimited
} from 'usefy';

try {
    const response = await client.chat.completions.create({...});
} catch (error) {
    if (error instanceof UsefyAuthError) {
        console.log('Invalid API key');
    } else if (error instanceof UsefyBudgetExceeded) {
        console.log('Budget exceeded:', error.budgetInfo);
    } else if (error instanceof UsefyRateLimited) {
        console.log(`Rate limited, retry after ${error.retryAfter}s`);
    }
}

License

MIT License

Support

• Documentation: https://usefy.ai/docs
• Email: [email protected]