🪙 xTokenCounter

Librería universal en TypeScript / Node.js para contar tokens, calcular costos oficiales en tiempo real de OpenAI (ChatGPT), Anthropic (Claude), DeepSeek y Google Gemini, y aplicar márgenes de ganancia personalizables para cobrar a tus clientes finales.

📦 Instalación

npm install xtokencounter

o si estás en desarrollo local dentro de tu monorepo/proyectos:

npm link

🌐 1. Sincronización de Precios en Tiempo Real (Remote Sync)

Si mañana DeepSeek, OpenAI, Claude o Google cambian sus precios, tu aplicación los actualizará automáticamente en tiempo real sin necesidad de modificar código ni re-desplegar tu servidor.

import { syncLLMPricing, calculateCost } from 'xtokencounter';

// Al iniciar tu servidor (Express, NestJS, Next.js, Fastify):
await syncLLMPricing(); // Sincroniza el catálogo más reciente con caché automática de 24h

// Todos los cálculos posteriores usarán los precios del mercado actualizados:
const cost = calculateCost('deepseek-v3', { inputTokens: 10000, outputTokens: 2000 }, { percentageMargin: 25 });

🛡️ Mecanismo Fail-Safe (Resiliencia ante Fallos de Red)

Si el servidor remoto o la red no responden, la librería mantiene las últimas tarifas registradas en memoria o sus valores de respaldo locales sin lanzar excepciones ni detener la ejecución de tu aplicación.

🏢 Usar tu propio Endpoint de Precios (Enterprise / Privado)

Puedes apuntar la sincronización a tu propio servidor o API interna:

await syncLLMPricing('https://api.tuempresa.com/v1/llm-pricing.json');

⚙️ 2. Modificación Manual de Precios al Instante

Si deseas cambiar o probar una tarifa personalizada para un modelo en tiempo de ejecución:

import { globalPricingRegistry, calculateCost } from 'xtokencounter';

// Actualizar manualmente el precio de DeepSeek V3 en 1 línea:
globalPricingRegistry.setPricing({
  model: 'deepseek-v3',
  provider: 'deepseek',
  inputPricePerM: 0.10,       // $0.10 USD por millón de tokens de entrada
  outputPricePerM: 0.20,      // $0.20 USD por millón de tokens de salida
  cachedInputPricePerM: 0.01, // $0.01 USD por millón de tokens en caché
});

// A partir de esta línea, calculateCost usará la nueva tarifa:
const result = calculateCost('deepseek-v3', { inputTokens: 5000, outputTokens: 1000 });

⚡ 3. Inicio Rápido y Uso General

Cálculo de Costo y Facturación por Modelo

import { calculateCost } from 'xtokencounter';

// OpenAI GPT-4o (+20% ganancia)
const openaiCost = calculateCost('gpt-4o', { inputTokens: 1000, outputTokens: 400 }, { percentageMargin: 20 });

// Anthropic Claude 3.5 Sonnet (+25% ganancia)
const claudeCost = calculateCost('claude-3-5-sonnet', { inputTokens: 2000, outputTokens: 800 }, { percentageMargin: 25 });

// DeepSeek R1 (+30% ganancia)
const deepseekCost = calculateCost('deepseek-r1', { inputTokens: 5000, outputTokens: 1500 }, { percentageMargin: 30 });

// Google Gemini 2.0 Flash (+20% ganancia)
const geminiCost = calculateCost('gemini-2.0-flash', { inputTokens: 3000, outputTokens: 600 }, { percentageMargin: 20 });

console.log(`Costo real OpenAI: $${openaiCost.totalBaseCostUSD} USD | Cobro al cliente: $${openaiCost.clientPriceUSD} USD`);
console.log(`Costo real Claude: $${claudeCost.totalBaseCostUSD} USD | Cobro al cliente: $${claudeCost.clientPriceUSD} USD`);
console.log(`Costo real DeepSeek: $${deepseekCost.totalBaseCostUSD} USD | Cobro al cliente: $${deepseekCost.clientPriceUSD} USD`);

📥 4. Extracción Automática desde SDKs Oficiales

Soporta las estructuras de respuesta oficiales de los SDKs / REST APIs de OpenAI, Anthropic, DeepSeek y Gemini:

import { extractUsageFromResponse, calculateCost } from 'xtokencounter';

// Ejemplo con respuesta de OpenAI (gpt-4o / o1 / o3-mini)
const openaiResponse = await openai.chat.completions.create({ model: 'gpt-4o', messages });
const openaiUsage = extractUsageFromResponse(openaiResponse);

// Ejemplo con respuesta de Anthropic Claude
const claudeResponse = await anthropic.messages.create({ model: 'claude-3-5-sonnet-20241022', messages });
const claudeUsage = extractUsageFromResponse(claudeResponse);

// Calcular cobro final al cliente
const billing = calculateCost('gpt-4o', openaiUsage, { percentageMargin: 25 });
console.log(`Precio final al cliente: $${billing.clientPriceUSD.toFixed(6)} USD`);

📈 5. Rastreador Analítico Multi-Proveedor (TokenTracker)

Agrupa el consumo acumulado de todos tus proveedores de IA por cliente, usuario o sesión:

import { TokenTracker } from 'xtokencounter';

const tracker = new TokenTracker({ percentageMargin: 20 });

// Registrar consumo de peticiones
tracker.trackUsage('gpt-4o', { inputTokens: 4000, outputTokens: 1200 }, { metadata: { userId: 'user_1' } });
tracker.trackUsage('claude-3-5-sonnet', { inputTokens: 6000, outputTokens: 1500 }, { metadata: { userId: 'user_2' } });
tracker.trackUsage('deepseek-r1', { inputTokens: 10000, outputTokens: 3000 }, { metadata: { userId: 'user_3' } });
tracker.trackUsage('gemini-2.0-flash', { inputTokens: 8000, outputTokens: 2000 }, { metadata: { userId: 'user_1' } });

// Generar informe analítico agrupado por proveedor y por modelo
const summary = tracker.getSummary();

console.log(`Peticiones Totales: ${summary.totalRequests}`);
console.log(`Costo Base Total (Proveedores): $${summary.totalBaseCostUSD.toFixed(4)} USD`);
console.log(`Total a Facturar a Clientes: $${summary.totalClientPriceUSD.toFixed(4)} USD`);
console.log(`Ganancia Neta: $${summary.totalProfitUSD.toFixed(4)} USD`);

console.log('📌 Agrupado por proveedor:', summary.byProvider);
console.log('📌 Agrupado por modelo:', summary.byModel);

🤖 Catálogo de Modelos e Integración

| Proveedor | Modelo | Entrada / 1M Tokens | Salida / 1M Tokens | Caché / 1M | | :--- | :--- | :--- | :--- | :--- | | OpenAI | gpt-4o | $2.50 USD | $10.00 USD | $1.25 USD | | OpenAI | gpt-4o-mini | $0.15 USD | $0.60 USD | $0.075 USD | | OpenAI | o1 | $15.00 USD | $60.00 USD | $7.50 USD | | OpenAI | o3-mini / o1-mini | $1.10 USD | $4.40 USD | $0.55 USD | | Anthropic | claude-3-5-sonnet | $3.00 USD | $15.00 USD | $0.30 USD | | Anthropic | claude-3-5-haiku | $1.00 USD | $5.00 USD | $0.10 USD | | Anthropic | claude-3-opus | $15.00 USD | $75.00 USD | $1.50 USD | | DeepSeek | deepseek-v3 / chat | $0.14 USD | $0.28 USD | $0.014 USD | | DeepSeek | deepseek-r1 / reasoner| $0.55 USD | $2.19 USD | $0.14 USD | | Google | gemini-2.0-flash | $0.10 USD | $0.40 USD | $0.025 USD | | Google | gemini-1.5-pro | $1.25 USD ($2.50 >128k) | $5.00 USD ($10.00 >128k) | $0.3125 USD |

⚙️ Opciones de Facturación y Ganancias (MarkupConfig)

• percentageMargin: Porcentaje de recargo extra sobre el costo base (ej: 25 para +25%).
• fixedFeePerRequestUSD: Fee fijo adicional en USD por cada llamada a la API (ej: $0.002).
• feePer1kTokensUSD: Tarifa fija adicional por cada 1,000 tokens procesados.
• costMultiplier: Multiplicador directo sobre el costo base (ej: 1.5 equivale a 150% del costo base).
• currency: Moneda del informe (USD por defecto).

📄 Licencia

MIT © xFORCE DEV TEAM