/**
 * Core TypeScript interfaces and types for OpenCage Geocoding API
 * Provides comprehensive typing for all API responses and requests
 */
/**
 * Coordinate pair representing latitude and longitude
 */
export interface Coordinates {
    /** Latitude in decimal degrees */
    lat: number;
    /** Longitude in decimal degrees */
    lng: number;
}
/**
 * Bounding box coordinates
 */
export interface BoundingBox {
    /** Southwest corner coordinates */
    southwest: Coordinates;
    /** Northeast corner coordinates */
    northeast: Coordinates;
}
/**
 * Geometry information from geocoding response
 */
export interface Geometry {
    /** Latitude in decimal degrees */
    lat: number;
    /** Longitude in decimal degrees */
    lng: number;
}
/**
 * Component parts of an address
 */
export interface AddressComponents {
    /** ISO 3166-1 alpha-2 country code */
    'ISO_3166-1_alpha-2'?: string;
    /** ISO 3166-1 alpha-3 country code */
    'ISO_3166-1_alpha-3'?: string;
    /** ISO 3166-2 subdivision code */
    'ISO_3166-2'?: string[];
    /** Building name */
    building?: string;
    /** City name */
    city?: string;
    /** City district */
    city_district?: string;
    /** Continent name */
    continent?: string;
    /** Country name */
    country?: string;
    /** Country code (2-letter) */
    country_code?: string;
    /** County name */
    county?: string;
    /** House number */
    house_number?: string;
    /** Neighbourhood */
    neighbourhood?: string;
    /** Political entity */
    political_union?: string;
    /** Postal code */
    postcode?: string;
    /** Road/street name */
    road?: string;
    /** State name */
    state?: string;
    /** State code */
    state_code?: string;
    /** State district */
    state_district?: string;
    /** Suburb */
    suburb?: string;
    /** Village */
    village?: string;
    /** Town */
    town?: string;
    /** Region */
    region?: string;
    /** Partial postcode */
    partial_postcode?: string;
    [key: string]: string | string[] | undefined;
}
/**
 * Annotation data with additional information
 */
export interface Annotations {
    /** DMS (Degrees, Minutes, Seconds) coordinates */
    DMS?: {
        lat: string;
        lng: string;
    };
    /** MGRS (Military Grid Reference System) */
    MGRS?: string;
    /** Maidenhead locator */
    Maidenhead?: string;
    /** Mercator projection coordinates */
    Mercator?: {
        x: number;
        y: number;
    };
    /** Open Street Map data */
    OSM?: {
        edit_url?: string;
        note_url?: string;
        url?: string;
    };
    /** UN M.49 codes */
    'UN_M49'?: {
        regions?: {
            [key: string]: string;
        };
        statistical_groupings?: string[];
    };
    /** Calling code */
    callingcode?: number;
    /** Currency information */
    currency?: {
        alternate_symbols?: string[];
        decimal_mark?: string;
        disambiguate_symbol?: string;
        html_entity?: string;
        iso_code?: string;
        iso_numeric?: string;
        name?: string;
        smallest_denomination?: number;
        subunit?: string;
        subunit_to_unit?: number;
        symbol?: string;
        symbol_first?: number;
        thousands_separator?: string;
    };
    /** Flag emoji */
    flag?: string;
    /** Geohash */
    geohash?: string;
    /** QIBLA direction */
    qibla?: number;
    /** Roadinfo */
    roadinfo?: {
        drive_on?: string;
        road?: string;
        speed_in?: string;
    };
    /** Sun information */
    sun?: {
        rise?: {
            apparent?: number;
            astronomical?: number;
            civil?: number;
            nautical?: number;
        };
        set?: {
            apparent?: number;
            astronomical?: number;
            civil?: number;
            nautical?: number;
        };
    };
    /** Timezone information */
    timezone?: {
        name?: string;
        now_in_dst?: number;
        offset_sec?: number;
        offset_string?: string;
        short_name?: string;
    };
    /** What3Words */
    what3words?: {
        words?: string;
    };
    /** Wikidata ID */
    wikidata?: string;
}
/**
 * Individual geocoding result
 */
export interface GeocodingResult {
    /** Address components */
    components: AddressComponents;
    /** Confidence score (0-10) */
    confidence: number;
    /** Formatted address string */
    formatted: string;
    /** Geographic coordinates */
    geometry: Geometry;
    /** Additional annotations */
    annotations?: Annotations;
    /** Bounding box */
    bounds?: BoundingBox;
}
/**
 * Rate limit information
 */
export interface RateLimit {
    /** Maximum requests allowed */
    limit: number;
    /** Remaining requests */
    remaining: number;
    /** Reset timestamp */
    reset: number;
}
/**
 * Request status information
 */
export interface Status {
    /** Status code */
    code: number;
    /** Status message */
    message: string;
}
/**
 * Full geocoding API response
 */
export interface GeocodingResponse {
    /** Documentation URL */
    documentation: string;
    /** Array of results */
    results: GeocodingResult[];
    /** Request status */
    status: Status;
    /** Stay updated information */
    stay_updated: string;
    /** Thanks message */
    thanks: string;
    /** Timestamp of request */
    timestamp: {
        created_http: string;
        created_unix: number;
    };
    /** Total number of results */
    total_results: number;
    /** We're hiring message */
    we_are_hiring?: string;
    /** Rate limit information */
    rate?: RateLimit;
    /** Licenses information */
    licenses?: Array<{
        name: string;
        url: string;
    }>;
}
/**
 * Batch geocoding request item
 */
export interface BatchGeocodingRequest {
    /** Query string */
    query: string;
    /** Optional parameters for this specific request */
    options?: Partial<GeocodingRequestOptions>;
}
/**
 * Batch geocoding response
 */
export interface BatchGeocodingResponse {
    /** Array of responses */
    responses: GeocodingResponse[];
    /** Request metadata */
    metadata: {
        /** Total requests processed */
        total_requests: number;
        /** Processing time in milliseconds */
        processing_time: number;
    };
}
/**
 * Forward geocoding request options
 */
export interface ForwardGeocodingOptions {
    /** Restrict to specific country codes */
    countrycode?: string | string[];
    /** Language for results */
    language?: string;
    /** Maximum number of results */
    limit?: number;
    /** Minimum confidence level */
    min_confidence?: number;
    /** No annotations flag */
    no_annotations?: boolean;
    /** No deduplication flag */
    no_dedupe?: boolean;
    /** No records flag */
    no_record?: boolean;
    /** Pretty print flag */
    pretty?: boolean;
    /** Restrict to bounds */
    bounds?: string;
    /** Proximity bias */
    proximity?: string;
    /** Roadinfo flag */
    roadinfo?: boolean;
    /** Add request flag */
    add_request?: boolean;
    /** Use abbreviated address format */
    abbrv?: boolean;
}
/**
 * Reverse geocoding request options
 */
export interface ReverseGeocodingOptions {
    /** Language for results */
    language?: string;
    /** No annotations flag */
    no_annotations?: boolean;
    /** No record flag */
    no_record?: boolean;
    /** Pretty print flag */
    pretty?: boolean;
    /** Roadinfo flag */
    roadinfo?: boolean;
    /** Add request flag */
    add_request?: boolean;
    /** Use abbreviated address format */
    abbrv?: boolean;
}
/**
 * General geocoding request options
 */
export declare type GeocodingRequestOptions = ForwardGeocodingOptions | ReverseGeocodingOptions;
/**
 * OpenCage SDK Configuration
 */
export interface OpenCageConfig {
    /** API key for OpenCage service */
    apiKey: string;
    /** Base API URL */
    baseUrl?: string;
    /** Default language */
    defaultLanguage?: string;
    /** Enable caching */
    enableCaching?: boolean;
    /** Cache TTL in milliseconds */
    cacheTtl?: number;
    /** Enable rate limiting */
    enableRateLimit?: boolean;
    /** Requests per second limit */
    rateLimit?: number;
    /** Timeout in milliseconds */
    timeout?: number;
    /** Retry attempts */
    retryAttempts?: number;
    /** Retry delay in milliseconds */
    retryDelay?: number;
    /** Enable debug mode */
    debug?: boolean;
}
/**
 * Cache entry structure
 */
export interface CacheEntry<T> {
    /** Cached data */
    data: T;
    /** Timestamp when cached */
    timestamp: number;
    /** TTL in milliseconds */
    ttl: number;
}
/**
 * Error types from OpenCage API
 */
export declare enum OpenCageErrorType {
    /** Network or connection error */
    NETWORK_ERROR = "NETWORK_ERROR",
    /** Authentication failed */
    AUTH_ERROR = "AUTH_ERROR",
    /** Rate limit exceeded */
    RATE_LIMIT_ERROR = "RATE_LIMIT_ERROR",
    /** Invalid request */
    REQUEST_ERROR = "REQUEST_ERROR",
    /** Server error */
    SERVER_ERROR = "SERVER_ERROR",
    /** Timeout error */
    TIMEOUT_ERROR = "TIMEOUT_ERROR",
    /** No results found */
    NO_RESULTS = "NO_RESULTS",
    /** Invalid API key */
    INVALID_API_KEY = "INVALID_API_KEY",
    /** Quota exceeded */
    QUOTA_EXCEEDED = "QUOTA_EXCEEDED",
    /** Unknown error */
    UNKNOWN_ERROR = "UNKNOWN_ERROR"
}
/**
 * OpenCage specific error details
 */
export interface OpenCageErrorDetails {
    /** Error type */
    type: OpenCageErrorType;
    /** Error message */
    message: string;
    /** HTTP status code */
    statusCode?: number;
    /** API response status */
    apiStatus?: Status;
    /** Rate limit information if applicable */
    rateLimit?: RateLimit;
    /** Original error object */
    originalError?: any;
    /** Request that caused the error */
    request?: {
        query: string;
        options?: any;
    };
}