nexustrade 5.3.0 → 5.4.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 CHANGED
@@ -140,6 +140,27 @@ A cached single-name spec that omitted the baseline therefore runs once more
140
140
  after upgrading, because its benchmark is now part of the run's identity. The
141
141
  portfolio handle accepts the same typed benchmark: `PortfolioHandle.backtest({ baselineAsset })`.
142
142
 
143
+ ### Equity curve and fills
144
+
145
+ The terminal `result.statistics` carries the aggregates (`percentChange`,
146
+ `sharpeRatio`, `maxDrawdown`, `winRate`, `closedTradeCount`, `totalFees`).
147
+ The curve and the individual fills are separate reads:
148
+
149
+ ```typescript
150
+ const curve = await client.getBacktestHistory(backtestId, { pageSize: 5000 });
151
+ // curve.points: time, value, cash, positionValue, comparisonValue, reservedCollateral
152
+ // follow curve.nextPage until null
153
+
154
+ const fills = await client.listBacktestEvents(backtestId, {
155
+ eventTypes: ["Order"],
156
+ orderStatuses: ["Filled"],
157
+ });
158
+ ```
159
+
160
+ History is retained for 30 days. Events exist only for a run submitted with
161
+ `generateEvents: true` and are retained for 3 days; otherwise the call raises
162
+ `events_unavailable`.
163
+
143
164
  ### Collateral at risk
144
165
 
145
166
  A terminal operation's `result.statistics` answers how much capital the run had
@@ -978,6 +999,8 @@ is missing here, so this list cannot drift from the code.
978
999
  | `getBacktest(backtestId)` | Read the operation |
979
1000
  | `waitForBacktest(backtestId, options)` | Block until terminal |
980
1001
  | `waitForBacktests(operations, options)` | Block on a whole batch |
1002
+ | `getBacktestHistory(backtestId, options)` | Equity curve, one page |
1003
+ | `listBacktestEvents(backtestId, options)` | Orders, fills and signals |
981
1004
 
982
1005
  **Optimization and walk-forward**
983
1006
 
@@ -1416,6 +1416,29 @@ class NexusTradeClient {
1416
1416
  const response = await this.transport.request("GET", `backtests/${encodePathSegment(backtestId)}`);
1417
1417
  return operationOf(response);
1418
1418
  }
1419
+ /** One page of a completed backtest's equity curve; follow `nextPage` until null. */
1420
+ async getBacktestHistory(backtestId, options = {}) {
1421
+ const query = encodeQuery({
1422
+ page: options.page === undefined ? undefined : String(options.page),
1423
+ page_size: options.pageSize === undefined ? undefined : String(options.pageSize),
1424
+ start_date: options.startDate,
1425
+ end_date: options.endDate,
1426
+ });
1427
+ return this.transport.request("GET", `backtests/${encodePathSegment(backtestId)}/history${query}`);
1428
+ }
1429
+ /** One page of a backtest's event tape. The run needs `generateEvents: true`; traces last 3 days. */
1430
+ async listBacktestEvents(backtestId, options = {}) {
1431
+ const query = encodeQuery({
1432
+ event_types: options.eventTypes?.join(","),
1433
+ order_statuses: options.orderStatuses?.join(","),
1434
+ ticker: options.ticker,
1435
+ start_date: options.startDate,
1436
+ end_date: options.endDate,
1437
+ page: options.page === undefined ? undefined : String(options.page),
1438
+ page_size: options.pageSize === undefined ? undefined : String(options.pageSize),
1439
+ });
1440
+ return this.transport.request("GET", `backtests/${encodePathSegment(backtestId)}/events${query}`);
1441
+ }
1419
1442
  /** Requires a registered API key; anonymous workspaces cannot optimize. */
1420
1443
  async createOptimization(handle, options) {
1421
1444
  return this.createPortfolioJob("optimizations", handle, options.idempotencyKey);
@@ -428,7 +428,7 @@ const updateInsiderWatchlist = (config) => ({
428
428
  type: "UpdateWatchlist", watchlistKey: config.watchlistKey,
429
429
  ...(config.output ? { output: config.output } : {}),
430
430
  source: compact({ type: "InsiderPurchases", windowDays: config.windowDays, role: config.role,
431
- ownerCik: config.ownerCik, issuerCik: config.issuerCik }),
431
+ ownerCik: config.ownerCik, issuerCik: config.issuerCik, includeAwards: config.includeAwards }),
432
432
  });
433
433
  exports.updateInsiderWatchlist = updateInsiderWatchlist;
434
434
  /** Scalar PIT screen: facts are sampled only when due. Volume uses certified completed historical OHLC at the replay interval; live quote/trade volume stays unknown. */
@@ -1256,7 +1256,7 @@ function InitialValue() {
1256
1256
  * @param asset Pass CANDIDATE in a dynamic rebalance pipeline.
1257
1257
  * @param ownerCik Exact nonzero SEC reporting owner CIK, up to 10 digits. Omit for a whole company (with issuerCik) or aggregate activity.
1258
1258
  * @param issuerCik Company CIK. With ownerCik, restricts that owner to this company. Alone, every reporting owner's events at this company, a joint filing counted once.
1259
- * @param instrument Disclosed instrument; defaults to Equity. Call/Put, award and acquisition metrics, and budget shares require ownerCik or issuerCik. AwardCount is SEC code A issuer acquisitions, not cash purchases or vested-share proof. Its default Equity bucket includes unresolved restricted units. AcquisitionCount and AcquisitionSharePercent combine public code P purchases with code A issuer acquisitions. Shares use qualifying signal counts across all the owner's tickers, or all the company's tickers under issuerCik alone.
1259
+ * @param instrument Disclosed instrument; defaults to Equity. Call/Put, award and acquisition metrics, and budget shares require ownerCik or issuerCik. AwardCount is SEC code A issuer acquisitions, not cash purchases or vested-share proof. AcquisitionValue is disclosed purchase dollars plus award shares at the target's current price. Its default Equity bucket includes unresolved restricted units. AcquisitionCount and AcquisitionSharePercent combine public code P purchases with code A issuer acquisitions. Shares use qualifying signal counts across all the owner's tickers, or all the company's tickers under issuerCik alone.
1260
1260
  */
1261
1261
  function InsiderTrades(asset, metric, role, windowDays, ownerCik, issuerCik, instrument) {
1262
1262
  const d = { type: "InsiderTrades" };
@@ -2448,18 +2448,18 @@ const geneEntryCooldownDays = (strategyIndex, values) => ({
2448
2448
  });
2449
2449
  exports.geneEntryCooldownDays = geneEntryCooldownDays;
2450
2450
  /** Sweep ConditionWindowLength (Strategy scope) over a value set. */
2451
- const geneConditionWindowLength = (strategyIndex, path, slot, values) => ({
2451
+ const geneConditionWindowLength = (strategyIndex, path, slot, values, indicatorPath) => ({
2452
2452
  field: "ConditionWindowLength",
2453
2453
  scope: "Strategy",
2454
- target: { scope: "Strategy", field: "ConditionWindowLength", strategyIndex, path, slot },
2454
+ target: { scope: "Strategy", field: "ConditionWindowLength", strategyIndex, path, slot, ...(indicatorPath === undefined ? {} : { indicatorPath }) },
2455
2455
  values: values,
2456
2456
  });
2457
2457
  exports.geneConditionWindowLength = geneConditionWindowLength;
2458
2458
  /** Sweep ConditionThreshold (Strategy scope) over a value set. */
2459
- const geneConditionThreshold = (strategyIndex, path, slot, values) => ({
2459
+ const geneConditionThreshold = (strategyIndex, path, slot, values, indicatorPath, parameter) => ({
2460
2460
  field: "ConditionThreshold",
2461
2461
  scope: "Strategy",
2462
- target: { scope: "Strategy", field: "ConditionThreshold", strategyIndex, path, slot },
2462
+ target: { scope: "Strategy", field: "ConditionThreshold", strategyIndex, path, slot, ...(indicatorPath === undefined ? {} : { indicatorPath }), ...(parameter === undefined ? {} : { parameter }) },
2463
2463
  values: values,
2464
2464
  });
2465
2465
  exports.geneConditionThreshold = geneConditionThreshold;
@@ -89,6 +89,24 @@ export interface ListOrdersOptions {
89
89
  limit?: number;
90
90
  includeRebalanceOrders?: boolean;
91
91
  }
92
+ export interface BacktestHistoryOptions {
93
+ page?: number;
94
+ /** Rows per page, at most 5000 (server default 500). */
95
+ pageSize?: number;
96
+ startDate?: string;
97
+ endDate?: string;
98
+ }
99
+ export interface ListBacktestEventsOptions {
100
+ /** e.g. ["Order"]. Omit for every actionable event. */
101
+ eventTypes?: ReadonlyArray<string>;
102
+ /** Order events only, e.g. ["Filled"]. */
103
+ orderStatuses?: ReadonlyArray<string>;
104
+ ticker?: string;
105
+ startDate?: string;
106
+ endDate?: string;
107
+ page?: number;
108
+ pageSize?: number;
109
+ }
92
110
  export interface ListPortfoliosOptions {
93
111
  portfolioIds?: string[];
94
112
  includeInactive?: boolean;
@@ -466,6 +484,10 @@ export declare class NexusTradeClient {
466
484
  }): Promise<AgentRun>;
467
485
  getAgent(agentId: string): Promise<JsonObject>;
468
486
  getBacktest(backtestId: string): Promise<JsonObject>;
487
+ /** One page of a completed backtest's equity curve; follow `nextPage` until null. */
488
+ getBacktestHistory(backtestId: string, options?: BacktestHistoryOptions): Promise<JsonObject>;
489
+ /** One page of a backtest's event tape. The run needs `generateEvents: true`; traces last 3 days. */
490
+ listBacktestEvents(backtestId: string, options?: ListBacktestEventsOptions): Promise<JsonObject>;
469
491
  /** Requires a registered API key; anonymous workspaces cannot optimize. */
470
492
  createOptimization(handle: JobInput, options: {
471
493
  idempotencyKey: string;
@@ -1406,6 +1406,29 @@ export class NexusTradeClient {
1406
1406
  const response = await this.transport.request("GET", `backtests/${encodePathSegment(backtestId)}`);
1407
1407
  return operationOf(response);
1408
1408
  }
1409
+ /** One page of a completed backtest's equity curve; follow `nextPage` until null. */
1410
+ async getBacktestHistory(backtestId, options = {}) {
1411
+ const query = encodeQuery({
1412
+ page: options.page === undefined ? undefined : String(options.page),
1413
+ page_size: options.pageSize === undefined ? undefined : String(options.pageSize),
1414
+ start_date: options.startDate,
1415
+ end_date: options.endDate,
1416
+ });
1417
+ return this.transport.request("GET", `backtests/${encodePathSegment(backtestId)}/history${query}`);
1418
+ }
1419
+ /** One page of a backtest's event tape. The run needs `generateEvents: true`; traces last 3 days. */
1420
+ async listBacktestEvents(backtestId, options = {}) {
1421
+ const query = encodeQuery({
1422
+ event_types: options.eventTypes?.join(","),
1423
+ order_statuses: options.orderStatuses?.join(","),
1424
+ ticker: options.ticker,
1425
+ start_date: options.startDate,
1426
+ end_date: options.endDate,
1427
+ page: options.page === undefined ? undefined : String(options.page),
1428
+ page_size: options.pageSize === undefined ? undefined : String(options.pageSize),
1429
+ });
1430
+ return this.transport.request("GET", `backtests/${encodePathSegment(backtestId)}/events${query}`);
1431
+ }
1409
1432
  /** Requires a registered API key; anonymous workspaces cannot optimize. */
1410
1433
  async createOptimization(handle, options) {
1411
1434
  return this.createPortfolioJob("optimizations", handle, options.idempotencyKey);
@@ -313,6 +313,7 @@ export type DisclosureWatchlistSource = {
313
313
  role?: "Any" | "Officer" | "Director" | "TenPercentOwner" | "OfficerOrDirector";
314
314
  ownerCik?: string;
315
315
  issuerCik?: string;
316
+ includeAwards?: boolean;
316
317
  };
317
318
  export type ScreenMetric = {
318
319
  type: "ObservedPrice" | "BarVolume" | "BarDollarVolume";
@@ -758,6 +759,7 @@ export declare const updateInsiderWatchlist: (config: {
758
759
  role?: "Any" | "Officer" | "Director" | "TenPercentOwner" | "OfficerOrDirector";
759
760
  ownerCik?: string;
760
761
  issuerCik?: string;
762
+ includeAwards?: boolean;
761
763
  output?: UpdateWatchlistAction["output"];
762
764
  }) => UpdateWatchlistAction & {
763
765
  source: Extract<DisclosureWatchlistSource, {
@@ -1269,9 +1271,9 @@ export declare function InitialValue(): Indicator;
1269
1271
  * @param asset Pass CANDIDATE in a dynamic rebalance pipeline.
1270
1272
  * @param ownerCik Exact nonzero SEC reporting owner CIK, up to 10 digits. Omit for a whole company (with issuerCik) or aggregate activity.
1271
1273
  * @param issuerCik Company CIK. With ownerCik, restricts that owner to this company. Alone, every reporting owner's events at this company, a joint filing counted once.
1272
- * @param instrument Disclosed instrument; defaults to Equity. Call/Put, award and acquisition metrics, and budget shares require ownerCik or issuerCik. AwardCount is SEC code A issuer acquisitions, not cash purchases or vested-share proof. Its default Equity bucket includes unresolved restricted units. AcquisitionCount and AcquisitionSharePercent combine public code P purchases with code A issuer acquisitions. Shares use qualifying signal counts across all the owner's tickers, or all the company's tickers under issuerCik alone.
1274
+ * @param instrument Disclosed instrument; defaults to Equity. Call/Put, award and acquisition metrics, and budget shares require ownerCik or issuerCik. AwardCount is SEC code A issuer acquisitions, not cash purchases or vested-share proof. AcquisitionValue is disclosed purchase dollars plus award shares at the target's current price. Its default Equity bucket includes unresolved restricted units. AcquisitionCount and AcquisitionSharePercent combine public code P purchases with code A issuer acquisitions. Shares use qualifying signal counts across all the owner's tickers, or all the company's tickers under issuerCik alone.
1273
1275
  */
1274
- export declare function InsiderTrades(asset: AssetArg, metric: "NetValue" | "BuyValue" | "SellValue" | "NetShares" | "BuyCount" | "SellCount" | "AwardCount" | "AcquisitionCount" | "DistinctBuyers" | "PurchaseSharePercent" | "AcquisitionSharePercent", role: Role, windowDays: number, ownerCik?: string, issuerCik?: string, instrument?: Instrument): Indicator;
1276
+ export declare function InsiderTrades(asset: AssetArg, metric: "NetValue" | "BuyValue" | "SellValue" | "NetShares" | "BuyCount" | "SellCount" | "AwardCount" | "AcquisitionValue" | "AcquisitionCount" | "DistinctBuyers" | "PurchaseSharePercent" | "AcquisitionSharePercent", role: Role, windowDays: number, ownerCik?: string, issuerCik?: string, instrument?: Instrument): Indicator;
1275
1277
  /**
1276
1278
  * Institutional positions in the asset disclosed on SEC Form 13F. Naming a manager follows one institution; an empty manager reads every manager holding the asset (SDK code passes an empty string). Level metrics read the latest quarter whose filing became public on or before the evaluation date; change metrics compare it with the quarter before. Positions are never summed across quarters, and an amended filing replaces the original only from the moment the amendment became public. Range: Counts, shares, dollars or a top-5 share of holdings; 0 when no 13F naming the asset was public within the window.
1277
1279
  * @param asset Ticker name (ex. SPY, BTC)
@@ -2046,9 +2048,9 @@ export declare const geneReplaceExitCondition: (strategyIndex: number, values: {
2046
2048
  /** Sweep EntryCooldownDays (Strategy scope) over a value set. */
2047
2049
  export declare const geneEntryCooldownDays: (strategyIndex: number, values: number[]) => Gene;
2048
2050
  /** Sweep ConditionWindowLength (Strategy scope) over a value set. */
2049
- export declare const geneConditionWindowLength: (strategyIndex: number, path: number[], slot: ConditionNodeSlot, values: number[]) => Gene;
2051
+ export declare const geneConditionWindowLength: (strategyIndex: number, path: number[], slot: ConditionNodeSlot, values: number[], indicatorPath?: number[]) => Gene;
2050
2052
  /** Sweep ConditionThreshold (Strategy scope) over a value set. */
2051
- export declare const geneConditionThreshold: (strategyIndex: number, path: number[], slot: ConditionNodeSlot, values: number[]) => Gene;
2053
+ export declare const geneConditionThreshold: (strategyIndex: number, path: number[], slot: ConditionNodeSlot, values: number[], indicatorPath?: number[], parameter?: string) => Gene;
2052
2054
  /** Sweep RankSignal (Action scope) over a value set. */
2053
2055
  export declare const geneRankSignal: (strategyIndex: number, values: {
2054
2056
  label: string;
@@ -231,7 +231,7 @@ export const updateInsiderWatchlist = (config) => ({
231
231
  type: "UpdateWatchlist", watchlistKey: config.watchlistKey,
232
232
  ...(config.output ? { output: config.output } : {}),
233
233
  source: compact({ type: "InsiderPurchases", windowDays: config.windowDays, role: config.role,
234
- ownerCik: config.ownerCik, issuerCik: config.issuerCik }),
234
+ ownerCik: config.ownerCik, issuerCik: config.issuerCik, includeAwards: config.includeAwards }),
235
235
  });
236
236
  /** Scalar PIT screen: facts are sampled only when due. Volume uses certified completed historical OHLC at the replay interval; live quote/trade volume stays unknown. */
237
237
  export const updateScreenerWatchlist = (config) => ({
@@ -1024,7 +1024,7 @@ export function InitialValue() {
1024
1024
  * @param asset Pass CANDIDATE in a dynamic rebalance pipeline.
1025
1025
  * @param ownerCik Exact nonzero SEC reporting owner CIK, up to 10 digits. Omit for a whole company (with issuerCik) or aggregate activity.
1026
1026
  * @param issuerCik Company CIK. With ownerCik, restricts that owner to this company. Alone, every reporting owner's events at this company, a joint filing counted once.
1027
- * @param instrument Disclosed instrument; defaults to Equity. Call/Put, award and acquisition metrics, and budget shares require ownerCik or issuerCik. AwardCount is SEC code A issuer acquisitions, not cash purchases or vested-share proof. Its default Equity bucket includes unresolved restricted units. AcquisitionCount and AcquisitionSharePercent combine public code P purchases with code A issuer acquisitions. Shares use qualifying signal counts across all the owner's tickers, or all the company's tickers under issuerCik alone.
1027
+ * @param instrument Disclosed instrument; defaults to Equity. Call/Put, award and acquisition metrics, and budget shares require ownerCik or issuerCik. AwardCount is SEC code A issuer acquisitions, not cash purchases or vested-share proof. AcquisitionValue is disclosed purchase dollars plus award shares at the target's current price. Its default Equity bucket includes unresolved restricted units. AcquisitionCount and AcquisitionSharePercent combine public code P purchases with code A issuer acquisitions. Shares use qualifying signal counts across all the owner's tickers, or all the company's tickers under issuerCik alone.
1028
1028
  */
1029
1029
  export function InsiderTrades(asset, metric, role, windowDays, ownerCik, issuerCik, instrument) {
1030
1030
  const d = { type: "InsiderTrades" };
@@ -2207,17 +2207,17 @@ export const geneEntryCooldownDays = (strategyIndex, values) => ({
2207
2207
  values: values,
2208
2208
  });
2209
2209
  /** Sweep ConditionWindowLength (Strategy scope) over a value set. */
2210
- export const geneConditionWindowLength = (strategyIndex, path, slot, values) => ({
2210
+ export const geneConditionWindowLength = (strategyIndex, path, slot, values, indicatorPath) => ({
2211
2211
  field: "ConditionWindowLength",
2212
2212
  scope: "Strategy",
2213
- target: { scope: "Strategy", field: "ConditionWindowLength", strategyIndex, path, slot },
2213
+ target: { scope: "Strategy", field: "ConditionWindowLength", strategyIndex, path, slot, ...(indicatorPath === undefined ? {} : { indicatorPath }) },
2214
2214
  values: values,
2215
2215
  });
2216
2216
  /** Sweep ConditionThreshold (Strategy scope) over a value set. */
2217
- export const geneConditionThreshold = (strategyIndex, path, slot, values) => ({
2217
+ export const geneConditionThreshold = (strategyIndex, path, slot, values, indicatorPath, parameter) => ({
2218
2218
  field: "ConditionThreshold",
2219
2219
  scope: "Strategy",
2220
- target: { scope: "Strategy", field: "ConditionThreshold", strategyIndex, path, slot },
2220
+ target: { scope: "Strategy", field: "ConditionThreshold", strategyIndex, path, slot, ...(indicatorPath === undefined ? {} : { indicatorPath }), ...(parameter === undefined ? {} : { parameter }) },
2221
2221
  values: values,
2222
2222
  });
2223
2223
  /** Sweep RankSignal (Action scope) over a value set. */
@@ -2,7 +2,7 @@ export { AgentRun } from "./agent.js";
2
2
  export type { AgentEvent, AgentRunOptions } from "./agent.js";
3
3
  export { HttpTransport, NexusTradeApiError, NexusTradeClient, NexusTradeWorkspaceSessionExpiredError, createCustomIndicator, createPortfolio, waitForOperation, } from "./client.js";
4
4
  export type { CongressAction, CongressChamber, CongressCommitteeAssignment, CongressInstrument, CongressMemberBadge, CongressOwner, CongressParseMethod, CongressParty, CongressSort, CongressionalAppliedFilters, CongressionalCoverage, CongressionalEnvelope, CongressionalFiler, CongressionalFilerActivity, CongressionalFilerDetail, CongressionalFilerListOptions, CongressionalFilerVolume, CongressionalFilerYearActivity, CongressionalFiling, CongressionalFilingLatency, CongressionalLeaderboard, CongressionalLeaderboardRow, CongressionalMemberRecordOptions, CongressionalTrade, CongressionalTradeDetail, CongressionalTradeFilters, CongressionalTradePage, CongressionalTradeSummary, CongressionalVolumeRank, ListCongressionalTradesOptions, Politician, PoliticianBot, PoliticianBotCurvePoint, PoliticianBotStatistics, PoliticianProfile, } from "./congress.js";
5
- export type { AddStrategiesOperation, BacktestCollateralStatistics, CustomIndicatorInput, CustomIndicatorPointInput, HttpTransportOptions, JsonObject, JsonValue, ListOrdersOptions, ListPortfoliosOptions, NexusTradeClientOptions, PortfolioEditOperation, UpdatePortfolioOperation, PortfolioRenameOperation, PublicApiTransport, RemoveStrategiesOperation, ReplaceStrategiesOperation, ReplaceStrategyOperation, RequestOptions, Transport, UploadTransport, WaitOptions, WorkspaceSessionTransport, } from "./client.js";
5
+ export type { AddStrategiesOperation, BacktestCollateralStatistics, CustomIndicatorInput, CustomIndicatorPointInput, HttpTransportOptions, JsonObject, JsonValue, ListOrdersOptions, BacktestHistoryOptions, ListBacktestEventsOptions, ListPortfoliosOptions, NexusTradeClientOptions, PortfolioEditOperation, UpdatePortfolioOperation, PortfolioRenameOperation, PublicApiTransport, RemoveStrategiesOperation, ReplaceStrategiesOperation, ReplaceStrategyOperation, RequestOptions, Transport, UploadTransport, WaitOptions, WorkspaceSessionTransport, } from "./client.js";
6
6
  export { PortfolioHandle, portfolioHandleFromWire, } from "./portfolio.js";
7
7
  export type { DeployOutcome, DeployResult, PortfolioHandleOptions, PortfolioListResult, PortfolioType, ReadonlyPortfolioPolicy, } from "./portfolio.js";
8
8
  export * from "./generated/ntSdk.generated.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nexustrade",
3
- "version": "5.3.0",
3
+ "version": "5.4.0",
4
4
  "description": "Typed TypeScript SDK for NexusTrade portfolio authoring, backtesting, optimization, and natural-language stock screening",
5
5
  "license": "MIT",
6
6
  "author": "Starks Technology",