nexustrade 1.52.0 → 1.58.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
 
@@ -98,6 +98,7 @@ exports.Negative = Negative;
98
98
  exports.NewInsiderDisclosure = NewInsiderDisclosure;
99
99
  exports.NewInstitutionalFiling = NewInstitutionalFiling;
100
100
  exports.NewPoliticalDisclosure = NewPoliticalDisclosure;
101
+ exports.NewsSentiment = NewsSentiment;
101
102
  exports.NewTradingWeek = NewTradingWeek;
102
103
  exports.OnBalanceVolume = OnBalanceVolume;
103
104
  exports.OpeningPrice = OpeningPrice;
@@ -680,14 +681,16 @@ function ChaikinMoneyFlow(asset, length = 20, interval = "Day") {
680
681
  * @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
681
682
  * @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
682
683
  * @param offsetBars Skip this many latest completed candles. 1 selects the previous window.
684
+ * @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.
683
685
  */
684
- function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0) {
686
+ function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0, minutePolicy = "strict") {
685
687
  const d = { type: "ChartBar" };
686
688
  setAsset(d, "targetAsset", asset);
687
689
  d["barMinutes"] = barMinutes;
688
690
  d["line"] = line;
689
691
  d["bars"] = bars;
690
692
  d["offsetBars"] = offsetBars;
693
+ d["minutePolicy"] = minutePolicy;
691
694
  return d;
692
695
  }
693
696
  /**
@@ -1606,6 +1609,19 @@ function NewPoliticalDisclosure(memberId, instrument, disclosureAction) {
1606
1609
  d["disclosureAction"] = disclosureAction;
1607
1610
  return d;
1608
1611
  }
1612
+ /**
1613
+ * Labelled news sentiment about the asset over its last lookbackDays daily news snapshots (default 1, the latest). Each trading day has one snapshot at 09:15 New York, and a row is visible from its snapshot's time. The lake assigns each article to the first snapshot it could have been in: for history that is by publish time, and an article that live collection fetched or labelled after a snapshot's deadline is moved to the next session's snapshot. Backtests and live trading read the same rows by that time. lookbackDays counts trading sessions whether or not the asset had news in them. Only articles in which the asset is the subject or significantly affected count; passing mentions, law-firm solicitations and routine filings never do, and copies of one story within 7 days count once per session. measure (default Mean): Mean is the average sentiment from -1.0 to 1.0, NetCount is positive minus negative articles, ArticleCount is the number of qualifying articles. Every measure has no value when the window cannot be read in full: before coverage begins in May 2021, across sessions with no published snapshot, or when the latest snapshot due has not been published. Mean also has no value when the window holds no qualifying article; the counts are then 0. Rows follow the security, so META reads Facebook-era FB articles.
1614
+ * @param asset Pass CANDIDATE in a dynamic rebalance pipeline.
1615
+ * @param measure Mean: average sentiment from -1 to 1, with no value when the window has no qualifying news. NetCount: positive minus negative articles. ArticleCount: qualifying articles. Every measure has no value before May 2021 coverage, across missing snapshots, or when the due snapshot is unpublished.
1616
+ * @param lookbackDays Whole trading sessions of daily 09:15 New York news snapshots; 1 is the latest. A row is visible from the snapshot the lake assigned it, the same time in backtests and live trading.
1617
+ */
1618
+ function NewsSentiment(asset, measure = "Mean", lookbackDays = 1) {
1619
+ const d = { type: "NewsSentiment" };
1620
+ setAsset(d, "targetAsset", asset);
1621
+ d["measure"] = measure;
1622
+ d["lookbackDays"] = lookbackDays;
1623
+ return d;
1624
+ }
1609
1625
  /**
1610
1626
  * NewTradingWeek indicator.
1611
1627
  */
@@ -2206,6 +2222,7 @@ const backtest = (portfolio, config) => ({
2206
2222
  "start_date": config.startDate,
2207
2223
  "end_date": config.endDate,
2208
2224
  "baseline_symbol": config.baselineSymbol,
2225
+ "baseline_asset": config.baselineAsset,
2209
2226
  "interval": config.interval,
2210
2227
  "initial_value": config.initialValue,
2211
2228
  "generate_events": config.generateEvents,
@@ -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";
@@ -775,20 +775,7 @@ export declare const sleeve: (config: {
775
775
  * Rank a universe and rotate an option book. Keep take-profit / stop-loss / DTE
776
776
  * exits in separate closeOption strategies, not here.
777
777
  */
778
- export declare const rebalanceOption: (config: {
779
- universe: Universe;
780
- pipeline: PipelineStage[];
781
- weightIndicator: Indicator | CandidateIndicator;
782
- structureTemplates: OptionStructureTemplate[];
783
- limit?: number;
784
- totalBudget?: DeploymentBudget;
785
- perNameAllocation?: OptionAllocation;
786
- sizingMode?: "fixedPerName" | "proportionalToWeight" | "proportionalToWeightWholeContracts";
787
- positionScope?: RebalanceOptionPositionScope;
788
- sleeves?: RebalanceOptionSleeve[];
789
- allocationPolicy?: AllocationPolicy;
790
- exposurePolicy?: ExposurePolicy;
791
- }) => RebalanceOptionAction;
778
+ export declare const rebalanceOption: (config: Omit<RebalanceOptionAction, "type">) => RebalanceOptionAction;
792
779
  export declare const pnlTrigger: (bounds: {
793
780
  minPnlPercent?: number;
794
781
  maxPnlPercent?: number;
@@ -919,8 +906,9 @@ export declare function ChaikinMoneyFlow(asset: AssetArg, length?: number, inter
919
906
  * @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
920
907
  * @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
921
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.
922
910
  */
923
- export declare function ChartBar(asset: AssetArg, barMinutes?: number, line?: "open" | "high" | "low" | "close" | "sma", bars?: number, offsetBars?: number): Indicator;
911
+ export declare function ChartBar(asset: AssetArg, barMinutes?: number, line?: "open" | "high" | "low" | "close" | "sma", bars?: number, offsetBars?: number, minutePolicy?: "strict" | "observed"): Indicator;
924
912
  /**
925
913
  * CommodityChannelIndex indicator.
926
914
  * @param asset Ticker name (ex. SPY, BTC)
@@ -1418,6 +1406,13 @@ export declare function NewInstitutionalFiling(manager: string): Indicator;
1418
1406
  * @param disclosureAction Which newly public trade sides trigger a decision.
1419
1407
  */
1420
1408
  export declare function NewPoliticalDisclosure(memberId: string, instrument: Instrument2, disclosureAction: "Any" | "Purchase" | "Sale"): Indicator;
1409
+ /**
1410
+ * Labelled news sentiment about the asset over its last lookbackDays daily news snapshots (default 1, the latest). Each trading day has one snapshot at 09:15 New York, and a row is visible from its snapshot's time. The lake assigns each article to the first snapshot it could have been in: for history that is by publish time, and an article that live collection fetched or labelled after a snapshot's deadline is moved to the next session's snapshot. Backtests and live trading read the same rows by that time. lookbackDays counts trading sessions whether or not the asset had news in them. Only articles in which the asset is the subject or significantly affected count; passing mentions, law-firm solicitations and routine filings never do, and copies of one story within 7 days count once per session. measure (default Mean): Mean is the average sentiment from -1.0 to 1.0, NetCount is positive minus negative articles, ArticleCount is the number of qualifying articles. Every measure has no value when the window cannot be read in full: before coverage begins in May 2021, across sessions with no published snapshot, or when the latest snapshot due has not been published. Mean also has no value when the window holds no qualifying article; the counts are then 0. Rows follow the security, so META reads Facebook-era FB articles.
1411
+ * @param asset Pass CANDIDATE in a dynamic rebalance pipeline.
1412
+ * @param measure Mean: average sentiment from -1 to 1, with no value when the window has no qualifying news. NetCount: positive minus negative articles. ArticleCount: qualifying articles. Every measure has no value before May 2021 coverage, across missing snapshots, or when the due snapshot is unpublished.
1413
+ * @param lookbackDays Whole trading sessions of daily 09:15 New York news snapshots; 1 is the latest. A row is visible from the snapshot the lake assigned it, the same time in backtests and live trading.
1414
+ */
1415
+ export declare function NewsSentiment(asset: AssetArg, measure?: "Mean" | "NetCount" | "ArticleCount", lookbackDays?: number): Indicator;
1421
1416
  /**
1422
1417
  * NewTradingWeek indicator.
1423
1418
  */
@@ -1753,7 +1748,7 @@ export interface FeeConfig {
1753
1748
  Stock?: FeeAmount;
1754
1749
  Cryptocurrency?: FeeAmount;
1755
1750
  Option?: FeeAmount;
1756
- /** Rust-owned option fill slippage; absent means the engine's 0.5 default. */
1751
+ /** Option fill slippage: 0=quote mid, 1=ask for buys/bid for sells; absent means 0.5. Requires a current executable quote. */
1757
1752
  OptionSlippageFraction?: number;
1758
1753
  }
1759
1754
  export interface MetricConstraint {
@@ -1792,15 +1787,17 @@ export interface BacktestConfig {
1792
1787
  startDate: string;
1793
1788
  /** Backtest end date (ISO format, e.g. 2024-12-31). Minute allows up to 730 days of minute data from start_date, counting minute-indicator warmup; never split a longer span into yearly Minute jobs. */
1794
1789
  endDate: string;
1795
- /** 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. */
1790
+ /** Legacy Stock benchmark shorthand for comparisonValue. Use baseline_asset with explicit Cryptocurrency type for crypto pairs; never provide both fields. When both fields are omitted, the single traded stock/option underlying is inferred, otherwise SPY. For single-name options use that underlying; compare multi-name books against a deliberately chosen benchmark. */
1796
1791
  baselineSymbol?: string;
1792
+ /** Typed buy-and-hold benchmark for comparisonValue. Use {type:'Cryptocurrency',symbol:'BTC-USD',name:'BTC-USD'} for BTC or {type:'Stock',symbol:'SPY',name:'SPY'} for a stock/ETF. Symbol text never determines asset type. Omit baseline_symbol when using this field. */
1793
+ baselineAsset?: Record<string, unknown>;
1797
1794
  /** Time interval: Day or Minute (default Day). Minute is a daytrade tape. 730 days of minute data (selected range plus warmup) is the HARD CAP; 90 days is only the DEFAULT when you name no dates. Name the dates you actually want — certifying a candidate on a full year or two is a normal second backtest, not an escalation. */
1798
1795
  interval?: "Day" | "Minute";
1799
1796
  /** Starting portfolio value (default 10000) Range 1..inf. */
1800
1797
  initialValue?: number;
1801
1798
  /** 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. */
1802
1799
  generateEvents?: boolean;
1803
- /** 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. */
1800
+ /** 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. */
1804
1801
  feeConfig?: FeeConfig;
1805
1802
  /** 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. */
1806
1803
  dividendPolicy?: "cash" | "reinvest";
@@ -460,14 +460,16 @@ export function ChaikinMoneyFlow(asset, length = 20, interval = "Day") {
460
460
  * @param line open: oldest selected candle; close: newest; high/low: range; sma: mean candle closes.
461
461
  * @param bars Number of chart candles, not elapsed minutes. SMA20 on five-minute candles: barMinutes=5, bars=20.
462
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.
463
464
  */
464
- export function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0) {
465
+ export function ChartBar(asset, barMinutes = 5, line = "close", bars = 1, offsetBars = 0, minutePolicy = "strict") {
465
466
  const d = { type: "ChartBar" };
466
467
  setAsset(d, "targetAsset", asset);
467
468
  d["barMinutes"] = barMinutes;
468
469
  d["line"] = line;
469
470
  d["bars"] = bars;
470
471
  d["offsetBars"] = offsetBars;
472
+ d["minutePolicy"] = minutePolicy;
471
473
  return d;
472
474
  }
473
475
  /**
@@ -1386,6 +1388,19 @@ export function NewPoliticalDisclosure(memberId, instrument, disclosureAction) {
1386
1388
  d["disclosureAction"] = disclosureAction;
1387
1389
  return d;
1388
1390
  }
1391
+ /**
1392
+ * Labelled news sentiment about the asset over its last lookbackDays daily news snapshots (default 1, the latest). Each trading day has one snapshot at 09:15 New York, and a row is visible from its snapshot's time. The lake assigns each article to the first snapshot it could have been in: for history that is by publish time, and an article that live collection fetched or labelled after a snapshot's deadline is moved to the next session's snapshot. Backtests and live trading read the same rows by that time. lookbackDays counts trading sessions whether or not the asset had news in them. Only articles in which the asset is the subject or significantly affected count; passing mentions, law-firm solicitations and routine filings never do, and copies of one story within 7 days count once per session. measure (default Mean): Mean is the average sentiment from -1.0 to 1.0, NetCount is positive minus negative articles, ArticleCount is the number of qualifying articles. Every measure has no value when the window cannot be read in full: before coverage begins in May 2021, across sessions with no published snapshot, or when the latest snapshot due has not been published. Mean also has no value when the window holds no qualifying article; the counts are then 0. Rows follow the security, so META reads Facebook-era FB articles.
1393
+ * @param asset Pass CANDIDATE in a dynamic rebalance pipeline.
1394
+ * @param measure Mean: average sentiment from -1 to 1, with no value when the window has no qualifying news. NetCount: positive minus negative articles. ArticleCount: qualifying articles. Every measure has no value before May 2021 coverage, across missing snapshots, or when the due snapshot is unpublished.
1395
+ * @param lookbackDays Whole trading sessions of daily 09:15 New York news snapshots; 1 is the latest. A row is visible from the snapshot the lake assigned it, the same time in backtests and live trading.
1396
+ */
1397
+ export function NewsSentiment(asset, measure = "Mean", lookbackDays = 1) {
1398
+ const d = { type: "NewsSentiment" };
1399
+ setAsset(d, "targetAsset", asset);
1400
+ d["measure"] = measure;
1401
+ d["lookbackDays"] = lookbackDays;
1402
+ return d;
1403
+ }
1389
1404
  /**
1390
1405
  * NewTradingWeek indicator.
1391
1406
  */
@@ -1986,6 +2001,7 @@ export const backtest = (portfolio, config) => ({
1986
2001
  "start_date": config.startDate,
1987
2002
  "end_date": config.endDate,
1988
2003
  "baseline_symbol": config.baselineSymbol,
2004
+ "baseline_asset": config.baselineAsset,
1989
2005
  "interval": config.interval,
1990
2006
  "initial_value": config.initialValue,
1991
2007
  "generate_events": config.generateEvents,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nexustrade",
3
- "version": "1.52.0",
3
+ "version": "1.58.0",
4
4
  "description": "Typed TypeScript SDK for NexusTrade portfolio authoring, backtesting, and optimization",
5
5
  "license": "MIT",
6
6
  "author": "Starks Technology",