feat: add new api for masked contact number in phone number module [ATLAS-197]

.changeset/few-deers-agree.md

@@ -0,0 +1,5 @@
+---
+"@razorpay/i18nify-js": minor
+---
+
+add new api for masked contact number in phone number module

packages/i18nify-js/README.md

@@ -541,6 +541,26 @@ console.log(getDialCodeByCountryCode('BR')); // Outputs the dial code for Brazil
 console.log(getDialCodeByCountryCode('DE')); // Outputs the dial code for Germany (+49)
 ```
 
+#### getMaskedPhoneNumber(countryCode, withDialCode = true)
+
+📱🌍 This function provides an easy way to generate a formatted, masked phone number for any specified country based on its ISO 3166-1 alpha-2 code. Ideal for applications that handle international phone data, it allows for displaying phone number formats in a user-friendly masked layout. If the country code is not recognized or if formatting data is missing, the function will clearly indicate an error, ensuring reliable and accurate use.
+
+##### Examples
+
+```
+// Displaying the masked phone number for India including the dial code
+console.log(getMaskedPhoneNumber('IN')); // Outputs: "+91 xxxx xxxxxx"
+
+// Displaying the masked phone number for India without the dial code
+console.log(getMaskedPhoneNumber('IN', false)); // Outputs: "xxxx xxxxxx"
+
+// Displaying the masked phone number for Malaysia including the dial code
+console.log(getMaskedPhoneNumber('MY')); // Outputs: "+60 xx xxxxx xx"
+
+// Displaying the masked phone number for Malaysia without the dial code
+console.log(getMaskedPhoneNumber('MY', false)); // Outputs: "xx xxxxx xx"
+```
+
 ### Module 03: Geo Module 🌍
 
 Dive into the digital atlas with the Geo Module 🌍, your ultimate toolkit for accessing geo contextual data from around the globe 🌐. Whether you're infusing your projects with national pride 🎉 or exploring different countries 🤔, this module is like a magic carpet ride 🧞‍♂️. With a range of functions at your disposal ✨, incorporating global data 🚩 into your app has never been easier. Let's explore these global gems 🌟:

packages/i18nify-js/src/modules/phoneNumber/__tests__/getMaskedPhoneNumber.test.ts

@@ -0,0 +1,60 @@
+import { CountryCodeType } from '../../types';
+import { getMaskedPhoneNumber } from '../index';
+
+describe('phoneNumber - getMaskedPhoneNumber', () => {
+  // Test data array for multiple countries
+  const testCasesWithDialCode = [
+    { countryCode: 'US', expected: '+1 xxx-xxx-xxxx' },
+    { countryCode: 'GB', expected: '+44 xxxx xxx xxx' },
+    { countryCode: 'DE', expected: '+49 xxx xxxxxxxx' },
+    { countryCode: 'IN', expected: '+91 xxxx xxxxxx' },
+    { countryCode: 'JP', expected: '+81 xx xxxx xxxx' },
+  ];
+
+  // Tests for valid inputs including dial code
+  testCasesWithDialCode.forEach(({ countryCode, expected }) => {
+    it(`should return the correct phone number format including dial code for ${countryCode}`, () => {
+      const result = getMaskedPhoneNumber(countryCode as CountryCodeType, true);
+      expect(result).toBe(expected);
+    });
+  });
+
+  // Tests for valid inputs without dial code
+  testCasesWithDialCode.forEach(({ countryCode, expected }) => {
+    it(`should return the correct phone number format without dial code for ${countryCode}`, () => {
+      const result = getMaskedPhoneNumber(
+        countryCode as CountryCodeType,
+        false,
+      );
+      // Remove the dial code and leading space from the expected string
+      const expectedWithoutDialCode = expected.substring(
+        expected.indexOf(' ') + 1,
+      );
+      expect(result).toBe(expectedWithoutDialCode);
+    });
+  });
+
+  // Test for invalid country code
+  it('should throw an error for an invalid country code', () => {
+    expect(() => {
+      // @ts-expect-error null is not a valid country code
+      getMaskedPhoneNumber('XYZ', true);
+    }).toThrow('Parameter "countryCode" is invalid: XYZ');
+  });
+
+  // Test for missing country code
+  it('should throw an error when country code is undefined', () => {
+    expect(() => {
+      // @ts-expect-error null is not a valid country code
+      getMaskedPhoneNumber(undefined, true);
+    }).toThrow('Parameter "countryCode" is invalid: undefined');
+  });
+
+  // Test for null country code
+  it('should throw an error when country code is null', () => {
+    expect(() => {
+      // @ts-expect-error null is not a valid country code
+      getMaskedPhoneNumber(null, true);
+    }).toThrow('Parameter "countryCode" is invalid: null');
+  });
+});

packages/i18nify-js/src/modules/phoneNumber/getMaskedPhoneNumber.ts

@@ -0,0 +1,41 @@
+import getDialCodeByCountryCode from './getDialCodeByCountryCode';
+import { withErrorBoundary } from '../../common/errorBoundary';
+import PHONE_FORMATTER_MAPPER from './data/phoneFormatterMapper.json';
+import { CountryCodeType } from '../types';
+
+/**
+ * Returns a masked phone number based on the country code.
+ *
+ * @param countryCode The ISO 3166-1 alpha-2 country code.
+ * @param withDialCode A boolean indicating whether to include the country's dial code in the result. It has a default value of "true"
+ * @returns The masked phone number as a string.
+ */
+const getMaskedPhoneNumber = (
+  countryCode: CountryCodeType,
+  withDialCode: boolean = true,
+): string => {
+  // Throw errors if countryCode is invalid
+  if (!countryCode)
+    throw new Error(`Parameter "countryCode" is invalid: ${countryCode}`);
+
+  // Retrieve the template for the given country code
+  const formattingTemplate = PHONE_FORMATTER_MAPPER[countryCode];
+
+  // Check if the country code is valid and a template exists
+  if (!formattingTemplate) {
+    throw new Error(`Parameter "countryCode" is invalid: ${countryCode}`);
+  }
+
+  // If including the dial code, prepend it to the template with a space
+  if (withDialCode) {
+    const dialCode = getDialCodeByCountryCode(countryCode);
+    return `${dialCode} ${formattingTemplate}`;
+  }
+
+  // Return the template directly if not including the dial code
+  return formattingTemplate;
+};
+
+export default withErrorBoundary<typeof getMaskedPhoneNumber>(
+  getMaskedPhoneNumber,
+);

packages/i18nify-js/src/modules/phoneNumber/index.ts

@@ -3,3 +3,4 @@ export { default as formatPhoneNumber } from './formatPhoneNumber';
 export { default as parsePhoneNumber } from './parsePhoneNumber';
 export { default as getDialCodes } from './getDialCodes';
 export { default as getDialCodeByCountryCode } from './getDialCodeByCountryCode';
+export { default as getMaskedPhoneNumber } from './getMaskedPhoneNumber';