@urbankitstudio/atlas 0.5.3 → 0.6.1

package/dist/index.d.cts

@@ -52,6 +52,58 @@ interface ContactInfo {
     url: string | null;
     email: string | null;
 }
+/** A short curated caveat about a county, written by a human. */
+interface CountyAdvisory {
+    body: string;
+    source?: {
+        label: string;
+        url: string;
+    };
+}
+/** The fields a caller can ask a county about. */
+type CapabilityField = "apn" | "owner_name" | "owner_mailing_address" | "situs_address" | "geometry" | "land_use" | "zoning";
+type CapabilityStatus = "available" | "not_published" | "restricted" | "unverified";
+/**
+ * Where a non-available status comes from. The type matters more than the
+ * prose, because it tells you whether you are reading a fact about a service, a
+ * claim the COUNTY makes, or a claim we make.
+ *
+ * `county_cited_statute` is the one to read carefully. It means the county
+ * publishes that citation as its own reason, reported here attributed to them
+ * rather than adopted as our reading of the law. San Bernardino County returns
+ * the literal string "Protected Per CA Gov Code 7928.205" in every owner-name
+ * row; that section protects the home address of elected and appointed
+ * officials, and San Diego County publishes owner names on its public layer.
+ * One statute, different county behaviour, so the attribution is not a
+ * formality.
+ */
+type CapabilityBasisType = "endpoint_schema" | "county_cited_statute" | "statute" | "county_policy";
+interface CapabilityBasis {
+    type: CapabilityBasisType;
+    /** One sentence you could show a user without editing. */
+    note: string;
+    citation?: string;
+    sourceUrl?: string;
+    /** Who makes the claim, when it is not us. Always set for county_cited_statute. */
+    attributedTo?: string;
+}
+/**
+ * REVIEWED capability assertions, per field. Only entries a human entered and
+ * checked appear here, which is exactly the knowledge you cannot compute from
+ * the bundled data yourself.
+ *
+ * What is NOT here is the mechanical half. Whether a field is simply absent
+ * from an endpoint's documented `searchFields` is derivable, and this package
+ * deliberately does not derive it: a second implementation of that
+ * classification would drift from the one the API bills against, and you would
+ * have no way to tell which was right. Read `endpoints[].searchFields` for the
+ * mechanical answer, and treat an entry here as outranking it.
+ */
+type CapabilityOverrides = Partial<Record<CapabilityField, {
+    status: CapabilityStatus;
+    basis: CapabilityBasis;
+    lawfulAlternativeUrl?: string | null;
+}>>;
 interface CountyRecord {
     id: string;
     state: string;
@@ -64,6 +116,14 @@ interface CountyRecord {
     contact: ContactInfo | null;
     hasPublicRest: boolean;
     notes: string | null;
+    /** Curated caveat about owner data on this county's public layer. */
+    ownerFieldNote?: CountyAdvisory | null;
+    /** Curated caveat about how old the county's published data is. */
+    dataVintage?: CountyAdvisory | null;
+    /** Reviewed, per-field capability assertions. See {@link CapabilityOverrides}. */
+    capabilityOverrides?: CapabilityOverrides | null;
+    relatedZoningCitySlug?: string | null;
+    relatedPropertyCitySlug?: string | null;
 }
 interface StateFile {
     stateSlug: string;
@@ -88,9 +148,41 @@ interface AtlasIndex {
         states: number;
         counties: number;
         endpoints: number;
+        /** Counties that publish at least one endpoint, i.e. the ones you can
+         *  actually query. Distinct from BOTH fields above: counties counts every
+         *  indexed county, endpoints counts endpoint RECORDS (a few counties
+         *  publish two). Those two coincided at 155/155 while four counties
+         *  published none, which is how published copy came to claim 155 verified
+         *  endpoints. Prefer this when the sentence is about queryable coverage. */
+        countiesWithEndpoint: number;
     };
 }
 
+/**
+ * The reviewed capability assertion for one field, or null when none exists.
+ *
+ * Null is the common answer and it is not a failure: it means nobody has had to
+ * write anything down about that field for that county, so the ordinary rules
+ * apply. Read `county.endpoints[].searchFields` to see what the layer actually
+ * documents.
+ *
+ * A non-null answer is the part worth branching on. It was entered by a human
+ * who checked something a field list cannot show, and it outranks whatever the
+ * field list implies. The clearest case: San Bernardino County publishes an
+ * `OwnerName` column, so the field list says owner names are available, and
+ * every row's value is the literal string "Protected Per CA Gov Code 7928.205".
+ * Only the reviewed record can tell you that.
+ */
+declare function reviewedCapability(county: Pick<CountyRecord, "capabilityOverrides">, field: CapabilityField): NonNullable<CapabilityOverrides[CapabilityField]> | null;
+/**
+ * True when a reviewed record says this field cannot be served, whatever the
+ * reason. Use it to decide whether to promise a user the field at all.
+ *
+ * False does NOT mean "available". It means no reviewed record says otherwise,
+ * so fall back to the endpoint's documented `searchFields`.
+ */
+declare function isReviewedUnservable(county: Pick<CountyRecord, "capabilityOverrides">, field: CapabilityField): boolean;
+
 /**
  * Look up a county by state slug and county slug.
  * Returns undefined if the state isn't populated yet or the county doesn't exist.
@@ -146,4 +238,4 @@ interface Atlas {
 }
 declare const atlas: Atlas;
 
-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 };
+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 };

package/dist/index.d.ts

@@ -52,6 +52,58 @@ interface ContactInfo {
     url: string | null;
     email: string | null;
 }
+/** A short curated caveat about a county, written by a human. */
+interface CountyAdvisory {
+    body: string;
+    source?: {
+        label: string;
+        url: string;
+    };
+}
+/** The fields a caller can ask a county about. */
+type CapabilityField = "apn" | "owner_name" | "owner_mailing_address" | "situs_address" | "geometry" | "land_use" | "zoning";
+type CapabilityStatus = "available" | "not_published" | "restricted" | "unverified";
+/**
+ * Where a non-available status comes from. The type matters more than the
+ * prose, because it tells you whether you are reading a fact about a service, a
+ * claim the COUNTY makes, or a claim we make.
+ *
+ * `county_cited_statute` is the one to read carefully. It means the county
+ * publishes that citation as its own reason, reported here attributed to them
+ * rather than adopted as our reading of the law. San Bernardino County returns
+ * the literal string "Protected Per CA Gov Code 7928.205" in every owner-name
+ * row; that section protects the home address of elected and appointed
+ * officials, and San Diego County publishes owner names on its public layer.
+ * One statute, different county behaviour, so the attribution is not a
+ * formality.
+ */
+type CapabilityBasisType = "endpoint_schema" | "county_cited_statute" | "statute" | "county_policy";
+interface CapabilityBasis {
+    type: CapabilityBasisType;
+    /** One sentence you could show a user without editing. */
+    note: string;
+    citation?: string;
+    sourceUrl?: string;
+    /** Who makes the claim, when it is not us. Always set for county_cited_statute. */
+    attributedTo?: string;
+}
+/**
+ * REVIEWED capability assertions, per field. Only entries a human entered and
+ * checked appear here, which is exactly the knowledge you cannot compute from
+ * the bundled data yourself.
+ *
+ * What is NOT here is the mechanical half. Whether a field is simply absent
+ * from an endpoint's documented `searchFields` is derivable, and this package
+ * deliberately does not derive it: a second implementation of that
+ * classification would drift from the one the API bills against, and you would
+ * have no way to tell which was right. Read `endpoints[].searchFields` for the
+ * mechanical answer, and treat an entry here as outranking it.
+ */
+type CapabilityOverrides = Partial<Record<CapabilityField, {
+    status: CapabilityStatus;
+    basis: CapabilityBasis;
+    lawfulAlternativeUrl?: string | null;
+}>>;
 interface CountyRecord {
     id: string;
     state: string;
@@ -64,6 +116,14 @@ interface CountyRecord {
     contact: ContactInfo | null;
     hasPublicRest: boolean;
     notes: string | null;
+    /** Curated caveat about owner data on this county's public layer. */
+    ownerFieldNote?: CountyAdvisory | null;
+    /** Curated caveat about how old the county's published data is. */
+    dataVintage?: CountyAdvisory | null;
+    /** Reviewed, per-field capability assertions. See {@link CapabilityOverrides}. */
+    capabilityOverrides?: CapabilityOverrides | null;
+    relatedZoningCitySlug?: string | null;
+    relatedPropertyCitySlug?: string | null;
 }
 interface StateFile {
     stateSlug: string;
@@ -88,9 +148,41 @@ interface AtlasIndex {
         states: number;
         counties: number;
         endpoints: number;
+        /** Counties that publish at least one endpoint, i.e. the ones you can
+         *  actually query. Distinct from BOTH fields above: counties counts every
+         *  indexed county, endpoints counts endpoint RECORDS (a few counties
+         *  publish two). Those two coincided at 155/155 while four counties
+         *  published none, which is how published copy came to claim 155 verified
+         *  endpoints. Prefer this when the sentence is about queryable coverage. */
+        countiesWithEndpoint: number;
     };
 }
 
+/**
+ * The reviewed capability assertion for one field, or null when none exists.
+ *
+ * Null is the common answer and it is not a failure: it means nobody has had to
+ * write anything down about that field for that county, so the ordinary rules
+ * apply. Read `county.endpoints[].searchFields` to see what the layer actually
+ * documents.
+ *
+ * A non-null answer is the part worth branching on. It was entered by a human
+ * who checked something a field list cannot show, and it outranks whatever the
+ * field list implies. The clearest case: San Bernardino County publishes an
+ * `OwnerName` column, so the field list says owner names are available, and
+ * every row's value is the literal string "Protected Per CA Gov Code 7928.205".
+ * Only the reviewed record can tell you that.
+ */
+declare function reviewedCapability(county: Pick<CountyRecord, "capabilityOverrides">, field: CapabilityField): NonNullable<CapabilityOverrides[CapabilityField]> | null;
+/**
+ * True when a reviewed record says this field cannot be served, whatever the
+ * reason. Use it to decide whether to promise a user the field at all.
+ *
+ * False does NOT mean "available". It means no reviewed record says otherwise,
+ * so fall back to the endpoint's documented `searchFields`.
+ */
+declare function isReviewedUnservable(county: Pick<CountyRecord, "capabilityOverrides">, field: CapabilityField): boolean;
+
 /**
  * Look up a county by state slug and county slug.
  * Returns undefined if the state isn't populated yet or the county doesn't exist.
@@ -146,4 +238,4 @@ interface Atlas {
 }
 declare const atlas: Atlas;
 
-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 };
+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 };