Guyana Phone Numbers: Format, Area Code & Validation Guide

// Landline
const landlineRegex = /^2[1-9]\d{5}$/;

// Mobile
const mobileRegex = /^(6\d{6}|7[0-5]\d{5})$/;

// Toll-free
const tollFreeRegex = /^800\d{4}$/;

// Premium Rate
const premiumRateRegex = /^9008\d{3}$/;

// Comprehensive E.164 validation with country code
function validateE164GuyanaNumber(number) {
  // Accept +592 or 592 prefix
  const e164Regex = /^\+?592(2[1-9]\d{5}|6\d{6}|7[0-5]\d{5}|800\d{4}|9008\d{3})$/;
  return e164Regex.test(number.replace(/[\s\-\(\)]/g, ''));
}

// Auto-detect number type
function detectNumberType(number) {
  const cleaned = number.replace(/\D/g, '');
  const nsn = cleaned.startsWith('592') ? cleaned.substring(3) : cleaned;

  if (nsn.length !== 7) return null;

  if (/^2[1-9]\d{5}$/.test(nsn)) return 'landline';
  if (/^6\d{6}$/.test(nsn)) return 'mobile';
  if (/^7[0-5]\d{5}$/.test(nsn)) return 'mobile';
  if (/^800\d{4}$/.test(nsn)) return 'tollFree';
  if (/^9008\d{3}$/.test(nsn)) return 'premiumRate';

  return null; // Invalid or reserved range
}

function validateGuyanaNumber(number, type) {
  const cleanedNumber = number.replace(/\D/g, ''); // Remove non-digit characters

  // Strip country code if present
  const nsn = cleanedNumber.startsWith('592') ? cleanedNumber.substring(3) : cleanedNumber;

  switch (type) {
    case 'landline': return landlineRegex.test(nsn);
    case 'mobile': return mobileRegex.test(nsn);
    case 'tollFree': return tollFreeRegex.test(nsn);
    case 'premiumRate': return premiumRateRegex.test(nsn);
    default: return false;
  }
}

// Example usage:
console.log(validateGuyanaNumber('2221234', 'landline')); // true
console.log(validateGuyanaNumber('+5926123456', 'mobile')); // true (after cleaning)
console.log(validateGuyanaNumber('800-1234', 'tollFree')); // true (after cleaning)
console.log(validateE164GuyanaNumber('+5922221234')); // true
console.log(detectNumberType('5926123456')); // 'mobile'
console.log(detectNumberType('5927612345')); // null (reserved range)

import re
from typing import Optional, Tuple
from datetime import datetime
import pytz

# Comprehensive validation patterns
PATTERNS = {
    'landline': re.compile(r'^2[1-9]\d{5}$'),
    'mobile': re.compile(r'^(6\d{6}|7[0-5]\d{5})$'),
    'tollFree': re.compile(r'^800\d{4}$'),
    'premiumRate': re.compile(r'^9008\d{3}$')
}

def format_guyana_number(local_number: str) -> str:
    """Convert local number to E.164 format."""
    cleaned = re.sub(r'\D', '', local_number)
    # Remove country code if already present
    if cleaned.startswith('592'):
        cleaned = cleaned[3:]
    if len(cleaned) != 7:
        raise ValueError(f"Invalid length: expected 7 digits, got {len(cleaned)}")
    return f"+592{cleaned}"

def format_for_display(e164_number: str, local: bool = False) -> str:
    """Format E.164 number for display."""
    cleaned = e164_number.replace('+', '').replace('592', '', 1)
    if local:
        return f"{cleaned[:3]}-{cleaned[3:]}"
    return f"+592 {cleaned[:3]}-{cleaned[3:]}"

def detect_number_type(number: str) -> Optional[str]:
    """Auto-detect the type of a Guyana phone number."""
    cleaned = re.sub(r'\D', '', number)
    if cleaned.startswith('592'):
        cleaned = cleaned[3:]

    if len(cleaned) != 7:
        return None

    for number_type, pattern in PATTERNS.items():
        if pattern.match(cleaned):
            return number_type

    return None  # Reserved or invalid range

def validate_guyana_number(number: str, number_type: Optional[str] = None) -> Tuple[bool, Optional[str]]:
    """
    Validate a Guyana phone number.

    Args:
        number: Phone number to validate
        number_type: Expected type (landline, mobile, tollFree, premiumRate) or None to auto-detect

    Returns:
        Tuple of (is_valid, detected_type)
    """
    cleaned = re.sub(r'\D', '', number)

    # Strip country code if present
    if cleaned.startswith('592'):
        cleaned = cleaned[3:]

    if len(cleaned) != 7:
        return False, None

    detected_type = detect_number_type(cleaned)

    if number_type:
        # Validate against specified type
        pattern = PATTERNS.get(number_type)
        if not pattern:
            return False, None
        return pattern.match(cleaned) is not None, detected_type

    # No type specified, any valid type passes
    return detected_type is not None, detected_type

def is_within_guyana_business_hours(check_time: datetime = None) -> bool:
    """Check if current time (or specified time) is within Guyana business hours."""
    guyana_tz = pytz.timezone('America/Guyana')  # UTC-4

    if check_time is None:
        check_time = datetime.now(pytz.UTC)

    local_time = check_time.astimezone(guyana_tz)

    # Business hours: 8 AM – 5 PM, Monday-Friday
    if local_time.weekday() >= 5:  # Saturday or Sunday
        return False

    return 8 <= local_time.hour < 17

# Example using popular phonenumbers library
try:
    import phonenumbers

    def validate_with_phonenumbers(number: str) -> dict:
        """Validate using Google's libphonenumber."""
        try:
            parsed = phonenumbers.parse(number, "GY")
            return {
                'valid': phonenumbers.is_valid_number(parsed),
                'possible': phonenumbers.is_possible_number(parsed),
                'type': phonenumbers.number_type(parsed),
                'e164': phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.E164),
                'international': phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.INTERNATIONAL)
            }
        except phonenumbers.NumberParseException as e:
            return {'valid': False, 'error': str(e)}

except ImportError:
    # phonenumbers library not available
    pass

# Example usage:
if __name__ == "__main__":
    test_numbers = [
        '2221234',      # Valid landline
        '+5926123456',  # Valid mobile
        '7612345',      # Invalid (reserved range)
        '800-1234'      # Valid toll-free
    ]

    for num in test_numbers:
        is_valid, num_type = validate_guyana_number(num)
        print(f"{num}: valid={is_valid}, type={num_type}")
        if is_valid:
            print(f"  E.164: {format_guyana_number(num)}")

const ErrorCodes = {
  EMPTY_INPUT: 'EMPTY_INPUT',
  INVALID_LENGTH: 'INVALID_LENGTH',
  INVALID_CHARACTERS: 'INVALID_CHARACTERS',
  INVALID_COUNTRY_CODE: 'INVALID_COUNTRY_CODE',
  RESERVED_RANGE: 'RESERVED_RANGE',
  INVALID_PREFIX: 'INVALID_PREFIX',
  UNKNOWN_ERROR: 'UNKNOWN_ERROR'
};

function processGuyanaNumber(input) {
  try {
    // Edge case: empty or null input
    if (!input || input.trim() === '') {
      throw { code: ErrorCodes.EMPTY_INPUT, message: 'Phone number cannot be empty' };
    }

    // Remove common formatting but preserve digits and +
    let cleaned = input.replace(/[\s\-\(\)]/g, '');

    // Edge case: invalid characters
    if (!/^[\+\d]+$/.test(cleaned)) {
      throw { code: ErrorCodes.INVALID_CHARACTERS, message: 'Phone number contains invalid characters' };
    }

    // Remove country code prefix if present
    if (cleaned.startsWith('+592')) {
      cleaned = cleaned.substring(4);
    } else if (cleaned.startsWith('592')) {
      cleaned = cleaned.substring(3);
    } else if (cleaned.startsWith('+')) {
      throw { code: ErrorCodes.INVALID_COUNTRY_CODE, message: 'Invalid country code (expected +592)' };
    }

    // Edge case: wrong length
    if (cleaned.length !== 7) {
      throw {
        code: ErrorCodes.INVALID_LENGTH,
        message: `Invalid length: expected 7 digits, got ${cleaned.length}`
      };
    }

    // Edge case: reserved ranges
    const firstDigit = cleaned[0];
    const firstTwo = cleaned.substring(0, 2);

    if (['3', '4', '5'].includes(firstDigit)) {
      throw { code: ErrorCodes.RESERVED_RANGE, message: `Range ${firstDigit}XXXXXX is reserved` };
    }

    if (firstTwo === '20') {
      throw { code: ErrorCodes.RESERVED_RANGE, message: 'Range 20XXXXX is reserved' };
    }

    if (firstDigit === '7' && parseInt(cleaned[1]) > 5) {
      throw { code: ErrorCodes.RESERVED_RANGE, message: 'Range 7[6-9]XXXXX is reserved' };
    }

    // Detect type and validate
    const type = detectNumberType(cleaned);
    if (!type) {
      throw { code: ErrorCodes.INVALID_PREFIX, message: 'Invalid number prefix or pattern' };
    }

    return {
      success: true,
      e164: `+592${cleaned}`,
      local: cleaned,
      type: type,
      formatted: `+592 ${cleaned.substring(0, 3)}-${cleaned.substring(3)}`
    };

  } catch (error) {
    console.error(`Error processing number: ${error.message}`);
    return {
      success: false,
      error: error.code || ErrorCodes.UNKNOWN_ERROR,
      message: error.message || 'Unknown error occurred',
      input: input
    };
  }
}

// Unit test examples
function runTests() {
  const testCases = [
    { input: '2221234', expected: true, description: 'Valid landline' },
    { input: '+5926123456', expected: true, description: 'Valid mobile with country code' },
    { input: '800-1234', expected: true, description: 'Valid toll-free with formatting' },
    { input: '', expected: false, description: 'Empty input' },
    { input: '123', expected: false, description: 'Too short' },
    { input: '20123456', expected: false, description: 'Reserved range 20' },
    { input: '7612345', expected: false, description: 'Reserved range 76' },
    { input: '312345', expected: false, description: 'Reserved prefix 3' },
    { input: 'abcd123', expected: false, description: 'Invalid characters' },
    { input: '+1 592 2221234', expected: false, description: 'Wrong country code format' }
  ];

  testCases.forEach(test => {
    const result = processGuyanaNumber(test.input);
    const passed = result.success === test.expected;
    console.log(`${passed ? '✓' : '✗'} ${test.description}: ${test.input}`);
    if (!passed) {
      console.log(`  Expected: ${test.expected}, Got: ${result.success}`);
      if (!result.success) console.log(`  Error: ${result.message}`);
    }
  });
}

// Batch validation example
async function validateBatch(numbers, batchSize = 100) {
  const results = [];

  for (let i = 0; i < numbers.length; i += batchSize) {
    const batch = numbers.slice(i_ i + batchSize);

    // Process batch in parallel
    const batchResults = await Promise.all(
      batch.map(number => Promise.resolve(processGuyanaNumber(number)))
    );

    results.push(...batchResults);

    // Optional: Progress callback
    if (i % 1000 === 0) {
      console.log(`Processed ${i}/${numbers.length} numbers`);
    }
  }

  return results;
}