@sil/data 0.1.0

package/dist/types/data/cities.d.ts

@@ -0,0 +1,22 @@
+import type { City } from "../types/index.js";
+/**
+ * Major world cities with geographic and demographic data.
+ * Includes the largest cities by population and all national capitals.
+ */
+export declare const cities: City[];
+/**
+ * Get cities for a specific country.
+ */
+export declare function getCitiesByCountry(countryCode: string): City[];
+/**
+ * Get the capital city of a country.
+ */
+export declare function getCapitalCity(countryCode: string): City | undefined;
+/**
+ * Get cities sorted by population (largest first).
+ */
+export declare function getCitiesByPopulation(limit?: number): City[];
+/**
+ * Search cities by name (case-insensitive partial match).
+ */
+export declare function searchCities(query: string): City[];

package/dist/types/data/continents.d.ts

@@ -0,0 +1,9 @@
+import type { Continent } from "../types/index.js";
+/**
+ * The seven continents with key metadata.
+ */
+export declare const continents: Continent[];
+/**
+ * Get a continent by its two-letter code.
+ */
+export declare function getContinentByCode(code: string): Continent | undefined;

package/dist/types/data/countries.d.ts

@@ -0,0 +1,18 @@
+import type { Country } from "../types/index.js";
+/**
+ * Complete list of world countries with ISO codes, flags, phone codes, and metadata.
+ * Based on ISO 3166-1 standard.
+ */
+export declare const countries: Country[];
+/**
+ * Get a country by its ISO 3166-1 alpha-2 code.
+ */
+export declare function getCountryByCode(code: string): Country | undefined;
+/**
+ * Get countries by continent.
+ */
+export declare function getCountriesByContinent(continent: Country["continent"]): Country[];
+/**
+ * Get a country's flag emoji by its ISO 3166-1 alpha-2 code.
+ */
+export declare function getCountryFlag(alpha2: string): string;

package/dist/types/data/currencies.d.ts

@@ -0,0 +1,13 @@
+import type { Currency } from "../types/index.js";
+/**
+ * Major world currencies with ISO 4217 codes, symbols, and the countries that use them.
+ */
+export declare const currencies: Currency[];
+/**
+ * Get currency by its ISO 4217 code.
+ */
+export declare function getCurrencyByCode(code: string): Currency | undefined;
+/**
+ * Get the currency used by a specific country.
+ */
+export declare function getCurrencyByCountry(countryCode: string): Currency | undefined;

package/dist/types/data/flags.d.ts

@@ -0,0 +1,39 @@
+import type { FlagInfo } from "../types/index.js";
+/**
+ * Build the flagcdn.com SVG URL for a country's flag.
+ * @param alpha2 ISO 3166-1 alpha-2 country code (case-insensitive)
+ */
+export declare function getFlagSvgUrl(alpha2: string): string;
+/**
+ * Build the flagcdn.com PNG URL for a country's flag.
+ * @param alpha2 ISO 3166-1 alpha-2 country code (case-insensitive)
+ * @param width Image width in pixels (40 | 80 | 160 | 320 | 640 | 1280 | 2560). Default: 320
+ */
+export declare function getFlagPngUrl(alpha2: string, width?: 40 | 80 | 160 | 320 | 640 | 1280 | 2560): string;
+/**
+ * Build a Wikimedia Commons URL for a country's outline SVG map.
+ * This is a reference URL—not bundled in the package.
+ * @param alpha3 ISO 3166-1 alpha-3 code (e.g., "USA")
+ */
+export declare function getCountryMapSvgUrl(alpha3: string): string;
+/**
+ * Flag metadata for all world countries.
+ *
+ * `colors` lists the most prominent flag colours (up to 4), most dominant first.
+ * `similar` lists alpha-2 codes of countries whose flags are visually similar—
+ *   useful for building confusing multiple-choice options in geography games.
+ */
+export declare const flagData: FlagInfo[];
+/**
+ * Get flag data for a specific country by its alpha-2 code.
+ */
+export declare function getFlagData(alpha2: string): FlagInfo | undefined;
+/**
+ * Get all countries whose flags share a given color.
+ */
+export declare function getFlagsByColor(color: FlagInfo["colors"][number]): FlagInfo[];
+/**
+ * Get all similar-flag entries for a given country.
+ * Returns an array of FlagInfo for each similar country.
+ */
+export declare function getSimilarFlags(alpha2: string): FlagInfo[];

package/dist/types/data/geography.d.ts

@@ -0,0 +1,33 @@
+import type { CountryGeography } from "../types/index.js";
+/**
+ * Geographic and climate data for all world countries.
+ * Includes centroid coordinates, bounding boxes, area, landlocked status,
+ * neighbouring countries, climate zone, and average annual temperature.
+ *
+ * Centroid (lat/lon) is the geographical centre of the country, used for
+ * distance and direction calculations in geography games.
+ *
+ * Climate zone follows a simplified Köppen classification.
+ * avgTemperature is approximate mean annual temperature in °C.
+ * @note The `neighbors` arrays use ISO 3166-1 alpha-2 codes, including
+ *   codes for disputed/special territories such as "EH" (Western Sahara)
+ *   and "XK" (Kosovo). These are included to accurately reflect shared land
+ *   borders, even where sovereignty is contested.
+ */
+export declare const countryGeography: CountryGeography[];
+/**
+ * Get geography data for a specific country by its alpha-2 code.
+ */
+export declare function getCountryGeography(alpha2: string): CountryGeography | undefined;
+/**
+ * Get all landlocked countries.
+ */
+export declare function getLandlockedCountries(): CountryGeography[];
+/**
+ * Get countries by climate zone.
+ */
+export declare function getCountriesByClimate(climate: CountryGeography["climate"]): CountryGeography[];
+/**
+ * Get all countries that neighbour a given country.
+ */
+export declare function getNeighbors(alpha2: string): CountryGeography[];

package/dist/types/data/phoneCodes.d.ts

@@ -0,0 +1,16 @@
+import type { PhoneCountryCode } from "../types/index.js";
+/**
+ * Phone country codes derived from the countries list, with additional
+ * entries for territories and special regions. Suitable for use in
+ * phone number input dropdowns.
+ */
+export declare const phoneCountryCodes: PhoneCountryCode[];
+/**
+ * Get a phone country code entry by its ISO 3166-1 alpha-2 code.
+ */
+export declare function getPhoneCodeByCountry(code: string): PhoneCountryCode | undefined;
+/**
+ * Get all countries with a specific phone code.
+ * Useful for finding all countries that share a dialing code (e.g., +1).
+ */
+export declare function getCountriesByPhoneCode(phoneCode: string): PhoneCountryCode[];

package/dist/types/data/states.d.ts

@@ -0,0 +1,18 @@
+import type { State } from "../types/index.js";
+/**
+ * Administrative divisions (states, provinces, territories, regions)
+ * for major countries around the world.
+ */
+export declare const states: State[];
+/**
+ * Get all states/provinces for a specific country.
+ */
+export declare function getStatesByCountry(countryCode: string): State[];
+/**
+ * Get a state by its code and country code.
+ */
+export declare function getStateByCode(code: string, countryCode: string): State | undefined;
+/**
+ * Get all states of a specific type.
+ */
+export declare function getStatesByType(type: State["type"]): State[];

package/dist/types/data/worldMap.d.ts

@@ -0,0 +1,122 @@
+/**
+ * World map SVG utilities.
+ *
+ * Provides the vector path data for 211 countries (ISO 3166-1 alpha-2 IDs)
+ * and helper functions to generate, style, and highlight countries in SVG format.
+ *
+ * Path data adapted from svg-world-maps (MIT) – https://github.com/homayounmmdy/svg-world-maps
+ *
+ * @example
+ * ```ts
+ * import { getWorldMapSvg, highlightCountries } from "@sil/data";
+ *
+ * // Render a plain world map
+ * document.getElementById("map").innerHTML = getWorldMapSvg({ fill: "#e0e0e0" });
+ *
+ * // Highlight specific countries
+ * document.getElementById("map").innerHTML = highlightCountries(
+ *   [{ code: "US", fill: "#4a90e2" }, { code: "DE", fill: "#e24a4a" }],
+ *   { fill: "#d0d0d0" }
+ * );
+ * ```
+ */
+import type { WorldMapCountry, WorldMapOptions, WorldMapHighlight } from "../types/index.js";
+/** ViewBox for the world map SVG canvas ("0 0 2000 857"). */
+export declare const WORLD_MAP_VIEWBOX = "0 0 2000 857";
+/**
+ * Default styling applied when no options are supplied.
+ */
+export declare const WORLD_MAP_DEFAULTS: Required<WorldMapOptions>;
+/**
+ * SVG path data for every country on the world map.
+ * Paths use ISO 3166-1 alpha-2 codes as identifiers.
+ * Countries that have no drawable path (e.g. very small island nations) have an empty `paths` array.
+ */
+export declare const worldMapCountries: WorldMapCountry[];
+/**
+ * Look up the SVG path data for a single country by its ISO alpha-2 code.
+ * The look-up is case-insensitive.
+ *
+ * @param code ISO 3166-1 alpha-2 code (e.g. "US", "de")
+ * @returns The matching {@link WorldMapCountry} entry, or `undefined` if not found.
+ *
+ * @example
+ * const germany = getCountryMapData("DE");
+ * // { code: "DE", name: "Germany", paths: ["M..."] }
+ */
+export declare function getCountryMapData(code: string): WorldMapCountry | undefined;
+/**
+ * Return all countries whose names contain the given search string
+ * (case-insensitive).
+ *
+ * @param name Full or partial country name
+ * @returns Array of matching {@link WorldMapCountry} entries.
+ *
+ * @example
+ * searchWorldMapCountries("land"); // → Greenland, Iceland, Finland, New Zealand, …
+ */
+export declare function searchWorldMapCountries(name: string): WorldMapCountry[];
+/**
+ * Generate a complete SVG world map string.
+ *
+ * Each country `<path>` element is given:
+ * - `id` set to its ISO alpha-2 code (e.g. `id="DE"`)
+ * - `data-code` – same ISO alpha-2 code
+ * - `data-name` – common country name
+ *
+ * This makes it straightforward to select and style countries via CSS or JavaScript:
+ * ```css
+ * #DE { fill: steelblue; }
+ * ```
+ * ```js
+ * document.getElementById("FR").style.fill = "red";
+ * ```
+ *
+ * @param options Optional styling overrides (merged with {@link WORLD_MAP_DEFAULTS}).
+ * @returns A complete `<svg>…</svg>` string ready for insertion into the DOM.
+ *
+ * @example
+ * const svg = getWorldMapSvg({ fill: "#e8f4f8", stroke: "#aaa", hoverFill: "#4a90e2" });
+ * document.getElementById("map").innerHTML = svg;
+ */
+export declare function getWorldMapSvg(options?: WorldMapOptions): string;
+/**
+ * Generate a world map SVG with specific countries highlighted in custom colours.
+ *
+ * All other countries keep the base fill from `options`.  Each highlighted
+ * country can optionally carry an accessible `<title>` (via `highlight.label`).
+ *
+ * @param highlights Array of {@link WorldMapHighlight} descriptors.
+ * @param options    Optional base styling (merged with {@link WORLD_MAP_DEFAULTS}).
+ * @returns A complete `<svg>…</svg>` string.
+ *
+ * @example
+ * const svg = highlightCountries(
+ *   [
+ *     { code: "US", fill: "#4a90e2", label: "United States" },
+ *     { code: "CA", fill: "#e24a4a" },
+ *   ],
+ *   { fill: "#eeeeee" }
+ * );
+ */
+export declare function highlightCountries(highlights: WorldMapHighlight[], options?: WorldMapOptions): string;
+/**
+ * Generate a world map SVG where countries are coloured by group.
+ *
+ * Useful for choropleth-style maps (e.g. continent groupings, data categories).
+ * Countries not present in any group get the base `options.fill`.
+ *
+ * @param groups  Map from a fill colour to an array of ISO alpha-2 codes.
+ * @param options Optional base styling.
+ * @returns A complete `<svg>…</svg>` string.
+ *
+ * @example
+ * const svg = colorizeWorldMap(
+ *   {
+ *     "#4a90e2": ["US", "CA", "MX"],
+ *     "#e24a4a": ["GB", "DE", "FR"],
+ *   },
+ *   { fill: "#dddddd" }
+ * );
+ */
+export declare function colorizeWorldMap(groups: Record<string, string[]>, options?: WorldMapOptions): string;

package/dist/types/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @sil/data
+ *
+ * A comprehensive collection of reusable world data:
+ * countries, phone codes, flags, cities, states, provinces, currencies, and more.
+ *
+ * @example
+ * ```ts
+ * import { phoneCountryCodes, countries, cities } from "@sil/data";
+ *
+ * // Use phone country codes in a select input
+ * const options = phoneCountryCodes.map(p => ({
+ *   label: `${p.flag} ${p.country} (${p.phoneCode})`,
+ *   value: p.phoneCode,
+ * }));
+ * ```
+ */
+export type { Country, PhoneCountryCode, City, State, StateType, Continent, ContinentName, Currency, CountryGeography, CountryBounds, ClimateZone, FlagInfo, FlagColor, CardinalDirection, WorldMapCountry, WorldMapOptions, WorldMapHighlight, } from "./types/index.js";
+export { countries, getCountryByCode, getCountriesByContinent, getCountryFlag, } from "./data/countries.js";
+export { phoneCountryCodes, getPhoneCodeByCountry, getCountriesByPhoneCode, } from "./data/phoneCodes.js";
+export { cities, getCitiesByCountry, getCapitalCity, getCitiesByPopulation, searchCities, } from "./data/cities.js";
+export { states, getStatesByCountry, getStateByCode, getStatesByType, } from "./data/states.js";
+export { continents, getContinentByCode } from "./data/continents.js";
+export { currencies, getCurrencyByCode, getCurrencyByCountry, } from "./data/currencies.js";
+export { countryGeography, getCountryGeography, getLandlockedCountries, getCountriesByClimate, getNeighbors, } from "./data/geography.js";
+export { flagData, getFlagData, getFlagsByColor, getSimilarFlags, getFlagSvgUrl, getFlagPngUrl, getCountryMapSvgUrl, } from "./data/flags.js";
+export { haversineDistance, bearing, bearingToCardinal, getDistanceBetweenCountries, getDirectionBetweenCountries, compareTemperature, compareSize, getHemisphere, getGeoHints, } from "./utils/geo.js";
+export type { GeoHint, Hemisphere } from "./utils/geo.js";
+export { WORLD_MAP_VIEWBOX, WORLD_MAP_DEFAULTS, worldMapCountries, getCountryMapData, searchWorldMapCountries, getWorldMapSvg, highlightCountries, colorizeWorldMap, } from "./data/worldMap.js";

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

@@ -0,0 +1,220 @@
+/**
+ * Represents a country with standard ISO codes and metadata.
+ */
+export interface Country {
+    /** Full official name of the country */
+    name: string;
+    /** Common/short name of the country */
+    nativeName?: string;
+    /** ISO 3166-1 alpha-2 code (e.g., "US") */
+    alpha2: string;
+    /** ISO 3166-1 alpha-3 code (e.g., "USA") */
+    alpha3: string;
+    /** ISO 3166-1 numeric code (e.g., "840") */
+    numeric: string;
+    /** Unicode emoji flag */
+    flag: string;
+    /** International dialing code (e.g., "+1") */
+    phoneCode: string;
+    /** Capital city name */
+    capital: string;
+    /** Continent name */
+    continent: ContinentName;
+    /** ISO 4217 currency code (e.g., "USD") */
+    currency: string;
+    /** Primary language(s) spoken */
+    languages: string[];
+    /** Top-level domain (e.g., ".us") */
+    tld?: string;
+}
+/**
+ * Continent names
+ */
+export type ContinentName = "Africa" | "Antarctica" | "Asia" | "Europe" | "North America" | "Oceania" | "South America";
+/**
+ * Phone country code entry, suitable for use in phone number inputs.
+ */
+export interface PhoneCountryCode {
+    /** Country name */
+    country: string;
+    /** ISO 3166-1 alpha-2 code */
+    code: string;
+    /** International dialing code with + prefix (e.g., "+1") */
+    phoneCode: string;
+    /** Unicode emoji flag */
+    flag: string;
+    /** Example number format (without country code) */
+    example?: string;
+}
+/**
+ * Represents a city with geographic and demographic data.
+ */
+export interface City {
+    /** City name */
+    name: string;
+    /** ISO 3166-1 alpha-2 country code */
+    country: string;
+    /** State, province, or region */
+    state?: string;
+    /** Approximate population */
+    population?: number;
+    /** Latitude */
+    lat: number;
+    /** Longitude */
+    lon: number;
+    /** Whether this is the capital of the country */
+    capital?: boolean;
+}
+/**
+ * Represents a state, province, or other administrative division.
+ */
+export interface State {
+    /** Full name of the state/province */
+    name: string;
+    /** State/province abbreviation code */
+    code: string;
+    /** ISO 3166-1 alpha-2 country code */
+    country: string;
+    /** Type of administrative division */
+    type: StateType;
+}
+/**
+ * Types of administrative divisions
+ */
+export type StateType = "state" | "province" | "territory" | "autonomous region" | "district" | "department" | "region" | "county" | "emirate" | "canton";
+/**
+ * Continent with metadata
+ */
+export interface Continent {
+    /** Continent name */
+    name: ContinentName;
+    /** Two-letter continent code */
+    code: string;
+    /** Approximate population */
+    population: number;
+    /** Area in square kilometers */
+    area: number;
+    /** Number of countries */
+    countries: number;
+}
+/**
+ * Currency information
+ */
+export interface Currency {
+    /** ISO 4217 currency code */
+    code: string;
+    /** Currency name */
+    name: string;
+    /** Currency symbol */
+    symbol: string;
+    /** Countries using this currency (alpha-2 codes) */
+    countries: string[];
+}
+/**
+ * Climate zones based on the Köppen climate classification (simplified).
+ */
+export type ClimateZone = "tropical" | "subtropical" | "arid" | "mediterranean" | "temperate" | "continental" | "subarctic" | "arctic";
+/**
+ * Geographic bounding box of a country.
+ */
+export interface CountryBounds {
+    /** Northernmost latitude */
+    north: number;
+    /** Southernmost latitude */
+    south: number;
+    /** Easternmost longitude */
+    east: number;
+    /** Westernmost longitude */
+    west: number;
+}
+/**
+ * Geographic and climate data for a country, useful for geography games.
+ */
+export interface CountryGeography {
+    /** ISO 3166-1 alpha-2 code */
+    alpha2: string;
+    /** Centroid latitude of the country */
+    lat: number;
+    /** Centroid longitude of the country */
+    lon: number;
+    /** Approximate bounding box */
+    bounds: CountryBounds;
+    /** Land area in km² */
+    area: number;
+    /** Whether the country is landlocked (has no coastline) */
+    landlocked: boolean;
+    /** Neighboring country alpha-2 codes */
+    neighbors: string[];
+    /** Primary climate zone */
+    climate: ClimateZone;
+    /** Average annual temperature in Celsius */
+    avgTemperature: number;
+}
+/**
+ * Primary colors that can appear on a country flag.
+ */
+export type FlagColor = "red" | "dark-red" | "white" | "blue" | "green" | "yellow" | "orange" | "black" | "gold" | "light-blue" | "dark-blue" | "dark-green" | "purple" | "brown";
+/**
+ * Flag metadata for a country, including visual similarity data for geography games.
+ */
+export interface FlagInfo {
+    /** ISO 3166-1 alpha-2 code */
+    alpha2: string;
+    /** URL to SVG flag image (via flagcdn.com) */
+    svgUrl: string;
+    /** URL to a 4×3 PNG flag image (via flagcdn.com) */
+    pngUrl: string;
+    /** Primary colors present on the flag (up to 4, most prominent first) */
+    colors: FlagColor[];
+    /**
+     * Alpha-2 codes of countries whose flags look visually similar.
+     * Useful for building "guess the flag" games with confusing options.
+     */
+    similar: string[];
+}
+/**
+ * 8-point cardinal / intercardinal compass directions.
+ */
+export type CardinalDirection = "N" | "NE" | "E" | "SE" | "S" | "SW" | "W" | "NW";
+/**
+ * SVG path data for a single country on the world map.
+ * A country may consist of multiple disjoint polygons (e.g. islands).
+ */
+export interface WorldMapCountry {
+    /** ISO 3166-1 alpha-2 code (e.g. "US") */
+    code: string;
+    /** Common country name */
+    name: string;
+    /** One or more SVG path `d` attribute strings */
+    paths: string[];
+}
+/**
+ * Styling options for rendering the world map SVG.
+ */
+export interface WorldMapOptions {
+    /** Fill color for all country shapes. Default: "#d0d0d0" */
+    fill?: string;
+    /** Stroke (border) color between countries. Default: "#ffffff" */
+    stroke?: string;
+    /** Stroke width in SVG units. Default: 0.5 */
+    strokeWidth?: number;
+    /** Fill color applied to a country on hover. Default: "#a0a0a0" */
+    hoverFill?: string;
+    /** SVG element width attribute (e.g. "100%", 800). Default: "100%" */
+    width?: string | number;
+    /** SVG element height attribute (e.g. "auto", 400). Default: "auto" */
+    height?: string | number;
+    /** Optional CSS class added to the `<svg>` element. */
+    className?: string;
+}
+/**
+ * Describes a highlighted country on the world map.
+ */
+export interface WorldMapHighlight {
+    /** ISO 3166-1 alpha-2 code of the country to highlight */
+    code: string;
+    /** Fill color to use for this country. Overrides the default fill. */
+    fill: string;
+    /** Optional accessible label (written as a `<title>` element). */
+    label?: string;
+}

package/dist/types/utils/geo.d.ts

@@ -0,0 +1,101 @@
+import type { CardinalDirection, ClimateZone } from "../types/index.js";
+/**
+ * Calculate the great-circle distance in kilometres between two geographic
+ * coordinates using the Haversine formula.
+ */
+export declare function haversineDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * Calculate the initial bearing (in degrees, 0 = north, clockwise) from one
+ * coordinate to another.
+ */
+export declare function bearing(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * Convert a bearing in degrees to an 8-point cardinal/intercardinal direction.
+ */
+export declare function bearingToCardinal(deg: number): CardinalDirection;
+/**
+ * Get the great-circle distance in km between two countries (by alpha-2 code),
+ * measured between their geographic centroids.
+ *
+ * Returns `null` if either country code is unknown.
+ */
+export declare function getDistanceBetweenCountries(alpha2A: string, alpha2B: string): number | null;
+/**
+ * Get the compass direction FROM country A TO country B (by alpha-2 code).
+ *
+ * For example, `getDirectionBetweenCountries("FR", "DE")` returns `"NE"`.
+ * Returns `null` if either country code is unknown.
+ */
+export declare function getDirectionBetweenCountries(fromAlpha2: string, toAlpha2: string): CardinalDirection | null;
+/**
+ * Compare the average annual temperature of two countries.
+ *
+ * Returns `"hotter"` if country B is warmer, `"colder"` if cooler, or
+ * `"similar"` if the difference is ≤ 3 °C.
+ *
+ * Useful in geography games: "The target country is hotter than your guess."
+ */
+export declare function compareTemperature(guessAlpha2: string, targetAlpha2: string): "hotter" | "colder" | "similar" | null;
+/**
+ * Compare the size (area) of two countries.
+ *
+ * Returns `"larger"` if the target country is bigger, `"smaller"` if smaller,
+ * or `"similar"` if within 20 % of each other.
+ */
+export declare function compareSize(guessAlpha2: string, targetAlpha2: string): "larger" | "smaller" | "similar" | null;
+/**
+ * Return a human-readable hemisphere description for a country's centroid.
+ *
+ * e.g. `"Northern"` | `"Southern"` | `"Eastern"` | `"Western"`
+ */
+export declare function getHemisphere(alpha2: string): Hemisphere | null;
+/**
+ * Hemisphere of a country: north/south and east/west of the prime meridian/equator.
+ */
+export interface Hemisphere {
+    /** "Northern" if centroid latitude ≥ 0, otherwise "Southern" */
+    ns: "Northern" | "Southern";
+    /** "Eastern" if centroid longitude ≥ 0, otherwise "Western" */
+    ew: "Eastern" | "Western";
+}
+/**
+ * A structured hint object for a geography guessing game.
+ *
+ * Given a player's guess and the secret target, produces all relevant hints.
+ */
+export interface GeoHint {
+    /** Distance from guessed country centroid to target centroid (km) */
+    distanceKm: number;
+    /** Compass direction from guess toward target */
+    direction: CardinalDirection;
+    /** Whether the target is hotter, colder, or similar in temperature */
+    temperature: "hotter" | "colder" | "similar";
+    /** Whether the target is larger, smaller, or similar in area */
+    size: "larger" | "smaller" | "similar";
+    /** Hemisphere of the target country */
+    hemisphere: Hemisphere;
+    /** Whether the target is landlocked */
+    landlocked: boolean;
+    /** Climate zone of the target */
+    climate: ClimateZone;
+}
+/**
+ * Generate all geography game hints comparing a player's guess to the target.
+ *
+ * Returns `null` if either alpha-2 code is not found in the dataset.
+ *
+ * @example
+ * ```ts
+ * const hints = getGeoHints("NL", "DE");
+ * // {
+ * //   distanceKm: 531,
+ * //   direction: "E",
+ * //   temperature: "similar",
+ * //   size: "larger",
+ * //   hemisphere: { ns: "Northern", ew: "Eastern" },
+ * //   landlocked: false,
+ * //   climate: "temperate",
+ * // }
+ * ```
+ */
+export declare function getGeoHints(guessAlpha2: string, targetAlpha2: string): GeoHint | null;