@yext/phonenumber-util 0.1.1 → 0.2.1

package/.github/workflows/pull-request.yml

@@ -0,0 +1,17 @@
+name: Run pull request checks
+
+on:
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test

package/.husky/pre-commit

@@ -3,4 +3,6 @@
 
 npx lint-staged
 npm run format
-npx vitest run --coverage
+npx vitest run --coverage
+npm run make-badges
+npx generate-license-file --input package.json --output THIRD-PARTY-NOTICES --overwrite

package/README.md

@@ -1,5 +1,7 @@
 Utility for extracting and validating phone numbers. Extracts an array of phone numbers from an inputted string, validates that these numbers appear genuine and provide data about those phone numbers.
 
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) ![Statements](https://img.shields.io/badge/statements-100%25-brightgreen.svg?style=flat) ![Branches](https://img.shields.io/badge/branches-100%25-brightgreen.svg?style=flat) ![Functions](https://img.shields.io/badge/functions-100%25-brightgreen.svg?style=flat) ![Lines](https://img.shields.io/badge/lines-100%25-brightgreen.svg?style=flat)
+
 ### Scripts
 
 #### Install dependencies
@@ -70,7 +72,7 @@ import { getPhoneParts } from '@yext/phonenumber-util';
 const validPhoneNumber = '3496333';
 getPhoneParts(validPhoneNumber); // Returns an object, assumed to be US / Canada, region code "1" but no area code can be reliably determined.
 
-const validPhoneNumber = '"+923331234567"';
+const validPhoneNumber = '+923331234567';
 getPhoneParts(validPhoneNumber); // Returns an object, assumed to be Pakistan, region code "92".
 ```
 
@@ -151,3 +153,94 @@ Example for US with no area code provided ("Hey there, my number is 349.9999. Pl
 ```javascript
 [];
 ```
+
+## Geography / Time Functionality
+
+In addition to the above methods, the following methods are also available via a different export.
+
+There is additional functionality exposed as `export`, but the primary expected use case is:
+
+#### findTimeFromAreaCode
+
+Returns an object with geographic and time related information for a given region.
+
+_NOTE:_ This is only applicable for United States and Canada.
+
+```javascript
+import { findTimeFromAreaCode } from '@yext/phonenumber-util/geo';
+findTimeFromAreaCode('928');
+```
+
+Example output for Arizona:
+
+```javascript
+{
+  areaCodeHasMultipleTimezones: false,
+  daylightSavings: true,
+  estimatedTime: true,
+  isQuietHours: false,
+  isTCPAQuietHours: false,
+  localTime24Hour: "15:00:00",
+  localTimeReadable: "3:00:00 PM",
+  region: {
+    code: "US",
+    flag: "🇺🇸",
+    name: "United States"
+  },
+  state: {
+    code: "AZ",
+    name: "Arizona"
+  },
+  stateHasMultipleTimezones: false,
+  timezoneOffset: "-07:00"
+}
+```
+
+```javascript
+import { findTimeFromAreaCode } from '@yext/phonenumber-util/geo';
+findTimeFromAreaCode('250', date); // A date object is optional, defaulting to the current time.
+```
+
+Example output for British Columbia:
+
+```javascript
+{
+  areaCodeHasMultipleTimezones: true,
+  daylightSavings: true,
+  estimatedTime: true,
+  isCRTCQuietHours: false,
+  isQuietHours: false,
+  localTime24Hour: "17:00:00",
+  localTimeReadable: "5:00:00 PM",
+  region: {
+    code: "CA",
+    flag: "🇨🇦",
+    name: "Canada"
+  },
+  state: {
+    code: "BC",
+    name: "British Columbia"
+  },
+  stateHasMultipleTimezones: true,
+  timezoneOffset: "-07:00"
+}
+```
+
+#### findRegionFromRegionCode
+
+```javascript
+import { findRegionFromRegionCode } from '@yext/phonenumber-util/geo';
+findRegionFromRegionCode('47');
+```
+
+Returns the string name of a given region name based on region code provided.
+
+_NOTE:_ This string is provided in English only (example: "Norway" and not the region-specific name "Norge").
+
+```javascript
+{
+  code: "NO",
+  flag: "🇳🇴",
+  name: "Norway"
+}
+```

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@yext/phonenumber-util",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "author": "bajohnson@hearsaycorp.com",
   "license": "BSD-3-Clause",
   "description": "Utility for extracting and validating phone numbers",
   "type": "module",
-  "main": "src/index.js",
+  "main": "src",
+  "exports": {
+    ".": "./src/base.js",
+    "./geo": "./src/geo.js"
+  },
   "types": "src/index.d.ts",
   "sideEffects": false,
   "repository": {
@@ -15,16 +19,19 @@
   "scripts": {
     "lint": "eslint **/*.js **/__tests__/*.js",
     "format": "prettier --write **/*.js **/__tests__/*.js",
-    "test": "vitest",
+    "test": "TZ=America/Los_Angeles vitest",
     "build": "node -e \"console.log('No build script for vanilla JS')\"",
-    "prepare": "husky"
+    "prepare": "husky",
+    "make-badges": "istanbul-badges-readme"
   },
   "devDependencies": {
     "@eslint/js": "^9.7.0",
     "@vitest/coverage-v8": "^2.1.1",
     "eslint": "^9.7.0",
+    "generate-license-file": "^3.5.1",
     "globals": "^15.8.0",
     "husky": "^9.1.5",
+    "istanbul-badges-readme": "^1.9.0",
     "lint-staged": "^15.2.10",
     "prettier": "^3.3.3",
     "vitest": "^2.1.1"

package/src/__tests__/{index.test.js → base.test.js}

@@ -7,7 +7,7 @@ import {
   findNumbersInString,
   findPhoneFormat,
   formatPhoneNumber,
-} from '../index.js';
+} from '../base.js';
 import { describe, it, expect } from 'vitest';
 
 const testNumbers = {
@@ -220,20 +220,29 @@ describe('Phone number pretty formatting', () => {
         format: findPhoneFormat({ regionCode: '57', e164: '+573211234567' }),
       },
       germany: {
-        e164: '+49 170 87654321',
+        e164: '+4917087654321',
         regionCode: '49',
         format: findPhoneFormat({ regionCode: '49', e164: '+4917087654321' }),
       },
       germanyAlt: {
-        e164: '+49 170 8765432',
+        e164: '+491708765432',
         regionCode: '49',
         format: findPhoneFormat({ regionCode: '49', e164: '+491708765432' }),
       },
+      norwayUnexpected: {
+        e164: '+47174087654',
+        regionCode: '47',
+        format: findPhoneFormat({ regionCode: '47', e164: '+471740876543' }),
+      },
     };
 
     expect(formatPhoneNumber(testNumbers.nullCase)).toBe(null);
     expect(formatPhoneNumber(testNumbers.us)).toBe('(310) 349-6200');
     expect(formatPhoneNumber(testNumbers.colombia)).toBe('+57 321 123 4567');
     expect(formatPhoneNumber(testNumbers.germanyAlt)).toBe('+49 17 08765432');
+    // This looks like a Norwegian number, but doesn't match a known format.  In this case, we'll return a sanitized generic format.
+    expect(formatPhoneNumber(testNumbers.norwayUnexpected)).toBe(
+      '+47174087654',
+    );
   });
 });

package/src/__tests__/geo.test.js

@@ -0,0 +1,310 @@
+import {
+  isDaylightSavingTime,
+  formatTimeOffset,
+  offsetTieBreaker,
+  findTimeDetails,
+  findTimeFromAreaCode,
+  findRegionFromRegionCode,
+} from '../geo.js';
+import { describe, it, expect } from 'vitest';
+
+const invalidPhone = {
+  timezoneOffset: null,
+  daylightSavings: null,
+  stateHasMultipleTimezones: null,
+  areaCodeHasMultipleTimezones: null,
+  estimatedTime: false,
+};
+
+const seattlePhone = {
+  areaCodeHasMultipleTimezones: false,
+  daylightSavings: true,
+  estimatedTime: false,
+  isQuietHours: false,
+  isTCPAQuietHours: false,
+  localTime24Hour: '08:00:00',
+  localTimeReadable: '8:00:00 AM',
+  stateHasMultipleTimezones: false,
+  timezoneOffset: '-07:00',
+  state: {
+    name: 'Washington',
+    code: 'WA',
+  },
+  region: {
+    name: 'United States',
+    code: 'US',
+    flag: '🇺🇸',
+  },
+};
+
+const portlandPhone = {
+  areaCodeHasMultipleTimezones: false,
+  daylightSavings: true,
+  estimatedTime: false,
+  isQuietHours: false,
+  isTCPAQuietHours: false,
+  localTime24Hour: '08:00:00',
+  localTimeReadable: '8:00:00 AM',
+  stateHasMultipleTimezones: true,
+  timezoneOffset: '-07:00',
+  state: {
+    name: 'Oregon',
+    code: 'OR',
+  },
+  region: {
+    name: 'United States',
+    code: 'US',
+    flag: '🇺🇸',
+  },
+};
+
+const arizonaPhoneJul = {
+  areaCodeHasMultipleTimezones: false,
+  daylightSavings: true,
+  estimatedTime: true,
+  isQuietHours: false,
+  isTCPAQuietHours: false,
+  localTime24Hour: '09:00:00',
+  localTimeReadable: '9:00:00 AM',
+  stateHasMultipleTimezones: false,
+  timezoneOffset: '-06:00',
+  state: {
+    name: 'Arizona',
+    code: 'AZ',
+  },
+  region: {
+    name: 'United States',
+    code: 'US',
+    flag: '🇺🇸',
+  },
+};
+
+const arizonaPhoneDec = {
+  areaCodeHasMultipleTimezones: false,
+  daylightSavings: false,
+  estimatedTime: false,
+  isQuietHours: false,
+  isTCPAQuietHours: false,
+  localTime24Hour: '09:00:00',
+  localTimeReadable: '9:00:00 AM',
+  stateHasMultipleTimezones: false,
+  timezoneOffset: '-07:00',
+  state: {
+    name: 'Arizona',
+    code: 'AZ',
+  },
+  region: {
+    name: 'United States',
+    code: 'US',
+    flag: '🇺🇸',
+  },
+};
+
+const texasPhone = {
+  areaCodeHasMultipleTimezones: true,
+  daylightSavings: false,
+  estimatedTime: true,
+  isQuietHours: false,
+  isTCPAQuietHours: false,
+  localTime24Hour: '10:00:00',
+  localTimeReadable: '10:00:00 AM',
+  stateHasMultipleTimezones: true,
+  timezoneOffset: '-06:00',
+  state: {
+    name: 'Texas',
+    code: 'TX',
+  },
+  region: {
+    name: 'United States',
+    code: 'US',
+    flag: '🇺🇸',
+  },
+};
+
+const floridaPhone = {
+  areaCodeHasMultipleTimezones: false,
+  daylightSavings: false,
+  estimatedTime: false,
+  isQuietHours: false,
+  isTCPAQuietHours: false,
+  localTime24Hour: '10:00:00',
+  localTimeReadable: '10:00:00 AM',
+  stateHasMultipleTimezones: true,
+  timezoneOffset: '-06:00',
+  state: {
+    name: 'Florida',
+    code: 'FL',
+  },
+  region: {
+    name: 'United States',
+    code: 'US',
+    flag: '🇺🇸',
+  },
+};
+
+const hawaiiPhone = {
+  areaCodeHasMultipleTimezones: false,
+  daylightSavings: false,
+  estimatedTime: false,
+  isQuietHours: true,
+  isTCPAQuietHours: true,
+  localTime24Hour: '06:00:00',
+  localTimeReadable: '6:00:00 AM',
+  stateHasMultipleTimezones: false,
+  timezoneOffset: '-10:00',
+  state: {
+    name: 'Hawaii',
+    code: 'HI',
+  },
+  region: {
+    name: 'United States',
+    code: 'US',
+    flag: '🇺🇸',
+  },
+};
+
+const canadianPhone = {
+  areaCodeHasMultipleTimezones: true,
+  daylightSavings: true,
+  estimatedTime: true,
+  isQuietHours: false,
+  isCRTCQuietHours: false,
+  localTime24Hour: '10:00:00',
+  localTimeReadable: '10:00:00 AM',
+  stateHasMultipleTimezones: true,
+  timezoneOffset: '-05:00',
+  state: {
+    name: 'British Columbia',
+    code: 'BC',
+  },
+  region: {
+    name: 'Canada',
+    code: 'CA',
+    flag: '🇨🇦',
+  },
+};
+
+describe('Daylight Savings', () => {
+  it('should correctly be determined if the time given is or is not within daylight savings time', () => {
+    const daylightSavings = new Date('2024-07-15T12:00:00');
+    const notDaylightSavings = new Date('2024-12-15T12:00:00');
+
+    expect(isDaylightSavingTime(daylightSavings)).toBe(true);
+    expect(isDaylightSavingTime(notDaylightSavings)).toBe(false);
+  });
+});
+
+describe('Formatting time offset', () => {
+  it('return a proper ISO 8601 formatted date string, regardless of hour length', () => {
+    expect(formatTimeOffset('-8:00')).toBe('-08:00');
+    expect(formatTimeOffset('-12:00')).toBe('-12:00');
+    expect(formatTimeOffset('+7:00')).toBe('+07:00');
+    expect(formatTimeOffset('-3:30')).toBe('-03:30');
+  });
+});
+
+describe('Errs on the side of caution, minimizing the given time options to the more narrow', () => {
+  it('Late at night, the available options for morning should be later', () => {
+    expect(
+      offsetTieBreaker(['-8:00', '-7:00'], new Date('2024-07-15T23:00:00')),
+    ).toBe('-7:00');
+  });
+
+  it('Early in day, the available options for morning should be earlier', () => {
+    expect(
+      offsetTieBreaker(['-8:00', '-7:00'], new Date('2024-07-15T08:00:00')),
+    ).toBe('-8:00');
+  });
+});
+
+describe('Provides compliance quiet hours for any given region', () => {
+  it('Returns quiet hours booleans for standard US area', () => {
+    // US regions should have TCPA quiet hours but not CRTC quiet hours.
+    expect(
+      findTimeDetails('-08:00', new Date('2024-07-15T21:00:00'), 'California')
+        .isTCPAQuietHours,
+    ).toEqual(false);
+    expect(
+      findTimeDetails('-08:00', new Date('2024-07-15T22:00:00'), 'California')
+        .isTCPAQuietHours,
+    ).toEqual(true);
+    expect(
+      findTimeDetails('-08:00', new Date('2024-07-15T08:00:00'), 'California')
+        .isTCPAQuietHours,
+    ).toEqual(true);
+    expect(
+      findTimeDetails('-08:00', new Date('2024-07-15T08:00:00'), 'California')
+        .isCRTCQuietHours,
+    ).toEqual(undefined);
+    expect(
+      findTimeDetails('-08:00', new Date('2024-07-15T09:00:00'), 'California')
+        .isTCPAQuietHours,
+    ).toEqual(false);
+
+    // Alberta should have CRTC quiet hours but not TCPA quiet hours.
+    expect(
+      findTimeDetails('-07:00', new Date('2024-07-15T09:00:00'), 'Alberta')
+        .isTCPAQuietHours,
+    ).toEqual(undefined);
+    expect(
+      findTimeDetails('-07:00', new Date('2024-07-20T07:00:00'), 'Alberta')
+        .isCRTCQuietHours,
+    ).toEqual(true);
+
+    // Both should have an abstracted general quiet hours value.
+    expect(
+      findTimeDetails('-08:00', new Date('2024-07-15T08:00:00'), 'California')
+        .isQuietHours,
+    ).toEqual(true);
+    expect(
+      findTimeDetails('-07:00', new Date('2024-07-15T7:00:00'), 'Alberta')
+        .isQuietHours,
+    ).toEqual(true);
+  });
+});
+
+describe('Provides general time information for the given phone number (US and Canada only)', () => {
+  it('Returns general time information for a phone number region', () => {
+    expect(findTimeFromAreaCode(null, new Date('2024-07-15T08:00:00'))).toEqual(
+      invalidPhone,
+    );
+    expect(
+      findTimeFromAreaCode('206', new Date('2024-07-15T08:00:00')),
+    ).toEqual(seattlePhone);
+    expect(
+      findTimeFromAreaCode('503', new Date('2024-07-15T08:00:00')),
+    ).toEqual(portlandPhone);
+    expect(
+      findTimeFromAreaCode('928', new Date('2024-07-15T08:00:00')),
+    ).toEqual(arizonaPhoneJul);
+    expect(
+      findTimeFromAreaCode('928', new Date('2024-12-15T08:00:00')),
+    ).toEqual(arizonaPhoneDec);
+    expect(
+      findTimeFromAreaCode('432', new Date('2024-12-15T08:00:00')),
+    ).toEqual(texasPhone);
+    expect(
+      findTimeFromAreaCode('850', new Date('2024-12-15T08:00:00')),
+    ).toEqual(floridaPhone);
+    expect(
+      findTimeFromAreaCode('808', new Date('2024-12-15T08:00:00')),
+    ).toEqual(hawaiiPhone);
+    expect(
+      findTimeFromAreaCode('236', new Date('2024-07-20T08:00:00')),
+    ).toEqual(canadianPhone);
+  });
+});
+
+describe('Provides region name for a given region code', () => {
+  it('Returns region name', () => {
+    expect(findRegionFromRegionCode(1).name).toEqual('United States, Canada');
+    expect(findRegionFromRegionCode(1, 206).name).toEqual('United States');
+    expect(findRegionFromRegionCode(7).name).toEqual('Russia, Kazakhstan');
+    expect(findRegionFromRegionCode(20).name).toEqual('Egypt');
+    expect(findRegionFromRegionCode(27).name).toEqual('South Africa');
+    expect(findRegionFromRegionCode(30).name).toEqual('Greece');
+    expect(findRegionFromRegionCode(31).name).toEqual('Netherlands');
+    expect(findRegionFromRegionCode(32).name).toEqual('Belgium');
+    expect(findRegionFromRegionCode(33).name).toEqual('France');
+  });
+});

package/src/areaCodeList.js

@@ -21,6 +21,7 @@ export const AREA_CODE_LIST = [
   '223',
   '224',
   '225',
+  '257',
   '228',
   '229',
   '231',
@@ -89,6 +90,7 @@ export const AREA_CODE_LIST = [
   '350',
   '351',
   '352',
+  '357',
   '360',
   '361',
   '363',
@@ -134,17 +136,20 @@ export const AREA_CODE_LIST = [
   '447',
   '448',
   '450',
+  '457',
   '458',
   '463',
   '464',
   '469',
   '470',
+  '471',
   '472',
   '473',
   '475',
   '478',
   '479',
   '480',
+  '483',
   '484',
   '501',
   '502',
@@ -212,6 +217,7 @@ export const AREA_CODE_LIST = [
   '618',
   '619',
   '620',
+  '621',
   '623',
   '626',
   '628',
@@ -241,6 +247,7 @@ export const AREA_CODE_LIST = [
   '671',
   '672',
   '678',
+  '679',
   '680',
   '681',
   '682',
@@ -270,14 +277,17 @@ export const AREA_CODE_LIST = [
   '726',
   '727',
   '728',
+  '729',
   '731',
   '732',
   '734',
   '737',
+  '738',
   '740',
   '742',
   '743',
   '747',
+  '748',
   '754',
   '757',
   '758',
@@ -331,6 +341,7 @@ export const AREA_CODE_LIST = [
   '832',
   '833',
   '835',
+  '837',
   '838',
   '839',
   '840',
@@ -393,6 +404,7 @@ export const AREA_CODE_LIST = [
   '939',
   '940',
   '941',
+  '942',
   '943',
   '945',
   '947',

package/src/{index.js → base.js}

@@ -234,18 +234,6 @@ export const getPhoneParts = (phoneNumber) => {
     phoneParts.e164 = formatPhoneNumberForE164(phoneParts);
     phoneParts.format = findPhoneFormat(phoneParts);
     phoneParts.formattedNumber = formatPhoneNumber(phoneParts);
-
-    // If there are left over x's, the formatting ran into something unexpected.
-    // This may be ok depending on the region and their phone number formats.
-    // But it does mean we don't want to display this number.
-    if (
-      phoneParts.formattedNumber &&
-      phoneParts.formattedNumber.indexOf('x') !== -1
-    ) {
-      // Since `rawNumber` isn't sanitized, we'll use a simple format that we
-      // are assured to be safe.
-      phoneParts.formattedNumber = strippedPhoneNumber;
-    }
   }
 
   return phoneParts;
@@ -353,16 +341,26 @@ export const findPhoneFormat = ({ regionCode, e164 }) => {
  * @param {Object} params - The parameters for formatting the phone number.
  * @param {string} params.format - The desired format for the phone number. Example: `(xxx) xxx-xxxx`.
  * @param {string} params.e164 - The E.164 formatted phone number to format. Example: `+12065551234`.
+ * @param {string} params.regionCode - The region code of the phone number.  Example, the US would be "1".
  * @returns {string|null} The formatted phone number, or null if the E.164 number or format is not provided.
  */
-export const formatPhoneNumber = ({ format, e164 }) => {
+export const formatPhoneNumber = ({ format, e164, regionCode }) => {
   let formattedNumber = '';
 
   if (e164 && format) {
     // Remove the leading '+' and let the format handle it.
-    const strippedPhone = e164.replace(/\D/g, '');
+    const strippedPhone = e164.replace(/\+/g, '');
     let phoneIndex = strippedPhone.length - 1;
 
+    // The US / NANP rarely includes region code prefix when sharing numbers.  Other regions often do, so we'll have a special condition to allow ignoring of the region code for region 1.
+    // For other regions, we'll return the stripped number to safely display the presumed good number that may be in a safe but not-ideal format.
+    if (
+      regionCode !== '1' &&
+      strippedPhone.length !== format.split('x').length - 1
+    ) {
+      return e164;
+    }
+
     // Traverse backward so we can omit country code in some formats (like US).
     for (let i = format.length; i >= 0; i--) {
       if (format[i]) {

package/src/compliance.js

@@ -0,0 +1,31 @@
+export const TCPA_QUIET_HOURS = {
+  start: 8,
+  end: 21,
+};
+
+export const CRTC_QUIET_HOURS = {
+  weekdays: {
+    start: 9,
+    end: 21.5,
+  },
+  weekends: {
+    start: 10,
+    end: 18,
+  },
+};
+
+export const CRTC_STATES = [
+  'Alberta',
+  'British Columbia',
+  'Manitoba',
+  'New Brunswick',
+  'Newfoundland and Labrador',
+  'Northwest Territories',
+  'Nova Scotia',
+  'Nunavut',
+  'Ontario',
+  'Nova Scotia and Prince Edward Island',
+  'Quebec',
+  'Saskatchewan',
+  'Yukon',
+];