@indodev/toolkit 0.4.0 → 0.4.2

package/dist/phone/index.d.ts

@@ -1,528 +1,81 @@
-/**
- * Validates an Indonesian phone number format.
- *
- * Accepts multiple input formats:
- * - National format: 08xx-xxxx-xxxx or 08xxxxxxxxxx
- * - International with +: +62 8xx-xxxx-xxxx or +628xxxxxxxxxx
- * - International without +: 62 8xx-xxxx-xxxx or 628xxxxxxxxxx
- *
- * For mobile numbers, validates:
- * - Starts with 08 (national) or 628 (international)
- * - Has valid operator prefix (0811, 0812, 0817, etc.)
- * - Total length is 10-13 digits (after removing non-digits)
- *
- * For landline numbers, validates:
- * - Starts with 0 followed by area code (021, 022, etc.)
- * - Total length is appropriate for landline
- *
- * @param phone - The phone number string to validate
- * @returns `true` if the phone number is valid, `false` otherwise
- *
- * @example
- * Valid mobile number (national):
- * ```typescript
- * validatePhoneNumber('081234567890'); // true
- * ```
- *
- * @example
- * Valid mobile number (international):
- * ```typescript
- * validatePhoneNumber('+6281234567890'); // true
- * validatePhoneNumber('6281234567890'); // true
- * ```
- *
- * @example
- * With separators:
- * ```typescript
- * validatePhoneNumber('0812-3456-7890'); // true
- * validatePhoneNumber('+62 812-3456-7890'); // true
- * ```
- *
- * @example
- * Invalid numbers:
- * ```typescript
- * validatePhoneNumber('1234'); // false - too short
- * validatePhoneNumber('08001234567'); // false - invalid prefix
- * validatePhoneNumber('+1234567890'); // false - wrong country code
- * ```
- *
- * @public
- */
-declare function validatePhoneNumber(phone: string): boolean;
-/**
- * Checks if a phone number is a mobile number.
- *
- * @param phone - The phone number to check
- * @returns `true` if it's a mobile number (08xx), `false` otherwise
- *
- * @example
- * ```typescript
- * isMobileNumber('081234567890'); // true
- * isMobileNumber('+6281234567890'); // true
- * isMobileNumber('0212345678'); // false (landline)
- * ```
- *
- * @public
- */
-declare function isMobileNumber(phone: string): boolean;
-/**
- * Checks if a phone number is a landline number.
- *
- * @param phone - The phone number to check
- * @returns `true` if it's a landline number, `false` otherwise
- *
- * @example
- * ```typescript
- * isLandlineNumber('0212345678'); // true
- * isLandlineNumber('081234567890'); // false (mobile)
- * ```
- *
- * @public
- */
-declare function isLandlineNumber(phone: string): boolean;
-
-/**
- * Format types for Indonesian phone numbers.
- *
- * - `international`: +62 format with spaces (e.g., '+62 812-3456-7890')
- * - `national`: 08xx format with dashes (e.g., '0812-3456-7890')
- * - `e164`: International format without spaces (e.g., '6281234567890')
- * - `display`: Formatted for display with separators (same as national)
- *
- * @public
- */
-type PhoneFormat = 'international' | 'national' | 'e164' | 'display';
-/**
- * Information extracted from a valid Indonesian phone number.
- *
- * Contains parsed data including country code, operator, formatted variants,
- * and validation status.
- *
- * @example
- * ```typescript
- * const info: PhoneInfo = {
- *   countryCode: '62',
- *   operator: 'Telkomsel',
- *   number: '81234567890',
- *   formatted: {
- *     international: '+62 812-3456-7890',
- *     national: '0812-3456-7890',
- *     e164: '6281234567890',
- *   },
- *   isValid: true,
- *   isMobile: true,
- *   isLandline: false,
- * };
- * ```
- *
- * @public
- */
-interface PhoneInfo {
-    /**
-     * Country code (always '62' for Indonesia).
-     */
-    countryCode: string;
-    /**
-     * Mobile operator name, or `null` if not detected.
-     *
-     * Possible values: 'Telkomsel', 'XL', 'Indosat', 'Tri', 'Smartfren', 'Axis'
-     *
-     * @example
-     * ```typescript
-     * 'Telkomsel' // for 0812, 0813, 0821, 0822, 0851, 0852, 0853
-     * 'XL'        // for 0817, 0818, 0819, 0859, 0877, 0878
-     * null        // if operator cannot be determined
-     * ```
-     */
-    operator: string | null;
-    /**
-     * Raw phone number without country code or leading zero.
-     *
-     * @example
-     * ```typescript
-     * '81234567890' // from '081234567890' or '+6281234567890'
-     * ```
-     */
-    number: string;
-    /**
-     * Phone number in various formatted styles.
-     */
-    formatted: {
-        /** International format with country code: '+62 812-3456-7890' */
-        international: string;
-        /** National format with leading zero: '0812-3456-7890' */
-        national: string;
-        /** E.164 format (no spaces/dashes): '6281234567890' */
-        e164: string;
-    };
-    /**
-     * Whether the phone number passed validation checks.
-     */
-    isValid: boolean;
-    /**
-     * Whether this is a mobile number (08xx).
-     */
-    isMobile: boolean;
-    /**
-     * Whether this is a landline number (02x, 04x, etc).
-     */
-    isLandline: boolean;
-    /**
-     * Region name for landline numbers, or `null` for mobile.
-     *
-     * @example
-     * ```typescript
-     * 'Jakarta'   // for 021 area code
-     * 'Bandung'   // for 022 area code
-     * null        // for mobile numbers
-     * ```
-     */
-    region?: string | null;
-}
-/**
- * Options for masking phone numbers.
- *
- * Controls how many digits to show at the start and end,
- * what character to use for masking, and optional separators.
- *
- * @example
- * Default masking:
- * ```typescript
- * { start: 4, end: 4, char: '*' }
- * // '0812****7890'
- * ```
- *
- * @example
- * With separator:
- * ```typescript
- * { start: 4, end: 4, char: '*', separator: '-' }
- * // '0812-****-7890'
- * ```
- *
- * @public
- */
-interface MaskOptions {
-    /**
-     * Number of digits to show at the start.
-     *
-     * @defaultValue 4
-     */
-    start?: number;
-    /**
-     * Number of digits to show at the end.
-     *
-     * @defaultValue 4
-     */
-    end?: number;
-    /**
-     * Character to use for masking hidden digits.
-     *
-     * @defaultValue '*'
-     */
-    char?: string;
-    /**
-     * Optional separator to add between groups of digits.
-     *
-     * @defaultValue undefined
-     */
-    separator?: string;
-}
+export { M as MaskOptions, O as OperatorName, P as PhoneFormat, l as PhoneInfo, d as cleanPhoneNumber, f as formatPhoneNumber, h as generateSmsLink, j as generateTelLink, e as generateWALink, g as getOperator, a as isLandlineNumber, i as isMobileNumber, k as isProvider, m as maskPhoneNumber, p as parsePhoneNumber, c as toE164, t as toInternational, b as toNational, v as validatePhoneNumber } from '../parse-BDfy3aQw.js';
 
 /**
- * Formats an Indonesian phone number to the specified format.
- *
- * Accepts various input formats and converts to the desired output format.
- * Automatically adds appropriate separators for readability.
- *
- * @param phone - The phone number to format
- * @param format - Target format ('international', 'national', 'e164', 'display')
- * @returns Formatted phone number, or original string if invalid
- *
- * @example
- * International format:
- * ```typescript
- * formatPhoneNumber('081234567890', 'international');
- * // '+62 812-3456-7890'
- * ```
- *
- * @example
- * National format:
- * ```typescript
- * formatPhoneNumber('+6281234567890', 'national');
- * // '0812-3456-7890'
- * ```
- *
- * @example
- * E.164 format (no spaces/dashes):
- * ```typescript
- * formatPhoneNumber('0812-3456-7890', 'e164');
- * // '6281234567890'
- * ```
- *
- * @public
- */
-declare function formatPhoneNumber(phone: string, format?: PhoneFormat): string;
-/**
- * Converts a phone number to international format (+62 xxx-xxxx-xxxx).
- *
- * @param phone - The phone number to convert
- * @returns Phone number in international format with separators
- *
- * @example
- * ```typescript
- * toInternational('081234567890');
- * // '+62 812-3456-7890'
- * ```
- *
- * @example
- * Already international:
- * ```typescript
- * toInternational('+6281234567890');
- * // '+62 812-3456-7890'
- * ```
- *
- * @public
- */
-declare function toInternational(phone: string): string;
-/**
- * Converts a phone number to national format (08xx-xxxx-xxxx).
- *
- * @param phone - The phone number to convert
- * @returns Phone number in national format with dashes
- *
- * @example
- * ```typescript
- * toNational('+6281234567890');
- * // '0812-3456-7890'
- * ```
- *
- * @example
- * Already national:
- * ```typescript
- * toNational('081234567890');
- * // '0812-3456-7890'
- * ```
- *
- * @public
- */
-declare function toNational(phone: string): string;
-/**
- * Converts a phone number to E.164 format (6281234567890).
- *
- * E.164 is the international standard format without spaces or dashes.
- * Suitable for API calls and database storage.
- *
- * @param phone - The phone number to convert
- * @returns Phone number in E.164 format
- *
- * @example
- * ```typescript
- * toE164('0812-3456-7890');
- * // '6281234567890'
- * ```
- *
- * @example
- * From international format:
- * ```typescript
- * toE164('+62 812-3456-7890');
- * // '6281234567890'
- * ```
- *
- * @public
- */
-declare function toE164(phone: string): string;
-/**
- * Removes all non-digit characters from a phone number, preserving leading +.
- *
- * @param phone - The phone number to clean
- * @returns Cleaned phone number with only digits (and optional leading +)
- *
- * @example
- * ```typescript
- * cleanPhoneNumber('0812-3456-7890');
- * // '081234567890'
- * ```
- *
- * @example
- * ```typescript
- * cleanPhoneNumber('+62 812 3456 7890');
- * // '+6281234567890'
- * ```
- *
- * @public
- */
-declare function cleanPhoneNumber(phone: string): string;
-/**
- * Masks a phone number for privacy protection.
+ * Normalizes a cleaned phone number to national format (0xxx).
  *
- * By default, shows the first 4 and last 4 digits, masking the middle digits.
- * Optionally formats with separators.
+ * Accepts pre-cleaned phone string (digits only, optional leading +).
+ * Use `cleanPhoneNumber()` first if input may contain separators.
  *
- * @param phone - The phone number to mask
- * @param options - Masking configuration options
- * @returns Masked phone number, or original string if invalid
- *
- * @example
- * Default masking:
- * ```typescript
- * maskPhoneNumber('081234567890');
- * // '0812****7890'
- * ```
+ * @param phone - Cleaned phone number string
+ * @returns Phone number in 08xx format, or empty string if invalid
  *
  * @example
- * Custom mask character:
  * ```typescript
- * maskPhoneNumber('081234567890', { char: 'X' });
- * // '0812XXXX7890'
+ * normalizePhoneNumber('+6281234567890'); // '081234567890'
+ * normalizePhoneNumber('6281234567890'); // '081234567890'
+ * normalizePhoneNumber('081234567890'); // '081234567890'
  * ```
  *
  * @example
- * With separator:
+ * Invalid inputs return empty string:
  * ```typescript
- * maskPhoneNumber('081234567890', { separator: '-' });
- * // '0812-****-7890'
+ * normalizePhoneNumber(''); // ''
+ * normalizePhoneNumber('620812345678'); // '' (620 is not valid country code pattern)
+ * normalizePhoneNumber('invalid'); // ''
  * ```
  *
  * @public
  */
-declare function maskPhoneNumber(phone: string, options?: MaskOptions): string;
-
-/**
- * Generates a WhatsApp click-to-chat link.
- *
- * @param phone - The Indonesian phone number
- * @param message - Optional pre-filled message
- * @returns WhatsApp link, or empty string if phone is invalid
- *
- * @example
- * ```typescript
- * generateWALink('081234567890', 'Halo!');
- * // 'https://wa.me/6281234567890?text=Halo%21'
- * ```
- */
-declare function generateWALink(phone: string, message?: string): string;
-/**
- * Generates an SMS link (sms:).
- *
- * @param phone - The Indonesian phone number
- * @param body - Optional SMS body
- * @returns SMS link, or empty string if phone is invalid
- *
- * @example
- * ```typescript
- * generateSmsLink('081234567890', 'Pesan ini');
- * // 'sms:+6281234567890?body=Pesan%20ini'
- * ```
- */
-declare function generateSmsLink(phone: string, body?: string): string;
-/**
- * Generates a telephone link (tel:).
- *
- * @param phone - The Indonesian phone number
- * @returns Tel link, or empty string if phone is invalid
- *
- * @example
- * ```typescript
- * generateTelLink('081234567890');
- * // 'tel:+6281234567890'
- * ```
- */
-declare function generateTelLink(phone: string): string;
-
+declare function normalizePhoneNumber(phone: string): string;
 /**
- * Parses an Indonesian phone number and extracts all information.
+ * Compares two phone numbers regardless of format.
  *
- * Extracts country code, operator, formatted variants, and determines
- * if it's a mobile or landline number.
+ * Both inputs are normalized to national format for comparison.
+ * Returns false if either input is invalid.
  *
- * @param phone - The phone number to parse
- * @returns Parsed phone information, or `null` if invalid
+ * @param phoneA - First phone number in any format
+ * @param phoneB - Second phone number in any format
+ * @returns true if both represent the same number, false otherwise
  *
  * @example
- * Parse a mobile number:
+ * Same number in different formats:
  * ```typescript
- * const info = parsePhoneNumber('081234567890');
- * console.log(info);
- * // {
- * //   countryCode: '62',
- * //   operator: 'Telkomsel',
- * //   number: '81234567890',
- * //   formatted: {
- * //     international: '+62 812-3456-7890',
- * //     national: '0812-3456-7890',
- * //     e164: '6281234567890'
- * //   },
- * //   isValid: true,
- * //   isMobile: true,
- * //   isLandline: false
- * // }
+ * comparePhones('081234567890', '+6281234567890'); // true
+ * comparePhones('0812-3456-7890', '6281234567890'); // true
  * ```
  *
  * @example
- * Parse with different input format:
+ * Different numbers:
  * ```typescript
- * const info = parsePhoneNumber('+62 812-3456-7890');
- * console.log(info.operator); // 'Telkomsel'
- * console.log(info.formatted.national); // '0812-3456-7890'
+ * comparePhones('081234567890', '081234567891'); // false
+ * comparePhones('0212345678', '0221234567'); // false
  * ```
  *
  * @example
- * Parse a landline:
+ * Invalid inputs return false:
  * ```typescript
- * const info = parsePhoneNumber('0212345678');
- * console.log(info.region); // 'Jakarta'
- * console.log(info.isLandline); // true
+ * comparePhones('invalid', '081234567890'); // false
+ * comparePhones('', ''); // false
  * ```
  *
  * @public
  */
-declare function parsePhoneNumber(phone: string): PhoneInfo | null;
+declare function comparePhones(phoneA: string, phoneB: string): boolean;
 /**
- * Detects the mobile operator from a phone number.
- *
- * Identifies the operator based on the phone number prefix.
- * Returns `null` if the operator cannot be determined or if it's not a mobile number.
- *
- * @param phone - The phone number to check
- * @returns Operator name, or `null` if not detected
+ * Gets the region name for a landline number.
  *
- * @example
- * Telkomsel numbers:
- * ```typescript
- * getOperator('081234567890'); // 'Telkomsel'
- * getOperator('0812-3456-7890'); // 'Telkomsel'
- * getOperator('+6281234567890'); // 'Telkomsel'
- * ```
+ * @param phone - Landline phone number in national format
+ * @returns Region name, or null if not found
  *
  * @example
- * XL numbers:
  * ```typescript
- * getOperator('081734567890'); // 'XL'
- * ```
- *
- * @example
- * Non-mobile or invalid:
- * ```typescript
- * getOperator('0212345678'); // null (landline)
- * getOperator('1234'); // null (invalid)
+ * getLandlineRegion('0212345678'); // 'Jakarta'
+ * getLandlineRegion('+62212345678'); // 'Jakarta'
+ * getLandlineRegion('081234567890'); // null (mobile)
  * ```
  *
  * @public
  */
-declare function getOperator(phone: string): string | null;
-/**
- * Checks if a phone number belongs to a specific provider.
- *
- * @param phone - The phone number to check
- * @param providerName - The provider name to match (case-insensitive)
- * @returns `true` if it matches, `false` otherwise
- *
- * @example
- * ```typescript
- * isProvider('081234567890', 'Telkomsel'); // true
- * isProvider('081734567890', 'xl'); // true
- * ```
- */
-declare function isProvider(phone: string, providerName: string): boolean;
+declare function getLandlineRegion(phone: string): string | null;
 
-export { type MaskOptions, type PhoneFormat, type PhoneInfo, cleanPhoneNumber, formatPhoneNumber, generateSmsLink, generateTelLink, generateWALink, getOperator, isLandlineNumber, isMobileNumber, isProvider, maskPhoneNumber, parsePhoneNumber, toE164, toInternational, toNational, validatePhoneNumber };
+export { comparePhones, getLandlineRegion, normalizePhoneNumber };