@usa-open-data-connectors/usa-sources 0.1.0

package/dist/openFdaFoodRecalls.js

@@ -0,0 +1,293 @@
+import { z } from 'zod';
+import { UsSourceApiError, UsSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/** Source name used in every error this adapter raises. */
+const OPENFDA_SOURCE_NAME = 'openfda-food-recalls';
+/** Base URL for the openFDA food enforcement endpoint. */
+export const OPENFDA_FOOD_ENFORCEMENT_BASE = 'https://api.fda.gov/food/enforcement.json';
+/**
+ * Classification FDA gives a recall that can seriously harm or kill.
+ *
+ * The endpoint carries Class I, Class II, Class III, and a handful of
+ * unclassified records; Class I is the one the story separates out.
+ */
+export const OPENFDA_CLASS_ONE = 'Class I';
+/** Initiator terms the agency uses for a firm's own recall and a mandated one. */
+export const OPENFDA_VOLUNTARY_TERM = 'Voluntary: Firm initiated';
+export const OPENFDA_MANDATED_TERM = 'FDA Mandated';
+/** Fields the adapter counts on. The endpoint carries exact-term variants. */
+export const OPENFDA_REPORT_DATE_FIELD = 'report_date';
+export const OPENFDA_CLASSIFICATION_COUNT_FIELD = 'classification.exact';
+export const OPENFDA_VOLUNTARY_COUNT_FIELD = 'voluntary_mandated.exact';
+/** Committed snapshot, so a build works when the openFDA host is unreachable. */
+const OPENFDA_FOOD_RECALL_FIXTURE_FILENAME = 'openfda-food-recalls-2026-09-30.json';
+/** Shape of the agency's date stamp, e.g. "20120620". */
+const OPENFDA_DATE_PATTERN = /^(\d{4})(\d{2})(\d{2})$/;
+// A rejected query answers with HTTP 404 or 400 and a body of
+// {error: {code, message}} instead of the data.
+const OPENFDA_ERROR_SCHEMA = z.object({
+    error: z.object({ code: z.string().optional(), message: z.string().optional() }),
+});
+const OPENFDA_COUNT_SCHEMA = z.object({
+    meta: z.object({ last_updated: z.string().optional() }).optional(),
+    results: z.array(z.object({ term: z.string(), count: z.number() })).min(1),
+});
+// A count of a date field comes back keyed by `time`; every other field is
+// keyed by `term`.
+const OPENFDA_DATE_COUNT_SCHEMA = z.object({
+    meta: z.object({ last_updated: z.string().optional() }).optional(),
+    results: z.array(z.object({ time: z.string(), count: z.number() })).min(1),
+});
+const OPENFDA_TOTAL_SCHEMA = z.object({
+    meta: z.object({ results: z.object({ total: z.number() }), last_updated: z.string().optional() }),
+});
+// The committed snapshot holds the four responses one summary needs, each
+// under the key that names the question it answers.
+const OPENFDA_FIXTURE_SCHEMA = z.object({
+    recallCount: z.number(),
+    reportDates: z.array(z.object({ time: z.string(), count: z.number() })),
+    classOneDates: z.array(z.object({ time: z.string(), count: z.number() })),
+    classifications: z.array(z.object({ term: z.string(), count: z.number() })),
+    voluntary: z.array(z.object({ term: z.string(), count: z.number() })),
+});
+/**
+ * Refuses an openFDA body that carries an error instead of data.
+ *
+ * @param payload - the JSON body from any endpoint on the host
+ */
+function throwOnOpenFdaError(payload) {
+    const parsed = OPENFDA_ERROR_SCHEMA.safeParse(payload);
+    if (parsed.success) {
+        const { code, message } = parsed.data.error;
+        throw new UsSourceApiError(OPENFDA_SOURCE_NAME, `The API rejected the query: ${code ?? 'error'} ${message ?? ''}`.trim());
+    }
+}
+/**
+ * Builds the URL that reports how many records the endpoint holds.
+ *
+ * @returns the request URL
+ */
+export function buildOpenFdaFoodRecallTotalUrl() {
+    return `${OPENFDA_FOOD_ENFORCEMENT_BASE}?limit=1`;
+}
+/**
+ * Builds the URL for one counted field, optionally inside a search.
+ *
+ * @param options - the field to count, and an optional openFDA search clause
+ * @returns the request URL
+ */
+export function buildOpenFdaFoodRecallCountUrl(options) {
+    const params = new URLSearchParams({
+        count: options?.field ?? OPENFDA_REPORT_DATE_FIELD,
+    });
+    if (options?.search !== undefined) {
+        params.set('search', options.search);
+    }
+    return `${OPENFDA_FOOD_ENFORCEMENT_BASE}?${params.toString()}`;
+}
+/**
+ * Reads the record count out of the metadata block.
+ *
+ * @param payload - the JSON body from the limit=1 request
+ * @returns how many enforcement reports the endpoint holds
+ */
+export function parseOpenFdaRecallTotal(payload) {
+    throwOnOpenFdaError(payload);
+    const parsed = OPENFDA_TOTAL_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError(OPENFDA_SOURCE_NAME, parsed.error.message);
+    }
+    return parsed.data.meta.results.total;
+}
+/**
+ * Reads one counted field into value and count pairs.
+ *
+ * @param payload - the JSON body from a count request
+ * @returns the values with their counts, in the order the agency sent them
+ */
+export function parseOpenFdaRecallCounts(payload) {
+    throwOnOpenFdaError(payload);
+    const parsed = OPENFDA_COUNT_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError(OPENFDA_SOURCE_NAME, parsed.error.message);
+    }
+    return parsed.data.results.map((entry) => ({ name: entry.term, count: entry.count }));
+}
+/**
+ * Reads a count of the date field into dated counts.
+ *
+ * @param payload - the JSON body from a count=report_date request
+ * @returns one entry per publication date, in the order the agency sent them
+ */
+export function parseOpenFdaRecallDateCounts(payload) {
+    throwOnOpenFdaError(payload);
+    const parsed = OPENFDA_DATE_COUNT_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError(OPENFDA_SOURCE_NAME, parsed.error.message);
+    }
+    return parsed.data.results.map((entry) => {
+        if (OPENFDA_DATE_PATTERN.exec(entry.time) === null) {
+            throw new UsSourceParseError(OPENFDA_SOURCE_NAME, `Unreadable publication date: ${entry.time}`);
+        }
+        return { date: entry.time, count: entry.count };
+    });
+}
+/**
+ * Reads the committed snapshot: four responses under the keys that name them.
+ *
+ * @param payload - the parsed contents of the snapshot file
+ * @returns the snapshot in the shape the summary builder reads
+ */
+export function parseOpenFdaFoodRecallSnapshot(payload) {
+    const parsed = OPENFDA_FIXTURE_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError(OPENFDA_SOURCE_NAME, parsed.error.message);
+    }
+    return {
+        recallCount: parsed.data.recallCount,
+        reportDates: parsed.data.reportDates.map((entry) => ({
+            date: entry.time,
+            count: entry.count,
+        })),
+        classOneDates: parsed.data.classOneDates.map((entry) => ({
+            date: entry.time,
+            count: entry.count,
+        })),
+        classifications: parsed.data.classifications.map((entry) => ({
+            name: entry.term,
+            count: entry.count,
+        })),
+        voluntary: parsed.data.voluntary.map((entry) => ({ name: entry.term, count: entry.count })),
+    };
+}
+/** Sums the counts of a dated or named list. */
+function sumCounts(entries) {
+    return entries.reduce((total, entry) => total + entry.count, 0);
+}
+/** Counts one dated list by calendar year. */
+function countByYear(entries) {
+    const byYear = new Map();
+    for (const entry of entries) {
+        const year = Number(entry.date.slice(0, 4));
+        byYear.set(year, (byYear.get(year) ?? 0) + entry.count);
+    }
+    return byYear;
+}
+/** Turns the agency's date stamp into the ISO date a reader recognises. */
+export function openFdaReportDateLabel(date) {
+    const match = OPENFDA_DATE_PATTERN.exec(date);
+    if (match === null) {
+        throw new UsSourceParseError(OPENFDA_SOURCE_NAME, `Unreadable publication date: ${date}`);
+    }
+    return `${match[1] ?? ''}-${match[2] ?? ''}-${match[3] ?? ''}`;
+}
+/**
+ * Folds the four responses into the per-year counts a story reads.
+ *
+ * Every recall in the file carries a publication date and a classification,
+ * so the two counts have to agree: a snapshot whose dates cover fewer recalls
+ * than the metadata reports is refused rather than charted short.
+ *
+ * @param snapshot - the counted responses, all from the same day
+ * @returns the per-year counts and the figures the copy quotes
+ */
+export function buildOpenFdaFoodRecallSummary(snapshot) {
+    const { recallCount, reportDates, classOneDates, classifications, voluntary } = snapshot;
+    if (reportDates.length === 0) {
+        throw new UsSourceParseError(OPENFDA_SOURCE_NAME, 'No publication dates to summarise');
+    }
+    const datedTotal = sumCounts(reportDates);
+    if (datedTotal !== recallCount) {
+        throw new UsSourceParseError(OPENFDA_SOURCE_NAME, `The publication dates cover ${String(datedTotal)} recalls and the endpoint reports ${String(recallCount)}`);
+    }
+    const classOneTotal = sumCounts(classOneDates);
+    const classOneInCounts = classifications.find((entry) => entry.name === OPENFDA_CLASS_ONE)?.count;
+    if (classOneInCounts !== undefined && classOneInCounts !== classOneTotal) {
+        throw new UsSourceParseError(OPENFDA_SOURCE_NAME, `The Class I dates cover ${String(classOneTotal)} recalls and the classification count reports ${String(classOneInCounts)}`);
+    }
+    const totalByYear = countByYear(reportDates);
+    const classOneByYear = countByYear(classOneDates);
+    const years = [...totalByYear.entries()]
+        .map(([year, total]) => {
+        const classOne = classOneByYear.get(year) ?? 0;
+        return { year, total, classOne, other: total - classOne };
+    })
+        .sort((left, right) => left.year - right.year);
+    const busiestYear = years.reduce((busiest, year) => year.total > busiest.total ? year : busiest);
+    const first = years[0];
+    const last = years[years.length - 1];
+    if (first === undefined || last === undefined) {
+        throw new UsSourceParseError(OPENFDA_SOURCE_NAME, 'No years to summarise');
+    }
+    const firstDate = reportDates[0];
+    const lastDate = reportDates[reportDates.length - 1];
+    if (firstDate === undefined || lastDate === undefined) {
+        throw new UsSourceParseError(OPENFDA_SOURCE_NAME, 'No publication dates to summarise');
+    }
+    return {
+        recallCount,
+        reportDateCount: reportDates.length,
+        firstReportDate: openFdaReportDateLabel(firstDate.date),
+        newestReportDate: openFdaReportDateLabel(lastDate.date),
+        firstYear: first.year,
+        newestYear: last.year,
+        newestYearCount: last.total,
+        years,
+        busiestYear,
+        classOneCount: classOneTotal,
+        classOneSharePercent: (classOneTotal / recallCount) * 100,
+        classifications,
+        voluntaryCount: voluntary.find((entry) => entry.name === OPENFDA_VOLUNTARY_TERM)?.count ?? 0,
+        mandatedCount: voluntary.find((entry) => entry.name === OPENFDA_MANDATED_TERM)?.count ?? 0,
+    };
+}
+/** Reads one URL as JSON, refusing a response the host did not deliver. */
+async function fetchOpenFdaJson(url, fetchImpl) {
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new UsSourceApiError(OPENFDA_SOURCE_NAME, `HTTP ${response.status} reading ${url}`);
+    }
+    return response.json();
+}
+/**
+ * Reads the food enforcement file as four counted responses.
+ *
+ * Keyless. The endpoint answers one question per request and cannot group by
+ * two fields at once, so the per-year Class I counts come from a second date
+ * count under a search clause. Without an API key the endpoint allows 240
+ * requests a minute and 1,000 a day, and five requests cover the whole file.
+ *
+ * @param options - an optional fetch stub
+ * @returns the per-year counts and the figures the copy quotes
+ */
+export async function fetchOpenFdaFoodRecalls(options) {
+    const fetchImpl = options?.fetchImpl ?? globalThis.fetch;
+    const [totalPayload, reportDatePayload, classOneDatePayload, classPayload, voluntaryPayload] = await Promise.all([
+        fetchOpenFdaJson(buildOpenFdaFoodRecallTotalUrl(), fetchImpl),
+        fetchOpenFdaJson(buildOpenFdaFoodRecallCountUrl({ field: OPENFDA_REPORT_DATE_FIELD }), fetchImpl),
+        fetchOpenFdaJson(buildOpenFdaFoodRecallCountUrl({
+            field: OPENFDA_REPORT_DATE_FIELD,
+            search: `classification:"${OPENFDA_CLASS_ONE}"`,
+        }), fetchImpl),
+        fetchOpenFdaJson(buildOpenFdaFoodRecallCountUrl({ field: OPENFDA_CLASSIFICATION_COUNT_FIELD }), fetchImpl),
+        fetchOpenFdaJson(buildOpenFdaFoodRecallCountUrl({ field: OPENFDA_VOLUNTARY_COUNT_FIELD }), fetchImpl),
+    ]);
+    return buildOpenFdaFoodRecallSummary({
+        recallCount: parseOpenFdaRecallTotal(totalPayload),
+        reportDates: parseOpenFdaRecallDateCounts(reportDatePayload),
+        classOneDates: parseOpenFdaRecallDateCounts(classOneDatePayload),
+        classifications: parseOpenFdaRecallCounts(classPayload),
+        voluntary: parseOpenFdaRecallCounts(voluntaryPayload),
+    });
+}
+/** openFDA food enforcement reports, keyless. */
+export const openFdaFoodRecallsAdapter = {
+    id: 'openfda-food-recalls',
+    name: 'openFDA food enforcement reports',
+    auth: 'none',
+    description: 'Every food recall FDA has published as an enforcement report, one record per recall, from June 2012 to the newest publication date.',
+    fetchLive: async (options) => fetchOpenFdaFoodRecalls(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: (payload) => buildOpenFdaFoodRecallSummary(parseOpenFdaFoodRecallSnapshot(payload)),
+    loadFixture: () => buildOpenFdaFoodRecallSummary(parseOpenFdaFoodRecallSnapshot(readFixtureJson(OPENFDA_FOOD_RECALL_FIXTURE_FILENAME))),
+};
+//# sourceMappingURL=openFdaFoodRecalls.js.map

package/dist/openFdaFoodRecalls.js.map

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

package/dist/registry.d.ts

@@ -0,0 +1,28 @@
+import type { UsDataAdapter, UsSourceProbe } from './types.js';
+/** Every US data source behind the uniform adapter interface. */
+export declare const US_DATA_SOURCES: UsDataAdapter<unknown>[];
+/** Looks up a source adapter by id. */
+export declare function getUsDataSource<T>(id: string): UsDataAdapter<T> | undefined;
+/**
+ * Probes one source with a live fetch and reports the outcome.
+ *
+ * @param adapter - the adapter to exercise
+ * @param options - an optional API key and fetch stub
+ * @returns whether the source answered, plus what it said
+ */
+export declare function probeUsDataSource<T>(adapter: UsDataAdapter<T>, options?: {
+    apiKey?: string;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<UsSourceProbe>;
+/**
+ * Probes every registered source in parallel, with optional per-source keys.
+ *
+ * @param options - a shared key, per-source keys, and a fetch stub
+ * @returns one probe result per registered source
+ */
+export declare function probeAllUsDataSources(options?: {
+    apiKey?: string;
+    apiKeys?: Record<string, string>;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<UsSourceProbe[]>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,aAAa,EAAkB,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/E,iEAAiE;AACjE,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC,OAAO,CAAC,EAYnD,CAAC;AAEF,uCAAuC;AACvC,wBAAgB,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,CAE3E;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EACzB,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAAE,GACjE,OAAO,CAAC,aAAa,CAAC,CAwBxB;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,CAAC,EAAE;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAW3B"}

package/dist/registry.js

@@ -0,0 +1,79 @@
+import { blsUnemploymentAdapter } from './blsSeries.js';
+import { cdcCountyObesityAdapter } from './cdcCountyObesity.js';
+import { cfpbConsumerComplaintsAdapter } from './cfpbConsumerComplaints.js';
+import { cpscProductRecallsAdapter } from './cpscProductRecalls.js';
+import { femaDisasterDeclarationsAdapter } from './femaDisasterDeclarations.js';
+import { nceiAnnualTemperatureAdapter } from './nceiAnnualTemperature.js';
+import { noaaSeaLevelAdapter } from './noaaSeaLevel.js';
+import { openFdaFoodRecallsAdapter } from './openFdaFoodRecalls.js';
+import { treasuryAvgInterestRateAdapter } from './treasuryAvgInterestRate.js';
+import { usgsHawaiiEarthquakesAdapter } from './usgsEarthquakes.js';
+import { usgsPeakStreamflowAdapter } from './usgsPeakStreamflow.js';
+/** Every US data source behind the uniform adapter interface. */
+export const US_DATA_SOURCES = [
+    blsUnemploymentAdapter,
+    usgsHawaiiEarthquakesAdapter,
+    cdcCountyObesityAdapter,
+    nceiAnnualTemperatureAdapter,
+    noaaSeaLevelAdapter,
+    treasuryAvgInterestRateAdapter,
+    femaDisasterDeclarationsAdapter,
+    openFdaFoodRecallsAdapter,
+    usgsPeakStreamflowAdapter,
+    cpscProductRecallsAdapter,
+    cfpbConsumerComplaintsAdapter,
+];
+/** Looks up a source adapter by id. */
+export function getUsDataSource(id) {
+    return US_DATA_SOURCES.find((source) => source.id === id);
+}
+/**
+ * Probes one source with a live fetch and reports the outcome.
+ *
+ * @param adapter - the adapter to exercise
+ * @param options - an optional API key and fetch stub
+ * @returns whether the source answered, plus what it said
+ */
+export async function probeUsDataSource(adapter, options) {
+    try {
+        const fetchOptions = {
+            ...(options?.apiKey === undefined ? {} : { apiKey: options.apiKey }),
+            ...(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+        };
+        const data = await adapter.fetchLive(fetchOptions);
+        return {
+            id: adapter.id,
+            name: adapter.name,
+            auth: adapter.auth,
+            ok: true,
+            status: 'ok',
+            sample: JSON.stringify(data).slice(0, 120),
+        };
+    }
+    catch (error) {
+        return {
+            id: adapter.id,
+            name: adapter.name,
+            auth: adapter.auth,
+            ok: false,
+            status: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Probes every registered source in parallel, with optional per-source keys.
+ *
+ * @param options - a shared key, per-source keys, and a fetch stub
+ * @returns one probe result per registered source
+ */
+export async function probeAllUsDataSources(options) {
+    const { apiKey, apiKeys, fetchImpl } = options ?? {};
+    return Promise.all(US_DATA_SOURCES.map((source) => {
+        const key = apiKeys?.[source.id] ?? apiKey;
+        return probeUsDataSource(source, {
+            ...(key === undefined ? {} : { apiKey: key }),
+            ...(fetchImpl === undefined ? {} : { fetchImpl }),
+        });
+    }));
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

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

package/dist/treasuryAvgInterestRate.d.ts

@@ -0,0 +1,107 @@
+import type { UsDataAdapter } from './types.js';
+/** One month of the average interest rate the Treasury pays on its debt. */
+export interface TreasuryInterestRateMonth {
+    /** The agency's own date for the row, e.g. "2026-08-31". */
+    recordDate: string;
+    /** Calendar year the month belongs to. */
+    year: number;
+    /** Calendar month, 1 for January. */
+    month: number;
+    /**
+     * Average interest rate on the interest-bearing debt outstanding that
+     * month, in percent. The agency averages every security in the portfolio,
+     * so it is the rate the whole debt carries rather than the rate on
+     * anything issued today.
+     */
+    averageInterestRatePercent: number;
+}
+/** One published run of the rate, folded down to the points a story leans on. */
+export interface TreasuryInterestRateSeries {
+    /** One entry per month with a value, oldest first. */
+    months: TreasuryInterestRateMonth[];
+    monthCount: number;
+    firstMonth: TreasuryInterestRateMonth;
+    lastMonth: TreasuryInterestRateMonth;
+    highest: TreasuryInterestRateMonth;
+    lowest: TreasuryInterestRateMonth;
+    /** Latest month minus the lowest month, in percentage points. */
+    changeSinceLowPercentPoints: number;
+    /** Latest month minus the first month, in percentage points. */
+    changeFirstToLastPercentPoints: number;
+}
+/** Base URL for the Treasury Fiscal Data API. */
+export declare const TREASURY_FISCAL_DATA_API_BASE = "https://api.fiscaldata.treasury.gov/services/api/fiscal_service";
+/** Dataset path for the average interest rates on Treasury securities. */
+export declare const TREASURY_AVG_INTEREST_RATE_PATH = "/v2/accounting/od/avg_interest_rates";
+/**
+ * Security type the adapter reads.
+ *
+ * "Interest-bearing Debt" holds the portfolio totals, the same rows the
+ * bureau's monthly statement is built from, rather than the rates on the
+ * bills, notes, and bonds issued today.
+ */
+export declare const TREASURY_AVG_INTEREST_RATE_SECURITY_TYPE = "Interest-bearing Debt";
+/** Security description that carries the whole portfolio's average rate. */
+export declare const TREASURY_AVG_INTEREST_RATE_SECURITY_DESCRIPTION = "Total Interest-bearing Debt";
+/** First year the dataset covers. */
+export declare const TREASURY_AVG_INTEREST_RATE_FIRST_YEAR = 2001;
+/**
+ * Row cap for one request.
+ *
+ * The API returns at most 10,000 rows a page and the series is around 300
+ * rows, so one request covers the whole run and the adapter never pages.
+ */
+export declare const TREASURY_AVG_INTEREST_RATE_ROW_LIMIT = 10000;
+/**
+ * Builds the request URL for the whole published series.
+ *
+ * The filter pins the response to the portfolio's own total, so the rows for
+ * bills, notes, bonds, and the non-marketable debt never reach the parser.
+ * The endpoint is keyless.
+ *
+ * @param options - an optional security type and row cap
+ * @returns the full request URL
+ */
+export declare function buildTreasuryAvgInterestRateUrl(options?: {
+    securityType?: string;
+    rowLimit?: number;
+}): string;
+/**
+ * Parses one response into the months that carry a rate.
+ *
+ * A row for another security type is a changed filter and stops the parse,
+ * so a response that ignored the filter cannot quietly widen the series. A
+ * row without a rate is dropped, which is how a month the agency could not
+ * compute would arrive. A row without a readable date is a changed shape and
+ * also stops the parse.
+ *
+ * @param payload - the JSON body from the Fiscal Data API
+ * @returns the months that carry a rate, in the order the agency sent them
+ */
+export declare function parseTreasuryAvgInterestRatePayload(payload: unknown): TreasuryInterestRateMonth[];
+/**
+ * Folds the parsed months into one series with the headline months named.
+ *
+ * The months are sorted oldest first, so a caller reading index 0 gets the
+ * start of the run and index -1 gets the newest month.
+ *
+ * @param months - the parsed months, in any order
+ * @returns the sorted months, the highest and lowest in the run, and the change
+ */
+export declare function buildTreasuryAvgInterestRateSeries(months: TreasuryInterestRateMonth[]): TreasuryInterestRateSeries;
+/**
+ * Reads the average interest rate on the Treasury's interest-bearing debt.
+ *
+ * One keyless request covers the whole published run, which starts in
+ * January 2001 and answers one row per month.
+ *
+ * @param options - an optional security type and fetch stub
+ * @returns the monthly rates, the highest and lowest months, and the change
+ */
+export declare function fetchTreasuryAvgInterestRates(options?: {
+    securityType?: string;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<TreasuryInterestRateSeries>;
+/** US Treasury average interest rate on the debt outstanding, keyless. */
+export declare const treasuryAvgInterestRateAdapter: UsDataAdapter<TreasuryInterestRateSeries>;
+//# sourceMappingURL=treasuryAvgInterestRate.d.ts.map

package/dist/treasuryAvgInterestRate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treasuryAvgInterestRate.d.ts","sourceRoot":"","sources":["../src/treasuryAvgInterestRate.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,4EAA4E;AAC5E,MAAM,WAAW,yBAAyB;IACxC,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,0BAA0B,EAAE,MAAM,CAAC;CACpC;AAED,iFAAiF;AACjF,MAAM,WAAW,0BAA0B;IACzC,sDAAsD;IACtD,MAAM,EAAE,yBAAyB,EAAE,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,yBAAyB,CAAC;IACtC,SAAS,EAAE,yBAAyB,CAAC;IACrC,OAAO,EAAE,yBAAyB,CAAC;IACnC,MAAM,EAAE,yBAAyB,CAAC;IAClC,iEAAiE;IACjE,2BAA2B,EAAE,MAAM,CAAC;IACpC,gEAAgE;IAChE,8BAA8B,EAAE,MAAM,CAAC;CACxC;AAED,iDAAiD;AACjD,eAAO,MAAM,6BAA6B,oEACyB,CAAC;AAEpE,0EAA0E;AAC1E,eAAO,MAAM,+BAA+B,yCAAyC,CAAC;AAEtF;;;;;;GAMG;AACH,eAAO,MAAM,wCAAwC,0BAA0B,CAAC;AAEhF,4EAA4E;AAC5E,eAAO,MAAM,+CAA+C,gCAAgC,CAAC;AAE7F,qCAAqC;AACrC,eAAO,MAAM,qCAAqC,OAAO,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,QAAS,CAAC;AA4B3D;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,CAAC,EAAE;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,CAQT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mCAAmC,CAAC,OAAO,EAAE,OAAO,GAAG,yBAAyB,EAAE,CAmEjG;AAED;;;;;;;;GAQG;AACH,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,yBAAyB,EAAE,GAClC,0BAA0B,CA+B5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,6BAA6B,CAAC,OAAO,CAAC,EAAE;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAetC;AAED,0EAA0E;AAC1E,eAAO,MAAM,8BAA8B,EAAE,aAAa,CAAC,0BAA0B,CAkBpF,CAAC"}