@fintech-mex/clabe-sdk

v1.0.2

Published

3 months ago

SDK moderno de TypeScript para validación, generación y análisis de CLABE (Clave Bancaria Estandarizada) mexicana. Construido con arquitectura limpia, compatibilidad universal y experiencia de desarrollador en mente.

0High
0Medium
0Low

mtoala

clabe banking mexico validation typescript

CLABE SDK

Modern TypeScript SDK for Mexican CLABE (Clave Bancaria Estandarizada) validation, generation, and parsing. Built with clean architecture, universal compatibility, and developer experience in mind.

📖 Documentación / Documentation

🇪🇸 Documentación en Español
🇺🇸 English Documentation

Documentación en Español

Características

✅ Soporte Completo de TypeScript - Definiciones de tipos completas e IntelliSense
🌐 Compatibilidad Universal - Funciona en navegadores, Node.js y entornos edge
🌳 Tree-Shakeable - Importa solo lo que necesitas para un bundle óptimo
🏗️ Arquitectura Limpia - Diseño dirigido por dominio con separación clara de responsabilidades
🧪 Completamente Probado - Cobertura de código del 95%+ con suite de pruebas integral
📚 Bien Documentado - Documentación completa de API con ejemplos
🚀 Alto Rendimiento - Algoritmos optimizados con sobrecarga mínima
🔒 Seguridad de Tipos - Configuración estricta de TypeScript previene errores en tiempo de ejecución

Instalación

npm

npm install @fintech-mex/clabe-sdk

yarn

yarn add @fintech-mex/clabe-sdk

pnpm

pnpm add @fintech-mex/clabe-sdk

Inicio Rápido

Clase SDK (Recomendado)

import { ClabeSDK } from '@fintech-mex/clabe-sdk';

// Crear instancia del SDK
const sdk = new ClabeSDK();

// Validar una CLABE
const result = sdk.validate('032180000118350004');
console.log(result.isValid); // true

// Generar una CLABE
const clabe = sdk.generate('032', '1234567890');
console.log(clabe); // '032012345678900004'

// Analizar componentes de CLABE
const info = sdk.parse('032180000118350004');
console.log(info.bankCode);      // '032'
console.log(info.accountNumber); // '18000011835'
console.log(info.bankName);      // 'IXE Banco, S.A.'

API Funcional (Tree-Shakeable)

import { validateClabe, generateClabe, parseClabe } from '@fintech-mex/clabe-sdk';

// Validar
const isValid = validateClabe('032180000118350004').isValid;

// Generar
const clabe = generateClabe('032', '1234567890');

// Analizar
const info = parseClabe('032180000118350004');

Ejemplos de Uso

Navegador (ES Modules)

<!DOCTYPE html>
<html>
<head>
    <script type="module">
        import { ClabeSDK } from 'https://unpkg.com/@fintech-mex/clabe-sdk/dist/esm/index.js';
        
        const sdk = new ClabeSDK();
        const result = sdk.validate('032180000118350004');
        console.log('CLABE es válida:', result.isValid);
    </script>
</head>
</html>

Navegador (UMD)

<!DOCTYPE html>
<html>
<head>
    <script src="https://unpkg.com/@fintech-mex/clabe-sdk/dist/umd/index.js"></script>
    <script>
        const sdk = new ClabeSDK.ClabeSDK();
        const result = sdk.validate('032180000118350004');
        console.log('CLABE es válida:', result.isValid);
    </script>
</head>
</html>

Node.js (CommonJS)

const { ClabeSDK } = require('@fintech-mex/clabe-sdk');

const sdk = new ClabeSDK();
const result = sdk.validate('032180000118350004');
console.log('CLABE es válida:', result.isValid);

Node.js (ES Modules)

import { ClabeSDK } from '@fintech-mex/clabe-sdk';

const sdk = new ClabeSDK();
const result = sdk.validate('032180000118350004');
console.log('CLABE es válida:', result.isValid);

React/Vue/Angular

import { ClabeSDK, validateClabe } from '@fintech-mex/clabe-sdk';

// En un componente React
function ValidadorClabe() {
  const [clabe, setClabe] = useState('');
  const [esValida, setEsValida] = useState(false);

  useEffect(() => {
    if (clabe.length === 18) {
      const result = validateClabe(clabe);
      setEsValida(result.isValid);
    }
  }, [clabe]);

  return (
    <input 
      value={clabe}
      onChange={(e) => setClabe(e.target.value)}
      className={esValida ? 'valid' : 'invalid'}
      placeholder="Ingresa tu CLABE de 18 dígitos"
    />
  );
}

Referencia de API

Clase ClabeSDK

Constructor

new ClabeSDK(config?: ClabeSDKConfig)

Parámetros:

config (opcional): Opciones de configuración

Opciones de Configuración:

interface ClabeSDKConfig {
  strictMode?: boolean;        // Validar que los códigos bancarios existan (default: false)
  includeBankInfo?: boolean;   // Incluir información bancaria en resultados (default: true)
  customBanks?: BankInfo[];    // Definiciones de bancos personalizados
}

Métodos

`validate(clabe: string): ValidationResult`

Valida una CLABE y devuelve resultados detallados.

const result = sdk.validate('032180000118350004');
console.log(result.isValid);  // true
console.log(result.errors);   // []

`isValid(clabe: string): boolean`

Verificación simple de validación booleana.

const esValida = sdk.isValid('032180000118350004'); // true

`generate(bankCode: string, accountNumber: string): string`

Genera una CLABE válida a partir de componentes.

const clabe = sdk.generate('032', '1234567890');
// Devuelve: '032012345678900004'

`parse(clabe: string): ClabeInfo`

Analiza una CLABE y extrae sus componentes.

const info = sdk.parse('032180000118350004');
// Devuelve: {
//   bankCode: '032',
//   accountNumber: '18000011835',
//   checkDigit: '0004',
//   isValid: true,
//   bankName: 'IXE Banco, S.A.'
// }

`getBankInfo(bankCode: string): BankInfo | null`

Obtiene información bancaria por código.

const banco = sdk.getBankInfo('032');
// Devuelve: { code: '032', name: 'IXE Banco, S.A.', shortName: 'IXE' }

API Funcional

Funciones de Validación

validateClabe(clabe: string): ValidationResult  // Validar CLABE con detalles
isValidClabe(clabe: string): boolean           // Validación simple booleana

Funciones de Generación

generateClabe(bankCode: string, accountNumber: string): string        // Generar CLABE
calculateCheckDigit(bankCode: string, accountNumber: string): string  // Calcular dígito verificador

Funciones de Análisis

parseClabe(clabe: string): ClabeInfo           // Analizar CLABE completa
extractBankCode(clabe: string): string         // Extraer código bancario
extractAccountNumber(clabe: string): string    // Extraer número de cuenta

Funciones de Utilidad

formatClabe(clabe: string): string    // Formatear CLABE
normalizeClabe(clabe: string): string // Normalizar CLABE

Manejo de Errores

El SDK proporciona tipos de error específicos para diferentes escenarios:

import { 
  InvalidClabeFormatError,    // Error de formato de CLABE
  InvalidBankCodeError,       // Error de código bancario
  InvalidAccountNumberError,  // Error de número de cuenta
  CheckDigitMismatchError     // Error de dígito verificador
} from '@fintech-mex/clabe-sdk';

try {
  const clabe = sdk.generate('999', '1234567890'); // Código bancario inválido
} catch (error) {
  if (error instanceof InvalidBankCodeError) {
    console.log('Código bancario inválido:', error.message);
  }
}

Soporte de TypeScript

El SDK está construido con TypeScript y proporciona definiciones de tipos completas:

import type { 
  ClabeInfo,        // Información de CLABE
  ValidationResult, // Resultado de validación
  BankInfo,         // Información bancaria
  ClabeSDKConfig    // Configuración del SDK
} from '@fintech-mex/clabe-sdk';

// Todos los tipos están completamente documentados con JSDoc
const info: ClabeInfo = sdk.parse('032180000118350004');

Rendimiento

Tamaño del Bundle: Librería principal < 10KB comprimida
Tree Shaking: Importa solo lo que necesitas
Tiempo de Ejecución: Rendimiento de validación O(1)
Memoria: Caché eficiente con limpieza automática

Compatibilidad de Navegadores

Navegadores Modernos: Chrome 63+, Firefox 67+, Safari 11.1+, Edge 79+
Soporte Legacy: Disponible vía build UMD con polyfills
Móviles: iOS Safari 11.3+, Chrome Mobile 63+

Compatibilidad de Node.js

Versiones LTS: Node.js 16.x, 18.x, 20.x+
Sistemas de Módulos: CommonJS y ES Modules
Estilos de Importación: require() e import

Contribuciones

¡Damos la bienvenida a las contribuciones! Por favor consulta nuestra Guía de Contribución para más detalles.

Configuración de Desarrollo

# Clonar el repositorio
git clone https://github.com/fintech-mex/clabe-sdk.git
cd clabe-sdk

# Instalar dependencias
npm install

# Ejecutar pruebas
npm test

# Construir todos los formatos
npm run build

# Ejecutar linting
npm run lint

Scripts Disponibles

npm run build - Construir todos los formatos de distribución (ESM, CJS, UMD, IIFE)
npm test - Ejecutar suite de pruebas con cobertura
npm run test:watch - Ejecutar pruebas en modo watch
npm run test:browser - Ejecutar pruebas de compatibilidad de navegador
npm run test:node - Ejecutar pruebas de compatibilidad de Node.js
npm run lint - Linting de código con ESLint
npm run format - Formatear código con Prettier
npm run typecheck - Ejecutar verificación de tipos de TypeScript

Licencia

Proyectos Relacionados

clabe-js - Implementación original en JavaScript
Especificación CLABE - Documentación oficial de CLABE

English Documentation

Features

✅ Full TypeScript Support - Complete type definitions and IntelliSense
🌐 Universal Compatibility - Works in browsers, Node.js, and edge environments
🌳 Tree-Shakeable - Import only what you need for optimal bundle size
🏗️ Clean Architecture - Domain-driven design with clear separation of concerns
🧪 Thoroughly Tested - 95%+ code coverage with comprehensive test suite
📚 Well Documented - Complete API documentation with examples
🚀 High Performance - Optimized algorithms with minimal overhead
🔒 Type Safe - Strict TypeScript configuration prevents runtime errors

Quick Start

import { ClabeSDK } from '@fintech-mex/clabe-sdk';

const sdk = new ClabeSDK();

// Validate CLABE
const result = sdk.validate('032180000118350004');
console.log(result.isValid); // true

// Generate CLABE
const clabe = sdk.generate('032', '1234567890');
console.log(clabe); // '032012345678900004'

// Parse CLABE
const info = sdk.parse('032180000118350004');
console.log(info.bankName); // 'IXE Banco, S.A.'

Documentation

📖 Complete API Documentation - Full API reference with examples
🚀 Usage Guide - Comprehensive usage guide for all environments
🔄 Migration Guide - Migrate from clabe-js library
💻 Examples - Framework-specific integration examples

CLABE Keywords for Developers

This library handles Mexican CLABE (Clave Bancaria Estandarizada) operations including:

clabe validation - Validate Mexican bank account numbers
clabe generation - Generate valid CLABE codes
clabe parsing - Extract bank and account information
mexican banking - Support for all Mexican banks
bank code validation - Verify Mexican bank codes
financial typescript - Type-safe financial operations
banking sdk - Complete banking utilities
clabe calculator - CLABE check digit calculation

Hecho con ❤️ en México 🇲🇽