@cyanheads/secedgar-mcp-server 0.18.1 → 0.19.1
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.
- package/AGENTS.md +36 -24
- package/CLAUDE.md +36 -24
- package/README.md +16 -12
- package/changelog/0.19.x/0.19.0.md +47 -0
- package/changelog/0.19.x/0.19.1.md +35 -0
- package/changelog/template.md +10 -3
- package/dist/config/server-config.js +2 -2
- package/dist/config/server-config.js.map +1 -1
- package/dist/index.js +27 -9
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/tools/dataset-schema.d.ts +14 -0
- package/dist/mcp-server/tools/dataset-schema.d.ts.map +1 -0
- package/dist/mcp-server/tools/dataset-schema.js +16 -0
- package/dist/mcp-server/tools/dataset-schema.js.map +1 -0
- package/dist/mcp-server/tools/definitions/company-search.tool.d.ts +44 -14
- package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/company-search.tool.js +197 -62
- package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts +26 -12
- package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/compare-companies.tool.js +41 -39
- package/dist/mcp-server/tools/definitions/compare-companies.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts +12 -3
- package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js +23 -9
- package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js +2 -2
- package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts +16 -16
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.js +17 -17
- package/dist/mcp-server/tools/definitions/dataframe-query.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts +26 -12
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.js +15 -37
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +36 -20
- package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/find-holders.tool.js +26 -41
- package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts +28 -12
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js +30 -44
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts +50 -14
- package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-filing.tool.js +193 -59
- package/dist/mcp-server/tools/definitions/get-filing.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts +14 -6
- package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-financials.tool.js +38 -41
- package/dist/mcp-server/tools/definitions/get-financials.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts +28 -12
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js +22 -35
- package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts +28 -12
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js +22 -31
- package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +36 -20
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +22 -39
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts +28 -12
- package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-material-events.tool.js +23 -32
- package/dist/mcp-server/tools/definitions/get-material-events.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts +16 -7
- package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-snapshot.tool.js +24 -32
- package/dist/mcp-server/tools/definitions/get-snapshot.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +232 -101
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-concepts.tool.js +3 -3
- package/dist/mcp-server/tools/definitions/search-concepts.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +46 -20
- package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-filings.tool.js +126 -68
- package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
- package/dist/mcp-server/tools/resolved-as.d.ts +10 -0
- package/dist/mcp-server/tools/resolved-as.d.ts.map +1 -0
- package/dist/mcp-server/tools/resolved-as.js +13 -0
- package/dist/mcp-server/tools/resolved-as.js.map +1 -0
- package/dist/mcp-server/tools/sec-upstream-errors.d.ts +44 -0
- package/dist/mcp-server/tools/sec-upstream-errors.d.ts.map +1 -0
- package/dist/mcp-server/tools/sec-upstream-errors.js +48 -0
- package/dist/mcp-server/tools/sec-upstream-errors.js.map +1 -0
- package/dist/services/canvas-bridge/canvas-bridge.d.ts +98 -45
- package/dist/services/canvas-bridge/canvas-bridge.d.ts.map +1 -1
- package/dist/services/canvas-bridge/canvas-bridge.js +137 -126
- package/dist/services/canvas-bridge/canvas-bridge.js.map +1 -1
- package/dist/services/canvas-bridge/sql-gate-extras.d.ts +4 -17
- package/dist/services/canvas-bridge/sql-gate-extras.d.ts.map +1 -1
- package/dist/services/canvas-bridge/sql-gate-extras.js +4 -22
- package/dist/services/canvas-bridge/sql-gate-extras.js.map +1 -1
- package/dist/services/edgar/concept-map.d.ts +10 -6
- package/dist/services/edgar/concept-map.d.ts.map +1 -1
- package/dist/services/edgar/concept-map.js +90 -22
- package/dist/services/edgar/concept-map.js.map +1 -1
- package/dist/services/edgar/data/former-tickers.json +24159 -0
- package/dist/services/edgar/edgar-api-service.d.ts +250 -62
- package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
- package/dist/services/edgar/edgar-api-service.js +808 -189
- package/dist/services/edgar/edgar-api-service.js.map +1 -1
- package/dist/services/edgar/filing-to-text.d.ts +71 -2
- package/dist/services/edgar/filing-to-text.d.ts.map +1 -1
- package/dist/services/edgar/filing-to-text.js +533 -5
- package/dist/services/edgar/filing-to-text.js.map +1 -1
- package/dist/services/edgar/former-tickers.d.ts +47 -0
- package/dist/services/edgar/former-tickers.d.ts.map +1 -0
- package/dist/services/edgar/former-tickers.js +77 -0
- package/dist/services/edgar/former-tickers.js.map +1 -0
- package/dist/services/edgar/listing-codes.d.ts +47 -0
- package/dist/services/edgar/listing-codes.d.ts.map +1 -0
- package/dist/services/edgar/listing-codes.js +110 -0
- package/dist/services/edgar/listing-codes.js.map +1 -0
- package/dist/services/edgar/mirror/edgar-mirror.d.ts +11 -1
- package/dist/services/edgar/mirror/edgar-mirror.d.ts.map +1 -1
- package/dist/services/edgar/mirror/edgar-mirror.js +19 -1
- package/dist/services/edgar/mirror/edgar-mirror.js.map +1 -1
- package/dist/services/edgar/mirror/tickers-sync.d.ts.map +1 -1
- package/dist/services/edgar/mirror/tickers-sync.js +1 -3
- package/dist/services/edgar/mirror/tickers-sync.js.map +1 -1
- package/dist/services/edgar/mirror/types.d.ts +3 -1
- package/dist/services/edgar/mirror/types.d.ts.map +1 -1
- package/dist/services/edgar/mirror/types.js +3 -1
- package/dist/services/edgar/mirror/types.js.map +1 -1
- package/dist/services/edgar/trigram-similarity.d.ts +5 -3
- package/dist/services/edgar/trigram-similarity.d.ts.map +1 -1
- package/dist/services/edgar/trigram-similarity.js +18 -17
- package/dist/services/edgar/trigram-similarity.js.map +1 -1
- package/dist/services/edgar/types.d.ts +20 -7
- package/dist/services/edgar/types.d.ts.map +1 -1
- package/package.json +6 -5
- package/server.json +3 -3
- package/skills/secedgar-guide/SKILL.md +3 -3
- package/dist/mcp-server/tools/escape-inline.d.ts +0 -35
- package/dist/mcp-server/tools/escape-inline.d.ts.map +0 -1
- package/dist/mcp-server/tools/escape-inline.js +0 -51
- package/dist/mcp-server/tools/escape-inline.js.map +0 -1
|
@@ -4,15 +4,19 @@
|
|
|
4
4
|
* with backoff, CIK resolution, and ticker/entity caching.
|
|
5
5
|
* @module services/edgar/edgar-api-service
|
|
6
6
|
*/
|
|
7
|
-
import { McpError, notFound, rateLimited, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
|
|
8
|
-
import { createPacer, httpErrorFromResponse, isRecord, logger, requestContextService, withExtra, } from '@cyanheads/mcp-ts-core/utils';
|
|
7
|
+
import { JsonRpcErrorCode, McpError, notFound, rateLimited, serviceUnavailable, } from '@cyanheads/mcp-ts-core/errors';
|
|
8
|
+
import { createPacer, httpErrorFromResponse, httpStatusToErrorCode, isRecord, logger, requestContextService, withExtra, } from '@cyanheads/mcp-ts-core/utils';
|
|
9
9
|
import { parseDocument } from 'htmlparser2';
|
|
10
10
|
import { getServerConfig } from '../../config/server-config.js';
|
|
11
11
|
import { getEdgarMirror } from './mirror/index.js';
|
|
12
12
|
import { CALL_FAILURE_BUDGET_MS, CallScope } from './call-scope.js';
|
|
13
13
|
import formerNamesData from './data/former-names.json' with { type: 'json' };
|
|
14
|
+
import formerTickersData from './data/former-tickers.json' with { type: 'json' };
|
|
14
15
|
import { parseFilingHeaders, parseSubmissionHeader, } from './filing-headers.js';
|
|
15
|
-
import {
|
|
16
|
+
import { buildFormerTickerIndex, readFormerTicker, withEarlierHolders, } from './former-tickers.js';
|
|
17
|
+
import { listedSymbol, readTickerSpelling } from './listing-codes.js';
|
|
18
|
+
import { MF_TICKERS_URL, TICKERS_URL } from './mirror/types.js';
|
|
19
|
+
import { trigramScorer } from './trigram-similarity.js';
|
|
16
20
|
import { childText, findTag, findTags } from './xml-nodes.js';
|
|
17
21
|
const MAX_RETRIES = 3;
|
|
18
22
|
const BASE_BACKOFF_MS = 1000;
|
|
@@ -54,6 +58,13 @@ const BODY_IDLE_TIMEOUT_MS = 15_000;
|
|
|
54
58
|
* `rate_limited` (#122).
|
|
55
59
|
*/
|
|
56
60
|
const SEC_UNREACHABLE_REASON = 'sec_unreachable';
|
|
61
|
+
/**
|
|
62
|
+
* `data.reason` once SEC answered the last attempt with a 500, 502, 503, or 504,
|
|
63
|
+
* whatever the earlier attempts got (#233). Declared and set retryable beside
|
|
64
|
+
* `sec_unreachable`, under one code for all four: a 504 is SEC's gateway failing,
|
|
65
|
+
* as this service's own header timeout is (#173), not this request timing out.
|
|
66
|
+
*/
|
|
67
|
+
const SEC_UNAVAILABLE_REASON = 'sec_unavailable';
|
|
57
68
|
const BUDGET_SPENT = { kind: 'budget_spent' };
|
|
58
69
|
/**
|
|
59
70
|
* `data.reason` on every SEC rate-limit failure — the upstream 429 and a call
|
|
@@ -72,8 +83,6 @@ const OPEN_GATE = { state: 'open' };
|
|
|
72
83
|
function rateLimitHint(retryAfterSeconds) {
|
|
73
84
|
return `SEC is rate-limiting this server's IP. It resumes serving an IP only after its request rate has stayed below 10 requests/second for 10 minutes, and any request sent meanwhile restarts that clock, so this server sends nothing to SEC until the cool-down ends — retry in ${retryAfterSeconds} seconds. A shared outbound IP can trigger the block even while this server stays under the limit.`;
|
|
74
85
|
}
|
|
75
|
-
/** URL for SEC's mutual-fund ticker file (ETFs and open-end funds). */
|
|
76
|
-
const MF_TICKERS_URL = 'https://www.sec.gov/files/company_tickers_mf.json';
|
|
77
86
|
/**
|
|
78
87
|
* How long a failed load of the fund-ticker file stands before one resolution
|
|
79
88
|
* refetches it (#119). A window rather than every resolution: against a
|
|
@@ -81,12 +90,146 @@ const MF_TICKERS_URL = 'https://www.sec.gov/files/company_tickers_mf.json';
|
|
|
81
90
|
* to each one. After a rate-limit failure the window stretches to the cool-down.
|
|
82
91
|
*/
|
|
83
92
|
const FUND_SLICE_RETRY_MS = 60_000;
|
|
93
|
+
const DAY_MS = 86_400_000;
|
|
94
|
+
/**
|
|
95
|
+
* How long a filer's failed recency read or live point read stands before a point read
|
|
96
|
+
* asks SEC about that filer again, the mirror answering meanwhile (#234): against a
|
|
97
|
+
* persistent 5xx, each filer costs one three-attempt ladder a minute rather than one per read.
|
|
98
|
+
*/
|
|
99
|
+
const FILER_RETRY_MS = 60_000;
|
|
100
|
+
/** Most filers the failure marks hold; past it the mark used longest ago is dropped. */
|
|
101
|
+
const FILER_FAILURE_LIMIT = 4_096;
|
|
102
|
+
const MIB = 1_048_576;
|
|
103
|
+
/**
|
|
104
|
+
* Most bytes each per-key cache of parsed SEC documents holds, by the estimates below —
|
|
105
|
+
* 448 MiB across the three; past its limit a cache drops the entries used longest ago.
|
|
106
|
+
* Every company-scoped read and every mirror point read (#234) goes through the submissions
|
|
107
|
+
* cache. The full-index share holds the heaviest run of quarters one pre-2001 browse reads
|
|
108
|
+
* (`FULL_INDEX_QUARTER_SCAN_CAP` in `search-filings.tool.ts`, 8: 1999Q1–2000Q4, about
|
|
109
|
+
* 221 MiB by `FULL_INDEX_ROW_BYTES`), so the next page of a browse reads no quarter again:
|
|
110
|
+
* a share smaller than one scan drops each quarter before the repeat reaches it.
|
|
111
|
+
* Exported for the cache tests.
|
|
112
|
+
*/
|
|
113
|
+
export const CACHE_BYTE_LIMITS = {
|
|
114
|
+
submissions: 160 * MIB,
|
|
115
|
+
archivePages: 32 * MIB,
|
|
116
|
+
fullIndex: 256 * MIB,
|
|
117
|
+
};
|
|
118
|
+
/**
|
|
119
|
+
* Estimated heap one value of a parsed filings column set retains (`filings.recent` or an
|
|
120
|
+
* archive page), at least the most measured under Bun or Node. Exported for the cache tests.
|
|
121
|
+
*/
|
|
122
|
+
export const FILING_VALUE_BYTES = 24;
|
|
123
|
+
/**
|
|
124
|
+
* Estimated heap a parsed submissions document retains beyond its `recent` columns (entity
|
|
125
|
+
* metadata, the archive-page manifest), at least the most measured under Bun or Node.
|
|
126
|
+
* Exported for the cache tests.
|
|
127
|
+
*/
|
|
128
|
+
export const SUBMISSIONS_DOC_BYTES = 4_096;
|
|
129
|
+
/**
|
|
130
|
+
* Estimated heap one parsed full-index row retains, at least the most measured under Bun or
|
|
131
|
+
* Node. Exported for the cache tests.
|
|
132
|
+
*/
|
|
133
|
+
export const FULL_INDEX_ROW_BYTES = 352;
|
|
134
|
+
/**
|
|
135
|
+
* A string-keyed map keeping the entries used most recently — a read or a write is a use —
|
|
136
|
+
* whose weights sum to at most `limit`: a write past it drops the entries used longest ago,
|
|
137
|
+
* and an entry heavier than `limit` on its own is not kept. The one eviction mechanism for
|
|
138
|
+
* the per-key document caches (weighed in estimated bytes) and the filer failure marks (one
|
|
139
|
+
* apiece).
|
|
140
|
+
*/
|
|
141
|
+
class LruMap {
|
|
142
|
+
entries = new Map();
|
|
143
|
+
limit;
|
|
144
|
+
total = 0;
|
|
145
|
+
constructor(limit) {
|
|
146
|
+
this.limit = limit;
|
|
147
|
+
}
|
|
148
|
+
/** The value under `key`, which becomes the entry used most recently. */
|
|
149
|
+
get(key) {
|
|
150
|
+
const entry = this.entries.get(key);
|
|
151
|
+
if (entry === undefined)
|
|
152
|
+
return undefined;
|
|
153
|
+
this.entries.delete(key);
|
|
154
|
+
this.entries.set(key, entry);
|
|
155
|
+
return entry.value;
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* Write `value` as the entry used most recently, then drop the least recently used until
|
|
159
|
+
* the weights fit. A value heavier than the limit is not kept and drops only its own key's
|
|
160
|
+
* earlier entry.
|
|
161
|
+
*/
|
|
162
|
+
set(key, value, weight) {
|
|
163
|
+
this.delete(key);
|
|
164
|
+
if (weight > this.limit)
|
|
165
|
+
return;
|
|
166
|
+
this.entries.set(key, { value, weight });
|
|
167
|
+
this.total += weight;
|
|
168
|
+
for (const [oldest, entry] of this.entries) {
|
|
169
|
+
if (this.total <= this.limit)
|
|
170
|
+
break;
|
|
171
|
+
this.entries.delete(oldest);
|
|
172
|
+
this.total -= entry.weight;
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
delete(key) {
|
|
176
|
+
const entry = this.entries.get(key);
|
|
177
|
+
if (entry === undefined)
|
|
178
|
+
return;
|
|
179
|
+
this.entries.delete(key);
|
|
180
|
+
this.total -= entry.weight;
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
/** Estimated heap a parsed filings column set retains: each column value at {@link FILING_VALUE_BYTES}. */
|
|
184
|
+
function filingColumnsBytes(columns) {
|
|
185
|
+
let values = 0;
|
|
186
|
+
for (const column of Object.values(columns)) {
|
|
187
|
+
if (Array.isArray(column))
|
|
188
|
+
values += column.length;
|
|
189
|
+
}
|
|
190
|
+
return values * FILING_VALUE_BYTES;
|
|
191
|
+
}
|
|
84
192
|
/** Trigram similarity threshold — minimum Dice score to include a candidate suggestion. */
|
|
85
193
|
const TRIGRAM_THRESHOLD = 0.3;
|
|
86
194
|
/** Maximum number of near-match suggestions to include. */
|
|
87
195
|
const TRIGRAM_TOP_N = 3;
|
|
88
196
|
/** The fund slice where nothing is read live: strict mirror mode. */
|
|
89
197
|
const NO_LIVE_FUNDS = { retryAt: undefined, rows: [] };
|
|
198
|
+
/**
|
|
199
|
+
* An entity-index hit's name and first ticker (#236). SEC writes a listed entity's tickers
|
|
200
|
+
* after its name (`SCHWAB CHARLES CORP (SCHW, SCHW-PJ, SCHW-PD)`) and again in a `tickers`
|
|
201
|
+
* field its schema does not document (`SCHW, SCHW-PJ, SCHW-PD`). That field is the
|
|
202
|
+
* authority: only the parenthetical repeating it is cut, so one SEC lists no tickers for
|
|
203
|
+
* (`DEERFIELD HOLDINGS INC (DE)`) stays in the name and never becomes a ticker.
|
|
204
|
+
*/
|
|
205
|
+
function splitEntityTickers(source) {
|
|
206
|
+
const tickers = typeof source.tickers === 'string' ? source.tickers : '';
|
|
207
|
+
const ticker = tickers.split(',')[0]?.trim();
|
|
208
|
+
if (!ticker)
|
|
209
|
+
return { name: source.entity };
|
|
210
|
+
const listed = ` (${tickers})`;
|
|
211
|
+
return {
|
|
212
|
+
name: source.entity.endsWith(listed) ? source.entity.slice(0, -listed.length) : source.entity,
|
|
213
|
+
ticker,
|
|
214
|
+
};
|
|
215
|
+
}
|
|
216
|
+
/** A subsidiaries exhibit's type: `EX-21`, `EX-21.1`, never `EX-210`. */
|
|
217
|
+
const SUBSIDIARIES_EXHIBIT = /^EX-21(?!\d)/i;
|
|
218
|
+
/**
|
|
219
|
+
* The name a full-text hit's `display_names` records for `cik` (`ROPER TECHNOLOGIES INC
|
|
220
|
+
* (ROP) (CIK 0000882835)` → `ROPER TECHNOLOGIES INC`), or `undefined` when none names it.
|
|
221
|
+
*/
|
|
222
|
+
function filerNameIn(displayNames, cik) {
|
|
223
|
+
const entry = displayNames?.find((name) => name.includes(`(CIK ${cik})`));
|
|
224
|
+
return entry === undefined ? undefined : cleanDisplayName(entry);
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* `name` as the phrase `findSubsidiaryParents` searches for: in double quotes, with any
|
|
228
|
+
* double quote inside it dropped, since one would end the phrase early.
|
|
229
|
+
*/
|
|
230
|
+
export function subsidiaryPhrase(name) {
|
|
231
|
+
return `"${name.replaceAll('"', '').trim()}"`;
|
|
232
|
+
}
|
|
90
233
|
// ---------------------------------------------------------------------------
|
|
91
234
|
// Corporate-suffix normalization
|
|
92
235
|
// ---------------------------------------------------------------------------
|
|
@@ -188,8 +331,11 @@ export function foldNamePunctuation(name) {
|
|
|
188
331
|
export function joinSpacedInitials(name) {
|
|
189
332
|
return name.replace(/(?<=(?:^| )\p{L}) (?=\p{L}(?: |$))/gu, '');
|
|
190
333
|
}
|
|
191
|
-
/**
|
|
192
|
-
|
|
334
|
+
/**
|
|
335
|
+
* A letter or digit: the characters a name's word boundary falls between (#218). A query
|
|
336
|
+
* with none names no company.
|
|
337
|
+
*/
|
|
338
|
+
export const NAME_WORD_CHAR = /[\p{L}\p{N}]/u;
|
|
193
339
|
/**
|
|
194
340
|
* Whether index `at` of `text` is a word boundary — a letter or digit on exactly one side,
|
|
195
341
|
* regex `\b` read over every script (#218). Either end of the string counts as a side
|
|
@@ -212,6 +358,97 @@ export function containsFromWordStart(name, query) {
|
|
|
212
358
|
return false;
|
|
213
359
|
}
|
|
214
360
|
const NAME_TIERS = [0, 1, 2, 3, 4];
|
|
361
|
+
/** The loosest exact tier: 0–2 are exact, 3 is prefix, 4 is substring. */
|
|
362
|
+
export const LAST_EXACT_TIER = 2;
|
|
363
|
+
/** The comparison forms of `query` (trimmed) that {@link nameTier} reads. */
|
|
364
|
+
export function nameQuery(query) {
|
|
365
|
+
const lower = query.trim().toLowerCase();
|
|
366
|
+
const folded = foldNamePunctuation(lower);
|
|
367
|
+
const joined = joinSpacedInitials(folded);
|
|
368
|
+
return {
|
|
369
|
+
lower,
|
|
370
|
+
lowerNormalized: normalizeCompanySuffix(lower),
|
|
371
|
+
folded,
|
|
372
|
+
foldedNormalized: normalizeCompanySuffix(folded),
|
|
373
|
+
joined,
|
|
374
|
+
joinedNormalized: normalizeCompanySuffix(joined),
|
|
375
|
+
};
|
|
376
|
+
}
|
|
377
|
+
/**
|
|
378
|
+
* The {@link NameTier} at which `name` (any case) matches `query`, or `undefined` when no
|
|
379
|
+
* tier reaches it. The three exact tiers also accept a suffix-normalized equality (#107)
|
|
380
|
+
* and the name minus its terminal suffix, so `Apple` names `Apple Inc.` exactly (#155);
|
|
381
|
+
* the query's own suffix is never dropped, so `Toro Co` never meets `TORO CORP.`.
|
|
382
|
+
*/
|
|
383
|
+
export function nameTier(name, query) {
|
|
384
|
+
// A suffix-dropped name is a prefix of the full one, so the strip runs on prefix hits only.
|
|
385
|
+
const isExact = (candidate, form, formNormalized) => candidate === form ||
|
|
386
|
+
normalizeCompanySuffix(candidate) === formNormalized ||
|
|
387
|
+
(candidate.startsWith(form) && stripCompanySuffix(candidate) === form);
|
|
388
|
+
const lowerName = name.toLowerCase();
|
|
389
|
+
if (isExact(lowerName, query.lower, query.lowerNormalized))
|
|
390
|
+
return 0;
|
|
391
|
+
const foldedName = foldNamePunctuation(lowerName);
|
|
392
|
+
if (isExact(foldedName, query.folded, query.foldedNormalized))
|
|
393
|
+
return 1;
|
|
394
|
+
const joinedName = joinSpacedInitials(foldedName);
|
|
395
|
+
// With no initials joined on either side, this repeats the folded tier's comparison.
|
|
396
|
+
if ((joinedName !== foldedName || query.joined !== query.folded) &&
|
|
397
|
+
isExact(joinedName, query.joined, query.joinedNormalized)) {
|
|
398
|
+
return 2;
|
|
399
|
+
}
|
|
400
|
+
if (joinedName.startsWith(query.joined) && isWordBoundary(joinedName, query.joined.length)) {
|
|
401
|
+
return 3;
|
|
402
|
+
}
|
|
403
|
+
return containsFromWordStart(lowerName, query.lower) ? 4 : undefined;
|
|
404
|
+
}
|
|
405
|
+
/** A joined form's words, sorted: the word-order tier's comparison key (#236). */
|
|
406
|
+
function sortedWords(joined) {
|
|
407
|
+
return joined.split(' ').sort().join(' ');
|
|
408
|
+
}
|
|
409
|
+
/**
|
|
410
|
+
* The word-order tier's key for a query: its joined form with the terminal suffix normalized,
|
|
411
|
+
* words sorted — the query's own suffix is never dropped (#155). `undefined` for one word,
|
|
412
|
+
* which the exact tiers already compare.
|
|
413
|
+
*/
|
|
414
|
+
function wordOrderQueryKey(query) {
|
|
415
|
+
return query.joined.includes(' ') ? sortedWords(query.joinedNormalized) : undefined;
|
|
416
|
+
}
|
|
417
|
+
/**
|
|
418
|
+
* The keys a registry or former name meets the word-order tier under (#236): its words once
|
|
419
|
+
* folded and its initials joined, sorted, with the terminal suffix normalized
|
|
420
|
+
* (`normalizeCompanySuffix`) and, when it has one, dropped (`stripCompanySuffix`) — the exact
|
|
421
|
+
* tiers' rules — so `SCHWAB CHARLES CORP` meets `Charles Schwab Corp` and `Charles Schwab`. A
|
|
422
|
+
* key of one word is left out, since a query of one word never reaches the tier.
|
|
423
|
+
*/
|
|
424
|
+
function wordOrderKeys(name) {
|
|
425
|
+
const joined = joinSpacedInitials(foldNamePunctuation(name.toLowerCase()));
|
|
426
|
+
const stripped = stripCompanySuffix(joined);
|
|
427
|
+
return [normalizeCompanySuffix(joined), ...(stripped === undefined ? [] : [stripped])]
|
|
428
|
+
.filter((form) => form.includes(' '))
|
|
429
|
+
.map(sortedWords);
|
|
430
|
+
}
|
|
431
|
+
/** `entries` with each CIK's first entry only, in order: a company's current and former names can both match. */
|
|
432
|
+
function matchesByCik(entries) {
|
|
433
|
+
const seen = new Set();
|
|
434
|
+
return entries.filter((entry) => !seen.has(entry.cik) && seen.add(entry.cik));
|
|
435
|
+
}
|
|
436
|
+
/** Word-order key → the entries meeting it, in `entries` order (#236). */
|
|
437
|
+
function buildWordOrderIndex(entries) {
|
|
438
|
+
const index = new Map();
|
|
439
|
+
for (const entry of entries) {
|
|
440
|
+
if (!entry.name)
|
|
441
|
+
continue;
|
|
442
|
+
for (const key of wordOrderKeys(entry.name)) {
|
|
443
|
+
const hits = index.get(key);
|
|
444
|
+
if (hits)
|
|
445
|
+
hits.push(entry);
|
|
446
|
+
else
|
|
447
|
+
index.set(key, [entry]);
|
|
448
|
+
}
|
|
449
|
+
}
|
|
450
|
+
return index;
|
|
451
|
+
}
|
|
215
452
|
// ---------------------------------------------------------------------------
|
|
216
453
|
// Near-match company suggestions
|
|
217
454
|
// ---------------------------------------------------------------------------
|
|
@@ -225,10 +462,10 @@ const NAME_TIERS = [0, 1, 2, 3, 4];
|
|
|
225
462
|
* meets TRIGRAM_THRESHOLD, sorted descending.
|
|
226
463
|
*/
|
|
227
464
|
export function suggestCompanies(query, allEntries) {
|
|
228
|
-
const
|
|
465
|
+
const similarity = trigramScorer(query.toLowerCase());
|
|
229
466
|
const scored = [];
|
|
230
467
|
for (const entry of allEntries) {
|
|
231
|
-
const score = Math.max(entry.name ?
|
|
468
|
+
const score = Math.max(entry.name ? similarity(entry.name.toLowerCase()) : 0, entry.ticker ? similarity(entry.ticker.toLowerCase()) : 0);
|
|
232
469
|
if (score >= TRIGRAM_THRESHOLD) {
|
|
233
470
|
scored.push({ score, entry });
|
|
234
471
|
}
|
|
@@ -257,12 +494,34 @@ class EdgarApiService {
|
|
|
257
494
|
gate = OPEN_GATE;
|
|
258
495
|
tickerCache;
|
|
259
496
|
tickerCacheLoad;
|
|
260
|
-
/**
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
497
|
+
/**
|
|
498
|
+
* Per-CIK submissions doc cache, keyed by padded CIK (TTL = EDGAR_TICKER_CACHE_TTL), holding at
|
|
499
|
+
* most `CACHE_BYTE_LIMITS.submissions`. Mirror point reads take each filer's recency from it
|
|
500
|
+
* (#234), so every filer the mirror serves passes through it.
|
|
501
|
+
*/
|
|
502
|
+
submissionsCache = new LruMap(CACHE_BYTE_LIMITS.submissions);
|
|
503
|
+
/** The newest XBRL acceptance each cached submissions document records, worked out once per document (#234). */
|
|
504
|
+
xbrlRecency = new WeakMap();
|
|
505
|
+
/** Each ticker index's word-order keys, built on the first query that reaches the tier (#236). */
|
|
506
|
+
wordOrderIndexes = new WeakMap();
|
|
507
|
+
/**
|
|
508
|
+
* Filers whose recency read or live point read SEC just failed, keyed by padded CIK, each
|
|
509
|
+
* mapped to the instant the mirror stops answering for it unasked (#234), at most
|
|
510
|
+
* {@link FILER_FAILURE_LIMIT} of them.
|
|
511
|
+
*/
|
|
512
|
+
filerFailures = new LruMap(FILER_FAILURE_LIMIT);
|
|
513
|
+
/** Each filer's recency read in flight, which the point reads asking meanwhile share (#234). */
|
|
514
|
+
recencyLoads = new Map();
|
|
515
|
+
/**
|
|
516
|
+
* Per-page submissions archive cache, keyed by page name (TTL = EDGAR_TICKER_CACHE_TTL),
|
|
517
|
+
* holding at most `CACHE_BYTE_LIMITS.archivePages`.
|
|
518
|
+
*/
|
|
519
|
+
archivePageCache = new LruMap(CACHE_BYTE_LIMITS.archivePages);
|
|
520
|
+
/**
|
|
521
|
+
* Per-quarter full-index cache, keyed by `${year}Q${quarter}` (TTL = EDGAR_TICKER_CACHE_TTL),
|
|
522
|
+
* holding at most `CACHE_BYTE_LIMITS.fullIndex`.
|
|
523
|
+
*/
|
|
524
|
+
fullIndexCache = new LruMap(CACHE_BYTE_LIMITS.fullIndex);
|
|
266
525
|
constructor() {
|
|
267
526
|
const config = getServerConfig();
|
|
268
527
|
this.cooldownMs = config.rateLimitCooldownSeconds * 1000;
|
|
@@ -317,13 +576,22 @@ class EdgarApiService {
|
|
|
317
576
|
/**
|
|
318
577
|
* Resolve a query (ticker, name, or CIK) to company match(es).
|
|
319
578
|
* - Numeric input → direct CIK lookup
|
|
320
|
-
* - 1-5 uppercase
|
|
579
|
+
* - 1-5 letters in any case, or anything typed in uppercase → the ticker lookup (O(1)):
|
|
580
|
+
* the symbol as listed, else a dotted share class in its hyphenated form (#110), with a
|
|
581
|
+
* `reading` naming any earlier, different holder of the symbol (#237)
|
|
582
|
+
* - Typed in uppercase, unlisted → the ticker-spelling readings (`readTickerSpelling`,
|
|
583
|
+
* #235): a US venue code dropped (`UEC.N`), a preferred class run together (`CFGPH`), a
|
|
584
|
+
* root listed only as classes (`GLOP`), each match carrying `reading`; a non-US listing
|
|
585
|
+
* (`7203.T`) is no match
|
|
321
586
|
* - No letter or digit (`.`, `'`) → no match
|
|
322
587
|
* - Otherwise → name search (exact as written; exact once commas, periods, and
|
|
323
588
|
* apostrophes are folded out and whitespace runs collapse; exact once spaced initials
|
|
324
589
|
* join; prefix of the joined form ending at a word boundary; substring as written
|
|
325
|
-
* starting at one — resolved within the best tier a current name reaches)
|
|
326
|
-
*
|
|
590
|
+
* starting at one — resolved within the best tier a current name reaches). Typed in
|
|
591
|
+
* uppercase, a former ticker (#237) answers ahead of it unless a current name is the
|
|
592
|
+
* input exactly, or the former holder is listed no more and the names find one company
|
|
593
|
+
* - No name tier matching and two or more words → the word-order tier (#236)
|
|
594
|
+
* - Then, for input not typed in uppercase, the ticker lookup, then a former ticker
|
|
327
595
|
* Returns a single match, an array of multiple matches, or an empty array (no match).
|
|
328
596
|
* Multiple matches are every candidate of that tier, deduplicated by CIK, current names
|
|
329
597
|
* first, never cut: a consumer shows the first ten through `ambiguousMatches` and counts
|
|
@@ -344,13 +612,26 @@ class EdgarApiService {
|
|
|
344
612
|
// return a CIK-only match and let the caller resolve identity from submissions.
|
|
345
613
|
return { cik: padded };
|
|
346
614
|
}
|
|
347
|
-
//
|
|
615
|
+
// A listed symbol (ETF/MF tickers from company_tickers_mf.json included) answers first for
|
|
616
|
+
// short alphabetic input in any case, and for any input typed in uppercase, so a reading
|
|
617
|
+
// or the period fold never takes a symbol the file lists; brokers and market-data sites
|
|
618
|
+
// write BRK.B where the file lists BRK-B, and no registrant has both forms on file (#110).
|
|
348
619
|
const upper = trimmed.toUpperCase();
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
620
|
+
const typedUpper = trimmed === upper;
|
|
621
|
+
// The listing always answers; a symbol an earlier, different company held carries a reading
|
|
622
|
+
// naming it (`XOM` stays ExxonMobil Holdings Corp and names EXXON MOBIL CORP, #237).
|
|
623
|
+
const listed = listedSymbol(upper, cache.byTicker);
|
|
624
|
+
if (listed && (typedUpper || /^[A-Z]{1,5}$/.test(upper))) {
|
|
625
|
+
return withEarlierHolders(listed, cache);
|
|
353
626
|
}
|
|
627
|
+
// Uppercase spellings vendors write for listed symbols, ahead of the name passes, which
|
|
628
|
+
// otherwise read `GS.K` as GSK plc through the period fold (#235).
|
|
629
|
+
const reading = readTickerSpelling(trimmed, cache);
|
|
630
|
+
if (reading !== undefined)
|
|
631
|
+
return reading;
|
|
632
|
+
// An uppercase symbol the file no longer lists reads as the company that held it last
|
|
633
|
+
// (#237), weighed against the name passes below.
|
|
634
|
+
const formerTicker = typedUpper ? readFormerTicker(trimmed, cache) : undefined;
|
|
354
635
|
// A query with no letter or digit names no company: `.` would fold to an empty string
|
|
355
636
|
// that starts every name (#219).
|
|
356
637
|
if (!NAME_WORD_CHAR.test(trimmed))
|
|
@@ -370,32 +651,7 @@ class EdgarApiService {
|
|
|
370
651
|
// `helix acquisition corp iii` — and a substring, matched as written, starts at one, so
|
|
371
652
|
// `SY Bancorp` never names Embassy Bancorp; a query ending mid-word (`Berkshire Hath`)
|
|
372
653
|
// still matches there when the name as written contains it.
|
|
373
|
-
const
|
|
374
|
-
const lowerNormalized = normalizeCompanySuffix(lower);
|
|
375
|
-
const folded = foldNamePunctuation(lower);
|
|
376
|
-
const foldedNormalized = normalizeCompanySuffix(folded);
|
|
377
|
-
const joined = joinSpacedInitials(folded);
|
|
378
|
-
const joinedNormalized = normalizeCompanySuffix(joined);
|
|
379
|
-
// A suffix-dropped name is a prefix of the full one, so the strip runs on prefix hits only.
|
|
380
|
-
const isExact = (name, form, formNormalized) => name === form ||
|
|
381
|
-
normalizeCompanySuffix(name) === formNormalized ||
|
|
382
|
-
(name.startsWith(form) && stripCompanySuffix(name) === form);
|
|
383
|
-
const tierOf = (name) => {
|
|
384
|
-
if (isExact(name, lower, lowerNormalized))
|
|
385
|
-
return 0;
|
|
386
|
-
const foldedName = foldNamePunctuation(name);
|
|
387
|
-
if (isExact(foldedName, folded, foldedNormalized))
|
|
388
|
-
return 1;
|
|
389
|
-
const joinedName = joinSpacedInitials(foldedName);
|
|
390
|
-
// With no initials joined on either side, this repeats the folded tier's comparison.
|
|
391
|
-
if ((joinedName !== foldedName || joined !== folded) &&
|
|
392
|
-
isExact(joinedName, joined, joinedNormalized)) {
|
|
393
|
-
return 2;
|
|
394
|
-
}
|
|
395
|
-
if (joinedName.startsWith(joined) && isWordBoundary(joinedName, joined.length))
|
|
396
|
-
return 3;
|
|
397
|
-
return containsFromWordStart(name, lower) ? 4 : undefined;
|
|
398
|
-
};
|
|
654
|
+
const forms = nameQuery(trimmed);
|
|
399
655
|
// Current names are registry rows, which carry a ticker; former names (the committed
|
|
400
656
|
// asset) carry none. Resolution runs within the best tier a current name reaches —
|
|
401
657
|
// several CIKs there are the ambiguity, and the tiers below are not listed. A former
|
|
@@ -407,7 +663,7 @@ class EdgarApiService {
|
|
|
407
663
|
for (const entry of cache.allEntries) {
|
|
408
664
|
if (!entry.name)
|
|
409
665
|
continue;
|
|
410
|
-
const tier =
|
|
666
|
+
const tier = nameTier(entry.name, forms);
|
|
411
667
|
if (tier === undefined)
|
|
412
668
|
continue;
|
|
413
669
|
(entry.ticker === undefined ? former : current)[tier].push(entry);
|
|
@@ -419,25 +675,47 @@ class EdgarApiService {
|
|
|
419
675
|
...current[bestCurrent],
|
|
420
676
|
...NAME_TIERS.filter((tier) => tier <= bestCurrent).flatMap((tier) => former[tier]),
|
|
421
677
|
];
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
678
|
+
const named = matchesByCik(candidates);
|
|
679
|
+
// The former ticker answers ahead of the names (`BK` is BNY, not BK Technologies, whose
|
|
680
|
+
// name only starts with it; `STR` starts many names) unless a current name is the input
|
|
681
|
+
// exactly (`CHUBB` is Chubb Ltd, not CommerceHub), or its holder is listed no more and the
|
|
682
|
+
// names find one company (`DINE` stays Dine Brands, not Rewards Network) (#237).
|
|
683
|
+
const exactCurrent = bestCurrent !== undefined && bestCurrent <= LAST_EXACT_TIER;
|
|
684
|
+
if (formerTicker &&
|
|
685
|
+
!exactCurrent &&
|
|
686
|
+
(formerTicker.ticker !== undefined || named.length !== 1)) {
|
|
687
|
+
return formerTicker;
|
|
688
|
+
}
|
|
689
|
+
if (named.length > 0)
|
|
690
|
+
return named.length === 1 ? named[0] : named;
|
|
691
|
+
// When no tier reaches any name, a query of two or more words may reorder one: SEC writes
|
|
692
|
+
// `SCHWAB CHARLES CORP` for `Charles Schwab` (#236). Current names before former ones (#155).
|
|
693
|
+
const key = wordOrderQueryKey(forms);
|
|
694
|
+
if (key !== undefined) {
|
|
695
|
+
const hits = this.wordOrderIndex(cache.allEntries).get(key) ?? [];
|
|
696
|
+
const reordered = matchesByCik([
|
|
697
|
+
...hits.filter((entry) => entry.ticker !== undefined),
|
|
698
|
+
...hits.filter((entry) => entry.ticker === undefined),
|
|
699
|
+
]);
|
|
700
|
+
if (reordered.length > 0) {
|
|
701
|
+
return reordered.length === 1 ? reordered[0] : reordered;
|
|
429
702
|
}
|
|
430
703
|
}
|
|
431
|
-
|
|
432
|
-
|
|
704
|
+
// A symbol typed in mixed or lower case, outside the short alphabetic shape, keeps the name
|
|
705
|
+
// passes ahead of its ticker lookup (`brk.b`, `Bf.b`), and so does a former ticker (`amrk`,
|
|
706
|
+
// while `bk` keeps the name passes' BK Technologies, #237).
|
|
707
|
+
if (listed)
|
|
708
|
+
return withEarlierHolders(listed, cache);
|
|
709
|
+
return (typedUpper ? undefined : readFormerTicker(trimmed, cache)) ?? [];
|
|
710
|
+
}
|
|
711
|
+
/** The word-order keys of one ticker index's entries, built once per index (#236). */
|
|
712
|
+
wordOrderIndex(entries) {
|
|
713
|
+
let index = this.wordOrderIndexes.get(entries);
|
|
714
|
+
if (!index) {
|
|
715
|
+
index = buildWordOrderIndex(entries);
|
|
716
|
+
this.wordOrderIndexes.set(entries, index);
|
|
433
717
|
}
|
|
434
|
-
|
|
435
|
-
// that bypassed the early ticker gate above). On a miss, retry a dotted symbol in
|
|
436
|
-
// SEC's hyphenated share-class form — brokers and market-data sites write BRK.B where
|
|
437
|
-
// company_tickers.json lists BRK-B, and no registrant has both forms on file (#110).
|
|
438
|
-
const tickerMatch = cache.byTicker.get(upper) ??
|
|
439
|
-
(upper.includes('.') ? cache.byTicker.get(upper.replaceAll('.', '-')) : undefined);
|
|
440
|
-
return tickerMatch ?? [];
|
|
718
|
+
return index;
|
|
441
719
|
}
|
|
442
720
|
/**
|
|
443
721
|
* Resolve an entity name to CIK candidates via EFTS entity-autocomplete
|
|
@@ -451,7 +729,9 @@ class EdgarApiService {
|
|
|
451
729
|
* Distinct from `searchFilings`: same URL path, different query param (`keysTyped`)
|
|
452
730
|
* and response shape (`_source.entity`, not the filing-document `_source`). A
|
|
453
731
|
* failure of the search backend throws `efts_degraded_response` like a search's,
|
|
454
|
-
* never reads as no match (#206). The name is escaped like a search's `q` (#205).
|
|
732
|
+
* never reads as no match (#206). The name is escaped like a search's `q` (#205). A
|
|
733
|
+
* listed entity's name comes back without the ticker list SEC appends to it, its first
|
|
734
|
+
* ticker beside it (#236).
|
|
455
735
|
*/
|
|
456
736
|
async resolveEntityByName(name, scope) {
|
|
457
737
|
const url = new URL('https://efts.sec.gov/LATEST/search-index');
|
|
@@ -469,17 +749,57 @@ class EdgarApiService {
|
|
|
469
749
|
const matches = [];
|
|
470
750
|
for (const hit of hits) {
|
|
471
751
|
const cik = hit._id?.padStart(10, '0');
|
|
472
|
-
const
|
|
473
|
-
if (!cik || !entity || seen.has(cik))
|
|
752
|
+
const source = hit._source;
|
|
753
|
+
if (!cik || !source?.entity || seen.has(cik))
|
|
474
754
|
continue;
|
|
475
755
|
seen.add(cik);
|
|
476
|
-
matches.push({ cik,
|
|
756
|
+
matches.push({ cik, ...splitEntityTickers(source) });
|
|
477
757
|
}
|
|
478
758
|
// A total with no numeric value reads as none, as searchFilings' shape guard reads it (#61):
|
|
479
759
|
// the ambiguity sentence formats `value`, so a malformed one would throw a raw TypeError.
|
|
480
760
|
const total = response.hits.total;
|
|
481
761
|
return { matches, total: typeof total?.value === 'number' ? total : undefined };
|
|
482
762
|
}
|
|
763
|
+
/**
|
|
764
|
+
* The filers whose 10-K subsidiaries exhibit (EX-21) holds `name` as a phrase (#236): one
|
|
765
|
+
* EDGAR full-text search for {@link subsidiaryPhrase} over 10-Ks, its first 100 documents.
|
|
766
|
+
* Only an exhibit whose type is EX-21 names a parent — the other 10-K documents that
|
|
767
|
+
* mention a private company are mostly a lender's schedule of investments or a
|
|
768
|
+
* competitor's or customer's narrative. Each filer of such an exhibit counts, since a
|
|
769
|
+
* combined report lists every co-registrant, and is reported at its newest one. Filers
|
|
770
|
+
* SEC's ticker file lists come first, then the newest exhibit, then search order. Fails
|
|
771
|
+
* as `searchFilings` fails.
|
|
772
|
+
*/
|
|
773
|
+
async findSubsidiaryParents(name, scope) {
|
|
774
|
+
const response = await this.searchFilings({ query: subsidiaryPhrase(name), forms: ['10-K'], size: 100 }, scope);
|
|
775
|
+
// Insertion order is search order: a newer exhibit updates a filer in place.
|
|
776
|
+
const found = new Map();
|
|
777
|
+
for (const { _source: source } of response.hits.hits) {
|
|
778
|
+
if (!SUBSIDIARIES_EXHIBIT.test(source.file_type ?? ''))
|
|
779
|
+
continue;
|
|
780
|
+
for (const filer of source.ciks ?? []) {
|
|
781
|
+
const cik = filer.padStart(10, '0');
|
|
782
|
+
const known = found.get(cik);
|
|
783
|
+
if (known && known.filingDate >= source.file_date)
|
|
784
|
+
continue;
|
|
785
|
+
const filerName = filerNameIn(source.display_names, cik);
|
|
786
|
+
found.set(cik, {
|
|
787
|
+
cik,
|
|
788
|
+
accessionNumber: source.adsh,
|
|
789
|
+
filingDate: source.file_date,
|
|
790
|
+
...(filerName !== undefined && { name: filerName }),
|
|
791
|
+
});
|
|
792
|
+
}
|
|
793
|
+
}
|
|
794
|
+
const cache = await this.getTickerCache(scope);
|
|
795
|
+
const parents = [...found.values()].map((parent) => {
|
|
796
|
+
const ticker = cache.byCik.get(parent.cik)?.ticker;
|
|
797
|
+
return ticker === undefined ? parent : { ...parent, ticker };
|
|
798
|
+
});
|
|
799
|
+
// `sort` is stable, so search order settles what the listing and the date leave tied.
|
|
800
|
+
return parents.sort((a, b) => Number(b.ticker !== undefined) - Number(a.ticker !== undefined) ||
|
|
801
|
+
b.filingDate.localeCompare(a.filingDate));
|
|
802
|
+
}
|
|
483
803
|
/** Reverse lookup: CIK → ticker symbol. */
|
|
484
804
|
async cikToTicker(cik, scope) {
|
|
485
805
|
const cache = await this.getTickerCache(scope);
|
|
@@ -541,20 +861,23 @@ class EdgarApiService {
|
|
|
541
861
|
* the last year or 1,000 filings, whichever holds more — + the `files[]`
|
|
542
862
|
* archive-page manifest). Cached per CIK within
|
|
543
863
|
* the ticker-cache TTL — the doc is large and re-read on every archive-paging
|
|
544
|
-
* scan (#78)
|
|
864
|
+
* scan (#78) and by every mirror point read (#234) — within
|
|
865
|
+
* `CACHE_BYTE_LIMITS.submissions`, the documents used longest ago dropped first. A 404
|
|
866
|
+
* throws (uncached) so a bad CIK still surfaces. A body without
|
|
545
867
|
* the shape the readers index fails as `sec_unreachable` (#186). Like every cache
|
|
546
868
|
* here, written only by a completed read — a cancelled or rejected one caches nothing.
|
|
547
869
|
*/
|
|
548
870
|
async getSubmissions(cik, scope) {
|
|
549
871
|
const padded = cik.padStart(10, '0');
|
|
550
|
-
const cached = this.submissionsCache
|
|
551
|
-
if (cached
|
|
552
|
-
return cached
|
|
872
|
+
const cached = this.readFresh(this.submissionsCache, padded);
|
|
873
|
+
if (cached !== undefined)
|
|
874
|
+
return cached;
|
|
553
875
|
const url = `https://data.sec.gov/submissions/CIK${padded}.json`;
|
|
554
876
|
const data = await this.fetchJson(url, scope);
|
|
555
877
|
if (!isSubmissionsBody(data))
|
|
556
878
|
throw unexpectedShape(url, 'a submissions document');
|
|
557
|
-
|
|
879
|
+
const bytes = SUBMISSIONS_DOC_BYTES + filingColumnsBytes(data.filings.recent);
|
|
880
|
+
this.submissionsCache.set(padded, { at: Date.now(), data }, bytes);
|
|
558
881
|
return data;
|
|
559
882
|
}
|
|
560
883
|
/**
|
|
@@ -563,17 +886,18 @@ class EdgarApiService {
|
|
|
563
886
|
* `recent` window. Read through `SubmissionsArchiveWalk`. The page body is a flat parallel-array object
|
|
564
887
|
* field-compatible with `FilingsRecent`; one without its six indexed columns fails
|
|
565
888
|
* as `sec_unreachable`, uncached (#186). Cached per page within the ticker-cache
|
|
566
|
-
* TTL (pages are large and effectively immutable once archived)
|
|
889
|
+
* TTL (pages are large and effectively immutable once archived) and
|
|
890
|
+
* `CACHE_BYTE_LIMITS.archivePages`, the pages used longest ago dropped first.
|
|
567
891
|
*/
|
|
568
892
|
async fetchArchivePage(name, scope) {
|
|
569
|
-
const cached = this.archivePageCache
|
|
570
|
-
if (cached
|
|
571
|
-
return cached
|
|
893
|
+
const cached = this.readFresh(this.archivePageCache, name);
|
|
894
|
+
if (cached !== undefined)
|
|
895
|
+
return cached;
|
|
572
896
|
const url = `https://data.sec.gov/submissions/${name}`;
|
|
573
897
|
const data = await this.fetchJson(url, scope);
|
|
574
898
|
if (!isFilingColumns(data))
|
|
575
899
|
throw unexpectedShape(url, 'a submissions archive page');
|
|
576
|
-
this.archivePageCache.set(name, { at: Date.now(), data });
|
|
900
|
+
this.archivePageCache.set(name, { at: Date.now(), data }, filingColumnsBytes(data));
|
|
577
901
|
return data;
|
|
578
902
|
}
|
|
579
903
|
/**
|
|
@@ -583,18 +907,29 @@ class EdgarApiService {
|
|
|
583
907
|
* full-text only reaches 2001, but the quarterly indexes reach 1993. The file
|
|
584
908
|
* is not form-filterable server-side (a whole-quarter download), so callers
|
|
585
909
|
* bound how many quarters they scan and filter client-side (#77). Cached per
|
|
586
|
-
* quarter within the ticker-cache TTL — an archived quarter is immutable
|
|
910
|
+
* quarter within the ticker-cache TTL — an archived quarter is immutable — and
|
|
911
|
+
* `CACHE_BYTE_LIMITS.fullIndex`, the quarters used longest ago dropped first.
|
|
587
912
|
*/
|
|
588
913
|
async fetchFullIndexQuarter(year, quarter, scope) {
|
|
589
914
|
const key = `${year}Q${quarter}`;
|
|
590
|
-
const cached = this.fullIndexCache
|
|
591
|
-
if (cached
|
|
592
|
-
return cached
|
|
915
|
+
const cached = this.readFresh(this.fullIndexCache, key);
|
|
916
|
+
if (cached !== undefined)
|
|
917
|
+
return cached;
|
|
593
918
|
const text = await this.fetchText(`https://www.sec.gov/Archives/edgar/full-index/${year}/QTR${quarter}/master.idx`, scope);
|
|
594
919
|
const data = parseMasterIndex(text);
|
|
595
|
-
this.fullIndexCache.set(key, { at: Date.now(), data });
|
|
920
|
+
this.fullIndexCache.set(key, { at: Date.now(), data }, data.length * FULL_INDEX_ROW_BYTES);
|
|
596
921
|
return data;
|
|
597
922
|
}
|
|
923
|
+
/** The document cached under `key` while within the ticker-cache TTL; an expired entry is dropped. */
|
|
924
|
+
readFresh(cache, key) {
|
|
925
|
+
const cached = cache.get(key);
|
|
926
|
+
if (cached === undefined)
|
|
927
|
+
return undefined;
|
|
928
|
+
if (this.isFresh(cached.at))
|
|
929
|
+
return cached.data;
|
|
930
|
+
cache.delete(key);
|
|
931
|
+
return undefined;
|
|
932
|
+
}
|
|
598
933
|
/** True when a cache entry loaded at `at` is still within the ticker-cache TTL. */
|
|
599
934
|
isFresh(at) {
|
|
600
935
|
return Date.now() - at < getServerConfig().tickerCacheTtl * 1000;
|
|
@@ -766,14 +1101,13 @@ class EdgarApiService {
|
|
|
766
1101
|
* Fetch every XBRL fact a company has reported. Returns `null` on 404.
|
|
767
1102
|
* Backs the whole-company reads (`get_snapshot`, `compare_companies`) and the
|
|
768
1103
|
* no-data error path, which surfaces the namespaces and tags a filer uses.
|
|
769
|
-
*
|
|
770
|
-
*
|
|
771
|
-
*
|
|
772
|
-
* anything but an array is dropped (#141).
|
|
1104
|
+
* Routed through the local mirror by {@link pointRead}; the mirror stores one row
|
|
1105
|
+
* per (cik, taxonomy, tag) and reassembles the API shape off a `cik` point lookup.
|
|
1106
|
+
* A concept unit that arrives as anything but an array is dropped (#141).
|
|
773
1107
|
*/
|
|
774
1108
|
async tryGetCompanyFacts(cik, scope) {
|
|
775
1109
|
const padded = cik.padStart(10, '0');
|
|
776
|
-
const facts = await this.
|
|
1110
|
+
const facts = await this.pointRead(padded, scope, (mirror) => mirror.getCompanyFacts(cik), () => this.tryFetchJson(`https://data.sec.gov/api/xbrl/companyfacts/CIK${padded}.json`, scope));
|
|
777
1111
|
for (const namespace of Object.values(facts?.facts ?? {})) {
|
|
778
1112
|
for (const concept of Object.values(namespace))
|
|
779
1113
|
concept.units = arrayUnits(concept.units);
|
|
@@ -782,57 +1116,197 @@ class EdgarApiService {
|
|
|
782
1116
|
}
|
|
783
1117
|
/**
|
|
784
1118
|
* Fetch XBRL data for a concept. Returns `null` if the company does not report this tag.
|
|
785
|
-
*
|
|
786
|
-
*
|
|
787
|
-
* A payload whose every unit arrives malformed comes
|
|
788
|
-
* tag is named but carries nothing (#141).
|
|
1119
|
+
* Routed through the local mirror by {@link pointRead}: where the store answers, a tag
|
|
1120
|
+
* it lacks for a filer it holds is `null` with no live read, as SEC's 404 for an
|
|
1121
|
+
* unreported tag would be (#234). A payload whose every unit arrives malformed comes
|
|
1122
|
+
* back with no units — the tag is named but carries nothing (#141).
|
|
789
1123
|
*/
|
|
790
1124
|
async tryGetCompanyConcept(cik, taxonomy, tag, scope) {
|
|
791
1125
|
const padded = cik.padStart(10, '0');
|
|
792
|
-
const concept = await this.
|
|
1126
|
+
const concept = await this.pointRead(padded, scope, (mirror) => mirror.getCompanyConcept(cik, taxonomy, tag), () => this.tryFetchJson(`https://data.sec.gov/api/xbrl/companyconcept/CIK${padded}/${taxonomy}/${tag}.json`, scope));
|
|
793
1127
|
if (concept)
|
|
794
1128
|
concept.units = arrayUnits(concept.units);
|
|
795
1129
|
return concept;
|
|
796
1130
|
}
|
|
797
1131
|
/**
|
|
798
1132
|
* Fetch cross-company frame data. Returns `null` if no companies report this combination.
|
|
799
|
-
* A frame is a full scan of the company-facts store, so
|
|
800
|
-
*
|
|
801
|
-
*
|
|
802
|
-
*
|
|
803
|
-
* the
|
|
1133
|
+
* A frame is a full scan of the company-facts store, so the mirror serves it only once
|
|
1134
|
+
* that layer is fully synced (`companyFactsComplete()`): a partial or mid-sync store
|
|
1135
|
+
* would yield a silently incomplete frame, so frames read live until it is complete,
|
|
1136
|
+
* and strict mode (`mirrorFallbackLive` off) throws instead (#29). On a complete store:
|
|
1137
|
+
* - Strict mode → the store's frame, `null` on a miss; nothing is sent.
|
|
1138
|
+
* - A period whose filing window was still open at the companyfacts checkpoint
|
|
1139
|
+
* ({@link frameWindowClosesMs}), or a store with no checkpoint → live, since filers
|
|
1140
|
+
* may have reported for it since (#234). On any failure but the caller's cancel the
|
|
1141
|
+
* store's frame answers, or the live failure stands when the store has none.
|
|
1142
|
+
* - A closed period → the store's frame, which applies the holder-form rules the live
|
|
1143
|
+
* frames API cannot (#123, #142); live on a miss.
|
|
804
1144
|
*/
|
|
805
|
-
tryGetFrames(taxonomy, tag, unit, period, scope) {
|
|
806
|
-
|
|
1145
|
+
async tryGetFrames(taxonomy, tag, unit, period, scope) {
|
|
1146
|
+
const live = () => this.tryFetchJson(`https://data.sec.gov/api/xbrl/frames/${taxonomy}/${tag}/${unit}/${period}.json`, scope);
|
|
1147
|
+
const mirror = getEdgarMirror();
|
|
1148
|
+
if (!mirror)
|
|
1149
|
+
return live();
|
|
1150
|
+
const strict = !getServerConfig().mirrorFallbackLive;
|
|
1151
|
+
if (!(await mirror.companyFactsComplete())) {
|
|
1152
|
+
if (strict)
|
|
1153
|
+
throw companyFactsNotSynced();
|
|
1154
|
+
return live();
|
|
1155
|
+
}
|
|
1156
|
+
const stored = () => mirror.getFrames(taxonomy, tag, unit, period);
|
|
1157
|
+
if (strict)
|
|
1158
|
+
return stored();
|
|
1159
|
+
// No checkpoint parses to NaN, which compares false: the period counts as open.
|
|
1160
|
+
const checkpointMs = Date.parse((await mirror.companyFactsCheckpoint()) ?? '');
|
|
1161
|
+
if (!(checkpointMs >= frameWindowClosesMs(period))) {
|
|
1162
|
+
try {
|
|
1163
|
+
return await live();
|
|
1164
|
+
}
|
|
1165
|
+
catch (error) {
|
|
1166
|
+
if (scope.signal.aborted)
|
|
1167
|
+
throw error;
|
|
1168
|
+
const frame = await stored();
|
|
1169
|
+
if (frame === null)
|
|
1170
|
+
throw error;
|
|
1171
|
+
return frame;
|
|
1172
|
+
}
|
|
1173
|
+
}
|
|
1174
|
+
return (await stored()) ?? live();
|
|
807
1175
|
}
|
|
808
1176
|
/**
|
|
809
|
-
* Route a
|
|
810
|
-
*
|
|
811
|
-
*
|
|
812
|
-
*
|
|
813
|
-
*
|
|
814
|
-
* -
|
|
815
|
-
* -
|
|
816
|
-
*
|
|
817
|
-
* -
|
|
818
|
-
*
|
|
819
|
-
*
|
|
1177
|
+
* Route a point read of one filer (`tryGetCompanyConcept`, `tryGetCompanyFacts`; `cik`
|
|
1178
|
+
* zero-padded) through the local mirror (#234):
|
|
1179
|
+
* - No mirror → live.
|
|
1180
|
+
* - The company-facts layer has never synced → live; strict mode (`mirrorFallbackLive`
|
|
1181
|
+
* off) throws instead.
|
|
1182
|
+
* - Strict mode → the store, `null` on a miss; nothing is sent.
|
|
1183
|
+
* - A filer the store does not hold → live, failing as the live read does, since the
|
|
1184
|
+
* store has nothing to answer with.
|
|
1185
|
+
* - The call's SEC-failure budget already spent, or no sign the filer has filed XBRL
|
|
1186
|
+
* since the store's facts were compiled ({@link filerMayHaveFiled}) → the store; a tag
|
|
1187
|
+
* it lacks is `null`, as SEC answers for a tag the filer does not report.
|
|
1188
|
+
* - Otherwise → live. A 404 answers the store's row where it holds one, since SEC never
|
|
1189
|
+
* drops a fact from a filer's companyfacts once reported, and `null` where it does not.
|
|
1190
|
+
* On any failure but the caller's cancel the store answers, and goes on answering for
|
|
1191
|
+
* that filer without asking SEC for {@link FILER_RETRY_MS}, or the failure's
|
|
1192
|
+
* `retryAfter` when longer — so a rate-limit refusal never turns an answer the store
|
|
1193
|
+
* holds into a failure — unless the call's own spent failure budget ended the read
|
|
1194
|
+
* ({@link markFilerFailed}).
|
|
820
1195
|
*/
|
|
821
|
-
async
|
|
1196
|
+
async pointRead(cik, scope, mirrorRead, live) {
|
|
822
1197
|
const mirror = getEdgarMirror();
|
|
823
|
-
if (mirror)
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
1198
|
+
if (!mirror)
|
|
1199
|
+
return live();
|
|
1200
|
+
const strict = !getServerConfig().mirrorFallbackLive;
|
|
1201
|
+
if (!(await mirror.companyFactsReady())) {
|
|
1202
|
+
if (strict)
|
|
1203
|
+
throw companyFactsNotSynced();
|
|
1204
|
+
return live();
|
|
1205
|
+
}
|
|
1206
|
+
if (strict)
|
|
1207
|
+
return mirrorRead(mirror);
|
|
1208
|
+
if (!(await mirror.holdsFiler(cik)))
|
|
1209
|
+
return live();
|
|
1210
|
+
if (scope.remainingMs === 0 || !(await this.filerMayHaveFiled(mirror, cik, scope))) {
|
|
1211
|
+
return mirrorRead(mirror);
|
|
1212
|
+
}
|
|
1213
|
+
let answer;
|
|
1214
|
+
try {
|
|
1215
|
+
answer = await live();
|
|
1216
|
+
}
|
|
1217
|
+
catch (error) {
|
|
1218
|
+
if (scope.signal.aborted)
|
|
1219
|
+
throw error;
|
|
1220
|
+
this.markFilerFailed(cik, error);
|
|
1221
|
+
return mirrorRead(mirror);
|
|
1222
|
+
}
|
|
1223
|
+
return answer ?? mirrorRead(mirror);
|
|
1224
|
+
}
|
|
1225
|
+
/**
|
|
1226
|
+
* Whether SEC may hold facts for the filer that the store lacks: its newest XBRL filing
|
|
1227
|
+
* ({@link filerRecency}) was accepted on or after the day before the companyfacts
|
|
1228
|
+
* checkpoint — the bulk archive's `Last-Modified` — a margin for filings accepted while
|
|
1229
|
+
* SEC compiled it. A store with no checkpoint answers yes, reading nothing; a failed
|
|
1230
|
+
* recency read answers no, so the store answers.
|
|
1231
|
+
*/
|
|
1232
|
+
async filerMayHaveFiled(mirror, cik, scope) {
|
|
1233
|
+
const checkpointMs = Date.parse((await mirror.companyFactsCheckpoint()) ?? '');
|
|
1234
|
+
if (Number.isNaN(checkpointMs))
|
|
1235
|
+
return true;
|
|
1236
|
+
const latestXbrlMs = await this.filerRecency(cik, scope);
|
|
1237
|
+
return latestXbrlMs !== undefined && latestXbrlMs >= checkpointMs - DAY_MS;
|
|
1238
|
+
}
|
|
1239
|
+
/**
|
|
1240
|
+
* The filer's newest XBRL acceptance in ms ({@link latestXbrlAcceptanceMs}) from its
|
|
1241
|
+
* submissions document, read through `getSubmissions` and its cache — so a call that
|
|
1242
|
+
* already holds the document sends nothing, and otherwise one read goes out per filer
|
|
1243
|
+
* per TTL — or `undefined` while a failure marks the filer ({@link markFilerFailed}).
|
|
1244
|
+
* Point reads asking while a read is in flight share it: a read the same call started,
|
|
1245
|
+
* or another call's that cannot outspend this call's SEC-failure budget, the waiter
|
|
1246
|
+
* charged the failure time it spent waiting; a read that could outlast the waiter's
|
|
1247
|
+
* budget is not joined, and the call reads for itself. A shared read is cancelled only
|
|
1248
|
+
* by the call that started it, and then each waiter asks again under its own scope. The
|
|
1249
|
+
* caller's own cancel rethrows untouched.
|
|
1250
|
+
*/
|
|
1251
|
+
async filerRecency(cik, scope) {
|
|
1252
|
+
for (;;) {
|
|
1253
|
+
const failedUntil = this.filerFailures.get(cik);
|
|
1254
|
+
if (failedUntil !== undefined) {
|
|
1255
|
+
if (Date.now() < failedUntil)
|
|
1256
|
+
return undefined;
|
|
1257
|
+
this.filerFailures.delete(cik);
|
|
1258
|
+
}
|
|
1259
|
+
const load = this.recencyLoads.get(cik);
|
|
1260
|
+
if (!load) {
|
|
1261
|
+
const promise = this.readFilerRecency(cik, scope).finally(() => {
|
|
1262
|
+
this.recencyLoads.delete(cik);
|
|
1263
|
+
});
|
|
1264
|
+
this.recencyLoads.set(cik, { promise, scope, waits: new Map() });
|
|
1265
|
+
return await promise;
|
|
1266
|
+
}
|
|
1267
|
+
if (load.scope === scope)
|
|
1268
|
+
return await load.promise;
|
|
1269
|
+
if (load.scope.remainingMs > scope.remainingMs)
|
|
1270
|
+
return await this.readFilerRecency(cik, scope);
|
|
1271
|
+
try {
|
|
1272
|
+
return await awaitShared(load, scope);
|
|
830
1273
|
}
|
|
831
|
-
|
|
832
|
-
|
|
1274
|
+
catch (error) {
|
|
1275
|
+
// A shared read rejects only when the call that started it is cancelled.
|
|
1276
|
+
if (scope.signal.aborted || !load.scope.signal.aborted)
|
|
1277
|
+
throw error;
|
|
833
1278
|
}
|
|
834
1279
|
}
|
|
835
|
-
|
|
1280
|
+
}
|
|
1281
|
+
/** One recency read; any failure but the caller's cancel answers `undefined`, marking the filer ({@link markFilerFailed}). */
|
|
1282
|
+
async readFilerRecency(cik, scope) {
|
|
1283
|
+
try {
|
|
1284
|
+
const submissions = await this.getSubmissions(cik, scope);
|
|
1285
|
+
let latest = this.xbrlRecency.get(submissions);
|
|
1286
|
+
if (latest === undefined) {
|
|
1287
|
+
latest = latestXbrlAcceptanceMs(submissions.filings);
|
|
1288
|
+
this.xbrlRecency.set(submissions, latest);
|
|
1289
|
+
}
|
|
1290
|
+
return latest;
|
|
1291
|
+
}
|
|
1292
|
+
catch (error) {
|
|
1293
|
+
if (scope.signal.aborted)
|
|
1294
|
+
throw error;
|
|
1295
|
+
this.markFilerFailed(cik, error);
|
|
1296
|
+
return undefined;
|
|
1297
|
+
}
|
|
1298
|
+
}
|
|
1299
|
+
/**
|
|
1300
|
+
* Have the store answer for the filer without asking SEC — no recency read, no live
|
|
1301
|
+
* point read — for {@link FILER_RETRY_MS}, or the failure's `retryAfter` when longer.
|
|
1302
|
+
* A failure the call's own failure budget ended ({@link budgetEndedFailures}) marks
|
|
1303
|
+
* nothing: SEC failed none of its attempts, so it says nothing about the filer.
|
|
1304
|
+
*/
|
|
1305
|
+
markFilerFailed(cik, error) {
|
|
1306
|
+
if (error instanceof McpError && budgetEndedFailures.has(error))
|
|
1307
|
+
return;
|
|
1308
|
+
const until = Date.now() + Math.max(FILER_RETRY_MS, retryAfterMs(error));
|
|
1309
|
+
this.filerFailures.set(cik, until, 1);
|
|
836
1310
|
}
|
|
837
1311
|
// --- Internals ---
|
|
838
1312
|
/**
|
|
@@ -840,15 +1314,16 @@ class EdgarApiService {
|
|
|
840
1314
|
* when `cutoff` is given — and `null` on 404. A body the ladder has no use for — a
|
|
841
1315
|
* 404's, a retried 5xx's, a 429's, one that lands as the caller cancels — is
|
|
842
1316
|
* cancelled unread (#188); an error the last attempt earns carries a bounded head
|
|
843
|
-
* of its body, read like any other (#202).
|
|
844
|
-
* (#181): a 5xx, an attempt that got no HTTP
|
|
845
|
-
* read, and — for a request that opts in
|
|
846
|
-
*
|
|
847
|
-
*
|
|
848
|
-
*
|
|
849
|
-
* other two `sec_unreachable`. Other
|
|
850
|
-
*
|
|
851
|
-
* `RequestCancelled` — those are
|
|
1317
|
+
* of its body on its `cause`, for the log only, read like any other (#202, #244).
|
|
1318
|
+
* The body is read inside the ladder (#181): a 5xx, an attempt that got no HTTP
|
|
1319
|
+
* response, a 2xx whose body failed to read, and — for a request that opts in
|
|
1320
|
+
* with `backendFailure` — a 2xx whose whole body relays a transient failure of
|
|
1321
|
+
* the search backend (#206) all retry up to `MAX_RETRIES` attempts, and then
|
|
1322
|
+
* the last attempt decides — a 5xx throws `sec_unavailable` (#233), a backend
|
|
1323
|
+
* failure `efts_degraded_response`, the other two `sec_unreachable`. Other
|
|
1324
|
+
* non-OK statuses throw at once, as does the local refusal while SEC's
|
|
1325
|
+
* rate-limit block is active, and the pacer's `RequestCancelled` — those are
|
|
1326
|
+
* `McpError`s from `send()`, never retried.
|
|
852
1327
|
*
|
|
853
1328
|
* Every failed attempt and every backoff is charged to the call's failure budget,
|
|
854
1329
|
* and the ladder ends early once the budget cannot cover another backoff and
|
|
@@ -876,7 +1351,7 @@ class EdgarApiService {
|
|
|
876
1351
|
// concurrent one while this retry waited for its slot. A 5xx it ends with had
|
|
877
1352
|
// its body released before the backoff, so the error is built without one.
|
|
878
1353
|
if (failed === undefined)
|
|
879
|
-
throw secUnreachable(url, outcome);
|
|
1354
|
+
throw endedByBudget(secUnreachable(url, outcome));
|
|
880
1355
|
throw await this.ladderFailure(url, failed, { attempt: attempt - 1, budgetStopped: true }, null);
|
|
881
1356
|
}
|
|
882
1357
|
let last = outcome;
|
|
@@ -916,20 +1391,27 @@ class EdgarApiService {
|
|
|
916
1391
|
failed = last;
|
|
917
1392
|
continue;
|
|
918
1393
|
}
|
|
919
|
-
|
|
1394
|
+
const cut = cutByBudget(last);
|
|
1395
|
+
const error = await this.ladderFailure(url, last, { attempt, budgetStopped: attempt < MAX_RETRIES || cut }, scope);
|
|
1396
|
+
// A wait this call's budget cut spends what is left of it, so no attempt follows one:
|
|
1397
|
+
// a first attempt cut short means SEC failed none of this request's attempts.
|
|
1398
|
+
throw attempt === 1 && cut ? endedByBudget(error) : error;
|
|
920
1399
|
}
|
|
921
1400
|
}
|
|
922
1401
|
/**
|
|
923
1402
|
* The error a request's last attempt earned: `sec_unreachable` for no response or
|
|
924
1403
|
* an unreadable body; `efts_degraded_response` for a body relaying a failure of the
|
|
925
|
-
* search backend (#206); for
|
|
926
|
-
* the
|
|
927
|
-
*
|
|
1404
|
+
* search backend (#206); `sec_unavailable` for a 500, 502, 503, or 504, its message
|
|
1405
|
+
* naming the attempt the ladder ended on and, when the failure budget stopped it,
|
|
1406
|
+
* the budget (#179, #233); for any other HTTP answer, its status-classified
|
|
1407
|
+
* `McpError`, with the 403 and 429 hints. Every HTTP answer keeps the status
|
|
1408
|
+
* mapping's `data`: `url`, `status`, and SEC's `Retry-After` when it sends one.
|
|
928
1409
|
*
|
|
929
1410
|
* An HTTP answer's body is read under `scope` for the error's diagnostic
|
|
930
|
-
* (`errorBodyHead`, #202)
|
|
931
|
-
*
|
|
932
|
-
*
|
|
1411
|
+
* (`errorBodyHead`, #202), which rides the error's `cause` to the log and never its
|
|
1412
|
+
* `data` (#244) — except a 429's, and the one `scope` is `null` for: a retried 5xx
|
|
1413
|
+
* whose body was released before its backoff. Either is built without a body, the
|
|
1414
|
+
* 429's cancelled unread (#188).
|
|
933
1415
|
*/
|
|
934
1416
|
async ladderFailure(url, last, end, scope) {
|
|
935
1417
|
if (last.kind === 'backend_failed')
|
|
@@ -937,14 +1419,15 @@ class EdgarApiService {
|
|
|
937
1419
|
if (last.kind !== 'answered')
|
|
938
1420
|
return secUnreachable(url, last, end);
|
|
939
1421
|
const { response } = last;
|
|
1422
|
+
const { status } = response;
|
|
1423
|
+
const host = new URL(url).hostname;
|
|
940
1424
|
const data = { url };
|
|
941
|
-
if (
|
|
942
|
-
const host = new URL(url).hostname;
|
|
1425
|
+
if (status === 403) {
|
|
943
1426
|
data.recovery = {
|
|
944
1427
|
hint: `${host} may be blocking requests. Check EDGAR_USER_AGENT format ("AppName contact@email.com") or retry later.`,
|
|
945
1428
|
};
|
|
946
1429
|
}
|
|
947
|
-
else if (
|
|
1430
|
+
else if (status === 429) {
|
|
948
1431
|
// send() closed the gate on this response, so the wait is the full cool-down.
|
|
949
1432
|
const retryAfter = this.cooldownSecondsRemaining();
|
|
950
1433
|
data.reason = RATE_LIMITED_REASON;
|
|
@@ -952,25 +1435,32 @@ class EdgarApiService {
|
|
|
952
1435
|
data.retryAfter = retryAfter;
|
|
953
1436
|
data.recovery = { hint: rateLimitHint(retryAfter) };
|
|
954
1437
|
}
|
|
1438
|
+
else if (RETRYABLE_STATUSES.has(status)) {
|
|
1439
|
+
data.reason = SEC_UNAVAILABLE_REASON;
|
|
1440
|
+
data.retryable = true;
|
|
1441
|
+
data.recovery = {
|
|
1442
|
+
hint: `SEC EDGAR (${host}) answered the last attempt with HTTP ${status} — a failure on SEC's side, not a problem with the request. Retry the same call in a minute.`,
|
|
1443
|
+
};
|
|
1444
|
+
}
|
|
955
1445
|
// A 429's body is SEC's full HTML block page; the hint above carries everything
|
|
956
|
-
// actionable, so the markup is not
|
|
957
|
-
|
|
1446
|
+
// actionable, so the markup is not read (#112).
|
|
1447
|
+
let body;
|
|
1448
|
+
if (scope === null || status === 429) {
|
|
958
1449
|
await discardBody(response);
|
|
959
1450
|
}
|
|
960
1451
|
else {
|
|
961
|
-
|
|
962
|
-
// The two names `httpErrorFromResponse` gives a body it captures itself.
|
|
963
|
-
if (body !== undefined)
|
|
964
|
-
Object.assign(data, { body, responseBody: body });
|
|
1452
|
+
body = await errorBodyHead(response, scope);
|
|
965
1453
|
}
|
|
966
1454
|
const error = await httpErrorFromResponse(response, {
|
|
967
1455
|
service: 'SEC EDGAR',
|
|
968
1456
|
data,
|
|
969
1457
|
captureBody: false,
|
|
1458
|
+
...(body !== undefined && { cause: errorBodyCause(status, body) }),
|
|
970
1459
|
});
|
|
971
|
-
if (!
|
|
1460
|
+
if (!RETRYABLE_STATUSES.has(status))
|
|
972
1461
|
return error;
|
|
973
|
-
|
|
1462
|
+
const { close, onAttempt } = ladderEndText(end);
|
|
1463
|
+
return serviceUnavailable(`SEC EDGAR (${host}) answered HTTP ${status} on ${onAttempt}${close}`, error.data, { cause: error });
|
|
974
1464
|
}
|
|
975
1465
|
/**
|
|
976
1466
|
* One attempt through the block gate and the pacer, under the caller's signal. A
|
|
@@ -1111,39 +1601,54 @@ class EdgarApiService {
|
|
|
1111
1601
|
return this.buildTickerCache(cache.baseRows, await this.loadMfTickers(scope), cache.loadedAt);
|
|
1112
1602
|
}
|
|
1113
1603
|
/**
|
|
1114
|
-
* Everything the ticker index holds but the live fund slice
|
|
1115
|
-
*
|
|
1116
|
-
*
|
|
1117
|
-
*
|
|
1118
|
-
*
|
|
1119
|
-
*
|
|
1120
|
-
*
|
|
1121
|
-
*
|
|
1604
|
+
* Everything the ticker index holds but the live fund slice. `liveFunds` says whether
|
|
1605
|
+
* company_tickers_mf.json supplements it — everywhere but strict mirror mode — as the
|
|
1606
|
+
* only source of series and class IDs, since the mirror stores a fund symbol as a bare
|
|
1607
|
+
* ticker → CIK row (#43).
|
|
1608
|
+
* - No mirror, or its ticker layer not synced → company_tickers.json, failing as that
|
|
1609
|
+
* read does; strict mode (`mirrorFallbackLive` off) throws instead.
|
|
1610
|
+
* - Strict mode → the mirror's rows, its fund rows its only fund tickers; nothing is sent.
|
|
1611
|
+
* - Otherwise → company_tickers.json, read every TTL as with no mirror, plus the mirror's
|
|
1612
|
+
* fund rows, which rank behind the live fund slice and still resolve a symbol it lacks
|
|
1613
|
+
* (#135). When the ticker file fails — a rate-limit refusal included — the index is
|
|
1614
|
+
* built from all the mirror's rows and stands for the TTL, with one warning (#234).
|
|
1615
|
+
* The load runs under the shared ticker load's scope, which no caller can cancel.
|
|
1122
1616
|
*/
|
|
1123
1617
|
async loadTickerBase(scope) {
|
|
1124
1618
|
const mirror = getEdgarMirror();
|
|
1125
|
-
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
};
|
|
1619
|
+
const mirrorRows = mirror && (await mirror.tickersReady())
|
|
1620
|
+
? (await mirror.getTickerRows()).map(mirrorIndexRow)
|
|
1621
|
+
: [];
|
|
1622
|
+
if (mirror && !getServerConfig().mirrorFallbackLive) {
|
|
1623
|
+
if (mirrorRows.length === 0) {
|
|
1624
|
+
throw serviceUnavailable('EDGAR mirror enabled but the ticker layer is not synced; run `bun run mirror:init`', { layer: 'tickers' });
|
|
1132
1625
|
}
|
|
1626
|
+
return { liveFunds: false, rows: mirrorRows };
|
|
1133
1627
|
}
|
|
1134
|
-
|
|
1135
|
-
|
|
1628
|
+
if (mirrorRows.length === 0)
|
|
1629
|
+
return { liveFunds: true, rows: await this.fetchTickerFile(scope) };
|
|
1630
|
+
try {
|
|
1631
|
+
const equity = await this.fetchTickerFile(scope);
|
|
1632
|
+
return {
|
|
1633
|
+
liveFunds: true,
|
|
1634
|
+
rows: [...equity, ...mirrorRows.filter((row) => row.kind === 'fund')],
|
|
1635
|
+
};
|
|
1636
|
+
}
|
|
1637
|
+
catch (error) {
|
|
1638
|
+
// Background index maintenance with no request of its own to attach to (#43).
|
|
1639
|
+
logger.warning("Ticker file (company_tickers.json) failed to load; the ticker index is built from the local mirror's rows until it reloads.", withExtra(requestContextService.createRequestContext({ operation: 'loadTickerBase' }), {
|
|
1640
|
+
endpoint: 'company_tickers',
|
|
1641
|
+
...failureFields(error),
|
|
1642
|
+
}));
|
|
1643
|
+
return { liveFunds: true, rows: mirrorRows };
|
|
1136
1644
|
}
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
1143
|
-
|
|
1144
|
-
ticker: entry.ticker,
|
|
1145
|
-
})),
|
|
1146
|
-
};
|
|
1645
|
+
}
|
|
1646
|
+
/** company_tickers.json as equity rows; a 200 holding no ticker entry fails as `sec_unreachable`. */
|
|
1647
|
+
async fetchTickerFile(scope) {
|
|
1648
|
+
const rows = parseTickerFile(await this.fetchJson(TICKERS_URL, scope));
|
|
1649
|
+
if (!rows)
|
|
1650
|
+
throw unexpectedShape(TICKERS_URL, 'the ticker file');
|
|
1651
|
+
return rows;
|
|
1147
1652
|
}
|
|
1148
1653
|
/**
|
|
1149
1654
|
* Fetch company_tickers_mf.json (ETFs and mutual funds) as fund rows carrying
|
|
@@ -1159,7 +1664,7 @@ class EdgarApiService {
|
|
|
1159
1664
|
* included (#179).
|
|
1160
1665
|
*/
|
|
1161
1666
|
async loadMfTickers(scope) {
|
|
1162
|
-
let
|
|
1667
|
+
let retryMs = FUND_SLICE_RETRY_MS;
|
|
1163
1668
|
let cause = { reason: 'malformed_body' };
|
|
1164
1669
|
try {
|
|
1165
1670
|
const rows = parseMfTickerFile(await this.fetchJson(MF_TICKERS_URL, scope));
|
|
@@ -1167,16 +1672,9 @@ class EdgarApiService {
|
|
|
1167
1672
|
return { retryAt: undefined, rows };
|
|
1168
1673
|
}
|
|
1169
1674
|
catch (error) {
|
|
1170
|
-
|
|
1171
|
-
|
|
1172
|
-
retryAfterMs = data.retryAfter * 1000;
|
|
1173
|
-
cause = {
|
|
1174
|
-
...(typeof data?.status === 'number' && { status: data.status }),
|
|
1175
|
-
...(typeof data?.reason === 'string' && { reason: data.reason }),
|
|
1176
|
-
error: error instanceof Error ? error.message : String(error),
|
|
1177
|
-
};
|
|
1675
|
+
retryMs = Math.max(FUND_SLICE_RETRY_MS, retryAfterMs(error));
|
|
1676
|
+
cause = failureFields(error);
|
|
1178
1677
|
}
|
|
1179
|
-
const retryMs = Math.max(FUND_SLICE_RETRY_MS, retryAfterMs);
|
|
1180
1678
|
// Background index maintenance with no request of its own to attach to, so the
|
|
1181
1679
|
// global logger carries it (#43).
|
|
1182
1680
|
logger.warning('Fund-ticker file (company_tickers_mf.json) failed to load; ETF and mutual-fund tickers stay unresolved until it is retried.', withExtra(requestContextService.createRequestContext({ operation: 'loadMfTickers' }), {
|
|
@@ -1244,6 +1742,7 @@ class EdgarApiService {
|
|
|
1244
1742
|
byCik,
|
|
1245
1743
|
bySeriesId,
|
|
1246
1744
|
byTicker,
|
|
1745
|
+
formerTickers: buildFormerTickerIndex(formerTickersData),
|
|
1247
1746
|
fundRetryAt: funds.retryAt,
|
|
1248
1747
|
loadedAt,
|
|
1249
1748
|
};
|
|
@@ -1266,6 +1765,103 @@ function arrayUnits(units) {
|
|
|
1266
1765
|
}
|
|
1267
1766
|
return kept;
|
|
1268
1767
|
}
|
|
1768
|
+
/**
|
|
1769
|
+
* The newest acceptance time, in ms, among the XBRL filings a submissions document lists
|
|
1770
|
+
* (#234). The `isXBRL` flag counts on any form: companyfacts takes facts from 8-Ks and
|
|
1771
|
+
* 424B2 fee exhibits as well as periodic reports. Archive pages are not read, so each
|
|
1772
|
+
* counts as an XBRL filing at the end of its last filing day (`filingTo` plus a day).
|
|
1773
|
+
* `+Infinity` — read live — when `recent` lacks either column or a time does not parse;
|
|
1774
|
+
* `-Infinity` when the filer lists no XBRL filing.
|
|
1775
|
+
*/
|
|
1776
|
+
function latestXbrlAcceptanceMs(filings) {
|
|
1777
|
+
const { acceptanceDateTime, isXBRL } = filings.recent;
|
|
1778
|
+
if (!Array.isArray(acceptanceDateTime) || !Array.isArray(isXBRL)) {
|
|
1779
|
+
return Number.POSITIVE_INFINITY;
|
|
1780
|
+
}
|
|
1781
|
+
let latest = Number.NEGATIVE_INFINITY;
|
|
1782
|
+
for (const [i, flag] of isXBRL.entries()) {
|
|
1783
|
+
if (flag !== 1)
|
|
1784
|
+
continue;
|
|
1785
|
+
const accepted = Date.parse(acceptanceDateTime[i] ?? '');
|
|
1786
|
+
if (Number.isNaN(accepted))
|
|
1787
|
+
return Number.POSITIVE_INFINITY;
|
|
1788
|
+
latest = Math.max(latest, accepted);
|
|
1789
|
+
}
|
|
1790
|
+
for (const page of filings.files) {
|
|
1791
|
+
const filedTo = Date.parse(page.filingTo);
|
|
1792
|
+
if (Number.isNaN(filedTo))
|
|
1793
|
+
return Number.POSITIVE_INFINITY;
|
|
1794
|
+
latest = Math.max(latest, filedTo + DAY_MS);
|
|
1795
|
+
}
|
|
1796
|
+
return latest;
|
|
1797
|
+
}
|
|
1798
|
+
/** A frames period: `CY2025`, `CY2026Q3`, or the instant `CY2026Q3I`. */
|
|
1799
|
+
const FRAME_PERIOD = /^CY(\d{4})(?:Q([1-4])I?)?$/;
|
|
1800
|
+
/**
|
|
1801
|
+
* When filers stop reporting for a frames period, in ms (#234): November 1 of the next
|
|
1802
|
+
* year for an annual period, whose frame takes fiscal years ending as late as June 30
|
|
1803
|
+
* plus four months to file; the first day of the seventh month after its calendar
|
|
1804
|
+
* quarter for a quarterly or instant period. `+Infinity`, never closed, for any other.
|
|
1805
|
+
*/
|
|
1806
|
+
function frameWindowClosesMs(period) {
|
|
1807
|
+
const match = FRAME_PERIOD.exec(period);
|
|
1808
|
+
if (!match)
|
|
1809
|
+
return Number.POSITIVE_INFINITY;
|
|
1810
|
+
const year = Number(match[1]);
|
|
1811
|
+
return match[2] === undefined
|
|
1812
|
+
? Date.UTC(year + 1, 10, 1)
|
|
1813
|
+
: Date.UTC(year, Number(match[2]) * 3 + 6, 1);
|
|
1814
|
+
}
|
|
1815
|
+
/**
|
|
1816
|
+
* The wait a failure's `data.retryAfter` asks for, in ms, at most the rate-limit
|
|
1817
|
+
* cool-down; 0 when it names none. A rate-limit refusal carries whole seconds; a 5xx
|
|
1818
|
+
* carries SEC's `Retry-After` header as sent, read when it gives seconds (an HTTP-date
|
|
1819
|
+
* reads as none).
|
|
1820
|
+
*/
|
|
1821
|
+
function retryAfterMs(error) {
|
|
1822
|
+
const retryAfter = error instanceof McpError ? error.data?.retryAfter : undefined;
|
|
1823
|
+
const seconds = typeof retryAfter === 'string' ? Number(retryAfter) : retryAfter;
|
|
1824
|
+
if (typeof seconds !== 'number' || !(seconds > 0))
|
|
1825
|
+
return 0;
|
|
1826
|
+
return Math.min(seconds, getServerConfig().rateLimitCooldownSeconds) * 1000;
|
|
1827
|
+
}
|
|
1828
|
+
/** A failed ticker-file load's log fields: its HTTP status and `data.reason` when it carries them, and its message. */
|
|
1829
|
+
function failureFields(error) {
|
|
1830
|
+
const data = error instanceof McpError ? error.data : undefined;
|
|
1831
|
+
return {
|
|
1832
|
+
...(typeof data?.status === 'number' && { status: data.status }),
|
|
1833
|
+
...(typeof data?.reason === 'string' && { reason: data.reason }),
|
|
1834
|
+
error: error instanceof Error ? error.message : String(error),
|
|
1835
|
+
};
|
|
1836
|
+
}
|
|
1837
|
+
/** Strict mirror mode's failure while the company-facts layer has never completed a sync. */
|
|
1838
|
+
function companyFactsNotSynced() {
|
|
1839
|
+
return serviceUnavailable('EDGAR mirror enabled but the company-facts layer is not synced; run `bun run mirror:init`', { layer: 'companyfacts' });
|
|
1840
|
+
}
|
|
1841
|
+
/**
|
|
1842
|
+
* Parse company_tickers.json — `{ cik_str, ticker, title }` entries keyed by index — into
|
|
1843
|
+
* equity rows, skipping any entry without that shape. Returns `undefined` when no entry
|
|
1844
|
+
* has it, which the caller fails like any unreadable answer (#234).
|
|
1845
|
+
*/
|
|
1846
|
+
function parseTickerFile(raw) {
|
|
1847
|
+
if (!isRecord(raw))
|
|
1848
|
+
return;
|
|
1849
|
+
const rows = [];
|
|
1850
|
+
for (const entry of Object.values(raw)) {
|
|
1851
|
+
if (!isRecord(entry) || typeof entry.ticker !== 'string' || typeof entry.title !== 'string') {
|
|
1852
|
+
continue;
|
|
1853
|
+
}
|
|
1854
|
+
if (typeof entry.cik_str !== 'number' && typeof entry.cik_str !== 'string')
|
|
1855
|
+
continue;
|
|
1856
|
+
rows.push({
|
|
1857
|
+
cik: String(entry.cik_str).padStart(10, '0'),
|
|
1858
|
+
kind: 'equity',
|
|
1859
|
+
name: entry.title,
|
|
1860
|
+
ticker: entry.ticker,
|
|
1861
|
+
});
|
|
1862
|
+
}
|
|
1863
|
+
return rows.length > 0 ? rows : undefined;
|
|
1864
|
+
}
|
|
1269
1865
|
/**
|
|
1270
1866
|
* Classify a mirror ticker row. The mirror schema has no series or class column:
|
|
1271
1867
|
* tickers-sync stores a fund symbol from company_tickers_mf.json with an empty
|
|
@@ -1683,6 +2279,17 @@ async function errorBodyHead(response, scope) {
|
|
|
1683
2279
|
return read.text;
|
|
1684
2280
|
return read.text === '' ? undefined : `${read.text}…`;
|
|
1685
2281
|
}
|
|
2282
|
+
/**
|
|
2283
|
+
* An error response's diagnostic body ({@link errorBodyHead}) as the `cause` of the
|
|
2284
|
+
* error built from that response (#244). The call's failure log record writes every
|
|
2285
|
+
* cause's `data` under the call's `requestId`, and no client envelope carries a cause.
|
|
2286
|
+
* On the error's own `data` the body would reach the caller as given: the framework
|
|
2287
|
+
* keeps off the wire only a body its own capture read, and that capture has no stall
|
|
2288
|
+
* bound or signal (#202).
|
|
2289
|
+
*/
|
|
2290
|
+
function errorBodyCause(status, body) {
|
|
2291
|
+
return new McpError(httpStatusToErrorCode(status) ?? JsonRpcErrorCode.InternalError, `SEC EDGAR's HTTP ${status} response body.`, { body });
|
|
2292
|
+
}
|
|
1686
2293
|
/**
|
|
1687
2294
|
* `text`'s first {@link ERROR_BODY_LIMIT_BYTES} bytes — never a partial code point —
|
|
1688
2295
|
* and `…`, or `undefined` when the whole of it fits: the bound on every upstream
|
|
@@ -1750,6 +2357,18 @@ function cutByBudget(last) {
|
|
|
1750
2357
|
}
|
|
1751
2358
|
}
|
|
1752
2359
|
}
|
|
2360
|
+
/**
|
|
2361
|
+
* The failures the call's own failure budget caused, SEC failing none of the request's
|
|
2362
|
+
* attempts (#179): a request the spent budget kept from being sent, and one whose only
|
|
2363
|
+
* attempt the budget cut short of its own 15 s wait. A filer is never marked failed for one
|
|
2364
|
+
* (`markFilerFailed`, #234). Tracked here rather than on `data`, which reaches the caller.
|
|
2365
|
+
*/
|
|
2366
|
+
const budgetEndedFailures = new WeakSet();
|
|
2367
|
+
/** `error`, recorded as one the call's own failure budget caused ({@link budgetEndedFailures}). */
|
|
2368
|
+
function endedByBudget(error) {
|
|
2369
|
+
budgetEndedFailures.add(error);
|
|
2370
|
+
return error;
|
|
2371
|
+
}
|
|
1753
2372
|
/** How a failure the call's failure budget ended says so, in its message (#179). */
|
|
1754
2373
|
const BUDGET_STOP_TEXT = `retries stopped at this call's ${CALL_FAILURE_BUDGET_MS / 1000} s budget for SEC failures`;
|
|
1755
2374
|
/** A wait in seconds, to one decimal where it is not whole: `15`, `9.1`. */
|