SlicePay Pricing Engine

Biblioteca TypeScript responsável por calcular o limite de crédito máximo permitido para um usuário com base em métricas financeiras críticas (comprometimento de renda, LTV, DSCR, Income Commitment e consolidação de dívidas).

Recursos

• Precisão decimal com decimal.js
• Validações rigorosas de entrada
• Dois modos de cálculo: simple (padrão) e complete (avançado)
• Limites modulares (comp renda, LTV, DSCR, Income Commitment) com possibilidade de expansão futura
• Suporte a taxas de juros variáveis por prazo
• Cálculo automático do melhor prazo para maximizar o limite
• Resultado consolidado com limite final, taxa, prazo, parcela, primeiro saque e breakdown
• Testes unitários abrangentes com Vitest

Instalação

npm install slicepay-pricing-engine

Uso

Modo Simple (Padrão)

O modo simple é o padrão e mantém compatibilidade total com versões anteriores:

import { calculateCreditLimit } from 'slicepay-pricing-engine';

const result = calculateCreditLimit({
  income: 20000,
  existingMonthlyPayment: 3000,
  existingPaymentInstallments: 60,
  collateralValue: 50000,
  totalDebt: 15000,
  maxIncomeRatio: 0.4,
  ltv: 0.4,
  interestRate: 0.02,
  maxInstallments: 120
});

if (result.eligible) {
  console.log('Limite aprovado', result.limit);
  console.log('Parcela mensal', result.monthlyPayment);
} else if (result.reason === 'debt_exceeds_limit') {
  console.log('Usuário inelegível: dívida excede limite disponível');
}

Modo Complete (Avançado)

O modo complete adiciona validações de DSCR, Income Commitment, despesas fixas e suporte a taxas variáveis por prazo:

import { calculateCreditLimit } from 'slicepay-pricing-engine';

const result = calculateCreditLimit({
  mode: 'complete',
  income: 8000,
  fixedExpenses: 2000,
  existingMonthlyPayment: 1000,
  existingPaymentInstallments: 60,
  collateralValue: 500000,
  totalDebt: 50000,
  maxIncomeRatio: 0.4,
  ltv: 0.4,
  minDscr: 1.50,
  maxIncomeCommitment: 0.40,
  interestRateCalculator: (termMonths: number) => {
    // Calcular taxa baseada no prazo
    return 0.02 + (termMonths / 1000); // Exemplo: taxa aumenta com prazo
  },
  minTerms: 12,
  maxTerms: 120,
  step: 6
});

if (result.eligible) {
  console.log('Limite aprovado', result.limit);
  console.log('Melhor prazo', result.breakdown.bestTerm);
  console.log('Fator limitante', result.breakdown.limitingFactor);
  console.log('Limite por DSCR', result.breakdown.maxByDscr);
  console.log('Limite por Income Commitment', result.breakdown.maxByIncomeCommitment);
} else {
  console.log('Razão da rejeição', result.reason);
}

API

calculateCreditLimit(input: PricingInput): PricingOutput

Entrada (PricingInput)

Campos obrigatórios (todos os modos):

• income: renda mensal comprovada
• existingMonthlyPayment: parcela mensal já comprometida
• existingPaymentInstallments: número de parcelas restantes dessa dívida
• collateralValue: valor do ativo em garantia
• totalDebt: dívida total a ser consolidada
• maxIncomeRatio: percentual máximo de comprometimento (0-1)
• ltv: percentual de Loan-to-Value (0-1)
• interestRate: taxa mensal (0.02 = 2%) - usado como fallback no modo complete
• maxInstallments: prazo máximo em meses (ex: 120) - usado no modo simple

Campos opcionais (modo complete):

• mode: 'simple' (padrão) ou 'complete'
• fixedExpenses: despesas fixas mensais (padrão: 0)
• minDscr: threshold mínimo de DSCR (padrão: 1.50)
• maxIncomeCommitment: percentual máximo de comprometimento de renda (padrão: 0.40)
• interestRateCalculator: função (termMonths: number) => number para calcular taxa por prazo (sobrescreve interestRate)
• validateDscr: habilitar validação de DSCR (padrão: true no modo complete)
• validateIncomeCommitment: habilitar validação de Income Commitment (padrão: true no modo complete)
• minTerms: prazo mínimo para testar (padrão: 12)
• maxTerms: prazo máximo para testar (padrão: 120)
• step: incremento entre prazos testados (padrão: 6)

Saída (PricingOutput)

Quando eligible === true:

• eligible: true
• limit: limite aprovado em reais
• interestRate: taxa aplicada (mensal)
• installments: prazo utilizado (no modo complete, é o bestTerm)
• monthlyPayment: parcela resultante
• firstWithdrawal: valor liberado no saque inicial
• breakdown: objeto com limites individuais:
  • incomeRatioLimit: limite por comprometimento de renda
  • ltvLimit: limite por Loan-to-Value
  • maxByDscr: limite por DSCR (apenas modo complete)
  • maxByIncomeCommitment: limite por Income Commitment (apenas modo complete)
  • limitingFactor: fator que limitou o cálculo ('income_ratio', 'ltv', 'dscr', 'income_commitment') (apenas modo complete)
  • bestTerm: prazo que resultou no maior limite (apenas modo complete)

Quando eligible === false:

• eligible: false
• reason: razão da rejeição:
  • 'debt_exceeds_limit': dívida excede limite disponível
  • 'no_valid_term': nenhum prazo resultou em limite válido (apenas modo complete)
  • 'dscr_too_low': DSCR abaixo do mínimo (apenas modo complete)
  • 'income_commitment_too_high': comprometimento de renda acima do máximo (apenas modo complete)
• breakdown: limites calculados (pode incluir campos do modo complete)

Métricas de Limite

Income Ratio (Comprometimento de Renda)

Calcula o limite baseado na capacidade de pagamento mensal:

• Capacidade = income × maxIncomeRatio
• Headroom = Capacidade - existingMonthlyPayment
• Limite = Valor presente da série de pagamentos (headroom)

LTV (Loan-to-Value)

Calcula o limite baseado no valor da garantia:

• Limite = collateralValue × ltv

DSCR (Debt Service Coverage Ratio) - Modo Complete

Valida que a renda líquida cobre adequadamente o serviço da dívida:

• Renda Líquida = income - fixedExpenses
• Serviço Dívida Máximo = Renda Líquida / minDscr
• Parcela Máxima Nova = Serviço Dívida Máximo - existingMonthlyPayment
• Limite = Valor presente da parcela máxima

Income Commitment - Modo Complete

Valida que o comprometimento total de renda não excede o máximo:

• Serviço Dívida Máximo = income × maxIncomeCommitment
• Parcela Máxima Nova = Serviço Dívida Máximo - existingMonthlyPayment
• Limite = Valor presente da parcela máxima

Scripts

npm run type-check   # verificação estática
npm run build        # gera artefatos em dist/
npm run test         # executa os testes unitários (Vitest)

Compatibilidade

A biblioteca mantém 100% de compatibilidade com código existente. O modo simple é o padrão e preserva o comportamento das versões anteriores. Todos os campos do modo complete são opcionais e não afetam o funcionamento do modo simple.