@urbankitstudio/atlas 0.6.37 → 0.6.39

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,3 +1,158 @@
1
+ /** Why a county the atlas records has no endpoint we can serve. One code per record. */
2
+ declare const COVERAGE_REASONS: readonly ["owner-data-sold", "no-public-service", "login-required", "licence-restricted", "attributes-missing", "owner-blank", "service-down", "data-stale", "technical"];
3
+ type CoverageReason = (typeof COVERAGE_REASONS)[number];
4
+ /**
5
+ * The county's OWN paid channel for the data we do not serve. Set only with
6
+ * reason "owner-data-sold", and never a commercial reseller.
7
+ */
8
+ interface CountyProduct {
9
+ name: string;
10
+ url: string;
11
+ }
12
+ /**
13
+ * The `coverage` field of a county record with hasPublicRest:false: why we
14
+ * cannot index the county, and when we last looked.
15
+ */
16
+ interface CountyCoverage {
17
+ reason: CoverageReason;
18
+ /** One sentence of at most 280 characters, written to be shown as is. */
19
+ summary: string;
20
+ /** YYYY-MM-DD: when we last checked the county's public sources. */
21
+ checked: string;
22
+ /** YYYY-MM-DD: when we plan to look again, when a date is set. */
23
+ recheck?: string;
24
+ countyProduct?: CountyProduct;
25
+ }
26
+ /**
27
+ * "not-in-atlas": the atlas has no record for the county. That is all it
28
+ * says: a misspelled name lands here too, so it never claims the county was
29
+ * never looked at.
30
+ * "no-public-data": the atlas records the county, and it publishes nothing we can serve.
31
+ */
32
+ type CoverageStatus = "not-in-atlas" | "no-public-data";
33
+ /** POST a request body here to ask for a county. Free, and no key is needed. */
34
+ declare const COUNTY_REQUEST_URL = "https://urbankitstudio.com/api/atlas/request";
35
+ /** The request message for a county the atlas has no record for. */
36
+ declare const COUNTY_REQUEST_MESSAGE = "This county is not in the UrbanKit atlas. If you have its name rather than its FIPS code, check the spelling first against the counties the atlas covers: find_county or list_counties (list_counties_in_state on the hosted MCP server), or `uks find` in the CLI. If the county is right, offer to request it for the person you are helping; if they say yes, call the request_county MCP tool with the body above (or POST the body to the url), adding their email if they want to be told when it ships. Requesting is free.";
37
+ /**
38
+ * The request message for a county we checked and cannot serve. It promises
39
+ * nothing: we recheck, and a request tells us someone wants the county.
40
+ */
41
+ declare const COUNTY_RECHECK_REQUEST_MESSAGE = "We checked this county and it publishes no parcel data we can serve. We recheck counties like this one, and a request tells us people want it, but it does not promise we will add it. Offer to request it for the person you are helping; if they say yes, call the request_county MCP tool with the body above (or POST the body to the url), adding their email if they want to be told if that changes. Requesting is free.";
42
+ /**
43
+ * The county a not-served answer is about, as any surface knows it. `state` is
44
+ * a two-letter abbreviation, a full name, a slug or a two-digit state FIPS
45
+ * code, in any case; `county` is a name or a slug; `fips` is the 5-digit
46
+ * county FIPS code. The core normalises all three, so the same county gives
47
+ * the same request body on every surface.
48
+ */
49
+ interface CountyRequestRef {
50
+ state: string;
51
+ county?: string | null;
52
+ fips?: string | null;
53
+ }
54
+ /** A ready-to-send request for one county. */
55
+ interface CountyRequestHint {
56
+ how: "POST";
57
+ url: string;
58
+ /**
59
+ * Only keys POST /api/atlas/request and the request_county tool accept:
60
+ * county_fips, county_name, state_abbrev, state_slug, county_slug.
61
+ */
62
+ body: Record<string, string>;
63
+ message: string;
64
+ }
65
+ /**
66
+ * The `request` block a not-served answer carries: a ready-to-send body for
67
+ * POST /api/atlas/request and the request_county tool.
68
+ *
69
+ * A county with a valid FIPS code is named by it, with the county's name
70
+ * (when the ref holds a name rather than a slug) and the state's abbreviation
71
+ * taken from the code. One without is named by the state and county slugs
72
+ * alone, so every spelling of the same county ("Kane", "kane-county") sends
73
+ * the same body; a state the core does not know is sent as the caller's own
74
+ * text, slugged, so the answer never tells a caller which states exist and
75
+ * the request is still stored for us to read. Every value is already in the
76
+ * form the endpoint stores, so the body parses unchanged.
77
+ *
78
+ * Null when the ref names no county the endpoint accepts: no valid FIPS, and
79
+ * a state or county with no letter or digit to slug.
80
+ */
81
+ declare function requestHint(ref: CountyRequestRef, status?: CoverageStatus): CountyRequestHint | null;
82
+ /** The two record fields that decide whether a county is served. */
83
+ interface EndpointPresenceLike {
84
+ hasPublicRest?: boolean | null;
85
+ endpoints?: ReadonlyArray<unknown> | null;
86
+ }
87
+ /**
88
+ * True when the county has a public endpoint we can query: hasPublicRest is
89
+ * true AND at least one endpoint is registered. Every "is this county served"
90
+ * test reads this one rule.
91
+ */
92
+ declare function countyHasEndpoint(record: EndpointPresenceLike | null | undefined): boolean;
93
+ /** What coverageAnswer reads from a county record. */
94
+ interface CoverageRecordLike extends EndpointPresenceLike {
95
+ contact?: {
96
+ department?: string | null;
97
+ url?: string | null;
98
+ } | null;
99
+ coverage?: CountyCoverage | null;
100
+ }
101
+ /** `why` for a county the atlas has no record for. */
102
+ declare const NOT_IN_ATLAS_WHY = "This county is not in the UrbanKit atlas.";
103
+ /** `why` for a recorded county whose record carries no coverage summary (data older than the field). */
104
+ declare const NO_PUBLIC_DATA_WHY = "This county publishes no parcel data we can serve.";
105
+ /** The one answer every surface gives for a county we do not serve. */
106
+ interface CoverageAnswer {
107
+ /** Always false: this block exists only for a county whose parcels we do not serve. */
108
+ indexed: false;
109
+ status: CoverageStatus;
110
+ /** The record's reason code; null when there is no record, or the record predates the field. */
111
+ reason: CoverageReason | null;
112
+ /** One sentence to show the person as is. */
113
+ why: string;
114
+ /** YYYY-MM-DD of the last check; null when there is no record. */
115
+ checked: string | null;
116
+ /** YYYY-MM-DD of the next planned check; null when the record sets no date. */
117
+ recheck: string | null;
118
+ /** The county office that holds the records, from the record's contact. */
119
+ county_office: {
120
+ department: string | null;
121
+ url: string | null;
122
+ } | null;
123
+ /** The county's own paid product, only when the county sells the data. */
124
+ county_product: CountyProduct | null;
125
+ /** The ready-to-send request; null only when the ref names no county the request endpoint accepts. */
126
+ request: CountyRequestHint | null;
127
+ /** The whole answer as text, coverageAnswerText(this): what a text surface prints, verbatim. */
128
+ message: string;
129
+ }
130
+ /** What coverageAnswerText reads: a coverage block, with or without its message. */
131
+ type CoverageTextInput = Pick<CoverageAnswer, "status" | "why" | "checked" | "county_office" | "county_product"> & {
132
+ recheck?: string | null;
133
+ request: {
134
+ url: string;
135
+ body: Record<string, string>;
136
+ } | null;
137
+ };
138
+ /**
139
+ * The coverage block as text: why, when we checked and when we check next, the
140
+ * county's own office and product, and how to request the county, one point
141
+ * per line. The text
142
+ * surfaces (the stdio MCP server, the `uks` CLI, the hosted MCP) print it
143
+ * verbatim, and the block carries it as `message`. The request line quotes the
144
+ * body and URL from the block, so the text and the JSON never disagree.
145
+ */
146
+ declare function coverageAnswerText(block: CoverageTextInput): string;
147
+ /**
148
+ * The coverage answer for a county lookup that found no served county.
149
+ * `record` is the atlas record, or undefined when the atlas has none; `ref`
150
+ * names the county for the request body. Null when the record HAS an
151
+ * endpoint: there is nothing to explain.
152
+ */
153
+ declare function coverageAnswer(record: null | undefined, ref: CountyRequestRef): CoverageAnswer;
154
+ declare function coverageAnswer(record: CoverageRecordLike | null | undefined, ref: CountyRequestRef): CoverageAnswer | null;
155
+
1
156
  type ServiceType = "FeatureServer" | "MapServer";
2
157
  type LicenseType = "public" | "open-data" | "restricted" | "unknown";
3
158
  /**
@@ -202,6 +357,12 @@ interface CountyRecord {
202
357
  dataVintage?: CountyAdvisory | null;
203
358
  /** Reviewed, per-field capability assertions. See {@link CapabilityOverrides}. */
204
359
  capabilityOverrides?: CapabilityOverrides | null;
360
+ /**
361
+ * Why we cannot index this county, as a reason code and one sentence. Set on
362
+ * every record with `hasPublicRest: false` from 0.6.38; read it through
363
+ * `coverageAnswer()`.
364
+ */
365
+ coverage?: CountyCoverage | null;
205
366
  relatedZoningCitySlug?: string | null;
206
367
  relatedPropertyCitySlug?: string | null;
207
368
  }
@@ -302,7 +463,110 @@ declare function reviewedCapability(county: Pick<CountyRecord, "capabilityOverri
302
463
  declare function isReviewedUnservable(county: Pick<CountyRecord, "capabilityOverrides">, field: CapabilityField): boolean;
303
464
 
304
465
  /**
305
- * Look up a county by state slug and county slug.
466
+ * The surfaces a county can be paused on, one flag each. True = paused.
467
+ *
468
+ * "paid_lookup": a REST lookup by a paying caller (PAYG or a paid plan).
469
+ * "paid_enrich": a billed single-parcel owner lookup (MCP enrich_address).
470
+ * "paid_bulk": a billed owner list of addresses (REST bulk rows).
471
+ * "paid_lists": a billed radius owner list (REST radius, MCP radius_owners).
472
+ * "free_site_lookup": the site's free lookup tools, and a REST lookup by an
473
+ * anonymous or free-tier caller.
474
+ * "free_site_lists": the site's free whole-layer download (ArcGIS to GeoJSON).
475
+ * "free_discovery": the county record beyond its identity (endpoint URLs,
476
+ * notes, every other field) in county metadata and the
477
+ * discovery tools.
478
+ */
479
+ declare const ACCESS_FLAGS: readonly ["paid_lookup", "paid_enrich", "paid_bulk", "paid_lists", "free_site_lookup", "free_site_lists", "free_discovery"];
480
+ type AccessFlag = (typeof ACCESS_FLAGS)[number];
481
+ type AccessFlags = Readonly<Record<AccessFlag, boolean>>;
482
+ /**
483
+ * Named sets of flags.
484
+ *
485
+ * "paid-off": every billed call. Free use still answers.
486
+ * "paid-lists-off": billed owner LISTS only (radius, bulk). Single-parcel
487
+ * lookups still work.
488
+ * "all-off": everything, free use included.
489
+ */
490
+ declare const ACCESS_PRESETS: readonly ["paid-off", "paid-lists-off", "all-off"];
491
+ type AccessPreset = (typeof ACCESS_PRESETS)[number];
492
+ declare const PRESET_FLAGS: Readonly<Record<AccessPreset, readonly AccessFlag[]>>;
493
+ /** The flags a preset sets: every flag present, true for the preset's own. */
494
+ declare function flagsFor(preset: AccessPreset): AccessFlags;
495
+ /** The paused flags, in ACCESS_FLAGS order. */
496
+ declare function pausedFlags(flags: AccessFlags): AccessFlag[];
497
+ /** The preset these flags are exactly, or "custom". */
498
+ declare function presetOf(flags: AccessFlags): AccessPreset | "custom";
499
+ /** Why a county is paused. One code per county. */
500
+ declare const ACCESS_REASONS: readonly ["licence-terms", "state-law", "county-request", "data-quality", "upstream-broken", "other"];
501
+ type AccessReason = (typeof ACCESS_REASONS)[number];
502
+ /** One paused county, as the operator recorded it. */
503
+ interface CountyAccessEntry {
504
+ county_fips: string;
505
+ flags: AccessFlags;
506
+ reason: AccessReason;
507
+ /** One sentence of at most 280 characters, written to be shown as is. */
508
+ why: string;
509
+ /** The county's own terms page, or the law, that the pause rests on. */
510
+ citation_url: string;
511
+ /** When the county was paused: an ISO timestamp, or YYYY-MM-DD. */
512
+ since: string;
513
+ }
514
+ /** Is `flag` paused for this county? No entry means the county is fully on. */
515
+ declare function accessBlocks(entry: {
516
+ flags: AccessFlags;
517
+ } | null | undefined, flag: AccessFlag): boolean;
518
+ /** What pausedAnswer reads from a county record. */
519
+ interface AccessRecordLike {
520
+ contact?: {
521
+ department?: string | null;
522
+ url?: string | null;
523
+ } | null;
524
+ /** The record's own endpoints: their hosts are what a withheld answer must not name. */
525
+ endpoints?: ReadonlyArray<{
526
+ url: string;
527
+ }> | null;
528
+ }
529
+ /** Where the county's free page lives. Either slug missing: no page offered. */
530
+ interface AccessPageRef {
531
+ state_slug?: string | null;
532
+ county_slug?: string | null;
533
+ }
534
+ declare const ATLAS_COUNTY_PAGE_BASE = "https://urbankitstudio.com/parcel-atlas";
535
+ /** The one answer every surface gives for a county that is paused. */
536
+ interface CountyPausedAnswer {
537
+ /** Always true: the county IS in the atlas. */
538
+ indexed: true;
539
+ status: "paused";
540
+ /** The preset the flags match, or "custom". */
541
+ preset: AccessPreset | "custom";
542
+ /** Which surfaces are paused, in ACCESS_FLAGS order. */
543
+ paused: AccessFlag[];
544
+ reason: AccessReason;
545
+ /** One sentence to show the person as is. Null under free_discovery when it
546
+ * names the county's service (discoverySafeContact). */
547
+ why: string | null;
548
+ /** The county's own terms page, or the law, that the pause rests on. Null
549
+ * under free_discovery when it names the county's service (discoverySafeContact). */
550
+ citation_url: string | null;
551
+ since: string;
552
+ /** The county office that holds the records, from the record's contact. */
553
+ county_office: {
554
+ department: string | null;
555
+ url: string | null;
556
+ } | null;
557
+ /** The free county page; null when free lookup or discovery is paused, or the page is unknown. */
558
+ free_alternatives: {
559
+ county_page: string;
560
+ } | null;
561
+ /** Always null: a paused county is not something to request. */
562
+ request: null;
563
+ }
564
+ /** The paused answer for one county. `record` is its atlas record when known. */
565
+ declare function pausedAnswer(entry: CountyAccessEntry, record: AccessRecordLike | null | undefined, page?: AccessPageRef): CountyPausedAnswer;
566
+
567
+ /**
568
+ * Look up a county by state slug and county slug. A two-letter state
569
+ * abbreviation is also accepted, as in findState.
306
570
  * Returns undefined if the state isn't populated yet or the county doesn't exist.
307
571
  *
308
572
  * @example
@@ -324,6 +588,9 @@ declare function findCountyByFips(fips: string): CountyRecord | undefined;
324
588
 
325
589
  /**
326
590
  * Look up a state's full county list by state slug (e.g. "illinois", "new-york").
591
+ * A two-letter abbreviation is also accepted ("IL", "ny"): the 50 states and DC
592
+ * read as their slug, by the same rule as the hosted MCP and REST API, and any
593
+ * other input is read as a slug unchanged.
327
594
  * Returns undefined if the state isn't populated in the bundled data yet.
328
595
  */
329
596
  declare function findState(stateSlug: string): StateFile | undefined;
@@ -336,7 +603,9 @@ declare function findState(stateSlug: string): StateFile | undefined;
336
603
  declare function listStates(): StateIndexEntry[];
337
604
 
338
605
  /**
339
- * Return the list of counties with mapped REST endpoints for a given state slug.
606
+ * Return the list of counties the atlas records for a given state slug, served
607
+ * or not (countyHasEndpoint tells them apart). A two-letter state abbreviation
608
+ * is also accepted, as in findState.
340
609
  * Returns an empty array if the state isn't populated yet.
341
610
  */
342
611
  declare function listCountiesByState(stateSlug: string): CountyRecord[];
@@ -870,4 +1139,4 @@ declare function citiesForCounty(stateSlug: string, countySlug: string): CitySum
870
1139
  declare const cityPropertyIndex: CityPropertyIndex;
871
1140
  declare const cityZoningIndex: CityZoningIndex;
872
1141
 
873
- export { type Atlas, type AtlasIndex, CITY_RECORD_LIMIT, CITY_STREET_MAX_LEN, type CapabilityBasis, type CapabilityBasisType, type CapabilityField, type CapabilityOverrides, type CapabilityStatus, type CaseFieldMap, type CasesSource, type CityDatasetDescriptor, type CityFilter, type CityKind, type CityLookup, type CityPropertyIndex, type CityPropertyIndexEntry, type CityPropertyRecord, type CityProvider, type CityQueryTemplate, type CitySource, type CitySummary, type CityZoningIndex, type CityZoningIndexEntry, type CityZoningRecord, type ContactInfo, type CountyAdvisory, type CountyRecord, type CurrentZoningFieldMap, type CurrentZoningSource, type DatasetKind, type DeepLinkCounty, type EndpointRecord, type EndpointStatus, type GeocoderConfig, type GeocoderProvider, LIVE_STATUS_URL, type LicenseType, POINT_PLACEHOLDER, type PropertyDataset, type PropertyDatasets, type PropertyFieldMap, type PropertySource, type PropertySourceType, type PropertyStatusBuckets, type SearchField, type ServiceType, type SplitStreet, type StateFile, type StateIndexEntry, type VerifiedBy, type ZoningByAddressSource, type ZoningSourceType, type ZoningStatusBuckets, type ZoningToolKind, atlas, atlasIndex, buildCityQuery, buildParcelLookupDeepLink, canonicalLayerUrl, casesLocationTemplate, casesQueryUrl, citiesForCounty, citiesForCountyIn, cityDatasetDescriptors, cityDatasets, cityPath, cityPropertyIndex, cityZoningIndex, countyOffersAttributeSearch, countyPath, countySlugFromName, currentZoningTemplate, findCity, findCityIn, findCounty, findCountyByFips, findState, getCityProperty, getCityZoning, isReviewedUnservable, listCities, listCountiesByState, listStates, mergeCityIndexes, offersAttributeSearch, offersPagination, propertyQueryUrl, reviewedCapability, slugify, splitAddressStreetName, splitStreet, statePath, streetForDataset };
1142
+ export { ACCESS_FLAGS, ACCESS_PRESETS, ACCESS_REASONS, ATLAS_COUNTY_PAGE_BASE, type AccessFlag, type AccessFlags, type AccessPageRef, type AccessPreset, type AccessReason, type AccessRecordLike, type Atlas, type AtlasIndex, CITY_RECORD_LIMIT, CITY_STREET_MAX_LEN, COUNTY_RECHECK_REQUEST_MESSAGE, COUNTY_REQUEST_MESSAGE, COUNTY_REQUEST_URL, COVERAGE_REASONS, type CapabilityBasis, type CapabilityBasisType, type CapabilityField, type CapabilityOverrides, type CapabilityStatus, type CaseFieldMap, type CasesSource, type CityDatasetDescriptor, type CityFilter, type CityKind, type CityLookup, type CityPropertyIndex, type CityPropertyIndexEntry, type CityPropertyRecord, type CityProvider, type CityQueryTemplate, type CitySource, type CitySummary, type CityZoningIndex, type CityZoningIndexEntry, type CityZoningRecord, type ContactInfo, type CountyAccessEntry, type CountyAdvisory, type CountyCoverage, type CountyPausedAnswer, type CountyProduct, type CountyRecord, type CountyRequestHint, type CountyRequestRef, type CoverageAnswer, type CoverageReason, type CoverageRecordLike, type CoverageStatus, type CoverageTextInput, type CurrentZoningFieldMap, type CurrentZoningSource, type DatasetKind, type DeepLinkCounty, type EndpointPresenceLike, type EndpointRecord, type EndpointStatus, type GeocoderConfig, type GeocoderProvider, LIVE_STATUS_URL, type LicenseType, NOT_IN_ATLAS_WHY, NO_PUBLIC_DATA_WHY, POINT_PLACEHOLDER, PRESET_FLAGS, type PropertyDataset, type PropertyDatasets, type PropertyFieldMap, type PropertySource, type PropertySourceType, type PropertyStatusBuckets, type SearchField, type ServiceType, type SplitStreet, type StateFile, type StateIndexEntry, type VerifiedBy, type ZoningByAddressSource, type ZoningSourceType, type ZoningStatusBuckets, type ZoningToolKind, accessBlocks, atlas, atlasIndex, buildCityQuery, buildParcelLookupDeepLink, canonicalLayerUrl, casesLocationTemplate, casesQueryUrl, citiesForCounty, citiesForCountyIn, cityDatasetDescriptors, cityDatasets, cityPath, cityPropertyIndex, cityZoningIndex, countyHasEndpoint, countyOffersAttributeSearch, countyPath, countySlugFromName, coverageAnswer, coverageAnswerText, currentZoningTemplate, findCity, findCityIn, findCounty, findCountyByFips, findState, flagsFor, getCityProperty, getCityZoning, isReviewedUnservable, listCities, listCountiesByState, listStates, mergeCityIndexes, offersAttributeSearch, offersPagination, pausedAnswer, pausedFlags, presetOf, propertyQueryUrl, requestHint, reviewedCapability, slugify, splitAddressStreetName, splitStreet, statePath, streetForDataset };
package/dist/index.d.ts CHANGED
@@ -1,3 +1,158 @@
1
+ /** Why a county the atlas records has no endpoint we can serve. One code per record. */
2
+ declare const COVERAGE_REASONS: readonly ["owner-data-sold", "no-public-service", "login-required", "licence-restricted", "attributes-missing", "owner-blank", "service-down", "data-stale", "technical"];
3
+ type CoverageReason = (typeof COVERAGE_REASONS)[number];
4
+ /**
5
+ * The county's OWN paid channel for the data we do not serve. Set only with
6
+ * reason "owner-data-sold", and never a commercial reseller.
7
+ */
8
+ interface CountyProduct {
9
+ name: string;
10
+ url: string;
11
+ }
12
+ /**
13
+ * The `coverage` field of a county record with hasPublicRest:false: why we
14
+ * cannot index the county, and when we last looked.
15
+ */
16
+ interface CountyCoverage {
17
+ reason: CoverageReason;
18
+ /** One sentence of at most 280 characters, written to be shown as is. */
19
+ summary: string;
20
+ /** YYYY-MM-DD: when we last checked the county's public sources. */
21
+ checked: string;
22
+ /** YYYY-MM-DD: when we plan to look again, when a date is set. */
23
+ recheck?: string;
24
+ countyProduct?: CountyProduct;
25
+ }
26
+ /**
27
+ * "not-in-atlas": the atlas has no record for the county. That is all it
28
+ * says: a misspelled name lands here too, so it never claims the county was
29
+ * never looked at.
30
+ * "no-public-data": the atlas records the county, and it publishes nothing we can serve.
31
+ */
32
+ type CoverageStatus = "not-in-atlas" | "no-public-data";
33
+ /** POST a request body here to ask for a county. Free, and no key is needed. */
34
+ declare const COUNTY_REQUEST_URL = "https://urbankitstudio.com/api/atlas/request";
35
+ /** The request message for a county the atlas has no record for. */
36
+ declare const COUNTY_REQUEST_MESSAGE = "This county is not in the UrbanKit atlas. If you have its name rather than its FIPS code, check the spelling first against the counties the atlas covers: find_county or list_counties (list_counties_in_state on the hosted MCP server), or `uks find` in the CLI. If the county is right, offer to request it for the person you are helping; if they say yes, call the request_county MCP tool with the body above (or POST the body to the url), adding their email if they want to be told when it ships. Requesting is free.";
37
+ /**
38
+ * The request message for a county we checked and cannot serve. It promises
39
+ * nothing: we recheck, and a request tells us someone wants the county.
40
+ */
41
+ declare const COUNTY_RECHECK_REQUEST_MESSAGE = "We checked this county and it publishes no parcel data we can serve. We recheck counties like this one, and a request tells us people want it, but it does not promise we will add it. Offer to request it for the person you are helping; if they say yes, call the request_county MCP tool with the body above (or POST the body to the url), adding their email if they want to be told if that changes. Requesting is free.";
42
+ /**
43
+ * The county a not-served answer is about, as any surface knows it. `state` is
44
+ * a two-letter abbreviation, a full name, a slug or a two-digit state FIPS
45
+ * code, in any case; `county` is a name or a slug; `fips` is the 5-digit
46
+ * county FIPS code. The core normalises all three, so the same county gives
47
+ * the same request body on every surface.
48
+ */
49
+ interface CountyRequestRef {
50
+ state: string;
51
+ county?: string | null;
52
+ fips?: string | null;
53
+ }
54
+ /** A ready-to-send request for one county. */
55
+ interface CountyRequestHint {
56
+ how: "POST";
57
+ url: string;
58
+ /**
59
+ * Only keys POST /api/atlas/request and the request_county tool accept:
60
+ * county_fips, county_name, state_abbrev, state_slug, county_slug.
61
+ */
62
+ body: Record<string, string>;
63
+ message: string;
64
+ }
65
+ /**
66
+ * The `request` block a not-served answer carries: a ready-to-send body for
67
+ * POST /api/atlas/request and the request_county tool.
68
+ *
69
+ * A county with a valid FIPS code is named by it, with the county's name
70
+ * (when the ref holds a name rather than a slug) and the state's abbreviation
71
+ * taken from the code. One without is named by the state and county slugs
72
+ * alone, so every spelling of the same county ("Kane", "kane-county") sends
73
+ * the same body; a state the core does not know is sent as the caller's own
74
+ * text, slugged, so the answer never tells a caller which states exist and
75
+ * the request is still stored for us to read. Every value is already in the
76
+ * form the endpoint stores, so the body parses unchanged.
77
+ *
78
+ * Null when the ref names no county the endpoint accepts: no valid FIPS, and
79
+ * a state or county with no letter or digit to slug.
80
+ */
81
+ declare function requestHint(ref: CountyRequestRef, status?: CoverageStatus): CountyRequestHint | null;
82
+ /** The two record fields that decide whether a county is served. */
83
+ interface EndpointPresenceLike {
84
+ hasPublicRest?: boolean | null;
85
+ endpoints?: ReadonlyArray<unknown> | null;
86
+ }
87
+ /**
88
+ * True when the county has a public endpoint we can query: hasPublicRest is
89
+ * true AND at least one endpoint is registered. Every "is this county served"
90
+ * test reads this one rule.
91
+ */
92
+ declare function countyHasEndpoint(record: EndpointPresenceLike | null | undefined): boolean;
93
+ /** What coverageAnswer reads from a county record. */
94
+ interface CoverageRecordLike extends EndpointPresenceLike {
95
+ contact?: {
96
+ department?: string | null;
97
+ url?: string | null;
98
+ } | null;
99
+ coverage?: CountyCoverage | null;
100
+ }
101
+ /** `why` for a county the atlas has no record for. */
102
+ declare const NOT_IN_ATLAS_WHY = "This county is not in the UrbanKit atlas.";
103
+ /** `why` for a recorded county whose record carries no coverage summary (data older than the field). */
104
+ declare const NO_PUBLIC_DATA_WHY = "This county publishes no parcel data we can serve.";
105
+ /** The one answer every surface gives for a county we do not serve. */
106
+ interface CoverageAnswer {
107
+ /** Always false: this block exists only for a county whose parcels we do not serve. */
108
+ indexed: false;
109
+ status: CoverageStatus;
110
+ /** The record's reason code; null when there is no record, or the record predates the field. */
111
+ reason: CoverageReason | null;
112
+ /** One sentence to show the person as is. */
113
+ why: string;
114
+ /** YYYY-MM-DD of the last check; null when there is no record. */
115
+ checked: string | null;
116
+ /** YYYY-MM-DD of the next planned check; null when the record sets no date. */
117
+ recheck: string | null;
118
+ /** The county office that holds the records, from the record's contact. */
119
+ county_office: {
120
+ department: string | null;
121
+ url: string | null;
122
+ } | null;
123
+ /** The county's own paid product, only when the county sells the data. */
124
+ county_product: CountyProduct | null;
125
+ /** The ready-to-send request; null only when the ref names no county the request endpoint accepts. */
126
+ request: CountyRequestHint | null;
127
+ /** The whole answer as text, coverageAnswerText(this): what a text surface prints, verbatim. */
128
+ message: string;
129
+ }
130
+ /** What coverageAnswerText reads: a coverage block, with or without its message. */
131
+ type CoverageTextInput = Pick<CoverageAnswer, "status" | "why" | "checked" | "county_office" | "county_product"> & {
132
+ recheck?: string | null;
133
+ request: {
134
+ url: string;
135
+ body: Record<string, string>;
136
+ } | null;
137
+ };
138
+ /**
139
+ * The coverage block as text: why, when we checked and when we check next, the
140
+ * county's own office and product, and how to request the county, one point
141
+ * per line. The text
142
+ * surfaces (the stdio MCP server, the `uks` CLI, the hosted MCP) print it
143
+ * verbatim, and the block carries it as `message`. The request line quotes the
144
+ * body and URL from the block, so the text and the JSON never disagree.
145
+ */
146
+ declare function coverageAnswerText(block: CoverageTextInput): string;
147
+ /**
148
+ * The coverage answer for a county lookup that found no served county.
149
+ * `record` is the atlas record, or undefined when the atlas has none; `ref`
150
+ * names the county for the request body. Null when the record HAS an
151
+ * endpoint: there is nothing to explain.
152
+ */
153
+ declare function coverageAnswer(record: null | undefined, ref: CountyRequestRef): CoverageAnswer;
154
+ declare function coverageAnswer(record: CoverageRecordLike | null | undefined, ref: CountyRequestRef): CoverageAnswer | null;
155
+
1
156
  type ServiceType = "FeatureServer" | "MapServer";
2
157
  type LicenseType = "public" | "open-data" | "restricted" | "unknown";
3
158
  /**
@@ -202,6 +357,12 @@ interface CountyRecord {
202
357
  dataVintage?: CountyAdvisory | null;
203
358
  /** Reviewed, per-field capability assertions. See {@link CapabilityOverrides}. */
204
359
  capabilityOverrides?: CapabilityOverrides | null;
360
+ /**
361
+ * Why we cannot index this county, as a reason code and one sentence. Set on
362
+ * every record with `hasPublicRest: false` from 0.6.38; read it through
363
+ * `coverageAnswer()`.
364
+ */
365
+ coverage?: CountyCoverage | null;
205
366
  relatedZoningCitySlug?: string | null;
206
367
  relatedPropertyCitySlug?: string | null;
207
368
  }
@@ -302,7 +463,110 @@ declare function reviewedCapability(county: Pick<CountyRecord, "capabilityOverri
302
463
  declare function isReviewedUnservable(county: Pick<CountyRecord, "capabilityOverrides">, field: CapabilityField): boolean;
303
464
 
304
465
  /**
305
- * Look up a county by state slug and county slug.
466
+ * The surfaces a county can be paused on, one flag each. True = paused.
467
+ *
468
+ * "paid_lookup": a REST lookup by a paying caller (PAYG or a paid plan).
469
+ * "paid_enrich": a billed single-parcel owner lookup (MCP enrich_address).
470
+ * "paid_bulk": a billed owner list of addresses (REST bulk rows).
471
+ * "paid_lists": a billed radius owner list (REST radius, MCP radius_owners).
472
+ * "free_site_lookup": the site's free lookup tools, and a REST lookup by an
473
+ * anonymous or free-tier caller.
474
+ * "free_site_lists": the site's free whole-layer download (ArcGIS to GeoJSON).
475
+ * "free_discovery": the county record beyond its identity (endpoint URLs,
476
+ * notes, every other field) in county metadata and the
477
+ * discovery tools.
478
+ */
479
+ declare const ACCESS_FLAGS: readonly ["paid_lookup", "paid_enrich", "paid_bulk", "paid_lists", "free_site_lookup", "free_site_lists", "free_discovery"];
480
+ type AccessFlag = (typeof ACCESS_FLAGS)[number];
481
+ type AccessFlags = Readonly<Record<AccessFlag, boolean>>;
482
+ /**
483
+ * Named sets of flags.
484
+ *
485
+ * "paid-off": every billed call. Free use still answers.
486
+ * "paid-lists-off": billed owner LISTS only (radius, bulk). Single-parcel
487
+ * lookups still work.
488
+ * "all-off": everything, free use included.
489
+ */
490
+ declare const ACCESS_PRESETS: readonly ["paid-off", "paid-lists-off", "all-off"];
491
+ type AccessPreset = (typeof ACCESS_PRESETS)[number];
492
+ declare const PRESET_FLAGS: Readonly<Record<AccessPreset, readonly AccessFlag[]>>;
493
+ /** The flags a preset sets: every flag present, true for the preset's own. */
494
+ declare function flagsFor(preset: AccessPreset): AccessFlags;
495
+ /** The paused flags, in ACCESS_FLAGS order. */
496
+ declare function pausedFlags(flags: AccessFlags): AccessFlag[];
497
+ /** The preset these flags are exactly, or "custom". */
498
+ declare function presetOf(flags: AccessFlags): AccessPreset | "custom";
499
+ /** Why a county is paused. One code per county. */
500
+ declare const ACCESS_REASONS: readonly ["licence-terms", "state-law", "county-request", "data-quality", "upstream-broken", "other"];
501
+ type AccessReason = (typeof ACCESS_REASONS)[number];
502
+ /** One paused county, as the operator recorded it. */
503
+ interface CountyAccessEntry {
504
+ county_fips: string;
505
+ flags: AccessFlags;
506
+ reason: AccessReason;
507
+ /** One sentence of at most 280 characters, written to be shown as is. */
508
+ why: string;
509
+ /** The county's own terms page, or the law, that the pause rests on. */
510
+ citation_url: string;
511
+ /** When the county was paused: an ISO timestamp, or YYYY-MM-DD. */
512
+ since: string;
513
+ }
514
+ /** Is `flag` paused for this county? No entry means the county is fully on. */
515
+ declare function accessBlocks(entry: {
516
+ flags: AccessFlags;
517
+ } | null | undefined, flag: AccessFlag): boolean;
518
+ /** What pausedAnswer reads from a county record. */
519
+ interface AccessRecordLike {
520
+ contact?: {
521
+ department?: string | null;
522
+ url?: string | null;
523
+ } | null;
524
+ /** The record's own endpoints: their hosts are what a withheld answer must not name. */
525
+ endpoints?: ReadonlyArray<{
526
+ url: string;
527
+ }> | null;
528
+ }
529
+ /** Where the county's free page lives. Either slug missing: no page offered. */
530
+ interface AccessPageRef {
531
+ state_slug?: string | null;
532
+ county_slug?: string | null;
533
+ }
534
+ declare const ATLAS_COUNTY_PAGE_BASE = "https://urbankitstudio.com/parcel-atlas";
535
+ /** The one answer every surface gives for a county that is paused. */
536
+ interface CountyPausedAnswer {
537
+ /** Always true: the county IS in the atlas. */
538
+ indexed: true;
539
+ status: "paused";
540
+ /** The preset the flags match, or "custom". */
541
+ preset: AccessPreset | "custom";
542
+ /** Which surfaces are paused, in ACCESS_FLAGS order. */
543
+ paused: AccessFlag[];
544
+ reason: AccessReason;
545
+ /** One sentence to show the person as is. Null under free_discovery when it
546
+ * names the county's service (discoverySafeContact). */
547
+ why: string | null;
548
+ /** The county's own terms page, or the law, that the pause rests on. Null
549
+ * under free_discovery when it names the county's service (discoverySafeContact). */
550
+ citation_url: string | null;
551
+ since: string;
552
+ /** The county office that holds the records, from the record's contact. */
553
+ county_office: {
554
+ department: string | null;
555
+ url: string | null;
556
+ } | null;
557
+ /** The free county page; null when free lookup or discovery is paused, or the page is unknown. */
558
+ free_alternatives: {
559
+ county_page: string;
560
+ } | null;
561
+ /** Always null: a paused county is not something to request. */
562
+ request: null;
563
+ }
564
+ /** The paused answer for one county. `record` is its atlas record when known. */
565
+ declare function pausedAnswer(entry: CountyAccessEntry, record: AccessRecordLike | null | undefined, page?: AccessPageRef): CountyPausedAnswer;
566
+
567
+ /**
568
+ * Look up a county by state slug and county slug. A two-letter state
569
+ * abbreviation is also accepted, as in findState.
306
570
  * Returns undefined if the state isn't populated yet or the county doesn't exist.
307
571
  *
308
572
  * @example
@@ -324,6 +588,9 @@ declare function findCountyByFips(fips: string): CountyRecord | undefined;
324
588
 
325
589
  /**
326
590
  * Look up a state's full county list by state slug (e.g. "illinois", "new-york").
591
+ * A two-letter abbreviation is also accepted ("IL", "ny"): the 50 states and DC
592
+ * read as their slug, by the same rule as the hosted MCP and REST API, and any
593
+ * other input is read as a slug unchanged.
327
594
  * Returns undefined if the state isn't populated in the bundled data yet.
328
595
  */
329
596
  declare function findState(stateSlug: string): StateFile | undefined;
@@ -336,7 +603,9 @@ declare function findState(stateSlug: string): StateFile | undefined;
336
603
  declare function listStates(): StateIndexEntry[];
337
604
 
338
605
  /**
339
- * Return the list of counties with mapped REST endpoints for a given state slug.
606
+ * Return the list of counties the atlas records for a given state slug, served
607
+ * or not (countyHasEndpoint tells them apart). A two-letter state abbreviation
608
+ * is also accepted, as in findState.
340
609
  * Returns an empty array if the state isn't populated yet.
341
610
  */
342
611
  declare function listCountiesByState(stateSlug: string): CountyRecord[];
@@ -870,4 +1139,4 @@ declare function citiesForCounty(stateSlug: string, countySlug: string): CitySum
870
1139
  declare const cityPropertyIndex: CityPropertyIndex;
871
1140
  declare const cityZoningIndex: CityZoningIndex;
872
1141
 
873
- export { type Atlas, type AtlasIndex, CITY_RECORD_LIMIT, CITY_STREET_MAX_LEN, type CapabilityBasis, type CapabilityBasisType, type CapabilityField, type CapabilityOverrides, type CapabilityStatus, type CaseFieldMap, type CasesSource, type CityDatasetDescriptor, type CityFilter, type CityKind, type CityLookup, type CityPropertyIndex, type CityPropertyIndexEntry, type CityPropertyRecord, type CityProvider, type CityQueryTemplate, type CitySource, type CitySummary, type CityZoningIndex, type CityZoningIndexEntry, type CityZoningRecord, type ContactInfo, type CountyAdvisory, type CountyRecord, type CurrentZoningFieldMap, type CurrentZoningSource, type DatasetKind, type DeepLinkCounty, type EndpointRecord, type EndpointStatus, type GeocoderConfig, type GeocoderProvider, LIVE_STATUS_URL, type LicenseType, POINT_PLACEHOLDER, type PropertyDataset, type PropertyDatasets, type PropertyFieldMap, type PropertySource, type PropertySourceType, type PropertyStatusBuckets, type SearchField, type ServiceType, type SplitStreet, type StateFile, type StateIndexEntry, type VerifiedBy, type ZoningByAddressSource, type ZoningSourceType, type ZoningStatusBuckets, type ZoningToolKind, atlas, atlasIndex, buildCityQuery, buildParcelLookupDeepLink, canonicalLayerUrl, casesLocationTemplate, casesQueryUrl, citiesForCounty, citiesForCountyIn, cityDatasetDescriptors, cityDatasets, cityPath, cityPropertyIndex, cityZoningIndex, countyOffersAttributeSearch, countyPath, countySlugFromName, currentZoningTemplate, findCity, findCityIn, findCounty, findCountyByFips, findState, getCityProperty, getCityZoning, isReviewedUnservable, listCities, listCountiesByState, listStates, mergeCityIndexes, offersAttributeSearch, offersPagination, propertyQueryUrl, reviewedCapability, slugify, splitAddressStreetName, splitStreet, statePath, streetForDataset };
1142
+ export { ACCESS_FLAGS, ACCESS_PRESETS, ACCESS_REASONS, ATLAS_COUNTY_PAGE_BASE, type AccessFlag, type AccessFlags, type AccessPageRef, type AccessPreset, type AccessReason, type AccessRecordLike, type Atlas, type AtlasIndex, CITY_RECORD_LIMIT, CITY_STREET_MAX_LEN, COUNTY_RECHECK_REQUEST_MESSAGE, COUNTY_REQUEST_MESSAGE, COUNTY_REQUEST_URL, COVERAGE_REASONS, type CapabilityBasis, type CapabilityBasisType, type CapabilityField, type CapabilityOverrides, type CapabilityStatus, type CaseFieldMap, type CasesSource, type CityDatasetDescriptor, type CityFilter, type CityKind, type CityLookup, type CityPropertyIndex, type CityPropertyIndexEntry, type CityPropertyRecord, type CityProvider, type CityQueryTemplate, type CitySource, type CitySummary, type CityZoningIndex, type CityZoningIndexEntry, type CityZoningRecord, type ContactInfo, type CountyAccessEntry, type CountyAdvisory, type CountyCoverage, type CountyPausedAnswer, type CountyProduct, type CountyRecord, type CountyRequestHint, type CountyRequestRef, type CoverageAnswer, type CoverageReason, type CoverageRecordLike, type CoverageStatus, type CoverageTextInput, type CurrentZoningFieldMap, type CurrentZoningSource, type DatasetKind, type DeepLinkCounty, type EndpointPresenceLike, type EndpointRecord, type EndpointStatus, type GeocoderConfig, type GeocoderProvider, LIVE_STATUS_URL, type LicenseType, NOT_IN_ATLAS_WHY, NO_PUBLIC_DATA_WHY, POINT_PLACEHOLDER, PRESET_FLAGS, type PropertyDataset, type PropertyDatasets, type PropertyFieldMap, type PropertySource, type PropertySourceType, type PropertyStatusBuckets, type SearchField, type ServiceType, type SplitStreet, type StateFile, type StateIndexEntry, type VerifiedBy, type ZoningByAddressSource, type ZoningSourceType, type ZoningStatusBuckets, type ZoningToolKind, accessBlocks, atlas, atlasIndex, buildCityQuery, buildParcelLookupDeepLink, canonicalLayerUrl, casesLocationTemplate, casesQueryUrl, citiesForCounty, citiesForCountyIn, cityDatasetDescriptors, cityDatasets, cityPath, cityPropertyIndex, cityZoningIndex, countyHasEndpoint, countyOffersAttributeSearch, countyPath, countySlugFromName, coverageAnswer, coverageAnswerText, currentZoningTemplate, findCity, findCityIn, findCounty, findCountyByFips, findState, flagsFor, getCityProperty, getCityZoning, isReviewedUnservable, listCities, listCountiesByState, listStates, mergeCityIndexes, offersAttributeSearch, offersPagination, pausedAnswer, pausedFlags, presetOf, propertyQueryUrl, requestHint, reviewedCapability, slugify, splitAddressStreetName, splitStreet, statePath, streetForDataset };