@fullqueso/mcp-bc-gastos 1.1.0

package/lib/anomaly-detector.js

@@ -0,0 +1,223 @@
+import { round2 } from '../utils/currency-converter.js';
+import { aggregateByCategory } from './expense-analyzer.js';
+import { BENCHMARKS } from '../config/benchmarks.js';
+
+export function detectAnomalies(currentData, previousData) {
+  const anomalies = [];
+
+  const currentCats = aggregateByCategory(currentData.expenses);
+  const previousCats = previousData ? aggregateByCategory(previousData.expenses) : null;
+
+  const currentIncome = currentData.totalIncome;
+  const previousIncome = previousData ? previousData.totalIncome : null;
+
+  // 1. Check each category for anomalies
+  for (const [key, cat] of Object.entries(currentCats)) {
+    const prevCat = previousCats ? previousCats[key] : null;
+    const benchmark = BENCHMARKS[key];
+    const pctOfIncome = currentIncome > 0 ? (cat.total / currentIncome) * 100 : 0;
+
+    // Anomaly: significantly above benchmark
+    if (benchmark && pctOfIncome > benchmark.alert_high) {
+      anomalies.push({
+        severity: 'critical',
+        icon: '🚨',
+        category: cat.name,
+        category_key: key,
+        type: 'above_benchmark',
+        description: `${cat.name} representa ${round2(pctOfIncome)}% de ingresos (umbral crítico: ${benchmark.alert_high}%)`,
+        current_value: round2(cat.total),
+        current_pct: round2(pctOfIncome),
+        threshold: benchmark.alert_high,
+        possible_causes: getPossibleCauses(key, 'above_benchmark'),
+        recommended_actions: getRecommendedActions(key, 'above_benchmark'),
+      });
+    } else if (benchmark && pctOfIncome > benchmark.max) {
+      anomalies.push({
+        severity: 'warning',
+        icon: '⚠️',
+        category: cat.name,
+        category_key: key,
+        type: 'above_normal',
+        description: `${cat.name} representa ${round2(pctOfIncome)}% de ingresos (rango normal: ${benchmark.min}-${benchmark.max}%)`,
+        current_value: round2(cat.total),
+        current_pct: round2(pctOfIncome),
+        threshold: benchmark.max,
+        possible_causes: getPossibleCauses(key, 'above_normal'),
+        recommended_actions: getRecommendedActions(key, 'above_normal'),
+      });
+    }
+
+    // Anomaly: significant increase vs previous period
+    if (prevCat && prevCat.total > 0) {
+      const changePct = ((cat.total - prevCat.total) / prevCat.total) * 100;
+
+      if (changePct > 30) {
+        anomalies.push({
+          severity: changePct > 50 ? 'critical' : 'warning',
+          icon: changePct > 50 ? '🚨' : '⚠️',
+          category: cat.name,
+          category_key: key,
+          type: 'spike',
+          description: `${cat.name} aumentó ${round2(changePct)}% vs periodo anterior`,
+          current_value: round2(cat.total),
+          previous_value: round2(prevCat.total),
+          change_pct: round2(changePct),
+          change_amount: round2(cat.total - prevCat.total),
+          possible_causes: getPossibleCauses(key, 'spike'),
+          recommended_actions: getRecommendedActions(key, 'spike'),
+        });
+      }
+
+      // Unusual drop (could indicate missed payments)
+      if (changePct < -40 && cat.total > 0) {
+        anomalies.push({
+          severity: 'info',
+          icon: 'ℹ️',
+          category: cat.name,
+          category_key: key,
+          type: 'unusual_drop',
+          description: `${cat.name} disminuyó ${round2(Math.abs(changePct))}% vs periodo anterior`,
+          current_value: round2(cat.total),
+          previous_value: round2(prevCat.total),
+          change_pct: round2(changePct),
+          possible_causes: ['Pago no registrado', 'Cambio de proveedor', 'Reclasificación contable'],
+          recommended_actions: ['Verificar que todos los pagos estén registrados', 'Confirmar que no hay facturas pendientes'],
+        });
+      }
+    }
+
+    // Anomaly: check individual accounts within a category for concentration
+    const accountValues = Object.values(cat.accounts);
+    if (accountValues.length > 1) {
+      const maxAccount = accountValues.reduce((max, a) => a.total > max.total ? a : max);
+      const acctConcentration = cat.total > 0 ? (maxAccount.total / cat.total) * 100 : 0;
+
+      if (acctConcentration > 80 && cat.total > currentIncome * 0.05) {
+        anomalies.push({
+          severity: 'info',
+          icon: 'ℹ️',
+          category: cat.name,
+          category_key: key,
+          type: 'concentration',
+          description: `${maxAccount.name} (${maxAccount.accountNumber}) concentra ${round2(acctConcentration)}% de ${cat.name}`,
+          account: maxAccount.accountNumber,
+          account_name: maxAccount.name,
+          amount: round2(maxAccount.total),
+          possible_causes: ['Concentración normal para esta categoría', 'Cuenta cajón para gastos varios'],
+          recommended_actions: ['Verificar clasificación de subcuentas'],
+        });
+      }
+    }
+  }
+
+  // 2. Check income anomalies
+  if (previousIncome && previousIncome > 0) {
+    const incomeChange = ((currentIncome - previousIncome) / previousIncome) * 100;
+    if (incomeChange < -20) {
+      anomalies.push({
+        severity: 'critical',
+        icon: '🚨',
+        category: 'Ingresos',
+        category_key: 'income',
+        type: 'income_drop',
+        description: `Ingresos cayeron ${round2(Math.abs(incomeChange))}% vs periodo anterior`,
+        current_value: round2(currentIncome),
+        previous_value: round2(previousIncome),
+        change_pct: round2(incomeChange),
+        possible_causes: ['Baja en ventas', 'Días no operativos', 'Estacionalidad'],
+        recommended_actions: ['Revisar análisis de ventas detallado', 'Comparar con tendencia del mercado'],
+      });
+    }
+  }
+
+  // 3. Check operating margin
+  if (currentData.operatingMarginPct < 35) {
+    anomalies.push({
+      severity: 'critical',
+      icon: '🚨',
+      category: 'Margen Operativo',
+      category_key: 'margin',
+      type: 'low_margin',
+      description: `Margen operativo en ${round2(currentData.operatingMarginPct)}% (mínimo recomendado: 40%)`,
+      current_value: round2(currentData.operatingMarginPct),
+      threshold: 40,
+      possible_causes: ['Gastos excesivos', 'Caída de ingresos', 'Combinación de ambos'],
+      recommended_actions: ['Revisar las categorías de gasto más altas', 'Evaluar oportunidades de incremento de ingresos'],
+    });
+  }
+
+  // Sort by severity
+  const severityOrder = { critical: 0, warning: 1, info: 2 };
+  anomalies.sort((a, b) => (severityOrder[a.severity] ?? 3) - (severityOrder[b.severity] ?? 3));
+
+  return {
+    store: currentData.storeName,
+    store_code: currentData.storeCode,
+    period: currentData.period,
+    total_anomalies: anomalies.length,
+    critical: anomalies.filter((a) => a.severity === 'critical').length,
+    warnings: anomalies.filter((a) => a.severity === 'warning').length,
+    info: anomalies.filter((a) => a.severity === 'info').length,
+    anomalies,
+  };
+}
+
+function getPossibleCauses(categoryKey, anomalyType) {
+  const causes = {
+    nomina: {
+      above_benchmark: ['Incremento salarial reciente', 'Contrataciones nuevas', 'Pago de utilidades o prestaciones'],
+      above_normal: ['Horas extra elevadas', 'Bonificaciones especiales'],
+      spike: ['Pago de liquidaciones', 'Retroactivos', 'Ajuste salarial'],
+    },
+    planta_fisica: {
+      above_benchmark: ['Aumento de alquiler', 'Facturas de servicios atrasadas', 'Mantenimiento extraordinario'],
+      above_normal: ['Temporada de alto consumo eléctrico', 'Reparaciones'],
+      spike: ['Factura acumulada', 'Renovación de contrato', 'Reparación mayor'],
+    },
+    marketing: {
+      above_benchmark: ['Campaña publicitaria especial', 'Lanzamiento de producto'],
+      above_normal: ['Inversión en redes sociales', 'Evento promocional'],
+      spike: ['Campaña de temporada', 'Inversión puntual en publicidad'],
+    },
+    logistica: {
+      above_benchmark: ['Aumento de precio combustible', 'Reparación de vehículo'],
+      above_normal: ['Mayor volumen de delivery', 'Mantenimiento vehicular'],
+      spike: ['Reparación mayor', 'Compra de repuestos'],
+    },
+    default: {
+      above_benchmark: ['Gasto inusual en esta categoría', 'Posible reclasificación contable'],
+      above_normal: ['Incremento gradual', 'Nuevo proveedor más costoso'],
+      spike: ['Pago acumulado', 'Gasto extraordinario'],
+    },
+  };
+
+  return (causes[categoryKey] || causes.default)[anomalyType] || causes.default[anomalyType];
+}
+
+function getRecommendedActions(categoryKey, anomalyType) {
+  const actions = {
+    nomina: {
+      above_benchmark: ['Revisar estructura de personal', 'Evaluar automatización de procesos', 'Comparar con otras tiendas'],
+      above_normal: ['Controlar horas extra', 'Revisar productividad por empleado'],
+      spike: ['Verificar pagos especiales', 'Confirmar que no hay duplicados'],
+    },
+    planta_fisica: {
+      above_benchmark: ['Negociar renovación de alquiler', 'Buscar eficiencia energética', 'Comparar tarifas de servicios'],
+      above_normal: ['Implementar ahorro energético', 'Revisar contratos de mantenimiento'],
+      spike: ['Verificar facturación correcta', 'Revisar si es gasto recurrente o puntual'],
+    },
+    marketing: {
+      above_benchmark: ['Medir ROI de campañas', 'Priorizar canales más efectivos'],
+      above_normal: ['Evaluar efectividad de campañas activas'],
+      spike: ['Verificar resultados de la campaña', 'Comparar costo vs incremento en ventas'],
+    },
+    default: {
+      above_benchmark: ['Revisar detalle de transacciones', 'Buscar alternativas más económicas'],
+      above_normal: ['Monitorear tendencia', 'Solicitar cotizaciones competitivas'],
+      spike: ['Investigar causa del incremento', 'Verificar clasificación contable correcta'],
+    },
+  };
+
+  return (actions[categoryKey] || actions.default)[anomalyType] || actions.default[anomalyType];
+}

package/lib/bc-client.js

@@ -0,0 +1,361 @@
+import { logger } from '../utils/logger.js';
+import { getExpenseCategory } from '../config/expense-accounts.js';
+import { resolveStores } from '../config/company-config.js';
+
+export class BCClient {
+  constructor() {
+    this.token = null;
+    this.tokenExpiry = null;
+    this.baseUrl = process.env.BC_API_BASE;
+    this.tenantId = process.env.BC_TENANT_ID;
+    this.environment = process.env.BC_ENVIRONMENT;
+  }
+
+  async getToken() {
+    if (this.token && this.tokenExpiry > Date.now()) {
+      return this.token;
+    }
+
+    logger.info('Fetching new BC access token...');
+    const response = await this.fetchWithRetry(process.env.BC_TOKEN_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        client_id: process.env.BC_CLIENT_ID,
+        client_secret: process.env.BC_CLIENT_SECRET,
+        scope: process.env.BC_SCOPE,
+        grant_type: 'client_credentials',
+      }),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Token request failed (${response.status}): ${errorText}`);
+    }
+
+    const data = await response.json();
+    this.token = data.access_token;
+    this.tokenExpiry = Date.now() + (data.expires_in - 300) * 1000;
+    logger.info('Token obtained successfully');
+    return this.token;
+  }
+
+  buildApiUrl(companyId, endpoint, params = {}) {
+    const base = `${this.baseUrl}/${this.tenantId}/${this.environment}/api/v2.0/companies(${companyId})/${endpoint}`;
+    const searchParams = new URLSearchParams();
+
+    if (params.$filter) searchParams.set('$filter', params.$filter);
+    if (params.$top) searchParams.set('$top', String(params.$top));
+    if (params.$orderby) searchParams.set('$orderby', params.$orderby);
+    if (params.$select) searchParams.set('$select', params.$select);
+
+    const qs = searchParams.toString();
+    return qs ? `${base}?${qs}` : base;
+  }
+
+  async apiCall(url) {
+    const token = await this.getToken();
+    logger.debug(`API call: ${url}`);
+
+    const response = await this.fetchWithRetry(url, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`BC API Error (${response.status}): ${errorText}`);
+    }
+
+    const data = await response.json();
+    return data.value || data;
+  }
+
+  async fetchWithRetry(url, options, retries = 3) {
+    for (let attempt = 1; attempt <= retries; attempt++) {
+      try {
+        return await fetch(url, options);
+      } catch (err) {
+        if (attempt === retries) throw err;
+        const delay = attempt * 2000;
+        logger.warn(`Fetch failed (attempt ${attempt}/${retries}), retrying in ${delay}ms...`);
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+
+  async apiCallAllPages(url) {
+    const token = await this.getToken();
+    let allResults = [];
+    let nextUrl = url;
+
+    while (nextUrl) {
+      logger.debug(`API call (paged): ${nextUrl}`);
+      const response = await this.fetchWithRetry(nextUrl, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`BC API Error (${response.status}): ${errorText}`);
+      }
+
+      const data = await response.json();
+      allResults = allResults.concat(data.value || []);
+      nextUrl = data['@odata.nextLink'] || null;
+    }
+
+    return allResults;
+  }
+
+  // Fetch General Ledger Entries for a specific account range
+  async getGLEntries(companyId, startDate, endDate, accountMin, accountMax) {
+    const url = this.buildApiUrl(companyId, 'generalLedgerEntries', {
+      $filter: `postingDate ge ${startDate} and postingDate le ${endDate} and accountNumber ge '${accountMin}' and accountNumber le '${accountMax}'`,
+      $select: 'entryNumber,postingDate,documentNumber,accountNumber,description,debitAmount,creditAmount',
+      $orderby: 'postingDate desc',
+    });
+    return this.apiCallAllPages(url);
+  }
+
+  // Fetch revenue entries (40000-49999) - credit balance = income
+  async getRevenueEntries(companyId, startDate, endDate) {
+    return this.getGLEntries(companyId, startDate, endDate, '40000', '49999');
+  }
+
+  // Fetch COGS entries (50000-59999) - debit balance = cost of goods sold
+  async getCOGSEntries(companyId, startDate, endDate) {
+    return this.getGLEntries(companyId, startDate, endDate, '50000', '59999');
+  }
+
+  // Fetch expense entries (60000-99999) - debit balance = operating expenses
+  async getExpenseEntries(companyId, startDate, endDate) {
+    return this.getGLEntries(companyId, startDate, endDate, '60000', '99999');
+  }
+
+  // Fetch all financial data for a store
+  async getStoreFinancialData(storeCode, startDate, endDate) {
+    const stores = resolveStores([storeCode]);
+    const store = stores[0];
+
+    logger.info(`Fetching financial data for ${store.name}: ${startDate} to ${endDate}`);
+
+    const [revenueEntries, cogsEntries, expenseEntries] = await Promise.all([
+      this.getRevenueEntries(store.companyId, startDate, endDate),
+      this.getCOGSEntries(store.companyId, startDate, endDate),
+      this.getExpenseEntries(store.companyId, startDate, endDate),
+    ]);
+
+    // Revenue (40000-49999): credit balance accounts, income = credit - debit
+    const totalRevenue = revenueEntries.reduce(
+      (sum, e) => sum + ((e.creditAmount || 0) - (e.debitAmount || 0)),
+      0
+    );
+
+    // COGS (50000-59999): debit balance accounts, cost = debit - credit
+    const totalCOGS = cogsEntries.reduce(
+      (sum, e) => sum + ((e.debitAmount || 0) - (e.creditAmount || 0)),
+      0
+    );
+
+    // Categorize expense entries (60000-99999)
+    const categorizedExpenses = expenseEntries.map((entry) => {
+      const category = getExpenseCategory(entry.accountNumber);
+      return {
+        ...entry,
+        categoryKey: category?.key || 'otros',
+        categoryName: category?.name || 'Otros Gastos',
+        categoryIcon: category?.icon || '📦',
+        // Expenses are debit entries; net = debit - credit
+        expenseAmount: (entry.debitAmount || 0) - (entry.creditAmount || 0),
+      };
+    });
+
+    const totalExpenses = categorizedExpenses.reduce((sum, e) => sum + e.expenseAmount, 0);
+
+    // Financial summary
+    const grossMargin = totalRevenue - totalCOGS;
+    const grossMarginPct = totalRevenue > 0 ? (grossMargin / totalRevenue) * 100 : 0;
+    const operatingMargin = totalRevenue - totalCOGS - totalExpenses;
+    const operatingMarginPct = totalRevenue > 0 ? (operatingMargin / totalRevenue) * 100 : 0;
+
+    return {
+      storeCode: store.code,
+      storeName: store.name,
+      period: { start: startDate, end: endDate },
+      expenses: categorizedExpenses,
+      totalRevenue,
+      totalCOGS,
+      grossMargin,
+      grossMarginPct,
+      totalExpenses,
+      // totalIncome = totalRevenue (for backward compat with analyzers)
+      totalIncome: totalRevenue,
+      operatingMargin,
+      operatingMarginPct,
+    };
+  }
+
+  // Fetch financial data for all requested stores
+  async getAllStoresFinancialData(storeCodes, startDate, endDate) {
+    const stores = resolveStores(storeCodes);
+    const results = {};
+
+    // Fetch stores sequentially to avoid BC API rate limiting
+    for (const store of stores) {
+      results[store.code] = await this.getStoreFinancialData(store.code, startDate, endDate);
+    }
+
+    return results;
+  }
+
+  // Fetch exchange rates
+  async getExchangeRates(storeCode) {
+    const stores = resolveStores([storeCode]);
+    const url = this.buildApiUrl(stores[0].companyId, 'currencyExchangeRates', {
+      $filter: `currencyCode eq 'VES'`,
+      $orderby: 'startingDate desc',
+    });
+    return this.apiCallAllPages(url);
+  }
+
+  getExchangeRateForDate(rates, targetDate) {
+    for (const rate of rates) {
+      if (rate.startingDate <= targetDate) {
+        return {
+          rate: rate.exchangeRateAmount / rate.relationalExchangeRateAmount,
+          startingDate: rate.startingDate,
+        };
+      }
+    }
+    if (rates.length > 0) {
+      const oldest = rates[rates.length - 1];
+      return {
+        rate: oldest.exchangeRateAmount / oldest.relationalExchangeRateAmount,
+        startingDate: oldest.startingDate,
+      };
+    }
+    return null;
+  }
+
+  // Fetch posted purchase invoices (includes vendorName directly)
+  async getPurchaseInvoices(companyId, startDate, endDate) {
+    const url = this.buildApiUrl(companyId, 'purchaseInvoices', {
+      $filter: `invoiceDate ge ${startDate} and invoiceDate le ${endDate}`,
+      $select: 'number,vendorNumber,vendorName',
+    });
+    return this.apiCallAllPages(url);
+  }
+
+  // Fetch vendor ledger entries to map documentNumber -> vendor info
+  async getVendorLedgerEntries(companyId, startDate, endDate) {
+    const url = this.buildApiUrl(companyId, 'vendorLedgerEntries', {
+      $filter: `postingDate ge ${startDate} and postingDate le ${endDate}`,
+      $select: 'documentNumber,vendorNumber,description',
+      $orderby: 'postingDate desc',
+    });
+    return this.apiCallAllPages(url);
+  }
+
+  // Fetch vendors list for name lookup
+  async getVendors(companyId) {
+    const url = this.buildApiUrl(companyId, 'vendors', {
+      $select: 'number,displayName',
+    });
+    return this.apiCallAllPages(url);
+  }
+
+  // Build a map of documentNumber -> { vendor_number, vendor_name }
+  // Strategy: purchaseInvoices first (has vendorName directly), then vendorLedgerEntries fallback
+  // Resilient: returns empty map if all vendor endpoints are unavailable
+  async buildVendorMap(companyId, startDate, endDate) {
+    // Strategy 1: purchaseInvoices — includes posted invoices with vendorName
+    try {
+      const invoices = await this.getPurchaseInvoices(companyId, startDate, endDate);
+      if (invoices.length > 0) {
+        const map = {};
+        for (const inv of invoices) {
+          if (inv.number && !map[inv.number]) {
+            map[inv.number] = {
+              vendor_number: inv.vendorNumber || null,
+              vendor_name: inv.vendorName || inv.vendorNumber || null,
+            };
+          }
+        }
+        logger.info(`Vendor map built from purchaseInvoices: ${Object.keys(map).length} documents mapped`);
+        return map;
+      }
+      logger.info('purchaseInvoices returned 0 results, trying vendorLedgerEntries...');
+    } catch (err) {
+      logger.warn(`purchaseInvoices failed (${err.message}), trying vendorLedgerEntries...`);
+    }
+
+    // Strategy 2: vendorLedgerEntries + vendors (cross-reference)
+    try {
+      const [vendorEntries, vendors] = await Promise.all([
+        this.getVendorLedgerEntries(companyId, startDate, endDate),
+        this.getVendors(companyId),
+      ]);
+
+      const vendorNames = {};
+      for (const v of vendors) {
+        vendorNames[v.number] = v.displayName;
+      }
+
+      const map = {};
+      for (const entry of vendorEntries) {
+        if (entry.documentNumber && !map[entry.documentNumber]) {
+          map[entry.documentNumber] = {
+            vendor_number: entry.vendorNumber,
+            vendor_name: vendorNames[entry.vendorNumber] || entry.vendorNumber,
+          };
+        }
+      }
+
+      logger.info(`Vendor map built from vendorLedgerEntries: ${Object.keys(map).length} documents mapped`);
+      return map;
+    } catch (err) {
+      logger.warn('All vendor lookup strategies failed, continuing without vendor info:', err.message);
+      return {};
+    }
+  }
+
+  // Fetch detailed GL entries with flexible filters for drill-down
+  async getDetailedGLEntries(companyId, filters = {}) {
+    const conditions = [];
+
+    if (filters.startDate) conditions.push(`postingDate ge ${filters.startDate}`);
+    if (filters.endDate) conditions.push(`postingDate le ${filters.endDate}`);
+    if (filters.accountNumber) {
+      conditions.push(`accountNumber eq '${filters.accountNumber}'`);
+    } else if (filters.accountMin && filters.accountMax) {
+      conditions.push(`accountNumber ge '${filters.accountMin}'`);
+      conditions.push(`accountNumber le '${filters.accountMax}'`);
+    }
+
+    const params = {
+      $filter: conditions.length > 0 ? conditions.join(' and ') : undefined,
+      $select: 'entryNumber,postingDate,documentNumber,accountNumber,description,debitAmount,creditAmount',
+      $orderby: 'postingDate desc',
+    };
+
+    if (filters.top) params.$top = String(filters.top);
+
+    const url = this.buildApiUrl(companyId, 'generalLedgerEntries', params);
+    return filters.top ? this.apiCall(url) : this.apiCallAllPages(url);
+  }
+
+  async getCompanies() {
+    const url = `${this.baseUrl}/${this.tenantId}/${this.environment}/api/v2.0/companies`;
+    return this.apiCall(url);
+  }
+
+  async testConnection() {
+    await this.getToken();
+    const companies = await this.getCompanies();
+    return {
+      authenticated: true,
+      companiesFound: companies.length,
+      companies: companies.map((c) => ({ id: c.id, name: c.name })),
+    };
+  }
+}