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

package/dist/nwsPointForecast.d.ts

@@ -0,0 +1,99 @@
+import type { UsDataAdapter } from './types.js';
+/** Adapter id for the National Weather Service point-forecast source. */
+export declare const NWS_POINT_FORECAST_SOURCE_ID = "nws-point-forecast";
+/**
+ * User-Agent header the National Weather Service asks every caller to send.
+ *
+ * The service returns an error page to a request that does not identify its
+ * operator, so the adapter sends a descriptive name and a contact address on
+ * every call. A real deployment should override the contact with its own.
+ */
+export declare const NWS_USER_AGENT = "usa-open-data-connectors contact@example.com";
+/**
+ * One forecast grid point, the service's lookup for a latitude and longitude.
+ *
+ * The point does not carry the forecast itself. It carries the grid the
+ * service snapped the coordinate to, plus the URLs that lead to the forecast,
+ * the hourly forecast, the raw grid data, and the nearby observations.
+ */
+export interface NwsForecastPoint {
+    /** Latitude of the point, as the service echoed it back. */
+    latitude: number;
+    /** Longitude of the point, as the service echoed it back. */
+    longitude: number;
+    /** City or place the point falls in, e.g. "Washington". */
+    city: string;
+    /** Two-letter state code the point falls in, e.g. "DC". */
+    state: string;
+    /** Forecast office code, e.g. "LWX". */
+    gridId: string;
+    gridX: number;
+    gridY: number;
+    /** URL of the forecast office that covers the point. */
+    forecastOfficeUrl: string;
+    /** URL of the daily forecast for the point. */
+    forecastUrl: string;
+    /** URL of the hourly forecast for the point. */
+    forecastHourlyUrl: string;
+    /** URL of the raw forecast grid data behind the point. */
+    forecastGridDataUrl: string;
+    /** URL of the observation stations near the point. */
+    observationStationsUrl: string;
+    /** Timezone the office uses, e.g. "America/New_York". */
+    timeZone: string;
+    /** Radar station code the office uses, or null when the service names none. */
+    radarStation: string | null;
+    /** URL of the county zone the point falls in. */
+    countyUrl: string;
+    /** URL of the fire weather zone the point falls in. */
+    fireWeatherZoneUrl: string;
+}
+/** Base URL for the National Weather Service API. */
+export declare const NWS_API_BASE = "https://api.weather.gov";
+/** Path of the point lookup that resolves a coordinate to a forecast grid. */
+export declare const NWS_POINT_FORECAST_PATH = "/points";
+/** Latitude of the default point, the Washington Monument in Washington, DC. */
+export declare const NWS_DEFAULT_LATITUDE = 38.8894;
+/** Longitude of the default point, the Washington Monument in Washington, DC. */
+export declare const NWS_DEFAULT_LONGITUDE = -77.0352;
+/**
+ * Builds the request URL for one point lookup.
+ *
+ * The endpoint is keyless. Coordinates are written the way the service takes
+ * them, latitude first and longitude second, with no space after the comma.
+ *
+ * @param latitude - the latitude to look up
+ * @param longitude - the longitude to look up
+ * @returns the full request URL
+ */
+export declare function buildNwsPointUrl(latitude?: number, longitude?: number): string;
+/**
+ * Parses one point lookup into the grid point and its forecast URLs.
+ *
+ * The service answers with a GeoJSON feature. A response whose type is not a
+ * feature or whose coordinates are not a latitude and longitude pair is a
+ * changed shape and stops the parse. The forecast and grid fields must also
+ * be present, because a point without them is not usable as a forecast entry.
+ *
+ * @param payload - the JSON body from the weather service
+ * @returns the grid point, its place, and the URLs that lead to the forecast
+ */
+export declare function parseNwsPointForecastPayload(payload: unknown): NwsForecastPoint;
+/**
+ * Reads one forecast grid point from the weather service.
+ *
+ * The service asks every caller to identify itself, so the request carries a
+ * descriptive User-Agent header. One keyless request resolves the coordinate
+ * to a grid point and returns the URLs that lead to the forecast.
+ *
+ * @param options - an optional latitude and longitude, plus a fetch stub
+ * @returns the grid point, its place, and the URLs that lead to the forecast
+ */
+export declare function fetchNwsPointForecast(options?: {
+    latitude?: number;
+    longitude?: number;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<NwsForecastPoint>;
+/** National Weather Service forecast grid point for a coordinate, keyless. */
+export declare const nwsPointForecastAdapter: UsDataAdapter<NwsForecastPoint>;
+//# sourceMappingURL=nwsPointForecast.d.ts.map

package/dist/nwsPointForecast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nwsPointForecast.d.ts","sourceRoot":"","sources":["../src/nwsPointForecast.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,yEAAyE;AACzE,eAAO,MAAM,4BAA4B,uBAAuB,CAAC;AAEjE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,iDAAiD,CAAC;AAE7E;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,sBAAsB,EAAE,MAAM,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,qDAAqD;AACrD,eAAO,MAAM,YAAY,4BAA4B,CAAC;AAEtD,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,YAAY,CAAC;AAEjD,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,UAAU,CAAC;AAE5C,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,WAAW,CAAC;AAmC9C;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,GAAE,MAA6B,EACvC,SAAS,GAAE,MAA8B,GACxC,MAAM,CAER;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CAsD/E;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,CAAC,EAAE;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAc5B;AAED,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,EAAE,aAAa,CAAC,gBAAgB,CAWnE,CAAC"}

package/dist/nwsPointForecast.js

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+import { UsSourceApiError, UsSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/** Adapter id for the National Weather Service point-forecast source. */
+export const NWS_POINT_FORECAST_SOURCE_ID = 'nws-point-forecast';
+/**
+ * User-Agent header the National Weather Service asks every caller to send.
+ *
+ * The service returns an error page to a request that does not identify its
+ * operator, so the adapter sends a descriptive name and a contact address on
+ * every call. A real deployment should override the contact with its own.
+ */
+export const NWS_USER_AGENT = 'usa-open-data-connectors contact@example.com';
+/** Base URL for the National Weather Service API. */
+export const NWS_API_BASE = 'https://api.weather.gov';
+/** Path of the point lookup that resolves a coordinate to a forecast grid. */
+export const NWS_POINT_FORECAST_PATH = '/points';
+/** Latitude of the default point, the Washington Monument in Washington, DC. */
+export const NWS_DEFAULT_LATITUDE = 38.8894;
+/** Longitude of the default point, the Washington Monument in Washington, DC. */
+export const NWS_DEFAULT_LONGITUDE = -77.0352;
+/** Committed snapshot, so a build works when the weather service is unreachable. */
+const NWS_POINT_FORECAST_FIXTURE_FILENAME = 'nws-point-forecast-2026-10-05.json';
+const NWS_PROPERTIES_SCHEMA = z.object({
+    city: z.string().optional(),
+    state: z.string().optional(),
+    gridId: z.string().optional(),
+    gridX: z.number().optional(),
+    gridY: z.number().optional(),
+    forecastOffice: z.string().optional(),
+    forecast: z.string().optional(),
+    forecastHourly: z.string().optional(),
+    forecastGridData: z.string().optional(),
+    observationStations: z.string().optional(),
+    timeZone: z.string().optional(),
+    radarStation: z.string().optional(),
+    county: z.string().optional(),
+    fireWeatherZone: z.string().optional(),
+    relativeLocation: z
+        .object({
+        properties: z
+            .object({ city: z.string().optional(), state: z.string().optional() })
+            .optional(),
+    })
+        .optional(),
+});
+const NWS_POINT_FORECAST_SCHEMA = z.object({
+    type: z.string().optional(),
+    geometry: z.object({ coordinates: z.array(z.number()).optional() }).optional(),
+    properties: NWS_PROPERTIES_SCHEMA.optional(),
+});
+/**
+ * Builds the request URL for one point lookup.
+ *
+ * The endpoint is keyless. Coordinates are written the way the service takes
+ * them, latitude first and longitude second, with no space after the comma.
+ *
+ * @param latitude - the latitude to look up
+ * @param longitude - the longitude to look up
+ * @returns the full request URL
+ */
+export function buildNwsPointUrl(latitude = NWS_DEFAULT_LATITUDE, longitude = NWS_DEFAULT_LONGITUDE) {
+    return `${NWS_API_BASE}${NWS_POINT_FORECAST_PATH}/${latitude},${longitude}`;
+}
+/**
+ * Parses one point lookup into the grid point and its forecast URLs.
+ *
+ * The service answers with a GeoJSON feature. A response whose type is not a
+ * feature or whose coordinates are not a latitude and longitude pair is a
+ * changed shape and stops the parse. The forecast and grid fields must also
+ * be present, because a point without them is not usable as a forecast entry.
+ *
+ * @param payload - the JSON body from the weather service
+ * @returns the grid point, its place, and the URLs that lead to the forecast
+ */
+export function parseNwsPointForecastPayload(payload) {
+    const parsed = NWS_POINT_FORECAST_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError(NWS_POINT_FORECAST_SOURCE_ID, parsed.error.message);
+    }
+    if (parsed.data.type !== 'Feature') {
+        throw new UsSourceParseError(NWS_POINT_FORECAST_SOURCE_ID, `The response is not a GeoJSON feature: ${parsed.data.type ?? 'missing type'}`);
+    }
+    const coordinates = parsed.data.geometry?.coordinates;
+    const longitude = coordinates?.[0];
+    const latitude = coordinates?.[1];
+    if (longitude === undefined || latitude === undefined) {
+        throw new UsSourceParseError(NWS_POINT_FORECAST_SOURCE_ID, 'The response carried no coordinate pair');
+    }
+    const properties = parsed.data.properties;
+    if (properties?.gridId === undefined ||
+        properties.gridX === undefined ||
+        properties.gridY === undefined ||
+        properties.forecast === undefined ||
+        properties.forecastOffice === undefined) {
+        throw new UsSourceParseError(NWS_POINT_FORECAST_SOURCE_ID, 'The response carried no forecast grid for the point');
+    }
+    return {
+        latitude,
+        longitude,
+        city: properties.relativeLocation?.properties?.city ?? '',
+        state: properties.relativeLocation?.properties?.state ?? '',
+        gridId: properties.gridId,
+        gridX: properties.gridX,
+        gridY: properties.gridY,
+        forecastOfficeUrl: properties.forecastOffice,
+        forecastUrl: properties.forecast,
+        forecastHourlyUrl: properties.forecastHourly ?? '',
+        forecastGridDataUrl: properties.forecastGridData ?? '',
+        observationStationsUrl: properties.observationStations ?? '',
+        timeZone: properties.timeZone ?? '',
+        radarStation: properties.radarStation ?? null,
+        countyUrl: properties.county ?? '',
+        fireWeatherZoneUrl: properties.fireWeatherZone ?? '',
+    };
+}
+/**
+ * Reads one forecast grid point from the weather service.
+ *
+ * The service asks every caller to identify itself, so the request carries a
+ * descriptive User-Agent header. One keyless request resolves the coordinate
+ * to a grid point and returns the URLs that lead to the forecast.
+ *
+ * @param options - an optional latitude and longitude, plus a fetch stub
+ * @returns the grid point, its place, and the URLs that lead to the forecast
+ */
+export async function fetchNwsPointForecast(options) {
+    const fetchImpl = options?.fetchImpl ?? globalThis.fetch;
+    const url = buildNwsPointUrl(options?.latitude ?? NWS_DEFAULT_LATITUDE, options?.longitude ?? NWS_DEFAULT_LONGITUDE);
+    const response = await fetchImpl(url, { headers: { 'User-Agent': NWS_USER_AGENT } });
+    if (!response.ok) {
+        throw new UsSourceApiError(NWS_POINT_FORECAST_SOURCE_ID, `HTTP ${response.status} reading the point forecast`);
+    }
+    return parseNwsPointForecastPayload(await response.json());
+}
+/** National Weather Service forecast grid point for a coordinate, keyless. */
+export const nwsPointForecastAdapter = {
+    id: NWS_POINT_FORECAST_SOURCE_ID,
+    name: 'NWS point forecast',
+    auth: 'none',
+    description: 'The National Weather Service forecast grid point for a latitude and longitude, with the URLs that lead to the daily and hourly forecast.',
+    fetchLive: async (options) => fetchNwsPointForecast(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: (payload) => parseNwsPointForecastPayload(payload),
+    loadFixture: () => parseNwsPointForecastPayload(readFixtureJson(NWS_POINT_FORECAST_FIXTURE_FILENAME)),
+};
+//# sourceMappingURL=nwsPointForecast.js.map

package/dist/nwsPointForecast.js.map

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

package/dist/registry.d.ts.map

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

package/dist/registry.js

@@ -1,4 +1,15 @@
 import { blsUnemploymentAdapter } from './blsSeries.js';
+import { btsTransportationStatsAdapter } from './btsTransportationStats.js';
+import { cdcSocrataCatalogueAdapter } from './cdcSocrataCatalogue.js';
+import { clinicalTrialsStudiesAdapter } from './clinicalTrialsStudies.js';
+import { epaEnvirofactsFacilitiesAdapter } from './epaEnvirofactsFacilities.js';
+import { fdicBankDirectoryAdapter } from './fdicBankDirectory.js';
+import { healthdataSocrataCatalogueAdapter } from './healthdataSocrataCatalogue.js';
+import { ncbiPubmedSearchAdapter } from './ncbiPubmedSearch.js';
+import { nwsPointForecastAdapter } from './nwsPointForecast.js';
+import { secEdgarFilingsAdapter } from './secEdgarFilings.js';
+import { treasuryDebtToPennyAdapter } from './treasuryDebtToPenny.js';
+import { usaspendingAgenciesAdapter } from './usaspendingAgencies.js';
 import { cdcCountyObesityAdapter } from './cdcCountyObesity.js';
 import { cfpbConsumerComplaintsAdapter } from './cfpbConsumerComplaints.js';
 import { cpscProductRecallsAdapter } from './cpscProductRecalls.js';
@@ -22,6 +33,17 @@ export const US_DATA_SOURCES = [
     usgsPeakStreamflowAdapter,
     cpscProductRecallsAdapter,
     cfpbConsumerComplaintsAdapter,
+    treasuryDebtToPennyAdapter,
+    secEdgarFilingsAdapter,
+    fdicBankDirectoryAdapter,
+    clinicalTrialsStudiesAdapter,
+    nwsPointForecastAdapter,
+    usaspendingAgenciesAdapter,
+    epaEnvirofactsFacilitiesAdapter,
+    ncbiPubmedSearchAdapter,
+    cdcSocrataCatalogueAdapter,
+    healthdataSocrataCatalogueAdapter,
+    btsTransportationStatsAdapter,
 ];
 /** Looks up a source adapter by id. */
 export function getUsDataSource(id) {

package/dist/registry.js.map

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

package/dist/secEdgarFilings.d.ts

@@ -0,0 +1,103 @@
+import type { UsDataAdapter } from './types.js';
+/** Adapter id for the SEC EDGAR submissions source. */
+export declare const SEC_EDGAR_FILINGS_SOURCE_ID = "sec-edgar-filings";
+/**
+ * User-Agent header the SEC asks every caller to send.
+ *
+ * The SEC blocks a request that does not identify its operator, so the
+ * adapter sends a descriptive name and a contact address on every call. A
+ * real deployment should override the contact with its own address.
+ */
+export declare const SEC_EDGAR_USER_AGENT = "usa-open-data-connectors contact@example.com";
+/** One filing in an issuer's recent submissions list. */
+export interface SecEdgarFiling {
+    /** The SEC's accession number, e.g. "0001958244-26-000636". */
+    accessionNumber: string;
+    /** Date the filing was made, e.g. "2026-10-02". */
+    filingDate: string;
+    /** End of the period the filing covers, or null when the form has none. */
+    reportDate: string | null;
+    /** Form type, e.g. "4" or "10-Q". */
+    form: string;
+    /** Path to the filing's main document inside the filing archive. */
+    primaryDocument: string;
+    /** Description of the main document, or null when the form has none. */
+    primaryDocDescription: string | null;
+    /** Size of the filing in bytes, or null when the SEC did not report one. */
+    sizeBytes: number | null;
+    /** Whether the filing carries XBRL data. */
+    isXbrl: boolean;
+    /** Whether the filing carries inline XBRL data. */
+    isInlineXbrl: boolean;
+}
+/** One form type and how many of the recent filings use it. */
+export interface SecEdgarFormCount {
+    form: string;
+    count: number;
+}
+/** An issuer's profile plus its recent filings, folded for a story. */
+export interface SecEdgarCompanyFilings {
+    /** Zero-padded Central Index Key, e.g. "0000320193". */
+    cik: string;
+    /** The issuer's registered name, e.g. "Apple Inc.". */
+    name: string;
+    entityType: string | null;
+    /** Standard Industrial Classification code. */
+    sic: string | null;
+    sicDescription: string | null;
+    /** Exchange tickers, empty when the issuer has none. */
+    tickers: string[];
+    /** Exchanges the issuer is listed on, empty when it has none. */
+    exchanges: string[];
+    /** Fiscal year end as the SEC writes it, e.g. "0926". */
+    fiscalYearEnd: string | null;
+    /** Recent filings, in the order the SEC sends them, newest first. */
+    filings: SecEdgarFiling[];
+    filingCount: number;
+    /** Date of the newest filing in the list, e.g. "2026-10-02". */
+    newestFilingDate: string;
+    /** Form types, most filings first, ties broken by form name. */
+    formCounts: SecEdgarFormCount[];
+}
+/** Base URL for the SEC EDGAR submissions service. */
+export declare const SEC_EDGAR_SUBMISSIONS_API_BASE = "https://data.sec.gov/submissions";
+/** Apple's Central Index Key, the issuer the committed fixture covers. */
+export declare const SEC_EDGAR_APPLE_CIK = "0000320193";
+/**
+ * Builds the request URL for one issuer's submissions file.
+ *
+ * The endpoint is keyless. The CIK is zero-padded to the ten digits the
+ * service expects, so a caller can pass "320193" as well as "0000320193".
+ *
+ * @param cik - the issuer's Central Index Key
+ * @returns the full request URL
+ */
+export declare function buildSecEdgarSubmissionsUrl(cik?: string): string;
+/**
+ * Parses one submissions response into an issuer's profile and recent filings.
+ *
+ * A response without a filings block, or with parallel arrays that do not line
+ * up, stops the parse. A filing without a readable date is a changed shape and
+ * also stops the parse.
+ *
+ * @param payload - the JSON body from the SEC submissions service
+ * @returns the issuer's profile, its recent filings, and the form counts
+ */
+export declare function parseSecEdgarFilingsPayload(payload: unknown): SecEdgarCompanyFilings;
+/**
+ * Reads one issuer's recent filings from the SEC's submissions service.
+ *
+ * The SEC asks every caller to identify itself, so the request carries a
+ * descriptive User-Agent header. One keyless request covers the issuer's
+ * recent filings and a little under a thousand rows.
+ *
+ * @param options - an optional Central Index Key and fetch stub
+ * @returns the issuer's profile, its recent filings, and the form counts
+ */
+export declare function fetchSecEdgarFilings(options?: {
+    cik?: string;
+    fetchImpl?: typeof globalThis.fetch;
+}): Promise<SecEdgarCompanyFilings>;
+/** SEC EDGAR issuer submissions and recent filings, keyless. */
+export declare const secEdgarFilingsAdapter: UsDataAdapter<SecEdgarCompanyFilings>;
+//# sourceMappingURL=secEdgarFilings.d.ts.map

package/dist/secEdgarFilings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secEdgarFilings.d.ts","sourceRoot":"","sources":["../src/secEdgarFilings.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,uDAAuD;AACvD,eAAO,MAAM,2BAA2B,sBAAsB,CAAC;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,iDAAiD,CAAC;AAEnF,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,4CAA4C;IAC5C,MAAM,EAAE,OAAO,CAAC;IAChB,mDAAmD;IACnD,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,uEAAuE;AACvE,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,+CAA+C;IAC/C,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,wDAAwD;IACxD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iEAAiE;IACjE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,yDAAyD;IACzD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qEAAqE;IACrE,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,gEAAgE;IAChE,UAAU,EAAE,iBAAiB,EAAE,CAAC;CACjC;AAED,sDAAsD;AACtD,eAAO,MAAM,8BAA8B,qCAAqC,CAAC;AAEjF,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAuChD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,GAAE,MAA4B,GAAG,MAAM,CASrF;AA0FD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,sBAAsB,CAqCpF;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACrC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAWlC;AAED,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,sBAAsB,CAUxE,CAAC"}

package/dist/secEdgarFilings.js

@@ -0,0 +1,214 @@
+import { z } from 'zod';
+import { UsSourceApiError, UsSourceParseError } from './errors.js';
+import { readFixtureJson } from './fixtures.js';
+/** Adapter id for the SEC EDGAR submissions source. */
+export const SEC_EDGAR_FILINGS_SOURCE_ID = 'sec-edgar-filings';
+/**
+ * User-Agent header the SEC asks every caller to send.
+ *
+ * The SEC blocks a request that does not identify its operator, so the
+ * adapter sends a descriptive name and a contact address on every call. A
+ * real deployment should override the contact with its own address.
+ */
+export const SEC_EDGAR_USER_AGENT = 'usa-open-data-connectors contact@example.com';
+/** Base URL for the SEC EDGAR submissions service. */
+export const SEC_EDGAR_SUBMISSIONS_API_BASE = 'https://data.sec.gov/submissions';
+/** Apple's Central Index Key, the issuer the committed fixture covers. */
+export const SEC_EDGAR_APPLE_CIK = '0000320193';
+/** Committed snapshot, so a build works when the SEC host is unreachable. */
+const SEC_EDGAR_FIXTURE_FILENAME = 'sec-edgar-filings-2026-10-05.json';
+/** Shape of a CIK as the submissions service uses it. */
+const CIK_PATTERN = /^\d{1,10}$/;
+/** Shape of a filing date, e.g. "2026-10-02". */
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+// The SEC sends the recent filings as parallel arrays, one array per column,
+// rather than one object per row. A field the form does not carry arrives as
+// an empty string rather than a missing key.
+const SEC_EDGAR_RECENT_SCHEMA = z.object({
+    accessionNumber: z.array(z.string()).optional(),
+    filingDate: z.array(z.string()).optional(),
+    reportDate: z.array(z.string()).optional(),
+    form: z.array(z.string()).optional(),
+    size: z.array(z.number()).optional(),
+    isXBRL: z.array(z.number()).optional(),
+    isInlineXBRL: z.array(z.number()).optional(),
+    primaryDocument: z.array(z.string()).optional(),
+    primaryDocDescription: z.array(z.string()).optional(),
+});
+const SEC_EDGAR_PAYLOAD_SCHEMA = z.object({
+    cik: z.string().optional(),
+    name: z.string().optional(),
+    entityType: z.string().optional(),
+    sic: z.string().optional(),
+    sicDescription: z.string().optional(),
+    tickers: z.array(z.string()).optional(),
+    exchanges: z.array(z.string()).optional(),
+    fiscalYearEnd: z.string().optional(),
+    stateOfIncorporation: z.string().optional(),
+    filings: z.object({ recent: SEC_EDGAR_RECENT_SCHEMA.optional() }).optional(),
+});
+/**
+ * Builds the request URL for one issuer's submissions file.
+ *
+ * The endpoint is keyless. The CIK is zero-padded to the ten digits the
+ * service expects, so a caller can pass "320193" as well as "0000320193".
+ *
+ * @param cik - the issuer's Central Index Key
+ * @returns the full request URL
+ */
+export function buildSecEdgarSubmissionsUrl(cik = SEC_EDGAR_APPLE_CIK) {
+    const trimmed = cik.trim();
+    if (!CIK_PATTERN.test(trimmed)) {
+        throw new UsSourceParseError(SEC_EDGAR_FILINGS_SOURCE_ID, `A Central Index Key must be up to ten digits: ${cik}`);
+    }
+    return `${SEC_EDGAR_SUBMISSIONS_API_BASE}/CIK${trimmed.padStart(10, '0')}.json`;
+}
+/** Reads a column the SEC may omit, as an empty list. */
+function columnOrEmpty(column) {
+    return column ?? [];
+}
+/**
+ * Zips the SEC's parallel filing arrays into one row per filing.
+ *
+ * The columns are parallel arrays, so a mismatch in their lengths means the
+ * response cannot be read as rows and stops the parse. A filing without a
+ * readable date is a changed shape and also stops the parse.
+ *
+ * @param recent - the recent filings object from the submissions file
+ * @returns one row per filing, in the order the SEC sent them
+ */
+function zipSecEdgarFilings(recent) {
+    const accessions = columnOrEmpty(recent.accessionNumber);
+    const dates = columnOrEmpty(recent.filingDate);
+    const reportDates = columnOrEmpty(recent.reportDate);
+    const forms = columnOrEmpty(recent.form);
+    const sizes = recent.size ?? [];
+    const xbrl = recent.isXBRL ?? [];
+    const inlineXbrl = recent.isInlineXBRL ?? [];
+    const primaryDocuments = columnOrEmpty(recent.primaryDocument);
+    const primaryDescriptions = columnOrEmpty(recent.primaryDocDescription);
+    const columns = [
+        { name: 'filingDate', values: dates },
+        { name: 'reportDate', values: reportDates },
+        { name: 'form', values: forms },
+        { name: 'size', values: sizes },
+        { name: 'isXBRL', values: xbrl },
+        { name: 'isInlineXBRL', values: inlineXbrl },
+        { name: 'primaryDocument', values: primaryDocuments },
+        { name: 'primaryDocDescription', values: primaryDescriptions },
+    ];
+    for (const column of columns) {
+        if (column.values.length !== accessions.length) {
+            throw new UsSourceParseError(SEC_EDGAR_FILINGS_SOURCE_ID, `The ${column.name} column holds ${column.values.length} entries, not ${accessions.length}`);
+        }
+    }
+    return accessions.map((accessionNumber, index) => {
+        const filingDate = dates[index] ?? '';
+        if (!ISO_DATE_PATTERN.test(filingDate)) {
+            throw new UsSourceParseError(SEC_EDGAR_FILINGS_SOURCE_ID, `Unreadable filing date: ${filingDate}`);
+        }
+        return {
+            accessionNumber,
+            filingDate,
+            reportDate: blankToNull(reportDates[index]),
+            form: forms[index] ?? '',
+            primaryDocument: primaryDocuments[index] ?? '',
+            primaryDocDescription: blankToNull(primaryDescriptions[index]),
+            sizeBytes: sizes[index] ?? null,
+            isXbrl: xbrl[index] === 1,
+            isInlineXbrl: inlineXbrl[index] === 1,
+        };
+    });
+}
+/** Turns the SEC's empty-string sentinel into null, and keeps real text. */
+function blankToNull(value) {
+    if (value === undefined || value.trim() === '') {
+        return null;
+    }
+    return value;
+}
+/** Counts how often each form appears, most filings first, ties by name. */
+function countSecEdgarForms(filings) {
+    const counts = new Map();
+    for (const filing of filings) {
+        counts.set(filing.form, (counts.get(filing.form) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .sort(([leftForm, leftCount], [rightForm, rightCount]) => leftCount === rightCount ? leftForm.localeCompare(rightForm) : rightCount - leftCount)
+        .map(([form, count]) => ({ form, count }));
+}
+/**
+ * Parses one submissions response into an issuer's profile and recent filings.
+ *
+ * A response without a filings block, or with parallel arrays that do not line
+ * up, stops the parse. A filing without a readable date is a changed shape and
+ * also stops the parse.
+ *
+ * @param payload - the JSON body from the SEC submissions service
+ * @returns the issuer's profile, its recent filings, and the form counts
+ */
+export function parseSecEdgarFilingsPayload(payload) {
+    const parsed = SEC_EDGAR_PAYLOAD_SCHEMA.safeParse(payload);
+    if (!parsed.success) {
+        throw new UsSourceParseError(SEC_EDGAR_FILINGS_SOURCE_ID, parsed.error.message);
+    }
+    const recent = parsed.data.filings?.recent;
+    if (recent === undefined) {
+        throw new UsSourceParseError(SEC_EDGAR_FILINGS_SOURCE_ID, 'The response carried no filings');
+    }
+    const filings = zipSecEdgarFilings(recent);
+    if (filings.length === 0) {
+        throw new UsSourceParseError(SEC_EDGAR_FILINGS_SOURCE_ID, 'The response carried no filings');
+    }
+    const newestFilingDate = filings
+        .map((filing) => filing.filingDate)
+        .sort()
+        .at(-1);
+    if (newestFilingDate === undefined) {
+        throw new UsSourceParseError(SEC_EDGAR_FILINGS_SOURCE_ID, 'No filing date to summarise');
+    }
+    return {
+        cik: parsed.data.cik ?? '',
+        name: parsed.data.name ?? '',
+        entityType: blankToNull(parsed.data.entityType),
+        sic: blankToNull(parsed.data.sic),
+        sicDescription: blankToNull(parsed.data.sicDescription),
+        tickers: parsed.data.tickers ?? [],
+        exchanges: parsed.data.exchanges ?? [],
+        fiscalYearEnd: blankToNull(parsed.data.fiscalYearEnd),
+        filings,
+        filingCount: filings.length,
+        newestFilingDate,
+        formCounts: countSecEdgarForms(filings),
+    };
+}
+/**
+ * Reads one issuer's recent filings from the SEC's submissions service.
+ *
+ * The SEC asks every caller to identify itself, so the request carries a
+ * descriptive User-Agent header. One keyless request covers the issuer's
+ * recent filings and a little under a thousand rows.
+ *
+ * @param options - an optional Central Index Key and fetch stub
+ * @returns the issuer's profile, its recent filings, and the form counts
+ */
+export async function fetchSecEdgarFilings(options) {
+    const fetchImpl = options?.fetchImpl ?? globalThis.fetch;
+    const url = buildSecEdgarSubmissionsUrl(options?.cik ?? SEC_EDGAR_APPLE_CIK);
+    const response = await fetchImpl(url, { headers: { 'User-Agent': SEC_EDGAR_USER_AGENT } });
+    if (!response.ok) {
+        throw new UsSourceApiError(SEC_EDGAR_FILINGS_SOURCE_ID, `HTTP ${response.status} reading the submissions file`);
+    }
+    return parseSecEdgarFilingsPayload(await response.json());
+}
+/** SEC EDGAR issuer submissions and recent filings, keyless. */
+export const secEdgarFilingsAdapter = {
+    id: SEC_EDGAR_FILINGS_SOURCE_ID,
+    name: 'SEC EDGAR filings',
+    auth: 'none',
+    description: "An issuer's recent filing history from SEC EDGAR, one row per filing, with the form type and the newest date in the list.",
+    fetchLive: async (options) => fetchSecEdgarFilings(options?.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+    parse: (payload) => parseSecEdgarFilingsPayload(payload),
+    loadFixture: () => parseSecEdgarFilingsPayload(readFixtureJson(SEC_EDGAR_FIXTURE_FILENAME)),
+};
+//# sourceMappingURL=secEdgarFilings.js.map