@flexemarkets/fm-sdk 0.3.4 → 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
@@ -5,7 +5,6 @@
5
5
  */
6
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";
11
10
  export declare const DEFAULT_ENDPOINT = "https://api.flexemarkets.com";
@@ -39,7 +38,7 @@ export declare class HttpError extends FlexemarketsError {
39
38
  *
40
39
  * Distinct from {@link HttpError}, which means the server answered and the
41
40
  * 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.
41
+ * malformed body.
43
42
  */
44
43
  export declare class ApiError extends FlexemarketsError {
45
44
  }
@@ -82,23 +81,20 @@ export declare function parseWidget(data: JsonObject): Widget;
82
81
  export declare function parseHolding(data: JsonObject): Holding;
83
82
  export declare function parseConnection(data: JsonObject): ClientConnection;
84
83
  /**
85
- * The orders inside a HAL envelope.
84
+ * The orders in a snapshot answer, which is a bare JSON array or a failure.
86
85
  *
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.
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.
92
90
  *
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.
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.
97
94
  *
98
- * So read the shape rather than assume one. All three are accepted, because
99
- * all three are still deployed somewhere.
95
+ * @throws ApiError when the answer is not a JSON array
100
96
  */
101
- export declare function embeddedOrders(data: unknown): JsonObject[];
97
+ export declare function ordersOf(data: unknown): JsonObject[];
102
98
  /**
103
99
  * The most aggressive price this market will accept on `side`.
104
100
  *
@@ -109,23 +105,6 @@ export declare function embeddedOrders(data: unknown): JsonObject[];
109
105
  * where the two bounds are equal and there is one legal price.
110
106
  */
111
107
  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
108
  export declare function server(endpoint: string): string;
130
109
  /**
131
110
  * Resolve an `--endpoint` value to config overrides. A bare marketplace id
@@ -152,7 +131,6 @@ export declare class Flexemarkets {
152
131
  private readonly _endpoint;
153
132
  private readonly _baseUrl;
154
133
  private readonly _bearerToken;
155
- private _apiRoot;
156
134
  private _account;
157
135
  private _user;
158
136
  private _tokenObj;
@@ -176,10 +154,7 @@ export declare class Flexemarkets {
176
154
  * `Snapshot.NO_SEQ` when the header is absent.
177
155
  */
178
156
  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
- */
157
+ /** PATCH with a JSON body -- the shape every session transition takes. */
183
158
  private _patch;
184
159
  /**
185
160
  * GET returning the body verbatim, for endpoints that answer with something
@@ -196,13 +171,21 @@ export declare class Flexemarkets {
196
171
  * cannot sign in as.
197
172
  */
198
173
  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. */
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
+ */
200
180
  approveAccount(accountName: string): Promise<Account | null>;
201
181
  /** One account by id. */
202
182
  accountById(accountId: number): Promise<Account | null>;
203
183
  /** One user by id. */
204
184
  userById(userId: number): Promise<Person>;
205
- /** 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
+ */
206
189
  identifiers(marketplaceId: number): Promise<string[]>;
207
190
  /** Delete the caller's own account. Its own route, not accounts/{yourId}. */
208
191
  deleteMyAccount(): Promise<void>;
@@ -236,7 +219,24 @@ export declare class Flexemarkets {
236
219
  managerOtpBundle(userIds: number[]): Promise<ManagerOtpBundle>;
237
220
  /** DELETE, whose answer is a status and nothing worth parsing. */
238
221
  private _delete;
239
- 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;
240
240
  marketplaces(): Promise<Marketplace[]>;
241
241
  marketplace(marketplaceId: number): Promise<Marketplace>;
242
242
  markets(marketplaceId: number): Promise<Market[]>;
@@ -256,6 +256,7 @@ export declare class Flexemarkets {
256
256
  */
257
257
  isManager(): boolean;
258
258
  hasRole(role: string): boolean;
259
+ /** The symbols of the marketplace's markets, read from the markets themselves. */
259
260
  symbols(marketplaceId: number): Promise<string[]>;
260
261
  /**
261
262
  * The marketplace's sessions — all of them.
@@ -264,10 +265,6 @@ export declare class Flexemarkets {
264
265
  * the `sessionIds` this used to accept was silently ignored: it returned the
265
266
  * whole history and looked like it had filtered. Filter the result; fm-ui
266
267
  * 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
268
  */
272
269
  sessions(marketplaceId: number): Promise<Session[]>;
273
270
  session(marketplaceId: number): Promise<Session>;
@@ -292,6 +289,11 @@ export declare class Flexemarkets {
292
289
  */
293
290
  submitMarket(marketplaceId: number, marketId: number, side: string, units: number): Promise<Order>;
294
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
+ */
295
297
  submitCancel(marketplaceId: number, marketId: number, originalId: number): Promise<Order>;
296
298
  /**
297
299
  * The active-orders snapshot: every resting limit order on the
@@ -312,27 +314,38 @@ export declare class Flexemarkets {
312
314
  * order differs. `Tape` sorts what it is given, so a caller seeding a tape
313
315
  * through `Desk` is unaffected; a caller reading this list directly
314
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.
315
333
  */
316
- recentTrades(marketplaceId: number, size?: number): Promise<Snapshot<Order[]>>;
317
334
  orders(marketplaceId: number, options?: {
318
335
  symbol?: string;
319
336
  sessionIds?: number[];
320
337
  }): Promise<Order[]>;
321
338
  /**
322
- * Tape in one market, in ascending order id.
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.
323
341
  *
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.
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.
334
346
  */
335
347
  trades(marketplaceId: number, symbol: string): Promise<Order[]>;
348
+ /** Comma-separated ids, matching the server's `?sessions=` filter. */
336
349
  holdings(marketplaceId: number, sessionIds?: number[] | null): Promise<Holding[]>;
337
350
  holding(marketplaceId: number): Promise<Holding>;
338
351
  /**
@@ -360,9 +373,15 @@ export declare class Flexemarkets {
360
373
  openSession(marketplaceId: number): Promise<Session>;
361
374
  pauseSession(marketplaceId: number): Promise<Session>;
362
375
  closeSession(marketplaceId: number): Promise<Session>;
363
- /** 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. */
364
383
  users(): Promise<Person[]>;
365
- /** The opening positions of one allocation. A V1 route, not on the API root. */
384
+ /** The opening positions of one allocation. */
366
385
  allotments(marketplaceId: number, allocationId: number): Promise<Allotment[]>;
367
386
  /**
368
387
  * Stage the opening positions for the next session.
@@ -378,9 +397,8 @@ export declare class Flexemarkets {
378
397
  /**
379
398
  * The holdings CSV, verbatim, for the current session or for given ones.
380
399
  *
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.
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.
384
402
  */
385
403
  downloadHoldings(marketplaceId: number, sessionIds?: number[] | null): Promise<string>;
386
404
  /**
@@ -424,8 +442,8 @@ export declare class Flexemarkets {
424
442
  * Take down a widget: the marketplace's for `key`, or one participant's.
425
443
  *
426
444
  * 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.
445
+ * only that participant's widget goes -- `participants/{userId}/widgets/{key}`
446
+ * -- and their marketplace widget for the same key, if any, shows again.
429
447
  *
430
448
  * An empty 404 is the server saying nothing was there. A 404 carrying a
431
449
  * failure document -- no such marketplace -- still throws, so a robot pointed