nexustrade 1.5.0 → 1.6.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
@@ -281,6 +281,11 @@ await client.listPortfolios({ includePaper: true, includePositions: true });
281
281
  await client.getPortfolio(portfolioId);
282
282
  ```
283
283
 
284
+ Fetched portfolio handles include a typed, read-only `policy` snapshot. Trading
285
+ policy changes are intentionally unavailable through the SDK; edit them in
286
+ Portfolio Settings. `PortfolioHandle.toJSON()` omits the snapshot so a fetched
287
+ portfolio cannot accidentally submit policy changes through an authoring call.
288
+
284
289
  `listPortfolios` filters with `includePaper`, `includeLive`, `includeInactive`,
285
290
  `includeChatPortfolios`, `search`, `limit`, and `page`. `includePositions`
286
291
  defaults off when `search` is set.
@@ -49,6 +49,43 @@ const client_ts_1 = require("./client.js");
49
49
  function isJsonObject(value) {
50
50
  return typeof value === "object" && value !== null && !Array.isArray(value);
51
51
  }
52
+ function isStringArray(value) {
53
+ return Array.isArray(value) && value.every((item) => typeof item === "string");
54
+ }
55
+ function isReadonlyPortfolioPolicy(value) {
56
+ if (!isJsonObject(value) || value.schemaVersion !== 2)
57
+ return false;
58
+ const stock = value.stockEligibility;
59
+ const automation = value.automatedApproval;
60
+ if (!isJsonObject(stock) || !isJsonObject(automation))
61
+ return false;
62
+ const industry = stock.industryFilter;
63
+ return (typeof value.revision === "number" &&
64
+ Number.isSafeInteger(value.revision) &&
65
+ value.revision >= 0 &&
66
+ typeof stock.minimumMarketCapUsd === "number" &&
67
+ Number.isSafeInteger(stock.minimumMarketCapUsd) &&
68
+ stock.minimumMarketCapUsd >= 0 &&
69
+ (stock.maximumMarketCapUsd === null ||
70
+ (typeof stock.maximumMarketCapUsd === "number" &&
71
+ Number.isSafeInteger(stock.maximumMarketCapUsd) &&
72
+ stock.maximumMarketCapUsd >= stock.minimumMarketCapUsd)) &&
73
+ isJsonObject(industry) &&
74
+ (industry.mode === "ALL" || industry.mode === "INCLUDE_ONLY") &&
75
+ (industry.match === "ANY" || industry.match === "ALL") &&
76
+ isStringArray(industry.industries) &&
77
+ stock.missingMarketCapBehavior === "EXCLUDE" &&
78
+ stock.missingIndustryBehavior === "EXCLUDE_WHEN_FILTER_SET" &&
79
+ stock.appliesTo === "DYNAMIC_STOCK_UNIVERSES" &&
80
+ typeof automation.enabled === "boolean" &&
81
+ typeof automation.maxAutomatedTradesPerDay === "number" &&
82
+ Number.isSafeInteger(automation.maxAutomatedTradesPerDay) &&
83
+ automation.maxAutomatedTradesPerDay >= 1 &&
84
+ automation.maxAutomatedTradesPerDay <= 25 &&
85
+ automation.countingUnit === "TRADE_ACTION" &&
86
+ automation.dailyWindow === "AMERICA_NEW_YORK_CALENDAR_DAY" &&
87
+ (value.updatedAt === undefined || typeof value.updatedAt === "string"));
88
+ }
52
89
  function encodePathSegment(value) {
53
90
  return encodeURIComponent(value);
54
91
  }
@@ -70,6 +107,11 @@ class PortfolioHandle {
70
107
  createdAt;
71
108
  updatedAt;
72
109
  brokerage;
110
+ /** Server-owned snapshot. It is intentionally omitted from authoring payloads. */
111
+ #policy;
112
+ get policy() {
113
+ return this.#policy;
114
+ }
73
115
  #transport;
74
116
  constructor(data, options = {}) {
75
117
  const record = { ...data };
@@ -112,6 +154,9 @@ class PortfolioHandle {
112
154
  this.updatedAt = record.updatedAt;
113
155
  if (typeof record.brokerage === "string")
114
156
  this.brokerage = record.brokerage;
157
+ if (isReadonlyPortfolioPolicy(record.policy)) {
158
+ this.#policy = record.policy;
159
+ }
115
160
  for (const [key, value] of Object.entries(record)) {
116
161
  if (key === "name" ||
117
162
  key === "initialValue" ||
@@ -125,7 +170,8 @@ class PortfolioHandle {
125
170
  key === "strategyNames" ||
126
171
  key === "createdAt" ||
127
172
  key === "updatedAt" ||
128
- key === "brokerage") {
173
+ key === "brokerage" ||
174
+ key === "policy") {
129
175
  continue;
130
176
  }
131
177
  // `__proto__`/`constructor` arrive as own enumerable keys from
@@ -1260,13 +1260,13 @@ export interface JobRequest {
1260
1260
  args: Record<string, unknown>;
1261
1261
  }
1262
1262
  export interface BacktestConfig {
1263
- /** Backtest start date (ISO format, e.g. 2024-01-01) */
1263
+ /** Backtest start date (ISO format, e.g. 2024-01-01). For interval=Minute, default first-look is the last 90 inclusive calendar days and the selected range cannot exceed 365 days. Do not use 2010-01-01 or a multi-year span on Minute. */
1264
1264
  startDate: string;
1265
- /** Backtest end date (ISO format, e.g. 2024-12-31) */
1265
+ /** Backtest end date (ISO format, e.g. 2024-12-31). Minute hard max is 365 days from start_date; extend a survivor in a later run instead of splitting into yearly Minute jobs. */
1266
1266
  endDate: string;
1267
1267
  /** Benchmark for comparisonValue (buy-and-hold of this ticker). Defaults to SPY if omitted — use SPY only for broad equity/market strategies. For single-name options, set to that underlying (AAPL options → AAPL). For multi-name options books, run separate backtests with each material underlying as baseline (AAPL for AAPL sleeve, MSFT for MSFT), or equal-weight B&H of the traded universe — do not default to SPY. */
1268
1268
  baselineSymbol?: string;
1269
- /** Time interval: Day or Minute (default Day) */
1269
+ /** Time interval: Day or Minute (default Day). Minute is a daytrade tape — first-look 90 days, hard max 365 days. */
1270
1270
  interval?: "Day" | "Minute";
1271
1271
  /** Starting portfolio value (default 10000) Range 1..inf. */
1272
1272
  initialValue?: number;
@@ -1276,7 +1276,7 @@ export interface BacktestConfig {
1276
1276
  feeConfig?: FeeConfig;
1277
1277
  }
1278
1278
  export interface WalkForwardConfig {
1279
- /** Global calendar start for the walk-forward study (ISO date). */
1279
+ /** Global calendar start for the walk-forward study (ISO date). Minute seed first-look is 90 days; each Minute evaluation window still cannot exceed 365 days. */
1280
1280
  globalStartDate: string;
1281
1281
  /** Global calendar end for the walk-forward study (ISO date). */
1282
1282
  globalEndDate: string;
@@ -1340,9 +1340,9 @@ export interface WalkForwardConfig {
1340
1340
  genes?: Gene[];
1341
1341
  }
1342
1342
  export interface OptimizationConfig {
1343
- /** Optimization start date (ISO format, e.g. 2024-01-01) */
1343
+ /** Optimization start date (ISO format, e.g. 2024-01-01). Minute interval inherits the backtest cap: first-look 90 days, hard max 365 days. */
1344
1344
  startDate: string;
1345
- /** Optimization end date (ISO format, e.g. 2024-12-31) */
1345
+ /** Optimization end date (ISO format, e.g. 2024-12-31). Minute selected range cannot exceed 365 days. */
1346
1346
  endDate: string;
1347
1347
  /** Fitness functions: sharpeRatio, sortinoRatio, maxDrawdown, avgDrawdown, percentChange, dollarsSold, ulcerPerformanceIndex, participationRate, distinctUnderlyingsTraded, medianDeployment */
1348
1348
  fitnessFunctions?: ("sharpeRatio" | "sortinoRatio" | "maxDrawdown" | "avgDrawdown" | "percentChange" | "dollarsSold" | "ulcerPerformanceIndex" | "participationRate" | "distinctUnderlyingsTraded" | "medianDeployment")[];
@@ -3,5 +3,5 @@ export type { AgentEvent, AgentRunOptions } from "./agent.js";
3
3
  export { HttpTransport, NexusTradeApiError, NexusTradeClient, createCustomIndicator, createPortfolio, waitForOperation, } from "./client.js";
4
4
  export type { CustomIndicatorInput, CustomIndicatorPointInput, HttpTransportOptions, JsonObject, JsonValue, ListPortfoliosOptions, NexusTradeClientOptions, RequestOptions, Transport, UploadTransport, WaitOptions, } from "./client.js";
5
5
  export { PortfolioHandle, portfolioHandleFromWire, } from "./portfolio.js";
6
- export type { DeployOutcome, DeployResult, PortfolioHandleOptions, PortfolioListResult, PortfolioType, } from "./portfolio.js";
6
+ export type { DeployOutcome, DeployResult, PortfolioHandleOptions, PortfolioListResult, PortfolioType, ReadonlyPortfolioPolicy, } from "./portfolio.js";
7
7
  export * from "./generated/ntSdk.generated.js";
@@ -32,6 +32,29 @@ export interface PortfolioHandleOptions {
32
32
  id?: string | null;
33
33
  transport?: Transport;
34
34
  }
35
+ export interface ReadonlyPortfolioPolicy {
36
+ readonly schemaVersion: 2;
37
+ readonly revision: number;
38
+ readonly stockEligibility: {
39
+ readonly minimumMarketCapUsd: number;
40
+ readonly maximumMarketCapUsd: number | null;
41
+ readonly industryFilter: {
42
+ readonly mode: "ALL" | "INCLUDE_ONLY";
43
+ readonly match: "ANY" | "ALL";
44
+ readonly industries: readonly string[];
45
+ };
46
+ readonly missingMarketCapBehavior: "EXCLUDE";
47
+ readonly missingIndustryBehavior: "EXCLUDE_WHEN_FILTER_SET";
48
+ readonly appliesTo: "DYNAMIC_STOCK_UNIVERSES";
49
+ };
50
+ readonly automatedApproval: {
51
+ readonly enabled: boolean;
52
+ readonly maxAutomatedTradesPerDay: number;
53
+ readonly countingUnit: "TRADE_ACTION";
54
+ readonly dailyWindow: "AMERICA_NEW_YORK_CALENDAR_DAY";
55
+ };
56
+ readonly updatedAt?: string;
57
+ }
35
58
  /** Runtime portfolio object. Implements the generated `Portfolio` shape. */
36
59
  export declare class PortfolioHandle implements Portfolio {
37
60
  #private;
@@ -51,6 +74,7 @@ export declare class PortfolioHandle implements Portfolio {
51
74
  createdAt?: string;
52
75
  updatedAt?: string;
53
76
  brokerage?: string;
77
+ get policy(): ReadonlyPortfolioPolicy | undefined;
54
78
  constructor(data: Portfolio | JsonObject, options?: PortfolioHandleOptions);
55
79
  static from(data: Portfolio | JsonObject, options?: PortfolioHandleOptions): PortfolioHandle;
56
80
  /** Omit `id` — class fields would otherwise serialize as `"id": null`. */
@@ -12,6 +12,43 @@ import { NexusTradeApiError, NO_HTTP_STATUS, } from "./client.js";
12
12
  function isJsonObject(value) {
13
13
  return typeof value === "object" && value !== null && !Array.isArray(value);
14
14
  }
15
+ function isStringArray(value) {
16
+ return Array.isArray(value) && value.every((item) => typeof item === "string");
17
+ }
18
+ function isReadonlyPortfolioPolicy(value) {
19
+ if (!isJsonObject(value) || value.schemaVersion !== 2)
20
+ return false;
21
+ const stock = value.stockEligibility;
22
+ const automation = value.automatedApproval;
23
+ if (!isJsonObject(stock) || !isJsonObject(automation))
24
+ return false;
25
+ const industry = stock.industryFilter;
26
+ return (typeof value.revision === "number" &&
27
+ Number.isSafeInteger(value.revision) &&
28
+ value.revision >= 0 &&
29
+ typeof stock.minimumMarketCapUsd === "number" &&
30
+ Number.isSafeInteger(stock.minimumMarketCapUsd) &&
31
+ stock.minimumMarketCapUsd >= 0 &&
32
+ (stock.maximumMarketCapUsd === null ||
33
+ (typeof stock.maximumMarketCapUsd === "number" &&
34
+ Number.isSafeInteger(stock.maximumMarketCapUsd) &&
35
+ stock.maximumMarketCapUsd >= stock.minimumMarketCapUsd)) &&
36
+ isJsonObject(industry) &&
37
+ (industry.mode === "ALL" || industry.mode === "INCLUDE_ONLY") &&
38
+ (industry.match === "ANY" || industry.match === "ALL") &&
39
+ isStringArray(industry.industries) &&
40
+ stock.missingMarketCapBehavior === "EXCLUDE" &&
41
+ stock.missingIndustryBehavior === "EXCLUDE_WHEN_FILTER_SET" &&
42
+ stock.appliesTo === "DYNAMIC_STOCK_UNIVERSES" &&
43
+ typeof automation.enabled === "boolean" &&
44
+ typeof automation.maxAutomatedTradesPerDay === "number" &&
45
+ Number.isSafeInteger(automation.maxAutomatedTradesPerDay) &&
46
+ automation.maxAutomatedTradesPerDay >= 1 &&
47
+ automation.maxAutomatedTradesPerDay <= 25 &&
48
+ automation.countingUnit === "TRADE_ACTION" &&
49
+ automation.dailyWindow === "AMERICA_NEW_YORK_CALENDAR_DAY" &&
50
+ (value.updatedAt === undefined || typeof value.updatedAt === "string"));
51
+ }
15
52
  function encodePathSegment(value) {
16
53
  return encodeURIComponent(value);
17
54
  }
@@ -33,6 +70,11 @@ export class PortfolioHandle {
33
70
  createdAt;
34
71
  updatedAt;
35
72
  brokerage;
73
+ /** Server-owned snapshot. It is intentionally omitted from authoring payloads. */
74
+ #policy;
75
+ get policy() {
76
+ return this.#policy;
77
+ }
36
78
  #transport;
37
79
  constructor(data, options = {}) {
38
80
  const record = { ...data };
@@ -75,6 +117,9 @@ export class PortfolioHandle {
75
117
  this.updatedAt = record.updatedAt;
76
118
  if (typeof record.brokerage === "string")
77
119
  this.brokerage = record.brokerage;
120
+ if (isReadonlyPortfolioPolicy(record.policy)) {
121
+ this.#policy = record.policy;
122
+ }
78
123
  for (const [key, value] of Object.entries(record)) {
79
124
  if (key === "name" ||
80
125
  key === "initialValue" ||
@@ -88,7 +133,8 @@ export class PortfolioHandle {
88
133
  key === "strategyNames" ||
89
134
  key === "createdAt" ||
90
135
  key === "updatedAt" ||
91
- key === "brokerage") {
136
+ key === "brokerage" ||
137
+ key === "policy") {
92
138
  continue;
93
139
  }
94
140
  // `__proto__`/`constructor` arrive as own enumerable keys from
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nexustrade",
3
- "version": "1.5.0",
3
+ "version": "1.6.0",
4
4
  "description": "Typed TypeScript SDK for NexusTrade portfolio authoring, backtesting, and optimization",
5
5
  "license": "MIT",
6
6
  "author": "Starks Technology",