@arctics/google-phonelib/dist/types/Library/PhoneNumberHandler.d.ts

A JavaScript/TypeScript package providing wrapper for Google's libphonenumber library

import { IPhoneNumber, IPhoneNumberInfo, IPhoneNumberUtil, NumberFormat } from '../types';
/**
 * PhoneNumberHandler class for parsing, formatting, and retrieving information about phone numbers.
 */
export declare class PhoneNumberHandler {
    /**
     * Instance of PhoneNumberUtil for phone number operations.
     * @private
     */
    private phoneUtil;
    /**
     * Parsed phone number object.
     * @private
     */
    private parsedPhoneNumber;
    /**
     * Creates an instance of PhoneNumberHandler.
     * @param {string} phoneNumber - The phone number string to parse.
     * @param {string} regionCode - The region code (e.g., 'US', 'GB') for parsing the phone number.
     * @param {string} mode - The parsing mode: 'parse' or 'parseAndKeepRawInput'. Defaults to 'parseAndKeepRawInput'. (optional)
     */
    constructor(phoneNumber: string, regionCode: string, mode?: string);
    /**
     * @return {IPhoneNumber} a phone number proto buffer filled with the parsed number.
     *
     * Ideal for executing all functions available by `i18n.phonenumbers.PhoneNumber`.
     */
    getParsedPhoneNumber: () => IPhoneNumber | null;
    /**
     * @return {PhoneNumberUtil} a phone number proto buffer filled with the parsed number.
     *
     * The method that offers the main utilities to work with phone numbers, such as formatting, parsing and validating.
     * Ideal for executing all functions available by `i18n.phonenumbers.PhoneNumberUtil`.
     */
    getPhoneNumberUtil: () => IPhoneNumberUtil;
    /**
     * Parses a string and returns it as a phone number in proto buffer format. The
     * method is quite lenient and looks for a number in the input text (raw input)
     * and does not check whether the string is definitely only a phone number. To
     * do this, it ignores punctuation and white-space, as well as any text before
     * the number (e.g. a leading "Tel: ") and trims the non-number bits.  It will
     * accept a number in any format (E164, national, international etc), assuming
     * it can be interpreted with the defaultRegion supplied. It also attempts to
     * convert any alpha characters into digits if it thinks this is a vanity number
     * of the type "1800 MICROSOFT".
     *
     * @param {?string} numberToParse number that we are attempting to parse. This
     *     can contain formatting such as +, ( and -, as well as a phone number
     *     extension. It can also be provided in RFC3966 format.
     * @param {?string} defaultRegion region that we are expecting the number to be
     *     from. This is only used if the number being parsed is not written in
     *     international format. The country_code for the number in this case would
     *     be stored as that of the default region supplied. If the number is
     *     guaranteed to start with a '+' followed by the country calling code, then
     *     'ZZ' or null can be supplied.
     * @return {IPhoneNumber} a phone number proto buffer filled
     *     with the parsed number.
     */
    private parse;
    /**
     * Parses a string and returns it in proto buffer format. This method differs
     * from {@link #parse} in that it always populates the raw_input field of the
     * protocol buffer with numberToParse as well as the country_code_source field.
     *
     * @param {string} numberToParse number that we are attempting to parse. This
     *     can contain formatting such as +, ( and -, as well as a phone number
     *     extension.
     * @param {?string} defaultRegion region that we are expecting the number to be
     *     from. This is only used if the number being parsed is not written in
     *     international format. The country calling code for the number in this
     *     case would be stored as that of the default region supplied.
     * @return {IPhoneNumber} a phone number proto buffer filled
     *     with the parsed number.
     */
    private parseAndKeepRawInput;
    /**
     * Formats the parsed phone number according to the specified format.
     * @param {NumberFormat} numberFormat - The desired format (PhoneNumberFormat.E164, PhoneNumberFormat.INTERNATIONAL, PhoneNumberFormat.NATIONAL, PhoneNumberFormat.RFC3966).
     * @returns {string | null} The formatted phone number, or null if an error occurs.
     */
    format(numberFormat: NumberFormat | number): string;
    /**
     * Formats a phone number using the original phone number format that the number
     * is parsed from. The original format is embedded in the country_code_source
     * field of the PhoneNumber object passed in. If such information is missing,
     * the number will be formatted into the NATIONAL format by default. When the
     * number contains a leading zero and this is unexpected for this country, or
     * we don't have a formatting pattern for the number, the method returns the
     * raw input when it is available.
     *
     * Note this method guarantees no digit will be inserted, removed or modified as
     * a result of formatting.
     *
     * @param {string} regionCallingFrom the region whose IDD needs to be prefixed
     *     if the original number has one.
     * @return {string} the formatted phone number in its original number format.
     */
    formatInOriginalFormat(regionCallingFrom: string): string;
    /**
     * Formats a phone number for out-of-country dialing purposes. If no
     * regionCallingFrom is supplied, we format the number in its INTERNATIONAL
     * format. If the country calling code is the same as that of the region where
     * the number is from, then NATIONAL formatting will be applied.
     *
     * <p>If the number itself has a country calling code of zero or an otherwise
     * invalid country calling code, then we return the number with no formatting
     * applied.
     *
     * <p>Note this function takes care of the case for calling inside of NANPA and
     * between Russia and Kazakhstan (who share the same country calling code). In
     * those cases, no international prefix is used. For regions which have multiple
     * international prefixes, the number in its INTERNATIONAL format will be
     * returned instead.
     *
     * @param {string} regionCallingFrom the region where the call is being placed.
     * @return {string} the formatted phone number.
     */
    formatOutOfCountryCallingNumber(regionCallingFrom: string): string;
    /**
     * Gets information about a phone number.
     * @returns {IPhoneNumberInfo} An object containing phone number information.
     * @property {number} countryCode The phone's country code.
     * @property {string} countryCodeSource The phone's extension when compared to i18n.phonenumbers.CountryCodeSource.
     * @property {string} extension The phone's extension.
     * @property {boolean} italianLeadingZero The phone's italian leading zero.
     * @property {number} nationalNumber The phone's national number.
     * @property {string} numberType The result from getNumberType() when compared to i18n.phonenumbers.PhoneNumberType.
     * @property {boolean} possible The result from isPossibleNumber().
     * @property {string} rawInput The phone's raw input.
     * @property {string | undefined} regionCode The result from getRegionCodeForNumber().
     * @property {boolean} valid The result from isValidNumber().
     * @property {boolean} validForRegion The result from isValidNumberForRegion().
     */
    getPhoneNumberInfo(): IPhoneNumberInfo;
    /**
     * Gets the type of the parsed phone number as a string.
     * @private
     * @returns {string} The phone number type (e.g., 'MOBILE', 'FIXED_LINE', 'UNKNOWN').
     */
    private getNumberType;
    /**
     * Gets the type of ountry code source the parsed phone number as a string.
     * @private
     * @returns {string} The country code source type (e.g., 'FROM_DEFAULT_COUNTRY', 'FROM_NUMBER_WITHOUT_PLUS_SIGN', 'UNSPECIFIED').
     */
    private getCountryCodeSource;
}