<?php
/**
 * SIMAFIR Functions
 * 
 * Funciones auxiliares para el módulo SIMAFIR
 * 
 * @package secmca-api
 * @version 1.5.45
 */

/**
 * Convierte ID de país a código ISO-3 o código de región
 * 
 * El API de SIMAFIR devuelve países con estructura:
 * {
 *   "id": 3,
 *   "nombre": "Costa Rica",
 *   "descripcion": "Costa Rica"
 * }
 * 
 * Esta función mapea el ID a códigos estándar ISO-3 (3 dígitos) para países
 * y códigos descriptivos para regiones.
 * 
 * @param int $country_id ID del país/región del API
 * @return string Código ISO-3 (CRI, SLV, GTM) o código de región (CA, CARD, CAPARD)
 * 
 * @example
 * simafir_country_id_to_code(3)   // Retorna: "CRI" (Costa Rica)
 * simafir_country_id_to_code(95)  // Retorna: "CA" (Centroamérica)
 */
function simafir_country_id_to_code($country_id) {
    // Mapeo de IDs a códigos ISO-3 (3 dígitos) y códigos de región
    $country_map = array(
        // Países individuales (ISO 3166-1 alpha-3)
        3   => 'CRI',     // Costa Rica
        13  => 'SLV',     // El Salvador
        50  => 'GTM',     // Guatemala
        17  => 'HND',     // Honduras
        4   => 'NIC',     // Nicaragua
        52  => 'DOM',     // República Dominicana
        161 => 'PAN',     // Panamá
        // Belice agregado
        999 => 'BLZ',     // Belice (ajustar ID según API real)
        
        // Regiones y agrupaciones
        95  => 'CA',      // CA - países centroamericanos (5)
        56  => 'CARD',    // CARD - Centroamérica y República Dominicana (6)
        78  => 'CAPARD',  // CAPARD - Centroamérica, República Dominicana y Panamá (7)
    );
    
    // Retornar código si existe, sino retornar el ID como string
    return isset($country_map[$country_id]) ? $country_map[$country_id] : strval($country_id);
}

/**
 * Verifica si un ID corresponde a un país (no región)
 * 
 * @param int $country_id ID del país/región del API
 * @return bool True si es un país individual, False si es región
 */
function simafir_is_country($country_id) {
    $countries = array(3, 13, 50, 17, 4, 52, 161);
    return in_array($country_id, $countries);
}

/**
 * Verifica si un ID corresponde a una región
 * 
 * @param int $country_id ID del país/región del API
 * @return bool True si es una región, False si es país individual
 */
function simafir_is_region($country_id) {
    $regions = array(95, 56, 78);
    return in_array($region_id, $regions);
}

/**
 * Obtiene el nombre del país/región por ID
 * 
 * @param int $country_id ID del país/región del API
 * @return string Nombre del país o región
 */
function simafir_get_country_name($country_id) {
    $country_names = array(
        3   => 'Costa Rica',
        13  => 'El Salvador',
        50  => 'Guatemala',
        17  => 'Honduras',
        4   => 'Nicaragua',
        52  => 'República Dominicana',
        161 => 'Panamá',
        95  => 'Centroamérica (5 países)',
        56  => 'Centroamérica y República Dominicana',
        78  => 'Centroamérica, República Dominicana y Panamá',
    );
    
    return isset($country_names[$country_id]) ? $country_names[$country_id] : 'Desconocido';
}
