@devdataphone/sdk 1.0.0

package/index.d.ts

@@ -0,0 +1,249 @@
+/**
+ * DevDataPhone SDK TypeScript Definitions
+ * @module @devdataphone/sdk
+ */
+
+export interface Country {
+  code: string;
+  name: string;
+  dialCode: string;
+  flag: string;
+  example: string;
+  regex: RegExp;
+  reservedRanges: Array<{
+    areaCode?: string;
+    exchange?: string;
+    to?: string;
+    prefix?: string;
+    start?: string;
+    end?: string;
+  }>;
+  numberLength: number | { min: number; max: number };
+  mobilePrefix?: string | null;
+  mobilePrefixes?: string[];
+  mobileStartDigits?: string[];
+}
+
+export interface AreaCode {
+  code: number;
+  state: string;
+  city?: string;
+  province?: string;
+}
+
+export interface GenerateOptions {
+  /** Country code (US, UK, CN, IN, AU, CA, DE, FR, JP, BR) */
+  region?: string;
+  /** Number of phone numbers to generate (1-1000) */
+  count?: number;
+  /** Output format ('e164', 'national', 'international', 'digits') */
+  format?: 'e164' | 'national' | 'international' | 'digits';
+}
+
+export interface GeneratedNumber {
+  /** Formatted phone number */
+  number: string;
+  /** E.164 formatted number */
+  e164: string;
+  /** National format */
+  national: string;
+  /** Country name */
+  country: string;
+  /** ISO country code */
+  countryCode: string;
+  /** International dial code */
+  dialCode: string;
+  /** Location (city/state or country) */
+  location: string;
+  /** Raw digits */
+  raw: string;
+}
+
+export interface ValidateOptions {
+  /** Default country code for local numbers */
+  defaultCountry?: string;
+  /** Enable strict validation */
+  strict?: boolean;
+}
+
+export interface ValidationResult {
+  /** Whether the number is valid */
+  valid: boolean;
+  /** E.164 formatted number */
+  e164: string | null;
+  /** Country name */
+  country: string | null;
+  /** ISO country code */
+  countryCode: string | null;
+  /** International dial code */
+  dialCode: string | null;
+  /** National significant number */
+  nationalNumber: string | null;
+  /** Number type (MOBILE, FIXED_LINE, UNKNOWN) */
+  type: 'MOBILE' | 'FIXED_LINE' | 'UNKNOWN';
+  /** Error message if invalid */
+  error: string | null;
+}
+
+export interface FormatOptions {
+  /** Default country code for local numbers */
+  defaultCountry?: string;
+}
+
+export type FormatStyleType = 'e164' | 'international' | 'national' | 'rfc3966' | 'digits';
+
+export const FormatStyle: {
+  E164: 'e164';
+  INTERNATIONAL: 'international';
+  NATIONAL: 'national';
+  RFC3966: 'rfc3966';
+  DIGITS: 'digits';
+};
+
+/**
+ * Generate random phone numbers
+ * @param options - Generation options
+ * @returns Array of generated phone numbers
+ * @throws Error if region is not supported or count is invalid
+ * @example
+ * const numbers = generate({ region: 'US', count: 10 });
+ */
+export function generate(options?: GenerateOptions): GeneratedNumber[];
+
+/**
+ * Generate a single phone number
+ * @param region - Country code (default: 'US')
+ * @param format - Output format (default: 'e164')
+ * @returns Single phone number string
+ * @example
+ * const number = generateOne('CN', 'national');
+ */
+export function generateOne(region?: string, format?: string): string;
+
+/**
+ * Validate a phone number
+ * @param input - Phone number to validate
+ * @param options - Validation options
+ * @returns Validation result
+ * @example
+ * const result = validate('+8613912345678');
+ * console.log(result.country); // 'China'
+ */
+export function validate(input: string, options?: ValidateOptions): ValidationResult;
+
+/**
+ * Quick validation check
+ * @param input - Phone number to validate
+ * @param defaultCountry - Default country code
+ * @returns true if valid
+ */
+export function isValid(input: string, defaultCountry?: string): boolean;
+
+/**
+ * Check if input is valid E.164 format
+ * @param input - Phone number
+ * @returns true if valid E.164
+ */
+export function isE164(input: string): boolean;
+
+/**
+ * Format a phone number
+ * @param input - Phone number
+ * @param style - Output format style
+ * @param options - Additional options
+ * @returns Formatted number or null if invalid
+ * @example
+ * format('+14155550100', 'national'); // '(415) 555-0100'
+ */
+export function format(
+  input: string,
+  style?: FormatStyleType,
+  options?: FormatOptions
+): string | null;
+
+/**
+ * Convert any phone number format to E.164
+ * @param input - Phone number
+ * @param defaultCountry - Default country code for local numbers
+ * @returns E.164 formatted number or null
+ */
+export function toE164(input: string, defaultCountry?: string): string | null;
+
+/**
+ * Convert to national format
+ * @param input - Phone number
+ * @param defaultCountry - Default country code
+ * @returns National formatted number or null
+ */
+export function toNational(input: string, defaultCountry?: string): string | null;
+
+/**
+ * Convert to international format
+ * @param input - Phone number
+ * @param defaultCountry - Default country code
+ * @returns International formatted number or null
+ */
+export function toInternational(input: string, defaultCountry?: string): string | null;
+
+/**
+ * Remove all non-digit characters except leading +
+ * @param input - Phone number
+ * @returns Sanitized number
+ */
+export function sanitize(input: string): string;
+
+/**
+ * Get country by code
+ * @param code - ISO 3166-1 alpha-2 country code
+ * @returns Country data or undefined
+ */
+export function getCountry(code: string): Country | undefined;
+
+/**
+ * Get all supported country codes
+ * @returns Array of country codes
+ */
+export function getSupportedCountries(): string[];
+
+/**
+ * Check if a country code is supported
+ * @param code - Country code
+ * @returns true if supported
+ */
+export function isSupported(code: string): boolean;
+
+/** Supported countries data */
+export const COUNTRIES: Country[];
+
+/** US Area codes data */
+export const US_AREA_CODES: AreaCode[];
+
+/** Canada Area codes data */
+export const CA_AREA_CODES: AreaCode[];
+
+/** SDK Version */
+export const VERSION: string;
+
+// Default export
+declare const _default: {
+  generate: typeof generate;
+  generateOne: typeof generateOne;
+  validate: typeof validate;
+  isValid: typeof isValid;
+  isE164: typeof isE164;
+  format: typeof format;
+  toE164: typeof toE164;
+  toNational: typeof toNational;
+  toInternational: typeof toInternational;
+  FormatStyle: typeof FormatStyle;
+  sanitize: typeof sanitize;
+  COUNTRIES: typeof COUNTRIES;
+  US_AREA_CODES: typeof US_AREA_CODES;
+  CA_AREA_CODES: typeof CA_AREA_CODES;
+  getCountry: typeof getCountry;
+  getSupportedCountries: typeof getSupportedCountries;
+  isSupported: typeof isSupported;
+  VERSION: typeof VERSION;
+};
+
+export default _default;

package/index.js

@@ -0,0 +1,175 @@
+/**
+ * DevDataPhone SDK
+ * Generate valid E.164 phone numbers for QA testing, database seeding, and mock data.
+ * 
+ * @example
+ * const { generate, validate, format } = require('@devdataphone/sdk');
+ * 
+ * // Generate 10 US phone numbers
+ * const numbers = generate({ region: 'US', count: 10 });
+ * 
+ * // Validate a phone number
+ * const result = validate('+14155550100');
+ * 
+ * // Format a phone number
+ * const formatted = format('+14155550100', 'national');
+ * 
+ * @module @devdataphone/sdk
+ * @version 1.0.0
+ * @license MIT
+ */
+
+'use strict';
+
+const { generate, generateOne } = require('./src/generator');
+const { validate, isValid, isE164, sanitize } = require('./src/validator');
+const { format, toE164, toNational, toInternational, FormatStyle } = require('./src/formatter');
+const { COUNTRIES, US_AREA_CODES, CA_AREA_CODES, getCountry, getSupportedCountries, isSupported } = require('./src/countries');
+
+/**
+ * SDK Version
+ * @type {string}
+ */
+const VERSION = '1.0.0';
+
+/**
+ * Generate random phone numbers
+ * @function generate
+ * @param {Object} options - Generation options
+ * @param {string} [options.region='US'] - Country code (US, UK, CN, IN, AU, CA, DE, FR, JP, BR)
+ * @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<Object>} Array of generated phone numbers
+ * @throws {Error} If region is not supported or count is invalid
+ * 
+ * @example
+ * // Generate 5 UK phone numbers
+ * const numbers = generate({ region: 'UK', count: 5 });
+ * console.log(numbers[0].number); // +447700900123
+ * console.log(numbers[0].national); // 07700 900123
+ */
+
+/**
+ * Generate a single phone number
+ * @function generateOne
+ * @param {string} [region='US'] - Country code
+ * @param {string} [format='e164'] - Output format
+ * @returns {string} Single phone number string
+ * 
+ * @example
+ * const number = generateOne('CN', 'national');
+ * console.log(number); // 139 1234 5678
+ */
+
+/**
+ * Validate a phone number
+ * @function validate
+ * @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 {Object} Validation result
+ * 
+ * @example
+ * const result = validate('+8613912345678');
+ * console.log(result.valid); // true
+ * console.log(result.country); // China
+ * console.log(result.countryCode); // CN
+ */
+
+/**
+ * Quick validation check
+ * @function isValid
+ * @param {string} input - Phone number to validate
+ * @param {string} [defaultCountry] - Default country code
+ * @returns {boolean}
+ * 
+ * @example
+ * console.log(isValid('+14155550100')); // true
+ * console.log(isValid('555-0100', 'US')); // true
+ */
+
+/**
+ * Check if input is valid E.164 format
+ * @function isE164
+ * @param {string} input - Phone number
+ * @returns {boolean}
+ * 
+ * @example
+ * console.log(isE164('+14155550100')); // true
+ * console.log(isE164('(415) 555-0100')); // false
+ */
+
+/**
+ * Format a phone number
+ * @function format
+ * @param {string} input - Phone number
+ * @param {string} [style='e164'] - Output format ('e164', 'international', 'national', 'rfc3966', 'digits')
+ * @param {Object} [options] - Additional options
+ * @returns {string|null} Formatted number or null if invalid
+ * 
+ * @example
+ * format('+14155550100', 'national'); // (415) 555-0100
+ * format('+14155550100', 'international'); // +1 415 555 0100
+ */
+
+/**
+ * Supported countries data
+ * @constant {Array<Object>} COUNTRIES
+ */
+
+/**
+ * US Area codes data
+ * @constant {Array<Object>} US_AREA_CODES
+ */
+
+/**
+ * Get country by code
+ * @function getCountry
+ * @param {string} code - ISO 3166-1 alpha-2 country code
+ * @returns {Object|undefined}
+ */
+
+/**
+ * Get all supported country codes
+ * @function getSupportedCountries
+ * @returns {string[]}
+ */
+
+/**
+ * Check if country is supported
+ * @function isSupported
+ * @param {string} code - Country code
+ * @returns {boolean}
+ */
+
+// Export all functions and constants
+module.exports = {
+  // Core functions
+  generate,
+  generateOne,
+  validate,
+  isValid,
+  isE164,
+  format,
+  
+  // Formatter helpers
+  toE164,
+  toNational,
+  toInternational,
+  FormatStyle,
+  
+  // Utilities
+  sanitize,
+  
+  // Country data
+  COUNTRIES,
+  US_AREA_CODES,
+  CA_AREA_CODES,
+  getCountry,
+  getSupportedCountries,
+  isSupported,
+  
+  // Meta
+  VERSION
+};

package/index.mjs

@@ -0,0 +1,31 @@
+/**
+ * DevDataPhone SDK - ESM Module Entry
+ * @module @devdataphone/sdk
+ */
+
+// Re-export from CommonJS module
+import pkg from './index.js';
+
+export const {
+  generate,
+  generateOne,
+  validate,
+  isValid,
+  isE164,
+  format,
+  toE164,
+  toNational,
+  toInternational,
+  FormatStyle,
+  sanitize,
+  COUNTRIES,
+  US_AREA_CODES,
+  CA_AREA_CODES,
+  getCountry,
+  getSupportedCountries,
+  isSupported,
+  VERSION
+} = pkg;
+
+// Default export
+export default pkg;

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@devdataphone/sdk",
+  "version": "1.0.0",
+  "description": "Generate valid E.164 phone numbers for QA testing, database seeding, and mock data. Zero server-side retention.",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./index.js",
+      "import": "./index.mjs",
+      "types": "./index.d.ts"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "src/"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "phone",
+    "phone-number",
+    "e164",
+    "mock-data",
+    "faker",
+    "generator",
+    "validation",
+    "testing",
+    "qa",
+    "libphonenumber"
+  ],
+  "author": "DevDataPhone",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/user/devdataphone"
+  },
+  "homepage": "https://devdataphone.com",
+  "bugs": {
+    "url": "https://github.com/user/devdataphone/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "peerDependencies": {
+    "libphonenumber-js": "^1.10.0"
+  },
+  "peerDependenciesMeta": {
+    "libphonenumber-js": {
+      "optional": true
+    }
+  }
+}