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

package/dist/cfpbConsumerComplaints.js

@@ -0,0 +1,273 @@
+import { z } from 'zod';
+import { UsSourceApiError, UsSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/** Base URL for the Consumer Complaint Database search API. */
+export 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 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 const CFPB_NEWEST_DATE_PROBE_DAYS = 14;
+/** How many products and companies one fetch keeps. */
+export const CFPB_TOP_LIST_LIMIT = 10;
+/** Committed snapshot, so a build works when consumerfinance.gov is unreachable. */
+const CFPB_COMPLAINT_FIXTURE_FILENAME = 'cfpb-consumer-complaints-2026-10-03.json';
+/** Shape of the totals-only response, `size=0&no_aggs=true`. */
+const CFPB_TOTAL_SCHEMA = z.object({
+    hits: z.object({ total: z.object({ value: z.number() }) }),
+});
+const CFPB_BUCKET_SCHEMA = z.object({ key: z.string(), doc_count: z.number() });
+// The terms aggregations are nested twice: once for the aggregation name and
+// once for the field group, so `product.buckets` sits under `aggregations.product.product`.
+const CFPB_AGGREGATIONS_SCHEMA = z.object({
+    aggregations: z.object({
+        product: z.object({ product: z.object({ buckets: z.array(CFPB_BUCKET_SCHEMA) }) }),
+        company: z.object({ company: z.object({ buckets: z.array(CFPB_BUCKET_SCHEMA) }) }),
+    }),
+});
+// The committed snapshot holds the folded counts rather than the raw rows,
+// because the full file is more than eighteen million records.
+const CFPB_SNAPSHOT_SCHEMA = z.object({
+    exportedAt: z.string(),
+    firstYear: z.number(),
+    newestYear: z.number(),
+    newestReceivedDate: z.string(),
+    totalComplaints: z.number(),
+    years: z.array(z.object({ year: z.number(), complaintCount: z.number() })).min(1),
+    topProducts: z.array(z.object({ product: z.string(), complaintCount: z.number() })),
+    topCompanies: z.array(z.object({ company: z.string(), complaintCount: z.number() })),
+});
+/**
+ * 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 function buildCfpComplaintCountUrl(year) {
+    const params = new URLSearchParams({
+        size: '0',
+        no_aggs: 'true',
+        date_received_min: `${year}-01-01`,
+        date_received_max: `${year}-12-31`,
+    });
+    return `${CFPB_COMPLAINT_SEARCH_API_BASE}?${params.toString()}`;
+}
+/**
+ * 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 function buildCfpComplaintDayUrl(isoDate) {
+    const params = new URLSearchParams({
+        size: '0',
+        no_aggs: 'true',
+        date_received_min: isoDate,
+        date_received_max: isoDate,
+    });
+    return `${CFPB_COMPLAINT_SEARCH_API_BASE}?${params.toString()}`;
+}
+/**
+ * Builds the request URL for the product and company tallies.
+ *
+ * @returns the full request URL
+ */
+export function buildCfpComplaintAggregationUrl() {
+    return `${CFPB_COMPLAINT_SEARCH_API_BASE}?size=0`;
+}
+/**
+ * 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 function parseCfpComplaintTotal(payload) {
+    const parsed = CFPB_TOTAL_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError('cfpb-consumer-complaints', parsed.error.message);
+    }
+    return parsed.data.hits.total.value;
+}
+/**
+ * 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 function parseCfpComplaintAggregations(payload) {
+    const parsed = CFPB_AGGREGATIONS_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError('cfpb-consumer-complaints', parsed.error.message);
+    }
+    const topProducts = parsed.data.aggregations.product.product.buckets
+        .filter((bucket) => bucket.doc_count > 0)
+        .map((bucket) => ({ product: bucket.key, complaintCount: bucket.doc_count }))
+        .slice(0, CFPB_TOP_LIST_LIMIT);
+    const topCompanies = parsed.data.aggregations.company.company.buckets
+        .filter((bucket) => bucket.doc_count > 0)
+        .map((bucket) => ({ company: bucket.key, complaintCount: bucket.doc_count }))
+        .slice(0, CFPB_TOP_LIST_LIMIT);
+    return { topProducts, topCompanies };
+}
+/** Picks the year with the most, or fewest, complaints. Ties go to the earlier year. */
+function extremeYear(years, direction) {
+    const first = years[0];
+    if (first === undefined) {
+        throw new UsSourceParseError('cfpb-consumer-complaints', 'No years to summarise');
+    }
+    return years.reduce((best, year) => {
+        if (direction === 'most') {
+            return year.complaintCount > best.complaintCount ? year : best;
+        }
+        return year.complaintCount < best.complaintCount ? year : best;
+    }, first);
+}
+/**
+ * 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 function buildCfpConsumerComplaintSeries(input) {
+    if (input.newestYear <= input.firstYear) {
+        throw new UsSourceParseError('cfpb-consumer-complaints', 'The window needs at least two years');
+    }
+    const first = input.years[0];
+    const newest = input.years[input.years.length - 1];
+    if (first === undefined || newest === undefined || first.year !== input.firstYear) {
+        throw new UsSourceParseError('cfpb-consumer-complaints', 'The year rows do not cover the window asked for');
+    }
+    if (newest.year !== input.newestYear) {
+        throw new UsSourceParseError('cfpb-consumer-complaints', 'The year rows do not reach the newest year');
+    }
+    const totalComplaints = input.years.reduce((sum, year) => sum + year.complaintCount, 0);
+    if (totalComplaints === 0) {
+        throw new UsSourceParseError('cfpb-consumer-complaints', 'No complaints to summarise');
+    }
+    const completeYears = input.years.filter((year) => year.year !== input.newestYear);
+    if (completeYears.length === 0) {
+        throw new UsSourceParseError('cfpb-consumer-complaints', 'No complete year to compare against');
+    }
+    return {
+        firstYear: input.firstYear,
+        newestYear: input.newestYear,
+        newestReceivedDate: input.newestReceivedDate,
+        totalComplaints,
+        years: input.years,
+        completeYearCount: completeYears.length,
+        busiestCompleteYear: extremeYear(completeYears, 'most'),
+        quietestCompleteYear: extremeYear(completeYears, 'fewest'),
+        topProducts: input.topProducts,
+        topCompanies: input.topCompanies,
+    };
+}
+/**
+ * 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 function parseCfpComplaintSnapshot(payload) {
+    const parsed = CFPB_SNAPSHOT_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError('cfpb-consumer-complaints', parsed.error.message);
+    }
+    return buildCfpConsumerComplaintSeries({
+        firstYear: parsed.data.firstYear,
+        newestYear: parsed.data.newestYear,
+        newestReceivedDate: parsed.data.newestReceivedDate,
+        years: parsed.data.years,
+        topProducts: parsed.data.topProducts,
+        topCompanies: parsed.data.topCompanies,
+    });
+}
+/**
+ * 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 async function findNewestCfpComplaintDate(fetchImpl, today = new Date()) {
+    for (let daysBack = 0; daysBack < CFPB_NEWEST_DATE_PROBE_DAYS; daysBack += 1) {
+        const day = new Date(today.getTime() - daysBack * 24 * 60 * 60 * 1000);
+        const isoDate = day.toISOString().slice(0, 10);
+        const response = await fetchImpl(buildCfpComplaintDayUrl(isoDate));
+        if (!response.ok) {
+            throw new UsSourceApiError('cfpb-consumer-complaints', `HTTP ${response.status} reading the complaint count for ${isoDate}`);
+        }
+        if (parseCfpComplaintTotal(await response.json()) > 0) {
+            return isoDate;
+        }
+    }
+    throw new UsSourceApiError('cfpb-consumer-complaints', `No complaint found in the last ${String(CFPB_NEWEST_DATE_PROBE_DAYS)} days`);
+}
+/**
+ * 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 async function fetchCfpConsumerComplaints(options) {
+    const fetchImpl = options?.fetchImpl ?? globalThis.fetch;
+    const firstYear = options?.firstYear ?? CFPB_COMPLAINT_FIRST_YEAR;
+    const newestYear = options?.newestYear ?? new Date().getFullYear();
+    const years = [];
+    for (let year = firstYear; year <= newestYear; year += 1) {
+        const response = await fetchImpl(buildCfpComplaintCountUrl(year));
+        if (!response.ok) {
+            throw new UsSourceApiError('cfpb-consumer-complaints', `HTTP ${response.status} reading the ${String(year)} complaint count`);
+        }
+        years.push({ year, complaintCount: parseCfpComplaintTotal(await response.json()) });
+    }
+    const aggregationResponse = await fetchImpl(buildCfpComplaintAggregationUrl());
+    if (!aggregationResponse.ok) {
+        throw new UsSourceApiError('cfpb-consumer-complaints', `HTTP ${aggregationResponse.status} reading the product and company tallies`);
+    }
+    const { topProducts, topCompanies } = parseCfpComplaintAggregations(await aggregationResponse.json());
+    const newestReceivedDate = await findNewestCfpComplaintDate(fetchImpl);
+    return buildCfpConsumerComplaintSeries({
+        firstYear,
+        newestYear,
+        newestReceivedDate,
+        years,
+        topProducts,
+        topCompanies,
+    });
+}
+/** US Consumer Financial Protection Bureau Consumer Complaint Database, keyless. */
+export const cfpbConsumerComplaintsAdapter = {
+    id: 'cfpb-consumer-complaints',
+    name: 'CFPB consumer complaints',
+    auth: 'none',
+    description: 'Every consumer complaint the Consumer Financial Protection Bureau has sent to a company, counted by year, with the products and companies named most often.',
+    fetchLive: async (options) => fetchCfpConsumerComplaints(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: (payload) => parseCfpComplaintSnapshot(payload),
+    loadFixture: () => parseCfpComplaintSnapshot(readFixtureJson(CFPB_COMPLAINT_FIXTURE_FILENAME)),
+};
+//# sourceMappingURL=cfpbConsumerComplaints.js.map

package/dist/cfpbConsumerComplaints.js.map

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

package/dist/cpscProductRecalls.d.ts

@@ -0,0 +1,146 @@
+import type { UsDataAdapter } from './types.js';
+/** One consumer product recall, trimmed to the fields a story counts. */
+export interface CpscProductRecall {
+    /** The agency's recall number, e.g. "26156". */
+    recallNumber: string;
+    /** Date the recall was published, e.g. "2025-12-18". */
+    recallDate: string;
+    /** Title of the recall notice. */
+    title: string;
+    /** Names of the products the recall covers. */
+    productNames: string[];
+    /** Remedies offered, e.g. "Refund" or "Repair". Empty when none are listed. */
+    remedyOptions: string[];
+    /**
+     * Countries that made the recalled product, e.g. "China". A recall names
+     * every country involved, so one recall can carry several.
+     */
+    manufacturerCountries: string[];
+}
+/** One calendar year of recalls. */
+export interface CpscRecallYearCount {
+    year: number;
+    recallCount: number;
+}
+/** One remedy option and how many recalls offer it. */
+export interface CpscRemedyOptionCount {
+    option: string;
+    recallCount: number;
+}
+/** One manufacturer country and how many recalls name it. */
+export interface CpscManufacturerCountryCount {
+    country: string;
+    recallCount: number;
+}
+/** The recall file folded into the shape a story reads. */
+export interface CpscProductRecallSeries {
+    firstYear: number;
+    /** Newest year in the window. The agency is still filling it. */
+    newestYear: number;
+    /** Date of the newest recall in the file, e.g. "2026-09-24". */
+    newestRecallDate: string;
+    totalRecalls: number;
+    /** One entry per year in the window, oldest first. A year with no recall keeps its zero row. */
+    years: CpscRecallYearCount[];
+    /** Years in the window before the newest one, which is complete. */
+    completeYearCount: number;
+    /** Busiest of the complete years. */
+    busiestCompleteYear: CpscRecallYearCount;
+    /** Quietest of the complete years. */
+    quietestCompleteYear: CpscRecallYearCount;
+    /** Remedy options, most recalls first. */
+    remedyOptions: CpscRemedyOptionCount[];
+    /** Manufacturer countries, most recalls first. */
+    manufacturerCountries: CpscManufacturerCountryCount[];
+}
+/** Window of calendar years one fetch reads. */
+export interface CpscRecallWindow {
+    firstYear: number;
+    newestYear: number;
+}
+/** Base URL for the SaferProducts.gov recall service. */
+export declare const CPSC_RECALL_API_BASE = "https://www.saferproducts.gov/RestWebServices/Recall";
+/**
+ * First calendar year the adapter reads.
+ *
+ * The service holds recalls from the 1970s, but a story that leans on recent
+ * years does not need a fifty-year fetch: every request costs a year of
+ * data, and the counts before 2014 are thin enough that the year-to-year
+ * shape is noise.
+ */
+export declare const CPSC_RECALL_FIRST_YEAR = 2014;
+/**
+ * Recall id the service uses for an error row.
+ *
+ * A failed query does not answer with an HTTP error. It answers 200 with a
+ * single row whose id is 0 and whose title begins "Error retrieving Recalls",
+ * which is why the parser checks the row rather than the status code.
+ */
+export declare const CPSC_ERROR_RECALL_ID = 0;
+/**
+ * Builds the request URL for one calendar year of recalls.
+ *
+ * The service refuses a range wider than a year with a body reading
+ * "The underlying provider failed on Open", so a caller reads one year per
+ * request. The endpoint is keyless.
+ *
+ * @param year - the calendar year to read
+ * @returns the full request URL
+ */
+export declare function buildCpscRecallUrl(year: number): string;
+/**
+ * Parses one year's response into the recalls dated inside that year.
+ *
+ * A failed query answers 200 with a single error row, which stops the parse
+ * rather than counting as a recall. A row dated outside the year asked for is
+ * dropped, so a response that ignored the date filter cannot widen the year.
+ * A row with no recall number or no readable date is a changed shape and also
+ * stops the parse.
+ *
+ * @param payload - the JSON body from the recall service
+ * @param year - the calendar year the request asked for
+ * @returns the recalls dated inside that year, in the order the agency sent them
+ */
+export declare function parseCpscRecallPayload(payload: unknown, year: number): CpscProductRecall[];
+/**
+ * Folds one window of recalls into the counts, the busiest and quietest
+ * complete years, and the remedy and country tallies.
+ *
+ * The newest year in the window is the year the agency is still filling, so
+ * the busiest and quietest years are picked from the years before it.
+ *
+ * @param recalls - the recalls read across the window
+ * @param window - the first and newest year the fetch covered
+ * @returns the counts and the named years
+ */
+export declare function buildCpscProductRecallSeries(recalls: CpscProductRecall[], window: CpscRecallWindow): CpscProductRecallSeries;
+/**
+ * Parses the folded counts a snapshot holds into the story shape.
+ *
+ * A snapshot is written by the daily loop and keeps the counts, not the year
+ * of raw rows they came from. The year counts must add to the file total, so
+ * a snapshot from a half-finished fetch cannot be read as a smaller file.
+ *
+ * @param payload - the JSON body of a committed snapshot
+ * @returns the counts and the named years
+ */
+export declare function parseCpscRecallSnapshot(payload: unknown): CpscProductRecallSeries;
+/**
+ * Reads the recall file one calendar year at a time.
+ *
+ * The window runs from 2014 to the current year, so a build makes one
+ * request per year and reads about thirteen. Each request carries a whole
+ * year as JSON: 2025 is 420 rows in about 1.3 MB. A failed query answers
+ * 200 with an error row, which the parser turns into a thrown error.
+ *
+ * @param options - an optional window and fetch stub
+ * @returns the counts and the named years
+ */
+export declare function fetchCpscProductRecalls(options?: {
+    firstYear?: number;
+    newestYear?: number;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<CpscProductRecallSeries>;
+/** US Consumer Product Safety Commission product recalls, keyless. */
+export declare const cpscProductRecallsAdapter: UsDataAdapter<CpscProductRecallSeries>;
+//# sourceMappingURL=cpscProductRecalls.d.ts.map

package/dist/cpscProductRecalls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cpscProductRecalls.d.ts","sourceRoot":"","sources":["../src/cpscProductRecalls.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,+EAA+E;IAC/E,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC;AAED,oCAAoC;AACpC,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,6DAA6D;AAC7D,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,2DAA2D;AAC3D,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,gGAAgG;IAChG,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,oEAAoE;IACpE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,sCAAsC;IACtC,oBAAoB,EAAE,mBAAmB,CAAC;IAC1C,0CAA0C;IAC1C,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,kDAAkD;IAClD,qBAAqB,EAAE,4BAA4B,EAAE,CAAC;CACvD;AAED,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,yDAAyD,CAAC;AAE3F;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAkEtC;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAmD1F;AAoFD;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,iBAAiB,EAAE,EAC5B,MAAM,EAAE,gBAAgB,GACvB,uBAAuB,CA4CzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,uBAAuB,CAcjF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,CAAC,EAAE;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAmBnC;AAED,sEAAsE;AACtE,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,uBAAuB,CAY5E,CAAC"}