@forwardslashns/fws-geo-location-api 1.0.0

package/dist/client/geo-location.client.js

@@ -0,0 +1,389 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeoLocationClient = void 0;
+const http_service_js_1 = require("../services/http.service.js");
+const country_mapper_js_1 = require("../mappers/country.mapper.js");
+const region_mapper_js_1 = require("../mappers/region.mapper.js");
+const city_mapper_js_1 = require("../mappers/city.mapper.js");
+const postal_code_mapper_js_1 = require("../mappers/postal-code.mapper.js");
+const api_constants_js_1 = require("../constants/api.constants.js");
+const feature_constants_js_1 = require("../constants/feature.constants.js");
+const geo_location_error_js_1 = require("../errors/geo-location.error.js");
+class GeoLocationClient {
+    httpService;
+    restrictions;
+    /** In-memory cache: ISO2 countryCode → Country. Populated on first full country fetch. */
+    countryCache = new Map();
+    constructor(options) {
+        this.httpService = new http_service_js_1.HttpService(options.usernames);
+        this.restrictions = options.restrictions ?? {};
+    }
+    // ---------------------------------------------------------------------------
+    // Countries
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns a list of countries.
+     *
+     * @param options - Optional per-call overrides for continent and country code filters.
+     *   When omitted the global `restrictions` passed to the constructor are used.
+     */
+    async getCountries(options) {
+        const continents = options?.continents ?? this.restrictions.continents;
+        const countryCodes = options?.countryCodes ?? this.restrictions.countries;
+        let countries;
+        if (continents && continents.length > 0) {
+            const results = await Promise.all(continents.map((continent) => this.fetchCountriesByContinent(continent)));
+            countries = results.flat();
+        }
+        else {
+            countries = await this.fetchAllCountries();
+        }
+        if (countryCodes && countryCodes.length > 0) {
+            const upper = countryCodes.map((c) => c.toUpperCase());
+            countries = countries.filter((c) => upper.includes(c.countryCode));
+        }
+        return countries;
+    }
+    // ---------------------------------------------------------------------------
+    // Regions (states / provinces / prefectures)
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns first-order administrative divisions (states, provinces, etc.)
+     * for the given country.
+     *
+     * @param countryCode - ISO 3166-1 alpha-2 country code, e.g. `"US"`.
+     * @param options - Optional per-call options.
+     */
+    async getRegions(countryCode, options) {
+        this.assertNonEmptyCountryCode(countryCode);
+        const pageSize = options?.maxRows ?? feature_constants_js_1.DEFAULT_MAX_ROWS;
+        const startRow = options?.page != null ? (options.page - 1) * pageSize : (options?.startRow ?? 0);
+        const currentPage = options?.page ?? (options?.startRow != null ? Math.floor(options.startRow / pageSize) + 1 : 1);
+        const params = {
+            country: countryCode.toUpperCase(),
+            featureCode: feature_constants_js_1.FEATURE_CODES.ADM1,
+            maxRows: pageSize,
+            orderby: feature_constants_js_1.GEONAMES_ORDERBY.RELEVANCE,
+            style: feature_constants_js_1.GEONAMES_STYLE.FULL,
+        };
+        if (startRow > 0) {
+            params['startRow'] = startRow;
+        }
+        const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.SEARCH}`, params);
+        const data = raw.geonames.map(region_mapper_js_1.mapRegion);
+        return {
+            data,
+            total: raw.totalResultsCount,
+            page: currentPage,
+            pageSize,
+            hasMore: startRow + data.length < raw.totalResultsCount,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Cities
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns populated places (cities, towns) for the given country,
+     * ordered by population descending.
+     *
+     * @param countryCode - ISO 3166-1 alpha-2 country code, e.g. `"DE"`.
+     * @param options - Optional filters: `regionCode`, `maxRows`, `orderBy`.
+     */
+    async getCities(countryCode, options) {
+        const pageSize = options?.maxRows ?? feature_constants_js_1.DEFAULT_MAX_ROWS;
+        const startRow = options?.page != null ? (options.page - 1) * pageSize : (options?.startRow ?? 0);
+        const currentPage = options?.page ?? (options?.startRow != null ? Math.floor(options.startRow / pageSize) + 1 : 1);
+        const params = {
+            featureClass: feature_constants_js_1.FEATURE_CLASSES.POPULATED_PLACE,
+            maxRows: pageSize,
+            orderby: options?.orderBy ?? feature_constants_js_1.GEONAMES_ORDERBY.POPULATION,
+            style: feature_constants_js_1.GEONAMES_STYLE.FULL,
+        };
+        if (startRow > 0) {
+            params['startRow'] = startRow;
+        }
+        if (countryCode && countryCode.trim().length > 0) {
+            params['country'] = countryCode.trim().toUpperCase();
+        }
+        if (options?.regionCode) {
+            params['adminCode1'] = options.regionCode.toUpperCase();
+        }
+        if (options?.searchTerm && options.searchTerm.trim().length > 0) {
+            params['q'] = options.searchTerm.trim();
+        }
+        const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.SEARCH}`, params);
+        const data = raw.geonames.map(city_mapper_js_1.mapCity);
+        return {
+            data,
+            total: raw.totalResultsCount,
+            page: currentPage,
+            pageSize,
+            hasMore: startRow + data.length < raw.totalResultsCount,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Postal codes
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns postal / zip codes for the given country. Supports optional
+     * prefix and place-name filters.
+     *
+     * Each result includes a `displayName` formatted as:
+     * `"{postalCode} — {placeName}, {adminName1}, {countryName}"`
+     *
+     * @param countryCode - ISO 3166-1 alpha-2 country code, e.g. `"US"`.
+     * @param options - Optional filters: `postalCodePrefix`, `placeName`, `maxRows`, `startRow`, `page`.
+     *
+     * **GeoNames limitation — a filter is required for large countries.**
+     * The underlying GeoNames `postalCodeSearchJSON` endpoint rejects bare country-only
+     * queries for countries with large postal code datasets (e.g. US, DE, FR) by returning
+     * status 15 ("no result found"). Providing either `postalCodePrefix` or `placeName`
+     * always works regardless of country size.
+     *
+     * To retrieve **all** postal codes for a country without knowing a prefix in advance,
+     * use {@link getAllPostalCodes} instead — it handles this constraint transparently by
+     * iterating through alphanumeric prefix buckets and supports a progressive `onProgress`
+     * callback for streaming results into the UI.
+     */
+    async getPostalCodes(countryCode, options) {
+        this.assertNonEmptyCountryCode(countryCode);
+        const upper = countryCode.toUpperCase();
+        const countryName = await this.resolveCountryName(upper);
+        const pageSize = options?.maxRows ?? feature_constants_js_1.DEFAULT_MAX_ROWS;
+        const startRow = options?.page != null ? (options.page - 1) * pageSize : (options?.startRow ?? 0);
+        const currentPage = options?.page ?? (options?.startRow != null ? Math.floor(options.startRow / pageSize) + 1 : 1);
+        const hasFilter = !!(options?.postalCodePrefix || options?.placeName);
+        const params = {
+            country: upper,
+            maxRows: pageSize,
+        };
+        if (startRow > 0) {
+            params['startRow'] = startRow;
+        }
+        if (options?.postalCodePrefix) {
+            params['postalcode_startsWith'] = options.postalCodePrefix;
+        }
+        if (options?.placeName) {
+            params['placename_startsWith'] = options.placeName;
+        }
+        try {
+            const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.POSTAL_CODE_SEARCH}`, params);
+            const data = raw.postalCodes.map((pc) => (0, postal_code_mapper_js_1.mapPostalCode)(pc, countryName));
+            return { data, total: -1, page: currentPage, pageSize, hasMore: data.length === pageSize };
+        }
+        catch (err) {
+            if (err instanceof geo_location_error_js_1.GeoLocationError && err.code === api_constants_js_1.GEONAMES_ERROR_CODES.NO_RESULT_FOUND) {
+                if (!hasFilter) {
+                    // GeoNames rejects bare country-only queries for large datasets.
+                    // Surface a descriptive error so callers understand what went wrong.
+                    throw new geo_location_error_js_1.GeoLocationError(`GeoNames does not support listing postal codes for "${upper}" without a filter — the country's ` +
+                        `dataset is too large for an unfiltered query. ` +
+                        `Provide a "postalCodePrefix" or "placeName" option, or use getAllPostalCodes() to retrieve ` +
+                        `the full dataset via prefix iteration.`, api_constants_js_1.GEONAMES_ERROR_CODES.NO_RESULT_FOUND);
+                }
+                // With a filter, status 15 simply means no matches — return an empty page.
+                return { data: [], total: -1, page: currentPage, pageSize, hasMore: false };
+            }
+            throw err;
+        }
+    }
+    /**
+     * Returns **all** postal codes for the given country by iterating through
+     * alphanumeric prefix buckets (`0–9`, `A–Z`) and paginating each bucket.
+     *
+     * Because GeoNames requires at least one search term, a bare country-only
+     * query always returns status 15. This method works around that constraint
+     * transparently: it fires one request per character prefix (up to 36), each
+     * with `postalcode_startsWith=<char>`, and pages through results in chunks
+     * of 1 000 until the bucket is exhausted. Prefixes that yield no results
+     * (status 15 or empty page) are skipped automatically.
+     *
+     * The results are deduplicated and returned as a single flat array sorted by
+     * postal code.
+     *
+     * **API credit cost**: roughly 1 request per 1 000 postal codes in the
+     * country, spread across up to 36 prefix buckets. For small countries
+     * (< 5 000 codes) expect 10–20 requests; for large ones (US ~43 000) expect
+     * ~80 requests.
+     *
+     * @param countryCode - ISO 3166-1 alpha-2 country code, e.g. `"US"`.
+     */
+    async getAllPostalCodes(countryCode, options) {
+        this.assertNonEmptyCountryCode(countryCode);
+        const upper = countryCode.toUpperCase();
+        const countryName = await this.resolveCountryName(upper);
+        const PREFIXES = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('');
+        const seen = new Set();
+        const all = [];
+        for (const prefix of PREFIXES) {
+            let startRow = 0;
+            while (true) {
+                let page;
+                try {
+                    const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.POSTAL_CODE_SEARCH}`, { country: upper, postalcode_startsWith: prefix, maxRows: feature_constants_js_1.MAX_ROWS_LIMIT, startRow });
+                    page = raw.postalCodes.map((pc) => (0, postal_code_mapper_js_1.mapPostalCode)(pc, countryName));
+                }
+                catch (err) {
+                    if (err instanceof geo_location_error_js_1.GeoLocationError && err.code === api_constants_js_1.GEONAMES_ERROR_CODES.NO_RESULT_FOUND) {
+                        break; // this prefix has no results — move on
+                    }
+                    throw err;
+                }
+                for (const pc of page) {
+                    const key = `${pc.postalCode}|${pc.placeName}|${pc.adminName1}`;
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        all.push(pc);
+                    }
+                }
+                if (page.length < feature_constants_js_1.MAX_ROWS_LIMIT)
+                    break; // last page for this prefix
+                startRow += feature_constants_js_1.MAX_ROWS_LIMIT;
+            }
+            // Notify caller of progress after each prefix bucket
+            if (options?.onProgress && all.length > 0) {
+                all.sort((a, b) => a.postalCode.localeCompare(b.postalCode, undefined, { numeric: true }));
+                options.onProgress(all.slice());
+            }
+        }
+        all.sort((a, b) => a.postalCode.localeCompare(b.postalCode, undefined, { numeric: true }));
+        return all;
+    }
+    /**
+     * Returns one page of postal codes for a country, working around the GeoNames
+     * per-country query limit that prevents retrieving all codes for large
+     * countries (e.g. US) in a single request.
+     *
+     * Internally the library iterates 36 alphanumeric prefix buckets (0–9, A–Z)
+     * and stores progress as an opaque cursor so callers never need to track
+     * offsets themselves.
+     *
+     * **Typical usage**
+     * ```ts
+     * let page = await client.getPostalCodesPage('US', { maxRows: 200 });
+     * while (page.hasMore) {
+     *   // process page.data …
+     *   page = await client.getPostalCodesPage('US', { cursor: page.nextCursor! });
+     * }
+     * // process last page.data …
+     * ```
+     *
+     * **API credit cost**: 1 GeoNames request per call (2 at the boundary
+     * between two prefix buckets). Far cheaper than `getAllPostalCodes` when
+     * you only need the first few pages.
+     *
+     * @param countryCode - ISO 3166-1 alpha-2 country code, e.g. `"US"`.
+     * @param options     - Optional cursor and page-size settings.
+     */
+    async getPostalCodesPage(countryCode, options) {
+        this.assertNonEmptyCountryCode(countryCode);
+        const upper = countryCode.toUpperCase();
+        const countryName = await this.resolveCountryName(upper);
+        const PREFIXES = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('');
+        const pageSize = Math.min(options?.maxRows ?? feature_constants_js_1.DEFAULT_MAX_ROWS, feature_constants_js_1.MAX_ROWS_LIMIT);
+        let prefixIdx = 0;
+        let startRow = 0;
+        if (options?.cursor) {
+            const raw = atob(options.cursor);
+            const colonAt = raw.indexOf(':');
+            prefixIdx = parseInt(raw.substring(0, colonAt), 10);
+            startRow = parseInt(raw.substring(colonAt + 1), 10);
+        }
+        const collected = [];
+        while (collected.length < pageSize && prefixIdx < PREFIXES.length) {
+            const prefix = PREFIXES[prefixIdx];
+            const remaining = pageSize - collected.length;
+            let page;
+            try {
+                const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.POSTAL_CODE_SEARCH}`, { country: upper, postalcode_startsWith: prefix, maxRows: remaining, startRow });
+                page = raw.postalCodes.map((pc) => (0, postal_code_mapper_js_1.mapPostalCode)(pc, countryName));
+            }
+            catch (err) {
+                if (err instanceof geo_location_error_js_1.GeoLocationError && err.code === api_constants_js_1.GEONAMES_ERROR_CODES.NO_RESULT_FOUND) {
+                    // No codes with this prefix — move on
+                    prefixIdx++;
+                    startRow = 0;
+                    continue;
+                }
+                throw err;
+            }
+            collected.push(...page);
+            if (page.length < remaining) {
+                // Prefix exhausted — advance to the next bucket
+                prefixIdx++;
+                startRow = 0;
+            }
+            else {
+                // Filled the page; more may remain in this prefix
+                startRow += page.length;
+                break;
+            }
+        }
+        const exhausted = prefixIdx >= PREFIXES.length;
+        const nextCursor = exhausted ? null : btoa(`${prefixIdx}:${startRow}`);
+        return {
+            data: collected,
+            nextCursor,
+            hasMore: !exhausted,
+            prefixProgress: { done: Math.min(prefixIdx, PREFIXES.length), total: 36 },
+        };
+    }
+    /**
+     * Finds a single postal code by its exact code string within a given country.
+     * Returns `null` when not found.
+     *
+     * @param postalCode - The exact postal / zip code to look up, e.g. `"10001"`.
+     * @param countryCode - ISO 3166-1 alpha-2 country code, e.g. `"US"`.
+     */
+    async findPostalCode(postalCode, countryCode) {
+        this.assertNonEmptyCountryCode(countryCode);
+        if (!postalCode || postalCode.trim().length === 0) {
+            throw new geo_location_error_js_1.GeoLocationError('postalCode must not be empty.');
+        }
+        const upper = countryCode.toUpperCase();
+        const countryName = await this.resolveCountryName(upper);
+        const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.POSTAL_CODE_SEARCH}`, {
+            country: upper,
+            postalcode: postalCode.trim(),
+            maxRows: 1,
+        });
+        if (!raw.postalCodes.length) {
+            return null;
+        }
+        return (0, postal_code_mapper_js_1.mapPostalCode)(raw.postalCodes[0], countryName);
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    async fetchAllCountries() {
+        const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.COUNTRY_INFO}`, {});
+        const countries = raw.geonames.map(country_mapper_js_1.mapCountry);
+        this.cacheCountries(countries);
+        return countries;
+    }
+    async fetchCountriesByContinent(continent) {
+        const raw = await this.httpService.get(`${api_constants_js_1.GEONAMES_BASE_URL}${api_constants_js_1.GEONAMES_ENDPOINTS.COUNTRY_INFO}`, { continent });
+        const countries = raw.geonames.map(country_mapper_js_1.mapCountry);
+        this.cacheCountries(countries);
+        return countries;
+    }
+    cacheCountries(countries) {
+        for (const country of countries) {
+            this.countryCache.set(country.countryCode, country);
+        }
+    }
+    async resolveCountryName(upperCountryCode) {
+        if (this.countryCache.has(upperCountryCode)) {
+            return this.countryCache.get(upperCountryCode).countryName;
+        }
+        const countries = await this.fetchAllCountries();
+        const found = countries.find((c) => c.countryCode === upperCountryCode);
+        return found?.countryName ?? upperCountryCode;
+    }
+    assertNonEmptyCountryCode(countryCode) {
+        if (!countryCode || countryCode.trim().length === 0) {
+            throw new geo_location_error_js_1.GeoLocationError('countryCode must not be empty.');
+        }
+    }
+}
+exports.GeoLocationClient = GeoLocationClient;

package/dist/constants/api.constants.d.ts

@@ -0,0 +1,21 @@
+export declare const GEONAMES_BASE_URL: "https://secure.geonames.org";
+export declare const GEONAMES_ENDPOINTS: {
+    readonly COUNTRY_INFO: "/countryInfoJSON";
+    readonly SEARCH: "/searchJSON";
+    readonly POSTAL_CODE_SEARCH: "/postalCodeSearchJSON";
+};
+export declare const GEONAMES_ERROR_CODES: {
+    readonly AUTHORIZATION_EXCEPTION: 10;
+    readonly RECORD_DOES_NOT_EXIST: 11;
+    readonly OTHER_ERROR: 12;
+    readonly DATABASE_TIMEOUT: 13;
+    readonly INVALID_PARAMETER: 14;
+    readonly NO_RESULT_FOUND: 15;
+    readonly DUPLICATE_EXCEPTION: 16;
+    readonly POST_LIMIT_EXCEEDED: 17;
+    readonly DAILY_LIMIT_EXCEEDED: 18;
+    readonly HOURLY_LIMIT_EXCEEDED: 19;
+    readonly WEEKLY_LIMIT_EXCEEDED: 20;
+};
+export declare const GEONAMES_RATE_LIMIT_CODES: ReadonlyArray<number>;
+//# sourceMappingURL=api.constants.d.ts.map

package/dist/constants/api.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.constants.d.ts","sourceRoot":"","sources":["../../src/constants/api.constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,EAAG,6BAAsC,CAAC;AAExE,eAAO,MAAM,kBAAkB;;;;CAIrB,CAAC;AAEX,eAAO,MAAM,oBAAoB;;;;;;;;;;;;CAYvB,CAAC;AAEX,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,MAAM,CAK3D,CAAC"}

package/dist/constants/api.constants.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GEONAMES_RATE_LIMIT_CODES = exports.GEONAMES_ERROR_CODES = exports.GEONAMES_ENDPOINTS = exports.GEONAMES_BASE_URL = void 0;
+exports.GEONAMES_BASE_URL = 'https://secure.geonames.org';
+exports.GEONAMES_ENDPOINTS = {
+    COUNTRY_INFO: '/countryInfoJSON',
+    SEARCH: '/searchJSON',
+    POSTAL_CODE_SEARCH: '/postalCodeSearchJSON',
+};
+exports.GEONAMES_ERROR_CODES = {
+    AUTHORIZATION_EXCEPTION: 10,
+    RECORD_DOES_NOT_EXIST: 11,
+    OTHER_ERROR: 12,
+    DATABASE_TIMEOUT: 13,
+    INVALID_PARAMETER: 14,
+    NO_RESULT_FOUND: 15,
+    DUPLICATE_EXCEPTION: 16,
+    POST_LIMIT_EXCEEDED: 17,
+    DAILY_LIMIT_EXCEEDED: 18,
+    HOURLY_LIMIT_EXCEEDED: 19,
+    WEEKLY_LIMIT_EXCEEDED: 20,
+};
+exports.GEONAMES_RATE_LIMIT_CODES = [
+    exports.GEONAMES_ERROR_CODES.DAILY_LIMIT_EXCEEDED,
+    exports.GEONAMES_ERROR_CODES.HOURLY_LIMIT_EXCEEDED,
+    exports.GEONAMES_ERROR_CODES.WEEKLY_LIMIT_EXCEEDED,
+    exports.GEONAMES_ERROR_CODES.POST_LIMIT_EXCEEDED,
+];

package/dist/constants/continent.constants.d.ts

@@ -0,0 +1,13 @@
+export declare const CONTINENT_CODES: {
+    readonly AFRICA: "AF";
+    readonly ASIA: "AS";
+    readonly EUROPE: "EU";
+    readonly NORTH_AMERICA: "NA";
+    readonly OCEANIA: "OC";
+    readonly SOUTH_AMERICA: "SA";
+    readonly ANTARCTICA: "AN";
+};
+export declare const CONTINENT_NAMES: Readonly<Record<string, string>>;
+/** Union of all valid GeoNames continent codes. */
+export type ContinentCode = (typeof CONTINENT_CODES)[keyof typeof CONTINENT_CODES];
+//# sourceMappingURL=continent.constants.d.ts.map

package/dist/constants/continent.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"continent.constants.d.ts","sourceRoot":"","sources":["../../src/constants/continent.constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe;;;;;;;;CAQlB,CAAC;AAEX,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQnD,CAAC;AAEX,mDAAmD;AACnD,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC"}

package/dist/constants/continent.constants.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTINENT_NAMES = exports.CONTINENT_CODES = void 0;
+exports.CONTINENT_CODES = {
+    AFRICA: 'AF',
+    ASIA: 'AS',
+    EUROPE: 'EU',
+    NORTH_AMERICA: 'NA',
+    OCEANIA: 'OC',
+    SOUTH_AMERICA: 'SA',
+    ANTARCTICA: 'AN',
+};
+exports.CONTINENT_NAMES = {
+    AF: 'Africa',
+    AS: 'Asia',
+    EU: 'Europe',
+    NA: 'North America',
+    OC: 'Oceania',
+    SA: 'South America',
+    AN: 'Antarctica',
+};

package/dist/constants/feature.constants.d.ts

@@ -0,0 +1,53 @@
+export declare const FEATURE_CLASSES: {
+    readonly POPULATED_PLACE: "P";
+    readonly ADMINISTRATIVE: "A";
+    readonly HYDROGRAPHIC: "H";
+    readonly AREA: "L";
+    readonly ROAD: "R";
+    readonly SPOT: "S";
+    readonly HYPSOGRAPHIC: "T";
+    readonly UNDERSEA: "U";
+    readonly VEGETATION: "V";
+};
+export declare const FEATURE_CODES: {
+    /** First-order administrative division (state, province, region) */
+    readonly ADM1: "ADM1";
+    /** Second-order administrative division (county, district, department) */
+    readonly ADM2: "ADM2";
+    /** Third-order administrative division */
+    readonly ADM3: "ADM3";
+    /** Fourth-order administrative division */
+    readonly ADM4: "ADM4";
+    /** Miscellaneous administrative division */
+    readonly ADMD: "ADMD";
+    /** Populated place (city, village, town) */
+    readonly PPL: "PPL";
+    /** Seat of a first-order administrative division (state capital) */
+    readonly PPLA: "PPLA";
+    /** Seat of a second-order administrative division */
+    readonly PPLA2: "PPLA2";
+    /** Seat of a third-order administrative division */
+    readonly PPLA3: "PPLA3";
+    /** Capital of a political entity (national capital) */
+    readonly PPLC: "PPLC";
+    /** Seat of government of a political entity */
+    readonly PPLG: "PPLG";
+    /** Section of a populated place */
+    readonly PPLX: "PPLX";
+};
+export declare const GEONAMES_ORDERBY: {
+    readonly POPULATION: "population";
+    readonly ELEVATION: "elevation";
+    readonly RELEVANCE: "relevance";
+};
+export declare const GEONAMES_STYLE: {
+    readonly SHORT: "SHORT";
+    readonly MEDIUM: "MEDIUM";
+    readonly LONG: "LONG";
+    readonly FULL: "FULL";
+};
+/** Default page size returned by all paginated library methods (GeoNames free tier allows up to 500). */
+export declare const DEFAULT_MAX_ROWS: 100;
+/** Hard maximum rows per single GeoNames request on the free tier. */
+export declare const MAX_ROWS_LIMIT: 500;
+//# sourceMappingURL=feature.constants.d.ts.map

package/dist/constants/feature.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature.constants.d.ts","sourceRoot":"","sources":["../../src/constants/feature.constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe;;;;;;;;;;CAUlB,CAAC;AAEX,eAAO,MAAM,aAAa;IACxB,oEAAoE;;IAEpE,0EAA0E;;IAE1E,0CAA0C;;IAE1C,2CAA2C;;IAE3C,4CAA4C;;IAE5C,4CAA4C;;IAE5C,oEAAoE;;IAEpE,qDAAqD;;IAErD,oDAAoD;;IAEpD,uDAAuD;;IAEvD,+CAA+C;;IAE/C,mCAAmC;;CAE3B,CAAC;AAEX,eAAO,MAAM,gBAAgB;;;;CAInB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AAEX,yGAAyG;AACzG,eAAO,MAAM,gBAAgB,EAAG,GAAY,CAAC;AAC7C,sEAAsE;AACtE,eAAO,MAAM,cAAc,EAAG,GAAY,CAAC"}

package/dist/constants/feature.constants.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ROWS_LIMIT = exports.DEFAULT_MAX_ROWS = exports.GEONAMES_STYLE = exports.GEONAMES_ORDERBY = exports.FEATURE_CODES = exports.FEATURE_CLASSES = void 0;
+exports.FEATURE_CLASSES = {
+    POPULATED_PLACE: 'P',
+    ADMINISTRATIVE: 'A',
+    HYDROGRAPHIC: 'H',
+    AREA: 'L',
+    ROAD: 'R',
+    SPOT: 'S',
+    HYPSOGRAPHIC: 'T',
+    UNDERSEA: 'U',
+    VEGETATION: 'V',
+};
+exports.FEATURE_CODES = {
+    /** First-order administrative division (state, province, region) */
+    ADM1: 'ADM1',
+    /** Second-order administrative division (county, district, department) */
+    ADM2: 'ADM2',
+    /** Third-order administrative division */
+    ADM3: 'ADM3',
+    /** Fourth-order administrative division */
+    ADM4: 'ADM4',
+    /** Miscellaneous administrative division */
+    ADMD: 'ADMD',
+    /** Populated place (city, village, town) */
+    PPL: 'PPL',
+    /** Seat of a first-order administrative division (state capital) */
+    PPLA: 'PPLA',
+    /** Seat of a second-order administrative division */
+    PPLA2: 'PPLA2',
+    /** Seat of a third-order administrative division */
+    PPLA3: 'PPLA3',
+    /** Capital of a political entity (national capital) */
+    PPLC: 'PPLC',
+    /** Seat of government of a political entity */
+    PPLG: 'PPLG',
+    /** Section of a populated place */
+    PPLX: 'PPLX',
+};
+exports.GEONAMES_ORDERBY = {
+    POPULATION: 'population',
+    ELEVATION: 'elevation',
+    RELEVANCE: 'relevance',
+};
+exports.GEONAMES_STYLE = {
+    SHORT: 'SHORT',
+    MEDIUM: 'MEDIUM',
+    LONG: 'LONG',
+    FULL: 'FULL',
+};
+/** Default page size returned by all paginated library methods (GeoNames free tier allows up to 500). */
+exports.DEFAULT_MAX_ROWS = 100;
+/** Hard maximum rows per single GeoNames request on the free tier. */
+exports.MAX_ROWS_LIMIT = 500;

package/dist/errors/geo-location.error.d.ts

@@ -0,0 +1,6 @@
+export declare class GeoLocationError extends Error {
+    readonly code?: number | undefined;
+    readonly name = "GeoLocationError";
+    constructor(message: string, code?: number | undefined);
+}
+//# sourceMappingURL=geo-location.error.d.ts.map

package/dist/errors/geo-location.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geo-location.error.d.ts","sourceRoot":"","sources":["../../src/errors/geo-location.error.ts"],"names":[],"mappings":"AAAA,qBAAa,gBAAiB,SAAQ,KAAK;aAKvB,IAAI,CAAC,EAAE,MAAM;IAJ/B,SAAyB,IAAI,sBAAsB;gBAGjD,OAAO,EAAE,MAAM,EACC,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC"}

package/dist/errors/geo-location.error.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeoLocationError = void 0;
+class GeoLocationError extends Error {
+    code;
+    name = 'GeoLocationError';
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.GeoLocationError = GeoLocationError;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { GeoLocationClient } from './client/geo-location.client.js';
+export { GeoLocationError } from './errors/geo-location.error.js';
+export { CONTINENT_CODES, CONTINENT_NAMES } from './constants/continent.constants.js';
+export { FEATURE_CLASSES, FEATURE_CODES, DEFAULT_MAX_ROWS } from './constants/feature.constants.js';
+export type { ContinentCode } from './constants/continent.constants.js';
+export type { AtLeastOne, PaginatedResult, GeoLocationClientOptions, GeoLocationRestrictions, GetCountriesOptions, GetRegionsOptions, GetCitiesOptions, GetPostalCodesOptions, GetAllPostalCodesOptions, GetPostalCodePageOptions, PostalCodePage, Country, Region, City, PostalCode, } from './types/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpG,YAAY,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxE,YAAY,EACV,UAAU,EACV,eAAe,EACf,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,wBAAwB,EACxB,cAAc,EACd,OAAO,EACP,MAAM,EACN,IAAI,EACJ,UAAU,GACX,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_ROWS = exports.FEATURE_CODES = exports.FEATURE_CLASSES = exports.CONTINENT_NAMES = exports.CONTINENT_CODES = exports.GeoLocationError = exports.GeoLocationClient = void 0;
+var geo_location_client_js_1 = require("./client/geo-location.client.js");
+Object.defineProperty(exports, "GeoLocationClient", { enumerable: true, get: function () { return geo_location_client_js_1.GeoLocationClient; } });
+var geo_location_error_js_1 = require("./errors/geo-location.error.js");
+Object.defineProperty(exports, "GeoLocationError", { enumerable: true, get: function () { return geo_location_error_js_1.GeoLocationError; } });
+var continent_constants_js_1 = require("./constants/continent.constants.js");
+Object.defineProperty(exports, "CONTINENT_CODES", { enumerable: true, get: function () { return continent_constants_js_1.CONTINENT_CODES; } });
+Object.defineProperty(exports, "CONTINENT_NAMES", { enumerable: true, get: function () { return continent_constants_js_1.CONTINENT_NAMES; } });
+var feature_constants_js_1 = require("./constants/feature.constants.js");
+Object.defineProperty(exports, "FEATURE_CLASSES", { enumerable: true, get: function () { return feature_constants_js_1.FEATURE_CLASSES; } });
+Object.defineProperty(exports, "FEATURE_CODES", { enumerable: true, get: function () { return feature_constants_js_1.FEATURE_CODES; } });
+Object.defineProperty(exports, "DEFAULT_MAX_ROWS", { enumerable: true, get: function () { return feature_constants_js_1.DEFAULT_MAX_ROWS; } });

package/dist/mappers/city.mapper.d.ts

@@ -0,0 +1,4 @@
+import type { GeoNamesSearchResultRaw } from '../types/geonames-raw.types.js';
+import type { City } from '../types/city.types.js';
+export declare function mapCity(raw: GeoNamesSearchResultRaw): City;
+//# sourceMappingURL=city.mapper.d.ts.map

package/dist/mappers/city.mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"city.mapper.d.ts","sourceRoot":"","sources":["../../src/mappers/city.mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,wBAAgB,OAAO,CAAC,GAAG,EAAE,uBAAuB,GAAG,IAAI,CAc1D"}