nexustrade 1.1.0 → 1.3.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
@@ -136,6 +136,15 @@ await client.createCustomIndicator(
136
136
  Point batches are unlimited in size; the SDK sends them inline or uploads them.
137
137
  Do not chunk by hand.
138
138
 
139
+ Declare `pointKind: "observation"` for point-in-time samples so date-only rows
140
+ retain same-day UTC availability on both inline and large-upload paths. Use
141
+ `period_aggregate` plus `aggregatePeriod` for closed periods, or `disclosed`
142
+ with per-row publication times.
143
+
144
+ For daily market prices, prefer `lake.query("sec_daily_ohlc", ...)` or the
145
+ canonical OHLC helper. `daily_ohlc` is a legacy/vendor table and may lag the
146
+ canonical daily series.
147
+
139
148
  ## Recipes
140
149
 
141
150
  <details open>
@@ -303,7 +312,17 @@ you did not create in this session as possibly live.
303
312
 
304
313
  Not in this SDK. Do not attempt to reach them through it:
305
314
 
306
- - **Screener** — MCP only.
315
+ - ~~**Screener** — MCP only.~~ **The screener is here now:**
316
+ `client.createNlScreen("...")` + `waitForNlScreen(id)` turns a plain-language
317
+ question into validated `lake.*` SQL, runs it, and returns the rows *and the
318
+ statement*. Prefer it over hand-writing SQL for stock selection — the server
319
+ picks tables from the same catalog the validator enforces, so it cannot name
320
+ a column that does not exist. Fall back to `createLakeQuery` only when
321
+ `outcome === "GENERATION_FAILED"`, or when the question is not a stock
322
+ screen. `EMPTY` is an answer, not a fallback trigger, and `CLARIFICATION`
323
+ means the question was ambiguous — answer it rather than guessing SQL. Always
324
+ report `result.sql`: it is model-generated, so it is the only way anyone can
325
+ check the numbers. Spends LLM credits; the lake API does not.
307
326
  - **Submitting a live order** — impossible from anywhere, not just here. Live
308
327
  orders are staged `PENDING_USER_APPROVAL` and a human approves them in the
309
328
  UI; the brokerage boundary refuses an unapproved live order regardless of
package/README.md CHANGED
@@ -27,7 +27,13 @@ npm install nexustrade
27
27
 
28
28
  ```ts
29
29
  import {
30
- NexusTradeClient, always, backtest, buy, portfolio, stockAsset, strategy,
30
+ NexusTradeClient,
31
+ always,
32
+ backtest,
33
+ buy,
34
+ portfolio,
35
+ stockAsset,
36
+ strategy,
31
37
  } from "nexustrade";
32
38
 
33
39
  const client = new NexusTradeClient({
@@ -41,12 +47,16 @@ const book = portfolio("Example", [
41
47
 
42
48
  const operation = await client.createBacktest(
43
49
  backtest(book, { startDate: "2024-01-01", endDate: "2024-12-31" }),
44
- { idempotencyKey: "example-v1" },
50
+ { idempotencyKey: "example-v1" }
45
51
  );
46
52
  const result = await client.waitForBacktest(operation.id as string);
47
53
  console.log(result.result);
48
54
  ```
49
55
 
56
+ Backtest operations may include `warnings: string[]` immediately after
57
+ submission and again in the terminal `result`. Treat them as material caveats;
58
+ they do not change a successful operation into a failure.
59
+
50
60
  ## Authoring strategies
51
61
 
52
62
  Every builder is generated from the same indicator specification the NexusTrade
@@ -58,38 +68,42 @@ TypeScript cannot overload comparison operators, so indicators compose through
58
68
  ```ts
59
69
  import * as nt from "nexustrade";
60
70
 
61
- const book = nt.portfolio("Momentum", [
62
- nt.strategy(
63
- "Rotate into strength",
64
- nt.always(),
65
- nt.dynamicRebalance({
66
- universe: nt.universe("SP500"),
67
- pipeline: [
68
- nt.filter(nt.gt(nt.Price(nt.CANDIDATE), nt.SMA(nt.CANDIDATE, 200))),
69
- nt.selectTop(nt.RSI(nt.CANDIDATE, 14), 10),
70
- ],
71
- weightIndicator: nt.RSI(nt.CANDIDATE, 14),
72
- limit: 10,
73
- deploymentPercent: 80,
74
- }),
75
- ),
76
- ], { initialValue: 100_000 });
71
+ const book = nt.portfolio(
72
+ "Momentum",
73
+ [
74
+ nt.strategy(
75
+ "Rotate into strength",
76
+ nt.always(),
77
+ nt.dynamicRebalance({
78
+ universe: nt.universe("SP500"),
79
+ pipeline: [
80
+ nt.filter(nt.gt(nt.Price(nt.CANDIDATE), nt.SMA(nt.CANDIDATE, 200))),
81
+ nt.selectTop(nt.RSI(nt.CANDIDATE, 14), 10),
82
+ ],
83
+ weightIndicator: nt.RSI(nt.CANDIDATE, 14),
84
+ limit: 10,
85
+ deploymentPercent: 80,
86
+ })
87
+ ),
88
+ ],
89
+ { initialValue: 100_000 }
90
+ );
77
91
  ```
78
92
 
79
93
  <details>
80
94
  <summary><b>What you can build</b> — 170+ generated builders</summary>
81
95
 
82
- | Group | Examples |
83
- | --- | --- |
84
- | **Price & volume** | `Price` `OpeningPrice` `HighOfDay` `VWAP` `Volume` `GapPercentage` |
85
- | **Technicals** | `SMA` `EMA` `RSI` `BollingerBand` `AverageTrueRange` `CrossAbove` |
86
- | **Position state** | `PositionValue` `PositionPercentChange` `PositionMaxDrawdown` |
87
- | **Portfolio state** | `PortfolioValue` `BuyingPower` `MaxDrawdown` `InitialValue` |
88
- | **Fundamentals** | `Fundamental` `Economic` `DaysUntilEarnings` `IsIndexMember` `IsIndustry` |
89
- | **Options** | `OptionDaysToExpiration` `OptionCollateral` `OptionUnrealizedPnL` `openOption` `closeOption` |
90
- | **Actions** | `buy` `sell` `alert` `dynamicRebalance` `rebalanceOption` |
91
- | **Selection** | `filter` `selectTop` `selectPercentile` `universe` |
92
- | **Logic** | `always` `atLeast` `atMost` `exactly` `fewerThan` `multi` `and` `or` |
96
+ | Group | Examples |
97
+ | ------------------- | -------------------------------------------------------------------------------------------- |
98
+ | **Price & volume** | `Price` `OpeningPrice` `HighOfDay` `VWAP` `Volume` `GapPercentage` |
99
+ | **Technicals** | `SMA` `EMA` `RSI` `BollingerBand` `AverageTrueRange` `CrossAbove` |
100
+ | **Position state** | `PositionValue` `PositionPercentChange` `PositionMaxDrawdown` |
101
+ | **Portfolio state** | `PortfolioValue` `BuyingPower` `MaxDrawdown` `InitialValue` |
102
+ | **Fundamentals** | `Fundamental` `Economic` `DaysUntilEarnings` `IsIndexMember` `IsIndustry` |
103
+ | **Options** | `OptionDaysToExpiration` `OptionCollateral` `OptionUnrealizedPnL` `openOption` `closeOption` |
104
+ | **Actions** | `buy` `sell` `alert` `dynamicRebalance` `rebalanceOption` |
105
+ | **Selection** | `filter` `selectTop` `selectPercentile` `universe` |
106
+ | **Logic** | `always` `atLeast` `atMost` `exactly` `fewerThan` `multi` `and` `or` |
93
107
 
94
108
  Every builder is fully typed — your editor completes the whole surface.
95
109
 
@@ -137,12 +151,12 @@ Every job kind reports the same envelope, so one poller serves all of them:
137
151
  const finished = await client.waitForBacktest(operation.id as string);
138
152
  ```
139
153
 
140
- | Option | Default | Meaning |
141
- | --- | --- | --- |
142
- | `timeoutSeconds` | `900` | Give up waiting (the job keeps running) |
143
- | `pollIntervalSeconds` | `2` | First interval; backs off 1.5× |
144
- | `maxPollIntervalSeconds` | `15` | Interval ceiling |
145
- | `throwOnFailure` | `true` | Throw on `failed`/`cancelled` instead of returning |
154
+ | Option | Default | Meaning |
155
+ | ------------------------ | ------- | -------------------------------------------------- |
156
+ | `timeoutSeconds` | `900` | Give up waiting (the job keeps running) |
157
+ | `pollIntervalSeconds` | `2` | First interval; backs off 1.5× |
158
+ | `maxPollIntervalSeconds` | `15` | Interval ceiling |
159
+ | `throwOnFailure` | `true` | Throw on `failed`/`cancelled` instead of returning |
146
160
 
147
161
  A timeout throws `operation_timeout` and does **not** cancel the job — call the
148
162
  waiter again with the same id rather than resubmitting.
@@ -160,7 +174,7 @@ const study = await client.createWalkForward(
160
174
  globalEndDate: "2024-12-31",
161
175
  foldCount: 4,
162
176
  }),
163
- { idempotencyKey: "wf-v1" },
177
+ { idempotencyKey: "wf-v1" }
164
178
  );
165
179
  await client.waitForWalkForward(study.id as string);
166
180
  ```
@@ -171,24 +185,26 @@ Authoring and backtesting a book does not persist it. `save` writes it to your
171
185
  account; `deploy` starts running it.
172
186
 
173
187
  ```ts
174
- const book = nt.portfolio("Momentum", [/* … */]);
188
+ const book = nt.portfolio("Momentum", [
189
+ /* … */
190
+ ]);
175
191
 
176
- await book.save({ idempotencyKey: "momentum-v1" }); // persists; sets book.id
177
- const deployment = await book.deploy(); // starts paper trading
178
- await book.undeploy(); // stops it
192
+ await book.save({ idempotencyKey: "momentum-v1" }); // persists; sets book.id
193
+ const deployment = await book.deploy(); // starts paper trading
194
+ await book.undeploy(); // stops it
179
195
  ```
180
196
 
181
197
  **`save` and `deploy` produce different ids, and the distinction matters.**
182
- `save` persists a *draft* and sets `book.id` to it. `deploy` mints the real
198
+ `save` persists a _draft_ and sets `book.id` to it. `deploy` mints the real
183
199
  paper portfolio and returns its own `portfolioId` — deploying creates a
184
200
  portfolio rather than converting the draft into one, so the two ids coexist.
185
201
  Hold on to `deployment.portfolioId` for anything that reads live state;
186
202
  `book.id` addresses the draft.
187
203
 
188
204
  ```ts
189
- deployment.portfolioId // the running portfolio
190
- deployment.deploymentType // paper, unless you deployed an existing live one
191
- deployment.outcome // created | reactivated
205
+ deployment.portfolioId; // the running portfolio
206
+ deployment.deploymentType; // paper, unless you deployed an existing live one
207
+ deployment.outcome; // created | reactivated
192
208
  ```
193
209
 
194
210
  Handle methods accept an optional `transport`; omitted, they resolve one from
@@ -204,7 +220,7 @@ await client.getPortfolio(portfolioId);
204
220
  `includeChatPortfolios`, `search`, `limit`, and `page`. `includePositions`
205
221
  defaults off when `search` is set.
206
222
 
207
- **A portfolio you create here is always paper**, and minting a *live* one still
223
+ **A portfolio you create here is always paper**, and minting a _live_ one still
208
224
  happens in the web app. Orders and brokerage status are reachable from here;
209
225
  see [Live trading](#live-trading).
210
226
 
@@ -224,7 +240,7 @@ await client.listBrokerages();
224
240
  // [{ brokerage: "Alpaca", connected: false,
225
241
  // connectUrl: "https://nexustrade.io/live-trading" }, ...]
226
242
 
227
- await client.connectBrokerage("Alpaca"); // logs the URL, waits until connected
243
+ await client.connectBrokerage("Alpaca"); // logs the URL, waits until connected
228
244
  ```
229
245
 
230
246
  `connectBrokerage` waits by default **only when stdout is a TTY**. In CI, cron,
@@ -246,9 +262,29 @@ await client.listPortfolios({ includeLive: true, includePaper: false });
246
262
  ```ts
247
263
  const result = await client.createOrders(
248
264
  portfolioId,
249
- [{ asset: { name: "SPY", type: "STOCK", symbol: "SPY" },
250
- side: "BUY", quantity: 10, orderType: "MARKET" }],
251
- { idempotencyKey: "rebalance-2024-04-01" },
265
+ [
266
+ {
267
+ asset: { name: "SPY", type: "STOCK", symbol: "SPY" },
268
+ side: "BUY",
269
+ quantity: 10,
270
+ orderType: "MARKET",
271
+ },
272
+ ],
273
+ { idempotencyKey: "rebalance-2024-04-01" }
274
+ );
275
+
276
+ // Dollar notional (stock/crypto only — options require contract quantity):
277
+ await client.createOrders(
278
+ portfolioId,
279
+ [
280
+ {
281
+ asset: { name: "AAPL", type: "STOCK", symbol: "AAPL" },
282
+ side: "BUY",
283
+ amount: 500,
284
+ orderType: "MARKET",
285
+ },
286
+ ],
287
+ { idempotencyKey: "buy-aapl-500" }
252
288
  );
253
289
  ```
254
290
 
@@ -278,17 +314,18 @@ const series = await client.createCustomIndicator(
278
314
  name: "WSB NVDA Mentions",
279
315
  scope: "asset",
280
316
  description: "Daily r/wallstreetbets mentions",
317
+ pointKind: "observation",
281
318
  points: [
282
319
  { timestamp: "2024-04-01", value: 152, ticker: "NVDA" },
283
320
  { timestamp: "2024-04-02", value: 90, ticker: "NVDA" },
284
321
  ],
285
322
  },
286
- { idempotencyKey: "wsb-mentions-v1" },
323
+ { idempotencyKey: "wsb-mentions-v1" }
287
324
  );
288
325
 
289
326
  const busy = nt.gt(
290
327
  nt.CustomIndicator(nt.stockAsset("NVDA"), String(series.customIndicatorId)),
291
- 100,
328
+ 100
292
329
  );
293
330
  const book = nt.portfolio("Attention", [
294
331
  nt.strategy("Buy the buzz", busy, nt.buy(nt.stockAsset("NVDA"), 25)),
@@ -298,6 +335,13 @@ const book = nt.portfolio("Attention", [
298
335
  `scope` is `"global"` (one series) or `"asset"` (one series per ticker, so every
299
336
  point needs a `ticker`). It cannot be changed after creation.
300
337
 
338
+ Declare `pointKind` whenever the time semantics are known: `observation` for
339
+ point-in-time samples, `period_aggregate` plus `aggregatePeriod` (`1d`, `1w`,
340
+ `1mo`, or `1q`) for closed-period values, and `disclosed` for values with an
341
+ explicit publication time on every row. The SDK applies this contract before
342
+ both inline and large-upload writes. A same-day date-only observation becomes
343
+ an explicit same-day UTC instant instead of shifting to the next calendar day.
344
+
301
345
  **Size is not a constraint.** `points` is unlimited. A batch that fits the
302
346
  request goes with it; a larger one is uploaded to storage and validated before
303
347
  the call resolves. Either way the returned indicator reflects what actually
@@ -310,7 +354,7 @@ success.
310
354
  await client.appendCustomIndicatorPoints(
311
355
  String(series.customIndicatorId),
312
356
  [{ timestamp: "2024-04-03", value: 118, ticker: "NVDA" }],
313
- { idempotencyKey: "wsb-mentions-2024-04-03" },
357
+ { idempotencyKey: "wsb-mentions-2024-04-03" }
314
358
  );
315
359
  ```
316
360
 
@@ -318,11 +362,13 @@ Creating a fresh series per run splits the history into fragments no strategy
318
362
  can read. Re-sending an identical batch is safe — the duplicate is not written
319
363
  twice.
320
364
 
321
- | Call | Purpose |
322
- | --- | --- |
323
- | `createCustomIndicator(spec, { idempotencyKey })` | Create, optionally seeded |
324
- | `appendCustomIndicatorPoints(id, points, { idempotencyKey })` | Add points |
325
- | `listCustomIndicators()` / `getCustomIndicator(id)` | Discover ids and coverage |
365
+ | Call | Purpose |
366
+ | ------------------------------------------------------------- | ------------------------- |
367
+ | `createCustomIndicator(spec, { idempotencyKey })` | Create, optionally seeded |
368
+ | `appendCustomIndicatorPoints(id, points, { idempotencyKey })` | Add points |
369
+ | `replaceCustomIndicatorPoints(id, points, { idempotencyKey })` | Replace points, retain id |
370
+ | `archiveCustomIndicator(id)` / `restoreCustomIndicator(id)` | Reversible lifecycle |
371
+ | `listCustomIndicators()` / `getCustomIndicator(id)` | Discover ids and coverage |
326
372
 
327
373
  Points accept `timestamp`, `value`, `ticker`, `assetType`, and `availableAt`
328
374
  — camelCase or snake_case, with `Date` objects allowed. Set `availableAt` when a
@@ -400,16 +446,49 @@ flowchart LR
400
446
  ```ts
401
447
  const query = await client.createLakeQuery(
402
448
  {
403
- query: "SELECT ticker, date, closingPrice FROM lake.daily_ohlc WHERE ticker = ?",
449
+ query:
450
+ "SELECT ticker, date, closingPrice FROM lake.daily_ohlc WHERE ticker = ?",
404
451
  params: ["AAPL"],
405
452
  limits: { maxRows: 10_000 },
406
453
  },
407
- { idempotencyKey: "aapl-daily-v1" },
454
+ { idempotencyKey: "aapl-daily-v1" }
408
455
  );
409
456
  const finished = await client.waitForLakeQuery(query.id as string);
410
457
  const manifest = await client.getLakeQueryManifest(finished.id as string);
411
458
  ```
412
459
 
460
+ ## Natural language
461
+
462
+ Describe the screen instead of writing the SQL. The server generates it,
463
+ validates it against the same `lake.*` catalog the engine reads, executes it,
464
+ and hands back both the rows and the statement.
465
+
466
+ ```ts
467
+ const screen = await client.createNlScreen(
468
+ "technology stocks with a market cap over 100 billion and a PE under 30"
469
+ );
470
+ const done = await client.waitForNlScreen(screen.id as string);
471
+
472
+ const result = done.result as Record<string, unknown>;
473
+ console.log(result.rows);
474
+ console.log(result.sql); // always check the SQL — it is model-generated
475
+ ```
476
+
477
+ `returnQuery` defaults to `true` because the SQL is the audit trail: without it
478
+ the rows are a number you cannot re-derive. It is returned on failure whatever
479
+ you pass, since a rejected query is the most useful thing to read.
480
+
481
+ Branch on `result.outcome`, not on status alone:
482
+
483
+ | `outcome` | Meaning |
484
+ | ------------------- | --------------------------------------------------------- |
485
+ | `ROWS` | Matches found |
486
+ | `EMPTY` | Every filter ran and nothing cleared them all — an answer |
487
+ | `CLARIFICATION` | The question was ambiguous; `result.clarification` asks |
488
+ | `GENERATION_FAILED` | The retry budget was spent — the only case worth retrying |
489
+
490
+ This method spends LLM credits. The structured `lake` API below does not.
491
+
413
492
  Use the manifest plus `downloadLakeQueryPart` to stream results within your own
414
493
  memory budget. NexusTrade picks a compatible backing engine for the referenced
415
494
  tables; your SQL does not change when it does.
@@ -424,94 +503,110 @@ is missing here, so this list cannot drift from the code.
424
503
 
425
504
  **Live trading and orders**
426
505
 
427
- | Method | Purpose |
428
- | --- | --- |
429
- | `listBrokerages()` | Every connectable brokerage and whether it is linked |
430
- | `getBrokerage(brokerage)` | Whether one brokerage is linked |
431
- | `connectBrokerage(brokerage, { wait })` | Log the connect URL and wait for the link |
432
- | `createOrders(portfolioId, orders, { idempotencyKey })` | Stage orders; live ones need approval |
506
+ | Method | Purpose |
507
+ | ------------------------------------------------------- | ---------------------------------------------------- |
508
+ | `listBrokerages()` | Every connectable brokerage and whether it is linked |
509
+ | `getBrokerage(brokerage)` | Whether one brokerage is linked |
510
+ | `connectBrokerage(brokerage, { wait })` | Log the connect URL and wait for the link |
511
+ | `createOrders(portfolioId, orders, { idempotencyKey })` | Stage orders; live ones need approval |
433
512
 
434
513
  **Portfolios**
435
514
 
436
- | Method | Purpose |
437
- | --- | --- |
438
- | `createPortfolio(book, { idempotencyKey })` | Persist a portfolio definition |
439
- | `listPortfolios(options)` | List portfolios, with filters and pagination |
440
- | `getPortfolio(portfolioId)` | Read one portfolio |
441
- | `deploy(portfolioId, { frequency })` | Start paper trading it |
442
- | `undeploy(portfolioId)` | Stop it |
515
+ | Method | Purpose |
516
+ | ------------------------------------------- | -------------------------------------------- |
517
+ | `createPortfolio(book, { idempotencyKey })` | Persist a portfolio definition |
518
+ | `listPortfolios(options)` | List portfolios, with filters and pagination |
519
+ | `getPortfolio(portfolioId)` | Read one portfolio |
520
+ | `deploy(portfolioId, { frequency })` | Start paper trading it |
521
+ | `undeploy(portfolioId)` | Stop it |
443
522
 
444
523
  **Backtests**
445
524
 
446
- | Method | Purpose |
447
- | --- | --- |
448
- | `createBacktest(handle, { idempotencyKey })` | Submit one backtest |
525
+ | Method | Purpose |
526
+ | ---------------------------------------------- | -------------------------- |
527
+ | `createBacktest(handle, { idempotencyKey })` | Submit one backtest |
449
528
  | `createBacktests(handles, { idempotencyKey })` | Submit many in one request |
450
- | `getBacktest(backtestId)` | Read the operation |
451
- | `waitForBacktest(backtestId, options)` | Block until terminal |
452
- | `waitForBacktests(operations, options)` | Block on a whole batch |
529
+ | `getBacktest(backtestId)` | Read the operation |
530
+ | `waitForBacktest(backtestId, options)` | Block until terminal |
531
+ | `waitForBacktests(operations, options)` | Block on a whole batch |
453
532
 
454
533
  **Optimization and walk-forward**
455
534
 
456
- | Method | Purpose |
457
- | --- | --- |
458
- | `createOptimization(handle, { idempotencyKey })` | Submit an optimization |
459
- | `getOptimization(optimizationId)` | Read the operation |
460
- | `waitForOptimization(optimizationId, options)` | Block until terminal |
461
- | `createWalkForward(handle, { idempotencyKey })` | Submit a walk-forward study |
462
- | `getWalkForward(studyId)` | Read the operation |
463
- | `waitForWalkForward(studyId, options)` | Block until terminal |
535
+ | Method | Purpose |
536
+ | ------------------------------------------------ | --------------------------- |
537
+ | `createOptimization(handle, { idempotencyKey })` | Submit an optimization |
538
+ | `getOptimization(optimizationId)` | Read the operation |
539
+ | `waitForOptimization(optimizationId, options)` | Block until terminal |
540
+ | `createWalkForward(handle, { idempotencyKey })` | Submit a walk-forward study |
541
+ | `getWalkForward(studyId)` | Read the operation |
542
+ | `waitForWalkForward(studyId, options)` | Block until terminal |
464
543
 
465
544
  **Custom data sources**
466
545
 
467
- | Method | Purpose |
468
- | --- | --- |
469
- | `createCustomIndicator(spec, { idempotencyKey })` | Create a series, optionally seeded |
470
- | `listCustomIndicators(options)` | List owned series |
471
- | `getCustomIndicator(id)` | Read one, with its point count and range |
472
- | `appendCustomIndicatorPoints(id, points, { idempotencyKey })` | Add points |
473
- | `createCustomIndicatorUpload(id, options)` | Open an upload slot (CSV/JSON/JSONL) |
474
- | `completeCustomIndicatorUpload(id, jobId)` | Start validating uploaded bytes |
475
- | `getCustomIndicatorUpload(id, jobId)` | Read the upload operation |
476
- | `waitForCustomIndicatorUpload(id, jobId, options)` | Block until validated |
546
+ | Method | Purpose |
547
+ | --------------------------------------------------------------------------- | -------------------------------------------------- |
548
+ | `createCustomIndicator(spec, { idempotencyKey })` | Create a series, optionally seeded |
549
+ | `listCustomIndicators(options)` | List owned series |
550
+ | `getCustomIndicator(id)` | Read one, with its point count and range |
551
+ | `appendCustomIndicatorPoints(id, points, { idempotencyKey })` | Add points |
552
+ | `replaceCustomIndicatorPoints(id, points, { idempotencyKey, allowShrink })` | Replace the complete series while retaining its id |
553
+ | `archiveCustomIndicator(id, { confirm })` | Soft-archive a series |
554
+ | `restoreCustomIndicator(id)` | Restore an archived series |
555
+ | `createCustomIndicatorUpload(id, options)` | Open an upload slot (CSV/JSON/JSONL) |
556
+ | `completeCustomIndicatorUpload(id, jobId)` | Start validating uploaded bytes |
557
+ | `getCustomIndicatorUpload(id, jobId)` | Read the upload operation |
558
+ | `waitForCustomIndicatorUpload(id, jobId, options)` | Block until validated |
477
559
 
478
560
  **Agent runs**
479
561
 
480
- | Method | Purpose |
481
- | --- | --- |
482
- | `createAgent(prompt, { idempotencyKey })` | Start a run |
483
- | `getAgent(agentId)` | Read its status |
484
- | `attachAgent(agentId, { cursor })` | Reattach to a run already in flight |
562
+ | Method | Purpose |
563
+ | ----------------------------------------- | ----------------------------------- |
564
+ | `createAgent(prompt, { idempotencyKey })` | Start a run |
565
+ | `getAgent(agentId)` | Read its status |
566
+ | `attachAgent(agentId, { cursor })` | Reattach to a run already in flight |
485
567
 
486
568
  **Lake SQL**
487
569
 
488
- | Method | Purpose |
489
- | --- | --- |
490
- | `createLakeQuery(request, { idempotencyKey })` | Submit read-only SQL |
491
- | `getLakeQuery(queryId)` | Read the operation |
492
- | `waitForLakeQuery(queryId, options)` | Block until terminal |
493
- | `cancelLakeQuery(queryId)` | Cancel an owned query |
494
- | `getLakeQueryManifest(queryId)` | Schema, checksums, and part metadata |
495
- | `downloadLakeQueryPart(queryId, part, options)` | Download one Parquet part |
496
- | `getLakeCatalog()` | List queryable tables |
497
- | `describeLakeTable(table)` | Columns and types for one table |
570
+ | Method | Purpose |
571
+ | ----------------------------------------------- | ------------------------------------ |
572
+ | `createLakeQuery(request, { idempotencyKey })` | Submit read-only SQL |
573
+ | `getLakeQuery(queryId)` | Read the operation |
574
+ | `waitForLakeQuery(queryId, options)` | Block until terminal |
575
+ | `cancelLakeQuery(queryId)` | Cancel an owned query |
576
+ | `createLakeAsk(question)` | Ask the lake in plain language |
577
+ | `getLakeAsk(askId)` | Read the operation |
578
+ | `waitForLakeAsk(askId, options)` | Block until terminal |
579
+ | `cancelLakeAsk(askId)` | Cancel an owned ask |
580
+ | `getLakeQueryManifest(queryId)` | Schema, checksums, and part metadata |
581
+ | `downloadLakeQueryPart(queryId, part, options)` | Download one Parquet part |
582
+ | `getLakeCatalog()` | List queryable tables |
583
+ | `describeLakeTable(table)` | Columns and types for one table |
584
+
585
+ **Natural language**
586
+
587
+ | Method | Purpose |
588
+ | ------------------------------------------- | ------------------------------------------- |
589
+ | `createNlScreen(question, { returnQuery })` | Screen stocks from a plain-language question |
590
+ | `getNlScreen(screenId)` | Read the operation |
591
+ | `waitForNlScreen(screenId, options)` | Block until terminal |
592
+ | `cancelNlScreen(screenId)` | Cancel an owned screen |
498
593
 
499
594
  **Client construction**
500
595
 
501
- | Method | Purpose |
502
- | --- | --- |
503
- | `new NexusTradeClient({ apiKey, baseUrl })` | Explicit credentials |
504
- | `NexusTradeClient.fromEnvironment()` | Read them from the environment or `.env` |
596
+ | Method | Purpose |
597
+ | ------------------------------------------- | ---------------------------------------- |
598
+ | `new NexusTradeClient({ apiKey, baseUrl })` | Explicit credentials |
599
+ | `NexusTradeClient.fromEnvironment()` | Read them from the environment or `.env` |
505
600
 
506
601
  **PortfolioHandle** — returned by the `portfolio(...)` builder and by
507
602
  `getPortfolio` / `listPortfolios`.
508
603
 
509
- | Method | Purpose |
510
- | --- | --- |
511
- | `save({ idempotencyKey })` | Persist it as a draft, setting `.id` |
512
- | `backtest({ startDate, endDate, idempotencyKey })` | Backtest it, preferring the saved id |
513
- | `deploy({ frequency })` | Mint the real paper portfolio (new id) |
514
- | `undeploy()` | Deactivate its deployment |
604
+ | Method | Purpose |
605
+ | -------------------------------------------------- | -------------------------------------- |
606
+ | `save({ idempotencyKey })` | Persist it as a draft, setting `.id` |
607
+ | `backtest({ startDate, endDate, idempotencyKey })` | Backtest it, preferring the saved id |
608
+ | `deploy({ frequency })` | Mint the real paper portfolio (new id) |
609
+ | `undeploy()` | Deactivate its deployment |
515
610
 
516
611
  ## Authentication
517
612
 
@@ -541,11 +636,11 @@ The real environment always wins — a `.env` value is used only when the variab
541
636
  is absent, so a stale file can never override what you exported. Nothing is
542
637
  written back to `process.env`. Opt out with `NEXUSTRADE_DISABLE_DOTENV=1`.
543
638
 
544
- | Scope | Grants |
545
- | --- | --- |
546
- | `read` | `getBacktest`, `getOptimization`, `getWalkForward` |
639
+ | Scope | Grants |
640
+ | ------- | --------------------------------------------------------------------------------- |
641
+ | `read` | `getBacktest`, `getOptimization`, `getWalkForward` |
547
642
  | `write` | `createPortfolio`, `createBacktest(s)`, `createOptimization`, `createWalkForward` |
548
- | `lake` | Lake catalog, query lifecycle, manifests, result parts |
643
+ | `lake` | Lake catalog, query lifecycle, manifests, result parts |
549
644
 
550
645
  A key missing the scope gets `403 insufficient_scope`.
551
646
 
@@ -577,23 +672,26 @@ import { NexusTradeApiError } from "nexustrade";
577
672
  try {
578
673
  await client.createBacktest(handle, { idempotencyKey: "run-1" });
579
674
  } catch (error) {
580
- if (error instanceof NexusTradeApiError && error.code === "rate_limit_exceeded") {
675
+ if (
676
+ error instanceof NexusTradeApiError &&
677
+ error.code === "rate_limit_exceeded"
678
+ ) {
581
679
  // back off
582
680
  }
583
681
  throw error;
584
682
  }
585
683
  ```
586
684
 
587
- | Status | Code | Meaning |
588
- | --- | --- | --- |
589
- | 401 | `invalid_token` | Missing, malformed, or expired key (or an OAuth JWT) |
590
- | 403 | `insufficient_scope` | Key lacks `read`, `write`, or `lake` |
591
- | 400 | `invalid_request`, `invalid_portfolio` | Malformed input |
592
- | 400 | `invalid_idempotency_key` | Must match `[A-Za-z0-9._:-]{1,160}` |
593
- | 409 | `idempotency_conflict` | Key reused with a different payload |
594
- | 409 | `idempotency_in_progress` | Same key, first call still running. Re-poll, do not resubmit |
595
- | 404 | `not_found`, `operation_not_found` | Unknown or not yours |
596
- | 429 | `rate_limit_exceeded` | Back off and retry |
685
+ | Status | Code | Meaning |
686
+ | ------ | -------------------------------------- | ------------------------------------------------------------ |
687
+ | 401 | `invalid_token` | Missing, malformed, or expired key (or an OAuth JWT) |
688
+ | 403 | `insufficient_scope` | Key lacks `read`, `write`, or `lake` |
689
+ | 400 | `invalid_request`, `invalid_portfolio` | Malformed input |
690
+ | 400 | `invalid_idempotency_key` | Must match `[A-Za-z0-9._:-]{1,160}` |
691
+ | 409 | `idempotency_conflict` | Key reused with a different payload |
692
+ | 409 | `idempotency_in_progress` | Same key, first call still running. Re-poll, do not resubmit |
693
+ | 404 | `not_found`, `operation_not_found` | Unknown or not yours |
694
+ | 429 | `rate_limit_exceeded` | Back off and retry |
597
695
 
598
696
  `status` is `0` when no HTTP status describes the failure: `transport_error`
599
697
  (never reached the API), `unsafe_redirect`, or an `invalid_response` envelope
@@ -603,7 +701,7 @@ check on an otherwise-successful reply.
603
701
 
604
702
  `new HttpTransport({ timeoutSeconds })` (default 30) is a total wall-clock
605
703
  deadline for one request. Neither it nor the poll timeout bounds how long a
606
- *job* takes.
704
+ _job_ takes.
607
705
 
608
706
  ## Scope
609
707