@mapslibvn/core 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,424 @@
+interface AttributionLink {
+    text: string;
+    href: string;
+    license?: string;
+}
+declare const ATTRIBUTION_LINKS: readonly AttributionLink[];
+declare function attributionText(): string;
+declare function attributionHtml(): string;
+
+/**
+ * Nguồn POI và profile archive (spec 07/09 mục 4). Đây là nguồn sự thật duy nhất cho API, SDK và
+ * pipeline: thêm profile mới = thêm một dòng vào POI_SOURCE_PROFILES + một lần export-tiles.
+ */
+declare const POI_SOURCES: readonly ["osm", "overture", "fsq"];
+type PoiSource = (typeof POI_SOURCES)[number];
+declare const POI_SOURCE_PROFILES: {
+    readonly all: readonly ["osm", "overture", "fsq"];
+    readonly osm: readonly ["osm"];
+    readonly 'osm-fsq': readonly ["osm", "fsq"];
+    readonly 'overture-fsq': readonly ["overture", "fsq"];
+    readonly overture: readonly ["overture"];
+    readonly fsq: readonly ["fsq"];
+};
+type PoiSourceProfile = keyof typeof POI_SOURCE_PROFILES;
+/**
+ * Mặc định ở mọi bề mặt (REST và SDK): cả ba nguồn, tức đúng hành vi trước khi có tuỳ chọn này.
+ * Đo 07/09/2026 cho thấy OSM chỉ là nguồn chính của 7 % POI, nên mặc định `osm` sẽ làm bản đồ mất
+ * ~93 % dữ liệu (`docs/evidence/poi-sources/do-truoc-primary-source.md`).
+ */
+declare const DEFAULT_POI_SOURCES: readonly PoiSource[];
+/** Bỏ trùng, sắp theo thứ tự POI_SOURCES. Rỗng hoặc có giá trị lạ → null. */
+declare function normalizePoiSources(list: readonly string[]): PoiSource[] | null;
+/**
+ * Chuỗi `sources=` của REST và thuộc tính `sources` của web component: phân cách dấu phẩy,
+ * `all` là bí danh cả ba; undefined/rỗng → mặc định; giá trị lạ → null (caller quyết định lỗi).
+ */
+declare function parsePoiSourcesCsv(raw: string | undefined | null): PoiSource[] | null;
+/** Khoá ổn định cho cache key và query string. */
+declare function poiSourcesKey(sources: readonly PoiSource[]): string;
+/** Tập nguồn → profile có archive; null nếu chưa build tổ hợp đó. */
+declare function profileForSources(sources: readonly PoiSource[]): PoiSourceProfile | null;
+/**
+ * Mệnh đề lọc dùng chung cho export-tiles và Places API; bảng `poi` phải có alias `p`.
+ * `arrayExpr` là biểu thức text[]: `$1::text[]` (postgres.js) hoặc `ARRAY['osm']::text[]` (pipeline).
+ * POI người dùng tạo có primary_source NULL và luôn được giữ.
+ */
+declare function poiSourceClause(arrayExpr: string): string;
+
+/** Kiểu dữ liệu Places API (spec 6.1) dùng chung cho Worker và SDK. */
+interface PlaceCategory {
+    code: string;
+    group: string;
+    name_vi: string;
+    name_en: string;
+}
+interface PlaceAddress {
+    housenumber?: string;
+    street?: string;
+    ward?: string;
+    province?: string;
+    text?: string;
+}
+interface Place {
+    id: string;
+    name: string;
+    category: PlaceCategory | null;
+    lat: number;
+    lng: number;
+    address: PlaceAddress;
+    contact?: Record<string, unknown> | null;
+    hours?: unknown;
+    quality_score: number | null;
+    status: 'active' | 'closed' | 'pending' | 'rejected';
+    updated_at: string;
+}
+interface PlaceSource {
+    source: 'osm' | 'overture' | 'fsq';
+    source_id: string;
+    role: 'primary' | 'secondary';
+}
+interface PlaceDetails extends Place {
+    sources: PlaceSource[];
+    attribution: {
+        text: string;
+        html: string;
+    };
+}
+type GeocodePrecision = 'rooftop' | 'alley' | 'interpolated' | 'street' | 'ward' | 'district' | 'province';
+type AutocompleteType = 'poi' | 'street' | 'address' | 'area';
+interface AutocompleteItem {
+    type: AutocompleteType;
+    id?: string;
+    name: string;
+    secondary: string;
+    lat: number;
+    lng: number;
+    precision?: GeocodePrecision;
+    score: number;
+    bbox?: [number, number, number, number];
+    /** Tên thay thế (OSM `alt_name`/`old_name`) đã khớp truy vấn, ví dụ "Công Lý" (spec 6.3). */
+    matched_alt?: string;
+}
+interface GeocodeMatched {
+    housenumber?: string;
+    street?: string;
+    ward?: string;
+    province?: string;
+    former?: {
+        ward?: string;
+        district?: string;
+        province?: string;
+    };
+}
+interface GeocodeItem {
+    lat: number;
+    lng: number;
+    precision: GeocodePrecision;
+    confidence: number;
+    matched: GeocodeMatched;
+    display_name: string;
+    bbox?: [number, number, number, number];
+}
+interface ReverseAddress {
+    approx_housenumber?: string;
+    street?: string;
+    ward?: string;
+    province?: string;
+    display_name: string;
+}
+interface ReverseResponse {
+    address: ReverseAddress;
+    nearest_poi: Place | null;
+}
+type EditKind = 'create' | 'update' | 'close' | 'reopen' | 'report';
+/** Trường được phép sửa/khai khi đóng góp (spec 6.1 + 6.5). */
+interface EditChanges {
+    name?: string;
+    lat?: number;
+    lng?: number;
+    category?: string;
+    housenumber?: string;
+    street?: string;
+    ward?: string;
+    province?: string;
+    address_text?: string;
+    contact?: {
+        phone?: string[];
+        website?: string[];
+        facebook?: string;
+    };
+    /** Chuỗi opening_hours OSM hoặc {osm: chuỗi}. */
+    hours?: string | {
+        osm: string;
+    };
+}
+interface SuggestEditRequest {
+    /** Bắt buộc trừ kind='create'. */
+    poi_id?: string;
+    kind: EditKind;
+    changes?: EditChanges;
+    photo_url?: string;
+    note?: string;
+    /** Chuỗi ổn định theo người dùng cuối do app nhúng cấp — server chỉ lưu bản băm. */
+    end_user_token: string;
+}
+interface SuggestEditResponse {
+    edit_id: number;
+    status: 'pending' | 'auto_approved';
+    /** POI đích; với kind='create' là id POI mới (pending cho tới khi được duyệt). */
+    poi_id: string | null;
+}
+/** POI đọc từ tile lớp `poi` khi người dùng bấm — SDK web và React Native dùng chung. */
+interface PoiFeature {
+    id: string;
+    name: string;
+    category: string;
+    group: string;
+    lngLat: [number, number];
+}
+
+type Theme = 'light' | 'dark';
+interface ClientOptions {
+    /** Khoá API dạng mlv_live_… */
+    apiKey: string;
+    /** Gốc API, ví dụ https://maps-api.example.com */
+    baseUrl: string;
+    /** Cho phép tiêm fetch cho test hoặc môi trường không có global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Header thêm cho mọi request, ví dụ `X-Bundle-Id` cho khoá `mobile` (spec 6.4).
+     * Không ghi đè được `X-Api-Key`.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Tập nguồn POI cho bản đồ và Places API (spec 07/09). Mặc định cả ba nguồn.
+     * Áp cho autocomplete/search/nearby/reverse và `styleUrl`; `getPlace`/`geocode` không lọc.
+     */
+    poiSources?: readonly PoiSource[];
+}
+interface AttributionResponse {
+    text: string;
+    html: string;
+    links: {
+        text: string;
+        href: string;
+        license?: string;
+    }[];
+}
+declare function createClient(options: ClientOptions): {
+    baseUrl: string;
+    attribution: () => Promise<AttributionResponse>;
+    styleUrl: (theme: Theme) => string;
+    autocomplete: (q: string, opts?: {
+        near?: [number, number];
+        limit?: number;
+        types?: AutocompleteType[];
+    }) => Promise<{
+        items: AutocompleteItem[];
+    }>;
+    search: (q: string, opts?: {
+        category?: string;
+        near?: [number, number];
+        radius?: number;
+        bbox?: [number, number, number, number];
+        limit?: number;
+        offset?: number;
+    }) => Promise<{
+        items: Place[];
+        total: number;
+    }>;
+    nearby: (opts: {
+        lat: number;
+        lng: number;
+        radius?: number;
+        category?: string;
+        limit?: number;
+    }) => Promise<{
+        items: Place[];
+    }>;
+    getPlace: (id: string) => Promise<PlaceDetails>;
+    geocode: (q: string, opts?: {
+        near?: [number, number];
+        limit?: number;
+    }) => Promise<{
+        items: GeocodeItem[];
+    }>;
+    reverse: (lat: number, lng: number) => Promise<ReverseResponse>;
+    /** Gửi đóng góp/sửa POI (spec 6.1). Khoá phải có scope edits:write. */
+    suggestEdit: (edit: SuggestEditRequest) => Promise<SuggestEditResponse>;
+};
+type MapsLibVNClient = ReturnType<typeof createClient>;
+
+declare class MapsLibVNError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId: string | undefined;
+    constructor(status: number, code: string, message: string, requestId?: string);
+}
+
+/** Từ đệm bị bỏ ở đầu tên POI khi so khớp (spec 5.3 bước 5; thêm `mtv`). Không dùng cho hiển thị. */
+declare const NAME_FILLERS: string[];
+/** Bỏ dấu tiếng Việt (giữ chữ hoa/thường), đ → d. */
+declare function stripDiacritics(s: string): string;
+/** Thay viết tắt (bảng abbrev.json) trên chuỗi đã lowercase + bỏ dấu; `f` trước số → `phuong`. */
+declare function expandAbbrev(s: string): string;
+/** Chuẩn hoá spec 5.3 bước 1–4: NFC → lowercase → bỏ dấu → viết tắt → bỏ dấu câu (giữ `/`, `-`) → gộp khoảng trắng. */
+declare function normalizeVi(input: string): string;
+/** Alias thương hiệu: chỉ thay khi biến thể đứng đầu chuỗi (hoặc bằng cả chuỗi). */
+declare function applyBrandAlias(s: string): string;
+/** Tên rút gọn để so khớp trigram (spec 5.3 bước 5–6). Nếu bỏ hết từ đệm mà rỗng thì giữ tên chuẩn hoá. */
+declare function nameCore(input: string): string;
+
+type AlleyKeyword = 'hem' | 'ngo' | 'ngach' | 'kiet';
+/** Kết quả phân tích địa chỉ (spec 5.7). Trường vắng = không nhận diện được. */
+interface ParsedAddress {
+    housenumber?: string;
+    alleyChain: string[];
+    houseInAlley?: string;
+    alleyKeyword?: AlleyKeyword;
+    street?: string;
+    streetNorm?: string;
+    ward?: string;
+    district?: string;
+    province?: string;
+    adminOriginal?: {
+        ward?: string;
+        district?: string;
+        province?: string;
+    };
+    confidence: number;
+}
+declare function parseAddress(input: string): ParsedAddress;
+
+type AdminAliasKeyInput = Pick<ParsedAddress, 'ward' | 'district' | 'province' | 'adminOriginal'>;
+/** Sinh khóa alias từ cụ thể đến rộng; pipeline quyết định khóa ngắn nào đủ duy nhất để publish. */
+declare function adminAliasKeys(input: AdminAliasKeyInput): string[];
+
+/**
+ * Biến đổi style JSON thuần (không cần Map đang chạy) — dùng cho React Native, nơi wrapper
+ * không có API đổi layout property của lớp có sẵn. Web dùng `applyLanguage` lúc chạy nhưng
+ * chia sẻ `nameExpression`/`isNameLabelLayer` từ đây.
+ */
+type Lang = 'vi' | 'en';
+interface StyleLayerLike {
+    id: string;
+    type: string;
+    source?: string | undefined;
+    layout?: Record<string, unknown> | undefined;
+}
+interface StyleLike {
+    layers?: readonly StyleLayerLike[] | undefined;
+}
+declare const POI_LAYER_ID = "poi";
+declare function isPoiStyleLayer(layer: StyleLayerLike): boolean;
+declare function nameExpression(lang: Lang): unknown[];
+/** Lớp nhãn tên (symbol có `text-field` tham chiếu `name`), trừ lớp chủ quyền luôn tiếng Việt. */
+declare function isNameLabelLayer(layer: StyleLayerLike): boolean;
+/** Đổi nhãn sang `lang`. `vi` là mặc định của style nên trả nguyên object. */
+declare function localizeStyle<T extends StyleLike>(style: T, lang: Lang): T;
+/** Ẩn lớp POI bằng `layout.visibility = 'none'`; trả style mới. */
+declare function hidePoiLayer<T extends StyleLike>(style: T): T;
+
+interface SearchKeys {
+    /** `viKey(applyToponymAlias(name_norm))` — cột `name_key`/`alias_key`. */
+    nameKey: string;
+    /** Tên thay thế đã `normalizeVi`, nối `' | '` giữ biên từ; null khi không có. Thứ tự = `name_alt`. */
+    nameAltNorm: string | null;
+}
+/**
+ * Nguồn sự thật duy nhất cho cột dẫn xuất tìm kiếm (spec 05/09 mục 6.1–6.3). Pipeline, backfill và
+ * test đối chiếu dbtest đều gọi hàm này, để không tồn tại hai định nghĩa `name_key`.
+ *
+ * `nameNorm` phải đã `normalizeVi`. `nameAlt` là mảng gốc (chưa chuẩn hoá) của OSM; phần tử rỗng,
+ * trùng nhau sau chuẩn hoá, hoặc trùng chính `nameNorm` đều bị bỏ, nhưng thứ tự KHÔNG đổi —
+ * `matched_alt` trong API dựa vào việc `name_alt` và `string_to_array(name_alt_norm, ' | ')` thẳng
+ * hàng theo chỉ số, nên pipeline phải ghi `name_alt` đã lọc bằng `filterNameAlt` dưới đây.
+ *
+ * Dấu `|` trong tên gốc không phá dấu phân cách vì `normalizeVi` chỉ giữ `a-z0-9/-` và khoảng
+ * trắng — mọi ký tự khác thành khoảng trắng.
+ */
+declare function searchKeys(nameNorm: string, nameAlt: readonly string[] | null | undefined): SearchKeys;
+/**
+ * Lọc `name_alt` theo đúng luật của `searchKeys`, để pipeline ghi mảng GỐC thẳng hàng với
+ * `name_alt_norm`. Trả về phần tử gốc, không phải dạng đã chuẩn hoá — cột `name_alt` dùng để
+ * hiển thị (`matched_alt`) nên phải giữ dấu.
+ */
+declare function filterNameAlt(nameNorm: string, nameAlt: readonly string[] | null | undefined): string[];
+
+/** Chuỗi có dấu hiệu người dùng gõ telex/VNI mà chưa được bộ gõ chuyển thành dấu. */
+declare function looksLikeTelex(normalized: string): boolean;
+/**
+ * Gập telex/VNI còn sót: `aa→a`, `ee→e`, `oo→o`, `dd→d`, `aw→a`, `ow→o`, `uw→u`; bỏ `s f r x j`
+ * đứng cuối từ khi trước nó là nguyên âm hoặc phụ âm cuối hợp lệ (xem mục mở rộng dưới); bỏ chữ
+ * số 1–9 dính cuối từ.
+ *
+ * Chỉ áp cho **truy vấn**, không bao giờ cho dữ liệu — đây là bậc 3b, chạy khi mọi bậc trước rỗng
+ * và chỉ khi `looksLikeTelex` đúng. Mặc định **tắt** ở lần phát hành đầu (cờ `AUTOCOMPLETE_TELEX`),
+ * bật sau khi log `stage_hit` cho thấy tỷ lệ truy vấn rỗng khớp mẫu telex đáng kể.
+ *
+ * **Mở rộng so với spec 5.6, có lý do:** spec chỉ nói bỏ dấu "sau nguyên âm", nhưng trong telex
+ * thật dấu đứng ở CUỐI ÂM TIẾT, tức sau cả phụ âm cuối — `ddoongf` (Đồng) có `f` sau `ng`. Theo
+ * đúng chữ của spec thì `ddoongf` chỉ gập được thành `dongf`, còn nguyên chữ `f`, làm bậc 3b gần
+ * như vô dụng với âm tiết đóng. Nên nới thành: bỏ `s f r x j` ở cuối từ khi ngay trước nó là
+ * nguyên âm **hoặc** một phụ âm cuối hợp lệ của tiếng Việt (`c ch m n ng nh p t`).
+ *
+ * Điều kiện này chính là thứ giữ cho tên nước ngoài không bị cắt: `highlands` có `d` trước `s` mà
+ * `d` không phải phụ âm cuối hợp lệ → giữ nguyên; `starbucks` có `k` → giữ nguyên. Còn `viets` thì
+ * `t` là phụ âm cuối hợp lệ → thành `viet`.
+ */
+declare function foldTelex(normalized: string): string;
+
+interface ToponymEntry {
+    /** Biến thể đã `normalizeVi`, khác dạng chuẩn. */
+    variants: string[];
+    /** Nguồn kiểm được: `osm:<type>/<id> <tag>` hoặc `wikipedia:vi:<trang>`. */
+    source: string;
+}
+/**
+ * Dạng chuẩn → biến thể địa danh, mỗi mục có nguồn (spec 05/09 mục 6.1). Pipeline và API dùng
+ * **cùng** bảng này: dữ liệu qua `searchKeys`, truy vấn qua nhánh `qAlias` ở bậc 1.
+ *
+ * Khoá `$comment` trong JSON bị bỏ khi nạp — nó là tài liệu biên soạn, không phải dữ liệu.
+ */
+declare const TOPONYM_ALIAS: Record<string, ToponymEntry>;
+/**
+ * Thay biến thể địa danh bằng dạng chuẩn ở **bất kỳ vị trí** theo biên từ — khác
+ * `applyBrandAlias` vốn chỉ thay ở đầu chuỗi. Đầu vào phải đã `normalizeVi`.
+ *
+ * Dùng hai chỗ: dữ liệu (`searchKeys` → cột `name_key`) và truy vấn (nhánh `qAlias` ở bậc 1 của
+ * autocomplete). Nhờ nhánh truy vấn mà biến thể khớp được **ngay**, không phải chờ pipeline chạy
+ * lại để điền `name_key`.
+ */
+declare function applyToponymAlias(normalized: string): string;
+
+/**
+ * Khoá ngữ âm cho tiếng Việt không dấu (spec 05/09 mục 6.2).
+ *
+ * Đầu vào phải là chuỗi đã `normalizeVi` (và nên đã qua `applyToponymAlias` — xem `searchKeys`).
+ * Áp luật theo **từng từ** theo thứ tự đầu từ → âm cuối → i/y, rồi **nối không khoảng trắng**.
+ * Chỉ giữ `[a-z0-9]`, nên `/` và `-` trong số nhà bị bỏ.
+ *
+ * Việc nối giúp phần lớn ca dính/tách từ cho cùng khoá (`sai gon` = `saigon`), nhưng **không phải
+ * mọi ca**: luật đầu từ chỉ áp ở đầu TỪ, nên `nhac trang` → `nhaccan` (tr→c) trong khi `nhatrang`
+ * → `nhatran` (tr nằm giữa từ). Tương tự `plei ku` → `pleicu` nhưng `pleiku` → `pleiku`. Fixture
+ * `vi-key.csv` ghi rõ hai nhóm này.
+ *
+ * **Giới hạn thứ hai, nặng hơn, đo trên production 08/09/2026:** vì nối không khoảng trắng, khoá
+ * của một tên NHIỀU TỪ là một cục (`Hủ Tiếu Mỹ Tho Thanh Xuân` → `hutieumithothanhxuan`). Bậc 3
+ * lọc bằng `word_similarity(qKey, name_key)`, mà `word_similarity` so theo **ranh giới từ** trong
+ * chuỗi đích — với khoá một cục thì không còn ranh giới nào, nên `mitho` gần như không khớp. Hệ
+ * quả: bậc 3 chỉ cứu được tên **ngắn** (`kontum` → Kon Tum, `bin than` → Bình Thạnh) và bất lực
+ * với mọi tên dài. Đối chứng: `my tho` gõ ĐÚNG chính tả cũng chỉ đưa `area Phường Mỹ Tho` lên
+ * hạng 10, và đó là do `withAreaSlot` nhét vào suất cuối chứ không phải do điểm.
+ *
+ * Sửa gốc là sinh khoá **giữ ranh giới từ**, nhưng việc đó đổi cột `name_key`/`alias_key` nên phải
+ * migration + backfill lại 1,52 triệu POI và đo lại bộ mờ 40 truy vấn. Chưa làm; ghi ở đây để lần
+ * sau có căn cứ. Xem docs/evidence/search-keys/16-nghiem-thu-production.md.
+ *
+ * Dùng ở **bậc 3** của autocomplete, sau các bậc chính xác hơn, nên việc luật gộp hơi rộng
+ * (`gi/r/d`, `tr/ch`, âm cuối miền Nam) chỉ ảnh hưởng thứ tự trong nhóm mờ.
+ */
+declare function viKey(normalized: string): string;
+
+export { ATTRIBUTION_LINKS, type AdminAliasKeyInput, type AlleyKeyword, type AttributionLink, type AttributionResponse, type AutocompleteItem, type AutocompleteType, type ClientOptions, DEFAULT_POI_SOURCES, type EditChanges, type EditKind, type GeocodeItem, type GeocodeMatched, type GeocodePrecision, type Lang, type MapsLibVNClient, MapsLibVNError, NAME_FILLERS, POI_LAYER_ID, POI_SOURCES, POI_SOURCE_PROFILES, type ParsedAddress, type Place, type PlaceAddress, type PlaceCategory, type PlaceDetails, type PlaceSource, type PoiFeature, type PoiSource, type PoiSourceProfile, type ReverseAddress, type ReverseResponse, type SearchKeys, type StyleLayerLike, type StyleLike, type SuggestEditRequest, type SuggestEditResponse, TOPONYM_ALIAS, type Theme, type ToponymEntry, adminAliasKeys, applyBrandAlias, applyToponymAlias, attributionHtml, attributionText, createClient, expandAbbrev, filterNameAlt, foldTelex, hidePoiLayer, isNameLabelLayer, isPoiStyleLayer, localizeStyle, looksLikeTelex, nameCore, nameExpression, normalizePoiSources, normalizeVi, parseAddress, parsePoiSourcesCsv, poiSourceClause, poiSourcesKey, profileForSources, searchKeys, stripDiacritics, viKey };