npm package: @kinkiwi/restcountries-sdk
Description: Rest countries SDK
Author: Coman Cosmin-Alexandru
Latest version: 1.2.8

# @kinkiwi/restcountries-sdk

> A TypeScript-first SDK for the [REST Countries v3.1 API](https://restcountries.com/), designed with SOLID principles and a clean developer experience.

---

![npm](https://img.shields.io/npm/v/@kinkiwi/restcountries-sdk?color=blue)
![typescript](https://img.shields.io/badge/types-TypeScript-blue)
![license](https://img.shields.io/npm/l/@kinkiwi/restcountries-sdk)
![build](https://img.shields.io/github/actions/workflow/status/kinkiwi/restcountries-sdk/ci.yml?label=build)

---

## Features

- Full TypeScript support with strict types for requests and responses
- Modular architecture with dedicated clients:
  - `countries` – all countries
  - `codes` – lookup by one or more alpha codes
  - `name` – search by name (with optional full-text match)
  - `currency` – filter by currency code
  - `language` – filter by spoken language
  - `region` – filter by region
  - `subregion` – filter by subregion
  - `demonym` – filter by demonym
  - `translation` – filter by translated name
- Optional field filtering using a strongly typed `fields` enum
- Clean, maintainable implementation based on SOLID and DRY principles
- Axios-based HTTP client with no runtime dependencies
- Designed for easy integration in both Node.js and browser-based TypeScript projects
- Enums with:
  - `Region`
  - `Subregion`
  - `CountryName`
  - `CCA2`
  - `CCN3`

## Installation

Install the SDK via npm or yarn:

```bash
npm install @kinkiwi/restcountries-sdk
```

```bash
yarn add @kinkiwi/restcountries-sdk
```

## Usage Examples

### Basic Country Lookup by Code

Fetch a country by its alpha-2 code, selecting only specific fields to reduce response size:

```ts
import { RestCountries, fields } from '@kinkiwi/restcountries-sdk';

const client = new RestCountries();

async function example() {
  const country = await client.codes.getByCode('US');

  console.log(country?.name.common); // "United States"
}

example();
```

Retrieve multiple countries in one request:

```ts
const countries = await client.codes.getByCodes(['US', 'CA', 'MX']);

console.log(countries.map((c) => c.name.common));
```

### Search by country name with full-text matching

```ts
const romania = await client.name.getFullText('Romania');

console.log(romania?.population);
```

### Filtering by fields

Sometimes we do not wish to retrieve all the fields of a Country, to use the filters we have to pass a fields array as a second parameter to the call:

```ts
const romania = await client.name.getFullText('Romania', [fields.name, fields.population]);

console.log(romania?.population);
```

There is also a fields preset that helps you get common fields like `basic`, `geo` and `identifiers`, like this:

```ts
import { fieldPreset } from '@kinkiwi/restcountries-sdk';

/**
 * fieldsPreset.basic = name, region, population
 */
const countries = await client.countries.get(fieldPreset.basic);

console.log(countries.length);
```

You can combine them with fields you need:

```ts
import { fieldPreset, fields } from '@kinkiwi/restcountries-sdk';

const customFields = [fields.unMember, ...fieldPreset.basic];

const countries = await client.countries.get(customFields);

console.log(countries.length);
```

## Error Handling

The SDK uses [Axios](https://axios-http.com/) under the hood to perform HTTP requests. When a request fails, the SDK will throw an error propagated from Axios.

### Types of Errors

- **Network errors:** Issues with connectivity or DNS.
- **HTTP errors:** Non-2xx HTTP responses (e.g., 404 Not Found, 500 Internal Server Error).
- **Timeouts or cancellation:** Requests that time out or are aborted.

### How Errors Are Exposed

All client methods return Promises and will throw if the request fails. You should use `try/catch` blocks or `.catch()` handlers to capture errors.

### Example

```ts
import { RestCountries, fields } from '@kinkiwi/restcountries-sdk';

const client = new RestCountries();

async function fetchCountry() {
  try {
    const country = await client.codes.getByCode('XYZ', [fields.name]);
  } catch (error) {
    if (axios.isAxiosError(error)) {
      console.error('API request failed:', error.response?.status, error.response?.data);
    } else {
      console.error('Unexpected error:', error);
    }
  }
}

fetchCountry();
```