regions-config

Paquete de configuración de regiones para las aplicaciones de IATI. Proporciona la configuración completa de cada región (zona horaria, tipos de documento, métodos de pago, links de footer, países a redirigir, etc.) junto con utilidades tipadas para acceder a ella.

ℹ️ Esta config la consumen los proyectos de purchase-funnel-widget y purchase-funnel (iati-backoffice-monorepo)

Regiones disponibles

| Clave | regionCode | Descripción | | --------- | ------------ | ----------------------------- | | es | es-ES | España | | commx | es-MX | México | | comeneu | en-EU | Internacional Europa (EN) | | comen | en-ROW | Internacional resto del mundo | | it | it-IT | Italia | | pt | pt-PT | Portugal | | comco | es-CO | Colombia | | compe | es-PE | Perú |

Instalación

npm install regions-config
# o
pnpm add regions-config

El paquete tiene acceso restringido (publishConfig.access: "restricted"). Asegúrate de estar autenticado en npm con una cuenta con permisos sobre el scope @iati:

npm login --scope=@iati

Uso dentro del monorepo

Si lo consumes desde otra app o paquete del mismo workspace, puedes apuntar directamente a la versión local:

{
  "dependencies": {
    "regions-config": "workspace:*"
  }
}

API

regionsConfig

Objeto con la configuración completa de todas las regiones, ya validada con Zod.

import { regionsConfig } from 'regions-config';

const spain = regionsConfig['es'];
console.log(spain.regionCode); // 'es-ES'

getRegionConfig(name: string): RegionConfig

Obtiene la configuración de una región a partir de su clave (elimina guiones y barras del nombre). Esto se usa generalmente para recuperar la config con la property short_name que viene del backend en el endpoint de commons (commons.site.short_name)

import { getRegionConfig } from 'regions-config';

const config = getRegionConfig('com/co'); // equivalente a regionsConfig['comco']

getRegionConfigById(id: number): RegionConfig

Obtiene la configuración de una región por su id numérico. Lanza un error si no se encuentra.

import { getRegionConfigById } from 'regions-config';

const config = getRegionConfigById(1); // región España

getRegionConfigByRegionCode(regionCode: RegionCode): RegionConfig

Obtiene la configuración de una región por su regionCode. Lanza un error si el código no existe.

import { getRegionConfigByRegionCode } from 'regions-config';

const config = getRegionConfigByRegionCode('es-ES');

validateRegion(region: RegionCode): void

Valida que un regionCode sea válido. Lanza un error si no corresponde a ninguna región configurada.

import { validateRegion } from 'regions-config';

validateRegion('es-ES'); // OK
validateRegion('xx-XX'); // Error: Invalid region: xx-XX

resolveDocumentTypeOptions(...): DocumentTypeOption[]

Resuelve las opciones de tipo de documento en función del país de origen del usuario (local o extranjero).

import { resolveDocumentTypeOptions } from 'regions-config';

const options = resolveDocumentTypeOptions(
  config.documentTypeOptions,
  config.documentTypeOptionsByOrigin,
  originCountryId,
  siteCountryId,
);

Si documentTypeOptionsByOrigin no está definido, devuelve el array documentTypeOptions base.

Tipos principales

type RegionConfig = {
  id: number;
  gtmId: string; // Formato: GTM-XXXXXXX
  regionCode: 'es-ES' | 'es-MX' | 'en-EU' | 'en-ROW' | 'it-IT' | 'pt-PT' | 'es-CO' | 'es-PE';
  timeZone: string;
  dateFormat: string;
  footer: Array<{ href: string; label: string }>;
  documentTypeOptions: Array<{ label: string; value: string }>;
  documentTypeOptionsByOrigin?: DocumentTypeOptionsByOrigin;
  paymentCardTypes: Array<{ id: number; name: string; imagePath: string }>;
  countriesToRedirect?: CountriesToRedirectMap;
  regionsToGroup?: RegionToGroup[];
  regionUrls?: { staging: string; production: string };
  webSitePath?: string;
};

Constantes exportadas

| Constante | Descripción | | --------------------------- | --------------------------------------- | | GROUP_REGIONS | IDs numéricos de los grupos de regiones | | EUROPE_COUNTRIES | Array de IDs de países europeos | | US_CANADA_COUNTRIES | Array de IDs de EE.UU. y Canadá | | US_CANADA_JAPAN_COUNTRIES | Array de IDs de EE.UU., Canadá y Japón | | WORLD_COUNTRIES | Array de IDs del resto del mundo |

Estructura del paquete

src/
├── const.ts                        # Constantes de países y grupos de regiones
├── index.ts                        # Punto de entrada y re-exports
├── regionsConfig.ts                # Construcción del objeto de configuración
├── domain/
│   └── RegionConfigSchema.ts       # Schema Zod y tipos TypeScript
├── regions/
│   ├── es.json                     # Config España
│   ├── commx.json                  # Config México
│   ├── comeneu.json                # Config Internacional Europa
│   ├── comen.json                  # Config Internacional resto del mundo
│   ├── it.json                     # Config Italia
│   ├── pt.json                     # Config Portugal
│   ├── comco.json                  # Config Colombia
│   ├── compe.json                  # Config Perú
│   └── index.ts
├── utils/
│   ├── getRegionConfig.ts
│   ├── getRegionConfigById.ts
│   ├── getRegionConfigByRegionCode.ts
│   └── resolveDocumentTypeOptions.ts
└── validators/
    └── validateRegion.ts

Scripts

# Compilar el paquete
pnpm build

# Validar la configuración de todas las regiones sin compilar
pnpm validate

# Modo watch (desarrollo)
pnpm dev

# Limpiar artefactos
pnpm clean

Validación

La configuración de cada región se valida con Zod (RegionConfigSchema) a través del script validate:

pnpm validate

Este script ejecuta tsx src/regionsConfig.ts, que recorre todos los JSONs de región, los resuelve (reemplazando referencias a constantes de países) y los parsea contra el schema. Si algún JSON está mal formado o le falta algún campo requerido, el proceso termina con un error descriptivo.

El script se ejecuta automáticamente antes de cada compilación (pnpm build internamente corre pnpm validate && tsup), por lo que un build exitoso garantiza que toda la configuración es válida.