@devdataphone/sdk 1.0.0

package/src/generator.js

@@ -0,0 +1,334 @@
+/**
+ * Phone number generator module
+ * Generates valid E.164 formatted phone numbers for testing
+ * @module generator
+ */
+
+'use strict';
+
+const { COUNTRIES, US_AREA_CODES, CA_AREA_CODES, getCountry, isSupported } = require('./countries');
+
+/**
+ * Generate a random integer between min and max (inclusive)
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+function randomInt(min, max) {
+  min = Math.ceil(min);
+  max = Math.floor(max);
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * Pad number with leading zeros
+ * @param {number|string} num
+ * @param {number} size
+ * @returns {string}
+ */
+function pad(num, size) {
+  let s = String(num);
+  while (s.length < size) s = '0' + s;
+  return s;
+}
+
+/**
+ * Generate random digits string
+ * @param {number} length
+ * @returns {string}
+ */
+function randomDigits(length) {
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += randomInt(0, 9);
+  }
+  return result;
+}
+
+/**
+ * Generate US phone number using reserved 555-01xx range
+ * @returns {{raw: string, location: string, areaCode: string}}
+ */
+function generateUS() {
+  const selection = US_AREA_CODES[randomInt(0, US_AREA_CODES.length - 1)];
+  const exchange = 555;
+  const subscriber = randomInt(100, 199);  // Reserved fictional range
+  return {
+    raw: `${selection.code}${exchange}${pad(subscriber, 4)}`,
+    formatted: `(${selection.code}) ${exchange}-${pad(subscriber, 4)}`,
+    location: `${selection.city}, ${selection.state}`,
+    areaCode: String(selection.code)
+  };
+}
+
+/**
+ * Generate Canada phone number
+ * @returns {{raw: string, location: string}}
+ */
+function generateCA() {
+  const selection = CA_AREA_CODES[randomInt(0, CA_AREA_CODES.length - 1)];
+  const exchange = 555;
+  const subscriber = randomInt(100, 199);
+  return {
+    raw: `${selection.code}${exchange}${pad(subscriber, 4)}`,
+    formatted: `(${selection.code}) ${exchange}-${pad(subscriber, 4)}`,
+    location: `${selection.city}, ${selection.province}`,
+    areaCode: String(selection.code)
+  };
+}
+
+/**
+ * Generate UK phone number using Ofcom reserved range
+ * @returns {{raw: string}}
+ */
+function generateUK() {
+  // Ofcom reserved: 07700 900000-900999
+  const subscriber = randomInt(0, 999);
+  return {
+    raw: `7700900${pad(subscriber, 3)}`,
+    formatted: `07700 900${pad(subscriber, 3)}`,
+    location: 'United Kingdom'
+  };
+}
+
+/**
+ * Generate Australia phone number using ACMA reserved range
+ * @returns {{raw: string}}
+ */
+function generateAU() {
+  // ACMA reserved: 0491 570 156-159
+  const lastThree = randomInt(156, 159);
+  return {
+    raw: `491570${lastThree}`,
+    formatted: `0491 570 ${lastThree}`,
+    location: 'Australia'
+  };
+}
+
+/**
+ * Generate China phone number
+ * @returns {{raw: string}}
+ */
+function generateCN() {
+  const country = getCountry('CN');
+  const prefixes = country.mobilePrefixes;
+  const prefix = prefixes[randomInt(0, prefixes.length - 1)];
+  const suffix = randomDigits(8);
+  return {
+    raw: `${prefix}${suffix}`,
+    formatted: `${prefix} ${suffix.slice(0, 4)} ${suffix.slice(4)}`,
+    location: 'China'
+  };
+}
+
+/**
+ * Generate India phone number
+ * @returns {{raw: string}}
+ */
+function generateIN() {
+  const startDigits = ['6', '7', '8', '9'];
+  const start = startDigits[randomInt(0, startDigits.length - 1)];
+  const rest = randomDigits(9);
+  return {
+    raw: `${start}${rest}`,
+    formatted: `${start}${rest.slice(0, 4)} ${rest.slice(4)}`,
+    location: 'India'
+  };
+}
+
+/**
+ * Generate Germany phone number
+ * @returns {{raw: string}}
+ */
+function generateDE() {
+  const country = getCountry('DE');
+  const prefix = country.mobilePrefixes[randomInt(0, country.mobilePrefixes.length - 1)];
+  const suffix = randomDigits(7);
+  return {
+    raw: `${prefix}${suffix}`,
+    formatted: `0${prefix} ${suffix}`,
+    location: 'Germany'
+  };
+}
+
+/**
+ * Generate France phone number
+ * @returns {{raw: string}}
+ */
+function generateFR() {
+  // French mobile starts with 06 or 07
+  const prefix = randomInt(0, 1) === 0 ? '6' : '7';
+  const rest = randomDigits(8);
+  return {
+    raw: `${prefix}${rest}`,
+    formatted: `0${prefix} ${rest.slice(0, 2)} ${rest.slice(2, 4)} ${rest.slice(4, 6)} ${rest.slice(6)}`,
+    location: 'France'
+  };
+}
+
+/**
+ * Generate Japan phone number
+ * @returns {{raw: string}}
+ */
+function generateJP() {
+  const country = getCountry('JP');
+  const prefix = country.mobilePrefixes[randomInt(0, country.mobilePrefixes.length - 1)];
+  const rest = randomDigits(8);
+  return {
+    raw: `${prefix}${rest}`,
+    formatted: `0${prefix}-${rest.slice(0, 4)}-${rest.slice(4)}`,
+    location: 'Japan'
+  };
+}
+
+/**
+ * Generate Brazil phone number
+ * @returns {{raw: string}}
+ */
+function generateBR() {
+  // Major area codes
+  const areaCodes = ['11', '21', '31', '41', '51', '61', '71', '81', '91'];
+  const areaCode = areaCodes[randomInt(0, areaCodes.length - 1)];
+  const rest = randomDigits(8);
+  return {
+    raw: `${areaCode}9${rest}`,
+    formatted: `(${areaCode}) 9${rest.slice(0, 4)}-${rest.slice(4)}`,
+    location: 'Brazil'
+  };
+}
+
+/**
+ * Generator function map
+ */
+const generators = {
+  US: generateUS,
+  CA: generateCA,
+  UK: generateUK,
+  AU: generateAU,
+  CN: generateCN,
+  IN: generateIN,
+  DE: generateDE,
+  FR: generateFR,
+  JP: generateJP,
+  BR: generateBR
+};
+
+/**
+ * Format output number based on style
+ * @param {string} raw - Raw number digits
+ * @param {string} countryCode - Country code
+ * @param {string} format - Output format
+ * @returns {string}
+ */
+function formatOutput(raw, countryCode, format) {
+  const country = getCountry(countryCode);
+  if (!country) return raw;
+
+  const dialCode = country.dialCode.replace('+', '');
+
+  switch (format) {
+    case 'e164':
+      return `+${dialCode}${raw}`;
+    case 'national':
+      // Return formatted version from generator
+      return raw;
+    case 'international':
+      return `+${dialCode} ${raw}`;
+    case 'digits':
+      return raw;
+    default:
+      return `+${dialCode}${raw}`;
+  }
+}
+
+/**
+ * Generate phone numbers
+ * @param {Object} options - Generation options
+ * @param {string} [options.region='US'] - Country code (US, UK, CN, etc.)
+ * @param {number} [options.count=1] - Number of phone numbers to generate (1-1000)
+ * @param {string} [options.format='e164'] - Output format ('e164', 'national', 'international', 'digits')
+ * @returns {Array<GeneratedNumber>}
+ * @throws {Error} If region is not supported or count is invalid
+ */
+function generate(options = {}) {
+  // Default options
+  const {
+    region = 'US',
+    count = 1,
+    format = 'e164'
+  } = options;
+
+  // Validate region
+  const normalizedRegion = String(region).toUpperCase();
+  if (!isSupported(normalizedRegion)) {
+    throw new Error(`Unsupported region: ${region}. Supported: ${Object.keys(generators).join(', ')}`);
+  }
+
+  // Validate count
+  const numCount = parseInt(count, 10);
+  if (isNaN(numCount) || numCount < 1) {
+    throw new Error('Count must be a positive integer');
+  }
+  if (numCount > 1000) {
+    throw new Error('Count cannot exceed 1000');
+  }
+
+  // Validate format
+  const validFormats = ['e164', 'national', 'international', 'digits'];
+  const normalizedFormat = String(format).toLowerCase();
+  if (!validFormats.includes(normalizedFormat)) {
+    throw new Error(`Invalid format: ${format}. Supported: ${validFormats.join(', ')}`);
+  }
+
+  // Get generator function
+  const generatorFn = generators[normalizedRegion];
+  if (!generatorFn) {
+    throw new Error(`No generator available for region: ${normalizedRegion}`);
+  }
+
+  const country = getCountry(normalizedRegion);
+  const results = [];
+
+  for (let i = 0; i < numCount; i++) {
+    const generated = generatorFn();
+    
+    let outputNumber;
+    if (normalizedFormat === 'national') {
+      outputNumber = generated.formatted;
+    } else if (normalizedFormat === 'digits') {
+      outputNumber = generated.raw;
+    } else {
+      outputNumber = formatOutput(generated.raw, normalizedRegion, normalizedFormat);
+    }
+
+    results.push({
+      number: outputNumber,
+      e164: `${country.dialCode}${generated.raw}`,
+      national: generated.formatted,
+      country: country.name,
+      countryCode: normalizedRegion,
+      dialCode: country.dialCode,
+      location: generated.location || country.name,
+      raw: generated.raw
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Generate a single phone number (convenience method)
+ * @param {string} [region='US'] - Country code
+ * @param {string} [format='e164'] - Output format
+ * @returns {string}
+ */
+function generateOne(region = 'US', format = 'e164') {
+  const result = generate({ region, count: 1, format });
+  return result[0].number;
+}
+
+module.exports = {
+  generate,
+  generateOne,
+  generators
+};

package/src/validator.js

@@ -0,0 +1,364 @@
+/**
+ * Phone number validation module
+ * Validates phone numbers against E.164 standard
+ * @module validator
+ */
+
+'use strict';
+
+const { COUNTRIES, getCountry, isSupported } = require('./countries');
+
+/**
+ * Remove all non-digit characters except leading +
+ * @param {string} input
+ * @returns {string}
+ */
+function sanitize(input) {
+  if (!input || typeof input !== 'string') return '';
+  
+  // Preserve leading + if present
+  const hasPlus = input.trim().startsWith('+');
+  const digits = input.replace(/\D/g, '');
+  
+  return hasPlus ? `+${digits}` : digits;
+}
+
+/**
+ * Extract country code from E.164 number
+ * @param {string} number - E.164 formatted number starting with +
+ * @returns {{countryCode: string, dialCode: string, nationalNumber: string}|null}
+ */
+function extractCountryCode(number) {
+  if (!number || !number.startsWith('+')) return null;
+
+  const digits = number.slice(1);  // Remove +
+
+  // Sort countries by dial code length (descending) to match longer codes first
+  const sortedCountries = [...COUNTRIES].sort((a, b) => 
+    b.dialCode.length - a.dialCode.length
+  );
+
+  for (const country of sortedCountries) {
+    const dialDigits = country.dialCode.replace('+', '');
+    if (digits.startsWith(dialDigits)) {
+      return {
+        countryCode: country.code,
+        dialCode: country.dialCode,
+        nationalNumber: digits.slice(dialDigits.length)
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Validate phone number length for a country
+ * @param {string} nationalNumber - National significant number
+ * @param {Object} country - Country data
+ * @returns {boolean}
+ */
+function validateLength(nationalNumber, country) {
+  if (!nationalNumber || !country) return false;
+
+  const len = nationalNumber.length;
+  const expected = country.numberLength;
+
+  if (typeof expected === 'number') {
+    return len === expected;
+  } else if (typeof expected === 'object' && expected.min && expected.max) {
+    return len >= expected.min && len <= expected.max;
+  }
+
+  // Default: allow 7-15 digits (E.164 standard)
+  return len >= 7 && len <= 15;
+}
+
+/**
+ * Validate using country-specific regex
+ * @param {string} input - Input number
+ * @param {Object} country - Country data
+ * @returns {boolean}
+ */
+function validateWithRegex(input, country) {
+  if (!country || !country.regex) return false;
+  
+  try {
+    return country.regex.test(input);
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Detect number type (MOBILE, FIXED_LINE, etc.)
+ * @param {string} nationalNumber
+ * @param {Object} country
+ * @returns {string}
+ */
+function detectType(nationalNumber, country) {
+  if (!nationalNumber || !country) return 'UNKNOWN';
+
+  // Check mobile prefix
+  if (country.mobilePrefix) {
+    if (nationalNumber.startsWith(country.mobilePrefix)) {
+      return 'MOBILE';
+    }
+  }
+
+  // Check mobile prefixes array
+  if (country.mobilePrefixes) {
+    for (const prefix of country.mobilePrefixes) {
+      if (nationalNumber.startsWith(prefix)) {
+        return 'MOBILE';
+      }
+    }
+  }
+
+  // Check mobile start digits
+  if (country.mobileStartDigits) {
+    if (country.mobileStartDigits.includes(nationalNumber[0])) {
+      return 'MOBILE';
+    }
+  }
+
+  return 'UNKNOWN';
+}
+
+/**
+ * Validation result object
+ * @typedef {Object} ValidationResult
+ * @property {boolean} valid - Whether the number is valid
+ * @property {string|null} e164 - E.164 formatted number
+ * @property {string|null} country - Country name
+ * @property {string|null} countryCode - ISO country code
+ * @property {string|null} dialCode - International dial code
+ * @property {string|null} nationalNumber - National significant number
+ * @property {string} type - Number type (MOBILE, FIXED_LINE, UNKNOWN)
+ * @property {string|null} error - Error message if invalid
+ */
+
+/**
+ * Validate a phone number
+ * @param {string} input - Phone number to validate
+ * @param {Object} [options] - Validation options
+ * @param {string} [options.defaultCountry] - Default country code for local numbers
+ * @param {boolean} [options.strict=false] - Enable strict validation
+ * @returns {ValidationResult}
+ */
+function validate(input, options = {}) {
+  const { defaultCountry, strict = false } = options;
+
+  // Handle empty input
+  if (!input || typeof input !== 'string') {
+    return {
+      valid: false,
+      e164: null,
+      country: null,
+      countryCode: null,
+      dialCode: null,
+      nationalNumber: null,
+      type: 'UNKNOWN',
+      error: 'Input is required'
+    };
+  }
+
+  const trimmed = input.trim();
+  if (trimmed === '') {
+    return {
+      valid: false,
+      e164: null,
+      country: null,
+      countryCode: null,
+      dialCode: null,
+      nationalNumber: null,
+      type: 'UNKNOWN',
+      error: 'Input is empty'
+    };
+  }
+
+  // Sanitize input
+  const sanitized = sanitize(trimmed);
+
+  // Check if it's an international format
+  if (sanitized.startsWith('+')) {
+    const extracted = extractCountryCode(sanitized);
+    
+    if (!extracted) {
+      return {
+        valid: false,
+        e164: null,
+        country: null,
+        countryCode: null,
+        dialCode: null,
+        nationalNumber: null,
+        type: 'UNKNOWN',
+        error: 'Unrecognized country code'
+      };
+    }
+
+    const country = getCountry(extracted.countryCode);
+    
+    // Validate length
+    if (!validateLength(extracted.nationalNumber, country)) {
+      return {
+        valid: false,
+        e164: null,
+        country: country.name,
+        countryCode: extracted.countryCode,
+        dialCode: extracted.dialCode,
+        nationalNumber: extracted.nationalNumber,
+        type: 'UNKNOWN',
+        error: `Invalid number length for ${country.name}`
+      };
+    }
+
+    // Strict mode: validate with regex
+    if (strict && !validateWithRegex(trimmed, country)) {
+      return {
+        valid: false,
+        e164: null,
+        country: country.name,
+        countryCode: extracted.countryCode,
+        dialCode: extracted.dialCode,
+        nationalNumber: extracted.nationalNumber,
+        type: 'UNKNOWN',
+        error: `Number format does not match ${country.name} pattern`
+      };
+    }
+
+    const type = detectType(extracted.nationalNumber, country);
+
+    return {
+      valid: true,
+      e164: sanitized,
+      country: country.name,
+      countryCode: extracted.countryCode,
+      dialCode: extracted.dialCode,
+      nationalNumber: extracted.nationalNumber,
+      type,
+      error: null
+    };
+  }
+
+  // Handle local format numbers
+  if (defaultCountry) {
+    const country = getCountry(defaultCountry);
+    if (!country) {
+      return {
+        valid: false,
+        e164: null,
+        country: null,
+        countryCode: null,
+        dialCode: null,
+        nationalNumber: null,
+        type: 'UNKNOWN',
+        error: `Unsupported country: ${defaultCountry}`
+      };
+    }
+
+    // Remove leading 0 if present (common in local formats)
+    let nationalNumber = sanitized;
+    if (nationalNumber.startsWith('0')) {
+      nationalNumber = nationalNumber.slice(1);
+    }
+
+    // Validate with regex if available
+    if (strict && !validateWithRegex(trimmed, country)) {
+      return {
+        valid: false,
+        e164: null,
+        country: country.name,
+        countryCode: country.code,
+        dialCode: country.dialCode,
+        nationalNumber,
+        type: 'UNKNOWN',
+        error: `Number format does not match ${country.name} pattern`
+      };
+    }
+
+    // Validate length
+    if (!validateLength(nationalNumber, country)) {
+      return {
+        valid: false,
+        e164: null,
+        country: country.name,
+        countryCode: country.code,
+        dialCode: country.dialCode,
+        nationalNumber,
+        type: 'UNKNOWN',
+        error: `Invalid number length for ${country.name}`
+      };
+    }
+
+    const type = detectType(nationalNumber, country);
+    const dialDigits = country.dialCode.replace('+', '');
+
+    return {
+      valid: true,
+      e164: `+${dialDigits}${nationalNumber}`,
+      country: country.name,
+      countryCode: country.code,
+      dialCode: country.dialCode,
+      nationalNumber,
+      type,
+      error: null
+    };
+  }
+
+  // No country context and not E.164 format
+  return {
+    valid: false,
+    e164: null,
+    country: null,
+    countryCode: null,
+    dialCode: null,
+    nationalNumber: sanitized,
+    type: 'UNKNOWN',
+    error: 'Cannot determine country. Use E.164 format (+XXX...) or provide defaultCountry option'
+  };
+}
+
+/**
+ * Quick validation check
+ * @param {string} input - Phone number to validate
+ * @param {string} [defaultCountry] - Default country code
+ * @returns {boolean}
+ */
+function isValid(input, defaultCountry) {
+  return validate(input, { defaultCountry }).valid;
+}
+
+/**
+ * Validate E.164 format specifically
+ * @param {string} input - Phone number to validate
+ * @returns {boolean}
+ */
+function isE164(input) {
+  if (!input || typeof input !== 'string') return false;
+  
+  const trimmed = input.trim();
+  
+  // Must start with +
+  if (!trimmed.startsWith('+')) return false;
+  
+  // Extract digits
+  const digits = trimmed.slice(1);
+  
+  // E.164: 1-15 digits after +
+  if (!/^\d{1,15}$/.test(digits)) return false;
+  
+  // Must have a valid country code
+  const extracted = extractCountryCode(trimmed);
+  if (!extracted) return false;
+  
+  return true;
+}
+
+module.exports = {
+  validate,
+  isValid,
+  isE164,
+  sanitize,
+  extractCountryCode
+};