@urbankitstudio/atlas 0.6.14 → 0.6.15

package/README.md

@@ -67,7 +67,14 @@ import { findCounty, buildParcelLookupDeepLink } from "@urbankitstudio/atlas";
 
 const kane = findCounty("illinois", "kane-county")!;
 const link = buildParcelLookupDeepLink(kane.endpoints[0]);
-// → https://urbankitstudio.com/tools/parcel-lookup?endpoint=https%3A%2F%2F...&fieldHint=TaxName
+// → https://urbankitstudio.com/tools/parcel-lookup?endpoint=https%3A%2F%2F...
+
+// Pass the county record as well and its primary layer (endpoints[0]), when
+// that layer refuses typed search or several counties share it, links to the
+// county's own page, which scopes it. Any other endpoint keeps the generic link:
+const alachua = findCounty("florida", "alachua-county")!;
+buildParcelLookupDeepLink(alachua.endpoints[0], undefined, alachua);
+// → https://urbankitstudio.com/tools/parcel-lookup/florida/alachua-county
 
 For single-address owner lookups in the browser, the free [Owner Lookup](https://urbankitstudio.com/tools/owner-lookup) tool reads the same county layers this package indexes.
 ```
@@ -81,7 +88,10 @@ For single-address owner lookups in the browser, the free [Owner Lookup](https:/
 | `findCounty(stateSlug, countySlug)` | `CountyRecord \| undefined` |
 | `findCountyByFips(fips)` | `CountyRecord \| undefined` — match by 5-digit county FIPS |
 | `listCountiesByState(stateSlug)` | `CountyRecord[]` |
-| `buildParcelLookupDeepLink(endpoint)` | URL string into the UrbanKit lookup tool |
+| `buildParcelLookupDeepLink(endpoint, base?, county?)` | URL string into the UrbanKit lookup tool; with `county`, the county route when the endpoint is that county's flagged or shared primary layer |
+| `canonicalLayerUrl(url)` | one key per layer: host + path, scheme, default port, query, fragment, a trailing `/query` and case folded away |
+| `offersAttributeSearch(endpoint)` | `false` when the layer refuses a `where` clause (`attributeSearch: "unsupported"`); query it by geometry instead |
+| `countyOffersAttributeSearch(county)` | `true` when any of the county's layers takes a `where` clause |
 | `slugify(s)`, `countySlugFromName(s)` | string helpers matching the atlas slug convention |
 | `statePath(slug)`, `countyPath(state, county)` | URL paths under `/parcel-atlas` |
 

package/dist/index.cjs

@@ -1,6 +1,13 @@
 'use strict';
 
 // src/capability.ts
+function offersAttributeSearch(endpoint) {
+  return !!endpoint && endpoint.attributeSearch !== "unsupported";
+}
+function countyOffersAttributeSearch(county) {
+  const endpoints = Array.isArray(county.endpoints) ? county.endpoints : [];
+  return endpoints.some(offersAttributeSearch);
+}
 function reviewedCapability(county, field) {
   return county.capabilityOverrides?.[field] ?? null;
 }
@@ -22794,12 +22801,31 @@ function countySlugFromName(county) {
   const name = county.trim();
   return slugify(COUNTY_UNIT_SUFFIX.test(name) ? name : `${name} County`);
 }
-function buildParcelLookupDeepLink(endpoint, base = "https://urbankitstudio.com/tools/parcel-lookup") {
+function canonicalLayerUrl(url) {
+  const raw = url.trim();
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    parsed = null;
+  }
+  if (!parsed || parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return raw.replace(/\/+$/, "").toLowerCase();
+  }
+  const path = parsed.pathname.replace(/\/{2,}/g, "/").replace(/\/+$/, "").replace(/\/query$/i, "").replace(/\/+$/, "");
+  const port = parsed.port ? `:${parsed.port}` : "";
+  return `${parsed.hostname}${port}${path}`.toLowerCase();
+}
+function buildParcelLookupDeepLink(endpoint, base = "https://urbankitstudio.com/tools/parcel-lookup", county) {
+  const searchable = offersAttributeSearch(endpoint);
+  const primary = county?.endpoints ? county.endpoints[0] : endpoint;
+  const isPrimary = !!primary && canonicalLayerUrl(primary.url) === canonicalLayerUrl(endpoint.url);
+  if (county && isPrimary && (!searchable || endpoint.scopeWhere)) {
+    return `${base}/${encodeURIComponent(county.stateSlug)}/${encodeURIComponent(county.countySlug)}`;
+  }
   const params = new URLSearchParams();
   params.set("endpoint", endpoint.url);
-  const ownerField = endpoint.searchFields.find(
-    (f) => /owner|taxpayer/i.test(f.name)
-  );
+  const ownerField = searchable ? endpoint.searchFields.find((f) => /owner|taxpayer/i.test(f.name)) : void 0;
   if (ownerField) params.set("fieldHint", ownerField.name);
   return `${base}?${params.toString()}`;
 }
@@ -22814,6 +22840,8 @@ exports.LIVE_STATUS_URL = LIVE_STATUS_URL;
 exports.atlas = atlas;
 exports.atlasIndex = atlasIndex;
 exports.buildParcelLookupDeepLink = buildParcelLookupDeepLink;
+exports.canonicalLayerUrl = canonicalLayerUrl;
+exports.countyOffersAttributeSearch = countyOffersAttributeSearch;
 exports.countyPath = countyPath;
 exports.countySlugFromName = countySlugFromName;
 exports.findCounty = findCounty;
@@ -22822,6 +22850,7 @@ exports.findState = findState;
 exports.isReviewedUnservable = isReviewedUnservable;
 exports.listCountiesByState = listCountiesByState;
 exports.listStates = listStates;
+exports.offersAttributeSearch = offersAttributeSearch;
 exports.reviewedCapability = reviewedCapability;
 exports.slugify = slugify;
 exports.statePath = statePath;

package/dist/index.d.cts

@@ -47,8 +47,12 @@ interface EndpointRecord {
      * Declares that this layer CANNOT serve an ATTRIBUTE search - a `where`-clause
      * query on a column, which is what "search by owner name / APN / address text"
      * means everywhere on the site. Absent (the default, and true of every
-     * registration except the 67 Florida counties on the shared FDOR layer, one
-     * layer and one live case, see below) means an attribute search IS offered.
+     * registration except 68: the 67 Florida counties on the shared FDOR layer,
+     * see below, and Orleans Parish LA, whose own layer never finishes a table
+     * scan) means an attribute search IS offered.
+     *
+     * Read it through `offersAttributeSearch` / `countyOffersAttributeSearch`,
+     * exported by this package, rather than comparing the string yourself.
      *
      * THIS IS THE ONE FLAG. Do not add a second field, and do not express this
      * with `searchable: false` on every column: `searchable` is a FIELD-level
@@ -65,7 +69,7 @@ interface EndpointRecord {
      * owner_name to not_published would be a false claim about data we do serve
      * and do bill for. Search and availability are different questions.
      *
-     * THE ONE LIVE CASE, and what would retire it. Florida's FDOR statewide
+     * THE SHARED-LAYER CASE, and what would retire it. Florida's FDOR statewide
      * cadastral layer carries all 67 counties and 10.8M parcels, and CO_NO - the
      * county code, the only column identifying a county, and therefore every
      * Florida registration's scopeWhere - is NOT INDEXED. Its declared indexes
@@ -213,6 +217,23 @@ interface AtlasIndex {
     };
 }
 
+/**
+ * Can this layer take a `where`-clause search at all (owner name, address text,
+ * a field filter)? False on a layer flagged `attributeSearch: "unsupported"`,
+ * which answers SPATIAL queries only: query it by geometry, as its
+ * `sampleQuery` shows, and read the owner and address fields off the hits.
+ *
+ * This is the package's one reader of that flag, so test it rather than the
+ * raw field. It is held equal to the site's reader (offersAttributeSearch in
+ * the monorepo's src/lib/capability-core.ts) on every bundled endpoint by the
+ * monorepo's atlas-package-capability-parity test.
+ */
+declare function offersAttributeSearch(endpoint: Pick<EndpointRecord, "attributeSearch"> | null | undefined): boolean;
+/**
+ * Does ANY of this county's layers take a `where` clause? Miami-Dade answers
+ * true through its own layer although its statewide FDOR layer is flagged.
+ */
+declare function countyOffersAttributeSearch(county: Pick<CountyRecord, "endpoints">): boolean;
 /**
  * The reviewed capability assertion for one field, or null when none exists.
  *
@@ -280,7 +301,51 @@ declare function listCountiesByState(stateSlug: string): CountyRecord[];
 
 declare function slugify(s: string): string;
 declare function countySlugFromName(county: string): string;
-declare function buildParcelLookupDeepLink(endpoint: EndpointRecord, base?: string): string;
+/**
+ * One spelling for one ArcGIS layer, so two spellings of the same layer compare
+ * equal. A URL that parses as http(s) keys on host + path, with no scheme (an
+ * http and an https spelling are one layer): the host lowercased, a default
+ * port dropped, dot segments resolved, repeated slashes collapsed, the query
+ * string and fragment dropped, a trailing `/query` (the operation, not the
+ * layer) and trailing slashes stripped, and the path lowercased, since ArcGIS
+ * REST paths are case-insensitive. Anything else is trimmed, stripped of
+ * trailing slashes and lowercased. Distinct layers stay distinct:
+ * `MapServer/15`, `MapServer/1` and `MapServer/150` are three keys.
+ *
+ * The site's copy (layerKey in the monorepo's src/lib/registered-layer.ts) is
+ * held equal to this one by its registered-layer test.
+ */
+declare function canonicalLayerUrl(url: string): string;
+/**
+ * The county a deep link is for. A CountyRecord satisfies it. Pass the record
+ * with its `endpoints` so the link can tell whether the endpoint is the
+ * county's primary layer; without them the caller vouches that it is.
+ */
+interface DeepLinkCounty {
+    stateSlug: string;
+    countySlug: string;
+    endpoints?: readonly Pick<EndpointRecord, "url">[];
+}
+/**
+ * A link into the UrbanKit parcel-lookup tool for one endpoint.
+ *
+ * Without `county` this is the generic `?endpoint=<url>` link it always was,
+ * except that `fieldHint` (the owner column to pre-select) is omitted on a
+ * layer that refuses typed search (`attributeSearch: "unsupported"`): there is
+ * no text search to pre-select a field for, and the generic route recognises
+ * a registry-flagged layer and offers none.
+ *
+ * With `county` (pass the CountyRecord itself), a flagged or SHARED layer
+ * (`scopeWhere` set) links to the county route `<base>/<state>/<county>`, but
+ * only when it IS the county's primary layer (`county.endpoints[0]`, compared
+ * by canonicalLayerUrl), because the county route always loads that one. Only
+ * the county route knows which county it is looking at, so only it can scope a
+ * shared layer and show a flagged layer as lookup by location. Any other
+ * endpoint keeps the generic link to exactly that endpoint: Broward's FDOR
+ * layer is its second, behind the county's own layer, so a county-route link
+ * for it would open a different layer.
+ */
+declare function buildParcelLookupDeepLink(endpoint: EndpointRecord, base?: string, county?: DeepLinkCounty): string;
 declare function statePath(stateSlug: string): string;
 declare function countyPath(stateSlug: string, countySlug: string): string;
 
@@ -294,4 +359,4 @@ interface Atlas {
 }
 declare const atlas: Atlas;
 
-export { type Atlas, type AtlasIndex, type CapabilityBasis, type CapabilityBasisType, type CapabilityField, type CapabilityOverrides, type CapabilityStatus, type ContactInfo, type CountyAdvisory, 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, isReviewedUnservable, listCountiesByState, listStates, reviewedCapability, slugify, statePath };
+export { type Atlas, type AtlasIndex, type CapabilityBasis, type CapabilityBasisType, type CapabilityField, type CapabilityOverrides, type CapabilityStatus, type ContactInfo, type CountyAdvisory, type CountyRecord, type DeepLinkCounty, type EndpointRecord, type EndpointStatus, LIVE_STATUS_URL, type LicenseType, type SearchField, type ServiceType, type StateFile, type StateIndexEntry, type VerifiedBy, atlas, atlasIndex, buildParcelLookupDeepLink, canonicalLayerUrl, countyOffersAttributeSearch, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, isReviewedUnservable, listCountiesByState, listStates, offersAttributeSearch, reviewedCapability, slugify, statePath };

package/dist/index.d.ts

@@ -47,8 +47,12 @@ interface EndpointRecord {
      * Declares that this layer CANNOT serve an ATTRIBUTE search - a `where`-clause
      * query on a column, which is what "search by owner name / APN / address text"
      * means everywhere on the site. Absent (the default, and true of every
-     * registration except the 67 Florida counties on the shared FDOR layer, one
-     * layer and one live case, see below) means an attribute search IS offered.
+     * registration except 68: the 67 Florida counties on the shared FDOR layer,
+     * see below, and Orleans Parish LA, whose own layer never finishes a table
+     * scan) means an attribute search IS offered.
+     *
+     * Read it through `offersAttributeSearch` / `countyOffersAttributeSearch`,
+     * exported by this package, rather than comparing the string yourself.
      *
      * THIS IS THE ONE FLAG. Do not add a second field, and do not express this
      * with `searchable: false` on every column: `searchable` is a FIELD-level
@@ -65,7 +69,7 @@ interface EndpointRecord {
      * owner_name to not_published would be a false claim about data we do serve
      * and do bill for. Search and availability are different questions.
      *
-     * THE ONE LIVE CASE, and what would retire it. Florida's FDOR statewide
+     * THE SHARED-LAYER CASE, and what would retire it. Florida's FDOR statewide
      * cadastral layer carries all 67 counties and 10.8M parcels, and CO_NO - the
      * county code, the only column identifying a county, and therefore every
      * Florida registration's scopeWhere - is NOT INDEXED. Its declared indexes
@@ -213,6 +217,23 @@ interface AtlasIndex {
     };
 }
 
+/**
+ * Can this layer take a `where`-clause search at all (owner name, address text,
+ * a field filter)? False on a layer flagged `attributeSearch: "unsupported"`,
+ * which answers SPATIAL queries only: query it by geometry, as its
+ * `sampleQuery` shows, and read the owner and address fields off the hits.
+ *
+ * This is the package's one reader of that flag, so test it rather than the
+ * raw field. It is held equal to the site's reader (offersAttributeSearch in
+ * the monorepo's src/lib/capability-core.ts) on every bundled endpoint by the
+ * monorepo's atlas-package-capability-parity test.
+ */
+declare function offersAttributeSearch(endpoint: Pick<EndpointRecord, "attributeSearch"> | null | undefined): boolean;
+/**
+ * Does ANY of this county's layers take a `where` clause? Miami-Dade answers
+ * true through its own layer although its statewide FDOR layer is flagged.
+ */
+declare function countyOffersAttributeSearch(county: Pick<CountyRecord, "endpoints">): boolean;
 /**
  * The reviewed capability assertion for one field, or null when none exists.
  *
@@ -280,7 +301,51 @@ declare function listCountiesByState(stateSlug: string): CountyRecord[];
 
 declare function slugify(s: string): string;
 declare function countySlugFromName(county: string): string;
-declare function buildParcelLookupDeepLink(endpoint: EndpointRecord, base?: string): string;
+/**
+ * One spelling for one ArcGIS layer, so two spellings of the same layer compare
+ * equal. A URL that parses as http(s) keys on host + path, with no scheme (an
+ * http and an https spelling are one layer): the host lowercased, a default
+ * port dropped, dot segments resolved, repeated slashes collapsed, the query
+ * string and fragment dropped, a trailing `/query` (the operation, not the
+ * layer) and trailing slashes stripped, and the path lowercased, since ArcGIS
+ * REST paths are case-insensitive. Anything else is trimmed, stripped of
+ * trailing slashes and lowercased. Distinct layers stay distinct:
+ * `MapServer/15`, `MapServer/1` and `MapServer/150` are three keys.
+ *
+ * The site's copy (layerKey in the monorepo's src/lib/registered-layer.ts) is
+ * held equal to this one by its registered-layer test.
+ */
+declare function canonicalLayerUrl(url: string): string;
+/**
+ * The county a deep link is for. A CountyRecord satisfies it. Pass the record
+ * with its `endpoints` so the link can tell whether the endpoint is the
+ * county's primary layer; without them the caller vouches that it is.
+ */
+interface DeepLinkCounty {
+    stateSlug: string;
+    countySlug: string;
+    endpoints?: readonly Pick<EndpointRecord, "url">[];
+}
+/**
+ * A link into the UrbanKit parcel-lookup tool for one endpoint.
+ *
+ * Without `county` this is the generic `?endpoint=<url>` link it always was,
+ * except that `fieldHint` (the owner column to pre-select) is omitted on a
+ * layer that refuses typed search (`attributeSearch: "unsupported"`): there is
+ * no text search to pre-select a field for, and the generic route recognises
+ * a registry-flagged layer and offers none.
+ *
+ * With `county` (pass the CountyRecord itself), a flagged or SHARED layer
+ * (`scopeWhere` set) links to the county route `<base>/<state>/<county>`, but
+ * only when it IS the county's primary layer (`county.endpoints[0]`, compared
+ * by canonicalLayerUrl), because the county route always loads that one. Only
+ * the county route knows which county it is looking at, so only it can scope a
+ * shared layer and show a flagged layer as lookup by location. Any other
+ * endpoint keeps the generic link to exactly that endpoint: Broward's FDOR
+ * layer is its second, behind the county's own layer, so a county-route link
+ * for it would open a different layer.
+ */
+declare function buildParcelLookupDeepLink(endpoint: EndpointRecord, base?: string, county?: DeepLinkCounty): string;
 declare function statePath(stateSlug: string): string;
 declare function countyPath(stateSlug: string, countySlug: string): string;
 
@@ -294,4 +359,4 @@ interface Atlas {
 }
 declare const atlas: Atlas;
 
-export { type Atlas, type AtlasIndex, type CapabilityBasis, type CapabilityBasisType, type CapabilityField, type CapabilityOverrides, type CapabilityStatus, type ContactInfo, type CountyAdvisory, 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, isReviewedUnservable, listCountiesByState, listStates, reviewedCapability, slugify, statePath };
+export { type Atlas, type AtlasIndex, type CapabilityBasis, type CapabilityBasisType, type CapabilityField, type CapabilityOverrides, type CapabilityStatus, type ContactInfo, type CountyAdvisory, type CountyRecord, type DeepLinkCounty, type EndpointRecord, type EndpointStatus, LIVE_STATUS_URL, type LicenseType, type SearchField, type ServiceType, type StateFile, type StateIndexEntry, type VerifiedBy, atlas, atlasIndex, buildParcelLookupDeepLink, canonicalLayerUrl, countyOffersAttributeSearch, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, isReviewedUnservable, listCountiesByState, listStates, offersAttributeSearch, reviewedCapability, slugify, statePath };

package/dist/index.js

@@ -1,4 +1,11 @@
 // src/capability.ts
+function offersAttributeSearch(endpoint) {
+  return !!endpoint && endpoint.attributeSearch !== "unsupported";
+}
+function countyOffersAttributeSearch(county) {
+  const endpoints = Array.isArray(county.endpoints) ? county.endpoints : [];
+  return endpoints.some(offersAttributeSearch);
+}
 function reviewedCapability(county, field) {
   return county.capabilityOverrides?.[field] ?? null;
 }
@@ -22792,12 +22799,31 @@ function countySlugFromName(county) {
   const name = county.trim();
   return slugify(COUNTY_UNIT_SUFFIX.test(name) ? name : `${name} County`);
 }
-function buildParcelLookupDeepLink(endpoint, base = "https://urbankitstudio.com/tools/parcel-lookup") {
+function canonicalLayerUrl(url) {
+  const raw = url.trim();
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    parsed = null;
+  }
+  if (!parsed || parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return raw.replace(/\/+$/, "").toLowerCase();
+  }
+  const path = parsed.pathname.replace(/\/{2,}/g, "/").replace(/\/+$/, "").replace(/\/query$/i, "").replace(/\/+$/, "");
+  const port = parsed.port ? `:${parsed.port}` : "";
+  return `${parsed.hostname}${port}${path}`.toLowerCase();
+}
+function buildParcelLookupDeepLink(endpoint, base = "https://urbankitstudio.com/tools/parcel-lookup", county) {
+  const searchable = offersAttributeSearch(endpoint);
+  const primary = county?.endpoints ? county.endpoints[0] : endpoint;
+  const isPrimary = !!primary && canonicalLayerUrl(primary.url) === canonicalLayerUrl(endpoint.url);
+  if (county && isPrimary && (!searchable || endpoint.scopeWhere)) {
+    return `${base}/${encodeURIComponent(county.stateSlug)}/${encodeURIComponent(county.countySlug)}`;
+  }
   const params = new URLSearchParams();
   params.set("endpoint", endpoint.url);
-  const ownerField = endpoint.searchFields.find(
-    (f) => /owner|taxpayer/i.test(f.name)
-  );
+  const ownerField = searchable ? endpoint.searchFields.find((f) => /owner|taxpayer/i.test(f.name)) : void 0;
   if (ownerField) params.set("fieldHint", ownerField.name);
   return `${base}?${params.toString()}`;
 }
@@ -22808,4 +22834,4 @@ function countyPath(stateSlug, countySlug) {
   return `/parcel-atlas/${stateSlug}/${countySlug}`;
 }
 
-export { LIVE_STATUS_URL, atlas, atlasIndex, buildParcelLookupDeepLink, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, isReviewedUnservable, listCountiesByState, listStates, reviewedCapability, slugify, statePath };
+export { LIVE_STATUS_URL, atlas, atlasIndex, buildParcelLookupDeepLink, canonicalLayerUrl, countyOffersAttributeSearch, countyPath, countySlugFromName, findCounty, findCountyByFips, findState, isReviewedUnservable, listCountiesByState, listStates, offersAttributeSearch, reviewedCapability, slugify, statePath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbankitstudio/atlas",
-  "version": "0.6.14",
+  "version": "0.6.15",
   "description": "JS SDK for the UrbanKit County Parcel REST API Atlas: 246 counties across all 50 US states and DC, 258 verified public ArcGIS REST endpoints for county parcel data, with searchable field metadata, sample queries and license info.",
   "keywords": [
     "parcel",