@usa-open-data-connectors/usa-sources 0.1.1 → 0.1.3

package/dist/clinicalTrialsStudies.js

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+import { UsSourceApiError, UsSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/** Adapter id for the ClinicalTrials.gov studies source. */
+export const CLINICALTRIALS_STUDIES_SOURCE_ID = 'clinicaltrials-studies';
+/** Base URL for the ClinicalTrials.gov studies API. */
+export const CLINICALTRIALS_STUDIES_API_BASE = 'https://clinicaltrials.gov/api/v2/studies';
+/** Page size for one request. */
+export const CLINICALTRIALS_STUDIES_PAGE_SIZE = 10;
+/** Committed snapshot, so a build works when the ClinicalTrials host is unreachable. */
+const CLINICALTRIALS_STUDIES_FIXTURE_FILENAME = 'clinicaltrials-studies-2026-10-05.json';
+const CLINICALTRIALS_STUDY_SCHEMA = z.object({
+    protocolSection: z
+        .object({
+        identificationModule: z
+            .object({ nctId: z.string().optional(), briefTitle: z.string().optional() })
+            .optional(),
+        statusModule: z
+            .object({
+            overallStatus: z.string().optional(),
+            startDateStruct: z.object({ date: z.string().optional() }).optional(),
+            lastUpdatePostDateStruct: z.object({ date: z.string().optional() }).optional(),
+        })
+            .optional(),
+        sponsorCollaboratorsModule: z
+            .object({ leadSponsor: z.object({ name: z.string().optional() }).optional() })
+            .optional(),
+        conditionsModule: z.object({ conditions: z.array(z.string()).optional() }).optional(),
+        designModule: z
+            .object({
+            studyType: z.string().optional(),
+            phases: z.array(z.string()).optional(),
+            enrollmentInfo: z
+                .object({ count: z.number().optional(), type: z.string().optional() })
+                .optional(),
+        })
+            .optional(),
+    })
+        .optional(),
+});
+const CLINICALTRIALS_PAYLOAD_SCHEMA = z.object({
+    studies: z.array(CLINICALTRIALS_STUDY_SCHEMA).optional(),
+    nextPageToken: z.string().optional(),
+});
+/**
+ * Builds the request URL for one page of studies.
+ *
+ * The endpoint is keyless. The default page size is small on purpose: one
+ * study carries a deep protocol record, so a caller reading many pages should
+ * pass the page token from the previous response.
+ *
+ * @param options - an optional page size
+ * @returns the full request URL
+ */
+export function buildClinicalTrialsStudiesUrl(options) {
+    const params = new URLSearchParams({
+        pageSize: String(options?.pageSize ?? CLINICALTRIALS_STUDIES_PAGE_SIZE),
+    });
+    return `${CLINICALTRIALS_STUDIES_API_BASE}?${params.toString()}`;
+}
+/** Counts studies per recruitment status, most studies first, ties by name. */
+function countClinicalTrialStatuses(studies) {
+    const counts = new Map();
+    for (const study of studies) {
+        counts.set(study.overallStatus, (counts.get(study.overallStatus) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort(([leftStatus, leftCount], [rightStatus, rightCount]) => leftCount === rightCount ? leftStatus.localeCompare(rightStatus) : rightCount - leftCount)
+        .map(([status, studyCount]) => ({ status, studyCount }));
+}
+/**
+ * Parses one page of studies into the fields a story reads.
+ *
+ * A study without a registry id or a brief title is a changed shape and stops
+ * the parse. Optional protocol blocks are read when present and left null
+ * when the registry did not carry them.
+ *
+ * @param payload - the JSON body from the ClinicalTrials.gov studies API
+ * @returns the studies in the page, the status counts, and the next page token
+ */
+export function parseClinicalTrialsStudiesPayload(payload) {
+    const parsed = CLINICALTRIALS_PAYLOAD_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError(CLINICALTRIALS_STUDIES_SOURCE_ID, parsed.error.message);
+    }
+    const rows = parsed.data.studies ?? [];
+    if (rows.length === 0) {
+        throw new UsSourceParseError(CLINICALTRIALS_STUDIES_SOURCE_ID, 'The response carried no studies');
+    }
+    const studies = rows.map((row) => {
+        const protocol = row.protocolSection;
+        const nctId = protocol?.identificationModule?.nctId;
+        const briefTitle = protocol?.identificationModule?.briefTitle;
+        if (nctId === undefined || briefTitle === undefined) {
+            throw new UsSourceParseError(CLINICALTRIALS_STUDIES_SOURCE_ID, 'A study arrived without its registry id or brief title');
+        }
+        const status = protocol?.statusModule;
+        const design = protocol?.designModule;
+        return {
+            nctId,
+            briefTitle,
+            overallStatus: status?.overallStatus ?? '',
+            studyType: design?.studyType ?? null,
+            phases: design?.phases ?? [],
+            conditions: protocol?.conditionsModule?.conditions ?? [],
+            leadSponsor: protocol?.sponsorCollaboratorsModule?.leadSponsor?.name ?? null,
+            enrollmentCount: design?.enrollmentInfo?.count ?? null,
+            enrollmentType: design?.enrollmentInfo?.type ?? null,
+            startDate: status?.startDateStruct?.date ?? null,
+            lastUpdatePostDate: status?.lastUpdatePostDateStruct?.date ?? null,
+        };
+    });
+    return {
+        studies,
+        studyCount: studies.length,
+        statusCounts: countClinicalTrialStatuses(studies),
+        nextPageToken: parsed.data.nextPageToken ?? null,
+    };
+}
+/**
+ * Reads one page of registered clinical studies.
+ *
+ * One keyless request covers the page. The response also carries a token for
+ * the next page of the same query, which the adapter keeps on the page it
+ * returns.
+ *
+ * @param options - an optional page size and fetch stub
+ * @returns the studies in the page, the status counts, and the next page token
+ */
+export async function fetchClinicalTrialsStudies(options) {
+    const fetchImpl = options?.fetchImpl ?? globalThis.fetch;
+    const url = buildClinicalTrialsStudiesUrl(options?.pageSize === undefined ? {} : { pageSize: options.pageSize });
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new UsSourceApiError(CLINICALTRIALS_STUDIES_SOURCE_ID, `HTTP ${response.status} reading the studies`);
+    }
+    return parseClinicalTrialsStudiesPayload(await response.json());
+}
+/** ClinicalTrials.gov registered studies, one row per study, keyless. */
+export const clinicalTrialsStudiesAdapter = {
+    id: CLINICALTRIALS_STUDIES_SOURCE_ID,
+    name: 'ClinicalTrials.gov studies',
+    auth: 'none',
+    description: 'Registered clinical studies from ClinicalTrials.gov, one row per study, with the status, phase, lead sponsor, and enrollment.',
+    fetchLive: async (options) => fetchClinicalTrialsStudies(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: (payload) => parseClinicalTrialsStudiesPayload(payload),
+    loadFixture: () => parseClinicalTrialsStudiesPayload(readFixtureJson(CLINICALTRIALS_STUDIES_FIXTURE_FILENAME)),
+};
+//# sourceMappingURL=clinicalTrialsStudies.js.map

package/dist/clinicalTrialsStudies.js.map

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

package/dist/epaEnvirofactsFacilities.d.ts

@@ -0,0 +1,94 @@
+import type { UsDataAdapter } from './types.js';
+/** Adapter id for the EPA Envirofacts facility source. */
+export declare const EPA_ENVIROFACTS_FACILITIES_SOURCE_ID = "epa-envirofacts-facilities";
+/** One Toxics Release Inventory facility from the Envirofacts service. */
+export interface EpaEnvirofactsFacility {
+    /** The EPA's own TRI facility id. */
+    facilityId: string;
+    /** Facility name as the register holds it. */
+    facilityName: string;
+    /** Street address of the site. */
+    streetAddress: string;
+    /** City of the site. */
+    city: string;
+    /** County the site sits in, spelled the way the service spells it. */
+    countyName: string;
+    /** Two-letter state code the service reports for the site. */
+    stateAbbr: string;
+    /** Postal code of the site. */
+    postalCode: string;
+    /** EPA region number as the service reports it, for example "1". */
+    region: string;
+    /** True when the service marks the facility as closed. */
+    closed: boolean;
+    /** Parent company name, or null when the service reports "NA" or leaves it out. */
+    parentCompanyName: string | null;
+}
+/** One county and how many facilities in the page sit there. */
+export interface EpaEnvirofactsCountyCount {
+    countyName: string;
+    facilityCount: number;
+}
+/** One page of facilities, folded for a story. */
+export interface EpaEnvirofactsFacilityPage {
+    facilities: EpaEnvirofactsFacility[];
+    facilityCount: number;
+    /** Facilities the service does not mark as closed. */
+    openCount: number;
+    /** Facilities the service marks as closed. */
+    closedCount: number;
+    /** Counties the facilities in the page sit in, most facilities first. */
+    counties: EpaEnvirofactsCountyCount[];
+}
+/** Base URL for the EPA Envirofacts service. */
+export declare const EPA_ENVIROFACTS_API_BASE = "https://data.epa.gov/efservice";
+/** Envirofacts table that holds the Toxics Release Inventory facility records. */
+export declare const EPA_ENVIROFACTS_TABLE = "TRI_FACILITY";
+/** Envirofacts column the state filter reads. */
+export declare const EPA_ENVIROFACTS_STATE_COLUMN = "STATE_ABBR";
+/** State the default URL asks for. */
+export declare const EPA_ENVIROFACTS_STATE_ABBR = "RI";
+/** Row window one request reads, the first ten rows. */
+export declare const EPA_ENVIROFACTS_ROW_WINDOW = "0:9";
+/**
+ * Builds the request URL for one page of Toxics Release Inventory facilities.
+ *
+ * The endpoint is keyless, and the state segment does narrow the rows: the
+ * value sits directly after the column name, with no `equals` operator.
+ * Envirofacts accepts an `equals` segment without complaining but then
+ * returns the table's first rows instead of the ones asked for.
+ *
+ * @param options - an optional state code and row window
+ * @returns the full request URL
+ */
+export declare function buildEpaEnvirofactsFacilitiesUrl(options?: {
+    stateAbbr?: string;
+    rowWindow?: string;
+}): string;
+/**
+ * Parses one response into the facilities in the page and its rollups.
+ *
+ * A row without a facility id, name, or state code fails the schema and stops
+ * the parse. An empty array is treated as a changed source, because the
+ * default query always returns rows.
+ *
+ * @param payload - the JSON body from the Envirofacts service
+ * @returns the facilities in the page, the open and closed counts, and the counties
+ */
+export declare function parseEpaEnvirofactsFacilitiesPayload(payload: unknown): EpaEnvirofactsFacilityPage;
+/**
+ * Reads one page of Toxics Release Inventory facilities from Envirofacts.
+ *
+ * One keyless request covers the page. The state segment in the URL narrows
+ * the rows, so the page holds facilities from the state that was asked for.
+ *
+ * @param options - an optional state code, row window, and fetch stub
+ * @returns the facilities in the page and its rollups
+ */
+export declare function fetchEpaEnvirofactsFacilities(options?: {
+    stateAbbr?: string;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<EpaEnvirofactsFacilityPage>;
+/** EPA Envirofacts Toxics Release Inventory facilities, keyless. */
+export declare const epaEnvirofactsFacilitiesAdapter: UsDataAdapter<EpaEnvirofactsFacilityPage>;
+//# sourceMappingURL=epaEnvirofactsFacilities.d.ts.map

package/dist/epaEnvirofactsFacilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epaEnvirofactsFacilities.d.ts","sourceRoot":"","sources":["../src/epaEnvirofactsFacilities.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,0DAA0D;AAC1D,eAAO,MAAM,oCAAoC,+BAA+B,CAAC;AAEjF,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,mFAAmF;IACnF,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,gEAAgE;AAChE,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,kDAAkD;AAClD,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,sBAAsB,EAAE,CAAC;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,QAAQ,EAAE,yBAAyB,EAAE,CAAC;CACvC;AAED,gDAAgD;AAChD,eAAO,MAAM,wBAAwB,mCAAmC,CAAC;AAEzE,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,iBAAiB,CAAC;AAEpD,iDAAiD;AACjD,eAAO,MAAM,4BAA4B,eAAe,CAAC;AAEzD,sCAAsC;AACtC,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,wDAAwD;AACxD,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAmDhD;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,CAAC,EAAE;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAIT;AAED;;;;;;;;;GASG;AACH,wBAAgB,oCAAoC,CAAC,OAAO,EAAE,OAAO,GAAG,0BAA0B,CAwCjG;AAED;;;;;;;;GAQG;AACH,wBAAsB,6BAA6B,CAAC,OAAO,CAAC,EAAE;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAatC;AAED,oEAAoE;AACpE,eAAO,MAAM,+BAA+B,EAAE,aAAa,CAAC,0BAA0B,CAarF,CAAC"}

package/dist/epaEnvirofactsFacilities.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import { UsSourceApiError, UsSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/** Adapter id for the EPA Envirofacts facility source. */
+export const EPA_ENVIROFACTS_FACILITIES_SOURCE_ID = 'epa-envirofacts-facilities';
+/** Base URL for the EPA Envirofacts service. */
+export const EPA_ENVIROFACTS_API_BASE = 'https://data.epa.gov/efservice';
+/** Envirofacts table that holds the Toxics Release Inventory facility records. */
+export const EPA_ENVIROFACTS_TABLE = 'TRI_FACILITY';
+/** Envirofacts column the state filter reads. */
+export const EPA_ENVIROFACTS_STATE_COLUMN = 'STATE_ABBR';
+/** State the default URL asks for. */
+export const EPA_ENVIROFACTS_STATE_ABBR = 'RI';
+/** Row window one request reads, the first ten rows. */
+export const EPA_ENVIROFACTS_ROW_WINDOW = '0:9';
+/** Committed snapshot, so a build works when the Envirofacts host is unreachable. */
+const EPA_ENVIROFACTS_FIXTURE_FILENAME = 'epa-envirofacts-facilities-2026-10-05.json';
+// The service answers with a bare JSON array, and a rejected query answers
+// with a body of {error}. The filter segment takes the value on its own: an
+// "equals" operator is accepted in the URL but never narrows the rows, so the
+// URL builder below does not use one.
+const EPA_ENVIROFACTS_FACILITY_SCHEMA = z.object({
+    tri_facility_id: z.string(),
+    facility_name: z.string(),
+    street_address: z.string().nullable().optional(),
+    city_name: z.string().nullable().optional(),
+    county_name: z.string().nullable().optional(),
+    state_abbr: z.string(),
+    zip_code: z.string().nullable().optional(),
+    region: z.string().nullable().optional(),
+    fac_closed_ind: z.string().nullable().optional(),
+    parent_co_name: z.string().nullable().optional(),
+});
+const EPA_ENVIROFACTS_PAYLOAD_SCHEMA = z.union([
+    z.array(EPA_ENVIROFACTS_FACILITY_SCHEMA),
+    z.object({ error: z.string().optional() }),
+]);
+/** Reads the parent company, treating the register's "NA" as absent. */
+function readEpaParentCompany(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed === '' || trimmed === 'NA' ? null : trimmed;
+}
+/** Counts facilities per county, most facilities first, then by name. */
+function countEpaEnvirofactsCounties(facilities) {
+    const counts = new Map();
+    for (const facility of facilities) {
+        counts.set(facility.countyName, (counts.get(facility.countyName) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort(([leftCounty, leftCount], [rightCounty, rightCount]) => leftCount === rightCount ? leftCounty.localeCompare(rightCounty) : rightCount - leftCount)
+        .map(([countyName, facilityCount]) => ({ countyName, facilityCount }));
+}
+/**
+ * Builds the request URL for one page of Toxics Release Inventory facilities.
+ *
+ * The endpoint is keyless, and the state segment does narrow the rows: the
+ * value sits directly after the column name, with no `equals` operator.
+ * Envirofacts accepts an `equals` segment without complaining but then
+ * returns the table's first rows instead of the ones asked for.
+ *
+ * @param options - an optional state code and row window
+ * @returns the full request URL
+ */
+export function buildEpaEnvirofactsFacilitiesUrl(options) {
+    const stateAbbr = options?.stateAbbr ?? EPA_ENVIROFACTS_STATE_ABBR;
+    const rowWindow = options?.rowWindow ?? EPA_ENVIROFACTS_ROW_WINDOW;
+    return `${EPA_ENVIROFACTS_API_BASE}/${EPA_ENVIROFACTS_TABLE}/${EPA_ENVIROFACTS_STATE_COLUMN}/${stateAbbr}/rows/${rowWindow}/JSON`;
+}
+/**
+ * Parses one response into the facilities in the page and its rollups.
+ *
+ * A row without a facility id, name, or state code fails the schema and stops
+ * the parse. An empty array is treated as a changed source, because the
+ * default query always returns rows.
+ *
+ * @param payload - the JSON body from the Envirofacts service
+ * @returns the facilities in the page, the open and closed counts, and the counties
+ */
+export function parseEpaEnvirofactsFacilitiesPayload(payload) {
+    const parsed = EPA_ENVIROFACTS_PAYLOAD_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError(EPA_ENVIROFACTS_FACILITIES_SOURCE_ID, parsed.error.message);
+    }
+    if (!Array.isArray(parsed.data)) {
+        throw new UsSourceApiError(EPA_ENVIROFACTS_FACILITIES_SOURCE_ID, parsed.data.error ?? 'The service rejected the query');
+    }
+    if (parsed.data.length === 0) {
+        throw new UsSourceParseError(EPA_ENVIROFACTS_FACILITIES_SOURCE_ID, 'The response carried no rows');
+    }
+    const facilities = parsed.data.map((row) => ({
+        facilityId: row.tri_facility_id,
+        facilityName: row.facility_name,
+        streetAddress: row.street_address ?? '',
+        city: row.city_name ?? '',
+        countyName: row.county_name ?? '',
+        stateAbbr: row.state_abbr,
+        postalCode: row.zip_code ?? '',
+        region: row.region ?? '',
+        closed: row.fac_closed_ind === '1',
+        parentCompanyName: readEpaParentCompany(row.parent_co_name),
+    }));
+    const closedCount = facilities.filter((facility) => facility.closed).length;
+    return {
+        facilities,
+        facilityCount: facilities.length,
+        openCount: facilities.length - closedCount,
+        closedCount,
+        counties: countEpaEnvirofactsCounties(facilities),
+    };
+}
+/**
+ * Reads one page of Toxics Release Inventory facilities from Envirofacts.
+ *
+ * One keyless request covers the page. The state segment in the URL narrows
+ * the rows, so the page holds facilities from the state that was asked for.
+ *
+ * @param options - an optional state code, row window, and fetch stub
+ * @returns the facilities in the page and its rollups
+ */
+export async function fetchEpaEnvirofactsFacilities(options) {
+    const fetchImpl = options?.fetchImpl ?? globalThis.fetch;
+    const url = buildEpaEnvirofactsFacilitiesUrl(options?.stateAbbr === undefined ? {} : { stateAbbr: options.stateAbbr });
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new UsSourceApiError(EPA_ENVIROFACTS_FACILITIES_SOURCE_ID, `HTTP ${response.status} reading the facilities`);
+    }
+    return parseEpaEnvirofactsFacilitiesPayload(await response.json());
+}
+/** EPA Envirofacts Toxics Release Inventory facilities, keyless. */
+export const epaEnvirofactsFacilitiesAdapter = {
+    id: EPA_ENVIROFACTS_FACILITIES_SOURCE_ID,
+    name: 'EPA Envirofacts facilities',
+    auth: 'none',
+    description: 'Toxics Release Inventory facilities from the EPA Envirofacts service, one row per site, with its county, address, and open or closed status.',
+    fetchLive: async (options) => fetchEpaEnvirofactsFacilities(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: (payload) => parseEpaEnvirofactsFacilitiesPayload(payload),
+    loadFixture: () => parseEpaEnvirofactsFacilitiesPayload(readFixtureJson(EPA_ENVIROFACTS_FIXTURE_FILENAME)),
+};
+//# sourceMappingURL=epaEnvirofactsFacilities.js.map

package/dist/epaEnvirofactsFacilities.js.map

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

package/dist/fdicBankDirectory.d.ts

@@ -0,0 +1,78 @@
+import type { UsDataAdapter } from './types.js';
+/** Adapter id for the FDIC bank directory source. */
+export declare const FDIC_BANK_DIRECTORY_SOURCE_ID = "fdic-bank-directory";
+/** One bank in the FDIC's institution directory. */
+export interface FdicBank {
+    /** The FDIC's own certificate number for the bank. */
+    id: string;
+    /** The bank's legal name. */
+    name: string;
+    /** City of the bank's main office. */
+    city: string;
+    /** Two-letter state code of the main office. */
+    stateAbbr: string;
+}
+/** One state and how many banks in the page sit there. */
+export interface FdicBankStateCount {
+    stateAbbr: string;
+    bankCount: number;
+}
+/** One page of the bank directory, folded for a story. */
+export interface FdicBankDirectory {
+    /** One entry per bank in the page. */
+    banks: FdicBank[];
+    bankCount: number;
+    /** How many banks the FDIC holds in total, not just in this page. */
+    totalBanks: number;
+    /** States the banks in the page sit in, most banks first. */
+    states: FdicBankStateCount[];
+}
+/** Base URL for the FDIC institutions API. */
+export declare const FDIC_BANK_API_BASE = "https://banks.data.fdic.gov/api/institutions";
+/** Row cap for one request. */
+export declare const FDIC_BANK_ROW_LIMIT = 10;
+/** Columns the adapter asks for. The directory carries many more. */
+export declare const FDIC_BANK_FIELDS = "NAME,CITY,STALP";
+/**
+ * Builds the request URL for one page of the bank directory.
+ *
+ * The endpoint is keyless. The `fields` parameter trims the response to the
+ * columns a story reads, which keeps each row small. The service answers the
+ * banks.data.fdic.gov host with a redirect to api.fdic.gov, which fetch
+ * follows.
+ *
+ * @param options - an optional row cap and column list
+ * @returns the full request URL
+ */
+export declare function buildFdicBankDirectoryUrl(options?: {
+    rowLimit?: number;
+    fields?: string;
+}): string;
+/**
+ * Parses one response into the banks in the page and the state counts.
+ *
+ * A row without an id, name, city, or state is a changed shape and stops the
+ * parse. The API's own total is used for `totalBanks`, falling back to the
+ * page size when the envelope omits it.
+ *
+ * @param payload - the JSON body from the FDIC institutions API
+ * @returns the banks in the page, the total the FDIC reports, and state counts
+ */
+export declare function parseFdicBankDirectoryPayload(payload: unknown): FdicBankDirectory;
+/**
+ * Reads one page of the FDIC's bank directory.
+ *
+ * One keyless request covers the page. The service trims each row to the
+ * columns asked for, so a story gets names, cities, and states without the
+ * full institution record.
+ *
+ * @param options - an optional row cap and fetch stub
+ * @returns the banks in the page, the FDIC total, and the state counts
+ */
+export declare function fetchFdicBankDirectory(options?: {
+    rowLimit?: number;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<FdicBankDirectory>;
+/** FDIC bank directory, one row per insured institution, keyless. */
+export declare const fdicBankDirectoryAdapter: UsDataAdapter<FdicBankDirectory>;
+//# sourceMappingURL=fdicBankDirectory.d.ts.map

package/dist/fdicBankDirectory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fdicBankDirectory.d.ts","sourceRoot":"","sources":["../src/fdicBankDirectory.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,qDAAqD;AACrD,eAAO,MAAM,6BAA6B,wBAAwB,CAAC;AAEnE,oDAAoD;AACpD,MAAM,WAAW,QAAQ;IACvB,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,MAAM,EAAE,kBAAkB,EAAE,CAAC;CAC9B;AAED,8CAA8C;AAC9C,eAAO,MAAM,kBAAkB,iDAAiD,CAAC;AAEjF,+BAA+B;AAC/B,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAuBlD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAMT;AAeD;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,CAiCjF;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,CAAC,EAAE;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAa7B;AAED,qEAAqE;AACrE,eAAO,MAAM,wBAAwB,EAAE,aAAa,CAAC,iBAAiB,CAYrE,CAAC"}

package/dist/fdicBankDirectory.js

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import { UsSourceApiError, UsSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/** Adapter id for the FDIC bank directory source. */
+export const FDIC_BANK_DIRECTORY_SOURCE_ID = 'fdic-bank-directory';
+/** Base URL for the FDIC institutions API. */
+export const FDIC_BANK_API_BASE = 'https://banks.data.fdic.gov/api/institutions';
+/** Row cap for one request. */
+export const FDIC_BANK_ROW_LIMIT = 10;
+/** Columns the adapter asks for. The directory carries many more. */
+export const FDIC_BANK_FIELDS = 'NAME,CITY,STALP';
+/** Committed snapshot, so a build works when the FDIC host is unreachable. */
+const FDIC_BANK_FIXTURE_FILENAME = 'fdic-bank-directory-2026-10-05.json';
+// The API wraps each institution in a result object with its own score, and
+// answers a rejected request with an HTTP error and a body of {errors}.
+const FDIC_BANK_ROW_SCHEMA = z.object({
+    data: z.object({
+        ID: z.string().optional(),
+        NAME: z.string().optional(),
+        CITY: z.string().optional(),
+        STALP: z.string().optional(),
+    }),
+});
+const FDIC_BANK_PAYLOAD_SCHEMA = z.object({
+    meta: z.object({ total: z.number().optional() }).optional(),
+    totals: z.object({ count: z.number().optional() }).optional(),
+    data: z.array(FDIC_BANK_ROW_SCHEMA).optional(),
+    errors: z.array(z.unknown()).optional(),
+});
+/**
+ * Builds the request URL for one page of the bank directory.
+ *
+ * The endpoint is keyless. The `fields` parameter trims the response to the
+ * columns a story reads, which keeps each row small. The service answers the
+ * banks.data.fdic.gov host with a redirect to api.fdic.gov, which fetch
+ * follows.
+ *
+ * @param options - an optional row cap and column list
+ * @returns the full request URL
+ */
+export function buildFdicBankDirectoryUrl(options) {
+    const params = new URLSearchParams({
+        limit: String(options?.rowLimit ?? FDIC_BANK_ROW_LIMIT),
+        fields: options?.fields ?? FDIC_BANK_FIELDS,
+    });
+    return `${FDIC_BANK_API_BASE}?${params.toString()}`;
+}
+/** Counts banks per state in the order they were seen. */
+function countFdicBankStates(banks) {
+    const counts = new Map();
+    for (const bank of banks) {
+        counts.set(bank.stateAbbr, (counts.get(bank.stateAbbr) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort(([leftState, leftCount], [rightState, rightCount]) => leftCount === rightCount ? leftState.localeCompare(rightState) : rightCount - leftCount)
+        .map(([stateAbbr, bankCount]) => ({ stateAbbr, bankCount }));
+}
+/**
+ * Parses one response into the banks in the page and the state counts.
+ *
+ * A row without an id, name, city, or state is a changed shape and stops the
+ * parse. The API's own total is used for `totalBanks`, falling back to the
+ * page size when the envelope omits it.
+ *
+ * @param payload - the JSON body from the FDIC institutions API
+ * @returns the banks in the page, the total the FDIC reports, and state counts
+ */
+export function parseFdicBankDirectoryPayload(payload) {
+    const parsed = FDIC_BANK_PAYLOAD_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError(FDIC_BANK_DIRECTORY_SOURCE_ID, parsed.error.message);
+    }
+    if (parsed.data.errors !== undefined && parsed.data.errors.length > 0) {
+        throw new UsSourceApiError(FDIC_BANK_DIRECTORY_SOURCE_ID, 'The API rejected the request');
+    }
+    const rows = parsed.data.data ?? [];
+    if (rows.length === 0) {
+        throw new UsSourceParseError(FDIC_BANK_DIRECTORY_SOURCE_ID, 'The response carried no rows');
+    }
+    const banks = rows.map((row) => {
+        const { ID, NAME, CITY, STALP } = row.data;
+        if (ID === undefined || NAME === undefined || CITY === undefined || STALP === undefined) {
+            throw new UsSourceParseError(FDIC_BANK_DIRECTORY_SOURCE_ID, 'A bank row arrived without its id, name, city, or state');
+        }
+        return { id: ID, name: NAME, city: CITY, stateAbbr: STALP };
+    });
+    const totalBanks = parsed.data.totals?.count ?? parsed.data.meta?.total ?? banks.length;
+    return {
+        banks,
+        bankCount: banks.length,
+        totalBanks,
+        states: countFdicBankStates(banks),
+    };
+}
+/**
+ * Reads one page of the FDIC's bank directory.
+ *
+ * One keyless request covers the page. The service trims each row to the
+ * columns asked for, so a story gets names, cities, and states without the
+ * full institution record.
+ *
+ * @param options - an optional row cap and fetch stub
+ * @returns the banks in the page, the FDIC total, and the state counts
+ */
+export async function fetchFdicBankDirectory(options) {
+    const fetchImpl = options?.fetchImpl ?? globalThis.fetch;
+    const url = buildFdicBankDirectoryUrl(options?.rowLimit === undefined ? {} : { rowLimit: options.rowLimit });
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new UsSourceApiError(FDIC_BANK_DIRECTORY_SOURCE_ID, `HTTP ${response.status} reading the bank directory`);
+    }
+    return parseFdicBankDirectoryPayload(await response.json());
+}
+/** FDIC bank directory, one row per insured institution, keyless. */
+export const fdicBankDirectoryAdapter = {
+    id: FDIC_BANK_DIRECTORY_SOURCE_ID,
+    name: 'FDIC bank directory',
+    auth: 'none',
+    description: 'Insured banks in the FDIC institution directory, one row per bank, with the city and state of its main office.',
+    fetchLive: async (options) => fetchFdicBankDirectory(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: (payload) => parseFdicBankDirectoryPayload(payload),
+    loadFixture: () => parseFdicBankDirectoryPayload(readFixtureJson(FDIC_BANK_FIXTURE_FILENAME)),
+};
+//# sourceMappingURL=fdicBankDirectory.js.map

package/dist/fdicBankDirectory.js.map

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