nexustrade 5.2.0 → 5.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +134 -1
- package/dist/cjs/client.js +97 -0
- package/dist/cjs/congress.js +29 -0
- package/dist/cjs/generated/ntSdk.generated.js +133 -133
- package/dist/esm/client.d.ts +60 -1
- package/dist/esm/client.js +97 -0
- package/dist/esm/congress.d.ts +390 -0
- package/dist/esm/congress.js +26 -0
- package/dist/esm/generated/ntSdk.generated.d.ts +133 -133
- package/dist/esm/generated/ntSdk.generated.js +133 -133
- package/dist/esm/index.d.ts +2 -1
- package/package.json +1 -1
package/dist/esm/client.d.ts
CHANGED
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
* pass an API key/base URL, or set NEXUSTRADE_API_KEY / NEXUSTRADE_API_BASE_URL.
|
|
6
6
|
*/
|
|
7
7
|
import { AgentRun } from "./agent.ts";
|
|
8
|
+
import { type CongressChamber, type CongressionalCoverage, type CongressionalEnvelope, type CongressionalFiler, type CongressionalFilerDetail, type CongressionalFilerListOptions, type CongressionalFilerVolume, type CongressionalFiling, type CongressionalFilingLatency, type CongressionalLeaderboard, type CongressionalMemberRecordOptions, type CongressionalTradeDetail, type CongressionalTradeFilters, type CongressionalTradePage, type CongressionalTradeSummary, type ListCongressionalTradesOptions, type PoliticianBot, type PoliticianProfile } from "./congress.ts";
|
|
8
9
|
import type { JobRequest, OrderStatus, Portfolio, Strategy } from "./generated/ntSdk.generated.js";
|
|
9
10
|
import { PortfolioHandle, type DeployResult, type PortfolioListResult } from "./portfolio.ts";
|
|
10
11
|
export type JsonValue = string | number | boolean | null | JsonValue[] | {
|
|
@@ -149,6 +150,17 @@ export interface UploadTransport extends Transport {
|
|
|
149
150
|
contentType: string;
|
|
150
151
|
}): Promise<void>;
|
|
151
152
|
}
|
|
153
|
+
/**
|
|
154
|
+
* Transports that can read NexusTrade's public REST API.
|
|
155
|
+
*
|
|
156
|
+
* Those routes are served at `/api/<path>` on the API origin, beside the
|
|
157
|
+
* versioned SDK routes rather than under them. `path` is relative to `/api/`.
|
|
158
|
+
* An API key is sent when the transport holds one; an anonymous workspace
|
|
159
|
+
* session is never sent, because these routes do not read it.
|
|
160
|
+
*/
|
|
161
|
+
export interface PublicApiTransport extends Transport {
|
|
162
|
+
getPublicApi(path: string): Promise<JsonObject>;
|
|
163
|
+
}
|
|
152
164
|
export interface HttpTransportOptions {
|
|
153
165
|
apiKey?: string;
|
|
154
166
|
baseUrl: string;
|
|
@@ -159,7 +171,7 @@ export interface WorkspaceSessionTransport extends Transport {
|
|
|
159
171
|
exportWorkspaceSession(): string | undefined;
|
|
160
172
|
importWorkspaceSession(workspaceSession: string): void;
|
|
161
173
|
}
|
|
162
|
-
export declare class HttpTransport implements Transport, UploadTransport, WorkspaceSessionTransport {
|
|
174
|
+
export declare class HttpTransport implements Transport, UploadTransport, WorkspaceSessionTransport, PublicApiTransport {
|
|
163
175
|
#private;
|
|
164
176
|
constructor(options: HttpTransportOptions);
|
|
165
177
|
get baseUrl(): string;
|
|
@@ -170,6 +182,7 @@ export declare class HttpTransport implements Transport, UploadTransport, Worksp
|
|
|
170
182
|
contentType: string;
|
|
171
183
|
}): Promise<void>;
|
|
172
184
|
request(method: string, path: string, options?: RequestOptions): Promise<JsonObject>;
|
|
185
|
+
getPublicApi(path: string): Promise<JsonObject>;
|
|
173
186
|
}
|
|
174
187
|
export interface NexusTradeClientOptions {
|
|
175
188
|
apiKey?: string;
|
|
@@ -476,6 +489,52 @@ export declare class NexusTradeClient {
|
|
|
476
489
|
cancelNlScreen(screenId: string): Promise<JsonObject>;
|
|
477
490
|
/** Block until a screen is terminal. See `waitForOperation`. */
|
|
478
491
|
waitForNlScreen(screenId: string, options?: WaitOptions): Promise<JsonObject>;
|
|
492
|
+
/**
|
|
493
|
+
* Congressional trade disclosures, newest first. No API key required.
|
|
494
|
+
*
|
|
495
|
+
* Defaults to equities first made public in the 30 days ending on the
|
|
496
|
+
* dataset's last update day. `fromDate` and `toDate` filter on
|
|
497
|
+
* `firstAvailableAt`. Trade from `availableAt`, when the disclosure became
|
|
498
|
+
* public, never `transactionDate`.
|
|
499
|
+
*/
|
|
500
|
+
listCongressionalTrades(options?: ListCongressionalTradesOptions): Promise<CongressionalEnvelope<CongressionalTradePage>>;
|
|
501
|
+
/** Purchase and sale totals over the same filters as the feed. No API key required. */
|
|
502
|
+
getCongressionalTradeSummary(filters?: CongressionalTradeFilters): Promise<CongressionalEnvelope<CongressionalTradeSummary>>;
|
|
503
|
+
/** Members ranked by their copy bot's cached backtest against SPY. No API key required. */
|
|
504
|
+
getCongressionalLeaderboard(options?: {
|
|
505
|
+
limit?: number;
|
|
506
|
+
}): Promise<CongressionalLeaderboard>;
|
|
507
|
+
/** Days from trade to public disclosure per member, slowest first. No API key required. */
|
|
508
|
+
listCongressionalFilingLatency(filters?: CongressionalFilerListOptions): Promise<CongressionalEnvelope<CongressionalFilingLatency[]>>;
|
|
509
|
+
/** Disclosed dollar volume per member, largest first. No API key required. */
|
|
510
|
+
listCongressionalTradeVolume(filters?: CongressionalFilerListOptions): Promise<CongressionalEnvelope<CongressionalFilerVolume[]>>;
|
|
511
|
+
/**
|
|
512
|
+
* One member's profile and whole trading record. No API key required.
|
|
513
|
+
*
|
|
514
|
+
* `id` is a Bioguide ID (`"P000197"`) or a page slug (`"nancy-pelosi"`).
|
|
515
|
+
* With neither date the record runs from 2012-01-01 to today, and
|
|
516
|
+
* `instrument` defaults to `"all"`.
|
|
517
|
+
*/
|
|
518
|
+
getPolitician(id: string, options?: CongressionalMemberRecordOptions): Promise<CongressionalEnvelope<PoliticianProfile>>;
|
|
519
|
+
/** A member's copy bot and its cached backtest. No API key required. */
|
|
520
|
+
getPoliticianBot(id: string): Promise<PoliticianBot>;
|
|
521
|
+
/** Members with disclosures matching the filters. Requires an API key. */
|
|
522
|
+
listCongressionalFilers(filters?: CongressionalFilerListOptions): Promise<CongressionalEnvelope<CongressionalFiler[]>>;
|
|
523
|
+
/**
|
|
524
|
+
* One member's summary, activity and trades by Bioguide ID. Requires an API key.
|
|
525
|
+
*
|
|
526
|
+
* With neither date the record runs from 2012-01-01 to today, and
|
|
527
|
+
* `instrument` defaults to `"all"`.
|
|
528
|
+
*/
|
|
529
|
+
getCongressionalFiler(filerKey: string, options?: CongressionalMemberRecordOptions): Promise<CongressionalEnvelope<CongressionalFilerDetail>>;
|
|
530
|
+
/** One disclosure with its amendment history. Requires an API key. */
|
|
531
|
+
getCongressionalTrade(eventId: string, options?: {
|
|
532
|
+
asOf?: string;
|
|
533
|
+
}): Promise<CongressionalEnvelope<CongressionalTradeDetail>>;
|
|
534
|
+
/** One source filing and every trade it disclosed. Requires an API key. */
|
|
535
|
+
getCongressionalFiling(chamber: CongressChamber, docId: string): Promise<CongressionalEnvelope<CongressionalFiling>>;
|
|
536
|
+
/** How much of the public record the dataset holds. Requires an API key. */
|
|
537
|
+
getCongressionalCoverage(): Promise<CongressionalEnvelope<CongressionalCoverage>>;
|
|
479
538
|
/** Resolve once a backtest is terminal. See `waitForOperation`. */
|
|
480
539
|
waitForBacktest(backtestId: string, options?: WaitOptions): Promise<JsonObject>;
|
|
481
540
|
/** Resolve once an optimization is terminal. See `waitForOperation`. */
|
package/dist/esm/client.js
CHANGED
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
* pass an API key/base URL, or set NEXUSTRADE_API_KEY / NEXUSTRADE_API_BASE_URL.
|
|
6
6
|
*/
|
|
7
7
|
import { AgentRun } from "./agent.js";
|
|
8
|
+
import { congressionalQueryParams, } from "./congress.js";
|
|
8
9
|
import { LazyDotenv, environmentValue } from "./env.js";
|
|
9
10
|
import { portfolioHandleFromWire, } from "./portfolio.js";
|
|
10
11
|
/** Boundary adapter: builder output is JSON by construction. */
|
|
@@ -153,6 +154,15 @@ function sameOrigin(left, right) {
|
|
|
153
154
|
function supportsUpload(transport) {
|
|
154
155
|
return typeof transport.putBytes === "function";
|
|
155
156
|
}
|
|
157
|
+
function supportsPublicApi(transport) {
|
|
158
|
+
return typeof transport.getPublicApi === "function";
|
|
159
|
+
}
|
|
160
|
+
async function readPublicApi(transport, path) {
|
|
161
|
+
if (!supportsPublicApi(transport)) {
|
|
162
|
+
throw new NexusTradeApiError(NO_HTTP_STATUS, "unsupported_transport", "Congressional trade reads require HttpTransport.getPublicApi.");
|
|
163
|
+
}
|
|
164
|
+
return (await transport.getPublicApi(path));
|
|
165
|
+
}
|
|
156
166
|
function assertValidApiKey(apiKey) {
|
|
157
167
|
const invalid = typeof apiKey !== "string" ||
|
|
158
168
|
apiKey.length === 0 ||
|
|
@@ -265,6 +275,10 @@ async function apiErrorFromResponse(response) {
|
|
|
265
275
|
if (body.message)
|
|
266
276
|
message = String(body.message);
|
|
267
277
|
}
|
|
278
|
+
else if (typeof decoded.message === "string" && decoded.message) {
|
|
279
|
+
// Public REST routes answer `{ message }` with no error envelope.
|
|
280
|
+
message = decoded.message;
|
|
281
|
+
}
|
|
268
282
|
}
|
|
269
283
|
catch {
|
|
270
284
|
// Non-JSON error bodies keep the transport-level code/message.
|
|
@@ -281,6 +295,9 @@ function workspaceSessionUrl(baseUrl) {
|
|
|
281
295
|
parsed.hash = "";
|
|
282
296
|
return parsed.toString();
|
|
283
297
|
}
|
|
298
|
+
function publicApiUrl(baseUrl, path) {
|
|
299
|
+
return `${new URL(baseUrl).origin}/api/${path.replace(/^\/+/, "")}`;
|
|
300
|
+
}
|
|
284
301
|
function supportsWorkspaceSession(transport) {
|
|
285
302
|
const candidate = transport;
|
|
286
303
|
return (typeof candidate.exportWorkspaceSession === "function" &&
|
|
@@ -441,6 +458,16 @@ export class HttpTransport {
|
|
|
441
458
|
if (options.idempotencyKey !== undefined) {
|
|
442
459
|
headers["Idempotency-Key"] = options.idempotencyKey;
|
|
443
460
|
}
|
|
461
|
+
return this.#send(method, url, headers, payload);
|
|
462
|
+
}
|
|
463
|
+
async getPublicApi(path) {
|
|
464
|
+
const headers = { Accept: "application/json" };
|
|
465
|
+
if (this.#apiKey !== undefined) {
|
|
466
|
+
headers.Authorization = `Bearer ${this.#apiKey}`;
|
|
467
|
+
}
|
|
468
|
+
return this.#send("GET", publicApiUrl(this.#baseUrl, path), headers);
|
|
469
|
+
}
|
|
470
|
+
async #send(method, url, headers, payload) {
|
|
444
471
|
const controller = new AbortController();
|
|
445
472
|
const timer = setTimeout(() => controller.abort(), this.#timeoutSeconds * 1000);
|
|
446
473
|
try {
|
|
@@ -1421,6 +1448,76 @@ export class NexusTradeClient {
|
|
|
1421
1448
|
async waitForNlScreen(screenId, options = {}) {
|
|
1422
1449
|
return waitForOperation((id) => this.getNlScreen(id), screenId, options);
|
|
1423
1450
|
}
|
|
1451
|
+
/**
|
|
1452
|
+
* Congressional trade disclosures, newest first. No API key required.
|
|
1453
|
+
*
|
|
1454
|
+
* Defaults to equities first made public in the 30 days ending on the
|
|
1455
|
+
* dataset's last update day. `fromDate` and `toDate` filter on
|
|
1456
|
+
* `firstAvailableAt`. Trade from `availableAt`, when the disclosure became
|
|
1457
|
+
* public, never `transactionDate`.
|
|
1458
|
+
*/
|
|
1459
|
+
async listCongressionalTrades(options = {}) {
|
|
1460
|
+
return readPublicApi(this.transport, `political-disclosures/trades${encodeQuery(congressionalQueryParams(options))}`);
|
|
1461
|
+
}
|
|
1462
|
+
/** Purchase and sale totals over the same filters as the feed. No API key required. */
|
|
1463
|
+
async getCongressionalTradeSummary(filters = {}) {
|
|
1464
|
+
return readPublicApi(this.transport, `political-disclosures/summary${encodeQuery(congressionalQueryParams(filters))}`);
|
|
1465
|
+
}
|
|
1466
|
+
/** Members ranked by their copy bot's cached backtest against SPY. No API key required. */
|
|
1467
|
+
async getCongressionalLeaderboard(options = {}) {
|
|
1468
|
+
return readPublicApi(this.transport, `political-disclosures/leaderboard${encodeQuery({
|
|
1469
|
+
limit: options.limit === undefined ? undefined : String(options.limit),
|
|
1470
|
+
})}`);
|
|
1471
|
+
}
|
|
1472
|
+
/** Days from trade to public disclosure per member, slowest first. No API key required. */
|
|
1473
|
+
async listCongressionalFilingLatency(filters = {}) {
|
|
1474
|
+
return readPublicApi(this.transport, `political-disclosures/filer-latency${encodeQuery(congressionalQueryParams(filters))}`);
|
|
1475
|
+
}
|
|
1476
|
+
/** Disclosed dollar volume per member, largest first. No API key required. */
|
|
1477
|
+
async listCongressionalTradeVolume(filters = {}) {
|
|
1478
|
+
return readPublicApi(this.transport, `political-disclosures/filer-volume${encodeQuery(congressionalQueryParams(filters))}`);
|
|
1479
|
+
}
|
|
1480
|
+
/**
|
|
1481
|
+
* One member's profile and whole trading record. No API key required.
|
|
1482
|
+
*
|
|
1483
|
+
* `id` is a Bioguide ID (`"P000197"`) or a page slug (`"nancy-pelosi"`).
|
|
1484
|
+
* With neither date the record runs from 2012-01-01 to today, and
|
|
1485
|
+
* `instrument` defaults to `"all"`.
|
|
1486
|
+
*/
|
|
1487
|
+
async getPolitician(id, options = {}) {
|
|
1488
|
+
return readPublicApi(this.transport, `political-disclosures/politicians/${encodePathSegment(id)}${encodeQuery(congressionalQueryParams(options))}`);
|
|
1489
|
+
}
|
|
1490
|
+
/** A member's copy bot and its cached backtest. No API key required. */
|
|
1491
|
+
async getPoliticianBot(id) {
|
|
1492
|
+
return readPublicApi(this.transport, `political-disclosures/politicians/${encodePathSegment(id)}/bot`);
|
|
1493
|
+
}
|
|
1494
|
+
/** Members with disclosures matching the filters. Requires an API key. */
|
|
1495
|
+
async listCongressionalFilers(filters = {}) {
|
|
1496
|
+
return readPublicApi(this.transport, `political-disclosures/filers${encodeQuery(congressionalQueryParams(filters))}`);
|
|
1497
|
+
}
|
|
1498
|
+
/**
|
|
1499
|
+
* One member's summary, activity and trades by Bioguide ID. Requires an API key.
|
|
1500
|
+
*
|
|
1501
|
+
* With neither date the record runs from 2012-01-01 to today, and
|
|
1502
|
+
* `instrument` defaults to `"all"`.
|
|
1503
|
+
*/
|
|
1504
|
+
async getCongressionalFiler(filerKey, options = {}) {
|
|
1505
|
+
return readPublicApi(this.transport, `political-disclosures/filers/${encodePathSegment(filerKey)}${encodeQuery(congressionalQueryParams(options))}`);
|
|
1506
|
+
}
|
|
1507
|
+
/** One disclosure with its amendment history. Requires an API key. */
|
|
1508
|
+
async getCongressionalTrade(eventId, options = {}) {
|
|
1509
|
+
return readPublicApi(this.transport, `political-disclosures/trades/${encodePathSegment(eventId)}${encodeQuery({
|
|
1510
|
+
asOf: options.asOf,
|
|
1511
|
+
})}`);
|
|
1512
|
+
}
|
|
1513
|
+
/** One source filing and every trade it disclosed. Requires an API key. */
|
|
1514
|
+
async getCongressionalFiling(chamber, docId) {
|
|
1515
|
+
return readPublicApi(this.transport, `political-disclosures/filings/${encodePathSegment(chamber)}/${encodePathSegment(docId)}`);
|
|
1516
|
+
}
|
|
1517
|
+
/** How much of the public record the dataset holds. Requires an API key. */
|
|
1518
|
+
async getCongressionalCoverage() {
|
|
1519
|
+
return readPublicApi(this.transport, "political-disclosures/coverage");
|
|
1520
|
+
}
|
|
1424
1521
|
/** Resolve once a backtest is terminal. See `waitForOperation`. */
|
|
1425
1522
|
async waitForBacktest(backtestId, options = {}) {
|
|
1426
1523
|
return waitForOperation((id) => this.getBacktest(id), backtestId, options);
|
|
@@ -0,0 +1,390 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Congressional (STOCK Act) disclosure types for the public REST API at
|
|
3
|
+
* `/api/political-disclosures`.
|
|
4
|
+
*
|
|
5
|
+
* `availableAt` is when a disclosure became public. It is the only date a
|
|
6
|
+
* strategy may act on: `transactionDate` is when the member traded, typically
|
|
7
|
+
* weeks before anyone outside Congress could know. Date filters and `sort` use
|
|
8
|
+
* `firstAvailableAt`, when the first version of a disclosure became public.
|
|
9
|
+
*/
|
|
10
|
+
export type CongressChamber = "house" | "senate";
|
|
11
|
+
export type CongressAction = "purchase" | "sale" | "exchange" | "unmarked";
|
|
12
|
+
export type CongressInstrument = "equity" | "option" | "fund" | "bond" | "other";
|
|
13
|
+
export type CongressOwner = "self" | "spouse" | "dependent_child" | "joint" | "not_indicated";
|
|
14
|
+
export type CongressParty = "Democrat" | "Republican" | "Independent" | "Other";
|
|
15
|
+
export type CongressParseMethod = "text" | "scan" | "html" | "paper";
|
|
16
|
+
export type CongressSort = "newest" | "oldest";
|
|
17
|
+
/**
|
|
18
|
+
* Filters shared by the trade feed and its aggregates.
|
|
19
|
+
*
|
|
20
|
+
* `toDate` defaults to the day of `asOf`, which defaults to the dataset's last
|
|
21
|
+
* update. With no `fromDate` the window is the 30 days ending at `toDate`.
|
|
22
|
+
* `instrument` defaults to `"equity"`; pass `"all"` to include options, funds
|
|
23
|
+
* and bonds.
|
|
24
|
+
*/
|
|
25
|
+
export interface CongressionalTradeFilters {
|
|
26
|
+
/** Free-text search. A phrase naming exactly one member resolves to that member. */
|
|
27
|
+
q?: string;
|
|
28
|
+
/** Bioguide ID, for example `"P000197"`. */
|
|
29
|
+
filerKey?: string;
|
|
30
|
+
ticker?: string;
|
|
31
|
+
chamber?: CongressChamber | "all";
|
|
32
|
+
action?: CongressAction | "all";
|
|
33
|
+
instrument?: CongressInstrument | "all";
|
|
34
|
+
/** `YYYY-MM-DD`, compared against the day of `firstAvailableAt`. Sent as `from`. */
|
|
35
|
+
fromDate?: string;
|
|
36
|
+
/** `YYYY-MM-DD`, compared against the day of `firstAvailableAt`. Sent as `to`. */
|
|
37
|
+
toDate?: string;
|
|
38
|
+
/** ISO timestamp. Reads the record as it was publicly known at that instant. */
|
|
39
|
+
asOf?: string;
|
|
40
|
+
}
|
|
41
|
+
/** The trade feed: the shared filters plus ordering and paging. */
|
|
42
|
+
export interface ListCongressionalTradesOptions extends CongressionalTradeFilters {
|
|
43
|
+
/** Orders by `firstAvailableAt`. Default `"newest"`. */
|
|
44
|
+
sort?: CongressSort;
|
|
45
|
+
/** `nextCursor` from the previous page, sent with the same filters. */
|
|
46
|
+
cursor?: string;
|
|
47
|
+
/** 1 to 100. Default 25. */
|
|
48
|
+
limit?: number;
|
|
49
|
+
}
|
|
50
|
+
/** The per-member lists (filers, filing latency, volume). Each has a fixed order. */
|
|
51
|
+
export interface CongressionalFilerListOptions extends CongressionalTradeFilters {
|
|
52
|
+
/** 1 to 100. Default 25. */
|
|
53
|
+
limit?: number;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* One member's record, for `getPolitician` and `getCongressionalFiler`.
|
|
57
|
+
*
|
|
58
|
+
* With neither date the record runs from 2012-01-01 to today. With only one,
|
|
59
|
+
* the other takes the feed default. `instrument` defaults to `"all"`.
|
|
60
|
+
*/
|
|
61
|
+
export interface CongressionalMemberRecordOptions {
|
|
62
|
+
ticker?: string;
|
|
63
|
+
action?: CongressAction | "all";
|
|
64
|
+
instrument?: CongressInstrument | "all";
|
|
65
|
+
/** Orders the trades by `firstAvailableAt`. Default `"newest"`. */
|
|
66
|
+
sort?: CongressSort;
|
|
67
|
+
/** `YYYY-MM-DD`, compared against the day of `firstAvailableAt`. Sent as `from`. */
|
|
68
|
+
fromDate?: string;
|
|
69
|
+
/** `YYYY-MM-DD`, compared against the day of `firstAvailableAt`. Sent as `to`. */
|
|
70
|
+
toDate?: string;
|
|
71
|
+
/** ISO timestamp. Reads the record as it was publicly known at that instant. */
|
|
72
|
+
asOf?: string;
|
|
73
|
+
/** `recentTradesNextCursor` from the previous page, sent with the same filters. */
|
|
74
|
+
cursor?: string;
|
|
75
|
+
/** Trades per page, 1 to 100. Default 25. */
|
|
76
|
+
limit?: number;
|
|
77
|
+
}
|
|
78
|
+
/** The filters the server applied, defaults included. */
|
|
79
|
+
export interface CongressionalAppliedFilters {
|
|
80
|
+
q: string | null;
|
|
81
|
+
filerKey: string | null;
|
|
82
|
+
ticker: string | null;
|
|
83
|
+
chamber: CongressChamber | "all";
|
|
84
|
+
action: CongressAction | "all";
|
|
85
|
+
instrument: CongressInstrument | "all";
|
|
86
|
+
sort: CongressSort;
|
|
87
|
+
from: string;
|
|
88
|
+
to: string;
|
|
89
|
+
asOf: string;
|
|
90
|
+
cursor: string | null;
|
|
91
|
+
limit: number;
|
|
92
|
+
}
|
|
93
|
+
export interface CongressionalCoverage {
|
|
94
|
+
filings: number;
|
|
95
|
+
events: number;
|
|
96
|
+
failedFilings: number;
|
|
97
|
+
latestAvailableAt: string | null;
|
|
98
|
+
latestProcessedAt: string | null;
|
|
99
|
+
byChamber: Record<CongressChamber, {
|
|
100
|
+
filings: number | null;
|
|
101
|
+
latestFilingDate: string | null;
|
|
102
|
+
}>;
|
|
103
|
+
}
|
|
104
|
+
/** Every disclosure read except the leaderboard and the copy bot. */
|
|
105
|
+
export interface CongressionalEnvelope<T> {
|
|
106
|
+
data: T;
|
|
107
|
+
snapshotId: string;
|
|
108
|
+
asOf: string;
|
|
109
|
+
dataUpdatedAt: string;
|
|
110
|
+
stale: boolean;
|
|
111
|
+
cache: "hit" | "miss" | "stale";
|
|
112
|
+
coverage: CongressionalCoverage | null;
|
|
113
|
+
filters: CongressionalAppliedFilters | null;
|
|
114
|
+
}
|
|
115
|
+
export interface CongressionalTrade {
|
|
116
|
+
/** `<chamber>:<docId>:<rowIndex>`, for example `"house:20035831:0"`. */
|
|
117
|
+
eventId: string;
|
|
118
|
+
version: number;
|
|
119
|
+
filerKey: string;
|
|
120
|
+
filerName: string;
|
|
121
|
+
chamber: CongressChamber;
|
|
122
|
+
owner: CongressOwner;
|
|
123
|
+
action: CongressAction;
|
|
124
|
+
partialSale: boolean;
|
|
125
|
+
instrument: CongressInstrument;
|
|
126
|
+
/** When the member traded. Not public knowledge on this date. */
|
|
127
|
+
transactionDate: string | null;
|
|
128
|
+
filingDate: string;
|
|
129
|
+
/** When the first version became public. `from`, `to` and `sort` use this. */
|
|
130
|
+
firstAvailableAt: string;
|
|
131
|
+
/** When this version became public. The date to trade from. */
|
|
132
|
+
availableAt: string;
|
|
133
|
+
supersededAt: string | null;
|
|
134
|
+
ticker: string | null;
|
|
135
|
+
assetDescription: string;
|
|
136
|
+
assetTypeCode: string | null;
|
|
137
|
+
assetTypeLabel: string | null;
|
|
138
|
+
/** Disclosures report a bracket, never an amount. */
|
|
139
|
+
amountBracket: string | null;
|
|
140
|
+
amountLow: number | null;
|
|
141
|
+
amountHigh: number | null;
|
|
142
|
+
tickerResolutionStatus: string | null;
|
|
143
|
+
sourceDocId: string;
|
|
144
|
+
sourceRowIndex: number;
|
|
145
|
+
sourceUrl: string;
|
|
146
|
+
/** `"scan"` and `"paper"` rows were read from an image. */
|
|
147
|
+
sourceParseMethod: CongressParseMethod | null;
|
|
148
|
+
}
|
|
149
|
+
export interface CongressMemberBadge {
|
|
150
|
+
party: CongressParty | null;
|
|
151
|
+
state: string | null;
|
|
152
|
+
slug: string;
|
|
153
|
+
}
|
|
154
|
+
export interface CongressionalTradePage {
|
|
155
|
+
trades: CongressionalTrade[];
|
|
156
|
+
/** Pass as `cursor` with the same filters; null on the last page. */
|
|
157
|
+
nextCursor: string | null;
|
|
158
|
+
/** `filerKey` to badge, for the members on this page. */
|
|
159
|
+
members?: Record<string, CongressMemberBadge>;
|
|
160
|
+
}
|
|
161
|
+
export interface CongressionalVolumeRank {
|
|
162
|
+
ticker: string;
|
|
163
|
+
events: number;
|
|
164
|
+
amountLow: number | null;
|
|
165
|
+
amountHigh: number | null;
|
|
166
|
+
}
|
|
167
|
+
export interface CongressionalTradeSummary {
|
|
168
|
+
purchaseEvents: number;
|
|
169
|
+
saleEvents: number;
|
|
170
|
+
otherEvents: number;
|
|
171
|
+
activeFilers: number;
|
|
172
|
+
disclosedEvents: number;
|
|
173
|
+
purchaseAmountLow: number | null;
|
|
174
|
+
purchaseAmountHigh: number | null;
|
|
175
|
+
purchaseMissingLow: number;
|
|
176
|
+
purchaseMissingHigh: number;
|
|
177
|
+
saleAmountLow: number | null;
|
|
178
|
+
saleAmountHigh: number | null;
|
|
179
|
+
saleMissingLow: number;
|
|
180
|
+
saleMissingHigh: number;
|
|
181
|
+
netAmountLow: number | null;
|
|
182
|
+
netAmountHigh: number | null;
|
|
183
|
+
unresolvedTickerEvents: number;
|
|
184
|
+
mostPurchased: Array<{
|
|
185
|
+
ticker: string;
|
|
186
|
+
events: number;
|
|
187
|
+
}>;
|
|
188
|
+
mostPurchasedByVolume?: CongressionalVolumeRank[];
|
|
189
|
+
}
|
|
190
|
+
export interface CongressionalFiler {
|
|
191
|
+
filerKey: string;
|
|
192
|
+
displayName: string;
|
|
193
|
+
chamber: CongressChamber;
|
|
194
|
+
disclosureEvents: number;
|
|
195
|
+
purchaseEvents: number;
|
|
196
|
+
saleEvents: number;
|
|
197
|
+
latestDisclosureAt: string | null;
|
|
198
|
+
identityStatus: "member";
|
|
199
|
+
}
|
|
200
|
+
export interface CongressionalFilerYearActivity {
|
|
201
|
+
year: number;
|
|
202
|
+
purchases: number;
|
|
203
|
+
sales: number;
|
|
204
|
+
purchaseMidpoint: number | null;
|
|
205
|
+
saleMidpoint: number | null;
|
|
206
|
+
}
|
|
207
|
+
export interface CongressionalFilerActivity {
|
|
208
|
+
byYear: CongressionalFilerYearActivity[];
|
|
209
|
+
firstPublicAt: string | null;
|
|
210
|
+
lastPublicAt: string | null;
|
|
211
|
+
filings: number;
|
|
212
|
+
/** Filings carrying a trade made public more than 45 days after it. */
|
|
213
|
+
lateFilings: number;
|
|
214
|
+
}
|
|
215
|
+
export interface CongressionalFilerDetail {
|
|
216
|
+
filer: CongressionalFiler;
|
|
217
|
+
summary: CongressionalTradeSummary;
|
|
218
|
+
recentTrades: CongressionalTrade[];
|
|
219
|
+
recentTradesNextCursor: string | null;
|
|
220
|
+
activity: CongressionalFilerActivity;
|
|
221
|
+
}
|
|
222
|
+
/** How long one member's disclosures take to become public. */
|
|
223
|
+
export interface CongressionalFilingLatency {
|
|
224
|
+
filerKey: string;
|
|
225
|
+
displayName: string;
|
|
226
|
+
transactions: number;
|
|
227
|
+
filings: number;
|
|
228
|
+
medianDaysToPublic: number | null;
|
|
229
|
+
p95DaysToPublic: number | null;
|
|
230
|
+
transactionsOverFortyFiveDays: number;
|
|
231
|
+
filingsOverFortyFiveDays: number;
|
|
232
|
+
}
|
|
233
|
+
/** One member's disclosed dollars, as sums of bracket bounds. */
|
|
234
|
+
export interface CongressionalFilerVolume {
|
|
235
|
+
filerKey: string;
|
|
236
|
+
displayName: string;
|
|
237
|
+
transactions: number;
|
|
238
|
+
purchaseTransactions: number;
|
|
239
|
+
saleTransactions: number;
|
|
240
|
+
filings: number;
|
|
241
|
+
volumeLow: number;
|
|
242
|
+
/** Null when any bracket is open-ended. */
|
|
243
|
+
volumeHigh: number | null;
|
|
244
|
+
volumeMidpoint: number;
|
|
245
|
+
openEndedTransactions: number;
|
|
246
|
+
party?: CongressParty | null;
|
|
247
|
+
state?: string | null;
|
|
248
|
+
slug?: string | null;
|
|
249
|
+
}
|
|
250
|
+
export interface CongressCommitteeAssignment {
|
|
251
|
+
id: string;
|
|
252
|
+
name: string;
|
|
253
|
+
title: string | null;
|
|
254
|
+
}
|
|
255
|
+
export interface Politician {
|
|
256
|
+
/** Bioguide ID. */
|
|
257
|
+
memberId: string;
|
|
258
|
+
slug: string;
|
|
259
|
+
displayName: string;
|
|
260
|
+
party: CongressParty | null;
|
|
261
|
+
committees: CongressCommitteeAssignment[];
|
|
262
|
+
imageUrl: string | null;
|
|
263
|
+
chamber: CongressChamber | null;
|
|
264
|
+
state: string | null;
|
|
265
|
+
district: number | null;
|
|
266
|
+
firstTookOffice: string | null;
|
|
267
|
+
lastServedEnd: string | null;
|
|
268
|
+
}
|
|
269
|
+
export interface PoliticianProfile {
|
|
270
|
+
politician: Politician;
|
|
271
|
+
profile: CongressionalFilerDetail;
|
|
272
|
+
}
|
|
273
|
+
export interface PoliticianBotStatistics {
|
|
274
|
+
totalReturn: number;
|
|
275
|
+
cagr: number | null;
|
|
276
|
+
fiveYearEquivalent: number | null;
|
|
277
|
+
spyTotalReturn: number | null;
|
|
278
|
+
spyCagr: number | null;
|
|
279
|
+
spyFiveYearEquivalent: number | null;
|
|
280
|
+
sharpe: number | null;
|
|
281
|
+
sortino: number | null;
|
|
282
|
+
maxDrawdown: number | null;
|
|
283
|
+
closedTrades: number | null;
|
|
284
|
+
fees: number | null;
|
|
285
|
+
medianDeployment: number | null;
|
|
286
|
+
distinctNames: number | null;
|
|
287
|
+
}
|
|
288
|
+
export interface PoliticianBotCurvePoint {
|
|
289
|
+
date: string;
|
|
290
|
+
value: number;
|
|
291
|
+
performanceValue?: number;
|
|
292
|
+
spy: number | null;
|
|
293
|
+
}
|
|
294
|
+
/** A member's copy bot: a cached engine backtest of following their disclosures. */
|
|
295
|
+
export interface PoliticianBot {
|
|
296
|
+
status: "ready" | "stale" | "computing" | "ineligible";
|
|
297
|
+
memberId: string;
|
|
298
|
+
displayName: string | null;
|
|
299
|
+
purchaseCount: number | null;
|
|
300
|
+
minPurchases: number;
|
|
301
|
+
profileId: string | null;
|
|
302
|
+
/** Pass to `forkPublicPortfolio` to copy the bot into your workspace. */
|
|
303
|
+
sharedPortfolioId: string | null;
|
|
304
|
+
windowStart: string | null;
|
|
305
|
+
windowEnd: string | null;
|
|
306
|
+
refreshedAt: string | null;
|
|
307
|
+
refreshRequestedAt: string | null;
|
|
308
|
+
refreshPending: boolean;
|
|
309
|
+
initialValue: number;
|
|
310
|
+
statistics: PoliticianBotStatistics | null;
|
|
311
|
+
curve: PoliticianBotCurvePoint[];
|
|
312
|
+
mixed: boolean;
|
|
313
|
+
}
|
|
314
|
+
export interface CongressionalLeaderboardRow {
|
|
315
|
+
memberId: string;
|
|
316
|
+
displayName: string;
|
|
317
|
+
slug: string | null;
|
|
318
|
+
party: CongressParty | null;
|
|
319
|
+
chamber: CongressChamber | null;
|
|
320
|
+
state: string | null;
|
|
321
|
+
windowStart: string;
|
|
322
|
+
windowEnd: string;
|
|
323
|
+
mixed: boolean;
|
|
324
|
+
totalReturn: number;
|
|
325
|
+
spyTotalReturn: number;
|
|
326
|
+
/** `totalReturn` minus `spyTotalReturn`. */
|
|
327
|
+
excessReturn: number;
|
|
328
|
+
/** `(1 + cagr)^5 - 1`, the ranking basis. */
|
|
329
|
+
fiveYearEquivalent: number | null;
|
|
330
|
+
sharpe: number | null;
|
|
331
|
+
maxDrawdown: number | null;
|
|
332
|
+
purchaseCount: number;
|
|
333
|
+
imageUrl: string | null;
|
|
334
|
+
lastServedEnd: string | null;
|
|
335
|
+
spark: {
|
|
336
|
+
bot: number[];
|
|
337
|
+
spy: Array<number | null>;
|
|
338
|
+
} | null;
|
|
339
|
+
}
|
|
340
|
+
export interface CongressionalLeaderboard {
|
|
341
|
+
/** Members whose copy bot beat SPY, best first. */
|
|
342
|
+
best: CongressionalLeaderboardRow[];
|
|
343
|
+
featured: {
|
|
344
|
+
memberId: string;
|
|
345
|
+
initialValue: number;
|
|
346
|
+
windowEnd: string;
|
|
347
|
+
curve: PoliticianBotCurvePoint[];
|
|
348
|
+
} | null;
|
|
349
|
+
/** Members whose copy bot trailed SPY, worst first. */
|
|
350
|
+
worst: CongressionalLeaderboardRow[];
|
|
351
|
+
byParty: Array<{
|
|
352
|
+
party: CongressParty | "Unknown";
|
|
353
|
+
members: number;
|
|
354
|
+
meanExcessReturn: number;
|
|
355
|
+
}>;
|
|
356
|
+
basis: {
|
|
357
|
+
rankedMembers: number;
|
|
358
|
+
beatSpy: number;
|
|
359
|
+
meanExcessReturn: number | null;
|
|
360
|
+
minPurchases: number;
|
|
361
|
+
minWindowDays: number;
|
|
362
|
+
benchmark: "SPY";
|
|
363
|
+
/** Starting capital of every ranked book. */
|
|
364
|
+
initialValue: number;
|
|
365
|
+
refreshedAt: string | null;
|
|
366
|
+
minPartyMembers: number;
|
|
367
|
+
};
|
|
368
|
+
}
|
|
369
|
+
export interface CongressionalTradeDetail {
|
|
370
|
+
current: CongressionalTrade;
|
|
371
|
+
/** Every version of the disclosure public as of the read, amendments included. */
|
|
372
|
+
history: CongressionalTrade[];
|
|
373
|
+
}
|
|
374
|
+
export interface CongressionalFiling {
|
|
375
|
+
chamber: CongressChamber;
|
|
376
|
+
docId: string;
|
|
377
|
+
filerKey: string | null;
|
|
378
|
+
filerName: string;
|
|
379
|
+
stateDistrict: string | null;
|
|
380
|
+
filingDate: string;
|
|
381
|
+
availableAt: string;
|
|
382
|
+
sourceUrl: string;
|
|
383
|
+
extractionStatus: "ok" | "failed" | "unsupported";
|
|
384
|
+
extractedRows: number;
|
|
385
|
+
amendedReportDate: string | null;
|
|
386
|
+
reportDate: string | null;
|
|
387
|
+
trades: CongressionalTrade[];
|
|
388
|
+
}
|
|
389
|
+
/** Query pairs in one fixed order, so both SDKs put the same bytes on the wire. */
|
|
390
|
+
export declare function congressionalQueryParams(options: ListCongressionalTradesOptions): Record<string, string | undefined>;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Congressional (STOCK Act) disclosure types for the public REST API at
|
|
3
|
+
* `/api/political-disclosures`.
|
|
4
|
+
*
|
|
5
|
+
* `availableAt` is when a disclosure became public. It is the only date a
|
|
6
|
+
* strategy may act on: `transactionDate` is when the member traded, typically
|
|
7
|
+
* weeks before anyone outside Congress could know. Date filters and `sort` use
|
|
8
|
+
* `firstAvailableAt`, when the first version of a disclosure became public.
|
|
9
|
+
*/
|
|
10
|
+
/** Query pairs in one fixed order, so both SDKs put the same bytes on the wire. */
|
|
11
|
+
export function congressionalQueryParams(options) {
|
|
12
|
+
return {
|
|
13
|
+
q: options.q,
|
|
14
|
+
filerKey: options.filerKey,
|
|
15
|
+
ticker: options.ticker,
|
|
16
|
+
chamber: options.chamber,
|
|
17
|
+
action: options.action,
|
|
18
|
+
instrument: options.instrument,
|
|
19
|
+
sort: options.sort,
|
|
20
|
+
from: options.fromDate,
|
|
21
|
+
to: options.toDate,
|
|
22
|
+
asOf: options.asOf,
|
|
23
|
+
cursor: options.cursor,
|
|
24
|
+
limit: options.limit === undefined ? undefined : String(options.limit),
|
|
25
|
+
};
|
|
26
|
+
}
|