@cliwant/mcp-sam-gov 1.0.0 → 1.1.0

package/dist/fred.d.ts

@@ -0,0 +1,108 @@
+/**
+ * fred.ts — FRED (Federal Reserve Economic Data, St. Louis Fed) — the MACRO
+ * CONTEXT lane (ADR-0048, Wave-4 source #2). GDP · CPI · interest rates ·
+ * unemployment · PPI … — the economy-wide backdrop for B2G bid escalation and
+ * market-timing that no contract/spending source carries.
+ *
+ * ★ THIS IS THE SERVER'S SECOND KEY-REQUIRED SOURCE (Census CBP was the first).
+ *   FRED has NO keyless tier: every request needs `&api_key=`, and a missing/bad
+ *   key returns HTTP 400 `{error_code, error_message}`. So, honestly: with NO
+ *   `FRED_API_KEY` these two tools THROW an `invalid_input` config error BEFORE any
+ *   fetch (never a fake-empty, never a keyless-pretend). The other 112 tools stay
+ *   keyless — this key is scoped to this one source. (Contrast the OPTIONAL keys of
+ *   datagov/bls/nvd, which lift a tier but are not required.)
+ *
+ * This module MIRRORS the census-economic.ts optional-key precedent: a `fredApiKey()`
+ * env seam, a pre-fetch `invalid_input` THROW when unset, the fixed-host SSRF assert
+ * + `redirect:"error"`, and the missing-sentinel→null idiom (Census's negative
+ * suppression sentinel there; FRED's `value === "."` here — the BLS `"-"` lineage).
+ * It writes ZERO coercion/meta code of its own: it REUSES `getJson` (the shared
+ * fetch envelope) / `driftError` / `num`·`str` (coerce.ts, null-never-0/empty) /
+ * `withMeta`·`buildMeta` (offset pagination via count-exact totals).
+ *
+ *   GET https://api.stlouisfed.org/fred/series/search
+ *       ?search_text=<q>&limit=&offset=&api_key=<KEY>&file_type=json
+ *   → { seriess:[{ id,title,frequency,frequency_short,units,seasonal_adjustment,
+ *        observation_start,observation_end,last_updated,popularity,notes }],
+ *       count, limit, offset }
+ *
+ *   GET https://api.stlouisfed.org/fred/series/observations
+ *       ?series_id=<id>&observation_start=&observation_end=&limit=&offset=
+ *        &sort_order=&api_key=<KEY>&file_type=json
+ *   → { observations:[{ date, value }], count, … }   ★value === "." ⇒ missing (null)
+ *
+ * ★ HONESTY (ADR-0048 P1–P5):
+ *   [KEY]  no key ⇒ invalid_input THROW pre-fetch (0 fetch); the message names
+ *          FRED_API_KEY + the free-signup URL. A 400 carrying `{error_message}` (a
+ *          bad series_id / expired key) ⇒ reclassified to invalid_input CARRYING the
+ *          FRED error_message — honestly reported, never a fake empty.
+ *   [P1]   both endpoints report `count` (the total) ⇒ totalAvailable = num(count)
+ *          EXACT; offset pagination (hasMore = offset+returned < count, nextOffset).
+ *          NEVER fabricated (RED if totalAvailable = returned).
+ *   [P3]   ★the missing crux: an observation `value === "."` ⇒ **null** (FRED's
+ *          missing sentinel — the BLS `"-"` lineage), NEVER 0. A genuine "0" ⇒ 0.
+ *   [P2]   a 400 ⇒ invalid_input (carrying error_message); a genuine no-match
+ *          (seriess:[] / observations:[]) ⇒ honest empty; a 5xx ⇒ upstream_unavailable
+ *          THROW; a 200 non-JSON ⇒ schema_drift.
+ *   [P4]   a body whose `seriess` / `observations` is absent or non-array ⇒ driftError
+ *          (never a fabricated empty).
+ *   [SSRF] fixed host `api.stlouisfed.org`; `series_id` charclass `^[A-Za-z0-9._-]+$`;
+ *          dates `^\d{4}-\d{2}-\d{2}$`; sort_order enum {asc,desc}. All VALUES ride
+ *          URLSearchParams; the key rides `&api_key=` ONLY — never a label/_meta/note
+ *          (the K-test).
+ */
+import { num } from "./coerce.js";
+import { type MetaBundle } from "./meta.js";
+export { num };
+export declare const FRED_HOST = "api.stlouisfed.org";
+/** Read FRED_API_KEY from env; trim; return the value or undefined (unset/blank). */
+export declare function fredApiKey(): string | undefined;
+/**
+ * num(), but map FRED's missing-observation sentinel `"."` → null (missing). A
+ * genuine "0" stays 0 (num("0") === 0); a real numeric string parses. This is the
+ * BLS `"-"` lineage — a data-absence marker, never a fabricated 0.
+ */
+export declare function fredValue(v: unknown): number | null;
+export type FredSearchSeriesArgs = {
+    query?: string;
+    limit?: number;
+    offset?: number;
+};
+export type FredSeries = {
+    id: string | null;
+    title: string | null;
+    frequency: string | null;
+    frequencyShort: string | null;
+    units: string | null;
+    seasonalAdjustment: string | null;
+    observationStart: string | null;
+    observationEnd: string | null;
+    lastUpdated: string | null;
+    popularity: number | null;
+};
+/**
+ * Search FRED series (`/fred/series/search`) by `search_text` → curated series
+ * rows + honest `_meta`. REQUIRES FRED_API_KEY (throws invalid_input pre-fetch when
+ * unset). totalAvailable = FRED's exact `count`; offset pagination.
+ */
+export declare function searchSeries(args: FredSearchSeriesArgs): Promise<MetaBundle>;
+export type FredSeriesObservationsArgs = {
+    seriesId?: string;
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+    offset?: number;
+    sortOrder?: string;
+};
+export type FredObservation = {
+    date: string | null;
+    value: number | null;
+};
+/**
+ * Fetch a FRED series' time series (`/fred/series/observations`) → date/value rows
+ * + honest `_meta`. REQUIRES FRED_API_KEY (throws invalid_input pre-fetch when
+ * unset). ★A missing observation (`value === "."`) maps to null, never 0.
+ * totalAvailable = FRED's exact `count`; offset pagination.
+ */
+export declare function seriesObservations(args: FredSeriesObservationsArgs): Promise<MetaBundle>;
+//# sourceMappingURL=fred.d.ts.map

package/dist/fred.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fred.d.ts","sourceRoot":"","sources":["../src/fred.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAIH,OAAO,EAAE,GAAG,EAAO,MAAM,aAAa,CAAC;AACvC,OAAO,EAAY,KAAK,UAAU,EAAqB,MAAM,WAAW,CAAC;AAKzE,OAAO,EAAE,GAAG,EAAE,CAAC;AAGf,eAAO,MAAM,SAAS,uBAAuB,CAAC;AA2B9C,qFAAqF;AACrF,wBAAgB,UAAU,IAAI,MAAM,GAAG,SAAS,CAI/C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGnD;AAgFD,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,UAAU,CAAC,CA4FrB;AAGD,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,0BAA0B,GAC/B,OAAO,CAAC,UAAU,CAAC,CAsHrB"}

package/dist/fred.js

@@ -0,0 +1,373 @@
+/**
+ * fred.ts — FRED (Federal Reserve Economic Data, St. Louis Fed) — the MACRO
+ * CONTEXT lane (ADR-0048, Wave-4 source #2). GDP · CPI · interest rates ·
+ * unemployment · PPI … — the economy-wide backdrop for B2G bid escalation and
+ * market-timing that no contract/spending source carries.
+ *
+ * ★ THIS IS THE SERVER'S SECOND KEY-REQUIRED SOURCE (Census CBP was the first).
+ *   FRED has NO keyless tier: every request needs `&api_key=`, and a missing/bad
+ *   key returns HTTP 400 `{error_code, error_message}`. So, honestly: with NO
+ *   `FRED_API_KEY` these two tools THROW an `invalid_input` config error BEFORE any
+ *   fetch (never a fake-empty, never a keyless-pretend). The other 112 tools stay
+ *   keyless — this key is scoped to this one source. (Contrast the OPTIONAL keys of
+ *   datagov/bls/nvd, which lift a tier but are not required.)
+ *
+ * This module MIRRORS the census-economic.ts optional-key precedent: a `fredApiKey()`
+ * env seam, a pre-fetch `invalid_input` THROW when unset, the fixed-host SSRF assert
+ * + `redirect:"error"`, and the missing-sentinel→null idiom (Census's negative
+ * suppression sentinel there; FRED's `value === "."` here — the BLS `"-"` lineage).
+ * It writes ZERO coercion/meta code of its own: it REUSES `getJson` (the shared
+ * fetch envelope) / `driftError` / `num`·`str` (coerce.ts, null-never-0/empty) /
+ * `withMeta`·`buildMeta` (offset pagination via count-exact totals).
+ *
+ *   GET https://api.stlouisfed.org/fred/series/search
+ *       ?search_text=<q>&limit=&offset=&api_key=<KEY>&file_type=json
+ *   → { seriess:[{ id,title,frequency,frequency_short,units,seasonal_adjustment,
+ *        observation_start,observation_end,last_updated,popularity,notes }],
+ *       count, limit, offset }
+ *
+ *   GET https://api.stlouisfed.org/fred/series/observations
+ *       ?series_id=<id>&observation_start=&observation_end=&limit=&offset=
+ *        &sort_order=&api_key=<KEY>&file_type=json
+ *   → { observations:[{ date, value }], count, … }   ★value === "." ⇒ missing (null)
+ *
+ * ★ HONESTY (ADR-0048 P1–P5):
+ *   [KEY]  no key ⇒ invalid_input THROW pre-fetch (0 fetch); the message names
+ *          FRED_API_KEY + the free-signup URL. A 400 carrying `{error_message}` (a
+ *          bad series_id / expired key) ⇒ reclassified to invalid_input CARRYING the
+ *          FRED error_message — honestly reported, never a fake empty.
+ *   [P1]   both endpoints report `count` (the total) ⇒ totalAvailable = num(count)
+ *          EXACT; offset pagination (hasMore = offset+returned < count, nextOffset).
+ *          NEVER fabricated (RED if totalAvailable = returned).
+ *   [P3]   ★the missing crux: an observation `value === "."` ⇒ **null** (FRED's
+ *          missing sentinel — the BLS `"-"` lineage), NEVER 0. A genuine "0" ⇒ 0.
+ *   [P2]   a 400 ⇒ invalid_input (carrying error_message); a genuine no-match
+ *          (seriess:[] / observations:[]) ⇒ honest empty; a 5xx ⇒ upstream_unavailable
+ *          THROW; a 200 non-JSON ⇒ schema_drift.
+ *   [P4]   a body whose `seriess` / `observations` is absent or non-array ⇒ driftError
+ *          (never a fabricated empty).
+ *   [SSRF] fixed host `api.stlouisfed.org`; `series_id` charclass `^[A-Za-z0-9._-]+$`;
+ *          dates `^\d{4}-\d{2}-\d{2}$`; sort_order enum {asc,desc}. All VALUES ride
+ *          URLSearchParams; the key rides `&api_key=` ONLY — never a label/_meta/note
+ *          (the K-test).
+ */
+import { ToolErrorCarrier } from "./errors.js";
+import { getJson, driftError } from "./datasource.js";
+import { num, str } from "./coerce.js";
+import { withMeta } from "./meta.js";
+// Re-export the shared honesty coercion (single audited copy in ./coerce.js —
+// ADR-0005 v2 FIX-C) so a `num` regression fails together across sources. NO local
+// num/str; the `"."`→null map is a WRAPPER around num, not a fork.
+export { num };
+// ─── SSRF core: the single fixed host + base path ─────────────────
+export const FRED_HOST = "api.stlouisfed.org";
+const FRED_SEARCH_PATH = "/fred/series/search";
+const FRED_OBS_PATH = "/fred/series/observations";
+// HOST+path labels — surface in ToolError.upstreamEndpoint; the key rides ONLY in
+// the &api_key= query param, so no token can ever appear here.
+const FRED_SEARCH_LABEL = "fred:/fred/series/search";
+const FRED_OBS_LABEL = "fred:/fred/series/observations";
+// ─── Validation charclasses (SSRF + "verify the input" honesty) ───
+const SERIES_ID_RE = /^[A-Za-z0-9._-]+$/; // FRED series ids: GDP, CPIAUCSL, DGS10 …
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/; // YYYY-MM-DD observation bounds
+const SORT_ORDERS = new Set(["asc", "desc"]);
+const DEFAULT_SEARCH_LIMIT = 25;
+const MAX_SEARCH_LIMIT = 1000;
+const DEFAULT_OBS_LIMIT = 100;
+const MAX_OBS_LIMIT = 100000;
+// ─── Honesty notes (ADR-0048 required set) ────────────────────────
+const KEY_REQUIRED_NOTE = "This source REQUIRES a free FRED_API_KEY (FRED has no keyless tier). The key is sent ONLY as the &api_key= query parameter to api.stlouisfed.org and is NEVER logged, echoed, or placed in this response.";
+const MISSING_VALUE_NOTE = "FRED encodes a MISSING observation as the literal '.' — such values are mapped to null (missing), NEVER 0. A genuine reported 0 is preserved as 0.";
+const COUNT_TOTAL_NOTE = "totalAvailable is FRED's exact reported `count` for the query; page with limit/offset (hasMore/nextOffset are derived from it, never fabricated).";
+// ─── The key seam (REQUIRED; value NEVER leaked past the &api_key= param) ──
+/** Read FRED_API_KEY from env; trim; return the value or undefined (unset/blank). */
+export function fredApiKey() {
+    const raw = process.env.FRED_API_KEY;
+    const trimmed = typeof raw === "string" ? raw.trim() : "";
+    return trimmed ? trimmed : undefined;
+}
+/**
+ * num(), but map FRED's missing-observation sentinel `"."` → null (missing). A
+ * genuine "0" stays 0 (num("0") === 0); a real numeric string parses. This is the
+ * BLS `"-"` lineage — a data-absence marker, never a fabricated 0.
+ */
+export function fredValue(v) {
+    if (v === ".")
+        return null;
+    return num(v);
+}
+// ─── Shared SSRF-guarded fetch (REQUIRED key; &api_key= ONLY carrier) ──
+/**
+ * GET one FRED JSON resource. The REQUIRED key is checked BEFORE any fetch (an
+ * unset FRED_API_KEY ⇒ invalid_input THROW, 0 network call). The query is built on
+ * the FIXED host from `params` + `&api_key=` + `&file_type=json` via URLSearchParams
+ * (no host/path steer); a post-construction hostname/protocol assertion +
+ * `redirect:"error"` lock it (fail closed on any off-host 3xx — it could carry the
+ * key away). `label` is host+path only.
+ *
+ * A 400 carrying `{error_message}` (a bad series_id / expired key) is reclassified
+ * to invalid_input CARRYING the FRED message. `getJson`/`fetchWithRetry` discards a
+ * non-ok body (it throws before reading it), so to surface FRED's honest reason we
+ * re-read the 400 body via a single bare GET on the error path ONLY (the happy /
+ * 5xx / 429 / timeout paths keep the shared envelope's retry taxonomy untouched).
+ */
+async function getFred(path, label, params, key) {
+    params.set("api_key", key);
+    params.set("file_type", "json");
+    const url = `https://${FRED_HOST}${path}?${params.toString()}`;
+    const built = new URL(url);
+    if (built.hostname !== FRED_HOST || built.protocol !== "https:") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Constructed FRED URL host ${JSON.stringify(built.hostname)} (${built.protocol}) is not ${FRED_HOST} over https — refusing to fetch (SSRF safety).`,
+            upstreamEndpoint: label,
+        });
+    }
+    try {
+        // The key rides in &api_key= ONLY (never the label/_meta); redirect:"error"
+        // (fail closed on any off-host 3xx). A 200 non-JSON body ⇒ getJson's r.json()
+        // throws SyntaxError ⇒ the caller reclassifies to schema_drift.
+        return await getJson(url, { label, redirect: "error" });
+    }
+    catch (e) {
+        if (e instanceof ToolErrorCarrier) {
+            // A 400 (missing/bad key, or a bad series_id) carries FRED's honest
+            // `{error_message}`, but fetchWithRetry discarded the body. Re-read it once so
+            // the caller learns the REAL reason (never a fake-empty). A body that no longer
+            // 400s / is unreadable falls back to the generic 400 carrier unchanged.
+            if (e.toolError.upstreamStatus === 400) {
+                const fredMsg = await readFredErrorMessage(url);
+                throw new ToolErrorCarrier({
+                    kind: "invalid_input",
+                    retryable: false,
+                    message: fredMsg
+                        ? `FRED rejected the request (HTTP 400): ${fredMsg}. Check FRED_API_KEY and the series_id / parameters.`
+                        : "FRED rejected the request (HTTP 400) — check FRED_API_KEY and the series_id / parameters.",
+                    upstreamStatus: 400,
+                    upstreamEndpoint: label,
+                });
+            }
+            throw e; // 5xx → upstream_unavailable, 404 → not_found, 429 → rate_limited …
+        }
+        throw e; // SyntaxError (200 non-JSON) → the caller maps it to driftError
+    }
+}
+/** Single bare GET to read a FRED 400's `error_message` (error path ONLY). null on any failure. */
+async function readFredErrorMessage(url) {
+    try {
+        const r = await fetch(url, {
+            signal: AbortSignal.timeout(15_000),
+            redirect: "error",
+        });
+        const body = (await r.json());
+        return typeof body?.error_message === "string" ? body.error_message : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Search FRED series (`/fred/series/search`) by `search_text` → curated series
+ * rows + honest `_meta`. REQUIRES FRED_API_KEY (throws invalid_input pre-fetch when
+ * unset). totalAvailable = FRED's exact `count`; offset pagination.
+ */
+export async function searchSeries(args) {
+    // ── [KEY] REQUIRED key — throw an honest config error BEFORE any fetch. ──
+    const key = fredApiKey();
+    if (key === undefined) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: "FRED requires a free API key. Get one at https://fred.stlouisfed.org/docs/api/api_key.html and set FRED_API_KEY.",
+            upstreamEndpoint: FRED_SEARCH_LABEL,
+        });
+    }
+    // ── Validate + default (belt-and-suspenders behind the server Zod; a DIRECT
+    //    handler call bypasses Zod). ──
+    const query = args.query ?? "";
+    if (query.trim() === "") {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: "fred_search_series requires a non-empty `query` (the FRED search_text), e.g. 'unemployment rate' or 'CPI'.",
+            upstreamEndpoint: FRED_SEARCH_LABEL,
+        });
+    }
+    const limit = clampLimit(args.limit, DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT);
+    const offset = clampOffset(args.offset);
+    const params = new URLSearchParams();
+    params.set("search_text", query);
+    params.set("limit", String(limit));
+    params.set("offset", String(offset));
+    let body;
+    try {
+        body = await getFred(FRED_SEARCH_PATH, FRED_SEARCH_LABEL, params, key);
+    }
+    catch (e) {
+        if (e instanceof SyntaxError) {
+            throw driftError(FRED_SEARCH_LABEL, "FRED /series/search returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).");
+        }
+        throw e;
+    }
+    // ── [P4] `seriess` MUST be an array (a missing/non-array is drift, never a
+    //    fabricated empty). ──
+    const b = (body ?? {});
+    if (!Array.isArray(b.seriess)) {
+        throw driftError(FRED_SEARCH_LABEL, "FRED /series/search shape drift — `seriess` must be an array.");
+    }
+    const series = b.seriess.map((row) => {
+        const s = (row ?? {});
+        return {
+            id: str(s.id),
+            title: str(s.title),
+            frequency: str(s.frequency),
+            frequencyShort: str(s.frequency_short),
+            units: str(s.units),
+            seasonalAdjustment: str(s.seasonal_adjustment),
+            observationStart: str(s.observation_start),
+            observationEnd: str(s.observation_end),
+            lastUpdated: str(s.last_updated),
+            popularity: num(s.popularity),
+        };
+    });
+    const returned = series.length;
+    const totalAvailable = num(b.count); // [P1] EXACT — never returned
+    const hasMore = totalAvailable !== null && offset + returned < totalAvailable;
+    const nextOffset = hasMore ? offset + returned : null;
+    return withMeta({ series }, {
+        source: `${FRED_HOST} /fred/series/search (FRED; FRED_API_KEY)`,
+        keylessMode: false, // ★KEYED — the second key-required source
+        returned,
+        totalAvailable,
+        filtersApplied: [`query:${query}`],
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit, hasMore, nextOffset },
+        notes: [KEY_REQUIRED_NOTE, COUNT_TOTAL_NOTE],
+    });
+}
+/**
+ * Fetch a FRED series' time series (`/fred/series/observations`) → date/value rows
+ * + honest `_meta`. REQUIRES FRED_API_KEY (throws invalid_input pre-fetch when
+ * unset). ★A missing observation (`value === "."`) maps to null, never 0.
+ * totalAvailable = FRED's exact `count`; offset pagination.
+ */
+export async function seriesObservations(args) {
+    // ── [KEY] REQUIRED key — throw an honest config error BEFORE any fetch. ──
+    const key = fredApiKey();
+    if (key === undefined) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: "FRED requires a free API key. Get one at https://fred.stlouisfed.org/docs/api/api_key.html and set FRED_API_KEY.",
+            upstreamEndpoint: FRED_OBS_LABEL,
+        });
+    }
+    // ── Validate (belt-and-suspenders behind the server Zod; a DIRECT handler call
+    //    bypasses Zod — `series_id` rides the query, dates/sort_order too). ──
+    const seriesId = args.seriesId ?? "";
+    if (!SERIES_ID_RE.test(seriesId)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid seriesId ${JSON.stringify(seriesId)} — expected a FRED series id (^[A-Za-z0-9._-]+$), e.g. "GDP", "CPIAUCSL", "UNRATE".`,
+            upstreamEndpoint: FRED_OBS_LABEL,
+        });
+    }
+    if (args.startDate !== undefined && !DATE_RE.test(args.startDate)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid startDate ${JSON.stringify(args.startDate)} — expected YYYY-MM-DD (^\\d{4}-\\d{2}-\\d{2}$).`,
+            upstreamEndpoint: FRED_OBS_LABEL,
+        });
+    }
+    if (args.endDate !== undefined && !DATE_RE.test(args.endDate)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid endDate ${JSON.stringify(args.endDate)} — expected YYYY-MM-DD (^\\d{4}-\\d{2}-\\d{2}$).`,
+            upstreamEndpoint: FRED_OBS_LABEL,
+        });
+    }
+    if (args.sortOrder !== undefined && !SORT_ORDERS.has(args.sortOrder)) {
+        throw new ToolErrorCarrier({
+            kind: "invalid_input",
+            retryable: false,
+            message: `Invalid sortOrder ${JSON.stringify(args.sortOrder)} — expected one of asc, desc.`,
+            upstreamEndpoint: FRED_OBS_LABEL,
+        });
+    }
+    const limit = clampLimit(args.limit, DEFAULT_OBS_LIMIT, MAX_OBS_LIMIT);
+    const offset = clampOffset(args.offset);
+    const params = new URLSearchParams();
+    params.set("series_id", seriesId);
+    params.set("limit", String(limit));
+    params.set("offset", String(offset));
+    const filtersApplied = [`series_id:${seriesId}`];
+    if (args.startDate !== undefined) {
+        params.set("observation_start", args.startDate);
+        filtersApplied.push(`observation_start:${args.startDate}`);
+    }
+    if (args.endDate !== undefined) {
+        params.set("observation_end", args.endDate);
+        filtersApplied.push(`observation_end:${args.endDate}`);
+    }
+    if (args.sortOrder !== undefined) {
+        params.set("sort_order", args.sortOrder);
+        filtersApplied.push(`sort_order:${args.sortOrder}`);
+    }
+    let body;
+    try {
+        body = await getFred(FRED_OBS_PATH, FRED_OBS_LABEL, params, key);
+    }
+    catch (e) {
+        if (e instanceof SyntaxError) {
+            throw driftError(FRED_OBS_LABEL, "FRED /series/observations returned a non-JSON body at HTTP 200 — schema drift (never read as an empty result).");
+        }
+        throw e;
+    }
+    // ── [P4] `observations` MUST be an array. ──
+    const b = (body ?? {});
+    if (!Array.isArray(b.observations)) {
+        throw driftError(FRED_OBS_LABEL, "FRED /series/observations shape drift — `observations` must be an array.");
+    }
+    const observations = b.observations.map((row) => {
+        const o = (row ?? {});
+        return { date: str(o.date), value: fredValue(o.value) }; // ★"." ⇒ null
+    });
+    const returned = observations.length;
+    const totalAvailable = num(b.count); // [P1] EXACT — never returned
+    const hasMore = totalAvailable !== null && offset + returned < totalAvailable;
+    const nextOffset = hasMore ? offset + returned : null;
+    return withMeta({ observations }, {
+        source: `${FRED_HOST} /fred/series/observations (FRED; FRED_API_KEY)`,
+        keylessMode: false, // ★KEYED
+        returned,
+        totalAvailable,
+        filtersApplied,
+        filtersDropped: [],
+        fieldsUnavailable: [],
+        pagination: { offset, limit, hasMore, nextOffset },
+        notes: [KEY_REQUIRED_NOTE, MISSING_VALUE_NOTE, COUNT_TOTAL_NOTE],
+    });
+}
+// ─── Small shared clamps (defensive, behind the server Zod bounds) ──
+function clampLimit(v, def, max) {
+    if (typeof v !== "number" || !Number.isFinite(v))
+        return def;
+    const n = Math.floor(v);
+    if (n < 1)
+        return 1;
+    if (n > max)
+        return max;
+    return n;
+}
+function clampOffset(v) {
+    if (typeof v !== "number" || !Number.isFinite(v))
+        return 0;
+    const n = Math.floor(v);
+    return n < 0 ? 0 : n;
+}
+//# sourceMappingURL=fred.js.map

package/dist/fred.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fred.js","sourceRoot":"","sources":["../src/fred.ts"],"names":[],"mappings":"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"}

package/dist/keys.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @cliwant/mcp-sam-gov/keys — API-key discovery + `.env` auto-loading.
+ *
+ * Why this exists
+ * ----------------
+ * The server rides 31 federal sources. MOST are fully keyless. But the set of
+ * *optional* keys (raise a rate limit, unlock one filter) plus the two *required*
+ * keys (Census business-patterns, FRED) has grown to the point where a user — or
+ * the AI driving the server — cannot tell, without reading source code:
+ *   - which env var each source reads,
+ *   - whether a key is REQUIRED or merely OPTIONAL,
+ *   - where to get one (free), and
+ *   - whether it is currently configured.
+ *
+ * `apiKeyStatus()` answers all four, truthfully, WITHOUT ever revealing a key's
+ * value (only a `currentlySet` boolean). `loadDotEnv()` lets a user configure
+ * keys ONCE in a `.env` file instead of the host's env block.
+ *
+ * Grounding: every `envVar` below is the exact string the code reads via
+ * `process.env.<NAME>` — DATA_GOV_API_KEY (datagovKey.ts), SAM_GOV_API_KEY
+ * (server.ts), BLS_API_KEY (bls.ts), NVD_API_KEY (nvd.ts), SOCRATA_APP_TOKEN
+ * (socrata.ts), CENSUS_API_KEY (census-economic.ts), FRED_API_KEY (fred.ts).
+ * No invented keys, sources, or signup URLs.
+ */
+/** One registry entry describing a single API key the server can use. */
+export type KeyRegistryEntry = {
+    /** The exact `process.env.<NAME>` the code reads. */
+    envVar: string;
+    /** Human-readable source(s) this key affects. */
+    sources: string[];
+    /** true ⇒ the source has NO keyless tier (the tool throws without it). */
+    required: boolean;
+    /** Free signup URL (the user creates the account — this is their step). */
+    signupUrl: string;
+    /** What setting the key unlocks (higher limit / a filter / a whole tool). */
+    unlocks: string;
+    /** Extra honesty note (keyless fallback, precedence, scope). */
+    note: string;
+};
+/**
+ * The 7 keys the server reads — code-grounded, no inventions.
+ *
+ * REQUIRED (2): CENSUS_API_KEY, FRED_API_KEY — those sources have no keyless
+ * tier, so the tool throws without them. OPTIONAL (5): everything else works
+ * keyless; a key only raises a rate limit or unlocks a single filter.
+ */
+export declare const KEY_REGISTRY: readonly KeyRegistryEntry[];
+/** Per-key status: the registry entry + a `currentlySet` boolean. NEVER the value. */
+export type KeyStatus = KeyRegistryEntry & {
+    currentlySet: boolean;
+};
+/** The `apiKeyStatus()` result shape. */
+export type ApiKeyStatusResult = {
+    keys: KeyStatus[];
+    /** envVars of REQUIRED keys not currently set (empty ⇒ all required keys present). */
+    requiredMissing: string[];
+    /** envVars of OPTIONAL keys not currently set. */
+    optionalMissing: string[];
+    /** Every key here is free to obtain. */
+    allKeysFree: boolean;
+};
+/**
+ * Report which API keys the server can use and whether each is configured.
+ *
+ * SECURITY: the returned object carries ONLY a `currentlySet` boolean per key —
+ * the key's VALUE is NEVER read into the output. (`isSet` inspects the value to
+ * compute the boolean, but the value itself never leaves this function.)
+ */
+export declare function apiKeyStatus(): ApiKeyStatusResult;
+/**
+ * MINIMAL, dependency-free `.env` loader.
+ *
+ * Reads `${cwd||process.cwd()}/.env` if present and sets `process.env[KEY]` for
+ * each `KEY=VALUE` line — but ONLY if that key is not already set, so a real
+ * environment variable always wins over `.env` (standard precedence). Supports
+ * `export KEY=VALUE`, `#` comments, blank lines, and surrounding single/double
+ * quotes on the value. NEVER throws: a missing file returns 0 (⇒ byte-identical
+ * startup), and a malformed line is skipped rather than fatal.
+ *
+ * @returns the number of vars newly set into process.env.
+ */
+export declare function loadDotEnv(cwd?: string): number;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,gBAAgB,EAiE1C,CAAC;AAQX,sFAAsF;AACtF,MAAM,MAAM,SAAS,GAAG,gBAAgB,GAAG;IAAE,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC;AAErE,yCAAyC;AACzC,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,sFAAsF;IACtF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kDAAkD;IAClD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CAYjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CA4C/C"}