@yext/phonenumber-util 0.1.0 → 0.2.0

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/CODEOWNERS

@@ -1,2 +1,2 @@
 # The following aliases have approval permissions in this repo:
-* @imbrianj @mi4l
+* @imbrianj @mi4l @DerekWW

package/README.md

@@ -47,7 +47,7 @@ Returns a boolean based on whether the passed number is presumed to be valid or
 This checks for region code, number length and validity of region code and area code (where applicable).
 
 ```javascript
-import { isValidPhoneNumber } from 'phonenumber-util';
+import { isValidPhoneNumber } from '@yext/phonenumber-util';
 const validPhoneNumber = '3103496333';
 isValidPhoneNumber(validPhoneNumber); // Returns `true` - "310" is an area code for California
 
@@ -66,11 +66,11 @@ isValidPhoneNumber(invalidIntlNumber); // Returns `false` - "666" is not a valid
 Return an object of relevant phone number parts and information.
 
 ```javascript
-import { getPhoneParts } from 'phonenumber-util';
+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".
 ```
 
@@ -109,7 +109,7 @@ Example for US with full area code provided ("310.349.9999"):
 ```javascript
 {
   areaCode: "310",
-  e164: "+13103103499999",
+  e164: "+13103499999",
   format: "(xxx) xxx-xxxx",
   formattedNumber: "(310) 349-9999",
   href: "tel:+13103499999",
@@ -133,7 +133,7 @@ Example for US with full area code provided ("Hey there, my number is 310.349.99
     index: 24,
     lastIndex: 36,
     areaCode: '310',
-    e164: '+13103103499999',
+    e164: '+13103499999',
     format: '(xxx) xxx-xxxx',
     formattedNumber: '(310) 349-9999',
     href: 'tel:+13103499999',
@@ -151,3 +151,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');
+```
+
+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,12 +1,17 @@
 {
   "name": "@yext/phonenumber-util",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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": {
     "type": "git",
     "url": "git+https://github.com/hearsaycorp/phonenumber-util.git"
@@ -14,7 +19,7 @@
   "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"
   },

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 = {

package/src/__tests__/geo.test.js

@@ -0,0 +1,286 @@
+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 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('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',
@@ -269,14 +276,18 @@ export const AREA_CODE_LIST = [
   '725',
   '726',
   '727',
+  '728',
+  '729',
   '731',
   '732',
   '734',
   '737',
+  '738',
   '740',
   '742',
   '743',
   '747',
+  '748',
   '754',
   '757',
   '758',
@@ -330,6 +341,7 @@ export const AREA_CODE_LIST = [
   '832',
   '833',
   '835',
+  '837',
   '838',
   '839',
   '840',
@@ -392,6 +404,7 @@ export const AREA_CODE_LIST = [
   '939',
   '940',
   '941',
+  '942',
   '943',
   '945',
   '947',

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',
+];

package/src/daylightSavings.js

@@ -0,0 +1,21 @@
+export const STATES_THAT_DONT_HAVE_DAYLIGHT_SAVINGS = [
+  'Arizona',
+  'Hawaii',
+  'British Columbia',
+  'Puerto Rico',
+  'Saskatchewan',
+  'Virgin Islands',
+  'Yukon, Northwest Territories, and Nunavut',
+];
+
+// Arizona does not follow Daylight Savings, but the Navajo Nation does.  The
+// 928 area code spans both Arizone (no DST) and Navajo Nation lands (DST).
+export const AREA_CODES_WITH_MULTIPLE_DAYLIGHT_SAVINGS = {
+  928: 'Arizona',
+  236: 'British Columbia',
+  250: 'British Columbia',
+  257: 'British Columbia',
+  672: 'British Columbia',
+  778: 'British Columbia',
+  306: 'Saskatchewan',
+};

package/src/geo.d.ts

@@ -0,0 +1,31 @@
+export function isDaylightSavingTime(date?: Date): boolean;
+
+export function formatTimeOffset(offset: string): string;
+
+export function offsetTieBreaker(timezones: string[], date: Date): string;
+
+export function findTimeDetails(
+  offset: string,
+  date: Date,
+  state: string
+): {
+  localTimeReadable: string;
+  localTime24Hour: string;
+  isTCPAQuietHours?: boolean;
+  isCRTCQuietHours?: boolean;
+  isQuietHours: boolean;
+};
+
+export function findTimeFromAreaCode(
+  areaCode: string,
+  date?: Date
+): {
+  timezoneOffset: string | null;
+  daylightSavings: boolean | null;
+  stateHasMultipleTimezones: boolean | null;
+  state: string | null;
+  areaCodeHasMultipleTimezones: boolean | null;
+  estimatedTime: boolean;
+};
+
+export function findRegionFromRegionCode(regionCode: string): string | undefined;