@flexemarkets/fm-sdk 0.0.10 → 0.1.0

package/dist/client.js

@@ -7,8 +7,10 @@ import { readFileSync, existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { orderedSecurities, toOrderType, toSide, unitGrid } from "./types.js";
+import { toInstant } from "./timestamps.js";
 import { EventListener, NO_SEQ } from "./stomp.js";
-import { DefaultMarketView, MarketViewHandle } from "./market-view.js";
+import { DefaultMarketView, MarketViewHandle, } from "./market-view.js";
 function readVersion() {
     try {
         const dir = fileURLToPath(new URL(".", import.meta.url));
@@ -37,7 +39,65 @@ export class ConnectionFailedError extends FlexemarketsError {
 }
 export class ConfigurationError extends FlexemarketsError {
 }
-function parsePerson(data) {
+/**
+ * A response the SDK has no better name for, carrying its status and body.
+ *
+ * The fallback. A status with a meaning worth acting on gets its own type —
+ * {@link AuthenticationError}, {@link ConflictError} — and this is what is
+ * left, so a caller can read the status rather than parse a message.
+ */
+export class HttpError extends FlexemarketsError {
+    statusCode;
+    body;
+    constructor(statusCode, body) {
+        super(`HTTP ${statusCode}: ${body}`);
+        this.statusCode = statusCode;
+        this.body = body;
+    }
+}
+/**
+ * The call could not be completed: the transport failed, or the response was
+ * not something the SDK could read.
+ *
+ * Distinct from {@link HttpError}, which means the server answered and the
+ * answer was an error. This means there was no usable answer at all — a
+ * malformed body, or a link the API root does not carry.
+ */
+export class ApiError extends FlexemarketsError {
+}
+/** A 409. The Java and Python SDKs have raised this since the admin surface landed. */
+export class ConflictError extends FlexemarketsError {
+}
+/**
+ * An account name was taken, and the server proposed another.
+ *
+ * A subclass of {@link ConflictError} rather than a sibling, so a caller that
+ * handles conflicts generally still catches this one. The suggestion is worth
+ * surfacing rather than retrying blindly: it is the name the account would end
+ * up known by.
+ */
+export class AccountNameConflictError extends ConflictError {
+    requestedName;
+    suggestedName;
+    constructor(message, requestedName, suggestedName) {
+        super(message);
+        this.requestedName = requestedName;
+        this.suggestedName = suggestedName;
+    }
+}
+/**
+ * A user could not be deleted because they still own marketplace data —
+ * orders or allotments. Deleting them would orphan it, so the server refuses;
+ * the caller has to decide what happens to the data first.
+ */
+export class PersonHasMarketplaceDataError extends ConflictError {
+    userId;
+    constructor(message, userId) {
+        super(message);
+        this.userId = userId;
+    }
+}
+export function parsePerson(data) {
     if (!data)
         return null;
     return {
@@ -48,11 +108,11 @@ function parsePerson(data) {
         email: data.email ?? null,
         roles: data.roles ?? [],
         accountOwner: data.accountOwner ?? false,
-        createdDate: data.createdDate ?? null,
-        lastModifiedDate: data.lastModifiedDate ?? null,
+        createdDate: toInstant(data.createdDate),
+        lastModifiedDate: toInstant(data.lastModifiedDate),
     };
 }
-function parseAccount(data) {
+export function parseAccount(data) {
     if (!data)
         return null;
     return {
@@ -60,13 +120,13 @@ function parseAccount(data) {
         name: data.name ?? null,
         description: data.description ?? null,
         owner: parsePerson(data.owner),
-        approval: data.approval ?? false,
+        approval: data.approval ?? null,
         approvalDescription: data.approvalDescription ?? null,
-        createdDate: data.createdDate ?? null,
-        lastModifiedDate: data.lastModifiedDate ?? null,
+        createdDate: toInstant(data.createdDate),
+        lastModifiedDate: toInstant(data.lastModifiedDate),
     };
 }
-function parseToken(data) {
+export function parseToken(data) {
     return {
         requestUrl: data.requestUrl ?? null,
         person: parsePerson(data.person),
@@ -74,7 +134,7 @@ function parseToken(data) {
         token: data.token ?? null,
     };
 }
-function parseSecurity(data) {
+export function parseSecurity(data) {
     return {
         marketId: data.marketId ?? 0,
         units: data.units ?? 0,
@@ -85,7 +145,7 @@ function parseSecurity(data) {
         canSell: data.canSell ?? false,
     };
 }
-function parseMarket(data) {
+export function parseMarket(data) {
     return {
         id: data.id ?? 0,
         marketplaceId: data.marketplaceId ?? 0,
@@ -101,7 +161,7 @@ function parseMarket(data) {
         unitTick: data.unitTick ?? 0,
     };
 }
-function parseMarketplace(data) {
+export function parseMarketplace(data) {
     return {
         id: data.id ?? 0,
         name: data.name ?? null,
@@ -109,7 +169,7 @@ function parseMarketplace(data) {
         markets: (data.markets ?? []).map(parseMarket),
     };
 }
-function parseSession(data) {
+export function parseSession(data) {
     return {
         marketplaceId: data.marketplaceId ?? 0,
         allocationId: data.allocationId ?? 0,
@@ -118,8 +178,8 @@ function parseSession(data) {
         state: data.state ?? null,
         name: data.name ?? null,
         description: data.description ?? null,
-        openDate: data.openDate ?? null,
-        closeDate: data.closeDate ?? null,
+        openDate: toInstant(data.openDate),
+        closeDate: toInstant(data.closeDate),
     };
 }
 export function parseOrder(data) {
@@ -128,8 +188,8 @@ export function parseOrder(data) {
         original: data.original ?? 0,
         supplier: data.supplier ?? 0,
         consumer: data.consumer ?? null,
-        type: data.type ?? null,
-        side: data.side ?? null,
+        type: toOrderType(data.type),
+        side: toSide(data.side),
         units: data.units ?? 0,
         price: data.price ?? 0,
         ownerId: data.ownerId ?? null,
@@ -139,8 +199,8 @@ export function parseOrder(data) {
         marketId: data.marketId ?? 0,
         ownerTarget: data.ownerTarget ?? null,
         clientDescription: data.clientDescription ?? null,
-        createdDate: data.createdDate ?? null,
-        lastModifiedDate: data.lastModifiedDate ?? null,
+        createdDate: toInstant(data.createdDate),
+        lastModifiedDate: toInstant(data.lastModifiedDate),
     };
 }
 function parseAllotment(data) {
@@ -154,7 +214,7 @@ function parseAllotment(data) {
             id: assetsRaw.id ?? null,
             name: assetsRaw.name ?? null,
             cash: assetsRaw.cash ?? 0,
-            securities: securitiesRaw.map(parseSecurity),
+            securities: orderedSecurities(securitiesRaw.map(parseSecurity)),
         };
     }
     return {
@@ -222,19 +282,35 @@ export function parseHolding(data) {
         name: data.name ?? null,
         cash: data.cash ?? 0,
         availableCash: data.availableCash ?? 0,
-        securities: securitiesRaw.map(parseSecurity),
+        securities: orderedSecurities(securitiesRaw.map(parseSecurity)),
     };
 }
-function parseConnection(data) {
+export function parseConnection(data) {
     return {
         marketplaceId: data.marketplaceId ?? 0,
         connectionId: data.id ?? data.connectionId ?? 0,
         ownerId: data.ownerId ?? 0,
-        established: data.established ?? null,
-        terminated: data.terminated ?? null,
+        established: toInstant(data.established),
+        terminated: toInstant(data.terminated),
         description: data.description ?? null,
+        sessionId: data.sessionId ?? null,
     };
 }
+/**
+ * The orders inside a HAL envelope.
+ *
+ * The server embeds them under `orders`. It was `orderDtoes` — Spring HATEOAS
+ * pluralising `OrderDto` — and every SDK still read that name long after the
+ * server stopped sending it, so `activeOrders` and `recentTrades` returned an
+ * empty array always. `MarketView` seeds from `activeOrders`, so its books were
+ * never seeded; they filled from live deltas and looked plausible.
+ *
+ * Both names are accepted, so an older server still works.
+ */
+function embeddedOrders(data) {
+    const embedded = data._embedded;
+    return embedded?.orders ?? embedded?.orderDtoes ?? [];
+}
 function parseApiRoot(data) {
     const linksRaw = data._links ?? {};
     const links = {};
@@ -248,6 +324,84 @@ function parseApiRoot(data) {
     }
     return { links };
 }
+/**
+ * The most aggressive price this market will accept on `side`.
+ *
+ * Ticks are anchored at `priceMinimum`, not at zero — the server tests
+ * `(price - priceMinimum) % priceTick` — so the top of the range is only legal
+ * when the range is a whole number of ticks. The highest legal price is the
+ * last tick at or below `priceMaximum`. A tick of zero marks a fixed dimension,
+ * where the two bounds are equal and there is one legal price.
+ */
+export function marketableLimit(market, side) {
+    if (side?.toUpperCase() !== "BUY" || market.priceTick <= 0) {
+        return market.priceMinimum;
+    }
+    const span = market.priceMaximum - market.priceMinimum;
+    return market.priceMinimum + Math.floor(span / market.priceTick) * market.priceTick;
+}
+/**
+ * The `scheme://host:port` of an absolute http(s) URL, else undefined.
+ *
+ * A relative href already resolves against the origin it was fetched from,
+ * and a scheme that is not HTTP is not ours to rewrite.
+ */
+function httpOrigin(url) {
+    if (!url)
+        return undefined;
+    const end = url.indexOf("://");
+    if (end < 0)
+        return undefined;
+    const scheme = url.substring(0, end).toLowerCase();
+    if (scheme !== "http" && scheme !== "https")
+        return undefined;
+    const pathStart = url.indexOf("/", end + 3);
+    return pathStart < 0 ? url : url.substring(0, pathStart);
+}
+/**
+ * Point the API root's links back at the host that was dialled.
+ *
+ * The server builds these hrefs from the request it believes it received, and
+ * behind a proxy that belief can be wrong: an origin reached over a plaintext
+ * leg reports `http://` even though the caller arrived on `https://`. Every
+ * call that goes through a link — which is most of them — then leaves on plain
+ * HTTP and meets the edge's redirect. A GET survives it. A POST does not: a
+ * 301 is followed as a GET with the body dropped, so placing an order or
+ * opening a session fails with nothing placed and nothing pointing at the
+ * scheme.
+ *
+ * Only the origin is replaced. The path, query and any URI template are the
+ * server's to choose; where it is reachable is not, and the token in hand was
+ * issued by the origin dialled, not by whatever the links name.
+ */
+export function rebaseApiRoot(root, endpoint) {
+    const origin = httpOrigin(endpoint);
+    if (!origin)
+        return root;
+    const links = {};
+    const moved = [];
+    for (const [name, href] of Object.entries(root.links)) {
+        const named = httpOrigin(href);
+        if (!named || named === origin) {
+            links[name] = href;
+            continue;
+        }
+        if (!moved.includes(named))
+            moved.push(named);
+        links[name] = origin + href.substring(named.length);
+    }
+    if (moved.length > 0) {
+        // Said out loud, because the rewrite would otherwise hide a deployment
+        // that is genuinely misconfigured — and a silent correction here is how it
+        // stays misconfigured. The SDK keeps working; the operator still gets told
+        // where to look.
+        console.warn(`[fm-sdk] The API root names ${moved.join(", ")} but this client dialled ${origin}; ` +
+            `rewriting ${moved.length} link origin(s) to match. The server is behind a proxy ` +
+            `that is not forwarding the request scheme, so its links are wrong. Fix it at the ` +
+            `edge — this rewrite only keeps calls working.`);
+    }
+    return { links };
+}
 // ---------------------------------------------------------------------------
 // HATEOAS link resolution
 // ---------------------------------------------------------------------------
@@ -255,10 +409,20 @@ function processTemplate(href) {
     const idx = href.indexOf("{");
     return idx >= 0 ? href.substring(0, idx) : href;
 }
+/**
+ * A V1 route, addressed from the server rather than through a HAL link.
+ *
+ * V1 is flat and versioned: the path is knowable without fetching the API root
+ * first, which is the point of it. Every call that moves here loses a HAL
+ * dependency as well as a version.
+ */
+function v1(endpoint, path) {
+    return `${server(endpoint)}/v1${path}`;
+}
 function uri(root, linkName) {
     const href = root.links[linkName];
     if (href === undefined)
-        throw new Error(`Link '${linkName}' not found in API root.`);
+        throw new ApiError(`Link '${linkName}' not found in API root.`);
     return processTemplate(href);
 }
 function uriId(root, linkName, id) {
@@ -368,10 +532,25 @@ function checkResponse(response, body) {
         throw new AuthenticationError(body);
     if (status === 403)
         throw new AuthorizationError(body);
+    if (status === 409)
+        throw new ConflictError(body);
     if (status >= 500)
         throw new ConnectionFailedError(body);
-    throw new FlexemarketsError(`HTTP ${status}: ${body}`);
+    throw new HttpError(status, body);
 }
+/** The server's proposed alternative name, when a 409 body carries one. */
+function suggestedNameIn(body) {
+    try {
+        const parsed = JSON.parse(body);
+        return parsed.suggestedName ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Flexemarkets client
+// ---------------------------------------------------------------------------
 export class Flexemarkets {
     _clientDescription;
     _endpoint;
@@ -380,6 +559,7 @@ export class Flexemarkets {
     _apiRoot;
     _account;
     _user;
+    _tokenObj;
     _eventListener = null;
     constructor(endpoint, baseUrl, bearerToken, clientDescription) {
         this._endpoint = endpoint;
@@ -411,6 +591,7 @@ export class Flexemarkets {
         const tokenObj = await signIn(baseUrl, config, desc);
         const bearer = `Bearer ${tokenObj.token}`;
         const fm = new Flexemarkets(ep, baseUrl, bearer, desc);
+        fm._tokenObj = tokenObj;
         fm._account = tokenObj.account;
         fm._user = tokenObj.person;
         // Fetch API root for HATEOAS links
@@ -524,9 +705,159 @@ export class Flexemarkets {
         checkResponse(resp, body);
         return JSON.parse(body);
     }
+    // -- administration --------------------------------------------------------
+    /*
+     * Creating accounts and users, approving them, deleting them, and minting
+     * one-time passcodes. fm-server's administrative surface, carried here so
+     * that the tools which run a course have a client that is not fm-lib-net.
+     *
+     * Several are destructive and one issues credentials. They need an admin or
+     * manager and the server answers 401/403 otherwise, which is the only
+     * guard: possessing the method is not possessing the right.
+     */
+    /**
+     * Register a new account and its owner, returning the owner's token.
+     *
+     * The owner's credentials go out as `ownerEmail`/`ownerPassword`. Sending
+     * `email`/`password` instead creates an account with an owner the server
+     * cannot sign in as.
+     */
+    async signup(accountName, email, password, firstName, lastName) {
+        const url = uri(this._apiRoot, "accounts");
+        try {
+            const data = await this._post(url, {
+                accountName,
+                ownerEmail: email,
+                ownerPassword: password,
+                firstName: firstName ?? null,
+                lastName: lastName ?? null,
+            });
+            return parseToken(data);
+        }
+        catch (e) {
+            // A taken name, with the server's proposed alternative. Raised as its
+            // own type so a caller can offer the suggestion rather than parsing it
+            // back out of a generic conflict.
+            if (e instanceof ConflictError) {
+                const suggested = suggestedNameIn(e.message);
+                throw new AccountNameConflictError(`Account name '${accountName}' is taken` +
+                    (suggested === null ? "" : `; server suggests '${suggested}'`), accountName, suggested);
+            }
+            throw e;
+        }
+    }
+    /** Approve an account by name, returning it as it now stands. */
+    async approveAccount(accountName) {
+        const url = `${server(this._endpoint)}/approvals`;
+        const data = await this._post(url, { name: accountName, approval: true });
+        return parseAccount(data.account);
+    }
+    /** One account by id. */
+    async accountById(accountId) {
+        return parseAccount(await this._get(uriId(this._apiRoot, "accounts", accountId)));
+    }
+    /** One user by id. */
+    async userById(userId) {
+        return parsePerson(await this._get(v1(this._endpoint, `/users/${userId}`)));
+    }
+    /** The marketplace's private-trader identifiers. */
+    async identifiers(marketplaceId) {
+        const url = uriIdSegment(this._apiRoot, "marketplaces", marketplaceId, "privateTraders");
+        return (await this._get(url));
+    }
+    /** Delete the caller's own account. Its own route, not accounts/{yourId}. */
+    async deleteMyAccount() {
+        await this._delete(`${server(this._endpoint)}/accounts/me`);
+    }
+    /** Every account on the server. Admin-only. */
+    async accounts() {
+        const url = uriParam(this._apiRoot, "accounts", "format=application/json");
+        const data = await this._get(url);
+        return data.map(parseAccount);
+    }
+    /** Delete an account. Destructive, and takes its users with it. */
+    async deleteAccount(accountId) {
+        await this._delete(uriId(this._apiRoot, "accounts", accountId));
+    }
+    /** Create a user in the caller's account. */
+    async createUser(email, password, firstName, lastName, roles = []) {
+        const url = v1(this._endpoint, "/users");
+        const data = await this._post(url, { email, password, firstName, lastName, roles });
+        return parsePerson(data);
+    }
+    /** Delete a user. Destructive. */
+    async deleteUser(userId) {
+        try {
+            await this._delete(uriId(this._apiRoot, "users", userId));
+        }
+        catch (e) {
+            // The user still owns orders or allotments. Deleting them would orphan
+            // it, so the server refuses and the caller has to decide what happens to
+            // the data first.
+            if (e instanceof ConflictError) {
+                throw new PersonHasMarketplaceDataError(`User ${userId} has marketplace data and cannot be deleted.`, userId);
+            }
+            throw e;
+        }
+    }
+    /** Create an empty marketplace. See also {@link createMarketplaceFromJson}. */
+    /** Delete a marketplace, and with it its sessions and their history. */
+    async deleteMarketplace(marketplaceId) {
+        await this._delete(uriId(this._apiRoot, "marketplaces", marketplaceId));
+    }
+    /**
+     * Add a market to a marketplace.
+     *
+     * Both dimensions are the caller's. Unit bounds used to be fixed at 1/100/1
+     * with no way to say otherwise, on a call that set the price grid three
+     * arguments earlier — and the server enforces the two identically, refusing
+     * an order for "units is not on a tic" exactly as for a price. Omitting
+     * `units` keeps the old default.
+     */
+    async createMarket(marketplaceId, symbol, name, price, units = unitGrid(), privateMarket = false) {
+        const url = uriIdSegment(this._apiRoot, "marketplaces", marketplaceId, "markets");
+        return parseMarket(await this._post(url, {
+            symbol,
+            name,
+            priceMinimum: price.minimum,
+            priceMaximum: price.maximum,
+            priceTick: price.tick,
+            unitMinimum: units.minimum,
+            unitMaximum: units.maximum,
+            unitTick: units.tick,
+            privateMarket,
+        }));
+    }
+    /**
+     * Mint one-time passcodes for the given users.
+     *
+     * These are credentials: not to be logged, not to be persisted, and
+     * delivered to the person they belong to.
+     */
+    async managerOtpBundle(userIds) {
+        const url = `${server(this._endpoint)}/otp/manager`;
+        const data = await this._post(url, { userIds });
+        return {
+            expiresAt: toInstant(data.expiresAt),
+            otps: (data.otps ?? []).map((o) => ({
+                userId: o.userId ?? 0,
+                email: o.email ?? null,
+                otp: o.otp ?? null,
+            })),
+        };
+    }
+    /** DELETE, whose answer is a status and nothing worth parsing. */
+    async _delete(url) {
+        const resp = await fetch(url.startsWith("/") ? `${this._baseUrl}${url}` : url, {
+            method: "DELETE",
+            headers: { ...this._authHeaders(), Accept: "application/json" },
+        });
+        const body = await resp.text();
+        checkResponse(resp, body);
+    }
     async _fetchApiRoot() {
         const data = await this._get(this._baseUrl);
-        return parseApiRoot(data);
+        return rebaseApiRoot(parseApiRoot(data), this._baseUrl);
     }
     // ======================================================================
     // REST APIs
@@ -547,21 +878,50 @@ export class Flexemarkets {
         const data = await this._get(url);
         return data.map(parseMarket);
     }
+    /**
+     * The token this connection signed in with.
+     *
+     * Exposed so a caller can open a sibling connection on the same identity
+     * without holding the password again.
+     */
+    token() {
+        return this._tokenObj;
+    }
+    /** Whether this connection's user holds ROLE_ADMIN. */
+    isAdmin() {
+        return this.hasRole("ROLE_ADMIN");
+    }
+    /**
+     * Whether this connection's user holds ROLE_MANAGER — the role that runs a
+     * study: opening and closing sessions, staging allocations, minting
+     * passcodes. Python has had it since the management surface landed.
+     */
+    isManager() {
+        return this.hasRole("ROLE_MANAGER");
+    }
+    hasRole(role) {
+        return (this._user?.roles ?? []).includes(role);
+    }
     async symbols(marketplaceId) {
         const url = uriIdSegment(this._apiRoot, "marketplaces", marketplaceId, "symbols");
         return (await this._get(url));
     }
     // -- sessions --------------------------------------------------------------
-    async sessions(marketplaceId, sessionIds) {
-        let url;
-        if (sessionIds && sessionIds.length > 0) {
-            url = uriIdSegmentParam(this._apiRoot, "marketplaces", marketplaceId, "sessions", `${sessionIdsParam(sessionIds)}&format=application/json`);
-        }
-        else {
-            url = uriIdSegmentParam(this._apiRoot, "marketplaces", marketplaceId, "sessions", "format=application/json");
-        }
-        const data = await this._get(url);
-        return data.map(parseSession);
+    /**
+     * The marketplace's sessions — all of them.
+     *
+     * There is no server-side filter. The route takes no session argument, so
+     * the `sessionIds` this used to accept was silently ignored: it returned the
+     * whole history and looked like it had filtered. Filter the result; fm-ui
+     * already does.
+     *
+     * On `GET /api/v1/marketplaces/{id}/sessions`, which answers with the same
+     * fields as the V0 route it replaces — verified against a running server,
+     * not assumed — and needs no `format=application/json` to avoid HAL.
+     */
+    async sessions(marketplaceId) {
+        const url = v1(this._endpoint, `/marketplaces/${marketplaceId}/sessions`);
+        return (await this._get(url)).map(parseSession);
     }
     async session(marketplaceId) {
         const url = uriIdSegment(this._apiRoot, "marketplaces", marketplaceId, "currentSession");
@@ -581,6 +941,45 @@ export class Flexemarkets {
         });
         return parseOrder(data);
     }
+    /**
+     * Cross the book: buy at the highest price this market allows, sell at the
+     * lowest. Immediate or cancel — whatever does not fill is cancelled.
+     *
+     * There is no market order on the server. Its type switch falls through to
+     * `LIMIT`, so every submission is bounds-checked against the market and must
+     * sit on a tick — which is why this asks the marketplace for the market
+     * first, and costs a round trip {@link submitLimit} does not.
+     *
+     * The cancel is unconditional: the exchange consumes a cancel by itself when
+     * no units remain, so a complete fill costs a harmless round trip rather than
+     * an inspection that would race the book. Without it, a market order that did
+     * not fill would rest at the market's extreme — the best price in the book,
+     * standing, for anyone to take.
+     *
+     * Returns the limit order as submitted. What it filled is a property of the
+     * book afterwards, not of this value.
+     */
+    async submitMarket(marketplaceId, marketId, side, units) {
+        const market = await this._market(marketplaceId, marketId);
+        const limit = await this.submitLimit(marketplaceId, marketId, side, units, marketableLimit(market, side));
+        try {
+            await this.submitCancel(marketplaceId, marketId, limit.id);
+        }
+        catch (e) {
+            // The order is placed. Reporting only "cancel failed" would invite a
+            // caller to retry the whole thing and trade twice.
+            throw new FlexemarketsError(`Order ${limit.id} was placed but its remainder could not be cancelled; ` +
+                `it may still be resting. Do not resubmit — cancel it. (${String(e)})`);
+        }
+        return limit;
+    }
+    async _market(marketplaceId, marketId) {
+        for (const candidate of await this.markets(marketplaceId)) {
+            if (candidate.id === marketId)
+                return candidate;
+        }
+        throw new InvalidArgumentError(`Market ${marketId} is not in marketplace ${marketplaceId}`);
+    }
     async submitCancel(marketplaceId, marketId, originalId) {
         const url = uri(this._apiRoot, "orders");
         const data = await this._post(url, {
@@ -595,28 +994,28 @@ export class Flexemarkets {
         return parseOrder(data);
     }
     /**
-     * V1 active-orders snapshot: every resting limit order on the
+     * The active-orders snapshot: every resting limit order on the
      * marketplace's current session, plus the `x-fm-as-of-seq` sequence
-     * the snapshot was read at. Used by `MarketView` Phase 2a seeding
+     * the snapshot was read at. Used by `MarketView` seeding
      * — clients apply WS deltas whose seq is greater than the returned
      * value and skip those whose seq is less than or equal.
      */
-    async activeOrdersV1(marketplaceId) {
+    async activeOrders(marketplaceId) {
         const baseRest = this._baseUrl;
         const url = `${baseRest}/v1/marketplaces/${marketplaceId}/orders/active`;
         const { data, asOfSeq } = await this._getSnapshot(url);
-        const orders = (data._embedded?.orderDtoes ?? []).map(parseOrder);
+        const orders = embeddedOrders(data).map(parseOrder);
         return { body: orders, asOfSeq };
     }
     /**
-     * V1 recent-trades snapshot for seeding the trade-history tape.
-     * Same `x-fm-as-of-seq` contract as `activeOrdersV1`. Server caps
+     * The recent-trades snapshot, for seeding the trade-history tape.
+     * Same `x-fm-as-of-seq` contract as `activeOrders`. Server caps
      * at 5000; default size is 1000.
      */
-    async recentTradesV1(marketplaceId, size = 1000) {
+    async recentTrades(marketplaceId, size = 1000) {
         const url = `${this._baseUrl}/v1/marketplaces/${marketplaceId}/orders/recent-trades?size=${size}`;
         const { data, asOfSeq } = await this._getSnapshot(url);
-        const orders = (data._embedded?.orderDtoes ?? []).map(parseOrder);
+        const orders = embeddedOrders(data).map(parseOrder);
         return { body: orders, asOfSeq };
     }
     async orders(marketplaceId, options) {
@@ -641,8 +1040,13 @@ export class Flexemarkets {
         const url = uriParamMarketplaceIdParam(this._apiRoot, "symbolTradesJson", marketplaceId, `symbol=${symbol}`);
         const data = await this._get(url);
         const orders = data.map(parseOrder);
-        for (const o of orders)
+        for (const o of orders) {
+            // The symbol-keyed route answers with the trade id in `original` and no
+            // symbol, because the query already fixed it. Filling both in is what
+            // makes the result a trade list rather than half-populated orders.
+            o.id = o.original;
             o.symbol = symbol;
+        }
         return orders;
     }
     // -- holdings --------------------------------------------------------------
@@ -662,15 +1066,16 @@ export class Flexemarkets {
         return parseHolding(await this._get(url));
     }
     // -- connections -----------------------------------------------------------
-    async connections(marketplaceId, sessionIds) {
-        // Canonical path is /marketplaces/{id}/connections ("/agents" is the
-        // retained pre-FM-4 alias); format=application/json yields a plain list
-        // (vs the HAL _embedded form).
-        const sid = sessionIdsParam(sessionIds ?? null);
-        const param = sid ? `${sid}&format=application/json` : "format=application/json";
-        const url = uriIdSegmentParam(this._apiRoot, "marketplaces", marketplaceId, "connections", param);
-        const data = await this._get(url);
-        return data.map(parseConnection);
+    /**
+     * Who is attached to the marketplace — all of them.
+     *
+     * No server-side filter, for the reason {@link sessions} gives. A connection
+     * carries the session it belonged to, so "who was present in that run" is a
+     * filter on the result.
+     */
+    async connections(marketplaceId) {
+        const url = uriIdSegmentParam(this._apiRoot, "marketplaces", marketplaceId, "connections", "format=application/json");
+        return (await this._get(url)).map(parseConnection);
     }
     // -- management ------------------------------------------------------------
     //
@@ -739,8 +1144,17 @@ export class Flexemarkets {
         const data = await this._post(url, body);
         return allotmentsToHoldings(data.map(parseAllotment));
     }
-    /** The holdings CSV, verbatim, as the server renders it. */
-    async downloadHoldings(marketplaceId) {
+    /**
+     * The holdings CSV, verbatim, for the current session or for given ones.
+     *
+     * The filter is spelled `sessions=` on this route and `sessionIds=` on
+     * sessions and connections. Using the wrong one is not an error — it is an
+     * unfiltered answer.
+     */
+    async downloadHoldings(marketplaceId, sessionIds) {
+        if (sessionIds && sessionIds.length > 0) {
+            return this._getText(uriIdSegmentParam(this._apiRoot, "marketplaces", marketplaceId, "holdings/downloads", `sessions=${sessionIds.join(",")}`));
+        }
         return this._getText(uriIdSegment(this._apiRoot, "marketplaces", marketplaceId, "holdings/downloads"));
     }
     /**
@@ -824,6 +1238,27 @@ export class Flexemarkets {
     async listen(marketplaceId, callback) {
         this._eventListener = await this._connectEvents(marketplaceId, callback);
     }
+    /**
+     * Open an *independent* event subscription, delivering to `callback` until
+     * the returned unsubscribe function is invoked.
+     *
+     * Unlike {@link listen}, which is one per connection and replaces itself,
+     * several of these coexist: each has its own stream and its own lifetime.
+     * That is what lets more than one MarketView live in one connection without
+     * trampling each other — the mechanism was already here for exactly that, as
+     * the package-private `_connectEvents`, but a caller who wanted a second
+     * stream of their own had no way to ask for one.
+     *
+     * Returns an unsubscribe function rather than an object with `close()`,
+     * matching what MarketView's `on*` handlers already return here. Java
+     * returns a `Subscription`; both names describe the same lifetime.
+     */
+    async subscribe(marketplaceId, callback) {
+        const listener = await this._connectEvents(marketplaceId, callback);
+        return () => {
+            void listener.close();
+        };
+    }
     /**
      * Package-private helper used by {@link DefaultMarketView} (Phase 2d)
      * to own its own EventListener subscription rather than clobbering
@@ -867,19 +1302,23 @@ export class Flexemarkets {
 async function signIn(baseUrl, config, clientDescription) {
     const tok = config.token ?? "";
     if (tok && isValidToken(tok)) {
-        const authUrl = `${baseUrl}/tokens`;
-        const resp = await fetch(authUrl, {
-            method: "POST",
+        // A caller who already holds a token has no account/email/password to
+        // present, so signing in is not available: POSTing /tokens with blanks is
+        // rejected -- the server answers 400 MESSAGE_NOT_READABLE for an empty
+        // password, which is what this used to send. Refreshing the token both
+        // validates it and returns the account and person behind it.
+        //
+        // This is the third time. fm-lib-net carried the branch, an earlier rewrite
+        // dropped it, and the Java SDK restored it with a test. This SDK and the
+        // Python one never had it, so token auth returned 400 in both from the day
+        // it was written.
+        const resp = await fetch(`${baseUrl}/tokens/refresh`, {
+            method: "GET",
             headers: {
                 Authorization: `Bearer ${tok}`,
-                "Content-Type": "application/json",
                 Accept: "application/json",
                 "User-Agent": FM_NETWORK_CLIENT,
             },
-            body: JSON.stringify({
-                username: `${config.account ?? ""}|${config.email ?? ""}`,
-                password: "",
-            }),
         });
         const body = await resp.text();
         if (resp.status === 401) {