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

package/dist/cdcCountyObesity.d.ts

@@ -0,0 +1,116 @@
+import type { UsDataAdapter } from './types.js';
+/** One county's model-based obesity estimate from the CDC PLACES release. */
+export interface CdcCountyObesityEstimate {
+    /** County name on its own, such as "Boulder". */
+    countyName: string;
+    /** Two-letter state postal code, such as "CO". */
+    stateAbbr: string;
+    /** Share of adults with obesity, as a percentage. */
+    percent: number;
+    /** Population the estimate covers. */
+    population: number;
+}
+/** The release's own national row, kept apart from the counties. */
+export interface CdcNationalObesityEstimate {
+    percent: number;
+    population: number;
+}
+/** One response, split into county rows and the national row. */
+export interface CdcCountyObesityPayload {
+    /** Counties with an estimate, lowest share of obesity first. */
+    counties: CdcCountyObesityEstimate[];
+    /** The national row, or null when the response carried none. */
+    national: CdcNationalObesityEstimate | null;
+    /** The survey year the estimates describe, or null when no row carried one. */
+    dataYear: number | null;
+}
+/** One release's estimates, folded down to the points a story leans on. */
+export interface CdcCountyObesitySet {
+    /** Counties with an estimate, lowest share of obesity first. */
+    counties: CdcCountyObesityEstimate[];
+    countyCount: number;
+    lowest: CdcCountyObesityEstimate;
+    highest: CdcCountyObesityEstimate;
+    national: CdcNationalObesityEstimate;
+    dataYear: number;
+}
+/**
+ * Socrata resource for the CDC PLACES county release this adapter reads.
+ *
+ * The id is per release: the 2025 release, whose estimates come from the 2023
+ * Behavioral Risk Factor Surveillance System (BRFSS) and the Census Bureau's
+ * 2023 county population estimates. A new release gets a new id, so a story
+ * pinned to this one keeps reading the numbers it was written against.
+ */
+export declare const CDC_PLACES_COUNTY_API_BASE = "https://data.cdc.gov/resource/swc5-untb.json";
+/** PLACES measure id for obesity among adults. */
+export declare const CDC_PLACES_OBESITY_MEASURE_ID = "OBESITY";
+/**
+ * PLACES value type id for crude prevalence.
+ *
+ * The same measure is also published age-adjusted, which would put two rows
+ * per county. The crude row is the one a story about places can compare.
+ */
+export declare const CDC_PLACES_CRUDE_PREVALENCE_ID = "CrdPrv";
+/** State code the release uses for its own national row. */
+export declare const CDC_PLACES_NATIONAL_STATE_CODE = "US";
+/** Row cap for one query. The release holds just under three thousand rows. */
+export declare const CDC_PLACES_COUNTY_ROW_LIMIT = 5000;
+/**
+ * Builds the query URL for the county obesity estimates.
+ *
+ * One request covers the whole release. The endpoint is keyless, and the
+ * filter holds the response to a single measure at crude prevalence, which
+ * is what keeps it near three thousand rows rather than thirty thousand.
+ *
+ * @param options - an optional row cap, for tests
+ * @returns the full query URL
+ */
+export declare function buildCdcCountyObesityUrl(options?: {
+    rowLimit?: number;
+}): string;
+/**
+ * Sorts counties by their obesity estimate, lowest first.
+ *
+ * The state and county name break a tie, so the order is stable across runs
+ * and a reader comparing two builds sees the same list.
+ *
+ * @param counties - county estimates in any order
+ * @returns the same estimates, lowest share of obesity first
+ */
+export declare function sortCdcCountiesByPercent(counties: CdcCountyObesityEstimate[]): CdcCountyObesityEstimate[];
+/**
+ * Parses one PLACES response into county rows and the national row.
+ *
+ * Two shapes in the release need handling before the rows are usable. A
+ * county the model could not estimate arrives with no value at all, which is
+ * how the smallest counties come back. The national row arrives with no
+ * county name, and the only thing marking it is the "US" state code, so it is
+ * pulled out separately rather than counted as a county.
+ *
+ * @param payload - the JSON body from the PLACES resource endpoint
+ * @returns the county estimates, the national row, and the survey year
+ */
+export declare function parseCdcCountyObesityPayload(payload: unknown): CdcCountyObesityPayload;
+/**
+ * Folds a parsed response into one set with its headline counties.
+ *
+ * @param payload - the parsed PLACES response
+ * @returns the counties, the lowest and highest, and the national row
+ */
+export declare function buildCdcCountyObesitySet(payload: CdcCountyObesityPayload): CdcCountyObesitySet;
+/**
+ * Reads the county obesity estimates from CDC PLACES.
+ *
+ * Keyless, one request. There is no window to choose: the resource always
+ * answers the release it belongs to.
+ *
+ * @param options - an optional fetch stub
+ * @returns the county estimates, the national row, and the survey year
+ */
+export declare function fetchCdcCountyObesity(options?: {
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<CdcCountyObesityPayload>;
+/** CDC PLACES county obesity estimates, keyless. */
+export declare const cdcCountyObesityAdapter: UsDataAdapter<CdcCountyObesitySet>;
+//# sourceMappingURL=cdcCountyObesity.d.ts.map

package/dist/cdcCountyObesity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdcCountyObesity.d.ts","sourceRoot":"","sources":["../src/cdcCountyObesity.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,oEAAoE;AACpE,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iEAAiE;AACjE,MAAM,WAAW,uBAAuB;IACtC,gEAAgE;IAChE,QAAQ,EAAE,wBAAwB,EAAE,CAAC;IACrC,gEAAgE;IAChE,QAAQ,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAC5C,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,QAAQ,EAAE,wBAAwB,EAAE,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,wBAAwB,CAAC;IACjC,OAAO,EAAE,wBAAwB,CAAC;IAClC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,iDAAiD,CAAC;AAEzF,kDAAkD;AAClD,eAAO,MAAM,6BAA6B,YAAY,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,WAAW,CAAC;AAEvD,4DAA4D;AAC5D,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAEnD,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,OAAO,CAAC;AA0BhD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAOhF;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,wBAAwB,EAAE,GACnC,wBAAwB,EAAE,CAU5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,uBAAuB,CAoCtF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,uBAAuB,GAAG,mBAAmB,CAc9F;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,CAAC,EAAE;IACpD,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAOnC;AAED,oDAAoD;AACpD,eAAO,MAAM,uBAAuB,EAAE,aAAa,CAAC,mBAAmB,CAiBtE,CAAC"}

package/dist/cdcCountyObesity.js

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+import { UsSourceApiError, UsSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/**
+ * Socrata resource for the CDC PLACES county release this adapter reads.
+ *
+ * The id is per release: the 2025 release, whose estimates come from the 2023
+ * Behavioral Risk Factor Surveillance System (BRFSS) and the Census Bureau's
+ * 2023 county population estimates. A new release gets a new id, so a story
+ * pinned to this one keeps reading the numbers it was written against.
+ */
+export const CDC_PLACES_COUNTY_API_BASE = 'https://data.cdc.gov/resource/swc5-untb.json';
+/** PLACES measure id for obesity among adults. */
+export const CDC_PLACES_OBESITY_MEASURE_ID = 'OBESITY';
+/**
+ * PLACES value type id for crude prevalence.
+ *
+ * The same measure is also published age-adjusted, which would put two rows
+ * per county. The crude row is the one a story about places can compare.
+ */
+export const CDC_PLACES_CRUDE_PREVALENCE_ID = 'CrdPrv';
+/** State code the release uses for its own national row. */
+export const CDC_PLACES_NATIONAL_STATE_CODE = 'US';
+/** Row cap for one query. The release holds just under three thousand rows. */
+export const CDC_PLACES_COUNTY_ROW_LIMIT = 5000;
+/** Columns the adapter asks for. The release carries many more. */
+const CDC_PLACES_COLUMNS = 'locationname,stateabbr,data_value,totalpopulation,year';
+// Socrata sends every column as a string and leaves a key out when the value
+// is missing, so each field is optional and the numbers are read defensively.
+const CDC_PLACES_ROW_SCHEMA = z.object({
+    locationname: z.string().optional(),
+    stateabbr: z.string().optional(),
+    data_value: z.string().optional(),
+    totalpopulation: z.string().optional(),
+    year: z.string().optional(),
+});
+const CDC_PLACES_RESPONSE_SCHEMA = z.array(CDC_PLACES_ROW_SCHEMA);
+/** Reads a numeric field the release sends as a string, or undefined. */
+function readCdcNumber(value) {
+    if (value === undefined || value.trim() === '') {
+        return undefined;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+/**
+ * Builds the query URL for the county obesity estimates.
+ *
+ * One request covers the whole release. The endpoint is keyless, and the
+ * filter holds the response to a single measure at crude prevalence, which
+ * is what keeps it near three thousand rows rather than thirty thousand.
+ *
+ * @param options - an optional row cap, for tests
+ * @returns the full query URL
+ */
+export function buildCdcCountyObesityUrl(options) {
+    const params = new URLSearchParams({
+        $select: CDC_PLACES_COLUMNS,
+        $where: `measureid='${CDC_PLACES_OBESITY_MEASURE_ID}' AND datavaluetypeid='${CDC_PLACES_CRUDE_PREVALENCE_ID}'`,
+        $limit: String(options?.rowLimit ?? CDC_PLACES_COUNTY_ROW_LIMIT),
+    });
+    return `${CDC_PLACES_COUNTY_API_BASE}?${params.toString()}`;
+}
+/**
+ * Sorts counties by their obesity estimate, lowest first.
+ *
+ * The state and county name break a tie, so the order is stable across runs
+ * and a reader comparing two builds sees the same list.
+ *
+ * @param counties - county estimates in any order
+ * @returns the same estimates, lowest share of obesity first
+ */
+export function sortCdcCountiesByPercent(counties) {
+    return [...counties].sort((left, right) => {
+        if (left.percent !== right.percent) {
+            return left.percent - right.percent;
+        }
+        if (left.stateAbbr !== right.stateAbbr) {
+            return left.stateAbbr.localeCompare(right.stateAbbr);
+        }
+        return left.countyName.localeCompare(right.countyName);
+    });
+}
+/**
+ * Parses one PLACES response into county rows and the national row.
+ *
+ * Two shapes in the release need handling before the rows are usable. A
+ * county the model could not estimate arrives with no value at all, which is
+ * how the smallest counties come back. The national row arrives with no
+ * county name, and the only thing marking it is the "US" state code, so it is
+ * pulled out separately rather than counted as a county.
+ *
+ * @param payload - the JSON body from the PLACES resource endpoint
+ * @returns the county estimates, the national row, and the survey year
+ */
+export function parseCdcCountyObesityPayload(payload) {
+    const parsed = CDC_PLACES_RESPONSE_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError('cdc', parsed.error.message);
+    }
+    const counties = [];
+    let national = null;
+    let dataYear = null;
+    for (const row of parsed.data) {
+        const percent = readCdcNumber(row.data_value);
+        const population = readCdcNumber(row.totalpopulation);
+        const year = readCdcNumber(row.year);
+        if (year !== undefined && Number.isInteger(year)) {
+            dataYear = dataYear === null ? year : Math.max(dataYear, year);
+        }
+        if (percent === undefined || population === undefined) {
+            continue;
+        }
+        if (row.stateabbr === CDC_PLACES_NATIONAL_STATE_CODE) {
+            national = { percent, population };
+            continue;
+        }
+        if (row.locationname === undefined || row.stateabbr === undefined) {
+            continue;
+        }
+        counties.push({
+            countyName: row.locationname,
+            stateAbbr: row.stateabbr,
+            percent,
+            population,
+        });
+    }
+    return { counties: sortCdcCountiesByPercent(counties), national, dataYear };
+}
+/**
+ * Folds a parsed response into one set with its headline counties.
+ *
+ * @param payload - the parsed PLACES response
+ * @returns the counties, the lowest and highest, and the national row
+ */
+export function buildCdcCountyObesitySet(payload) {
+    const { counties, national, dataYear } = payload;
+    const lowest = counties[0];
+    const highest = counties[counties.length - 1];
+    if (lowest === undefined || highest === undefined) {
+        throw new UsSourceParseError('cdc', 'No county estimates in the response');
+    }
+    if (national === null) {
+        throw new UsSourceParseError('cdc', 'The response carried no national row');
+    }
+    if (dataYear === null) {
+        throw new UsSourceParseError('cdc', 'The response carried no survey year');
+    }
+    return { counties, countyCount: counties.length, lowest, highest, national, dataYear };
+}
+/**
+ * Reads the county obesity estimates from CDC PLACES.
+ *
+ * Keyless, one request. There is no window to choose: the resource always
+ * answers the release it belongs to.
+ *
+ * @param options - an optional fetch stub
+ * @returns the county estimates, the national row, and the survey year
+ */
+export async function fetchCdcCountyObesity(options) {
+    const fetchImpl = options?.fetchImpl ?? globalThis.fetch;
+    const response = await fetchImpl(buildCdcCountyObesityUrl());
+    if (!response.ok) {
+        throw new UsSourceApiError('cdc', `HTTP ${response.status} reading the county estimates`);
+    }
+    return parseCdcCountyObesityPayload(await response.json());
+}
+/** CDC PLACES county obesity estimates, keyless. */
+export const cdcCountyObesityAdapter = {
+    id: 'cdc-county-obesity',
+    name: 'CDC county adult obesity',
+    auth: 'none',
+    description: 'Model-based share of adults with obesity in each US county, from the CDC PLACES release.',
+    fetchLive: async (options) => buildCdcCountyObesitySet(await fetchCdcCountyObesity({
+        ...(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    })),
+    parse: (payload) => buildCdcCountyObesitySet(parseCdcCountyObesityPayload(payload)),
+    loadFixture: () => buildCdcCountyObesitySet(parseCdcCountyObesityPayload(readFixtureJson('cdc-county-obesity-2026-09-25.json'))),
+};
+//# sourceMappingURL=cdcCountyObesity.js.map

package/dist/cdcCountyObesity.js.map

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

package/dist/cfpbConsumerComplaints.d.ts

@@ -0,0 +1,152 @@
+import type { UsDataAdapter } from './types.js';
+/** One calendar year of complaints. */
+export interface CfpComplaintYearCount {
+    year: number;
+    complaintCount: number;
+}
+/** One company and how many complaints name it. */
+export interface CfpComplaintCompanyCount {
+    company: string;
+    complaintCount: number;
+}
+/** One product and how many complaints sit under it. */
+export interface CfpComplaintProductCount {
+    product: string;
+    complaintCount: number;
+}
+/** The complaint file folded into the shape a story reads. */
+export interface CfpConsumerComplaintSeries {
+    firstYear: number;
+    /** Newest year in the window. The bureau is still filling it. */
+    newestYear: number;
+    /** Date of the newest complaint in the file, e.g. "2026-10-02". */
+    newestReceivedDate: string;
+    /** Complaints counted across the window. */
+    totalComplaints: number;
+    /** One entry per year in the window, oldest first. */
+    years: CfpComplaintYearCount[];
+    /** Years in the window before the newest one. */
+    completeYearCount: number;
+    /** Busiest of the years before the newest one. */
+    busiestCompleteYear: CfpComplaintYearCount;
+    /** Quietest of the years before the newest one. */
+    quietestCompleteYear: CfpComplaintYearCount;
+    /** Products, most complaints first. */
+    topProducts: CfpComplaintProductCount[];
+    /** Companies, most complaints first. */
+    topCompanies: CfpComplaintCompanyCount[];
+}
+/** Base URL for the Consumer Complaint Database search API. */
+export declare const CFPB_COMPLAINT_SEARCH_API_BASE = "https://www.consumerfinance.gov/data-research/consumer-complaints/search/api/v1/";
+/**
+ * First calendar year the adapter reads.
+ *
+ * The bureau published its first complaints on 1 December 2011, so that year
+ * holds one month. The window keeps it rather than dropping it, and the data
+ * note on the page says the first bar covers December only.
+ */
+export declare const CFPB_COMPLAINT_FIRST_YEAR = 2011;
+/**
+ * How many days back the newest-complaint probe walks.
+ *
+ * The bureau adds complaints every day, but the newest one is normally filed
+ * within the last day or two. The probe walks back from today and stops at
+ * the first day with a complaint, so a quiet weekend costs a few requests.
+ */
+export declare const CFPB_NEWEST_DATE_PROBE_DAYS = 14;
+/** How many products and companies one fetch keeps. */
+export declare const CFPB_TOP_LIST_LIMIT = 10;
+/**
+ * Builds the request URL for one calendar year of complaint totals.
+ *
+ * `no_aggs=true` drops the term aggregations the search API computes by
+ * default, which takes the response from several hundred kilobytes to about
+ * fifteen, and `size=0` drops the rows.
+ *
+ * @param year - the calendar year to read
+ * @returns the full request URL
+ */
+export declare function buildCfpComplaintCountUrl(year: number): string;
+/**
+ * Builds the request URL for one day of complaint totals.
+ *
+ * @param isoDate - the day to read, e.g. "2026-10-02"
+ * @returns the full request URL
+ */
+export declare function buildCfpComplaintDayUrl(isoDate: string): string;
+/**
+ * Builds the request URL for the product and company tallies.
+ *
+ * @returns the full request URL
+ */
+export declare function buildCfpComplaintAggregationUrl(): string;
+/**
+ * Reads the total complaint count out of a totals-only response.
+ *
+ * @param payload - the JSON body from the search API
+ * @returns the number of complaints the query matched
+ */
+export declare function parseCfpComplaintTotal(payload: unknown): number;
+/**
+ * Reads the product and company tallies out of an aggregation response.
+ *
+ * @param payload - the JSON body from the search API with aggregations
+ * @returns products and companies, most complaints first
+ */
+export declare function parseCfpComplaintAggregations(payload: unknown): {
+    topProducts: CfpComplaintProductCount[];
+    topCompanies: CfpComplaintCompanyCount[];
+};
+/**
+ * Folds one window of year counts into the series a story reads.
+ *
+ * The newest year in the window is the year the bureau is still filling, so
+ * the busiest and quietest years are picked from the years before it.
+ *
+ * @param input - the year rows and the tallies read alongside them
+ * @returns the counts and the named years
+ */
+export declare function buildCfpConsumerComplaintSeries(input: {
+    firstYear: number;
+    newestYear: number;
+    newestReceivedDate: string;
+    years: CfpComplaintYearCount[];
+    topProducts: CfpComplaintProductCount[];
+    topCompanies: CfpComplaintCompanyCount[];
+}): CfpConsumerComplaintSeries;
+/**
+ * Parses the folded counts a committed snapshot holds into the story shape.
+ *
+ * @param payload - the JSON body of a committed snapshot
+ * @returns the counts and the named years
+ */
+export declare function parseCfpComplaintSnapshot(payload: unknown): CfpConsumerComplaintSeries;
+/**
+ * Walks back from today to the newest day with a published complaint.
+ *
+ * The search API has no date sort, so the adapter asks a day at a time and
+ * stops at the first non-empty one. That is normally one or two requests.
+ *
+ * @param fetchImpl - the fetch implementation to use
+ * @param today - the day to start from, defaulting to now
+ * @returns the newest day with a complaint, e.g. "2026-10-02"
+ */
+export declare function findNewestCfpComplaintDate(fetchImpl: typeof globalThis.fetch, today?: Date): Promise<string>;
+/**
+ * Reads the complaint database at build time.
+ *
+ * The search API answers one question per request, so the window costs one
+ * request per year plus one for the product and company tallies and one or
+ * two to find the newest day. The endpoint is keyless.
+ *
+ * @param options - an optional window and fetch stub
+ * @returns the counts and the named years
+ */
+export declare function fetchCfpConsumerComplaints(options?: {
+    firstYear?: number;
+    newestYear?: number;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<CfpConsumerComplaintSeries>;
+/** US Consumer Financial Protection Bureau Consumer Complaint Database, keyless. */
+export declare const cfpbConsumerComplaintsAdapter: UsDataAdapter<CfpConsumerComplaintSeries>;
+//# sourceMappingURL=cfpbConsumerComplaints.d.ts.map

package/dist/cfpbConsumerComplaints.d.ts.map

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