nexustrade 0.4.0 → 1.1.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.
@@ -1,9 +1,8 @@
1
1
  /**
2
2
  * Typed NexusTrade JSON API client.
3
3
  *
4
- * Mirrors the Python client method-for-method; `verifyNtSdk.ts` asserts the two
5
- * surfaces stay identical. Transport-generic: callers pass an API key/base URL,
6
- * or set NEXUSTRADE_API_KEY / NEXUSTRADE_API_BASE_URL.
4
+ * Method names and behavior match the Python SDK. Transport-generic: callers
5
+ * pass an API key/base URL, or set NEXUSTRADE_API_KEY / NEXUSTRADE_API_BASE_URL.
7
6
  */
8
7
  import { AgentRun } from "./agent.ts";
9
8
  import type { JobRequest, Portfolio } from "./generated/ntSdk.generated.js";
@@ -42,6 +41,8 @@ export declare const DEFAULT_POLL_TIMEOUT_SECONDS = 900;
42
41
  export declare const DEFAULT_POLL_INTERVAL_SECONDS = 2;
43
42
  export declare const MAX_POLL_INTERVAL_SECONDS = 15;
44
43
  export declare const POLL_BACKOFF_FACTOR = 1.5;
44
+ export declare const DEFAULT_CONNECT_TIMEOUT_SECONDS = 300;
45
+ export declare const CONNECT_POLL_INTERVAL_SECONDS = 3;
45
46
  export declare class NexusTradeApiError extends Error {
46
47
  readonly status: number;
47
48
  readonly code: string;
@@ -74,15 +75,29 @@ export interface BinaryTransport extends Transport {
74
75
  maxBytes?: number;
75
76
  }): Promise<Uint8Array>;
76
77
  }
78
+ /**
79
+ * Transports that can PUT bytes to a presigned storage URL.
80
+ *
81
+ * The URL is absolute and the call carries no credential.
82
+ */
83
+ export interface UploadTransport extends Transport {
84
+ putBytes(url: string, data: Uint8Array<ArrayBuffer>, options: {
85
+ contentType: string;
86
+ }): Promise<void>;
87
+ }
77
88
  export interface HttpTransportOptions {
78
89
  apiKey: string;
79
90
  baseUrl: string;
80
91
  timeoutSeconds?: number;
81
92
  }
82
- export declare class HttpTransport implements Transport {
93
+ export declare class HttpTransport implements Transport, UploadTransport {
83
94
  #private;
84
95
  constructor(options: HttpTransportOptions);
85
96
  get baseUrl(): string;
97
+ /** PUT a payload to a presigned storage URL. Sends no credential. */
98
+ putBytes(url: string, data: Uint8Array<ArrayBuffer>, options: {
99
+ contentType: string;
100
+ }): Promise<void>;
86
101
  request(method: string, path: string, options?: RequestOptions): Promise<JsonObject>;
87
102
  }
88
103
  export interface NexusTradeClientOptions {
@@ -108,6 +123,20 @@ export interface WaitOptions {
108
123
  * false. Transport errors from `fetch` propagate — a poller that swallowed
109
124
  * them would report an infrastructure outage as a still-running job.
110
125
  */
126
+ export interface CustomIndicatorPointInput {
127
+ timestamp: string | Date;
128
+ value: number;
129
+ ticker?: string;
130
+ assetType?: string;
131
+ availableAt?: string | Date;
132
+ [field: string]: unknown;
133
+ }
134
+ export interface CustomIndicatorInput {
135
+ name: string;
136
+ description?: string;
137
+ scope?: "global" | "asset";
138
+ points?: ReadonlyArray<CustomIndicatorPointInput>;
139
+ }
111
140
  export declare function waitForOperation(fetch: (operationId: string) => Promise<JsonObject>, operationId: string, options?: WaitOptions): Promise<JsonObject>;
112
141
  export declare class NexusTradeClient {
113
142
  private readonly transport;
@@ -117,7 +146,7 @@ export declare class NexusTradeClient {
117
146
  idempotencyKey: string;
118
147
  }): Promise<JsonObject>;
119
148
  /**
120
- * List portfolios. Mirrors MCP `fetch_portfolios` (boolean includes, page/limit).
149
+ * List portfolios with optional filters and pagination.
121
150
  * `includePositions` defaults off when `search` is set.
122
151
  */
123
152
  listPortfolios(options?: ListPortfoliosOptions): Promise<PortfolioListResult>;
@@ -127,6 +156,129 @@ export declare class NexusTradeClient {
127
156
  frequency?: string;
128
157
  }): Promise<DeployResult>;
129
158
  undeploy(portfolioId: string): Promise<JsonObject>;
159
+ /**
160
+ * Create a custom data source and return it, including its id.
161
+ *
162
+ * `scope` is `"global"` (one series) or `"asset"` (one series per ticker, so
163
+ * every point needs a `ticker`); it defaults to `"global"` and cannot be
164
+ * changed later. `points` is optional and unlimited in size — small batches
165
+ * are sent with the request, larger ones are uploaded, and the returned
166
+ * indicator reflects what landed either way.
167
+ *
168
+ * The id it returns is what a `CustomIndicator` node binds to:
169
+ *
170
+ * ```ts
171
+ * const series = await client.createCustomIndicator(
172
+ * {
173
+ * name: "WSB NVDA Mentions",
174
+ * scope: "asset",
175
+ * points: [{ timestamp: "2024-04-01", value: 152, ticker: "NVDA" }],
176
+ * },
177
+ * { idempotencyKey: "wsb-mentions-v1" },
178
+ * );
179
+ * CustomIndicator(stockAsset("NVDA"), String(series.customIndicatorId));
180
+ * ```
181
+ *
182
+ * Retrying with the same `idempotencyKey` returns the original series rather
183
+ * than creating a second one.
184
+ */
185
+ createCustomIndicator(indicator: CustomIndicatorInput, options: {
186
+ idempotencyKey: string;
187
+ }): Promise<JsonObject>;
188
+ /** List the custom data sources this account owns. */
189
+ listCustomIndicators(options?: {
190
+ includeArchived?: boolean;
191
+ }): Promise<JsonObject[]>;
192
+ /** Read one custom data source, including its current point count. */
193
+ getCustomIndicator(customIndicatorId: string): Promise<JsonObject>;
194
+ /**
195
+ * Add points to an existing series and return the updated indicator.
196
+ *
197
+ * Recurring collection must append to the same `customIndicatorId` every
198
+ * run; creating a fresh series per run splits the history into fragments a
199
+ * strategy cannot read. Re-sending an identical batch is safe — the
200
+ * duplicate is not written twice.
201
+ *
202
+ * The batch is unlimited in size and, as with creation, is sent inline or
203
+ * uploaded depending on how large it is.
204
+ */
205
+ appendCustomIndicatorPoints(customIndicatorId: string, points: ReadonlyArray<CustomIndicatorPointInput>, options: {
206
+ idempotencyKey: string;
207
+ }): Promise<JsonObject>;
208
+ /**
209
+ * Open an upload slot and return a presigned `uploadUrl` to PUT to.
210
+ *
211
+ * Accepts `csv`, `json`, or `jsonl` up to 100 MB. PUT the bytes to the
212
+ * returned URL, then call `completeCustomIndicatorUpload`. Most callers can
213
+ * pass `points` to `createCustomIndicator` or
214
+ * `appendCustomIndicatorPoints` instead and skip all three steps.
215
+ *
216
+ * Retrying with the same `idempotencyKey` re-signs the same job, since the
217
+ * first URL expires in 15 minutes. Once its bytes have arrived the reply
218
+ * carries no `uploadUrl` — there is nothing left to send, so skip the PUT
219
+ * and wait on `jobId`.
220
+ */
221
+ createCustomIndicatorUpload(customIndicatorId: string, options: {
222
+ fileName: string;
223
+ idempotencyKey: string;
224
+ format?: "csv" | "json" | "jsonl";
225
+ contentType?: string;
226
+ sizeBytes?: number;
227
+ }): Promise<JsonObject>;
228
+ /** Start validation of uploaded bytes and return the operation. */
229
+ completeCustomIndicatorUpload(customIndicatorId: string, jobId: string): Promise<JsonObject>;
230
+ /** Read an upload operation. `phase` distinguishes the live states. */
231
+ getCustomIndicatorUpload(customIndicatorId: string, jobId: string): Promise<JsonObject>;
232
+ /** Block until an upload is validated. See `waitForOperation`. */
233
+ waitForCustomIndicatorUpload(customIndicatorId: string, jobId: string, options?: WaitOptions): Promise<JsonObject>;
234
+ private uploadCustomIndicatorPoints;
235
+ /**
236
+ * Every connectable brokerage and whether this account has linked it.
237
+ *
238
+ * Reports all of them, connected or not, each with a `connectUrl` — an empty
239
+ * result would say nothing about what to do next.
240
+ */
241
+ listBrokerages(): Promise<JsonObject[]>;
242
+ /** Whether one named brokerage is connected. */
243
+ getBrokerage(brokerage: string): Promise<JsonObject>;
244
+ /**
245
+ * Resolve once the brokerage is connected, logging where to connect it.
246
+ *
247
+ * Linking a brokerage is an OAuth redirect, so an API key cannot complete it
248
+ * — a human has to open the URL. What this does is make that unmissable and
249
+ * then wait for it.
250
+ *
251
+ * `wait` defaults to whether stdout is a TTY. Interactively it logs the URL
252
+ * and polls until the link appears. Non-interactively — CI, cron, a piped
253
+ * script — it rejects with `brokerage_not_connected` at once rather than
254
+ * stalling for the timeout in front of nobody. Pass `wait` to override.
255
+ */
256
+ connectBrokerage(brokerage: string, options?: {
257
+ wait?: boolean;
258
+ timeoutSeconds?: number;
259
+ pollIntervalSeconds?: number;
260
+ }): Promise<JsonObject>;
261
+ /**
262
+ * Stage orders against a portfolio.
263
+ *
264
+ * **Paper orders are accepted immediately. Live orders are staged for
265
+ * approval and are never sent to a broker by this call.** A live response
266
+ * carries `requiresApproval: true` and an `approvalUrl`; nothing has traded
267
+ * until a human approves it there. No argument changes that.
268
+ *
269
+ * ```ts
270
+ * const result = await client.createOrders(
271
+ * portfolioId,
272
+ * [{ asset: { name: "SPY", type: "STOCK", symbol: "SPY" },
273
+ * side: "BUY", quantity: 10, orderType: "MARKET" }],
274
+ * { idempotencyKey: "rebalance-2024-04-01" },
275
+ * );
276
+ * if (result.requiresApproval) console.log("approve at", result.approvalUrl);
277
+ * ```
278
+ */
279
+ createOrders(portfolioId: string, orders: ReadonlyArray<JsonObject>, options: {
280
+ idempotencyKey: string;
281
+ }): Promise<JsonObject>;
130
282
  createBacktests(backtests: ReadonlyArray<JobInput>, options: {
131
283
  idempotencyKey: string;
132
284
  }): Promise<JsonObject[]>;
@@ -192,6 +344,11 @@ export declare class NexusTradeClient {
192
344
  /** @internal PortfolioHandle lazy-client attachment. */
193
345
  export declare function clientTransport(client: NexusTradeClient): Transport;
194
346
  /** Convenience wrapper for scripts that do not need a persistent client. */
347
+ export declare function createCustomIndicator(indicator: CustomIndicatorInput, options: {
348
+ idempotencyKey: string;
349
+ client?: NexusTradeClient;
350
+ }): Promise<JsonObject>;
351
+ /** Convenience wrapper for scripts that do not need a persistent client. */
195
352
  export declare function createPortfolio(portfolio: JsonObject, options: {
196
353
  idempotencyKey: string;
197
354
  client?: NexusTradeClient;