@flexemarkets/fm-sdk 0.0.10 → 0.1.0

package/dist/client.d.ts

@@ -3,9 +3,10 @@
  *
  * Port of fm.client (Python) / fm.Flexemarkets (Java).
  */
-import type { Account, Allotment, ClientConnection, Holding, Market, Marketplace, Order, Person, Session } from "./types.js";
+import type { Account, Allotment, ClientConnection, Holding, ManagerOtpBundle, Market, Marketplace, Order, Person, Security, Session, TickGrid, Token } from "./types.js";
 import { EventListener, type EventCallback } from "./stomp.js";
-import { type MarketView } from "./market-view.js";
+import type { ApiRoot } from "./hal.js";
+import { type MarketView, type Subscription } from "./market-view.js";
 import type { Snapshot } from "./snapshot.js";
 export declare class FlexemarketsError extends Error {
 }
@@ -19,9 +20,91 @@ export declare class ConnectionFailedError extends FlexemarketsError {
 }
 export declare class ConfigurationError extends FlexemarketsError {
 }
+/**
+ * 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 declare class HttpError extends FlexemarketsError {
+    readonly statusCode: number;
+    readonly body: string;
+    constructor(statusCode: number, body: string);
+}
+/**
+ * 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 declare class ApiError extends FlexemarketsError {
+}
+/** A 409. The Java and Python SDKs have raised this since the admin surface landed. */
+export declare 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 declare class AccountNameConflictError extends ConflictError {
+    readonly requestedName: string;
+    readonly suggestedName: string | null;
+    constructor(message: string, requestedName: string, suggestedName: string | null);
+}
+/**
+ * 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 declare class PersonHasMarketplaceDataError extends ConflictError {
+    readonly userId: number;
+    constructor(message: string, userId: number);
+}
 type JsonObject = Record<string, unknown>;
+export declare function parsePerson(data: JsonObject | null | undefined): Person | null;
+export declare function parseAccount(data: JsonObject | null | undefined): Account | null;
+export declare function parseToken(data: JsonObject): Token;
+export declare function parseSecurity(data: JsonObject): Security;
+export declare function parseMarket(data: JsonObject): Market;
+export declare function parseMarketplace(data: JsonObject): Marketplace;
+export declare function parseSession(data: JsonObject): Session;
 export declare function parseOrder(data: JsonObject): Order;
 export declare function parseHolding(data: JsonObject): Holding;
+export declare function parseConnection(data: JsonObject): ClientConnection;
+/**
+ * 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 declare function marketableLimit(market: Market, side: string): number;
+/**
+ * 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 declare function rebaseApiRoot(root: ApiRoot, endpoint: string): ApiRoot;
 /**
  * Resolve an `--endpoint` value to config overrides. A bare marketplace id
  * (e.g. "2540") resolves to that marketplace on the default production host; a
@@ -29,11 +112,6 @@ export declare function parseHolding(data: JsonObject): Holding;
  * URL. Development environments give a full URL when localhost is wanted.
  */
 export declare function resolveEndpoint(endpoint: string): Record<string, string>;
-export interface FlexemarketsOptions {
-    credential?: string;
-    endpoint?: string;
-    clientDescription?: string;
-}
 export declare class Flexemarkets {
     private readonly _clientDescription;
     private readonly _endpoint;
@@ -42,6 +120,7 @@ export declare class Flexemarkets {
     private _apiRoot;
     private _account;
     private _user;
+    private _tokenObj;
     private _eventListener;
     private constructor();
     /** Connect to the Flexemarkets API. */
@@ -74,29 +153,125 @@ export declare class Flexemarkets {
      */
     private _getText;
     private _post;
+    /**
+     * 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.
+     */
+    signup(accountName: string, email: string, password: string, firstName?: string | null, lastName?: string | null): Promise<Token>;
+    /** Approve an account by name, returning it as it now stands. */
+    approveAccount(accountName: string): Promise<Account | null>;
+    /** One account by id. */
+    accountById(accountId: number): Promise<Account | null>;
+    /** One user by id. */
+    userById(userId: number): Promise<Person>;
+    /** The marketplace's private-trader identifiers. */
+    identifiers(marketplaceId: number): Promise<string[]>;
+    /** Delete the caller's own account. Its own route, not accounts/{yourId}. */
+    deleteMyAccount(): Promise<void>;
+    /** Every account on the server. Admin-only. */
+    accounts(): Promise<Account[]>;
+    /** Delete an account. Destructive, and takes its users with it. */
+    deleteAccount(accountId: number): Promise<void>;
+    /** Create a user in the caller's account. */
+    createUser(email: string, password: string, firstName: string, lastName: string, roles?: string[]): Promise<Person>;
+    /** Delete a user. Destructive. */
+    deleteUser(userId: number): Promise<void>;
+    /** Create an empty marketplace. See also {@link createMarketplaceFromJson}. */
+    /** Delete a marketplace, and with it its sessions and their history. */
+    deleteMarketplace(marketplaceId: number): Promise<void>;
+    /**
+     * 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.
+     */
+    createMarket(marketplaceId: number, symbol: string, name: string, price: TickGrid, units?: TickGrid, privateMarket?: boolean): Promise<Market>;
+    /**
+     * 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.
+     */
+    managerOtpBundle(userIds: number[]): Promise<ManagerOtpBundle>;
+    /** DELETE, whose answer is a status and nothing worth parsing. */
+    private _delete;
     private _fetchApiRoot;
     marketplaces(): Promise<Marketplace[]>;
     marketplace(marketplaceId: number): Promise<Marketplace>;
     markets(marketplaceId: number): Promise<Market[]>;
+    /**
+     * 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(): Token;
+    /** Whether this connection's user holds ROLE_ADMIN. */
+    isAdmin(): boolean;
+    /**
+     * 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(): boolean;
+    hasRole(role: string): boolean;
     symbols(marketplaceId: number): Promise<string[]>;
-    sessions(marketplaceId: number, sessionIds?: number[] | null): Promise<Session[]>;
+    /**
+     * 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.
+     */
+    sessions(marketplaceId: number): Promise<Session[]>;
     session(marketplaceId: number): Promise<Session>;
     submitLimit(marketplaceId: number, marketId: number, side: string, units: number, price: number): Promise<Order>;
+    /**
+     * 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.
+     */
+    submitMarket(marketplaceId: number, marketId: number, side: string, units: number): Promise<Order>;
+    private _market;
     submitCancel(marketplaceId: number, marketId: number, originalId: number): Promise<Order>;
     /**
-     * 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.
      */
-    activeOrdersV1(marketplaceId: number): Promise<Snapshot<Order[]>>;
+    activeOrders(marketplaceId: number): Promise<Snapshot<Order[]>>;
     /**
-     * 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.
      */
-    recentTradesV1(marketplaceId: number, size?: number): Promise<Snapshot<Order[]>>;
+    recentTrades(marketplaceId: number, size?: number): Promise<Snapshot<Order[]>>;
     orders(marketplaceId: number, options?: {
         symbol?: string;
         sessionIds?: number[];
@@ -104,7 +279,14 @@ export declare class Flexemarkets {
     trades(marketplaceId: number, symbol: string): Promise<Order[]>;
     holdings(marketplaceId: number, sessionIds?: number[] | null): Promise<Holding[]>;
     holding(marketplaceId: number): Promise<Holding>;
-    connections(marketplaceId: number, sessionIds?: number[] | null): Promise<ClientConnection[]>;
+    /**
+     * 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.
+     */
+    connections(marketplaceId: number): Promise<ClientConnection[]>;
     /**
      * Create a marketplace from its JSON definition, returning what was made.
      *
@@ -137,8 +319,14 @@ export declare class Flexemarkets {
      * computes with; the allotment encoding is applied here.
      */
     allocate(marketplaceId: number, holdings: Holding[]): Promise<Holding[]>;
-    /** The holdings CSV, verbatim, as the server renders it. */
-    downloadHoldings(marketplaceId: number): Promise<string>;
+    /**
+     * 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.
+     */
+    downloadHoldings(marketplaceId: number, sessionIds?: number[] | null): Promise<string>;
     /**
      * Load opening positions from a holdings CSV. Stages the next allocation on
      * the same terms as {@link allocate}.
@@ -162,6 +350,22 @@ export declare class Flexemarkets {
     _releaseSharedView(marketplaceId: number): void;
     /** Start receiving real-time events via WebSocket STOMP. */
     listen(marketplaceId: number, callback: EventCallback): Promise<void>;
+    /**
+     * 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.
+     */
+    subscribe(marketplaceId: number, callback: EventCallback): Promise<Subscription>;
     /**
      * Package-private helper used by {@link DefaultMarketView} (Phase 2d)
      * to own its own EventListener subscription rather than clobbering