{"id":36499268,"url":"https://github.com/juspay/cards-validator","last_synced_at":"2026-01-15T02:58:28.780Z","repository":{"id":321787617,"uuid":"1087223409","full_name":"juspay/cards-validator","owner":"juspay","description":"Simple card validator","archived":false,"fork":false,"pushed_at":"2026-01-09T14:45:59.000Z","size":101,"stargazers_count":1,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"release","last_synced_at":"2026-01-12T04:49:36.280Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/juspay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-31T15:05:10.000Z","updated_at":"2026-01-09T14:46:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/juspay/cards-validator","commit_stats":null,"previous_names":["sandeepsj/simple-card-validator-ts","juspay/cards-validator"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/juspay/cards-validator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juspay%2Fcards-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juspay%2Fcards-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juspay%2Fcards-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juspay%2Fcards-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/juspay","download_url":"https://codeload.github.com/juspay/cards-validator/tar.gz/refs/heads/release","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/juspay%2Fcards-validator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28441904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-12T02:16:45.356Z","updated_at":"2026-01-15T02:58:28.774Z","avatar_url":"https://github.com/juspay.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 💳 Cards Validator\n\n### A comprehensive JS/TS library for validating credit and debit card numbers\n\n[![npm version](https://img.shields.io/npm/v/@juspay/cards-validator.svg)](https://www.npmjs.com/package/@juspay/cards-validator)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@juspay/cards-validator)](https://bundlephobia.com/package/@juspay/cards-validator)\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n🎯 **Card Type Detection**  \nAutomatically detects 12+ major card types including Visa, MasterCard, American Express, Discover, JCB, Maestro, RuPay, UnionPay, and more\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n✅ **Luhn Algorithm Validation**  \nImplements the industry-standard Luhn algorithm for card number validation\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n📏 **Length Validation**  \nValidates card number length based on card type specifications\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n🔢 **CVV Length Information**  \nProvides valid CVV lengths for each detected card type\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n🎨 **Range-based Detection**  \nUses both regex patterns and BIN ranges for accurate card type identification\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n📘 **TypeScript Support**  \nFully typed with comprehensive type definitions\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd colspan=\"2\" align=\"center\"\u003e\n\n⚡ **Zero Dependencies**  \nLightweight library with no external dependencies\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## 💳 Supported Card Types\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cb\u003eClick to view all supported card types\u003c/b\u003e\u003c/summary\u003e\n\n| 🏦 Card Type | 🔍 Pattern/Range | 📏 Valid Lengths | 🔢 CVV Length |\n|--------------|------------------|------------------|---------------|\n| 🔵 Visa | `^4` | 16 | 3 |\n| 🔴 MasterCard | BIN ranges 222100-272099, 510000-559999 | 16 | 3 |\n| 🔵 American Express | `^3[47]` | 15 | 4 |\n| 🟠 Discover | `^(6011\\|622...)` | 16 | 3 |\n| 🟢 JCB | `^35(2[89]\\|[3-8][0-9])` | 16 | 3 |\n| 🔴 Maestro | `^(5018\\|5081\\|...)` | 12-19 | 0, 3 |\n| 🟣 RuPay | BIN ranges | 16 | 3 |\n| 🔵 UnionPay | `^6[0289]\\|9[0245689]...` | 16-19 | 3 |\n| ⚪ Diners Club | `^30[0-5]`, `^3([689]\\|09)` | 14 | 3 |\n| 🟢 Laser | `^(6304\\|670[69]\\|6771)` | 16-19 | 3, 4 |\n| 🔵 Visa Electron | `^(4026\\|417500\\|...)` | 16 | 3 |\n| 🟠 Sodexo | `^(637513)` | 16 | 3 |\n\n\u003c/details\u003e\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install @juspay/cards-validator\n```\n\n**Alternative package managers:**\n\n```bash\n# Using Yarn\nyarn add @juspay/cards-validator\n\n# Using pnpm\npnpm add @juspay/cards-validator\n```\n\n---\n\n## 🚀 Usage\n\n### 🎯 Basic Usage\n\n```typescript\nimport CardValidator from '@juspay/cards-validator';\n\n// Create a new validator instance\nconst validator = new CardValidator('4111111111111111');\n\n// Get card validation details\nconst result = validator.getCardDetails();\n\nconsole.log(result);\n// Output:\n// {\n//   card_type: 'visa',\n//   valid: true,\n//   luhn_valid: true,\n//   length_valid: true,\n//   cvv_length: [3],\n//   supported_lengths: [16]\n// }\n```\n\n### 🔧 Advanced Usage\n\n```typescript\nimport CardValidator, { CardDetails } from '@juspay/cards-validator';\n\n// Validate different card types\nconst cards = [\n  '4111111111111111',    // Visa\n  '5555555555554444',    // MasterCard\n  '378282246310005',     // American Express\n  '6011111111111117',    // Discover\n];\n\ncards.forEach(cardNumber =\u003e {\n  const validator = new CardValidator(cardNumber);\n  const result: CardDetails = validator.getCardDetails();\n\n  console.log(`Card: ${cardNumber}`);\n  console.log(`Type: ${result.card_type}`);\n  console.log(`Valid: ${result.valid}`);\n  console.log(`CVV Length: ${result.cvv_length.join(', ')}`);\n  console.log('---');\n});\n```\n\n### 🔄 Handling Spaces and Dashes\n\nThe library automatically normalizes card numbers by removing spaces and dashes:\n\n```typescript\nconst validator1 = new CardValidator('4111 1111 1111 1111');\nconst validator2 = new CardValidator('4111-1111-1111-1111');\nconst validator3 = new CardValidator('4111111111111111');\n\n// All three will produce the same result\nconsole.log(validator1.getCardDetails().valid); // true\nconsole.log(validator2.getCardDetails().valid); // true\nconsole.log(validator3.getCardDetails().valid); // true\n```\n\n---\n\n## 📚 API Reference\n\n### 🏗️ CardValidator Class\n\n#### Constructor\n\n```typescript\nnew CardValidator(cardNumber: string)\n```\n\n- `cardNumber`: The credit card number to validate (string)\n\n#### Methods\n\n##### 📋 `getCardDetails(): CardDetails`\n\nReturns a comprehensive validation result object.\n\n---\n\n### 📝 Types\n\n#### 📊 `CardDetails`\n\n```typescript\ninterface CardDetails {\n  card_type: string;           // Detected card type (e.g., 'visa', 'mastercard', 'amex', 'unknown')\n  valid: boolean;              // Overall validity (luhn_valid \u0026\u0026 length_valid)\n  luhn_valid: boolean;         // Whether card passes Luhn algorithm check\n  length_valid: boolean;       // Whether card length is valid for detected type\n  cvv_length: number[];        // Valid CVV lengths for this card type, e.g., [3] or [3, 4]\n  supported_lengths: number[]; // Valid card number lengths, e.g., [16] or [12,13,14,15,16,17,18,19]\n}\n```\n\n#### 💳 `CardType`\n\n```typescript\ninterface CardType {\n  name: string;\n  valid_length: number[];\n  cvv_length: number[];\n  pattern?: RegExp;      // For pattern-based detection\n  range?: number[][];    // For BIN range-based detection\n  gaps?: number[];       // Optional: for formatting (e.g., Sodexo)\n}\n```\n\n---\n\n## 💡 Examples\n\n### 🎨 Validate and Format Card Information\n\n```typescript\nimport CardValidator from '@juspay/cards-validator';\n\nfunction formatCardInfo(cardNumber: string) {\n  const validator = new CardValidator(cardNumber);\n  const result = validator.getCardDetails();\n\n  if (result.valid) {\n    return {\n      isValid: true,\n      cardType: result.card_type.replace('_', ' ').toUpperCase(),\n      cvvLength: result.cvv_length,\n      message: `Valid ${result.card_type} card`\n    };\n  } else {\n    return {\n      isValid: false,\n      cardType: result.card_type,\n      issues: [\n        !result.luhn_valid \u0026\u0026 'Invalid checksum',\n        !result.length_valid \u0026\u0026 'Invalid length'\n      ].filter(Boolean),\n      message: 'Invalid card number'\n    };\n  }\n}\n\n// Examples\nconsole.log(formatCardInfo('4111111111111111'));\n// { isValid: true, cardType: 'VISA', cvvLength: [3], message: 'Valid visa card' }\n\nconsole.log(formatCardInfo('4111111111111112'));\n// { isValid: false, cardType: 'visa', issues: ['Invalid checksum'], message: 'Invalid card number' }\n```\n\n---\n\n## 🛠️ Development\n\n### ⚙️ Prerequisites\n\n- Node.js (version 14 or higher)\n- npm, yarn, or pnpm\n\n### 🔧 Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/juspay/cards-validator.git\ncd cards-validator\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run tests\nnpm test\n\n# Run development mode with watch\nnpm run dev\n```\n\n### 📜 Scripts\n\n| Script | Description |\n|--------|-------------|\n| `npm run build` | 🔨 Compile TypeScript to JavaScript |\n| `npm run dev` | 👀 Watch mode for development |\n| `npm test` | 🧪 Run test suite |\n| `npm run clean` | 🧹 Remove build artifacts |\n| `npm run lint` | 🔍 Run ESLint |\n| `npm run format` | ✨ Format code with Prettier |\n\n---\n\n## 🧪 Testing\n\nThe library includes comprehensive tests covering:\n\n✅ Card type detection for all supported card types  \n✅ Luhn algorithm validation  \n✅ Length validation  \n✅ Edge cases and error handling  \n✅ Input normalization (spaces, dashes)\n\nRun tests with:\n\n```bash\nnpm test\n```\n\n---\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n---\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 📋 Changelog\n\n### v0.1.0\n- ✨ Initial release\n- 💳 Support for 12+ major card types\n- ✅ Luhn algorithm validation\n- 📏 Length validation\n- 📘 TypeScript support\n- 🧪 Comprehensive test suite\n\n---\n\n## 🙏 Acknowledgments\n\n- 🔐 [Luhn Algorithm](https://en.wikipedia.org/wiki/Luhn_algorithm) for card number validation\n- 💳 Card type patterns and ranges based on industry standards\n- 🌟 Inspired by various open-source card validation libraries\n\n---\n\n## 📞 Support\n\nIf you encounter any issues or have questions, please file an issue on the [GitHub repository](https://github.com/juspay/cards-validator/issues).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nMade with ❤️ by [Juspay Technologies](https://juspay.in)\n\n⭐ Star us on [GitHub](https://github.com/juspay/cards-validator) — it helps us grow!\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuspay%2Fcards-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjuspay%2Fcards-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjuspay%2Fcards-validator/lists"}