@cyanheads/secedgar-mcp-server 0.19.0 → 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 +15 -6
- package/CLAUDE.md +15 -6
- package/README.md +3 -1
- package/changelog/0.19.x/0.19.1.md +35 -0
- package/dist/mcp-server/tools/definitions/company-search.tool.d.ts +16 -2
- package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/company-search.tool.js +177 -32
- package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +8 -8
- package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/find-holders.tool.js +2 -9
- package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +8 -8
- 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 +3 -10
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +20 -13
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +8 -8
- package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-filings.tool.js +4 -11
- package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
- package/dist/mcp-server/tools/resolved-as.d.ts +4 -2
- package/dist/mcp-server/tools/resolved-as.d.ts.map +1 -1
- package/dist/mcp-server/tools/resolved-as.js +5 -3
- package/dist/mcp-server/tools/resolved-as.js.map +1 -1
- package/dist/mcp-server/tools/sec-upstream-errors.d.ts +15 -1
- package/dist/mcp-server/tools/sec-upstream-errors.d.ts.map +1 -1
- package/dist/mcp-server/tools/sec-upstream-errors.js +15 -1
- package/dist/mcp-server/tools/sec-upstream-errors.js.map +1 -1
- package/dist/services/edgar/data/former-tickers.json +24159 -0
- package/dist/services/edgar/edgar-api-service.d.ts +92 -16
- package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
- package/dist/services/edgar/edgar-api-service.js +268 -69
- package/dist/services/edgar/edgar-api-service.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/types.d.ts +9 -4
- package/dist/services/edgar/types.d.ts.map +1 -1
- package/package.json +4 -3
- package/server.json +3 -3
- package/skills/secedgar-guide/SKILL.md +1 -1
|
@@ -4,14 +4,16 @@
|
|
|
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';
|
|
16
|
+
import { buildFormerTickerIndex, readFormerTicker, withEarlierHolders, } from './former-tickers.js';
|
|
15
17
|
import { listedSymbol, readTickerSpelling } from './listing-codes.js';
|
|
16
18
|
import { MF_TICKERS_URL, TICKERS_URL } from './mirror/types.js';
|
|
17
19
|
import { trigramScorer } from './trigram-similarity.js';
|
|
@@ -193,6 +195,41 @@ const TRIGRAM_THRESHOLD = 0.3;
|
|
|
193
195
|
const TRIGRAM_TOP_N = 3;
|
|
194
196
|
/** The fund slice where nothing is read live: strict mirror mode. */
|
|
195
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
|
+
}
|
|
196
233
|
// ---------------------------------------------------------------------------
|
|
197
234
|
// Corporate-suffix normalization
|
|
198
235
|
// ---------------------------------------------------------------------------
|
|
@@ -294,8 +331,11 @@ export function foldNamePunctuation(name) {
|
|
|
294
331
|
export function joinSpacedInitials(name) {
|
|
295
332
|
return name.replace(/(?<=(?:^| )\p{L}) (?=\p{L}(?: |$))/gu, '');
|
|
296
333
|
}
|
|
297
|
-
/**
|
|
298
|
-
|
|
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;
|
|
299
339
|
/**
|
|
300
340
|
* Whether index `at` of `text` is a word boundary — a letter or digit on exactly one side,
|
|
301
341
|
* regex `\b` read over every script (#218). Either end of the string counts as a side
|
|
@@ -318,6 +358,97 @@ export function containsFromWordStart(name, query) {
|
|
|
318
358
|
return false;
|
|
319
359
|
}
|
|
320
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
|
+
}
|
|
321
452
|
// ---------------------------------------------------------------------------
|
|
322
453
|
// Near-match company suggestions
|
|
323
454
|
// ---------------------------------------------------------------------------
|
|
@@ -371,6 +502,8 @@ class EdgarApiService {
|
|
|
371
502
|
submissionsCache = new LruMap(CACHE_BYTE_LIMITS.submissions);
|
|
372
503
|
/** The newest XBRL acceptance each cached submissions document records, worked out once per document (#234). */
|
|
373
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();
|
|
374
507
|
/**
|
|
375
508
|
* Filers whose recency read or live point read SEC just failed, keyed by padded CIK, each
|
|
376
509
|
* mapped to the instant the mirror stops answering for it unasked (#234), at most
|
|
@@ -444,7 +577,8 @@ class EdgarApiService {
|
|
|
444
577
|
* Resolve a query (ticker, name, or CIK) to company match(es).
|
|
445
578
|
* - Numeric input → direct CIK lookup
|
|
446
579
|
* - 1-5 letters in any case, or anything typed in uppercase → the ticker lookup (O(1)):
|
|
447
|
-
* the symbol as listed, else a dotted share class in its hyphenated form (#110)
|
|
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)
|
|
448
582
|
* - Typed in uppercase, unlisted → the ticker-spelling readings (`readTickerSpelling`,
|
|
449
583
|
* #235): a US venue code dropped (`UEC.N`), a preferred class run together (`CFGPH`), a
|
|
450
584
|
* root listed only as classes (`GLOP`), each match carrying `reading`; a non-US listing
|
|
@@ -453,8 +587,11 @@ class EdgarApiService {
|
|
|
453
587
|
* - Otherwise → name search (exact as written; exact once commas, periods, and
|
|
454
588
|
* apostrophes are folded out and whitespace runs collapse; exact once spaced initials
|
|
455
589
|
* join; prefix of the joined form ending at a word boundary; substring as written
|
|
456
|
-
* starting at one — resolved within the best tier a current name reaches)
|
|
457
|
-
*
|
|
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
|
|
458
595
|
* Returns a single match, an array of multiple matches, or an empty array (no match).
|
|
459
596
|
* Multiple matches are every candidate of that tier, deduplicated by CIK, current names
|
|
460
597
|
* first, never cut: a consumer shows the first ten through `ambiguousMatches` and counts
|
|
@@ -481,14 +618,20 @@ class EdgarApiService {
|
|
|
481
618
|
// write BRK.B where the file lists BRK-B, and no registrant has both forms on file (#110).
|
|
482
619
|
const upper = trimmed.toUpperCase();
|
|
483
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).
|
|
484
623
|
const listed = listedSymbol(upper, cache.byTicker);
|
|
485
|
-
if (listed && (typedUpper || /^[A-Z]{1,5}$/.test(upper)))
|
|
486
|
-
return listed;
|
|
624
|
+
if (listed && (typedUpper || /^[A-Z]{1,5}$/.test(upper))) {
|
|
625
|
+
return withEarlierHolders(listed, cache);
|
|
626
|
+
}
|
|
487
627
|
// Uppercase spellings vendors write for listed symbols, ahead of the name passes, which
|
|
488
628
|
// otherwise read `GS.K` as GSK plc through the period fold (#235).
|
|
489
629
|
const reading = readTickerSpelling(trimmed, cache);
|
|
490
630
|
if (reading !== undefined)
|
|
491
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;
|
|
492
635
|
// A query with no letter or digit names no company: `.` would fold to an empty string
|
|
493
636
|
// that starts every name (#219).
|
|
494
637
|
if (!NAME_WORD_CHAR.test(trimmed))
|
|
@@ -508,32 +651,7 @@ class EdgarApiService {
|
|
|
508
651
|
// `helix acquisition corp iii` — and a substring, matched as written, starts at one, so
|
|
509
652
|
// `SY Bancorp` never names Embassy Bancorp; a query ending mid-word (`Berkshire Hath`)
|
|
510
653
|
// still matches there when the name as written contains it.
|
|
511
|
-
const
|
|
512
|
-
const lowerNormalized = normalizeCompanySuffix(lower);
|
|
513
|
-
const folded = foldNamePunctuation(lower);
|
|
514
|
-
const foldedNormalized = normalizeCompanySuffix(folded);
|
|
515
|
-
const joined = joinSpacedInitials(folded);
|
|
516
|
-
const joinedNormalized = normalizeCompanySuffix(joined);
|
|
517
|
-
// A suffix-dropped name is a prefix of the full one, so the strip runs on prefix hits only.
|
|
518
|
-
const isExact = (name, form, formNormalized) => name === form ||
|
|
519
|
-
normalizeCompanySuffix(name) === formNormalized ||
|
|
520
|
-
(name.startsWith(form) && stripCompanySuffix(name) === form);
|
|
521
|
-
const tierOf = (name) => {
|
|
522
|
-
if (isExact(name, lower, lowerNormalized))
|
|
523
|
-
return 0;
|
|
524
|
-
const foldedName = foldNamePunctuation(name);
|
|
525
|
-
if (isExact(foldedName, folded, foldedNormalized))
|
|
526
|
-
return 1;
|
|
527
|
-
const joinedName = joinSpacedInitials(foldedName);
|
|
528
|
-
// With no initials joined on either side, this repeats the folded tier's comparison.
|
|
529
|
-
if ((joinedName !== foldedName || joined !== folded) &&
|
|
530
|
-
isExact(joinedName, joined, joinedNormalized)) {
|
|
531
|
-
return 2;
|
|
532
|
-
}
|
|
533
|
-
if (joinedName.startsWith(joined) && isWordBoundary(joinedName, joined.length))
|
|
534
|
-
return 3;
|
|
535
|
-
return containsFromWordStart(name, lower) ? 4 : undefined;
|
|
536
|
-
};
|
|
654
|
+
const forms = nameQuery(trimmed);
|
|
537
655
|
// Current names are registry rows, which carry a ticker; former names (the committed
|
|
538
656
|
// asset) carry none. Resolution runs within the best tier a current name reaches —
|
|
539
657
|
// several CIKs there are the ambiguity, and the tiers below are not listed. A former
|
|
@@ -545,7 +663,7 @@ class EdgarApiService {
|
|
|
545
663
|
for (const entry of cache.allEntries) {
|
|
546
664
|
if (!entry.name)
|
|
547
665
|
continue;
|
|
548
|
-
const tier =
|
|
666
|
+
const tier = nameTier(entry.name, forms);
|
|
549
667
|
if (tier === undefined)
|
|
550
668
|
continue;
|
|
551
669
|
(entry.ticker === undefined ? former : current)[tier].push(entry);
|
|
@@ -557,21 +675,47 @@ class EdgarApiService {
|
|
|
557
675
|
...current[bestCurrent],
|
|
558
676
|
...NAME_TIERS.filter((tier) => tier <= bestCurrent).flatMap((tier) => former[tier]),
|
|
559
677
|
];
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
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;
|
|
568
688
|
}
|
|
569
|
-
if (
|
|
570
|
-
return
|
|
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;
|
|
702
|
+
}
|
|
571
703
|
}
|
|
572
704
|
// A symbol typed in mixed or lower case, outside the short alphabetic shape, keeps the name
|
|
573
|
-
// passes ahead of its ticker lookup (`brk.b`, `Bf.b`)
|
|
574
|
-
|
|
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);
|
|
717
|
+
}
|
|
718
|
+
return index;
|
|
575
719
|
}
|
|
576
720
|
/**
|
|
577
721
|
* Resolve an entity name to CIK candidates via EFTS entity-autocomplete
|
|
@@ -585,7 +729,9 @@ class EdgarApiService {
|
|
|
585
729
|
* Distinct from `searchFilings`: same URL path, different query param (`keysTyped`)
|
|
586
730
|
* and response shape (`_source.entity`, not the filing-document `_source`). A
|
|
587
731
|
* failure of the search backend throws `efts_degraded_response` like a search's,
|
|
588
|
-
* 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).
|
|
589
735
|
*/
|
|
590
736
|
async resolveEntityByName(name, scope) {
|
|
591
737
|
const url = new URL('https://efts.sec.gov/LATEST/search-index');
|
|
@@ -603,17 +749,57 @@ class EdgarApiService {
|
|
|
603
749
|
const matches = [];
|
|
604
750
|
for (const hit of hits) {
|
|
605
751
|
const cik = hit._id?.padStart(10, '0');
|
|
606
|
-
const
|
|
607
|
-
if (!cik || !entity || seen.has(cik))
|
|
752
|
+
const source = hit._source;
|
|
753
|
+
if (!cik || !source?.entity || seen.has(cik))
|
|
608
754
|
continue;
|
|
609
755
|
seen.add(cik);
|
|
610
|
-
matches.push({ cik,
|
|
756
|
+
matches.push({ cik, ...splitEntityTickers(source) });
|
|
611
757
|
}
|
|
612
758
|
// A total with no numeric value reads as none, as searchFilings' shape guard reads it (#61):
|
|
613
759
|
// the ambiguity sentence formats `value`, so a malformed one would throw a raw TypeError.
|
|
614
760
|
const total = response.hits.total;
|
|
615
761
|
return { matches, total: typeof total?.value === 'number' ? total : undefined };
|
|
616
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
|
+
}
|
|
617
803
|
/** Reverse lookup: CIK → ticker symbol. */
|
|
618
804
|
async cikToTicker(cik, scope) {
|
|
619
805
|
const cache = await this.getTickerCache(scope);
|
|
@@ -1128,15 +1314,16 @@ class EdgarApiService {
|
|
|
1128
1314
|
* when `cutoff` is given — and `null` on 404. A body the ladder has no use for — a
|
|
1129
1315
|
* 404's, a retried 5xx's, a 429's, one that lands as the caller cancels — is
|
|
1130
1316
|
* cancelled unread (#188); an error the last attempt earns carries a bounded head
|
|
1131
|
-
* of its body, read like any other (#202).
|
|
1132
|
-
* (#181): a 5xx, an attempt that got no HTTP
|
|
1133
|
-
* read, and — for a request that opts in
|
|
1134
|
-
*
|
|
1135
|
-
*
|
|
1136
|
-
* `sec_unavailable` (#233), a backend
|
|
1137
|
-
* other two `sec_unreachable`. Other
|
|
1138
|
-
*
|
|
1139
|
-
* `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.
|
|
1140
1327
|
*
|
|
1141
1328
|
* Every failed attempt and every backoff is charged to the call's failure budget,
|
|
1142
1329
|
* and the ladder ends early once the budget cannot cover another backoff and
|
|
@@ -1221,9 +1408,10 @@ class EdgarApiService {
|
|
|
1221
1408
|
* mapping's `data`: `url`, `status`, and SEC's `Retry-After` when it sends one.
|
|
1222
1409
|
*
|
|
1223
1410
|
* An HTTP answer's body is read under `scope` for the error's diagnostic
|
|
1224
|
-
* (`errorBodyHead`, #202)
|
|
1225
|
-
*
|
|
1226
|
-
*
|
|
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).
|
|
1227
1415
|
*/
|
|
1228
1416
|
async ladderFailure(url, last, end, scope) {
|
|
1229
1417
|
if (last.kind === 'backend_failed')
|
|
@@ -1255,20 +1443,19 @@ class EdgarApiService {
|
|
|
1255
1443
|
};
|
|
1256
1444
|
}
|
|
1257
1445
|
// A 429's body is SEC's full HTML block page; the hint above carries everything
|
|
1258
|
-
// actionable, so the markup is not
|
|
1446
|
+
// actionable, so the markup is not read (#112).
|
|
1447
|
+
let body;
|
|
1259
1448
|
if (scope === null || status === 429) {
|
|
1260
1449
|
await discardBody(response);
|
|
1261
1450
|
}
|
|
1262
1451
|
else {
|
|
1263
|
-
|
|
1264
|
-
// The two names `httpErrorFromResponse` gives a body it captures itself.
|
|
1265
|
-
if (body !== undefined)
|
|
1266
|
-
Object.assign(data, { body, responseBody: body });
|
|
1452
|
+
body = await errorBodyHead(response, scope);
|
|
1267
1453
|
}
|
|
1268
1454
|
const error = await httpErrorFromResponse(response, {
|
|
1269
1455
|
service: 'SEC EDGAR',
|
|
1270
1456
|
data,
|
|
1271
1457
|
captureBody: false,
|
|
1458
|
+
...(body !== undefined && { cause: errorBodyCause(status, body) }),
|
|
1272
1459
|
});
|
|
1273
1460
|
if (!RETRYABLE_STATUSES.has(status))
|
|
1274
1461
|
return error;
|
|
@@ -1555,6 +1742,7 @@ class EdgarApiService {
|
|
|
1555
1742
|
byCik,
|
|
1556
1743
|
bySeriesId,
|
|
1557
1744
|
byTicker,
|
|
1745
|
+
formerTickers: buildFormerTickerIndex(formerTickersData),
|
|
1558
1746
|
fundRetryAt: funds.retryAt,
|
|
1559
1747
|
loadedAt,
|
|
1560
1748
|
};
|
|
@@ -2091,6 +2279,17 @@ async function errorBodyHead(response, scope) {
|
|
|
2091
2279
|
return read.text;
|
|
2092
2280
|
return read.text === '' ? undefined : `${read.text}…`;
|
|
2093
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
|
+
}
|
|
2094
2293
|
/**
|
|
2095
2294
|
* `text`'s first {@link ERROR_BODY_LIMIT_BYTES} bytes — never a partial code point —
|
|
2096
2295
|
* and `…`, or `undefined` when the whole of it fits: the bound on every upstream
|