@lokal-id/core 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lokal contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @lokal-id/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@lokal-id/core?color=cb3837)](https://www.npmjs.com/package/@lokal-id/core)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/lokal-id/lokal/blob/HEAD/LICENSE)
+
+Indonesian data primitives for apps and AI agents: NIK, NPWP, phone numbers, Rupiah, *terbilang*, holidays and working days, Kemendagri regions with postal codes, and **Samaran**, which masks Indonesian personal data before it reaches an LLM and restores it afterwards.
+
+No dependencies. Part of [Lokal](https://github.com/lokal-id/lokal) · [Bahasa Indonesia](https://github.com/lokal-id/lokal/blob/HEAD/README.id.md)
+
+## Install
+
+```sh
+npm install @lokal-id/core
+```
+
+## Usage
+
+```ts
+import { parseNik, parsePhone, formatRupiah, parseRupiah, terbilang, addWorkingDays, Samaran } from '@lokal-id/core';
+import { listWilayah, searchWilayah, wilayahName, findByPostalCode } from '@lokal-id/core/wilayah';
+
+parseNik('3201011508950001', { lookupWilayah: wilayahName });
+// { valid: true, province: 'Jawa Barat', regency: 'Kabupaten Bogor', gender: 'L', birthDate: '1995-08-15', … }
+parsePhone('0812 3456 7890');           // { e164: '+6281234567890', operator: 'Telkomsel', … }
+formatRupiah(1500000);                  // 'Rp1.500.000'
+parseRupiah('sejuta setengah');         // { amount: 1500000, approximate: false }
+terbilang(1500000, { currency: true }); // 'satu juta lima ratus ribu rupiah'
+addWorkingDays('2026-03-17', 1);        // '2026-03-25', skipping Nyepi and Lebaran
+listWilayah('32.76');                   // districts of Kota Depok
+findByPostalCode('16431');              // villages that use this postal code
+```
+
+### Samaran
+
+```ts
+const samaran = new Samaran();
+const { text } = samaran.mask('nama saya budi santoso, NIK 3201011508950001, HP 0812-3456-7890');
+// 'nama saya [NAME_1], NIK [NIK_1], HP [PHONE_1]'
+
+samaran.unmask(await llm(text));        // placeholders are replaced with the original values
+```
+
+The same value always gets the same placeholder, so the model can still deduplicate and join. Use `mode: 'partial'` for logs and admin screens (`3201********0001`).
+
+`@lokal-id/core/wilayah` loads about 4.4 MB of region data and runs on Node only. The main entry point does not load it and is safe for browsers.
+
+## Data
+
+| Data | Source |
+|---|---|
+| Regions: 38 provinces, 416 regencies, 98 cities, 7,285 districts, 8,496 *kelurahan*, 75,266 villages | [cahyadsn/wilayah](https://github.com/cahyadsn/wilayah) (MIT), following Kepmendagri 300.2.2-2138/2025 |
+| Postal codes for all 83,762 villages | [cahyadsn/wilayah_kodepos](https://github.com/cahyadsn/wilayah_kodepos) (MIT) |
+| Holidays and *cuti bersama* for 2026 and 2027 | SKB 3 Menteri. Other years return an error, not a guess |
+
+Detection limits and full documentation are in the [Lokal README](https://github.com/lokal-id/lokal#limitations).
+
+## License
+
+[MIT](https://github.com/lokal-id/lokal/blob/HEAD/LICENSE)

package/data/LICENSE-kodepos.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Cahya DSN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/data/LICENSE-wilayah.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-2025 Cahya DSN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/data/README.md

@@ -0,0 +1,14 @@
+# Data wilayah
+
+`wilayah.json` (provinsi, kabupaten/kota, kecamatan) and `desa.json` (kelurahan/desa) are generated from
+[cahyadsn/wilayah](https://github.com/cahyadsn/wilayah) `db/wilayah.sql`, which follows
+Kepmendagri No 300.2.2-2138 Tahun 2025 (as amended by 300.2.2-2430 Tahun 2025, which only reassigns four islands). The
+totals match the decree exactly: 38 provinsi, 416 kabupaten, 98 kota, 7,285 kecamatan, 8,496 kelurahan, 75,266 desa.
+That data is MIT-licensed; see `LICENSE-wilayah.txt`.
+
+Regenerate after a new Kepmendagri decree:
+
+```sh
+curl -L -o wilayah.sql https://raw.githubusercontent.com/cahyadsn/wilayah/master/db/wilayah.sql
+npm run data:wilayah -w @lokal-id/core -- path/to/wilayah.sql
+```