interface LoaderOptions {
    baseUrl?: string;
    fetch?: typeof fetch;
    signal?: AbortSignal;
}

declare const VERSIONS: readonly ["19751231", "19801231", "19851231", "19901231", "19951231", "20001231", "20011231", "20021231", "20031231", "20041231", "20051231", "20061231", "20071231", "20081231", "20091231", "20101231", "20111231", "20121210", "20121231", "20131231", "20141231", "20151231", "20160201", "20170418", "20170801", "20171016", "20180301", "20180401", "20180724", "20181106", "20190403", "20190908", "20191001", "20191231", "20200101", "20200701", "20201001", "20210101", "20210401", "20210701", "20220101", "20220309", "20220401", "20220701", "20221001", "20230101", "20230401", "20230701", "20231001", "20231231", "20240101", "20240401", "20240701", "20241001", "20241231", "20250101", "20250401", "20250701", "20251001", "20251231", "20260201", "20260401", "20260701"];
type VersionKey = typeof VERSIONS[number];

/**
 * 버전 키 목록 (동기).
 *
 * 이 배열은 **패키지 배포 시점의 스냅샷**이다. 새 시점 데이터가 dist/data/ 에
 * 추가돼도 이 상수는 재배포 전까지 갱신되지 않는다. 최신 목록이 필요하면
 * {@link versionsAsync} 를 쓸 것 (manifest.json 을 런타임에 읽어 항상 최신).
 *
 * get/compare/matchAdm 의 입력 검증에도 이 동기 상수를 쓴다 (하위호환 유지).
 */
declare function versions(year?: number): string[];
/**
 * 버전 키 목록 (비동기, 런타임 최신).
 *
 * 원격 `manifest.json` 의 `versions` 배열을 읽으므로, 라이브러리 재배포 없이
 * dist/data/ 데이터만 갱신돼도 최신 시점까지 반영된다. manifest 에 versions 가
 * 없는 옛 배포이거나 네트워크 실패 시 동기 {@link VERSIONS} 스냅샷으로 fallback.
 *
 * @param year  4자리 연도로 필터 (예: 2025). 생략 시 전체.
 * @param opts  baseUrl / fetch / signal (LoaderOptions).
 */
declare function versionsAsync(year?: number, opts?: LoaderOptions): Promise<string[]>;

type Level = "emd" | "sgg" | "sido";
interface GetOptions {
    /** 기본 false (light, 단순화). true 면 원본 해상도 parquet. */
    detail?: boolean;
    /** fetch 기본 URL 오버라이드. 테스트 / 자체 호스팅용. */
    baseUrl?: string;
    /** 커스텀 fetch (Node 18+ 는 글로벌 fetch 사용 가능). */
    fetch?: typeof fetch;
    /** AbortSignal. */
    signal?: AbortSignal;
}
interface EmdProperties {
    emd7: string | null;
    emd8: string | null;
    emdcd: string | null;
    emdnm: string;
    sggcd: string | null;
    sggnm: string | null;
    sidocd: string | null;
    sidonm: string;
    area: number;
}
interface SggProperties {
    sggcd: string | null;
    sggnm: string;
    sidocd: string | null;
    sidonm: string;
    area: number;
}
interface SidoProperties {
    sidocd: string | null;
    sidonm: string;
    area: number;
}
type AdmProperties = EmdProperties | SggProperties | SidoProperties;
interface AdmFeature<P = AdmProperties> {
    type: "Feature";
    properties: P;
    geometry: GeoJSON.Polygon | GeoJSON.MultiPolygon;
}
interface AdmFeatureCollection<P = AdmProperties> {
    type: "FeatureCollection";
    /**
     * 이 데이터의 좌표계.
     * - `"EPSG:4326"` — `detail: false` (light). Leaflet/MapLibre 에 바로 사용 가능.
     * - `"EPSG:5179"` — `detail: true` (원본). UTM-K 미터 좌표라 재투영이 필요하다.
     */
    crs?: "EPSG:4326" | "EPSG:5179";
    features: AdmFeature<P>[];
}

/** 원본 parquet 파일을 ArrayBuffer 로 반환. 파싱하지 않음.
 *
 * 용도:
 * - Web Worker 로 transferable 전달해서 main thread 부담 최소화
 * - IndexedDB / Cache API 에 바이트 그대로 저장
 * - parquet-wasm, @geoarrow/deck.gl-layers 등에 직접 투입
 *
 * Geometry 는 WKB, CRS 는 EPSG:4326, 압축은 snappy. geo-parquet spec 호환.
 */
declare function getParquet(key: string, level?: Level, options?: GetOptions): Promise<ArrayBuffer>;
/** 지도 데이터를 GeoJSON `FeatureCollection` 으로 반환.
 *
 * 내부적으로 `getParquet()` 로 받은 parquet 바이트를 파싱해서 GeoJSON 으로 변환.
 * deck.gl `GeoJsonLayer`, Leaflet `L.geoJSON`, MapLibre `GeoJSONSource` 에 바로 투입 가능.
 *
 * geometry 는 `Polygon` 또는 `MultiPolygon`.
 *
 * **좌표계 주의** — 두 파일의 저장 좌표계가 다르다:
 * - `detail: false` (기본, light) → **EPSG:4326** (경위도). 웹 지도에 바로 쓸 수 있다.
 * - `detail: true` (원본)         → **EPSG:5179** (UTM-K, 미터). 재투영이 필요하다.
 *
 * 파이썬 `adk.get()` 은 geopandas 로 CRS 를 통일하지만, JS 는 재투영 의존성을
 * 두지 않으므로 저장된 좌표를 그대로 돌려준다. 반환된 `crs` 필드로 판별할 것.
 */
declare function get(key: string, level?: Level, options?: GetOptions): Promise<AdmFeatureCollection>;

interface FindRow {
    version_key: string;
    level: Level;
    sidonm: string | null;
    sggnm: string | null;
    name: string;
    code: string | null;
    code7: string | null;
    code8: string | null;
    sggcd: string | null;
    sidocd: string | null;
}
interface FindOptions {
    level?: Level;
    /**
     * 이름 검색이면 `name` 컬럼 단독 완전 일치 (공백 포함 쿼리와 결합 불가).
     * 코드 검색이면 prefix 대신 **자릿수 완전일치**.
     */
    exact?: boolean;
    /**
     * `"name"` / `"code"` 로 검색 방식 강제. 생략하면 자동 판별
     * (숫자로만 이루어진 쿼리 → 코드 검색).
     */
    by?: "name" | "code";
    /** `[2025]` 단일 연도 / `[2000, 2005]` inclusive range. 길이 1 또는 2. */
    year?: number[];
    /** 인덱스 parquet 베이스 URL 오버라이드. */
    baseUrl?: string;
    /** 커스텀 fetch (테스트용). */
    fetch?: typeof fetch;
    signal?: AbortSignal;
}
declare function clearIndexCache(): void;
/**
 * 행정구역명 **또는 코드**로 버전 검색.
 *
 * 숫자로만 이루어진 쿼리는 자동으로 **코드 검색**이 된다 (행정구역명 중 숫자로만
 * 된 것은 없어 이름 검색과 충돌하지 않는다). `by` 로 강제 가능.
 *
 * ```ts
 * await find("종로구");        // 이름 검색
 * await find("11110");         // 코드 — 시군구 11110 + 하위 읍면동 전부
 * await find("1111051500");    // 코드 — 해당 읍면동
 * await find("11110", { by: "name" });   // 이름 검색 강제
 * ```
 *
 * 코드 검색은 **prefix 매칭**이라 자릿수를 정확히 맞추지 않아도 된다.
 * `"11"` → 시도 11 + 시군구 `11xxx` + 읍면동 `11xxxxxxxx` 전부.
 * `level` 로 좁히고, `exact: true` 면 자릿수 완전일치만.
 * `code`(행안부) / `code7` / `code8`(통계청) 셋 다 매칭 대상.
 */
declare function find(name: string, options?: FindOptions): Promise<FindRow[]>;
declare function findVersions(rows: FindRow[]): string[];
declare function findFirst(rows: FindRow[]): string | null;
declare function findLast(rows: FindRow[]): string | null;

/**
 * 출장소(出張所) 한 건.
 *
 * 출장소는 행안부 행정동 코드 체계에만 존재하고 **경계 지도가 없다**.
 * 그래서 `version_key` 대신 `created` / `abolished` (YYYYMMDD) 로 유효 기간을
 * 나타낸다. `abolished` 가 null 이면 현존.
 */
interface OfficeRow {
    /** 행안부 행정동 10자리. */
    code: string;
    name: string;
    sggnm: string | null;
    sidonm: string | null;
    sggcd: string | null;
    sidocd: string | null;
    /** 뒤 5자리가 00000 이면 "sgg", 아니면 "emd". */
    level: "sgg" | "emd";
    created: string | null;
    abolished: string | null;
}
interface FindOfficesOptions {
    /** 코드 완전일치 / 이름 완전일치. 기본은 prefix·substring. */
    exact?: boolean;
    /** `"name"` / `"code"` 로 검색 방식 강제. 생략하면 자동 판별. */
    by?: "name" | "code";
    baseUrl?: string;
    fetch?: typeof fetch;
    signal?: AbortSignal;
}
/**
 * 출장소 검색. 코드(prefix) 또는 이름(substring).
 *
 * **지도가 없으므로 `get()` 으로 경계를 받을 수 없고, `find()` 결과에도 포함되지
 * 않는다.** 코드를 넣었을 때 "이게 어디인지" 를 알려주기 위한 별도 경로.
 *
 * ```ts
 * await findOffices("2920083000");  // 광주 광산구 임곡출장소 (1995~1998 말소)
 * await findOffices("28265");       // 인천 서구 검단출장소
 * await findOffices("영종");         // 이름으로
 * ```
 */
declare function findOffices(query: string, options?: FindOfficesOptions): Promise<OfficeRow[]>;

interface CompareRow {
    version_key: string;
    emdcd: string;
    emdnm: string;
    sggcd: string | null;
    sggnm: string | null;
    sidocd: string | null;
    sidonm: string | null;
    shape_id: number;
    /** diff rows only: "changed" | "only_in_a" | "only_in_b". same rows omit. */
    status?: "changed" | "only_in_a" | "only_in_b";
    /** diff rows only. changed → 0–1, only_* → null. */
    iou?: number | null;
}
interface CompareResult {
    va: string;
    vb: string;
    threshold: number;
    same: CompareRow[];
    diff: CompareRow[];
}
interface CompareOptions extends LoaderOptions {
    /** shape_id 다를 때 iou >= threshold 면 same 으로 승격. 기본 0.99. */
    threshold?: number;
}
declare function compare(versions: [string, string], options?: CompareOptions): Promise<CompareResult>;

interface MatchEmdRow {
    version_key: string;
    emdcd: string;
    emdnm: string;
    sggcd: string | null;
    sggnm: string | null;
    sidocd: string | null;
    sidonm: string | null;
    area: number;
    weight: number;
}
interface MatchSggRow {
    version_key: string;
    sggcd: string;
    sggnm: string;
    sidocd: string | null;
    sidonm: string | null;
    area: number;
    weight: number;
}
interface MatchSidoRow {
    version_key: string;
    sidocd: string;
    sidonm: string;
    area: number;
    weight: number;
}
interface MatchOptions extends LoaderOptions {
    base: string;
    region: string;
    target: string | string[];
    /** weight 가 이 값 미만이면 결과에서 제외. 기본 0. */
    minWeight?: number;
}
interface MatchResult {
    base: string;
    region: string;
    targets: string[];
    emd: MatchEmdRow[];
    sgg: () => Promise<MatchSggRow[]>;
    sido: () => Promise<MatchSidoRow[]>;
}
declare function matchAdm(opts: MatchOptions): Promise<MatchResult>;

/** 인덱스 parquet 수정 이력 + 현재 data_version 조회. */

interface ChangelogEntry {
    /** YYYY.MM.DD 형식의 data_version 태그. */
    version: string;
    /** 사람이 읽는 한 줄 요약. */
    changes: string;
}
interface Manifest {
    data_version: string;
    schema_version: string;
    min_lib_version: string;
    created_at: string;
    /** 사용 가능한 버전 키 목록 (오름차순). 옛 배포에는 없을 수 있음 (optional). */
    versions?: string[];
    history: ChangelogEntry[];
    files: Record<string, {
        size: number;
        sha256: string;
    }>;
}
declare function clearManifestCache(): void;
/** 원격 manifest.json 을 받아 파싱. 프로세스 내 메모리 캐시. */
declare function fetchManifest(opts?: LoaderOptions): Promise<Manifest>;
/** 현재 원격 data_version (예: "2026.04.25"). 네트워크 실패 시 throw. */
declare function dataVersion(opts?: LoaderOptions): Promise<string>;
/** 인덱스 수정 이력. 최신이 [0]. */
declare function changelog(opts?: LoaderOptions): Promise<ChangelogEntry[]>;

export { type AdmFeature, type AdmFeatureCollection, type AdmProperties, type ChangelogEntry, type CompareOptions, type CompareResult, type CompareRow, type EmdProperties, type FindOfficesOptions, type FindOptions, type FindRow, type GetOptions, type Level, type Manifest, type MatchEmdRow, type MatchOptions, type MatchResult, type MatchSggRow, type MatchSidoRow, type OfficeRow, type SggProperties, type SidoProperties, VERSIONS, type VersionKey, changelog, clearIndexCache, clearManifestCache, compare, dataVersion, fetchManifest, find, findFirst, findLast, findOffices, findVersions, get, getParquet, matchAdm, versions, versionsAsync };