nexustrade 5.1.0 → 5.2.2

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
@@ -119,6 +119,27 @@ Backtest operations may include `warnings: string[]` immediately after
119
119
  submission and again in the terminal `result`. Treat them as material caveats;
120
120
  they do not change a successful operation into a failure.
121
121
 
122
+ ### Benchmark
123
+
124
+ A terminal `result` also carries the benchmark the run was compared against:
125
+ `result.baselineSymbol` and `result.baselineStatistics`, the buy-and-hold
126
+ benchmark's statistics over the same window (for example
127
+ `baselineStatistics.percentChange`). Choose the benchmark with
128
+ `backtest(book, { ..., baselineAsset: { type: "Stock", symbol: "QQQ" } })`, or
129
+ `{ type: "Cryptocurrency", symbol: "BTC-USD" }`. `baselineSymbol` is the older
130
+ Stock-only shorthand; pass one or the other, never both. When both are
131
+ omitted, the single traded stock or option underlying is the benchmark,
132
+ otherwise SPY.
133
+
134
+ Changed in 5.2.0: an omitted baseline used to be SPY for every API backtest.
135
+ It is now inferred exactly as the MCP `backtest_portfolio` tool infers it, and
136
+ an explicit baseline symbol is uppercased. Earlier results were not rerun. A
137
+ new run of the same book can therefore report a different benchmark, so pass
138
+ the baseline explicitly where an earlier comparison must hold.
139
+ A cached single-name spec that omitted the baseline therefore runs once more
140
+ after upgrading, because its benchmark is now part of the run's identity. The
141
+ portfolio handle accepts the same typed benchmark: `PortfolioHandle.backtest({ baselineAsset })`.
142
+
122
143
  ### Collateral at risk
123
144
 
124
145
  A terminal operation's `result.statistics` answers how much capital the run had
@@ -898,6 +919,7 @@ is missing here, so this list cannot drift from the code.
898
919
  | `new NexusTradeClient({ apiKey, baseUrl })` | Explicit credentials |
899
920
  | `new NexusTradeClient()` | Lazy anonymous workspace with strict limits |
900
921
  | `NexusTradeClient.fromEnvironment()` | Read them from the environment or `.env` |
922
+ | `new NexusTradeClient({ requestTimeoutSeconds })` | Per-request HTTP timeout (default 30); also accepted by `fromEnvironment` |
901
923
  | `exportWorkspaceSession()` | Export an anonymous workspace for later use |
902
924
  | `importWorkspaceSession(token)` | Resume an existing anonymous workspace |
903
925
 
@@ -1025,9 +1047,17 @@ check on an otherwise-successful reply.
1025
1047
 
1026
1048
  ## Timeouts
1027
1049
 
1028
- `new HttpTransport({ timeoutSeconds })` (default 30) is a total wall-clock
1029
- deadline for one request. Neither it nor the poll timeout bounds how long a
1030
- _job_ takes.
1050
+ `new NexusTradeClient({ requestTimeoutSeconds })` (default 30) sets the HTTP
1051
+ transport's total wall-clock deadline for one request. Raise it for large
1052
+ `createBacktests` batches:
1053
+
1054
+ ```ts
1055
+ const client = NexusTradeClient.fromEnvironment({ requestTimeoutSeconds: 120 });
1056
+ ```
1057
+
1058
+ It is separate from the `timeoutSeconds` wait option, which bounds how long a
1059
+ poll waits. Neither bounds how long a _job_ takes. A custom `transport`
1060
+ configures its own timeout, so passing both throws.
1031
1061
 
1032
1062
  ## Scope
1033
1063
 
@@ -510,6 +510,7 @@ const BACKTEST_ARG_NAMES = [
510
510
  ["start_date", "startDate"],
511
511
  ["end_date", "endDate"],
512
512
  ["baseline_symbol", "baseline"],
513
+ ["baseline_asset", "baselineAsset"],
513
514
  ["interval", "interval"],
514
515
  ["initial_value", "initialValue"],
515
516
  ["generate_events", "generateEvents"],
@@ -788,6 +789,10 @@ class NexusTradeClient {
788
789
  transport;
789
790
  constructor(options = {}) {
790
791
  if (options.transport) {
792
+ if (options.requestTimeoutSeconds !== undefined) {
793
+ throw new Error("requestTimeoutSeconds applies only to the built-in HTTP transport; " +
794
+ "configure a custom transport directly.");
795
+ }
791
796
  this.transport = options.transport;
792
797
  return;
793
798
  }
@@ -801,10 +806,11 @@ class NexusTradeClient {
801
806
  apiKey,
802
807
  baseUrl: baseUrl ?? exports.DEFAULT_API_BASE_URL,
803
808
  workspaceSession: options.workspaceSession,
809
+ timeoutSeconds: options.requestTimeoutSeconds,
804
810
  });
805
811
  }
806
- static fromEnvironment() {
807
- return new NexusTradeClient();
812
+ static fromEnvironment(options = {}) {
813
+ return new NexusTradeClient(options);
808
814
  }
809
815
  /** Return the anonymous workspace token after the first API call bootstraps it. */
810
816
  exportWorkspaceSession() {