@indodev/toolkit 0.0.1

package/dist/phone/index.d.ts

@@ -0,0 +1,472 @@
+/**
+ * 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;
+}
+
+/**
+ * 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.
+ *
+ * By default, shows the first 4 and last 4 digits, masking the middle digits.
+ * Optionally formats with 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'
+ * ```
+ *
+ * @example
+ * Custom mask character:
+ * ```typescript
+ * maskPhoneNumber('081234567890', { char: 'X' });
+ * // '0812XXXX7890'
+ * ```
+ *
+ * @example
+ * With separator:
+ * ```typescript
+ * maskPhoneNumber('081234567890', { separator: '-' });
+ * // '0812-****-7890'
+ * ```
+ *
+ * @public
+ */
+declare function maskPhoneNumber(phone: string, options?: MaskOptions): string;
+
+/**
+ * Parses an Indonesian phone number and extracts all information.
+ *
+ * Extracts country code, operator, formatted variants, and determines
+ * if it's a mobile or landline number.
+ *
+ * @param phone - The phone number to parse
+ * @returns Parsed phone information, or `null` if invalid
+ *
+ * @example
+ * Parse a mobile number:
+ * ```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
+ * // }
+ * ```
+ *
+ * @example
+ * Parse with different input format:
+ * ```typescript
+ * const info = parsePhoneNumber('+62 812-3456-7890');
+ * console.log(info.operator); // 'Telkomsel'
+ * console.log(info.formatted.national); // '0812-3456-7890'
+ * ```
+ *
+ * @example
+ * Parse a landline:
+ * ```typescript
+ * const info = parsePhoneNumber('0212345678');
+ * console.log(info.region); // 'Jakarta'
+ * console.log(info.isLandline); // true
+ * ```
+ *
+ * @public
+ */
+declare function parsePhoneNumber(phone: string): PhoneInfo | null;
+/**
+ * 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
+ *
+ * @example
+ * Telkomsel numbers:
+ * ```typescript
+ * getOperator('081234567890'); // 'Telkomsel'
+ * getOperator('0812-3456-7890'); // 'Telkomsel'
+ * getOperator('+6281234567890'); // 'Telkomsel'
+ * ```
+ *
+ * @example
+ * XL numbers:
+ * ```typescript
+ * getOperator('081734567890'); // 'XL'
+ * ```
+ *
+ * @example
+ * Non-mobile or invalid:
+ * ```typescript
+ * getOperator('0212345678'); // null (landline)
+ * getOperator('1234'); // null (invalid)
+ * ```
+ *
+ * @public
+ */
+declare function getOperator(phone: string): string | null;
+
+export { type MaskOptions, type PhoneFormat, type PhoneInfo, cleanPhoneNumber, formatPhoneNumber, getOperator, isLandlineNumber, isMobileNumber, maskPhoneNumber, parsePhoneNumber, toE164, toInternational, toNational, validatePhoneNumber };