@devdataphone/sdk 1.0.0

package/src/countries.js

@@ -0,0 +1,240 @@
+/**
+ * Country/Region data for phone number generation
+ * @module countries
+ */
+
+'use strict';
+
+/**
+ * Supported countries with their phone number metadata
+ * @type {Array<Country>}
+ */
+const COUNTRIES = [
+  {
+    code: 'US',
+    name: 'United States',
+    dialCode: '+1',
+    flag: '🇺🇸',
+    example: '(212) 555-0123',
+    // E.164 compliant regex
+    regex: /^(\+1)?[-. ]?\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/,
+    // Reserved fictional ranges (FCC/NANP)
+    reservedRanges: [
+      { areaCode: '555', exchange: '0100', to: '0199' }  // 555-0100 to 555-0199
+    ],
+    numberLength: 10,  // National significant number length
+    mobilePrefix: null  // US doesn't distinguish mobile by prefix
+  },
+  {
+    code: 'UK',
+    name: 'United Kingdom',
+    dialCode: '+44',
+    flag: '🇬🇧',
+    example: '07700 900123',
+    regex: /^(\+44|0)7\d{9}$/,
+    // Ofcom reserved drama/test ranges
+    reservedRanges: [
+      { prefix: '07700', start: '900000', end: '900999' }
+    ],
+    numberLength: 10,
+    mobilePrefix: '7'
+  },
+  {
+    code: 'CA',
+    name: 'Canada',
+    dialCode: '+1',
+    flag: '🇨🇦',
+    example: '(416) 555-0199',
+    regex: /^(\+1)?[-. ]?\(?([0-9]{3})\)?[-. ]?([0-9]{3})[-. ]?([0-9]{4})$/,
+    // Same NANP reserved ranges as US
+    reservedRanges: [
+      { areaCode: '555', exchange: '0100', to: '0199' }
+    ],
+    numberLength: 10,
+    mobilePrefix: null
+  },
+  {
+    code: 'AU',
+    name: 'Australia',
+    dialCode: '+61',
+    flag: '🇦🇺',
+    example: '0491 570 156',
+    regex: /^(\+61|0)4\d{8}$/,
+    // ACMA reserved ranges
+    reservedRanges: [
+      { prefix: '0491', start: '570156', end: '570159' }
+    ],
+    numberLength: 9,  // Without leading 0
+    mobilePrefix: '4'
+  },
+  {
+    code: 'CN',
+    name: 'China',
+    dialCode: '+86',
+    flag: '🇨🇳',
+    example: '139 1234 5678',
+    regex: /^(\+86)?1[3-9]\d{9}$/,
+    // No official reserved ranges, generate from common prefixes
+    reservedRanges: [],
+    numberLength: 11,
+    mobilePrefix: '1',
+    // Common mobile carrier prefixes
+    mobilePrefixes: [
+      '130', '131', '132', '133', '134', '135', '136', '137', '138', '139',
+      '150', '151', '152', '153', '155', '156', '157', '158', '159',
+      '166', '170', '171', '172', '173', '175', '176', '177', '178',
+      '180', '181', '182', '183', '184', '185', '186', '187', '188', '189',
+      '191', '198', '199'
+    ]
+  },
+  {
+    code: 'IN',
+    name: 'India',
+    dialCode: '+91',
+    flag: '🇮🇳',
+    example: '98123 45678',
+    regex: /^(\+91|0)?[6-9]\d{9}$/,
+    reservedRanges: [],
+    numberLength: 10,
+    mobilePrefix: null,
+    // Valid starting digits for mobile
+    mobileStartDigits: ['6', '7', '8', '9']
+  },
+  {
+    code: 'DE',
+    name: 'Germany',
+    dialCode: '+49',
+    flag: '🇩🇪',
+    example: '0170 1234567',
+    regex: /^(\+49|0)[1-9]\d{6,13}$/,
+    reservedRanges: [],
+    numberLength: { min: 7, max: 14 },
+    mobilePrefixes: ['151', '152', '157', '159', '160', '162', '163', '170', '171', '172', '173', '174', '175', '176', '177', '178', '179']
+  },
+  {
+    code: 'FR',
+    name: 'France',
+    dialCode: '+33',
+    flag: '🇫🇷',
+    example: '06 12 34 56 78',
+    regex: /^(\+33|0)[1-9]\d{8}$/,
+    reservedRanges: [],
+    numberLength: 9,
+    mobilePrefix: '6'
+  },
+  {
+    code: 'JP',
+    name: 'Japan',
+    dialCode: '+81',
+    flag: '🇯🇵',
+    example: '090-1234-5678',
+    regex: /^(\+81|0)[7-9]0\d{8}$/,
+    reservedRanges: [],
+    numberLength: 10,
+    mobilePrefixes: ['70', '80', '90']
+  },
+  {
+    code: 'BR',
+    name: 'Brazil',
+    dialCode: '+55',
+    flag: '🇧🇷',
+    example: '(11) 91234-5678',
+    regex: /^(\+55)?[1-9]{2}9[0-9]{8}$/,
+    reservedRanges: [],
+    numberLength: 11,
+    mobilePrefix: '9'
+  }
+];
+
+/**
+ * Area codes for US/Canada number generation
+ * @type {Array<{code: number, state: string}>}
+ */
+const US_AREA_CODES = [
+  // New York
+  { code: 212, state: 'NY', city: 'New York City' },
+  { code: 718, state: 'NY', city: 'New York City' },
+  { code: 917, state: 'NY', city: 'New York City' },
+  { code: 646, state: 'NY', city: 'New York City' },
+  { code: 347, state: 'NY', city: 'New York City' },
+  // California
+  { code: 310, state: 'CA', city: 'Los Angeles' },
+  { code: 213, state: 'CA', city: 'Los Angeles' },
+  { code: 323, state: 'CA', city: 'Los Angeles' },
+  { code: 415, state: 'CA', city: 'San Francisco' },
+  { code: 650, state: 'CA', city: 'San Francisco Bay' },
+  { code: 408, state: 'CA', city: 'San Jose' },
+  { code: 619, state: 'CA', city: 'San Diego' },
+  // Texas
+  { code: 512, state: 'TX', city: 'Austin' },
+  { code: 713, state: 'TX', city: 'Houston' },
+  { code: 214, state: 'TX', city: 'Dallas' },
+  { code: 469, state: 'TX', city: 'Dallas' },
+  // Others
+  { code: 202, state: 'DC', city: 'Washington' },
+  { code: 312, state: 'IL', city: 'Chicago' },
+  { code: 773, state: 'IL', city: 'Chicago' },
+  { code: 206, state: 'WA', city: 'Seattle' },
+  { code: 617, state: 'MA', city: 'Boston' },
+  { code: 305, state: 'FL', city: 'Miami' },
+  { code: 407, state: 'FL', city: 'Orlando' },
+  { code: 404, state: 'GA', city: 'Atlanta' },
+  { code: 303, state: 'CO', city: 'Denver' },
+  { code: 602, state: 'AZ', city: 'Phoenix' },
+  { code: 702, state: 'NV', city: 'Las Vegas' },
+  { code: 215, state: 'PA', city: 'Philadelphia' }
+];
+
+/**
+ * Canada-specific area codes
+ * @type {Array<{code: number, province: string}>}
+ */
+const CA_AREA_CODES = [
+  { code: 416, province: 'ON', city: 'Toronto' },
+  { code: 647, province: 'ON', city: 'Toronto' },
+  { code: 905, province: 'ON', city: 'Greater Toronto' },
+  { code: 604, province: 'BC', city: 'Vancouver' },
+  { code: 778, province: 'BC', city: 'British Columbia' },
+  { code: 514, province: 'QC', city: 'Montreal' },
+  { code: 438, province: 'QC', city: 'Montreal' },
+  { code: 403, province: 'AB', city: 'Calgary' },
+  { code: 780, province: 'AB', city: 'Edmonton' },
+  { code: 613, province: 'ON', city: 'Ottawa' }
+];
+
+/**
+ * Get country by code
+ * @param {string} code - ISO 3166-1 alpha-2 country code
+ * @returns {Country|undefined}
+ */
+function getCountry(code) {
+  if (!code || typeof code !== 'string') return undefined;
+  return COUNTRIES.find(c => c.code === code.toUpperCase());
+}
+
+/**
+ * Get all supported country codes
+ * @returns {string[]}
+ */
+function getSupportedCountries() {
+  return COUNTRIES.map(c => c.code);
+}
+
+/**
+ * Check if a country code is supported
+ * @param {string} code
+ * @returns {boolean}
+ */
+function isSupported(code) {
+  if (!code || typeof code !== 'string') return false;
+  return COUNTRIES.some(c => c.code === code.toUpperCase());
+}
+
+module.exports = {
+  COUNTRIES,
+  US_AREA_CODES,
+  CA_AREA_CODES,
+  getCountry,
+  getSupportedCountries,
+  isSupported
+};

package/src/formatter.js

@@ -0,0 +1,299 @@
+/**
+ * Phone number formatting module
+ * Formats phone numbers into various standard formats
+ * @module formatter
+ */
+
+'use strict';
+
+const { getCountry } = require('./countries');
+const { extractCountryCode, sanitize } = require('./validator');
+
+/**
+ * Format styles
+ * @enum {string}
+ */
+const FormatStyle = {
+  E164: 'e164',           // +14155550100
+  INTERNATIONAL: 'international',  // +1 415 555 0100
+  NATIONAL: 'national',   // (415) 555-0100
+  RFC3966: 'rfc3966',     // tel:+1-415-555-0100
+  DIGITS: 'digits'        // 14155550100
+};
+
+/**
+ * Format US/Canada number in national format
+ * @param {string} nationalNumber
+ * @returns {string}
+ */
+function formatUSNational(nationalNumber) {
+  if (nationalNumber.length !== 10) return nationalNumber;
+  const areaCode = nationalNumber.slice(0, 3);
+  const exchange = nationalNumber.slice(3, 6);
+  const subscriber = nationalNumber.slice(6);
+  return `(${areaCode}) ${exchange}-${subscriber}`;
+}
+
+/**
+ * Format UK number in national format
+ * @param {string} nationalNumber
+ * @returns {string}
+ */
+function formatUKNational(nationalNumber) {
+  if (nationalNumber.length < 10) return nationalNumber;
+  // Mobile: 07XXX XXXXXX
+  if (nationalNumber.startsWith('7')) {
+    return `0${nationalNumber.slice(0, 4)} ${nationalNumber.slice(4)}`;
+  }
+  return `0${nationalNumber}`;
+}
+
+/**
+ * Format China number in national format
+ * @param {string} nationalNumber
+ * @returns {string}
+ */
+function formatCNNational(nationalNumber) {
+  if (nationalNumber.length !== 11) return nationalNumber;
+  const prefix = nationalNumber.slice(0, 3);
+  const middle = nationalNumber.slice(3, 7);
+  const end = nationalNumber.slice(7);
+  return `${prefix} ${middle} ${end}`;
+}
+
+/**
+ * Format Australia number in national format
+ * @param {string} nationalNumber
+ * @returns {string}
+ */
+function formatAUNational(nationalNumber) {
+  if (nationalNumber.length !== 9) return nationalNumber;
+  // Mobile: 04XX XXX XXX
+  if (nationalNumber.startsWith('4')) {
+    return `0${nationalNumber.slice(0, 3)} ${nationalNumber.slice(3, 6)} ${nationalNumber.slice(6)}`;
+  }
+  return `0${nationalNumber}`;
+}
+
+/**
+ * Format India number in national format
+ * @param {string} nationalNumber
+ * @returns {string}
+ */
+function formatINNational(nationalNumber) {
+  if (nationalNumber.length !== 10) return nationalNumber;
+  const first5 = nationalNumber.slice(0, 5);
+  const last5 = nationalNumber.slice(5);
+  return `${first5} ${last5}`;
+}
+
+/**
+ * Format Germany number in national format
+ * @param {string} nationalNumber
+ * @returns {string}
+ */
+function formatDENational(nationalNumber) {
+  if (nationalNumber.length < 7) return nationalNumber;
+  // Mobile prefix (3 digits) + rest
+  const prefix = nationalNumber.slice(0, 3);
+  const rest = nationalNumber.slice(3);
+  return `0${prefix} ${rest}`;
+}
+
+/**
+ * Format France number in national format
+ * @param {string} nationalNumber
+ * @returns {string}
+ */
+function formatFRNational(nationalNumber) {
+  if (nationalNumber.length !== 9) return nationalNumber;
+  // Format: 0X XX XX XX XX
+  const parts = [];
+  parts.push('0' + nationalNumber[0]);
+  for (let i = 1; i < 9; i += 2) {
+    parts.push(nationalNumber.slice(i, i + 2));
+  }
+  return parts.join(' ');
+}
+
+/**
+ * Format Japan number in national format
+ * @param {string} nationalNumber
+ * @returns {string}
+ */
+function formatJPNational(nationalNumber) {
+  if (nationalNumber.length !== 10) return nationalNumber;
+  // Mobile: 0X0-XXXX-XXXX
+  const prefix = nationalNumber.slice(0, 2);
+  const middle = nationalNumber.slice(2, 6);
+  const end = nationalNumber.slice(6);
+  return `0${prefix}-${middle}-${end}`;
+}
+
+/**
+ * Format Brazil number in national format
+ * @param {string} nationalNumber
+ * @returns {string}
+ */
+function formatBRNational(nationalNumber) {
+  if (nationalNumber.length !== 11) return nationalNumber;
+  // Format: (XX) XXXXX-XXXX
+  const areaCode = nationalNumber.slice(0, 2);
+  const first = nationalNumber.slice(2, 7);
+  const second = nationalNumber.slice(7);
+  return `(${areaCode}) ${first}-${second}`;
+}
+
+/**
+ * National format functions by country code
+ */
+const nationalFormatters = {
+  US: formatUSNational,
+  CA: formatUSNational,
+  UK: formatUKNational,
+  CN: formatCNNational,
+  AU: formatAUNational,
+  IN: formatINNational,
+  DE: formatDENational,
+  FR: formatFRNational,
+  JP: formatJPNational,
+  BR: formatBRNational
+};
+
+/**
+ * Format international style with spaces
+ * @param {string} dialCode
+ * @param {string} nationalNumber
+ * @param {string} countryCode
+ * @returns {string}
+ */
+function formatInternational(dialCode, nationalNumber, countryCode) {
+  // Get national format and replace leading 0 removal
+  const formatter = nationalFormatters[countryCode];
+  if (formatter) {
+    let national = formatter(nationalNumber);
+    // Remove leading 0 if present
+    if (national.startsWith('0')) {
+      national = national.slice(1);
+    }
+    return `${dialCode} ${national}`;
+  }
+  return `${dialCode} ${nationalNumber}`;
+}
+
+/**
+ * Format phone number
+ * @param {string} input - Phone number to format
+ * @param {string} [style='e164'] - Output format style
+ * @param {Object} [options] - Additional options
+ * @param {string} [options.defaultCountry] - Default country for local numbers
+ * @returns {string|null} Formatted number or null if invalid
+ */
+function format(input, style = 'e164', options = {}) {
+  if (!input || typeof input !== 'string') return null;
+
+  const { defaultCountry } = options;
+  const trimmed = input.trim();
+  const normalizedStyle = String(style).toLowerCase();
+
+  // Sanitize input
+  const sanitized = sanitize(trimmed);
+
+  let countryCode;
+  let dialCode;
+  let nationalNumber;
+
+  // Handle E.164 format
+  if (sanitized.startsWith('+')) {
+    const extracted = extractCountryCode(sanitized);
+    if (!extracted) return null;
+
+    countryCode = extracted.countryCode;
+    dialCode = extracted.dialCode;
+    nationalNumber = extracted.nationalNumber;
+  } 
+  // Handle local format with defaultCountry
+  else if (defaultCountry) {
+    const country = getCountry(defaultCountry);
+    if (!country) return null;
+
+    countryCode = country.code;
+    dialCode = country.dialCode;
+    nationalNumber = sanitized.startsWith('0') ? sanitized.slice(1) : sanitized;
+  } 
+  else {
+    return null;
+  }
+
+  const country = getCountry(countryCode);
+  if (!country) return null;
+
+  // Format based on style
+  switch (normalizedStyle) {
+    case FormatStyle.E164:
+      return `${dialCode}${nationalNumber}`;
+
+    case FormatStyle.INTERNATIONAL:
+      return formatInternational(dialCode, nationalNumber, countryCode);
+
+    case FormatStyle.NATIONAL: {
+      const formatter = nationalFormatters[countryCode];
+      if (formatter) {
+        return formatter(nationalNumber);
+      }
+      return nationalNumber;
+    }
+
+    case FormatStyle.RFC3966: {
+      const e164 = `${dialCode}${nationalNumber}`.replace('+', '');
+      // Format with hyphens
+      const international = formatInternational(dialCode, nationalNumber, countryCode);
+      const formatted = international.replace(/\s+/g, '-').replace(/[()]/g, '');
+      return `tel:${formatted}`;
+    }
+
+    case FormatStyle.DIGITS:
+      return `${dialCode.replace('+', '')}${nationalNumber}`;
+
+    default:
+      return `${dialCode}${nationalNumber}`;
+  }
+}
+
+/**
+ * Convert any phone number format to E.164
+ * @param {string} input - Phone number
+ * @param {string} [defaultCountry] - Default country code for local numbers
+ * @returns {string|null}
+ */
+function toE164(input, defaultCountry) {
+  return format(input, 'e164', { defaultCountry });
+}
+
+/**
+ * Convert to national format
+ * @param {string} input - Phone number
+ * @param {string} [defaultCountry] - Default country code
+ * @returns {string|null}
+ */
+function toNational(input, defaultCountry) {
+  return format(input, 'national', { defaultCountry });
+}
+
+/**
+ * Convert to international format
+ * @param {string} input - Phone number
+ * @param {string} [defaultCountry] - Default country code
+ * @returns {string|null}
+ */
+function toInternational(input, defaultCountry) {
+  return format(input, 'international', { defaultCountry });
+}
+
+module.exports = {
+  format,
+  toE164,
+  toNational,
+  toInternational,
+  FormatStyle
+};