clabe-validator 1.7.1

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-2021 individual contributors to CLABE Validator
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# CLABE Validator
+<img src=https://centerkey.com/graphics/center-key-logo.svg align=right width=200 alt=logo>
+
+_JavaScript library to analyze or create a CLABE number for a Mexican bank account_
+
+[![License:MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/center-key/clabe-validator/blob/main/LICENSE.txt)
+[![npm](https://img.shields.io/npm/v/clabe-validator.svg)](https://www.npmjs.com/package/clabe-validator)
+[![Vulnerabilities](https://snyk.io/test/github/center-key/clabe-validator/badge.svg)](https://snyk.io/test/github/center-key/clabe-validator)
+[![Hits](https://data.jsdelivr.com/v1/package/npm/clabe-validator/badge?style=rounded)](https://www.jsdelivr.com/package/npm/clabe-validator)
+[![Build](https://github.com/center-key/clabe-validator/workflows/build/badge.svg)](https://github.com/center-key/clabe-validator/actions?query=workflow%3Abuild)
+
+CLABE (Clave Bancaria Estandarizada &mdash; Spanish for "standardized banking code") is a banking
+standard from the Mexican Bank Association (Asociación de Bancos de México &mdash; ABM) for
+uniform numbering of bank accounts.&nbsp; CLABE numbers are 18 digits long.&nbsp;
+See: https://en.wikipedia.org/wiki/CLABE
+
+## A) Online Form
+Try it out:<br>
+[https://centerkey.com/clabe](https://centerkey.com/clabe/)
+
+## B) Setup
+### Web browser
+Include in a web page:
+```html
+<script src=clabe.min.js></script>
+```
+or from the [jsdelivr.com CDN](https://www.jsdelivr.com/package/npm/clabe-validator):
+```html
+<script src=https://cdn.jsdelivr.net/npm/clabe-validator@1.7/dist/clabe.min.js></script>
+```
+### Node.js server
+Install package for node:
+```shell
+$ npm install clabe-validator
+```
+Import package:
+```javascript
+import { clabe } from 'clabe-validator';
+```
+Or for older CommonJS/UMD environments:
+```javascript
+const { clabe } = require('clabe-validator');  //deprecated
+```
+
+**Note:** _Release v1.4.0 contains a significant number of bank and city code additions plus
+updates to reflect financial institution mergers and name changes._
+
+## C) Validator Usage
+Pass the CLABE number as an 18-character string into `clabe.validate(clabeNum)`.
+
+### 1. Example JavaScript code
+```javascript
+const clabeNum = '002010077777777771';
+const clabeCheck = clabe.validate(clabeNum);
+console.log(clabeCheck.ok ? '¡Que bueno!' : '¡Muy mal!');
+console.log('Your bank: ' + clabeCheck.bank);
+```
+
+### 2. Example JSON result for a valid CLABE number
+```javascript
+{
+   ok:       true,
+   formatOk: true,
+   error:    null,
+   message:  'Valid',
+   clabe:    '002010077777777771',
+   tag:      'BANAMEX',
+   bank:     'Banco Nacional de México, S.A.',
+   city:     'Aguascalientes MX-AGU',
+   account:  '07777777777',
+   code:     { bank: '002', city: '010' },
+   checksum: 1,
+}
+```
+
+### 3. Example JSON result for an invalid CLABE number
+```javascript
+{
+   ok:       false,
+   formatOk: true,
+   error:    'invalid-city',
+   message:  'Invalid city code: 000',
+}
+```
+The `formatOk` field indicates if the CLABE's length and checksum are both valid (even if the bank
+code or city code are unknown).
+
+### 4. Possible errors
+| Error code           | Error message                                   | Format Ok |
+| -------------------- | ----------------------------------------------- | ----------|
+| `invalid-length`     | Must be exactly 18 digits long                  | `false`   |
+| `invalid-characters` | Must be only numeric digits (no letters)        | `false`   |
+| `invalid-checksum`   | Invalid checksum, last digit should be: [DIGIT] | `false`   |
+| `invalid-bank`       | Invalid bank code: [CODE]                       | `true`    |
+| `invalid-city`       | Invalid city code: [CODE]                       | `true`    |
+
+## D) Calculator Usage
+Pass the bank code, city code, and account number into
+`clabe.calculate(bankCode, cityCode, accountNumber)`
+and get the 18-character CLABE number back.
+
+```javascript
+const clabeNum = clabe.calculate(2, 10, 7777777777);
+console.log(clabeNum === '002010077777777771');  //true
+```
+
+## E) TypeScript Declarations
+The **TypeScript Declaration File** file is [clabe.d.ts](dist/clabe.d.ts) in the **dist** folder.
+
+The `clabe.validate(clabeNum: string)` function returns a `ClabeCheck` object:
+```typescript
+type ClabeCheck = {
+   ok:       boolean,
+   formatOk: boolean,
+   error:    string | null,
+   message:  string,
+   clabe:    string | null,
+   tag:      string | null,
+   bank:     string | null,
+   city:     string | null,
+   account:  string,
+   code:     { bank: string, city: string },
+   checksum: number | null,
+   };
+```
+
+Example TypeScript usage with explicit types:
+```typescript
+import { clabe, ClabeCheck } from 'clabe-validator';
+
+const clabeNum: string =       '002010077777777771';
+const clabeCheck: ClabeCheck = clabe.validate(clabeNum);  //{ ok: true, error: null, ... }
+const bankCode: string =       clabeCheck.code.bank;      //'002'
+```
+
+## F) Contributor Notes
+To be a contributor, **fork** the project and run the commands `npm install` and `npm test` on your
+local clone.&nbsp; Make your edits and rerun the tests.&nbsp; Pull requests welcome.
+
+## G) Genesis
+The origin of this project goes back to when I needed to send money to Guanajuato, Mexico to pay
+nurses who were providing medical care of a relative.&nbsp;
+I was initially unable to transfer funds because the money transfer service reported that the CLABE
+number I supplied was invalid.&nbsp;
+Through a little sleuthing and a lot of luck, I discovered that a financial services company had
+accidentally omitted the very last modulo operation in their CLABE checksum calculation.&nbsp;
+The result was that Mexican bank account numbers ending in a zero were rejected.
+
+This project was created to fix the checksum bug.&nbsp;
+It is an open source community project and is not supported by any company.
+<br>
+
+---
+Feel free to submit questions at:<br>
+[github.com/center-key/clabe-validator/issues](https://github.com/center-key/clabe-validator/issues)
+
+CLABE Validator code is open source under the [MIT License](LICENSE.txt),
+and the documentation is published under the
+[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0) license.

package/dist/clabe.d.ts

@@ -0,0 +1,39 @@
+//! clabe-validator v1.7.1 ~ https://github.com/center-key/clabe-validator ~ MIT License
+
+export declare type ClabeBank = {
+    tag?: string;
+    name?: string;
+};
+export declare type ClabeBanksMap = {
+    [bankCode: number]: ClabeBank;
+};
+export declare type ClabeCity = [number, string];
+export declare type ClabeCitiesMap = {
+    [cityCode: number]: string;
+};
+export declare type ClabeCheck = {
+    ok: boolean;
+    formatOk: boolean;
+    error: string | null;
+    message: string;
+    clabe: string | null;
+    tag: string | null;
+    bank: string | null;
+    city: string | null;
+    account: string;
+    code: {
+        bank: string;
+        city: string;
+    };
+    checksum: number | null;
+};
+declare const clabe: {
+    version: string;
+    computeChecksum(clabeNum17: string): number | null;
+    validate(clabeNum: string): ClabeCheck;
+    calculate(bankCode: number, cityCode: number, accountNumber: number): string;
+    banksMap: ClabeBanksMap;
+    cities: ClabeCity[];
+    citiesMap: ClabeCitiesMap;
+};
+export { clabe };