@yext/phonenumber-util 0.3.0 → 0.4.1

package/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to NPM
+
+permissions:
+  contents: read
+  id-token: write
+
+on:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    environment: Release
+    name: Publish to NPM
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Run linting
+        run: npm run lint
+
+      - name: Publish to NPM
+        run: npm publish --provenance --access public

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

@@ -1,5 +1,8 @@
 name: Run pull request checks
 
+permissions:
+  contents: read
+
 on:
   pull_request:
     branches: ["main"]
@@ -12,6 +15,9 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
       - run: npm ci
       - run: npm run lint
       - run: npm test

package/.nvmrc

@@ -1 +1 @@
-22
+24

package/CODEOWNERS

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

package/README.md

@@ -39,6 +39,85 @@ npm test
 npx vitest run --coverage
 ```
 
+#### Release Process
+
+This package is automatically published to NPM via GitHub Actions when a new version tag is pushed.
+
+To publish a new version:
+
+1. **Bump the version** using one of these commands:
+
+   ```bash
+   npm run version:patch  # For bug fixes (0.4.0 → 0.4.1)
+   npm run version:minor  # For new features (0.4.0 → 0.5.0)
+   npm run version:major  # For breaking changes (0.4.0 → 1.0.0)
+   ```
+
+2. **Push the changes and tags**:
+
+   ```bash
+   npm run release
+   ```
+
+   This will run tests, linting, and push both commits and tags to GitHub.
+
+3. **GitHub Actions will automatically**:
+   - Run tests and linting
+   - Publish to NPM with provenance
+   - Use OIDC authentication for secure publishing
+
+### ⚠️ **SECURITY WARNING**
+
+**The `rawNumber` field contains UNSANITIZED user input and poses XSS risks if displayed in web applications.**
+
+#### 🚨 **NEVER do this:**
+
+```javascript
+// DANGEROUS - Direct HTML insertion
+document.getElementById('phone').innerHTML = result.rawNumber;
+
+// DANGEROUS - Template literal insertion
+element.innerHTML = `Call ${result.rawNumber}`;
+
+// DANGEROUS - React without escaping
+return <div>{result.rawNumber}</div>;
+```
+
+#### ✅ **Safe approaches:**
+
+```javascript
+// SAFE - Use formatted version for display
+document.getElementById('phone').textContent = result.formattedNumber;
+
+// SAFE - Use rawNumber for string replacement/processing
+const updatedText = originalText.replace(
+  result.rawNumber,
+  result.formattedNumber,
+);
+
+// SAFE - Escape before HTML insertion
+document.getElementById('phone').innerHTML = escapeHtml(result.rawNumber);
+
+// SAFE - React with proper text content
+return <div>{result.formattedNumber}</div>;
+```
+
+#### **Why `rawNumber` exists:**
+
+The `rawNumber` field enables powerful text replacement functionality:
+
+```javascript
+const text = 'Call me at (310) 555-1234 anytime!';
+const numbers = findNumbersInString(text);
+let updatedText = text;
+
+numbers.forEach((phone) => {
+  // Replace original with formatted version
+  updatedText = updatedText.replace(phone.rawNumber, phone.formattedNumber);
+});
+// Result: "Call me at (310) 555-1234 anytime!" → formatted consistently
+```
+
 ### Warning
 
 The returned object will include a `rawNumber` value. This value is the return of the exact value passed to the function. No sanitization occurs with this value. If you reference this number, ensure you sanitize it _BEFORE_ passing to this function.

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@yext/phonenumber-util",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "author": "bajohnson@hearsaycorp.com",
   "license": "BSD-3-Clause",
   "description": "Utility for extracting and validating phone numbers",
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "main": "src",
   "exports": {
@@ -22,19 +25,23 @@
     "test": "TZ=America/Los_Angeles vitest",
     "build": "node -e \"console.log('No build script for vanilla JS')\"",
     "prepare": "husky",
-    "make-badges": "istanbul-badges-readme"
+    "make-badges": "istanbul-badges-readme",
+    "version:patch": "npm version patch",
+    "version:minor": "npm version minor",
+    "version:major": "npm version major",
+    "release": "npm run test && npm run lint && git push && git push --tags"
   },
   "devDependencies": {
-    "@eslint/js": "^9.28.0",
-    "@vitest/coverage-v8": "^3.2.3",
-    "eslint": "^9.28.0",
-    "generate-license-file": "4.0.0",
-    "globals": "^16.2.0",
+    "@eslint/js": "^9.38.0",
+    "@vitest/coverage-v8": "^4.0.2",
+    "eslint": "^9.38.0",
+    "generate-license-file": "^4.1.0",
+    "globals": "^16.4.0",
     "husky": "^9.1.7",
     "istanbul-badges-readme": "^1.9.0",
-    "lint-staged": "^16.1.0",
-    "prettier": "^3.5.3",
-    "vitest": "^3.2.3"
+    "lint-staged": "^16.2.6",
+    "prettier": "^3.6.2",
+    "vitest": "^4.0.2"
   },
   "eslintConfig": {},
   "lint-staged": {

package/src/__tests__/base.test.js

@@ -433,6 +433,11 @@ describe('Phone number pretty formatting', () => {
         regionCode: '47',
         format: findPhoneFormat({ regionCode: '47', e164: '+471740876543' }),
       },
+      egyptStringFormat: {
+        e164: '+201012345678',
+        regionCode: '20',
+        format: findPhoneFormat({ regionCode: '20', e164: '+201012345678' }),
+      },
     };
 
     expect(formatPhoneNumber(testNumbers.nullCase)).toBe(null);
@@ -443,5 +448,68 @@ describe('Phone number pretty formatting', () => {
     expect(formatPhoneNumber(testNumbers.norwayUnexpected)).toBe(
       '+47174087654',
     );
+    // Egypt has a string format (not array), this tests the else if (formatRaw)
+    expect(formatPhoneNumber(testNumbers.egyptStringFormat)).toBe(
+      '+20 101 234 5678',
+    );
+  });
+});
+
+describe('E.164 formatting edge cases', () => {
+  describe('formatPhoneNumberForE164 with missing required fields', () => {
+    it('should format US numbers with separate area code correctly', () => {
+      expect(
+        formatPhoneNumberForE164({
+          regionCode: '1',
+          areaCode: '310',
+          localNumber: '3496200',
+        }),
+      ).toBe('+13103496200');
+    });
+
+    it('should format international numbers without area code correctly', () => {
+      expect(
+        formatPhoneNumberForE164({
+          regionCode: '44',
+          areaCode: null,
+          localNumber: '2079460958',
+        }),
+      ).toBe('+442079460958');
+    });
+  });
+
+  describe('International number parsing with unknown region codes', () => {
+    it('should handle international numbers that do not match any known region code in the loop', () => {
+      // Test a number with + prefix and valid length but an unrecognized region code
+      // The parser should try all region code lengths (1, 2, 3 digits) but find no match in PHONE_FORMATS
+      const phoneParts = getPhoneParts('+00012345678');
+      // Should not have regionCode since +000, +00, or +0 are not valid region codes
+      expect(phoneParts.regionCode).toBeNull();
+      expect(phoneParts.localNumber).toBeNull();
+    });
+
+    it('should handle numbers that skip the international parsing else-if block entirely', () => {
+      // Test numbers with + prefix that exceed the maximum length for international number parsing
+      // The parser checks strippedPhoneNumber.length <= 14, so 16 chars (15 digits + plus sign) is too long
+      // This ensures the else-if branch is not entered, leaving regionCode and localNumber as null
+      const longNumber = getPhoneParts('+123456789012345'); // 15 digits, 16 chars total
+      expect(longNumber.regionCode).toBeNull();
+      expect(longNumber.localNumber).toBeNull();
+    });
+  });
+
+  describe('findNumbersInString with multiple phone numbers', () => {
+    it('should extract multiple valid phone numbers from a single string', () => {
+      const text = 'Call me at +1 (310) 349-6200 or +44 20 7946 0958.';
+      const results = findNumbersInString(text);
+      expect(results.length).toBe(2);
+      expect(results[0].e164).toBe('+13103496200');
+      expect(results[1].e164).toBe('+442079460958');
+    });
+
+    it('should return an empty array when no valid phone numbers are present', () => {
+      const text = 'No phone numbers here!';
+      expect(findNumbersInString(text)).toEqual([]);
+    });
   });
 });

package/src/__tests__/geo.test.js

@@ -5,7 +5,12 @@ import {
   findTimeDetails,
   findTimeFromAreaCode,
   findRegionFromRegionCode,
+  findAllNumbersInfoInString,
 } from '../geo.js';
+import { AREA_CODE_LIST } from '../areaCodeList.js';
+import { AREA_CODES, REGION_CODES } from '../phoneCodes.js';
+import { PHONE_FORMATS } from '../phoneFormats.js';
+
 import { describe, it, expect } from 'vitest';
 
 const invalidPhone = {
@@ -184,6 +189,268 @@ const canadianPhone = {
   },
 };
 
+const longStringWithNumbers = `
+It was a cold, rainy evening when Sophie stumbled upon the weathered journal in the attic of her late grandfather's home. The journal's leather cover was cracked, its pages yellowed with time. Inside, however, was a web of mystery that would unravel Sophie's life over the coming weeks. The most intriguing part? Each entry ended with a phone number-a mix of US, Canadian, and international numbers-written in her grandfather's meticulous hand.
+The first number, 617-555-0134, was scribbled below a cryptic entry about "the Boston job." Sophie's heart raced as she dialed the Massachusetts number. A gruff voice answered on the third ring. "This is Detective Harris. Who's calling?" Sophie's voice trembled as she explained the journal. Harris's tone softened. "If that journal belonged to Robert Fields, you need to be careful. He was involved in some deep, dangerous stuff."
+Sophie wasn't deterred. Instead, her curiosity grew. The next number was Canadian: +1-416-555-2468, written beneath an entry about a maple leaf emblem. The line connected to a cafe in Toronto. A barista named Elena answered and, after a moment of hesitation, said, "I remember Mr. Fields. He came in every Tuesday for a year. Always ordered the same thing-a double espresso-and left me an envelope every time."
+Sophie's pulse quickened as Elena offered to send a picture of one of the envelopes. Within an hour, Sophie received an email with an image showing a wax seal bearing an intricate insignia. Below it, another phone number was scrawled: +44 20 7946 0958, a UK number. Without hesitation, Sophie dialed.
+"Briggs Antiquities, London," a posh voice answered. Sophie explained her discovery, and the receptionist transferred her to a man named Charles. "Ah, Robert Fields," Charles said wistfully. "He was a loyal patron, always seeking artifacts tied to the Knights Templar. If you have his journal, you might find yourself part of a larger puzzle."
+The puzzle, it seemed, spanned the globe. Another entry mentioned "the desert winds" and was linked to a number in Dubai: +971 4 555 1234. The number connected her to a man named Tariq, who revealed that Robert had been searching for a rare relic-a golden compass said to point to treasure. Tariq's description matched the insignia Sophie had seen on the envelope.
+"But why so many numbers?" Sophie muttered to herself. Each call led to another layer of intrigue. A South African number, +27 21 555 6789, took her to Cape Town, where a historian named Amara spoke of Robert's fascination with lost languages. "He believed there was a cipher hidden in ancient texts. If he left you his journal, you're meant to decode it."
+Another number, +55-11-5555-1234 in Brazil, led her to a tech entrepreneur in Sao Paulo who had once helped Robert crack encrypted files. "I thought he was crazy," the entrepreneur said. "But now? Maybe he was onto something."
+Sophie pieced together her grandfather's movements over decades. Each phone number represented a person who had played a role in his quest. An Australian number, +61 2 5551 2345, introduced her to a diver named Liam who had helped Robert retrieve artifacts from a shipwreck. "He was fearless," Liam recalled. "And determined."
+Back in the US, a Seattle number, 206-555-7890, connected Sophie to a lawyer who held a key to Robert's safety deposit box. Inside was a single piece of parchment and yet another number: +49 30 555 4321, this time in Germany. The number belonged to a librarian in Berlin who recognized the parchment as part of a centuries-old map.
+The map, Sophie realized, was the heart of the mystery. Each phone number had been a breadcrumb leading her closer to understanding her grandfather's obsession. The final number, scribbled in bold at the back of the journal, was unlike the others. It was an Argentinian number: +54 11 5555 6789. Sophie hesitated, her finger hovering over the dial button. She took a deep breath and called.
+"Sophie Fields," a voice answered before she could speak. "We've been expecting you."
+"Who is this?" she demanded, her voice trembling.
+"A friend of your grandfather," the voice replied. "He knew you would finish what he started."
+The call ended abruptly, leaving Sophie with more questions than answers. But as she stared at the journal, now marked with notes and connections, she felt a sense of purpose. Each phone number was a clue, each person a piece of a puzzle her grandfather had trusted her to solve.
+And Sophie was determined to finish what Robert Fields had begun.`;
+const longStringOutput = [
+  {
+    index: 464,
+    lastIndex: 476,
+    areaCode: '617',
+    e164: '+16175550134',
+    format: '(xxx) xxx-xxxx',
+    formattedNumber: '(617) 555-0134',
+    href: 'tel:+16175550134',
+    localNumber: '5550134',
+    rawNumber: '617-555-0134',
+    regionCode: '1',
+    timezoneOffset: '-04:00',
+    stateHasMultipleTimezones: false,
+    areaCodeHasMultipleTimezones: false,
+    daylightSavings: true,
+    estimatedTime: false,
+    state: { name: 'Massachusetts', code: 'MA' },
+    region: { name: 'United States', code: 'US', flag: '🇺🇸' },
+    localTimeReadable: '11:00:00 AM',
+    localTime24Hour: '11:00:00',
+    isTCPAQuietHours: false,
+    isQuietHours: false,
+  },
+  {
+    index: 961,
+    lastIndex: 976,
+    areaCode: '416',
+    e164: '+14165552468',
+    format: '(xxx) xxx-xxxx',
+    formattedNumber: '(416) 555-2468',
+    href: 'tel:+14165552468',
+    localNumber: '5552468',
+    rawNumber: '+1-416-555-2468',
+    regionCode: '1',
+    timezoneOffset: '-04:00',
+    stateHasMultipleTimezones: true,
+    areaCodeHasMultipleTimezones: false,
+    daylightSavings: true,
+    estimatedTime: false,
+    state: { name: 'Ontario', code: 'ON' },
+    region: { name: 'Canada', code: 'CA', flag: '🇨🇦' },
+    localTimeReadable: '11:00:00 AM',
+    localTime24Hour: '11:00:00',
+    isCRTCQuietHours: false,
+    isQuietHours: false,
+  },
+  {
+    index: 1524,
+    lastIndex: 1540,
+    areaCode: null,
+    e164: '+442079460958',
+    format: '+xx xxxx xxxxxx',
+    formattedNumber: '+44 2079 460958',
+    href: 'tel:+442079460958',
+    localNumber: '2079460958',
+    rawNumber: '+44 20 7946 0958',
+    regionCode: '44',
+    name: 'United Kingdom',
+    code: 'GB',
+    flag: '🇬🇧',
+  },
+  {
+    index: 2056,
+    lastIndex: 2071,
+    areaCode: null,
+    e164: '+97145551234',
+    format: '+xxx xx xxx xxxx',
+    formattedNumber: '+97145551234',
+    href: 'tel:+97145551234',
+    localNumber: '45551234',
+    rawNumber: '+971 4 555 1234',
+    regionCode: '971',
+    name: 'United Arab Emirates',
+    code: 'AE',
+    flag: '🇦🇪',
+  },
+  {
+    index: 2422,
+    lastIndex: 2437,
+    areaCode: null,
+    e164: '+27215556789',
+    format: '+xx xx xxx xxxx',
+    formattedNumber: '+27 21 555 6789',
+    href: 'tel:+27215556789',
+    localNumber: '215556789',
+    rawNumber: '+27 21 555 6789',
+    regionCode: '27',
+    name: 'South Africa',
+    code: 'ZA',
+    flag: '🇿🇦',
+  },
+  {
+    index: 2672,
+    lastIndex: 2688,
+    areaCode: null,
+    e164: '+551155551234',
+    format: '+xx xx xxxx-xxxx',
+    formattedNumber: '+55 11 5555-1234',
+    href: 'tel:+551155551234',
+    localNumber: '1155551234',
+    rawNumber: '+55-11-5555-1234',
+    regionCode: '55',
+    name: 'Brazil',
+    code: 'BR',
+    flag: '🇧🇷',
+  },
+  {
+    index: 3045,
+    lastIndex: 3060,
+    areaCode: null,
+    e164: '+61255512345',
+    format: '+xx xxx xxx xxx',
+    formattedNumber: '+61 255 512 345',
+    href: 'tel:+61255512345',
+    localNumber: '255512345',
+    rawNumber: '+61 2 5551 2345',
+    regionCode: '61',
+    name: 'Australia',
+    code: 'AU',
+    flag: '🇦🇺',
+  },
+  {
+    index: 3244,
+    lastIndex: 3256,
+    areaCode: '206',
+    e164: '+12065557890',
+    format: '(xxx) xxx-xxxx',
+    formattedNumber: '(206) 555-7890',
+    href: 'tel:+12065557890',
+    localNumber: '5557890',
+    rawNumber: '206-555-7890',
+    regionCode: '1',
+    timezoneOffset: '-07:00',
+    stateHasMultipleTimezones: false,
+    areaCodeHasMultipleTimezones: false,
+    daylightSavings: true,
+    estimatedTime: false,
+    state: { name: 'Washington', code: 'WA' },
+    region: { name: 'United States', code: 'US', flag: '🇺🇸' },
+    localTimeReadable: '8:00:00 AM',
+    localTime24Hour: '08:00:00',
+    isTCPAQuietHours: false,
+    isQuietHours: false,
+  },
+  {
+    index: 3397,
+    lastIndex: 3412,
+    areaCode: null,
+    e164: '+49305554321',
+    format: '+xx xx xxxxxxx',
+    formattedNumber: '+49 30 5554321',
+    href: 'tel:+49305554321',
+    localNumber: '305554321',
+    rawNumber: '+49 30 555 4321',
+    regionCode: '49',
+    name: 'Germany',
+    code: 'DE',
+    flag: '🇩🇪',
+  },
+  {
+    index: 3820,
+    lastIndex: 3836,
+    areaCode: null,
+    e164: '+541155556789',
+    format: '+xx xxx-xxx-xxxx',
+    formattedNumber: '+54 115-555-6789',
+    href: 'tel:+541155556789',
+    localNumber: '1155556789',
+    rawNumber: '+54 11 5555 6789',
+    regionCode: '54',
+    name: 'Argentina',
+    code: 'AR',
+    flag: '🇦🇷',
+  },
+];
+
+describe('Validate that every allow-list area code has matching geo and time info', () => {
+  it('should ensure every area code in AREA_CODE_LIST has a matching region code in AREA_CODES', () => {
+    AREA_CODE_LIST.forEach((areaCode) => {
+      const areaCodeInfo = AREA_CODES[areaCode];
+
+      if (!areaCodeInfo) {
+        console.warn(
+          `Area code ${areaCode} does not have a matching AREA_CODES entry.`,
+        );
+      }
+
+      expect(areaCodeInfo).toBeDefined();
+      expect(areaCodeInfo).not.toBeNull();
+    });
+
+    Object.keys(AREA_CODES).forEach((areaCode) => {
+      const exists = AREA_CODE_LIST.has(areaCode);
+
+      if (!exists) {
+        console.warn(
+          `Area code ${areaCode} does not have a matching AREA_CODE_LIST entry.`,
+        );
+      }
+
+      expect(exists).toBe(true);
+    });
+  });
+
+  it('should ensure every area code in AREA_CODE_LIST has a matching timezone', () => {
+    AREA_CODE_LIST.forEach((areaCode) => {
+      const timezone = findTimeFromAreaCode(
+        areaCode,
+        new Date('2024-07-15T08:00:00'),
+      );
+      expect(timezone).toBeDefined();
+      expect(timezone).not.toBeNull();
+    });
+  });
+
+  it('should ensure every region code in REGION_CODES has a matching phone format', () => {
+    Object.keys(REGION_CODES).forEach((regionCode) => {
+      const phoneFormat = PHONE_FORMATS[regionCode];
+
+      if (!phoneFormat) {
+        console.warn(
+          `Region code ${regionCode} does not have a matching PHONE_FORMATS entry.`,
+        );
+      }
+
+      expect(phoneFormat).toBeDefined();
+      expect(phoneFormat).not.toBeNull();
+    });
+
+    Object.keys(PHONE_FORMATS).forEach((regionCode) => {
+      const regionInfo = REGION_CODES[regionCode];
+
+      if (!regionInfo) {
+        console.warn(
+          `Region code ${regionCode} does not have a matching REGION_CODES entry.`,
+        );
+      }
+
+      expect(regionInfo).toBeDefined();
+      expect(regionInfo).not.toBeNull();
+    });
+  });
+});
+
 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');
@@ -308,3 +575,37 @@ describe('Provides region name for a given region code', () => {
     expect(findRegionFromRegionCode(33).name).toEqual('France');
   });
 });
+
+describe('Extracts all useful phone info from a long string of text', () => {
+  it('Returns all phone numbers and geo data', () => {
+    const numbers = findAllNumbersInfoInString(
+      longStringWithNumbers,
+      new Date('2024-07-20T08:00:00'),
+    );
+
+    expect(numbers).toEqual(longStringOutput);
+  });
+});
+
+describe('Area code region information mapping', () => {
+  it('should include region details when area code has region information', () => {
+    const result = findTimeFromAreaCode('206', new Date('2024-07-15T08:00:00'));
+
+    expect(result.region).toBeDefined();
+    expect(result.region.name).toBe('United States');
+    expect(result.region.code).toBe('US');
+    expect(result.state).toBeDefined();
+    expect(result.state.name).toBe('Washington');
+    expect(result.state.code).toBe('WA');
+  });
+
+  it('should include region flag for area codes with region property', () => {
+    // Test with Puerto Rico which has a region property with flag
+    const result = findTimeFromAreaCode('787', new Date('2024-07-15T08:00:00'));
+
+    expect(result.region).toBeDefined();
+    expect(result.region.flag).toBeDefined();
+    expect(result.region.name).toBe('Puerto Rico');
+    expect(result.region.code).toBe('PR');
+  });
+});

package/src/areaCodeList.js

@@ -2,7 +2,7 @@
 // If a new area code is added to this array, it must also be added to the AREA_CODES object in phoneCodes.js.
 // If a new area code is added and covers a region that has multiple timezones, it will need to be added to the STATES_WITH_MULTIPLE_TIMEZONES object in timezones.js.
 // If a new area code is added and covers a region that has portions that do and portions that do not adhere to daylight savings time, it will need to be added to the AREA_CODES_WITH_MULTIPLE_DAYLIGHT_SAVINGS object in daylightSavings.js.
-export const AREA_CODE_LIST = [
+export const AREA_CODE_LIST = new Set([
   '201',
   '202',
   '203',
@@ -38,6 +38,7 @@ export const AREA_CODE_LIST = [
   '242',
   '246',
   '248',
+  '249',
   '250',
   '251',
   '252',
@@ -46,6 +47,7 @@ export const AREA_CODE_LIST = [
   '256',
   '260',
   '262',
+  '263',
   '264',
   '267',
   '268',
@@ -98,15 +100,18 @@ export const AREA_CODE_LIST = [
   '350',
   '351',
   '352',
+  '354',
   '357',
   '360',
   '361',
   '363',
   '364',
   '365',
+  '367',
   '368',
   '369',
   '380',
+  '382',
   '385',
   '386',
   '387',
@@ -150,11 +155,13 @@ export const AREA_CODE_LIST = [
   '458',
   '463',
   '464',
+  '468',
   '469',
   '470',
   '471',
   '472',
   '473',
+  '474',
   '475',
   '478',
   '479',
@@ -236,6 +243,7 @@ export const AREA_CODE_LIST = [
   '580',
   '581',
   '582',
+  '584',
   '585',
   '586',
   '587',
@@ -301,6 +309,7 @@ export const AREA_CODE_LIST = [
   '680',
   '681',
   '682',
+  '683',
   '684',
   '686',
   '688',
@@ -343,6 +352,7 @@ export const AREA_CODE_LIST = [
   '743',
   '747',
   '748',
+  '753',
   '754',
   '757',
   '758',
@@ -494,4 +504,4 @@ export const AREA_CODE_LIST = [
   '985',
   '986',
   '989',
-];
+]);

package/src/base.d.ts

@@ -14,6 +14,11 @@ export interface PhoneValidationResult {
   isValid: boolean;
 }
 
+export interface PhoneNumberInText extends PhoneParts {
+  index: number;
+  lastIndex: number;
+}
+
 export function formatPhoneNumberForE164(
   phoneParts: Pick<PhoneParts, 'regionCode' | 'areaCode' | 'localNumber'>
 ): string | null;
@@ -22,26 +27,23 @@ export function formatPhoneNumberLink(
   phoneParts: Pick<PhoneParts, 'regionCode' | 'areaCode' | 'localNumber'>
 ): string | null;
 
-export function isValidPhoneNumber(phoneNumber: string): boolean;
+export function isValidPhoneNumber(phoneNumber?: string | null | undefined): boolean;
 
-export function isValidPhoneNumberWithDescription(phoneNumber: string): PhoneValidationResult;
+export function isValidPhoneNumberWithDescription(phoneNumber?: string | null | undefined): PhoneValidationResult;
 
-export function getPhoneParts(phoneNumber?: string | null): PhoneParts;
+export function getPhoneParts(phoneNumber?: string | null | undefined): PhoneParts;
 
-export function sanitizeRawNumber(phoneNumber: string): string;
+export function sanitizeRawNumber(phoneNumber?: string | null | undefined): string;
 
-export function findNumbersInString(text: string): Array<{
-  index: number;
-  lastIndex: number;
-} & PhoneParts>;
+export function findNumbersInString(text?: string | null | undefined): PhoneNumberInText[];
 
 export function findPhoneFormat(params: {
-  regionCode: string;
-  e164: string;
+  regionCode?: string | null;
+  e164?: string | null;
 }): string;
 
 export function formatPhoneNumber(params: {
-  format: string;
-  e164: string;
-  regionCode: string;
+  format?: string | null;
+  e164?: string | null;
+  regionCode?: string | null;
 }): string | null;

package/src/base.js

@@ -225,7 +225,7 @@ export const getPhoneParts = (phoneNumber) => {
     // If no region code is provided, assume US with the format 3109309000 after being stripped of non-numeric values.
     // We'll try and derive the area code by looking it up against the known area codes.
     else if (strippedPhoneNumber.length === US_PHONE_LENGTH) {
-      if (AREA_CODE_LIST.indexOf(strippedPhoneNumber.substring(0, 3)) !== -1) {
+      if (AREA_CODE_LIST.has(strippedPhoneNumber.substring(0, 3))) {
         phoneParts.regionCode = '1';
         phoneParts.areaCode = strippedPhoneNumber.substring(0, 3);
         phoneParts.localNumber = strippedPhoneNumber.substring(3);
@@ -264,7 +264,7 @@ export const getPhoneParts = (phoneNumber) => {
   if (
     phoneParts.regionCode === '1' &&
     phoneParts.areaCode &&
-    AREA_CODE_LIST.indexOf(phoneParts.areaCode) === -1
+    !AREA_CODE_LIST.has(phoneParts.areaCode)
   ) {
     phoneParts.areaCode = null;
   }
@@ -322,8 +322,8 @@ export const findNumbersInString = (text) => {
     if (
       number.replace(new RegExp(`[${VALID_PUNCTUATION}]`, 'g'), '').length >= 6
     ) {
-      const index = text.indexOf(number);
-      const lastIndex = index + number.length;
+      const index = match.index;
+      const lastIndex = regex.lastIndex;
       const phoneParts = getPhoneParts(number);
 
       // Presumed phone numbers may be invalidated by omission of formattedNumber from getPhoneParts.
@@ -362,15 +362,16 @@ export const findPhoneFormat = ({ regionCode, e164 }) => {
   if (formatRaw && numberLength) {
     // The PHONE_FORMATS will have arrays for regions with inconsistent number lengths / formats.
     if (Array.isArray(formatRaw)) {
-      formatRaw.forEach((value) => {
+      for (const value of formatRaw) {
         const templateLength = value.split('x').length - 1;
         if (numberLength === templateLength) {
           format = value;
+          break;
         }
-      });
+      }
     }
     // Some region (such as the US) will have a consistent format, so we expect a string.
-    else if (formatRaw) {
+    else {
       format = formatRaw;
     }
   }

package/src/daylightSavings.js

@@ -18,4 +18,6 @@ export const AREA_CODES_WITH_MULTIPLE_DAYLIGHT_SAVINGS = {
   672: 'British Columbia',
   778: 'British Columbia',
   306: 'Saskatchewan',
+  474: 'Saskatchewan',
+  639: 'Saskatchewan',
 };

package/src/geo.d.ts

@@ -1,40 +1,86 @@
-export function isDaylightSavingTime(date?: Date): boolean;
-
-export function formatTimeOffset(offset: string): string;
+export interface RegionInfo {
+  name: string;
+  code: string;
+  flag: string;
+}
 
-export function offsetTieBreaker(timezones: string[], date: Date): string;
+export interface StateInfo {
+  name: string;
+  code: string;
+}
 
-export function findTimeDetails(
-  offset: string,
-  date: Date,
-  state: string
-): {
+export interface TimeDetails {
   localTimeReadable: string;
   localTime24Hour: string;
   isTCPAQuietHours?: boolean;
   isCRTCQuietHours?: boolean;
   isQuietHours: boolean;
-};
+}
 
-export function findTimeFromAreaCode(
-  areaCode: string,
-  date?: Date
-): {
+export interface AreaCodeTimeInfo {
   timezoneOffset: string | null;
   daylightSavings: boolean | null;
   stateHasMultipleTimezones: boolean | null;
-  state: { name: string; code: string } | null;
-  region?: { name: string; code: string; flag: string };
   areaCodeHasMultipleTimezones: boolean | null;
   estimatedTime: boolean;
+  state?: StateInfo;
+  region?: RegionInfo;
+  localTimeReadable?: string;
   localTime24Hour?: string;
+  isTCPAQuietHours?: boolean;
+  isCRTCQuietHours?: boolean;
+  isQuietHours?: boolean;
+}
+
+export interface PhoneNumberWithGeoInfo {
+  index: number;
+  lastIndex: number;
+  areaCode: string | null;
+  e164: string | null;
+  format: string | null;
+  formattedNumber: string | null;
+  href: string | null;
+  localNumber: string | null;
+  rawNumber: string | undefined; // Can be undefined, matches base PhoneParts
+  regionCode: string | null;
+  // Geo-specific fields (all present in actual return)
+  timezoneOffset?: string | null;
+  daylightSavings?: boolean | null;
+  stateHasMultipleTimezones?: boolean | null;
+  areaCodeHasMultipleTimezones?: boolean | null;
+  estimatedTime?: boolean;
+  state?: StateInfo | null;
+  region?: RegionInfo | null;
   localTimeReadable?: string;
+  localTime24Hour?: string;
   isTCPAQuietHours?: boolean;
   isCRTCQuietHours?: boolean;
   isQuietHours?: boolean;
-};
+}
+
+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,
+  stateName: string
+): TimeDetails;
+
+export function findTimeFromAreaCode(
+  areaCode: string,
+  date?: Date
+): AreaCodeTimeInfo;
 
 export function findRegionFromRegionCode(
   regionCode: string | number,
   areaCode?: string
-): { name: string; code: string; flag: string } | undefined;
+): RegionInfo | null;
+
+export function findAllNumbersInfoInString(
+  text: string,
+  date?: Date
+): PhoneNumberWithGeoInfo[];

package/src/geo.js

@@ -12,6 +12,7 @@ import {
   STATES_THAT_DONT_HAVE_DAYLIGHT_SAVINGS,
   AREA_CODES_WITH_MULTIPLE_DAYLIGHT_SAVINGS,
 } from './daylightSavings.js';
+import { findNumbersInString } from './base.js';
 
 /**
  * Determines whether the given date is within daylight saving time for the local time zone.
@@ -154,13 +155,11 @@ export function findTimeFromAreaCode(areaCode, date = new Date()) {
       code: AREA_CODES[areaCode].code,
     };
 
-    if (AREA_CODES[areaCode].region) {
-      returnTime.region = {
-        name: AREA_CODES[areaCode].region.name,
-        code: AREA_CODES[areaCode].region.code,
-        flag: AREA_CODES[areaCode].region.flag,
-      };
-    }
+    returnTime.region = {
+      name: AREA_CODES[areaCode].region.name,
+      code: AREA_CODES[areaCode].region.code,
+      flag: AREA_CODES[areaCode].region.flag,
+    };
   }
 
   if (!stateName || !STATE_TIMEZONES[stateName]) {
@@ -256,3 +255,22 @@ export function findRegionFromRegionCode(regionCode, areaCode) {
 
   return regionInfo;
 }
+
+/**
+ * Finds all phone numbers in a string and adds in geographical and/or time zone information to that object.
+ *
+ * @param {string} text - The text to search for phone numbers.
+ * @param {Date} [date=new Date()] - The date to use for determining time zone information. Defaults to the current date.
+ * @returns {Array<object>} An array of objects, where each object represents a found phone number
+ * and includes details from `findNumbersInString` as well as geographical and/or time zone information.
+ */
+export function findAllNumbersInfoInString(text, date = new Date()) {
+  const numbers = findNumbersInString(text);
+
+  return numbers.map((item) => {
+    const geo = item.areaCode
+      ? findTimeFromAreaCode(item.areaCode, date)
+      : findRegionFromRegionCode(item.regionCode);
+    return { ...item, ...geo };
+  });
+}

package/src/phoneCodes.js

@@ -568,6 +568,7 @@ export const AREA_CODES = {
   778: { name: 'British Columbia', code: 'BC', region: CANADA },
   204: { name: 'Manitoba', code: 'MB', region: CANADA },
   431: { name: 'Manitoba', code: 'MB', region: CANADA },
+  584: { name: 'Manitoba', code: 'MB', region: CANADA },
   506: { name: 'New Brunswick', code: 'NB', region: CANADA },
   709: { name: 'Newfoundland and Labrador', code: 'NL', region: CANADA },
   782: {
@@ -581,30 +582,39 @@ export const AREA_CODES = {
     region: CANADA,
   },
   226: { name: 'Ontario', code: 'ON', region: CANADA },
+  249: { name: 'Ontario', code: 'ON', region: CANADA },
   289: { name: 'Ontario', code: 'ON', region: CANADA },
   343: { name: 'Ontario', code: 'ON', region: CANADA },
   365: { name: 'Ontario', code: 'ON', region: CANADA },
+  382: { name: 'Ontario', code: 'ON', region: CANADA },
   416: { name: 'Ontario', code: 'ON', region: CANADA },
   437: { name: 'Ontario', code: 'ON', region: CANADA },
   519: { name: 'Ontario', code: 'ON', region: CANADA },
   548: { name: 'Ontario', code: 'ON', region: CANADA },
   613: { name: 'Ontario', code: 'ON', region: CANADA },
   647: { name: 'Ontario', code: 'ON', region: CANADA },
+  683: { name: 'Ontario', code: 'ON', region: CANADA },
   705: { name: 'Ontario', code: 'ON', region: CANADA },
+  753: { name: 'Ontario', code: 'ON', region: CANADA },
   742: { name: 'Ontario', code: 'ON', region: CANADA },
   807: { name: 'Ontario', code: 'ON', region: CANADA },
   942: { name: 'Ontario', code: 'ON', region: CANADA },
   905: { name: 'Ontario', code: 'ON', region: CANADA },
+  263: { name: 'Quebec', code: 'QC', region: CANADA },
+  354: { name: 'Quebec', code: 'QC', region: CANADA },
+  367: { name: 'Quebec', code: 'QC', region: CANADA },
   387: { name: 'Quebec', code: 'QC', region: CANADA },
   418: { name: 'Quebec', code: 'QC', region: CANADA },
   438: { name: 'Quebec', code: 'QC', region: CANADA },
   450: { name: 'Quebec', code: 'QC', region: CANADA },
+  468: { name: 'Quebec', code: 'QC', region: CANADA },
   514: { name: 'Quebec', code: 'QC', region: CANADA },
   579: { name: 'Quebec', code: 'QC', region: CANADA },
   581: { name: 'Quebec', code: 'QC', region: CANADA },
   819: { name: 'Quebec', code: 'QC', region: CANADA },
   873: { name: 'Quebec', code: 'QC', region: CANADA },
   306: { name: 'Saskatchewan', code: 'SK', region: CANADA },
+  474: { name: 'Saskatchewan', code: 'SK', region: CANADA },
   639: { name: 'Saskatchewan', code: 'SK', region: CANADA },
   867: {
     name: 'Yukon, Northwest Territories, and Nunavut',
@@ -708,6 +718,7 @@ export const REGION_CODES = {
   679: { name: 'Fiji', code: 'FJ', flag: '🇫🇯' },
   358: { name: 'Finland', code: 'FI', flag: '🇫🇮' },
   33: { name: 'France', code: 'FR', flag: '🇫🇷' },
+  594: { name: 'French Guiana', code: 'GF', flag: '🇬🇫' },
   689: { name: 'French Polynesia', code: 'PF', flag: '🇵🇫' },
   241: { name: 'Gabon', code: 'GA', flag: '🇬🇦' },
   220: { name: 'Gambia', code: 'GM', flag: '🇬🇲' },
@@ -761,6 +772,7 @@ export const REGION_CODES = {
   223: { name: 'Mali', code: 'ML', flag: '🇲🇱' },
   356: { name: 'Malta', code: 'MT', flag: '🇲🇹' },
   692: { name: 'Marshall Islands', code: 'MH', flag: '🇲🇭' },
+  596: { name: 'Martinique', code: 'MQ', flag: '🇲🇶' },
   222: { name: 'Mauritania', code: 'MR', flag: '🇲🇷' },
   230: { name: 'Mauritius', code: 'MU', flag: '🇲🇺' },
   262: { name: 'Mayotte, Reunion', code: 'YT/RE', flag: '🇾🇹/🇷🇪' },

package/src/phoneFormats.js

@@ -15,34 +15,35 @@ export const PHONE_FORMATS = {
   40: '+xx xxx xxx xxx', // Romania
   41: '+xx xxx xxx xx xx', // Switzerland
   43: [
-    '+xx xxxx xxx-xxx', // 10 digits (mobile)
-    '+xx xxxx xxx-xxxx', // 11 digits
+    '+xx xxxx xxxx', // 10 digits (landline)
+    '+xx xxxx xxxx xx', // 12 digits (mobile)
   ], // Austria
   44: [
-    '+xx xxxx xxxxxx', // 10 digits (landline)
-    '+xx xxxxx xxxxxx', // 11 digits (mobile)
+    '+xx xxxx xxxxxx', // 12 digits (landline/mobile)
+    '+xx xxxxx xxxxxx', // 13 digits (some mobiles)
   ], // United Kingdom
   45: '+xx xx xx xx xx', // Denmark
   46: '+xx xx-xxx xx xx', // Sweden
   47: '+xx xxx xx xxx', // Norway
   48: '+xx xxx xxx xxx', // Poland
   49: [
-    '+xx xxx xxxxxxx', // 10 digits (standard)
-    '+xx xxxx xxxxxxxx', // 11 digits (mobile)
+    '+xx xx xxxxxxx', // 11 digits (landline: +49 + 2-digit area code + 7 digits)
+    '+xx xxx xxxxxxx', // 12 digits (landline: +49 + 3-digit area code + 7 digits)
+    '+xx xxx xxxxxxxx', // 12 digits (mobile: +49 + 3-digit prefix + 8 digits)
   ], // Germany
   51: '+xx xxx xxx xxx', // Peru
   52: [
-    '+xx xxx xxx xxxx', // 10 digits (standard)
-    '+xx xx xx xxxx xxxx', // 12 digits (with area code)
+    '+xx xxx xxx xxxx', // 12 digits (landline)
+    '+xx xxx xxx xxxx', // 13 digits (mobile with 1)
   ], // Mexico
   53: '+xx x xxx xxxx', // Cuba
   54: [
-    '+xx xxx-xxx-xxxx', // 10 digits (mobile and Buenos Aires)
-    '+xx xxxx-xx-xxxx', // 11 digits (mobile with 9 prefix)
+    '+xx xxx-xxx-xxxx', // 12 digits (landline)
+    '+xx xxxx-xxx-xxxx', // 13 digits (mobile with 9 prefix)
   ], // Argentina
   55: [
-    '+xx xx xxxx-xxxx', // 10 digits (standard)
-    '+xx xx xxxxx-xxxx', // 11 digits (mobile)
+    '+xx xx xxxx-xxxx', // 12 digits (landline)
+    '+xx xx xxxxx-xxxx', // 13 digits (mobile)
   ], // Brazil
   56: '+xx x xxxx xxxx', // Chile
   57: '+xx xxx xxx xxxx', // Colombia
@@ -145,7 +146,6 @@ export const PHONE_FORMATS = {
   269: '+xxx xxx xx xx', // Comoros
   290: '+xxx xxxx', // Saint Helena
   291: '+xxx x xxx xxx', // Eritrea
-  295: '+xxx xxx xxxx', // San Marino
   297: '+xxx xxx xxxx', // Aruba
   298: '+xxx xxx xxx', // Faroe Islands
   299: '+xxx xx xx xx', // Greenland

package/src/timezones.js

@@ -118,6 +118,11 @@ export const STATES_WITH_MULTIPLE_TIMEZONES = {
     458: ['-08:00', '-07:00'],
     541: ['-08:00', '-07:00'],
   },
+  Saskatchewan: {
+    306: ['-07:00', '-06:00', '-05:00'],
+    474: ['-07:00', '-06:00', '-05:00'],
+    639: ['-07:00', '-06:00', '-05:00'],
+  },
   'South Dakota': {
     605: ['-06:00', '-07:00'],
   },
@@ -142,7 +147,9 @@ export const STATES_WITH_MULTIPLE_TIMEZONES = {
     807: ['-05:00', '-06:00'],
   },
   Quebec: {
+    367: ['-04:00'],
     418: ['-04:00'],
+    581: ['-04:00'],
   },
   'Newfoundland and Labrador': {
     709: ['-03:30', '-04:00'],