@flexemarkets/fm-sdk 0.3.4 → 0.5.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/dist/client.d.ts CHANGED
@@ -3,9 +3,8 @@
3
3
  *
4
4
  * Port of fm.client (Python) / fm.Flexemarkets (Java).
5
5
  */
6
- import type { Account, Allotment, ClientConnection, Holding, ManagerOtpBundle, Market, Marketplace, Order, ParticipantState, Person, Security, Session, TickGrid, Token, Widget, WidgetPush } from "./types.js";
6
+ import type { Account, Allotment, ClientConnection, Holding, ManagerOtpBundle, Market, Marketplace, Order, ParticipantState, Person, Security, Session, TickGrid, Token, Widget, WidgetPush, MarketplaceRobot, RobotParameterConfig, RobotParameterControl } from "./types.js";
7
7
  import { EventListener, type EventCallback } from "./stomp.js";
8
- import type { ApiRoot } from "./hal.js";
9
8
  import { type Desk, type Subscription } from "./desk.js";
10
9
  import type { Snapshot } from "./snapshot.js";
11
10
  export declare const DEFAULT_ENDPOINT = "https://api.flexemarkets.com";
@@ -17,6 +16,20 @@ export declare class AuthorizationError extends FlexemarketsError {
17
16
  }
18
17
  export declare class InvalidArgumentError extends FlexemarketsError {
19
18
  }
19
+ /**
20
+ * An order the desk did not send, because fm-server would refuse it.
21
+ *
22
+ * Rejected by `Desk.submitLimit` when the session the desk holds is not open,
23
+ * or the holding it holds does not grant the order's side in that market --
24
+ * the two refusals fm-server answers with 400 `SESSION_CLOSED` and
25
+ * `ORDER_NOT_ALLOWED`, which `reason` names. An {@link InvalidArgumentError},
26
+ * so a caller catching the server's answer catches this too.
27
+ * `flexemarkets.desk(id, { refuseLocally: false })` sends every order instead.
28
+ */
29
+ export declare class OrderRefusedLocallyError extends InvalidArgumentError {
30
+ readonly reason: "SESSION_CLOSED" | "ORDER_NOT_ALLOWED";
31
+ constructor(reason: "SESSION_CLOSED" | "ORDER_NOT_ALLOWED", message: string);
32
+ }
20
33
  export declare class ConnectionFailedError extends FlexemarketsError {
21
34
  }
22
35
  export declare class ConfigurationError extends FlexemarketsError {
@@ -39,7 +52,7 @@ export declare class HttpError extends FlexemarketsError {
39
52
  *
40
53
  * Distinct from {@link HttpError}, which means the server answered and the
41
54
  * answer was an error. This means there was no usable answer at all — a
42
- * malformed body, or a link the API root does not carry.
55
+ * malformed body.
43
56
  */
44
57
  export declare class ApiError extends FlexemarketsError {
45
58
  }
@@ -78,27 +91,26 @@ export declare function parseMarketplace(data: JsonObject): Marketplace;
78
91
  export declare function parseSession(data: JsonObject): Session;
79
92
  export declare function parseOrder(data: JsonObject): Order;
80
93
  export declare function parseParticipantState(data: JsonObject): ParticipantState;
94
+ export declare function parseRobotParameterConfig(data: JsonObject): RobotParameterConfig;
95
+ export declare function parseMarketplaceRobot(data: JsonObject): MarketplaceRobot;
81
96
  export declare function parseWidget(data: JsonObject): Widget;
82
97
  export declare function parseHolding(data: JsonObject): Holding;
83
98
  export declare function parseConnection(data: JsonObject): ClientConnection;
84
99
  /**
85
- * The orders inside a HAL envelope.
100
+ * The orders in a snapshot answer, which is a bare JSON array or a failure.
86
101
  *
87
- * The server embeds them under `orders`. It was `orderDtoes` — Spring HATEOAS
88
- * pluralising `OrderDto` — and every SDK still read that name long after the
89
- * server stopped sending it, so `activeOrders` and `recentTrades` returned an
90
- * empty array always. `Desk` seeds from `activeOrders`, so its books were
91
- * never seeded; they filled from live deltas and looked plausible.
102
+ * Only the array is read because the V1 route never sent anything else:
103
+ * `GET /api/v1/marketplaces/{id}/orders` has always answered a bare array, and
104
+ * 0.4 requires fm-server 4.6.2. The HAL envelopes earlier SDKs tolerated
105
+ * belonged to the routes 0.4 no longer calls.
92
106
  *
93
- * Then the envelope itself went: fm-server now sends a bare array. Accepting
94
- * both *names* did not survive that, and this SDK failed the same silent way a
95
- * second time — `._embedded` on an array is `undefined`, so it returned an
96
- * empty book rather than throwing, while Java and Python at least raised.
107
+ * Anything else throws rather than reading as empty. An empty snapshot is the
108
+ * failure that hid twice before: `Desk` seeded an empty book, filled it from
109
+ * live deltas, and looked plausible.
97
110
  *
98
- * So read the shape rather than assume one. All three are accepted, because
99
- * all three are still deployed somewhere.
111
+ * @throws ApiError when the answer is not a JSON array
100
112
  */
101
- export declare function embeddedOrders(data: unknown): JsonObject[];
113
+ export declare function ordersOf(data: unknown): JsonObject[];
102
114
  /**
103
115
  * The most aggressive price this market will accept on `side`.
104
116
  *
@@ -109,23 +121,6 @@ export declare function embeddedOrders(data: unknown): JsonObject[];
109
121
  * where the two bounds are equal and there is one legal price.
110
122
  */
111
123
  export declare function marketableLimit(market: Market, side: string): number;
112
- /**
113
- * Point the API root's links back at the host that was dialled.
114
- *
115
- * The server builds these hrefs from the request it believes it received, and
116
- * behind a proxy that belief can be wrong: an origin reached over a plaintext
117
- * leg reports `http://` even though the caller arrived on `https://`. Every
118
- * call that goes through a link — which is most of them — then leaves on plain
119
- * HTTP and meets the edge's redirect. A GET survives it. A POST does not: a
120
- * 301 is followed as a GET with the body dropped, so placing an order or
121
- * opening a session fails with nothing placed and nothing pointing at the
122
- * scheme.
123
- *
124
- * Only the origin is replaced. The path, query and any URI template are the
125
- * server's to choose; where it is reachable is not, and the token in hand was
126
- * issued by the origin dialled, not by whatever the links name.
127
- */
128
- export declare function rebaseApiRoot(root: ApiRoot, endpoint: string): ApiRoot;
129
124
  export declare function server(endpoint: string): string;
130
125
  /**
131
126
  * Resolve an `--endpoint` value to config overrides. A bare marketplace id
@@ -151,11 +146,17 @@ export declare class Flexemarkets {
151
146
  private readonly _clientDescription;
152
147
  private readonly _endpoint;
153
148
  private readonly _baseUrl;
154
- private readonly _bearerToken;
155
- private _apiRoot;
149
+ /**
150
+ * The sign-in this client presents, replaced whole when an expired one is
151
+ * renewed (see {@link _renewToken}); the bearer header is derived from it,
152
+ * so `token()` and every request agree on which token is current.
153
+ */
154
+ private _tokenObj;
155
+ /** Kept only to sign in again when the token runs out; null for a client given a token. */
156
+ private _credentials;
157
+ private _renewing;
156
158
  private _account;
157
159
  private _user;
158
- private _tokenObj;
159
160
  private _eventListener;
160
161
  private constructor();
161
162
  /** Connect to the Flexemarkets API. */
@@ -168,6 +169,24 @@ export declare class Flexemarkets {
168
169
  get endpointUrl(): string;
169
170
  get endpointMarketplaceId(): number;
170
171
  private _authHeaders;
172
+ /** The Authorization header for the current sign-in. */
173
+ private get _bearerToken();
174
+ /**
175
+ * fetch with this client's token; if it has expired, renew it once and send
176
+ * again. Tokens live 24 hours, so a robot that ran longer ended the first
177
+ * time it asked for anything after that, or looped on the refusal -- a Utah
178
+ * poller, about 250 times a day at 00Z.
179
+ */
180
+ private _fetch;
181
+ /**
182
+ * Sign in again with the credentials this client was made with. False when
183
+ * it was given a token rather than credentials, or the sign-in fails; the
184
+ * caller then answers with the refusal it had. `presented` is the header
185
+ * the refused request or stream connect carried: one another caller has
186
+ * already replaced is not renewed again, and concurrent callers share one
187
+ * sign-in.
188
+ */
189
+ private _renewToken;
171
190
  private _get;
172
191
  /**
173
192
  * GET helper that returns the parsed body bundled with the
@@ -176,11 +195,11 @@ export declare class Flexemarkets {
176
195
  * `Snapshot.NO_SEQ` when the header is absent.
177
196
  */
178
197
  private _getSnapshot;
179
- /**
180
- * PATCH with no body — the shape every session transition takes: the verb and
181
- * the path carry the whole request.
182
- */
198
+ /** PATCH with a JSON body -- the shape every session transition takes. */
183
199
  private _patch;
200
+ /** PUT with a JSON body -- a robot parameter's configuration, say. */
201
+ private _put;
202
+ private _sendJson;
184
203
  /**
185
204
  * GET returning the body verbatim, for endpoints that answer with something
186
205
  * other than JSON — the holdings download is a CSV, and JSON.parse dies on
@@ -196,13 +215,21 @@ export declare class Flexemarkets {
196
215
  * cannot sign in as.
197
216
  */
198
217
  signup(accountName: string, email: string, password: string, firstName?: string | null, lastName?: string | null): Promise<Token>;
199
- /** Approve an account by name, returning it as it now stands. */
218
+ /**
219
+ * Approve an account by name, returning it as it now stands.
220
+ *
221
+ * V1 approves an account by id; the name is looked up in the account list
222
+ * first, so callers keep naming the account they signed up.
223
+ */
200
224
  approveAccount(accountName: string): Promise<Account | null>;
201
225
  /** One account by id. */
202
226
  accountById(accountId: number): Promise<Account | null>;
203
227
  /** One user by id. */
204
228
  userById(userId: number): Promise<Person>;
205
- /** The marketplace's private-trader identifiers. */
229
+ /**
230
+ * The names of the participants a caller may target: `GET participants`,
231
+ * names only. A row carries the user id too, for a manager; not needed here.
232
+ */
206
233
  identifiers(marketplaceId: number): Promise<string[]>;
207
234
  /** Delete the caller's own account. Its own route, not accounts/{yourId}. */
208
235
  deleteMyAccount(): Promise<void>;
@@ -236,7 +263,24 @@ export declare class Flexemarkets {
236
263
  managerOtpBundle(userIds: number[]): Promise<ManagerOtpBundle>;
237
264
  /** DELETE, whose answer is a status and nothing worth parsing. */
238
265
  private _delete;
239
- private _fetchApiRoot;
266
+ /**
267
+ * DELETE whose answer is the resource as it ended -- an order's CANCEL.
268
+ */
269
+ private _deleteFor;
270
+ /**
271
+ * Send one CSV file as the body, `Content-Type: text/csv` -- format by
272
+ * header, where 0.3 posted it as a multipart upload to an `/uploads`
273
+ * segment. Bytes, not a string, so the file's own encoding survives.
274
+ */
275
+ private _sendCsv;
276
+ /**
277
+ * A V1 route. 0.4 addresses every route from the server rather than through
278
+ * the HAL root's links: the path is knowable without fetching anything
279
+ * first, and a root that drops a link can no longer take a call with it.
280
+ */
281
+ private _v1;
282
+ /** The V1 route of one marketplace, under which nearly everything lives. */
283
+ private _marketplace;
240
284
  marketplaces(): Promise<Marketplace[]>;
241
285
  marketplace(marketplaceId: number): Promise<Marketplace>;
242
286
  markets(marketplaceId: number): Promise<Market[]>;
@@ -256,6 +300,7 @@ export declare class Flexemarkets {
256
300
  */
257
301
  isManager(): boolean;
258
302
  hasRole(role: string): boolean;
303
+ /** The symbols of the marketplace's markets, read from the markets themselves. */
259
304
  symbols(marketplaceId: number): Promise<string[]>;
260
305
  /**
261
306
  * The marketplace's sessions — all of them.
@@ -264,10 +309,6 @@ export declare class Flexemarkets {
264
309
  * the `sessionIds` this used to accept was silently ignored: it returned the
265
310
  * whole history and looked like it had filtered. Filter the result; fm-ui
266
311
  * already does.
267
- *
268
- * On `GET /api/v1/marketplaces/{id}/sessions`, which answers with the same
269
- * fields as the V0 route it replaces — verified against a running server,
270
- * not assumed — and needs no `format=application/json` to avoid HAL.
271
312
  */
272
313
  sessions(marketplaceId: number): Promise<Session[]>;
273
314
  session(marketplaceId: number): Promise<Session>;
@@ -292,6 +333,11 @@ export declare class Flexemarkets {
292
333
  */
293
334
  submitMarket(marketplaceId: number, marketId: number, side: string, units: number): Promise<Order>;
294
335
  private _market;
336
+ /**
337
+ * DELETE the order: the server builds the CANCEL from the order's own
338
+ * lineage and market, and answers with it. `marketId` is no longer sent --
339
+ * the order already says which market it is in.
340
+ */
295
341
  submitCancel(marketplaceId: number, marketId: number, originalId: number): Promise<Order>;
296
342
  /**
297
343
  * The active-orders snapshot: every resting limit order on the
@@ -312,27 +358,38 @@ export declare class Flexemarkets {
312
358
  * order differs. `Tape` sorts what it is given, so a caller seeding a tape
313
359
  * through `Desk` is unaffected; a caller reading this list directly
314
360
  * should not assume one.
361
+ *
362
+ * With `marketId`, only that market's legs (`&market=`), `size` of them,
363
+ * two to a trade. What `Desk` seeds each tape from: read for every market
364
+ * at once, a busy market's legs fill the limit and a quiet market's tape
365
+ * comes up empty, though it has traded.
366
+ */
367
+ recentTrades(marketplaceId: number, size?: number, marketId?: number): Promise<Snapshot<Order[]>>;
368
+ /**
369
+ * The marketplace's orders.
370
+ *
371
+ * With no option, the current session's orders less every cancelled one, the
372
+ * CANCEL that consumed it, and both legs of a self-cross -- what a study
373
+ * ranking participants needs. Without `cancelled=false` the V1 read is the
374
+ * raw lifecycle, which is what `sessionIds` asks for: every LIMIT and CANCEL
375
+ * row of the named runs, as the exchange stored them. `symbol` reads one
376
+ * market's active orders, with the symbol filled in.
315
377
  */
316
- recentTrades(marketplaceId: number, size?: number): Promise<Snapshot<Order[]>>;
317
378
  orders(marketplaceId: number, options?: {
318
379
  symbol?: string;
319
380
  sessionIds?: number[];
320
381
  }): Promise<Order[]>;
321
382
  /**
322
- * Tape in one market, in ascending order id.
383
+ * One market's traded legs, as many as the server gives in one read
384
+ * ({@link MAX_TRADED_LEGS}), in the server's order.
323
385
  *
324
- * Answered by a symbol-keyed route, so the orders come back without the
325
- * symbol on them and with the trade id in `original`; both are filled in
326
- * before returning, which is what makes the result a trade list rather than
327
- * a set of half-populated orders.
328
- *
329
- * This is the FM-3 surface (`/api/orders-json/symbol-trades`) and its order
330
- * is the server's, which sorts by order id and nothing else. It is neither
331
- * chronological by trade time nor most-recent-first — the first element is
332
- * the lowest id, not the latest trade. Sort by `lastModifiedDate` if you
333
- * want time order.
386
+ * The answer carries the trade id in `original` and no symbol on the orders,
387
+ * because the query already fixed the symbol. Both are filled in before
388
+ * returning, which is what makes the result a trade list rather than a set of
389
+ * half-populated orders. Sort by `lastModifiedDate` if you want time order.
334
390
  */
335
391
  trades(marketplaceId: number, symbol: string): Promise<Order[]>;
392
+ /** Comma-separated ids, matching the server's `?sessions=` filter. */
336
393
  holdings(marketplaceId: number, sessionIds?: number[] | null): Promise<Holding[]>;
337
394
  holding(marketplaceId: number): Promise<Holding>;
338
395
  /**
@@ -360,9 +417,15 @@ export declare class Flexemarkets {
360
417
  openSession(marketplaceId: number): Promise<Session>;
361
418
  pauseSession(marketplaceId: number): Promise<Session>;
362
419
  closeSession(marketplaceId: number): Promise<Session>;
363
- /** Everyone in the caller's account. `usersJson`, not the HAL `users` form. */
420
+ /**
421
+ * A session's lifecycle is its state, PATCHed. Asking for the state it is
422
+ * already in changes nothing; one it cannot reach from where it is --
423
+ * pausing a closed session -- is refused.
424
+ */
425
+ private _sessionState;
426
+ /** Everyone in the caller's account. */
364
427
  users(): Promise<Person[]>;
365
- /** The opening positions of one allocation. A V1 route, not on the API root. */
428
+ /** The opening positions of one allocation. */
366
429
  allotments(marketplaceId: number, allocationId: number): Promise<Allotment[]>;
367
430
  /**
368
431
  * Stage the opening positions for the next session.
@@ -378,9 +441,8 @@ export declare class Flexemarkets {
378
441
  /**
379
442
  * The holdings CSV, verbatim, for the current session or for given ones.
380
443
  *
381
- * The filter is spelled `sessions=` on this route and `sessionIds=` on
382
- * sessions and connections. Using the wrong one is not an error — it is an
383
- * unfiltered answer.
444
+ * The same route as {@link holdings}, asked for `text/csv`: the format is
445
+ * chosen by the Accept header, not by a `/downloads` segment.
384
446
  */
385
447
  downloadHoldings(marketplaceId: number, sessionIds?: number[] | null): Promise<string>;
386
448
  /**
@@ -424,8 +486,8 @@ export declare class Flexemarkets {
424
486
  * Take down a widget: the marketplace's for `key`, or one participant's.
425
487
  *
426
488
  * True if one was removed, false if there was none to remove. With `userId`,
427
- * only that participant's widget goes; their marketplace widget for the same
428
- * key, if any, shows again.
489
+ * only that participant's widget goes -- `participants/{userId}/widgets/{key}`
490
+ * -- and their marketplace widget for the same key, if any, shows again.
429
491
  *
430
492
  * An empty 404 is the server saying nothing was there. A 404 carrying a
431
493
  * failure document -- no such marketplace -- still throws, so a robot pointed
@@ -437,6 +499,29 @@ export declare class Flexemarkets {
437
499
  * participant -- what a manager reads to check on a robot.
438
500
  */
439
501
  allWidgets(marketplaceId: number): Promise<Widget[]>;
502
+ /**
503
+ * Every robot the marketplace's robot host offers, with whether it is
504
+ * enabled here and how a manager has configured its parameters.
505
+ *
506
+ * Readable by participants as well as managers: it is what a launch form is
507
+ * built from. Asks the robot host for its catalogue, so it fails when the
508
+ * host cannot be reached.
509
+ */
510
+ marketplaceRobots(marketplaceId: number): Promise<MarketplaceRobot[]>;
511
+ /**
512
+ * Set a robot parameter's value in a marketplace, and whether participants
513
+ * may move it, returning the configuration as stored.
514
+ *
515
+ * A null `control` fixes the value: participants launching the robot see it
516
+ * read-only. A control exposes it within that range, starting at `value`,
517
+ * which must lie inside it. The server refuses a parameter the robot does
518
+ * not declare, a platform parameter, and a range outside the robot's own
519
+ * bounds.
520
+ *
521
+ * The control goes up flat beside the value, and a fixed parameter sends the
522
+ * value alone: the server reads any bound as a control.
523
+ */
524
+ configureRobotParameter(marketplaceId: number, robotId: string, paramName: string, value: string, control: RobotParameterControl | null): Promise<RobotParameterConfig>;
440
525
  private readonly _sharedViews;
441
526
  private readonly _sharedViewPromises;
442
527
  /**
@@ -450,8 +535,16 @@ export declare class Flexemarkets {
450
535
  * callers with different identities each get their own desk —
451
536
  * multi-tenant WS multiplexing is a server-side concern, not a
452
537
  * client-side one.
538
+ *
539
+ * `submitLimit` on the returned handle rejects, without sending, an order
540
+ * the desk knows fm-server would refuse -- a session that is not open, a
541
+ * side the holding does not grant -- with {@link OrderRefusedLocallyError}.
542
+ * `{ refuseLocally: false }` sends every order and leaves the answer to the
543
+ * server.
453
544
  */
454
- desk(marketplaceId: number): Promise<Desk>;
545
+ desk(marketplaceId: number, options?: {
546
+ refuseLocally?: boolean;
547
+ }): Promise<Desk>;
455
548
  _releaseSharedView(marketplaceId: number): void;
456
549
  /** Start receiving real-time events via WebSocket STOMP. */
457
550
  listen(marketplaceId: number, callback: EventCallback): Promise<void>;