interface DataVersion {
    version: string;
    sample: boolean;
    lastUpdatedAt: string;
    description: string;
    sources: string[];
}
declare function getDataVersion(): DataVersion;

interface Province {
    code: string;
    name: string;
    type: "province" | "city";
    nameWithType: string;
    slug: string;
    normalizedName: string;
}
interface Ward {
    code: string;
    name: string;
    type: "ward" | "commune" | "special_zone";
    nameWithType: string;
    provinceCode: string;
    slug: string;
    normalizedName: string;
}
interface LegacyProvince {
    code: string;
    name: string;
    type: "province" | "city";
    nameWithType: string;
    slug: string;
    normalizedName: string;
}
interface LegacyDistrict {
    code: string;
    name: string;
    type: "district" | "city" | "town" | "urban_district";
    nameWithType: string;
    provinceCode: string;
    slug: string;
    normalizedName: string;
}
/**
 * A ward name retired in an earlier (pre-2025) reform round that was absorbed,
 * deterministically, into the surviving `LegacyWard` that carries this entry.
 * Lets addresses written with the old name (e.g. "Phước Tiến", merged into
 * "Tân Tiến" on 2024-11-01) still resolve. Matching is by `normalizedName`;
 * `code`/`since`/`decree` are carried for auditability only.
 */
interface LegacyFormerName {
    name: string;
    normalizedName: string;
    code?: string;
    since?: string;
    decree?: string;
}
interface LegacyWard {
    code: string;
    name: string;
    type: "ward" | "commune" | "town";
    nameWithType: string;
    districtCode: string;
    provinceCode: string;
    slug: string;
    normalizedName: string;
    /** Former names this ward absorbed in a pre-2025 reform; see {@link LegacyFormerName}. */
    formerNames?: LegacyFormerName[];
}
type MappingType = "unchanged" | "renamed" | "merged" | "split" | "split_population" | "province_changed" | "ambiguous" | "manual_review_required";
interface AddressMapping {
    oldProvinceCode: string;
    oldDistrictCode?: string;
    oldWardCode?: string;
    newProvinceCode: string;
    newWardCode: string;
    type: MappingType;
    note?: string;
}

declare function getProvinces(): Province[];
declare function getWards(): Ward[];
declare function getProvinceByCode(code: string): Province | undefined;
declare function getProvinceByName(name: string): Province | undefined;
declare function getWardByCode(code: string): Ward | undefined;
declare function getWardsByProvince(provinceCode: string): Ward[];

declare function normalizeText(text: string): string;

declare function normalizeAdministrativePrefix(text: string): string;

declare function removeVietnameseTones(text: string): string;

interface ScoredResult<T> {
    item: T;
    score: number;
    strategy: "exact" | "normalized" | "contains" | "fuzzy";
}

declare function searchProvince(keyword: string): Array<ScoredResult<Province>>;

interface SearchWardOptions {
    provinceCode?: string;
}
declare function searchWard(keyword: string, options?: SearchWardOptions): Array<ScoredResult<Ward>>;

declare function searchAdministrativeUnit(keyword: string): {
    provinces: ScoredResult<Province>[];
    wards: ScoredResult<Ward>[];
};

declare function validateProvince(provinceCode: string): boolean;
declare function validateWard(wardCode: string): boolean;
declare function validateAddress(input: {
    provinceCode: string;
    wardCode: string;
}): HierarchyValidationResult;

interface StructuredOldAddressInput {
    province?: string;
    district?: string;
    ward?: string;
    streetAddress?: string;
}
interface ParsedAddress {
    input: string;
    streetAddress?: string;
    province?: string;
    district?: string;
    ward?: string;
    confidence: number;
    warnings: string[];
}

type MatchStrategy = "old_ward_district_province_exact" | "old_ward_province_exact" | "former_ward" | "split_population" | "normalized_exact" | "no_diacritics" | "abbreviation" | "fuzzy" | "candidate_suggestion" | "failed";
interface ConversionCandidate {
    newProvinceCode: string;
    newProvinceName: string;
    newWardCode: string;
    newWardName: string;
    confidence: number;
    strategy: MatchStrategy;
    reason: string;
}
interface ConversionResult {
    success: boolean;
    input: string | StructuredOldAddressInput;
    streetAddress?: string;
    oldAddress?: {
        provinceCode?: string;
        provinceName?: string;
        districtCode?: string;
        districtName?: string;
        wardCode?: string;
        wardName?: string;
    };
    newAddress?: {
        provinceCode: string;
        provinceName: string;
        wardCode: string;
        wardName: string;
    };
    confidence: number;
    strategy: MatchStrategy;
    warnings: string[];
    candidates: ConversionCandidate[];
}
interface HierarchyValidationResult {
    valid: boolean;
    province?: Province;
    ward?: Ward;
    reason?: string;
}
interface BatchConversionResult {
    total: number;
    matched: number;
    ambiguous: number;
    failed: number;
    averageConfidence: number;
    results: ConversionResult[];
}

interface ValidateHierarchyInput {
    provinceCode: string;
    wardCode: string;
}
declare function validateHierarchy(input: ValidateHierarchyInput): HierarchyValidationResult;

declare function parseAddress(text: string): ParsedAddress;

declare function convertAddressText(text: string): ConversionResult;

declare function convertOldToNew(input: StructuredOldAddressInput): ConversionResult;
declare function convertBatch(items: Array<string | StructuredOldAddressInput>): BatchConversionResult;

export { type AddressMapping, type BatchConversionResult, type ConversionCandidate, type ConversionResult, type HierarchyValidationResult, type LegacyDistrict, type LegacyFormerName, type LegacyProvince, type LegacyWard, type MappingType, type MatchStrategy, type ParsedAddress, type Province, type StructuredOldAddressInput, type Ward, convertAddressText, convertBatch, convertOldToNew, getDataVersion, getProvinceByCode, getProvinceByName, getProvinces, getWardByCode, getWards, getWardsByProvince, normalizeAdministrativePrefix, normalizeText, parseAddress, removeVietnameseTones, searchAdministrativeUnit, searchProvince, searchWard, validateAddress, validateHierarchy, validateProvince, validateWard };