nuban-predictor/README.md

Predicts Nigerian banks with a confidence score based on NUBAN account number.

# NUBAN Predictor

A lightweight JavaScript library to predict and validate Nigerian Uniform Bank Account Numbers (NUBAN). It uses the standard NUBAN algorithm combined with a smart ranking system based on account prefixes to handle collisions and provide the most likely bank.

## Features

- **Validate NUBAN**: Checks if a 10-digit account number is valid for a specific bank code.
- **Predict Bank**: Returns a list of possible banks for a given account number, sorted by confidence.
- **Smart Ranking**: Uses known account prefixes (e.g., '00' for GTB, '80' for OPay) to boost the confidence score of the correct bank.
- **Supports DMBs & OFIs**: Handles both Deposit Money Banks (3-digit code) and Other Financial Institutions (5-digit code).

## Installation

You can install this package via npm (once published) or include it directly in your project.

```bash
npm install nuban-predictor
```

## Usage

```javascript
const NubanPredictor = require('nuban-predictor');

const predictor = new NubanPredictor();

// Predict bank for an account number
const results = predictor.predict("0459803240");

console.log(results);
/*
Output:
[
  {
    name: 'Guaranty Trust Bank (GTB)',
    code: '058',
    type: 'DMB',
    prefixes: [ '00', '01', '02', '04', '05', '06' ],
    confidence: 60
  },
  ... other matches with lower confidence
]
*/
```

## API

### `new NubanPredictor()`

Creates a new instance of the predictor.

### `predictor.predict(accountNumber)`

- **accountNumber**: `string` - The 10-digit NUBAN account number.
- **Returns**: `Array` - An array of bank objects that match the NUBAN algorithm, sorted by confidence score (highest first).

### `predictor.validate(accountNumber, bankCode, type)`

- **accountNumber**: `string` - The 10-digit NUBAN.
- **bankCode**: `string` - The CBN bank code (e.g., "058" for GTB).
- **type**: `string` - "DMB" (Commercial Bank) or "OFI" (Microfinance/Fintech).
- **Returns**: `boolean` - True if the account number is valid for the bank code.

## License

ISC