@flexemarkets/fm-sdk 0.4.0 → 0.6.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,7 +3,7 @@
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
8
  import { type Desk, type Subscription } from "./desk.js";
9
9
  import type { Snapshot } from "./snapshot.js";
@@ -16,6 +16,20 @@ export declare class AuthorizationError extends FlexemarketsError {
16
16
  }
17
17
  export declare class InvalidArgumentError extends FlexemarketsError {
18
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
+ }
19
33
  export declare class ConnectionFailedError extends FlexemarketsError {
20
34
  }
21
35
  export declare class ConfigurationError extends FlexemarketsError {
@@ -77,6 +91,8 @@ export declare function parseMarketplace(data: JsonObject): Marketplace;
77
91
  export declare function parseSession(data: JsonObject): Session;
78
92
  export declare function parseOrder(data: JsonObject): Order;
79
93
  export declare function parseParticipantState(data: JsonObject): ParticipantState;
94
+ export declare function parseRobotParameterConfig(data: JsonObject): RobotParameterConfig;
95
+ export declare function parseMarketplaceRobot(data: JsonObject): MarketplaceRobot;
80
96
  export declare function parseWidget(data: JsonObject): Widget;
81
97
  export declare function parseHolding(data: JsonObject): Holding;
82
98
  export declare function parseConnection(data: JsonObject): ClientConnection;
@@ -130,10 +146,17 @@ export declare class Flexemarkets {
130
146
  private readonly _clientDescription;
131
147
  private readonly _endpoint;
132
148
  private readonly _baseUrl;
133
- private readonly _bearerToken;
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;
134
158
  private _account;
135
159
  private _user;
136
- private _tokenObj;
137
160
  private _eventListener;
138
161
  private constructor();
139
162
  /** Connect to the Flexemarkets API. */
@@ -145,7 +168,40 @@ export declare class Flexemarkets {
145
168
  get userId(): number;
146
169
  get endpointUrl(): string;
147
170
  get endpointMarketplaceId(): number;
171
+ /** What the previous call cost, waiting to ride on the next as Client-Timing. */
172
+ private _lastTiming;
173
+ /**
174
+ * Every call the client makes, timed: it carries what the previous call cost
175
+ * -- `rtt=<ns>`, and `;net=<ns>` when the server's `Server-Timing: st=` said
176
+ * its own share -- the format the Java SDK and fm-ui send and fm-server's
177
+ * ApiMetricsFilter reads, so a robot's latency shows in the Connections
178
+ * view. Each figure arrives one call late, since a round trip is not known
179
+ * until its own request has gone; taken rather than read, so it is reported
180
+ * once; net= left out rather than zero when the server's share is unknown.
181
+ * Measured to the response headers; a call that throws records nothing.
182
+ * _fetch sends through this, so a resend after renewing the token is
183
+ * timed as its own call.
184
+ */
185
+ private _timedFetch;
148
186
  private _authHeaders;
187
+ /** The Authorization header for the current sign-in. */
188
+ private get _bearerToken();
189
+ /**
190
+ * fetch with this client's token; if it has expired, renew it once and send
191
+ * again. Tokens live 24 hours, so a robot that ran longer ended the first
192
+ * time it asked for anything after that, or looped on the refusal -- a Utah
193
+ * poller, about 250 times a day at 00Z.
194
+ */
195
+ private _fetch;
196
+ /**
197
+ * Sign in again with the credentials this client was made with. False when
198
+ * it was given a token rather than credentials, or the sign-in fails; the
199
+ * caller then answers with the refusal it had. `presented` is the header
200
+ * the refused request or stream connect carried: one another caller has
201
+ * already replaced is not renewed again, and concurrent callers share one
202
+ * sign-in.
203
+ */
204
+ private _renewToken;
149
205
  private _get;
150
206
  /**
151
207
  * GET helper that returns the parsed body bundled with the
@@ -156,6 +212,9 @@ export declare class Flexemarkets {
156
212
  private _getSnapshot;
157
213
  /** PATCH with a JSON body -- the shape every session transition takes. */
158
214
  private _patch;
215
+ /** PUT with a JSON body -- a robot parameter's configuration, say. */
216
+ private _put;
217
+ private _sendJson;
159
218
  /**
160
219
  * GET returning the body verbatim, for endpoints that answer with something
161
220
  * other than JSON — the holdings download is a CSV, and JSON.parse dies on
@@ -455,6 +514,29 @@ export declare class Flexemarkets {
455
514
  * participant -- what a manager reads to check on a robot.
456
515
  */
457
516
  allWidgets(marketplaceId: number): Promise<Widget[]>;
517
+ /**
518
+ * Every robot the marketplace's robot host offers, with whether it is
519
+ * enabled here and how a manager has configured its parameters.
520
+ *
521
+ * Readable by participants as well as managers: it is what a launch form is
522
+ * built from. Asks the robot host for its catalogue, so it fails when the
523
+ * host cannot be reached.
524
+ */
525
+ marketplaceRobots(marketplaceId: number): Promise<MarketplaceRobot[]>;
526
+ /**
527
+ * Set a robot parameter's value in a marketplace, and whether participants
528
+ * may move it, returning the configuration as stored.
529
+ *
530
+ * A null `control` fixes the value: participants launching the robot see it
531
+ * read-only. A control exposes it within that range, starting at `value`,
532
+ * which must lie inside it. The server refuses a parameter the robot does
533
+ * not declare, a platform parameter, and a range outside the robot's own
534
+ * bounds.
535
+ *
536
+ * The control goes up flat beside the value, and a fixed parameter sends the
537
+ * value alone: the server reads any bound as a control.
538
+ */
539
+ configureRobotParameter(marketplaceId: number, robotId: string, paramName: string, value: string, control: RobotParameterControl | null): Promise<RobotParameterConfig>;
458
540
  private readonly _sharedViews;
459
541
  private readonly _sharedViewPromises;
460
542
  /**
@@ -468,8 +550,16 @@ export declare class Flexemarkets {
468
550
  * callers with different identities each get their own desk —
469
551
  * multi-tenant WS multiplexing is a server-side concern, not a
470
552
  * client-side one.
471
- */
472
- desk(marketplaceId: number): Promise<Desk>;
553
+ *
554
+ * `submitLimit` on the returned handle rejects, without sending, an order
555
+ * the desk knows fm-server would refuse -- a session that is not open, a
556
+ * side the holding does not grant -- with {@link OrderRefusedLocallyError}.
557
+ * `{ refuseLocally: false }` sends every order and leaves the answer to the
558
+ * server.
559
+ */
560
+ desk(marketplaceId: number, options?: {
561
+ refuseLocally?: boolean;
562
+ }): Promise<Desk>;
473
563
  _releaseSharedView(marketplaceId: number): void;
474
564
  /** Start receiving real-time events via WebSocket STOMP. */
475
565
  listen(marketplaceId: number, callback: EventCallback): Promise<void>;
package/dist/client.js CHANGED
@@ -32,6 +32,23 @@ export class AuthorizationError extends FlexemarketsError {
32
32
  }
33
33
  export class InvalidArgumentError extends FlexemarketsError {
34
34
  }
35
+ /**
36
+ * An order the desk did not send, because fm-server would refuse it.
37
+ *
38
+ * Rejected by `Desk.submitLimit` when the session the desk holds is not open,
39
+ * or the holding it holds does not grant the order's side in that market --
40
+ * the two refusals fm-server answers with 400 `SESSION_CLOSED` and
41
+ * `ORDER_NOT_ALLOWED`, which `reason` names. An {@link InvalidArgumentError},
42
+ * so a caller catching the server's answer catches this too.
43
+ * `flexemarkets.desk(id, { refuseLocally: false })` sends every order instead.
44
+ */
45
+ export class OrderRefusedLocallyError extends InvalidArgumentError {
46
+ reason;
47
+ constructor(reason, message) {
48
+ super(message);
49
+ this.reason = reason;
50
+ }
51
+ }
35
52
  export class ConnectionFailedError extends FlexemarketsError {
36
53
  }
37
54
  export class ConfigurationError extends FlexemarketsError {
@@ -209,6 +226,53 @@ export function parseParticipantState(data) {
209
226
  fields: { ...(data.fields ?? {}) },
210
227
  };
211
228
  }
229
+ function numberOrNull(value) {
230
+ return value === null || value === undefined ? null : Number(value);
231
+ }
232
+ function parseRobotParameter(data) {
233
+ return {
234
+ name: data.name ?? "",
235
+ label: data.label ?? null,
236
+ description: data.description ?? null,
237
+ type: data.type ?? null,
238
+ valueType: data.valueType ?? null,
239
+ // The robots write "required": null for a parameter that is not.
240
+ required: data.required === true,
241
+ defaultValue: data.default ?? null,
242
+ unit: data.unit ?? null,
243
+ min: numberOrNull(data.min),
244
+ max: numberOrNull(data.max),
245
+ };
246
+ }
247
+ export function parseRobotParameterConfig(data) {
248
+ const control = data.control ?? null;
249
+ return {
250
+ marketplaceId: data.marketplaceId ?? null,
251
+ robotId: data.robotId ?? "",
252
+ paramName: data.paramName ?? "",
253
+ value: data.value ?? "",
254
+ control: control === null
255
+ ? null
256
+ : { min: Number(control.min), max: Number(control.max), step: Number(control.step) },
257
+ exposed: data.exposed === true,
258
+ };
259
+ }
260
+ export function parseMarketplaceRobot(data) {
261
+ const manifest = data.manifest ?? {};
262
+ const groups = manifest.parameters ?? {};
263
+ const group = (name) => (groups[name] ?? []).map(parseRobotParameter);
264
+ return {
265
+ manifest: {
266
+ id: manifest.id ?? "",
267
+ version: manifest.version ?? null,
268
+ name: manifest.name ?? null,
269
+ description: manifest.description ?? null,
270
+ parameters: { manager: group("manager"), user: group("user"), platform: group("platform") },
271
+ },
272
+ enabled: data.enabled === true,
273
+ configuration: (data.configuration ?? []).map(parseRobotParameterConfig),
274
+ };
275
+ }
212
276
  export function parseWidget(data) {
213
277
  return {
214
278
  id: data.id ?? null,
@@ -542,19 +606,38 @@ function suggestedNameIn(body) {
542
606
  // ---------------------------------------------------------------------------
543
607
  // Flexemarkets client
544
608
  // ---------------------------------------------------------------------------
609
+ /** A 401 that says the token ran out, as distinct from one that is wrong. */
610
+ async function tokenExpired(resp) {
611
+ if (resp.status !== 401)
612
+ return false;
613
+ try {
614
+ const body = JSON.parse(await resp.clone().text());
615
+ return body.error === "ACCOUNT_TOKEN_EXPIRED";
616
+ }
617
+ catch {
618
+ return false;
619
+ }
620
+ }
545
621
  export class Flexemarkets {
546
622
  _clientDescription;
547
623
  _endpoint;
548
624
  _baseUrl;
549
- _bearerToken;
625
+ /**
626
+ * The sign-in this client presents, replaced whole when an expired one is
627
+ * renewed (see {@link _renewToken}); the bearer header is derived from it,
628
+ * so `token()` and every request agree on which token is current.
629
+ */
630
+ _tokenObj;
631
+ /** Kept only to sign in again when the token runs out; null for a client given a token. */
632
+ _credentials = null;
633
+ _renewing = null;
550
634
  _account;
551
635
  _user;
552
- _tokenObj;
553
636
  _eventListener = null;
554
- constructor(endpoint, baseUrl, bearerToken, clientDescription) {
637
+ constructor(endpoint, baseUrl, tokenObj, clientDescription) {
555
638
  this._endpoint = endpoint;
556
639
  this._baseUrl = baseUrl;
557
- this._bearerToken = bearerToken;
640
+ this._tokenObj = tokenObj;
558
641
  this._clientDescription = clientDescription;
559
642
  }
560
643
  /** Connect to the Flexemarkets API. */
@@ -579,9 +662,10 @@ export class Flexemarkets {
579
662
  const baseUrl = server(ep);
580
663
  // Authenticate
581
664
  const tokenObj = await signIn(baseUrl, config, desc);
582
- const bearer = `Bearer ${tokenObj.token}`;
583
- const fm = new Flexemarkets(ep, baseUrl, bearer, desc);
584
- fm._tokenObj = tokenObj;
665
+ const fm = new Flexemarkets(ep, baseUrl, tokenObj, desc);
666
+ if (config.account && config.email && config.password && !(config.token && isValidToken(config.token))) {
667
+ fm._credentials = { ...config };
668
+ }
585
669
  fm._account = tokenObj.account;
586
670
  fm._user = tokenObj.person;
587
671
  return fm;
@@ -609,11 +693,87 @@ export class Flexemarkets {
609
693
  return resourceId(this._endpoint);
610
694
  }
611
695
  // -- internal HTTP helpers -------------------------------------------------
696
+ /** What the previous call cost, waiting to ride on the next as Client-Timing. */
697
+ _lastTiming = null;
698
+ /**
699
+ * Every call the client makes, timed: it carries what the previous call cost
700
+ * -- `rtt=<ns>`, and `;net=<ns>` when the server's `Server-Timing: st=` said
701
+ * its own share -- the format the Java SDK and fm-ui send and fm-server's
702
+ * ApiMetricsFilter reads, so a robot's latency shows in the Connections
703
+ * view. Each figure arrives one call late, since a round trip is not known
704
+ * until its own request has gone; taken rather than read, so it is reported
705
+ * once; net= left out rather than zero when the server's share is unknown.
706
+ * Measured to the response headers; a call that throws records nothing.
707
+ * _fetch sends through this, so a resend after renewing the token is
708
+ * timed as its own call.
709
+ */
710
+ async _timedFetch(url, init) {
711
+ const headers = new Headers(init.headers);
712
+ const timing = this._lastTiming;
713
+ this._lastTiming = null;
714
+ if (timing !== null)
715
+ headers.set("Client-Timing", timing);
716
+ const started = process.hrtime.bigint();
717
+ const resp = await fetch(url, { ...init, headers });
718
+ const rtt = process.hrtime.bigint() - started;
719
+ const served = /st=(\d+)/.exec(resp.headers.get("Server-Timing") ?? "");
720
+ this._lastTiming = served
721
+ ? `rtt=${rtt};net=${rtt > BigInt(served[1]) ? rtt - BigInt(served[1]) : 0n}`
722
+ : `rtt=${rtt}`;
723
+ return resp;
724
+ }
612
725
  _authHeaders() {
613
726
  return { Authorization: this._bearerToken };
614
727
  }
728
+ /** The Authorization header for the current sign-in. */
729
+ get _bearerToken() {
730
+ return `Bearer ${this._tokenObj.token}`;
731
+ }
732
+ /**
733
+ * fetch with this client's token; if it has expired, renew it once and send
734
+ * again. Tokens live 24 hours, so a robot that ran longer ended the first
735
+ * time it asked for anything after that, or looped on the refusal -- a Utah
736
+ * poller, about 250 times a day at 00Z.
737
+ */
738
+ async _fetch(url, init) {
739
+ const presented = this._bearerToken;
740
+ const resp = await this._timedFetch(url, init);
741
+ if (!(await tokenExpired(resp)) || !(await this._renewToken(presented)))
742
+ return resp;
743
+ const headers = { ...init.headers, Authorization: this._bearerToken };
744
+ return this._timedFetch(url, { ...init, headers });
745
+ }
746
+ /**
747
+ * Sign in again with the credentials this client was made with. False when
748
+ * it was given a token rather than credentials, or the sign-in fails; the
749
+ * caller then answers with the refusal it had. `presented` is the header
750
+ * the refused request or stream connect carried: one another caller has
751
+ * already replaced is not renewed again, and concurrent callers share one
752
+ * sign-in.
753
+ */
754
+ async _renewToken(presented) {
755
+ if (this._credentials === null)
756
+ return false;
757
+ if (presented !== this._bearerToken)
758
+ return true;
759
+ if (this._renewing === null) {
760
+ this._renewing = (async () => {
761
+ try {
762
+ this._tokenObj = await signIn(this._baseUrl, this._credentials, this._clientDescription);
763
+ return true;
764
+ }
765
+ catch {
766
+ return false;
767
+ }
768
+ finally {
769
+ this._renewing = null;
770
+ }
771
+ })();
772
+ }
773
+ return this._renewing;
774
+ }
615
775
  async _get(url) {
616
- const resp = await fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
776
+ const resp = await this._fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
617
777
  headers: {
618
778
  ...this._authHeaders(),
619
779
  Accept: "application/json",
@@ -631,7 +791,7 @@ export class Flexemarkets {
631
791
  * `Snapshot.NO_SEQ` when the header is absent.
632
792
  */
633
793
  async _getSnapshot(url) {
634
- const resp = await fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
794
+ const resp = await this._fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
635
795
  headers: {
636
796
  ...this._authHeaders(),
637
797
  Accept: "application/json",
@@ -646,8 +806,15 @@ export class Flexemarkets {
646
806
  }
647
807
  /** PATCH with a JSON body -- the shape every session transition takes. */
648
808
  async _patch(url, json) {
649
- const resp = await fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
650
- method: "PATCH",
809
+ return this._sendJson("PATCH", url, json);
810
+ }
811
+ /** PUT with a JSON body -- a robot parameter's configuration, say. */
812
+ async _put(url, json) {
813
+ return this._sendJson("PUT", url, json);
814
+ }
815
+ async _sendJson(method, url, json) {
816
+ const resp = await this._fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
817
+ method,
651
818
  headers: {
652
819
  ...this._authHeaders(),
653
820
  "Content-Type": "application/json",
@@ -666,7 +833,7 @@ export class Flexemarkets {
666
833
  * the header row.
667
834
  */
668
835
  async _getText(url) {
669
- const resp = await fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
836
+ const resp = await this._fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
670
837
  headers: {
671
838
  ...this._authHeaders(),
672
839
  Accept: "text/csv, */*",
@@ -678,7 +845,7 @@ export class Flexemarkets {
678
845
  return body;
679
846
  }
680
847
  async _post(url, json) {
681
- const resp = await fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
848
+ const resp = await this._fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
682
849
  method: "POST",
683
850
  headers: {
684
851
  ...this._authHeaders(),
@@ -844,7 +1011,7 @@ export class Flexemarkets {
844
1011
  }
845
1012
  /** DELETE, whose answer is a status and nothing worth parsing. */
846
1013
  async _delete(url) {
847
- const resp = await fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
1014
+ const resp = await this._fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
848
1015
  method: "DELETE",
849
1016
  headers: { ...this._authHeaders(), Accept: "application/json" },
850
1017
  });
@@ -855,7 +1022,7 @@ export class Flexemarkets {
855
1022
  * DELETE whose answer is the resource as it ended -- an order's CANCEL.
856
1023
  */
857
1024
  async _deleteFor(url) {
858
- const resp = await fetch(url, {
1025
+ const resp = await this._fetch(url, {
859
1026
  method: "DELETE",
860
1027
  headers: { ...this._authHeaders(), Accept: "application/json", "User-Agent": FM_NETWORK_CLIENT },
861
1028
  });
@@ -869,7 +1036,7 @@ export class Flexemarkets {
869
1036
  * segment. Bytes, not a string, so the file's own encoding survives.
870
1037
  */
871
1038
  async _sendCsv(method, url, filename) {
872
- const resp = await fetch(url, {
1039
+ const resp = await this._fetch(url, {
873
1040
  method,
874
1041
  headers: {
875
1042
  ...this._authHeaders(),
@@ -1269,7 +1436,7 @@ export class Flexemarkets {
1269
1436
  async removeWidget(marketplaceId, key, userId) {
1270
1437
  const owner = userId !== undefined && userId !== null ? `/participants/${userId}` : "";
1271
1438
  const url = `${this._marketplace(marketplaceId)}${owner}/widgets/${encodeURIComponent(key)}`;
1272
- const resp = await fetch(url, {
1439
+ const resp = await this._fetch(url, {
1273
1440
  method: "DELETE",
1274
1441
  headers: { ...this._authHeaders(), Accept: "application/json", "User-Agent": FM_NETWORK_CLIENT },
1275
1442
  });
@@ -1287,6 +1454,42 @@ export class Flexemarkets {
1287
1454
  const data = await this._get(`${this._marketplace(marketplaceId)}/widgets?participant=all`);
1288
1455
  return data.map(parseWidget);
1289
1456
  }
1457
+ /**
1458
+ * Every robot the marketplace's robot host offers, with whether it is
1459
+ * enabled here and how a manager has configured its parameters.
1460
+ *
1461
+ * Readable by participants as well as managers: it is what a launch form is
1462
+ * built from. Asks the robot host for its catalogue, so it fails when the
1463
+ * host cannot be reached.
1464
+ */
1465
+ async marketplaceRobots(marketplaceId) {
1466
+ const data = await this._get(`${this._marketplace(marketplaceId)}/robots`);
1467
+ return data.map(parseMarketplaceRobot);
1468
+ }
1469
+ /**
1470
+ * Set a robot parameter's value in a marketplace, and whether participants
1471
+ * may move it, returning the configuration as stored.
1472
+ *
1473
+ * A null `control` fixes the value: participants launching the robot see it
1474
+ * read-only. A control exposes it within that range, starting at `value`,
1475
+ * which must lie inside it. The server refuses a parameter the robot does
1476
+ * not declare, a platform parameter, and a range outside the robot's own
1477
+ * bounds.
1478
+ *
1479
+ * The control goes up flat beside the value, and a fixed parameter sends the
1480
+ * value alone: the server reads any bound as a control.
1481
+ */
1482
+ async configureRobotParameter(marketplaceId, robotId, paramName, value, control) {
1483
+ const body = { value };
1484
+ if (control !== null) {
1485
+ body.min = control.min;
1486
+ body.max = control.max;
1487
+ body.step = control.step;
1488
+ }
1489
+ const url = `${this._marketplace(marketplaceId)}/robots/${encodeURIComponent(robotId)}`
1490
+ + `/parameters/${encodeURIComponent(paramName)}`;
1491
+ return parseRobotParameterConfig(await this._put(url, body));
1492
+ }
1290
1493
  // -- events / WebSocket ----------------------------------------------------
1291
1494
  _sharedViews = new Map();
1292
1495
  _sharedViewPromises = new Map();
@@ -1301,12 +1504,19 @@ export class Flexemarkets {
1301
1504
  * callers with different identities each get their own desk —
1302
1505
  * multi-tenant WS multiplexing is a server-side concern, not a
1303
1506
  * client-side one.
1507
+ *
1508
+ * `submitLimit` on the returned handle rejects, without sending, an order
1509
+ * the desk knows fm-server would refuse -- a session that is not open, a
1510
+ * side the holding does not grant -- with {@link OrderRefusedLocallyError}.
1511
+ * `{ refuseLocally: false }` sends every order and leaves the answer to the
1512
+ * server.
1304
1513
  */
1305
- async desk(marketplaceId) {
1514
+ async desk(marketplaceId, options = {}) {
1515
+ const refuseLocally = options.refuseLocally ?? true;
1306
1516
  const existing = this._sharedViews.get(marketplaceId);
1307
1517
  if (existing !== undefined) {
1308
1518
  existing.refCount++;
1309
- return new DeskHandle(existing.desk, () => this._releaseSharedView(marketplaceId));
1519
+ return new DeskHandle(existing.desk, () => this._releaseSharedView(marketplaceId), refuseLocally);
1310
1520
  }
1311
1521
  // Two concurrent desk() calls for the same marketplaceId need
1312
1522
  // to dedupe — JS is single-threaded but awaits introduce
@@ -1333,10 +1543,10 @@ export class Flexemarkets {
1333
1543
  if (registered.desk !== shared)
1334
1544
  shared.close();
1335
1545
  registered.refCount++;
1336
- return new DeskHandle(registered.desk, () => this._releaseSharedView(marketplaceId));
1546
+ return new DeskHandle(registered.desk, () => this._releaseSharedView(marketplaceId), refuseLocally);
1337
1547
  }
1338
1548
  this._sharedViews.set(marketplaceId, { desk: shared, refCount: 1 });
1339
- return new DeskHandle(shared, () => this._releaseSharedView(marketplaceId));
1549
+ return new DeskHandle(shared, () => this._releaseSharedView(marketplaceId), refuseLocally);
1340
1550
  }
1341
1551
  _releaseSharedView(marketplaceId) {
1342
1552
  const entry = this._sharedViews.get(marketplaceId);
@@ -1349,7 +1559,18 @@ export class Flexemarkets {
1349
1559
  }
1350
1560
  /** Start receiving real-time events via WebSocket STOMP. */
1351
1561
  async listen(marketplaceId, callback) {
1352
- this._eventListener = await this._connectEvents(marketplaceId, callback);
1562
+ // The stream this replaces is closed, not dropped with its socket,
1563
+ // heartbeats and reconnects still running.
1564
+ const previous = this._eventListener;
1565
+ this._eventListener = null;
1566
+ if (previous !== null)
1567
+ previous.close();
1568
+ const listener = await this._connectEvents(marketplaceId, callback);
1569
+ // Another listen() may have finished while this one connected.
1570
+ const raced = this._eventListener;
1571
+ if (raced !== null)
1572
+ raced.close();
1573
+ this._eventListener = listener;
1353
1574
  }
1354
1575
  /**
1355
1576
  * Open an *independent* event subscription, delivering to `callback` until
@@ -1382,7 +1603,7 @@ export class Flexemarkets {
1382
1603
  const wsUrl = server(this._endpoint)
1383
1604
  .replace("https://", "wss://")
1384
1605
  .replace("http://", "ws://") + "/events";
1385
- const events = new EventListener(wsUrl, this._bearerToken, marketplaceId, callback, this._clientDescription, parseHolding, parseOrder);
1606
+ const events = new EventListener(wsUrl, () => this._bearerToken, marketplaceId, callback, this._clientDescription, parseHolding, parseOrder, (presented) => this._renewToken(presented));
1386
1607
  await events.start();
1387
1608
  return events;
1388
1609
  }