# Iranian Bank List Javascript

A Javascript library to identify Iranian banks based on card numbers (first 6 digits) and IBANs. It also includes utility functions to validate card numbers and IBANs using standard algorithms.

![GitHub Release](https://img.shields.io/github/v/release/masihgh/iranian-bank-list-js)
![NPM Downloads](https://img.shields.io/npm/d18m/iranian-bank-list?color=red)
![GitHub License](https://img.shields.io/github/license/masihgh/iranian-bank-list-js)
![GitHub Repo stars](https://img.shields.io/github/stars/masihgh/iranian-bank-list-js)
![GitHub forks](https://img.shields.io/github/forks/masihgh/iranian-bank-list-js)

> Note: This project uses part of the publicly available bank dataset from: <https://github.com/masihgh/iranian-bank-list>

## Getting Started

To get started with this package, you first need to install it via npm or yarn:

```bash
npm install iranian-bank-list
```

or

```bash
yarn add iranian-bank-list
```

Then, you can import and use the methods in your JavaScript or TypeScript project:

```js
import { getAllBanks, findByCardNumber, validateIbanChecksum } from 'iranian-bank-list';

const banks = getAllBanks();
const bank = findByCardNumber('6037991234567890');
const isValidIban = validateIbanChecksum('IR820540102680020817909002');

console.log(banks, bank, isValidIban);
```

## Methods

### 1. `getAllBanks()`

Returns an array of all bank objects with their inline SVG logos.

**Returns:**

```js
Array<Object>
```

**Example:**

```js
import { getAllBanks } from 'iranian-bank-list';

const banks = getAllBanks();
console.log(banks[0]);
// {
//   bank_name: "...",
//   bank_logo: "<svg>...</svg>",
//   card_regex: "...",
//   iban_regex: "...",
//   ...
// }
```

---

### 2. `getBankByCardNumber(cardNumber)`

Finds a bank object matching a given full card number using the bank's regex pattern.

**Parameters:**

- `cardNumber` (`string | number`): The full bank card number to check.

**Returns:**

- `Object | undefined` — The matching bank object or `undefined` if not found.

**Example:**

```js
import { getBankByCardNumber } from 'iranian-bank-list';

const bank = getBankByCardNumber('6273811234567890');
if (bank) {
  console.log(bank.bank_name);
}
```

---

### 3. `getBankByIban(iban)`

Finds a bank object matching a given IBAN string using the bank's regex pattern.

**Parameters:**

- `iban` (`string`): The full IBAN string to check.

**Returns:**

- `Object | undefined` — The matching bank object or `undefined` if not found.

**Example:**

```js
import { getBankByIban } from 'iranian-bank-list';

const bank = getBankByIban('IR820540102680020817909002');
if (bank) {
  console.log(bank.bank_name);
}
```

---

### 4. `validateIban(iban)`

Checks if the IBAN belongs to a known bank (using `getBankByIban`).

**Parameters:**

- `iban` (`string`): The IBAN string to validate.

**Returns:**

- `boolean` — `true` if IBAN matches a known bank, `false` otherwise.

**Example:**

```js
import { validateIban } from 'iranian-bank-list';

console.log(validateIban('IR820540102680020817909002'));  // true or false
```

---

### 5. `validateIranianCard(cardNumber)`

Validates an Iranian bank card number using the Luhn algorithm.

**Parameters:**

- `cardNumber` (`string | number`): The full 16-digit bank card number.

**Returns:**

- `boolean` — `true` if the card number is valid, `false` otherwise.

**Example:**

```js
import { validateIranianCard } from 'iranian-bank-list';

console.log(validateIranianCard('6273811234567890')); // true or false
```

---

### 6. `validateIbanChecksum(iban)`

Validates an IBAN string using the international standard mod-97 checksum.

**Parameters:**

- `iban` (`string`): The full IBAN string to validate.

**Returns:**

- `boolean` — `true` if the IBAN checksum is valid, `false` otherwise.

**Example:**

```js
import { validateIbanChecksum } from 'iranian-bank-list';

console.log(validateIbanChecksum('IR820540102680020817909002')); // true or false
```

---

### 7. `findByName(name)`

Finds a bank by its exact bank name (case-insensitive).

**Parameters:**

- `name` (`string`): The bank name to search for.

**Returns:**

- `Object | undefined` — Bank object if found, otherwise `undefined`.

**Example:**

```js
import { findByName } from './index.js';

const bank = findByName('melli');
console.log(bank);
```

---

### 8. findByCardNumber(cardNumber)

Finds a bank by full card number using the bank's card regex.

**Parameters:**

- `cardNumber` (`string|number`): The full card number.

**Returns:**

- `Object | undefined` — Bank object if found, otherwise `undefined`.

**Example:**

```js
import { findByCardNumber } from './index.js';

const bank = findByCardNumber('6037991234567890');
console.log(bank);
```

---

### 3. findByIBan(iban)

Finds a bank by full IBAN number using the bank's IBAN regex.

**Parameters:**

- `iban` (`string`): The full IBAN string.

**Returns:**

- `Object | undefined` — Bank object if found, otherwise `undefined`.

**Example:**

```js
import { findByIBan } from './index.js';

const bank = findByIBan('IR820540102680020817909002');
console.log(bank);
```

---

## License

This project is licensed under the [MIT License](./LICENSE.md).

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.