From f146ea8e50473dbff4b549bf1705dcc5f52f8209 Mon Sep 17 00:00:00 2001 From: Andres Contreras Date: Wed, 11 Feb 2026 09:31:23 +0100 Subject: [PATCH] docs: add professional README with unified template (#6) Standardize README.md with a consistent template including CI badge, features, installation, quick start, configuration, and documentation sections. Add paths-ignore to ci.yml to skip CI for docs-only changes. --- .github/workflows/ci.yml | 19 ++- README.md | 244 ++++++++++----------------------------- 2 files changed, 76 insertions(+), 187 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b9093b6..9567aee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,8 +2,22 @@ name: CI on: push: branches: [develop] + paths-ignore: + - '**.md' + - 'docs/**' + - 'tutorials/**' + - 'examples/**/README.md' + - 'LICENSE' + - '.gitignore' pull_request: branches: [develop, main] + paths-ignore: + - '**.md' + - 'docs/**' + - 'tutorials/**' + - 'examples/**/README.md' + - 'LICENSE' + - '.gitignore' workflow_dispatch: inputs: triggered-by: @@ -13,10 +27,5 @@ on: jobs: build: uses: fireflyframework/.github/.github/workflows/java-ci.yml@main - permissions: - packages: read - contents: read - actions: write with: java-version: '25' - secrets: inherit diff --git a/README.md b/README.md index e35df94..ebbcd18 100644 --- a/README.md +++ b/README.md @@ -1,219 +1,99 @@ -# Firefly Common Validators +# Firefly Framework - Validators [![CI](https://github.com/fireflyframework/fireflyframework-validators/actions/workflows/ci.yml/badge.svg)](https://github.com/fireflyframework/fireflyframework-validators/actions/workflows/ci.yml) -A comprehensive library providing robust validators for enterprise and mission-critical applications, part of the Firefly platform. +[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) +[![Java](https://img.shields.io/badge/Java-21%2B-orange.svg)](https://openjdk.org) +[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-green.svg)](https://spring.io/projects/spring-boot) -## Overview +> Financial and domain-specific Bean Validation validators for enterprise Java applications. -The Firefly Validators library provides a set of high-quality validation utilities specifically designed for enterprise applications. These validators ensure data integrity and compliance with international standards, helping you build robust and reliable financial software. +--- -## Features +## Table of Contents + +- [Overview](#overview) +- [Features](#features) +- [Requirements](#requirements) +- [Installation](#installation) +- [Quick Start](#quick-start) +- [Configuration](#configuration) +- [Documentation](#documentation) +- [Contributing](#contributing) +- [License](#license) + +## Overview + +Firefly Framework Validators provides a comprehensive set of Jakarta Bean Validation constraint annotations and their corresponding validators, purpose-built for financial services and enterprise applications. -This library contains validators for the following enterprise data validation formats: +Each validator is implemented as a custom constraint annotation paired with a `ConstraintValidator` implementation, making them composable with standard Bean Validation workflows. The library covers account numbers, IBAN, BIC/SWIFT, credit cards, CVV, currency codes, phone numbers, tax IDs, national IDs, interest rates, amounts, dates, PIN codes, sort codes, and password strength. -- **IBAN Validator**: Validates International Bank Account Numbers according to ISO 13616 standard -- **BIC Validator**: Validates Bank Identifier Codes (SWIFT codes) according to ISO 9362 standard -- **Credit Card Validator**: Validates credit card numbers for various card types using the Luhn algorithm -- **Currency Code Validator**: Validates ISO 4217 currency codes with special support for European currencies -- **Sort Code Validator**: Validates UK bank sort codes with formatting and parsing capabilities -- **Account Number Validator**: Validates bank account numbers for various countries with country-specific rules +## Features -Each validator provides comprehensive validation logic, helpful utility methods, and clear error reporting. +- `@ValidAccountNumber` - Account number format validation +- `@ValidIban` - IBAN (International Bank Account Number) validation +- `@ValidBic` - BIC/SWIFT code validation +- `@ValidCreditCard` - Credit card number validation (Luhn algorithm) +- `@ValidCVV` - Card verification value validation +- `@ValidCurrencyCode` - ISO 4217 currency code validation +- `@ValidPhoneNumber` - International phone number validation +- `@ValidTaxId` - Tax identification number validation +- `@ValidNationalId` - National identity document validation +- `@ValidAmount` - Monetary amount validation +- `@ValidInterestRate` - Interest rate range validation +- `@ValidDate` / `@ValidDateTime` - Date and datetime format validation +- `@ValidPIN` - Personal identification number validation +- `@ValidSortCode` - Bank sort code validation +- `@ValidPasswordStrength` - Password complexity validation ## Requirements -- Java 11 or higher -- Maven 3.6 or higher (for building) +- Java 21+ +- Spring Boot 3.x +- Maven 3.9+ ## Installation -Add the following dependency to your Maven `pom.xml`: - ```xml org.fireflyframework fireflyframework-validators - 1.0.0-SNAPSHOT + 26.01.01 ``` -For Gradle projects, add: - -```groovy -implementation 'org.fireflyframework:fireflyframework-validators:1.0.0-SNAPSHOT' -``` - -## Usage - -### IBAN Validator - -The IBAN (International Bank Account Number) validator checks if an IBAN is valid according to the ISO 13616 standard, including country-specific length validation, character set validation, and check digit verification. +## Quick Start ```java -IbanValidator validator = new IbanValidator(); - -// Validate an IBAN -boolean isValid = validator.isValid("DE89 3704 0044 0532 0130 00"); -// Returns: true +import org.fireflyframework.annotations.ValidIban; +import org.fireflyframework.annotations.ValidAmount; -// Invalid IBAN examples -boolean isTooShort = validator.isValid("DE89 3704 0044 0532 0130"); // Too short -boolean hasInvalidCountry = validator.isValid("US12 1234 5678 9012 3456"); // Invalid country code -``` +public class TransferRequest { -### BIC Validator + @ValidIban + private String recipientIban; -The BIC (Bank Identifier Code) validator, also known as SWIFT code validator, checks if a BIC is valid according to the ISO 9362 standard. It validates the format and provides methods to extract different parts of the BIC. + @ValidAmount + private BigDecimal amount; -```java -BicValidator validator = new BicValidator(); - -// Validate a BIC -boolean isValid = validator.isValid("DEUTDEFF"); -// Returns: true - -// Get parts of a BIC -String bankCode = validator.getBankCode("DEUTDEFF"); // Returns: "DEUT" -String countryCode = validator.getCountryCode("DEUTDEFF"); // Returns: "DE" -String locationCode = validator.getLocationCode("DEUTDEFF"); // Returns: "FF" -String branchCode = validator.getBranchCode("DEUTDEFF"); // Returns: "XXX" (default) -``` - -### Credit Card Validator - -The Credit Card validator checks if a credit card number is valid using the Luhn algorithm and card-specific patterns. It can identify the card type and mask the card number for display purposes. - -```java -CreditCardValidator validator = new CreditCardValidator(); - -// Validate a credit card number -boolean isValid = validator.isValid("4111 1111 1111 1111"); -// Returns: true - -// Get the card type -CreditCardValidator.CardType cardType = validator.getCardType("4111 1111 1111 1111"); -// Returns: CardType.VISA - -// Mask a card number for display -String masked = validator.maskCardNumber("4111 1111 1111 1111"); -// Returns: "************1111" + @ValidCurrencyCode + private String currency; +} ``` -Supported card types: -- Visa -- MasterCard -- American Express -- Discover -- Diners Club -- JCB +## Configuration -### Currency Code Validator - -The Currency Code validator checks if a currency code is valid according to the ISO 4217 standard. It provides special methods for checking Euro and European currencies. - -```java -CurrencyCodeValidator validator = new CurrencyCodeValidator(); +No configuration is required. Validators are automatically discovered by the Jakarta Bean Validation provider. -// Validate a currency code -boolean isValid = validator.isValid("EUR"); -// Returns: true +## Documentation -// Check if it's the Euro currency -boolean isEuro = validator.isEuroCurrency("EUR"); -// Returns: true - -// Check if it's a European currency -boolean isEuropean = validator.isEuropeanCurrency("GBP"); -// Returns: true - -// Invalid currency code examples -boolean isTooLong = validator.isValid("EURO"); // Too long -boolean isTooShort = validator.isValid("EU"); // Too short -boolean isNonExistent = validator.isValid("ABC"); // Non-existent code -``` - -### Sort Code Validator - -The Sort Code validator checks if a UK bank sort code is valid. It provides methods to normalize, format, and extract parts of the sort code. - -```java -SortCodeValidator validator = new SortCodeValidator(); - -// Validate a sort code -boolean isValid = validator.isValid("12-34-56"); -// Returns: true - -// Normalize a sort code (remove separators) -String normalized = validator.normalize("12-34-56"); -// Returns: "123456" - -// Format a sort code with hyphens -String formatted = validator.format("123456"); -// Returns: "12-34-56" - -// Get parts of a sort code -String bankId = validator.getBankIdentifier("12-34-56"); // Returns: "12" -String branchId = validator.getBranchIdentifier("12-34-56"); // Returns: "3456" -``` - -### Account Number Validator - -The Account Number validator checks if a bank account number is valid for a specific country. It has special support for UK account numbers and bank accounts. - -```java -AccountNumberValidator validator = new AccountNumberValidator(); - -// Validate an account number for a specific country -boolean isValid = validator.isValid("12345678", "GB"); -// Returns: true - -// Validate a UK account number -boolean isValidUk = validator.isValidUkAccountNumber("12345678"); -// Returns: true - -// Validate a UK bank account (sort code + account number) -boolean isValidAccount = validator.isValidUkBankAccount("12-34-56", "12345678"); -// Returns: true - -// Format a UK bank account -String formatted = validator.formatUkBankAccount("12-34-56", "12345678"); -// Returns: "12-34-56 12345678" -``` - -Supported countries include: -- GB (United Kingdom): 8 digits -- FR (France): 10 digits -- DE (Germany): 10 digits -- ES (Spain): 10 digits -- IT (Italy): 12 digits -- NL (Netherlands): 10 digits -- BE (Belgium): 12 digits -- CH (Switzerland): 4-11 digits - -## Standards Compliance - -This library is designed to comply with the following international standards: - -- **ISO 13616**: International Bank Account Number (IBAN) -- **ISO 9362**: Business Identifier Code (BIC) -- **ISO/IEC 7812**: Identification cards - Identification of issuers -- **ISO 4217**: Currency codes -- **UK Financial Standards**: Sort codes and account numbers - -## Dependencies - -- **Apache Commons Validator (1.7)**: Used for some validation utilities -- **JUnit 5 (5.9.2)**: Used for testing (test scope only) -- **AssertJ (3.24.2)**: Used for fluent assertions in tests (test scope only) +No additional documentation available for this project. ## Contributing -Contributions to the Firefly Validators library are welcome! Please follow these steps: +Contributions are welcome. Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details on our code of conduct, development process, and how to submit pull requests. + +## License -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'Add some amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request +Copyright 2024-2026 Firefly Software Solutions Inc. -Please ensure your code follows the existing style and includes appropriate tests. +Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.