@flexemarkets/fm-sdk 0.12.0 → 0.14.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/README.md CHANGED
@@ -118,8 +118,8 @@ fm-ticker OPEN
118
118
 
119
119
  Symbol Bid Ask Spread Last trades
120
120
  ------ ------ ------ ------ -----------
121
- AAPL $ 9.50 $10.50 $ 1.00 $9.50 $10.00
122
- IBM $ 4.00 $ 5.00 $ 1.00 $4.50
121
+ AAPL 9.50 10.50 1.00 9.50 10.00
122
+ IBM 4.00 5.00 1.00 4.50
123
123
  ```
124
124
 
125
125
  The display refreshes on each order book update. Press `Ctrl-C` to stop.
package/dist/client.d.ts CHANGED
@@ -7,8 +7,21 @@ import type { Account, Allotment, ClientConnection, Holding, ManagerOtpBundle, M
7
7
  import { EventListener, type EventCallback } from "./stomp.js";
8
8
  import { type Desk, type Subscription } from "./desk.js";
9
9
  import type { Snapshot } from "./snapshot.js";
10
+ import { Page } from "./page.js";
10
11
  export declare const DEFAULT_ENDPOINT = "https://api.flexemarkets.com";
12
+ /**
13
+ * Base of every Flexemarkets error.
14
+ *
15
+ * An error that is the server's answer carries it: `statusCode`, the `body` as
16
+ * sent, and `reason`, the body's `error` -- `SESSION_CLOSED`, `ORDER_INVALID`,
17
+ * `ACCOUNT_TOKEN_EXPIRED` -- which is what a caller branches on, where the
18
+ * message is for people. All three are null for an error the SDK raised
19
+ * itself, and `reason` is null when the body named no error.
20
+ */
11
21
  export declare class FlexemarketsError extends Error {
22
+ statusCode: number | null;
23
+ reason: string | null;
24
+ body: string | null;
12
25
  }
13
26
  export declare class AuthenticationError extends FlexemarketsError {
14
27
  }
@@ -143,6 +156,12 @@ export declare function loadConfig(): Record<string, string>;
143
156
  * order carried the whole JSON document.
144
157
  */
145
158
  export declare function detail(body: string): string;
159
+ /** How long a request may take, start to finish, before it is given up. */
160
+ export declare const REQUEST_TIMEOUT_MS = 30000;
161
+ /** The timeout in force: {@link REQUEST_TIMEOUT_MS}, unless a test has shortened it. */
162
+ export declare const requestTimeout: {
163
+ ms: number;
164
+ };
146
165
  export declare class Flexemarkets {
147
166
  private readonly _clientDescription;
148
167
  private readonly _endpoint;
@@ -215,6 +234,14 @@ export declare class Flexemarkets {
215
234
  * `Snapshot.NO_SEQ` when the header is absent.
216
235
  */
217
236
  private _getSnapshot;
237
+ /** GET a body the answer needs a response header beside: a snapshot's sequence, a page's next link. */
238
+ private _getRead;
239
+ /**
240
+ * A page of a collection: `url` with `?limit=` and `?before=`, and the
241
+ * `before` of the page after it read from the `Link: <...>; rel="next"` the
242
+ * server sends while older rows remain.
243
+ */
244
+ private _page;
218
245
  /** PATCH with a JSON body -- the shape every session transition takes. */
219
246
  private _patch;
220
247
  /** PUT with a JSON body -- a robot parameter's configuration, say. */
@@ -255,6 +282,11 @@ export declare class Flexemarkets {
255
282
  deleteMyAccount(): Promise<void>;
256
283
  /** Every account on the server. Admin-only. */
257
284
  accounts(): Promise<Account[]>;
285
+ /**
286
+ * A page of `accounts()`: the newest `limit`, or of those whose id is below
287
+ * `before` -- a page's `next`. The server answers at most 5,000.
288
+ */
289
+ accountsPage(limit: number, before?: number): Promise<Page<Account>>;
258
290
  /** Delete an account. Destructive, and takes its users with it. */
259
291
  deleteAccount(accountId: number): Promise<void>;
260
292
  /** Create a user in the caller's account. */
@@ -303,7 +335,18 @@ export declare class Flexemarkets {
303
335
  * header, where 0.3 posted it as a multipart upload to an `/uploads`
304
336
  * segment. Bytes, not a string, so the file's own encoding survives.
305
337
  */
338
+ /**
339
+ * Send a create under an `Idempotency-Key`, and once more under the same key
340
+ * if its answer was lost. A create that lost its connection may or may not
341
+ * have landed; fm-server 4.17 answers a key it already holds with what it
342
+ * answered the first time (its IdempotencyFilter), so the resend makes one
343
+ * marketplace, market or call, never two. Orders do the same with their own
344
+ * `submissionId`.
345
+ */
346
+ private _create;
306
347
  private _sendCsv;
348
+ /** CSV as the request body, declared text/csv; see {@link _sendCsv}. */
349
+ private _sendCsvContent;
307
350
  /**
308
351
  * A V1 route. 0.4 addresses every route from the server rather than through
309
352
  * the HAL root's links: the path is knowable without fetching anything
@@ -313,6 +356,11 @@ export declare class Flexemarkets {
313
356
  /** The V1 route of one marketplace, under which nearly everything lives. */
314
357
  private _marketplace;
315
358
  marketplaces(): Promise<Marketplace[]>;
359
+ /**
360
+ * A page of `marketplaces()`: the newest `limit`, or of those whose id is below
361
+ * `before` -- a page's `next`. The server answers at most 5,000.
362
+ */
363
+ marketplacesPage(limit: number, before?: number): Promise<Page<Marketplace>>;
316
364
  marketplace(marketplaceId: number): Promise<Marketplace>;
317
365
  markets(marketplaceId: number): Promise<Market[]>;
318
366
  /**
@@ -342,8 +390,30 @@ export declare class Flexemarkets {
342
390
  * already does.
343
391
  */
344
392
  sessions(marketplaceId: number): Promise<Session[]>;
393
+ /**
394
+ * A page of `sessions()`: the newest `limit`, or of those whose id is below
395
+ * `before` -- a page's `next`. The server answers at most 5,000.
396
+ */
397
+ sessionsPage(marketplaceId: number, limit: number, before?: number): Promise<Page<Session>>;
345
398
  session(marketplaceId: number): Promise<Session>;
346
- submitLimit(marketplaceId: number, marketId: number, side: string, units: number, price: number): Promise<Order>;
399
+ /**
400
+ * Place a limit order.
401
+ *
402
+ * A private market matches an order only with one aimed back at its owner, so
403
+ * an order there names its counterparty: by `ownerTargetId` when the caller
404
+ * knows it, or by `ownerTarget`, the allotment name. The id is the
405
+ * unambiguous one, but only a manager can learn ids -- a participant's
406
+ * `identifiers()` are names -- so a participant has the name and nothing
407
+ * else. Name one or the other, not both.
408
+ *
409
+ * `clientDescription` is this order's own reference, as the server keeps it
410
+ * on the order; it defaults to the description this client connected with.
411
+ */
412
+ submitLimit(marketplaceId: number, marketId: number, side: string, units: number, price: number, options?: {
413
+ ownerTarget?: string;
414
+ ownerTargetId?: number;
415
+ clientDescription?: string;
416
+ }): Promise<Order>;
347
417
  /**
348
418
  * Cross the book: buy at the highest price this market allows, sell at the
349
419
  * lowest. Immediate or cancel — whatever does not fill is cancelled.
@@ -410,6 +480,12 @@ export declare class Flexemarkets {
410
480
  symbol?: string;
411
481
  sessionIds?: number[];
412
482
  }): Promise<Order[]>;
483
+ /**
484
+ * A page of `orders()` with no filter -- cancellations left out, as there:
485
+ * the newest `limit`, or of those whose id is below `before` -- a page's
486
+ * `next`. The server answers at most 5,000.
487
+ */
488
+ ordersPage(marketplaceId: number, limit: number, before?: number): Promise<Page<Order>>;
413
489
  /**
414
490
  * One market's traded legs, as many as the server gives in one read
415
491
  * ({@link MAX_TRADED_LEGS}), in the server's order.
@@ -431,6 +507,11 @@ export declare class Flexemarkets {
431
507
  * filter on the result.
432
508
  */
433
509
  connections(marketplaceId: number): Promise<ClientConnection[]>;
510
+ /**
511
+ * A page of `connections()`: the newest `limit`, or of those whose id is below
512
+ * `before` -- a page's `next`. The server answers at most 5,000.
513
+ */
514
+ connectionsPage(marketplaceId: number, limit: number, before?: number): Promise<Page<ClientConnection>>;
434
515
  /**
435
516
  * Create a marketplace from its JSON definition, returning what was made.
436
517
  *
@@ -459,6 +540,11 @@ export declare class Flexemarkets {
459
540
  private _sessionState;
460
541
  /** Everyone in the caller's account. */
461
542
  users(): Promise<Person[]>;
543
+ /**
544
+ * A page of `users()`: the newest `limit`, or of those whose id is below
545
+ * `before` -- a page's `next`. The server answers at most 5,000.
546
+ */
547
+ usersPage(limit: number, before?: number): Promise<Page<Person>>;
462
548
  /** The opening positions of one allocation. */
463
549
  allotments(marketplaceId: number, allocationId: number): Promise<Allotment[]>;
464
550
  /**
@@ -484,6 +570,17 @@ export declare class Flexemarkets {
484
570
  * the same terms as {@link allocate}.
485
571
  */
486
572
  uploadHoldings(marketplaceId: number, filename: string): Promise<Holding[]>;
573
+ /**
574
+ * Stage an allocation from holdings CSV text, as {@link uploadHoldings} does
575
+ * from a file.
576
+ *
577
+ * For a program that builds the CSV rather than reading one -- an admin
578
+ * robot writing back the holdings it downloaded and changed -- which
579
+ * otherwise writes a file only to have it read again. The text is sent as it
580
+ * is; a `# holdings -- begin` / `-- end` frame around it is accepted, as in a
581
+ * downloaded file.
582
+ */
583
+ uploadHoldingsCsv(marketplaceId: number, csv: string): Promise<Holding[]>;
487
584
  /**
488
585
  * Load per-participant private state from a CSV, returning what was stored.
489
586
  *
@@ -548,6 +645,11 @@ export declare class Flexemarkets {
548
645
  clearNow(marketplaceId: number, marketId: number): Promise<MarketCall>;
549
646
  /** Every call the marketplace's call markets have made, oldest first; one session's with `sessionId`. */
550
647
  calls(marketplaceId: number, sessionId?: number): Promise<MarketCall[]>;
648
+ /**
649
+ * A page of `calls()`: the newest `limit`, or of those whose id is below
650
+ * `before` -- a page's `next`. The server answers at most 5,000.
651
+ */
652
+ callsPage(marketplaceId: number, limit: number, before?: number): Promise<Page<MarketCall>>;
551
653
  /**
552
654
  * Every robot the marketplace's robot host offers, with whether it is
553
655
  * enabled here and how a manager has configured its parameters.
@@ -611,15 +713,27 @@ export declare class Flexemarkets {
611
713
  * Returns an unsubscribe function rather than an object with `close()`,
612
714
  * matching what Desk's `on*` handlers already return here. Java
613
715
  * returns a `Subscription`; both names describe the same lifetime.
716
+ *
717
+ * With `history`, the first orders update is every order of the current
718
+ * session as this caller may see it -- cancelled and split ones included, a
719
+ * counterparty's private order named from the caller's side -- stamped with
720
+ * the `seq` it was read at, and each reconnect delivers it again. That is
721
+ * fm-server's original subscribe, and the only whole history a participant
722
+ * can read: the REST history is a manager's. Without it the first update is
723
+ * empty and the book comes from `activeOrders`. A history is one frame, so on
724
+ * a session with a very long one it is a large frame -- fm-server's V1
725
+ * subscribe exists to avoid exactly that.
614
726
  */
615
- subscribe(marketplaceId: number, callback: EventCallback): Promise<Subscription>;
727
+ subscribe(marketplaceId: number, callback: EventCallback, options?: {
728
+ history?: boolean;
729
+ }): Promise<Subscription>;
616
730
  /**
617
731
  * Package-private helper used by {@link DefaultDesk} (Phase 2d)
618
732
  * to own its own EventListener subscription rather than clobbering
619
733
  * the singleton {@link #_eventListener}. Lets multiple
620
734
  * desk(marketplaceId) calls coexist within one Flexemarkets.
621
735
  */
622
- _connectEvents(marketplaceId: number, callback: EventCallback): Promise<EventListener>;
736
+ _connectEvents(marketplaceId: number, callback: EventCallback, history?: boolean): Promise<EventListener>;
623
737
  /** Reconnect the WebSocket after a transport error. */
624
738
  reconnect(): Promise<void>;
625
739
  close(): void;