feat(tiempo-beneficios): add client benefit time analysis tools with anti-timeout optimizations

- Add individual client time to benefits analysis (get_tiempo_beneficios_cliente)
- Add bulk analysis tool for all clients (get_tiempo_beneficios_todos_clientes)
- Implement comprehensive statistical reporting with medians, distributions, and payment patterns
- Add rate limiting and timeout prevention optimizations:
  * Maximum 50 clients per request when incluir_sin_facturas=false (anti-timeout)
  * Maximum 100 clients per request when incluir_sin_facturas=true (anti-rate-limit)
  * Early exit pattern for clients without invoices
  * Timeout protection with 25-second processing limit
- Change default incluir_sin_facturas to false for business-focused revenue analysis
- Add comprehensive pagination documentation and examples
- Include 14 unit tests covering all scenarios and optimizations

Business benefits:
- ROI analysis from client registration to first payment
- Cash flow management with payment pattern insights
- Collection strategy optimization based on client payment behavior
- Client retention analysis through payment timing distributions

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cristotodev

src/index.ts

@@ -88,6 +88,8 @@ import { SubcuentasResource } from './modules/accounting/subcuentas/resource.js'
 import { TarifasResource } from './modules/configuration/tarifas/resource.js';
 // Import new tool functions
 import { toolByCifnifImplementation, toolClientesMorososImplementation, toolClientesTopFacturacionImplementation, toolClientesSinComprasImplementation, toolExportarFacturaImplementation, toolClientesFrecuenciaComprasImplementation, toolFacturasConErroresImplementation, toolClientesPerdidosImplementation } from './modules/sales-orders/facturaclientes/tool.js';
+import { toolTiempoBeneficiosImplementation } from './modules/sales-orders/facturaclientes/tool-tiempo-beneficios.js';
+import { toolTiempoBeneficiosBulkImplementation } from './modules/sales-orders/facturaclientes/tool-tiempo-beneficios-bulk.js';
 import { lowStockToolImplementation } from './modules/core-business/stocks/tool.js';
 import { toolProductosMasVendidosImplementation } from './modules/sales-orders/line-items/lineafacturaclientes/tool.js';
 import { productosNoVendidosToolDefinition, productosNoVendidosToolImplementation } from './modules/core-business/productos/index.js';
@@ -435,6 +437,29 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ['fecha_desde', 'fecha_hasta']
         }
       },
+      {
+        name: 'get_tiempo_beneficios_cliente',
+        description: 'Calcula el tiempo que tarda un cliente en generar beneficios desde su alta hasta el primer y último pago de facturas. Realiza análisis en tres pasos: 1) Busca datos del cliente por código, 2) Obtiene facturas del cliente, 3) Consulta recibos/pagos asociados. Calcula días desde fecha alta hasta primer y último pago, totales facturados y pagados. Útil para análisis de retorno de inversión en clientes, gestión de tesorería y estrategias de cobranza.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            codcliente: { type: 'string', description: 'Código del cliente para analizar (requerido)' }
+          },
+          required: ['codcliente']
+        }
+      },
+      {
+        name: 'get_tiempo_beneficios_todos_clientes',
+        description: 'Calcula el tiempo hasta beneficios para todos los clientes en un análisis bulk. Devuelve el detalle individual de cada cliente y un informe estadístico completo con medias, medianas, totales y distribuciones. Realiza procesamiento eficiente en lote para análisis masivos de rentabilidad de clientes. Útil para obtener insights generales de la cartera de clientes, identificar patrones de pago y optimizar estrategias de cobranza.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            limit: { type: 'number', description: 'Número máximo de clientes a procesar (1-500)', minimum: 1, maximum: 500, default: 100 },
+            offset: { type: 'number', description: 'Número de clientes a omitir para paginación', minimum: 0, default: 0 },
+            incluir_sin_facturas: { type: 'boolean', description: 'Si incluir clientes sin facturas en el análisis', default: true }
+          }
+        }
+      },
       {
         name: 'get_clientes_perdidos',
         description: 'Obtiene una lista de clientes que tenían facturas anteriormente pero no han comprado desde una fecha específica hasta ahora. Excluye clientes que nunca han comprado (sin historial de facturas). Realiza análisis en tres pasos: 1) Obtiene todos los clientes con historial de facturas, 2) Identifica clientes con facturas anteriores a la fecha límite, 3) Filtra aquellos sin facturas desde la fecha hasta hoy. Útil para campañas de recuperación de clientes perdidos, análisis de retención y estrategias de reactivación.',
@@ -3051,6 +3076,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return await toolClientesTopFacturacionImplementation(request.params.arguments as any, fsClient);
       }
 
+      case 'get_tiempo_beneficios_cliente': {
+        return await toolTiempoBeneficiosImplementation(request.params.arguments as any, fsClient);
+      }
+
+      case 'get_tiempo_beneficios_todos_clientes': {
+        return await toolTiempoBeneficiosBulkImplementation(request.params.arguments as any, fsClient);
+      }
+
       case 'get_clientes_perdidos': {
         return await toolClientesPerdidosImplementation(request.params.arguments as any, fsClient);
       }

src/modules/sales-orders/facturaclientes/index.ts

@@ -10,4 +10,12 @@ export {
   toolClientesTopFacturacionImplementation as facturaclientesTopFacturacionToolImplementation,
   toolClientesPerdidosDefinition as facturaclientesPerdidosToolDefinition,
   toolClientesPerdidosImplementation as facturaclientesPerdidosToolImplementation
-} from './tool.js';
+} from './tool.js';
+export {
+  toolTiempoBeneficiosDefinition as facturaclientesTiempoBeneficiosToolDefinition,
+  toolTiempoBeneficiosImplementation as facturaclientesTiempoBeneficiosToolImplementation
+} from './tool-tiempo-beneficios.js';
+export {
+  toolTiempoBeneficiosBulkDefinition as facturaclientesTiempoBeneficiosBulkToolDefinition,
+  toolTiempoBeneficiosBulkImplementation as facturaclientesTiempoBeneficiosBulkToolImplementation
+} from './tool-tiempo-beneficios-bulk.js';