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.
- package/AGENTS.md +64 -14
- package/README.md +361 -14
- package/dist/cjs/agent.js +12 -6
- package/dist/cjs/client.js +403 -14
- package/dist/cjs/index.js +2 -1
- package/dist/cjs/portfolio.js +1 -3
- package/dist/esm/agent.d.ts +2 -5
- package/dist/esm/agent.js +12 -6
- package/dist/esm/client.d.ts +162 -5
- package/dist/esm/client.js +401 -13
- package/dist/esm/index.d.ts +2 -2
- package/dist/esm/index.js +1 -1
- package/dist/esm/portfolio.d.ts +1 -3
- package/dist/esm/portfolio.js +1 -3
- package/package.json +1 -1
package/dist/esm/client.d.ts
CHANGED
|
@@ -1,9 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Typed NexusTrade JSON API client.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
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
|
|
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;
|