@cliwant/mcp-sam-gov 1.8.0 → 1.10.0

package/README.ja.md

@@ -1,7 +1,7 @@
 # @cliwant/mcp-sam-gov
 
 > **最も包括的なキーレス連邦データ MCP サーバー。**
-> SAM.gov · USAspending · SEC EDGAR · OFAC · FDIC · Federal Register · Regulations.gov · eCFR · FAR/DFARS · BLS · Treasury · NIH · NSF · ClinicalTrials · CMS · NVD/CISA · USITC · Census · FRED · BEA · DOL · FEMA · openFDA · NHTSA · CPSC · EPA Envirofacts · CourtListener · IRS-990(ProPublica) ほか **48 の連邦データソース、143 ツール。** キーレス優先 — Census business-patterns · FRED · BEA · DOL データエンドポイントの 4 ソースのみ無料キーが必要で、残り 44 ソースはキー不要。
+> SAM.gov · USAspending · SEC EDGAR · OFAC · FDIC · Federal Register · Regulations.gov · eCFR · FAR/DFARS · BLS · Treasury · NIH · NSF · ClinicalTrials · CMS · NVD/CISA · USITC · Census · FRED · BEA · DOL · FEMA · openFDA · NHTSA · CPSC · EPA Envirofacts · CourtListener · IRS-990(ProPublica) ほか **48 の連邦データソース、144 ツール。** キーレス優先 — Census business-patterns · FRED · BEA · DOL データエンドポイントの 4 ソースのみ無料キーが必要で、残り 44 ソースはキー不要。
 > API キー不要、登録不要、サインアップ不要。Claude Desktop, Claude Code, Codex CLI, Cursor, Continue, Gemini CLI、すべての MCP ホスト対応。
 
 [English README](./README.md) · [한국어 README](./README.ko.md)
@@ -30,7 +30,7 @@
 | 🌐 **貿易・地理・災害** | "この品目の HTS 関税、この住所の Census tract、この州の FEMA 宣言" | USITC HTS, Census, FEMA, Socrata, CKAN |
 | 🎓 **grant・データセット** | "過去 30 日のサイバーセキュリティ grant、連邦オープンデータセット発見" | Grants.gov, data.gov |
 
-**48 の連邦データソース、合計 143 ツール — キーレス優先: Census business-patterns · FRED · BEA · DOL データエンドポイントの 4 ソースのみ無料キーが必要で、残り 44 ソースはキー不要。** (初期の 52 ツール版でおおよそ p50 ~0.25s / p95 ~0.8s を計測 — ソースや上流負荷で変動する近似値であり保証値ではありません。)
+**48 の連邦データソース、合計 144 ツール — キーレス優先: Census business-patterns · FRED · BEA · DOL データエンドポイントの 4 ソースのみ無料キーが必要で、残り 44 ソースはキー不要。** (初期の 52 ツール版でおおよそ p50 ~0.25s / p95 ~0.8s を計測 — ソースや上流負荷で変動する近似値であり保証値ではありません。)
 
 ---
 
@@ -57,7 +57,7 @@ Claude Code (CLI) を既に使用している場合：
 /plugin install cliwant/mcp-sam-gov
 ```
 
-MCP サーバー + Claude が 143 ツールをいつ・どう呼ぶかを教える [SKILL.md ワークフローガイド](./skills/sam-gov/SKILL.md) を同時登録。
+MCP サーバー + Claude が 144 ツールをいつ・どう呼ぶかを教える [SKILL.md ワークフローガイド](./skills/sam-gov/SKILL.md) を同時登録。
 
 ### 🔵 パス 3 — Codex / Cursor / Continue / Gemini 等の手動インストール
 
@@ -188,9 +188,9 @@ npm はインストール済みユーザーに新バージョンを通知しな
 
 **自動投稿は一切ありません。** サーバーにトークンもアカウントもなく、リンクを作るだけで、開いて送信するのは**あなた**です。事前入力リンクにはツール名・エラー種別・サーバーバージョンのみが含まれ、クエリ値は含まれません。公開リポジトリなので、機微な内容は削除してから送信してください。直接開く: [**New issue**](https://github.com/cliwant/mcp-sam-gov/issues/new/choose)。
 
-## ツールカタログ (143)
+## ツールカタログ (144)
 
-ワークフロー別グループ。キーレス優先 — 大半はキー不要、Census business-patterns · FRED · BEA · DOL データエンドポイントは無料キーが必要。全 per-tool 一覧と入力 schema・誠実性 caveat の原文は [英語 README のカタログセクション](./README.md#tool-catalog-143-tools) を正とします。
+ワークフロー別グループ。キーレス優先 — 大半はキー不要、Census business-patterns · FRED · BEA · DOL データエンドポイントは無料キーが必要。全 per-tool 一覧と入力 schema・誠実性 caveat の原文は [英語 README のカタログセクション](./README.md#tool-catalog-144-tools) を正とします。
 
 - **案件 + ソリシテーション — SAM.gov + Grants.gov (10)**: `sam_search_opportunities` `sam_search_shaping` `sam_get_opportunity` `sam_fetch_description` `sam_fetch_attachment_text` `sam_attachment_url` `sam_lookup_organization` `sam_lookup_notice_fields` `grants_search` `grants_get_opportunity`
 - **spending・受注・競合 — USAspending + FPDS + GAO (31)**: `usas_search_awards` `usas_search_individual_awards` `usas_get_award_detail` `usas_search_awards_by_recipient` `usas_search_subawards` `usas_search_recompetes` `usas_search_expiring_contracts`(deprecated) `usas_analyze_incumbent` `usas_search_teaming_partners` `usas_spending_over_time` `usas_search_agency_spending` `usas_search_subagency_spending` `usas_search_psc_spending` `usas_search_cfda_spending` `usas_search_state_spending` `usas_search_federal_account_spending` `usas_search_recipients` `usas_get_recipient_profile` `usas_get_agency_profile` `usas_get_agency_awards_summary` `usas_get_agency_budget_function` `usas_list_toptier_agencies` `usas_lookup_agency` `usas_autocomplete_naics` `usas_autocomplete_recipient` `usas_naics_hierarchy` `usas_glossary` `usas_list_disaster_codes`(災害緊急基金コード(DEFC)一覧 — COVID-19·IIJA/インフラ等の緊急歳出タグ) `usas_disaster_spending`(指定 DEFC の災害/緊急基金支出の地域別内訳 — どの州/郡/選挙区が COVID/IIJA 救済金を受領) `fpds_search_awards` `gao_protest_lookup`

package/README.ko.md

@@ -1,7 +1,7 @@
 # @cliwant/mcp-sam-gov
 
 > **가장 포괄적인 keyless 연방 데이터 MCP 서버.**
-> SAM.gov · USAspending · SEC EDGAR · OFAC · FDIC · Federal Register · Regulations.gov · eCFR · FAR/DFARS · BLS · Treasury · NIH · NSF · ClinicalTrials · CMS · NVD/CISA · USITC · Census · FRED · BEA · DOL · FEMA · openFDA · NHTSA · CPSC · EPA Envirofacts · CourtListener · IRS-990(ProPublica) 외 **48개 연방 데이터 소스, 143개 도구.** keyless 우선 — Census business-patterns · FRED · BEA · DOL 데이터 엔드포인트 4개 소스만 무료 키가 필요하고 나머지 44개 소스는 키가 필요 없습니다.
+> SAM.gov · USAspending · SEC EDGAR · OFAC · FDIC · Federal Register · Regulations.gov · eCFR · FAR/DFARS · BLS · Treasury · NIH · NSF · ClinicalTrials · CMS · NVD/CISA · USITC · Census · FRED · BEA · DOL · FEMA · openFDA · NHTSA · CPSC · EPA Envirofacts · CourtListener · IRS-990(ProPublica) 외 **48개 연방 데이터 소스, 144개 도구.** keyless 우선 — Census business-patterns · FRED · BEA · DOL 데이터 엔드포인트 4개 소스만 무료 키가 필요하고 나머지 44개 소스는 키가 필요 없습니다.
 > API 키 / 등록 / 가입 불필요. Claude Desktop, Claude Code, Codex CLI, Cursor, Continue, Gemini CLI, 모든 MCP 호스트 호환.
 
 [English README](./README.md) · [日本語 README](./README.ja.md)
@@ -30,7 +30,7 @@
 | 🌐 **무역·지리·재난** | "이 품목 HTS 관세, 이 주소 Census tract, 이 주의 FEMA 선포" | USITC HTS, Census, FEMA, Socrata, CKAN |
 | 🎓 **grant·데이터셋** | "최근 30일 사이버보안 grant, 연방 오픈 데이터셋 발굴" | Grants.gov, data.gov |
 
-**48개 연방 데이터 소스, 총 143개 도구 — keyless 우선: Census business-patterns · FRED · BEA · DOL 데이터 엔드포인트 4개 소스만 무료 키가 필요하고 나머지 44개 소스는 키가 필요 없습니다.** (초기 52-도구 빌드 기준 대략 p50 ~0.25s / p95 ~0.8s 측정 — 소스·업스트림 부하에 따라 변동하는 근사치이며 보장값이 아님.)
+**48개 연방 데이터 소스, 총 144개 도구 — keyless 우선: Census business-patterns · FRED · BEA · DOL 데이터 엔드포인트 4개 소스만 무료 키가 필요하고 나머지 44개 소스는 키가 필요 없습니다.** (초기 52-도구 빌드 기준 대략 p50 ~0.25s / p95 ~0.8s 측정 — 소스·업스트림 부하에 따라 변동하는 근사치이며 보장값이 아님.)
 
 ---
 
@@ -57,7 +57,7 @@ PowerShell, npm 등 필요 없음.
 /plugin install cliwant/mcp-sam-gov
 ```
 
-MCP 서버 + Claude 가 143개 도구를 언제 / 어떻게 호출할지 가르치는 [SKILL.md 워크플로 가이드](./skills/sam-gov/SKILL.md) 동시 등록.
+MCP 서버 + Claude 가 144개 도구를 언제 / 어떻게 호출할지 가르치는 [SKILL.md 워크플로 가이드](./skills/sam-gov/SKILL.md) 동시 등록.
 
 ### 🔵 경로 3 — Codex / Cursor / Continue / Gemini 등 수동 설치
 
@@ -188,9 +188,9 @@ npm은 설치한 사용자에게 새 버전을 알려주지 않으므로, 서버
 
 **자동 제출은 절대 없습니다.** 서버엔 토큰·계정이 없고 링크만 만들며, 열어서 제출하는 건 **사용자**입니다. 프리필 링크에는 툴명·에러종류·서버버전만 담기고 쿼리값은 담기지 않습니다. 공개 레포이니 민감한 내용은 지우고 제출하세요. 직접 열기: [**New issue**](https://github.com/cliwant/mcp-sam-gov/issues/new/choose).
 
-## 도구 카탈로그 (143개)
+## 도구 카탈로그 (144개)
 
-워크플로별 그룹. keyless 우선 — 대부분 키가 필요 없고, Census business-patterns · FRED · BEA · DOL 데이터 엔드포인트는 무료 키가 필요합니다. 전체 per-tool 목록과 입력 schema·정직성 caveat 원문은 [영문 README 의 카탈로그 섹션](./README.md#tool-catalog-143-tools)을 기준으로 하세요.
+워크플로별 그룹. keyless 우선 — 대부분 키가 필요 없고, Census business-patterns · FRED · BEA · DOL 데이터 엔드포인트는 무료 키가 필요합니다. 전체 per-tool 목록과 입력 schema·정직성 caveat 원문은 [영문 README 의 카탈로그 섹션](./README.md#tool-catalog-144-tools)을 기준으로 하세요.
 
 - **입찰 + 솔리시테이션 — SAM.gov + Grants.gov (10)**: `sam_search_opportunities` `sam_search_shaping` `sam_get_opportunity` `sam_fetch_description` `sam_fetch_attachment_text` `sam_attachment_url` `sam_lookup_organization` `sam_lookup_notice_fields` `grants_search` `grants_get_opportunity`
 - **spending·수주·경쟁 — USAspending + FPDS + GAO (31)**: `usas_search_awards` `usas_search_individual_awards` `usas_get_award_detail` `usas_search_awards_by_recipient` `usas_search_subawards` `usas_search_recompetes` `usas_search_expiring_contracts`(deprecated) `usas_analyze_incumbent` `usas_search_teaming_partners` `usas_spending_over_time` `usas_search_agency_spending` `usas_search_subagency_spending` `usas_search_psc_spending` `usas_search_cfda_spending` `usas_search_state_spending` `usas_search_federal_account_spending` `usas_search_recipients` `usas_get_recipient_profile` `usas_get_agency_profile` `usas_get_agency_awards_summary` `usas_get_agency_budget_function` `usas_list_toptier_agencies` `usas_lookup_agency` `usas_autocomplete_naics` `usas_autocomplete_recipient` `usas_naics_hierarchy` `usas_glossary` `usas_list_disaster_codes`(재난긴급자금코드(DEFC) 목록 — COVID-19·IIJA/인프라 등 긴급세출 태그) `usas_disaster_spending`(지정 DEFC의 재난/긴급자금 지출 지역별 분해 — 어느 주/카운티/선거구가 COVID/IIJA 구호금 수령) `fpds_search_awards` `gao_protest_lookup`

package/README.md

@@ -4,7 +4,7 @@
 
 ### **$4 trillion of public federal data, one `npm install` away.**
 
-The most comprehensive **keyless-first** MCP server for US federal contracting + spending + regulation + partner vetting. **143 tools across 48 federal data sources** — keyless-first: only 4 sources (Census business-patterns, FRED, BEA, and DOL's data endpoint) need a free key; the other 44 need none. Works today, in any AI agent.
+The most comprehensive **keyless-first** MCP server for US federal contracting + spending + regulation + partner vetting. **144 tools across 48 federal data sources** — keyless-first: only 4 sources (Census business-patterns, FRED, BEA, and DOL's data endpoint) need a free key; the other 44 need none. Works today, in any AI agent.
 
 [![npm](https://img.shields.io/npm/v/@cliwant/mcp-sam-gov?color=cb3837&label=%40cliwant%2Fmcp-sam-gov&logo=npm)](https://www.npmjs.com/package/@cliwant/mcp-sam-gov)
 [![mcp-registry](https://img.shields.io/badge/MCP%20Registry-active-2ea44f?logo=anthropic)](https://registry.modelcontextprotocol.io/v0/servers?search=cliwant)
@@ -50,7 +50,7 @@ The most comprehensive **keyless-first** MCP server for US federal contracting +
 |---|---|
 | GovWin: $30K-$100K/yr per seat | Free, MIT license |
 | API key registration → wait 24h → quota tier shopping | `npm install` → working in 60s |
-| 5+ separate vendor APIs / scrapers | 1 unified surface, 143 tools across 48 sources |
+| 5+ separate vendor APIs / scrapers | 1 unified surface, 144 tools across 48 sources |
 | LLMs hallucinate NAICS codes / agency names | Anti-hallucination autocomplete guards built-in |
 | Brittle scraping breaks weekly | Daily live smoke test ([badge above](#)) |
 | Procurement officer → IT ticket → 3-week wait | Claude Desktop double-click install |
@@ -79,7 +79,7 @@ The federal data this wraps is **public domain**. There is no good reason it sho
 | 🌐 **Trade, geo & disaster** | "HTS tariff for this product; Census tract for this address; FEMA declarations in this state" | USITC HTS, US Census, FEMA, Socrata, CKAN |
 | 🎓 **Grants & datasets** | "Cybersecurity grants posted in the last 30 days; discover federal open datasets" | Grants.gov, data.gov |
 
-**143 tools across 48 federal data sources — keyless-first: only 4 sources (Census business-patterns, FRED, BEA, and DOL's data endpoint) need a free key; the other 44 need none.** (An earlier 52-tool build measured roughly p50 ~0.25s / p95 ~0.8s against production federal APIs; latency varies by source and upstream load — treat it as fast, not a benchmarked guarantee.)
+**144 tools across 48 federal data sources — keyless-first: only 4 sources (Census business-patterns, FRED, BEA, and DOL's data endpoint) need a free key; the other 44 need none.** (An earlier 52-tool build measured roughly p50 ~0.25s / p95 ~0.8s against production federal APIs; latency varies by source and upstream load — treat it as fast, not a benchmarked guarantee.)
 
 ---
 
@@ -106,7 +106,7 @@ If you already use Claude Code (the CLI):
 /plugin install cliwant/mcp-sam-gov
 ```
 
-This installs the MCP server **plus** a [SKILL.md](./skills/sam-gov/SKILL.md) workflow guide that teaches Claude when + how to use each of the 143 tools.
+This installs the MCP server **plus** a [SKILL.md](./skills/sam-gov/SKILL.md) workflow guide that teaches Claude when + how to use each of the 144 tools.
 
 ### 🔵 Path 3 — Manual install for any MCP host (Codex, Cursor, Continue, Gemini)
 
@@ -174,7 +174,7 @@ Then point your host config at the absolute path:
 
 (Or skip this entirely — use Path 1's `.mcpb` and it auto-configures.)
 
-Restart Claude Desktop fully (system tray quit on Windows / Quit menu on macOS), then look for the 🔨 icon. You should see "sam-gov (143 tools)".
+Restart Claude Desktop fully (system tray quit on Windows / Quit menu on macOS), then look for the 🔨 icon. You should see "sam-gov (144 tools)".
 
 ### Claude Code
 
@@ -399,7 +399,7 @@ This server is built to **improve from real usage**. Because an AI agent (not a
 
 You can also open one directly: [**New issue**](https://github.com/cliwant/mcp-sam-gov/issues/new/choose) — bug / feature / wrong-output templates.
 
-## Tool catalog (143 tools)
+## Tool catalog (144 tools)
 
 Grouped by workflow. Keyless-first — most tools need no key; Census business-patterns, FRED, BEA, and DOL's data endpoint require a free key, and a handful of others gain higher limits from an optional free key (noted above). Descriptions are condensed — each tool's own `inputSchema` carries the full contract and honesty caveats.
 
@@ -522,7 +522,8 @@ Grouped by workflow. Keyless-first — most tools need no key; Census business-p
 - `regulations_search_documents` — search Regulations.gov rulemaking documents (rules, proposed rules, notices)
 - `regulations_search_comments` — search public comments on rulemakings
 - `regulations_get_docket` — fetch one Regulations.gov docket by id
-- `ecfr_search` — full-text search across the entire CFR (titleNumber=48 for FAR)
+- `ecfr_search` — full-text search across the entire CFR (titleNumber=48 for FAR); returns ranked snippets + ecfrUrl
+- `ecfr_get_section` — the FULL text of one CFR section by citation (any title; for FAR/DFARS prefer `far_clause_lookup`)
 - `ecfr_list_titles` — all 50 CFR titles + last-amended dates
 - `far_clause_lookup` — authoritative FAR/DFARS clause text + its prescription (exact clause number)
 - `far_search` — FAR/DFARS-scoped search (excludes GSAM, collapses to current in-force version)

package/dist/arcgis-feature.d.ts

@@ -0,0 +1,68 @@
+/**
+ * arcgis-feature.ts — generic ArcGIS REST FeatureServer/MapServer layer query
+ * over a CURATED service allowlist (loop — SLED bid campaign, 2026-07-19).
+ *
+ * WHAT IT ADDS: an enormous amount of US government data (esp. SLED procurement /
+ * GIS / infrastructure) is published as ArcGIS REST feature layers. This is the
+ * QUERY companion to `arcgis_hub_discover_datasets` (which DISCOVERS Hub datasets):
+ * it queries the ROWS of a curated set of high-value ArcGIS layers. First payload:
+ * the DC OCP "PASS" procurement layers (solicitations / contracts / purchase
+ * orders / payments) — DC's live open-solicitation feed with 46 fields, keyless.
+ *
+ * The module REUSES `getJson` (redirect:"error") / `driftError` / `num`·`str` /
+ * `withMeta`·`buildMeta`, mirroring socrata.ts (curated allowlist) + datagov-
+ * catalog.ts. KEYLESS.
+ *
+ * ★ SSRF: the caller supplies a `service` ENUM key (never a free host/URL); each
+ *   allowlist entry is a FIXED, live-verified ArcGIS layer base URL. The query
+ *   URL is built on that fixed base, and a post-construction assertion requires
+ *   the built hostname === the allowlist entry's host (over https) BEFORE the
+ *   fetch; `redirect:"error"`. `where`/`outFields`/`orderByFields` ride in
+ *   URLSearchParams (encoded) — they filter/project the read-only layer and
+ *   CANNOT alter the host (a malformed `where` ⇒ upstream 400 ⇒ invalid_input,
+ *   surfaced, never silent). Adding a service later = an allowlist SOURCE edit +
+ *   a live count/`/query` verification — NEVER a free runtime param.
+ *
+ * ★ HONESTY PILLARS (captured live 2026-07-19):
+ *   P1: totalAvailable = the layer's EXACT match count (a `returnCountOnly=true`
+ *     companion query), NEVER the page length. Best-effort: a count failure ⇒
+ *     totalAvailable:null + a note (the rows are still returned) — never a fake
+ *     total. `exceededTransferLimit` also forces hasMore.
+ *   P2: getJson THROWS on 429/5xx/timeout; an ArcGIS `{error:{code,message}}`
+ *     body (HTTP 200) is classified (400 ⇒ invalid_input, else upstream) and
+ *     THROWN — never a fake empty. A genuine no-match (features:[], count:0) ⇒
+ *     honest empty.
+ *   P3: attributes pass through VERBATIM (they are the layer's own record). NOTE
+ *     (disclosed every response): ArcGIS date fields are epoch MILLISECONDS and a
+ *     negative/sentinel value (e.g. -2209093200000 ≈ year 1900) is a placeholder,
+ *     not a real date — surfaced verbatim, never coerced.
+ *   P4: `body.features` absent/non-array (and no error) ⇒ driftError; a 200
+ *     non-JSON body ⇒ schema_drift via the catch-ladder.
+ */
+import { num } from "./coerce.js";
+import { type MetaBundle } from "./meta.js";
+export { num };
+export type ArcgisService = {
+    key: string;
+    base: string;
+    label: string;
+    note: string;
+};
+export declare const ARCGIS_SERVICES: readonly ArcgisService[];
+export type ArcgisFeatureQueryArgs = {
+    service: string;
+    where?: string;
+    outFields?: string;
+    orderByFields?: string;
+    limit?: number;
+    offset?: number;
+};
+/**
+ * Query rows from a curated ArcGIS REST feature layer. `service` is an allowlist
+ * enum; `where` (SQL-ish filter, default 1=1), `outFields` (default *),
+ * `orderByFields`, `limit`/`offset`. Returns curated record attributes + honest
+ * `_meta` (totalAvailable = the layer's exact match count via a returnCountOnly
+ * companion; epoch-ms date disclosure).
+ */
+export declare function featureQuery(args: ArcgisFeatureQueryArgs): Promise<MetaBundle>;
+//# sourceMappingURL=arcgis-feature.d.ts.map

package/dist/arcgis-feature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arcgis-feature.d.ts","sourceRoot":"","sources":["../src/arcgis-feature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAIH,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAEzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAMf,MAAM,MAAM,aAAa,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AACvF,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EA2B1C,CAAC;AAmDX,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,CAmFpF"}

package/dist/arcgis-feature.js

@@ -0,0 +1,206 @@
+/**
+ * arcgis-feature.ts — generic ArcGIS REST FeatureServer/MapServer layer query
+ * over a CURATED service allowlist (loop — SLED bid campaign, 2026-07-19).
+ *
+ * WHAT IT ADDS: an enormous amount of US government data (esp. SLED procurement /
+ * GIS / infrastructure) is published as ArcGIS REST feature layers. This is the
+ * QUERY companion to `arcgis_hub_discover_datasets` (which DISCOVERS Hub datasets):
+ * it queries the ROWS of a curated set of high-value ArcGIS layers. First payload:
+ * the DC OCP "PASS" procurement layers (solicitations / contracts / purchase
+ * orders / payments) — DC's live open-solicitation feed with 46 fields, keyless.
+ *
+ * The module REUSES `getJson` (redirect:"error") / `driftError` / `num`·`str` /
+ * `withMeta`·`buildMeta`, mirroring socrata.ts (curated allowlist) + datagov-
+ * catalog.ts. KEYLESS.
+ *
+ * ★ SSRF: the caller supplies a `service` ENUM key (never a free host/URL); each
+ *   allowlist entry is a FIXED, live-verified ArcGIS layer base URL. The query
+ *   URL is built on that fixed base, and a post-construction assertion requires
+ *   the built hostname === the allowlist entry's host (over https) BEFORE the
+ *   fetch; `redirect:"error"`. `where`/`outFields`/`orderByFields` ride in
+ *   URLSearchParams (encoded) — they filter/project the read-only layer and
+ *   CANNOT alter the host (a malformed `where` ⇒ upstream 400 ⇒ invalid_input,
+ *   surfaced, never silent). Adding a service later = an allowlist SOURCE edit +
+ *   a live count/`/query` verification — NEVER a free runtime param.
+ *
+ * ★ HONESTY PILLARS (captured live 2026-07-19):
+ *   P1: totalAvailable = the layer's EXACT match count (a `returnCountOnly=true`
+ *     companion query), NEVER the page length. Best-effort: a count failure ⇒
+ *     totalAvailable:null + a note (the rows are still returned) — never a fake
+ *     total. `exceededTransferLimit` also forces hasMore.
+ *   P2: getJson THROWS on 429/5xx/timeout; an ArcGIS `{error:{code,message}}`
+ *     body (HTTP 200) is classified (400 ⇒ invalid_input, else upstream) and
+ *     THROWN — never a fake empty. A genuine no-match (features:[], count:0) ⇒
+ *     honest empty.
+ *   P3: attributes pass through VERBATIM (they are the layer's own record). NOTE
+ *     (disclosed every response): ArcGIS date fields are epoch MILLISECONDS and a
+ *     negative/sentinel value (e.g. -2209093200000 ≈ year 1900) is a placeholder,
+ *     not a real date — surfaced verbatim, never coerced.
+ *   P4: `body.features` absent/non-array (and no error) ⇒ driftError; a 200
+ *     non-JSON body ⇒ schema_drift via the catch-ladder.
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { num } from "./coerce.js";
+import { withMeta } from "./meta.js";
+export { num };
+export const ARCGIS_SERVICES = [
+    { key: "dc_pass_solicitations", base: "https://maps2.dcgis.dc.gov/dcgis/rest/services/DCGIS_DATA/Government_Operations/MapServer/19", label: "DC OCP PASS — Solicitations", note: "DC Office of Contracting & Procurement live solicitations (SOLICITATIONNUMBER, SOLICITATIONTITLE, DUE_DATE, OPENDATE, CLOSEDATE, NIGPCODE, CONTRACTINGOFFICER, AWARD_TO…). ~25k." },
+    { key: "dc_pass_contracts", base: "https://maps2.dcgis.dc.gov/dcgis/rest/services/DCGIS_DATA/Government_Operations/MapServer/37", label: "DC OCP PASS — Contracts", note: "DC awarded contracts. ~50k." },
+    { key: "dc_pass_purchase_orders", base: "https://maps2.dcgis.dc.gov/dcgis/rest/services/DCGIS_DATA/Government_Operations/MapServer/16", label: "DC OCP PASS — Purchase Orders", note: "DC purchase orders. ~275k." },
+    { key: "dc_pass_payments", base: "https://maps2.dcgis.dc.gov/dcgis/rest/services/DCGIS_DATA/Government_Operations/MapServer/17", label: "DC OCP PASS — Payments", note: "DC vendor payments. ~1.55M." },
+    // ── Additional US local-gov procurement layers (loop, 2026-07-19) — found via
+    //    arcgis_hub_discover_datasets, each on a reachable Esri-hosted services*.
+    //    arcgis.com endpoint (NOT WAF-gated) + live-verified returnCountOnly. ──
+    { key: "asheville_purchase_orders", base: "https://services.arcgis.com/aJ16ENn1AaqdFlqx/ArcGIS/rest/services/Financials/FeatureServer/9", label: "Asheville NC — Purchase Order Line Items", note: "City of Asheville NC purchase-order line items. ~62.8k." },
+    { key: "asheville_po_summary", base: "https://services.arcgis.com/aJ16ENn1AaqdFlqx/ArcGIS/rest/services/Financials/FeatureServer/8", label: "Asheville NC — Purchase Order Summary", note: "City of Asheville NC purchase-order summary. ~18.7k." },
+    { key: "bellevue_vendor_payments", base: "https://services1.arcgis.com/EYzEZbDhXZjURPbP/arcgis/rest/services/YTD_Vendor_Payments/FeatureServer/0", label: "Bellevue WA — YTD Vendor Payments", note: "City of Bellevue WA year-to-date vendor payments. ~15.8k." },
+    { key: "bellevue_awarded_contracts", base: "https://services1.arcgis.com/EYzEZbDhXZjURPbP/arcgis/rest/services/Annual_Awarded_Contracts/FeatureServer/0", label: "Bellevue WA — Annual Awarded Contracts", note: "City of Bellevue WA annual awarded contracts. ~2.0k." },
+    { key: "miamidade_purchase_orders_2017", base: "https://services.arcgis.com/8Pc9XBTAsYuxx9Ny/arcgis/rest/services/miamidade_procurement_data_2017/FeatureServer/0", label: "Miami-Dade County FL — Purchase Orders (ADPICS) 2017", note: "Miami-Dade County FL purchase orders — a 2017 snapshot (historical, disclosed). ~94.8k." },
+    { key: "miamidade_purchase_orders_2025", base: "https://services.arcgis.com/8Pc9XBTAsYuxx9Ny/arcgis/rest/services/miamidade_procurement_data_informs_2025/FeatureServer/0", label: "Miami-Dade County FL — Purchase Orders (INFORMS) 2025", note: "Miami-Dade County FL purchase orders — CURRENT (2025 INFORMS). ~25k." },
+    { key: "suffolk_county_ny_contracts_2018", base: "https://services.arcgis.com/JsDD4qdG5r2a7hR5/arcgis/rest/services/County_Contracts_2018/FeatureServer/0", label: "Suffolk County NY — County Contracts 2018", note: "Suffolk County NY contracts — a 2018 snapshot (historical, disclosed). ~1.4k." },
+    { key: "matsu_borough_ak_checkbook", base: "https://services.arcgis.com/fX5IGselyy1TirdY/arcgis/rest/services/Logos_Checkbook_Data/FeatureServer/0", label: "Matanuska-Susitna Borough AK — Checkbook", note: "Matanuska-Susitna Borough AK checkbook (vendor spend). ~1.2k." },
+    { key: "lasvegas_checkbook", base: "https://services1.arcgis.com/F1v0ufATbBQScMtY/arcgis/rest/services/Processed_Checkbook_Table_View/FeatureServer/0", label: "City of Las Vegas NV — Open Checkbook", note: "City of Las Vegas NV checkbook (DEPARTMENT/VENDOR/TRANSACTION_AMOUNT/TRANSACTION_DATE). ~373k." },
+    { key: "baltimore_checkbook", base: "https://services1.arcgis.com/UWYHeuuJISiGmgXx/arcgis/rest/services/OpenCheckbookFY2022_Through_Present/FeatureServer/0", label: "Baltimore City MD — Open Checkbook (FY2022–present)", note: "Baltimore City MD checkbook, FY2022 through present (Supplier_Name/Payment_Amount/Supplier_Contract_Number/Agency). ~367k." },
+    { key: "naperville_vendor_payments", base: "https://services1.arcgis.com/rXJ6QApc2sOtl1Pd/arcgis/rest/services/Expenditures_2018_to_Current_Year/FeatureServer/0", label: "City of Naperville IL — Vendor Payments (2018–current)", note: "City of Naperville IL vendor payments, 2018 to current year (Vendor_Name/Payment_Amount/Purch_Order_No/Check_Date). ~127k." },
+    { key: "worcester_ma_checkbook_fy25", base: "https://services1.arcgis.com/j8dqo2DJE7mVUBU1/arcgis/rest/services/Fiscal_Year_2025_Open_Checkbook/FeatureServer/0", label: "City of Worcester MA — Open Checkbook FY2025", note: "City of Worcester MA open checkbook, FY2025 (Payee/Pmt_Amount/Departments/Spend_Categories/Pmt_Date). ~38k." },
+    { key: "lasvegas_purchasing_contracts", base: "https://services1.arcgis.com/F1v0ufATbBQScMtY/arcgis/rest/services/Purchasing_Contracts__view/FeatureServer/0", label: "City of Las Vegas NV — Purchasing Contracts", note: "City of Las Vegas NV purchasing contract register (Project_Number/Project_Name/Supplier_Name/Award_Date/Termination_Date). ~3.4k, all with a supplier. Complements lasvegas_checkbook (payments)." },
+    { key: "txdot_construction_projects", base: "https://services.arcgis.com/KTcxiTD9dsQw4r7Z/arcgis/rest/services/TxDOT_Projects_Info_All/FeatureServer/0", label: "Texas DOT — Projects (with awarded construction company)", note: "Texas Department of Transportation highway projects (CNSTR_CMPNY_NM awarded construction company/CNSTR_NTPD_DT notice-to-proceed/TYPE_OF_WORK/HWY_NBR). ~85k rows, ~14.1k with an awarded contractor (filter CNSTR_CMPNY_NM IS NOT NULL for awards)." },
+    { key: "akdot_construction_awards", base: "https://services.arcgis.com/r4A0V7UzH9fcLVvv/arcgis/rest/services/AWARDS_DASHBOARD_AWARDS_TABLE_POINTS/FeatureServer/0", label: "Alaska DOT&PF — Construction Bid Awards", note: "Alaska Department of Transportation & Public Facilities construction bid awards (ContractID/Contractor/Bids_Received/Engineer_Est/Award_Amount/Advertised_Date/Bid_Opening_Date/Reg_Award_Date/DOT_Region). ~1.1k." },
+    { key: "akdot_aashtoware_proposals", base: "https://services.arcgis.com/r4A0V7UzH9fcLVvv/arcgis/rest/services/AASHTOWARE_Proposals_Points/FeatureServer/0", label: "Alaska DOT&PF — AASHTOWARE Proposals/Lettings", note: "Alaska DOT&PF AASHTOWARE proposals & lettings with awarded vendor (ProposalId/LettingId/StateProjectNumber/RefVendor_LongName/RefVendor_DBECertStatus/AwardedAmount/Contract_ID/FundType). ~1k, ~1,035 with an AwardedAmount>0. Complements akdot_construction_awards." },
+    { key: "iowadot_public_bid_awards", base: "https://services.arcgis.com/8lRhdTsQyJpO52F1/arcgis/rest/services/Project_Scheduling_Public_Bid_Point_View/FeatureServer/0", label: "Iowa DOT — Public Bid / Project Scheduling", note: "Iowa Department of Transportation public bid & project scheduling (PROJECT_NUMBER/WORK_DESC/LETTING_FISCAL_YEAR/PROGRAM_ESTIMATE/CONTRACT_AWARDED/AWARDED/FINAL_CONTRACT/CONTRACTOR/CONTRACT_ID/STATUS). ~360." },
+    { key: "okdot_cirb_contract_status", base: "https://services6.arcgis.com/RBtoEUQ2lmN0K3GY/arcgis/rest/services/CIRB_Project_Status/FeatureServer/0", label: "Oklahoma DOT — CIRB Contract Status", note: "Oklahoma Department of Transportation County Improvements for Roads & Bridges (CIRB) contract status (T_PROJECT/JP_DESCRIPTION/A_CONTRACT_AMOUNT/A_AMOUNT_EARNED/A_AMOUNT_PAID/D_LET_DATE/D_CONTRACT_AWARD_DATE/D_WORK_ORDER_DATE). ~780." },
+    { key: "topeka_checkbook_aggregate", base: "https://services1.arcgis.com/EvtgI3PZ9PyCGJZS/arcgis/rest/services/Checkbook_Aggregate/FeatureServer/0", label: "City of Topeka KS — Open Checkbook (aggregate FY2015–2023)", note: "City of Topeka KS open checkbook, all years aggregated FY2015–2023 (fiscal_year/fiscal_period/department/program/fund/vendor_name/description/dollars). ~332k rows, ~323.6k with dollars>0." },
+];
+const SERVICE_BY_KEY = new Map(ARCGIS_SERVICES.map((s) => [s.key, s]));
+const DATE_NOTE = "ArcGIS date fields are epoch MILLISECONDS (e.g. DUE_DATE, OPENDATE, CLOSEDATE); a negative/sentinel value (≈ year 1900) is a placeholder, not a real date — surfaced verbatim, parse client-side.";
+// ─── SSRF-guarded fetch (fixed allowlist base + hostname assertion) ──
+async function getArcgisQuery(svc, params) {
+    const url = `${svc.base}/query?${params.toString()}`;
+    const allowedHost = new URL(svc.base).hostname;
+    const built = new URL(url);
+    if (built.hostname !== allowedHost || built.protocol !== "https:") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Constructed ArcGIS URL host ${JSON.stringify(built.hostname)} (${built.protocol}) does not match the allowlisted service host ${JSON.stringify(allowedHost)} over https — refusing to fetch (SSRF safety).`,
+            retryable: false,
+            upstreamEndpoint: `arcgis:${svc.key}`,
+        });
+    }
+    return getJson(url, { label: `arcgis:${svc.key}`, redirect: "error" });
+}
+// ArcGIS returns HTTP 200 + `{error:{code,message}}` for BOTH a bad query AND a
+// transient server hiccup, and the messages OVERLAP (live-verified 2026-07-19):
+//   - "Failed to execute query." ⇒ a bad column/field/where (the caller's query).
+//   - "Unable to complete operation." ⇒ AMBIGUOUS — a bad SQL syntax OR a transient
+//     server blip (observed intermittently on a valid query).
+// So classify a clearly-input message as invalid_input (non-retryable), but treat
+// the ambiguous/generic one as upstream_unavailable (RETRYABLE) — misclassifying a
+// server blip as invalid_input would falsely blame the caller for an outage.
+const ARCGIS_INPUT_ERROR_RE = /failed to execute query|invalid|parameter|field|syntax|parse|not supported|does not exist|cannot find|out of range/i;
+/** An ArcGIS `{error:{code,message}}` body (HTTP 200) ⇒ throw the right kind. */
+function throwIfArcgisError(svc, body) {
+    const e = body?.error;
+    if (e && typeof e === "object") {
+        const code = num(e.code);
+        const msg = String(e.message ?? "ArcGIS query error");
+        const inputish = code === 400 && ARCGIS_INPUT_ERROR_RE.test(msg);
+        throw new ToolErrorCarrier({
+            kind: inputish ? "invalid_input" : "upstream_unavailable",
+            message: `ArcGIS ${svc.key} error${code !== null ? ` (${code})` : ""}: ${msg}`.slice(0, 300),
+            retryable: !inputish,
+            upstreamEndpoint: `arcgis:${svc.key}`,
+        });
+    }
+}
+/**
+ * Query rows from a curated ArcGIS REST feature layer. `service` is an allowlist
+ * enum; `where` (SQL-ish filter, default 1=1), `outFields` (default *),
+ * `orderByFields`, `limit`/`offset`. Returns curated record attributes + honest
+ * `_meta` (totalAvailable = the layer's exact match count via a returnCountOnly
+ * companion; epoch-ms date disclosure).
+ */
+export async function featureQuery(args) {
+    const svc = SERVICE_BY_KEY.get(args.service);
+    if (!svc) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            message: `Unknown ArcGIS service ${JSON.stringify(args.service)}. Allowed: ${ARCGIS_SERVICES.map((s) => s.key).join(", ")}.`,
+            retryable: false,
+        });
+    }
+    const limit = args.limit ?? 50;
+    const offset = args.offset ?? 0;
+    const where = args.where && args.where.trim() ? args.where.trim() : "1=1";
+    const outFields = args.outFields && args.outFields.trim() ? args.outFields.trim() : "*";
+    const filtersApplied = ["service"];
+    if (args.where && args.where.trim())
+        filtersApplied.push("where");
+    // ── Primary rows query. ──
+    const rowParams = new URLSearchParams();
+    rowParams.set("where", where);
+    rowParams.set("outFields", outFields);
+    rowParams.set("returnGeometry", "false");
+    rowParams.set("resultOffset", String(offset));
+    rowParams.set("resultRecordCount", String(limit));
+    if (args.orderByFields && args.orderByFields.trim())
+        rowParams.set("orderByFields", args.orderByFields.trim());
+    rowParams.set("f", "json");
+    let body;
+    try {
+        body = await getArcgisQuery(svc, rowParams);
+    }
+    catch (e) {
+        if (e instanceof ToolErrorCarrier)
+            throw e;
+        if (e instanceof SyntaxError)
+            throw driftError(`arcgis:${svc.key}`, "ArcGIS returned a non-JSON body at HTTP 200 — schema drift.");
+        throw e;
+    }
+    throwIfArcgisError(svc, body); // P2: a 200 {error} body ⇒ throw (never a fake empty)
+    const b = (body ?? {});
+    // P4: features MUST be an array (a missing/non-array, with no error, is drift).
+    if (!Array.isArray(b.features)) {
+        throw driftError(`arcgis:${svc.key}`, "ArcGIS shape drift — response.features must be an array.");
+    }
+    const records = b.features.map((f) => f?.attributes ?? {});
+    const returned = records.length;
+    // ── P1: totalAvailable = the layer's exact match count (returnCountOnly
+    //    companion). BEST-EFFORT: any count failure ⇒ null + note (rows kept). ──
+    let totalAvailable = null;
+    let countNote = null;
+    try {
+        const countParams = new URLSearchParams();
+        countParams.set("where", where);
+        countParams.set("returnCountOnly", "true");
+        countParams.set("f", "json");
+        const cbody = await getArcgisQuery(svc, countParams);
+        throwIfArcgisError(svc, cbody);
+        const c = num(cbody?.count);
+        if (c !== null)
+            totalAvailable = c;
+        else
+            countNote = "The returnCountOnly companion returned an unexpected shape — totalAvailable is unknown (null); the rows are still complete.";
+    }
+    catch {
+        countNote = "The returnCountOnly companion failed (transient) — totalAvailable is unknown (null); the rows are still returned.";
+    }
+    const exceeded = b.exceededTransferLimit === true;
+    const hasMore = totalAvailable !== null ? offset + returned < totalAvailable : (exceeded || returned >= limit);
+    const nextOffset = hasMore ? offset + returned : null;
+    const notes = [`Source: ${svc.label} (ArcGIS REST feature layer, keyless). ${svc.note}`, DATE_NOTE];
+    if (countNote)
+        notes.push(countNote);
+    return withMeta({ service: svc.key, records }, {
+        source: `${new URL(svc.base).hostname} via ArcGIS REST (keyless)`,
+        keylessMode: true,
+        returned,
+        totalAvailable,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit, hasMore, nextOffset },
+        notes,
+    });
+}
+//# sourceMappingURL=arcgis-feature.js.map

package/dist/arcgis-feature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arcgis-feature.js","sourceRoot":"","sources":["../src/arcgis-feature.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAsC,MAAM,WAAW,CAAC;AAEzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAOf,MAAM,CAAC,MAAM,eAAe,GAA6B;IACvD,EAAE,GAAG,EAAE,uBAAuB,EAAE,IAAI,EAAE,8FAA8F,EAAE,KAAK,EAAE,6BAA6B,EAAE,IAAI,EAAE,kLAAkL,EAAE;IACtW,EAAE,GAAG,EAAE,mBAAmB,EAAE,IAAI,EAAE,8FAA8F,EAAE,KAAK,EAAE,yBAAyB,EAAE,IAAI,EAAE,6BAA6B,EAAE;IACzM,EAAE,GAAG,EAAE,yBAAyB,EAAE,IAAI,EAAE,8FAA8F,EAAE,KAAK,EAAE,+BAA+B,EAAE,IAAI,EAAE,4BAA4B,EAAE;IACpN,EAAE,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,8FAA8F,EAAE,KAAK,EAAE,wBAAwB,EAAE,IAAI,EAAE,6BAA6B,EAAE;IACvM,+EAA+E;IAC/E,8EAA8E;IAC9E,6EAA6E;IAC7E,EAAE,GAAG,EAAE,2BAA2B,EAAE,IAAI,EAAE,8FAA8F,EAAE,KAAK,EAAE,0CAA0C,EAAE,IAAI,EAAE,yDAAyD,EAAE;IAC9P,EAAE,GAAG,EAAE,sBAAsB,EAAE,IAAI,EAAE,8FAA8F,EAAE,KAAK,EAAE,uCAAuC,EAAE,IAAI,EAAE,sDAAsD,EAAE;IACnP,EAAE,GAAG,EAAE,0BAA0B,EAAE,IAAI,EAAE,wGAAwG,EAAE,KAAK,EAAE,mCAAmC,EAAE,IAAI,EAAE,2DAA2D,EAAE;IAClQ,EAAE,GAAG,EAAE,4BAA4B,EAAE,IAAI,EAAE,6GAA6G,EAAE,KAAK,EAAE,wCAAwC,EAAE,IAAI,EAAE,sDAAsD,EAAE;IACzQ,EAAE,GAAG,EAAE,gCAAgC,EAAE,IAAI,EAAE,mHAAmH,EAAE,KAAK,EAAE,sDAAsD,EAAE,IAAI,EAAE,yFAAyF,EAAE;IACpU,EAAE,GAAG,EAAE,gCAAgC,EAAE,IAAI,EAAE,2HAA2H,EAAE,KAAK,EAAE,uDAAuD,EAAE,IAAI,EAAE,sEAAsE,EAAE;IAC1T,EAAE,GAAG,EAAE,kCAAkC,EAAE,IAAI,EAAE,yGAAyG,EAAE,KAAK,EAAE,2CAA2C,EAAE,IAAI,EAAE,+EAA+E,EAAE;IACvS,EAAE,GAAG,EAAE,4BAA4B,EAAE,IAAI,EAAE,wGAAwG,EAAE,KAAK,EAAE,0CAA0C,EAAE,IAAI,EAAE,+DAA+D,EAAE;IAC/Q,EAAE,GAAG,EAAE,oBAAoB,EAAE,IAAI,EAAE,mHAAmH,EAAE,KAAK,EAAE,uCAAuC,EAAE,IAAI,EAAE,gGAAgG,EAAE;IAChT,EAAE,GAAG,EAAE,qBAAqB,EAAE,IAAI,EAAE,wHAAwH,EAAE,KAAK,EAAE,qDAAqD,EAAE,IAAI,EAAE,4HAA4H,EAAE;IAChW,EAAE,GAAG,EAAE,4BAA4B,EAAE,IAAI,EAAE,sHAAsH,EAAE,KAAK,EAAE,wDAAwD,EAAE,IAAI,EAAE,4HAA4H,EAAE;IACxW,EAAE,GAAG,EAAE,6BAA6B,EAAE,IAAI,EAAE,oHAAoH,EAAE,KAAK,EAAE,8CAA8C,EAAE,IAAI,EAAE,6GAA6G,EAAE;IAC9U,EAAE,GAAG,EAAE,+BAA+B,EAAE,IAAI,EAAE,+GAA+G,EAAE,KAAK,EAAE,6CAA6C,EAAE,IAAI,EAAE,mMAAmM,EAAE;IACha,EAAE,GAAG,EAAE,6BAA6B,EAAE,IAAI,EAAE,2GAA2G,EAAE,KAAK,EAAE,0DAA0D,EAAE,IAAI,EAAE,sPAAsP,EAAE;IAC1d,EAAE,GAAG,EAAE,2BAA2B,EAAE,IAAI,EAAE,wHAAwH,EAAE,KAAK,EAAE,yCAAyC,EAAE,IAAI,EAAE,oNAAoN,EAAE;IAClb,EAAE,GAAG,EAAE,4BAA4B,EAAE,IAAI,EAAE,+GAA+G,EAAE,KAAK,EAAE,+CAA+C,EAAE,IAAI,EAAE,wQAAwQ,EAAE;IACpe,EAAE,GAAG,EAAE,2BAA2B,EAAE,IAAI,EAAE,4HAA4H,EAAE,KAAK,EAAE,4CAA4C,EAAE,IAAI,EAAE,gNAAgN,EAAE;IACrb,EAAE,GAAG,EAAE,4BAA4B,EAAE,IAAI,EAAE,wGAAwG,EAAE,KAAK,EAAE,qCAAqC,EAAE,IAAI,EAAE,2OAA2O,EAAE;IACtb,EAAE,GAAG,EAAE,4BAA4B,EAAE,IAAI,EAAE,wGAAwG,EAAE,KAAK,EAAE,4DAA4D,EAAE,IAAI,EAAE,6LAA6L,EAAE;CACvZ,CAAC;AAEX,MAAM,cAAc,GAAuC,IAAI,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAE3G,MAAM,SAAS,GACb,mMAAmM,CAAC;AAEtM,wEAAwE;AACxE,KAAK,UAAU,cAAc,CAAC,GAAkB,EAAE,MAAuB;IACvE,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,IAAI,UAAU,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;IACrD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,KAAK,CAAC,QAAQ,KAAK,WAAW,IAAI,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAClE,MAAM,IAAI,gBAAgB,CAAC;YACzB,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,+BAA+B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,KAAK,CAAC,QAAQ,iDAAiD,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,gDAAgD;YACrN,SAAS,EAAE,KAAK;YAChB,gBAAgB,EAAE,UAAU,GAAG,CAAC,GAAG,EAAE;SACtC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,UAAU,GAAG,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,gFAAgF;AAChF,gFAAgF;AAChF,kFAAkF;AAClF,oFAAoF;AACpF,8DAA8D;AAC9D,kFAAkF;AAClF,mFAAmF;AACnF,6EAA6E;AAC7E,MAAM,qBAAqB,GACzB,qHAAqH,CAAC;AAExH,iFAAiF;AACjF,SAAS,kBAAkB,CAAC,GAAkB,EAAE,IAAa;IAC3D,MAAM,CAAC,GAAI,IAAiE,EAAE,KAAK,CAAC;IACpF,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,GAAG,CAAE,CAAwB,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,GAAG,GAAG,MAAM,CAAE,CAA2B,CAAC,OAAO,IAAI,oBAAoB,CAAC,CAAC;QACjF,MAAM,QAAQ,GAAG,IAAI,KAAK,GAAG,IAAI,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,gBAAgB,CAAC;YACzB,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,sBAAsB;YACzD,OAAO,EAAE,UAAU,GAAG,CAAC,GAAG,SAAS,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;YAC5F,SAAS,EAAE,CAAC,QAAQ;YACpB,gBAAgB,EAAE,UAAU,GAAG,CAAC,GAAG,EAAE;SACtC,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAYD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAA4B;IAC7D,MAAM,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,gBAAgB,CAAC;YACzB,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,0BAA0B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC5H,SAAS,EAAE,KAAK;SACjB,CAAC,CAAC;IACL,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IAC1E,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;IACxF,MAAM,cAAc,GAAa,CAAC,SAAS,CAAC,CAAC;IAC7C,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE;QAAE,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAElE,4BAA4B;IAC5B,MAAM,SAAS,GAAG,IAAI,eAAe,EAAE,CAAC;IACxC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC9B,SAAS,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACtC,SAAS,CAAC,GAAG,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IACzC,SAAS,CAAC,GAAG,CAAC,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9C,SAAS,CAAC,GAAG,CAAC,mBAAmB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAClD,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE;QAAE,SAAS,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/G,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAE3B,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,gBAAgB;YAAE,MAAM,CAAC,CAAC;QAC3C,IAAI,CAAC,YAAY,WAAW;YAAE,MAAM,UAAU,CAAC,UAAU,GAAG,CAAC,GAAG,EAAE,EAAE,6DAA6D,CAAC,CAAC;QACnI,MAAM,CAAC,CAAC;IACV,CAAC;IACD,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,sDAAsD;IAErF,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAA4D,CAAC;IAClF,gFAAgF;IAChF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/B,MAAM,UAAU,CAAC,UAAU,GAAG,CAAC,GAAG,EAAE,EAAE,0DAA0D,CAAC,CAAC;IACpG,CAAC;IACD,MAAM,OAAO,GAAI,CAAC,CAAC,QAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAA8B,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC;IACxG,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IAEhC,yEAAyE;IACzE,8EAA8E;IAC9E,IAAI,cAAc,GAAkB,IAAI,CAAC;IACzC,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,IAAI,eAAe,EAAE,CAAC;QAC1C,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAChC,WAAW,CAAC,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;QAC3C,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QACrD,kBAAkB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC/B,MAAM,CAAC,GAAG,GAAG,CAAE,KAA6B,EAAE,KAAK,CAAC,CAAC;QACrD,IAAI,CAAC,KAAK,IAAI;YAAE,cAAc,GAAG,CAAC,CAAC;;YAC9B,SAAS,GAAG,6HAA6H,CAAC;IACjJ,CAAC;IAAC,MAAM,CAAC;QACP,SAAS,GAAG,mHAAmH,CAAC;IAClI,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,CAAC,qBAAqB,KAAK,IAAI,CAAC;IAClD,MAAM,OAAO,GAAG,cAAc,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,QAAQ,IAAI,KAAK,CAAC,CAAC;IAC/G,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAEtD,MAAM,KAAK,GAAa,CAAC,WAAW,GAAG,CAAC,KAAK,0CAA0C,GAAG,CAAC,IAAI,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9G,IAAI,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAErC,OAAO,QAAQ,CACb,EAAE,OAAO,EAAE,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,EAC7B;QACE,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,4BAA4B;QACjE,WAAW,EAAE,IAAI;QACjB,QAAQ;QACR,cAAc;QACd,cAAc;QACd,cAAc,EAAE,EAAE;QAClB,iBAAiB,EAAE,EAAE;QACrB,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE;QAClD,KAAK;KAC0B,CAClC,CAAC;AACJ,CAAC"}

package/dist/arcgis-hub.d.ts

@@ -0,0 +1,90 @@
+/**
+ * arcgis-hub.ts — ArcGIS Hub dataset DISCOVERY (`hub.arcgis.com/api/v3/datasets`),
+ * a NEW keyless-first SLED-discovery platform (loop cycle 9).
+ *
+ * WHAT IT ADDS: a large fraction of US state/local/regional/tribal (SLED) open
+ * data — especially GIS / infrastructure / permits / boundaries / procurement —
+ * is published on ArcGIS Hub, NOT on Socrata or CKAN. This tool DISCOVERS those
+ * datasets (keyword search over the whole Hub) so a B2G researcher can find what
+ * fragmented local data exists. It is the ArcGIS sibling of
+ * `socrata_discover_datasets` / `datagov_search_datasets`.
+ *
+ * The module writes ZERO fetch/coercion/error/meta code — it REUSES `getJson`
+ * (redirect:"error") / `driftError` / `num`·`str` (coerce.ts, null-never-0 /
+ * null-never-empty-string) / `withMeta`·`buildMeta`, mirroring datagov-catalog.ts.
+ * KEYLESS: no key seam (no token is ever read/sent).
+ *
+ * ★ SSRF: the host is a compile-time literal (`ARCGIS_HUB_HOST`). Every input
+ *   (`q` / `filter[openData]` / `page[size]` / `page[start]`) rides in a
+ *   MODULE-BUILT `URLSearchParams` assembled key-by-key from validated typed args
+ *   — NO raw-query / raw-host passthrough (this is a FIXED-host catalog search, so
+ *   there is no per-jurisdiction host vector like socrata_query has). A
+ *   post-construction hostname/protocol assertion + `redirect:"error"` lock it.
+ *
+ * ★ PROVENANCE (the crux — different trust posture from our other sources): ArcGIS
+ *   Hub is a GLOBAL, OPEN publishing platform. Anyone — a US city, a foreign
+ *   government, an NGO, a company — can publish, so results are NOT all US and NOT
+ *   all governmental. This tool is therefore explicitly a DISCOVERY aid, NOT a
+ *   curated official-source allowlist (unlike `socrata_query`, whose hosts are a
+ *   vetted allowlist). Each result surfaces `owner`/`orgName`/`source`/`region`
+ *   VERBATIM so the consumer can VET the publisher, and every response carries the
+ *   global-platform disclosure. `openDataOnly` (default true) biases toward items
+ *   the publisher designated as open data. DISCOVERY ONLY — to read rows, follow
+ *   the dataset on its own ArcGIS endpoint (a guarded row-query tool is a planned
+ *   addition; ArcGIS feature services live on arbitrary hosts, which needs its own
+ *   SSRF design).
+ *
+ * ★ HONESTY PILLARS (captured live 2026-07-19):
+ *   P1 (real total): the v3 response carries `meta.total` (== `meta.stats.totalCount`)
+ *     — the EXACT match count across the Hub. `totalAvailable = num(meta.total)`
+ *     (NEVER data.length); a page is `truncated` when `offset + returned < total`.
+ *     Pagination is a 1-based record offset (`page[start] = offset + 1`).
+ *   P2: getJson→fetchWithRetry THROWS on 429 (rate_limited) / 5xx
+ *     (upstream_unavailable) / timeout — NEVER a fake empty. A genuine no-match
+ *     (`data:[]`, total 0) ⇒ honest empty (datasets:[], returned:0, total:0,
+ *     complete:true).
+ *   P3: every scalar via `str` (null-never-empty) / booleans preserved / `num`
+ *     for counts (null-never-0). A missing owner/source/region is null, never "".
+ *   P4: `body.data` absent/non-array ⇒ driftError; a 200 non-JSON body ⇒
+ *     schema_drift via the catch-ladder (ToolErrorCarrier rethrow FIRST so a
+ *     429/5xx keeps its taxonomy → SyntaxError→driftError → bare rethrow).
+ */
+import { num } from "./coerce.js";
+import { type MetaBundle } from "./meta.js";
+export { num };
+export declare const ARCGIS_HUB_HOST = "hub.arcgis.com";
+export type HubDataset = {
+    id: string | null;
+    name: string | null;
+    description: string | null;
+    owner: string | null;
+    orgName: string | null;
+    source: string | null;
+    region: string | null;
+    type: string | null;
+    sector: string | null;
+    keywords: string[];
+    downloadable: boolean | null;
+    hasApi: boolean | null;
+    created: string | null;
+    modified: string | null;
+    landingPage: string | null;
+    itemId: string | null;
+};
+export type ArcgisHubDiscoverArgs = {
+    query: string;
+    openDataOnly?: boolean;
+    limit?: number;
+    offset?: number;
+};
+/**
+ * Search ArcGIS Hub datasets by keyword. Filters: `query` (→q, REQUIRED, ≥2
+ * non-whitespace chars), `openDataOnly` (default true → filter[openData]=true,
+ * biases toward publisher-designated open data), `limit` (→page[size]), `offset`
+ * (→page[start]=offset+1, 1-based). The query is MODULE-BUILT from validated typed
+ * args (NO raw passthrough). Returns curated dataset rows + honest `_meta`:
+ * totalAvailable = the EXACT Hub match count (meta.total, P1), the global-platform
+ * provenance disclosure, and per-row publisher fields for vetting.
+ */
+export declare function discoverDatasets(args: ArcgisHubDiscoverArgs): Promise<MetaBundle>;
+//# sourceMappingURL=arcgis-hub.d.ts.map

package/dist/arcgis-hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arcgis-hub.d.ts","sourceRoot":"","sources":["../src/arcgis-hub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAIH,OAAO,EAAE,GAAG,EAAO,MAAM,aAAa,CAAC;AACvC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAIzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAGf,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAahD,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAkEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,UAAU,CAAC,CA6FrB"}