Tawfir.Toolkit 1.0.8

Tawfir.Toolkit

A comprehensive .NET utilities library containing validation attributes and helper classes for common operations including encryption, calculations, random generation, and validation (KSA ID, Email, etc.).

Installation

dotnet add package Tawfir.Toolkit

Features

• 🛡️ Card Analyzer - Fraud Prevention: Advanced credit card analysis with Luhn validation, BIN detection, geographic validation, and real-time fraud detection
• Validation Attributes: KSA ID, Saudi National ID, Non-Saudi Iqama, Email, Arabic Text, and English Text validation attributes
• Static Validators: Programmatic validation methods for all validation types
• Multilingual Text Validation: Comprehensive support for Arabic and English text validation with flexible options
• Helper Classes: Encryption, card expressions, and random generation
• Regex Patterns: Pre-defined regex patterns for common validations including enhanced Arabic and English patterns

Note: NuGet package includes icon.png for package display

Validation Attributes

KsaId

Use as a validation attribute for any KSA ID (Saudi or Non-Saudi):

using Tawfir.Toolkit.Validator;
using System.ComponentModel.DataAnnotations;

public class UserModel
{
    [KsaId(ErrorMessage = "Invalid KSA ID")]
    public string KsaIdNumber { get; set; }
    
    // Or use with Required attribute
    [Required]
    [KsaId(ErrorMessage = "KSA ID is required and must be valid")]
    public string NationalId { get; set; }
}

The attribute validates:

• 10-digit format
• Correct prefix (1 for Saudi, 2 for Non-Saudi)
• Checksum algorithm validity

SaudiNationalId

Use specifically for Saudi National Id numbers (must start with 1):

using Tawfir.Toolkit.Validator;
using System.ComponentModel.DataAnnotations;

public class SaudiUserModel
{
    [SaudiNationalId(ErrorMessage = "Invalid Saudi National Id")]
    public string SaudiNationalIdNumber { get; set; }
    
    // Or use with Required attribute
    [Required(ErrorMessage = "Saudi National Id is required")]
    [SaudiNationalId(ErrorMessage = "Must be a valid Saudi National Id starting with 1")]
    public string NationalId { get; set; }
}

The SaudiNationalId attribute validates:

• All standard Civil ID validations (format, checksum)
• Additional check: Must start with digit 1 (Saudi nationals only)

NonSaudiIqama

Use specifically for Non-Saudi Iqama numbers (must start with 2):

using Tawfir.Toolkit.Validator;
using System.ComponentModel.DataAnnotations;

public class NonSaudiUserModel
{
    [NonSaudiIqama(ErrorMessage = "Invalid Non-Saudi Iqama")]
    public string IqamaNumber { get; set; }
    
    // Or use with Required attribute
    [Required(ErrorMessage = "Non-Saudi Iqama is required")]
    [NonSaudiIqama(ErrorMessage = "Must be a valid Non-Saudi Iqama starting with 2")]
    public string IqamaId { get; set; }
}

The NonSaudiIqama attribute validates:

• All standard Civil ID validations (format, checksum)
• Additional check: Must start with digit 2 (Non-Saudi nationals only)

Email

Use for email address validation:

using Tawfir.Toolkit.Validator;
using System.ComponentModel.DataAnnotations;

public class UserModel
{
    [Email(ErrorMessage = "Invalid email address")]
    public string EmailAddress { get; set; }
    
    // Or use with Required attribute
    [Required(ErrorMessage = "Email is required")]
    [Email(ErrorMessage = "Must be a valid email address")]
    public string ContactEmail { get; set; }
}

The Email attribute validates:

• Valid email format using regex pattern
• Standard email format requirements

TextArabic

Use for Arabic text validation with comprehensive Unicode support:

using Tawfir.Toolkit.Validator;
using System.ComponentModel.DataAnnotations;

public class ContentModel
{
    // Basic Arabic text validation
    [TextArabic(ErrorMessage = "يجب أن يكون النص بالعربية فقط")]
    public string Description { get; set; }
    
    // Arabic name validation (letters only, no numbers)
    [TextArabic(NameOnly = true, ErrorMessage = "الاسم يجب أن يكون بالأحرف العربية فقط")]
    public string Name { get; set; }
    
    // Arabic text with diacritics (Tashkeel)
    [TextArabic(AllowDiacritics = true)]
    public string TextWithTashkeel { get; set; }
    
    // Arabic text with Arabic numerals
    [TextArabic(AllowArabicNumerals = true)]
    public string AddressWithNumbers { get; set; }
    
    // Combined with Required
    [Required]
    [TextArabic(NameOnly = true)]
    public string FullName { get; set; }
}

The TextArabic attribute validates:

• Full Unicode Arabic character support (U+0600-U+06FF and extended ranges)
• Arabic Supplement, Extended-A, and Presentation Forms
• Optional diacritics (Tashkeel) support
• Optional name-only validation (letters only, no numbers)
• Optional Arabic numerals support (٠-٩, ۰-۹)

Supported Unicode Ranges:

• Arabic (U+0600-U+06FF)
• Arabic Supplement (U+0750-U+077F)
• Arabic Extended-A (U+08A0-U+08FF)
• Arabic Presentation Forms-A (U+FB50-U+FDFF)
• Arabic Presentation Forms-B (U+FE70-U+FEFF)
• Arabic Diacritics (U+064B-U+065F)

TextEnglish

Use for English text validation with various options:

using Tawfir.Toolkit.Validator;
using System.ComponentModel.DataAnnotations;

public class ContentModel
{
    // Basic English text validation (letters only)
    [TextEnglish(ErrorMessage = "Text must be in English only")]
    public string Description { get; set; }
    
    // English name validation (letters and hyphens)
    [TextEnglish(NameOnly = true, ErrorMessage = "Name must contain only English letters")]
    public string FullName { get; set; }
    
    // English text with punctuation
    [TextEnglish(AllowPunctuation = true)]
    public string Comment { get; set; }
    
    // English text with numbers
    [TextEnglish(AllowNumbers = true)]
    public string AddressLine { get; set; }
    
    // Combined with Required
    [Required]
    [TextEnglish(NameOnly = true)]
    public string FirstName { get; set; }
}

The TextEnglish attribute validates:

• English letters only (A-Z, a-z) by default
• Optional name validation (allows hyphens for names like "Mary-Jane")
• Optional punctuation support (.,!?;:'-)
• Optional alphanumeric support (letters + numbers)

Note: All attributes allow null/empty values by default. Use [Required] if the field is mandatory.

Static Validator Methods

You can also validate programmatically:

using Tawfir.Toolkit.Validator;

// Validate any Civil ID (Saudi or Non-Saudi)
bool isValid = KsaIdValidator.IsValid("1234567890");

// Validate specifically for Saudi National Id (must start with 1)
bool isSaudiValid = KsaSaudiNationalIdValidator.IsValid("1234567890");

// Validate specifically for Non-Saudi Iqama (must start with 2)
bool isNonSaudiValid = KsaNonSaudiIqamaValidator.IsValid("2234567890");

// Validate email address
bool isValidEmail = EmailValidator.IsValid("user@example.com");

// Validate Arabic text
bool isArabicValid = TextArabicValidator.IsValid("مرحبا بك");

// Validate Arabic text with diacritics
bool isArabicWithDiacritics = TextArabicValidator.IsValidWithDiacritics("مَرْحَباً");

// Validate Arabic name (letters only)
bool isArabicName = TextArabicValidator.IsValidName("محمد أحمد");

// Validate Arabic text with Arabic numerals
bool isArabicWithNumerals = TextArabicValidator.IsValidWithArabicNumerals("الشارع ١٢");

// Validate English text
bool isEnglishValid = TextEnglishValidator.IsValid("Hello World");

// Validate English text with punctuation
bool isEnglishWithPunctuation = TextEnglishValidator.IsValidWithPunctuation("Hello, World!");

// Validate English name (with hyphens)
bool isEnglishName = TextEnglishValidator.IsValidName("Mary-Jane Smith");

// Validate English alphanumeric text
bool isEnglishAlphanumeric = TextEnglishValidator.IsValidAlphanumeric("Street 123");

Helper Classes

EncryptionHelper

Encrypt and decrypt strings:

using Tawfir.Toolkit.Helpers;

var encrypted = EncryptionHelper.Encrypt("sensitive data");
var decrypted = EncryptionHelper.Decrypt(encrypted);

Card Analyzer - Fraud Prevention & Security

Advanced credit card analysis and validation for fraud prevention:

using Tawfir.Toolkit.FinTech;

var creditCard = new CreditCard();

// Analyze card for fraud prevention
var cardInfo = creditCard.GetCardInfo("4111111111111111");

// Check validation
if (!cardInfo.IsValid)
{
    // Card failed Luhn algorithm validation - potential fraud
    Console.WriteLine($"Invalid card: {cardInfo.ErrorMessage}");
    return;
}

// Fraud detection checks
if (cardInfo.CardBrand == "Unknown")
{
    // Unknown card brand - suspicious
    // Flag for manual review
}

// Verify card type matches expected
if (cardInfo.CardType == "Debit" && expectedType == "Credit")
{
    // Mismatch detected - potential fraud
}

// Check issuer country for geographic validation
if (cardInfo.IssuerCountry == "Saudi Arabia" && userLocation != "KSA")
{
    // Geographic mismatch - flag for review
}

// Co-badged card detection (Mada + International)
if (cardInfo.IsCoBadged)
{
    // Card can be used on both local (Mada) and international networks
    // Useful for fraud pattern analysis
}

Key Fraud Prevention Features:

✅ Luhn Algorithm Validation - Detects invalid card numbers instantly
✅ BIN (Bank Identification Number) Analysis - Identifies card brand, type, and issuer
✅ Geographic Validation - Verifies issuer country matches transaction location
✅ Card Type Verification - Ensures card type (Credit/Debit) matches expected
✅ Co-badged Card Detection - Identifies dual-network cards for pattern analysis
✅ Format Validation - Validates card number format (13-19 digits)
✅ Real-time Analysis - No external API calls required for basic validation

Fraud Prevention Use Cases:

1. E-commerce Payment Processing

   • Validate card numbers before processing
   • Detect invalid cards using Luhn algorithm
   • Flag suspicious cards for manual review

2. Geographic Fraud Detection

   • Verify issuer country matches user location
   • Detect cross-border fraud patterns
   • Validate Mada cards for Saudi transactions

3. Card Type Validation

   • Ensure card type matches transaction type
   • Detect debit cards used for credit-only services
   • Validate corporate vs personal cards

4. BIN Analysis

   • Identify card issuer and brand
   • Detect unknown or suspicious BINs
   • Track fraud patterns by card brand

5. Real-time Fraud Scoring

   • Combine multiple validation checks
   • Create fraud risk scores
   • Automatically flag high-risk transactions

Supported Card Brands:

• Visa
• Mastercard
• American Express
• Discover
• JCB
• Diners Club
• Maestro
• UnionPay
• Mada (Saudi Arabia) - with automatic bank identification
• Co-badged cards (Mada + Visa/Mastercard)

Example: Complete Fraud Prevention Check

public bool IsSuspiciousCard(string cardNumber, string userCountry)
{
    var creditCard = new CreditCard();
    var cardInfo = creditCard.GetCardInfo(cardNumber);
    
    // Basic validation
    if (!cardInfo.IsValid)
        return true; // Invalid card = fraud
    
    // Unknown brand
    if (cardInfo.CardBrand == "Unknown")
        return true; // Suspicious
    
    // Geographic mismatch for Mada cards
    if (cardInfo.CardBrand == "Mada" && userCountry != "Saudi Arabia")
        return true; // Mada cards should be used in KSA
    
    // Check if issuer country matches user location
    if (!string.IsNullOrEmpty(cardInfo.IssuerCountry) && 
        cardInfo.IssuerCountry != userCountry)
    {
        // Flag for additional verification
        return true;
    }
    
    return false; // Card appears legitimate
}

CardExpression

Card number processing and tokenization:

using Tawfir.Toolkit.Helpers;

string cardToken = CardExpression.GetCardToken(cardNo, expiryDate);
string cardNumber = CardExpression.GetCardNumber(cardToken);

RandomGen

Generate random strings and numbers:

using Tawfir.Toolkit.Helpers;

string randomString = RandomGen.String(length: 10);
string numbersOnly = RandomGen.String(length: 6, NumbersOnly: true);
int randomInt = RandomGen.INT(from: 1, to: 100);

Regex Patterns (RegexExp)

Pre-defined regex patterns for common validations:

using Tawfir.Toolkit.Models;
using System.Text.RegularExpressions;

// Civil ID patterns
Regex.IsMatch(id, RegexExp.Saudi);        // Saudi National ID (starts with 1)
Regex.IsMatch(id, RegexExp.NonSaudi);     // Non-Saudi Iqama (starts with 2)
Regex.IsMatch(id, RegexExp.CivilId);      // Any Civil ID (starts with 1 or 2)

// Financial patterns
Regex.IsMatch(iban, RegexExp.IBAN);       // Saudi IBAN format

// Contact patterns
Regex.IsMatch(mobile, RegexExp.Mobile);   // Saudi mobile (05XXXXXXXX)
Regex.IsMatch(phone, RegexExp.Phone);     // Saudi phone (01XXXXXXXX)

// Security patterns
Regex.IsMatch(password, RegexExp.Password);  // Strong password
Regex.IsMatch(pin, RegexExp.PIN);            // 6-character PIN
Regex.IsMatch(pin, RegexExp.PINCC);          // 4-character PIN
Regex.IsMatch(otp, RegexExp.OTP);            // OTP code

// Date patterns
Regex.IsMatch(date, RegexExp.Date_G);     // Gregorian date (DD/MM/YYYY)
Regex.IsMatch(date, RegexExp.Date_H);    // Hijri date (DD/MM/YYYY)

// Text patterns
Regex.IsMatch(text, RegexExp.Alphabetical);     // Alphabetical with Arabic support
Regex.IsMatch(text, RegexExp.Alphabetical_En);   // English only
Regex.IsMatch(text, RegexExp.Alphabetical_AR);   // Arabic with numbers (basic)

// Enhanced Arabic patterns
Regex.IsMatch(text, RegexExp.Arabic_Only);              // Full Arabic Unicode support
Regex.IsMatch(text, RegexExp.Arabic_Letters_Only);      // Arabic letters + Arabic numerals
Regex.IsMatch(text, RegexExp.Arabic_With_Diacritics);   // Arabic with Tashkeel marks
Regex.IsMatch(text, RegexExp.Arabic_Name);              // Arabic names (letters only)

// Enhanced English patterns
Regex.IsMatch(text, RegexExp.English_Only);             // English letters only
Regex.IsMatch(text, RegexExp.English_Letters_Only);     // English letters + numbers
Regex.IsMatch(text, RegexExp.English_With_Punctuation); // English with punctuation
Regex.IsMatch(text, RegexExp.English_Name);             // English names (letters + hyphens)

Arabic Text Validation - Detailed Guide

The toolkit provides comprehensive Arabic text validation with multiple options:

Available Patterns

Usage Examples

using Tawfir.Toolkit.Validator;

// Validate general Arabic text
var text1 = "مرحبا بك في السعودية";
var isValid1 = TextArabicValidator.IsValid(text1); // true

// Validate Arabic name (no numbers allowed)
var name = "محمد أحمد";
var isValidName = TextArabicValidator.IsValidName(name); // true

// Validate text with Arabic numerals
var address = "الشارع ١٢ حي النخيل";
var isValidAddr = TextArabicValidator.IsValidWithArabicNumerals(address); // true

// Validate text with diacritics
var quranicText = "بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ";
var isValidQuran = TextArabicValidator.IsValidWithDiacritics(quranicText); // true

Common Use Cases

1. User Names (Arabic only)

[TextArabic(NameOnly = true)]
public string FullName { get; set; }

2. Addresses (Arabic with numbers)

[TextArabic(AllowArabicNumerals = true)]
public string Address { get; set; }

3. Religious or Formal Text (with diacritics)

[TextArabic(AllowDiacritics = true)]
public string FormalText { get; set; }

4. General Arabic Content

[TextArabic]
public string Description { get; set; }

English Text Validation - Detailed Guide

The toolkit provides comprehensive English text validation with multiple options:

Available Patterns

Usage Examples

using Tawfir.Toolkit.Validator;

// Validate general English text
var text1 = "Hello World";
var isValid1 = TextEnglishValidator.IsValid(text1); // true

// Validate English name with hyphen
var name = "Mary-Jane Smith";
var isValidName = TextEnglishValidator.IsValidName(name); // true

// Validate text with alphanumeric
var address = "Street 123 Building A";
var isValidAddr = TextEnglishValidator.IsValidAlphanumeric(address); // true

// Validate text with punctuation
var sentence = "Hello, World! How are you?";
var isValidSentence = TextEnglishValidator.IsValidWithPunctuation(sentence); // true

Common Use Cases

1. User Names (English only)

[TextEnglish(NameOnly = true)]
public string FullName { get; set; }

2. Addresses (English with numbers)

[TextEnglish(AllowNumbers = true)]
public string Address { get; set; }

3. Comments and Reviews (with punctuation)

[TextEnglish(AllowPunctuation = true)]
public string Comment { get; set; }

4. General English Content

[TextEnglish]
public string Description { get; set; }

Namespaces

• Tawfir.Toolkit.Validator - Validation attributes and static validators
• Tawfir.Toolkit.Helpers - Helper classes for common operations
• Tawfir.Toolkit.Models - Models and constants (e.g., RegexExp)

Requirements

• .NET 9.0 or higher

License

Current Version (Free)

• The current version of RedisCacheService is fully free and available for use without any restrictions.
• All existing features, including caching operations, session management, distributed locking, and more, are available at no cost.

Future Plans (Q1 2026)

• Starting in the first quarter of 2026, we will introduce new premium features and enhanced support that will be available under a paid license.
• The current free version will continue to be available and maintained.
• Paid plans will include:
  • Advanced features and capabilities
  • Priority support and technical assistance
  • Enhanced monitoring and analytics
  • Additional enterprise-grade features

Note: Existing users of the free version can continue using it without any changes. The transition to paid features is optional and only applies to new premium capabilities.

Support

For support, please contact:

• Email: info@waelelazizy.com
• Phone: 00973 33030730

Author

wael EL azizy - waelelazizy.com