import { ITGlueClient } from '../client';
import { QueryUtilOptions, QueryParams, BaseListResponse, BaseItemResponse, CountryResource, RegionResource } from '../types';
/**
 * Countries resource module for IT Glue API
 *
 * Provides methods to interact with the /countries endpoint.
 * Countries represent geographic countries and their administrative regions,
 * serving as reference data for location-based information throughout IT Glue.
 * This includes contact addresses, organization locations, and asset deployment
 * tracking. Countries provide hierarchical geographic data with associated regions
 * (states, provinces, territories) for detailed location management.
 *
 * **Note: This is a read-only resource.** Countries and their regions cannot be
 * created, updated, or deleted through the API as they are maintained as
 * standardized geographic reference data by IT Glue.
 *
 * Countries are typically referenced by:
 * - Organizations (headquarters and office locations)
 * - Contacts (address information)
 * - Locations (physical site addresses)
 * - Assets (deployment and datacenter locations)
 * - Regions (administrative subdivisions within countries)
 *
 * ## Related Resources
 * Countries are commonly used with:
 * - {@link Regions} - Administrative subdivisions within countries (states, provinces)
 * - {@link Locations} - Physical sites and facilities located in countries
 * - {@link Organizations} - Organizations with headquarters or offices in countries
 * - {@link Contacts} - People with addresses in specific countries
 * - {@link Configurations} - IT assets deployed in specific countries
 * - {@link Documents} - Documentation related to country-specific operations
 * - {@link FlexibleAssets} - Custom tracking of country-specific data and compliance
 * - {@link RelatedItems} - Create relationships between countries and other resources
 * - {@link Tags} - Categorize resources by geographic regions
 *
 * @see {@link Regions#list} for retrieving regions within countries
 * @see {@link Locations#list} for retrieving locations in specific countries
 * @see {@link Organizations#list} for retrieving organizations by country
 * @see {@link Contacts#list} for retrieving contacts by country
 *
 * @example
 * import { ITGlueClient } from '../client';
 * import { Countries } from './resources/countries';
 *
 * const client = new ITGlueClient({ apiKey: 'your-api-key' });
 * const countries = new Countries(client);
 *
 * // List countries
 * const list = await countries.list();
 *
 * // Get a single country
 * const country = await countries.get('1');
 *
 * // List regions for a country
 * const regions = await countries.listRegions('1');
 *
 * // Get a specific region for a country
 * const region = await countries.getRegion('1', '2');
 *
 * @category Reference Data
 */
export declare class Countries {
    private client;
    private basePath;
    private paginationUtil;
    /**
     * Create a Countries resource instance
     * @param {ITGlueClient} client - ITGlueClient instance
     */
    constructor(client: ITGlueClient);
    /**
     * List all countries
     *
     * Retrieves a list of all countries available in IT Glue. Countries are read-only
     * reference data representing geographic nations used for location-based information
     * throughout the system. This data is standardized and maintained by IT Glue.
     *
     * @param {QueryUtilOptions} [options] - Optional query parameters (filter, sort, page, etc.)
     * @param {boolean} [allPages=false] - If true, fetches all pages automatically
     * @returns {Promise<BaseListResponse<CountryResource>>} List of countries and pagination metadata
     * @example
     * // Basic usage - get first page of countries
     * const results = await client.countries.list();
     * console.log(`Found ${results.data.length} countries`);
     * console.log('Total pages:', results.meta.pagination.total_pages);
     *
     * @example
     * // Advanced usage with pagination and sorting
     * const results = await client.countries.list({
     *   page: { number: 2, size: 50 },
     *   sort: 'name' // Sort alphabetically
     * });
     *
     * // Access country information
     * results.data.forEach(country => {
     *   console.log(`Country: ${country.attributes.name}`);
     *   console.log(`Code: ${country.attributes.iso || 'N/A'}`);
     * });
     *
     * @example
     * // Filtering countries by name pattern
     * const usCountries = await client.countries.list({
     *   filter: {
     *     name: 'United'
     *   },
     *   sort: 'name'
     * });
     *
     * console.log(`Found ${usCountries.data.length} countries with 'United' in name`);
     *
     * @example
     * // Get all countries for location management
     * const allCountries = await client.countries.list({}, true); // allPages = true
     * console.log(`Retrieved all ${allCountries.data.length} countries`);
     *
     * // Create country lookup map for address validation
     * const countryLookup = {};
     * allCountries.data.forEach(country => {
     *   countryLookup[country.id] = {
     *     name: country.attributes.name,
     *     iso: country.attributes.iso,
     *     code: country.attributes.code
     *   };
     * });
     *
     * // Group countries by continent/region for reporting
     * const countriesByRegion = {
     *   northAmerica: [],
     *   europe: [],
     *   asia: [],
     *   other: []
     * };
     *
     * allCountries.data.forEach(country => {
     *   const name = country.attributes.name.toLowerCase();
     *   if (name.includes('united states') || name.includes('canada') || name.includes('mexico')) {
     *     countriesByRegion.northAmerica.push(country.attributes.name);
     *   } else if (name.includes('kingdom') || name.includes('germany') || name.includes('france')) {
     *     countriesByRegion.europe.push(country.attributes.name);
     *   } else if (name.includes('japan') || name.includes('china') || name.includes('india')) {
     *     countriesByRegion.asia.push(country.attributes.name);
     *   } else {
     *     countriesByRegion.other.push(country.attributes.name);
     *   }
     * });
     *
     * @example
     * // Manual pagination for large country datasets
     * async function getAllCountriesWithDetails() {
     *   let page = 1;
     *   let allCountries = [];
     *   let hasMore = true;
     *
     *   while (hasMore) {
     *     const response = await client.countries.list({
     *       page: { number: page, size: 100 },
     *       sort: 'name'
     *     });
     *
     *     allCountries = [...allCountries, ...response.data];
     *     hasMore = response.meta.pagination.total_pages > page;
     *     page++;
     *   }
     *
     *   return allCountries;
     * }
     *
     * @example
     * // Error handling for list operations
     * try {
     *   const results = await client.countries.list({
     *     filter: { invalid_field: 'value' }
     *   });
     * } catch (error) {
     *   if (error.response?.status === 400) {
     *     console.log('Invalid filter parameters:', error.response.data.errors);
     *   } else if (error.response?.status === 401) {
     *     console.log('Authentication failed - check your API key');
     *   } else if (error.response?.status === 403) {
     *     console.log('Access denied - insufficient permissions to list countries');
     *   } else {
     *     console.log('Request failed:', error.message);
     *   }
     * }
     */
    list(options?: QueryUtilOptions, allPages?: boolean): Promise<BaseListResponse<CountryResource>>;
    /**
     * Get a single country by ID
     *
     * Retrieves detailed information about a specific country. Countries are read-only
     * reference data that provide geographic information for location-based features
     * throughout IT Glue, including contact addresses and organization locations.
     *
     * @param {string} id - Country ID
     * @param {QueryParams} [params] - Optional query parameters
     * @returns {Promise<BaseItemResponse<CountryResource>>} Country resource
     * @throws {Error} When country not found (404)
     * @example
     * // Basic usage - get country by ID
     * const country = await client.countries.get('1');
     * console.log('Country name:', country.data.attributes.name);
     * console.log('ISO code:', country.data.attributes.iso);
     * console.log('Country code:', country.data.attributes.code);
     *
     * @example
     * // Get country with related regions included
     * const countryWithRegions = await client.countries.get('1', {
     *   include: ['regions']
     * });
     *
     * // Access included data
     * const included = countryWithRegions.included || [];
     * const regions = included.filter(item => item.type === 'regions');
     *
     * console.log(`Country: ${countryWithRegions.data.attributes.name}`);
     * console.log(`Regions: ${regions.length} administrative divisions`);
     * regions.forEach(region => {
     *   console.log(`- ${region.attributes.name} (${region.attributes.abbreviation || 'N/A'})`);
     * });
     *
     * @example
     * // Error handling for get operations
     * try {
     *   const country = await client.countries.get('invalid-id');
     * } catch (error) {
     *   if (error.response?.status === 404) {
     *     console.log('Country not found');
     *   } else if (error.response?.status === 403) {
     *     console.log('Access denied - insufficient permissions');
     *   } else {
     *     console.log('Error retrieving country:', error.message);
     *   }
     * }
     *
     * @example
     * // Safe get with existence check for address validation
     * async function safeGetCountry(id) {
     *   try {
     *     const country = await client.countries.get(id);
     *     return {
     *       id: country.data.id,
     *       name: country.data.attributes.name,
     *       iso: country.data.attributes.iso,
     *       code: country.data.attributes.code
     *     };
     *   } catch (error) {
     *     if (error.response?.status === 404) {
     *       return null; // Country doesn't exist
     *     }
     *     throw error; // Re-throw other errors
     *   }
     * }
   * @see
   * {@link Regions#get} - Get specific region details
   * {@link Regions#list} - List regions related to countries
   * {@link Locations#get} - Get specific location details
   * {@link Locations#list} - List locations related to countries
   
     */
    get(id: string, params?: QueryParams): Promise<BaseItemResponse<CountryResource>>;
    /**
     * List all regions for a specific country
     *
     * Retrieves a list of administrative regions (states, provinces, territories) for
     * a specific country. Regions provide detailed geographic subdivision data for
     * precise location tracking within countries. This is particularly useful for
     * countries with complex administrative structures like the United States, Canada,
     * Australia, and others.
     *
     * @param {string} countryId - Country ID (required)
     * @param {QueryUtilOptions} [options] - Optional query parameters (filter, sort, page, etc.)
     * @param {boolean} [allPages=false] - If true, fetches all pages automatically
     * @returns {Promise<BaseListResponse<RegionResource>>} List of regions for the country and pagination metadata
     * @throws {Error} When country not found (404)
     * @example
     * // Basic usage - list all regions for a country (e.g., US states)
     * const regions = await client.countries.listRegions('1');
     * console.log(`Found ${regions.data.length} regions`);
     * console.log('Total pages:', regions.meta.pagination.total_pages);
     *
     * @example
     * // Advanced usage with pagination and sorting
     * const regions = await client.countries.listRegions('1', {
     *   page: { number: 2, size: 25 },
     *   sort: 'name' // Sort alphabetically
     * });
     *
     * // Access region information
     * regions.data.forEach(region => {
     *   console.log(`Region: ${region.attributes.name}`);
     *   console.log(`Abbreviation: ${region.attributes.abbreviation || 'N/A'}`);
     * });
     *
     * @example
     * // Filtering regions by name pattern
     * const californiaRegions = await client.countries.listRegions('1', {
     *   filter: {
     *     name: 'California'
     *   },
     *   sort: 'name'
     * });
     *
     * console.log(`Found ${californiaRegions.data.length} regions matching 'California'`);
     *
     * @example
     * // Get all regions for address validation and dropdowns
     * const allRegions = await client.countries.listRegions('1', {}, true); // allPages = true
     * console.log(`Retrieved all ${allRegions.data.length} regions for country`);
     *
     * // Create region lookup for address forms
     * const regionLookup = {};
     * allRegions.data.forEach(region => {
     *   regionLookup[region.id] = {
     *     name: region.attributes.name,
     *     abbreviation: region.attributes.abbreviation,
     *     code: region.attributes.code
     *   };
     * });
     *
     * // Group regions by type (if available)
     * const regionsByType = {
     *   states: [],
     *   territories: [],
     *   districts: [],
     *   other: []
     * };
     *
     * allRegions.data.forEach(region => {
     *   const name = region.attributes.name.toLowerCase();
     *   if (name.includes('territory')) {
     *     regionsByType.territories.push(region.attributes.name);
     *   } else if (name.includes('district')) {
     *     regionsByType.districts.push(region.attributes.name);
     *   } else if (region.attributes.abbreviation && region.attributes.abbreviation.length === 2) {
     *     regionsByType.states.push(region.attributes.name);
     *   } else {
     *     regionsByType.other.push(region.attributes.name);
     *   }
     * });
     *
     * @example
     * // Manual pagination for large region datasets
     * async function getAllRegionsForCountry(countryId) {
     *   let page = 1;
     *   let allRegions = [];
     *   let hasMore = true;
     *
     *   while (hasMore) {
     *     const response = await client.countries.listRegions(countryId, {
     *       page: { number: page, size: 100 },
     *       sort: 'name'
     *     });
     *
     *     allRegions = [...allRegions, ...response.data];
     *     hasMore = response.meta.pagination.total_pages > page;
     *     page++;
     *   }
     *
     *   return allRegions;
     * }
     *
     * @example
     * // Error handling for region listing
     * try {
     *   const regions = await client.countries.listRegions('invalid-country-id');
     * } catch (error) {
     *   if (error.response?.status === 404) {
     *     console.log('Country not found');
     *   } else if (error.response?.status === 400) {
     *     console.log('Invalid request parameters:', error.response.data.errors);
     *   } else if (error.response?.status === 403) {
     *     console.log('Access denied - insufficient permissions');
     *   } else {
     *     console.log('Request failed:', error.message);
     *   }
     * }
     */
    listRegions(countryId: string, options?: QueryUtilOptions, allPages?: boolean): Promise<BaseListResponse<RegionResource>>;
    /**
     * Get a specific region for a country
     *
     * Retrieves detailed information about a specific administrative region within
     * a country. This provides precise geographic data for location tracking,
     * including state/province codes, full names, and other regional identifiers
     * used in address management and asset location tracking.
     *
     * @param {string} countryId - Country ID (required)
     * @param {string} regionId - Region ID (required)
     * @param {QueryParams} [params] - Optional query parameters
     * @returns {Promise<BaseItemResponse<RegionResource>>} Region resource for the country
     * @throws {Error} When country not found (404) or region not found (404)
     * @example
     * // Basic usage - get a specific region (e.g., California in the US)
     * const region = await client.countries.getRegion('1', '2');
     * console.log('Region name:', region.data.attributes.name);
     * console.log('Abbreviation:', region.data.attributes.abbreviation);
     * console.log('Region code:', region.data.attributes.code);
     *
     * @example
     * // Get region with related country information
     * const regionWithCountry = await client.countries.getRegion('1', '2', {
     *   include: ['country']
     * });
     *
     * // Access included data
     * const included = regionWithCountry.included || [];
     * const country = included.find(item => item.type === 'countries');
     *
     * console.log(`Region: ${regionWithCountry.data.attributes.name}`);
     * console.log(`Country: ${country?.attributes.name || 'Unknown'}`);
     * console.log(`Full location: ${regionWithCountry.data.attributes.name}, ${country?.attributes.name || 'Unknown'}`);
     *
     * @example
     * // Error handling for region retrieval
     * try {
     *   const region = await client.countries.getRegion('1', 'invalid-region-id');
     * } catch (error) {
     *   if (error.response?.status === 404) {
     *     console.log('Country or region not found');
     *   } else if (error.response?.status === 403) {
     *     console.log('Access denied - insufficient permissions');
     *   } else {
     *     console.log('Error retrieving region:', error.message);
     *   }
     * }
     *
     * @example
     * // Safe get region for address validation
     * async function safeGetRegion(countryId, regionId) {
     *   try {
     *     const region = await client.countries.getRegion(countryId, regionId);
     *     return {
     *       id: region.data.id,
     *       name: region.data.attributes.name,
     *       abbreviation: region.data.attributes.abbreviation,
     *       code: region.data.attributes.code,
     *       countryId: countryId
     *     };
     *   } catch (error) {
     *     if (error.response?.status === 404) {
     *       return null; // Country or region doesn't exist
     *     }
     *     throw error; // Re-throw other errors
     *   }
     * }
     *
     * @example
     * // Validate address components using country and region data
     * async function validateAddressLocation(countryId, regionId) {
     *   try {
     *     // Get both country and region information
     *     const [country, region] = await Promise.all([
     *       client.countries.get(countryId),
     *       client.countries.getRegion(countryId, regionId)
     *     ]);
     *
     *     return {
     *       valid: true,
     *       location: {
     *         country: country.data.attributes.name,
     *         countryCode: country.data.attributes.iso,
     *         region: region.data.attributes.name,
     *         regionCode: region.data.attributes.abbreviation
     *       }
     *     };
     *   } catch (error) {
     *     return {
     *       valid: false,
     *       error: error.response?.status === 404 ? 'Invalid country or region' : error.message
     *     };
     *   }
     * }
     */
    getRegion(countryId: string, regionId: string, params?: QueryParams): Promise<BaseItemResponse<RegionResource>>;
}