Transform repository into a multi-language data file project with separated data and library releases

README.md

@@ -1,18 +1,101 @@
-Validação para cartão de crédito.
+Credit Card BIN Data - Data File Project
 ====================
 
-Bin e padrões para validação de cartão de crédito.
+**This is a data file project** similar to tzdata, providing credit card BIN (Bank Identification Number) patterns as a source of truth for other libraries.
 
-Repositório para esta [gist](https://gist.github.com/erikhenrique/5931368)
+This repository contains authoritative data about credit card BIN patterns for validation and brand identification, along with reference implementations in multiple programming languages.
 
-Os dados dos cartões: ~~Elo~~, Hipercard desta tabela *não* são oficiais.
-Tentei diversas vezes falar com o pessoal dessas bandeiras afim de ter uma informação oficial, porém, é muito difícil falar com o setor técnico e as atendentes nem sabem o que é bin de cartão :(
+Repository for this [gist](https://gist.github.com/erikhenrique/5931368)
 
-Esta tabela inicialmente foi montada com coleta de dados de cartões de crédito reais. Onde o usuário colocava o número do cartão de crédito dele e quando não conseguíamos saber qual a banheira pedíamos para que o usuário selecionasse a bandeira e desta forma armazenavamos os primeiros digitos do cartão.
+## 📁 Project Structure
 
-### Pull Request, contribua
+```
+bin-cc/
+├── data/                    # Source of truth - Credit card BIN data
+│   ├── brands.json         # All brand patterns (BIN, validation, CVV)
+│   └── README.md           # Data schema documentation
+│
+├── libs/                   # Reference implementations
+│   └── javascript/         # JavaScript/Node.js implementation
+│
+└── examples/               # Usage examples in different languages
+    ├── javascript-example.js
+    ├── python/
+    ├── elixir/
+    ├── ruby/
+    └── dotnet/
+```
 
-Fique a vontade para mandar um PR para que esta tabela permaneça atualizada. Ao fazer o PR por favor, informe como conseguiu essa informação de atualização para que possamos sempre ter dados confiáveis nesta tabela.
+## 🎯 Data Source
+
+The **authoritative data** is located in the [`data/`](./data) directory:
+- [`data/brands.json`](./data/brands.json) - Complete BIN patterns for all supported brands
+- [`data/README.md`](./data/README.md) - Full schema documentation
+
+## 📚 Implementations
+
+### JavaScript/Node.js
+Complete implementation available in [`libs/javascript/`](./libs/javascript/)
+
+**Installation:**
+```bash
+npm install creditcard-identifier
+```
+
+**Usage:**
+```javascript
+const cc = require('creditcard-identifier');
+console.log(cc.findBrand('4012001037141112')); // 'visa'
+```
+
+See [JavaScript documentation](./libs/javascript/README.md) for details.
+
+### Python
+Example implementation in [`examples/python/`](./examples/python/)
+
+### Elixir
+Example implementation in [`examples/elixir/`](./examples/elixir/)
+
+### Ruby
+Example implementation in [`examples/ruby/`](./examples/ruby/)
+
+### .NET
+Example implementation in [`examples/dotnet/`](./examples/dotnet/)
+
+## 🎴 Supported Card Brands
+
+| Brand      | Starts with                                  | Max length | CVV length |
+| ---------- | ------------------------------------------- | ---------- | ---------- |
+| Visa       | 4, 6367                                     | 13, 16     | 3          |
+| Mastercard | 5, 222100 to 272099                         | 16         | 3          |
+| Diners     | 301, 305, 36, 38                            | 14, 16     | 3          |
+| Elo        | 4011, 401178, 401179, 431274, 438935, etc.  | 16         | 3          |
+| Amex       | 34, 37                                      | 15         | 4          |
+| Discover   | 6011, 622, 64, 65                           | 16         | 4          |
+| Aura       | 50                                          | 16         | 3          |
+| Hipercard  | 38, 60                                      | 13, 16, 19 | 3          |
+
+**Note:** Some Brazilian brands (Elo, Hipercard, Aura) do not have official public documentation. Patterns collected from real-world usage.
+
+## 🤝 Contributing
+
+Contributions are welcome! To update BIN patterns or add new implementations:
+
+1. **Data updates:** Edit [`data/brands.json`](./data/brands.json) and document your source
+2. **New implementations:** Add to the appropriate language folder in `examples/`
+3. **Tests:** Ensure all tests pass before submitting
+
+Please provide the source of information when updating BIN patterns to maintain data reliability.
+
+## 📝 License
+
+MIT License
+
+## 👥 Contributors
+
+- @jotafelipe
+- @ahonorato 
+- @renatoelias
 
 
 | Bandeira   | Começa com                                  | Máximo de número | Máximo de número cvc |

data/README.md

@@ -0,0 +1,100 @@
+# Credit Card BIN Data Schema
+
+This directory contains the credit card BIN (Bank Identification Number) data files that serve as the source of truth for credit card brand identification.
+
+## File Structure
+
+### brands.json
+
+Contains an array of credit card brand objects with their validation patterns.
+
+**Schema:**
+
+```json
+[
+  {
+    "name": "string",        // Brand name (e.g., "visa", "mastercard", "amex")
+    "regexpBin": "string",   // Regular expression to identify the brand from the first digits (BIN)
+    "regexpFull": "string",  // Regular expression to validate the full card number
+    "regexpCvv": "string"    // Regular expression to validate the CVV/CVC code
+  }
+]
+```
+
+**Example:**
+
+```json
+{
+  "name": "visa",
+  "regexpBin": "^4|^6367",
+  "regexpFull": "^4[0-9]{12}(?:[0-9]{3})?|6367[0-9]{12}$",
+  "regexpCvv": "^\\d{3}$"
+}
+```
+
+## Supported Brands
+
+The following credit card brands are currently supported:
+
+- **Elo** - Brazilian credit card brand
+- **Diners** - Diners Club International
+- **Discover** - Discover Financial Services
+- **Hipercard** - Brazilian credit card brand
+- **Amex** (American Express)
+- **Aura** - Brazilian credit card brand
+- **Mastercard** - Mastercard Worldwide
+- **Visa** - Visa Inc.
+
+## Data Usage
+
+### For Library Developers
+
+If you're building a library that needs credit card validation data:
+
+```javascript
+// Method 1: Import the module
+const ccData = require('creditcard-identifier');
+const brands = ccData.data.brands;
+
+// Method 2: Load JSON directly
+const fs = require('fs');
+const path = require('path');
+const dataPath = require.resolve('creditcard-identifier/data/brands.json');
+const brands = JSON.parse(fs.readFileSync(dataPath, 'utf8'));
+```
+
+### For Application Developers
+
+If you're building an application and need to validate credit cards:
+
+```javascript
+const creditcard = require('creditcard-identifier');
+
+// Use the provided functions
+const brand = creditcard.findBrand('4012001037141112');
+const isSupported = creditcard.isSupported('4012001037141112');
+```
+
+## Contributing
+
+When contributing new brand data or updating existing patterns:
+
+1. Update the `data/brands.json` file
+2. Ensure the data follows the schema above
+3. Add test cases in `test/creditcard-identifier.test.js`
+4. Document the source of the information in your pull request
+5. Run `npm run test-unit` to verify all tests pass
+
+## Data Sources
+
+The data in this project has been collected from:
+
+- Real credit card samples (anonymized BIN patterns only)
+- Official brand documentation (where available)
+- Community contributions
+
+**Note:** Some brands (Elo, Hipercard, Aura) may not have official public documentation. The patterns for these brands have been collected from real-world usage and community input.
+
+## License
+
+This data is provided under the MIT license. See the main LICENSE file for details.

data/brands.json

@@ -0,0 +1,50 @@
+[
+  {
+    "name": "elo",
+    "regexpBin": "^401178|^401179|^431274|^438935|^451416|^457393|^457631|^457632|^504175|^627780|^636297|^636368|^(506699|5067[0-6]\\d|50677[0-8])|^(50900\\d|5090[1-9]\\d|509[1-9]\\d{2})|^65003[1-3]|^(65003[5-9]|65004\\d|65005[0-1])|^(65040[5-9]|6504[1-3]\\d)|^(65048[5-9]|65049\\d|6505[0-2]\\d|65053[0-8])|^(65054[1-9]|6505[5-8]\\d|65059[0-8])|^(65070\\d|65071[0-8])|^65072[0-7]|^(65090[1-9]|65091\\d|650920)|^(65165[2-9]|6516[6-7]\\d)|^(65500\\d|65501\\d)|^(65502[1-9]|6550[3-4]\\d|65505[0-8])",
+    "regexpFull": "^(401178|401179|431274|438935|451416|457393|457631|457632|504175|627780|636297|636368|(506699|5067[0-6]\\d|50677[0-8])|(50900\\d|5090[1-9]\\d|509[1-9]\\d{2})|65003[1-3]|(65003[5-9]|65004\\d|65005[0-1])|(65040[5-9]|6504[1-3]\\d)|(65048[5-9]|65049\\d|6505[0-2]\\d|65053[0-8])|(65054[1-9]|6505[5-8]\\d|65059[0-8])|(65070\\d|65071[0-8])|65072[0-7]|(65090[1-9]|65091\\d|650920)|(65165[2-9]|6516[6-7]\\d)|(65500\\d|65501\\d)|(65502[1-9]|6550[3-4]\\d|65505[0-8]))[0-9]{10,12}",
+    "regexpCvv": "^\\d{3}$"
+  },
+  {
+    "name": "diners",
+    "regexpBin": "^3(?:0[0-5]|[68][0-9])",
+    "regexpFull": "^3(?:0[0-5]|[68][0-9])[0-9]{11}$",
+    "regexpCvv": "^\\d{3}$"
+  },
+  {
+    "name": "discover",
+    "regexpBin": "^6(?:011|5[0-9]{2})",
+    "regexpFull": "^6(?:011|5[0-9]{2})[0-9]{12}$",
+    "regexpCvv": "^\\d{3}$"
+  },
+  {
+    "name": "hipercard",
+    "regexpBin": "^3841[046]0|^60",
+    "regexpFull": "^(38[0-9]{17}|60[0-9]{14})$",
+    "regexpCvv": "^\\d{3}$"
+  },
+  {
+    "name": "amex",
+    "regexpBin": "^3[47]",
+    "regexpFull": "^3[47][0-9]{13}$",
+    "regexpCvv": "^\\d{3,4}$"
+  },
+  {
+    "name": "aura",
+    "regexpBin": "^50[0-9]",
+    "regexpFull": "^50[0-9]{14,17}$",
+    "regexpCvv": "^\\d{3}$"
+  },
+  {
+    "name": "mastercard",
+    "regexpBin": "^5[1-5][0-9][0-9]|^2[2-7][0-2][0-9]",
+    "regexpFull": "^5[1-5][0-9]{14}$|^2[2-7][0-2][0-9]{13}$",
+    "regexpCvv": "^\\d{3}$"
+  },
+  {
+    "name": "visa",
+    "regexpBin": "^4|^6367",
+    "regexpFull": "^4[0-9]{12}(?:[0-9]{3})?|6367[0-9]{12}$",
+    "regexpCvv": "^\\d{3}$"
+  }
+]