@forwardslashns/fws-geo-location-api 1.0.0

package/dist/mappers/city.mapper.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapCity = mapCity;
+function mapCity(raw) {
+    return {
+        geonameId: raw.geonameId,
+        name: raw.name,
+        countryCode: raw.countryCode,
+        countryName: raw.countryName,
+        adminCode1: raw.adminCode1,
+        adminName1: raw.adminName1,
+        population: raw.population ?? 0,
+        lat: parseFloat(raw.lat) || 0,
+        lng: parseFloat(raw.lng) || 0,
+        featureCode: raw.fcode,
+        featureName: raw.fcodeName,
+    };
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"country.mapper.d.ts","sourceRoot":"","sources":["../../src/mappers/country.mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAGzD,wBAAgB,UAAU,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAe3D"}

package/dist/mappers/country.mapper.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapCountry = mapCountry;
+function mapCountry(raw) {
+    return {
+        countryCode: raw.countryCode,
+        isoAlpha3: raw.isoAlpha3,
+        isoNumeric: raw.isoNumeric,
+        countryName: raw.countryName,
+        continent: raw.continent,
+        continentName: raw.continentName,
+        capital: raw.capital,
+        languages: raw.languages ? raw.languages.split(',').map((l) => l.trim()) : [],
+        population: parseInt(raw.population, 10) || 0,
+        geonameId: raw.geonameId,
+        currencyCode: raw.currencyCode,
+        areaInSqKm: parseFloat(raw.areaInSqKm) || 0,
+    };
+}

package/dist/mappers/postal-code.mapper.d.ts

@@ -0,0 +1,4 @@
+import type { GeoNamesPostalCodeRaw } from '../types/geonames-raw.types.js';
+import type { PostalCode } from '../types/postal-code.types.js';
+export declare function mapPostalCode(raw: GeoNamesPostalCodeRaw, countryName: string): PostalCode;
+//# sourceMappingURL=postal-code.mapper.d.ts.map

package/dist/mappers/postal-code.mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postal-code.mapper.d.ts","sourceRoot":"","sources":["../../src/mappers/postal-code.mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAOhE,wBAAgB,aAAa,CAAC,GAAG,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,CAgBzF"}

package/dist/mappers/postal-code.mapper.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapPostalCode = mapPostalCode;
+function buildDisplayName(postalCode, placeName, adminName1, countryName) {
+    const parts = [placeName, adminName1, countryName].filter(Boolean);
+    return `${postalCode} \u2014 ${parts.join(', ')}`;
+}
+function mapPostalCode(raw, countryName) {
+    return {
+        postalCode: raw.postalCode,
+        placeName: raw.placeName,
+        countryCode: raw.countryCode,
+        countryName,
+        adminCode1: raw.adminCode1,
+        adminName1: raw.adminName1,
+        adminCode2: raw.adminCode2,
+        adminName2: raw.adminName2,
+        adminCode3: raw.adminCode3,
+        adminName3: raw.adminName3,
+        lat: raw.lat,
+        lng: raw.lng,
+        displayName: buildDisplayName(raw.postalCode, raw.placeName, raw.adminName1, countryName),
+    };
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"region.mapper.d.ts","sourceRoot":"","sources":["../../src/mappers/region.mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAC9E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAEvD,wBAAgB,SAAS,CAAC,GAAG,EAAE,uBAAuB,GAAG,MAAM,CAiB9D"}

package/dist/mappers/region.mapper.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapRegion = mapRegion;
+function mapRegion(raw) {
+    const isoCode = raw.adminCodes1?.ISO3166_2
+        ? `${raw.countryCode}-${raw.adminCodes1.ISO3166_2}`
+        : `${raw.countryCode}-${raw.adminCode1}`;
+    return {
+        geonameId: raw.geonameId,
+        name: raw.name,
+        code: raw.adminCode1,
+        isoCode,
+        countryCode: raw.countryCode,
+        countryName: raw.countryName,
+        population: raw.population ?? 0,
+        lat: parseFloat(raw.lat) || 0,
+        lng: parseFloat(raw.lng) || 0,
+        featureCode: raw.fcode,
+    };
+}

package/dist/services/http.service.d.ts

@@ -0,0 +1,8 @@
+import type { AtLeastOne } from '../types/common.types.js';
+export declare class HttpService {
+    private readonly usernames;
+    private currentUsernameIndex;
+    constructor(usernames: AtLeastOne<string>);
+    get<T>(url: string, params: Record<string, string | number>): Promise<T>;
+}
+//# sourceMappingURL=http.service.d.ts.map

package/dist/services/http.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.service.d.ts","sourceRoot":"","sources":["../../src/services/http.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAiB3D,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,oBAAoB,CAAa;gBAEtB,SAAS,EAAE,UAAU,CAAC,MAAM,CAAC;IAInC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CA4CtF"}

package/dist/services/http.service.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpService = void 0;
+const axios_1 = __importDefault(require("axios"));
+const geo_location_error_js_1 = require("../errors/geo-location.error.js");
+const api_constants_js_1 = require("../constants/api.constants.js");
+function isGeoNamesErrorResponse(data) {
+    return (typeof data === 'object' &&
+        data !== null &&
+        'status' in data &&
+        typeof data.status === 'object' &&
+        data.status !== null &&
+        'value' in data.status &&
+        'message' in data.status);
+}
+class HttpService {
+    usernames;
+    currentUsernameIndex = 0;
+    constructor(usernames) {
+        this.usernames = usernames;
+    }
+    async get(url, params) {
+        while (this.currentUsernameIndex < this.usernames.length) {
+            const username = this.usernames[this.currentUsernameIndex];
+            try {
+                const response = await axios_1.default.get(url, {
+                    params: { ...params, username },
+                    timeout: 15_000,
+                });
+                const data = response.data;
+                if (isGeoNamesErrorResponse(data)) {
+                    const { value, message } = data.status;
+                    if (api_constants_js_1.GEONAMES_RATE_LIMIT_CODES.includes(value)) {
+                        this.currentUsernameIndex++;
+                        continue;
+                    }
+                    if (value === api_constants_js_1.GEONAMES_ERROR_CODES.AUTHORIZATION_EXCEPTION) {
+                        throw new geo_location_error_js_1.GeoLocationError(`GeoNames authorization error for username "${username}": ${message}`, value);
+                    }
+                    throw new geo_location_error_js_1.GeoLocationError(`GeoNames API error (code ${value}): ${message}`, value);
+                }
+                return data;
+            }
+            catch (err) {
+                if (err instanceof geo_location_error_js_1.GeoLocationError)
+                    throw err;
+                if (axios_1.default.isAxiosError(err)) {
+                    throw new geo_location_error_js_1.GeoLocationError(`HTTP request to GeoNames failed: ${err.message ?? 'unknown error'}`);
+                }
+                throw err;
+            }
+        }
+        throw new geo_location_error_js_1.GeoLocationError(`All ${String(this.usernames.length)} GeoNames username(s) have reached their rate limit. ` +
+            'Add more usernames to the client or wait until the limit resets.');
+    }
+}
+exports.HttpService = HttpService;

package/dist/types/city.types.d.ts

@@ -0,0 +1,21 @@
+export interface City {
+    geonameId: number;
+    /** City display name, e.g. "New York City" */
+    name: string;
+    /** ISO 3166-1 alpha-2 country code, e.g. "US" */
+    countryCode: string;
+    /** Full country name, e.g. "United States" */
+    countryName: string;
+    /** First-order admin code (state/province), e.g. "NY" */
+    adminCode1: string;
+    /** First-order admin name (state/province), e.g. "New York" */
+    adminName1: string;
+    population: number;
+    lat: number;
+    lng: number;
+    /** GeoNames feature code, e.g. "PPLA", "PPL", "PPLC" */
+    featureCode: string;
+    /** Human-readable description of the feature code */
+    featureName: string;
+}
+//# sourceMappingURL=city.types.d.ts.map

package/dist/types/city.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"city.types.d.ts","sourceRoot":"","sources":["../../src/types/city.types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,IAAI;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/types/city.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/client.types.d.ts

@@ -0,0 +1,133 @@
+import type { ContinentCode } from '../constants/continent.constants.js';
+import type { AtLeastOne } from './common.types.js';
+import type { PostalCode } from './postal-code.types.js';
+export interface GeoLocationRestrictions {
+    /**
+     * Restrict all API calls to the given continent(s).
+     * Uses GeoNames continent codes: 'AF' | 'AS' | 'EU' | 'NA' | 'OC' | 'SA' | 'AN'
+     */
+    continents?: ContinentCode[];
+    /**
+     * Restrict all API calls to the given ISO 3166-1 alpha-2 country codes (e.g. ['US', 'DE']).
+     * Applied as a post-filter where the GeoNames API does not support direct filtering.
+     */
+    countries?: string[];
+}
+export interface GeoLocationClientOptions {
+    /**
+     * One or more GeoNames usernames used for API authentication.
+     * Must contain at least one username — enforced at compile time via the AtLeastOne type.
+     * When a username hits its daily/hourly/weekly credit limit the client automatically
+     * advances to the next username in the array.
+     */
+    usernames: AtLeastOne<string>;
+    /**
+     * Optional global restrictions applied to every API call.
+     * Can be overridden per method call via the method's own options argument.
+     */
+    restrictions?: GeoLocationRestrictions;
+}
+export interface GetCountriesOptions {
+    /** Override global continent restriction for this call only. */
+    continents?: ContinentCode[];
+    /** Override global country restriction for this call only. */
+    countryCodes?: string[];
+}
+export interface GetRegionsOptions {
+    /** Maximum number of results to return. GeoNames free tier cap: 500. Default: 100. */
+    maxRows?: number;
+    /** Zero-based row offset for pagination. Mutually exclusive with `page`. */
+    startRow?: number;
+    /**
+     * 1-based page number — convenience alias for `startRow`.
+     * Page 1 = `startRow` 0, page 2 = `startRow` equal to `maxRows`, etc.
+     * Takes precedence over `startRow` when both are provided.
+     */
+    page?: number;
+}
+export interface GetCitiesOptions {
+    /**
+     * Filter cities to a specific first-order administrative division
+     * (e.g. 'NY' for New York state, 'CA' for California).
+     */
+    regionCode?: string;
+    /** Maximum number of results to return. GeoNames free tier cap: 500. Default: 100. */
+    maxRows?: number;
+    /** Sort order for results. Default: 'population'. */
+    orderBy?: 'population' | 'elevation' | 'relevance';
+    /**
+     * Free-text search term for city name. Useful when no country is specified
+     * for a global city lookup.
+     */
+    searchTerm?: string;
+    /** Zero-based row offset for pagination. Mutually exclusive with `page`. */
+    startRow?: number;
+    /**
+     * 1-based page number — convenience alias for `startRow`.
+     * Page 1 = `startRow` 0, page 2 = `startRow` equal to `maxRows`, etc.
+     * Takes precedence over `startRow` when both are provided.
+     */
+    page?: number;
+}
+export interface GetPostalCodesOptions {
+    /** Return only postal codes starting with this prefix. */
+    postalCodePrefix?: string;
+    /** Return only postal codes whose place name starts with this string. */
+    placeName?: string;
+    /** Maximum number of results to return. GeoNames free tier cap: 500. Default: 100. */
+    maxRows?: number;
+    /** Zero-based row offset for pagination. Mutually exclusive with `page`. */
+    startRow?: number;
+    /**
+     * 1-based page number — convenience alias for `startRow`.
+     * Page 1 = `startRow` 0, page 2 = `startRow` equal to `maxRows`, etc.
+     * Takes precedence over `startRow` when both are provided.
+     */
+    page?: number;
+}
+export interface GetAllPostalCodesOptions {
+    /**
+     * Called after every prefix bucket is fully fetched, with all postal codes
+     * collected so far. Use this to stream results into the UI progressively
+     * rather than waiting for the entire country dataset to finish loading.
+     *
+     * Note: the array passed is a snapshot at the time of the call — mutating it
+     * has no effect on the internal collection.
+     */
+    onProgress?: (loaded: ReadonlyArray<PostalCode>) => void;
+}
+export interface GetPostalCodePageOptions {
+    /**
+     * Opaque cursor returned by a previous `getPostalCodesPage` call.
+     * Omit (or pass `undefined`) to start from the very first postal code.
+     */
+    cursor?: string;
+    /**
+     * Number of postal codes to return per page.
+     * Clamped to the GeoNames free-tier maximum of 500.
+     * Default: the library's `DEFAULT_MAX_ROWS` (100).
+     */
+    maxRows?: number;
+}
+export interface PostalCodePage {
+    /** Postal codes for this page, already mapped to the library's `PostalCode` shape. */
+    data: PostalCode[];
+    /**
+     * Pass this value as `cursor` to the next `getPostalCodesPage` call to
+     * retrieve the following page.  `null` when the entire country dataset has
+     * been returned.
+     */
+    nextCursor: string | null;
+    /** Convenience flag — `true` when `nextCursor` is non-null. */
+    hasMore: boolean;
+    /**
+     * How far through the 36 alphanumeric prefix buckets (0-9, A-Z) the cursor
+     * currently sits.  Useful for rendering a progress indicator.
+     * `{ done: 36, total: 36 }` when exhausted.
+     */
+    prefixProgress: {
+        done: number;
+        total: 36;
+    };
+}
+//# sourceMappingURL=client.types.d.ts.map

package/dist/types/client.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.types.d.ts","sourceRoot":"","sources":["../../src/types/client.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,SAAS,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,uBAAuB,CAAC;CACxC;AAED,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,UAAU,CAAC,EAAE,aAAa,EAAE,CAAC;IAC7B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW,GAAG,WAAW,CAAC;IACnD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;CAC1D;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,cAAc,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,EAAE,CAAA;KAAE,CAAC;CAC7C"}

package/dist/types/client.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/common.types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A tuple type that enforces at least one element.
+ * Used to guarantee that the `usernames` array passed to GeoLocationClient
+ * always contains at least one valid GeoNames username — enforced at compile time.
+ */
+export type AtLeastOne<T> = [T, ...T[]];
+/**
+ * Wraps a page of results returned by a paginated list method.
+ *
+ * Methods backed by the GeoNames `searchJSON` endpoint (cities, regions) can
+ * provide the true server-side total (`totalResultsCount`).  For other
+ * endpoints that do not expose a total (e.g. postal codes), `total` is `-1`.
+ */
+export interface PaginatedResult<T> {
+    /** The items for the current page. */
+    data: T[];
+    /**
+     * Total number of records matching the query on the server.
+     * `-1` means the data source does not expose a total count.
+     */
+    total: number;
+    /** Current 1-based page number. */
+    page: number;
+    /** Maximum number of records per page (the requested page size). */
+    pageSize: number;
+    /** `true` when there are more pages available after this one. */
+    hasMore: boolean;
+}
+//# sourceMappingURL=common.types.d.ts.map

package/dist/types/common.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.types.d.ts","sourceRoot":"","sources":["../../src/types/common.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;AAExC;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,sCAAsC;IACtC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;CAClB"}

package/dist/types/common.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/country.types.d.ts

@@ -0,0 +1,25 @@
+import type { ContinentCode } from '../constants/continent.constants.js';
+export interface Country {
+    /** ISO 3166-1 alpha-2 code, e.g. "US" */
+    countryCode: string;
+    /** ISO 3166-1 alpha-3 code, e.g. "USA" */
+    isoAlpha3: string;
+    /** ISO 3166-1 numeric code, e.g. "840" */
+    isoNumeric: string;
+    /** Full English name, e.g. "United States" */
+    countryName: string;
+    /** GeoNames continent code */
+    continent: ContinentCode;
+    /** Full continent name, e.g. "North America" */
+    continentName: string;
+    /** Capital city name */
+    capital: string;
+    /** BCP 47 language tags spoken in the country */
+    languages: string[];
+    population: number;
+    geonameId: number;
+    /** ISO 4217 currency code, e.g. "USD" */
+    currencyCode: string;
+    areaInSqKm: number;
+}
+//# sourceMappingURL=country.types.d.ts.map

package/dist/types/country.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"country.types.d.ts","sourceRoot":"","sources":["../../src/types/country.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAEzE,MAAM,WAAW,OAAO;IACtB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,SAAS,EAAE,aAAa,CAAC;IACzB,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/types/country.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/geonames-raw.types.d.ts

@@ -0,0 +1,77 @@
+/** Raw shape of a single country returned by GeoNames countryInfoJSON. */
+export interface GeoNamesCountryRaw {
+    continent: string;
+    capital: string;
+    languages: string;
+    geonameId: number;
+    south: number;
+    isoAlpha3: string;
+    north: number;
+    fipsCode: string;
+    population: string;
+    east: number;
+    isoNumeric: string;
+    areaInSqKm: string;
+    countryCode: string;
+    west: number;
+    countryName: string;
+    postalCodeFormat: string;
+    continentName: string;
+    currencyCode: string;
+}
+export interface GeoNamesCountryInfoResponse {
+    geonames: GeoNamesCountryRaw[];
+}
+/** Raw shape of a single result returned by GeoNames searchJSON. */
+export interface GeoNamesSearchResultRaw {
+    adminCode1: string;
+    adminCode2?: string;
+    adminName1: string;
+    adminName2?: string;
+    adminCodes1?: {
+        ISO3166_2: string;
+    };
+    countryCode: string;
+    countryId: string;
+    countryName: string;
+    fcl: string;
+    fclName: string;
+    fcode: string;
+    fcodeName: string;
+    geonameId: number;
+    lat: string;
+    lng: string;
+    name: string;
+    population: number;
+    toponymName: string;
+}
+export interface GeoNamesSearchResponse {
+    totalResultsCount: number;
+    geonames: GeoNamesSearchResultRaw[];
+}
+/** Raw shape of a single postal code returned by GeoNames postalCodeSearchJSON. */
+export interface GeoNamesPostalCodeRaw {
+    postalCode: string;
+    placeName: string;
+    countryCode: string;
+    adminCode1: string;
+    adminName1: string;
+    adminCode2?: string;
+    adminName2?: string;
+    adminCode3?: string;
+    adminName3?: string;
+    lat: number;
+    lng: number;
+    'ISO3166-2': string;
+}
+export interface GeoNamesPostalCodeResponse {
+    postalCodes: GeoNamesPostalCodeRaw[];
+}
+/** GeoNames error envelope — returned inside a 200 response body on failure. */
+export interface GeoNamesErrorResponse {
+    status: {
+        message: string;
+        value: number;
+    };
+}
+//# sourceMappingURL=geonames-raw.types.d.ts.map

package/dist/types/geonames-raw.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geonames-raw.types.d.ts","sourceRoot":"","sources":["../../src/types/geonames-raw.types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAED,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,uBAAuB,EAAE,CAAC;CACrC;AAED,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,qBAAqB,EAAE,CAAC;CACtC;AAED,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH"}

package/dist/types/geonames-raw.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+export type { AtLeastOne, PaginatedResult } from './common.types.js';
+export type { GeoLocationClientOptions, GeoLocationRestrictions, GetCountriesOptions, GetRegionsOptions, GetCitiesOptions, GetPostalCodesOptions, GetAllPostalCodesOptions, GetPostalCodePageOptions, PostalCodePage, } from './client.types.js';
+export type { Country } from './country.types.js';
+export type { Region } from './region.types.js';
+export type { City } from './city.types.js';
+export type { PostalCode } from './postal-code.types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACrE,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,wBAAwB,EACxB,cAAc,GACf,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/postal-code.types.d.ts

@@ -0,0 +1,31 @@
+export interface PostalCode {
+    /** The postal / zip code string, e.g. "10001" */
+    postalCode: string;
+    /** Primary place name for this postal code, e.g. "New York City" */
+    placeName: string;
+    /** ISO 3166-1 alpha-2 country code, e.g. "US" */
+    countryCode: string;
+    /** Full country name, e.g. "United States" */
+    countryName: string;
+    /** First-order admin code (state/province), e.g. "NY" */
+    adminCode1: string;
+    /** First-order admin name (state/province), e.g. "New York" */
+    adminName1: string;
+    /** Second-order admin code (county/district), e.g. "061" */
+    adminCode2?: string;
+    /** Second-order admin name (county/district), e.g. "New York County" */
+    adminName2?: string;
+    /** Third-order admin code */
+    adminCode3?: string;
+    /** Third-order admin name */
+    adminName3?: string;
+    lat: number;
+    lng: number;
+    /**
+     * User-friendly display name for use in dropdowns and autocomplete components.
+     * Format: "{postalCode} — {placeName}, {adminName1}, {countryName}"
+     * Example: "10001 — New York City, New York, United States"
+     */
+    displayName: string;
+}
+//# sourceMappingURL=postal-code.types.d.ts.map

package/dist/types/postal-code.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postal-code.types.d.ts","sourceRoot":"","sources":["../../src/types/postal-code.types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/types/postal-code.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/region.types.d.ts

@@ -0,0 +1,19 @@
+export interface Region {
+    geonameId: number;
+    /** Region display name, e.g. "New York" */
+    name: string;
+    /** First-order admin code, e.g. "NY" */
+    code: string;
+    /** ISO 3166-2 code, e.g. "US-NY" */
+    isoCode: string;
+    /** ISO 3166-1 alpha-2 country code, e.g. "US" */
+    countryCode: string;
+    /** Full country name, e.g. "United States" */
+    countryName: string;
+    population: number;
+    lat: number;
+    lng: number;
+    /** GeoNames feature code, e.g. "ADM1" */
+    featureCode: string;
+}
+//# sourceMappingURL=region.types.d.ts.map

package/dist/types/region.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"region.types.d.ts","sourceRoot":"","sources":["../../src/types/region.types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/types/region.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });