@cliwant/mcp-sam-gov 1.2.0 → 1.4.0
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/README.ja.md +22 -9
- package/README.ko.md +22 -9
- package/README.md +70 -12
- package/dist/bea.d.ts +105 -0
- package/dist/bea.d.ts.map +1 -0
- package/dist/bea.js +303 -0
- package/dist/bea.js.map +1 -0
- package/dist/census-economic.d.ts +1 -1
- package/dist/census-economic.d.ts.map +1 -1
- package/dist/census-economic.js +12 -6
- package/dist/census-economic.js.map +1 -1
- package/dist/cms-facility.d.ts +112 -0
- package/dist/cms-facility.d.ts.map +1 -0
- package/dist/cms-facility.js +311 -0
- package/dist/cms-facility.js.map +1 -0
- package/dist/cms-hospital.d.ts +105 -0
- package/dist/cms-hospital.d.ts.map +1 -0
- package/dist/cms-hospital.js +290 -0
- package/dist/cms-hospital.js.map +1 -0
- package/dist/cms-supplier.d.ts +133 -0
- package/dist/cms-supplier.d.ts.map +1 -0
- package/dist/cms-supplier.js +414 -0
- package/dist/cms-supplier.js.map +1 -0
- package/dist/cms-utilization.d.ts +113 -0
- package/dist/cms-utilization.d.ts.map +1 -0
- package/dist/cms-utilization.js +328 -0
- package/dist/cms-utilization.js.map +1 -0
- package/dist/courtlistener.d.ts +115 -0
- package/dist/courtlistener.d.ts.map +1 -0
- package/dist/courtlistener.js +398 -0
- package/dist/courtlistener.js.map +1 -0
- package/dist/cpsc.d.ts +81 -0
- package/dist/cpsc.d.ts.map +1 -0
- package/dist/cpsc.js +283 -0
- package/dist/cpsc.js.map +1 -0
- package/dist/dol.d.ts +118 -0
- package/dist/dol.d.ts.map +1 -0
- package/dist/dol.js +421 -0
- package/dist/dol.js.map +1 -0
- package/dist/epa-envirofacts.d.ts +97 -0
- package/dist/epa-envirofacts.d.ts.map +1 -0
- package/dist/epa-envirofacts.js +292 -0
- package/dist/epa-envirofacts.js.map +1 -0
- package/dist/fred.d.ts +1 -1
- package/dist/fred.js +1 -1
- package/dist/keys.d.ts +11 -8
- package/dist/keys.d.ts.map +1 -1
- package/dist/keys.js +55 -8
- package/dist/keys.js.map +1 -1
- package/dist/lda.d.ts +105 -0
- package/dist/lda.d.ts.map +1 -0
- package/dist/lda.js +317 -0
- package/dist/lda.js.map +1 -0
- package/dist/nhtsa.d.ts +91 -0
- package/dist/nhtsa.d.ts.map +1 -0
- package/dist/nhtsa.js +263 -0
- package/dist/nhtsa.js.map +1 -0
- package/dist/nonprofit.d.ts +116 -0
- package/dist/nonprofit.d.ts.map +1 -0
- package/dist/nonprofit.js +342 -0
- package/dist/nonprofit.js.map +1 -0
- package/dist/openfda-device.d.ts +85 -0
- package/dist/openfda-device.d.ts.map +1 -0
- package/dist/openfda-device.js +277 -0
- package/dist/openfda-device.js.map +1 -0
- package/dist/openfda.d.ts +133 -0
- package/dist/openfda.d.ts.map +1 -0
- package/dist/openfda.js +402 -0
- package/dist/openfda.js.map +1 -0
- package/dist/server.d.ts.map +1 -1
- package/dist/server.js +872 -6
- package/dist/server.js.map +1 -1
- package/package.json +2 -1
- package/src/bea.ts +372 -0
- package/src/census-economic.ts +12 -6
- package/src/cms-facility.ts +379 -0
- package/src/cms-hospital.ts +344 -0
- package/src/cms-supplier.ts +527 -0
- package/src/cms-utilization.ts +389 -0
- package/src/courtlistener.ts +465 -0
- package/src/cpsc.ts +333 -0
- package/src/dol.ts +515 -0
- package/src/epa-envirofacts.ts +342 -0
- package/src/fred.ts +1 -1
- package/src/keys.ts +60 -8
- package/src/lda.ts +385 -0
- package/src/nhtsa.ts +352 -0
- package/src/nonprofit.ts +460 -0
- package/src/openfda-device.ts +356 -0
- package/src/openfda.ts +495 -0
- package/src/server.ts +995 -6
package/dist/bea.js
ADDED
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* bea.ts — BEA (Bureau of Economic Analysis) Regional Economic Accounts — the
|
|
3
|
+
* REGIONAL / SUB-NATIONAL economic lane (ADR-0051). County / state / MSA GDP by
|
|
4
|
+
* industry (CAGDP2 / SAGDP2N) and personal income (CAINC1 / SAINC1) — the
|
|
5
|
+
* place-of-performance market context that neither the national FRED macro series
|
|
6
|
+
* nor the Census establishment counts carry.
|
|
7
|
+
*
|
|
8
|
+
* ★ THIS IS THE SERVER'S THIRD KEY-REQUIRED SOURCE (Census CBP #1, FRED #2). The
|
|
9
|
+
* BEA Data API has NO keyless tier: every request needs `UserID=`. So, honestly:
|
|
10
|
+
* with NO `BEA_API_KEY` this tool THROWS an `invalid_input` config error BEFORE
|
|
11
|
+
* any fetch (never a fake-empty, never a keyless-pretend). The other tools
|
|
12
|
+
* stay keyless — this key is scoped to this one source. (Contrast the OPTIONAL
|
|
13
|
+
* keys of datagov/bls/nvd, which lift a tier but are not required.)
|
|
14
|
+
*
|
|
15
|
+
* This module MIRRORS the census-economic.ts / fred.ts key-required precedent: a
|
|
16
|
+
* `beaApiKey()` env seam, a pre-fetch `invalid_input` THROW when unset, the
|
|
17
|
+
* fixed-host SSRF assert + `redirect:"error"`, and a data-absence-sentinel→null
|
|
18
|
+
* idiom (Census's negative floor / FRED's `"."` — here BEA's string suppression
|
|
19
|
+
* codes `(NA) (D) (NM) (L) *`). It REUSES `getJson` (the shared fetch envelope) /
|
|
20
|
+
* `driftError` / `num`·`str` (coerce.ts, null-never-0/empty) / `withMeta`·`buildMeta`.
|
|
21
|
+
* The key rides ONLY in the `UserID=` query param, NOWHERE else (never the label,
|
|
22
|
+
* `_meta.source`, notes, or a log — the K-test).
|
|
23
|
+
*
|
|
24
|
+
* GET https://apps.bea.gov/api/data
|
|
25
|
+
* ?UserID=<BEA_API_KEY> (REQUIRED)
|
|
26
|
+
* &method=GetData&datasetname=Regional&ResultFormat=json (fixed)
|
|
27
|
+
* &TableName=<tableName> (e.g. CAGDP2, SAGDP2N, CAINC1)
|
|
28
|
+
* &GeoFips=<geoFips> (STATE | county FIPS | MSA)
|
|
29
|
+
* &LineCode=<lineCode> (industry line, or ALL)
|
|
30
|
+
* &Year=<year> (YYYY | LAST5 | ALL)
|
|
31
|
+
* &Frequency=<frequency> (A | Q)
|
|
32
|
+
* → { BEAAPI:{ Results:{ Statistic, UnitOfMeasure, Dimensions:[…],
|
|
33
|
+
* Data:[{ Code, GeoFips, GeoName, TimePeriod, CL_UNIT, UNIT_MULT,
|
|
34
|
+
* DataValue, NoteRef }], Notes:[{ NoteRef, NoteText }] } } }
|
|
35
|
+
*
|
|
36
|
+
* ★ HONESTY (ADR-0051 P1–P5):
|
|
37
|
+
* [KEY] no key ⇒ invalid_input THROW pre-fetch (0 fetch); the message names
|
|
38
|
+
* BEA_API_KEY + the free-signup URL.
|
|
39
|
+
* [P1] BEA GetData returns the COMPLETE set for the filter (no server
|
|
40
|
+
* pagination) ⇒ totalAvailable = the row count, complete:true. NEVER
|
|
41
|
+
* fabricated.
|
|
42
|
+
* [★P2] ★the crux: a missing/invalid key (and any bad-parameter request) returns
|
|
43
|
+
* HTTP **200** carrying `BEAAPI.Results.Error` — NOT an HTTP error status.
|
|
44
|
+
* The catch-ladder checks `Results.Error` FIRST (BEFORE the Data-array
|
|
45
|
+
* drift check) and throws invalid_input SURFACING `APIErrorDescription`
|
|
46
|
+
* (+ code) — NEVER read as an empty result. `Data:[]` (a genuine empty
|
|
47
|
+
* array) ⇒ honest empty (returned:0, complete:true). A 5xx/timeout ⇒
|
|
48
|
+
* upstream_unavailable THROW. A 200 non-JSON ⇒ schema_drift.
|
|
49
|
+
* [★P3] `DataValue` is a STRING WITH COMMAS ("1,234,567") — strip commas then
|
|
50
|
+
* `num()`. The suppression/not-available sentinels `(NA) (D) (NM) (L) *`
|
|
51
|
+
* (and any non-numeric after the comma-strip) map to **null** (withheld),
|
|
52
|
+
* NEVER 0 — a real "0" stays 0. `UNIT_MULT` (power-of-10 multiplier) is
|
|
53
|
+
* reported as `unitMult` and `CL_UNIT` as `unitOfMeasure`; the raw value is
|
|
54
|
+
* surfaced WITH the multiplier — it is NEVER multiplied in (that would lose
|
|
55
|
+
* precision and double-count against the disclosed multiplier).
|
|
56
|
+
* [P4] `BEAAPI` / `Results` / `Data` absent or non-array ⇒ driftError — BUT
|
|
57
|
+
* ONLY after the Results.Error check (an Error response is P2, not drift).
|
|
58
|
+
* [SSRF] fixed host `apps.bea.gov`; `tableName` ^[A-Za-z0-9]{2,20}$; `geoFips`
|
|
59
|
+
* ^[A-Za-z0-9]{2,10}$; `lineCode` ^([0-9]{1,4}|ALL)$; `year`
|
|
60
|
+
* ^\d{4}$|LAST5|ALL; `frequency` {A,Q}. All VALUES ride URLSearchParams;
|
|
61
|
+
* the key rides `UserID=` ONLY.
|
|
62
|
+
*/
|
|
63
|
+
import { ToolErrorCarrier } from "./errors.js";
|
|
64
|
+
import { getJson, driftError } from "./datasource.js";
|
|
65
|
+
import { num, str } from "./coerce.js";
|
|
66
|
+
import { withMeta } from "./meta.js";
|
|
67
|
+
// Re-export the shared honesty coercion (single audited copy in ./coerce.js —
|
|
68
|
+
// ADR-0005 v2 FIX-C) so a `num` regression fails together across sources. NO local
|
|
69
|
+
// num/str; the sentinel/comma-strip map is a WRAPPER around num, not a fork.
|
|
70
|
+
export { num };
|
|
71
|
+
// ─── SSRF core: the single fixed host + base path ─────────────────
|
|
72
|
+
export const BEA_HOST = "apps.bea.gov";
|
|
73
|
+
const BEA_PATH = "/api/data";
|
|
74
|
+
// HOST+path label — surfaces in ToolError.upstreamEndpoint; the key rides ONLY in
|
|
75
|
+
// the UserID= query param, so no token can ever appear here.
|
|
76
|
+
const BEA_LABEL = "bea:/api/data";
|
|
77
|
+
// ─── Validation charclasses (SSRF + "verify the input" honesty) ───
|
|
78
|
+
const TABLE_RE = /^[A-Za-z0-9]{2,20}$/; // e.g. CAGDP2, SAGDP2N, CAINC1
|
|
79
|
+
const GEOFIPS_RE = /^[A-Za-z0-9]{2,10}$/; // STATE | county FIPS | MSA code
|
|
80
|
+
const LINECODE_RE = /^([0-9]{1,4}|ALL)$/; // industry line, or ALL
|
|
81
|
+
const YEAR_RE = /^\d{4}$/; // a single 4-digit year
|
|
82
|
+
const YEAR_KEYWORDS = new Set(["LAST5", "ALL"]);
|
|
83
|
+
const FREQUENCIES = new Set(["A", "Q"]);
|
|
84
|
+
const DEFAULT_YEAR = "LAST5";
|
|
85
|
+
const DEFAULT_FREQUENCY = "A";
|
|
86
|
+
// BEA encodes a suppressed / not-available cell as one of these string codes in
|
|
87
|
+
// DataValue: (NA)=not available, (D)=disclosure-suppressed, (NM)=not meaningful,
|
|
88
|
+
// (L)=less than half the unit, *=statistically insignificant. Any of these — and
|
|
89
|
+
// any non-numeric value after the comma-strip — is a data-absence marker, NEVER a
|
|
90
|
+
// number and NEVER 0.
|
|
91
|
+
const BEA_SUPPRESSION = new Set(["(NA)", "(D)", "(NM)", "(L)", "*"]);
|
|
92
|
+
// ─── Honesty notes (ADR-0051 required set) ────────────────────────
|
|
93
|
+
const KEY_REQUIRED_NOTE = "This source REQUIRES a free BEA_API_KEY (the BEA Data API has no keyless tier). The key is sent ONLY as the UserID= query parameter to apps.bea.gov and is NEVER logged, echoed, or placed in this response.";
|
|
94
|
+
const DATAVALUE_NOTE = "dataValue is parsed from BEA's comma-formatted DataValue string ('1,234,567' → 1234567). BEA suppression/not-available codes ((NA)/(D)/(NM)/(L)/*) map to null (withheld) — NEVER 0 (a genuine 0 is preserved as 0).";
|
|
95
|
+
const UNIT_MULT_NOTE = "unitMult is BEA's UNIT_MULT (a power-of-10 multiplier) and unitOfMeasure is CL_UNIT (the unit label). The raw dataValue is surfaced ALONGSIDE unitMult and is NOT multiplied by it — apply unitMult yourself if a scaled figure is needed (multiplying here would lose precision and double-count).";
|
|
96
|
+
const NO_PAGINATION_NOTE = "BEA GetData returns the COMPLETE set of rows matching the filter (no server-side pagination); totalAvailable equals the number of rows returned. Narrow with geoFips / lineCode / year to reduce the row count.";
|
|
97
|
+
// ─── The key seam (REQUIRED; value NEVER leaked past the UserID= param) ──
|
|
98
|
+
/** Read BEA_API_KEY from env; trim; return the value or undefined (unset/blank). */
|
|
99
|
+
export function beaApiKey() {
|
|
100
|
+
const raw = process.env.BEA_API_KEY;
|
|
101
|
+
const trimmed = typeof raw === "string" ? raw.trim() : "";
|
|
102
|
+
return trimmed ? trimmed : undefined;
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* num(), but for BEA's comma-formatted DataValue string. Strips a suppression code
|
|
106
|
+
* ((NA)/(D)/(NM)/(L)/*) → null, otherwise removes thousands commas and defers to
|
|
107
|
+
* num (so "1,234,567" ⇒ 1234567, a genuine "0" ⇒ 0, and any residual non-numeric
|
|
108
|
+
* ⇒ null — NEVER a fabricated 0).
|
|
109
|
+
*/
|
|
110
|
+
export function beaDataValue(v) {
|
|
111
|
+
if (typeof v === "string") {
|
|
112
|
+
const s = v.trim();
|
|
113
|
+
if (s === "" || BEA_SUPPRESSION.has(s))
|
|
114
|
+
return null;
|
|
115
|
+
return num(s.replace(/,/g, ""));
|
|
116
|
+
}
|
|
117
|
+
return num(v);
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Fetch BEA Regional Economic Accounts rows for a table × geography × line filter
|
|
121
|
+
* → normalized rows + summarized BEA Notes + honest `_meta`. REQUIRES BEA_API_KEY
|
|
122
|
+
* (throws invalid_input pre-fetch when unset). ★A missing/invalid key (and any bad
|
|
123
|
+
* parameter) surfaces as an HTTP-200 `BEAAPI.Results.Error` carrier which is
|
|
124
|
+
* detected and thrown as invalid_input BEFORE the Data-array shape check.
|
|
125
|
+
*/
|
|
126
|
+
export async function regionalData(args) {
|
|
127
|
+
// ── [KEY] REQUIRED key — throw an honest config error BEFORE any fetch. ──
|
|
128
|
+
const key = beaApiKey();
|
|
129
|
+
if (key === undefined) {
|
|
130
|
+
throw new ToolErrorCarrier({
|
|
131
|
+
kind: "invalid_input",
|
|
132
|
+
retryable: false,
|
|
133
|
+
message: "BEA Regional Economic Accounts requires a free API key. Get one at https://apps.bea.gov/API/signup/ and set BEA_API_KEY.",
|
|
134
|
+
upstreamEndpoint: BEA_LABEL,
|
|
135
|
+
});
|
|
136
|
+
}
|
|
137
|
+
// ── Validate + default the inputs (belt-and-suspenders behind the server Zod;
|
|
138
|
+
// a DIRECT handler call bypasses Zod). All ride in the query string. ──
|
|
139
|
+
const tableName = args.tableName ?? "";
|
|
140
|
+
if (!TABLE_RE.test(tableName)) {
|
|
141
|
+
throw new ToolErrorCarrier({
|
|
142
|
+
kind: "invalid_input",
|
|
143
|
+
retryable: false,
|
|
144
|
+
message: `Invalid tableName ${JSON.stringify(tableName)} — expected a BEA Regional table code (^[A-Za-z0-9]{2,20}$), e.g. "CAGDP2" (county GDP by industry), "SAGDP2N" (state GDP), "CAINC1" (personal income).`,
|
|
145
|
+
upstreamEndpoint: BEA_LABEL,
|
|
146
|
+
});
|
|
147
|
+
}
|
|
148
|
+
const geoFips = args.geoFips ?? "";
|
|
149
|
+
if (!GEOFIPS_RE.test(geoFips)) {
|
|
150
|
+
throw new ToolErrorCarrier({
|
|
151
|
+
kind: "invalid_input",
|
|
152
|
+
retryable: false,
|
|
153
|
+
message: `Invalid geoFips ${JSON.stringify(geoFips)} — expected a BEA GeoFips selector (^[A-Za-z0-9]{2,10}$), e.g. "STATE" (all states), a county FIPS like "06075", or an MSA code.`,
|
|
154
|
+
upstreamEndpoint: BEA_LABEL,
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
const lineCode = args.lineCode ?? "";
|
|
158
|
+
if (!LINECODE_RE.test(lineCode)) {
|
|
159
|
+
throw new ToolErrorCarrier({
|
|
160
|
+
kind: "invalid_input",
|
|
161
|
+
retryable: false,
|
|
162
|
+
message: `Invalid lineCode ${JSON.stringify(lineCode)} — expected an integer industry line (^[0-9]{1,4}$), e.g. "1", or "ALL" for every line.`,
|
|
163
|
+
upstreamEndpoint: BEA_LABEL,
|
|
164
|
+
});
|
|
165
|
+
}
|
|
166
|
+
const year = args.year ?? DEFAULT_YEAR;
|
|
167
|
+
if (!YEAR_KEYWORDS.has(year) && !YEAR_RE.test(year)) {
|
|
168
|
+
throw new ToolErrorCarrier({
|
|
169
|
+
kind: "invalid_input",
|
|
170
|
+
retryable: false,
|
|
171
|
+
message: `Invalid year ${JSON.stringify(year)} — expected a 4-digit year (^\\d{4}$), "LAST5", or "ALL".`,
|
|
172
|
+
upstreamEndpoint: BEA_LABEL,
|
|
173
|
+
});
|
|
174
|
+
}
|
|
175
|
+
const frequency = args.frequency ?? DEFAULT_FREQUENCY;
|
|
176
|
+
if (!FREQUENCIES.has(frequency)) {
|
|
177
|
+
throw new ToolErrorCarrier({
|
|
178
|
+
kind: "invalid_input",
|
|
179
|
+
retryable: false,
|
|
180
|
+
message: `Invalid frequency ${JSON.stringify(frequency)} — expected one of A (annual), Q (quarterly).`,
|
|
181
|
+
upstreamEndpoint: BEA_LABEL,
|
|
182
|
+
});
|
|
183
|
+
}
|
|
184
|
+
// ── Build the query (all VALUES via URLSearchParams — no host/path steer; the
|
|
185
|
+
// REQUIRED key rides ONLY here in UserID=). ──
|
|
186
|
+
const params = new URLSearchParams();
|
|
187
|
+
params.set("UserID", key);
|
|
188
|
+
params.set("method", "GetData");
|
|
189
|
+
params.set("datasetname", "Regional");
|
|
190
|
+
params.set("ResultFormat", "json");
|
|
191
|
+
params.set("TableName", tableName);
|
|
192
|
+
params.set("GeoFips", geoFips);
|
|
193
|
+
params.set("LineCode", lineCode);
|
|
194
|
+
params.set("Year", year);
|
|
195
|
+
params.set("Frequency", frequency);
|
|
196
|
+
const url = `https://${BEA_HOST}${BEA_PATH}?${params.toString()}`;
|
|
197
|
+
// Belt-and-suspenders: the fixed host + strictly-validated query leave nothing to
|
|
198
|
+
// steer the authority; assert the built URL cannot have been moved off-host.
|
|
199
|
+
const built = new URL(url);
|
|
200
|
+
if (built.hostname !== BEA_HOST || built.protocol !== "https:") {
|
|
201
|
+
throw new ToolErrorCarrier({
|
|
202
|
+
kind: "invalid_input",
|
|
203
|
+
retryable: false,
|
|
204
|
+
message: `Constructed BEA URL host ${JSON.stringify(built.hostname)} (${built.protocol}) is not ${BEA_HOST} over https — refusing to fetch (SSRF safety).`,
|
|
205
|
+
upstreamEndpoint: BEA_LABEL,
|
|
206
|
+
});
|
|
207
|
+
}
|
|
208
|
+
// ── Fetch through the shared envelope. The key rides UserID= ONLY (never the
|
|
209
|
+
// label/_meta); redirect:"error" fails closed on any off-host 3xx (it could
|
|
210
|
+
// carry the key away). A 5xx/timeout ⇒ upstream_unavailable THROW; a 200
|
|
211
|
+
// non-JSON body ⇒ getJson's r.json() throws a SyntaxError ⇒ we reclassify to
|
|
212
|
+
// schema_drift. ★A missing/invalid key returns HTTP 200 with an Error carrier,
|
|
213
|
+
// so it does NOT surface here — it is detected in the parse ladder below. ──
|
|
214
|
+
let body;
|
|
215
|
+
try {
|
|
216
|
+
body = await getJson(url, { label: BEA_LABEL, redirect: "error" });
|
|
217
|
+
}
|
|
218
|
+
catch (e) {
|
|
219
|
+
if (e instanceof SyntaxError) {
|
|
220
|
+
throw driftError(BEA_LABEL, "BEA /api/data returned a non-JSON body at HTTP 200 — treating as schema drift (never read as an empty result).");
|
|
221
|
+
}
|
|
222
|
+
throw e; // 5xx → upstream_unavailable, 404 → not_found, 429 → rate_limited …
|
|
223
|
+
}
|
|
224
|
+
// ── [P4] Navigate BEAAPI.Results. An absent BEAAPI/Results is drift — BUT the
|
|
225
|
+
// Results.Error check (P2) comes FIRST below, since an error RESPONSE also
|
|
226
|
+
// carries BEAAPI.Results (with an Error member, not a Data array). ──
|
|
227
|
+
const beaapi = body?.BEAAPI;
|
|
228
|
+
if (beaapi === null || typeof beaapi !== "object") {
|
|
229
|
+
throw driftError(BEA_LABEL, "BEA response is missing the `BEAAPI` envelope — treating as schema drift (never a fabricated empty).");
|
|
230
|
+
}
|
|
231
|
+
const results = beaapi.Results;
|
|
232
|
+
if (results === null || typeof results !== "object") {
|
|
233
|
+
throw driftError(BEA_LABEL, "BEA response is missing `BEAAPI.Results` — treating as schema drift (never a fabricated empty).");
|
|
234
|
+
}
|
|
235
|
+
// ── [★P2] The CRUX: a missing/invalid key (or any bad parameter) returns HTTP
|
|
236
|
+
// 200 carrying `BEAAPI.Results.Error` — checked HERE, BEFORE the Data-array
|
|
237
|
+
// drift check, so an error response is surfaced as invalid_input CARRYING the
|
|
238
|
+
// APIErrorDescription (+ code), NEVER read as an empty result. ──
|
|
239
|
+
const errNode = results.Error;
|
|
240
|
+
if (errNode !== undefined && errNode !== null) {
|
|
241
|
+
const errObj = (Array.isArray(errNode) ? errNode[0] : errNode);
|
|
242
|
+
const code = str(errObj?.APIErrorCode);
|
|
243
|
+
const desc = str(errObj?.APIErrorDescription);
|
|
244
|
+
throw new ToolErrorCarrier({
|
|
245
|
+
kind: "invalid_input",
|
|
246
|
+
retryable: false,
|
|
247
|
+
message: desc
|
|
248
|
+
? `BEA rejected the request${code ? ` (APIErrorCode ${code})` : ""}: ${desc}. Check BEA_API_KEY and the tableName / geoFips / lineCode / year parameters.`
|
|
249
|
+
: `BEA rejected the request${code ? ` (APIErrorCode ${code})` : ""} — check BEA_API_KEY and the tableName / geoFips / lineCode / year parameters.`,
|
|
250
|
+
upstreamEndpoint: BEA_LABEL,
|
|
251
|
+
});
|
|
252
|
+
}
|
|
253
|
+
// ── [P4] `Data` MUST be an array (a missing/non-array is drift, never a
|
|
254
|
+
// fabricated empty). An EMPTY array is a genuine honest-empty (below). ──
|
|
255
|
+
const data = results.Data;
|
|
256
|
+
if (!Array.isArray(data)) {
|
|
257
|
+
throw driftError(BEA_LABEL, "BEA `BEAAPI.Results.Data` is missing or not an array — treating as schema drift (never a fabricated empty).");
|
|
258
|
+
}
|
|
259
|
+
// ── [P3] Map each Data row (comma-stripped/sentinel→null DataValue; UNIT_MULT /
|
|
260
|
+
// CL_UNIT reported, NOT applied). ──
|
|
261
|
+
const rows = data.map((raw) => {
|
|
262
|
+
const row = (raw ?? {});
|
|
263
|
+
return {
|
|
264
|
+
geoFips: str(row.GeoFips),
|
|
265
|
+
geoName: str(row.GeoName),
|
|
266
|
+
timePeriod: str(row.TimePeriod),
|
|
267
|
+
lineCode: str(row.Code),
|
|
268
|
+
dataValue: beaDataValue(row.DataValue),
|
|
269
|
+
unitOfMeasure: str(row.CL_UNIT),
|
|
270
|
+
unitMult: num(row.UNIT_MULT),
|
|
271
|
+
noteRef: str(row.NoteRef),
|
|
272
|
+
};
|
|
273
|
+
});
|
|
274
|
+
// ── Summarize the BEA Notes (footnotes). A missing/non-array Notes ⇒ []. ──
|
|
275
|
+
const notesNode = results.Notes;
|
|
276
|
+
const notes = Array.isArray(notesNode)
|
|
277
|
+
? notesNode.map((raw) => {
|
|
278
|
+
const n = (raw ?? {});
|
|
279
|
+
return { noteRef: str(n.NoteRef), noteText: str(n.NoteText) };
|
|
280
|
+
})
|
|
281
|
+
: [];
|
|
282
|
+
// ── [P1] The COMPLETE set for the filter (no server pagination). ──
|
|
283
|
+
const totalAvailable = rows.length;
|
|
284
|
+
const meta = {
|
|
285
|
+
// MODE only — never the key value (K-test).
|
|
286
|
+
source: "apps.bea.gov /api/data (BEA Regional Economic Accounts; BEA_API_KEY)",
|
|
287
|
+
keylessMode: false, // ★KEYED — the third key-required source
|
|
288
|
+
returned: rows.length,
|
|
289
|
+
totalAvailable,
|
|
290
|
+
filtersApplied: [
|
|
291
|
+
`tableName:${tableName}`,
|
|
292
|
+
`geoFips:${geoFips}`,
|
|
293
|
+
`lineCode:${lineCode}`,
|
|
294
|
+
`year:${year}`,
|
|
295
|
+
`frequency:${frequency}`,
|
|
296
|
+
],
|
|
297
|
+
filtersDropped: [],
|
|
298
|
+
fieldsUnavailable: [],
|
|
299
|
+
notes: [KEY_REQUIRED_NOTE, DATAVALUE_NOTE, UNIT_MULT_NOTE, NO_PAGINATION_NOTE],
|
|
300
|
+
};
|
|
301
|
+
return withMeta({ rows, notes }, meta);
|
|
302
|
+
}
|
|
303
|
+
//# sourceMappingURL=bea.js.map
|
package/dist/bea.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bea.js","sourceRoot":"","sources":["../src/bea.ts"],"names":[],"mappings":"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"}
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* its keyless tier — a request WITHOUT a key is 302-redirected to a "Missing
|
|
9
9
|
* Key" HTML page. So, honestly: with NO `CENSUS_API_KEY` this tool THROWS an
|
|
10
10
|
* `invalid_input` config error BEFORE any fetch (never a fake-empty, never a
|
|
11
|
-
* keyless-pretend). The other
|
|
11
|
+
* keyless-pretend). The other tools stay keyless — this key is scoped to
|
|
12
12
|
* this one source. (Contrast the OPTIONAL keys of datagov/bls/nvd, which lift a
|
|
13
13
|
* tier but are not required.)
|
|
14
14
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"census-economic.d.ts","sourceRoot":"","sources":["../src/census-economic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAIH,OAAO,EAAE,GAAG,EAAO,MAAM,aAAa,CAAC;AACvC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAKzE,OAAO,EAAE,GAAG,EAAE,CAAC;
|
|
1
|
+
{"version":3,"file":"census-economic.d.ts","sourceRoot":"","sources":["../src/census-economic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAIH,OAAO,EAAE,GAAG,EAAO,MAAM,aAAa,CAAC;AACvC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAKzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAqCf,uFAAuF;AACvF,wBAAgB,YAAY,IAAI,MAAM,GAAG,SAAS,CAIjD;AAGD,MAAM,MAAM,MAAM,GAAG;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAiBF,MAAM,MAAM,0BAA0B,GAAG;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,UAAU,CAAC,CA+QrB"}
|
package/dist/census-economic.js
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
* its keyless tier — a request WITHOUT a key is 302-redirected to a "Missing
|
|
9
9
|
* Key" HTML page. So, honestly: with NO `CENSUS_API_KEY` this tool THROWS an
|
|
10
10
|
* `invalid_input` config error BEFORE any fetch (never a fake-empty, never a
|
|
11
|
-
* keyless-pretend). The other
|
|
11
|
+
* keyless-pretend). The other tools stay keyless — this key is scoped to
|
|
12
12
|
* this one source. (Contrast the OPTIONAL keys of datagov/bls/nvd, which lift a
|
|
13
13
|
* tier but are not required.)
|
|
14
14
|
*
|
|
@@ -77,16 +77,22 @@ const YEAR_RE = /^\d{4}$/; // rides in the PATH — strict 4-digit (no path inje
|
|
|
77
77
|
const NAICS_RE = /^\d{2,6}$/; // 2–6 digit NAICS-2017 sector/code
|
|
78
78
|
const STATE_FIPS_RE = /^\d{2}$/; // 2-digit state FIPS
|
|
79
79
|
const GEOGRAPHIES = new Set(["us", "state", "county"]);
|
|
80
|
-
//
|
|
81
|
-
// unavailable cell as a large NEGATIVE value (-999999999 / -888888888 /
|
|
82
|
-
// -666666666 …)
|
|
83
|
-
// value at/below this floor is a sentinel, NOT data.
|
|
80
|
+
// DEFENSIVE large-negative sentinel floor. Some Census products (ACS/SAIPE) encode a
|
|
81
|
+
// withheld/unavailable cell as a large NEGATIVE jam value (-999999999 / -888888888 /
|
|
82
|
+
// -666666666 …); establishment/employment/payroll counts are non-negative, so any
|
|
83
|
+
// value at/below this floor is a sentinel, NOT data → mapped to null.
|
|
84
|
+
// ★HONESTY CAVEAT: CBP itself does NOT primarily use these jam values — modern CBP
|
|
85
|
+
// uses NOISE INFUSION (EMP_N noise-range columns) + suppression FLAGS (EMP_N_F …),
|
|
86
|
+
// which this tool does NOT currently request or interpret (it surfaces values as
|
|
87
|
+
// reported). So this floor is a conservative cross-product guard, not CBP's confirmed
|
|
88
|
+
// mechanism; a keyed live verification of CBP's exact withheld-cell encoding is pending
|
|
89
|
+
// (no CENSUS_API_KEY was available at build time). See SUPPRESSED_NOTE.
|
|
84
90
|
const CENSUS_SENTINEL_FLOOR = -100000000;
|
|
85
91
|
const DEFAULT_YEAR = "2022"; // the latest confirmed CBP vintage (ADR-0047)
|
|
86
92
|
// ─── Honesty notes (ADR-0047 required set) ────────────────────────
|
|
87
93
|
const KEY_REQUIRED_NOTE = "This source REQUIRES a free CENSUS_API_KEY (the Census Data API has no keyless tier). The key is sent ONLY as the &key= query parameter to api.census.gov and is NEVER logged, echoed, or placed in this response.";
|
|
88
94
|
const PAYROLL_UNITS_NOTE = "annualPayrollUsd is ANNUAL payroll in US dollars, converted from the Census PAYANN field's $1,000 units (×1000). establishments and employees are integer counts (as-of the reference year).";
|
|
89
|
-
const SUPPRESSED_NOTE = "
|
|
95
|
+
const SUPPRESSED_NOTE = "Disclosure protection: any large-negative jam sentinel (e.g. -999999999) is mapped to null (withheld) — NEVER a negative number and NEVER 0; a genuine 0 is preserved as 0. NOTE: modern CBP applies NOISE INFUSION (perturbed values) plus suppression flag columns (e.g. EMP_N_F) rather than jam sentinels; this tool surfaces values as reported and does not currently interpret suppression flags, so a flagged/noise-infused cell is returned as its reported number — treat exact small counts as approximate.";
|
|
90
96
|
const NO_PAGINATION_NOTE = "CBP returns the COMPLETE set of geographies matching the filter (no server-side pagination); totalAvailable equals the number of rows returned. Narrow with naics / geography to reduce the row count.";
|
|
91
97
|
// ─── The key seam (REQUIRED; value NEVER leaked past the &key= param) ──
|
|
92
98
|
/** Read CENSUS_API_KEY from env; trim; return the value or undefined (unset/blank). */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"census-economic.js","sourceRoot":"","sources":["../src/census-economic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAsC,MAAM,WAAW,CAAC;AAEzE,8EAA8E;AAC9E,iFAAiF;AACjF,WAAW;AACX,OAAO,EAAE,GAAG,EAAE,CAAC;AAEf,qEAAqE;AACrE,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;AAC1C,MAAM,iBAAiB,GAAG,kBAAkB,CAAC,CAAC,gDAAgD;AAE9F,qEAAqE;AACrE,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,yDAAyD;AACpF,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,mCAAmC;AACjE,MAAM,aAAa,GAAG,SAAS,CAAC,CAAC,qBAAqB;AACtD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEvD,
|
|
1
|
+
{"version":3,"file":"census-economic.js","sourceRoot":"","sources":["../src/census-economic.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* cms-facility.ts — CMS "facility directory" across FOUR provider-data datasets
|
|
3
|
+
* (`data.cms.gov`, the provider-data DKAN datastore-query API; ADR-0063). KEYLESS.
|
|
4
|
+
*
|
|
5
|
+
* WHAT IT ADDS: `cms_facility_directory` — a healthcare-facility directory / market
|
|
6
|
+
* lane that generalizes cms_hospital_compare (ADR-0062) BEYOND hospitals: a caller
|
|
7
|
+
* picks a `facilityType` (nursing_home | home_health | hospice | dialysis) and the
|
|
8
|
+
* tool routes to the RIGHT CMS provider-data dataset, returning each facility's
|
|
9
|
+
* name / address / city / state / zip / ownership. The facility-level complement to
|
|
10
|
+
* the utilization and hospital lanes — WHERE these Medicare-certified facilities are.
|
|
11
|
+
*
|
|
12
|
+
* ★THE facilityType → DATASET-ID CONSTANT MAP (the load-bearing SSRF guard): the
|
|
13
|
+
* USER value never enters the URL path. `facilityType` is a Zod ENUM; it indexes a
|
|
14
|
+
* MODULE-CONSTANT map to a VETTED dataset id (e.g. nursing_home → "4pq5-n9py") that
|
|
15
|
+
* is spliced into the path. An unknown facilityType is blocked by the enum
|
|
16
|
+
* (invalid_input) BEFORE any fetch — only one of four compile-time ids can ever
|
|
17
|
+
* reach the path.
|
|
18
|
+
*
|
|
19
|
+
* ★THE ONE-REQUEST COUNT PATTERN (P1 honesty, inherited from cms-hospital): the DKAN
|
|
20
|
+
* datastore-query response is `{ count, results, schema, query }` — `count` is the
|
|
21
|
+
* EXACT per-filter total in the SAME body as the rows. So totalAvailable = the
|
|
22
|
+
* response's top-level `count` (nursing_home ⇒ 14695), NEVER `results.length`.
|
|
23
|
+
*
|
|
24
|
+
* ★FIELD-NAME VARIANCE ACROSS DATASETS (the one genuinely-new complexity vs.
|
|
25
|
+
* cms-hospital) — live-verified 2026-07-15. The facility NAME, ADDRESS, and
|
|
26
|
+
* OWNERSHIP columns are NAMED DIFFERENTLY per dataset, so each is COALESCED over a
|
|
27
|
+
* fixed candidate order (null if none present — NEVER an empty string, NEVER
|
|
28
|
+
* fabricated):
|
|
29
|
+
* name : provider_name → facility_name → legal_business_name
|
|
30
|
+
* address : address → provider_address → address_line_1
|
|
31
|
+
* ownership : ownership_type → type_of_ownership → profit_or_nonprofit
|
|
32
|
+
* (city = citytown, state = state, zip = zip_code are uniform across all four.)
|
|
33
|
+
* Per-dataset verified columns:
|
|
34
|
+
* nursing_home 4pq5-n9py: provider_name / provider_address / ownership_type
|
|
35
|
+
* home_health 6jpm-sxkc: provider_name / address / type_of_ownership
|
|
36
|
+
* hospice yc9t-dgbk: facility_name / address_line_1 / ownership_type
|
|
37
|
+
* dialysis 23ew-n7w9: facility_name / address_line_1 / profit_or_nonprofit
|
|
38
|
+
* ★ADR-0063 said nursing_home's address is `address`; it is actually
|
|
39
|
+
* `provider_address` (probed live) — the coalescing candidate list covers it.
|
|
40
|
+
*
|
|
41
|
+
* ★THE facilityName FILTER COLUMN also varies: the `contains` filter targets the
|
|
42
|
+
* dataset's OWN primary-name column (provider_name for nursing_home/home_health,
|
|
43
|
+
* facility_name for hospice/dialysis) — stored per-type in the constant map.
|
|
44
|
+
*
|
|
45
|
+
* The module writes ZERO fetch/coercion/error/meta code — it REUSES `getJson`
|
|
46
|
+
* (redirect:"error") / `driftError` (datasource.ts), `str` (coerce.ts,
|
|
47
|
+
* null-never-empty-string), and `withMeta`·`buildMeta` (meta.ts, offset pagination
|
|
48
|
+
* + totalAvailable). It MIRRORS cms-hospital.ts's fixed-host SSRF idiom (a single
|
|
49
|
+
* host const + a post-construction hostname/protocol assertion + redirect:"error" +
|
|
50
|
+
* `conditions[i][…]` bracket keys and values carried via URLSearchParams) and its
|
|
51
|
+
* schema_drift catch-ladder (ToolErrorCarrier rethrow FIRST → SyntaxError→driftError
|
|
52
|
+
* → bare rethrow).
|
|
53
|
+
*
|
|
54
|
+
* GET https://data.cms.gov/provider-data/api/1/datastore/query/{datasetId}/0
|
|
55
|
+
* ?limit=&offset=&conditions[0][property]=state&conditions[0][value]=VA&conditions[0][operator]==
|
|
56
|
+
* → { count: 383, results: [ { provider_name, provider_address, … }, … ], schema, query }
|
|
57
|
+
*
|
|
58
|
+
* ★ SSRF: the host is a compile-time literal (`CMS_HOST`); the dataset id is chosen
|
|
59
|
+
* by a Zod-enum key from a MODULE-CONSTANT map (never the user string). Every USER
|
|
60
|
+
* filter VALUE rides as a URLSearchParams VALUE (`conditions[i][value]=…`) — the
|
|
61
|
+
* bracket key AND the value are encoded, so a value can never break out of the
|
|
62
|
+
* path or inject a parameter. state is `^[A-Za-z]{2}$`; facilityName is a bounded
|
|
63
|
+
* free-text charclass; size/offset are coerced to integers. A post-construction
|
|
64
|
+
* hostname/protocol assertion + `redirect:"error"` fail closed on any off-host 3xx.
|
|
65
|
+
*
|
|
66
|
+
* ★ HONESTY (ADR-0063 P1–P5, live-verified 2026-07-15 on data.cms.gov):
|
|
67
|
+
* [P1] totalAvailable = the response's top-level `count` (EXACT per-filter total),
|
|
68
|
+
* NOT the slice length. hasMore = offset+returned < count.
|
|
69
|
+
* [P2] results:[] ⇒ honest empty (returned:0). An invalid facilityType is blocked
|
|
70
|
+
* by the Zod enum (invalid_input). getJson maps a 4xx/5xx via
|
|
71
|
+
* errorFromResponse and THROWS (503 ⇒ upstream_unavailable, 400 ⇒
|
|
72
|
+
* invalid_input, 404 ⇒ not_found); a 200 non-JSON body OR a body missing
|
|
73
|
+
* `count`/`results` ⇒ schema_drift (NEVER a fabricated empty).
|
|
74
|
+
* [P3] name/address/ownership are COALESCED over the candidate order — null if none
|
|
75
|
+
* (NEVER an empty string, NEVER fabricated). String fields via str().
|
|
76
|
+
* [P4] results non-array OR count non-number ⇒ driftError.
|
|
77
|
+
*/
|
|
78
|
+
import { str } from "./coerce.js";
|
|
79
|
+
import { type MetaBundle } from "./meta.js";
|
|
80
|
+
export { str };
|
|
81
|
+
type FacilityType = "nursing_home" | "home_health" | "hospice" | "dialysis";
|
|
82
|
+
export type Facility = {
|
|
83
|
+
name: string | null;
|
|
84
|
+
address: string | null;
|
|
85
|
+
city: string | null;
|
|
86
|
+
state: string | null;
|
|
87
|
+
zip: string | null;
|
|
88
|
+
facilityType: FacilityType;
|
|
89
|
+
ownership: string | null;
|
|
90
|
+
};
|
|
91
|
+
/**
|
|
92
|
+
* Coalesce a row's value over a candidate column order → string | null.
|
|
93
|
+
* Returns the FIRST column whose str() is non-null (str nulls ""/whitespace/"null");
|
|
94
|
+
* null if NONE — NEVER an empty string, NEVER a fabricated value (P3).
|
|
95
|
+
*/
|
|
96
|
+
export declare function coalesceField(row: Record<string, unknown>, fields: string[]): string | null;
|
|
97
|
+
export type CmsFacilityDirectoryArgs = {
|
|
98
|
+
facilityType?: string;
|
|
99
|
+
state?: string;
|
|
100
|
+
facilityName?: string;
|
|
101
|
+
size?: number;
|
|
102
|
+
offset?: number;
|
|
103
|
+
};
|
|
104
|
+
/**
|
|
105
|
+
* Fetch CMS provider-data facility rows for a `facilityType` (+ optional state /
|
|
106
|
+
* facility-name fragment) → normalized facility rows + honest `_meta`. The
|
|
107
|
+
* facilityType (a Zod enum) indexes the FACILITY_DATASETS constant map to a vetted
|
|
108
|
+
* dataset id — the user value never enters the path. A SINGLE request: the response's
|
|
109
|
+
* top-level `count` is the EXACT per-filter total (P1 — never the slice length).
|
|
110
|
+
*/
|
|
111
|
+
export declare function facilityDirectory(args: CmsFacilityDirectoryArgs): Promise<MetaBundle>;
|
|
112
|
+
//# sourceMappingURL=cms-facility.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cms-facility.d.ts","sourceRoot":"","sources":["../src/cms-facility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AAIH,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAIzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAkBf,KAAK,YAAY,GAAG,cAAc,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AA8D5E,MAAM,MAAM,QAAQ,GAAG;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,MAAM,EAAE,GACf,MAAM,GAAG,IAAI,CAMf;AA0CD,MAAM,MAAM,wBAAwB,GAAG;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,UAAU,CAAC,CAkIrB"}
|