@indodev/toolkit 0.4.0 → 0.4.2

package/dist/parse-BDfy3aQw.d.cts

@@ -0,0 +1,542 @@
+/**
+ * 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;
+
+/**
+ * Indonesian mobile operator names.
+ *
+ * @public
+ */
+type OperatorName = 'Telkomsel' | 'XL' | 'Indosat' | 'Smartfren' | 'Axis';
+/**
+ * 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', '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: OperatorName | 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;
+
+/**
+ * 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'
+ * ```
+ *
+ * @public
+ */
+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'
+ * ```
+ *
+ * @public
+ */
+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'
+ * ```
+ *
+ * @public
+ */
+declare function generateTelLink(phone: string): 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): OperatorName | 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
+ * ```
+ *
+ * @public
+ */
+declare function isProvider(phone: string, providerName: string): boolean;
+
+export { type MaskOptions as M, type OperatorName as O, type PhoneFormat as P, isLandlineNumber as a, toNational as b, toE164 as c, cleanPhoneNumber as d, generateWALink as e, formatPhoneNumber as f, getOperator as g, generateSmsLink as h, isMobileNumber as i, generateTelLink as j, isProvider as k, type PhoneInfo as l, maskPhoneNumber as m, parsePhoneNumber as p, toInternational as t, validatePhoneNumber as v };