nexustrade 1.34.0 → 1.36.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
@@ -145,6 +145,8 @@ For daily market prices, prefer `lake.query("sec_daily_ohlc", ...)` or the
145
145
  canonical OHLC helper. `daily_ohlc` is a legacy/vendor table and may lag the
146
146
  canonical daily series.
147
147
 
148
+ `client.listOrders({ portfolioId, statuses, page, limit })` lists owned orders with a read key. `client.cancelOrders(orderIds, { idempotencyKey, portfolioId })` cancels explicit IDs with a trade key. Inspect both `canceled` and `rejected`, and reuse the same key/payload for retries. Defaults and status gates are documented in README.
149
+
148
150
  ## Recipes
149
151
 
150
152
  <details open>
package/README.md CHANGED
@@ -508,6 +508,50 @@ approval. The brokerage boundary refuses an unapproved live order regardless of
508
508
  what any caller asks for, so this is a property of the system rather than a
509
509
  promise made by this method. At most 50 orders per request.
510
510
 
511
+ Listing requires a `read` key; cancellation requires a `trade` key. Both
512
+ require a registered account and are unavailable inside compute sandboxes.
513
+
514
+ ```ts
515
+ const page = await client.listOrders({
516
+ portfolioId,
517
+ statuses: ["Accepted", "Pending User Approval"],
518
+ page: 1,
519
+ limit: 50,
520
+ });
521
+ console.log(page.orders, page.totalPages);
522
+
523
+ // Cancel only explicit IDs you selected from the listing.
524
+ const cancellation = await client.cancelOrders(["ORDER_ID"], {
525
+ portfolioId,
526
+ idempotencyKey: "cancel-order-v1",
527
+ });
528
+ console.log(cancellation.canceled, cancellation.rejected);
529
+ ```
530
+
531
+ Listing defaults to `Accepted` and `Pending User Approval`. Request `Pending`,
532
+ `Partially Filled`, `Filled`, or `Canceled` explicitly to inspect other states.
533
+ Pages are 1-based, with a default limit of 50 and a maximum of 100. The response
534
+ includes `orders`, `total`, `returned`, `page`, `limit`, `totalPages`, `truncated`,
535
+ and `ignoredStatuses`; unknown statuses are reported there when valid statuses
536
+ remain, and a wholly invalid filter raises an error. Set
537
+ `includeRebalanceOrders: true`
538
+ for an additional page of pending rebalance actions. Their IDs are separate from
539
+ order IDs and cannot be passed to cancellation.
540
+
541
+ Cancellation accepts at most 50 IDs and returns `canceled` and `rejected` arrays.
542
+ Each success includes `orderId`, `mode` (`db`, `broker`, or `already_canceled`),
543
+ and `canceledOrderIds`, including sibling legs canceled together. Each rejection
544
+ includes `orderId` and `reason`. Inspect both arrays: HTTP success does not mean
545
+ every order was canceled. The optional portfolio ID guards against canceling an
546
+ order from another portfolio. Reuse the same idempotency key and identical
547
+ payload when retrying; an already canceled order returns `already_canceled`.
548
+
549
+ The same cancellation rules as MCP/REST apply: `Accepted` and
550
+ `Pending User Approval` orders can be canceled; `Pending`, `Partially Filled`,
551
+ and `Filled` orders are rejected. Rebalance children must be managed through
552
+ their parent action. Live orders with a broker ID invoke broker cancellation.
553
+ Creation still stages live orders for human approval.
554
+
511
555
  ## Your own data
512
556
 
513
557
  A custom data source is a time series you own — sentiment counts, a proprietary
@@ -716,6 +760,8 @@ is missing here, so this list cannot drift from the code.
716
760
  | `getBrokerage(brokerage)` | Whether one brokerage is linked |
717
761
  | `connectBrokerage(brokerage, { wait })` | Log the connect URL and wait for the link |
718
762
  | `createOrders(portfolioId, orders, { idempotencyKey })` | Stage orders; live ones need approval |
763
+ | `listOrders(options)` | List owned orders by portfolio/status, with pagination |
764
+ | `cancelOrders(orderIds, { idempotencyKey, portfolioId })` | Cancel explicit IDs with a result for each |
719
765
 
720
766
  **Portfolios**
721
767
 
@@ -1264,6 +1264,41 @@ class NexusTradeClient {
1264
1264
  idempotencyKey: options.idempotencyKey,
1265
1265
  });
1266
1266
  }
1267
+ /** List owned orders. Defaults to Accepted and Pending User Approval; pages are 1-based. */
1268
+ async listOrders(options = {}) {
1269
+ if (options.statuses !== undefined && options.statuses.length === 0) {
1270
+ throw new Error("statuses must be a non-empty array.");
1271
+ }
1272
+ const query = encodeQuery({
1273
+ portfolioId: options.portfolioId,
1274
+ statuses: options.statuses?.join(","),
1275
+ page: options.page === undefined ? undefined : String(options.page),
1276
+ limit: options.limit === undefined ? undefined : String(options.limit),
1277
+ includeRebalanceOrders: options.includeRebalanceOrders === undefined
1278
+ ? undefined
1279
+ : String(options.includeRebalanceOrders),
1280
+ });
1281
+ return this.transport.request("GET", `orders${query}`);
1282
+ }
1283
+ /** Cancel explicit order IDs; inspect both canceled and rejected. Live cancellation reaches the broker. */
1284
+ async cancelOrders(orderIds, options) {
1285
+ if (!Array.isArray(orderIds) ||
1286
+ orderIds.length === 0 ||
1287
+ orderIds.some((id) => typeof id !== "string" || !id.trim())) {
1288
+ throw new Error("orderIds must be a non-empty array of non-empty strings.");
1289
+ }
1290
+ if (orderIds.length > 50)
1291
+ throw new Error("at most 50 orders may be canceled per request.");
1292
+ return this.transport.request("POST", "orders/cancel", {
1293
+ body: {
1294
+ orderIds: [...orderIds],
1295
+ ...(options.portfolioId === undefined
1296
+ ? {}
1297
+ : { portfolioId: options.portfolioId }),
1298
+ },
1299
+ idempotencyKey: options.idempotencyKey,
1300
+ });
1301
+ }
1267
1302
  async createBacktests(backtests, options) {
1268
1303
  const inputs = backtests.map((item) => backtestInput(asJsonObject(item)));
1269
1304
  const response = await this.transport.request("POST", "backtests/batch", {
@@ -1069,9 +1069,9 @@ function InitialValue() {
1069
1069
  /**
1070
1070
  * InsiderTrades indicator.
1071
1071
  * @param asset Pass CANDIDATE in a dynamic rebalance pipeline.
1072
- * @param ownerCik Exact nonzero SEC reporting owner CIK, up to 10 digits. Omit for aggregate activity.
1073
- * @param issuerCik Restrict an exact owner to this company CIK; omit to follow them across companies.
1074
- * @param instrument Disclosed instrument; defaults to Equity. Call/Put, award and acquisition metrics, and budget shares require ownerCik. AwardCount is SEC code A issuer acquisitions, not cash purchases or vested-share proof. Its default Equity bucket includes unresolved restricted units. AcquisitionCount and AcquisitionSharePercent combine public code P purchases with code A issuer acquisitions. Shares use qualifying signal counts across all the owner's tickers.
1072
+ * @param ownerCik Exact nonzero SEC reporting owner CIK, up to 10 digits. Omit for a whole company (with issuerCik) or aggregate activity.
1073
+ * @param issuerCik Company CIK. With ownerCik, restricts that owner to this company. Alone, every reporting owner's events at this company, a joint filing counted once.
1074
+ * @param instrument Disclosed instrument; defaults to Equity. Call/Put, award and acquisition metrics, and budget shares require ownerCik or issuerCik. AwardCount is SEC code A issuer acquisitions, not cash purchases or vested-share proof. Its default Equity bucket includes unresolved restricted units. AcquisitionCount and AcquisitionSharePercent combine public code P purchases with code A issuer acquisitions. Shares use qualifying signal counts across all the owner's tickers, or all the company's tickers under issuerCik alone.
1075
1075
  */
1076
1076
  function InsiderTrades(asset, metric, role, windowDays, ownerCik, issuerCik, instrument) {
1077
1077
  const d = { type: "InsiderTrades" };
@@ -1453,11 +1453,11 @@ function Negative(operand) {
1453
1453
  }
1454
1454
  /**
1455
1455
  * NewInsiderDisclosure indicator.
1456
- * @param ownerCik Exact SEC reporting owner CIK. Omit for aggregate Form 4 activity.
1457
- * @param issuerCik Optional company CIK; requires ownerCik.
1456
+ * @param ownerCik Exact SEC reporting owner CIK. Omit for a whole company (with issuerCik) or aggregate Form 4 activity.
1457
+ * @param issuerCik Company CIK. With ownerCik, restricts that owner; alone, every reporting owner at this company, a joint filing once.
1458
1458
  * @param role The reporting owner's role.
1459
- * @param instrument Call and Put require ownerCik.
1460
- * @param disclosureAction Which newly public Form 4 action triggers a decision. Award requires ownerCik.
1459
+ * @param instrument Call and Put require ownerCik or issuerCik.
1460
+ * @param disclosureAction Which newly public Form 4 action triggers a decision. Award requires ownerCik or issuerCik.
1461
1461
  */
1462
1462
  function NewInsiderDisclosure(ownerCik, issuerCik, role = "Any", instrument = "Equity", disclosureAction = "Any") {
1463
1463
  const d = { type: "NewInsiderDisclosure" };
@@ -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, Strategy } from "./generated/ntSdk.generated.js";
8
+ import type { JobRequest, OrderStatus, 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;
@@ -78,6 +78,13 @@ export interface ReplaceStrategiesOperation {
78
78
  * this route, so typing them here would only compile a guaranteed 403.
79
79
  */
80
80
  export type PortfolioEditOperation = PortfolioRenameOperation | AddStrategiesOperation | RemoveStrategiesOperation | ReplaceStrategyOperation | ReplaceStrategiesOperation;
81
+ export interface ListOrdersOptions {
82
+ portfolioId?: string;
83
+ statuses?: ReadonlyArray<OrderStatus>;
84
+ page?: number;
85
+ limit?: number;
86
+ includeRebalanceOrders?: boolean;
87
+ }
81
88
  export interface ListPortfoliosOptions {
82
89
  portfolioIds?: string[];
83
90
  includeInactive?: boolean;
@@ -419,6 +426,13 @@ export declare class NexusTradeClient {
419
426
  createOrders(portfolioId: string, orders: ReadonlyArray<JsonObject>, options: {
420
427
  idempotencyKey: string;
421
428
  }): Promise<JsonObject>;
429
+ /** List owned orders. Defaults to Accepted and Pending User Approval; pages are 1-based. */
430
+ listOrders(options?: ListOrdersOptions): Promise<JsonObject>;
431
+ /** Cancel explicit order IDs; inspect both canceled and rejected. Live cancellation reaches the broker. */
432
+ cancelOrders(orderIds: ReadonlyArray<string>, options: {
433
+ idempotencyKey: string;
434
+ portfolioId?: string;
435
+ }): Promise<JsonObject>;
422
436
  createBacktests(backtests: ReadonlyArray<JobInput>, options: {
423
437
  idempotencyKey: string;
424
438
  }): Promise<JsonObject[]>;
@@ -1254,6 +1254,41 @@ export class NexusTradeClient {
1254
1254
  idempotencyKey: options.idempotencyKey,
1255
1255
  });
1256
1256
  }
1257
+ /** List owned orders. Defaults to Accepted and Pending User Approval; pages are 1-based. */
1258
+ async listOrders(options = {}) {
1259
+ if (options.statuses !== undefined && options.statuses.length === 0) {
1260
+ throw new Error("statuses must be a non-empty array.");
1261
+ }
1262
+ const query = encodeQuery({
1263
+ portfolioId: options.portfolioId,
1264
+ statuses: options.statuses?.join(","),
1265
+ page: options.page === undefined ? undefined : String(options.page),
1266
+ limit: options.limit === undefined ? undefined : String(options.limit),
1267
+ includeRebalanceOrders: options.includeRebalanceOrders === undefined
1268
+ ? undefined
1269
+ : String(options.includeRebalanceOrders),
1270
+ });
1271
+ return this.transport.request("GET", `orders${query}`);
1272
+ }
1273
+ /** Cancel explicit order IDs; inspect both canceled and rejected. Live cancellation reaches the broker. */
1274
+ async cancelOrders(orderIds, options) {
1275
+ if (!Array.isArray(orderIds) ||
1276
+ orderIds.length === 0 ||
1277
+ orderIds.some((id) => typeof id !== "string" || !id.trim())) {
1278
+ throw new Error("orderIds must be a non-empty array of non-empty strings.");
1279
+ }
1280
+ if (orderIds.length > 50)
1281
+ throw new Error("at most 50 orders may be canceled per request.");
1282
+ return this.transport.request("POST", "orders/cancel", {
1283
+ body: {
1284
+ orderIds: [...orderIds],
1285
+ ...(options.portfolioId === undefined
1286
+ ? {}
1287
+ : { portfolioId: options.portfolioId }),
1288
+ },
1289
+ idempotencyKey: options.idempotencyKey,
1290
+ });
1291
+ }
1257
1292
  async createBacktests(backtests, options) {
1258
1293
  const inputs = backtests.map((item) => backtestInput(asJsonObject(item)));
1259
1294
  const response = await this.transport.request("POST", "backtests/batch", {
@@ -504,7 +504,7 @@ export type FundamentalMetric = "totalRevenue" | "grossProfit" | "operatingIncom
504
504
  export type PositionEffect = "open" | "close";
505
505
  export type OrderStatus = "Pending" | "Accepted" | "Pending User Approval" | "Canceled" | "Filled" | "Partially Filled";
506
506
  export type Side = "Buy" | "Sell";
507
- export type Role = "Any" | "Officer" | "Director" | "TenPercentOwner";
507
+ export type Role = "Any" | "Officer" | "Director" | "TenPercentOwner" | "OfficerOrDirector";
508
508
  export type Instrument = "Equity" | "Call" | "Put";
509
509
  export type Instrument2 = "Equity" | "Option";
510
510
  export type MinOrMax = "min" | "max";
@@ -1020,9 +1020,9 @@ export declare function InitialValue(): Indicator;
1020
1020
  /**
1021
1021
  * InsiderTrades indicator.
1022
1022
  * @param asset Pass CANDIDATE in a dynamic rebalance pipeline.
1023
- * @param ownerCik Exact nonzero SEC reporting owner CIK, up to 10 digits. Omit for aggregate activity.
1024
- * @param issuerCik Restrict an exact owner to this company CIK; omit to follow them across companies.
1025
- * @param instrument Disclosed instrument; defaults to Equity. Call/Put, award and acquisition metrics, and budget shares require ownerCik. AwardCount is SEC code A issuer acquisitions, not cash purchases or vested-share proof. Its default Equity bucket includes unresolved restricted units. AcquisitionCount and AcquisitionSharePercent combine public code P purchases with code A issuer acquisitions. Shares use qualifying signal counts across all the owner's tickers.
1023
+ * @param ownerCik Exact nonzero SEC reporting owner CIK, up to 10 digits. Omit for a whole company (with issuerCik) or aggregate activity.
1024
+ * @param issuerCik Company CIK. With ownerCik, restricts that owner to this company. Alone, every reporting owner's events at this company, a joint filing counted once.
1025
+ * @param instrument Disclosed instrument; defaults to Equity. Call/Put, award and acquisition metrics, and budget shares require ownerCik or issuerCik. AwardCount is SEC code A issuer acquisitions, not cash purchases or vested-share proof. Its default Equity bucket includes unresolved restricted units. AcquisitionCount and AcquisitionSharePercent combine public code P purchases with code A issuer acquisitions. Shares use qualifying signal counts across all the owner's tickers, or all the company's tickers under issuerCik alone.
1026
1026
  */
1027
1027
  export declare function InsiderTrades(asset: AssetArg, metric: "NetValue" | "BuyValue" | "SellValue" | "NetShares" | "BuyCount" | "SellCount" | "AwardCount" | "AcquisitionCount" | "DistinctBuyers" | "PurchaseSharePercent" | "AcquisitionSharePercent", role: Role, windowDays: number, ownerCik?: string, issuerCik?: string, instrument?: Instrument): Indicator;
1028
1028
  /**
@@ -1226,11 +1226,11 @@ export declare function Multiply(left: Indicator, right: Indicator): Indicator;
1226
1226
  export declare function Negative(operand: Indicator): Indicator;
1227
1227
  /**
1228
1228
  * NewInsiderDisclosure indicator.
1229
- * @param ownerCik Exact SEC reporting owner CIK. Omit for aggregate Form 4 activity.
1230
- * @param issuerCik Optional company CIK; requires ownerCik.
1229
+ * @param ownerCik Exact SEC reporting owner CIK. Omit for a whole company (with issuerCik) or aggregate Form 4 activity.
1230
+ * @param issuerCik Company CIK. With ownerCik, restricts that owner; alone, every reporting owner at this company, a joint filing once.
1231
1231
  * @param role The reporting owner's role.
1232
- * @param instrument Call and Put require ownerCik.
1233
- * @param disclosureAction Which newly public Form 4 action triggers a decision. Award requires ownerCik.
1232
+ * @param instrument Call and Put require ownerCik or issuerCik.
1233
+ * @param disclosureAction Which newly public Form 4 action triggers a decision. Award requires ownerCik or issuerCik.
1234
1234
  */
1235
1235
  export declare function NewInsiderDisclosure(ownerCik?: string, issuerCik?: string, role?: Role, instrument?: Instrument, disclosureAction?: "Any" | "Purchase" | "Sale" | "Award"): Indicator;
1236
1236
  /**
@@ -869,9 +869,9 @@ export function InitialValue() {
869
869
  /**
870
870
  * InsiderTrades indicator.
871
871
  * @param asset Pass CANDIDATE in a dynamic rebalance pipeline.
872
- * @param ownerCik Exact nonzero SEC reporting owner CIK, up to 10 digits. Omit for aggregate activity.
873
- * @param issuerCik Restrict an exact owner to this company CIK; omit to follow them across companies.
874
- * @param instrument Disclosed instrument; defaults to Equity. Call/Put, award and acquisition metrics, and budget shares require ownerCik. AwardCount is SEC code A issuer acquisitions, not cash purchases or vested-share proof. Its default Equity bucket includes unresolved restricted units. AcquisitionCount and AcquisitionSharePercent combine public code P purchases with code A issuer acquisitions. Shares use qualifying signal counts across all the owner's tickers.
872
+ * @param ownerCik Exact nonzero SEC reporting owner CIK, up to 10 digits. Omit for a whole company (with issuerCik) or aggregate activity.
873
+ * @param issuerCik Company CIK. With ownerCik, restricts that owner to this company. Alone, every reporting owner's events at this company, a joint filing counted once.
874
+ * @param instrument Disclosed instrument; defaults to Equity. Call/Put, award and acquisition metrics, and budget shares require ownerCik or issuerCik. AwardCount is SEC code A issuer acquisitions, not cash purchases or vested-share proof. Its default Equity bucket includes unresolved restricted units. AcquisitionCount and AcquisitionSharePercent combine public code P purchases with code A issuer acquisitions. Shares use qualifying signal counts across all the owner's tickers, or all the company's tickers under issuerCik alone.
875
875
  */
876
876
  export function InsiderTrades(asset, metric, role, windowDays, ownerCik, issuerCik, instrument) {
877
877
  const d = { type: "InsiderTrades" };
@@ -1253,11 +1253,11 @@ export function Negative(operand) {
1253
1253
  }
1254
1254
  /**
1255
1255
  * NewInsiderDisclosure indicator.
1256
- * @param ownerCik Exact SEC reporting owner CIK. Omit for aggregate Form 4 activity.
1257
- * @param issuerCik Optional company CIK; requires ownerCik.
1256
+ * @param ownerCik Exact SEC reporting owner CIK. Omit for a whole company (with issuerCik) or aggregate Form 4 activity.
1257
+ * @param issuerCik Company CIK. With ownerCik, restricts that owner; alone, every reporting owner at this company, a joint filing once.
1258
1258
  * @param role The reporting owner's role.
1259
- * @param instrument Call and Put require ownerCik.
1260
- * @param disclosureAction Which newly public Form 4 action triggers a decision. Award requires ownerCik.
1259
+ * @param instrument Call and Put require ownerCik or issuerCik.
1260
+ * @param disclosureAction Which newly public Form 4 action triggers a decision. Award requires ownerCik or issuerCik.
1261
1261
  */
1262
1262
  export function NewInsiderDisclosure(ownerCik, issuerCik, role = "Any", instrument = "Equity", disclosureAction = "Any") {
1263
1263
  const d = { type: "NewInsiderDisclosure" };
@@ -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, 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, 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.34.0",
3
+ "version": "1.36.0",
4
4
  "description": "Typed TypeScript SDK for NexusTrade portfolio authoring, backtesting, and optimization",
5
5
  "license": "MIT",
6
6
  "author": "Starks Technology",