npm package: @fintech-mex/clabe-sdk
Description: 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.
Author: fintech-mex
Latest version: 1.0.2

# CLABE SDK

[![npm version](https://badge.fury.io/js/@fintech-mex%2Fclabe-sdk.svg)](https://badge.fury.io/js/@fintech-mex%2Fclabe-sdk)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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.

*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](#documentación-en-español)**
- **🇺🇸 [English Documentation](#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
```bash
npm install @fintech-mex/clabe-sdk
```

#### yarn
```bash
yarn add @fintech-mex/clabe-sdk
```

#### pnpm
```bash
pnpm add @fintech-mex/clabe-sdk
```

### Inicio Rápido

#### Clase SDK (Recomendado)

```typescript
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)

```typescript
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)

```html
<!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)

```html
<!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)

```javascript
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)

```javascript
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

```typescript
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

```typescript
new ClabeSDK(config?: ClabeSDKConfig)
```

**Parámetros:**
- `config` (opcional): Opciones de configuración

**Opciones de Configuración:**
```typescript
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.

```typescript
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.

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

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

Genera una CLABE válida a partir de componentes.

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

###### `parse(clabe: string): ClabeInfo`

Analiza una CLABE y extrae sus componentes.

```typescript
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.

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

#### API Funcional

##### Funciones de Validación

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

##### Funciones de Generación

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

##### Funciones de Análisis

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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](CONTRIBUTING.md) para más detalles.

#### Configuración de Desarrollo

```bash
# 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

MIT © [fintech-mex](https://github.com/fintech-mex)

### Proyectos Relacionados

- [clabe-js](https://github.com/fintech-mex-mx/clabe-js) - Implementación original en JavaScript
- [Especificación CLABE](https://www.banxico.org.mx/) - 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

```typescript
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](./docs/api.md)** - Full API reference with examples
- 🚀 **[Usage Guide](./docs/usage-guide.md)** - Comprehensive usage guide for all environments
- 🔄 **[Migration Guide](./docs/migration-guide.md)** - Migrate from clabe-js library
- 💻 **[Examples](./docs/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 🇲🇽**