npm install @persian-tools/persian-tools

import { extractCardNumber } from "@persian-tools/persian-tools";

const text = "My card number is 6037701689095443 for payment";

// Basic extraction with validation
const cards = extractCardNumber(text, {
	checkValidation: true,
	detectBankNumber: true,
});

console.log(cards[0]);
// {
//   index: 1,
//   base: "6037701689095443",
//   pure: "6037701689095443",
//   startIndex: 17,
//   endIndex: 35,
//   isValid: true,
//   bankName: "بانک کشاورزی"
// }

// Returns ExtractCardNumberComplete[] (with validation + bank)
const fullResults = extractCardNumber(text, {
	checkValidation: true,
	detectBankNumber: true,
});

// Returns ExtractCardNumberWithValidation[] (validation only)
const validatedResults = extractCardNumber(text, {
	checkValidation: true,
	detectBankNumber: false,
});

// Returns ExtractCardNumberWithBank[] (bank detection only)
const bankResults = extractCardNumber(text, {
	checkValidation: false,
	detectBankNumber: true,
});

// Returns ExtractCardNumberBase[] (basic extraction)
const basicResults = extractCardNumber(text, {
	checkValidation: false,
	detectBankNumber: false,
});

// Large document processing (1MB+)
const hugeDocument = "..."; // Very large text
const results = extractCardNumber(hugeDocument, {
	optimizeForLargeText: true,
	maxResults: 10,
	filterValidCardNumbers: true,
});

// Extract partially masked card numbers
const maskedText = "Card: 6037-****-8909-5443";
const fuzzyResults = extractCardNumber(maskedText, {
	enableFuzzyMatching: true,
	checkValidation: false,
});

// Include surrounding text context
const contextResults = extractCardNumber(text, {
	includeContext: true,
	contextLength: 20,
});

console.log(contextResults[0].context);
// {
//   before: "My card number is ",
//   after: " for payment",
//   full: "My card number is 6037701689095443 for payment"
// }

const multiFormatText = `
  Formatted: 6037-7016-8909-5443
  Spaced: 6037 7016 8909 5443
  Persian: ۶۰۳۷۷۰۱۶۸۹۰۹۵۴۴۳
  Arabic: ٦٠٣٧٧٠١٦٨٩٠٩٥٤٤٣
  Dots: 6037.7016.8909.5443
  Underscores: 6037_7016_8909_5443
`;

const results = extractCardNumber(multiFormatText);
// All formats are normalized to: "6037701689095443"

interface ExtractCardNumberBase {
	index: number; // 1-based position in results
	base: string; // Original matched text
	pure: string; // Normalized card number
	startIndex: number; // Start position in text
	endIndex: number; // End position in text
}

interface ExtractCardNumberWithValidation extends ExtractCardNumberBase {
	isValid: boolean; // Luhn validation result
}

interface ExtractCardNumberWithBank extends ExtractCardNumberBase {
	bankName: string | null; // Iranian bank name
}

interface ExtractCardNumberComplete extends ExtractCardNumberWithValidation, ExtractCardNumberWithBank {}

const cards = extractCardNumber("Card: 6037701689095443", {
	detectBankNumber: true,
});

console.log(cards[0].bankName); // "بانک کشاورزی"

// Empty or invalid input
extractCardNumber(""); // Returns []
extractCardNumber(null); // Returns []

// No card numbers found
extractCardNumber("No cards here"); // Returns []

// Malformed card numbers are filtered out
extractCardNumber("Invalid: 123456789"); // Returns []

// v1.x usage continues to work unchanged
const legacyResults = extractCardNumber(text, {
	checkValidation: true,
	detectBankNumber: false,
	filterValidCardNumbers: true,
});