@countrydataapi/sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,562 @@
+/**
+ * Common types for Country Data API SDK
+ */
+type Language = 'en' | 'es' | 'pt' | 'fr' | 'de' | 'it';
+interface ApiResponse<T> {
+    success: boolean;
+    data: T[];
+    count: number;
+    tokens_used: number;
+    remaining_tokens?: number;
+    cost_per_item?: number;
+}
+interface ApiError {
+    error: boolean;
+    message: string;
+}
+interface RequestOptions {
+    fields?: string;
+    lang?: Language;
+    limit?: number;
+    limitToken?: number;
+    [key: string]: unknown;
+}
+interface StatusResponse {
+    remainingTokens: number;
+}
+
+/**
+ * Country types for Country Data API SDK
+ */
+interface Currency {
+    currency: string;
+    name: string;
+    symbol: string;
+}
+interface CountryLanguage {
+    language: string;
+    name: string;
+}
+interface Translation {
+    translation: string;
+    official: string;
+    common: string;
+}
+interface CarInfo {
+    signs: string[];
+    side: string;
+}
+interface CapitalInfo {
+    lat: string;
+    lng: string;
+}
+interface IddInfo {
+    root: string;
+    suffixes: string[];
+}
+interface Gini {
+    year: string;
+    value: string;
+}
+interface Demonym {
+    lang: string;
+    f: string;
+    m: string;
+}
+interface Country {
+    id: string;
+    lang: string;
+    country_name: string;
+    country_short_iso?: string;
+    country_phone_code?: string;
+    country_cca2?: string;
+    country_ccn3?: string;
+    country_cca3?: string;
+    country_cioc?: string;
+    country_independent?: boolean;
+    country_status?: string;
+    country_unMember?: boolean;
+    country_capital?: string[];
+    country_altSpellings?: string[];
+    country_region?: string;
+    country_subregion?: string;
+    country_latLng?: string[];
+    country_landlocked?: boolean;
+    country_borders?: string[];
+    country_area?: string;
+    country_flag?: string;
+    country_map_googleMaps?: string;
+    country_map_openStreetMaps?: string;
+    country_population?: string;
+    country_fifa?: string;
+    country_timezones?: string[];
+    country_continents?: string[];
+    country_flag_png?: string;
+    country_flag_svg?: string;
+    country_flag_alt?: string;
+    country_coatOfArms_png?: string;
+    country_coatOfArms_svg?: string;
+    country_startofWeek?: string;
+    country_postal_code_format?: string;
+    country_postal_code_regex?: string;
+    country_continent_code?: string;
+    country_tld?: string[];
+    country_currencies?: Currency[];
+    country_languages?: CountryLanguage[];
+    country_translations?: Translation[];
+    country_car_info?: CarInfo;
+    country_capital_info?: CapitalInfo[];
+    country_gini?: Gini;
+    country_demonyms?: Demonym[];
+    country_name_additional_info?: Record<string, unknown>;
+    country_idd_info?: IddInfo;
+    country_current_currency?: string;
+    country_GDP?: string;
+    country_GDP_per_capita_PPP?: string;
+    country_location?: string;
+    country_land?: string;
+    country_terrain?: string;
+    country_climate?: string;
+    country_natural_hazards?: string;
+    country_note?: string;
+    country_history?: string;
+    country_life_expectancy?: string;
+    country_median_age?: string;
+    country_birth_rate?: string;
+    country_death_rate?: string;
+    country_sex_ratio?: string;
+    country_literacy?: string;
+    country_roadways?: string;
+    country_airports?: string;
+    country_railways?: string;
+    country_waterways?: string;
+    country_heliports?: string;
+    country_airports_paved?: string;
+    country_wikipedia_url?: string;
+}
+
+/**
+ * State types for Country Data API SDK
+ */
+interface State {
+    id: string;
+    lang: string;
+    state_name: string;
+    state_cities?: string[];
+    state_zip_codes?: string[];
+}
+
+/**
+ * City types for Country Data API SDK
+ */
+interface City {
+    id: string;
+    lang: string;
+    city_name: string;
+}
+
+/**
+ * Zipcode types for Country Data API SDK
+ */
+interface Zipcode {
+    id: string;
+    lang: string;
+    zipcode: string;
+}
+
+/**
+ * Select types for Country Data API SDK
+ * Optimized lightweight responses for dropdowns
+ */
+interface SelectCountry {
+    id: string;
+    name: string;
+    code: string;
+    phone_code: string;
+    flag: string;
+}
+interface SelectState {
+    id: string;
+    name: string;
+}
+interface SelectCity {
+    id: string;
+    name: string;
+}
+
+/**
+ * HTTP client for Country Data API SDK
+ */
+interface HttpClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: HttpClientConfig);
+    get<T>(endpoint: string, params?: Record<string, unknown>): Promise<T>;
+    private buildUrl;
+    private handleError;
+    private handleApiError;
+}
+
+/**
+ * Countries resource for Country Data API SDK
+ */
+
+interface GetCountryByNameOptions extends RequestOptions {
+    name: string;
+}
+interface GetCountryByCodeOptions extends RequestOptions {
+    code: string;
+}
+interface GetCountriesByRegionOptions extends RequestOptions {
+    region: string;
+}
+interface GetCountriesByCurrencyOptions extends RequestOptions {
+    currency: string;
+}
+interface GetCountriesByLanguageOptions extends RequestOptions {
+    language: string;
+}
+interface GetCountriesByTimezoneOptions extends RequestOptions {
+    timezone: string;
+}
+interface GetCountriesByStateOptions extends RequestOptions {
+    state: string;
+}
+interface GetCountriesByCityOptions extends RequestOptions {
+    city: string;
+}
+interface GetCountriesByZipCodeOptions extends RequestOptions {
+    zipCode: string;
+}
+declare class Countries {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get all countries
+     * @example
+     * const countries = await api.countries.getAll({ lang: 'es', limit: 50 });
+     */
+    getAll(options?: RequestOptions): Promise<ApiResponse<Country>>;
+    /**
+     * Get country by name
+     * @example
+     * const spain = await api.countries.getByName({ name: 'Spain' });
+     */
+    getByName(options: GetCountryByNameOptions): Promise<ApiResponse<Country>>;
+    /**
+     * Get country by ISO code (alpha-2, alpha-3, numeric, or CIOC)
+     * @example
+     * const spain = await api.countries.getByCode({ code: 'ES' });
+     */
+    getByCode(options: GetCountryByCodeOptions): Promise<ApiResponse<Country>>;
+    /**
+     * Get countries by region
+     * @example
+     * const european = await api.countries.getByRegion({ region: 'Europe' });
+     */
+    getByRegion(options: GetCountriesByRegionOptions): Promise<ApiResponse<Country>>;
+    /**
+     * Get countries by currency code
+     * @example
+     * const euroCountries = await api.countries.getByCurrency({ currency: 'EUR' });
+     */
+    getByCurrency(options: GetCountriesByCurrencyOptions): Promise<ApiResponse<Country>>;
+    /**
+     * Get countries by language
+     * @example
+     * const spanishSpeaking = await api.countries.getByLanguage({ language: 'spa' });
+     */
+    getByLanguage(options: GetCountriesByLanguageOptions): Promise<ApiResponse<Country>>;
+    /**
+     * Get countries by timezone
+     * @example
+     * const utcCountries = await api.countries.getByTimezone({ timezone: 'UTC' });
+     */
+    getByTimezone(options: GetCountriesByTimezoneOptions): Promise<ApiResponse<Country>>;
+    /**
+     * Get countries by state
+     * @example
+     * const countries = await api.countries.getByState({ state: 'California' });
+     */
+    getByState(options: GetCountriesByStateOptions): Promise<ApiResponse<Country>>;
+    /**
+     * Get countries by city
+     * @example
+     * const countries = await api.countries.getByCity({ city: 'Madrid' });
+     */
+    getByCity(options: GetCountriesByCityOptions): Promise<ApiResponse<Country>>;
+    /**
+     * Get countries by zip code
+     * @example
+     * const countries = await api.countries.getByZipCode({ zipCode: '28001' });
+     */
+    getByZipCode(options: GetCountriesByZipCodeOptions): Promise<ApiResponse<Country>>;
+}
+
+/**
+ * States resource for Country Data API SDK
+ */
+
+interface GetStateByNameOptions extends RequestOptions {
+    state: string;
+}
+interface GetStatesByCountryOptions extends RequestOptions {
+    country: string;
+}
+interface GetStatesByCityOptions extends RequestOptions {
+    city: string;
+}
+interface GetStatesByZipcodeOptions extends RequestOptions {
+    zipcode: string;
+}
+declare class States {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get all states
+     * @example
+     * const states = await api.states.getAll({ lang: 'es' });
+     */
+    getAll(options?: RequestOptions & {
+        limitStates?: number;
+    }): Promise<ApiResponse<State>>;
+    /**
+     * Get state by name
+     * @example
+     * const state = await api.states.getByName({ state: 'Madrid' });
+     */
+    getByName(options: GetStateByNameOptions): Promise<ApiResponse<State>>;
+    /**
+     * Get states by country
+     * @example
+     * const spanishStates = await api.states.getByCountry({ country: 'Spain' });
+     */
+    getByCountry(options: GetStatesByCountryOptions): Promise<ApiResponse<State>>;
+    /**
+     * Get states by city
+     * @example
+     * const states = await api.states.getByCity({ city: 'Madrid' });
+     */
+    getByCity(options: GetStatesByCityOptions): Promise<ApiResponse<State>>;
+    /**
+     * Get states by zipcode
+     * @example
+     * const states = await api.states.getByZipcode({ zipcode: '28001' });
+     */
+    getByZipcode(options: GetStatesByZipcodeOptions): Promise<ApiResponse<State>>;
+}
+
+/**
+ * Cities resource for Country Data API SDK
+ */
+
+interface GetCityOptions extends RequestOptions {
+    city: string;
+}
+interface GetCitiesByCountryOptions extends RequestOptions {
+    country: string;
+}
+interface GetCitiesByStateOptions extends RequestOptions {
+    state: string;
+}
+declare class Cities {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get all cities
+     * @example
+     * const cities = await api.cities.getAll({ lang: 'es', limitToken: 100 });
+     */
+    getAll(options?: RequestOptions): Promise<ApiResponse<City>>;
+    /**
+     * Get city by name or ID
+     * @example
+     * const city = await api.cities.get({ city: 'Madrid' });
+     */
+    get(options: GetCityOptions): Promise<ApiResponse<City>>;
+    /**
+     * Get cities by country
+     * @example
+     * const cities = await api.cities.getByCountry({ country: 'Spain' });
+     */
+    getByCountry(options: GetCitiesByCountryOptions): Promise<ApiResponse<City>>;
+    /**
+     * Get cities by state
+     * @example
+     * const cities = await api.cities.getByState({ state: 'Madrid' });
+     */
+    getByState(options: GetCitiesByStateOptions): Promise<ApiResponse<City>>;
+}
+
+/**
+ * Zipcodes resource for Country Data API SDK
+ */
+
+interface GetZipcodesByStateOptions extends RequestOptions {
+    state: string;
+}
+interface GetZipcodesByCountryOptions extends RequestOptions {
+    country: string;
+}
+interface GetZipcodesByRegionOptions extends RequestOptions {
+    region: string;
+}
+declare class Zipcodes {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get all zipcodes
+     * @example
+     * const zipcodes = await api.zipcodes.getAll({ limitToken: 100 });
+     */
+    getAll(options?: RequestOptions): Promise<ApiResponse<string>>;
+    /**
+     * Get zipcodes by state
+     * @example
+     * const zipcodes = await api.zipcodes.getByState({ state: 'Madrid' });
+     */
+    getByState(options: GetZipcodesByStateOptions): Promise<ApiResponse<string>>;
+    /**
+     * Get zipcodes by country
+     * @example
+     * const zipcodes = await api.zipcodes.getByCountry({ country: 'Spain' });
+     */
+    getByCountry(options: GetZipcodesByCountryOptions): Promise<ApiResponse<string>>;
+    /**
+     * Get zipcodes by region
+     * @example
+     * const zipcodes = await api.zipcodes.getByRegion({ region: 'Europe' });
+     */
+    getByRegion(options: GetZipcodesByRegionOptions): Promise<ApiResponse<string>>;
+}
+
+/**
+ * Select resource for Country Data API SDK
+ * Optimized endpoints for dropdowns (costs only 1 token)
+ */
+
+interface SelectCountriesOptions {
+    lang?: Language;
+    [key: string]: unknown;
+}
+interface SelectStatesOptions {
+    country: string;
+    lang?: Language;
+    [key: string]: unknown;
+}
+interface SelectCitiesOptions {
+    state: string;
+    country?: string;
+    lang?: Language;
+    [key: string]: unknown;
+}
+declare class Select {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get countries optimized for select/dropdown (costs 1 token)
+     * @example
+     * const countries = await api.select.countries({ lang: 'es' });
+     */
+    countries(options?: SelectCountriesOptions): Promise<ApiResponse<SelectCountry>>;
+    /**
+     * Get states for a country optimized for select/dropdown (costs 1 token)
+     * @example
+     * const states = await api.select.states({ country: 'ES' });
+     */
+    states(options: SelectStatesOptions): Promise<ApiResponse<SelectState>>;
+    /**
+     * Get cities for a state optimized for select/dropdown (costs 1 token)
+     * @example
+     * const cities = await api.select.cities({ state: 'Madrid', country: 'ES' });
+     */
+    cities(options: SelectCitiesOptions): Promise<ApiResponse<SelectCity>>;
+}
+
+/**
+ * Main client for Country Data API SDK
+ */
+
+interface CountryDataApiConfig {
+    /**
+     * Your API key from countrydataapi.com
+     */
+    apiKey: string;
+    /**
+     * Base URL for the API (default: https://api.countrydataapi.com)
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds (default: 30000)
+     */
+    timeout?: number;
+    /**
+     * Default language for responses (default: 'en')
+     */
+    defaultLanguage?: Language;
+}
+declare class CountryDataApi {
+    private readonly http;
+    private readonly config;
+    /**
+     * Countries resource - query country data
+     */
+    readonly countries: Countries;
+    /**
+     * States resource - query state/province data
+     */
+    readonly states: States;
+    /**
+     * Cities resource - query city data
+     */
+    readonly cities: Cities;
+    /**
+     * Zipcodes resource - query postal code data
+     */
+    readonly zipcodes: Zipcodes;
+    /**
+     * Select resource - optimized endpoints for dropdowns (1 token each)
+     */
+    readonly select: Select;
+    /**
+     * Create a new Country Data API client
+     * @example
+     * const api = new CountryDataApi({ apiKey: 'your-api-key' });
+     * const countries = await api.countries.getAll({ lang: 'es' });
+     */
+    constructor(config: CountryDataApiConfig);
+    /**
+     * Get remaining tokens for your API key
+     * @example
+     * const status = await api.getStatus();
+     * console.log(`Remaining tokens: ${status.remainingTokens}`);
+     */
+    getStatus(): Promise<StatusResponse>;
+}
+
+/**
+ * Error classes for Country Data API SDK
+ */
+declare class CountryDataApiError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly response?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
+}
+declare class AuthenticationError extends CountryDataApiError {
+    constructor(message?: string);
+}
+declare class RateLimitError extends CountryDataApiError {
+    constructor(message?: string);
+}
+declare class InsufficientTokensError extends CountryDataApiError {
+    constructor(message?: string);
+}
+declare class ValidationError extends CountryDataApiError {
+    constructor(message: string);
+}
+
+export { type ApiError, type ApiResponse, AuthenticationError, type CapitalInfo, type CarInfo, type City, type Country, CountryDataApi, type CountryDataApiConfig, CountryDataApiError, type CountryLanguage, type Currency, type Demonym, type GetCitiesByCountryOptions, type GetCitiesByStateOptions, type GetCityOptions, type GetCountriesByCurrencyOptions, type GetCountriesByLanguageOptions, type GetCountriesByRegionOptions, type GetCountriesByTimezoneOptions, type GetCountryByCodeOptions, type GetCountryByNameOptions, type GetStateByNameOptions, type GetStatesByCityOptions, type GetStatesByCountryOptions, type GetStatesByZipcodeOptions, type GetZipcodesByCountryOptions, type GetZipcodesByRegionOptions, type GetZipcodesByStateOptions, type Gini, type IddInfo, InsufficientTokensError, type Language, RateLimitError, type RequestOptions, type SelectCitiesOptions, type SelectCity, type SelectCountriesOptions, type SelectCountry, type SelectState, type SelectStatesOptions, type State, type StatusResponse, type Translation, ValidationError, type Zipcode };