nexustrade 0.1.0 → 0.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 +27 -1
- package/dist/cjs/agent.js +223 -0
- package/dist/cjs/client.js +175 -23
- package/dist/cjs/env.js +28 -2
- package/dist/cjs/generated/ntSdk.generated.js +2 -4
- package/dist/cjs/index.js +6 -1
- package/dist/cjs/portfolio.js +300 -0
- package/dist/esm/agent.d.ts +86 -0
- package/dist/esm/agent.js +219 -0
- package/dist/esm/client.d.ts +52 -0
- package/dist/esm/client.js +160 -9
- package/dist/esm/env.d.ts +16 -1
- package/dist/esm/env.js +26 -2
- package/dist/esm/generated/ntSdk.generated.d.ts +2 -1
- package/dist/esm/generated/ntSdk.generated.js +2 -4
- package/dist/esm/index.d.ts +5 -1
- package/dist/esm/index.js +2 -0
- package/dist/esm/portfolio.d.ts +89 -0
- package/dist/esm/portfolio.js +262 -0
- package/package.json +1 -1
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* PortfolioHandle — one object you author, save, deploy, fetch, and backtest.
|
|
3
|
+
*
|
|
4
|
+
* Keeps the generated `Portfolio` interface as the shape; this class adds
|
|
5
|
+
* lifecycle methods. `toJSON()` omits `id` so request bodies never leak
|
|
6
|
+
* `"id": null`. Mirrors `portfolio_handle.py`.
|
|
7
|
+
*
|
|
8
|
+
* Holds a `Transport` (same pattern as `AgentRun`) so the generated builder can
|
|
9
|
+
* import this module without a cycle through `client.ts`.
|
|
10
|
+
*
|
|
11
|
+
* See designs/2026-07-26-sdk-portfolio-objects.md.
|
|
12
|
+
*/
|
|
13
|
+
import { NexusTradeApiError, NO_HTTP_STATUS, } from "./client.js";
|
|
14
|
+
function isJsonObject(value) {
|
|
15
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
16
|
+
}
|
|
17
|
+
function encodePathSegment(value) {
|
|
18
|
+
return encodeURIComponent(value);
|
|
19
|
+
}
|
|
20
|
+
/** Runtime portfolio object. Implements the generated `Portfolio` shape. */
|
|
21
|
+
export class PortfolioHandle {
|
|
22
|
+
name;
|
|
23
|
+
initialValue;
|
|
24
|
+
strategies;
|
|
25
|
+
main;
|
|
26
|
+
supportsFractionalShares;
|
|
27
|
+
supportsCrypto;
|
|
28
|
+
alertsEnabled;
|
|
29
|
+
/** Chat draft id after `save()`, or fetched portfolio id. Not serialized. */
|
|
30
|
+
id = null;
|
|
31
|
+
/** Present on list/get summaries: paper | live | chat. */
|
|
32
|
+
type;
|
|
33
|
+
isActive;
|
|
34
|
+
strategyNames;
|
|
35
|
+
createdAt;
|
|
36
|
+
updatedAt;
|
|
37
|
+
brokerage;
|
|
38
|
+
#transport;
|
|
39
|
+
constructor(data, options = {}) {
|
|
40
|
+
const record = { ...data };
|
|
41
|
+
const wireId = options.id ??
|
|
42
|
+
(typeof record.portfolioId === "string" ? record.portfolioId : null) ??
|
|
43
|
+
(typeof record.id === "string" ? record.id : null);
|
|
44
|
+
delete record.portfolioId;
|
|
45
|
+
delete record.id;
|
|
46
|
+
this.name = String(record.name ?? "");
|
|
47
|
+
if (typeof record.initialValue === "number") {
|
|
48
|
+
this.initialValue = record.initialValue;
|
|
49
|
+
}
|
|
50
|
+
this.strategies = Array.isArray(record.strategies)
|
|
51
|
+
? record.strategies.filter((s) => typeof s === "object" && s !== null && !Array.isArray(s))
|
|
52
|
+
: [];
|
|
53
|
+
if (typeof record.main === "boolean")
|
|
54
|
+
this.main = record.main;
|
|
55
|
+
if (typeof record.supportsFractionalShares === "boolean") {
|
|
56
|
+
this.supportsFractionalShares = record.supportsFractionalShares;
|
|
57
|
+
}
|
|
58
|
+
if (typeof record.supportsCrypto === "boolean") {
|
|
59
|
+
this.supportsCrypto = record.supportsCrypto;
|
|
60
|
+
}
|
|
61
|
+
if (typeof record.alertsEnabled === "boolean") {
|
|
62
|
+
this.alertsEnabled = record.alertsEnabled;
|
|
63
|
+
}
|
|
64
|
+
if (record.type === "paper" ||
|
|
65
|
+
record.type === "live" ||
|
|
66
|
+
record.type === "chat") {
|
|
67
|
+
this.type = record.type;
|
|
68
|
+
}
|
|
69
|
+
if (typeof record.isActive === "boolean")
|
|
70
|
+
this.isActive = record.isActive;
|
|
71
|
+
if (Array.isArray(record.strategyNames)) {
|
|
72
|
+
this.strategyNames = record.strategyNames.map(String);
|
|
73
|
+
}
|
|
74
|
+
if (typeof record.createdAt === "string")
|
|
75
|
+
this.createdAt = record.createdAt;
|
|
76
|
+
if (typeof record.updatedAt === "string")
|
|
77
|
+
this.updatedAt = record.updatedAt;
|
|
78
|
+
if (typeof record.brokerage === "string")
|
|
79
|
+
this.brokerage = record.brokerage;
|
|
80
|
+
for (const [key, value] of Object.entries(record)) {
|
|
81
|
+
if (key === "name" ||
|
|
82
|
+
key === "initialValue" ||
|
|
83
|
+
key === "strategies" ||
|
|
84
|
+
key === "main" ||
|
|
85
|
+
key === "supportsFractionalShares" ||
|
|
86
|
+
key === "supportsCrypto" ||
|
|
87
|
+
key === "alertsEnabled" ||
|
|
88
|
+
key === "type" ||
|
|
89
|
+
key === "isActive" ||
|
|
90
|
+
key === "strategyNames" ||
|
|
91
|
+
key === "createdAt" ||
|
|
92
|
+
key === "updatedAt" ||
|
|
93
|
+
key === "brokerage") {
|
|
94
|
+
continue;
|
|
95
|
+
}
|
|
96
|
+
// `__proto__`/`constructor` arrive as own enumerable keys from
|
|
97
|
+
// JSON.parse; assigning them replaces the instance prototype and the
|
|
98
|
+
// handle silently loses save/deploy/toJSON.
|
|
99
|
+
if (key === "__proto__" || key === "constructor")
|
|
100
|
+
continue;
|
|
101
|
+
Object.defineProperty(this, key, {
|
|
102
|
+
value,
|
|
103
|
+
writable: true,
|
|
104
|
+
enumerable: true,
|
|
105
|
+
configurable: true,
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
this.id = wireId;
|
|
109
|
+
this.#transport = options.transport ?? null;
|
|
110
|
+
}
|
|
111
|
+
static from(data, options = {}) {
|
|
112
|
+
return new PortfolioHandle(data, options);
|
|
113
|
+
}
|
|
114
|
+
/** Omit `id` — class fields would otherwise serialize as `"id": null`. */
|
|
115
|
+
toJSON() {
|
|
116
|
+
const body = {
|
|
117
|
+
name: this.name,
|
|
118
|
+
strategies: this.strategies,
|
|
119
|
+
};
|
|
120
|
+
if (this.initialValue !== undefined)
|
|
121
|
+
body.initialValue = this.initialValue;
|
|
122
|
+
if (this.main !== undefined)
|
|
123
|
+
body.main = this.main;
|
|
124
|
+
if (this.supportsFractionalShares !== undefined) {
|
|
125
|
+
body.supportsFractionalShares = this.supportsFractionalShares;
|
|
126
|
+
}
|
|
127
|
+
if (this.supportsCrypto !== undefined) {
|
|
128
|
+
body.supportsCrypto = this.supportsCrypto;
|
|
129
|
+
}
|
|
130
|
+
if (this.alertsEnabled !== undefined) {
|
|
131
|
+
body.alertsEnabled = this.alertsEnabled;
|
|
132
|
+
}
|
|
133
|
+
if (this.type !== undefined)
|
|
134
|
+
body.type = this.type;
|
|
135
|
+
if (this.isActive !== undefined)
|
|
136
|
+
body.isActive = this.isActive;
|
|
137
|
+
if (this.strategyNames !== undefined) {
|
|
138
|
+
body.strategyNames = this.strategyNames;
|
|
139
|
+
}
|
|
140
|
+
if (this.createdAt !== undefined)
|
|
141
|
+
body.createdAt = this.createdAt;
|
|
142
|
+
if (this.updatedAt !== undefined)
|
|
143
|
+
body.updatedAt = this.updatedAt;
|
|
144
|
+
if (this.brokerage !== undefined)
|
|
145
|
+
body.brokerage = this.brokerage;
|
|
146
|
+
return body;
|
|
147
|
+
}
|
|
148
|
+
async #resolveTransport(transport) {
|
|
149
|
+
if (transport)
|
|
150
|
+
return transport;
|
|
151
|
+
if (this.#transport)
|
|
152
|
+
return this.#transport;
|
|
153
|
+
// Lazy: avoids importing NexusTradeClient at module load (cycle with client).
|
|
154
|
+
const { NexusTradeClient, clientTransport } = await import("./client.js");
|
|
155
|
+
this.#transport = clientTransport(NexusTradeClient.fromEnvironment());
|
|
156
|
+
return this.#transport;
|
|
157
|
+
}
|
|
158
|
+
/** Persist as a chat draft. Sets `.id` to the ChatPortfolio id. */
|
|
159
|
+
async save(options) {
|
|
160
|
+
const transport = await this.#resolveTransport(options.transport);
|
|
161
|
+
const response = await transport.request("POST", "portfolios", {
|
|
162
|
+
body: this.toJSON(),
|
|
163
|
+
idempotencyKey: options.idempotencyKey,
|
|
164
|
+
});
|
|
165
|
+
const result = response.portfolio;
|
|
166
|
+
if (!isJsonObject(result) || typeof result.portfolioId !== "string") {
|
|
167
|
+
throw new NexusTradeApiError(NO_HTTP_STATUS, "invalid_response", "Portfolio save response is missing portfolioId.");
|
|
168
|
+
}
|
|
169
|
+
this.id = result.portfolioId;
|
|
170
|
+
this.#transport = transport;
|
|
171
|
+
return this;
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Mint/activate the real paper portfolio.
|
|
175
|
+
* Returns a *different* id than `save()` — see `DeployResult.portfolioId`.
|
|
176
|
+
*/
|
|
177
|
+
async deploy(options = {}) {
|
|
178
|
+
if (!this.id) {
|
|
179
|
+
throw new Error("Portfolio must be saved before deploy().");
|
|
180
|
+
}
|
|
181
|
+
const transport = await this.#resolveTransport(options.transport);
|
|
182
|
+
const body = {};
|
|
183
|
+
if (options.frequency !== undefined)
|
|
184
|
+
body.frequency = options.frequency;
|
|
185
|
+
const response = await transport.request("POST", `portfolios/${encodePathSegment(this.id)}/deploy`, { body });
|
|
186
|
+
const result = isJsonObject(response.deployment)
|
|
187
|
+
? response.deployment
|
|
188
|
+
: response;
|
|
189
|
+
if (!isJsonObject(result) || typeof result.portfolioId !== "string") {
|
|
190
|
+
throw new NexusTradeApiError(NO_HTTP_STATUS, "invalid_response", "Deploy response is missing portfolioId.");
|
|
191
|
+
}
|
|
192
|
+
return {
|
|
193
|
+
portfolioId: String(result.portfolioId),
|
|
194
|
+
chatPortfolioId: typeof result.chatPortfolioId === "string"
|
|
195
|
+
? result.chatPortfolioId
|
|
196
|
+
: undefined,
|
|
197
|
+
name: typeof result.name === "string" ? result.name : "",
|
|
198
|
+
outcome: typeof result.outcome === "string" ? result.outcome : "",
|
|
199
|
+
deploymentType: typeof result.deploymentType === "string"
|
|
200
|
+
? result.deploymentType
|
|
201
|
+
: undefined,
|
|
202
|
+
};
|
|
203
|
+
}
|
|
204
|
+
async undeploy(options = {}) {
|
|
205
|
+
if (!this.id) {
|
|
206
|
+
throw new Error("Portfolio must be saved before undeploy().");
|
|
207
|
+
}
|
|
208
|
+
const transport = await this.#resolveTransport(options.transport);
|
|
209
|
+
const response = await transport.request("POST", `portfolios/${encodePathSegment(this.id)}/undeploy`, { body: {} });
|
|
210
|
+
const result = isJsonObject(response.undeployment)
|
|
211
|
+
? response.undeployment
|
|
212
|
+
: response;
|
|
213
|
+
if (!isJsonObject(result)) {
|
|
214
|
+
throw new NexusTradeApiError(NO_HTTP_STATUS, "invalid_response", "Undeploy response is missing body.");
|
|
215
|
+
}
|
|
216
|
+
return result;
|
|
217
|
+
}
|
|
218
|
+
/** By id once saved; inline body before. */
|
|
219
|
+
async backtest(options) {
|
|
220
|
+
const transport = await this.#resolveTransport(options.transport);
|
|
221
|
+
const input = this.id
|
|
222
|
+
? {
|
|
223
|
+
portfolioId: this.id,
|
|
224
|
+
startDate: options.startDate,
|
|
225
|
+
endDate: options.endDate,
|
|
226
|
+
}
|
|
227
|
+
: {
|
|
228
|
+
portfolio: this.toJSON(),
|
|
229
|
+
startDate: options.startDate,
|
|
230
|
+
endDate: options.endDate,
|
|
231
|
+
};
|
|
232
|
+
if (options.baseline !== undefined)
|
|
233
|
+
input.baseline = options.baseline;
|
|
234
|
+
if (options.interval !== undefined)
|
|
235
|
+
input.interval = options.interval;
|
|
236
|
+
if (options.initialValue !== undefined) {
|
|
237
|
+
input.initialValue = options.initialValue;
|
|
238
|
+
}
|
|
239
|
+
if (options.generateEvents !== undefined) {
|
|
240
|
+
input.generateEvents = options.generateEvents;
|
|
241
|
+
}
|
|
242
|
+
if (options.feeConfig !== undefined)
|
|
243
|
+
input.feeConfig = options.feeConfig;
|
|
244
|
+
const response = await transport.request("POST", "backtests/batch", {
|
|
245
|
+
body: { backtests: [input] },
|
|
246
|
+
idempotencyKey: options.idempotencyKey,
|
|
247
|
+
});
|
|
248
|
+
const operations = response.operations;
|
|
249
|
+
if (!Array.isArray(operations) ||
|
|
250
|
+
operations.length !== 1 ||
|
|
251
|
+
!isJsonObject(operations[0])) {
|
|
252
|
+
throw new NexusTradeApiError(NO_HTTP_STATUS, "invalid_response", "Backtest response is missing operations.");
|
|
253
|
+
}
|
|
254
|
+
return operations[0];
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
export function portfolioHandleFromWire(data, options = {}) {
|
|
258
|
+
if (!isJsonObject(data)) {
|
|
259
|
+
throw new NexusTradeApiError(NO_HTTP_STATUS, "invalid_response", "Portfolio response is not an object.");
|
|
260
|
+
}
|
|
261
|
+
return PortfolioHandle.from(data, options);
|
|
262
|
+
}
|