@zukall/zap 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,419 @@
-# Temporary Holding Version
+# ZAP — Zukall Addressing Protocol
 
-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.
+**`@zukall/zap`** generates addresses directly from latitude and longitude using
+fixed country/province grids. Protocol **2** encodes **100-meter blocks** and
+separate **whole-meter remainders**. It needs no Google Places API, geocoding
+service, network request, or runtime dependency. Generation works offline.
+
+```text
+1194 S 382 E #16-20, Kampala, UG ZAP
+2106 S 3614 E #22-64, Miami, FL US ZAP
+580 S 770 E #43-46, HT ZAP
+```
+
+These illustrate the display format. Actual numbers depend on the original GPS
+point and selected grid; a city label never changes the origin or verifies
+administrative membership.
+
+## Installation and local verification
+
+After publication:
+
+```sh
+npm install @zukall/zap
+```
+
+Before publication, install the verified local package:
+
+```sh
+npm install /absolute/path/to/your-address-protocol/.artifacts/zukall-zap-0.2.0.tgz
+```
+
+Build and verify the source:
+
+```sh
+cd /absolute/path/to/your-address-protocol
+npm ci
+npm run check
+npm run pack:check
+```
+
+Node.js 20 or newer is required for development and Node consumers. Browser
+bundlers can use the same generator; runtime code has no Node-specific APIs.
+ESM, CommonJS and TypeScript declarations are included. `pack:check` installs the
+tarball into a temporary consumer and verifies both module formats and types.
+
+## Quick start: ESM
+
+```js
+import { generateAddress } from "@zukall/zap";
+
+const result = generateAddress({
+  countryCode: "UG",
+  city: "Kampala",
+  latitude: 0.3476,
+  longitude: 32.5825,
+});
+
+console.log(result.address); // 1139 S 339 E #33-19, Kampala, UG ZAP
+console.log(result.protocolVersion); // 2 (string)
+console.log(result.northSouthBlock); // 1139
+console.log(result.eastWestBlock); // 339
+console.log(result.northSouthRemainder); // 33
+console.log(result.eastWestRemainder); // 19
+console.log(result.coordinateSuffix); // #33-19
+```
+
+The complete result is:
+
+```json
+{
+  "protocol": "ZAP",
+  "protocolVersion": "2",
+  "address": "1139 S 339 E #33-19, Kampala, UG ZAP",
+  "countryCode": "UG",
+  "gridName": "Uganda",
+  "countryVersion": "ne-admin0-239eec57ac17-v1",
+  "gridVersion": "ne-admin0-239eec57ac17-v1",
+  "coordinates": {
+    "latitude": 0.3476,
+    "longitude": 32.5825
+  },
+  "center": {
+    "latitude": 1.372243,
+    "longitude": 32.277466499999946
+  },
+  "widthMeters": 606730,
+  "heightMeters": 633245,
+  "northingMeters": -113933.63641380174,
+  "eastingMeters": 33919.40824532269,
+  "city": "Kampala",
+  "northSouthBlock": 1139,
+  "eastWestBlock": 339,
+  "northSouthDirection": "S",
+  "eastWestDirection": "E",
+  "northSouthRemainder": 33,
+  "eastWestRemainder": 19,
+  "coordinateSuffix": "#33-19",
+  "blockSizeMeters": 100,
+  "detailSizeMeters": 1,
+  "encoding": "blocks-100m-detail-1m-floor-absolute-dashed-suffix-2x2-v1",
+  "gridId": "ZAP:2:UG:ne-admin0-239eec57ac17-v1:ne-admin0-239eec57ac17-v1:AEQD-SPHERE-v1:6371008.8:1.372243:32.277466499999946:blocks-100m-detail-1m-floor-absolute-dashed-suffix-2x2-v1"
+}
+```
+
+`coordinates` retains the original GPS point. `northingMeters` and `eastingMeters`
+are signed, **unrounded** projected offsets. Remainders are numbers for application
+use; `coordinateSuffix` and `address` always format them with two digits.
+`widthMeters` and `heightMeters` are approximate rectangle dimensions rounded to
+whole meters.
+
+You may also pass an optional `street` label. It is returned as separate metadata
+and does not enter the formatted coordinate address or affect the grid. City and
+street labels are trimmed, whitespace is normalized, and blank labels are omitted.
+
+## CommonJS and selected provinces
+
+```js
+const { generateAddress, ZAP_PROTOCOL } = require("@zukall/zap");
+
+const result = generateAddress({
+  countryCode: "US",
+  provinceCode: "FL",
+  city: "Miami",
+  latitude: 25.7617,
+  longitude: -80.1918,
+});
+
+console.log(ZAP_PROTOCOL.name); // Zukall Addressing Protocol
+console.log(result.address); // 2181 S 3643 E #89-31, Miami, FL US ZAP
+```
+
+Countries with province/state grids require the caller to choose one. Countries
+with country-wide grids require only the country code and reject province codes.
+Existing corners, origins, snapshot versions and overlapping rectangles are
+unchanged. Rectangle containment does not establish actual administrative
+membership. City and street labels do not determine the selected grid.
+
+## TypeScript and the named namespace
+
+```ts
+import {
+  generateAddress,
+  zap,
+  type AddressInput,
+  type AddressResult,
+} from "@zukall/zap";
+
+const input: AddressInput = {
+  countryCode: "US",
+  provinceCode: "AK",
+  latitude: 61.2181,
+  longitude: -149.9003,
+};
+
+const result: AddressResult = generateAddress(input);
+console.log(result.address); // 214 N 4726 E #44-94, AK US ZAP
+console.log(zap.generateAddress(input).address); // Same address
+console.log(zap.protocol.version); // 2
+```
+
+Public types include `AddressInput`, `AddressResult`, `AddressEncoding`,
+`LegacyAddressInput`, `LegacyAddressResult`, `GridInput`, `Coordinates`, `Corners`,
+`Country`, `Province`, `ProvinceCountry`, `CountryOption`, and `ProvinceOption`.
+ESM and CommonJS consumers receive matching declarations.
+
+## Display formatting and the encoding
+
+The format is:
+
+```text
+{northSouthBlock} {N|S} {eastWestBlock} {E|W} #{northSouthRemainder}-{eastWestRemainder}, {city}, {provinceCode} {countryCode} ZAP
+```
+
+Missing city/province components are omitted cleanly. The final province,
+country and `ZAP` labels are separated by spaces:
+
+```js
+const withoutCity = generateAddress({
+  countryCode: "UG", latitude: 0.3476, longitude: 32.5825,
+});
+console.log(withoutCity.address); // 1139 S 339 E #33-19, UG ZAP
+
+const withoutCityInProvince = generateAddress({
+  countryCode: "US", provinceCode: "CA", latitude: 34.0522, longitude: -118.2437,
+});
+console.log(withoutCityInProvince.address); // 3568 S 940 E #20-58, CA US ZAP
+```
+
+For each signed projected axis:
+
+1. Choose direction from its sign: negative northing is S, negative easting is W.
+2. Take `wholeMeters = Math.floor(Math.abs(offset))`.
+3. Calculate `block = Math.floor(wholeMeters / 100)`.
+4. Calculate `remainder = wholeMeters % 100`.
+5. Pad both remainders to two digits and join north/south first: `#03-06`.
+
+Northing `-119416.594` and easting `38220.747` produce
+`1194 S 382 E #16-20`. Magnitude `99.999` remains block 0, remainder 99;
+magnitude 100 becomes block 1, remainder 00. Exact zero and negative zero use
+N/E, but `-0.3` meters keeps S/W even though its whole-meter magnitude is zero.
+Blocks may have any number of digits. Neither nearest-meter rounding nor old
+5-meter snapping is applied.
+
+The spherical azimuthal equidistant projection and Earth radius 6,371,008.8 meters
+are unchanged. The grid axes remain fixed. A diagonal or curved street can change
+both blocks; each address is independently derived from its GPS point. Roads
+do not rotate the grid or introduce sequential house numbers. Moving 100
+projected meters away from the origin along one axis increments that block while
+preserving the other axis and both remainders.
+
+## Country and province selectors
+
+```js
+import { getCountries, getCountry, getProvinces } from "@zukall/zap";
+
+console.log(getCountries().length); // 239
+console.log(getCountries().find(item => item.code === "US"));
+// { code: "US", name: "United States", requiresProvince: true }
+console.log(getProvinces("US").length); // 51
+console.log(getProvinces("US").find(item => item.code === "FL"));
+// { code: "FL", name: "Florida" }
+console.log(getProvinces("UG")); // []
+console.log(getCountry("UG").name); // Uganda
+```
+
+Options are sorted by name, and each call returns a fresh array. Country/province
+codes are trimmed and uppercased. Keep province codes as strings, preserving
+leading zeros and source-specific codes returned by `getProvinces`.
+
+These 22 countries require a configured province:
+
+```text
+DZ CD SD LY TD NE AO ML ZA ET MR RU CA US CN BR AU IN AR KZ SA ID
+```
+
+They contain 530 province grids. The remaining 217 country/territory entries use
+country-wide grids. Select the country/province explicitly; the generator does
+not infer membership from intersecting rectangles.
+
+## Save the full record and keep unit details separate
+
+```js
+import { generateAddress } from "@zukall/zap";
+
+const result = generateAddress({
+  countryCode: "UG", city: "Kampala", latitude: 0.3476, longitude: 32.5825,
+});
+
+const record = {
+  ...result, // Address, blocks, original GPS, versions, center, encoding, gridId
+  street: "Example Road",
+  apartment: "12B",
+  floor: "3",
+  unit: "Office 4",
+};
+const saved = JSON.parse(JSON.stringify(record));
+console.log(saved.address); // 1139 S 339 E #33-19, Kampala, UG ZAP
+console.log(saved.unit); // Office 4 (separate from #33-19)
+```
+
+Persist the original address text and complete result, especially `coordinates`,
+`protocolVersion`, `countryVersion`, `gridVersion`, and `gridId`. Treat `gridId` as
+opaque. Cell identity uses that ID with the structured blocks, directions and
+remainders; city/street/unit labels are independent display metadata. The package
+does not include a reverse decoder or change your stored records.
+
+## Open directions from saved GPS
+
+```js
+import { getDirectionsUrl } from "@zukall/zap";
+
+// Use the stored record, including when it contains a protocol-1 address.
+const url = getDirectionsUrl(saved);
+console.log(url);
+// https://www.google.com/maps/dir/?api=1&destination=0.3476%2C32.5825
+
+// In a browser, open this from the user's Directions button:
+window.open(url, "_blank", "noopener,noreferrer");
+```
+
+The optional helper builds a [Google Maps directions URL](https://developers.google.com/maps/documentation/urls/get-started#directions)
+from the original coordinates. It performs no API request and does not need an
+API key. You can also pass `saved.coordinates` to your own map provider. Never
+use the formatted ZAP string, grid center, city name, or coordinate suffix as the
+routing destination.
+
+## Upgrade from protocol 1 without changing issued addresses
+
+Package `0.2.0` introduces protocol 2. `generateAddress` no longer accepts
+`gridSizeMeters`; remove that option when intentionally issuing a new protocol-2
+address. Passing it is rejected in TypeScript and at runtime, including when a
+JavaScript caller passes `undefined`.
+
+Previously issued records retain their original address, GPS point,
+`protocolVersion: "1"`, grid interval and original `gridId`. Continue displaying
+those saved values. Do not regenerate or overwrite them merely on package upgrade.
+
+To explicitly reproduce a version-1 address, use its original GPS and interval:
+
+```ts
+import {
+  generateLegacyAddress,
+  type LegacyAddressInput,
+  type LegacyAddressResult,
+} from "@zukall/zap";
+
+const legacyInput: LegacyAddressInput = {
+  countryCode: "UG",
+  latitude: 0.3476,
+  longitude: 32.5825,
+  gridSizeMeters: 5,
+};
+const original: LegacyAddressResult = generateLegacyAddress(legacyInput);
+console.log(original.address); // 113935 S 33920 E, UG, ZAP
+console.log(original.protocolVersion); // 1
+console.log(original.gridSizeMeters); // 5
+```
+
+`generateLegacyAddress` retains the original result schema, nearest-interval
+snapping and grid identity. Its default is 5 meters; supported original intervals
+are integers 1–1000. `LEGACY_ZAP_PROTOCOL` exposes the frozen version-1 rules.
+See [PROTOCOL-V1.md](PROTOCOL-V1.md).
+
+If a user requests a new protocol-2 address for a saved location, explicitly
+select its original country/province and GPS coordinates, omit the legacy grid
+option, generate a **new record**, and retain the old record as history. Changing
+the text of an old record without changing its protocol metadata is incorrect.
+
+## Handle invalid input
+
+```js
+function tryAddress(input) {
+  try {
+    return { ok: true, result: generateAddress(input) };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+console.log(tryAddress({ countryCode: "US", latitude: 34, longitude: -118 }));
+// { ok: false, error: "Please select your province or state." }
+```
+
+Validation rejects missing/non-string codes, unknown countries/provinces,
+non-numeric or non-finite coordinates, latitude outside ±90, longitude outside
+±180, coordinates outside the selected inclusive rectangle, non-string cities,
+non-string street labels, and the obsolete `gridSizeMeters` option. Numeric strings must be converted before
+calling. Empty city labels are omitted. Zero coordinates, date-line rectangles,
+and Antarctica's full 360-degree rectangle remain supported.
+
+## Inspect immutable source data
+
+```js
+import {
+  countries, provinceCountries, provinceGrids,
+  provinceCounts, provinceDataNotes, additionalSourceAreas,
+} from "@zukall/zap/data";
+
+console.log(countries.UG.corners); // Original four country corners
+console.log(provinceCounts.US); // 51
+console.log(provinceCounts.DZ); // 48 in this frozen snapshot
+console.log(provinceDataNotes.DZ); // Historical coverage notes
+console.log(provinceCountries.US.province.CA.name); // California
+console.log(provinceGrids.US.provinces.CA.name); // California
+console.log(Object.keys(additionalSourceAreas).length); // 13
+```
+
+The data is the unchanged Natural Earth snapshot, with historical divisions,
+source-specific keys, and some territorial groupings. It supplies fixed grid
+origins rather than a current postal/administrative directory. The 13 additional
+source areas remain outside address generation. Bounds and versions are frozen at
+runtime; future changes require new snapshots and preservation of older versions.
+See [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) and [PROTOCOL.md](PROTOCOL.md).
+
+## Public API
+
+| Export | Purpose |
+| --- | --- |
+| `generateAddress(input)` | Generate a protocol-2 address with fixed 100-meter blocks and 1-meter detail. |
+| `generateLegacyAddress(input)` | Explicitly reproduce the original protocol-1 address and grid ID. |
+| `getDirectionsUrl(savedRecord)` | Build directions using original saved GPS coordinates, for either version. |
+| `getCountries()` / `getCountry(code)` | Select or inspect immutable country configurations. |
+| `getProvinces(code)` | List configured provinces; country-wide grids return `[]`. |
+| `ZAP_PROTOCOL` / `LEGACY_ZAP_PROTOCOL` | Read current or original protocol constants. |
+| `zap` | Access the same functions through a named namespace. |
+| `@zukall/zap/data` | Inspect frozen snapshots, counts, notes and additional source areas. |
+
+## Tests, packaging, and publication
+
+```sh
+npm run typecheck
+npm test
+npm run pack:check
+```
+
+Tests cover the requested formats, all directions, zero and sub-meter negatives,
+99/100-meter boundaries, two-digit suffixes, country/province selection, unchanged
+grid identity components, date-line rectangles, diagonal sequences, 100-meter
+axis movements, old-address compatibility, saved GPS directions, and all centers
+and corners of 747 configured grids. Package verification checks ESM/CommonJS
+runtime exports and compiles both TypeScript consumer formats, including the
+removed-option error.
+
+`npm pack` also runs the checks through `prepack`. Publishing is a separate action:
+
+```sh
+npm login
+npm run pack:check
+npm publish .artifacts/zukall-zap-0.2.0.tgz --access public
+```
+
+An npm account with permission to publish `@zukall/zap` is required. Building and
+packing do not publish the package. Package version is `0.2.0`; current protocol
+version is `2`, while preserved legacy results remain version `1`.
+
+## License
+
+Code: [MIT](LICENSE). Natural Earth data: public domain, documented in
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,19 @@
+# Bundled map data
+
+The country and province grid rectangles derive from Natural Earth at 1:10 million
+scale, using WGS84 coordinates. Natural Earth places its vector and raster data in
+the public domain: https://www.naturalearthdata.com/about/terms-of-use/.
+
+- Countries: https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-0-countries/
+- Provinces: https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-1-states-provinces/
+- Province snapshot SHA256 recorded by the source files:
+  `22d0e3ad85eb3e27f17cabf8ba2d50e554fbc27a87796ff891d958185da62fb5`.
+- Retrieval date recorded by the supplied files: 2026-10-10.
+
+The source files preserve their original bounds and snapshot versions. Province
+counts and historical coverage notes are available from `@zukall/zap/data`.
+The recorded retrieval date does not establish the current validity of administrative
+divisions. Bounding rectangles can overlap and do not establish administrative membership.
+
+The MIT license covers this package's code. Natural Earth's public-domain terms
+apply to the underlying map data.

package/dist/cjs/address.d.ts

@@ -0,0 +1,3 @@
+import type { AddressInput, AddressResult } from "./types.js";
+/** Generate a protocol-2 address directly from the original GPS coordinates. */
+export declare function generateAddress(input: AddressInput): AddressResult;

package/dist/cjs/address.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAddress = generateAddress;
+const encoding_js_1 = require("./encoding.js");
+const grid_js_1 = require("./grid.js");
+const protocol_js_1 = require("./protocol.js");
+function displayLabel(value, name) {
+    if (value !== undefined && typeof value !== "string") {
+        throw new TypeError(`${name} must be a string when supplied.`);
+    }
+    return value?.trim().replace(/\s+/g, " ") || undefined;
+}
+/** Generate a protocol-2 address directly from the original GPS coordinates. */
+function generateAddress(input) {
+    if (input && typeof input === "object" && "gridSizeMeters" in input) {
+        throw new TypeError("gridSizeMeters is a protocol-1 option. Remove it for ZAP 2, or use generateLegacyAddress to reproduce an original address.");
+    }
+    const { identityComponents, ...grid } = (0, grid_js_1.projectAddress)(input);
+    const city = displayLabel(input.city, "city");
+    const street = displayLabel(input.street, "street");
+    const encoded = (0, encoding_js_1.encodeOffsets)(grid.northingMeters, grid.eastingMeters);
+    const location = [grid.provinceCode, grid.countryCode, protocol_js_1.ZAP_PROTOCOL.addressSuffix]
+        .filter(Boolean).join(" ");
+    const position = `${encoded.northSouthBlock} ${encoded.northSouthDirection} ${encoded.eastWestBlock} ${encoded.eastWestDirection} ${encoded.coordinateSuffix}`;
+    return {
+        protocol: protocol_js_1.ZAP_PROTOCOL.id,
+        protocolVersion: protocol_js_1.ZAP_PROTOCOL.version,
+        address: [position, ...(city ? [city] : []), location].join(", "),
+        ...grid,
+        ...(city ? { city } : {}),
+        ...(street ? { street } : {}),
+        ...encoded,
+        blockSizeMeters: protocol_js_1.ZAP_PROTOCOL.blockSizeMeters,
+        detailSizeMeters: protocol_js_1.ZAP_PROTOCOL.detailSizeMeters,
+        encoding: protocol_js_1.ZAP_PROTOCOL.encoding,
+        gridId: [protocol_js_1.ZAP_PROTOCOL.id, protocol_js_1.ZAP_PROTOCOL.version, ...identityComponents, protocol_js_1.ZAP_PROTOCOL.encoding].join(":"),
+    };
+}

package/dist/cjs/address_bounty.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Direct country/province configuration for generateAddress.
+ * Natural Earth 1:10 million, WGS84 degrees, public-domain map data.
+ * Sources retrieved 2026-10-10:
+ * https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-0-countries/
+ * https://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-1-states-provinces/
+ *
+ * 239 country/territory keys; 22 countries use province grids, including US states.
+ * The remaining 217 entries use country-wide rectangles. No invented province codes.
+ * Source units without ISO/EH codes are exported separately under NE_ keys.
+ * Some territories are grouped under a parent: this is not ISO-249 coverage.
+ * XK is the source's Kosovo code, not an officially assigned ISO code.
+ * Source de facto territorial grouping is retained.
+ *
+ * Corner order: topLeft, topRight, bottomRight, bottomLeft.
+ * Numbers are rounded outward to six decimals to contain source geometry.
+ * Six decimals are representation precision, not centimeter boundary accuracy.
+ * Rectangles can overlap; administrative membership must be verified separately.
+ * For date-line crossings west > east. ZAP supports these rectangles.
+ * AQ (Antarctica) spans all longitudes. ZAP handles its explicit 360-degree span.
+ * US territories such as PR and GU have separate country/territory entries.
+ * These versions and corners are frozen at runtime. Updates require a new snapshot.
+ */
+import type { Country } from "./types.js";
+export declare const countries: Readonly<Record<string, Country>>;
+export declare const additionalSourceAreas: Readonly<Record<string, Country>>;