nexustrade 1.11.0 → 1.12.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
@@ -325,6 +325,49 @@ await client.listPortfolios({ includePaper: true, includePositions: true });
325
325
  await client.getPortfolio(portfolioId);
326
326
  ```
327
327
 
328
+ ### Editing a saved portfolio
329
+
330
+ `updatePortfolio` applies deterministic edits with no LLM in the path. The
331
+ `operations` array is a typed union, so the compiler knows which fields each
332
+ edit needs.
333
+
334
+ ```ts
335
+ import type { PortfolioEditOperation } from "nexustrade";
336
+
337
+ const operations: PortfolioEditOperation[] = [
338
+ { type: "rename", name: "AAPL Income" },
339
+ {
340
+ type: "replaceStrategy",
341
+ targetStrategyId: strategyId, // or targetStrategyName
342
+ strategyObject: nt.strategy(
343
+ "Buy AAPL",
344
+ nt.always(),
345
+ nt.buy(nt.stockAsset("AAPL"), 25, "percent of portfolio"),
346
+ {
347
+ orderExecution: nt.limitOrder({
348
+ price: nt.unitPriceLimit(150),
349
+ workingTime: nt.goodForDay(),
350
+ }),
351
+ },
352
+ ),
353
+ },
354
+ ];
355
+
356
+ await client.updatePortfolio(portfolioId, operations, {
357
+ idempotencyKey: "aapl-limit-v1",
358
+ });
359
+ ```
360
+
361
+ The five edits are `rename`, `addStrategies`, `removeStrategies`,
362
+ `replaceStrategy`, and `replaceStrategies`. Deploy, undeploy, delete,
363
+ scheduling, and trading-policy operations are not reachable on this route.
364
+
365
+ **`replaceStrategies` replaces the whole set**, so a strategy left out of the
366
+ array is deleted. Carry unchanged strategies through verbatim, including the
367
+ `orderExecution` each already has, or a working Limit silently reverts to
368
+ Market. `removeStrategies` takes strategy ids from a fetched portfolio; removal
369
+ by name is rejected.
370
+
328
371
  Fetched portfolio handles include a typed, read-only `policy` snapshot. Trading
329
372
  policy changes are intentionally unavailable through the SDK; edit them in
330
373
  Portfolio Settings. `PortfolioHandle.toJSON()` omits the snapshot so a fetched
@@ -25,6 +25,14 @@ function asJsonObject(value) {
25
25
  }
26
26
  return value;
27
27
  }
28
+ /**
29
+ * Boundary adapter, for the same reason `asJsonObject` exists: the operation
30
+ * members are `interface`s, which TypeScript denies the implicit index
31
+ * signature `JsonObject` requires. An operation is JSON by construction.
32
+ */
33
+ function editOperationAsJsonObject(operation) {
34
+ return { ...operation };
35
+ }
28
36
  function encodeQuery(params) {
29
37
  const search = new URLSearchParams();
30
38
  for (const [key, value] of Object.entries(params)) {
@@ -843,7 +851,7 @@ class NexusTradeClient {
843
851
  throw new Error("updatePortfolio needs at least one operation.");
844
852
  }
845
853
  const response = await this.transport.request("POST", `portfolios/${encodePathSegment(portfolioId)}/operations`, {
846
- body: { operations: operations.map((operation) => ({ ...operation })) },
854
+ body: { operations: operations.map(editOperationAsJsonObject) },
847
855
  idempotencyKey: options.idempotencyKey,
848
856
  });
849
857
  if (!isJsonObject(response.portfolio)) {
@@ -5,7 +5,7 @@
5
5
  * pass an API key/base URL, or set NEXUSTRADE_API_KEY / NEXUSTRADE_API_BASE_URL.
6
6
  */
7
7
  import { AgentRun } from "./agent.ts";
8
- import type { JobRequest, Portfolio } from "./generated/ntSdk.generated.js";
8
+ import type { JobRequest, Portfolio, Strategy } from "./generated/ntSdk.generated.js";
9
9
  import { PortfolioHandle, type DeployResult, type PortfolioListResult } from "./portfolio.ts";
10
10
  export type JsonValue = string | number | boolean | null | JsonValue[] | {
11
11
  [key: string]: JsonValue;
@@ -25,6 +25,59 @@ export type JsonObject = {
25
25
  */
26
26
  export type PortfolioInput = Portfolio | JsonObject;
27
27
  export type JobInput = JobRequest | JsonObject;
28
+ /**
29
+ * One deterministic portfolio edit, as accepted by
30
+ * `POST /portfolios/:id/operations`. The book is addressed by the
31
+ * `updatePortfolio` argument, so an operation never carries a portfolio id of
32
+ * its own — the route stamps it and ignores one sent in the body.
33
+ *
34
+ * Strategy payloads are FINISHED objects in the shape `strategy()` emits,
35
+ * `orderExecution` included. The server ingests them deterministically, with no
36
+ * LLM in the path; natural-language strategy strings are rejected.
37
+ */
38
+ export interface PortfolioRenameOperation {
39
+ type: "rename";
40
+ name: string;
41
+ }
42
+ /** Append strategies. Existing strategies and their open orders are untouched. */
43
+ export interface AddStrategiesOperation {
44
+ type: "addStrategies";
45
+ strategyObjects: Strategy[];
46
+ }
47
+ /**
48
+ * Remove strategies by id, as returned on a fetched portfolio's `strategies`.
49
+ * Removal by name is not supported.
50
+ */
51
+ export interface RemoveStrategiesOperation {
52
+ type: "removeStrategies";
53
+ strategyIds: string[];
54
+ }
55
+ /** Swap a single strategy. Exactly one of the two targets identifies it. */
56
+ export type ReplaceStrategyOperation = {
57
+ type: "replaceStrategy";
58
+ strategyObject: Strategy;
59
+ } & ({
60
+ targetStrategyId: string;
61
+ targetStrategyName?: never;
62
+ } | {
63
+ targetStrategyName: string;
64
+ targetStrategyId?: never;
65
+ });
66
+ /**
67
+ * Replace the whole strategy set. The array REPLACES the book, so a strategy
68
+ * left out is deleted — carry unchanged strategies through verbatim, including
69
+ * the `orderExecution` each already has.
70
+ */
71
+ export interface ReplaceStrategiesOperation {
72
+ type: "replaceStrategies";
73
+ strategyObjects: Strategy[];
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;
28
81
  export interface ListPortfoliosOptions {
29
82
  portfolioIds?: string[];
30
83
  includeInactive?: boolean;
@@ -211,7 +264,7 @@ export declare class NexusTradeClient {
211
264
  * Guest workspaces may rename and add/remove/replace strategies; deployment,
212
265
  * scheduling, policy, and trading operations remain account-only.
213
266
  */
214
- updatePortfolio(portfolioId: string, operations: ReadonlyArray<JsonObject>, options: {
267
+ updatePortfolio(portfolioId: string, operations: ReadonlyArray<PortfolioEditOperation>, options: {
215
268
  idempotencyKey: string;
216
269
  }): Promise<PortfolioHandle>;
217
270
  /** Fork a public/shared portfolio into this workspace as an editable copy. */
@@ -18,6 +18,14 @@ function asJsonObject(value) {
18
18
  }
19
19
  return value;
20
20
  }
21
+ /**
22
+ * Boundary adapter, for the same reason `asJsonObject` exists: the operation
23
+ * members are `interface`s, which TypeScript denies the implicit index
24
+ * signature `JsonObject` requires. An operation is JSON by construction.
25
+ */
26
+ function editOperationAsJsonObject(operation) {
27
+ return { ...operation };
28
+ }
21
29
  function encodeQuery(params) {
22
30
  const search = new URLSearchParams();
23
31
  for (const [key, value] of Object.entries(params)) {
@@ -833,7 +841,7 @@ export class NexusTradeClient {
833
841
  throw new Error("updatePortfolio needs at least one operation.");
834
842
  }
835
843
  const response = await this.transport.request("POST", `portfolios/${encodePathSegment(portfolioId)}/operations`, {
836
- body: { operations: operations.map((operation) => ({ ...operation })) },
844
+ body: { operations: operations.map(editOperationAsJsonObject) },
837
845
  idempotencyKey: options.idempotencyKey,
838
846
  });
839
847
  if (!isJsonObject(response.portfolio)) {
@@ -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 { BacktestCollateralStatistics, CustomIndicatorInput, CustomIndicatorPointInput, HttpTransportOptions, JsonObject, JsonValue, ListPortfoliosOptions, NexusTradeClientOptions, RequestOptions, Transport, UploadTransport, WaitOptions, WorkspaceSessionTransport, } from "./client.js";
4
+ export type { AddStrategiesOperation, BacktestCollateralStatistics, CustomIndicatorInput, CustomIndicatorPointInput, HttpTransportOptions, JsonObject, JsonValue, ListPortfoliosOptions, NexusTradeClientOptions, PortfolioEditOperation, 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.11.0",
3
+ "version": "1.12.0",
4
4
  "description": "Typed TypeScript SDK for NexusTrade portfolio authoring, backtesting, and optimization",
5
5
  "license": "MIT",
6
6
  "author": "Starks Technology",