@cliwant/mcp-sam-gov 0.2.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (228) hide show
  1. package/LICENSE +21 -21
  2. package/README.ja.md +48 -16
  3. package/README.ko.md +48 -16
  4. package/README.md +279 -67
  5. package/dist/attachments.d.ts +63 -0
  6. package/dist/attachments.d.ts.map +1 -0
  7. package/dist/attachments.js +576 -0
  8. package/dist/attachments.js.map +1 -0
  9. package/dist/bls.d.ts +267 -0
  10. package/dist/bls.d.ts.map +1 -0
  11. package/dist/bls.js +1549 -0
  12. package/dist/bls.js.map +1 -0
  13. package/dist/cache.d.ts +42 -0
  14. package/dist/cache.d.ts.map +1 -0
  15. package/dist/cache.js +64 -0
  16. package/dist/cache.js.map +1 -0
  17. package/dist/census.d.ts +182 -0
  18. package/dist/census.d.ts.map +1 -0
  19. package/dist/census.js +576 -0
  20. package/dist/census.js.map +1 -0
  21. package/dist/ckan.d.ts +141 -0
  22. package/dist/ckan.d.ts.map +1 -0
  23. package/dist/ckan.js +393 -0
  24. package/dist/ckan.js.map +1 -0
  25. package/dist/clinicaltrials.d.ts +180 -0
  26. package/dist/clinicaltrials.d.ts.map +1 -0
  27. package/dist/clinicaltrials.js +730 -0
  28. package/dist/clinicaltrials.js.map +1 -0
  29. package/dist/cms.d.ts +140 -0
  30. package/dist/cms.d.ts.map +1 -0
  31. package/dist/cms.js +482 -0
  32. package/dist/cms.js.map +1 -0
  33. package/dist/coerce.d.ts +32 -0
  34. package/dist/coerce.d.ts.map +1 -0
  35. package/dist/coerce.js +50 -0
  36. package/dist/coerce.js.map +1 -0
  37. package/dist/datagov-catalog.d.ts +84 -0
  38. package/dist/datagov-catalog.d.ts.map +1 -0
  39. package/dist/datagov-catalog.js +233 -0
  40. package/dist/datagov-catalog.js.map +1 -0
  41. package/dist/datagov.d.ts +146 -0
  42. package/dist/datagov.d.ts.map +1 -0
  43. package/dist/datagov.js +689 -0
  44. package/dist/datagov.js.map +1 -0
  45. package/dist/datagovKey.d.ts +36 -0
  46. package/dist/datagovKey.d.ts.map +1 -0
  47. package/dist/datagovKey.js +60 -0
  48. package/dist/datagovKey.js.map +1 -0
  49. package/dist/datasource.d.ts +313 -0
  50. package/dist/datasource.d.ts.map +1 -0
  51. package/dist/datasource.js +551 -0
  52. package/dist/datasource.js.map +1 -0
  53. package/dist/disclosure.d.ts +55 -0
  54. package/dist/disclosure.d.ts.map +1 -0
  55. package/dist/disclosure.js +57 -0
  56. package/dist/disclosure.js.map +1 -0
  57. package/dist/ecfr.d.ts +4 -2
  58. package/dist/ecfr.d.ts.map +1 -1
  59. package/dist/ecfr.js +92 -17
  60. package/dist/ecfr.js.map +1 -1
  61. package/dist/echo.d.ts +143 -0
  62. package/dist/echo.d.ts.map +1 -0
  63. package/dist/echo.js +424 -0
  64. package/dist/echo.js.map +1 -0
  65. package/dist/edgar.d.ts +377 -0
  66. package/dist/edgar.d.ts.map +1 -0
  67. package/dist/edgar.js +2418 -0
  68. package/dist/edgar.js.map +1 -0
  69. package/dist/errors.d.ts +102 -0
  70. package/dist/errors.d.ts.map +1 -0
  71. package/dist/errors.js +247 -0
  72. package/dist/errors.js.map +1 -0
  73. package/dist/fac.d.ts +180 -0
  74. package/dist/fac.d.ts.map +1 -0
  75. package/dist/fac.js +416 -0
  76. package/dist/fac.js.map +1 -0
  77. package/dist/far.d.ts +170 -0
  78. package/dist/far.d.ts.map +1 -0
  79. package/dist/far.js +804 -0
  80. package/dist/far.js.map +1 -0
  81. package/dist/fdic.d.ts +599 -0
  82. package/dist/fdic.d.ts.map +1 -0
  83. package/dist/fdic.js +1624 -0
  84. package/dist/fdic.js.map +1 -0
  85. package/dist/federal-register.d.ts +139 -2
  86. package/dist/federal-register.d.ts.map +1 -1
  87. package/dist/federal-register.js +432 -15
  88. package/dist/federal-register.js.map +1 -1
  89. package/dist/fema.d.ts +181 -0
  90. package/dist/fema.d.ts.map +1 -0
  91. package/dist/fema.js +436 -0
  92. package/dist/fema.js.map +1 -0
  93. package/dist/fpds.d.ts +108 -0
  94. package/dist/fpds.d.ts.map +1 -0
  95. package/dist/fpds.js +519 -0
  96. package/dist/fpds.js.map +1 -0
  97. package/dist/gao.d.ts +64 -0
  98. package/dist/gao.d.ts.map +1 -0
  99. package/dist/gao.js +640 -0
  100. package/dist/gao.js.map +1 -0
  101. package/dist/govinfo.d.ts +111 -0
  102. package/dist/govinfo.d.ts.map +1 -0
  103. package/dist/govinfo.js +422 -0
  104. package/dist/govinfo.js.map +1 -0
  105. package/dist/grants.d.ts +27 -4
  106. package/dist/grants.d.ts.map +1 -1
  107. package/dist/grants.js +114 -11
  108. package/dist/grants.js.map +1 -1
  109. package/dist/gsa-csv.d.ts +249 -0
  110. package/dist/gsa-csv.d.ts.map +1 -0
  111. package/dist/gsa-csv.js +784 -0
  112. package/dist/gsa-csv.js.map +1 -0
  113. package/dist/integrity.d.ts +212 -0
  114. package/dist/integrity.d.ts.map +1 -0
  115. package/dist/integrity.js +707 -0
  116. package/dist/integrity.js.map +1 -0
  117. package/dist/meta.d.ts +165 -0
  118. package/dist/meta.d.ts.map +1 -0
  119. package/dist/meta.js +162 -0
  120. package/dist/meta.js.map +1 -0
  121. package/dist/nih.d.ts +117 -0
  122. package/dist/nih.d.ts.map +1 -0
  123. package/dist/nih.js +291 -0
  124. package/dist/nih.js.map +1 -0
  125. package/dist/nppes.d.ts +157 -0
  126. package/dist/nppes.d.ts.map +1 -0
  127. package/dist/nppes.js +648 -0
  128. package/dist/nppes.js.map +1 -0
  129. package/dist/nsf.d.ts +176 -0
  130. package/dist/nsf.d.ts.map +1 -0
  131. package/dist/nsf.js +554 -0
  132. package/dist/nsf.js.map +1 -0
  133. package/dist/nvd.d.ts +176 -0
  134. package/dist/nvd.d.ts.map +1 -0
  135. package/dist/nvd.js +912 -0
  136. package/dist/nvd.js.map +1 -0
  137. package/dist/ofac.d.ts +205 -0
  138. package/dist/ofac.d.ts.map +1 -0
  139. package/dist/ofac.js +919 -0
  140. package/dist/ofac.js.map +1 -0
  141. package/dist/pricing.d.ts +110 -0
  142. package/dist/pricing.d.ts.map +1 -0
  143. package/dist/pricing.js +843 -0
  144. package/dist/pricing.js.map +1 -0
  145. package/dist/sam-gov/client.d.ts +60 -2
  146. package/dist/sam-gov/client.d.ts.map +1 -1
  147. package/dist/sam-gov/client.js +320 -54
  148. package/dist/sam-gov/client.js.map +1 -1
  149. package/dist/sam-gov/index.d.ts +1 -1
  150. package/dist/sam-gov/index.d.ts.map +1 -1
  151. package/dist/sam-gov/index.js +1 -1
  152. package/dist/sam-gov/index.js.map +1 -1
  153. package/dist/sam-gov/types.d.ts +24 -0
  154. package/dist/sam-gov/types.d.ts.map +1 -1
  155. package/dist/sba.d.ts +72 -0
  156. package/dist/sba.d.ts.map +1 -0
  157. package/dist/sba.js +281 -0
  158. package/dist/sba.js.map +1 -0
  159. package/dist/server.d.ts +14 -2
  160. package/dist/server.d.ts.map +1 -1
  161. package/dist/server.js +3897 -295
  162. package/dist/server.js.map +1 -1
  163. package/dist/snapshot.d.ts +98 -0
  164. package/dist/snapshot.d.ts.map +1 -0
  165. package/dist/snapshot.js +146 -0
  166. package/dist/snapshot.js.map +1 -0
  167. package/dist/socrata.d.ts +157 -0
  168. package/dist/socrata.d.ts.map +1 -0
  169. package/dist/socrata.js +448 -0
  170. package/dist/socrata.js.map +1 -0
  171. package/dist/treasury.d.ts +143 -0
  172. package/dist/treasury.d.ts.map +1 -0
  173. package/dist/treasury.js +436 -0
  174. package/dist/treasury.js.map +1 -0
  175. package/dist/usaspending.d.ts +260 -65
  176. package/dist/usaspending.d.ts.map +1 -1
  177. package/dist/usaspending.js +1664 -228
  178. package/dist/usaspending.js.map +1 -1
  179. package/dist/usitc.d.ts +142 -0
  180. package/dist/usitc.d.ts.map +1 -0
  181. package/dist/usitc.js +339 -0
  182. package/dist/usitc.js.map +1 -0
  183. package/package.json +24 -2
  184. package/src/attachments.ts +652 -0
  185. package/src/bls.ts +1943 -0
  186. package/src/cache.ts +73 -0
  187. package/src/census.ts +735 -0
  188. package/src/ckan.ts +495 -0
  189. package/src/clinicaltrials.ts +923 -0
  190. package/src/cms.ts +634 -0
  191. package/src/coerce.ts +47 -0
  192. package/src/datagov-catalog.ts +296 -0
  193. package/src/datagov.ts +907 -0
  194. package/src/datagovKey.ts +68 -0
  195. package/src/datasource.ts +721 -0
  196. package/src/disclosure.ts +61 -0
  197. package/src/ecfr.ts +231 -127
  198. package/src/echo.ts +496 -0
  199. package/src/edgar.ts +3014 -0
  200. package/src/errors.ts +303 -0
  201. package/src/fac.ts +529 -0
  202. package/src/far.ts +1007 -0
  203. package/src/fdic.ts +2052 -0
  204. package/src/federal-register.ts +706 -191
  205. package/src/fema.ts +541 -0
  206. package/src/fpds.ts +620 -0
  207. package/src/gao.ts +744 -0
  208. package/src/govinfo.ts +497 -0
  209. package/src/grants.ts +290 -155
  210. package/src/gsa-csv.ts +992 -0
  211. package/src/integrity.ts +928 -0
  212. package/src/meta.ts +292 -0
  213. package/src/nih.ts +375 -0
  214. package/src/nppes.ts +834 -0
  215. package/src/nsf.ts +706 -0
  216. package/src/nvd.ts +1124 -0
  217. package/src/ofac.ts +1166 -0
  218. package/src/pricing.ts +1075 -0
  219. package/src/sam-gov/client.ts +345 -63
  220. package/src/sam-gov/index.ts +5 -1
  221. package/src/sam-gov/types.ts +22 -0
  222. package/src/sba.ts +357 -0
  223. package/src/server.ts +4559 -327
  224. package/src/snapshot.ts +192 -0
  225. package/src/socrata.ts +532 -0
  226. package/src/treasury.ts +575 -0
  227. package/src/usaspending.ts +2680 -925
  228. package/src/usitc.ts +420 -0
@@ -0,0 +1,377 @@
1
+ /**
2
+ * SEC EDGAR — company filings, XBRL financial facts, ticker→CIK, and full-text
3
+ * search (keyless). First capital-markets source (ADR-0003); 2nd consumer of the
4
+ * fetch/map/meta shape after treasury.ts.
5
+ *
6
+ * Fully PUBLIC, KEYLESS. Hosts: data.sec.gov, efts.sec.gov, www.sec.gov/files
7
+ * (+ www.sec.gov/Archives for constructed links). No API key; instead SEC
8
+ * requires a descriptive `User-Agent` on EVERY request and self-throttling to
9
+ * ≤10 req/s (a breach → ~10-minute IP block).
10
+ *
11
+ * Three layers (mirror treasury.ts):
12
+ * fetch — `getEdgar(url, label)`: sets the mandatory UA (+ gzip) on the init,
13
+ * serializes every EDGAR fetch through a per-process min-interval gate
14
+ * (~110ms → ≤~9 req/s), and reuses errors.ts retry/timeout/taxonomy.
15
+ * map — PURE columnar/curated mappers (zipRecent, companyfacts extraction,
16
+ * FTS hit map). `num(x)` → number|null (NEVER 0 for absent). `padCik`.
17
+ * meta — `withMeta(...)`: hands totalAvailable/returned/pagination/notes to
18
+ * meta.ts's buildMeta, which DERIVES complete/truncated.
19
+ *
20
+ * HONESTY / REVIEW FIXES (ADR-0003 "Review outcome (v2)", live-verified 2026-07-10):
21
+ * F1 — the committed default UA is an ORG contact on the project domain
22
+ * (`cliwant-mcp-sam-gov/1.0 (contact: opendata@cliwant.com)`), NOT a
23
+ * github.com URL (SEC 403s any UA containing `github.com`) and NOT a
24
+ * personal email. Override via EDGAR_USER_AGENT.
25
+ * F2 — `edgar_full_text_search` has NO `size` param: efts ignores it (5/20/100/
26
+ * 200 all return 100), so page size is a fixed 100. Pagination is by `from`.
27
+ * F3 — FTS window overflow: `from > 9900` (from+100 > 10000) is rejected as
28
+ * invalid_input BEFORE the fetch; and after r.json(), a missing `hits.hits`
29
+ * (SEC returns HTTP 200 + `{message:"Internal server error"}` past the
30
+ * window) is thrown as schema_drift, never crashed on.
31
+ * F4 — default curated concepts DO NOT include EarningsPerShareBasic (its unit
32
+ * is `USD/shares`, so the default `unit="USD"` would silently return
33
+ * nothing). A requested concept present only in another unit → a note,
34
+ * never a silent/fabricated 0.
35
+ * F5 — FTS `hits.total.relation === "gte"` → `totalIsLowerBound:true` passed to
36
+ * withMeta (machine-readable, not only a note). See meta.ts.
37
+ * F6 — getEdgar disambiguates a 403 by reading the body: "automated"/
38
+ * "Undeclared" ⇒ invalid_input (bad UA, don't retry); else ⇒ rate_limited,
39
+ * retryable, retryAfterSeconds 600 (the ~10-min block).
40
+ * F7 — FTS `_source` has NO primary-document filename; the output `filingIndexUrl`
41
+ * is the filing's ARCHIVE INDEX directory built from `adsh` (no fabricated
42
+ * doc URL). `edgar_company_filings` DOES use the real `primaryDocument`.
43
+ *
44
+ * CIK↔UEI JOIN CAVEAT (load-bearing, in every tool's `_meta.notes` +
45
+ * fieldsUnavailable): EDGAR keys on 10-digit SEC CIK, NOT SAM UEI/DUNS or a
46
+ * USAspending recipient id. No reliable programmatic CIK↔UEI join exists;
47
+ * bridging an EDGAR filer to a federal contracting entity is name/ticker-only
48
+ * (fuzzy) and MUST NOT be asserted as authoritative.
49
+ */
50
+ import { type MetaBundle } from "./meta.js";
51
+ /**
52
+ * A CIK (int or string, padded or not) → the canonical 10-digit zero-padded
53
+ * form EDGAR's data.sec.gov paths require. Strips non-digits first (accepts
54
+ * "CIK320193", "320193", 320193). e.g. 320193 → "0000320193".
55
+ */
56
+ export declare function padCik(x: string | number): string;
57
+ /**
58
+ * Coerce an XBRL value to number|null. Returns **null (never 0)** for absent —
59
+ * a missing fact is an honest "unknown", never a fabricated zero. XBRL `val` is
60
+ * already a JSON number, but guard strings/nullish/non-finite defensively.
61
+ */
62
+ export declare function num(x: unknown): number | null;
63
+ export type TickerEntry = {
64
+ cik: string;
65
+ ticker: string;
66
+ title: string;
67
+ };
68
+ /**
69
+ * Map a company query (exact ticker, else title substring) to its 10-digit CIK
70
+ * via the memoized company_tickers.json. Returns up to 50 matches; `found:false`
71
+ * on none. The CIK is the join key the other three tools take.
72
+ */
73
+ export declare function lookupCik(args: {
74
+ query: string;
75
+ }): Promise<MetaBundle>;
76
+ export type Filing = {
77
+ accession: string | null;
78
+ form: string | null;
79
+ filingDate: string | null;
80
+ reportDate: string | null;
81
+ primaryDocument: string | null;
82
+ primaryDocDescription: string | null;
83
+ primaryDocUrl: string | null;
84
+ isXBRL: boolean;
85
+ };
86
+ /**
87
+ * A company's SEC filings. By default (`fullHistory` off) returns the recent
88
+ * window (from `filings.recent` — up to 1 year OR 1000 filings, whichever is
89
+ * more), optionally narrowed to specific `forms`, with offset pagination. HONESTY:
90
+ * the response is COMPLETE only when `filings.files[]` (older shards) is empty;
91
+ * when shards exist, `totalAvailable` is the grand total (recent + Σ shard counts),
92
+ * `hasMore:true`, and a note discloses that only the recent window was searched.
93
+ * With `fullHistory:true`, the older `files[]` shards are fetched (newest-first up
94
+ * to `maxShards`, default 10) and assembled (recent ++ shard001..N, descending
95
+ * preserved, NO re-sort) into the COMPLETE history — a capped/failed fan-out is
96
+ * disclosed as PARTIAL (never a capped set claimed complete). `totalAvailable`
97
+ * stays the grand total regardless of the cap (buildMeta forces complete:false
98
+ * when returned < total).
99
+ */
100
+ export declare function companyFilings(args: {
101
+ cikOrTicker: string;
102
+ forms?: string[];
103
+ limit?: number;
104
+ offset?: number;
105
+ fullHistory?: boolean;
106
+ maxShards?: number;
107
+ }): Promise<MetaBundle>;
108
+ /**
109
+ * The default curated us-gaap concepts (F4 — NO EarningsPerShareBasic; its unit
110
+ * is USD/shares, so the default unit="USD" would silently return nothing). The
111
+ * two revenue tags cover the same logical concept — filers report under one or
112
+ * the other — so this is the 6 curated USD concepts. Extracting only these
113
+ * avoids returning the full ~500-concept companyfacts payload.
114
+ */
115
+ export declare const DEFAULT_FACT_CONCEPTS: string[];
116
+ /**
117
+ * Curated XBRL financial facts for a filer. Extracts only the requested (or the
118
+ * 6 default) concepts in the requested `unit` (default USD), from the memoized
119
+ * companyfacts doc. HONESTY: a concept ABSENT for this filer is OMITTED and
120
+ * listed in a note (NEVER surfaced as 0); a concept present only in a DIFFERENT
121
+ * unit (e.g. EPS in USD/shares) is listed under `wrongUnit` with a note, never a
122
+ * silent 0. `latest` reduces each concept to its single most-recent data point.
123
+ */
124
+ export declare function companyFacts(args: {
125
+ cikOrTicker: string;
126
+ concepts?: string[];
127
+ unit?: string;
128
+ latest?: boolean;
129
+ }): Promise<MetaBundle>;
130
+ export type FtsResult = {
131
+ accession: string | null;
132
+ form: string | null;
133
+ filingDate: string | null;
134
+ entityNames: string[];
135
+ ciks: string[];
136
+ filingIndexUrl: string | null;
137
+ };
138
+ /**
139
+ * Full-text search across EDGAR filings (2001-present). F2 — NO `size` param
140
+ * (efts always returns 100/page); pagination is by `from`. F3 — `from > 9900`
141
+ * is rejected as invalid_input BEFORE the fetch (from+100 would exceed the 10000
142
+ * window, which efts answers with HTTP 200 + an error body; from=9900 itself is a
143
+ * VALID final page), and a response missing `hits.hits` is thrown as schema_drift
144
+ * (never crashed on). F5 — `hits.total.relation === "gte"` (true total unknown,
145
+ * ≥10000) surfaces as `totalIsLowerBound:true`. ADR-0018 — optional `ciks` (pin
146
+ * filings BY entities, exact 10-digit CIK) + `entityName` (fuzzy filer-name)
147
+ * narrowing filters; a no-digit/CIK-0 `ciks` entry is rejected pre-fetch (M1).
148
+ */
149
+ export declare function fullTextSearch(args: {
150
+ q: string;
151
+ forms?: string[];
152
+ startdt?: string;
153
+ enddt?: string;
154
+ ciks?: string[];
155
+ entityName?: string;
156
+ from?: number;
157
+ }): Promise<MetaBundle>;
158
+ /**
159
+ * The `taxonomy` path-segment enum — the SSRF guard for that segment (no free
160
+ * value reaches the host). Only members LIVE-CONFIRMED to resolve a real frame
161
+ * (per-segment live-verify discipline, ADR-0017 Open-Q5) are shipped. Maker
162
+ * probes 2026-07-12: us-gaap (Assets/Revenues/NetIncomeLoss/EPS) + dei
163
+ * (EntityCommonStockSharesOutstanding/EntityPublicFloat) → 200; the guessed
164
+ * srt/invest/us-ins tags → 404, so they are DROPPED (conservative floor).
165
+ */
166
+ export declare const FRAMES_TAXONOMIES: readonly ["us-gaap", "dei"];
167
+ /** One filer's row in a frame. `start` is present ONLY for duration concepts. */
168
+ export type FrameRow = {
169
+ accn: string | null;
170
+ cik: string | null;
171
+ entityName: string | null;
172
+ loc: string | null;
173
+ end: string | null;
174
+ val: number | null;
175
+ start?: string | null;
176
+ };
177
+ /**
178
+ * Summary distribution over the FULL cross-section (M2/M3). Computed over the
179
+ * FINITE `val`s only (num() → null for absent/blank/"null"/non-finite, which are
180
+ * excluded and counted in `nonFiniteExcluded`; a real 0 survives). Percentiles use
181
+ * LINEAR INTERPOLATION on the ascending-sorted finite vals. `count===0` (no finite
182
+ * vals) ⇒ EVERY stat field null (never 0/NaN/Infinity — the null-never-0 row rule
183
+ * lifted onto the aggregate).
184
+ */
185
+ export type FrameStats = {
186
+ count: number;
187
+ min: number | null;
188
+ max: number | null;
189
+ sum: number | null;
190
+ mean: number | null;
191
+ median: number | null;
192
+ p25: number | null;
193
+ p75: number | null;
194
+ nonFiniteExcluded: number;
195
+ };
196
+ /**
197
+ * Keyless cross-filer XBRL cross-section. In ONE call, return every filer's
198
+ * reported value for a single us-gaap/dei concept in a single calendar period —
199
+ * the complete cross-section — for peer benchmarking + distribution stats.
200
+ *
201
+ * HONESTY (ADR-0017 v2):
202
+ * - `totalAvailable` = SEC's own `pts` (NEVER a page length). Drift guards THROW
203
+ * schema_drift on a non-frames shape (data not array / pts non-numeric) or a
204
+ * `pts !== data.length` mismatch (a truncation frames has no way to page past,
205
+ * so refusing is the honest move — Open-Q2 resolved: THROW is the DEFAULT).
206
+ * - The upstream frame is fetched in FULL; `limit`/`offset` is a CLIENT-SIDE
207
+ * window disclosed as such (M1 — the completeness note never calls a subset
208
+ * page "complete"; buildMeta derives complete/truncated from returned/total/
209
+ * hasMore, mirroring edgar_company_filings — NO forced complete:true).
210
+ * - A 404 (tag/unit/period/taxonomy quadruple did not match) ⇒ honest found:false
211
+ * with the semantic note (absence ≠ 0). NEVER a fabricated val:0.
212
+ * - Row `val` is num()-coerced (null-never-0). `start` appears only on duration
213
+ * rows. `uom` echoes SEC's OWN unit (e.g. requested 'USD-per-shares' ⇒ 'USD/shares').
214
+ * - `includeStats` computes over the FULL data[] (all rows, before the slice).
215
+ */
216
+ export declare function xbrlFrames(args: {
217
+ tag: string;
218
+ period: string;
219
+ taxonomy?: string;
220
+ unit?: string;
221
+ limit?: number;
222
+ offset?: number;
223
+ includeStats?: boolean;
224
+ }): Promise<MetaBundle>;
225
+ export declare const MAX_INDEX_ROWS = 500000;
226
+ /** One filing row from master.idx. CIK stays a STRING (never num-coerced). */
227
+ export type FilingIndexRow = {
228
+ cik: string | null;
229
+ cikPadded: string | null;
230
+ companyName: string | null;
231
+ formType: string | null;
232
+ dateFiled: string | null;
233
+ filename: string | null;
234
+ filingUrl: string | null;
235
+ };
236
+ type ParsedFullIndex = {
237
+ rows: FilingIndexRow[];
238
+ malformedRows: number;
239
+ totalIsLowerBound: boolean;
240
+ };
241
+ /**
242
+ * Parse the raw master.idx body into `FilingIndexRow[]`.
243
+ *
244
+ * DRIFT keys on the ABSENCE of the `CIK|Company Name|Form Type|Date Filed|Filename`
245
+ * header + the `----` dashes boundary ONLY (M1) — a non-index / error / format-changed
246
+ * body served with HTTP 200 (e.g. an S3 error HTML page) → THROW `driftError`. A
247
+ * body WITH the header+dashes but ZERO data rows is a GENUINE-EMPTY quarter (2026/QTR4
248
+ * live) → returned to the caller (NOT thrown). A body WITH the header+dashes whose
249
+ * EVERY data row fails the 5-field split → THROW `driftError` (all-malformed = format
250
+ * drift). The fixed preamble (`Description:` …) BEFORE the header is skipped.
251
+ */
252
+ export declare function parseFullIndex(body: string, maxRows?: number): ParsedFullIndex;
253
+ /** For tests: evict the full-index bounded LRU (mirrors cache.ts `_clearCache` for
254
+ * this dedicated cache, which the shared `_clearCache` does not touch). */
255
+ export declare function _resetFullIndexCache(): void;
256
+ /**
257
+ * Read the SEC EDGAR quarterly full-index for (year, quarter) and return the
258
+ * filings matching the given CLIENT-SIDE filters (form / CIK / company substring /
259
+ * date range), offset-paginated, with the EXACT total match count for the quarter.
260
+ *
261
+ * HONESTY (ADR-0026 v2):
262
+ * - FULL-SCAN → `totalAvailable` is the EXACT filtered match count across the WHOLE
263
+ * quarter (never a page length, never a byte-capped under-count — SEC ignores Range).
264
+ * - A bounds-valid but unpublished quarter 403s (getEdgar mislabels it rate_limited);
265
+ * TOOL-LOCAL reclassify to an AMBIGUOUS both-causes error (unpublished quarter OR
266
+ * the 10 req/s rate-block) — never a bare rate-limit, never a fake-empty.
267
+ * - Drift on header/dashes ABSENCE or an all-malformed body (THROW); header+0-rows ⇒
268
+ * genuine-empty (complete:true). A future year / bad quarter ⇒ invalid_input, 0 fetch.
269
+ * - CIK stays a STRING; every column via the module-local `str` (null-never-"").
270
+ * - `companyContains` is a LITERAL case-insensitive substring (C110 N/A — no token split).
271
+ */
272
+ export declare function filingIndex(args: {
273
+ year: number;
274
+ quarter: number;
275
+ formType?: string;
276
+ cik?: string | number;
277
+ companyContains?: string;
278
+ dateFrom?: string;
279
+ dateTo?: string;
280
+ limit?: number;
281
+ offset?: number;
282
+ }): Promise<MetaBundle>;
283
+ /**
284
+ * Parse the raw daily master.YYYYMMDD.idx body into `FilingIndexRow[]` (DEDICATED —
285
+ * NOT parseFullIndex). DRIFT keys on the ABSENCE of the daily `CIK|Company Name|Form
286
+ * Type|Date Filed|File Name` header (★ File Name WITH A SPACE) + the `----` dashes
287
+ * boundary ONLY (M1/fact #2) — a non-index / error / format-changed body served with
288
+ * HTTP 200 → THROW `driftError`. A body WITH the header+dashes but ZERO data rows is a
289
+ * GENUINE-EMPTY day → returned (NOT thrown; near-unreachable for a real trading day but
290
+ * honest). A body WITH the header+dashes whose EVERY data row fails the 5-field split →
291
+ * THROW `driftError` (all-malformed = format drift). Date Filed is normalized to ISO.
292
+ */
293
+ export declare function parseDailyIndex(body: string, maxRows?: number): ParsedFullIndex;
294
+ /** For tests: evict the daily-index bounded LRU (mirrors `_resetFullIndexCache`). */
295
+ export declare function _resetDailyIndexCache(): void;
296
+ /**
297
+ * Read the SEC EDGAR daily-index for one calendar `date` and return the filings
298
+ * matching the given CLIENT-SIDE filters (form / CIK / company substring),
299
+ * offset-paginated, with the EXACT total match count for the day.
300
+ *
301
+ * HONESTY (ADR-0027 v1 + M1 + M2):
302
+ * - ★M2 — an EXACT date round-trip (Date.UTC component re-extraction) rejects
303
+ * Feb-30 / day-40 / non-leap-Feb-29 / a malformed / a FUTURE date PRE-fetch
304
+ * (invalid_input, 0 GET). NOT the `!isNaN(Date.UTC(...))` shortcut (it rolls overflow).
305
+ * - Fetch the .idx FIRST (happy path pays zero oracle cost). 200 + parseable ⇒
306
+ * found:true; FULL-SCAN → EXACT totalAvailable (byte-cap forbidden).
307
+ * - ★M1 — on a 403 (getEdgar mislabels the daily AccessDenied XML rate_limited/403;
308
+ * caught TOOL-LOCAL), consult index.json; maxListedMasterDate makes it recency-aware:
309
+ * requestedYyyymmdd > maxListed ⇒ NOT-YET-DISSEMINATED (found:false, complete:FALSE)
310
+ * requestedYyyymmdd ≤ maxListed & unlisted ⇒ TRUE genuine-absent (found:false, complete:true)
311
+ * listed but .idx 403'd ⇒ honest rate_limited (retryable ~600s)
312
+ * oracle itself 403/bad-shape ⇒ ambiguous both-causes upstream_unavailable
313
+ * - A REAL 429 (status 429, not 403) is NOT caught → stays honest rate_limited.
314
+ * - CIK stays a STRING; every column via `str`; companyContains is a LITERAL
315
+ * case-insensitive substring (C110 N/A — no token split).
316
+ */
317
+ export declare function dailyFilingIndex(args: {
318
+ date: string;
319
+ formType?: string;
320
+ cik?: string | number;
321
+ companyContains?: string;
322
+ limit?: number;
323
+ offset?: number;
324
+ }): Promise<MetaBundle>;
325
+ /**
326
+ * The `taxonomy` path-segment enum — the SSRF guard for that segment (no free value
327
+ * reaches the host). us-gaap + dei live-confirmed on Apple; ifrs-full live-confirmed on
328
+ * Spotify (CIK0001639920 / ifrs-full / Assets → 200, unit EUR, frame CY2017Q4I). `srt`
329
+ * is DROPPED (S2 — it was NOT probed to a resolving 200; a valid-but-unreported tuple is
330
+ * an honest 404, so a slightly-broad enum can never fabricate — but ship only confirmed).
331
+ */
332
+ export declare const CONCEPT_TAXONOMIES: readonly ["us-gaap", "dei", "ifrs-full"];
333
+ /** One output row: unit-tagged, (start,end)-keyed, canonical = frame present. */
334
+ export type ConceptRow = {
335
+ unit: string;
336
+ start: string | null;
337
+ end: string | null;
338
+ val: number | null;
339
+ accn: string | null;
340
+ fy: number | null;
341
+ fp: string | null;
342
+ form: string | null;
343
+ filed: string | null;
344
+ frame: string | null;
345
+ canonical: boolean;
346
+ };
347
+ /**
348
+ * One filer × one XBRL concept × the COMPLETE reported time-series. Reuses resolveCik
349
+ * (ticker→CIK path EXISTS) + buildConceptUrl (the frames path-segment SSRF doctrine,
350
+ * THREE segments) + getEdgar VERBATIM. `unit`/`form`/`fy` are CLIENT-SIDE filters;
351
+ * `canonicalOnly` (default false) dedups to one canonical row per (unit,start,end),
352
+ * FULLY DISCLOSED. limit/offset window the already-fully-fetched set.
353
+ *
354
+ * HONESTY (ADR-0041 v2):
355
+ * - ★M1 — every row carries `start`; period identity is the (start,end) PAIR. A
356
+ * same-`end` different-`start` pair is a different-duration fact, NOT a revision.
357
+ * - ★M2 — canonicalOnly dedup key = (unit,start,end): partition by unit first, keep
358
+ * one canonical row per distinct (start,end) — never dropping a whole unit's row.
359
+ * - ★S1 — unitsAvailable[].count = the RAW units[key].length (pre-filter).
360
+ * - val null-never-0 via num(); every row unit-tagged (no USD↔shares conflation).
361
+ * - 404 (bad CIK/taxonomy/concept) → notFoundBundle (never a fabricated val:0);
362
+ * 5xx/timeout/non-JSON/units-shape-drift → THROW; a bad `unit` filter → honest empty
363
+ * + the available-units note (unit is CLIENT-SIDE, never a path segment).
364
+ */
365
+ export declare function companyConcept(args: {
366
+ cikOrTicker: string;
367
+ concept: string;
368
+ taxonomy?: string;
369
+ unit?: string;
370
+ form?: string;
371
+ fy?: number;
372
+ canonicalOnly?: boolean;
373
+ limit?: number;
374
+ offset?: number;
375
+ }): Promise<MetaBundle>;
376
+ export {};
377
+ //# sourceMappingURL=edgar.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"edgar.d.ts","sourceRoot":"","sources":["../src/edgar.ts"],"names":[],"mappings":"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"}