@flexemarkets/fm-sdk 0.3.3 → 0.4.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,11 +3,11 @@
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 } from "./types.js";
6
+ import type { Account, Allotment, ClientConnection, Holding, ManagerOtpBundle, Market, Marketplace, Order, ParticipantState, Person, Security, Session, TickGrid, Token, Widget, WidgetPush } 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";
10
+ export declare const DEFAULT_ENDPOINT = "https://api.flexemarkets.com";
11
11
  export declare class FlexemarketsError extends Error {
12
12
  }
13
13
  export declare class AuthenticationError extends FlexemarketsError {
@@ -38,7 +38,7 @@ export declare class HttpError extends FlexemarketsError {
38
38
  *
39
39
  * Distinct from {@link HttpError}, which means the server answered and the
40
40
  * answer was an error. This means there was no usable answer at all — a
41
- * malformed body, or a link the API root does not carry.
41
+ * malformed body.
42
42
  */
43
43
  export declare class ApiError extends FlexemarketsError {
44
44
  }
@@ -77,26 +77,24 @@ export declare function parseMarketplace(data: JsonObject): Marketplace;
77
77
  export declare function parseSession(data: JsonObject): Session;
78
78
  export declare function parseOrder(data: JsonObject): Order;
79
79
  export declare function parseParticipantState(data: JsonObject): ParticipantState;
80
+ export declare function parseWidget(data: JsonObject): Widget;
80
81
  export declare function parseHolding(data: JsonObject): Holding;
81
82
  export declare function parseConnection(data: JsonObject): ClientConnection;
82
83
  /**
83
- * The orders inside a HAL envelope.
84
+ * The orders in a snapshot answer, which is a bare JSON array or a failure.
84
85
  *
85
- * The server embeds them under `orders`. It was `orderDtoes` — Spring HATEOAS
86
- * pluralising `OrderDto` — and every SDK still read that name long after the
87
- * server stopped sending it, so `activeOrders` and `recentTrades` returned an
88
- * empty array always. `Desk` seeds from `activeOrders`, so its books were
89
- * never seeded; they filled from live deltas and looked plausible.
86
+ * Only the array is read because the V1 route never sent anything else:
87
+ * `GET /api/v1/marketplaces/{id}/orders` has always answered a bare array, and
88
+ * 0.4 requires fm-server 4.6.2. The HAL envelopes earlier SDKs tolerated
89
+ * belonged to the routes 0.4 no longer calls.
90
90
  *
91
- * Then the envelope itself went: fm-server now sends a bare array. Accepting
92
- * both *names* did not survive that, and this SDK failed the same silent way a
93
- * second time — `._embedded` on an array is `undefined`, so it returned an
94
- * empty book rather than throwing, while Java and Python at least raised.
91
+ * Anything else throws rather than reading as empty. An empty snapshot is the
92
+ * failure that hid twice before: `Desk` seeded an empty book, filled it from
93
+ * live deltas, and looked plausible.
95
94
  *
96
- * So read the shape rather than assume one. All three are accepted, because
97
- * all three are still deployed somewhere.
95
+ * @throws ApiError when the answer is not a JSON array
98
96
  */
99
- export declare function embeddedOrders(data: unknown): JsonObject[];
97
+ export declare function ordersOf(data: unknown): JsonObject[];
100
98
  /**
101
99
  * The most aggressive price this market will accept on `side`.
102
100
  *
@@ -107,23 +105,6 @@ export declare function embeddedOrders(data: unknown): JsonObject[];
107
105
  * where the two bounds are equal and there is one legal price.
108
106
  */
109
107
  export declare function marketableLimit(market: Market, side: string): number;
110
- /**
111
- * Point the API root's links back at the host that was dialled.
112
- *
113
- * The server builds these hrefs from the request it believes it received, and
114
- * behind a proxy that belief can be wrong: an origin reached over a plaintext
115
- * leg reports `http://` even though the caller arrived on `https://`. Every
116
- * call that goes through a link — which is most of them — then leaves on plain
117
- * HTTP and meets the edge's redirect. A GET survives it. A POST does not: a
118
- * 301 is followed as a GET with the body dropped, so placing an order or
119
- * opening a session fails with nothing placed and nothing pointing at the
120
- * scheme.
121
- *
122
- * Only the origin is replaced. The path, query and any URI template are the
123
- * server's to choose; where it is reachable is not, and the token in hand was
124
- * issued by the origin dialled, not by whatever the links name.
125
- */
126
- export declare function rebaseApiRoot(root: ApiRoot, endpoint: string): ApiRoot;
127
108
  export declare function server(endpoint: string): string;
128
109
  /**
129
110
  * Resolve an `--endpoint` value to config overrides. A bare marketplace id
@@ -132,12 +113,24 @@ export declare function server(endpoint: string): string;
132
113
  * URL. Development environments give a full URL when localhost is wanted.
133
114
  */
134
115
  export declare function resolveEndpoint(endpoint: string): Record<string, string>;
116
+ export declare function loadPropertiesFile(path: string): Record<string, string>;
117
+ export declare function loadConfig(): Record<string, string>;
118
+ /**
119
+ * What the server said, rather than the envelope it said it in.
120
+ *
121
+ * Failures arrive as `{"error","message","path","shortDigest","status"}` and
122
+ * the message is the only part a caller can act on. Falls back to the raw
123
+ * body when it does not parse, since that is when the caller most needs to
124
+ * see what came back. As the Java SDK's `_detail`, which had this fix alone:
125
+ * here a refused sign-in said only "Authentication failed.", and a refused
126
+ * order carried the whole JSON document.
127
+ */
128
+ export declare function detail(body: string): string;
135
129
  export declare class Flexemarkets {
136
130
  private readonly _clientDescription;
137
131
  private readonly _endpoint;
138
132
  private readonly _baseUrl;
139
133
  private readonly _bearerToken;
140
- private _apiRoot;
141
134
  private _account;
142
135
  private _user;
143
136
  private _tokenObj;
@@ -161,10 +154,7 @@ export declare class Flexemarkets {
161
154
  * `Snapshot.NO_SEQ` when the header is absent.
162
155
  */
163
156
  private _getSnapshot;
164
- /**
165
- * PATCH with no body — the shape every session transition takes: the verb and
166
- * the path carry the whole request.
167
- */
157
+ /** PATCH with a JSON body -- the shape every session transition takes. */
168
158
  private _patch;
169
159
  /**
170
160
  * GET returning the body verbatim, for endpoints that answer with something
@@ -181,13 +171,21 @@ export declare class Flexemarkets {
181
171
  * cannot sign in as.
182
172
  */
183
173
  signup(accountName: string, email: string, password: string, firstName?: string | null, lastName?: string | null): Promise<Token>;
184
- /** Approve an account by name, returning it as it now stands. */
174
+ /**
175
+ * Approve an account by name, returning it as it now stands.
176
+ *
177
+ * V1 approves an account by id; the name is looked up in the account list
178
+ * first, so callers keep naming the account they signed up.
179
+ */
185
180
  approveAccount(accountName: string): Promise<Account | null>;
186
181
  /** One account by id. */
187
182
  accountById(accountId: number): Promise<Account | null>;
188
183
  /** One user by id. */
189
184
  userById(userId: number): Promise<Person>;
190
- /** The marketplace's private-trader identifiers. */
185
+ /**
186
+ * The names of the participants a caller may target: `GET participants`,
187
+ * names only. A row carries the user id too, for a manager; not needed here.
188
+ */
191
189
  identifiers(marketplaceId: number): Promise<string[]>;
192
190
  /** Delete the caller's own account. Its own route, not accounts/{yourId}. */
193
191
  deleteMyAccount(): Promise<void>;
@@ -221,7 +219,24 @@ export declare class Flexemarkets {
221
219
  managerOtpBundle(userIds: number[]): Promise<ManagerOtpBundle>;
222
220
  /** DELETE, whose answer is a status and nothing worth parsing. */
223
221
  private _delete;
224
- private _fetchApiRoot;
222
+ /**
223
+ * DELETE whose answer is the resource as it ended -- an order's CANCEL.
224
+ */
225
+ private _deleteFor;
226
+ /**
227
+ * Send one CSV file as the body, `Content-Type: text/csv` -- format by
228
+ * header, where 0.3 posted it as a multipart upload to an `/uploads`
229
+ * segment. Bytes, not a string, so the file's own encoding survives.
230
+ */
231
+ private _sendCsv;
232
+ /**
233
+ * A V1 route. 0.4 addresses every route from the server rather than through
234
+ * the HAL root's links: the path is knowable without fetching anything
235
+ * first, and a root that drops a link can no longer take a call with it.
236
+ */
237
+ private _v1;
238
+ /** The V1 route of one marketplace, under which nearly everything lives. */
239
+ private _marketplace;
225
240
  marketplaces(): Promise<Marketplace[]>;
226
241
  marketplace(marketplaceId: number): Promise<Marketplace>;
227
242
  markets(marketplaceId: number): Promise<Market[]>;
@@ -241,6 +256,7 @@ export declare class Flexemarkets {
241
256
  */
242
257
  isManager(): boolean;
243
258
  hasRole(role: string): boolean;
259
+ /** The symbols of the marketplace's markets, read from the markets themselves. */
244
260
  symbols(marketplaceId: number): Promise<string[]>;
245
261
  /**
246
262
  * The marketplace's sessions — all of them.
@@ -249,10 +265,6 @@ export declare class Flexemarkets {
249
265
  * the `sessionIds` this used to accept was silently ignored: it returned the
250
266
  * whole history and looked like it had filtered. Filter the result; fm-ui
251
267
  * already does.
252
- *
253
- * On `GET /api/v1/marketplaces/{id}/sessions`, which answers with the same
254
- * fields as the V0 route it replaces — verified against a running server,
255
- * not assumed — and needs no `format=application/json` to avoid HAL.
256
268
  */
257
269
  sessions(marketplaceId: number): Promise<Session[]>;
258
270
  session(marketplaceId: number): Promise<Session>;
@@ -277,6 +289,11 @@ export declare class Flexemarkets {
277
289
  */
278
290
  submitMarket(marketplaceId: number, marketId: number, side: string, units: number): Promise<Order>;
279
291
  private _market;
292
+ /**
293
+ * DELETE the order: the server builds the CANCEL from the order's own
294
+ * lineage and market, and answers with it. `marketId` is no longer sent --
295
+ * the order already says which market it is in.
296
+ */
280
297
  submitCancel(marketplaceId: number, marketId: number, originalId: number): Promise<Order>;
281
298
  /**
282
299
  * The active-orders snapshot: every resting limit order on the
@@ -297,27 +314,38 @@ export declare class Flexemarkets {
297
314
  * order differs. `Tape` sorts what it is given, so a caller seeding a tape
298
315
  * through `Desk` is unaffected; a caller reading this list directly
299
316
  * should not assume one.
317
+ *
318
+ * With `marketId`, only that market's legs (`&market=`), `size` of them,
319
+ * two to a trade. What `Desk` seeds each tape from: read for every market
320
+ * at once, a busy market's legs fill the limit and a quiet market's tape
321
+ * comes up empty, though it has traded.
322
+ */
323
+ recentTrades(marketplaceId: number, size?: number, marketId?: number): Promise<Snapshot<Order[]>>;
324
+ /**
325
+ * The marketplace's orders.
326
+ *
327
+ * With no option, the current session's orders less every cancelled one, the
328
+ * CANCEL that consumed it, and both legs of a self-cross -- what a study
329
+ * ranking participants needs. Without `cancelled=false` the V1 read is the
330
+ * raw lifecycle, which is what `sessionIds` asks for: every LIMIT and CANCEL
331
+ * row of the named runs, as the exchange stored them. `symbol` reads one
332
+ * market's active orders, with the symbol filled in.
300
333
  */
301
- recentTrades(marketplaceId: number, size?: number): Promise<Snapshot<Order[]>>;
302
334
  orders(marketplaceId: number, options?: {
303
335
  symbol?: string;
304
336
  sessionIds?: number[];
305
337
  }): Promise<Order[]>;
306
338
  /**
307
- * Tape in one market, in ascending order id.
308
- *
309
- * Answered by a symbol-keyed route, so the orders come back without the
310
- * symbol on them and with the trade id in `original`; both are filled in
311
- * before returning, which is what makes the result a trade list rather than
312
- * a set of half-populated orders.
339
+ * One market's traded legs, as many as the server gives in one read
340
+ * ({@link MAX_TRADED_LEGS}), in the server's order.
313
341
  *
314
- * This is the FM-3 surface (`/api/orders-json/symbol-trades`) and its order
315
- * is the server's, which sorts by order id and nothing else. It is neither
316
- * chronological by trade time nor most-recent-first — the first element is
317
- * the lowest id, not the latest trade. Sort by `lastModifiedDate` if you
318
- * want time order.
342
+ * The answer carries the trade id in `original` and no symbol on the orders,
343
+ * because the query already fixed the symbol. Both are filled in before
344
+ * returning, which is what makes the result a trade list rather than a set of
345
+ * half-populated orders. Sort by `lastModifiedDate` if you want time order.
319
346
  */
320
347
  trades(marketplaceId: number, symbol: string): Promise<Order[]>;
348
+ /** Comma-separated ids, matching the server's `?sessions=` filter. */
321
349
  holdings(marketplaceId: number, sessionIds?: number[] | null): Promise<Holding[]>;
322
350
  holding(marketplaceId: number): Promise<Holding>;
323
351
  /**
@@ -345,9 +373,15 @@ export declare class Flexemarkets {
345
373
  openSession(marketplaceId: number): Promise<Session>;
346
374
  pauseSession(marketplaceId: number): Promise<Session>;
347
375
  closeSession(marketplaceId: number): Promise<Session>;
348
- /** Everyone in the caller's account. `usersJson`, not the HAL `users` form. */
376
+ /**
377
+ * A session's lifecycle is its state, PATCHed. Asking for the state it is
378
+ * already in changes nothing; one it cannot reach from where it is --
379
+ * pausing a closed session -- is refused.
380
+ */
381
+ private _sessionState;
382
+ /** Everyone in the caller's account. */
349
383
  users(): Promise<Person[]>;
350
- /** The opening positions of one allocation. A V1 route, not on the API root. */
384
+ /** The opening positions of one allocation. */
351
385
  allotments(marketplaceId: number, allocationId: number): Promise<Allotment[]>;
352
386
  /**
353
387
  * Stage the opening positions for the next session.
@@ -363,9 +397,8 @@ export declare class Flexemarkets {
363
397
  /**
364
398
  * The holdings CSV, verbatim, for the current session or for given ones.
365
399
  *
366
- * The filter is spelled `sessions=` on this route and `sessionIds=` on
367
- * sessions and connections. Using the wrong one is not an error — it is an
368
- * unfiltered answer.
400
+ * The same route as {@link holdings}, asked for `text/csv`: the format is
401
+ * chosen by the Accept header, not by a `/downloads` segment.
369
402
  */
370
403
  downloadHoldings(marketplaceId: number, sessionIds?: number[] | null): Promise<string>;
371
404
  /**
@@ -388,6 +421,40 @@ export declare class Flexemarkets {
388
421
  * resolves to. A study's existing values file needs no change.
389
422
  */
390
423
  uploadState(marketplaceId: number, filename: string): Promise<ParticipantState[]>;
424
+ /**
425
+ * Push widgets to participants' screens, returning them as stored.
426
+ *
427
+ * One request for the whole list, which is what the server's rate limit is
428
+ * shaped for: a session-open that tells sixty traders their values is one
429
+ * push of sixty, not sixty pushes. A push to a target and key that already
430
+ * has a widget replaces it.
431
+ *
432
+ * Not staged, unlike an allocation: it reaches the screen as soon as the
433
+ * server stores it, and it is cleared when the session closes.
434
+ *
435
+ * The server checks the content and refuses a list with anything wrong in it
436
+ * as an InvalidArgumentError; nothing in the list is stored. Pushing faster
437
+ * than the server allows is answered 429, which arrives as an HttpError with
438
+ * that status: back off and push again.
439
+ */
440
+ pushWidgets(marketplaceId: number, widgets: WidgetPush[]): Promise<Widget[]>;
441
+ /**
442
+ * Take down a widget: the marketplace's for `key`, or one participant's.
443
+ *
444
+ * True if one was removed, false if there was none to remove. With `userId`,
445
+ * only that participant's widget goes -- `participants/{userId}/widgets/{key}`
446
+ * -- and their marketplace widget for the same key, if any, shows again.
447
+ *
448
+ * An empty 404 is the server saying nothing was there. A 404 carrying a
449
+ * failure document -- no such marketplace -- still throws, so a robot pointed
450
+ * at the wrong marketplace does not read its clean-up as done.
451
+ */
452
+ removeWidget(marketplaceId: number, key: string, userId?: number): Promise<boolean>;
453
+ /**
454
+ * Every widget pushed to the marketplace and still standing, for every
455
+ * participant -- what a manager reads to check on a robot.
456
+ */
457
+ allWidgets(marketplaceId: number): Promise<Widget[]>;
391
458
  private readonly _sharedViews;
392
459
  private readonly _sharedViewPromises;
393
460
  /**