test-numbers-generator/README.md

Generate and validate European test phone numbers (mobile and landline) in safe, non-existent ranges.

# test-numbers-generator

Generate and validate European test phone numbers (mobile and landline) in safe, non-existent ranges.

## Features

- 📱 **Mobile Numbers**: Generate test mobile numbers for 17 European and North African countries
- 🏠 **Landline Numbers**: Generate test landline numbers for all supported countries
- 🆔 **Dutch Identifiers**: Generate and validate Dutch BSN, IBAN, KvK numbers
- 📮 **Postcodes**: Generate and validate postcodes for multiple countries
- 🌍 **Real Address Data**: Fetch real Dutch postcodes and address data using the PDOK Locatieserver API
- 🔍 **Address Validation**: Check address details by postcode and house number
- 🏘️ **Place Names**: Fetch random valid Dutch place names

## Supported Countries

🇳🇱 Netherlands • 🇩🇪 Germany • 🇧🇪 Belgium • 🇫🇷 France • 🇬🇧 United Kingdom • 🇪🇸 Spain • 🇮🇹 Italy • 🇦🇹 Austria • 🇨🇭 Switzerland • 🇸🇪 Sweden • 🇳🇴 Norway • 🇩🇰 Denmark • 🇫🇮 Finland • 🇵🇹 Portugal • 🇮🇪 Ireland • 🇹🇷 Turkey • 🇲🇦 Morocco

## Installation

```bash
npm install test-numbers-generator
```

## Usage

### Mobile Phone Numbers

```ts
import { generateTestMobileNumber, isTestMobileNumber } from 'test-numbers-generator';

// Generate a mobile number (uses international 00 prefix)
const mobileNL = generateTestMobileNumber.Netherlands();
console.log(mobileNL); // "0031 6 12345678"

const mobileDE = generateTestMobileNumber.Germany();
console.log(mobileDE); // "0049 015 1234567" (or 016/017)

const mobileFR = generateTestMobileNumber.France();
console.log(mobileFR); // "0033 6 12345678" (or 7)

// Validate mobile numbers
console.log(isTestMobileNumber.Netherlands(mobileNL)); // true
console.log(isTestMobileNumber.Germany("0049 018 1234567")); // false (invalid prefix)
```

### Landline Phone Numbers

```ts
import { generateTestLandlineNumber, isTestLandlineNumber } from 'test-numbers-generator';

const landlineNL = generateTestLandlineNumber.Netherlands();
console.log(landlineNL); // "010 991234567"

const landlineDE = generateTestLandlineNumber.Germany();
console.log(landlineDE); // "030 9912345"

// Validate landline numbers
console.log(isTestLandlineNumber.Netherlands(landlineNL)); // true
```

### Dutch BSN (Burgerservicenummer)

```ts
import { generateTestBSN, isValidBSN } from 'test-numbers-generator';

const bsn = generateTestBSN();
console.log(bsn); // "999012345" (test range)
console.log(isValidBSN(bsn)); // true
console.log(isValidBSN("123456789")); // false (invalid checksum)
```

### Dutch IBAN

```ts
import { generateTestDutchIBAN, isValidDutchIBAN } from 'test-numbers-generator';

const iban = generateTestDutchIBAN();
console.log(iban); // "NL99INGB0123456789"
console.log(isValidDutchIBAN(iban)); // true
```

### KvK Numbers

```ts
import { generateTestKvKNumber } from 'test-numbers-generator';

const kvk = generateTestKvKNumber();
console.log(kvk); // "12345678"
```

### Postcodes

```ts
import { generateTestPostcode, isValidDutchPostcode } from 'test-numbers-generator';

const postcodeNL = generateTestPostcode.Netherlands();
console.log(postcodeNL); // "9999 XX"
console.log(isValidDutchPostcode(postcodeNL)); // true
```

### Real Dutch Address Data (PDOK API)

```ts
import { 
  fetchRandomDutchPostcodeFromPDOK, 
  checkAdresByPostcodeHuisnummer,
  fetchPostcodesMetHuisnummerToevoeging,
  getRandomPlaatsnaam 
} from 'test-numbers-generator';

// Fetch a real, existing Dutch postcode
const realPostcode = await fetchRandomDutchPostcodeFromPDOK();
console.log(realPostcode); // "1011 AC"

// Check address details by postcode and house number
const address = await checkAdresByPostcodeHuisnummer('1011 AC', 1);
console.log(address); // { straatnaam: 'Prins Hendrikkade', woonplaats: 'Amsterdam' }

// Find postcodes with house number additions (like 12A, 12-B)
const postcodesWithAdditions = await fetchPostcodesMetHuisnummerToevoeging('Amsterdam', 20);
console.log(postcodesWithAdditions); // Set of postcodes

// Get a random valid Dutch place name
const placeName = await getRandomPlaatsnaam();
console.log(placeName); // "Amsterdam"
```

## Mobile Number Format Details

All mobile numbers are generated using the international `00` prefix format and follow official country specifications:

- **🇳🇱 Netherlands**: `0031 6 xxxxxxxx` (9 digits after 06)
- **🇩🇪 Germany**: `0049 015/016/017 xxxxxxx` (10-11 digits after country code)
- **🇧🇪 Belgium**: `0032 047/048/049 xxxxxxx` (9 digits total)
- **🇫🇷 France**: `0033 6/7 xxxxxxxx` (8 digits after prefix)
- **🇬🇧 United Kingdom**: `0044 7 xxxxxxxxx` (9 digits after 7)
- **🇪🇸 Spain**: `0034 6/7xxxxxxxx` (9 digits total)
- **��🇹 Italy**: `0039 3xx xxxxxxx` (10 digits total)
- **🇦🇹 Austria**: `0043 06xx xxxxxxx` (10-13 digits total)
- **🇨🇭 Switzerland**: `0041 07x xxxxxx` (9 digits total)
- **🇸🇪 Sweden**: `0046 7 xxxxxxxx` (8 digits after 7)
- **🇳🇴 Norway**: `0047 4x/9x xxxxxx` (8 digits total)
- **🇩🇰 Denmark**: `0045 xxxxxxxx` (8 digits, various prefixes)
- **🇫🇮 Finland**: `00358 04x/050 xxxxxx` (9-10 digits total)
- **🇵🇹 Portugal**: `00351 9x xxxxxxx` (9 digits total)
- **🇮🇪 Ireland**: `00353 08x xxxxxx` (9 digits total)
- **🇹🇷 Turkey**: `0090 053x xxxxxx` (10 digits total)
- **🇲🇦 Morocco**: `00212 06/07 xxxxxxx` (9 digits total)

## API Reference

### Types

```ts
type SupportedCountry = 
  | 'Netherlands' | 'Germany' | 'Belgium' | 'France' | 'UnitedKingdom' 
  | 'Spain' | 'Italy' | 'Austria' | 'Switzerland' | 'Sweden' 
  | 'Norway' | 'Denmark' | 'Finland' | 'Portugal' | 'Ireland' 
  | 'Turkey' | 'Morocco';

type PhoneNumberType = 'mobile' | 'landline';
```

### Functions

```ts
// Phone number generators
generateTestMobileNumber: Record<SupportedCountry, () => string>
generateTestLandlineNumber: Record<SupportedCountry, () => string>

// Phone number validators
isTestMobileNumber: Record<SupportedCountry, (number: string) => boolean>
isTestLandlineNumber: Record<SupportedCountry, (number: string) => boolean>
isTestPhoneNumber(number: string): boolean

// Dutch identifiers
generateTestBSN(): string
isValidBSN(bsn: string): boolean
generateTestDutchIBAN(): string
isValidDutchIBAN(iban: string): boolean
generateTestKvKNumber(): string

// Postcodes
generateTestPostcode: Record<SupportedPostcodeCountry, () => string>
isValidDutchPostcode(postcode: string): boolean

// Real address data (async)
fetchRandomDutchPostcodeFromPDOK(): Promise<string>
checkAdresByPostcodeHuisnummer(postcode: string, huisnummer: number): Promise<AddressInfo>
fetchPostcodesMetHuisnummerToevoeging(plaats: string, limit?: number): Promise<Set<string>>
getRandomPlaatsnaam(): Promise<string>
```

## Test Numbers Policy

All generated numbers are designed to be **safe for testing**:

- 📱 Mobile numbers use realistic formats but are in test ranges
- 🏠 Landline numbers include "99" sequences to indicate test numbers  
- 🆔 BSN numbers use the 999xxxxxx test range
- 🏦 IBAN numbers use test bank codes
- 📮 Postcodes use 9999 XX format for tests

**⚠️ Important**: These numbers should only be used for testing purposes and are not real, active numbers.

## Contributing

Contributions are welcome! Please ensure all tests pass:

```bash
npm test
npm run test:coverage
```

## License

MIT