Package Exports

usefy
usefy/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (usefy) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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: support@usefy.ai