npm package: @randstad-uca/countries-states-cities
Description: Una librería personalizada para acceder a información sobre países, estados/provincias y ciudades de forma organizada y tipada.
Author: falvarez1
Latest version: 1.0.13

# 🌍 Randstad Countries, States & Cities Library

> Una librería en TypeScript para acceder a información sobre países, estados/provincias y ciudades de forma organizada y tipada.

```bash
npm install @randstad-uca/countries-states-cities
```

## 🧩 Características

- ✅ Soporte multilenguaje (ej: español, inglés).
- ✅ Archivos JSON separados por idioma.
- ✅ Fácil de mantener y expandir.
- ✅ Uso simple desde cualquier parte del proyecto.
- ✅ Compatible con sistemas offline (si se usa con .tgz o archivos locales).

---

### 🧩 Uso Básico

```bash
import location from '@randstad-uca/countries-states-cities';
```
---

### 🏁 Métodos Disponibles

1. getAllCountries(type?: Type): CountryResponse[]

Devuelve todos los países.
- **Parámetros**: 
    type: 'base' | 'full' (opcional, por defecto es 'base')
- **Ejemplo**: 
```ts
const allCountries = location.getAllCountries();
const baseCountries = location.getAllCountries('full');
```

2. getCountry(isoCode: string, type?: Type): CountryResponse | undefined
Busca un país por su código ISO.

- **Parámetros**: 
isoCode: Código ISO del país (ej: "AR" para Argentina)
type: 'base' | 'full' (opcional, por defecto es 'base')
- **Ejemplo**: 
```ts
const argentina = location.getCountry("AR");
const argentinaBase = location.getCountry("AR", "base");
```

3. getAllStates(countryCode: string, type?: Type): StateResponse[]
Devuelve todos los estados de un país.

- **Parámetros**:
countryCode: Código ISO del país (ej: "AR")
type: 'base' | 'full' (opcional, por defecto es 'base')
- **Ejemplo**: 
```ts
const estadosDeARG = location.getAllStates("AR");
const estadosDeARGBase = location.getAllStates("AR", "base");
```

4. getCitiesByState(countryCode: string, stateCode: number | string): CityResponse[]
Devuelve todas las ciudades de un estado de Argentina solo se usa este en las API habilitadas

- **Parámetros**:
countryCode: Código ISO del país (ej: "AR")
stateCode: Código del estado (puede ser número o string)
- **Ejemplo**: 
```ts
const citiesOfArgentina = location.getCitiesByState("AR", 1);
```

5. getCityByLocCodLocSec(locCod: number, locSec: number): City[]
Devuelve todas las ciudades de con locCod y locSec de Argentina solo se usa este en las API habilitadas

- **Parámetros**:
locCod: Código númerico postal de la provincia (ej: 5539)
locSec: Código númerico seccion de la provincia (ej: 1)
- **Ejemplo**: 
```ts
const citiesOfArgentinaByLocCodLocSec = location.getCityByLocCodLocSec(1741, 8);
```

6. getState(stateCode: number): State[]
Devuelve estado especificamente de Argentina correspodiente al stateCode

- **Parámetros**:
stateCode: stateCode de la provincia (ej: 6)
- **Ejemplo**: 
```ts
const stateByCodePRV = location.getState(6);
```

---

### 🧱 Tipos Soportados

```ts
type Type = 'base' | 'full';
```

Interfaces Base

#### CountryBase
```ts
{
  PaiCod: string;     // Nombre del país
  PaiNom: string;     // Nombre formal
  PaiAFICod: number;  // Código interno
  PaiIso: string;     // Código ISO
}
```
#### StateBase
```ts
{
  PrvCod: number;     // Código del estado
  PrvNom: string;     // Nombre del estado
}
```
#### CityBase
```ts
{
  LocCod: number;     // Código de la ciudad
  LocSec: number;     // Código secundario
  LocNom: string;     // Nombre de la ciudad
  PrvCod: number;     // Código del estado al que pertenece
}
```
---

### 📁 Estructura del Proyecto
```
country-state-cities/
├── src/
│   ├── assets              - Banderas .svg
│   ├── index.ts            - Funciones principales
│   ├── data/               # Archivos JSON con datos
│   ├── script/             # Copy data to build
│   ├── services/           # Servicio principal
│   ├── utils/              # Funciones auxiliares
│   ├── types/              # Tipos e interfaces globales
│   └── test/               # Scripts de prueba
├── dist/                   - Código compilado (build)
├── package.json
├── README.md
└── tsconfig.json
```