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

package/dist/btsTransportationStats.d.ts

@@ -0,0 +1,87 @@
+import type { UsDataAdapter } from './types.js';
+/** Adapter id for the bts-transportation-stats source. */
+export declare const BTS_TRANSPORTATION_STATS_SOURCE_ID = "bts-transportation-stats";
+/** One catalogue entry from the Socrata discovery API. */
+export interface BtsCatalogueEntry {
+    /** Four-by-four Socrata dataset id, e.g. "ahfs-x44r". */
+    id: string;
+    /** Human-readable title of the dataset, chart, story, or file. */
+    name: string;
+    /** What the entry is: "dataset", "chart", "story", "file", or "href". */
+    assetType: string;
+    /** Publishing office the entry belongs to, or null when the catalogue lists none. */
+    category: string | null;
+    /** How the entry is rendered, e.g. "tabular", "href", or "story". */
+    viewType: string;
+    /** When the entry was created, in seconds since the Unix epoch. */
+    createdAtEpochSeconds: number;
+    /** When the entry was last modified, in seconds since the Unix epoch. */
+    viewLastModifiedEpochSeconds: number;
+    /** How many times the entry has been viewed. */
+    viewCount: number;
+    /** How many times the entry has been downloaded. */
+    downloadCount: number;
+}
+/** One category and how many catalogue entries carry it. */
+export interface BtsCatalogueCategoryCount {
+    category: string;
+    entryCount: number;
+}
+/** One page of the catalogue, folded for a story. */
+export interface BtsTransportationCatalogue {
+    /** One entry per catalogue item in the page. */
+    entries: BtsCatalogueEntry[];
+    entryCount: number;
+    /** Entries whose asset type is "dataset". */
+    datasetCount: number;
+    /** Entry with the latest creation time. Ties go to the earlier list entry. */
+    newestEntry: BtsCatalogueEntry;
+    /**
+     * Categories in the page, most entries first, ties broken by name. An entry
+     * the catalogue lists without a category is counted under "Uncategorised".
+     */
+    categories: BtsCatalogueCategoryCount[];
+}
+/** Base URL for the Bureau of Transportation Statistics Socrata catalogue. */
+export declare const BTS_TRANSPORTATION_STATS_API_BASE = "https://data.bts.gov/api/views.json";
+/** How many catalogue entries one request reads. */
+export declare const BTS_TRANSPORTATION_STATS_LIMIT = 10;
+/**
+ * Builds the request URL for one page of the catalogue.
+ *
+ * The endpoint is keyless. The service answers the whole catalogue by default,
+ * so the adapter asks for a short page.
+ *
+ * @param options - an optional entry cap
+ * @returns the full request URL
+ */
+export declare function buildBtsTransportationStatsUrl(options?: {
+    limit?: number;
+}): string;
+/**
+ * Parses one page of the catalogue into the entries and the category counts.
+ *
+ * An entry without an id, a name, or a creation time is a changed shape and
+ * stops the parse. An empty page also stops the parse, because a catalogue
+ * with no entries is not a usable answer.
+ *
+ * @param payload - the JSON body from the Socrata discovery API
+ * @returns the entries in the page, the counts, and the newest entry
+ */
+export declare function parseBtsTransportationStatsPayload(payload: unknown): BtsTransportationCatalogue;
+/**
+ * Reads one page of the Bureau of Transportation Statistics catalogue.
+ *
+ * One keyless request covers the page and reports what the catalogue holds,
+ * without reading any dataset's rows.
+ *
+ * @param options - an optional entry cap and fetch stub
+ * @returns the entries in the page, the counts, and the newest entry
+ */
+export declare function fetchBtsTransportationStats(options?: {
+    limit?: number;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<BtsTransportationCatalogue>;
+/** Bureau of Transportation Statistics catalogue of datasets, charts, and stories, keyless. */
+export declare const btsTransportationStatsAdapter: UsDataAdapter<BtsTransportationCatalogue>;
+//# sourceMappingURL=btsTransportationStats.d.ts.map

package/dist/btsTransportationStats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"btsTransportationStats.d.ts","sourceRoot":"","sources":["../src/btsTransportationStats.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,0DAA0D;AAC1D,eAAO,MAAM,kCAAkC,6BAA6B,CAAC;AAE7E,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,4BAA4B,EAAE,MAAM,CAAC;IACrC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,4DAA4D;AAC5D,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qDAAqD;AACrD,MAAM,WAAW,0BAA0B;IACzC,gDAAgD;IAChD,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,EAAE,iBAAiB,CAAC;IAC/B;;;OAGG;IACH,UAAU,EAAE,yBAAyB,EAAE,CAAC;CACzC;AAED,8EAA8E;AAC9E,eAAO,MAAM,iCAAiC,wCAAwC,CAAC;AAEvF,oDAAoD;AACpD,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAkDjD;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAKnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAAC,OAAO,EAAE,OAAO,GAAG,0BAA0B,CAuC/F;AAED;;;;;;;;GAQG;AACH,wBAAsB,2BAA2B,CAAC,OAAO,CAAC,EAAE;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAatC;AAED,+FAA+F;AAC/F,eAAO,MAAM,6BAA6B,EAAE,aAAa,CAAC,0BAA0B,CAanF,CAAC"}

package/dist/btsTransportationStats.js

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+import { UsSourceApiError, UsSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/** Adapter id for the bts-transportation-stats source. */
+export const BTS_TRANSPORTATION_STATS_SOURCE_ID = 'bts-transportation-stats';
+/** Base URL for the Bureau of Transportation Statistics Socrata catalogue. */
+export const BTS_TRANSPORTATION_STATS_API_BASE = 'https://data.bts.gov/api/views.json';
+/** How many catalogue entries one request reads. */
+export const BTS_TRANSPORTATION_STATS_LIMIT = 10;
+/** Committed snapshot, so a build works when the Bureau of Transportation Statistics host is unreachable. */
+const BTS_TRANSPORTATION_STATS_FIXTURE_FILENAME = 'bts-transportation-stats-2026-10-05.json';
+/** Category bucket the adapter uses for an entry the catalogue lists without one. */
+const BTS_TRANSPORTATION_UNCATEGORISED = 'Uncategorised';
+// The discovery API sends a bare JSON array. A value the catalogue does not
+// carry arrives as null, and every count arrives as a number.
+const BTS_TRANSPORTATION_STATS_ENTRY_SCHEMA = z.object({
+    id: z.string().optional(),
+    name: z.string().optional(),
+    assetType: z.string().optional(),
+    category: z.string().nullable().optional(),
+    viewType: z.string().optional(),
+    createdAt: z.number().optional(),
+    viewLastModified: z.number().optional(),
+    viewCount: z.number().optional(),
+    downloadCount: z.number().optional(),
+});
+const BTS_TRANSPORTATION_STATS_PAYLOAD_SCHEMA = z.array(BTS_TRANSPORTATION_STATS_ENTRY_SCHEMA);
+/** Counts entries per category, most entries first, ties by name. */
+function countBtsCatalogueCategories(entries) {
+    const counts = new Map();
+    for (const entry of entries) {
+        const category = entry.category ?? BTS_TRANSPORTATION_UNCATEGORISED;
+        counts.set(category, (counts.get(category) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort(([leftCategory, leftCount], [rightCategory, rightCount]) => leftCount === rightCount ? leftCategory.localeCompare(rightCategory) : rightCount - leftCount)
+        .map(([category, entryCount]) => ({ category, entryCount }));
+}
+/** Picks the entry with the latest creation time, ties to the earlier entry. */
+function newestBtsCatalogueEntry(entries) {
+    const first = entries[0];
+    if (first === undefined) {
+        throw new UsSourceParseError(BTS_TRANSPORTATION_STATS_SOURCE_ID, 'No entries to summarise');
+    }
+    return entries.reduce((best, entry) => (entry.createdAtEpochSeconds > best.createdAtEpochSeconds ? entry : best), first);
+}
+/**
+ * Builds the request URL for one page of the catalogue.
+ *
+ * The endpoint is keyless. The service answers the whole catalogue by default,
+ * so the adapter asks for a short page.
+ *
+ * @param options - an optional entry cap
+ * @returns the full request URL
+ */
+export function buildBtsTransportationStatsUrl(options) {
+    const params = new URLSearchParams({
+        limit: String(options?.limit ?? BTS_TRANSPORTATION_STATS_LIMIT),
+    });
+    return `https://data.bts.gov/api/views.json?${params.toString()}`;
+}
+/**
+ * Parses one page of the catalogue into the entries and the category counts.
+ *
+ * An entry without an id, a name, or a creation time is a changed shape and
+ * stops the parse. An empty page also stops the parse, because a catalogue
+ * with no entries is not a usable answer.
+ *
+ * @param payload - the JSON body from the Socrata discovery API
+ * @returns the entries in the page, the counts, and the newest entry
+ */
+export function parseBtsTransportationStatsPayload(payload) {
+    const parsed = BTS_TRANSPORTATION_STATS_PAYLOAD_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError(BTS_TRANSPORTATION_STATS_SOURCE_ID, parsed.error.message);
+    }
+    if (parsed.data.length === 0) {
+        throw new UsSourceParseError(BTS_TRANSPORTATION_STATS_SOURCE_ID, 'The response carried no entries');
+    }
+    const entries = parsed.data.map((row) => {
+        if (row.id === undefined || row.name === undefined || row.createdAt === undefined) {
+            throw new UsSourceParseError(BTS_TRANSPORTATION_STATS_SOURCE_ID, 'A catalogue entry arrived without its id, name, or creation time');
+        }
+        return {
+            id: row.id,
+            name: row.name,
+            assetType: row.assetType ?? '',
+            category: row.category ?? null,
+            viewType: row.viewType ?? '',
+            createdAtEpochSeconds: row.createdAt,
+            viewLastModifiedEpochSeconds: row.viewLastModified ?? row.createdAt,
+            viewCount: row.viewCount ?? 0,
+            downloadCount: row.downloadCount ?? 0,
+        };
+    });
+    return {
+        entries,
+        entryCount: entries.length,
+        datasetCount: entries.filter((entry) => entry.assetType === 'dataset').length,
+        newestEntry: newestBtsCatalogueEntry(entries),
+        categories: countBtsCatalogueCategories(entries),
+    };
+}
+/**
+ * Reads one page of the Bureau of Transportation Statistics catalogue.
+ *
+ * One keyless request covers the page and reports what the catalogue holds,
+ * without reading any dataset's rows.
+ *
+ * @param options - an optional entry cap and fetch stub
+ * @returns the entries in the page, the counts, and the newest entry
+ */
+export async function fetchBtsTransportationStats(options) {
+    const fetchImpl = options?.fetchImpl ?? globalThis.fetch;
+    const url = buildBtsTransportationStatsUrl(options?.limit === undefined ? {} : { limit: options.limit });
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new UsSourceApiError(BTS_TRANSPORTATION_STATS_SOURCE_ID, `HTTP ${response.status} reading the catalogue`);
+    }
+    return parseBtsTransportationStatsPayload(await response.json());
+}
+/** Bureau of Transportation Statistics catalogue of datasets, charts, and stories, keyless. */
+export const btsTransportationStatsAdapter = {
+    id: BTS_TRANSPORTATION_STATS_SOURCE_ID,
+    name: 'BTS transportation statistics',
+    auth: 'none',
+    description: 'The Bureau of Transportation Statistics Socrata catalogue, one row per published dataset, chart, or story, with its category, view count, and download count.',
+    fetchLive: async (options) => fetchBtsTransportationStats(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: (payload) => parseBtsTransportationStatsPayload(payload),
+    loadFixture: () => parseBtsTransportationStatsPayload(readFixtureJson(BTS_TRANSPORTATION_STATS_FIXTURE_FILENAME)),
+};
+//# sourceMappingURL=btsTransportationStats.js.map

package/dist/btsTransportationStats.js.map

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

package/dist/cdcSocrataCatalogue.d.ts

@@ -0,0 +1,87 @@
+import type { UsDataAdapter } from './types.js';
+/** Adapter id for the cdc-socrata-catalogue source. */
+export declare const CDC_SOCRATA_CATALOGUE_SOURCE_ID = "cdc-socrata-catalogue";
+/** One catalogue entry from the Socrata discovery API. */
+export interface CdcSocrataCatalogueEntry {
+    /** Four-by-four Socrata dataset id, e.g. "ahfs-x44r". */
+    id: string;
+    /** Human-readable title of the dataset, chart, story, or file. */
+    name: string;
+    /** What the entry is: "dataset", "chart", "story", "file", or "href". */
+    assetType: string;
+    /** Publishing office the entry belongs to, or null when the catalogue lists none. */
+    category: string | null;
+    /** How the entry is rendered, e.g. "tabular", "href", or "story". */
+    viewType: string;
+    /** When the entry was created, in seconds since the Unix epoch. */
+    createdAtEpochSeconds: number;
+    /** When the entry was last modified, in seconds since the Unix epoch. */
+    viewLastModifiedEpochSeconds: number;
+    /** How many times the entry has been viewed. */
+    viewCount: number;
+    /** How many times the entry has been downloaded. */
+    downloadCount: number;
+}
+/** One category and how many catalogue entries carry it. */
+export interface CdcSocrataCategoryCount {
+    category: string;
+    entryCount: number;
+}
+/** One page of the catalogue, folded for a story. */
+export interface CdcSocrataCatalogue {
+    /** One entry per catalogue item in the page. */
+    entries: CdcSocrataCatalogueEntry[];
+    entryCount: number;
+    /** Entries whose asset type is "dataset". */
+    datasetCount: number;
+    /** Entry with the latest creation time. Ties go to the earlier list entry. */
+    newestEntry: CdcSocrataCatalogueEntry;
+    /**
+     * Categories in the page, most entries first, ties broken by name. An entry
+     * the catalogue lists without a category is counted under "Uncategorised".
+     */
+    categories: CdcSocrataCategoryCount[];
+}
+/** Base URL for the CDC Socrata catalogue. */
+export declare const CDC_SOCRATA_CATALOGUE_API_BASE = "https://data.cdc.gov/api/views.json";
+/** How many catalogue entries one request reads. */
+export declare const CDC_SOCRATA_CATALOGUE_LIMIT = 10;
+/**
+ * Builds the request URL for one page of the catalogue.
+ *
+ * The endpoint is keyless. The service answers the whole catalogue by default,
+ * so the adapter asks for a short page.
+ *
+ * @param options - an optional entry cap
+ * @returns the full request URL
+ */
+export declare function buildCdcSocrataCatalogueUrl(options?: {
+    limit?: number;
+}): string;
+/**
+ * Parses one page of the catalogue into the entries and the category counts.
+ *
+ * An entry without an id, a name, or a creation time is a changed shape and
+ * stops the parse. An empty page also stops the parse, because a catalogue
+ * with no entries is not a usable answer.
+ *
+ * @param payload - the JSON body from the Socrata discovery API
+ * @returns the entries in the page, the counts, and the newest entry
+ */
+export declare function parseCdcSocrataCataloguePayload(payload: unknown): CdcSocrataCatalogue;
+/**
+ * Reads one page of the CDC catalogue.
+ *
+ * One keyless request covers the page and reports what the catalogue holds,
+ * without reading any dataset's rows.
+ *
+ * @param options - an optional entry cap and fetch stub
+ * @returns the entries in the page, the counts, and the newest entry
+ */
+export declare function fetchCdcSocrataCatalogue(options?: {
+    limit?: number;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<CdcSocrataCatalogue>;
+/** CDC Socrata catalogue of datasets, charts, and stories, keyless. */
+export declare const cdcSocrataCatalogueAdapter: UsDataAdapter<CdcSocrataCatalogue>;
+//# sourceMappingURL=cdcSocrataCatalogue.d.ts.map

package/dist/cdcSocrataCatalogue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdcSocrataCatalogue.d.ts","sourceRoot":"","sources":["../src/cdcSocrataCatalogue.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,uDAAuD;AACvD,eAAO,MAAM,+BAA+B,0BAA0B,CAAC;AAEvE,0DAA0D;AAC1D,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,4BAA4B,EAAE,MAAM,CAAC;IACrC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,4DAA4D;AAC5D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qDAAqD;AACrD,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,EAAE,wBAAwB,CAAC;IACtC;;;OAGG;IACH,UAAU,EAAE,uBAAuB,EAAE,CAAC;CACvC;AAED,8CAA8C;AAC9C,eAAO,MAAM,8BAA8B,wCAAwC,CAAC;AAEpF,oDAAoD;AACpD,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAkD9C;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAKhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAuCrF;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,CAAC,EAAE;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAa/B;AAED,uEAAuE;AACvE,eAAO,MAAM,0BAA0B,EAAE,aAAa,CAAC,mBAAmB,CAazE,CAAC"}

package/dist/cdcSocrataCatalogue.js

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+import { UsSourceApiError, UsSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/** Adapter id for the cdc-socrata-catalogue source. */
+export const CDC_SOCRATA_CATALOGUE_SOURCE_ID = 'cdc-socrata-catalogue';
+/** Base URL for the CDC Socrata catalogue. */
+export const CDC_SOCRATA_CATALOGUE_API_BASE = 'https://data.cdc.gov/api/views.json';
+/** How many catalogue entries one request reads. */
+export const CDC_SOCRATA_CATALOGUE_LIMIT = 10;
+/** Committed snapshot, so a build works when the CDC host is unreachable. */
+const CDC_SOCRATA_CATALOGUE_FIXTURE_FILENAME = 'cdc-socrata-catalogue-2026-10-05.json';
+/** Category bucket the adapter uses for an entry the catalogue lists without one. */
+const CDC_SOCRATA_UNCATEGORISED = 'Uncategorised';
+// The discovery API sends a bare JSON array. A value the catalogue does not
+// carry arrives as null, and every count arrives as a number.
+const CDC_SOCRATA_CATALOGUE_ENTRY_SCHEMA = z.object({
+    id: z.string().optional(),
+    name: z.string().optional(),
+    assetType: z.string().optional(),
+    category: z.string().nullable().optional(),
+    viewType: z.string().optional(),
+    createdAt: z.number().optional(),
+    viewLastModified: z.number().optional(),
+    viewCount: z.number().optional(),
+    downloadCount: z.number().optional(),
+});
+const CDC_SOCRATA_CATALOGUE_PAYLOAD_SCHEMA = z.array(CDC_SOCRATA_CATALOGUE_ENTRY_SCHEMA);
+/** Counts entries per category, most entries first, ties by name. */
+function countCdcSocrataCategories(entries) {
+    const counts = new Map();
+    for (const entry of entries) {
+        const category = entry.category ?? CDC_SOCRATA_UNCATEGORISED;
+        counts.set(category, (counts.get(category) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort(([leftCategory, leftCount], [rightCategory, rightCount]) => leftCount === rightCount ? leftCategory.localeCompare(rightCategory) : rightCount - leftCount)
+        .map(([category, entryCount]) => ({ category, entryCount }));
+}
+/** Picks the entry with the latest creation time, ties to the earlier entry. */
+function newestCdcSocrataEntry(entries) {
+    const first = entries[0];
+    if (first === undefined) {
+        throw new UsSourceParseError(CDC_SOCRATA_CATALOGUE_SOURCE_ID, 'No entries to summarise');
+    }
+    return entries.reduce((best, entry) => (entry.createdAtEpochSeconds > best.createdAtEpochSeconds ? entry : best), first);
+}
+/**
+ * Builds the request URL for one page of the catalogue.
+ *
+ * The endpoint is keyless. The service answers the whole catalogue by default,
+ * so the adapter asks for a short page.
+ *
+ * @param options - an optional entry cap
+ * @returns the full request URL
+ */
+export function buildCdcSocrataCatalogueUrl(options) {
+    const params = new URLSearchParams({
+        limit: String(options?.limit ?? CDC_SOCRATA_CATALOGUE_LIMIT),
+    });
+    return `https://data.cdc.gov/api/views.json?${params.toString()}`;
+}
+/**
+ * Parses one page of the catalogue into the entries and the category counts.
+ *
+ * An entry without an id, a name, or a creation time is a changed shape and
+ * stops the parse. An empty page also stops the parse, because a catalogue
+ * with no entries is not a usable answer.
+ *
+ * @param payload - the JSON body from the Socrata discovery API
+ * @returns the entries in the page, the counts, and the newest entry
+ */
+export function parseCdcSocrataCataloguePayload(payload) {
+    const parsed = CDC_SOCRATA_CATALOGUE_PAYLOAD_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError(CDC_SOCRATA_CATALOGUE_SOURCE_ID, parsed.error.message);
+    }
+    if (parsed.data.length === 0) {
+        throw new UsSourceParseError(CDC_SOCRATA_CATALOGUE_SOURCE_ID, 'The response carried no entries');
+    }
+    const entries = parsed.data.map((row) => {
+        if (row.id === undefined || row.name === undefined || row.createdAt === undefined) {
+            throw new UsSourceParseError(CDC_SOCRATA_CATALOGUE_SOURCE_ID, 'A catalogue entry arrived without its id, name, or creation time');
+        }
+        return {
+            id: row.id,
+            name: row.name,
+            assetType: row.assetType ?? '',
+            category: row.category ?? null,
+            viewType: row.viewType ?? '',
+            createdAtEpochSeconds: row.createdAt,
+            viewLastModifiedEpochSeconds: row.viewLastModified ?? row.createdAt,
+            viewCount: row.viewCount ?? 0,
+            downloadCount: row.downloadCount ?? 0,
+        };
+    });
+    return {
+        entries,
+        entryCount: entries.length,
+        datasetCount: entries.filter((entry) => entry.assetType === 'dataset').length,
+        newestEntry: newestCdcSocrataEntry(entries),
+        categories: countCdcSocrataCategories(entries),
+    };
+}
+/**
+ * Reads one page of the CDC catalogue.
+ *
+ * One keyless request covers the page and reports what the catalogue holds,
+ * without reading any dataset's rows.
+ *
+ * @param options - an optional entry cap and fetch stub
+ * @returns the entries in the page, the counts, and the newest entry
+ */
+export async function fetchCdcSocrataCatalogue(options) {
+    const fetchImpl = options?.fetchImpl ?? globalThis.fetch;
+    const url = buildCdcSocrataCatalogueUrl(options?.limit === undefined ? {} : { limit: options.limit });
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new UsSourceApiError(CDC_SOCRATA_CATALOGUE_SOURCE_ID, `HTTP ${response.status} reading the catalogue`);
+    }
+    return parseCdcSocrataCataloguePayload(await response.json());
+}
+/** CDC Socrata catalogue of datasets, charts, and stories, keyless. */
+export const cdcSocrataCatalogueAdapter = {
+    id: CDC_SOCRATA_CATALOGUE_SOURCE_ID,
+    name: 'CDC Socrata catalogue',
+    auth: 'none',
+    description: "The CDC's Socrata catalogue, one row per published dataset, chart, or story, with its category, view count, and download count.",
+    fetchLive: async (options) => fetchCdcSocrataCatalogue(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: (payload) => parseCdcSocrataCataloguePayload(payload),
+    loadFixture: () => parseCdcSocrataCataloguePayload(readFixtureJson(CDC_SOCRATA_CATALOGUE_FIXTURE_FILENAME)),
+};
+//# sourceMappingURL=cdcSocrataCatalogue.js.map

package/dist/cdcSocrataCatalogue.js.map

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

package/dist/clinicalTrialsStudies.d.ts

@@ -0,0 +1,92 @@
+import type { UsDataAdapter } from './types.js';
+/** Adapter id for the ClinicalTrials.gov studies source. */
+export declare const CLINICALTRIALS_STUDIES_SOURCE_ID = "clinicaltrials-studies";
+/** One registered clinical study, trimmed to the fields a story reads. */
+export interface ClinicalTrialStudy {
+    /** The registry's own study id, e.g. "NCT07065435". */
+    nctId: string;
+    /** Short title the sponsor registered. */
+    briefTitle: string;
+    /** Recruitment status, e.g. "RECRUITING" or "COMPLETED". */
+    overallStatus: string;
+    /** Study type, e.g. "INTERVENTIONAL" or "OBSERVATIONAL", or null when absent. */
+    studyType: string | null;
+    /** Trial phases, e.g. ["PHASE2"]. Empty for observational studies. */
+    phases: string[];
+    /** Conditions the study covers. */
+    conditions: string[];
+    /** Name of the lead sponsor, or null when the study names none. */
+    leadSponsor: string | null;
+    /** Number of participants the study plans or enrolled, or null when absent. */
+    enrollmentCount: number | null;
+    /** Whether the enrollment count is expected or actual, or null when absent. */
+    enrollmentType: string | null;
+    /**
+     * Date the study started. ClinicalTrials.gov writes a day-precision date
+     * when it has one and a month-precision date such as "2000-10" when it does
+     * not, so the adapter keeps the string as the registry wrote it.
+     */
+    startDate: string | null;
+    /** Date of the study's latest update post, or null when absent. */
+    lastUpdatePostDate: string | null;
+}
+/** One recruitment status and how many studies in the page carry it. */
+export interface ClinicalTrialStatusCount {
+    status: string;
+    studyCount: number;
+}
+/** One page of studies, folded for a story. */
+export interface ClinicalTrialStudyPage {
+    /** One entry per study in the page. */
+    studies: ClinicalTrialStudy[];
+    studyCount: number;
+    /** Recruitment statuses in the page, most studies first, ties by status name. */
+    statusCounts: ClinicalTrialStatusCount[];
+    /** Token for the next page of the same query, or null on the last page. */
+    nextPageToken: string | null;
+}
+/** Base URL for the ClinicalTrials.gov studies API. */
+export declare const CLINICALTRIALS_STUDIES_API_BASE = "https://clinicaltrials.gov/api/v2/studies";
+/** Page size for one request. */
+export declare const CLINICALTRIALS_STUDIES_PAGE_SIZE = 10;
+/**
+ * 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 declare function buildClinicalTrialsStudiesUrl(options?: {
+    pageSize?: number;
+}): string;
+/**
+ * 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 declare function parseClinicalTrialsStudiesPayload(payload: unknown): ClinicalTrialStudyPage;
+/**
+ * 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 declare function fetchClinicalTrialsStudies(options?: {
+    pageSize?: number;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<ClinicalTrialStudyPage>;
+/** ClinicalTrials.gov registered studies, one row per study, keyless. */
+export declare const clinicalTrialsStudiesAdapter: UsDataAdapter<ClinicalTrialStudyPage>;
+//# sourceMappingURL=clinicalTrialsStudies.d.ts.map

package/dist/clinicalTrialsStudies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clinicalTrialsStudies.d.ts","sourceRoot":"","sources":["../src/clinicalTrialsStudies.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,4DAA4D;AAC5D,eAAO,MAAM,gCAAgC,2BAA2B,CAAC;AAEzE,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sEAAsE;IACtE,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,mCAAmC;IACnC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,mEAAmE;IACnE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,+EAA+E;IAC/E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,+EAA+E;IAC/E,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mEAAmE;IACnE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,wEAAwE;AACxE,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,uCAAuC;IACvC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,YAAY,EAAE,wBAAwB,EAAE,CAAC;IACzC,2EAA2E;IAC3E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,uDAAuD;AACvD,eAAO,MAAM,+BAA+B,8CAA8C,CAAC;AAE3F,iCAAiC;AACjC,eAAO,MAAM,gCAAgC,KAAK,CAAC;AAwCnD;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAKrF;AAeD;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,OAAO,GAAG,sBAAsB,CA+C1F;AAED;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,CAAC,EAAE;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAalC;AAED,yEAAyE;AACzE,eAAO,MAAM,4BAA4B,EAAE,aAAa,CAAC,sBAAsB,CAa9E,CAAC"}