npm package: @onereach/phonenumber-interpreter
Description: Google's libphonenumber pre-compiled with the closure compiler
Latest version: 0.0.17

[![npm version][npm-image]][npm-url]
[![downloads][downloads-image]][npm-url]
[![build status][build-image]][build-url]
[![Language grade: JavaScript][lgtm-image]][lgtm-url]
[![Install size][packagephobia-image]][packagephobia-url]

## Basic usage
```js
var PhoneNumber = require( '@onereach/phonenumber-interpreter' );

const phoneNumber = {
  input: '3034567779',
  chosenOption: 'chooseCountry';
  isoCountry: 'us',
  allowedCountries: ['us', 'ca'],
  allowSpecialNumbers: true
};

// chosenOption = 'allowAll' (default) || 'chooseCountry' || 'allowOnlySelected';
// 'isoCountry' is the region code which is taken into account, when the 'chooseCountry' option is chosen;
// 'allowedCountries' is an array which contains allowed country codes & taken into account when the 'allowOnlySelected' option is chosen;
// 'allowSpecialNumbers' is a boolean value which defines whether the toll-free, shared-cost and premium numbers are allowed;

var pn = new PhoneNumber( '3034567779', regionCode = '+1', allowSpecialNumbers = true);
// regionCode & allowSpecialNumbers args are not required. Default values will be assigned, if there are no params;
var pn = new PhoneNumber(phoneNumber);

pn.isValid( );  // -> true
pn.isMobile( ); // -> true
pn.canBeIntlDialled( ); // -> true
pn.getNumber( );                   // -> '+13034567779'
pn.getNumber( 'e164' );            // -> '+13034567779' (default)
pn.getNumber( 'international' );   // -> '+1 303-456-7779'
pn.getNumber( 'national' );        // -> '(303) 456-7779'
pn.getNumber( 'rfc3966' );         // -> 'tel:+1-303-456-7779'
pn.getNumber( 'significant' );     // -> '3034567779'
pn.getRegionCode( );               // -> 'US'
pn.getCountryCode( );              // -> +1

pn.toJSON( );                  // -> json blob, so that:
JSON.stringify( pn, null, 4 ); // -> This:
// {
//     "input": "3034567779",
//     "normalized": "+13034567779"
//     "type": "FIXED_LINE_OR_MOBILE",
//     "canBeInternationallyDialled": true,
//     "possiblyMobile": true,
//     "isSpecial": false,
//     "validatity": {
//       "valid": true,
//       "possible": true,
//       "code": "valid",
//       "message": "Phone number is valid and possible",
//     },
//     "formats": {
//       "e164": "+13034567779",
//       "national": "(303) 456-7779",
//       "international": "+1 303-456-7779",
//       "significant": "3034567779",
//       "rfc3966": "tel:+1-303-456-7779"
//     },
//     "location": {
//       "country": {
//          "name": "United States of America",
//          "iso2": "US",
//          "iso3": "USA",
//          "dialCode": "1"
//        }
//     }
// }
```

### Detect country

When constructed with a phone number on `e164` format (i.e. prefixed with a `+`), awesome-phonenumber will auto-detect the country:

```js
PhoneNumber( '3034567779' ).getRegionCode( ); // -> 'US'
```

## API types

The API consists of the `PhoneNumber` class which sometimes uses *enums*. These are:

### <a name="phone-number-types"></a>Phone number types
```js
'fixed-line' 
'fixed-line-or-mobile'
'mobile'
'pager'
'personal'
'premium-rate'
'shared-cost'
'toll-free'
'uan'
'voip'
'unknown
```

### Phone number possibilities

```js
'is-possible'
'invalid-country-code'
'too-long'
'too-short'
'unknown'
'special-numbers-disallowed'
'country-not-allowed'
'country-not-matched'
```

### Phone number formats

```js
'international'
'national'
'e164'
'rfc3966'
'significant'
```

## API functions

### Library
```js
var PhoneNumber = require( '@onereach/phonenumber-interpreter' );
```

### Country codes

There are conversion functions between the 2-character ISO 3166-1 region codes (e.g. 'SE' for Sweden) and the corresponding country calling codes.

```js
PhoneNumber.getCountryCodeForRegionCode( regionCode );  // -> countryCode
PhoneNumber.getRegionCodeForCountryCode( countryCode ); // -> regionCode
```

#### Example

```js
PhoneNumber.getCountryCodeForRegionCode( 'US' ); // -> +1
PhoneNumber.getRegionCodeForCountryCode( 1 );   // -> 'US'
```

### Supported calling codes

```js
PhoneNumber.getSupportedCallingCodes( ); // -> [ calling codes... ]
```

### Supported region codes

```js
PhoneNumber.getSupportedRegionCodes( ); // -> [ region codes... ]
```

### Phone numbers

An instance of the `PhoneNumber` class will be created even if `PhoneNumber` is called as a function.

```js
var pn = PhoneNumber( number, regionCode );
var pn = new PhoneNumber( number, regionCode, allowSpecialNumbers );
var pn = new PhoneNumber ( phoneNumberObject ); // {input: String, chosenOption: String, isoCountry: String, allowedCountries: [], allowSpecialNumbers: Boolean}
```

PhoneNumber objects can also be created using the `getExample( regionCode[, type ] )` function, see section [Example phone numbers for country](#example) below.

```js
pn.toJSON( );               // -> json blob as seen in "Basic usage" above
pn.isValid( );              // -> Boolean
pn.isPossible( );           // -> Boolean
pn.getType( );              // -> Any of the "Phone number types" defined above
pn.isMobile( );             // -> true if type is 'mobile' or 'fixed-line-or-mobile'
pn.isFixedLine( );          // -> true if type is 'fixed-line' or 'fixed-line-or-mobile'
pn.getNumber( [ format ] ); // -> Formatted number, see "Basic usage" for examples

// Returns the number formatted to how to dial it from another region.
pn.getNumberFrom( fromRegionCode );
```

#### Example

```js
// Calling the American number 3034567779 from Japan:
PhoneNumber( '3034567779' ).getNumberFrom( 'JP' ); // '010 +1+303-456-7779'
```

### <a name="example"></a>Example phone numbers for country

Sometimes you want to display a formatted example phone number for a certain country (and maybe also a certain type of phone number). The `getExample` function is used for this.

```js
PhoneNumber.getExample( regionCode[, phoneNumberType] ); // PhoneNumber object
```

The `phoneNumberType` is any of the [types defined above](#phone-number-types).

#### Example

```js
PhoneNumber.getExample( 'US' ).getNumber( );                      // '+13034567779'
PhoneNumber.getExample( 'SE', 'MOBILE' ).getNumber( );            // '+13034567779'
PhoneNumber.getExample( 'SE', 'MOBILE ).getNumber( 'national' ); // '(303) 456-7779'
```

[npm-image]: https://img.shields.io/npm/v/awesome-phonenumber.svg
[npm-url]: https://npmjs.org/package/awesome-phonenumber
[downloads-image]: https://img.shields.io/npm/dm/awesome-phonenumber.svg
[build-image]: https://img.shields.io/github/workflow/status/grantila/awesome-phonenumber/Master.svg
[build-url]: https://github.com/grantila/awesome-phonenumber/actions?query=workflow%3AMaster
[lgtm-image]: https://img.shields.io/lgtm/grade/javascript/g/grantila/awesome-phonenumber.svg?logo=lgtm&logoWidth=18
[lgtm-url]: https://lgtm.com/projects/g/grantila/awesome-phonenumber/context:javascript
[packagephobia-image]: https://packagephobia.now.sh/badge?p=awesome-phonenumber
[packagephobia-url]: https://packagephobia.now.sh/result?p=awesome-phonenumber