@geoalgeria/poste 1.0.1 → 1.1.0

package/README.md

@@ -1,47 +1,81 @@
+<div align="center">
+
 # @geoalgeria/poste
 
-Algeria **post offices** and **ATMs** with real postal codes, bilingual
-(French / Arabic) names, geographic coordinates, and commune/wilaya linkage.
+**Every Algérie Poste office and ATM — as data you can install.**
+
+[![npm](https://img.shields.io/npm/v/@geoalgeria/poste)](https://www.npmjs.com/package/@geoalgeria/poste)
+[![npm downloads](https://img.shields.io/npm/dm/@geoalgeria/poste)](https://www.npmjs.com/package/@geoalgeria/poste)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+</div>
+
+3,908 post offices and 2,026 ATMs across Algeria — with **real postal codes**, bilingual (French / Arabic) names, GPS coordinates, and commune/wilaya linkage. Sourced from Algérie Poste, shipped as JSON, CSV, and GeoJSON. Part of [GeoAlgeria](https://github.com/yasserstudio/geoalgeria).
+
+```bash
+npm install @geoalgeria/poste
+```
+
+```js
+import poste from "@geoalgeria/poste";
+
+const offices = poste.postOffices();   // 3,908
+const atms = poste.atms();             // 2,026
+
+// Post offices in a commune (joins GeoAlgeria's code_commune)
+const inAdrar = offices.filter((o) => o.commune_code === "0101");
+
+// Nearest ATM? Everything has lat/lng to compute against.
+```
+
+## What you can build
+
+- **Postal-code validation & lookup** — every office carries its real `postal_code`.
+- **Branch / ATM locators** — coordinates on (almost) every record, ready for distance sorting or a map.
+- **Fintech & logistics** — match addresses to the nearest post office or GAB.
+- **Maps** — drop-in GeoJSON point layers for the whole postal network.
+
+## What's inside
 
 | Dataset | Count | Notes |
 | --- | --- | --- |
-| Post offices | **3,908** | each with its own postal code (`cp`) |
+| Post offices | **3,908** | each with its own postal code (`postal_code`) |
 | ATMs | **2,026** | Algérie Poste GAB network |
-| Distinct postal codes | **3,908** | one per office |
 
-## Source
+## Formats
 
-Data is sourced from **Algérie Poste** via the public BaridiMap API
-(<https://baridimap.poste.dz>):
+The npm package ships the **JSON** (importable directly):
 
-- `GET https://baridimap-api.poste.dz/api/postoffices`
-- `GET https://baridimap-api.poste.dz/api/atms`
+```js
+import offices from "@geoalgeria/poste/data/postoffices.json" with { type: "json" };
+// or via CDN, no install:
+// https://cdn.jsdelivr.net/npm/@geoalgeria/poste/data/postoffices.json
+```
 
-Run `npm run fetch` (or `node scripts/fetch.mjs`) to regenerate every output
-from the live API. The same run also mirrors the data into the sibling
-`geoalgeria` package at `packages/dataset/data/poste/`, so the two never drift —
-this package is the canonical source. Re-fetch periodically — Algérie Poste
-updates offices and, eventually, the post-2025 wilaya reorganization (BaridiMap
-currently still files offices under the 58-wilaya scheme, so new wilayas 59–69
-appear under their mother wilaya).
+The loaders and record shapes are fully **typed** — TypeScript definitions ship in the package:
 
-## Files
+```ts
+import poste, { type PostOffice, type Atm } from "@geoalgeria/poste";
+const offices: PostOffice[] = poste.postOffices();
+```
+
+**CSV and GeoJSON** are in the repo under [`data/`](data) and bundled in every
+[GitHub Release](https://github.com/yasserstudio/geoalgeria/releases):
 
 ```
 data/
-  postoffices.json          # 3908 offices (array)
-  atms.json                 # 2026 ATMs (array)
-  metadata.json             # source, counts, generated_at
-  csv/postoffices.csv
+  postoffices.json            # 3,908 offices (array)
+  atms.json                   # 2,026 ATMs (array)
+  metadata.json               # source, counts, generated_at
+  csv/postoffices.csv         # repo + Release bundle (not in npm tarball)
   csv/atms.csv
-  geojson/postoffices.geojson   # Point features (offices with coordinates)
+  geojson/postoffices.geojson # Point features (records with coordinates)
   geojson/atms.geojson
 ```
 
-> GeoJSON files include only records that have coordinates — a handful of
-> offices and ATMs report no `lat`/`lng` and are omitted from the GeoJSON
-> outputs (but remain in the JSON/CSV). ATM records have no `commune_code`
-> (the source API does not provide one).
+> GeoJSON includes only records that have coordinates — a handful of offices and
+> ATMs report no `lat`/`lng` and are omitted there (but remain in JSON/CSV). ATM
+> records have no `commune_code` (the source API doesn't provide one).
 
 ## Record shapes
 
@@ -54,7 +88,6 @@ data/
   "name_ar": "أدرار م ر",
   "class": "CE",
   "postal_code": "01000",
-  "postal_code_old": null,
   "address": "ADRAR CENTRE RUE DES MARYTIM",
   "commune_code": "0101",
   "commune_fr": "ADRAR",
@@ -67,46 +100,29 @@ data/
 }
 ```
 
-`class` is the office category (`CE`, `R1`–`R4`, `HC`, `GA`). `commune_code`
-is Algérie Poste's 4-digit commune code, which joins to GeoAlgeria's
-`code_commune` field.
+`class` is the office category (`CE`, `R1`–`R4`, `HC`, `GA`). `commune_code` is
+Algérie Poste's 4-digit commune code, which joins to GeoAlgeria's `code_commune`.
 
-**ATM**
+**ATM** — same shape, keyed by `id`/`name`/`postal_code`/`wilaya_*` with `lat`/`lng`; no `commune_code`.
 
-```json
-{
-  "id": "1165",
-  "name": "AOULEF",
-  "status": "1",
-  "postal_code": "01003",
-  "postal_code_old": null,
-  "address": null,
-  "commune_fr": "AOULEF",
-  "commune_ar": "أولف",
-  "wilaya_code": "01",
-  "wilaya_fr": "ADRAR",
-  "wilaya_ar": "أدرار",
-  "lat": 26.9728317,
-  "lng": 1.07709
-}
-```
-
-## Usage
-
-```js
-import poste from "@geoalgeria/poste";
+## Need the administrative divisions too?
 
-const offices = poste.postOffices();      // 3908
-const banks = poste.atms();               // 2026
+If you also need wilayas, dairas, and communes, use the main
+**[`geoalgeria`](https://www.npmjs.com/package/geoalgeria)** package — it mirrors
+this postal data in and exposes `postOffices` / `atms` alongside the full
+division dataset. Use `@geoalgeria/poste` when you *only* need postal/banking data.
 
-// All post offices in a commune (joins GeoAlgeria code_commune -> commune_code)
-const inCommune = offices.filter((o) => o.commune_code === "1731");
-```
+## Source
 
-Or load a specific format directly: `@geoalgeria/poste/data/geojson/atms.geojson`.
+Data comes from **Algérie Poste** via the public BaridiMap API
+(<https://baridimap.poste.dz>). Run `npm run fetch` to regenerate every output
+from the live API; the same run mirrors the data into the `geoalgeria` package so
+the two never drift (this package is the canonical source). Re-fetch periodically
+— BaridiMap still files offices under the 58-wilaya scheme, so new wilayas 59–69
+currently appear under their mother wilaya.
 
 ## License & attribution
 
-Code is MIT. The underlying data is © **Algérie Poste** and is redistributed
-here for reference and to power [GeoAlgeria](https://geoalgeria.com). Verify
-against Algérie Poste for authoritative, real-time information.
+Code is [MIT](LICENSE). The underlying data is © **Algérie Poste**, redistributed
+for reference and to power [GeoAlgeria](https://geoalgeria.com). Verify against
+Algérie Poste for authoritative, real-time information.

package/package.json

@@ -1,19 +1,25 @@
 {
   "name": "@geoalgeria/poste",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "type": "module",
   "description": "Algeria post offices (3908) and ATMs (2026) — real postal codes, bilingual names, coordinates, commune/wilaya linkage. Sourced from Algérie Poste (baridimap.poste.dz). JSON, CSV, GeoJSON.",
   "main": "index.js",
+  "types": "types/index.d.ts",
   "exports": {
-    ".": "./index.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./index.js"
+    },
     "./data/*": "./data/*"
   },
   "files": [
     "data/**/*.json",
+    "types/",
     "index.js"
   ],
   "scripts": {
-    "fetch": "node scripts/fetch.mjs"
+    "fetch": "node scripts/fetch.mjs",
+    "test": "node ../../scripts/validate-packages.mjs poste"
   },
   "keywords": [
     "algeria",

package/types/index.d.ts

@@ -0,0 +1,93 @@
+// Type definitions for @geoalgeria/poste
+// Data sourced from Algérie Poste (baridimap.poste.dz).
+
+/** A post office (bureau de poste). */
+export interface PostOffice {
+  /** Numeric office id. */
+  id: number;
+  /** Office name (French / transliterated). */
+  name: string;
+  /** Office name in Arabic. */
+  name_ar: string;
+  /** Office class/category (e.g. "RP"). */
+  class: string;
+  /** 5-digit postal code. */
+  postal_code: string;
+  /** Previous postal code, if the office was renumbered. */
+  postal_code_old: string | null;
+  /** Street address. */
+  address: string;
+  /** 4-digit zero-padded commune code; links to geoalgeria communes. */
+  commune_code: string;
+  /** Commune name in French. */
+  commune_fr: string;
+  /** Commune name in Arabic. */
+  commune_ar: string;
+  /** Wilaya code as a string ("1".."58"). */
+  wilaya_code: string;
+  /** Wilaya name in French. */
+  wilaya_fr: string;
+  /** Wilaya name in Arabic. */
+  wilaya_ar: string;
+  /** Latitude, or null when the office is not geocoded. */
+  lat: number | null;
+  /** Longitude, or null when the office is not geocoded. */
+  lng: number | null;
+}
+
+/** An ATM (distributeur automatique). */
+export interface Atm {
+  /** ATM id. */
+  id: string;
+  /** ATM name/label. */
+  name: string;
+  /** Operational status. */
+  status: string;
+  /** 5-digit postal code of the hosting office. */
+  postal_code: string;
+  /** Previous postal code, if renumbered. */
+  postal_code_old: string | null;
+  /** Street address. Currently null for every ATM (the source omits it); typed
+   *  as `string | null` so a future populated value is not a breaking change. */
+  address: string | null;
+  /** Commune name in French. */
+  commune_fr: string;
+  /** Commune name in Arabic. */
+  commune_ar: string;
+  /** Wilaya code as a string ("1".."58"). */
+  wilaya_code: string;
+  /** Wilaya name in French. */
+  wilaya_fr: string;
+  /** Wilaya name in Arabic. */
+  wilaya_ar: string;
+  /** Latitude, or null when not geocoded. */
+  lat: number | null;
+  /** Longitude, or null when not geocoded. */
+  lng: number | null;
+}
+
+/** Dataset metadata (data/metadata.json). */
+export interface Metadata {
+  source: string;
+  api: string;
+  license: string;
+  postoffices: number;
+  atms: number;
+  distinct_postal_codes: number;
+  /** ISO date (YYYY-MM-DD) the snapshot was generated. */
+  generated_at: string;
+}
+
+/** All post offices. */
+export function postOffices(): PostOffice[];
+/** All ATMs. */
+export function atms(): Atm[];
+/** Dataset metadata. */
+export function metadata(): Metadata;
+
+declare const _default: {
+  postOffices: typeof postOffices;
+  atms: typeof atms;
+  metadata: typeof metadata;
+};
+export default _default;