nexustrade 1.42.0 → 1.55.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/AGENTS.md CHANGED
@@ -7,9 +7,11 @@ friendlier read.
7
7
  ## What this package is
8
8
 
9
9
  A typed client plus ~170 **generated** builders for authoring trading
10
- strategies. The builders are generated from the same indicator specification the
11
- NexusTrade engine executes, so a book assembled from them is structurally valid
12
- before it ever leaves the process.
10
+ strategies. The builders are generated from the engine's indicator specification.
11
+ They describe draft payloads; the API still validates complete portfolios and
12
+ their conditions. A builder's existence does not guarantee support for every
13
+ trading method. Read the [option selection and execution limits](README.md#option-selection-and-execution-limits)
14
+ before claiming exact option timing, expiration selection, or rolling behavior.
13
15
 
14
16
  ```
15
17
  author a portfolio → submit a job → poll until terminal → read result
package/README.md CHANGED
@@ -234,6 +234,36 @@ nt.strategy("Sell the credit spread for the debit fill plus $0.50", whenDebitSpr
234
234
  It keeps the no-worse-than-current-quote protection, but it is not a resting
235
235
  price target. Live option strategies must choose an explicit Limit policy.
236
236
 
237
+ ### Option selection and execution limits
238
+
239
+ Builders describe drafts. Typechecking does not prove that the engine can
240
+ execute every requested rule; the API validates complete portfolios and their
241
+ conditions.
242
+
243
+ - Expiration selectors support a DTE window and `nearest`, `middle`, or
244
+ `furthest`. `middle` selects the middle eligible expiration by index, not the
245
+ expiration nearest a target such as 180 days. There is no monthly-only or
246
+ quarterly-only expiration filter.
247
+ - `rebalanceOption` accepts `renewBeforeDays` (integer 1–90) and
248
+ `revisitDisclosedTargets`. These maintain modeled political-disclosure option
249
+ targets. The strategy must contain a `NewPoliticalDisclosure` condition for
250
+ instrument `Option` with exactly one member ID. These fields do not implement
251
+ a general close-and-replace roll for a trend strategy.
252
+ - For backtests, the job's `feeConfig.OptionSlippageFraction` sets quote-side
253
+ fills: `0` uses the midpoint, `1` uses ask for buys and bid for sells, and the
254
+ default is `0.5`. This job setting does not add a last-trade fallback or define
255
+ live order execution.
256
+ - Evaluation timing and order execution are separate. `OpenClose` schedules
257
+ evaluations at session open and close; it does not itself carry a signal
258
+ observed at close into an order at the next open. Explicit zero timing offsets
259
+ and a `gt(MinutesAfterOpen(), Value(0))` condition can restrict evaluations
260
+ to the calendar session close. `MinutesUntilClose` counts down to 16:00 Eastern,
261
+ so it cannot identify an early session close.
262
+
263
+ When authoring an approximation, describe the actual expiration policy, signal
264
+ timing, fills, and replacement behavior. Backtest results describe that
265
+ implementation, not the exact method it approximates.
266
+
237
267
  <details>
238
268
  <summary><b>What you can build</b> — 170+ generated builders</summary>
239
269
 
@@ -394,9 +424,15 @@ await client.updatePortfolio(portfolioId, operations, {
394
424
  });
395
425
  ```
396
426
 
397
- The five edits are `rename`, `addStrategies`, `removeStrategies`,
398
- `replaceStrategy`, and `replaceStrategies`. Deploy, undeploy, delete,
399
- scheduling, and trading-policy operations are not reachable on this route.
427
+ Prefer one `updatePortfolio` operation with a finished `portfolio` patch.
428
+ It can combine `strategies`, `deployment` (frequency and timing), `name`,
429
+ `policy.stockEligibility`, `dividendPolicy`, and alerts. Omitted fields retain
430
+ their saved values. Draft starting capital and capabilities can change only
431
+ before deployment. The existing strategy and rename operations remain supported.
432
+ Every authored operation for the target in one call commits together; validation
433
+ failure saves none of them. Reusing the same idempotency key replays the saved
434
+ result. Deploy, undeploy, delete and automated approval remain separate account
435
+ operations.
400
436
 
401
437
  **`replaceStrategies` replaces the whole set**, so a strategy left out of the
402
438
  array is deleted. Carry unchanged strategies through verbatim, including the
@@ -827,7 +863,7 @@ is missing here, so this list cannot drift from the code.
827
863
  | `createPortfolio(book, { idempotencyKey })` | Persist a portfolio definition |
828
864
  | `listPortfolios(options)` | List portfolios, with filters and pagination |
829
865
  | `getPortfolio(portfolioId)` | Read one portfolio |
830
- | `updatePortfolio(id, operations, { idempotencyKey })` | Rename or edit strategies deterministically |
866
+ | `updatePortfolio(id, operations, { idempotencyKey })` | Atomically save a finished authored portfolio patch |
831
867
  | `forkPublicPortfolio(sharedId, { idempotencyKey })` | Fork a public portfolio into the workspace |
832
868
  | `deploy(portfolioId, { frequency })` | Start paper trading it |
833
869
  | `undeploy(portfolioId)` | Stop it |
@@ -867,8 +867,8 @@ class NexusTradeClient {
867
867
  }
868
868
  /**
869
869
  * Apply deterministic no-code portfolio edits without invoking Aurora.
870
- * Guest workspaces may rename and add/remove/replace strategies; deployment,
871
- * scheduling, policy, and trading operations remain account-only.
870
+ * Finished authored patches can combine strategies, evaluation timing and
871
+ * stock eligibility in one save. Activation and automated approval remain separate.
872
872
  */
873
873
  async updatePortfolio(portfolioId, operations, options) {
874
874
  if (operations.length === 0) {
@@ -13,6 +13,7 @@ exports.BollingerBand = BollingerBand;
13
13
  exports.BullishFairValueGap = BullishFairValueGap;
14
14
  exports.BuyingPower = BuyingPower;
15
15
  exports.ChaikinMoneyFlow = ChaikinMoneyFlow;
16
+ exports.ChartBar = ChartBar;
16
17
  exports.CommodityChannelIndex = CommodityChannelIndex;
17
18
  exports.CompoundAnnualGrowthRate = CompoundAnnualGrowthRate;
18
19
  exports.ConsecutiveDecrease = ConsecutiveDecrease;
@@ -672,6 +673,25 @@ function ChaikinMoneyFlow(asset, length = 20, interval = "Day") {
672
673
  d.window = { length: length, interval: interval };
673
674
  return d;
674
675
  }
676
+ /**
677
+ * ChartBar indicator.
678
+ * @param asset Ticker name (ex. SPY, BTC)
679
+ * @param barMinutes Completed candles aligned to 9:30 ET for stocks. Must divide the 390-minute regular session.
680
+ * @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
681
+ * @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
682
+ * @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
683
+ * @param minutePolicy strict requires every minute. observed aggregates actual eligible-trade prints, skips empty candles, and publishes after the clock bucket closes. No synthetic prices; source coverage is a separate check.
684
+ */
685
+ function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0, minutePolicy = "strict") {
686
+ const d = { type: "ChartBar" };
687
+ setAsset(d, "targetAsset", asset);
688
+ d["barMinutes"] = barMinutes;
689
+ d["line"] = line;
690
+ d["bars"] = bars;
691
+ d["offsetBars"] = offsetBars;
692
+ d["minutePolicy"] = minutePolicy;
693
+ return d;
694
+ }
675
695
  /**
676
696
  * CommodityChannelIndex indicator.
677
697
  * @param asset Ticker name (ex. SPY, BTC)
@@ -72,12 +72,13 @@ export interface ReplaceStrategiesOperation {
72
72
  type: "replaceStrategies";
73
73
  strategyObjects: Strategy[];
74
74
  }
75
- /**
76
- * The edits `updatePortfolio` accepts. Deploy, undeploy, delete, scheduling and
77
- * trading-policy operations are deliberately absent: they are not reachable on
78
- * this route, so typing them here would only compile a guaranteed 403.
79
- */
80
- export type PortfolioEditOperation = PortfolioRenameOperation | AddStrategiesOperation | RemoveStrategiesOperation | ReplaceStrategyOperation | ReplaceStrategiesOperation;
75
+ /** Complete finished authored patch; omitted fields retain their saved values. */
76
+ export interface UpdatePortfolioOperation {
77
+ type: "updatePortfolio";
78
+ portfolio: Partial<Pick<Portfolio, "name" | "initialValue" | "strategies" | "deployment" | "policy" | "dividendPolicy" | "alertsEnabled" | "supportsFractionalShares" | "supportsCrypto">>;
79
+ }
80
+ /** All operations in one call for this portfolio are validated and saved atomically. */
81
+ export type PortfolioEditOperation = UpdatePortfolioOperation | PortfolioRenameOperation | AddStrategiesOperation | RemoveStrategiesOperation | ReplaceStrategyOperation | ReplaceStrategiesOperation;
81
82
  export interface ListOrdersOptions {
82
83
  portfolioId?: string;
83
84
  statuses?: ReadonlyArray<OrderStatus>;
@@ -268,8 +269,8 @@ export declare class NexusTradeClient {
268
269
  getPortfolio(portfolioId: string): Promise<PortfolioHandle>;
269
270
  /**
270
271
  * Apply deterministic no-code portfolio edits without invoking Aurora.
271
- * Guest workspaces may rename and add/remove/replace strategies; deployment,
272
- * scheduling, policy, and trading operations remain account-only.
272
+ * Finished authored patches can combine strategies, evaluation timing and
273
+ * stock eligibility in one save. Activation and automated approval remain separate.
273
274
  */
274
275
  updatePortfolio(portfolioId: string, operations: ReadonlyArray<PortfolioEditOperation>, options: {
275
276
  idempotencyKey: string;
@@ -857,8 +857,8 @@ export class NexusTradeClient {
857
857
  }
858
858
  /**
859
859
  * Apply deterministic no-code portfolio edits without invoking Aurora.
860
- * Guest workspaces may rename and add/remove/replace strategies; deployment,
861
- * scheduling, policy, and trading operations remain account-only.
860
+ * Finished authored patches can combine strategies, evaluation timing and
861
+ * stock eligibility in one save. Activation and automated approval remain separate.
862
862
  */
863
863
  async updatePortfolio(portfolioId, operations, options) {
864
864
  if (operations.length === 0) {
@@ -430,9 +430,9 @@ export interface RebalanceOptionAction {
430
430
  sleeves?: RebalanceOptionSleeve[];
431
431
  allocationPolicy?: AllocationPolicy;
432
432
  exposurePolicy?: ExposurePolicy;
433
- /** Simulated option replacement before modeled expiry when no full sale was disclosed. */
433
+ /** Disclosure maintenance only: requires a NewPoliticalDisclosure Option condition with exactly one memberId; integer 1..90. Not a generic DTE roll. */
434
434
  renewBeforeDays?: number;
435
- /** Revisit continuing public option targets only when another option filing arrives. */
435
+ /** Disclosure maintenance only: revisit continuing public option targets when another option filing arrives. Same condition restriction as renewBeforeDays. */
436
436
  revisitDisclosedTargets?: boolean;
437
437
  }
438
438
  export type OptionParentSelectionSort = "oldest" | "highestPnl" | "nearestExpiry";
@@ -547,6 +547,12 @@ export interface AuthoredStockEligibility {
547
547
  export interface AuthoredPortfolioPolicy {
548
548
  stockEligibility: AuthoredStockEligibility;
549
549
  }
550
+ export interface AuthoredDeploymentTiming {
551
+ frequency: "Constant" | "OpenClose";
552
+ openDelayMinutes?: number;
553
+ closeLeadMinutes?: number;
554
+ intervalSeconds?: number;
555
+ }
550
556
  export interface Portfolio {
551
557
  name: string;
552
558
  initialValue?: number;
@@ -560,6 +566,7 @@ export interface Portfolio {
560
566
  /** "cash" (default when omitted) or "reinvest" into the paying stock. */
561
567
  dividendPolicy?: DividendPolicy;
562
568
  policy?: AuthoredPortfolioPolicy;
569
+ deployment?: AuthoredDeploymentTiming;
563
570
  }
564
571
  export type DividendPolicy = "cash" | "reinvest";
565
572
  export type AssetType = "Stock" | "Cryptocurrency" | "Option" | "Other";
@@ -768,20 +775,7 @@ export declare const sleeve: (config: {
768
775
  * Rank a universe and rotate an option book. Keep take-profit / stop-loss / DTE
769
776
  * exits in separate closeOption strategies, not here.
770
777
  */
771
- export declare const rebalanceOption: (config: {
772
- universe: Universe;
773
- pipeline: PipelineStage[];
774
- weightIndicator: Indicator | CandidateIndicator;
775
- structureTemplates: OptionStructureTemplate[];
776
- limit?: number;
777
- totalBudget?: DeploymentBudget;
778
- perNameAllocation?: OptionAllocation;
779
- sizingMode?: "fixedPerName" | "proportionalToWeight" | "proportionalToWeightWholeContracts";
780
- positionScope?: RebalanceOptionPositionScope;
781
- sleeves?: RebalanceOptionSleeve[];
782
- allocationPolicy?: AllocationPolicy;
783
- exposurePolicy?: ExposurePolicy;
784
- }) => RebalanceOptionAction;
778
+ export declare const rebalanceOption: (config: Omit<RebalanceOptionAction, "type">) => RebalanceOptionAction;
785
779
  export declare const pnlTrigger: (bounds: {
786
780
  minPnlPercent?: number;
787
781
  maxPnlPercent?: number;
@@ -848,6 +842,7 @@ export declare const portfolio: (name: string, strategies: Strategy[], options?:
848
842
  alertsEnabled?: boolean;
849
843
  dividendPolicy?: DividendPolicy;
850
844
  policy?: AuthoredPortfolioPolicy;
845
+ deployment?: AuthoredDeploymentTiming;
851
846
  }) => PortfolioHandle;
852
847
  /**
853
848
  * AbsoluteValue indicator.
@@ -904,6 +899,16 @@ export declare function BuyingPower(): Indicator;
904
899
  * @param interval Unit of time
905
900
  */
906
901
  export declare function ChaikinMoneyFlow(asset: AssetArg, length?: number, interval?: Interval): Indicator;
902
+ /**
903
+ * ChartBar indicator.
904
+ * @param asset Ticker name (ex. SPY, BTC)
905
+ * @param barMinutes Completed candles aligned to 9:30 ET for stocks. Must divide the 390-minute regular session.
906
+ * @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
907
+ * @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
908
+ * @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
909
+ * @param minutePolicy strict requires every minute. observed aggregates actual eligible-trade prints, skips empty candles, and publishes after the clock bucket closes. No synthetic prices; source coverage is a separate check.
910
+ */
911
+ export declare function ChartBar(asset: AssetArg, barMinutes?: number, line?: "open" | "high" | "low" | "close" | "sma", bars?: number, offsetBars?: number, minutePolicy?: "strict" | "observed"): Indicator;
907
912
  /**
908
913
  * CommodityChannelIndex indicator.
909
914
  * @param asset Ticker name (ex. SPY, BTC)
@@ -1736,7 +1741,7 @@ export interface FeeConfig {
1736
1741
  Stock?: FeeAmount;
1737
1742
  Cryptocurrency?: FeeAmount;
1738
1743
  Option?: FeeAmount;
1739
- /** Rust-owned option fill slippage; absent means the engine's 0.5 default. */
1744
+ /** Option fill slippage: 0=quote mid, 1=ask for buys/bid for sells; absent means 0.5. Requires a current executable quote. */
1740
1745
  OptionSlippageFraction?: number;
1741
1746
  }
1742
1747
  export interface MetricConstraint {
@@ -1783,7 +1788,7 @@ export interface BacktestConfig {
1783
1788
  initialValue?: number;
1784
1789
  /** Generate detailed event data (signals, orders, audits) during backtest. Costs 5x research tokens. Events are Mongo hot-store traces retained for 3 days. Use query_backtest_events to explore them while retained. */
1785
1790
  generateEvents?: boolean;
1786
- /** Optional fee contract keyed by AssetTypeEnum (Stock/Cryptocurrency/Option) with {amount, type: percent|dollars}. Omit for shared defaults (Option $0.65/contract). For replay of an optimizer/walk-forward study, pass that study's persisted feeConfig. Option fill slippage (OptionSlippageFraction) is not set here — engine default 0.5 applies. */
1791
+ /** Optional fee contract keyed by AssetTypeEnum (Stock/Cryptocurrency/Option) with {amount, type: percent|dollars}. Omit for shared defaults (Option $0.65/contract). For replay of an optimizer/walk-forward study, pass that study's persisted feeConfig. OptionSlippageFraction is supported: 0 fills at quote mid, 1 at ask for buys/bid for sells; omitted uses the engine default 0.5. Fills require a current executable quote; this does not enable last-trade fallback pricing. */
1787
1792
  feeConfig?: FeeConfig;
1788
1793
  /** Overrides the portfolio's dividend policy for this run only. Omit to use the portfolio's own setting (cash unless it was set to reinvest). "reinvest" buys more of the paying stock on each pay date, which is what a buy-and-hold comparison against the SPY total-return baseline needs. */
1789
1794
  dividendPolicy?: "cash" | "reinvest";
@@ -453,6 +453,25 @@ export function ChaikinMoneyFlow(asset, length = 20, interval = "Day") {
453
453
  d.window = { length: length, interval: interval };
454
454
  return d;
455
455
  }
456
+ /**
457
+ * ChartBar indicator.
458
+ * @param asset Ticker name (ex. SPY, BTC)
459
+ * @param barMinutes Completed candles aligned to 9:30 ET for stocks. Must divide the 390-minute regular session.
460
+ * @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
461
+ * @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
462
+ * @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
463
+ * @param minutePolicy strict requires every minute. observed aggregates actual eligible-trade prints, skips empty candles, and publishes after the clock bucket closes. No synthetic prices; source coverage is a separate check.
464
+ */
465
+ export function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0, minutePolicy = "strict") {
466
+ const d = { type: "ChartBar" };
467
+ setAsset(d, "targetAsset", asset);
468
+ d["barMinutes"] = barMinutes;
469
+ d["line"] = line;
470
+ d["bars"] = bars;
471
+ d["offsetBars"] = offsetBars;
472
+ d["minutePolicy"] = minutePolicy;
473
+ return d;
474
+ }
456
475
  /**
457
476
  * CommodityChannelIndex indicator.
458
477
  * @param asset Ticker name (ex. SPY, BTC)
@@ -1,7 +1,7 @@
1
1
  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
- export type { AddStrategiesOperation, BacktestCollateralStatistics, CustomIndicatorInput, CustomIndicatorPointInput, HttpTransportOptions, JsonObject, JsonValue, ListOrdersOptions, ListPortfoliosOptions, NexusTradeClientOptions, PortfolioEditOperation, PortfolioRenameOperation, RemoveStrategiesOperation, ReplaceStrategiesOperation, ReplaceStrategyOperation, RequestOptions, Transport, UploadTransport, WaitOptions, WorkspaceSessionTransport, } from "./client.js";
4
+ export type { AddStrategiesOperation, BacktestCollateralStatistics, CustomIndicatorInput, CustomIndicatorPointInput, HttpTransportOptions, JsonObject, JsonValue, ListOrdersOptions, ListPortfoliosOptions, NexusTradeClientOptions, PortfolioEditOperation, UpdatePortfolioOperation, PortfolioRenameOperation, RemoveStrategiesOperation, ReplaceStrategiesOperation, ReplaceStrategyOperation, RequestOptions, Transport, UploadTransport, WaitOptions, WorkspaceSessionTransport, } from "./client.js";
5
5
  export { PortfolioHandle, portfolioHandleFromWire, } from "./portfolio.js";
6
6
  export type { DeployOutcome, DeployResult, PortfolioHandleOptions, PortfolioListResult, PortfolioType, ReadonlyPortfolioPolicy, } from "./portfolio.js";
7
7
  export * from "./generated/ntSdk.generated.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nexustrade",
3
- "version": "1.42.0",
3
+ "version": "1.55.0",
4
4
  "description": "Typed TypeScript SDK for NexusTrade portfolio authoring, backtesting, and optimization",
5
5
  "license": "MIT",
6
6
  "author": "Starks Technology",