feat [ROW-516]: introduce getByCountry api

.changeset/unlucky-pets-march.md

@@ -0,0 +1,5 @@
+---
+"@razorpay/i18nify-js": patch
+---
+
+introduce getByCountry api

packages/i18nify-js/README.md

@@ -691,6 +691,55 @@ console.log(res);
 */
 ```
 
+#### getByCountry
+
+The getByCountry API offers a treasure trove of information about any country in the world. With a single query, you can uncover details like country names, languages, currencies, dial codes, timezones, and even links to their flags. It’s a perfect tool for building apps that need geographic or cultural context.
+
+##### Examples
+
+```javascript
+// Fetching the metadata for a country
+const res = await getByCountry('AF');
+console.log(res);
+/*
+    {
+      "country_name": "Afghanistan",
+      "continent_code": "AS",
+      "continent_name": "Asia",
+      "alpha_3": "AFG",
+      "numeric_code": "004",
+      "flag": "https://flagcdn.com/af.svg",
+      "sovereignty": "UN member state",
+      "dial_code": "+93",
+      "supported_currency": [
+        "AFN"
+      ],
+      "timezones": {
+        "Asia/Kabul": {
+          "utc_offset": "UTC +04:30"
+        }
+      },
+      "timezone_of_capital": "Asia/Kabul",
+      "locales": {
+        "fa_AF": {
+          "name": "Persian (Afghanistan)"
+        },
+        "ps": {
+          "name": "Pashto"
+        },
+        "uz_AF": {
+          "name": "Uzbek"
+        },
+        "tk": {
+          "name": "Turkmen"
+        }
+      },
+      "default_locale": "fa_AF",
+      "default_currency": "AFN"
+    }
+*/
+```
+
 #### getStates(country_code)
 
 Embark on a state-by-state discovery with the getStates API! Get access to a treasure trove of state information, including names, time zones, and even a list of vibrant cities within each state.

packages/i18nify-js/src/modules/geo/__tests__/getByCountry.test.ts

@@ -0,0 +1,32 @@
+import { CountryCodeType } from '../../types';
+import getByCountry from '../getByCountry';
+import { COUNTRIES_METADATA } from '../mocks/country';
+import { CountryMetaType } from '../types';
+
+type MockResponse = {
+  metadata_information: Record<string, CountryMetaType>;
+};
+
+global.fetch = jest.fn(() =>
+  Promise.resolve({
+    ok: true,
+    status: 200,
+    json: () => Promise.resolve<MockResponse>(COUNTRIES_METADATA),
+  } as Response),
+);
+
+describe('getByCountry', () => {
+  it('fetches country metadata correctly', async () => {
+    const countries = await getByCountry('AF');
+    expect(countries).toHaveProperty('country_name');
+    expect(countries.country_name).toBe('Afghanistan');
+    expect(countries.alpha_3).toBe('AFG');
+  });
+
+  it('handles API errors', async () => {
+    global.fetch = jest.fn(() => Promise.reject('API Error'));
+    await expect(getByCountry('random' as CountryCodeType)).rejects.toThrow(
+      'An error occurred while fetching country metadata. The error details are: undefined.',
+    );
+  });
+});

packages/i18nify-js/src/modules/geo/getByCountry.ts

@@ -0,0 +1,27 @@
+import { withErrorBoundary } from '../../common/errorBoundary';
+import { CountryCodeType } from '../types';
+import { I18NIFY_DATA_SOURCE } from './constants';
+import { CountryMetaType } from './types';
+
+/**
+ * Retrieves the meta data for a country
+ *
+ * This function makes a network request to central i18nify-data source and
+ * returns a promise for the meta data for a country
+ *
+ * @returns {Promise} Promise object for data of a country
+ */
+const getByCountry = (
+  _countryCode: CountryCodeType,
+): Promise<CountryMetaType> => {
+  return fetch(`${I18NIFY_DATA_SOURCE}/country/metadata/data.json`)
+    .then((res) => res.json())
+    .then((res) => res.metadata_information[_countryCode])
+    .catch((err) => {
+      throw new Error(
+        `An error occurred while fetching country metadata. The error details are: ${err.message}.`,
+      );
+    });
+};
+
+export default withErrorBoundary<typeof getByCountry>(getByCountry);

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

@@ -4,3 +4,4 @@ export { default as getAllCountries } from './getAllCountries';
 export { default as getStates } from './getStates';
 export { default as getCities } from './getCities';
 export { default as getZipcodes } from './getZipcodes';
+export { default as getByCountry } from './getByCountry';