import { ITGlueClient } from '../client';
import { QueryUtilOptions, QueryParams, BaseListResponse, BaseItemResponse, RegionResource } from '../types';
/**
 * Regions resource module for IT Glue API
 *
 * Provides methods to interact with the /regions endpoint.
 * Regions represent administrative subdivisions within countries, such as states,
 * provinces, territories, or other geographic divisions. They provide detailed
 * location data for precise address management and asset tracking within countries.
 * Regions are essential for accurate location-based information in contact addresses,
 * organization locations, and asset deployment tracking.
 *
 * **Note: This is a read-only resource.** Regions cannot be created, updated, or
 * deleted through the API as they are maintained as standardized geographic
 * reference data by IT Glue. The region data is synchronized with international
 * geographic standards and country-specific administrative divisions.
 *
 * Regions are typically referenced by:
 * - Countries (parent geographic entity)
 * - Organizations (office and facility locations)
 * - Contacts (detailed address information)
 * - Locations (physical site addresses)
 * - Assets (deployment and datacenter locations)
 *
 * Common examples include:
 * - US States: California (CA), New York (NY), Texas (TX)
 * - Canadian Provinces: Ontario (ON), British Columbia (BC), Quebec (QC)
 * - Australian States: New South Wales (NSW), Victoria (VIC), Queensland (QLD)
 * - UK Countries: England, Scotland, Wales, Northern Ireland
 *
 * ## Related Resources
 * Regions are commonly used with:
 * - {@link Countries} - Parent countries that contain regions
 * - {@link Locations} - Physical sites and facilities located in specific regions
 * - {@link Organizations} - Organizations with offices or facilities in regions
 * - {@link Contacts} - People with addresses in specific regions
 * - {@link Configurations} - IT assets deployed in specific regions
 * - {@link Documents} - Documentation related to region-specific operations
 * - {@link FlexibleAssets} - Custom tracking of region-specific data and compliance
 * - {@link RelatedItems} - Create relationships between regions and other resources
 * - {@link Tags} - Categorize resources by regional characteristics
 *
 * @see {@link Countries.listRegions} for retrieving regions within countries
 * @see {@link Countries.getRegion} for retrieving specific regions
 * @see {@link Locations#list} for retrieving locations in specific regions
 * @see {@link Organizations#list} for retrieving organizations by region
 * @see {@link Contacts#list} for retrieving contacts by region
 *
 * @example
 * import { ITGlueClient } from '../client';
 * import { Regions } from './resources/regions';
 *
 * const client = new ITGlueClient({ apiKey: 'your-api-key' });
 * const regions = new Regions(client);
 *
 * // List regions
 * const list = await regions.list();
 *
 * // Get a single region
 * const region = await regions.get('1');
 *
 * // List regions for a specific country
 * const filtered = await regions.list({
 *   filter: { country_id: '1' }
 * });
 *
 * @category Reference Data
 */
export declare class Regions {
    private client;
    private basePath;
    private paginationUtil;
    /**
     * Create a Regions resource instance
     * @param {ITGlueClient} client - ITGlueClient instance
     */
    constructor(client: ITGlueClient);
    /**
     * List all regions
     *
     * Retrieves a list of all administrative regions available in IT Glue. Regions
     * are read-only reference data representing geographic subdivisions within countries
     * (states, provinces, territories). This data is standardized and maintained by
     * IT Glue for accurate location-based information throughout the system.
     *
     * @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 and pagination metadata
     * @example
     * // Basic usage - get first page of regions
     * const results = await client.regions.list();
     * console.log(`Found ${results.data.length} regions`);
     * console.log('Total pages:', results.meta.pagination.total_pages);
     *
     * @example
     * // Advanced usage with country filtering and sorting
     * const usStates = await client.regions.list({
     *   filter: { country_id: '1' }, // United States
     *   sort: 'name',
     *   page: { number: 1, size: 50 },
     *   include: ['country']
     * });
     *
     * console.log('US States and territories:');
     * usStates.data.forEach(region => {
     *   console.log(`${region.attributes.name} (${region.attributes.iso_code})`);
     * });
     *
     * @example
     * // Filter regions by name pattern for address validation
     * const californiaRegions = await client.regions.list({
     *   filter: { name: 'California' },
     *   include: ['country']
     * });
     *
     * if (californiaRegions.data.length > 0) {
     *   const california = californiaRegions.data[0];
     *   console.log(`Found: ${california.attributes.name} (${california.attributes.iso_code})`);
     *   console.log(`Country: ${california.relationships?.country?.data?.id}`);
     * }
     *
     * @example
     * // Get all regions with country grouping for location management
     * const allRegions = await client.regions.list({}, true); // allPages = true
     *
     * // Group regions by country for location dropdown
     * const regionsByCountry = {};
     * allRegions.data.forEach(region => {
     *   const countryId = region.relationships?.country?.data?.id;
     *   if (!regionsByCountry[countryId]) {
     *     regionsByCountry[countryId] = [];
     *   }
     *   regionsByCountry[countryId].push({
     *     id: region.id,
     *     name: region.attributes.name,
     *     code: region.attributes.iso_code
     *   });
     * });
     *
     * console.log('Regions grouped by country:', Object.keys(regionsByCountry).length);
     *
     * @example
     * // Manual pagination for large region datasets
     * async function getAllRegionsWithDetails() {
     *   let page = 1;
     *   let allRegions = [];
     *   let hasMore = true;
     *
     *   while (hasMore) {
     *     const response = await client.regions.list({
     *       page: { number: page, size: 100 },
     *       include: ['country'],
     *       sort: 'name'
     *     });
     *
     *     allRegions = [...allRegions, ...response.data];
     *     hasMore = response.meta.pagination.total_pages > page;
     *     page++;
     *
     *     console.log(`Loaded page ${page - 1}, total regions: ${allRegions.length}`);
     *   }
     *
     *   return allRegions;
     * }
     *
     * @example
     * // Error handling for region listing
     * try {
     *   const regions = await client.regions.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 === 429) {
     *     console.log('Rate limit exceeded - please wait before retrying');
     *   } else {
     *     console.log('Request failed:', error.message);
     *   }
     * }
     */
    list(options?: QueryUtilOptions, allPages?: boolean): Promise<BaseListResponse<RegionResource>>;
    /**
     * Get a single region by ID
     *
     * Retrieves detailed information about a specific administrative region.
     * Regions are read-only reference data that provide precise geographic
     * subdivision information for location tracking, including ISO codes,
     * full names, and country associations used in address management
     * and asset location tracking.
     *
     * @param {string} id - Region ID (required)
     * @param {QueryParams} [params] - Optional query parameters
     * @returns {Promise<BaseItemResponse<RegionResource>>} Region resource
     * @throws {Error} When region not found (404)
     * @example
     * // Basic usage - get region by ID
     * const region = await client.regions.get('123');
     * console.log('Region name:', region.data.attributes.name);
     * console.log('ISO code:', region.data.attributes.iso_code);
     *
     * @example
     * // Get region with country information included
     * const regionWithCountry = await client.regions.get('123', {
     *   include: ['country']
     * });
     *
     * // Access included country data
     * const included = regionWithCountry.included || [];
     * const country = included.find(item => item.type === 'countries');
     * if (country) {
     *   console.log(`${regionWithCountry.data.attributes.name}, ${country.attributes.name}`);
     * }
     *
     * @example
     * // Error handling for region retrieval
     * try {
     *   const region = await client.regions.get('invalid-id');
     * } catch (error) {
     *   if (error.response?.status === 404) {
     *     console.log('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 region lookup with existence check
     * async function safeGetRegion(id) {
     *   try {
     *     const region = await client.regions.get(id, {
     *       include: ['country']
     *     });
     *
     *     return {
     *       id: region.data.id,
     *       name: region.data.attributes.name,
     *       code: region.data.attributes.iso_code,
     *       countryId: region.data.relationships?.country?.data?.id
     *     };
     *   } catch (error) {
     *     if (error.response?.status === 404) {
     *       return null; // Region doesn't exist
     *     }
     *     throw error; // Re-throw other errors
     *   }
     * }
   * @see
   * {@link Countries#get} - Get specific countrie details
   * {@link Countries#list} - List countries related to regions
   * {@link Locations#get} - Get specific location details
   * {@link Locations#list} - List locations related to regions
   
     */
    get(id: string, params?: QueryParams): Promise<BaseItemResponse<RegionResource>>;
}