@urbankitstudio/atlas 0.5.2 → 0.5.3

package/README.md

@@ -92,6 +92,42 @@ atlas.totals;           // { states, counties, endpoints }
 atlas.byStateSlug;      // Map<stateSlug, StateFile>
 ```
 
+## `status` is a publish-time claim, not a live signal
+
+This package ships static JSON and makes no network calls, so `status` and
+`lastVerified` on every endpoint describe what was true **when the version you
+installed was published**. `status: "live"` means a check passed before publish —
+not that the endpoint is up right now. A county can go down the day after a
+release and every installed copy keeps saying `"live"` until the next one.
+
+The distinction is not hypothetical: on 2026-08-04 a county was being served as
+`"live"` from its registry entry while the liveness probe had it down that same
+afternoon.
+
+For the current answer, ask the health endpoint — no API key, refreshed every
+two hours:
+
+```ts
+import { LIVE_STATUS_URL } from "@urbankitstudio/atlas";
+
+const res = await fetch(`${LIVE_STATUS_URL}?fips=17089`);
+const health = await res.json();
+// { ok: true, found: true, county_fips: "17089",
+//   status: "ok" | "degraded" | "down" | "unknown",
+//   consecutive_failures, last_ok_at, checked_at }
+```
+
+Two cases to handle rather than ignore:
+
+- **`found: false`** means no observation exists — the county may be untracked or
+  never probed. It is *not* a statement that the endpoint is healthy.
+- **A `503`** means the health store itself was unreachable. Also not a health
+  claim.
+
+Treat both as *unknown*. Neither should render as "up".
+
+Omit `?fips=` to get every tracked county in one call.
+
 ## Coverage today
 
 The atlas currently bundles **155 counties across all 50 US states**, covering the largest counties in each. Call `listStates()` to enumerate the full set; every state is now populated with at least one verified county endpoint.

package/dist/index.cjs

@@ -1,5 +1,8 @@
 'use strict';
 
+// src/types.ts
+var LIVE_STATUS_URL = "https://urbankitstudio.com/api/atlas/status";
+
 // data/index.json
 var data_default = {
   version: "0.3.0",
@@ -8225,6 +8228,7 @@ function countyPath(stateSlug, countySlug) {
   return `/parcel-atlas/${stateSlug}/${countySlug}`;
 }
 
+exports.LIVE_STATUS_URL = LIVE_STATUS_URL;
 exports.atlas = atlas;
 exports.atlasIndex = atlasIndex;
 exports.buildParcelLookupDeepLink = buildParcelLookupDeepLink;

package/dist/index.d.cts

@@ -1,7 +1,29 @@
 type ServiceType = "FeatureServer" | "MapServer";
 type LicenseType = "public" | "open-data" | "restricted" | "unknown";
+/**
+ * The registry's curation stamp for an endpoint, AS OF THE MOMENT THIS PACKAGE
+ * WAS PUBLISHED. It is not a live signal and cannot be — this package ships
+ * static JSON and makes no network calls.
+ *
+ * So `"live"` here means "a check passed before publish", not "this endpoint is
+ * up right now". A county can go down the day after a release and every
+ * installed copy will keep reporting `"live"` until the next one.
+ *
+ * For the current answer, query the public health endpoint, which reports what
+ * the liveness probe last observed (every two hours) and requires no API key:
+ *
+ *     GET https://urbankitstudio.com/api/atlas/status?fips=17089
+ *
+ * A `found: false` there means no observation exists — which is not the same as
+ * healthy. See LIVE_STATUS_URL below.
+ */
 type EndpointStatus = "live" | "stale" | "unreachable" | "unverified";
 type VerifiedBy = "manual" | "arcgis-hub-seed" | "automated";
+/**
+ * Where to ask whether an endpoint is actually up right now. Keyless.
+ * Omit the query string for every tracked county.
+ */
+declare const LIVE_STATUS_URL = "https://urbankitstudio.com/api/atlas/status";
 interface SearchField {
     name: string;
     label: string;
@@ -18,7 +40,10 @@ interface EndpointRecord {
     sampleQuery: string | null;
     license: LicenseType;
     licenseUrl: string | null;
+    /** Publish-time claim, NOT live. See {@link EndpointStatus}. */
     status: EndpointStatus;
+    /** ISO date this entry was last verified before publish — a human curation
+     *  date, not a probe result, and always at least as old as this release. */
     lastVerified: string;
     verifiedBy: VerifiedBy;
 }
@@ -121,4 +146,4 @@ interface Atlas {
 }
 declare const atlas: Atlas;
 
-export { type Atlas, type AtlasIndex, type ContactInfo, type CountyRecord, type EndpointRecord, type EndpointStatus, type LicenseType, type SearchField, type ServiceType, type StateFile, type StateIndexEntry, type VerifiedBy, atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, listCountiesByState, listStates, slugify, statePath };
+export { type Atlas, type AtlasIndex, type ContactInfo, type CountyRecord, type EndpointRecord, type EndpointStatus, LIVE_STATUS_URL, type LicenseType, type SearchField, type ServiceType, type StateFile, type StateIndexEntry, type VerifiedBy, atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, listCountiesByState, listStates, slugify, statePath };

package/dist/index.d.ts

@@ -1,7 +1,29 @@
 type ServiceType = "FeatureServer" | "MapServer";
 type LicenseType = "public" | "open-data" | "restricted" | "unknown";
+/**
+ * The registry's curation stamp for an endpoint, AS OF THE MOMENT THIS PACKAGE
+ * WAS PUBLISHED. It is not a live signal and cannot be — this package ships
+ * static JSON and makes no network calls.
+ *
+ * So `"live"` here means "a check passed before publish", not "this endpoint is
+ * up right now". A county can go down the day after a release and every
+ * installed copy will keep reporting `"live"` until the next one.
+ *
+ * For the current answer, query the public health endpoint, which reports what
+ * the liveness probe last observed (every two hours) and requires no API key:
+ *
+ *     GET https://urbankitstudio.com/api/atlas/status?fips=17089
+ *
+ * A `found: false` there means no observation exists — which is not the same as
+ * healthy. See LIVE_STATUS_URL below.
+ */
 type EndpointStatus = "live" | "stale" | "unreachable" | "unverified";
 type VerifiedBy = "manual" | "arcgis-hub-seed" | "automated";
+/**
+ * Where to ask whether an endpoint is actually up right now. Keyless.
+ * Omit the query string for every tracked county.
+ */
+declare const LIVE_STATUS_URL = "https://urbankitstudio.com/api/atlas/status";
 interface SearchField {
     name: string;
     label: string;
@@ -18,7 +40,10 @@ interface EndpointRecord {
     sampleQuery: string | null;
     license: LicenseType;
     licenseUrl: string | null;
+    /** Publish-time claim, NOT live. See {@link EndpointStatus}. */
     status: EndpointStatus;
+    /** ISO date this entry was last verified before publish — a human curation
+     *  date, not a probe result, and always at least as old as this release. */
     lastVerified: string;
     verifiedBy: VerifiedBy;
 }
@@ -121,4 +146,4 @@ interface Atlas {
 }
 declare const atlas: Atlas;
 
-export { type Atlas, type AtlasIndex, type ContactInfo, type CountyRecord, type EndpointRecord, type EndpointStatus, type LicenseType, type SearchField, type ServiceType, type StateFile, type StateIndexEntry, type VerifiedBy, atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, listCountiesByState, listStates, slugify, statePath };
+export { type Atlas, type AtlasIndex, type ContactInfo, type CountyRecord, type EndpointRecord, type EndpointStatus, LIVE_STATUS_URL, type LicenseType, type SearchField, type ServiceType, type StateFile, type StateIndexEntry, type VerifiedBy, atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, listCountiesByState, listStates, slugify, statePath };

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/types.ts
+var LIVE_STATUS_URL = "https://urbankitstudio.com/api/atlas/status";
+
 // data/index.json
 var data_default = {
   version: "0.3.0",
@@ -8223,4 +8226,4 @@ function countyPath(stateSlug, countySlug) {
   return `/parcel-atlas/${stateSlug}/${countySlug}`;
 }
 
-export { atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, listCountiesByState, listStates, slugify, statePath };
+export { LIVE_STATUS_URL, atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, listCountiesByState, listStates, slugify, statePath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbankitstudio/atlas",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "JS SDK for the UrbanKit County Parcel REST API Atlas — public ArcGIS REST endpoints for US county parcel data, with searchable field metadata, sample queries, and license info.",
   "keywords": [
     "parcel",